@ractive-ch/tab-mcp 0.5.1 → 0.6.1

package/oauth/cimd.d.ts

@@ -7,8 +7,10 @@
  * against SSRF (threat model A3): https only, default port, no credentials,
  * the host resolved first and every address checked to be public, no
  * redirects, 5 s, 64 KiB, `application/json`, results cached and fetches per
- * domain and in total rate-limited.
+ * domain and in total rate-limited. A `private_key_jwt` client's `jwks_uri`
+ * is fetched under the same rules (DEC-106).
  */
+import { type JwtAlgorithm } from "../jwt.js";
 import type { Logger } from "../log.js";
 /** What the relay needs to know about a client. */
 export interface ClientMetadata {
@@ -19,6 +21,23 @@ export interface ClientMetadata {
     /** Host of the client id URL: the verified part. */
     host: string;
     redirectUris: string[];
+    /** How the client authenticates at `/token` (DEC-104, DEC-106). */
+    auth: ClientAuth;
+}
+/**
+ * `none`: a public client. `private_key_jwt`: it signs a client assertion
+ * with a key from `jwksUri`; `publicAllowed` when its document also lists
+ * `none` (DEC-104), so a grant may start without one (DEC-106).
+ */
+export type ClientAuth = {
+    method: "none";
+} | PrivateKeyJwtAuth;
+export interface PrivateKeyJwtAuth {
+    method: "private_key_jwt";
+    jwksUri: string;
+    /** `token_endpoint_auth_signing_alg` if the document names one, else all. */
+    algorithms: readonly JwtAlgorithm[];
+    publicAllowed: boolean;
 }
 /** Why a client id was refused; `message` is plain English for the page. */
 export declare class ClientMetadataError extends Error {
@@ -45,6 +64,14 @@ export interface ClientMetadataFetcherOptions {
     testMode?: CimdTestMode;
     now?: () => number;
 }
+/** How `validateDocument` reads a document. */
+export interface DocumentOptions {
+    /** Test mode: a `jwks_uri` may use `http:` and any port, like the client id. */
+    test?: boolean;
+    /** A `private_key_jwt` document fell back to `none` (DEC-104), and why. */
+    onFallback?: (reason: string) => void;
+}
+export declare function isTransient(error: ClientMetadataError): boolean;
 /**
  * Clean a self-declared name for display: control and line/paragraph
  * separators become spaces; format characters (`Cf`: zero-width, bidi,
@@ -64,8 +91,26 @@ export declare function limitKey(hostname: string): string;
 export declare class ClientMetadataFetcher {
     #private;
     constructor(options?: ClientMetadataFetcherOptions);
-    /** The client's metadata, from the cache or freshly fetched. Throws `ClientMetadataError`. */
-    get(clientId: string): Promise<ClientMetadata>;
+    /**
+     * The client's metadata, from the cache or freshly fetched. Throws
+     * `ClientMetadataError`. With `allowStale` (the token and revocation
+     * endpoints, DEC-106) a document up to an hour past its cache lifetime is
+     * served when the fresh fetch fails transiently or is rate-limited, so a
+     * busy or briefly unreachable host does not cut off apps that already
+     * have grants. `/authorize` always wants a current document.
+     */
+    get(clientId: string, options?: {
+        allowStale?: boolean;
+    }): Promise<ClientMetadata>;
+    /**
+     * A client's JWKS document, under the CIMD fetch's SSRF rules and rate
+     * limits (DEC-106). `validateDocument` checked `jwksUri` (https, the
+     * client id's host); this checks it again before any network use. Not
+     * cached here: `JwksCache` does that. Only a document that was fetched
+     * and accepted names a `jwksUri`, so this is charged to the budget of
+     * known clients. Throws `ClientMetadataError`.
+     */
+    fetchJwks(jwksUri: string): Promise<unknown>;
 }
 /**
  * Whether a name contains a domain-shaped token that is not the verified
@@ -74,7 +119,7 @@ export declare class ClientMetadataFetcher {
  */
 export declare function foreignDomain(name: string, hostname: string): boolean;
 /** Check a fetched document against the CIMD rules and what the relay supports. */
-export declare function validateDocument(doc: unknown, clientId: string, url: URL): ClientMetadata;
+export declare function validateDocument(doc: unknown, clientId: string, url: URL, options?: DocumentOptions): ClientMetadata;
 /**
  * A redirect URI the relay accepts (DEC-067): absolute, no fragment or
  * credentials, and `https:`; `http:` only for loopback hosts (RFC 8252 §7.3);

package/oauth/client-auth.d.ts

@@ -0,0 +1,86 @@
+/**
+ * `private_key_jwt` client authentication at `/token` and `/revoke` (RFC 7521
+ * §4.2, RFC 7523 §2.2 and §3, OpenID Connect Core §9; DEC-106). The client
+ * signs a short JWT with a key it publishes at the `jwks_uri` of its Client
+ * ID Metadata Document; the signature is checked with `jwt.ts` (asymmetric
+ * algorithms only, each tied to its key type, keys never from the header).
+ */
+import { type KeySource } from "../jwt.js";
+import { type PrivateKeyJwtAuth } from "./cimd.js";
+/** The only `client_assertion_type` (RFC 7523 §2.2). */
+export declare const CLIENT_ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer";
+/**
+ * Latest `exp` accepted: an hour ahead, the ceiling other authorization
+ * servers set (Okta) and a lifetime libraries default to; ChatGPT's own is
+ * not known, so a shorter `exp` limit could refuse it.
+ */
+export declare const CLIENT_ASSERTION_MAX_LIFETIME_MS: number;
+/**
+ * How long an assertion is usable (DEC-106): five minutes from its `iat`,
+ * or, without `iat`, `exp` at most five minutes ahead. A client signs just
+ * before it sends, so this costs no client anything, and it bounds how long
+ * a `jti` must be remembered whatever `exp` says.
+ */
+export declare const CLIENT_ASSERTION_MAX_AGE_MS: number;
+/** Clock leeway for `exp`, `iat` and `nbf`. */
+export declare const CLIENT_ASSERTION_LEEWAY_MS = 30000;
+/** Records a one-time key until `expiresAt`; `false` if already recorded. */
+export type ClaimNonce = (key: string, expiresAt: number, now: number) => Promise<boolean>;
+export interface AssertionCheck {
+    /** The client id the assertion must be for (`iss` and `sub`). */
+    clientId: string;
+    auth: PrivateKeyJwtAuth;
+    keys: KeySource;
+    /** What `aud` must contain one of: the issuer, the endpoint's URL. */
+    audiences: readonly string[];
+    claimNonce: ClaimNonce;
+    now: number;
+}
+/**
+ * The `sub` of an assertion, unverified: the client id when the request has
+ * no `client_id` (RFC 7521 §4.2). Verification then checks it like any other.
+ */
+export declare function assertionSubject(assertion: string): string | undefined;
+/** The replay store's key: the client and its `jti`, hashed. */
+export declare function nonceKey(clientId: string, jti: string): string;
+/**
+ * Check a client assertion; throws `JwtError` with a short reason for the
+ * log. The `jti` is recorded only once everything else passed, so only the
+ * holder of the client's key can add entries to the replay store.
+ */
+export declare function verifyClientAssertion(assertion: string, check: AssertionCheck): Promise<void>;
+/**
+ * The key a client's replay share is counted under (review of PR 65): its
+ * full host name, so clients under one shared suffix (`github.io`,
+ * `pages.dev`, `co.uk`) do not share one; an IPv4 literal as is, an IPv6
+ * literal by its /64, which one party usually holds whole.
+ */
+export declare function quotaKey(clientId: string): string;
+/**
+ * The replay store's live entries per AI app host on this instance
+ * (DEC-106, keyed by `quotaKey`). Anyone can be a client by publishing a
+ * document, so one host may fill only its own share, whatever the store;
+ * the total bounds memory. Expired entries are dropped at most once a
+ * second.
+ */
+export declare class NonceQuota {
+    #private;
+    constructor(perDomain: number, max: number);
+    /** Why `domain` may not add an entry now, or `undefined` if it may. */
+    refusal(domain: string, now: number): "domain_full" | "full" | undefined;
+    add(domain: string, until: number): void;
+    /** Drops expired entries; returns whether it ran (at most once a second). */
+    sweep(now: number): boolean;
+}
+/**
+ * One `JwksCache` per client `jwks_uri` (10 minutes, an unknown `kid`
+ * fetched again after 5 s, the last good keys for an hour after a failure),
+ * loaded with the SSRF-guarded fetch. At most 1000, 100 per domain; a new
+ * one pushes out the least recently used of the domain that holds the most,
+ * so one party's many documents push out their own keys (review of PR 65).
+ */
+export declare class ClientKeySets {
+    #private;
+    constructor(load: (url: string) => Promise<unknown>, now?: () => number);
+    for(jwksUri: string): KeySource;
+}

package/oauth/domain-cache.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A bounded least-recently-used map whose entries each belong to a domain
+ * (DEC-106, review of PR 65). Anyone can publish client documents, so the
+ * caches of documents and keys must not let one party push out the others':
+ *
+ * - one domain holds at most `perDomain` entries; a new one replaces that
+ *   domain's least recently used entry;
+ * - when the map is full, a new entry replaces one that `isDead` says may go
+ *   (past its use), else the least recently used entry of the domain that
+ *   holds the most.
+ *
+ * So many documents of one attacker push out their own. What is left: an
+ * attacker with as many domains as the map has room for, one entry each,
+ * ties with everyone, and least recently used goes first.
+ */
+export declare class DomainCache<V> {
+    #private;
+    constructor(max: number, perDomain: number, isDead?: (value: V, now: number) => boolean);
+    get size(): number;
+    /** The value, marked as most recently used. */
+    get(key: string): V | undefined;
+    delete(key: string): void;
+    set(key: string, domain: string, value: V, now: number): void;
+}

package/oauth/server.d.ts

@@ -8,6 +8,7 @@
  *   relaxed), `resource` bound to one address (RFC 8707), `iss` in every
  *   response (RFC 9207), and the pairing step of the address's site (DEC-042);
  * - `/token` for the authorization code and rotating refresh tokens (DEC-029);
