@proof-holdings/mcp-server 1.0.0 → 1.2.0

package/dist/authBoundary.d.ts

@@ -0,0 +1,193 @@
+/**
+ * The boundary between what this server answers with no account and what needs one
+ * (`h-mcp-oauth-remote-wiring`).
+ *
+ * WHY IT LIVES HERE, and not inside a tool handler: the answer to "you need to sign in" is an HTTP
+ * 401 carrying `WWW-Authenticate`, and that is what a client's OAuth stack reads. By the time a tool
+ * handler runs, the response is already a JSON-RPC result — the same refusal delivered there is
+ * text, not a challenge, and every measured client ignores it (`docs/mcp-oauth-client-probe.md`).
+ * So the remote server has to classify the message BEFORE handing it to the transport, and this
+ * module is the one place that classification is written down.
+ *
+ * WHERE IT SITS, and why not on `initialize`: the control measurement in the probe put a 401 on the
+ * opening handshake and the human saw `Failed to connect — connection timed out after 30000ms`,
+ * i.e. a broken connection rather than an invitation to sign in. Anonymous connection is a closed
+ * criterion of `h-mcp-remote`, so the 401 lands on the TOOL CALL that needs an account and nowhere
+ * else.
+ */
+/**
+ * Tools that work with no credential at all.
+ *
+ * Derived from `PUBLIC_PATHS` in `./http.js` — the endpoints the HTTP client is allowed to call
+ * with no bearer — plus the two tools that never touch our API: `verify_delegation` /
+ * `verify_delegations` run `@proof-holdings/delegation-verifier` against an issuer's public
+ * surfaces, and `render_auth_link` is local QR generation.
+ *
+ * `__tests__/auth-boundary.test.ts` compares this list against the tools the factory actually
+ * registers, in BOTH directions: a name here that no tool answers to would refuse nothing while
+ * reading exactly like a boundary, and anything the server registers that is not here must be
+ * refused without a key.
+ */
+export declare const KEYLESS_TOOLS: ReadonlySet<string>;
+/**
+ * Tools that WORK over a `start_login` session.
+ *
+ * Their endpoints are the caller's own account records — the paths `SESSION_AUTH_PREFIXES` in
+ * `./http.ts` signs with the session token (plus `/api/v1/auth/me`). Every other keyed tool needs
+ * the API key the client's Authenticate step grants, and the refusal below tells the caller which
+ * side of that line the tool they asked for is on, BEFORE they walk the road. It used to say
+ * "call start_login" to everyone; a human did, signed in through Telegram, and was refused again by
+ * a second text that finally explained the difference (h-fix-mcp-refusal-roads).
+ *
+ * Hand-written here because the package cannot read docs/api-map.yaml at runtime, and held equal to
+ * the truth in BOTH directions by `src/__tests__/drift/api-parity.test.ts` (`parseMcpSessionTools`
+ * joins this set to the map through the paths the client signs) and by `validateMcpSessionToolCoverage`
+ * in `scripts/validate-api-map.ts`. `__tests__/auth-boundary.test.ts` keeps it to registered tools
+ * and disjoint from `KEYLESS_TOOLS`.
+ */
+export declare const SESSION_TOOLS: ReadonlySet<string>;
+/**
+ * What a caller must do to open a tool, in the two channels a client delivers ANONYMOUSLY and
+ * ALWAYS: the descriptions in `tools/list` and the `instructions` of the `initialize` result.
+ *
+ * WHY THE REFUSAL BELOW IS NOT ENOUGH, measured rather than reasoned. The 401 + `WWW-Authenticate`
+ * is correct and stays — it is the entire reason an OAuth-capable client offers to authenticate. But
+ * an MCP client raises that 401 as a TRANSPORT error: it throws before the body becomes a tool
+ * result, so `authorizationRequiredBody` reaches probes and developers and never reaches the model.
+ * On a live Claude Code session that gap was filled by the client's own guess — "the token expired",
+ * said about a server that had never been handed a token. Returning the refusal as a plain result
+ * instead would fix the reading and break the button (`docs/mcp-oauth-client-probe.md`), so the fact
+ * is stated a second time, up front, where it is always readable.
+ *
+ * ONLY WHILE IT IS TRUE. With a credential in hand every notice would be noise, charged to the
+ * agent's context on every `tools/list` for every tool — so a keyed server adds nothing at all.
+ */
+export interface AccessContext {
+    /** The Streamable HTTP entrypoint. Changes the recipe, exactly as it does for `HttpClient`. */
+    remote?: boolean;
+    /** Whether this server was built with an API key. */
+    hasCredential: boolean;
+}
+/**
+ * The suffix appended to one tool's description, or `''` when the tool needs nothing.
+ *
+ * The session/keyed split is the same one `keyless_alternative` makes in the refusal, and it is
+ * here for the same reason: telling every refused caller to run `start_login` walked a human
+ * through an entire Telegram login and into a SECOND refusal that contradicted the first
+ * (`h-fix-mcp-refusal-roads`).
+ */
+export declare function accessNoticeFor(tool: string, context: AccessContext): string;
+/**
+ * The `instructions` string of the `initialize` result — the one place the whole arrangement can be
+ * stated once instead of per tool.
+ *
+ * Whether a given client actually shows this to its model is NOT assumed here; it is measured on a
+ * live client as part of this task, and the per-tool notice above is what carries the fact when the
+ * answer is no.
+ */
+export declare function serverInstructions(context: AccessContext): string;
+/**
+ * RFC 9728 — the document our `WWW-Authenticate` names in `resource_metadata`.
+ *
+ * A DELIBERATE SECOND COPY of `PROTECTED_RESOURCE_METADATA_PATH` in the backend's
+ * `src/constants/mcpOauth.ts`. This package is its own build and published separately, so it cannot
+ * import from `src/`; the two are held together by text instead —
+ * `src/__tests__/drift/mcp-oauth-remote-wiring.test.ts` reads this literal out of this file and
+ * compares it with the constant. Rename either side without the other and that suite goes red,
+ * which is the only thing standing between "the header points at a document" and "the header points
+ * at a 404 while every test is green".
+ */
+export declare const PROTECTED_RESOURCE_METADATA_PATH = "/.well-known/oauth-protected-resource";
+/** Absolute address of the protected-resource document for a given API origin. */
+export declare function resourceMetadataUrl(baseUrl: string): string;
+/**
+ * The `WWW-Authenticate` value. Form taken from the run that actually worked — all three clients
+ * followed `resource_metadata` from this exact shape (`mcp/probe/oauth-probe.mjs`).
+ */
+export declare function authorizationChallenge(baseUrl: string): string;
+export interface AuthorizationRequiredBody {
+    error: 'authorization_required';
+    error_description: string;
+    /**
+     * `GET /api/v1/mcp/connect` — the machine-readable connection document, for the CLIENT. It was
+     * called `login_url` until a human opened it in a browser expecting a sign-in page and got raw
+     * JSON. There is no page that connects an MCP client: connecting happens inside the client.
+     */
+    connect_instructions_url: string;
+    /**
+     * What `start_login` gets this caller — true PER TOOL. For a tool in `SESSION_TOOLS` it is a
+     * working road; for any other keyed tool it says so plainly, instead of sending them down it.
+     */
+    keyless_alternative: string;
+}
+/**
+ * Stands in for the name of a `tools/call` that did not give one. It never matches a real tool, so
+ * it cannot collide with `KEYLESS_TOOLS`, and the refusal below recognises it.
+ */
+export declare const MALFORMED_TOOL_NAME = "<unnamed>";
+/**
+ * The refusal for a `tools/call` that named no tool.
+ *
+ * Its own body because it is its own situation: such a call is classified KEYED (fail-closed), but
+ * answering it with "the tool <unnamed> needs a Proof account. Sign in…" would send somebody whose
+ * message was malformed off to authenticate, which fixes nothing. The 401 and the challenge stay —
+ * the classification is what they follow from — while the words say what is actually wrong.
+ */
+export declare function malformedToolCallBody(): {
+    error: 'invalid_request';
+    error_description: string;
+};
+/**
+ * The human half of the refusal, written for the WORST measured client rather than the best.
+ *
+ * MCP Inspector replays the call by itself and Claude Desktop does it after one button press, so
+ * neither user ever reads this. Claude Code turns toward OAuth, stops before the browser step,
+ * needs a separate `claude mcp login`, and does NOT replay the call — for that person this text is
+ * the entire instruction, which is why it names the action twice over rather than reporting a
+ * state.
+ *
+ * `connect_instructions_url` is the existing public `GET /api/v1/mcp/connect` (`h-mcp-showcase`) rather than a new
+ * address. Nothing here makes a network call: `start_login` would be the more direct link, but it
+ * CREATES a login session, so calling it from a 401 handler would hand any anonymous caller a
+ * generator of Redis entries. It is named in the text instead, for clients that cannot speak OAuth
+ * at all.
+ */
+export declare function authorizationRequiredBody(baseUrl: string, tool: string): AuthorizationRequiredBody;
+/**
+ * The refusal for a request whose credential does not match the session it names.
+ *
+ * A separate text because it is a different situation, not a different tool: nothing the caller
+ * asked for is wrong, the session id and the token simply belong to two different connections. The
+ * challenge beside it is the same, so a client that lost its token still turns toward the
+ * authorization server instead of retrying forever.
+ */
+export declare function sessionCredentialMismatchBody(): {
+    error: 'authorization_required';
+    error_description: string;
+};
+/** One tool call that needs an account. `malformed` means the call named no tool at all. */
+export interface KeyedToolCall {
+    name: string;
+    malformed: boolean;
+}
+/**
+ * Names of the tool calls in this JSON-RPC message that need an account.
+ *
+ * FAIL-CLOSED on every axis: a name that is not in `KEYLESS_TOOLS` is keyed, including one that
+ * matches no tool at all — a typo must break a tool rather than open a hole. Anything that is not a
+ * `tools/call` (the handshake, `tools/list`, notifications, an unparseable body) contributes
+ * nothing, because refusing those is the arrangement the probe measured as a broken connection.
+ *
+ * `registered`, when the caller holds it, is the set of names the session's server answers to. A
+ * well-formed name outside it is then skipped rather than keyed, so the SDK refuses it as an unknown
+ * tool instead of the caller being sent to sign in over a typo (M9, live review 2026-09-26). That
+ * opens nothing — no registered tool answers to such a name — and the typo protection above still
+ * holds, since a keyed tool missing from `KEYLESS_TOOLS` is registered and therefore still keyed.
+ * One bound, stated rather than implied: the SDK looks the name up in a plain object, so an
+ * inherited name (`constructor`, `toString`) resolves to a prototype member, not to nothing, and what
+ * refuses it is the SDK's own `enabled` check ("Tool constructor disabled") — a property of the
+ * dependency, not of this gate.
+ * Without the set (the opening request, before any server exists) the rule stays fully fail-closed.
+ */
+export declare function keyedToolsIn(body: unknown, registered?: ReadonlySet<string>): KeyedToolCall[];
+//# sourceMappingURL=authBoundary.d.ts.map

