@try-works/dsh-model-as-tool 0.1.3 → 0.4.0

package/lib/mcp/oauth.d.ts

@@ -0,0 +1,149 @@
+/**
+ * The embedded LOCAL OAuth 2.1 authorization server + resource-server verifier
+ * (P26-15).
+ *
+ * P26-15 permits exactly two implementations: a tested authorization-server
+ * integration, or a properly implemented embedded/local server — and forbids
+ * inventing token cryptography. This module is the second: the signing and
+ * verification primitives are Node's OWN WebCrypto (`crypto.subtle` HMAC-SHA256),
+ * and only the JWT envelope around them is assembled here. No cipher, mode or
+ * hash is hand-rolled.
+ *
+ * The shape follows the parts of RFC 6749/6750/8414/9728 a resource server and a
+ * local issuer need:
+ *
+ * - HS256-signed JWTs with `iss`, `sub` (client id), `aud`, `scope`, `iat`, `exp`
+ *   and a unique `jti`;
+ * - RFC 6750 challenges: `WWW-Authenticate: Bearer error="invalid_token"|...`
+ *   with `scope="..."` on insufficient_scope;
+ * - per-client credentials with INDEPENDENT revocation (a revoked client's tokens
+ *   fail while every other client keeps working);
+ * - RFC 8414 authorization-server metadata and RFC 9728 protected-resource
+ *   metadata, so a client can discover issuer/audience/token endpoint.
+ *
+ * The static-token mode remains available as CUSTOM authentication and still
+ * claims nothing; this module is what a deployment turns on when it wants the
+ * OAuth profile, and `authProfile()` reports which mode is live.
+ *
+ * @module @try-works/dsh-model-as-tool/mcp/oauth
+ */
+import type { ClientCredentialStore } from './credential-store.ts';
+/** One registered client of the local authorization server. */
+export interface OAuthClient {
+    /** The client's identity, recorded in the token's `sub` and in receipts. */
+    readonly clientId: string;
+    /** The client's secret, the shared symmetric key for HS256. */
+    readonly secret: string;
+    /** The scope this client may be granted. */
+    readonly scope: readonly string[];
+}
+/** Configuration for the embedded authorization server. */
+export interface LocalOAuthServerConfig {
+    /** The issuer URI, stamped into every token's `iss`. */
+    readonly issuer: string;
+    /** The resource the tokens target, stamped into `aud`. */
+    readonly audience: string;
+    /** Token lifetime in seconds. */
+    readonly tokenLifetimeSeconds?: number;
+    /** Clock skew tolerated on verification, in seconds. */
+    readonly leewaySeconds?: number;
+    /**
+     * The durable credential store (SEC-01).
+     *
+     * When present, generated and operator-provisioned clients are PERSISTED
+     * owner-only, revocation survives restarts, and the server hydrates its
+     * registry from the store at construction. A generation that cannot be
+     * persisted registers nothing (fail-closed). Absent keeps the earlier
+     * in-memory behavior.
+     */
+    readonly store?: ClientCredentialStore;
+}
+/** A generated credential, with the secret returned exactly once. */
+export interface GeneratedClientCredential {
+    readonly clientId: string;
+    /** Crypto-random, shown once here and never re-echoed (SEC-01). */
+    readonly secret: string;
+}
+/** Why verification failed, in RFC 6750 error-code vocabulary. */
+export type OAuthTokenError = {
+    readonly code: 'invalid_request';
+    readonly description: string;
+} | {
+    readonly code: 'invalid_token';
+    readonly description: string;
+} | {
+    readonly code: 'insufficient_scope';
+    readonly description: string;
+    readonly scope: string;
+};
+/** A verified token's claims. */
+export interface VerifiedToken {
+    readonly clientId: string;
+    readonly scope: readonly string[];
+    readonly audience: string;
+    readonly jti: string;
+}
+/** The embedded local authorization server. */
+export interface LocalOAuthServer {
+    /** Register or replace a client credential. */
+    upsertClient(client: OAuthClient): void;
+    /**
+     * GENERATE a fresh client credential with a crypto-random secret (SEC-01).
+     *
+     * The secret is returned EXACTLY ONCE, in the returned object; every later surface
+     * names only the clientId. The generation is fail-closed: when the durable store is
+     * present and the credential cannot be persisted, nothing is registered and the
+     * call throws — a credential that a restart would forget must never appear usable.
+     */
+    generateClient(options: {
+        readonly clientId: string;
+        readonly scope?: readonly string[];
+    }): GeneratedClientCredential;
+    /** Revoke ONE client; its tokens fail, every other client is untouched. */
+    revokeClient(clientId: string): void;
+    /** Issue an access token for a client, or undefined for an unknown/revoked client. */
+    issueAccessToken(clientId: string, scope?: readonly string[]): Promise<string>;
+    /**
+     * Verify a presented bearer token: signature, issuer, audience, expiry and
+     * scope, against the live client registry and revocation set.
+     */
+    verify(token: string, requiredScope?: readonly string[]): Promise<{
+        readonly ok: true;
+        readonly token: VerifiedToken;
+    } | {
+        readonly ok: false;
+        readonly error: OAuthTokenError;
+    }>;
+    /** RFC 8414 authorization-server metadata. */
+    authorizationServerMetadata(): Record<string, unknown>;
+    /** RFC 9728 protected-resource metadata. */
+    protectedResourceMetadata(): Record<string, unknown>;
+}
+/**
+ * Create the embedded local authorization server.
+ *
+ * The signing key is DERIVED per client from its secret (SHA-256), so each
+ * client's tokens are signed with a key only that client's secret can produce —
+ * and revoking a client is removing its secret from the registry, which is the
+ * one-sided operation a resource server can perform without consulting the
+ * authorization server.
+ * @param config - issuer, audience and lifetimes.
+ * @returns the server.
+ */
+export declare function createLocalOAuthServer(config: LocalOAuthServerConfig): LocalOAuthServer;
+/** Build the RFC 6750 challenge header for a verification failure. */
+export declare function oauthChallenge(error: OAuthTokenError, realm?: string): string;
+/**
+ * The HTTP status RFC 6750 §3.1 assigns to each token error.
+ *
+ * All three are 401-shaped failures, but the RFC distinguishes them so a client
+ * can tell "malformed request, fix it" (400) from "credential bad, re-auth"
+ * (401) from "credential fine, grant too small" (403). Flattening every
+ * challenge to 401 was the F4 gap: a client receiving 400 for a revoked token
+ * would re-send the same request, and one receiving 401 for insufficient scope
+ * would re-authenticate pointlessly instead of asking for the scope.
+ */
+export declare function oauthErrorStatus(error: OAuthTokenError): 400 | 401 | 403;
+/** Extract the error code from a challenge, for tests and diagnostics. */
+export declare function challengeErrorCode(challenge: string): string | undefined;
+//# sourceMappingURL=oauth.d.ts.map

