@proof-holdings/mcp-server 1.0.0 → 1.1.0

package/dist/factory.js

@@ -0,0 +1,123 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { HttpClient } from './http.js';
+import { accessNoticeFor, serverInstructions } from './authBoundary.js';
+import { registerTools as registerVerifications } from './tools/verifications.js';
+import { registerTools as registerVerificationRequests } from './tools/verification-requests.js';
+import { registerTools as registerProofs } from './tools/proofs.js';
+import { registerTools as registerSessions } from './tools/sessions.js';
+import { registerTools as registerAssets } from './tools/assets.js';
+import { registerTools as registerAuth } from './tools/auth.js';
+import { registerTools as registerSettings } from './tools/settings.js';
+import { registerTools as registerTemplates } from './tools/templates.js';
+import { registerTools as registerWebhookDeliveries } from './tools/webhook-deliveries.js';
+import { registerTools as registerBilling } from './tools/billing.js';
+import { registerTools as registerProfiles } from './tools/profiles.js';
+import { registerTools as registerEmails } from './tools/emails.js';
+import { registerTools as registerPhones } from './tools/phones.js';
+import { registerTools as registerApiKeys } from './tools/api-keys.js';
+import { registerTools as registerTwofa } from './tools/twofa.js';
+import { registerTools as registerDomains } from './tools/domains.js';
+import { registerTools as registerDnsCredentials } from './tools/dns-credentials.js';
+import { registerTools as registerUserRequests } from './tools/user-requests.js';
+import { registerTools as registerUserDomainVerify } from './tools/user-domain-verify.js';
+import { registerTools as registerPublicProfiles } from './tools/public-profiles.js';
+import { registerTools as registerAuthorizations } from './tools/authorizations.js';
+import { registerTools as registerConfirmations } from './tools/confirmations.js';
+import { registerTools as registerHitl } from './tools/hitl.js';
+import { registerTools as registerHitlKeys } from './tools/hitl-keys.js';
+import { registerTools as registerProofMe } from './tools/proof-me.js';
+import { registerTools as registerCircles } from './tools/circles.js';
+import { registerTools as registerDelegations } from './tools/delegations.js';
+import { registerTools as registerDelegationVerify } from './tools/delegation-verify.js';
+import { registerTools as registerAuthFlows } from './tools/auth-flows.js';
+import { registerTools as registerAccounts } from './tools/accounts.js';
+import { registerTools as registerRenderAuthLink } from './tools/render-auth-link.js';
+/**
+ * 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 function createProofServer(options) {
+    const http = new HttpClient({
+        apiKey: options.apiKey,
+        baseUrl: options.baseUrl,
+        remote: options.remote,
+    });
+    const access = { remote: options.remote, hasCredential: Boolean(options.apiKey) };
+    const server = new McpServer({
+        name: 'proof-holdings',
+        // The version every client reads back from `initialize`, and the one a user quotes in a bug
+        // report. A LITERAL rather than a read of `mcp/package.json` — a CHOICE, not a constraint;
+        // the manifest is reachable from here. What makes the literal safe is the pin below, never
+        // that choice. Held equal to the manifest by
+        // `src/__tests__/drift/delegation-publication.test.ts` (h-npm-registry-release). If this is
+        // ever replaced by a real read, delete the pin in the same change: a pin over a derived
+        // value guards nothing.
+        version: '1.1.0',
+    }, { instructions: serverInstructions(access) });
+    const bound = server.tool.bind(server);
+    /**
+     * The registrar every module below is handed, wrapping `server.tool` so the access notice is
+     * appended in ONE place (`h-fix-mcp-agent-facing-text`, SC-1).
+     *
+     * Editing 176 descriptions by hand would have put the same sentence in 176 places, drifting one
+     * tool at a time, and each copy would have had to know the transport it was registered on —
+     * which a description literal cannot. Here the classification in `authBoundary.ts` is read once,
+     * beside the connection that determines it. The signature is `server.tool`'s own, and only the
+     * description argument is touched: a registration whose second argument is not a string is passed
+     * through untouched rather than being coerced, because the SDK accepts several call shapes and a
+     * wrapper that assumes one would corrupt the others.
+     */
+    const tool = ((...args) => {
+        const [name, description] = args;
+        if (typeof name === 'string' && typeof description === 'string') {
+            const rest = args.slice(2);
+            return bound(name, description + accessNoticeFor(name, access), ...rest);
+        }
+        return bound(...args);
+    });
+    registerVerifications(tool, http);
+    registerVerificationRequests(tool, http);
+    registerProofs(tool, http);
+    registerSessions(tool, http);
+    registerAssets(tool, http);
+    registerAuth(tool, http);
+    registerSettings(tool, http);
+    registerTemplates(tool, http);
+    registerWebhookDeliveries(tool, http);
+    registerBilling(tool, http);
+    registerProfiles(tool, http);
+    registerEmails(tool, http);
+    registerPhones(tool, http);
+    registerApiKeys(tool, http);
+    registerTwofa(tool, http);
+    registerDomains(tool, http);
+    registerDnsCredentials(tool, http);
+    registerUserRequests(tool, http);
+    registerUserDomainVerify(tool, http);
+    registerPublicProfiles(tool, http);
+    registerAuthorizations(tool, http);
+    registerConfirmations(tool, http);
+    registerHitl(tool, http);
+    registerHitlKeys(tool, http);
+    registerProofMe(tool, http);
+    registerCircles(tool, http);
+    registerDelegations(tool, http);
+    // Takes the base URL rather than the HTTP client: verifying a third party's delegation runs
+    // against PUBLIC surfaces only and carries no API key.
+    registerDelegationVerify(tool, { baseUrl: options.baseUrl });
+    registerAuthFlows(tool, http);
+    registerAccounts(tool, http);
+    registerRenderAuthLink(tool);
+    return { server, http };
+}
+//# sourceMappingURL=factory.js.map

