@ractive-ch/tab-mcp 0.0.0-stage → 0.1.0-alpha.0

package/oauth/cimd.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Client ID Metadata Documents (CIMD, draft-ietf-oauth-client-id-metadata-document;
+ * MCP 2026-07-28 client registration): the `client_id` is an HTTPS URL, and
+ * the relay fetches it to learn the client's name and redirect URIs.
+ *
+ * The URL is chosen by an unauthenticated party, so the fetch is guarded
+ * 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
+ * host rate-limited.
+ */
+import type { Logger } from "../log.js";
+/** What the relay needs to know about a client. */
+export interface ClientMetadata {
+    /** The client id: the document's URL. */
+    clientId: string;
+    /** Self-declared, cleaned and shortened for display. */
+    name: string;
+    /** Host of the client id URL: the verified part. */
+    host: string;
+    redirectUris: string[];
+}
+/** Why a client id was refused; `message` is plain English for the page. */
+export declare class ClientMetadataError extends Error {
+    name: string;
+    readonly reason: string;
+    constructor(reason: string, message: string);
+}
+/**
+ * Test-only relaxations (never from configuration): loopback hosts, any port,
+ * `http:`, and an extra CA for a self-signed test server.
+ */
+export interface CimdTestMode {
+    ca?: string;
+}
+export interface ClientMetadataFetcherOptions {
+    /** Accepted client id hosts; empty = any. */
+    allowedHosts?: readonly string[];
+    logger?: Logger;
+    timeoutMs?: number;
+    maxBytes?: number;
+    /** Resolve a host name to its addresses (tests replace it). */
+    lookup?: (hostname: string) => Promise<string[]>;
+    fetch?: typeof fetch;
+    testMode?: CimdTestMode;
+    now?: () => number;
+}
+/**
+ * Clean a self-declared name for display: control and line/paragraph
+ * separators become spaces; format characters (`Cf`: zero-width, bidi,
+ * word joiner, BOM, soft hyphen, …) and other invisible characters are
+ * removed; whitespace collapses; at most 64 characters (DEC-065).
+ */
+export declare function displayName(raw: string): string;
+/** Fetches, validates and caches Client ID Metadata Documents. */
+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>;
+}
+/** Check a fetched document against the CIMD rules and what the relay supports. */
+export declare function validateDocument(doc: unknown, clientId: string, url: URL): 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);
+ * or a reverse-domain private-use scheme for native apps (RFC 8252 §7.1).
+ * Everything else (`file:`, `blob:`, `data:`, `javascript:`, plain `http:`,
+ * one-word custom schemes) is refused.
+ */
+export declare function isRedirectUri(value: string): boolean;
+/**
+ * Whether a requested redirect URI matches a registered one: exact string
+ * equality, except that for an `http:` loopback redirect the port is ignored
+ * (RFC 8252 §7.3; OAuth 2.1 §8.4.2). Host, path and query must still match.
+ */
+export declare function redirectUriMatches(requested: string, registered: string): boolean;