package/dist/authBoundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authBoundary.d.ts","sourceRoot":"","sources":["../src/authBoundary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,MAAM,CAc5C,CAAC;AAEH;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,MAAM,CAuD5C,CAAC;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,aAAa;IAC5B,+FAA+F;IAC/F,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,qDAAqD;IACrD,aAAa,EAAE,OAAO,CAAC;CACxB;AAwBD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,MAAM,CAQ5E;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CA4CjE;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gCAAgC,0CAA0C,CAAC;AAExF,kFAAkF;AAClF,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE,wBAAwB,CAAC;IAChC,iBAAiB,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,wBAAwB,EAAE,MAAM,CAAC;IACjC;;;OAGG;IACH,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,cAAc,CAAC;AAE/C;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,IAAI;IAAE,KAAK,EAAE,iBAAiB,CAAC;IAAC,iBAAiB,EAAE,MAAM,CAAA;CAAE,CAO/F;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,yBAAyB,CAmBlG;AAED;;;;;;;GAOG;AACH,wBAAgB,6BAA6B,IAAI;IAAE,KAAK,EAAE,wBAAwB,CAAC;IAAC,iBAAiB,EAAE,MAAM,CAAA;CAAE,CAO9G;AAED,4FAA4F;AAC5F,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,aAAa,EAAE,CA2B7F"}

