sealnet-mcp 0.2.4 → 0.3.0

package/dist/index.d.ts

@@ -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,110 @@ 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` open the state with the agent's key, resolve the
+ *     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.
+ *
+ * Two stateful concerns the factory owns:
+ *   - **State (SPEC-ADDRESS F1 §4)**: every MCP host on the machine runs
+ *     its own `serve` on the same state, so each tool change goes through
+ *     `ctx.update` = `state.updateState`: under the state lock, read the
+ *     file anew, apply the change, save. Startup runs a journal recovery
+ *     pass (`recovery.ts`) the same way, before any tool registers. In
+ *     ephemeral mode (`state: null`) the change applies to memory only.
+ *   - **Tool errors**: thrown `ToolError`s (and `state_busy`) 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 (`seed.ts::openAgentState`); `null` = ephemeral: a new identity, 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.
@@ -595,6 +1048,15 @@ interface PendingOperation {
      * backend — see `HandleEntry.backend_url`.
      */
     backend_url?: string;
+    /**
+     * The process running the operation (SPEC-ADDRESS F1 §4): several MCP
+     * hosts share this state, and recovery leaves an entry alone while its
+     * owner may still be running. Absent on 0.2.x entries.
+     */
+    readonly owner?: {
+        readonly pid: number;
+        readonly hostname: string;
+    };
 }
 interface AuditEntry {
     readonly ts: string;
@@ -649,6 +1111,19 @@ declare function loadState(passphrase: string, statePath: string): Promise<State
  * is non-adaptive — but cheap and follows defence-in-depth).
  */
 declare function saveState(state: StateView, passphrase: string, statePath: string): Promise<void>;
+/**
+ * A change to the state: insertions, and deletions as explicit operations
+ * (a key missing from one process's view must not delete what another
+ * process wrote). `false` = nothing to write, only read the file anew.
+ */
+type StateMutation = (state: StateView) => boolean | void | Promise<boolean | void>;
+/**
+ * The one way to change the state on disk (SPEC-ADDRESS F1 §4): under the
+ * state lock, read `state.json` anew, apply `mutate`, save. Several MCP hosts
+ * share the file, so a process never writes its own copy of the whole view.
+ * Returns the state as it now is.
+ */
+declare function updateState(passphrase: string, statePath: string, mutate: StateMutation): Promise<StateView>;
 
 /**
  * X25519 identity for the MCP server (incoming targeted-share recipient).
@@ -658,9 +1133,10 @@ declare function saveState(state: StateView, passphrase: string, statePath: stri
  * `seal keygen`, the SDK and `sealnet` use — byte-for-byte compatible by
  * construction, not by spec.
  *
- * The `Identity` view is held only in process memory; it is reconstructed
- * from `state.identity` on every server start. The serialised form lives
- * inside the AES-256-GCM ciphertext of `state.ts`.
+ * The secret is the agent's root secret (`seed.ts`, SPEC-ADDRESS F1); the
+ * `Identity` view is reconstructed from `state.identity`, which must equal
+ * it, on every server start. The serialised form lives inside the
+ * AES-256-GCM ciphertext of `state.ts`.
  */
 
 interface Identity {
@@ -669,6 +1145,8 @@ interface Identity {
 }
 /** A fresh X25519 keypair for this server. */
 declare function generateIdentity(): Promise<Identity>;
+/** The keypair of a root secret (`seed.ts`): the seed is the X25519 secret. */
+declare function identityFromSeed(seed: Uint8Array): Promise<Identity>;
 /**
  * Project an `Identity` into the serialised form that lives in
  * `state.identity` (base64-encoded raw bytes; matches contract
@@ -683,22 +1161,22 @@ declare function identityToFields(id: Identity): IdentityFields;
 declare function loadIdentity(fields: IdentityFields): Promise<Identity>;
 
 /**
- * Exclusive lifetime lock for the seal-mcp state directory (ISSUE-0623).
+ * The seal-mcp state lock, taken for each write (ISSUE-0623, SPEC-ADDRESS F1 §4).
  *
  * # Why
  *
- * `state.json` is a whole-envelope read-modify-write store: the server
- * loads the decrypted view once at boot and every `persist()` re-encrypts
- * and atomically replaces the file. Two MCP processes pointed at the same
- * state dir (the DEFAULT for every MCP host on the machine — Cursor +
- * Claude Desktop both spawn `seal-mcp serve`) would silently overwrite
- * each other's handles and audit entries: last writer wins, the other
- * process's owner tokens are gone forever.
+ * `state.json` is a whole-envelope read-modify-write store. Every MCP host on
+ * the machine (Claude Desktop, Claude Code, Cursor) spawns its own
+ * `sealnet-mcp serve` on the same state dir, and all of them must work: one
+ * seed, one address. So a process does not own the state for its lifetime;
+ * each change re-reads the file, applies this process's change and saves
+ * (`state.ts::updateState`), and the lock makes that sequence exclusive. Two
+ * writers without it would overwrite each other's handles: last writer wins,
+ * the other process's owner tokens are gone forever.
  *
- * The fix is a single-writer discipline: exactly one process may hold
- * the state open for writing for its lifetime. Second `serve` (or a
- * concurrent `init`/`reset`) fails fast with a legible error instead of
- * corrupting capability state.
+ * Waiting for the lock ends after `LOCK_WAIT_MS` with `StateBusyError`
+ * (`state_busy`). Inside one process the writes queue (`withStateLock`): the
+ * lock file names a pid, and the process would otherwise wait for itself.
  *
  * # Mechanism (DR-mcp: TOCTOU-hardened)
  *
@@ -719,10 +1197,11 @@ declare function loadIdentity(fields: IdentityFields): Promise<Identity>;
  * fresh holder slipped in between probe and rename), and only then
  * creates its own lock. A lock from a different hostname (network
  * volume) is never broken automatically — we cannot probe liveness
- * across hosts.
+ * across hosts. The same rule (`holderMayRun`) tells journal recovery
+ * whose upload it must leave alone.
  *
  * PID-recycling is the accepted residual risk: the probe window is
- * milliseconds and the failure mode (refusing to start) is safe.
+ * milliseconds and the failure mode (waiting, then `state_busy`) is safe.
  *
  * Release verifies ownership: the lock is unlinked only if it still
  * carries OUR pid+hostname, so a process can never release a lock a
@@ -741,6 +1220,11 @@ declare class StateLockedError extends Error {
     readonly lockPath: string;
     constructor(lockPath: string, holder: LockHolderInfo | null);
 }
+/** The lock stayed taken for `LOCK_WAIT_MS`; nothing was written (contract `state_busy`). */
+declare class StateBusyError extends Error {
+    readonly code = "state_busy";
+    constructor(locked: StateLockedError);
+}
 interface StateLock {
     readonly lockPath: string;
     /** Idempotent. Removes the lock file (if still ours) and the process-exit hook. */
@@ -754,6 +1238,11 @@ interface AcquireLockDeps {
     /** Override hostname for tests. */
     readonly host?: string;
 }
+/**
+ * Whether the process a lock or a journal entry names may still be running:
+ * alive on this host, or on another host, which cannot be probed.
+ */
+declare function holderMayRun(holder: Pick<LockHolderInfo, 'pid' | 'hostname'>, deps?: AcquireLockDeps): boolean;
 /**
  * Acquire the exclusive state-dir lock or throw `StateLockedError`.
  *
@@ -763,6 +1252,11 @@ interface AcquireLockDeps {
  * `mode` does not repair an existing directory).
  */
 declare function acquireStateLock(stateDir: string, deps?: AcquireLockDeps): Promise<StateLock>;
+/**
+ * Run `fn` holding the state lock: waits up to `LOCK_WAIT_MS` for another
+ * process to finish its write, then fails with `StateBusyError`.
+ */
+declare function withStateLock<T>(stateDir: string, fn: () => Promise<T>, deps?: AcquireLockDeps): Promise<T>;
 /**
  * Read-only probe for `doctor`: report who (if anyone) holds the lock
  * and whether it looks stale from this host's perspective.
@@ -776,8 +1270,10 @@ declare function probeStateLock(stateDir: string, deps?: AcquireLockDeps): Promi
 /**
  * Startup recovery for the durable operation journal (ISSUE-0623).
  *
- * Runs once in `createServer()` after the state lock is held and the
- * envelope is decrypted, BEFORE any tool can execute. Each surviving
+ * Runs once in `createServer()`, under the state lock (`updateState`),
+ * BEFORE any tool can execute. Several MCP hosts share the state
+ * (SPEC-ADDRESS F1 §4), so an entry whose `owner` may still be running
+ * is a neighbour's upload in progress and is left alone. Every other
  * `state.pending` entry is a `seal_share` that crashed (or lost its
  * process) mid-flight; the step recorded at the last checkpoint tells
  * us exactly what is safe to do:
@@ -827,7 +1323,7 @@ interface RecoveryReport {
 }
 /**
  * Reconcile `view.pending` in place. Returns the report + whether the
- * view changed (caller persists once at the end — a crash during
+ * view changed (the caller writes once at the end — a crash during
  * recovery just means the same idempotent pass reruns next start).
  */
 declare function recoverPendingOperations(view: StateView, client: RevokeClient, opts?: {
@@ -877,33 +1373,29 @@ interface ResolveOptions {
 }
 declare function resolveStateDir(opts?: ResolveOptions): PathResolution;
 
-/**
- * Passphrase resolution + hidden TTY prompt for `seal-mcp`.
- *
- * Priority chain (per `shared/contracts/seal_mcp.v1.json::passphrase_delivery`):
- *
- *   1. OS keychain via `@napi-rs/keyring` (service `'seal-mcp'`, account `'state'`).
- *   2. `SEAL_MCP_PASSPHRASE` environment variable. Logs a warning to
- *      stderr because env vars are visible via `/proc/<pid>/environ`
- *      on Linux, `ps -E`/`procstat -e` on BSD, and via the process
- *      object on Windows.
- *   3. Cleartext on disk — REFUSED. Listed only to document the
- *      refusal; the resolver has no codepath that reads from a file.
- *
- * The keychain module is an optional dependency loaded lazily (same pattern
- * as `clipboardy` in `handoff.ts`), so a machine without it, or without a
- * keychain, falls back to the env var without crashing at import time.
- */
-declare const KEYCHAIN_SERVICE: "seal-mcp";
-declare const KEYCHAIN_ACCOUNT: "state";
-declare const PASSPHRASE_ENV_VAR: "SEAL_MCP_PASSPHRASE";
-type PassphraseSource = 'keychain' | 'env';
-interface ResolvedPassphrase {
-    readonly passphrase: string;
-    readonly source: PassphraseSource;
+declare const SEED_ENV_VAR = "SEAL_SEED";
+declare const EPHEMERAL_ENV_VAR = "SEAL_MCP_EPHEMERAL";
+/** 0.2.x only: read once, to move a state of that version. */
+declare const PASSPHRASE_ENV_VAR = "SEAL_MCP_PASSPHRASE";
+declare const SEED_FILE_NAME = "seed";
+declare const KEYCHAIN_SERVICE = "seal-mcp";
+declare const KEYCHAIN_ACCOUNT = "seed";
+type SeedSource = 'env' | 'keychain' | 'file';
+interface RootSecret {
+    readonly seed: Uint8Array;
+    readonly source: SeedSource;
+}
+declare class SeedInvalidError extends Error {
+    readonly code = "seed_invalid";
+    constructor(where: string);
+}
+/** The state belongs to another key (contract `root_secret.identity_conflict`). */
+declare class IdentityConflictError extends Error {
+    readonly code = "identity_conflict";
+    constructor(statePath: string);
 }
 /**
- * Surface used by `passphrase.ts` — `keytar`'s shape, kept narrow on purpose
+ * Surface used by this module — `keytar`'s shape, kept narrow on purpose
  * so tests can stub the keychain without pulling in the native module.
  */
 interface KeytarLike {
@@ -911,43 +1403,35 @@ interface KeytarLike {
     setPassword(service: string, account: string, password: string): Promise<void>;
     deletePassword(service: string, account: string): Promise<boolean>;
 }
-declare class KeytarUnavailableError extends Error {
-    readonly code = "keytar_unavailable";
-    constructor(detail: string);
-}
-declare class PassphraseNotFoundError extends Error {
-    readonly code = "passphrase_not_found";
-    constructor();
+/** The seed from the first source that has one; `null` when none has. */
+declare function readSeed(stateDir: string, env?: NodeJS.ProcessEnv): Promise<RootSecret | null>;
+/** The state passphrase: base64url(HKDF-SHA256(seed, 'seal-mcp:state:v1', 'passphrase', 32 bytes)). */
+declare function statePassphrase(seed: Uint8Array): string;
+interface AgentState {
+    readonly root: RootSecret;
+    readonly passphrase: string;
+    /** This call made the state (a first start). */
+    readonly created: boolean;
+    /** This call moved a 0.2.x state under the seed: where that version's passphrase came from. */
+    readonly moved: 'keychain' | 'env' | null;
 }
 /**
- * Try keychain first, then env var. NEVER reads from a file. Returns
- * `null` if neither source has a passphrase — caller decides whether to
- * prompt interactively (`init`) or hard-refuse (`serve`).
- */
-declare function resolvePassphraseFromStores(env?: NodeJS.ProcessEnv): Promise<ResolvedPassphrase | null>;
-/**
- * Probe whether the OS keychain is usable AND whether the seal-mcp
- * entry already exists. Used by `sealnet-mcp doctor`.
+ * The agent's state, opened with its root secret: made on the first start
+ * (with the seed, when there is none), moved once from 0.2.x (SPEC-ADDRESS
+ * F1 §3), refused when it belongs to another key. Under the state lock, so
+ * two hosts starting together make one seed and one state.
  */
+declare function openAgentState(path: PathResolution, env?: NodeJS.ProcessEnv): Promise<AgentState>;
+/** `reset`: the seed file and the keychain entries (the seed, and 0.2.x's passphrase). */
+declare function deleteRootSecret(stateDir: string): Promise<{
+    seedFile: boolean;
+    keychain: boolean;
+}>;
+/** `doctor`: is there a keychain, and does it hold the seed. */
 declare function probeKeychain(): Promise<{
     available: boolean;
-    hasEntry: boolean;
+    hasSeed: boolean;
 }>;
-declare function setKeychainPassphrase(passphrase: string): Promise<void>;
-declare function deleteKeychainPassphrase(): Promise<boolean>;
-/**
- * Prompt for a passphrase on the TTY without echoing keystrokes.
- *
- * Requires `process.stdin.isTTY === true` — caller must verify ahead
- * of time and route non-TTY callers to the env-var path.
- *
- * Special keys:
- *   - `\r` / `\n`               → resolve with the accumulated buffer.
- *   - `\u0003` (Ctrl-C)         → reject with `cancelled`.
- *   - `\u0004` (Ctrl-D) on empty buffer → reject with `cancelled`.
- *   - `\u007f` / `\b` (Backspace) → delete last char.
- */
-declare function promptHiddenPassphrase(prompt: string): Promise<string>;
 
 /**
  * Shared `ToolContext` and helpers used by every tool implementation.
@@ -959,20 +1443,20 @@ declare function promptHiddenPassphrase(prompt: string): Promise<string>;
  * context) and prevents accidental global state.
  */
 
-/** Mutable, single-source-of-truth state passed across tool calls. */
+/** What every tool call gets. */
 interface ToolContext {
+    /** The state as this process last read or wrote it; `update` replaces it. */
     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
-     * mutate `ctx.state` in-place and call `await ctx.persist()` when
-     * ready. Errors propagate to the tool which surfaces them as a
-     * structured MCP error to the model.
+     * The one way a tool changes the state (`state.ts::updateState`): the file
+     * is read anew under the lock, `mutate` applied and saved, and `state`
+     * becomes the result. Other MCP hosts on the machine write the same file,
+     * so a tool never mutates `state` itself. Errors propagate to the tool.
      */
-    persist: () => Promise<void>;
-    /** No keychain, nothing on disk: handles die with the process (receipt says so). */
+    readonly update: (mutate: StateMutation) => Promise<void>;
+    /** `serve --ephemeral`, nothing on disk: handles die with the process (receipt says so). */
     readonly ephemeral?: boolean;
     /** `seal_request` handles waiting on a link, to their intake id; in memory only. */
     readonly requests?: Map<string, string>;
@@ -1320,4 +1804,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 AgentState, type AuditEntry, BACKEND_URL_ENV_VAR, BackendError, DEFAULT_BACKEND_URL, DEFAULT_PUBLIC_HOST, EPHEMERAL_ENV_VAR, type HandleEntry, HandoffBothChannelsFailedError, type HandoffPayload, type HandoffResult, type Identity, IdentityConflictError, type IdentityFields, KEYCHAIN_ACCOUNT, KEYCHAIN_SERVICE, type KeytarLike, LOCK_FILE_NAME, type LockHolderInfo, type McpServerHandle, type McpServerOptions, PASSPHRASE_ENV_VAR, PUBLIC_HOST_ENV_VAR, type PathResolution, type PendingCompensation, type PendingOperation, type PendingStep, type RecoveryReport, type ResolveOptions, type RevokeClient, type RootSecret, SEED_ENV_VAR, SEED_FILE_NAME, 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, SeedInvalidError, type SeedSource, StateBusyError, StateCorrupt, type StateDirSource, type StateLock, StateLockedError, type StateMutation, StatePassphraseInvalid, type StateView, ToolError, acquireStateLock, createEmptyState, createServer, deleteRootSecret, generateHandle, generateIdentity, holderMayRun, identityFromSeed, identityToFields, isValidHandle, loadIdentity, loadState, openAgentState, performHandoff, probeKeychain, probeStateLock, readSeed, recoverPendingOperations, resolveBackendUrl, resolvePublicHost, resolveStateDir, saveState, sealList, sealOpen, sealRevoke, sealShare, statePassphrase, updateState, withStateLock };