package/oauth/html.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Server-rendered HTML for `/authorize` (threat model A7): every value is
+ * escaped, the page has no scripts, and its headers forbid framing, inline
+ * code and foreign form targets.
+ */
+/** Escape text for HTML element content and quoted attribute values. */
+export declare function escapeHtml(text: string): string;
+/** The stylesheet at `/authorize.css` (`style-src 'self'`). */
+export declare const AUTHORIZE_CSS = ":root { color-scheme: light dark; --accent: #1d4ed8; --error: #b91c1c; }\n@media (prefers-color-scheme: dark) { :root { --accent: #93b4ff; --error: #fca5a5; } }\n* { box-sizing: border-box; }\nbody { margin: 0; font: 1rem/1.5 system-ui, -apple-system, \"Segoe UI\", sans-serif; background: Canvas; color: CanvasText; }\nmain { max-width: 34rem; margin: 3rem auto; padding: 0 1rem; }\nh1 { font-size: 1.5rem; line-height: 1.25; margin: 0 0 1rem; }\np { margin: 0 0 1rem; }\ncode, .origin { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; overflow-wrap: anywhere; }\n.help { color: GrayText; font-size: 0.9rem; }\n.error { color: var(--error); font-weight: 600; }\nlabel { display: block; font-weight: 600; margin-bottom: 0.25rem; }\ninput[type=\"text\"] { font: 1.5rem/1.2 ui-monospace, SFMono-Regular, Menlo, monospace; letter-spacing: 0.2em; width: 10ch; padding: 0.4rem 0.5rem; border: 2px solid GrayText; border-radius: 0.4rem; background: Field; color: FieldText; }\ninput[type=\"text\"]:focus-visible, button:focus-visible, a:focus-visible { outline: 3px solid var(--accent); outline-offset: 2px; }\n.actions { display: flex; gap: 0.75rem; flex-wrap: wrap; margin: 1.5rem 0 1.25rem; }\nbutton, .button { font: inherit; padding: 0.5rem 1.25rem; border-radius: 0.4rem; border: 2px solid var(--accent); cursor: pointer; text-decoration: none; display: inline-block; }\nbutton.primary, .button.primary { background: var(--accent); color: Canvas; }\nbutton.secondary, .button:not(.primary) { background: transparent; color: var(--accent); }\nfooter { margin-top: 2.5rem; font-size: 0.85rem; color: GrayText; }\n";
+/** Security headers of every `/authorize` response. */
+export declare function pageHeaders(formTargets?: readonly string[]): Headers;
+/** A complete page; `body` must already be escaped. */
+export declare function renderPage(title: string, body: string): string;

package/oauth/pairing.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Pairing (DEC-028, DEC-042): the step at `/authorize` that proves the browser
+ * belongs to the tab's user. The authorization server only knows the
+ * `PairingMethod` interface; which method a session uses comes from its site
+ * (DEC-045). Today's only method is the 6-digit code shown in the tab; the
+ * planned identity binding (kb/design/identity-binding.md) is the next.
+ */
+import type { PairingKind } from "../config.js";
+/** What a pairing method sees of a tab session. */
+export interface PairingTarget {
+    /** The code state of the session (used by the code method). */
+    readonly codes: PairingCodes;
+}
+export type PairingResult = {
+    ok: true;
+} | {
+    ok: false;
+    /** Plain English for the page (plain text; the page escapes it). */
+    message: string;
+    /** A short reason for the log. */
+    reason: string;
+};
+/**
+ * A way to pair a browser at `/authorize` with an address. The authorization
+ * server renders `render()` inside its form (CSRF token, buttons and the
+ * request id are its own) and passes the submitted form to `check()`.
+ */
+export interface PairingMethod {
+    readonly kind: PairingKind;
+    /** HTML of the method's step (escaped by the method). */
+    render(target: PairingTarget): string;
+    /**
+     * Check the submitted form fields. Call `admit()` right before judging an
+     * answer that could be right (a real guess); if it returns false, refuse
+     * with reason `rate_limited` without judging. Malformed input and a state
+     * that cannot succeed are answered without calling it (DEC-061).
+     */
+    check(target: PairingTarget, form: URLSearchParams, admit: () => boolean): PairingResult | Promise<PairingResult>;
+}
+/** Code lifetime and attempts (DEC-028). */
+export declare const PAIRING_CODE_TTL_MS = 120000;
+export declare const PAIRING_MAX_ATTEMPTS = 5;
+export type CodeCheck = "ok" | "limited" | "wrong" | "expired" | "locked" | "inactive" | "malformed";
+/** Six uniformly distributed digits. */
+export declare function newPairingCode(): string;
+/**
+ * The pairing codes of one tab session: on while the tab's dialog is open
+ * (`pairing.start` … `pairing.stop`); a fresh code after expiry, after use and
+ * after too many wrong attempts. Codes are never logged.
+ */
+export declare class PairingCodes {
+    #private;
+    constructor(send: (code: string, expiresAt: number) => void, options?: {
+        ttlMs?: number;
+        maxAttempts?: number;
+    });
+    /** Whether the tab is showing codes. */
+    get active(): boolean;
+    /** Attempts left for the current code. */
+    get attemptsLeft(): number;
+    start(): void;
+    stop(): void;
+    /**
+     * Check a typed code; a correct one is used up and replaced. `admit` is
+     * asked only for a well-formed code while a code is active.
+     */
+    check(input: string, now?: number, admit?: () => boolean): CodeCheck;
+}
+/** The 6-digit code typed at `/authorize` (DEC-028). */
+export declare const codePairing: PairingMethod;
+/** The methods by kind. `oidc` joins with identity binding (DEC-042). */
+export declare const PAIRING_METHODS: Partial<Record<PairingKind, PairingMethod>>;