package/dist/authBoundary.js

@@ -0,0 +1,341 @@
+/**
+ * The boundary between what this server answers with no account and what needs one
+ * (`h-mcp-oauth-remote-wiring`).
+ *
+ * WHY IT LIVES HERE, and not inside a tool handler: the answer to "you need to sign in" is an HTTP
+ * 401 carrying `WWW-Authenticate`, and that is what a client's OAuth stack reads. By the time a tool
+ * handler runs, the response is already a JSON-RPC result — the same refusal delivered there is
+ * text, not a challenge, and every measured client ignores it (`docs/mcp-oauth-client-probe.md`).
+ * So the remote server has to classify the message BEFORE handing it to the transport, and this
+ * module is the one place that classification is written down.
+ *
+ * WHERE IT SITS, and why not on `initialize`: the control measurement in the probe put a 401 on the
+ * opening handshake and the human saw `Failed to connect — connection timed out after 30000ms`,
+ * i.e. a broken connection rather than an invitation to sign in. Anonymous connection is a closed
+ * criterion of `h-mcp-remote`, so the 401 lands on the TOOL CALL that needs an account and nowhere
+ * else.
+ */
+/**
+ * Tools that work with no credential at all.
+ *
+ * Derived from `PUBLIC_PATHS` in `./http.js` — the endpoints the HTTP client is allowed to call
+ * with no bearer — plus the two tools that never touch our API: `verify_delegation` /
+ * `verify_delegations` run `@proof-holdings/delegation-verifier` against an issuer's public
+ * surfaces, and `render_auth_link` is local QR generation.
+ *
+ * `__tests__/auth-boundary.test.ts` compares this list against the tools the factory actually
+ * registers, in BOTH directions: a name here that no tool answers to would refuse nothing while
+ * reading exactly like a boundary, and anything the server registers that is not here must be
+ * refused without a key.
+ */
+export const KEYLESS_TOOLS = new Set([
+    // Bootstrap: create an account and sign in, which is how a keyless caller stops being keyless.
+    'create_account',
+    'send_account_email',
+    'wait_for_account_creation',
+    'start_login',
+    'wait_for_login',
+    // Public verification surface: checking somebody else's proof is not an account operation.
+    'validate_proof',
+    'list_revoked_proofs',
+    'verify_delegation',
+    'verify_delegations',
+    // Local computation, no HTTP at all.
+    'render_auth_link',
+]);
+/**
+ * Tools that WORK over a `start_login` session.
+ *
+ * Their endpoints are the caller's own account records — the paths `SESSION_AUTH_PREFIXES` in
+ * `./http.ts` signs with the session token (plus `/api/v1/auth/me`). Every other keyed tool needs
+ * the API key the client's Authenticate step grants, and the refusal below tells the caller which
+ * side of that line the tool they asked for is on, BEFORE they walk the road. It used to say
+ * "call start_login" to everyone; a human did, signed in through Telegram, and was refused again by
+ * a second text that finally explained the difference (h-fix-mcp-refusal-roads).
+ *
+ * Hand-written here because the package cannot read docs/api-map.yaml at runtime, and held equal to
+ * the truth in BOTH directions by `src/__tests__/drift/api-parity.test.ts` (`parseMcpSessionTools`
+ * joins this set to the map through the paths the client signs) and by `validateMcpSessionToolCoverage`
+ * in `scripts/validate-api-map.ts`. `__tests__/auth-boundary.test.ts` keeps it to registered tools
+ * and disjoint from `KEYLESS_TOOLS`.
+ */
+export const SESSION_TOOLS = new Set([
+    'add_domain',
+    'add_verification_provider',
+    'cancel_user_request',
+    'check_domain_credentials',
+    'check_domain_email_status',
+    'check_user_domain_verification',
+    'claim_request_assets',
+    'claim_username',
+    'confirm_domain_email_code',
+    'connect_cloudflare',
+    'connect_dns_provider',
+    'connect_godaddy',
+    'create_api_key',
+    'create_dns_credential',
+    'create_user_request',
+    'delete_dns_credential',
+    'delete_domain',
+    'extend_request',
+    'get_2fa_status',
+    'get_add_email_status',
+    'get_add_phone_status',
+    'get_api_key_usage',
+    'get_current_user',
+    'get_dns_providers',
+    'get_domain',
+    'get_user_domain_verification_status',
+    'list_api_keys',
+    'list_dns_credentials',
+    'list_domains',
+    'list_emails',
+    'list_incoming_requests',
+    'list_my_requests',
+    'list_phones',
+    'regenerate_api_key',
+    'remove_email',
+    'remove_phone',
+    'resend_domain_email',
+    'resend_email_otp',
+    'revoke_api_key',
+    'set_primary_email',
+    'set_primary_phone',
+    'setup_domain_email',
+    'share_request_email',
+    'start_2fa',
+    'start_add_email',
+    'start_add_phone',
+    'start_domain_email_verification',
+    'start_user_domain_verification',
+    'update_public_proofs',
+    'verify_2fa',
+    'verify_2fa_magic_link',
+    'verify_domain',
+    'verify_domain_with_credentials',
+    'verify_email_otp',
+]);
+/** How to get an account here — the one sentence that differs between the two transports. */
+function credentialRecipe(remote) {
+    return remote
+        ? 'authenticate this client (in Claude Code: /mcp → this server → Authenticate)'
+        : "set PROOF_API_KEY in this server's environment and restart it";
+}
+/**
+ * The same recipe as an IMPERATIVE, for the per-tool notice.
+ *
+ * Separate from the sentence above because every registration outside `KEYLESS_TOOLS` pays for it.
+ * Measured on the built server:
+ * the full-prose form added 33.8 KB to 41.8 KB of descriptions — it doubled the anonymous
+ * `tools/list`, which is the listing this whole epic exists to serve. The recipe survives; the
+ * padding does not, and `instructions` carries the long form once.
+ */
+function shortRecipe(remote) {
+    return remote
+        ? 'Authenticate this client (Claude Code: /mcp → Authenticate)'
+        : 'Set PROOF_API_KEY and restart this server';
+}
+/**
+ * The suffix appended to one tool's description, or `''` when the tool needs nothing.
+ *
+ * The session/keyed split is the same one `keyless_alternative` makes in the refusal, and it is
+ * here for the same reason: telling every refused caller to run `start_login` walked a human
+ * through an entire Telegram login and into a SECOND refusal that contradicted the first
+ * (`h-fix-mcp-refusal-roads`).
+ */
+export function accessNoticeFor(tool, context) {
+    if (context.hasCredential)
+        return '';
+    if (KEYLESS_TOOLS.has(tool))
+        return '';
+    const recipe = shortRecipe(context.remote);
+    return SESSION_TOOLS.has(tool)
+        ? `\n\nACCESS: needs a Proof account. ${recipe}, or sign in with start_login — a session opens this tool — then call this tool again.`
+        : `\n\nACCESS: needs a Proof account. ${recipe}, then call this tool again. start_login does NOT open this tool.`;
+}
+/**
+ * The `instructions` string of the `initialize` result — the one place the whole arrangement can be
+ * stated once instead of per tool.
+ *
+ * Whether a given client actually shows this to its model is NOT assumed here; it is measured on a
+ * live client as part of this task, and the per-tool notice above is what carries the fact when the
+ * answer is no.
+ */
+export function serverInstructions(context) {
+    const opening = 'Proof — identity and control verification (proof.holdings): verification requests across SMS, ' +
+        'messenger and biometric channels, human approvals, proof tokens, delegations and public profiles.';
+    if (context.hasCredential) {
+        return (`${opening} This connection is authenticated. Which tools work depends on the SCOPES of the key it ` +
+            'carries, not on this server: a tool outside them answers 403 insufficient_scope naming the scope it ' +
+            'wanted, which is a different problem from needing an account.');
+    }
+    // DERIVED from the set rather than retyped beside it: the keyless surface has widened three times
+    // in this epic, and a prose list would go on claiming an account is needed for a tool that needs
+    // none, with every gate green. Nothing hand-written describes the set either — a sentence
+    // categorising what these tools "cover" is true of today's ten and silently false of the
+    // eleventh, which is the same drift one clause later.
+    const keyless = [...KEYLESS_TOOLS].sort().join(', ');
+    // The 401 paragraph is REMOTE-ONLY. On stdio there is no HTTP layer to answer 401: the refusal is
+    // an `api_key_required` the handler returns as readable text, so an opaque failure there really is
+    // a crashed process or a call that outlived the client's timeout. Telling the agent otherwise
+    // would hand it a pre-written wrong cause — the same defect as "the token expired".
+    const opaqueFailure = context.remote
+        ? 'If a tool call fails at the transport with no readable explanation, the usual cause is this server ' +
+            'answering 401 to ask for authentication — the refusal carries its reason in a body most clients ' +
+            'discard, so no expired token is involved: authenticate, then make the call again. A session left ' +
+            'idle for a long time is the other cause: this server drops idle sessions, and the next call on a ' +
+            'dropped one needs a reconnect rather than a credential.'
+        : 'A tool that needs an account answers a readable `api_key_required` result rather than failing, so ' +
+            'an opaque failure here is not a credential problem — it is a crashed server process or a call that ' +
+            "outlived your client's request timeout.";
+    return [
+        `${opening} This connection is ANONYMOUS — nothing has been signed in yet.`,
+        `Works right now with no account: ${keyless}.`,
+        `Everything else needs a Proof account, and each such tool says so in its own description. Two roads: ${credentialRecipe(context.remote)} and then CALL THE TOOL AGAIN — some clients replay it for you, Claude Code does not. That grants an API key, whose SCOPES then decide which tools work (a tool outside them answers 403 insufficient_scope, not a request to sign in). Or call start_login and wait_for_login, which signs ` +
+            'in a session that opens only your own account records — emails, phones, domains, API keys, 2FA, DNS ' +
+            "credentials, verification requests, your public profile's username and proof list.",
+        opaqueFailure,
+    ].join('\n\n');
+}
+/**
+ * RFC 9728 — the document our `WWW-Authenticate` names in `resource_metadata`.
+ *
+ * A DELIBERATE SECOND COPY of `PROTECTED_RESOURCE_METADATA_PATH` in the backend's
+ * `src/constants/mcpOauth.ts`. This package is its own build and published separately, so it cannot
+ * import from `src/`; the two are held together by text instead —
+ * `src/__tests__/drift/mcp-oauth-remote-wiring.test.ts` reads this literal out of this file and
+ * compares it with the constant. Rename either side without the other and that suite goes red,
+ * which is the only thing standing between "the header points at a document" and "the header points
+ * at a 404 while every test is green".
+ */
+export const PROTECTED_RESOURCE_METADATA_PATH = '/.well-known/oauth-protected-resource';
+/** Absolute address of the protected-resource document for a given API origin. */
+export function resourceMetadataUrl(baseUrl) {
+    return `${baseUrl.replace(/\/+$/, '')}${PROTECTED_RESOURCE_METADATA_PATH}`;
+}
+/**
+ * The `WWW-Authenticate` value. Form taken from the run that actually worked — all three clients
+ * followed `resource_metadata` from this exact shape (`mcp/probe/oauth-probe.mjs`).
+ */
+export function authorizationChallenge(baseUrl) {
+    return `Bearer realm="proof", resource_metadata="${resourceMetadataUrl(baseUrl)}"`;
+}
+/**
+ * Stands in for the name of a `tools/call` that did not give one. It never matches a real tool, so
+ * it cannot collide with `KEYLESS_TOOLS`, and the refusal below recognises it.
+ */
+export const MALFORMED_TOOL_NAME = '<unnamed>';
+/**
+ * The refusal for a `tools/call` that named no tool.
+ *
+ * Its own body because it is its own situation: such a call is classified KEYED (fail-closed), but
+ * answering it with "the tool <unnamed> needs a Proof account. Sign in…" would send somebody whose
+ * message was malformed off to authenticate, which fixes nothing. The 401 and the challenge stay —
+ * the classification is what they follow from — while the words say what is actually wrong.
+ */
+export function malformedToolCallBody() {
+    return {
+        error: 'invalid_request',
+        error_description: 'This tools/call named no tool, so there is nothing to run — and nothing to authorize either. ' +
+            'Send params.name with the tool you meant.',
+    };
+}
+/**
+ * The human half of the refusal, written for the WORST measured client rather than the best.
+ *
+ * MCP Inspector replays the call by itself and Claude Desktop does it after one button press, so
+ * neither user ever reads this. Claude Code turns toward OAuth, stops before the browser step,
+ * needs a separate `claude mcp login`, and does NOT replay the call — for that person this text is
+ * the entire instruction, which is why it names the action twice over rather than reporting a
+ * state.
+ *
+ * `connect_instructions_url` is the existing public `GET /api/v1/mcp/connect` (`h-mcp-showcase`) rather than a new
+ * address. Nothing here makes a network call: `start_login` would be the more direct link, but it
+ * CREATES a login session, so calling it from a 401 handler would hand any anonymous caller a
+ * generator of Redis entries. It is named in the text instead, for clients that cannot speak OAuth
+ * at all.
+ */
+export function authorizationRequiredBody(baseUrl, tool) {
+    const sessionReaches = SESSION_TOOLS.has(tool);
+    return {
+        error: 'authorization_required',
+        error_description: `The tool "${tool}" needs a Proof account. Sign in, then CALL THE TOOL AGAIN — some clients ` +
+            'replay the call for you, Claude Code does not. Connecting happens inside the client; there is ' +
+            'no web page for it. In Claude Code: /mcp → this server → Authenticate, or `claude mcp login ' +
+            '<server>` in a separate terminal window (it needs an interactive terminal). Then repeat the ' +
+            'call yourself.',
+        connect_instructions_url: `${baseUrl.replace(/\/+$/, '')}/api/v1/mcp/connect`,
+        keyless_alternative: sessionReaches
+            ? 'No OAuth support in your client? Call start_login — it returns a sign-in link, and ' +
+                'render_auth_link turns that link into a QR code — then wait_for_login. This tool works over ' +
+                'that signed-in session.'
+            : 'start_login will NOT unlock this tool. A signed-in session covers only your own account ' +
+                'records — emails, phones, domains, API keys, 2FA, DNS credentials, verification requests, ' +
+                "your public profile's username and proof list. This tool needs the API key that connecting grants.",
+    };
+}
+/**
+ * The refusal for a request whose credential does not match the session it names.
+ *
+ * A separate text because it is a different situation, not a different tool: nothing the caller
+ * asked for is wrong, the session id and the token simply belong to two different connections. The
+ * challenge beside it is the same, so a client that lost its token still turns toward the
+ * authorization server instead of retrying forever.
+ */
+export function sessionCredentialMismatchBody() {
+    return {
+        error: 'authorization_required',
+        error_description: 'This session was opened with a different credential. A session belongs to the token that ' +
+            'opened it — reconnect to start a new one rather than reusing this session id.',
+    };
+}
+/**
+ * Names of the tool calls in this JSON-RPC message that need an account.
+ *
+ * FAIL-CLOSED on every axis: a name that is not in `KEYLESS_TOOLS` is keyed, including one that
+ * matches no tool at all — a typo must break a tool rather than open a hole. Anything that is not a
+ * `tools/call` (the handshake, `tools/list`, notifications, an unparseable body) contributes
+ * nothing, because refusing those is the arrangement the probe measured as a broken connection.
+ *
+ * `registered`, when the caller holds it, is the set of names the session's server answers to. A
+ * well-formed name outside it is then skipped rather than keyed, so the SDK refuses it as an unknown
+ * tool instead of the caller being sent to sign in over a typo (M9, live review 2026-09-26). That
+ * opens nothing — no registered tool answers to such a name — and the typo protection above still
+ * holds, since a keyed tool missing from `KEYLESS_TOOLS` is registered and therefore still keyed.
+ * One bound, stated rather than implied: the SDK looks the name up in a plain object, so an
+ * inherited name (`constructor`, `toString`) resolves to a prototype member, not to nothing, and what
+ * refuses it is the SDK's own `enabled` check ("Tool constructor disabled") — a property of the
+ * dependency, not of this gate.
+ * Without the set (the opening request, before any server exists) the rule stays fully fail-closed.
+ */
+export function keyedToolsIn(body, registered) {
+    const messages = Array.isArray(body) ? body : [body];
+    const keyed = [];
+    for (const message of messages) {
+        const entry = message;
+        if (!entry || typeof entry !== 'object')
+            continue;
+        if (entry.method !== 'tools/call')
+            continue;
+        const name = entry.params?.name;
+        // A `tools/call` whose name is missing or not a string is KEYED, under a placeholder —
+        // `continue` would have made a malformed call the one shape that walks past the gate.
+        //
+        // REACHABLE, and stated so rather than waved away: on the remote transport this classification
+        // runs BEFORE the message reaches the SDK, so the SDK's schema never gets to refuse it. Which
+        // is why "malformed" is carried as a FLAG rather than inferred later from the placeholder
+        // string: a caller may send `params.name: "<unnamed>"`, and deciding at the refusal by
+        // comparing strings would answer that caller "this call named no tool" — a sentence about a
+        // message they did not send. The decision belongs where the evidence is.
+        if (typeof name !== 'string' || !name) {
+            keyed.push({ name: MALFORMED_TOOL_NAME, malformed: true });
+            continue;
+        }
+        if (registered && !registered.has(name))
+            continue;
+        if (!KEYLESS_TOOLS.has(name))
+            keyed.push({ name, malformed: false });
+    }
+    return keyed;
+}
+//# sourceMappingURL=authBoundary.js.map

