sealnet-mcp 0.2.4 → 0.2.5

package/dist/index.d.cts

@@ -1,108 +1,457 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { WorkloadCredentials } from '@seal/crypto/node';
-import { S } from './open-DUqF6AyG.js';
-export { B as BackendError, S as SealApi, G as SealApiOptions, a0 as SealMetadata } from './open-DUqF6AyG.js';
 
 /**
- * MCP server bootstrap — wires the five tools (`seal_share`,
- * `seal_request`, `seal_open`, `seal_list`, `seal_revoke`) to a
- * stdio-transport `McpServer` instance, and `seal_pro_secret_use`,
- * `seal_pro_secret_request` and `seal_pro_file_get` when SEAL Pro workload
- * credentials exist (contract `pro_tools`).
- *
- * The bootstrap is intentionally factored as a `createServer()`
- * factory that returns an awaitable handle, NOT a hard-coded
- * `main()` entry. That shape:
- *   - lets `cli.ts` configure passphrase delivery, state path,
- *     backend base URL, etc. before launching;
- *   - lets test code spawn an in-process MCP without spawning a
- *     subprocess;
- *   - keeps the "where do creds come from?" decision out of the
- *     pure tool implementations.
- *
- * Tool `title`, `description` and `annotations` come from
- * `shared/contracts/seal_mcp.v1.json` (contract first, §6.2), and so do
- * the descriptions of the inputs the contract describes; the zod input
- * schemas live here.
+ * The `/seal/*` HTTP surface — one implementation for every runtime.
+ *
+ * Everything the protocol does with bytes (AEON framing, streaming upload,
+ * download + decrypt, blobs, key store) already lives in this package. What
+ * did not was the thin layer around it: the routes, the wire shapes and the
+ * error classification of the SEAL backend's non-upload endpoints. That layer
+ * existed six times — the Slack bot's `seal/backend.ts`, the MCP server's
+ * `client.ts` (a line-for-line subset of it), the SEAL web's `seal_client.ts`
+ * plus a second axios stack in `lib/api.ts`, fifteen inline `fetch` calls
+ * across the web's features, and the SDK's `anonymous.ts`. One contract,
+ * six readings of it, and every fix landing in one of them.
+ *
+ * This module is that layer, once. It is deliberately NOT a runtime: it
+ * takes a `fetch` and a `baseUrl` and hands back parsed wire objects or a
+ * `Response` the caller consumes its own way. That is what lets one file
+ * serve a browser (BFF origin, cookie gates, service-worker download), a
+ * Slack bot (disk-backed streaming), an MCP server (in-memory) and an SDK
+ * (wildcard-CORS, no credentials) without any of them branching on who the
+ * others are.
+ *
+ * Two rules this file follows and the six copies did not:
+ *
+ *   * Wire shapes are exported as they appear on the wire. Callers that
+ *     want camelCase compose `toSealMetadata` / `toOwnerFiles`; callers that
+ *     already speak snake_case (the web's views) keep doing so. One route,
+ *     one method, one type.
+ *   * Every failure is a `BackendError` carrying BOTH the coarse class the
+ *     bots switch on (`not_found` / `revoked` / `rate_limited` / `auth` /
+ *     `transient`) and the backend's own `{detail, code, retry_after}`
+ *     envelope, which is what the web needs to tell `nda.required` from
+ *     `otp.required` from a stale blob version.
+ */
+/** Coarse failure class. Callers map this onto their own user-facing text. */
+type BackendErrorCode = 'not_found' | 'revoked' | 'rate_limited' | 'auth' | 'transient' | 'unknown';
+/**
+ * A non-2xx answer from the SEAL backend.
  *
- * Three stateful concerns the factory owns (all three skipped in
- * ephemeral mode, `state: null`, where nothing touches the disk):
- *   - **Exclusive state lock (ISSUE-0623)**: `acquireStateLock` makes
- *     this process the ONLY writer of the state dir for its lifetime;
- *     a second `serve` on the same dir fails fast instead of silently
- *     clobbering handles. Released in `close()` / on process exit.
- *   - **State persistence**: each tool mutates `ctx.state` in-place
- *     and calls `await ctx.persist()`; persist() re-encrypts the
- *     view and writes atomically via `state.saveState`. A mutex
- *     serialises persist() calls so concurrent tool calls cannot
- *     race on the same on-disk envelope. Startup runs a journal
- *     recovery pass (`recovery.ts`) before any tool registers.
- *   - **Tool errors**: thrown `ToolError`s are converted to MCP's
- *     `{ isError: true, content: [...] }` payload with the typed
- *     `code` echoed back to the model. Other errors bubble as
- *     internal_error so the model never sees raw stack traces.
+ * `code` is the coarse class (from the status). `appCode` is the backend's
+ * own machine-readable code from the `{detail, code, retry_after}` envelope
+ * — `nda.required`, `otp.required`, `blob.version_mismatch`, `seal.not_found`
+ * and friends. Callers that can act on the specific cause read `appCode`;
+ * callers that only need "gone vs denied vs try again" read `code`.
  */