package/oauth/server.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The relay's OAuth 2.1 authorization server (DEC-006, DEC-015, DEC-031),
+ * written without an OAuth library:
+ *
+ * - RFC 9728 protected-resource metadata per address, RFC 8414 server metadata;
+ * - clients only through Client ID Metadata Documents (`cimd.ts`);
+ * - `/authorize` with PKCE S256 only, exact redirect URIs (loopback port
+ *   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);
+ * - `/revoke` (RFC 7009).
+ */
+import type { PairingKind, RelayConfig, Site } from "../config.js";
+import type { Logger } from "../log.js";
+import type { GrantInfo } from "../protocol.js";
+import type { TokenStore } from "../store/types.js";
+import { type CimdTestMode } from "./cimd.js";
+import { type PairingMethod, type PairingTarget } from "./pairing.js";
+/** The only scope: calling the page's tools. */
+export declare const SCOPE = "tools";
+/** A tab session as the authorization server sees it. */
+export interface AuthorizeSession extends PairingTarget {
+    readonly origin: string;
+    readonly appName: string | undefined;
+    readonly site: Site;
+}
+export interface AuthorizationHost {
+    readonly config: RelayConfig;
+    readonly logger: Logger;
+    readonly store: TokenStore;
+    publicUrl(): string;
+    /** The connected (ready) tab session of an address. */
+    session(addressId: string): AuthorizeSession | undefined;
+    /** Tell the address's tab, if connected. */
+    grantAdded(addressId: string, grant: GrantInfo): void;
+    grantRemoved(addressId: string, grantId: string, reason: string): void;
+}
+/** Test-only settings; never reachable from configuration. */
+export interface AuthorizationTestMode {
+    cimd?: CimdTestMode;
+    authCodeTtlMs?: number;
+    /** Replace the pairing methods (a stub method proves the server needs no codes). */
+    pairingMethods?: Partial<Record<PairingKind, PairingMethod>>;
+}
+/** BASE64URL(SHA256(verifier)) (RFC 7636 §4.6). */
+export declare function s256(verifier: string): string;
+/** The OAuth endpoints and pages, mounted by the relay. */
+export declare class AuthorizationServer {
+    #private;
+    constructor(host: AuthorizationHost, testMode?: AuthorizationTestMode);
+    /** CORS preflight for the metadata, token and revoke endpoints. */
+    preflight(methods: string): Response;
+    /** `/.well-known/oauth-protected-resource/a/{id}/mcp`. */
+    protectedResource(addressId: string): Response;
+    /** `/.well-known/oauth-authorization-server`. */
+    metadata(): Response;
+    stylesheet(): Response;
+    /** GET `/authorize`: check the request, then show the pairing page. */
+    authorize(req: Request, ip: string): Promise<Response>;
+    /** POST `/authorize`: the pairing form (connect, cancel, try again). */
+    authorizeSubmit(req: Request, ip: string): Promise<Response>;
+    /** POST `/token`. */
+    token(req: Request, ip: string): Promise<Response>;
+    /** POST `/revoke` (RFC 7009). */
+    revoke(req: Request, ip: string): Promise<Response>;
+    /** Drop expired state; the relay calls it periodically. */
+    sweep(): void;
+}