package/dist/factory.js.map

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

package/dist/http.d.ts

@@ -1,26 +1,86 @@
 export interface HttpClientConfig {
-    apiKey: string;
+    /**
+     * API key (Bearer). OPTIONAL — the server also runs in public mode, where the bootstrap
+     * and verification surfaces work with no credential at all and every other tool answers
+     * `api_key_required` instead of the process exiting at startup.
+     */
+    apiKey?: string;
     baseUrl: string;
     timeout?: number;
     maxRetries?: number;
+    /**
+     * True when this client serves the REMOTE transport (`src/remote.ts`) rather than a local stdio
+     * process. It changes exactly one thing — what the "you need a key" refusal tells the user to do
+     * — because the stdio instruction (set `PROOF_API_KEY`, restart the server) is impossible on a
+     * server somebody else runs.
+     */
+    remote?: boolean;
 }
 type QueryValue = string | number | boolean | undefined;
+/**
+ * Endpoints the client may call with NO credential — the public mode surface.
+ *
+ * Stored as (method, prefix) PAIRS, not bare prefixes, and the reason is load-bearing:
+ * `/api/v1/auth/sessions` is the prefix of two public routes (create a login session, poll one)
+ * AND of two `jwt+api_key` ones (`GET /auth/sessions` lists sessions, `DELETE /auth/sessions/:id`
+ * revokes one). A prefix-only list would mark those two public, so a keyless call would travel to
+ * the network and come back `invalid_token` instead of getting the structured hint here.
+ *
+ * The drift rule `validateMcpPublicPathCoverage` (scripts/validate-api-map.ts) requires every
+ * `auth: public` + `mcp: available` endpoint in docs/api-map.yaml to appear below. That rule is a
+ * LOWER BOUND, not the definition: the two poll routes are carried here but not required by it,
+ * because the map holds them `planned` (they are reached through `wait_for_login` /
+ * `wait_for_account_creation` rather than by a tool of their own). Removing them would leave both
+ * wait tools broken in public mode while every check stayed green.
+ */
+export declare const PUBLIC_PATHS: ReadonlyArray<{
+    method: string;
+    prefix: string;
+}>;
 export declare class HttpClient {
     readonly baseUrl: string;
-    private readonly apiKey;
+    private readonly apiKey?;
     private readonly timeout;
     private readonly maxRetries;
+    private readonly remote;
+    private sessionToken?;
+    private refreshToken?;
+    private refreshing?;
     constructor(config: HttpClientConfig);
     request<T>(method: string, path: string, options?: {
         body?: unknown;
         query?: Record<string, QueryValue>;
+        headers?: Record<string, string>;
+        /** Internal: set on the post-refresh retry to prevent an infinite refresh loop. */
+        _refreshed?: boolean;
     }): Promise<T>;
+    /**
+     * True once a login flow has put a session on this client (`captureSetCookie`).
+     *
+     * Boolean only, never the token: the remote server needs to know whether this CONNECTION has
+     * been signed in — the bootstrap road `start_login` opens — and nothing else. Without it a caller
+     * with no API key looks identical before and after signing in, and the tools behind
+     * `SESSION_AUTH_PREFIXES` are refused to a user who just logged in.
+     */
+    hasSessionToken(): boolean;
     get<T>(path: string, query?: Record<string, QueryValue>): Promise<T>;
     post<T>(path: string, body?: unknown): Promise<T>;
     put<T>(path: string, body?: unknown): Promise<T>;
     patch<T>(path: string, body?: unknown): Promise<T>;
-    del<T>(path: string): Promise<T>;
+    del<T>(path: string, body?: unknown): Promise<T>;
     private buildUrl;
+    /** True for endpoints behind `jwtAuth` — the user JWT session surface. */
+    private usesSessionAuth;
+    /** Capture the `token` / `refresh_token` cookies the login + refresh flows set via Set-Cookie. */
+    private captureSetCookie;
+    /**
+     * Exchange the refresh token for a rotated access token. Returns true on success.
+     * Concurrent callers share one in-flight refresh so a single-use refresh token is
+     * only spent once (otherwise the loser would post a consumed token and wipe the
+     * freshly-rotated session).
+     */
+    private refreshSession;
+    private doRefresh;
     private backoff;
     private sleep;
 }

