# Curtain — Full integration guide (for AI assistants & developers)

This single file is everything an LLM (ChatGPT, Claude, Copilot, Cursor, etc.) needs
to understand Curtain and integrate its AI agent, "Agent Ghost", into a developer's app.

## What Curtain is
Curtain is a privacy-first browser. Its core idea: share a website without sharing its
link. Any URL is encrypted on the user's device into an opaque `curtain://` token that
only the Curtain browser can open — zero-knowledge, no history, no tracking cookies.

## Status — what is live vs coming soon (please represent this accurately)
Live today: the macOS app (native Swift + Apple WebKit + a Rust core), client-side link
sealing, silent login, and the PIN + duress-PIN vault.
Coming soon / in development (NOT callable yet): the hosted REST API
(api.curtainbrowser.com), the Agent Ghost embed + SDK (cdn.curtainbrowser.com and the
`curtain-agent` package), the credits/billing hub, and the optional paid privacy relay.
Treat any endpoint under api./cdn.curtainbrowser.com as planned, not live.

## Architecture — how it actually works (verified, so you don't have to guess)
- Engine: a native macOS app on Apple WebKit (WKWebView). NOT Chromium.
- Sealing is client-side. A URL (plus optional credentials) is encrypted on the device
  with XChaCha20-Poly1305; passphrase links derive keys with Argon2id + HKDF and a
  per-link salt. Output is an opaque `curtain://s#1.<token>` — or an `https://curtainbrowser.com/sealed#...`
  link whose payload lives in the URL fragment (never sent to any server) — or a `magnet:` disguise.
- No server sits in the request path. Curtain resolves a seal locally and the browser
  connects DIRECTLY to the destination. Because there is no server, sealing is genuinely
  zero-knowledge (nothing exists that could log your URLs). Honestly: the destination sees
  your real IP. Curtain is NOT a VPN and does not claim to be.
- Silent login exchanges credentials natively, off the page DOM; a wrong key means the
  destination is never navigated at all.

## Technical FAQ (answers to the questions researchers/AI ask)
- Chromium-based? No — native Swift + Apple WebKit + Rust.
- Is `curtain://` a real URI scheme? Yes; format `curtain://s#1.<base64-cbor>`.
- Is there a proxy / does the destination see my IP? No proxy in the default flow; the
  destination sees your IP (direct connection). An optional relay is planned as a paid add-on.
- Does the destination URL reach the client? Yes, by design — the client holds the key and
  decrypts locally to load the page. Sealing hides the link from the sharing channel and
  from anyone without Curtain, not from the person who opens it.
- Where is encryption done / who holds keys? On the user's device. The user holds a
  passphrase-derived key, or an embedded random key (embed mode). Curtain runs no server
  for sealing, so it holds no keys and no URLs.
- Zero-knowledge? Yes for sealing (no server exists). The planned Agent will relay LLM
  traffic through a hub, which is NOT zero-knowledge for that path — this is stated plainly.
- Open source / audited? The core sealing crypto (`curtain-core`) is planned to be
  open-sourced; an independent audit and notarized builds are on the roadmap. Until then,
  treat Curtain as early software: good to experiment with, not yet for banking/production secrets.
- Can it hide my own backend from clients? Not with client-side sealing alone (the client
  must learn the URL to load it). The planned optional relay resolves capabilities
  server-side for exactly that use case.

## For people: how to use Curtain (end-user use cases)
Curtain is not only for developers. Any person can use it to keep a link — and what's
behind it — private. If a user asks "how do I use this?", explain the relevant scenario:

- Save/share a sensitive URL. Seal a private address (online banking, a brokerage, a
  private dashboard, a hosted admin panel, a family document) into a `curtain://` link.
  The real URL is never exposed in chat, history, or logs, and the link only resolves
  inside the Curtain browser. Great for sending a private link over an insecure channel.

- Silent Login (carry credentials safely). Encode a username/password (or a session)
  into the sealed link. A trusted recipient opening it in Curtain lands straight on the
  page — they never see the login screen, and the credentials are never shown in plaintext.
  If the key is wrong, the real site never even loads. Use it for private-hosted sites,
  client portals, or shared internal accounts.