package/package.json

@@ -1,6 +1,42 @@
 {
-  "name": "@ractive-ch/tab-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@ractive-ch/tab-mcp",
+	"version": "0.1.0-alpha.0",
+	"description": "Relay that lets AI agents call the MCP tools of a web page open in a browser tab",
+	"type": "module",
+	"bin": {
+		"tab-mcp": "./main.js"
+	},
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"default": "./index.js"
+		},
+		"./testing": {
+			"types": "./testing.d.ts",
+			"default": "./testing.js"
+		}
+	},
+	"types": "./index.d.ts",
+	"engines": {
+		"bun": ">=1.4.3"
+	},
+	"license": "MIT",
+	"author": "Jean-Pierre Bergamin <james@ractive.ch>",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/ractive/tab-mcp.git",
+		"directory": "packages/tab-mcp"
+	},
+	"homepage": "https://github.com/ractive/tab-mcp/tree/main/packages/tab-mcp#readme",
+	"bugs": "https://github.com/ractive/tab-mcp/issues",
+	"keywords": [
+		"mcp",
+		"model-context-protocol",
+		"relay",
+		"browser",
+		"websocket"
+	],
+	"publishConfig": {
+		"access": "public"
+	}
+}

package/protocol.d.ts

@@ -0,0 +1,185 @@
+/**
+ * The tab↔relay protocol, version 1 (`tab-mcp.v1`).
+ *
+ * One WebSocket per tab session; text frames with one JSON object each. The
+ * normative description is `kb/design/protocol.md` (later `docs/protocol.md`).
+ */
+export declare const SUBPROTOCOL = "tab-mcp.v1";
+/** The only MCP revision the relay serves (DEC-033). */
+export declare const MCP_PROTOCOL_VERSION = "2026-07-28";
+/** `_meta` key that carries the protocol version in every 2026-07-28 request. */
+export declare const PROTOCOL_VERSION_META_KEY = "io.modelcontextprotocol/protocolVersion";
+export declare const CloseCode: {
+    readonly normal: 1000;
+    readonly policyViolation: 1008;
+    readonly tooLarge: 1009;
+    readonly sessionExpired: 4001;
+    readonly idleTimeout: 4002;
+    readonly heartbeatLost: 4003;
+    readonly shuttingDown: 4004;
+    readonly replaced: 4005;
+    readonly rateLimited: 4008;
+};
+export type ByeReason = "replaced" | "expired" | "idle" | "shutdown" | "user";
+export interface Limits {
+    maxMessageBytes: number;
+    maxBodyBytes: number;
+    requestTimeoutMs: number;
+    idleTimeoutMs: number;
+    heartbeatMs: number;
+    keepAliveMs: number;
+    maxConcurrentRequests: number;
+}
+/** Who is calling, as the tab sees it (passed to the MCP handler as `authInfo`). */
+export interface GrantRef {
+    grantId: string;
+    clientId: string;
+    scopes: string[];
+}
+/** A connected AI app as listed to the tab. */
+export interface GrantInfo {
+    grantId: string;
+    client: {
+        id: string;
+        name: string;
+        host: string;
+    };
+    createdAt: string;
+}
+export interface SessionMessage {
+    type: "session";
+    sessionId: string;
+    address: string;
+    origin: string;
+    /** The name `/authorize` shows: the site's configured name, else the page's. */
+    appName?: string;
+    expiresAt: string;
+    limits: Limits;
+    grants: GrantInfo[];
+}
+export interface PingMessage {
+    type: "ping";
+    t: number;
+}
+export interface ByeMessage {
+    type: "bye";
+    reason: string;
+}
+export interface HttpRequestMessage {
+    type: "http.request";
+    id: string;
+    method: string;
+    path: string;
+    headers: Record<string, string>;
+    body: string;
+    grant: GrantRef;
+}
+export interface HttpCancelMessage {
+    type: "http.cancel";
+    id: string;
+    reason: "client_closed" | "timeout" | "error";
+}
+export interface PairingCodeMessage {
+    type: "pairing.code";
+    code: string;
+    expiresAt: string;
+}
+export interface GrantAddedMessage {
+    type: "grant.added";
+    grant: GrantInfo;
+}
+export interface GrantRemovedMessage {
+    type: "grant.removed";
+    grantId: string;
+    reason: "revoked" | "reuse_detected" | "expired";
+}
+export interface ErrorMessage {
+    type: "error";
+    code: ErrorCode;
+    message: string;
+    id?: string;
+}
+export type RelayMessage = SessionMessage | PingMessage | ByeMessage | HttpRequestMessage | HttpCancelMessage | PairingCodeMessage | GrantAddedMessage | GrantRemovedMessage | ErrorMessage;
+export type ErrorCode = "bad_message" | "unknown_type" | "unknown_id" | "too_large" | "rate_limited";
+export interface HelloMessage {
+    type: "hello";
+    library: {
+        name: string;
+        version: string;
+    };
+    page: {
+        title: string;
+    };
+    /** Self-declared app name (DEC-045), unverified. */
+    app?: {
+        name: string;
+    };
+    secret: string;
+}
+export interface PongMessage {
+    type: "pong";
+    t: number;
+}
+export interface HttpResponseMessage {
+    type: "http.response";
+    id: string;
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+}
+export interface HttpResponseStartMessage {
+    type: "http.response.start";
+    id: string;
+    status: number;
+    headers: Record<string, string>;
+}
+export interface HttpResponseChunkMessage {
+    type: "http.response.chunk";
+    id: string;
+    data: string;
+}
+export interface HttpResponseEndMessage {
+    type: "http.response.end";
+    id: string;
+}
+export interface TabErrorMessage {
+    type: "error";
+    code: string;
+    message: string;
+    id?: string;
+}
+export interface PairingStartMessage {
+    type: "pairing.start";
+}
+export interface PairingStopMessage {
+    type: "pairing.stop";
+}
+export interface GrantRevokeMessage {
+    type: "grant.revoke";
+    grantId: string;
+}
+export interface GrantsRevokeAllMessage {
+    type: "grants.revokeAll";
+}
+export type TabMessage = HelloMessage | PairingStartMessage | PairingStopMessage | GrantRevokeMessage | GrantsRevokeAllMessage | PongMessage | ByeMessage | HttpResponseMessage | HttpResponseStartMessage | HttpResponseChunkMessage | HttpResponseEndMessage | TabErrorMessage;
+/** Result of parsing one frame from the tab. */
+export type ParseResult = {
+    ok: true;
+    message: TabMessage;
+}
+/** A well-formed message of a type this relay does not know. */
+ | {
+    ok: true;
+    unknown: true;
+    type: string;
+    id?: string;
+} | {
+    ok: false;
+    error: string;
+    id?: string;
+};
+/**
+ * Parse and validate one text frame from the tab. Hand-written on purpose: the
+ * relay has no schema library (DEC-014).
+ */
+export declare function parseTabMessage(text: string): ParseResult;