package/dist/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,KAAK,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;AAExD,qBAAa,UAAU;IACrB,SAAgB,OAAO,EAAE,MAAM,CAAC;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAExB,MAAM,EAAE,gBAAgB;IAO9B,OAAO,CAAC,CAAC,EACb,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;KACpC,GACA,OAAO,CAAC,CAAC,CAAC;IA2Eb,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAIpE,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAIjD,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAIhD,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAIlD,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;IAIhC,OAAO,CAAC,QAAQ;IAYhB,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,KAAK;CAGd;AAED,qBAAa,QAAS,SAAQ,KAAK;aAGf,IAAI,EAAE,MAAM;aACZ,UAAU,EAAE,MAAM;aAClB,OAAO,CAAC,EAAE,OAAO;gBAHjC,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,OAAO,YAAA;CAMpC"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,KAAK,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;AAwBxD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,YAAY,EAAE,aAAa,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAO1E,CAAC;AAQF,qBAAa,UAAU;IACrB,SAAgB,OAAO,EAAE,MAAM,CAAC;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;IACjC,OAAO,CAAC,YAAY,CAAC,CAAS;IAC9B,OAAO,CAAC,YAAY,CAAC,CAAS;IAC9B,OAAO,CAAC,UAAU,CAAC,CAAmB;gBAE1B,MAAM,EAAE,gBAAgB;IAQ9B,OAAO,CAAC,CAAC,EACb,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QACR,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;QACnC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACjC,mFAAmF;QACnF,UAAU,CAAC,EAAE,OAAO,CAAC;KACtB,GACA,OAAO,CAAC,CAAC,CAAC;IA2Hb;;;;;;;OAOG;IACH,eAAe,IAAI,OAAO;IAI1B,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAIpE,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAIjD,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAIhD,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAIlD,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAIhD,OAAO,CAAC,QAAQ;IAYhB,0EAA0E;IAC1E,OAAO,CAAC,eAAe;IAIvB,kGAAkG;IAClG,OAAO,CAAC,gBAAgB;IAexB;;;;;OAKG;IACH,OAAO,CAAC,cAAc;YASR,SAAS;IA6BvB,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,KAAK;CAGd;AAED,qBAAa,QAAS,SAAQ,KAAK;aAGf,IAAI,EAAE,MAAM;aACZ,UAAU,EAAE,MAAM;aAClB,OAAO,CAAC,EAAE,OAAO;gBAHjC,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,OAAO,YAAA;CAMpC"}