+ * - client authentication `none` or `private_key_jwt` (DEC-106);
  * - `/revoke` (RFC 7009).
  */
 import type { PairingKind, RelayConfig, Site } from "../config.js";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ractive-ch/tab-mcp",
-	"version": "0.5.1",
+	"version": "0.6.1",
 	"description": "Relay that lets AI agents call the MCP tools of a web page open in a browser tab",
 	"type": "module",
 	"bin": {
@@ -18,7 +18,7 @@
 	},
 	"types": "./index.d.ts",
 	"engines": {
-		"bun": ">=1.4.3"
+		"bun": ">=1.4.4"
 	},
 	"license": "MIT",
 	"author": "Jean-Pierre Bergamin <james@ractive.ch>",

package/relay.d.ts

@@ -13,6 +13,12 @@ export interface CreateRelayOptions extends Omit<Partial<RelayConfig>, "store">
     /** Logger; defaults to JSON lines on stdout at `logLevel`. */
     logger?: Logger;
 }
+/**
+ * The public URL in development without `publicUrl`: the loopback address the
+ * relay listens on, so the addresses match the URL the page was given;
+ * `localhost` for any other host (`0.0.0.0`, `::`, a name).
+ */
+export declare function developmentUrl(host: string, port: number): string;
 export interface Relay {
     /** The external origin (issuer and address base). */
     readonly url: string;

package/store/memory.d.ts

@@ -3,6 +3,18 @@ import type { GrantSummary, RevokeOptions, RevokeSelector, TokenRecord, TokenSto
 export declare function isLive(record: TokenRecord, now: number): boolean;
 /** Group live records into grant summaries, oldest grant first. */
 export declare function summarizeGrants(records: Iterable<TokenRecord>, now: number): GrantSummary[];
+/**
+ * One-time values (client assertion `jti`s, DEC-106) until their expiry, in
+ * process memory: `TokenStore.claimNonce` for the memory store, and the
+ * relay's own fallback for stores without it.
+ */
+export declare class NonceSet {
+    #private;
+    get size(): number;
+    claim(key: string, expiresAt: number, now: number): boolean;
+    sweep(now: number): number;
+    clear(): void;
+}
 /** Tokens in process memory; everything is lost on restart. */
 export declare class MemoryTokenStore implements TokenStore {
     #private;
@@ -12,5 +24,6 @@ export declare class MemoryTokenStore implements TokenStore {
     revoke(selector: RevokeSelector, options: RevokeOptions): Promise<number>;
     listGrants(addressId: string, now: number): Promise<GrantSummary[]>;
     deleteExpired(now: number): Promise<number>;
+    claimNonce(key: string, expiresAt: number, now: number): Promise<boolean>;
     close(): Promise<void>;
 }

package/store/sqlite.d.ts

@@ -13,5 +13,7 @@ export declare class SqliteTokenStore implements TokenStore {
     revoke(selector: RevokeSelector, options: RevokeOptions): Promise<number>;
     listGrants(addressId: string, now: number): Promise<GrantSummary[]>;
     deleteExpired(now: number): Promise<number>;
+    /** One statement: inserted, or an expired entry replaced; a live one stays. */
+    claimNonce(key: string, expiresAt: number, now: number): Promise<boolean>;
     close(): Promise<void>;
 }

package/store/types.d.ts

@@ -45,6 +45,14 @@ export interface TokenRecord {
      * makes every request of such a grant fail as a mismatch.
      */
     subject?: string;
+    /**
+     * Client authentication binding (DEC-106): `private_key_jwt` when the
+     * grant was made or refreshed with a client assertion; its refresh tokens
+     * then need one too. Must be stored and returned unchanged: a store that
+     * drops it lets such a grant's refresh tokens be redeemed without the
+     * client's key.
+     */
+    clientAuth?: "private_key_jwt";
 }
 /** One connected AI app of an address. */
 export interface GrantSummary {
@@ -100,6 +108,15 @@ export interface TokenStore {
     listGrants(addressId: string, now: number): Promise<GrantSummary[]>;
     /** Delete every record with `expiresAt <= now` and tombstones past `keepUntil`. Returns how many records. */
     deleteExpired(now: number): Promise<number>;
+    /**
+     * Optional (DEC-106): remember a one-time value (the hash of a client
+     * assertion's client id and `jti`) until `expiresAt`. Returns `true` for
+     * the one call that recorded it, `false` while it is remembered; an entry
+     * with `expiresAt <= now` counts as absent. Must be atomic, like
+     * `markUsed`. `deleteExpired` should drop expired entries. Without it the
+     * relay remembers them in its own memory, which is per instance.
+     */
+    claimNonce?(key: string, expiresAt: number, now: number): Promise<boolean>;
     /** Release resources (database handles). Optional. */
     close?(): Promise<void>;
 }

package/testing.d.ts

@@ -1,5 +1,36 @@
 /**
- * `@ractive-ch/tab-mcp/testing`: the `TokenStore` conformance suite for
- * `bun test` (DEC-041).
+ * `@ractive-ch/tab-mcp/testing`: helpers for `bun test`. The `TokenStore`
+ * conformance suite (DEC-041), and an in-process relay with a token helper
+ * for end-to-end tests of a page's tools without pairing by hand.
  */
+import { type CreateRelayOptions, type Relay } from "./relay.js";
+import type { TokenStore } from "./store/types.js";
 export { tokenStoreConformance } from "./store/conformance.js";
+/** A relay started by `startTestRelay`. */
+export interface TestRelay {
+    relay: Relay;
+    /** The relay's token store, for `tokenFor`. */
+    store: TokenStore;
+    /** The relay's URL, for the page's `relay` option: `http://127.0.0.1:<port>`. */
+    url: string;
+    stop(): Promise<void>;
+}
+/**
+ * Start a relay in this process on a free port of 127.0.0.1, in development
+ * mode, open to every page origin, with a memory store and no log output
+ * (unless `logger` or `logLevel` is given). `options` override any of that.
+ * For tests only: it accepts any origin.
+ */
+export declare function startTestRelay(options?: Omit<CreateRelayOptions, "store"> & {
+    store?: TokenStore;
+}): TestRelay;
+/**
+ * An access token for a page's MCP address, written straight into the relay's
+ * token store, as if an AI app had paired. Use it as `Authorization: Bearer
+ * <token>` with an MCP client. It lasts an hour unless `ttlMs` says otherwise.
+ */
+export declare function tokenFor(store: TokenStore, address: string, options?: {
+    clientId?: string;
+    clientName?: string;
+    ttlMs?: number;
+}): Promise<string>;