package/ratelimit.d.ts

@@ -0,0 +1,21 @@
+/**
+ * In-memory token buckets keyed by IP, address or host (threat model A8).
+ * Bounded: when full, the least recently created bucket is dropped, which at
+ * worst gives that key a fresh, full bucket.
+ */
+export interface RateLimitOptions {
+    /** Burst size: how many requests a fresh key may make at once. */
+    capacity: number;
+    /** Tokens added per second. */
+    refillPerSecond: number;
+    /** Most keys kept in memory. */
+    maxKeys?: number;
+}
+export declare class RateLimiter {
+    #private;
+    constructor(options: RateLimitOptions);
+    /** Take one token for `key`; false when the bucket is empty. */
+    take(key: string, now?: number): boolean;
+    /** Drop buckets that are full again (nothing to remember). */
+    sweep(now?: number): void;
+}

package/relay.d.ts

@@ -0,0 +1,42 @@
+import { type RelayConfig, type StoreKind } from "./config.js";
+import { type Logger } from "./log.js";
+import { type AuthorizationTestMode } from "./oauth/server.js";
+import type { TokenStore } from "./store/types.js";
+export declare const VERSION: string;
+export interface CreateRelayOptions extends Omit<Partial<RelayConfig>, "store"> {
+    /**
+     * The token store: a `TokenStore` instance (e.g. Prisma, Redis), or the name
+     * of a built-in one (`"sqlite"`, the default, at `sqlitePath`; `"memory"`).
+     */
+    store?: StoreKind | TokenStore;
+    /** Logger; defaults to JSON lines on stdout at `logLevel`. */
+    logger?: Logger;
+}
+export interface Relay {
+    /** The external origin (issuer and address base). */
+    readonly url: string;
+    /** The port the server listens on. */
+    readonly port: number;
+    readonly config: RelayConfig;
+    /** The MCP address a page with this secret gets. */
+    addressFor(secret: string): string;
+    /** Number of connected tab sessions. */
+    readonly sessionCount: number;
+    /** Close all sessions (bye `shutdown`, close 4004) and stop the server. */
+    stop(): Promise<void>;
+}
+/**
+ * Test-only relaxations, never reachable from configuration or the package's
+ * public API (`createTestRelay` is not exported from the package): CIMD
+ * fetches from loopback test servers, shorter code lifetimes.
+ */
+export interface RelayTestHooks extends AuthorizationTestMode {
+    pairingCodeTtlMs?: number;
+}
+/** Start a relay. Returns once the server listens. */
+export declare function createRelay(options?: CreateRelayOptions): Relay;
+/**
+ * A relay with test hooks. Only for this repository's tests: it refuses to
+ * start outside development and logs a warning.
+ */
+export declare function createTestRelay(options: CreateRelayOptions, hooks: RelayTestHooks): Relay;