-
-interface McpServerOptions {
-    /** Encrypted state on disk; `null` = ephemeral: identity and handles in memory only. */
-    readonly state: {
-        readonly path: string;
-        readonly passphrase: string;
-    } | null;
-    readonly backendBaseUrl?: string;
-    readonly publicHost?: string;
-    /** SEAL Pro workload; omitted = read the environment or the enrollment file, `null` = none. */
-    readonly workload?: WorkloadCredentials | null;
+declare class BackendError extends Error {
+    readonly code: BackendErrorCode;
+    readonly status: number;
+    /** Raw response body, when it was read. */
+    readonly body?: string;
+    /** `detail` from the canonical error envelope, when the body carried one. */
+    readonly detail?: string;
+    /** `code` from the canonical error envelope (e.g. `nda.required`). */
+    readonly appCode?: string;
+    /** `retry_after` seconds from the envelope, when present. */
+    readonly retryAfter?: number;
+    constructor(message: string, code: BackendErrorCode, status: number, extra?: {
+        body?: string;
+        detail?: string;
+        appCode?: string;
+        retryAfter?: number;
+    });
 }
-interface McpServerHandle {
-    readonly mcp: McpServer;
-    readonly transport: StdioServerTransport;
-    readonly close: () => Promise<void>;
+/** One file row of `GET /seal/{id}` (the public, recipient-facing view). */
+interface SealFileWire {
+    id: string;
+    size: number;
+    sha256_hex: string | null;
+    name?: string;
+    mime?: string | null;
+    name_encrypted?: string;
+    name_nonce?: string;
+    mime_encrypted?: string;
+    mime_nonce?: string;
+    is_folder?: boolean;
+    parent_folder_id?: string | null;
+    revoked_at?: string | null;
 }
 /**
- * Bootstrap an MCP server. Loads + decrypts the state, instantiates
- * the backend client and the five tools, then connects over stdio.
- *
- * @throws `StatePassphraseInvalid` / `StateCorrupt` from state.ts.
- * @throws `Error` if `globalThis.fetch` is missing (Node <18).
+ * `GET /seal/{id}` — public metadata. No counter ticks here: `single_use`
+ * and `max_opens` are consumed by the ciphertext fetch, not by reading the
+ * description of a seal.
  */
-declare function createServer(options: McpServerOptions): Promise<McpServerHandle>;
-
+interface SealMetaWire {
+    id: string;
+    expires_at: string;
+    revoked_at: string | null;
+    e2ee: boolean;
+    nda_required: boolean;
+    otp_required: boolean;
+    single_use: boolean;
+    max_opens?: number | null;
+    total_bytes?: number;
+    /**
+     * P1-1: the server's own verdict on the caller's gate session. Absent on
+     * pre-P1-1 backends, which is why the web keeps a cookie heuristic behind
+     * an explicit "legacy" branch rather than treating absence as "invalid".
+     */
+    nda_session_valid?: boolean;
+    otp_session_valid?: boolean;
+    files: SealFileWire[];
+}
+/** One file row of `GET /seal/{id}/owner` (includes revoked files). */
+interface OwnerFileWire extends SealFileWire {
+    revoked_at?: string | null;
+}
+/** `GET /seal/{id}/owner` — the owner-authenticated view of a seal. */
+interface OwnerSealWire {
+    id: string;
+    created_at: string;
+    expires_at: string;
+    revoked_at?: string | null;
+    e2ee: boolean;
+    nda_required: boolean;
+    otp_required?: boolean;
+    single_use: boolean;
+    geo_allowlist: string[] | null;
+    max_opens: number | null;
+    tier?: string;
+    total_bytes?: number;
+    files: OwnerFileWire[];
+}
+/** One row of the access log. IPs arrive truncated; the full value never leaves the DB. */
+interface AuditEventWire {
+    id: string;
+    event: string;
+    ts: string;
+    country: string | null;
+    ip_truncated: string | null;
+    file_id: string | null;
+    filename: string | null;
+    range_request?: boolean;
+}
+/** Per-file aggregation of the access log. */
+interface AuditSummaryWire {
+    file_id: string | null;
+    filename: string | null;
+    downloads: number;
+    countries: string[];
+    subnets: string[];
+    last_download_ts: string | null;
+}
+/** `GET /seal/{id}/audit` — the human-readable access log. */
+interface AuditWire {
+    seal_id: string;
+    revoked_at: string | null;
+    events: AuditEventWire[];
+    summary: AuditSummaryWire[];
+}
+/** `POST /seal/{id}/subscriptions` — owner notification webhook. */
+interface SubscriptionWire {
+    id: string;
+    secret: string;
+}
+/** What an intake request asks for (SPEC-AGENTS §4.4). */
+type IntakeKind = 'secret' | 'file' | 'any';
 /**
- * Single URL resolver for the two origins the MCP server talks about
- * (ISSUE-0622).
- *
- * The two origins are INDEPENDENT in production:
- *
- *   - backend  → `https://api.seal.net`  — FastAPI, where uploads /
- *     metadata / revoke calls go;
- *   - public   → `https://seal.net`      — the frontend that share
- *     URLs must point at so a recipient's browser can open them.
- *
- * Before this module the public host was DERIVED from the backend URL
- * ("strip a trailing `/api`"), which worked for single-origin
- * self-hosted setups but produced `https://api.seal.net/s/…` links in
- * the default production configuration — the API origin serves no
- * frontend, so the link was dead on arrival.
- *
- * Resolution precedence (same for both origins):
- *   1. explicit value (CLI flag / `McpServerOptions` / library caller)
- *   2. environment variable (`SEAL_MCP_BACKEND_URL` / `SEAL_MCP_PUBLIC_HOST`)
- *   3. production default
+ * `/intake/{id}` — a person hands an agent a file or a secret through
+ * seal.net. `share_path` (`/s/{seal}/{code}#x25519:…`) appears once the page
+ * reported its seal, and only until the request expires; it opens only with
+ * the key named by `recipient_pub`.
+ */
+interface IntakeWire {
+    id: string;
+    status: 'pending' | 'fulfilled' | 'expired';
+    label: string;
+    what: string;
+    where_url: string | null;
+    kind: IntakeKind;
+    recipient_pub: string;
+    expires_at: string;
+    share_path: string | null;
+}
+interface IntakeCreate {
+    /** The agent's X25519 public key, base64url without padding. */
+    readonly recipientPub: string;
+    readonly label: string;
+    readonly what: string;
+    readonly whereUrl?: string;
+    readonly kind?: IntakeKind;
+    readonly ttlSeconds?: number;
+}
+/** camelCase file row, for callers that prefer it (Slack, MCP). */
+interface SealFileMeta {
+    readonly id: string;
+    readonly size: number;
+    readonly sha256_hex: string | null;
+    readonly name_encrypted?: string;
+    readonly name_nonce?: string;
+    readonly mime_encrypted?: string;
+    readonly mime_nonce?: string;
+}
+/** camelCase projection of `SealMetaWire`. */
+interface SealMetadata {
+    readonly id: string;
+    readonly expiresAt: string;
+    readonly revokedAt: string | null;
+    readonly e2ee: boolean;
+    readonly ndaRequired: boolean;
+    readonly otpRequired: boolean;
+    readonly singleUse: boolean;
+    readonly maxOpens: number | null;
+    readonly files: SealFileMeta[];
+}
+interface SealApiOptions {
+    /**
+     * Origin (or origin + prefix) every path is appended to. The browser
+     * passes its BFF prefix (`/api`) so gate cookies land on the SPA origin;
+     * a bot passes the API origin directly.
+     */
+    readonly baseUrl: string;
+    /** Injected `fetch`. Defaults to the global one. */
+    readonly fetch?: typeof fetch;
+    /**
+     * Credentials mode for every request.
+     *
+     * The browser needs `'include'` for the OTP/NDA session cookies. The
+     * public send-only SDK needs `'omit'`: the wildcard-CORS send endpoints
+     * answer `Access-Control-Allow-Origin: *`, which browsers refuse for a
+     * credentialed request — send auth is the `X-Owner-Token` header, never
+     * a cookie. Node ignores the field.
+     */
+    readonly credentials?: RequestCredentials;
+}
+/** Per-call knobs shared by every method. */
+interface RequestOptions {
+    readonly signal?: AbortSignal;
+}
+/** Knobs of `openDownload`. */
+interface DownloadRequestOptions extends RequestOptions {
+    /**
+     * `false` hands `file.not_ready` to the caller at once. Default: ask again
+     * a few times (see `openDownload`).
+     */
+    readonly retryNotReady?: boolean;
+}
+/** Query parameters accepted by the download endpoint. */
+interface DownloadTarget {
+    readonly fileId: string;
+    /** Public hand-out of a single file (SEAL Pro decision 2). */
+    readonly publicToken?: string;
+    /** Public hand-out of a whole seal. */
+    readonly viewToken?: string;
+    /**
+     * The caller is the seal's OWNER. A password, an NDA and a country list are
+     * what the owner asks of recipients, so a verified token passes them; it
+     * does not lift `single_use` / `max_opens`, which count every download
+     * (F-221). A token that does not verify is refused, not ignored.
+     */
+    readonly ownerToken?: string;
+}
+/** OTP verification input. `fileId`+`publicToken` scope the gate to one file. */
+interface OtpVerification {
+    readonly code: string;
+    readonly fileId?: string;
+    readonly publicToken?: string;
+}
+/** NDA acceptance input, mirroring the backend's snake_case payload. */
+interface NdaAcceptance {
+    readonly signature: string;
+    readonly timestamp: string;
+    readonly firstName: string;
+    readonly lastName: string;
+    readonly company?: string;
+    readonly fileId?: string;
+    readonly publicToken?: string;
+    /**
+     * The exact text the recipient saw. Transient — the backend renders it
+     * into the receipt PDF and never stores it.
+     */
+    readonly ndaText?: string;
+}
+/**
+ * The `/seal/*` client.
  *
- * Self-hosted deployments where frontend and backend live on other
- * origins must set BOTH knobs — the resolver never guesses one from
- * the other.
+ * Methods either return a parsed wire object or throw `BackendError`. Two
+ * of them (`openDownload`, `openAuditDownload`) return the raw `Response`
+ * instead: their bodies are bytes, and how bytes are consumed is a property
+ * of the runtime — the browser hands them to a service worker, the Slack
+ * bot streams them to disk, the MCP server buffers them.
  */
-declare const DEFAULT_BACKEND_URL = "https://api.seal.net";
-declare const DEFAULT_PUBLIC_HOST = "https://seal.net";
-declare const BACKEND_URL_ENV_VAR = "SEAL_MCP_BACKEND_URL";
-declare const PUBLIC_HOST_ENV_VAR = "SEAL_MCP_PUBLIC_HOST";
-/** Backend base URL: explicit → `SEAL_MCP_BACKEND_URL` → production default. */
-declare function resolveBackendUrl(explicit?: string): string;
-/** Public share-URL origin: explicit → `SEAL_MCP_PUBLIC_HOST` → production default. */
-declare function resolvePublicHost(explicit?: string): string;
+declare class SealApi {
+    readonly baseUrl: string;
+    private readonly injectedFetch;
+    private readonly credentials;
+    constructor(options: SealApiOptions);
+    /**
+     * The transport for one request.
+     *
+     * Called with `globalThis` as receiver, ALWAYS. Storing `globalThis.fetch`
+     * on an instance and calling it as `this.fetchImpl(...)` hands the browser a
+     * receiver that is not `window`, and it answers "Failed to execute 'fetch'
+     * on 'Window': Illegal invocation". Node does not care, which is exactly why
+     * the previous copies of this client — all of them Node-only — could carry
+     * the same line for a year without anyone noticing.
+     *
+     * Resolved per call rather than captured in the constructor: a browser host
+     * may replace `window.fetch` after this module is evaluated (SEAL Pro does,
+     * to re-anchor root-absolute paths onto its `/pro` base path), and clients
+     * built as module-level singletons are constructed before that happens.
+     */
+    private fetchImpl;
+    /** Absolute (or origin-relative) URL for a path that must start with `/`. */
+    url(path: string): string;
+    private request;
+    private static ownerHeaders;
+    /** `GET /seal/{id}` — public metadata. Ticks no counters. */
+    getMetadata(sealId: string, opts?: RequestOptions): Promise<SealMetaWire>;
+    /**
+     * `GET /seal/{id}/share/{code}` — the recipient's encrypted key blob.
+     *
+     * Public by construction: the blob is opaque ciphertext, so the server has
+     * nothing to gate on. Reading it ticks no counter, which is what lets a
+     * client show the file list before the recipient commits to a download.
+     */
+    getShareBlob(sealId: string, shareCode: string, opts?: RequestOptions): Promise<Uint8Array<ArrayBuffer>>;
+    /**
+     * `POST /seal/{id}/otp` — verify the recipient password.
+     *
+     * The backend answers with `Set-Cookie: otp_{sealId}=…`. A browser stores
+     * it and cannot read it back (`sessionCookie` is null there, by design);
+     * Node has no cookie jar, so the pair is extracted and returned for the
+     * caller to forward on the download.
+     */
+    verifyOtp(sealId: string, input: OtpVerification, opts?: RequestOptions): Promise<{
+        status: string;
+        sessionCookie: string | null;
+    }>;
+    /** `POST /seal/{id}/nda` — record the recipient's signature. */
+    acceptNda(sealId: string, input: NdaAcceptance, opts?: RequestOptions): Promise<{
+        status: string;
+    }>;
+    /** The ciphertext-download URL. Building it is separate from fetching it. */
+    downloadUrl(sealId: string, target: DownloadTarget): string;
+    /**
+     * `GET /seal/{id}/download` — the ciphertext, as a live `Response`.
+     *
+     * THIS is the call that consumes `single_use` / `max_opens`, so every
+     * policy check a caller wants to make belongs before it: once a counter
+     * ticks it stays ticked, whatever the caller does with the bytes.
+     *
+     * The backend answers 307 to a signed storage URL for EVERY seal — it never
+     * serves a byte itself (audit/SPEC-UPLOAD-SCALE.md §6). A runtime whose
+     * `fetch` follows redirects (Node: Slack, MCP, SDK) gets the ciphertext
+     * from storage here; the browser talks to its BFF, which hands the same
+     * URL back as JSON because script cannot read `Location`. The body is left
+     * unread on purpose: how bytes are consumed is the runtime's business.
+     *
+     * `file.not_ready` (409, "clients should retry after retry_after") is
+     * asked again, up to NOT_READY_MAX_RETRIES times, pausing `retry_after`
+     * seconds. It is a SAFETY NET, not the mechanism: the sender waits for
+     * verification before handing out a link, and recipients are only listed
+     * verified files, so this is met by a client that kept an older listing or
+     * by a verification slower than the sender's wait. Few and spaced, on
+     * purpose — every refused attempt writes a line to the owner's access log
+     * and spends the download rate limit (F-162). Asking again is safe: the
+     * backend refuses an unverified file BEFORE it counts an open
+     * (`seal/download.py`, pinned by `test_download_gate_order.py`).
+     *
+     * Its terminal twin, `file.verification_failed`, is never retried — the
+     * bytes were rejected and are being burned. It is recognisable only by
+     * `appCode`: its HTTP status is 410, which `code` folds into `revoked`.
+     */
+    openDownload(sealId: string, target: DownloadTarget & {
+        readonly sessionCookie?: string;
+    }, opts?: DownloadRequestOptions): Promise<Response>;
+    /** `GET /seal/{id}/owner` — the owner's view, revoked files included. */
+    getOwnerSeal(sealId: string, ownerToken: string, opts?: RequestOptions): Promise<OwnerSealWire>;
+    /**
+     * `GET /seal/{id}/blob` — the owner's encrypted key blob.
+     *
+     * Public endpoint (opaque ciphertext). The `ETag` travels back because a
+     * writer must send it as `If-Match`: the blob is read-modify-written by
+     * every append, and two tabs doing that without CAS silently lose keys.
+     */
+    readOwnerBlob(sealId: string, opts?: RequestOptions): Promise<{
+        blob: Uint8Array<ArrayBuffer>;
+        etag: string | null;
+    }>;
+    /**
+     * `PATCH /seal/{id}/blob` — replace the owner's encrypted key blob.
+     *
+     * `ifMatch` opts into the CAS contract; without it the backend takes the
+     * legacy last-write-wins path. A stale version comes back as a
+     * `BackendError` with `status === 412` and `appCode === 'blob.version_mismatch'`.
+     */
+    writeOwnerBlob(sealId: string, ownerToken: string, encryptedBlobB64: string, opts?: RequestOptions & {
+        readonly ifMatch?: string | null;
+    }): Promise<{
+        etag: string | null;
+    }>;
+    /** `POST /seal/{id}/share` — mint a share link, returns its code. */
+    createShareLink(sealId: string, ownerToken: string, encryptedBlobB64: string, opts?: RequestOptions): Promise<string>;
+    /**
+     * `POST /seal/{id}/share/{code}/revoke` — revoke one share link.
+     * Idempotent: an already-revoked link is success, not a failure.
+     */
+    revokeShareLink(sealId: string, shareCode: string, ownerToken: string, opts?: RequestOptions): Promise<void>;
+    /**
+     * `POST /seal/{id}/revoke` — revoke the whole seal.
+     *
+     * Idempotent, including at the extremes: a seal that is already gone (404)
+     * or already revoked (410) satisfies the caller's intent, so both count as
+     * success. `revokedAt` is null when the server had nothing left to report.
+     */
+    revoke(sealId: string, ownerToken: string, opts?: RequestOptions): Promise<{
+        status: string;
+        revokedAt: string | null;
+    }>;
+    /**
+     * `POST /seal/{id}/files/{fileId}/revoke` — revoke a single file.
+     * Idempotent for the same reason as the share-link revoke.
+     */
+    revokeFile(sealId: string, fileId: string, ownerToken: string, opts?: RequestOptions): Promise<void>;
+    /** `GET /seal/{id}/audit` — the access log, PII already truncated server-side. */
+    getAudit(sealId: string, ownerToken: string, opts?: RequestOptions): Promise<AuditWire>;
+    /**
+     * `GET /seal/{id}/audit/download` — the signed JSONL export, as a live
+     * `Response`. It is an evidentiary artifact (Ed25519 over each line), so
+     * the bytes are handed over untouched.
+     */
+    openAuditDownload(sealId: string, ownerToken: string, opts?: RequestOptions): Promise<Response>;
+    /**
+     * `POST /seal/{id}/subscriptions` — register an owner-notification
+     * webhook. The derived HMAC secret is returned exactly once.
+     */
+    createSubscription(sealId: string, ownerToken: string, body?: {
+        readonly reference?: string;
+    }, opts?: RequestOptions): Promise<SubscriptionWire>;
+    /**
+     * `POST /billing/checkout` — the Stripe payment page for a seal registered
+     * above the free limit (SPEC-AGENTS §5.2). A repeat call within the
+     * session's life returns the same page.
+     */
+    createCheckout(sealId: string, ownerToken: string, tier: string, opts?: RequestOptions): Promise<string>;
+    /** `POST /intake` — open a request; the person answers at `/i/{id}`. */
+    createIntake(input: IntakeCreate, opts?: RequestOptions): Promise<IntakeWire>;
+    /**
+     * `GET /intake/{id}` — the request as it stands. `waitSeconds` (at most
+     * `limits.json::INTAKE_WAIT_MAX_SECONDS`) holds the answer until the page
+     * reports or the wait runs out.
+     */
+    getIntake(intakeId: string, opts?: RequestOptions & {
+        readonly waitSeconds?: number;
+    }): Promise<IntakeWire>;
+    /** `POST /intake/{id}/fulfil` — the page reports the seal it made; once. */
+    fulfilIntake(intakeId: string, link: {
+        readonly sealId: string;
+        readonly shareCode: string;
+        readonly fragment: string;
+    }, opts?: RequestOptions): Promise<IntakeWire>;
+}
 
 /**
  * Streaming Uploader Types
@@ -419,6 +768,115 @@ interface SingleFileUploadResult {
  */
 declare function uploadSingleFile(ctx: UploadContext, file: File, policy?: UploadPolicy, callbacks?: UploadCallbacks): Promise<SingleFileUploadResult>;
 
+/** What a workload needs to be itself: which workload, which API, and its private seed. */
+interface WorkloadCredentials {
+    workloadId: string;
+    /** API base URL including `/api/v1`; in production `https://api.seal.net/pro-api/api/v1`. */
+    baseUrl: string;
+    /** The 64-byte seed (base64) both private keys derive from. */
+    seedB64: string;
+}
+
+/**
+ * MCP server bootstrap — wires the five tools (`seal_share`,
+ * `seal_request`, `seal_open`, `seal_list`, `seal_revoke`) to a
+ * stdio-transport `McpServer` instance, and `seal_pro_secret_use`,
+ * `seal_pro_secret_request` and `seal_pro_file_get` when SEAL Pro workload
+ * credentials exist (contract `pro_tools`).
+ *
+ * The bootstrap is intentionally factored as a `createServer()`
+ * factory that returns an awaitable handle, NOT a hard-coded
+ * `main()` entry. That shape:
+ *   - lets `cli.ts` configure passphrase delivery, state path,
+ *     backend base URL, etc. before launching;
+ *   - lets test code spawn an in-process MCP without spawning a
+ *     subprocess;
+ *   - keeps the "where do creds come from?" decision out of the
+ *     pure tool implementations.
+ *
+ * Tool `title`, `description` and `annotations` come from
+ * `shared/contracts/seal_mcp.v1.json` (contract first, §6.2), and so do
+ * the descriptions of the inputs the contract describes; the zod input
+ * schemas live here.
+ *
+ * Three stateful concerns the factory owns (all three skipped in
+ * ephemeral mode, `state: null`, where nothing touches the disk):
+ *   - **Exclusive state lock (ISSUE-0623)**: `acquireStateLock` makes
+ *     this process the ONLY writer of the state dir for its lifetime;
+ *     a second `serve` on the same dir fails fast instead of silently
+ *     clobbering handles. Released in `close()` / on process exit.
+ *   - **State persistence**: each tool mutates `ctx.state` in-place
+ *     and calls `await ctx.persist()`; persist() re-encrypts the
+ *     view and writes atomically via `state.saveState`. A mutex
+ *     serialises persist() calls so concurrent tool calls cannot
+ *     race on the same on-disk envelope. Startup runs a journal
+ *     recovery pass (`recovery.ts`) before any tool registers.
+ *   - **Tool errors**: thrown `ToolError`s are converted to MCP's
+ *     `{ isError: true, content: [...] }` payload with the typed
+ *     `code` echoed back to the model. Other errors bubble as
+ *     internal_error so the model never sees raw stack traces.
+ */
+
+interface McpServerOptions {
+    /** Encrypted state on disk; `null` = ephemeral: identity and handles in memory only. */
+    readonly state: {
+        readonly path: string;
+        readonly passphrase: string;
+    } | null;
+    readonly backendBaseUrl?: string;
+    readonly publicHost?: string;
+    /** SEAL Pro workload; omitted = read the environment or the enrollment file, `null` = none. */
+    readonly workload?: WorkloadCredentials | null;
+}
+interface McpServerHandle {
+    readonly mcp: McpServer;
+    readonly transport: StdioServerTransport;
+    readonly close: () => Promise<void>;
+}
+/**
+ * Bootstrap an MCP server. Loads + decrypts the state, instantiates
+ * the backend client and the five tools, then connects over stdio.
+ *
+ * @throws `StatePassphraseInvalid` / `StateCorrupt` from state.ts.
+ * @throws `Error` if `globalThis.fetch` is missing (Node <18).
+ */
+declare function createServer(options: McpServerOptions): Promise<McpServerHandle>;
+
+/**
+ * Single URL resolver for the two origins the MCP server talks about
+ * (ISSUE-0622).
+ *
+ * The two origins are INDEPENDENT in production:
+ *
+ *   - backend  → `https://api.seal.net`  — FastAPI, where uploads /
+ *     metadata / revoke calls go;
+ *   - public   → `https://seal.net`      — the frontend that share
+ *     URLs must point at so a recipient's browser can open them.
+ *
+ * Before this module the public host was DERIVED from the backend URL
+ * ("strip a trailing `/api`"), which worked for single-origin
+ * self-hosted setups but produced `https://api.seal.net/s/…` links in
+ * the default production configuration — the API origin serves no
+ * frontend, so the link was dead on arrival.
+ *
+ * Resolution precedence (same for both origins):
+ *   1. explicit value (CLI flag / `McpServerOptions` / library caller)
+ *   2. environment variable (`SEAL_MCP_BACKEND_URL` / `SEAL_MCP_PUBLIC_HOST`)
+ *   3. production default
+ *
+ * Self-hosted deployments where frontend and backend live on other
+ * origins must set BOTH knobs — the resolver never guesses one from
+ * the other.
+ */
+declare const DEFAULT_BACKEND_URL = "https://api.seal.net";
+declare const DEFAULT_PUBLIC_HOST = "https://seal.net";
+declare const BACKEND_URL_ENV_VAR = "SEAL_MCP_BACKEND_URL";
+declare const PUBLIC_HOST_ENV_VAR = "SEAL_MCP_PUBLIC_HOST";
+/** Backend base URL: explicit → `SEAL_MCP_BACKEND_URL` → production default. */
+declare function resolveBackendUrl(explicit?: string): string;
+/** Public share-URL origin: explicit → `SEAL_MCP_PUBLIC_HOST` → production default. */
+declare function resolvePublicHost(explicit?: string): string;
+
 /**
  * Out-of-band delivery of the share link to the human user. The link is
  * the whole capability (key in the fragment); there is no password.
@@ -963,7 +1421,7 @@ declare function promptHiddenPassphrase(prompt: string): Promise<string>;
 interface ToolContext {
     readonly state: StateView;
     readonly identity: Identity;
-    readonly client: S;
+    readonly client: SealApi;
     /**
      * Persistence hook. The server is responsible for serialising and
      * encrypting `ctx.state` to disk after a successful mutation; tools
@@ -1320,4 +1778,4 @@ interface SealShareDeps {
 }
 declare function sealShare(ctx: ToolContext, input: SealShareInput, deps?: SealShareDeps): Promise<SealShareOutput>;
 
-export { APP_NAME, type AcquireLockDeps, type AuditEntry, BACKEND_URL_ENV_VAR, DEFAULT_BACKEND_URL, DEFAULT_PUBLIC_HOST, type HandleEntry, HandoffBothChannelsFailedError, type HandoffPayload, type HandoffResult, type Identity, type IdentityFields, KEYCHAIN_ACCOUNT, KEYCHAIN_SERVICE, type KeytarLike, KeytarUnavailableError, LOCK_FILE_NAME, type LockHolderInfo, type McpServerHandle, type McpServerOptions, PASSPHRASE_ENV_VAR, PUBLIC_HOST_ENV_VAR, PassphraseNotFoundError, type PassphraseSource, type PathResolution, type PendingCompensation, type PendingOperation, type PendingStep, type RecoveryReport, type ResolveOptions, type ResolvedPassphrase, type RevokeClient, STATE_FILE_NAME, type SealListInput, type SealListOutput, type SealOpenInput, type SealOpenOutput, type SealRevokeInput, type SealRevokeOutput, type SealShareInput, type SealShareMode, type SealShareOutput, StateCorrupt, type StateDirSource, type StateLock, StateLockedError, StatePassphraseInvalid, type StateView, ToolError, acquireStateLock, createEmptyState, createServer, deleteKeychainPassphrase, generateHandle, generateIdentity, identityToFields, isValidHandle, loadIdentity, loadState, performHandoff, probeKeychain, probeStateLock, promptHiddenPassphrase, recoverPendingOperations, resolveBackendUrl, resolvePassphraseFromStores, resolvePublicHost, resolveStateDir, saveState, sealList, sealOpen, sealRevoke, sealShare, setKeychainPassphrase };
+export { APP_NAME, type AcquireLockDeps, type AuditEntry, BACKEND_URL_ENV_VAR, BackendError, DEFAULT_BACKEND_URL, DEFAULT_PUBLIC_HOST, type HandleEntry, HandoffBothChannelsFailedError, type HandoffPayload, type HandoffResult, type Identity, type IdentityFields, KEYCHAIN_ACCOUNT, KEYCHAIN_SERVICE, type KeytarLike, KeytarUnavailableError, LOCK_FILE_NAME, type LockHolderInfo, type McpServerHandle, type McpServerOptions, PASSPHRASE_ENV_VAR, PUBLIC_HOST_ENV_VAR, PassphraseNotFoundError, type PassphraseSource, type PathResolution, type PendingCompensation, type PendingOperation, type PendingStep, type RecoveryReport, type ResolveOptions, type ResolvedPassphrase, type RevokeClient, STATE_FILE_NAME, SealApi, type SealApiOptions, type SealListInput, type SealListOutput, type SealMetadata, type SealOpenInput, type SealOpenOutput, type SealRevokeInput, type SealRevokeOutput, type SealShareInput, type SealShareMode, type SealShareOutput, StateCorrupt, type StateDirSource, type StateLock, StateLockedError, StatePassphraseInvalid, type StateView, ToolError, acquireStateLock, createEmptyState, createServer, deleteKeychainPassphrase, generateHandle, generateIdentity, identityToFields, isValidHandle, loadIdentity, loadState, performHandoff, probeKeychain, probeStateLock, promptHiddenPassphrase, recoverPendingOperations, resolveBackendUrl, resolvePassphraseFromStores, resolvePublicHost, resolveStateDir, saveState, sealList, sealOpen, sealRevoke, sealShare, setKeychainPassphrase };