package/dist/http.js

@@ -1,16 +1,103 @@
-const VERSION = '1.0.0';
+// The version this client sends in its own `User-Agent` (`proof-mcp/<version>`), i.e. what the
+// issuer's logs attribute a request to. A LITERAL for the same reason `factory.ts`'s `serverInfo`
+// one is, and safe for the same reason: the pin, not the choice. Held equal to `mcp/package.json`
+// by `src/__tests__/drift/delegation-publication.test.ts` (h-npm-registry-release).
+//
+// Of the carriers a version bump has to move, this is the one it misses: a bare constant at the
+// top of a module about HTTP, where nothing about editing the manifest leads a reader.
+const VERSION = '1.1.0';
+// Path prefixes protected by `jwtAuth` ONLY (pure JWT surface — these 401 with an API key).
+// Deliberately excludes the dual-auth (`jwtOrApiKeyAuth`) endpoints that already work with the
+// API key and enforce its scopes — `/me/{profiles,settings,usage,export,assets}`,
+// `/profiles/me`, `/profiles/me/assets`, `/profiles/profiles/:id/proofs`, and `/auth/sessions`
+// (list/revoke). Sending the JWT there would silently switch the principal from the API-key
+// tenant to the logged-in user and bypass scope checks. The two `/profiles/me/*` entries
+// below are the jwt-only exceptions inside that otherwise dual-auth family.
+const SESSION_AUTH_PREFIXES = [
+    '/api/v1/me/emails',
+    '/api/v1/me/phones',
+    '/api/v1/me/api-keys',
+    '/api/v1/me/2fa',
+    '/api/v1/me/domains',
+    '/api/v1/me/dns-credentials',
+    '/api/v1/me/dns-providers',
+    '/api/v1/me/verification-requests',
+    '/api/v1/me/verify/',
+    '/api/v1/me/account',
+    '/api/v1/profiles/me/username',
+    '/api/v1/profiles/me/proofs',
+];
+/**
+ * Endpoints the client may call with NO credential — the public mode surface.
+ *
+ * Stored as (method, prefix) PAIRS, not bare prefixes, and the reason is load-bearing:
+ * `/api/v1/auth/sessions` is the prefix of two public routes (create a login session, poll one)
+ * AND of two `jwt+api_key` ones (`GET /auth/sessions` lists sessions, `DELETE /auth/sessions/:id`
+ * revokes one). A prefix-only list would mark those two public, so a keyless call would travel to
+ * the network and come back `invalid_token` instead of getting the structured hint here.
+ *
+ * The drift rule `validateMcpPublicPathCoverage` (scripts/validate-api-map.ts) requires every
+ * `auth: public` + `mcp: available` endpoint in docs/api-map.yaml to appear below. That rule is a
+ * LOWER BOUND, not the definition: the two poll routes are carried here but not required by it,
+ * because the map holds them `planned` (they are reached through `wait_for_login` /
+ * `wait_for_account_creation` rather than by a tool of their own). Removing them would leave both
+ * wait tools broken in public mode while every check stayed green.
+ */
+export const PUBLIC_PATHS = [
+    { method: 'POST', prefix: '/api/v1/proofs/validate' },
+    { method: 'GET', prefix: '/api/v1/proofs/revoked' },
+    { method: 'POST', prefix: '/api/v1/auth/sessions' },
+    { method: 'GET', prefix: '/api/v1/auth/sessions/' },
+    { method: 'POST', prefix: '/api/v1/accounts' },
+    { method: 'GET', prefix: '/api/v1/accounts/' },
+];
+/** True when (method, path) is on the public surface above. Method is compared case-insensitively. */
+function isPublicPath(method, path) {
+    const verb = method.toUpperCase();
+    return PUBLIC_PATHS.some((p) => p.method === verb && path.startsWith(p.prefix));
+}
 export class HttpClient {
     baseUrl;
     apiKey;
     timeout;
     maxRetries;
+    remote;
+    sessionToken;
+    refreshToken;
+    refreshing;
     constructor(config) {
         this.apiKey = config.apiKey;
         this.baseUrl = config.baseUrl.replace(/\/$/, '');
         this.timeout = config.timeout ?? 30_000;
         this.maxRetries = config.maxRetries ?? 2;
+        this.remote = config.remote ?? false;
     }
     async request(method, path, options) {
+        const useSession = this.usesSessionAuth(path) && !!this.sessionToken;
+        const bearer = useSession ? this.sessionToken : this.apiKey;
+        // Public mode: answer before the network rather than after it. A credential-less call to a
+        // keyed route would otherwise spend a round trip to return `invalid_token`, which reads to an
+        // agent as "the key is wrong" rather than "there is no key yet".
+        if (!bearer && !isPublicPath(method, path)) {
+            // The wording matters as much as the code, and it has to be true for the transport the caller
+            // is actually on. It once said "run create_account to get a key from inside this session",
+            // which an agent can follow forever without succeeding on stdio: the key is read from the
+            // environment and has no runtime setter. But the fix was written for stdio alone, and on the
+            // REMOTE server the resulting instruction is not merely unhelpful — it is impossible, since
+            // nobody can set an env var on somebody else's pod or restart it. A signed-in remote user
+            // calling a tool outside the session surface is exactly who reads this.
+            throw new ApiError(this.remote
+                ? 'This operation needs a Proof account with an API key. Connect this server to your account ' +
+                    '(your client\'s sign-in / "Authenticate" step), then call the tool again. Signing in with ' +
+                    'start_login alone covers your own contact and account records — emails, phones, domains, ' +
+                    'API keys, 2FA, DNS credentials, verification requests, your public profile\'s username ' +
+                    'and proof list; account-wide reads such as the platform summary, settings and usage ' +
+                    'need the key that connecting grants.'
+                : 'This operation needs a Proof API key, which must be present in PROOF_API_KEY when the server starts. ' +
+                    'Without one you can still create an account or sign in (create_account, start_login) and check ' +
+                    'proofs and delegations. If you are signed in, create_api_key works over that session — but the new ' +
+                    'key takes effect only after it is put in PROOF_API_KEY and this MCP server is restarted.', 'api_key_required', 401);
+        }
         const url = this.buildUrl(path, options?.query);
         let lastError;
         for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
@@ -20,14 +107,17 @@ export class HttpClient {
                 const response = await fetch(url, {
                     method,
                     headers: {
+                        ...options?.headers,
                         'Content-Type': 'application/json',
-                        'Authorization': `Bearer ${this.apiKey}`,
+                        ...(bearer ? { 'Authorization': `Bearer ${bearer}` } : {}),
                         'User-Agent': `proof-mcp/${VERSION}`,
                     },
                     body: options?.body ? JSON.stringify(options.body) : undefined,
                     signal: controller.signal,
                 });
                 clearTimeout(timeoutId);
+                // Capture the JWT session cookie set by the login / account-creation flows
+                this.captureSetCookie(response);
                 if (response.status === 429 && attempt < this.maxRetries) {
                     const retryAfter = response.headers.get('Retry-After');
                     const parsed = retryAfter ? parseInt(retryAfter, 10) : NaN;
@@ -44,6 +134,15 @@ export class HttpClient {
                     const apiError = body.error;
                     const code = apiError?.code ?? `http_${response.status}`;
                     const message = apiError?.message ?? `Request failed with status ${response.status}`;
+                    // Expired session JWT: refresh once and retry the original request.
+                    if (response.status === 401 &&
+                        code === 'token_expired' &&
+                        useSession &&
+                        !options?._refreshed &&
+                        this.refreshToken &&
+                        (await this.refreshSession())) {
+                        return this.request(method, path, { ...options, _refreshed: true });
+                    }
                     throw new ApiError(message, code, response.status, apiError?.details);
                 }
                 return body;
@@ -68,6 +167,17 @@ export class HttpClient {
         }
         throw new ApiError(lastError?.message ?? 'Network request failed', 'network_error', 0);
     }
+    /**
+     * True once a login flow has put a session on this client (`captureSetCookie`).
+     *
+     * Boolean only, never the token: the remote server needs to know whether this CONNECTION has
+     * been signed in — the bootstrap road `start_login` opens — and nothing else. Without it a caller
+     * with no API key looks identical before and after signing in, and the tools behind
+     * `SESSION_AUTH_PREFIXES` are refused to a user who just logged in.
+     */
+    hasSessionToken() {
+        return !!this.sessionToken;
+    }
     get(path, query) {
         return this.request('GET', path, { query });
     }
@@ -80,8 +190,8 @@ export class HttpClient {
     patch(path, body) {
         return this.request('PATCH', path, { body });
     }
-    del(path) {
-        return this.request('DELETE', path);
+    del(path, body) {
+        return this.request('DELETE', path, body ? { body } : undefined);
     }
     buildUrl(path, query) {
         const url = new URL(path, this.baseUrl);
@@ -94,6 +204,75 @@ export class HttpClient {
         }
         return url.toString();
     }
+    /** True for endpoints behind `jwtAuth` — the user JWT session surface. */
+    usesSessionAuth(path) {
+        return SESSION_AUTH_PREFIXES.some((prefix) => path.startsWith(prefix)) || path === '/api/v1/auth/me';
+    }
+    /** Capture the `token` / `refresh_token` cookies the login + refresh flows set via Set-Cookie. */
+    captureSetCookie(response) {
+        // getSetCookie() requires Node >= 18.14 / undici; guard so older runtimes don't throw.
+        if (typeof response.headers.getSetCookie !== 'function')
+            return;
+        const cookies = response.headers.getSetCookie();
+        for (const cookie of cookies) {
+            const pair = cookie.split(';', 1)[0];
+            const eq = pair.indexOf('=');
+            if (eq === -1)
+                continue;
+            const name = pair.slice(0, eq).trim();
+            const value = pair.slice(eq + 1).trim();
+            if (name === 'token')
+                this.sessionToken = value;
+            else if (name === 'refresh_token')
+                this.refreshToken = value;
+        }
+    }
+    /**
+     * Exchange the refresh token for a rotated access token. Returns true on success.
+     * Concurrent callers share one in-flight refresh so a single-use refresh token is
+     * only spent once (otherwise the loser would post a consumed token and wipe the
+     * freshly-rotated session).
+     */
+    refreshSession() {
+        if (!this.refreshToken)
+            return Promise.resolve(false);
+        if (this.refreshing)
+            return this.refreshing;
+        this.refreshing = this.doRefresh().finally(() => {
+            this.refreshing = undefined;
+        });
+        return this.refreshing;
+    }
+    async doRefresh() {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const response = await fetch(this.buildUrl('/api/v1/auth/refresh'), {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Cookie': `refresh_token=${this.refreshToken}`,
+                    'User-Agent': `proof-mcp/${VERSION}`,
+                },
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                this.sessionToken = undefined;
+                this.refreshToken = undefined;
+                return false;
+            }
+            this.captureSetCookie(response);
+            return true;
+        }
+        catch {
+            this.sessionToken = undefined;
+            this.refreshToken = undefined;
+            return false;
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
     backoff(attempt) {
         return Math.min(1000 * Math.pow(2, attempt), 10000);
     }

package/dist/http.js.map

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

package/dist/remote.d.ts

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+/**
+ * Remote entrypoint: the Proof MCP server over Streamable HTTP (`h-mcp-remote`, SC-3 + SC-4).
+ *
+ * Deployed as its own service, NOT as a route inside the existing backend. The reason is
+ * structural rather than stylistic: `src/cluster.ts` forks one worker per CPU and round-robins
+ * between them, while a Streamable HTTP session lives in the memory of ONE process. Mounting this
+ * on the clustered backend would lose sessions by default, not in an edge case. The deployment
+ * therefore pins requests to a replica by the REPLICA PREFIX this server puts in every session id
+ * it mints (`<replica>.<uuid>`); see `replicaId` below for why hashing the id itself cannot work,
+ * and `k8s/mcp-remote/nginx-mcp.conf` for the routing that consumes the prefix. That routing is
+ * deliberately NOT in the base nginx configmap — see that directory's README for the ingress it
+ * would otherwise take down, and `src/__tests__/drift/mcp-remote-deployment.test.ts`, which asserts
+ * the base stays free of it.
+ *
+ * ANONYMOUS FIRST, KEYED ON REQUEST (`h-mcp-oauth-remote-wiring`). Every connection starts with the
+ * keyless surface and the ability to log in through the normal flows; a client that has been
+ * through the OAuth ceremony (`h-mcp-oauth-server`) presents the API key it was granted, and this
+ * server reads it from the `Authorization` header ONLY. A `?api_key=` query parameter is never
+ * read: a token in a URL is copied into proxy logs and `Referer`, and the standard clients all send
+ * a header. The token is resolved ONCE, at open, by self-inspection (`GET /api/v1/me/api-key`) —
+ * purely so the refusal is legible; nothing is cached from it, and the key travels to the backend
+ * on every call, which is what makes a revocation take effect immediately rather than at session
+ * TTL. Where the 401 lands is a measurement, not a preference: on the TOOL CALL that needs an
+ * account, because a 401 on `initialize` reached the human as a connection timeout and cost the
+ * anonymous connection entirely (`docs/mcp-oauth-client-probe.md`).
+ *
+ * Each connection needs its OWN `HttpClient` for two reasons now: `captureSetCookie` writes a login
+ * session onto the instance, and the API key of one connection must never be reachable from
+ * another. The boundary between keyless and keyed tools lives in `./authBoundary.js`.
+ */
+import { type Server } from 'node:http';
+import { HttpClient } from './http.js';
+export interface RemoteServerOptions {
+    baseUrl: string;
+    /** Maximum concurrent MCP sessions. Each one registers the full tool set, so this is a memory bound. */
+    maxSessions?: number;
+    /** Idle time after which a session is closed and dropped. */
+    sessionTtlMs?: number;
+    sweepIntervalMs?: number;
+    /**
+     * Which replica this process is. It is PREFIXED to every session id it mints, and the proxy
+     * routes on that prefix.
+     *
+     * This is not decoration, it is the only thing that makes sticky routing possible. Hashing the
+     * session id — the obvious reading of "sticky by mcp-session-id" — cannot work: the replica is
+     * chosen when the connection OPENS, and at that moment no session id exists yet, so the hash of
+     * the id minted afterwards lands wherever it lands. Measured on a two-replica nginx stand, that
+     * arrangement sent 45 of 60 follow-up requests to a replica that had never heard of the session.
+     * Carrying the replica in the id turns the routing decision into a lookup instead of a guess.
+     */
+    replicaId?: string;
+}
+export interface RemoteServer {
+    httpServer: Server;
+    sessionCount(): number;
+    /** Test seam: the live per-session HTTP clients, to assert they are distinct instances. */
+    debugClients(): HttpClient[];
+    close(): Promise<void>;
+}
+/**
+ * Ceiling on the burst, expressed FLEET-WIDE because the bucket it spends is fleet-wide.
+ *
+ * The burst below is sized off `maxSessions`, which is per replica — and the bucket it lands in is
+ * `ipRateLimit(300, 60, 'me')` keyed on the pod's egress IP, i.e. shared by every replica. So the
+ * figure that matters is `replicas × burst`, and stating the burst per replica beside a rate stated
+ * fleet-wide is how those two drift apart: at `replicas: 3` and the default cap, an unbounded burst
+ * is 300 — the entire minute's bucket, spent at exactly the moment those sessions also begin their
+ * ordinary `/me/*` calls through it. `src/__tests__/drift/mcp-remote-deployment.test.ts` derives
+ * `replicas × min(MCP_MAX_SESSIONS, RESOLVE_BURST_CEILING)` — the EFFECTIVE burst, not this
+ * constant alone — against the backend's own literal, so SCALING THE FLEET reddens it instead of
+ * surfacing as 429s in production. Raising THIS constant is caught elsewhere and deliberately so:
+ * while the manifest cap sits at or below the ceiling, the effective burst does not move, and the
+ * unit case in `mcp/__tests__/remote.test.ts` that runs a cap ABOVE the ceiling is what holds it.
+ */
+export declare const RESOLVE_BURST_CEILING = 100;
+/**
+ * A token bucket over the self-inspection above. Process-local on purpose: what it protects is this
+ * process's own outbound channel, and a shared counter would need a store this service does not
+ * have and must not grow for a defensive bound.
+ *
+ * Exported for its own test. The arithmetic below has a failure mode no HTTP-level case can reach
+ * cheaply — a clock that steps BACKWARDS — and the previous version's clock seam was a default
+ * parameter on an unexported function, i.e. unreachable from a test even in principle. That is the
+ * same shape `positiveIntEnv` above was fixed for once already.
+ */
+export declare function createResolveBudget(maxSessions: number, now?: () => number): {
+    /** True when a self-inspection may be sent; consumes one token. */
+    take(): boolean;
+};
+/**
+ * The replica's own index: `MCP_REPLICA_ID` if set, otherwise the ordinal a StatefulSet puts at the
+ * end of the pod hostname (`mcp-remote-1` → `1`). Falls back to `0` for a single process, which is
+ * what the stdio-style local run and the tests get.
+ */
+/**
+ * Reads a positive-integer setting, falling back to the built-in default on anything else.
+ *
+ * A typo must not disable the bound it configures. `Number('abc')` is NaN, and both
+ * `size >= NaN` and `lastSeen < NaN` are false — so an unparseable value would fail OPEN on exactly
+ * the two limits this server relies on, with the pod still passing every probe. INTEGER rather than
+ * merely finite-and-positive, because `MCP_SESSION_TTL_MS=0.5` would sweep every session on the
+ * first tick and `MCP_MAX_SESSIONS=0.5` would silently mean one.
+ *
+ * Exported and at module scope so it can be tested — the previous version was a closure inside the
+ * entrypoint guard, unreachable from a test even in principle, which left the fix one edit wide.
+ */
+export declare function positiveIntEnv(name: string, env?: NodeJS.ProcessEnv): number | undefined;
+export declare function resolveReplicaId(explicit?: string, hostname?: string): string;
+export declare function createRemoteServer(options: RemoteServerOptions): RemoteServer;
+//# sourceMappingURL=remote.d.ts.map

package/dist/remote.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote.d.ts","sourceRoot":"","sources":["../src/remote.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,EAAsC,KAAK,MAAM,EAAuB,MAAM,WAAW,CAAC;AAiBjG,OAAO,EAAY,UAAU,EAAE,MAAM,WAAW,CAAC;AAEjD,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,wGAAwG;IACxG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;;;;OAUG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,IAAI,MAAM,CAAC;IACvB,2FAA2F;IAC3F,YAAY,IAAI,UAAU,EAAE,CAAC;IAC7B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AA2RD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAkBzC;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,MAAgC;IAMhG,mEAAmE;YAC3D,OAAO;EAclB;AAoGD;;;;GAIG;AACH;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,GAAG,SAAS,CAarG;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAsB,GAAG,MAAM,CAI5F;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CAwT7E"}