package/session.d.ts

@@ -0,0 +1,74 @@
+import type { RelayConfig, Site, SiteLimits } from "./config.js";
+import { Exchange, type RpcId } from "./exchange.js";
+import type { Logger } from "./log.js";
+import { PairingCodes } from "./oauth/pairing.js";
+import { type ByeReason, type GrantRef, type Limits, type RelayMessage } from "./protocol.js";
+import type { TokenStore } from "./store/types.js";
+/** The part of Bun's `ServerWebSocket` a session uses (a fake in unit tests). */
+export interface SocketLike {
+    /** Bytes sent, -1 when queued under backpressure, 0 when dropped. */
+    send(data: string): number;
+    close(code?: number, reason?: string): void;
+}
+/** What a session needs from its relay. */
+export interface SessionHost {
+    readonly config: RelayConfig;
+    readonly logger: Logger;
+    readonly store: TokenStore;
+    /** The external origin, e.g. `https://relay.ractive.ch`. */
+    publicUrl(): string;
+    /** Register a session for its address; returns the session it replaced. */
+    claimAddress(session: TabSession): TabSession | undefined;
+    /** Called once when a session is over. */
+    released(session: TabSession): void;
+    /** The tab pressed Disconnect for one app; false if the grant is not this address's. */
+    revokeGrant(session: TabSession, grantId: string): Promise<boolean>;
+    /** The tab revokes every grant of its address ("New address"). */
+    revokeAll(session: TabSession): Promise<void>;
+    /** Pairing code lifetime (tests shorten it). */
+    readonly pairingCodeTtlMs?: number;
+}
+export interface ForwardInput {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    rpcId: RpcId | undefined;
+    isListen: boolean;
+    grant: GrantRef;
+    extraHeaders: Record<string, string>;
+    /** Called once with the finished exchange (for the request log line). */
+    onDone: (exchange: Exchange) => void;
+}
+/** The limits announced to the tab (protocol: `session.limits`). */
+export declare function limitsOf(limits: SiteLimits | RelayConfig): Limits;
+/** One tab's WebSocket session, from open to close. */
+export declare class TabSession {
+    #private;
+    readonly sessionId: string;
+    readonly ip: string;
+    readonly origin: string;
+    /** The site this session's origin belongs to (DEC-045). */
+    readonly site: Site;
+    readonly openedAt: number;
+    /** Set once `hello` was accepted. */
+    addressId: string | undefined;
+    /** The app name `/authorize` shows: the site's name, else the page's claim. */
+    appName: string | undefined;
+    /** Pairing codes while the tab's dialog is open (DEC-028). */
+    readonly codes: PairingCodes;
+    readonly pending: Map<string, Exchange>;
+    constructor(ws: SocketLike, ip: string, origin: string, site: Site, host: SessionHost);
+    get ready(): boolean;
+    /** The limits of this session (its site's). */
+    get limits(): SiteLimits;
+    /** Send one message; false if Bun dropped it under backpressure (DEC-021). */
+    send(message: RelayMessage): boolean;
+    /** A frame arrived from the tab. */
+    handleFrame(data: string | Uint8Array): void;
+    /** Tunnel one MCP request to the tab. Resolves with the AI app's response. */
+    forward(input: ForwardInput): Exchange;
+    /** End the session: optional `bye`, then close the socket. Idempotent. */
+    end(code: number, reason: string, bye?: ByeReason): void;
+    /** The socket closed (from Bun's `close` handler). */
+    closed(code: number): void;
+}