package/dist/authBoundary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authBoundary.js","sourceRoot":"","sources":["../src/authBoundary.ts"],"names":[],"mappings":"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"}

package/dist/factory.d.ts

@@ -0,0 +1,35 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { HttpClient } from './http.js';
+export interface ProofServerOptions {
+    /** API key (Bearer). Absent → public mode, exactly as on the stdio path. */
+    apiKey?: string;
+    baseUrl: string;
+    /**
+     * Set by the REMOTE entrypoint. The only thing it changes is what a "you need a key" refusal
+     * tells the user to do: the stdio instruction (set `PROOF_API_KEY`, restart the server) is
+     * impossible on a server run by somebody else.
+     */
+    remote?: boolean;
+}
+export interface ProofServerInstance {
+    server: McpServer;
+    http: HttpClient;
+    /** Every tool name registered on `server`, collected by the registrar below as it registers them. */
+    toolNames: ReadonlySet<string>;
+}
+/**
+ * Builds one MCP server with its own HTTP client.
+ *
+ * Why a factory at all (`h-mcp-remote`, SC-4): the stdio entrypoint serves exactly one user, so one
+ * `HttpClient` per process is correct there. The remote server serves many, and `HttpClient` keeps
+ * `sessionToken` / `refreshToken` as INSTANCE fields written by `captureSetCookie` — sharing one
+ * across connections would hand the next user the previous user's logged-in session. So the unit of
+ * isolation is the connection, and this function is that unit.
+ *
+ * The registration list below is the ONLY copy in the package: `server.ts` calls this rather than
+ * repeating it. A second copy would work on the day it was written and drift one module at a time
+ * afterwards, with both paths green — `__tests__/factory.test.ts` pins both the list's completeness
+ * against `src/tools` and the absence of a second copy in `server.ts`.
+ */
+export declare function createProofServer(options: ProofServerOptions): ProofServerInstance;
+//# sourceMappingURL=factory.d.ts.map

package/dist/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../src/factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAuB,MAAM,yCAAyC,CAAC;AAEzF,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAoCvC,MAAM,WAAW,kBAAkB;IACjC,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,SAAS,CAAC;IAClB,IAAI,EAAE,UAAU,CAAC;IACjB,qGAAqG;IACrG,SAAS,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAChC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,mBAAmB,CA0FlF"}