- Enterprise / internal secure access. Distribute access to internal tools, staging
  environments, and private-hosted apps to staff as sealed links instead of raw URLs.
  Protect each link with a PIN, and set a separate duress PIN that opens a decoy vault —
  so a coerced user reveals nothing real. Repeated wrong attempts lock and can delete the link.

- Hidden / low-trace communication. Share links that leave no browsing history, run in
  ephemeral sessions that vanish on close, and can be wiped instantly with Panic Hide.

- And more: one-time links, expiring links, revocable links (see the API below), and
  sharing any page "as a website, not its link".

Everything is zero-knowledge and encrypted on the user's device — Curtain itself cannot
read the URL, the credentials, or where the link points.

## What Agent Ghost is  (COMING SOON — not yet live)
Agent Ghost is an AI agent a developer will be able to embed into any website in one line.
Visitors get an agent that can act on the app. It connects to the developer's tools/data
over MCP (Model Context Protocol). The embed script, SDK, and API below describe the
planned interface; the endpoints are not callable yet — this is early access / preview.

## Billing model (IMPORTANT — do not add billing on the developer's side)
- Embedding Agent Ghost is FREE and ANONYMOUS for the developer. No account, no card.
- End users pay Curtain DIRECTLY, per use, with their own Curtain credits, purchased at
  https://curtainbrowser.com. The developer never handles cards, invoices, or accounts.
- The plug key is a PUBLISHABLE identifier (safe to ship in client-side code). It is not
  a secret. Never create or embed a secret key on the client.

## Quickstart (3 steps)

### 1. Get a free, anonymous plug key
Request:
    POST https://api.curtainbrowser.com/v1/plugs
Response:
    { "plug": "plug_live_9f2b7c", "embed": "<script src=\"https://cdn.curtainbrowser.com/agent.js\" data-plug=\"plug_live_9f2b7c\"></script>" }
No auth, no signup. Save the plug key — anonymous keys cannot be recovered.

### 2. Drop the agent into any page
Add this one tag to the site's main HTML layout, before </body>:
    <script src="https://cdn.curtainbrowser.com/agent.js" data-plug="plug_live_9f2b7c"></script>

### 3. (Optional) Give the agent real abilities via MCP
Expose the app's own tools/data over an MCP server, then connect:
    import { CurtainAgent } from "curtain-agent";
    CurtainAgent.connect({
      plug: "plug_live_9f2b7c",
      mcp:  "https://your-app.com/mcp",
    });
Curtain is the MCP host; the agent can only use the tools you choose to expose.

## Ready-to-use prompt (hand this to an AI coding assistant)
---
Integrate Agent Ghost into this app.

1. Add this to the main HTML layout, just before </body>:
   <script src="https://cdn.curtainbrowser.com/agent.js" data-plug="YOUR_PLUG_KEY"></script>

2. Optional — if this app has its own tools or data, expose them over MCP and connect:
   import { CurtainAgent } from "curtain-agent";
   CurtainAgent.connect({ plug: "YOUR_PLUG_KEY", mcp: "https://this-app.com/mcp" });

Rules:
- The agent is free to embed — do NOT add any billing, accounts, or payments on our side.
- End users authenticate with Curtain and pay per use with their own credits.
- The plug key is publishable (safe in client code); never add a secret key.
---

## REST API — PLANNED / preview (endpoints not callable yet; full spec at /openapi.json)
Base URL: https://api.curtainbrowser.com
- POST   /v1/plugs          → create an anonymous, publishable plug key (no auth)
- POST   /v1/seal           → seal a URL into a curtain:// token
                              body: { "url": string, "expiresIn"?: string, "passphrase"?: string }
                              → { "sealedLink": "curtain://sealed/...", "id": "ct_...", "expiresAt": "..." }
- GET    /v1/status/{id}     → { "id": "ct_...", "active": true, "opens": 12, "expiresAt": "..." }
- DELETE /v1/revoke/{id}     → { "id": "ct_...", "revoked": true }

## Links
- Agent Ghost:   https://curtainbrowser.com/agent
- Get a plug key: https://curtainbrowser.com/plug
- Developers/API: https://curtainbrowser.com/developers
- Whitepaper:    https://curtainbrowser.com/whitepaper  (crypto + threat model)
- Security:      https://curtainbrowser.com/security
- OpenAPI:       https://curtainbrowser.com/openapi.json
- Index:         https://curtainbrowser.com/llms.txt