sealnet-mcp 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,1325 @@
+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.
+ *
+ * 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;
+
+/**
+ * Streaming Uploader Types
+ *
+ * CANON: All upload logic is in internal/upload-engine.ts
+ * This file exports ONLY types for backwards compatibility.
+ */
+/**
+ * Progress of one upload call, in ONE base.
+ *
+ * It used to come in two: the single-request path reported a percentage
+ * WITHIN each phase, over plaintext bytes, re-zeroing at every phase
+ * boundary; the multipart path reported one global percentage over delivered
+ * ciphertext. Nothing in the event said which, so every consumer guessed from
+ * the file size and carried its own projection — six of them, all different
+ * (F-150, F-159, F-165, F-165a, F-177). The emitter is fixed instead, and the
+ * projections are gone.
+ */
+interface UploadProgress {
+    phase: "hashing" | "encrypting" | "uploading" | "verifying" | "done";
+    /**
+     * 0–100 for the whole call, and it never decreases — on either path,
+     * across phases, across retries. 100 only with `phase: 'done'`.
+     */
+    percent: number;
+    /**
+     * Ciphertext bytes that storage has CONFIRMED. Never bytes handed to a
+     * socket: `xhr.upload.onprogress` reports what the OS buffered, which runs
+     * ahead of the wire and then freezes — the lie the owner banned. So this
+     * moves in steps of one part, and a single-request file is 0 until it
+     * lands.
+     */
+    deliveredBytes: number;
+    /** Ciphertext bytes this call will deliver in all. */
+    totalBytes: number;
+    /**
+     * Ciphertext bytes ENCRYPTED so far, delivered or not.
+     *
+     * Local work, and honest about being that: it is not a claim that anything
+     * left the machine (`deliveredBytes` is the only such claim). A screen uses
+     * it for the stretch before the first part lands, which on a large file is
+     * seconds of a bar that would otherwise sit still — the first thing the
+     * owner called broken when he looked at the extension's popup.
+     */
+    preparedBytes?: number;
+    /** Confirmed bytes per second over the recent past; absent before the first delivery. */
+    speedBps?: number;
+    /** Time left at `speedBps`; absent when there is no speed yet. */
+    etaMs?: number;
+    /**
+     * `stalled`: the upload has been failing and retrying for a while with
+     * nothing delivered — a screen says "no connection, retrying" instead of
+     * showing a bar that stopped for no visible reason.
+     */
+    state: "running" | "stalled";
+    /** 1 on a clean run; grows with each retry since the last delivery. */
+    attempt: number;
+    /** Set when one callback covers several files (append): which one this is. */
+    fileIndex?: number;
+    totalFiles?: number;
+}
+
+/**
+ * Transport policy: when a failed network step is tried again, and when an
+ * upload gives up.
+ *
+ * Every network step of an upload goes through here — multipart init, the
+ * presign calls, each part PUT, complete, and the single-request leg's
+ * initiate / PUT / confirm. Before this the rules were literals scattered
+ * over two files and they disagreed: a part got three attempts inside four
+ * seconds, the single-request leg and `init` / `complete` got one, and a
+ * five-second network dip killed a 490 MB upload that had already delivered
+ * 480 MB of it (F-146…F-148, F-179).
+ *
+ * The rule is a STALL CLOCK for the whole upload, not a budget per step:
+ *
+ *   * a failure is retried for as long as the upload as a whole keeps
+ *     making progress — every confirmed part (or confirmed file) stops the
+ *     clock, and the next failure starts it from zero;
+ *   * the clock is only ever read when something FAILS. A part that is
+ *     merely slow — 16 MiB on a 256 KB/s link takes minutes — is never
+ *     timed by it: no watchdog may kill a healthy slow transfer. A DEAD
+ *     socket is another matter and is not this clock's business either — see
+ *     "liveness" in `multipart-uploader.ts` (audit/SPEC-UPLOAD-SCALE.md §4);
+ *   * attempts are not counted at all. What ends an upload is `maxStallMs`
+ *     with nothing delivered, a failure that cannot heal (most 4xx), or the
+ *     caller's cancel.
+ *
+ * The numbers live in `shared/contracts/upload.json` so the other clients
+ * can read the same ones (F-167).
+ *
+ * @internal - NOT exported from SDK public API
+ */
+
+interface TransportPolicy {
+    /** Delay before retry N (the last entry repeats). */
+    retryBackoffMs: readonly number[];
+    /** Each delay is scaled by a random factor in `1 ± ratio`. */
+    retryJitterRatio: number;
+    /** Failing with nothing delivered for this long ⇒ state `stalled`. */
+    stallNoticeMs: number;
+    /**
+     * Failing with nothing delivered for this long ⇒ the upload gives up.
+     * `Infinity` for a caller whose user has a Cancel button and would
+     * rather wait out an outage than lose the upload.
+     */
+    maxStallMs: number;
+    /** Slowest link a single PUT is still allowed to finish on. */
+    putFloorBytesPerSecond: number;
+    putMinDeadlineMs: number;
+    controlTimeoutMs: number;
+    completeTimeoutMs: number;
+    /**
+     * Parallel part PUTs: where the pool starts, and how wide it may get.
+     * Storage speaks HTTP/1.1 only, so every PUT is a connection of its own and
+     * a browser gives a host six: `poolMax` + `hedgeMaxConcurrent` must fit.
+     */
+    poolStart: number;
+    poolMax: number;
+    /**
+     * How narrow the pool may get on a line so slow that its flows are near
+     * `putFloorBytesPerSecond` each — the speed below which a PUT's deadline
+     * calls it dead. Fewer flows there means each one stays clear of it.
+     */
+    poolMin: number;
+    /** Widen when the aggregate rate grew by this factor since the last resize… */
+    poolGrowRatio: number;
+    /** …step back when it fell to this fraction of it. */
+    poolShrinkRatio: number;
+    /** Encrypted parts that may wait for a slot (bounds memory). */
+    partQueueLimit: number;
+    /** Never duplicate a part before it has been in flight this long. */
+    hedgeMinInflightMs: number;
+    /** A part is an outlier when it is this many times slower than its peers' median. */
+    hedgeLagFactor: number;
+    hedgePollMs: number;
+    /** Duplicate copies in flight across the whole upload, at most. */
+    hedgeMaxConcurrent: number;
+    /**
+     * No part delivered and no socket of ANY copy taking bytes for this long,
+     * while some copy still has bytes to send ⇒ the connections are dead: every
+     * part in flight is reconnected. Only where the transport reports socket
+     * activity (XHR in a window).
+     */
+    livenessSilenceMs: number;
+    /**
+     * The server verifies a delivered file INSIDE `complete` / `confirm` and says
+     * so in its answer (audit/SPEC-UPLOAD-SCALE.md §3). Only when it could not
+     * ask storage does it answer `accepted` and leave the verdict to a worker;
+     * then the sender polls, with these pauses (the last one repeats), for at
+     * most `verifyFallbackWaitMs`. The check is a HEAD, so the wait no longer
+     * grows with the size of the file.
+     */
+    verifyPollBackoffMs: readonly number[];
+    verifyFallbackWaitMs: number;
+    /** Window `speedBps` is averaged over. Display only; decides nothing. */
+    speedWindowMs: number;
+}
+
+/**
+ * What an upload is told by its caller: where to send, how to authenticate,
+ * and the size policy. Shared by the registration flows (`engine.ts`) and the
+ * one primitive that moves bytes (`session.ts`), so neither imports the other
+ * for a type.
+ *
+ * @internal - NOT exported from SDK public API
+ */
+
+interface UploadContext {
+    /** API base URL */
+    baseUrl: string;
+    /** Authentication */
+    auth: AuthConfig;
+    /** Seal ID (for file uploads after seal creation) */
+    sealId?: string;
+    /** Room ID (for Vault uploads) */
+    roomId?: string;
+    /** TTL (for Seal creation) */
+    ttl?: string;
+    /** SHORT LINKS: SHA256 hash of client-generated owner_token (64 hex chars) */
+    ownerTokenHash?: string;
+    /** SHORT LINKS: Client-generated owner token for auth (P2/P5 fix) */
+    ownerToken?: string;
+    /**
+     * Where `appendMany` posts, as a path template containing `{sealId}`.
+     *
+     * §4.4: the protocol must not know which product is calling it. It used
+     * to choose between `/seal/{id}/append` and
+     * `/vault/org/seals/{id}/files/append` by looking at the auth kind — and
+     * the second route does not exist on any server; it is a rewrite rule in
+     * one web's `next.config.js`. A protocol that names a route its server
+     * never serves is a protocol guessing about its caller.
+     *
+     * Defaults to the anonymous seal route, which every SEAL client uses.
+     * A caller whose deployment maps append elsewhere passes its own.
+     */
+    appendPath?: string;
+    /** Backend OTP / "Password". 6-10 chars (backend pattern). */
+    otp?: string;
+    /** Recipient must accept NDA before downloading. */
+    nda?: boolean;
+    /** Owner email (required if nda=true; backend Pydantic validator
+     *  enforces). Used for NDA-PDF receipt delivery. */
+    ownerEmail?: string;
+    /** Single-use: first download deletes ciphertext. */
+    singleUse?: boolean;
+    /** Geo allowlist (ISO 3166-1 alpha-2 country codes). */
+    geo?: string[];
+    /** Max number of total downloads across all recipients. */
+    maxOpens?: number;
+    /**
+     * Paid tier for a seal above the free limit (`5gb` | `50gb` | `500gb`,
+     * SPEC-AGENTS §5.2). The seal is born unpaid: its uploads answer 402
+     * until the payment lands, and then `UploadSession.resume()` goes on.
+     */
+    tier?: string;
+    /**
+     * fetch credentials mode for API calls. The seal.net web app relies on
+     * cookies for its OTP/NDA session, so `'include'` stays the default.
+     * The public send-only SDK passes `'omit'`: the wildcard-CORS send
+     * endpoints answer `Access-Control-Allow-Origin: *`, which the browser
+     * rejects for credentialed requests — send auth is the X-Owner-Token
+     * header, never a cookie.
+     */
+    credentials?: RequestCredentials;
+}
+interface AuthConfig {
+    kind: 'none' | 'ownerToken' | 'bearer';
+    value?: string;
+}
+interface UploadPolicy {
+    /** Threshold for switching to multipart upload (default: 8 MiB = one fine part) */
+    multipartThresholdBytes: number;
+    /** Part size for multipart upload (default: 16MB) */
+    partSizeBytes: number;
+    /** Max size for in-memory ZIP (default: 100MB) */
+    zipSmallLimitBytes: number;
+    /**
+     * Overrides of the contract's transport policy. The one a product sets is
+     * `maxStallMs: Infinity`: a screen with a Cancel button would rather sit
+     * out an outage than lose the upload; a headless caller keeps the
+     * contract's ceiling so it cannot hang forever.
+     */
+    transport?: Partial<TransportPolicy>;
+}
+/** Whether every file of a result was seen `verified` before it returned. */
+type VerificationOutcome = 'verified' | 'pending';
+
+/**
+ * Internal Upload Engine
+ *
+ * The registration flows: what each entry point tells the server before any
+ * byte moves (`POST /seal` with one file, with several, with a folder's
+ * paths, or an append to an existing seal). That is the ONLY thing the flows
+ * differ in. Moving a registered file's bytes — the small-file-or-multipart
+ * choice, the transport, resume and cancel — is `./session`, once.
+ *
+ * @internal - NOT exported from SDK public API
+ */
+
+interface UploadCallbacks {
+    onProgress?: (progress: UploadProgress) => void;
+    signal?: AbortSignal;
+    /**
+     * Awaited immediately after `POST /seal` returns an id, BEFORE any
+     * bytes are uploaded. Lets journaling callers (seal-mcp) persist the
+     * (seal_id, owner_token) pair so the seal can be compensated even if
+     * the rest of the upload fails or the process crashes mid-flight —
+     * without this the id only surfaces when the whole pipeline resolves,
+     * and a lost confirm response orphans a fully-live seal (DR-mcp).
+     * A rejection here aborts the upload; the caller owns compensation.
+     */
+    onSealCreated?: (sealId: string) => void | Promise<void>;
+}
+/**
+ * SHORT LINKS: Single file upload result
+ *
+ * NOTE: shareUrl and ownerToken are NOT returned here.
+ * They are constructed in use_seal_submit.ts from:
+ * - sealId (from response)
+ * - linkKey (client-generated)
+ * - ownerToken (client-generated, stored in encrypted blob)
+ */
+interface SingleFileUploadResult {
+    sealId: string;
+    fileId: string;
+    encryptionKey: Uint8Array<ArrayBuffer>;
+    sha256_hex: string;
+    /**
+     * Server-assigned expiry from the create-seal response, when the backend
+     * sends one. The server is the only authority here: it may clamp the
+     * requested TTL (plan limits, policy), and the client's clock may be
+     * skewed — a caller that recomputes `now + ttl` locally reports a number
+     * the seal does not actually have. Optional because older/other backends
+     * may omit the field; callers fall back to their own estimate and should
+     * say so.
+     */
+    expiresAt?: string;
+    /**
+     * `verified`: the server re-hashed every file before this returned — the
+     * link can be handed out. `pending`: the bytes were accepted but
+     * verification outlasted the wait; a recipient is not offered a file
+     * until it passes.
+     */
+    verification: VerificationOutcome;
+}
+/**
+ * Upload a single file into a new seal.
+ *
+ * A file below the multipart threshold is encrypted FIRST, so its row is
+ * registered under the real ciphertext digest rather than a placeholder
+ * (the digest is what the signed `seal_created` audit line records). A
+ * larger file cannot know its digest before streaming and registers a
+ * placeholder, which `/multipart/complete` replaces.
+ */
+declare function uploadSingleFile(ctx: UploadContext, file: File, policy?: UploadPolicy, callbacks?: UploadCallbacks): Promise<SingleFileUploadResult>;
+
+/**
+ * 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.
+ *
+ * Implements `shared/contracts/seal_mcp.v1.json::handoff_delivery`.
+ *
+ * # Why handoff at all?
+ *
+ * The MCP design principle is: **the model never holds capability by
+ * default**. If the share link were returned in the
+ * `seal_share` tool result, the model would have a copy in its context
+ * window — visible to any agent in the chain, exfiltrated by any
+ * `chat.history.export` tool, persisted in trace logs forever.
+ *
+ * Handoff routes the secret around the model entirely: into the OS
+ * clipboard (primary) or onto a `0o600` file on the same machine
+ * (fallback). The model only sees `{ handle, receipt, handoff_channel,
+ * handoff_file? }` — none of which lets it reconstruct the share.
+ *
+ * # Channels
+ *
+ * 1. **Clipboard** — `clipboardy.write(\`${url}\n\`)`.
+ *    Works on macOS (`pbcopy`), Linux X11/Wayland (`xclip`/`xsel`/
+ *    `wl-copy`), WSL (`clip.exe`), Windows (`clip`). Fails fast in
+ *    headless SSH with no `DISPLAY`.
+ * 2. **File** — atomic `fs.open(path, 'wx', 0o600)` inside
+ *    `${XDG_RUNTIME_DIR or os.tmpdir()}/seal-mcp/`, content
+ *    `url\n` plain text (user `cat`s it). Best-effort
+ *    `setTimeout fs.unlink` after `max(expire_ms, 1 hour)`.
+ *
+ * On total failure both channels return `handoff_both_channels_failed`
+ * — better than silently leaking the secret into the model's output.
+ */
+declare class HandoffBothChannelsFailedError extends Error {
+    readonly code = "handoff_both_channels_failed";
+    readonly clipboardError?: unknown;
+    readonly fileError?: unknown;
+    constructor(message: string, clipboardError?: unknown, fileError?: unknown);
+}
+type HandoffChannel = 'clipboard' | 'file';
+interface HandoffPayload {
+    readonly handle: string;
+    readonly shareUrl: string;
+    readonly expireMs: number;
+}
+interface HandoffResult {
+    readonly channel: HandoffChannel;
+    readonly file?: string;
+}
+interface HandoffDeps {
+    readonly clipboardWrite?: (text: string) => Promise<void>;
+    readonly tmpdirOverride?: string;
+    readonly disableClipboard?: boolean;
+    readonly scheduleCleanup?: (path: string, delayMs: number) => void;
+}
+/**
+ * Deliver a share link out-of-band.
+ *
+ * Order: clipboard → file. On total failure throws
+ * `HandoffBothChannelsFailedError` and emits NO surface containing
+ * the secret — caller MUST NOT log either result. The model gets
+ * `{ channel, file? }` per the contract; never the URL.
+ *
+ * @throws HandoffBothChannelsFailedError if both channels fail.
+ */
+declare function performHandoff(payload: HandoffPayload, deps?: HandoffDeps): Promise<HandoffResult>;
+
+/**
+ * Encrypted state envelope for `~/.config/seal-mcp/state.json`.
+ *
+ * Wire format = `shared/contracts/seal_mcp.v1.json::state_envelope`:
+ *
+ *     Argon2id(passphrase, salt) → 32-byte KEK
+ *     AES-256-GCM(KEK, nonce, plaintext_json) → ciphertext || 16-byte tag
+ *
+ * Everything except the envelope metadata (algo params, salt, nonce)
+ * lives inside the AEAD ciphertext. Identity secret + handle owner-tokens
+ * + audit log are all owner-equivalent capability — encrypting only the
+ * identity and leaving tokens in plaintext would be a security illusion.
+ *
+ * No plaintext field is EVER persisted unencrypted: every save() goes
+ * through `encrypt()`, every load() through `decrypt()`. Atomic write
+ * via `fs.writeFile(tmp) + fs.rename(tmp, final)` so a crash mid-write
+ * leaves either the old envelope or the new one, never a half-written
+ * one.
+ */
+interface IdentityFields {
+    readonly x25519_secret_b64: string;
+    readonly x25519_public_b64: string;
+}
+interface HandleEntry {
+    readonly seal_id: string;
+    readonly owner_token_b64: string;
+    readonly created_at: string;
+    readonly mode: 'handoff' | 'forward';
+    readonly expires_at: string;
+    /**
+     * Set when `seal_revoke` succeeds. Keeping the row (rather than
+     * deleting it) is what makes revoke idempotent per
+     * `seal_mcp.v1.json::tools.seal_revoke.output`: a second call on the
+     * same handle returns `{revoked: true}` without re-hitting the
+     * backend. `seal_list` filters revoked handles unless
+     * `include_expired = true`, so the model can't accidentally probe
+     * them either.
+     */
+    revoked_at?: string;
+    /**
+     * FINAL out-of-band delivery channel actually used (handoff mode
+     * only; ISSUE-0623 requires attempted + final channels to be
+     * durable). Attempted channels live on the `PendingOperation`
+     * while the op is in flight; the final one is recorded here at
+     * completion.
+     */
+    handoff_channel?: 'clipboard' | 'file';
+    /**
+     * Backend base URL the seal was created against (DR-mcp: backend
+     * provenance). Revoke refuses to run against a DIFFERENT backend,
+     * because that backend's 404 would be misread as idempotent success
+     * while the seal stays live on its real authority. Absent on
+     * pre-provenance entries — those are treated as belonging to the
+     * currently configured backend (the only guess available).
+     */
+    backend_url?: string;
+}
+/**
+ * Durable operation journal (ISSUE-0623).
+ *
+ * A `seal_share` writes a `PendingOperation` BEFORE its first remote
+ * effect and updates it at every step boundary, so a crash at any
+ * point leaves enough encrypted-at-rest context to either revoke an
+ * orphaned seal or adopt an already-delivered one at next startup
+ * (`recovery.ts`). Completion deletes the entry in the same envelope
+ * write that inserts the durable `HandleEntry` — an op is never in
+ * both maps.
+ *
+ * Step semantics:
+ *   - `preparing`   → journaled, upload NOT yet confirmed. No
+ *                     `seal_id`; nothing remotely addressable.
+ *   - `awaiting_payment` → the seal is over 1 GB and unpaid (SPEC-AGENTS
+ *                     §5.2); what would finish it lives in memory only,
+ *                     so recovery revokes it like `uploaded`.
+ *   - `uploaded`    → ciphertext live on backend, URL has NOT been
+ *                     delivered anywhere. Safe (and correct) to
+ *                     revoke on recovery.
+ *   - `delivering`  → handoff attempt started; the URL may already
+ *                     sit in the user's clipboard / 0o600 file.
+ *                     Recovery must NOT revoke — it adopts the seal
+ *                     as a normal handle so the owner keeps control.
+ *   - `compensating`→ a revoke compensation was attempted and failed
+ *                     (`compensation.outcome === 'failed'`); retried
+ *                     at next startup.
+ */
+interface PendingCompensation {
+    readonly action: 'revoke';
+    readonly outcome: 'failed';
+    readonly error: string;
+    readonly at: string;
+}
+type PendingStep = 'preparing' | 'awaiting_payment' | 'uploaded' | 'delivering' | 'compensating';
+interface PendingOperation {
+    readonly tool: 'seal_share';
+    readonly mode: 'handoff' | 'forward';
+    readonly started_at: string;
+    readonly owner_token_b64: string;
+    readonly expires_at: string;
+    step: PendingStep;
+    seal_id?: string;
+    /** Channels `performHandoff` will try, in order (handoff mode only). */
+    handoff_channels_attempted?: ReadonlyArray<'clipboard' | 'file'>;
+    compensation?: PendingCompensation;
+    /**
+     * Backend base URL the operation runs against (DR-mcp: backend
+     * provenance). Recovery must not compensate against a different
+     * backend — see `HandleEntry.backend_url`.
+     */
+    backend_url?: string;
+}
+interface AuditEntry {
+    readonly ts: string;
+    readonly tool: 'seal_share' | 'seal_request' | 'seal_open' | 'seal_list' | 'seal_revoke';
+    readonly handle: string | null;
+    /**
+     * Free-form contextual label per tool. Contract permits any string
+     * (`{ "type": ["string", "null"] }`) and the value carries
+     * tool-specific meaning:
+     *   - seal_share → 'handoff' | 'forward'
+     *   - seal_request → 'local' | 'link'
+     *   - seal_open  → 'metadata' | 'inline' | 'file'
+     *   - seal_list  → null
+     *   - seal_revoke → original handle mode echoed back
+     */
+    readonly mode: string | null;
+}
+interface StateView {
+    version: 1;
+    identity: IdentityFields;
+    handles: Record<string, HandleEntry>;
+    audit: AuditEntry[];
+    /**
+     * Durable operation journal keyed by handle (the handle is minted
+     * before the first remote effect, so it doubles as the op id).
+     * Absent in pre-ISSUE-0623 envelopes — `loadState` normalises to
+     * `{}` so old state files keep loading.
+     */
+    pending: Record<string, PendingOperation>;
+}
+declare class StatePassphraseInvalid extends Error {
+    constructor();
+}
+declare class StateCorrupt extends Error {
+    constructor(reason: string);
+}
+declare function createEmptyState(identity: IdentityFields): StateView;
+/**
+ * Decrypt and validate a state file. Throws:
+ *   - `StatePassphraseInvalid` on AEAD tag failure (wrong passphrase
+ *     or tampered file).
+ *   - `StateCorrupt` on JSON / envelope / plaintext schema violations.
+ *   - Node fs errors on missing file / permissions (let them propagate).
+ */
+declare function loadState(passphrase: string, statePath: string): Promise<StateView>;
+/**
+ * Encrypt + atomically write a state file. Creates parent dir with
+ * 0o700 if missing. File is written 0o600. Pattern: write tmp, fsync,
+ * then rename — POSIX guarantees rename atomicity.
+ *
+ * A fresh 16-byte salt is generated on every save (overkill — Argon2id
+ * is non-adaptive — but cheap and follows defence-in-depth).
+ */
+declare function saveState(state: StateView, passphrase: string, statePath: string): Promise<void>;
+
+/**
+ * X25519 identity for the MCP server (incoming targeted-share recipient).
+ *
+ * The keys come from `@seal/protocol` (`generateRecipientKeyPair`,
+ * `recipientPublicKey`), which derives them in the same core the Rust CLI's
+ * `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`.
+ */
+
+interface Identity {
+    readonly secret: Uint8Array;
+    readonly public: Uint8Array;
+}
+/** A fresh X25519 keypair for this server. */
+declare function generateIdentity(): Promise<Identity>;
+/**
+ * Project an `Identity` into the serialised form that lives in
+ * `state.identity` (base64-encoded raw bytes; matches contract
+ * `shared/contracts/seal_mcp.v1.json::state_envelope.plaintext_schema.properties.identity`).
+ */
+declare function identityToFields(id: Identity): IdentityFields;
+/**
+ * Reconstruct an `Identity` from `state.identity`. Validates both key
+ * lengths AND that `public` actually corresponds to `secret` — catches a
+ * corrupted / tampered state where the two fields drifted apart.
+ */
+declare function loadIdentity(fields: IdentityFields): Promise<Identity>;
+
+/**
+ * Exclusive lifetime lock for the seal-mcp state directory (ISSUE-0623).
+ *
+ * # 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.
+ *
+ * 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.
+ *
+ * # Mechanism (DR-mcp: TOCTOU-hardened)
+ *
+ * Creation is atomic WITH content: the holder info JSON is written to a
+ * private temp file first, then `link(tmp, state.lock)` publishes it —
+ * `link` fails with `EEXIST` if the lock exists (atomic on POSIX and
+ * NTFS), and a contender can never observe a half-written lock from a
+ * healthy holder. (The previous `open('wx')`-then-write protocol had an
+ * empty-file window that a contender misread as a stale lock and
+ * unlinked, yielding two simultaneous owners.)
+ *
+ * The lock file holds `{ pid, hostname, acquired_at }` so a contender
+ * can detect a stale lock: if the recorded pid is no longer alive ON
+ * THE SAME HOST, the previous holder crashed without cleanup. Breaking
+ * a stale lock is also atomic: the contender `rename`s the lock aside
+ * to a private name — only ONE contender wins the rename — verifies the
+ * claimed file still describes the stale holder (renaming it back if a
+ * 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.
+ *
+ * PID-recycling is the accepted residual risk: the probe window is
+ * milliseconds and the failure mode (refusing to start) 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
+ * contender legitimately re-acquired. Same check runs in the
+ * best-effort sync unlink on `process.on('exit')`.
+ */
+declare const LOCK_FILE_NAME = "state.lock";
+interface LockHolderInfo {
+    readonly pid: number;
+    readonly hostname: string;
+    readonly acquired_at: string;
+}
+declare class StateLockedError extends Error {
+    readonly code = "state_locked";
+    readonly holder: LockHolderInfo | null;
+    readonly lockPath: string;
+    constructor(lockPath: string, holder: LockHolderInfo | null);
+}
+interface StateLock {
+    readonly lockPath: string;
+    /** Idempotent. Removes the lock file (if still ours) and the process-exit hook. */
+    release: () => Promise<void>;
+}
+interface AcquireLockDeps {
+    /** Override liveness probe for tests. Default: `process.kill(pid, 0)`. */
+    readonly isPidAlive?: (pid: number) => boolean;
+    /** Override own pid for tests. */
+    readonly pid?: number;
+    /** Override hostname for tests. */
+    readonly host?: string;
+}
+/**
+ * Acquire the exclusive state-dir lock or throw `StateLockedError`.
+ *
+ * Creates `stateDir` (0o700) if missing so `init` can lock before the
+ * first `saveState`. Refuses to operate on a symlinked state dir and
+ * re-tightens permissions on a pre-existing one (DR-mcp: `mkdir` with
+ * `mode` does not repair an existing directory).
+ */
+declare function acquireStateLock(stateDir: string, deps?: AcquireLockDeps): Promise<StateLock>;
+/**
+ * Read-only probe for `doctor`: report who (if anyone) holds the lock
+ * and whether it looks stale from this host's perspective.
+ */
+declare function probeStateLock(stateDir: string, deps?: AcquireLockDeps): Promise<{
+    held: boolean;
+    holder: LockHolderInfo | null;
+    stale: boolean;
+}>;
+
+/**
+ * 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
+ * `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:
+ *
+ *   - `preparing`   — WITHOUT a seal_id: no remote effect ever
+ *                     confirmed. Nothing to compensate; drop the entry
+ *                     (backend GC owns incomplete multipart uploads).
+ *                     WITH a seal_id (journaled by the upload engine's
+ *                     onSealCreated hook): the seal is live — treat it
+ *                     like `uploaded` and revoke the orphan.
+ *   - `uploaded`    — ciphertext live, URL never delivered anywhere.
+ *                     A live seal whose link nobody holds is pure
+ *                     orphan storage: revoke it (awaited).
+ *   - `awaiting_payment` — an unpaid seal over 1 GB; what would finish
+ *                     it died with the process. Revoked like `uploaded`
+ *                     (the revoke closes its payment page).
+ *   - `delivering`  — the handoff attempt started, so the URL may
+ *                     already sit in the user's clipboard / 0o600
+ *                     file. Revoking would kill a link the user may
+ *                     have sent already — instead ADOPT the op as a
+ *                     durable handle. The owner keeps control: it
+ *                     shows up in `seal_list` and can be revoked
+ *                     explicitly via `seal_revoke`.
+ *   - `compensating`— an earlier awaited revoke failed and was
+ *                     journaled; retry it now.
+ *
+ * Revoke failures stay in the journal (`step='compensating'`, outcome
+ * recorded) and are retried at the next startup — compensation is
+ * durable, never fire-and-forget.
+ */
+
+/** Minimal client slice recovery needs — keeps tests trivial. */
+interface RevokeClient {
+    /** Backend base URL this client talks to (provenance comparisons). */
+    readonly baseUrl: string;
+    revoke(sealId: string, ownerTokenB64: string): Promise<unknown>;
+}
+interface RecoveryReport {
+    /** `delivering` ops adopted as durable handles. */
+    readonly adopted: string[];
+    /** Orphan seals successfully revoked (`uploaded` / retry). */
+    readonly revoked: string[];
+    /** Revoke retries that failed again — kept in the journal. */
+    readonly stillFailing: string[];
+    /** `preparing` entries dropped (no remote effect to undo). */
+    readonly dropped: string[];
+}
+/**
+ * Reconcile `view.pending` in place. Returns the report + whether the
+ * view changed (caller persists 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?: {
+    now?: () => Date;
+    log?: (line: string) => void;
+}): Promise<{
+    report: RecoveryReport;
+    changed: boolean;
+}>;
+
+/**
+ * State-path resolver for `sealnet-mcp` (the directory keeps the name `seal-mcp`).
+ *
+ * Resolution priority (highest wins):
+ *   1. `--state-dir <path>` CLI flag (caller passes via `cliFlag`).
+ *   2. `SEAL_MCP_CONFIG_DIR` environment variable. Mirrors the Rust
+ *      `seal-cli` (`seal/clients/core/src/config.rs::Config::dir`)
+ *      so power users with multiple profiles get the same override
+ *      knob across both clients.
+ *   3. OS-native default:
+ *        - macOS:   `~/Library/Application Support/seal-mcp`
+ *        - Linux/*BSD: `$XDG_CONFIG_HOME ?? ~/.config/seal-mcp`
+ *        - Windows: `$APPDATA/seal-mcp` (or `~/AppData/Roaming/seal-mcp`)
+ *      Matches `env-paths` (Sindre Sorhus) without taking the dep.
+ *
+ * Pure function — does not touch the filesystem. Callers `mkdir` lazily
+ * via `state.saveState` which already enforces `0o700` on the dir and
+ * `0o600` on the envelope.
+ */
+declare const APP_NAME = "seal-mcp";
+declare const STATE_FILE_NAME = "state.json";
+type StateDirSource = 'flag' | 'env' | 'os-default';
+interface PathResolution {
+    readonly dir: string;
+    readonly statePath: string;
+    readonly source: StateDirSource;
+}
+interface ResolveOptions {
+    /** Explicit `--state-dir <path>` from commander. Empty/undefined = skip. */
+    readonly cliFlag?: string;
+    /** Override process.env for tests. */
+    readonly env?: NodeJS.ProcessEnv;
+    /** Override process.platform for tests (default current). */
+    readonly platform?: NodeJS.Platform;
+    /** Override os.homedir() for tests. */
+    readonly home?: string;
+}
+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 `keytar` (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.
+ *
+ * `keytar` is loaded lazily (same pattern as `clipboardy` in
+ * `handoff.ts`) so headless environments lacking `libsecret-1.so.0`
+ * (Linux) can still fall back to the env var without crashing the CLI
+ * 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;
+}
+/**
+ * Surface used by `passphrase.ts` — kept narrow on purpose so tests can
+ * stub keytar without pulling in the native module.
+ */
+interface KeytarLike {
+    getPassword(service: string, account: string): Promise<string | null>;
+    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();
+}
+/**
+ * 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`.
+ */
+declare function probeKeychain(): Promise<{
+    available: boolean;
+    hasEntry: 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.
+ *
+ * Each tool is a pure async function `(ctx, input) → output` so the
+ * `server.ts` bootstrap can wire tools to the MCP SDK by registering
+ * arrow-functions that close over a single `ToolContext` instance.
+ * Keeps the tool implementations test-friendly (inject a fake
+ * context) and prevents accidental global state.
+ */
+
+/** Mutable, single-source-of-truth state passed across tool calls. */
+interface ToolContext {
+    readonly state: StateView;
+    readonly identity: Identity;
+    readonly client: S;
+    /**
+     * 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.
+     */
+    persist: () => Promise<void>;
+    /** No keychain, 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>;
+    /**
+     * `seal_share` handles waiting for a payment (SPEC-AGENTS §5.2), to what
+     * finishes them; in memory only — a restart revokes the unpaid seal
+     * (`recovery.ts`, step `awaiting_payment`).
+     */
+    readonly payments?: Map<string, PendingPayment>;
+    /** UTC-now hook for deterministic testing. */
+    now?: () => Date;
+}
+/** A share stopped on 402: `finish` waits for the payment and completes it. */
+interface PendingPayment {
+    readonly finish: (onProgress?: (done: number, total: number) => void) => Promise<unknown>;
+}
+/**
+ * Generate an opaque handle of the form `h_<12 base64url chars>`,
+ * matching `seal_mcp.v1.json::output_handoff.handle.pattern`.
+ *
+ * 9 random bytes = 72 bits of entropy. With ≤10^6 handles in flight
+ * the birthday-collision probability is ≈ 2·10^-11 — well below the
+ * MCP server's effective lifetime.
+ */
+declare function generateHandle(): string;
+/** Validate a handle against the contract pattern. */
+declare function isValidHandle(handle: string): boolean;
+/**
+ * Tool-side error type. The server converts these into structured
+ * MCP error responses with `code` as the error symbol.
+ */
+declare class ToolError extends Error {
+    readonly code: string;
+    readonly cause?: unknown;
+    constructor(code: string, message: string, cause?: unknown);
+}
+
+/**
+ * `seal_list` — return the model-visible view of locally-tracked
+ * handles. Pure local state read; no backend round-trip required.
+ *
+ * Output shape and field names track
+ * `shared/contracts/seal_mcp.v1.json::tools.seal_list.output` exactly
+ * (FINDINGS Bug #5 fix, 2026-05-26). Pre-fix history:
+ *
+ *   - Pre-Bug-#5 wire: `{ entries: [{ handle, createdAt, expiresAt,
+ *     mode, revokedAt? }] }`. snake_vs_camel + missing `status` +
+ *     missing `file_count` + extra `expiresAt`/`revokedAt`. Any host
+ *     validating against the published contract would have rejected
+ *     it; golden phase 3.6b ("strictly matches the v1 contract shape")
+ *     surfaced this divergence.
+ *
+ * Why wrap in `{entries:[]}` instead of returning a bare array (which
+ * the original contract said): MCP's `CallToolResult.structuredContent`
+ * is typed `Record<string, unknown>` and a validating host will reject
+ * a top-level array there. The contract was updated to match this
+ * MCP-level constraint in the same patch as this file.
+ *
+ * The expired/revoked filter still excludes "dead" handles by default
+ * so the model doesn't waste turns trying to `seal_open` /
+ * `seal_revoke` them. Revoke on an already-revoked handle is
+ * idempotent per `seal_revoke`, but listing it is just noise.
+ */
+
+interface SealListInput {
+    /** If true, include entries with status 'expired' or 'revoked'; defaults false. */
+    readonly includeExpired?: boolean;
+}
+type SealListStatus = 'active' | 'expired' | 'revoked';
+/**
+ * One row in `seal_list.output.entries`. Field set and casing must
+ * stay aligned with `seal_mcp.v1.json::seal_list.output.entries.items`
+ * — that schema has `additionalProperties: false`, so adding a field
+ * here without bumping the contract will be rejected by validating
+ * MCP hosts.
+ */
+interface SealListEntry {
+    readonly handle: string;
+    readonly created_at: string;
+    readonly status: SealListStatus;
+    /**
+     * Always `1` today: `seal_share` accepts a single `path`. The
+     * contract reserves the field so a future multi-file `seal_share`
+     * doesn't need a v2 bump.
+     */
+    readonly file_count: number;
+    readonly mode: 'handoff' | 'forward';
+}
+interface SealListOutput {
+    readonly entries: SealListEntry[];
+}
+declare function sealList(ctx: ToolContext, input?: SealListInput): Promise<SealListOutput>;
+
+/**
+ * `seal_open` — read a SEAL link: describe it, return small text inline, or
+ * stream every file it carries to disk.
+ *
+ * Reading the link is the protocol's (`openShareLink`: parse, unwrap a
+ * targeted fragment with THIS server's X25519 identity, public metadata,
+ * share blob, file names) — the same code the SDK opens links with (И4). What
+ * stays here is this tool's policy:
+ *
+ * Metadata (default): the first file's name, MIME and size, the file count,
+ * the seal's flags. No download, no counter tick.
+ *
+ * Inline: refused WITHOUT a download — so a refusal never burns
+ * `single_use`/`max_opens` — when the MIME is not JSON/CSV/plain text
+ * (HTML/PDF/XHTML carry prompt-injection risk, binary cannot be sanitised),
+ * when the sender marked it a secret (`inline_blocked.secret`, И2), or when
+ * the ciphertext exceeds `INLINE_CIPHERTEXT_MAX_BYTES`. Otherwise one
+ * download, decrypted through `decryptVerified` (ciphertext digest checked
+ * against the one registered at upload, ISSUE-0606), a plaintext cap, and a
+ * fatal UTF-8 decode.
+ *
+ * File (SPEC-AGENTS §5.1): every file the link carries a key for, streamed to
+ * disk by `@seal/protocol/node` — the name given only after the digest
+ * matched, 0600, memory one segment whatever the size. The model gets paths,
+ * sizes and plaintext digests, never content. Each download counts against
+ * the seal like a browser's.
+ */
+
+interface SealOpenInput {
+    readonly url: string;
+    readonly mode?: 'metadata' | 'inline' | 'file';
+    /** `file` mode: directory to write into; default `~/Downloads`, created if missing. */
+    readonly dir?: string;
+    /** `file` mode: ciphertext bytes received so far, out of the seal's total. */
+    readonly onProgress?: (done: number, total: number) => void;
+}
+/** One file of the seal, written to disk (`mode: 'file'`). */
+interface SealOpenFileEntry {
+    readonly path: string;
+    readonly filename: string;
+    readonly sizeBytes: number;
+    readonly mime: string;
+    readonly sha256: string;
+}
+interface SealOpenFileOutput {
+    readonly handle: string;
+    readonly files: readonly SealOpenFileEntry[];
+}
+interface SealOpenMetadataOutput {
+    readonly handle: string;
+    readonly filename: string;
+    readonly sizeBytes: number;
+    readonly mime: string;
+    readonly fileCount: number;
+    readonly ownerEmailHash: string | null;
+    readonly geoRestriction: string | null;
+    readonly singleUse: boolean;
+    readonly maxReads: number;
+    readonly expiresAt: string;
+}
+interface SealOpenInlineRefusal {
+    readonly handle: string;
+    readonly refusal: 'inline_blocked.binary' | 'inline_blocked.injection_risk' | 'inline_blocked.too_large' | 'inline_blocked.secret';
+    readonly mime: string | null;
+    readonly note: string;
+}
+/** Successful inline body — the model gets the decrypted UTF-8 text. */
+interface SealOpenInlineSuccess {
+    readonly handle: string;
+    readonly mime: 'application/json' | 'text/csv' | 'text/plain';
+    readonly sizeBytes: number;
+    readonly encoding: 'utf-8';
+    readonly content: string;
+}
+type SealOpenOutput = SealOpenMetadataOutput | SealOpenInlineRefusal | SealOpenInlineSuccess | SealOpenFileOutput;
+declare function sealOpen(ctx: ToolContext, input: SealOpenInput): Promise<SealOpenOutput>;
+
+/**
+ * `seal_revoke` — invalidate a SEAL by opaque handle.
+ *
+ * The model never learns the raw `seal_id` or `owner_token`; we look
+ * them up from the handle row in `state.handles`. Idempotent:
+ * revoking an already-revoked / already-expired handle returns
+ * `{revoked: true}` without error, per
+ * `seal_mcp.v1.json::tools.seal_revoke.output`.
+ */
+
+interface SealRevokeInput {
+    readonly handle: string;
+}
+interface SealRevokeOutput {
+    readonly revoked: boolean;
+    readonly revokedAt: string;
+}
+declare function sealRevoke(ctx: ToolContext, input: SealRevokeInput): Promise<SealRevokeOutput>;
+
+/**
+ * `seal_share` — create a new SEAL from a local file or folder and deliver the
+ * share link (key in its fragment, no separate password) out-of-band
+ * (handoff) or back to the model (forward, targeted recipient only,
+ * hard policy gate).
+ *
+ * # Modes
+ *
+ * **`handoff` (default)** — URL delivered via clipboard or 0o600 file.
+ * Model receives only an opaque `handle` and a receipt. Anonymous_v1
+ * fragment (raw link_key in URL).
+ *
+ * **`forward` (opt-in, Phase 3.5d)** — URL returned in the tool
+ * response so the model can paste it into chat. Hard policy:
+ *   - `to` REQUIRED (X25519 recipient pubkey, 32 B base64url-no-pad)
+ *   - `expire ≤ 30m` (enforced client-side; backend also caps at
+ *     `MAX_FORWARD_EXPIRE_MINUTES`)
+ *   - `max_reads = 1` (locked — any other value rejected)
+ * Wire format: `targeted_x25519_v1` (see
+ * `shared/contracts/seal_share_url.v1.json`). Fragment built by
+ * `@seal/protocol::buildTargetedFragment` using the same WASM
+ * `wasm_sealbox_wrap` as the Rust CLI's `seal send --to`.
+ *
+ * # Pipeline
+ *
+ *   1. **forward only**: validate `to` + `expire ≤ 30m` + `max_reads = 1`.
+ *      Validation happens BEFORE upload so a bad request doesn't
+ *      leak an orphaned ciphertext on the backend.
+ *   2. Open the path lazily as a `globalThis.File` (`openSource`): a
+ *      file as it is, a folder as one ZIP streamed into a private 0600
+ *      temp file (`zip.ts`, SPEC-AGENTS §5.1) and removed when the call
+ *      ends. Above the free limit the seal is created with a tier and
+ *      paid for (`awaitPayment`, §5.2); more than the tier holds is
+ *      refused before upload. Without `expire`, a handoff over 100 MiB
+ *      lives 1d instead of 5m (contract `expire_default`).
+ *   3. Generate ownerToken (32 B) + ownerTokenHash via the bundled e2ee primitives.
+ *   4. **Journal (ISSUE-0623)**: persist `state.pending[handle] =
+ *      { owner_token, mode, step: 'preparing', … }` BEFORE the first
+ *      remote effect. Every step below updates the journal; every
+ *      post-upload failure runs an AWAITED revoke compensation whose
+ *      outcome is recorded (and retried at startup by `recovery.ts`
+ *      if it fails). Completion removes the journal entry in the same
+ *      envelope write that inserts the durable handle.
+ *   5. `uploadSingleFile(...)` — full AEON streaming upload via the
+ *      multipart protocol; identical wire format to the browser
+ *      (Phase 2.4 unified WASM init across runtimes). Journal step →
+ *      `uploaded` (seal_id recorded — full revoke capability durable).
+ *   6. Generate a separate `shareLinkKey` and encrypt a share-blob
+ *      containing `{ file_keys: { sha256_hex: file_key_b64 } }`.
+ *   7. `POST /seal/{id}/share` with the encrypted blob → server
+ *      allocates `share_code`.
+ *   8. Build URL fragment:
+ *        - **handoff**: `base64url(shareLinkKey)` (anonymous_v1)
+ *        - **forward**: `x25519:` || `base64url(packed)` (targeted_x25519_v1)
+ *   9. Deliver:
+ *        - **handoff**: journal step → `delivering` (+ attempted
+ *          channels), then `performHandoff` (clipboard / 0o600 file)
+ *        - **forward**: return `share_url` in the tool response (model gets it)
+ *   10. Persist `state.handles[handle] = { seal_id, owner_token, mode,
+ *       expires_at, created_at, handoff_channel? }` + drop the journal
+ *       entry (single atomic write).
+ *
+ * # Zero-knowledge invariants enforced
+ *   - `handle` returned to the model contains no capability material.
+ *   - The share blob is opaque to the backend (zero-knowledge).
+ *   - **handoff mode**: URL never appears in the tool result.
+ *   - **forward mode**: URL IS in the tool result (this is the point);
+ *     for `targeted_x25519_v1` URLs the URL alone is NOT a usable
+ *     capability without the recipient's identity secret, so leaking
+ *     the URL (e.g. via chat history) does not compromise content.
+ */
+
+type SealShareMode = 'handoff' | 'forward';
+interface SealShareInput {
+    /** Required unless `payment` is given. */
+    readonly path?: string;
+    /** Over 1 GB: the tier to pay for; default the smallest that fits. */
+    readonly tier?: string;
+    /** Handle of a share waiting for its payment: wait for it and finish. */
+    readonly payment?: string;
+    readonly mode?: SealShareMode;
+    readonly expire?: string;
+    readonly maxReads?: number;
+    readonly burn?: boolean;
+    readonly to?: string;
+    /**
+     * Explicit MIME override. Defaults to extension-based detection via
+     * `guessMimeFromName`; unknown extensions get
+     * `application/octet-stream`. Encrypted into the per-file metadata
+     * bundle (zero-knowledge to backend).
+     */
+    readonly mime?: string;
+    /** Ciphertext bytes storage has confirmed, out of the upload's total. */
+    readonly onProgress?: (done: number, total: number) => void;
+}
+interface SealShareHandoffOutput {
+    readonly handle: string;
+    readonly receipt: string;
+    readonly handoffChannel: 'clipboard' | 'file';
+    readonly handoffFile?: string;
+    readonly expiresAt: string;
+}
+/**
+ * Forward-mode output (contract: `seal_mcp.v1.json::seal_share.output_forward`).
+ * Includes `shareUrl` — model receives the targeted-X25519 URL. The
+ * URL alone is not a usable capability without the recipient's
+ * identity secret. `password` is omitted because the targeted_x25519_v1
+ * fragment carries the wrapped key inline (zero-knowledge to backend).
+ */
+interface SealShareForwardOutput {
+    readonly handle: string;
+    readonly shareUrl: string;
+    readonly expiresAt: string;
+    readonly maxReads: 1;
+    readonly mode: 'forward';
+}
+/**
+ * Over 1 GB without URL-mode elicitation (contract `seal_share.output_payment`):
+ * the model shows `paymentUrl` and calls again with `payment: handle`.
+ */
+interface SealSharePaymentOutput {
+    readonly handle: string;
+    readonly paymentUrl: string;
+    readonly tier: string;
+    /** Payment deadline; the seal is revoked after it. */
+    readonly expiresAt: string;
+    readonly receipt: string;
+}
+type SealShareOutput = SealShareHandoffOutput | SealShareForwardOutput | SealSharePaymentOutput;
+interface SealShareDeps {
+    readonly handoff?: HandoffDeps;
+    /**
+     * Override the public origin share URLs are built on. Default is the
+     * `config.ts` resolver chain (`SEAL_MCP_PUBLIC_HOST` env →
+     * `https://seal.net`) — NOT derived from the backend URL, which in
+     * production is the separate `https://api.seal.net` origin serving
+     * no frontend (ISSUE-0622).
+     */
+    readonly publicHost?: string;
+    /**
+     * Inject the upload pipeline. Default: the bundled `uploadSingleFile`
+     * streaming uploader. Tests substitute a fixture that returns a
+     * canned `UploadResult` so they don't need a live backend.
+     * Production code must NOT pass this — the default is the
+     * cross-stack-verified streaming uploader.
+     */
+    readonly uploadSingleFile?: typeof uploadSingleFile;
+    /** URL-mode elicitation for the payment page, when the client supports it. */
+    readonly elicitUrl?: (params: {
+        url: string;
+        message: string;
+        elicitationId: string;
+    }) => Promise<string>;
+    /** Tell the client the out-of-band part is done (`notifications/elicitation/complete`). */
+    readonly elicitationDone?: (elicitationId: string) => Promise<void>;
+}
+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 };