package/lib/mcp/oauth.d.ts.map

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

package/lib/mcp/oauth.js

@@ -0,0 +1,396 @@
+/**
+ * The embedded LOCAL OAuth 2.1 authorization server + resource-server verifier
+ * (P26-15).
+ *
+ * P26-15 permits exactly two implementations: a tested authorization-server
+ * integration, or a properly implemented embedded/local server — and forbids
+ * inventing token cryptography. This module is the second: the signing and
+ * verification primitives are Node's OWN WebCrypto (`crypto.subtle` HMAC-SHA256),
+ * and only the JWT envelope around them is assembled here. No cipher, mode or
+ * hash is hand-rolled.
+ *
+ * The shape follows the parts of RFC 6749/6750/8414/9728 a resource server and a
+ * local issuer need:
+ *
+ * - HS256-signed JWTs with `iss`, `sub` (client id), `aud`, `scope`, `iat`, `exp`
+ *   and a unique `jti`;
+ * - RFC 6750 challenges: `WWW-Authenticate: Bearer error="invalid_token"|...`
+ *   with `scope="..."` on insufficient_scope;
+ * - per-client credentials with INDEPENDENT revocation (a revoked client's tokens
+ *   fail while every other client keeps working);
+ * - RFC 8414 authorization-server metadata and RFC 9728 protected-resource
+ *   metadata, so a client can discover issuer/audience/token endpoint.
+ *
+ * The static-token mode remains available as CUSTOM authentication and still
+ * claims nothing; this module is what a deployment turns on when it wants the
+ * OAuth profile, and `authProfile()` reports which mode is live.
+ *
+ * @module @try-works/dsh-model-as-tool/mcp/oauth
+ */
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+const ENCODER = new TextEncoder();
+/** Base64url without padding, the JWT alphabet. */
+function b64url(bytes) {
+    return Buffer.from(bytes).toString('base64url');
+}
+/** Decode one base64url JWT part to its JSON value. */
+function decodePart(part) {
+    if (part === undefined || part.length === 0)
+        return undefined;
+    try {
+        const parsed = JSON.parse(Buffer.from(part, 'base64url').toString('utf8'));
+        return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Create the embedded local authorization server.
+ *
+ * The signing key is DERIVED per client from its secret (SHA-256), so each
+ * client's tokens are signed with a key only that client's secret can produce —
+ * and revoking a client is removing its secret from the registry, which is the
+ * one-sided operation a resource server can perform without consulting the
+ * authorization server.
+ * @param config - issuer, audience and lifetimes.
+ * @returns the server.
+ */
+export function createLocalOAuthServer(config) {
+    const lifetime = config.tokenLifetimeSeconds ?? 900;
+    const leeway = config.leewaySeconds ?? 30;
+    const clients = new Map();
+    const revoked = new Map(); // clientId -> secret hash, so a re-registration restores access
+    // SEC-01: hydrate the registry from the durable store, so generated credentials
+    // survive a restart. Revoked clients are ABSENT from the store (revocation deletes),
+    // so everything listed is live.
+    for (const stored of config.store?.list() ?? []) {
+        if (stored.scheme !== 'oauth-resource-server')
+            continue;
+        clients.set(stored.clientId, { clientId: stored.clientId, secret: stored.secret, scope: stored.scope });
+    }
+    // The key type is inferred: naming `CryptoKey` here collides with the DOM value
+    // of the same name in the Node type surface.
+    const keyFor = (secret) => {
+        const digest = createHash('sha256').update(secret).digest();
+        return crypto.subtle.importKey('raw', digest, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign', 'verify']);
+    };
+    /**
+     * The LIVE registry entry for one client id.
+     *
+     * When the durable store exists it is the SOLE authority: the store row is
+     * read fresh on every issue and verify, and there is NO fallback to the
+     * construction-time hydration —
+     *
+     * - a row ABSENT from the store is an unknown/revoked client, even if this
+     *   process hydrated the id earlier (delete-then-recreate invalidates old
+     *   tokens; deletion through any surface takes effect on the next call);
+     * - a row with the WRONG SCHEME (static-token where an OAuth row was
+     *   hydrated) is REJECTED as an OAuth client — scheme confusion must not
+     *   resurrect a hydrated entry;
+     * - a credential generated after this server was constructed ISSUES
+     *   immediately (the earlier design answered "unknown client" until
+     *   restart).
+     *
+     * The in-memory map serves ONLY the store-less mode.
+     */
+    const liveClient = (clientId) => {
+        if (config.store !== undefined) {
+            const stored = config.store.get(clientId);
+            if (stored === undefined)
+                return undefined;
+            if (stored.scheme !== 'oauth-resource-server')
+                return undefined;
+            return { clientId: stored.clientId, secret: stored.secret, scope: stored.scope };
+        }
+        return clients.get(clientId);
+    };
+    /** Validate scope names once, so a bad name is refused at registration. */
+    const assertScopeNames = (scope) => {
+        // Scope names are RFC 6749 scope-tokens: no whitespace. A name containing a
+        // space can never be satisfied (issue joins with ' ', verify splits), so
+        // registering one is a configuration error and is refused here rather than
+        // silently issuing credentials that can never authorize (review F-g).
+        for (const name of scope) {
+            if (!/^[A-Za-z0-9._:\/-]+$/.test(name)) {
+                throw new Error(`scope name ${JSON.stringify(name)} is not an RFC 6749 scope-token`);
+            }
+        }
+    };
+    const register = (client) => {
+        assertScopeNames(client.scope);
+        // SEC-01 FAIL-CLOSED: persist FIRST, register only when the credential is durable —
+        // a generation that a restart would forget must never appear usable.
+        if (config.store !== undefined) {
+            config.store.upsert({
+                clientId: client.clientId,
+                secret: client.secret,
+                scheme: 'oauth-resource-server',
+                scope: client.scope,
+                createdAt: new Date().toISOString(),
+            });
+        }
+        clients.set(client.clientId, client);
+        revoked.delete(client.clientId);
+    };
+    return {
+        upsertClient(client) {
+            register(client);
+        },
+        generateClient(options) {
+            if (typeof options.clientId !== 'string' || options.clientId.length === 0 || options.clientId.length > 64) {
+                throw new Error('clientId must be a non-empty string of at most 64 characters');
+            }
+            if (clients.has(options.clientId) || config.store?.get(options.clientId) !== undefined) {
+                throw new Error(`a credential for ${JSON.stringify(options.clientId)} already exists; revoke it first`);
+            }
+            // SEC-01: high entropy — 32 crypto-random bytes, base64url-encoded. The secret
+            // is generated SERVER-SIDE and returned exactly once from this function.
+            const secret = randomBytes(32).toString('base64url');
+            register({ clientId: options.clientId, secret, scope: options.scope ?? ['mcp:call'] });
+            return { clientId: options.clientId, secret };
+        },
+        revokeClient(clientId) {
+            /**
+             * Revocation is decided by the LIVE authority, never by the hydrated map:
+             * a client generated AFTER this server was constructed (a "late client")
+             * exists only in the durable store, and revoking it must delete the
+             * durable record just like any other. The revocation FINGERPRINT is the
+             * hash of the client's own SECRET — scoped to the credential, not the id —
+             * so a legitimate re-generation of the same id with a fresh secret is
+             * never blocked by an old revocation.
+             */
+            const client = liveClient(clientId);
+            if (client !== undefined) {
+                revoked.set(clientId, createHash('sha256').update(client.secret).digest('hex'));
+                // Durable revocation: the store entry is DELETED, so the credential does not
+                // resurrect on the next boot. A persistence failure surfaces to the caller;
+                // the in-memory revocation still stands for this process.
+                config.store?.delete(clientId);
+            }
+        },
+        async issueAccessToken(clientId, scope) {
+            const client = liveClient(clientId);
+            if (client === undefined)
+                return undefined;
+            // SECRET-SCOPED revocation: the fingerprint is the hash of the revoked
+            // secret itself, so re-generating the same id with a FRESH secret issues
+            // again, while a revoked secret never does.
+            const revokedHash = revoked.get(clientId);
+            if (revokedHash !== undefined && revokedHash === createHash('sha256').update(client.secret).digest('hex')) {
+                return undefined;
+            }
+            const grantedScope = scope === undefined || scope.length === 0
+                ? [...client.scope]
+                : [...new Set(scope.filter(name => client.scope.includes(name)))];
+            const now = Math.floor(Date.now() / 1000);
+            const header = b64url(ENCODER.encode(JSON.stringify({ alg: 'HS256', typ: 'JWT' })));
+            const payload = b64url(ENCODER.encode(JSON.stringify({
+                iss: config.issuer,
+                sub: client.clientId,
+                aud: config.audience,
+                scope: grantedScope.join(' '),
+                iat: now,
+                exp: now + lifetime,
+                jti: `jti_${now.toString(36)}_${Math.random().toString(36).slice(2, 10)}`,
+            })));
+            const signingInput = `${header}.${payload}`;
+            const signature = await crypto.subtle.sign('HMAC', await keyFor(client.secret), ENCODER.encode(signingInput));
+            return `${signingInput}.${b64url(new Uint8Array(signature))}`;
+        },
+        async verify(token, requiredScope) {
+            const parts = token.split('.');
+            if (parts.length !== 3) {
+                return {
+                    ok: false,
+                    error: { code: 'invalid_request', description: 'the credential is not a JWT with three parts' },
+                };
+            }
+            const header = decodePart(parts[0]);
+            const payload = decodePart(parts[1]);
+            if (header?.alg !== 'HS256' || payload === undefined) {
+                return {
+                    ok: false,
+                    error: { code: 'invalid_request', description: 'the credential is not an HS256 JWT with a JSON payload' },
+                };
+            }
+            const clientId = payload.sub;
+            if (typeof clientId !== 'string') {
+                return {
+                    ok: false,
+                    error: { code: 'invalid_request', description: 'the credential carries no subject' },
+                };
+            }
+            // The LIVE registry entry: the durable store first, so a rotated or
+            // deleted credential is judged by the CURRENT secret and scope, never by
+            // the construction-time snapshot.
+            const client = liveClient(clientId);
+            if (client === undefined) {
+                return {
+                    ok: false,
+                    error: { code: 'invalid_token', description: 'the credential is from an unknown client' },
+                };
+            }
+            // SIGNATURE FIRST: only a credential signed with the client's own key may
+            // present claims about that client, so nothing below reads an unsigned claim
+            // — including the revocation state, which a forged credential must not be
+            // able to probe (F2: the revoked check sat here before and answered an
+            // unsigned token claiming sub=X, revealing whether X is revoked).
+            const signingInput = `${parts[0]}.${parts[1]}`;
+            const signaturePart = parts[2];
+            const presented = Buffer.from(signaturePart, 'base64url');
+            const expected = new Uint8Array(await crypto.subtle.sign('HMAC', await keyFor(client.secret), ENCODER.encode(signingInput)));
+            const matches = presented.length === expected.length && timingSafeEqual(presented, expected);
+            if (!matches) {
+                return {
+                    ok: false,
+                    error: { code: 'invalid_token', description: 'the credential signature does not verify' },
+                };
+            }
+            const revokedHash = revoked.get(clientId);
+            if (revokedHash !== undefined && revokedHash === createHash('sha256').update(client.secret).digest('hex')) {
+                return {
+                    ok: false,
+                    error: { code: 'invalid_token', description: 'the credential is revoked' },
+                };
+            }
+            // SEC-01: a client deleted from the durable store by ANY surface — the local
+            // revokeClient, the host's management action, or another process — is revoked
+            // for this process too, on the very next verification. The live lookup above
+            // consults the store; this is the in-memory fallback check.
+            if (config.store !== undefined && config.store.get(clientId) === undefined) {
+                return {
+                    ok: false,
+                    error: { code: 'invalid_token', description: 'the credential is revoked' },
+                };
+            }
+            // Issuer and audience are validated AFTER the signature: only then are they
+            // facts the issuer asserted rather than text an attacker wrote.
+            if (payload.iss !== config.issuer) {
+                return {
+                    ok: false,
+                    error: { code: 'invalid_token', description: 'the credential was issued by a different authorization server' },
+                };
+            }
+            const audience = payload.aud;
+            const audiences = Array.isArray(audience) ? audience : [audience];
+            if (!audiences.includes(config.audience)) {
+                return {
+                    ok: false,
+                    error: { code: 'invalid_token', description: `the credential audience does not include ${config.audience}` },
+                };
+            }
+            const exp = payload.exp;
+            const now = Math.floor(Date.now() / 1000);
+            if (typeof exp !== 'number' || now > exp + leeway) {
+                return {
+                    ok: false,
+                    error: { code: 'invalid_token', description: 'the credential has expired' },
+                };
+            }
+            const iat = payload.iat;
+            if (typeof iat === 'number' && iat > now + leeway) {
+                return {
+                    ok: false,
+                    error: { code: 'invalid_token', description: 'the credential is not yet valid' },
+                };
+            }
+            const scope = typeof payload.scope === 'string'
+                ? payload.scope.split(' ').filter(Boolean)
+                : [];
+            /**
+             * F1 FIX (review): the presented scope is CAPPED at the client's registered
+             * grant. Issuance already caps it, but with symmetric keys a client can
+             * self-mint a token claiming ANY scope — verification is therefore the only
+             * place the per-client grant can be enforced, and it was not. A claim the
+             * registry does not admit is refused here, never trusted.
+             */
+            const overGrant = scope.filter(name => !client.scope.includes(name));
+            if (overGrant.length > 0) {
+                return {
+                    ok: false,
+                    error: {
+                        code: 'invalid_token',
+                        description: `the credential claims scope beyond this client's grant: ${overGrant.join(', ')}`,
+                    },
+                };
+            }
+            const required = requiredScope ?? [];
+            const missing = required.filter(name => !scope.includes(name));
+            if (missing.length > 0) {
+                return {
+                    ok: false,
+                    error: {
+                        code: 'insufficient_scope',
+                        description: `the credential lacks required scope: ${missing.join(', ')}`,
+                        scope: required.join(' '),
+                    },
+                };
+            }
+            return {
+                ok: true,
+                token: {
+                    clientId,
+                    scope,
+                    audience: config.audience,
+                    jti: typeof payload.jti === 'string' ? payload.jti : '',
+                },
+            };
+        },
+        authorizationServerMetadata() {
+            return {
+                issuer: config.issuer,
+                // NO token_endpoint (F3, review): issuance is programmatic-only here, so
+                // advertising an endpoint the transport never serves would be an RFC 8414
+                // lie. A client that finds this issuer knows credentials come from the
+                // operator's configuration, not from a token request.
+                response_types_supported: ['token'],
+                token_endpoint_auth_methods_supported: ['client_secret_post'],
+                grant_types_supported: ['client_credentials'],
+            };
+        },
+        protectedResourceMetadata() {
+            return {
+                resource: config.audience,
+                authorization_servers: [config.issuer],
+                bearer_methods_supported: ['header'],
+                scopes_supported: [...new Set([...clients.values()].flatMap(client => client.scope))],
+            };
+        },
+    };
+}
+/** Build the RFC 6750 challenge header for a verification failure. */
+export function oauthChallenge(error, realm = 'tool-mode') {
+    const params = [
+        `realm="${realm}"`,
+        `error="${error.code}"`,
+        `error_description="${error.description.replaceAll('"', "'")}"`,
+    ];
+    if (error.code === 'insufficient_scope')
+        params.push(`scope="${error.scope}"`);
+    return `Bearer ${params.join(', ')}`;
+}
+/**
+ * The HTTP status RFC 6750 §3.1 assigns to each token error.
+ *
+ * All three are 401-shaped failures, but the RFC distinguishes them so a client
+ * can tell "malformed request, fix it" (400) from "credential bad, re-auth"
+ * (401) from "credential fine, grant too small" (403). Flattening every
+ * challenge to 401 was the F4 gap: a client receiving 400 for a revoked token
+ * would re-send the same request, and one receiving 401 for insufficient scope
+ * would re-authenticate pointlessly instead of asking for the scope.
+ */
+export function oauthErrorStatus(error) {
+    switch (error.code) {
+        case 'invalid_request': return 400;
+        case 'insufficient_scope': return 403;
+        case 'invalid_token': return 401;
+    }
+}
+/** Extract the error code from a challenge, for tests and diagnostics. */
+export function challengeErrorCode(challenge) {
+    return /error="([^"]+)"/.exec(challenge)?.[1];
+}
+//# sourceMappingURL=oauth.js.map

package/lib/mcp/protocol.d.ts

@@ -46,8 +46,15 @@ export declare const META_KEYS: {
  * Error codes.
  *
  * The reserved range belongs to the protocol. P26-03 is explicit that custom
- * errors must not be allocated there, so this module declares only codes the
- * revision defines and refuses to mint new ones in that band.
+ * errors must not be allocated there, and the pinned revision partitions the
+ * bands: `-32768..-32000` is JSON-RPC's own predefined-error allocation,
+ * `-32020..-32099` is reserved for MCP-defined codes (allocated sequentially,
+ * and this module declares exactly those the revision defines), while
+ * `-32000..-32019` is the IMPLEMENTATION-DEFINED sub-range — the specification
+ * will never define codes there, and receivers must not assume cross-
+ * implementation semantics. `rateLimited` lives in that sub-range deliberately:
+ * it is a documented implementation allocation, never a minted code in the
+ * reserved band.
  */
 export declare const ERROR_CODES: {
     /** Standard JSON-RPC. */
@@ -60,6 +67,16 @@ export declare const ERROR_CODES: {
     readonly headerMismatch: -32020;
     readonly unsupportedClientCapability: -32021;
     readonly unsupportedProtocolVersion: -32022;
+    /**
+     * Implementation-defined (-32000..-32019, never allocated by the specification).
+     *
+     * The revision defines NO rate-limit error, so a refusal uses this documented
+     * implementation code rather than pretending the request was invalid (-32600) or
+     * minting a code in the MCP-reserved band. The HTTP 429 status carries the
+     * semantics; receivers that do not know this code still get a conformant
+     * `JSONRPCErrorResponse` envelope and a `Retry-After` header.
+     */
+    readonly rateLimited: -32001;
 };
 /** The convention for a tool that ran and returned a domain failure (P26-04). */
 export interface ToolErrorPayload {
@@ -136,21 +153,43 @@ export interface FeatureDeclaration {
  * cannot advertise a feature it does not have by accident.
  */
 export declare const ADVERTISED_FEATURES: readonly FeatureDeclaration[];
+/**
+ * What the server may advertise, given what is ACTUALLY WIRED (P26-12).
+ *
+ * The static matrix declared `subscriptions/listen` as implemented unconditionally — while
+ * the only production transport never received a registry and therefore answered `-32601`
+ * for it. An advertised feature that no client can obtain is worse than an absent one: a
+ * client plans around it and fails later.
+ *
+ * The feature is now conditional on the wiring, and the DEFAULT is `false` because that is
+ * the production reality. A caller that has genuinely composed a subscription registry says
+ * so; nothing else can make the claim true by declaring it.
+ *
+ * @param wiring - which optional surfaces are composed.
+ * @returns the advertised-feature matrix for this deployment.
+ */
+export declare function advertisedFeatures(wiring?: {
+    readonly subscriptions?: boolean;
+}): readonly FeatureDeclaration[];
 /**
  * The capabilities object this server may advertise.
  *
- * Derived from {@link ADVERTISED_FEATURES} rather than written twice, so the
- * matrix and the advertised capabilities cannot disagree.
- * @returns the capability names that are genuinely implemented.
+ * Derived from the matrix rather than written twice, so the two cannot disagree.
+ * @param wiring - which optional surfaces are composed.
+ * @returns the capability names that are genuinely implemented HERE.
  */
-export declare function implementedCapabilities(): string[];
+export declare function implementedCapabilities(wiring?: {
+    readonly subscriptions?: boolean;
+}): string[];
 /**
  * Whether a client's REQUIRED capability is one this server supports (P26-03).
  *
  * @param required - capability names the client declared as required.
  * @returns the unsupported names, empty when all are supported.
  */
-export declare function unsupportedRequiredCapabilities(required: readonly string[]): string[];
+export declare function unsupportedRequiredCapabilities(required: readonly string[], wiring?: {
+    readonly subscriptions?: boolean;
+}): string[];
 /**
  * The caching fields every cacheable result must carry (P26-14).
  *

package/lib/mcp/protocol.d.ts.map

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