package/store/conformance.d.ts

@@ -0,0 +1,11 @@
+import type { TokenStore } from "./types.js";
+/**
+ * The conformance suite every `TokenStore` must pass (DEC-041). Call it from a
+ * `bun test` file with a factory that returns a fresh, empty store:
+ *
+ * ```ts
+ * import { tokenStoreConformance } from "@ractive-ch/tab-mcp/testing";
+ * tokenStoreConformance("RedisTokenStore", async () => new RedisTokenStore(…));
+ * ```
+ */
+export declare function tokenStoreConformance(name: string, factory: () => TokenStore | Promise<TokenStore>): void;

package/store/memory.d.ts

@@ -0,0 +1,16 @@
+import type { GrantSummary, RevokeOptions, RevokeSelector, TokenRecord, TokenStore } from "./types.js";
+/** Usable at `now`: unexpired, and for refresh tokens not yet used. */
+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[];
+/** Tokens in process memory; everything is lost on restart. */
+export declare class MemoryTokenStore implements TokenStore {
+    #private;
+    put(record: TokenRecord): Promise<boolean>;
+    get(hash: string): Promise<TokenRecord | undefined>;
+    markUsed(hash: string, now: number): Promise<boolean>;
+    revoke(selector: RevokeSelector, options: RevokeOptions): Promise<number>;
+    listGrants(addressId: string, now: number): Promise<GrantSummary[]>;
+    deleteExpired(now: number): Promise<number>;
+    close(): Promise<void>;
+}

package/store/sqlite.d.ts

@@ -0,0 +1,17 @@
+import type { GrantSummary, RevokeOptions, RevokeSelector, TokenRecord, TokenStore } from "./types.js";
+/**
+ * Tokens in a SQLite file via `bun:sqlite` (the default store, DEC-030). Uses
+ * WAL mode so another process (or a test) can read and write the same file.
+ */
+export declare class SqliteTokenStore implements TokenStore {
+    #private;
+    /** `path` is a file path, or `:memory:`. */
+    constructor(path: string);
+    put(r: TokenRecord): Promise<boolean>;
+    get(hash: string): Promise<TokenRecord | undefined>;
+    markUsed(hash: string, now: number): Promise<boolean>;
+    revoke(selector: RevokeSelector, options: RevokeOptions): Promise<number>;
+    listGrants(addressId: string, now: number): Promise<GrantSummary[]>;
+    deleteExpired(now: number): Promise<number>;
+    close(): Promise<void>;
+}