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

package/AI_NOTICE

@@ -0,0 +1,9 @@
+AI-GENERATED CODE NOTICE
+
+This repository contains code that was generated in whole or in part by AI systems under human supervision.
+
+To the extent that any portions of this code are not subject to copyright protection under applicable law, those portions are provided without restriction. Where copyright does subsist, it is licensed under the terms below.
+
+No representation is made regarding the copyright status of any individual contribution.
+
+See LICENSE for the full license text.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jean-Pierre Bergamin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/address.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Stable addresses (DEC-027): the page keeps a random secret, the address id is
+ * `base32(sha256(secret))`. The relay stores nothing to recognise an address.
+ */
+/** RFC 4648 base32, lower case, without padding. */
+export declare function base32(bytes: Uint8Array): string;
+export declare function isWellFormedSecret(secret: string): boolean;
+export declare function isAddressId(id: string): boolean;
+/** The address id for a page secret: base32(sha256(UTF-8 secret)). */
+export declare function addressIdFromSecret(secret: string): string;
+/** A new page secret (what the browser library does; used by tests and tools). */
+export declare function newSecret(): string;
+/** Shortened address id for logs: enough to correlate, too short to use. */
+export declare function shortAddress(id: string): string;

package/config.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Relay configuration: defaults (DEC-034), validation, and reading `TAB_MCP_*`
+ * environment variables. The table lives in `kb/design/architecture.md`.
+ */
+export type TrustProxy = "none" | "x-real-ip" | "x-forwarded-for";
+export type LogLevel = "error" | "warn" | "info" | "debug";
+export type StoreKind = "sqlite" | "memory";
+/**
+ * How a browser at `/authorize` proves it belongs to the tab's user (DEC-042):
+ * the 6-digit code shown in the tab (DEC-028), or, later, identity binding.
+ */
+export type PairingKind = "code" | "oidc";
+/** The limits a site may set for its own tab sessions (DEC-045). */
+export interface SiteLimits {
+    maxMessageBytes: number;
+    maxConcurrentRequests: number;
+    requestTimeoutMs: number;
+    keepAliveMs: number;
+    idleTimeoutMs: number;
+    sessionLifetimeMs: number;
+    heartbeatMs: number;
+}
+/** One site (page origin) the relay serves, as configured (DEC-045). */
+export interface SiteConfig {
+    /** The page origin, e.g. `https://ractive.ch`. */
+    origin: string;
+    /** The app name `/authorize` shows; wins over the name the page sends. */
+    name?: string;
+    /** Pairing method; `code` (the default) is the only one so far. */
+    pairing?: PairingKind;
+    /** Overrides of the instance-wide limits for this site's sessions. */
+    limits?: Partial<SiteLimits>;
+}
+/** A site with everything filled in. */
+export interface Site {
+    /** The origin, or `*` for the open relay's default site. */
+    origin: string;
+    name?: string;
+    pairing: PairingKind;
+    limits: SiteLimits;
+}
+/**
+ * The smallest `maxMessageBytes` the relay accepts: MCP requests need room,
+ * and the browser library refuses a session that cannot frame a response
+ * chunk (below 896 bytes).
+ */
+export declare const MIN_MESSAGE_BYTES = 16384;
+/** Longest app name (configured or sent by the page). */
+export declare const MAX_APP_NAME = 64;
+export interface RelayConfig {
+    /** External origin, e.g. `https://relay.ractive.ch`. Optional only in development. */
+    publicUrl?: string;
+    port: number;
+    host: string;
+    /**
+     * Page origins allowed to open tab sessions with the instance-wide limits;
+     * `"*"` admits any (open relay). Shorthand for `sites` without overrides.
+     */
+    allowedOrigins: string[] | "*";
+    /** Sites with their own name, pairing method or limits (DEC-045). */
+    sites: SiteConfig[];
+    /** Hosts whose Client ID Metadata Documents are accepted; empty = any. */
+    clientIdHosts: string[];
+    trustProxy: TrustProxy;
+    /** CORS without credentials on the MCP endpoint (DEC-036). */
+    cors: boolean;
+    store: StoreKind;
+    sqlitePath: string;
+    maxSessions: number;
+    maxSessionsPerIp: number;
+    maxConcurrentRequests: number;
+    requestTimeoutMs: number;
+    keepAliveMs: number;
+    idleTimeoutMs: number;
+    sessionLifetimeMs: number;
+    heartbeatMs: number;
+    helloTimeoutMs: number;
+    /** Deadline for receiving an MCP request body (Bun's idle timer does not cover it). */
+    bodyTimeoutMs: number;
+    /** Limit for MCP request bodies and for messages from the tab. */
+    maxMessageBytes: number;
+    accessTokenTtlMs: number;
+    refreshTokenTtlMs: number;
+    /**
+     * Absolute end of a grant after pairing: refreshes slide by
+     * `refreshTokenTtlMs` but never beyond this (DEC-062).
+     */
+    grantLifetimeMs: number;
+    /** How often expired tokens are deleted from the store. */
+    sweepIntervalMs: number;
+    /** Per-socket WebSocket send buffer; beyond it sends are dropped (DEC-021). */
+    backpressureLimitBytes: number;
+    /** Bun's HTTP idle timeout in seconds; MCP requests switch it off per request. */
+    httpIdleTimeoutS: number;
+    logLevel: LogLevel;
+    /** Allows `http:` public URLs and a derived public URL. */
+    development: boolean;
+}
+export declare const DEFAULT_CONFIG: Readonly<RelayConfig>;
+export declare class ConfigError extends Error {
+    name: string;
+}
+/** Normalise an origin (`scheme://host[:port]`), or throw. */
+export declare function normalizeOrigin(value: string): string;
+/** Fill in defaults and validate. Throws `ConfigError` on bad values. */
+export declare function resolveConfig(input?: Partial<RelayConfig>): RelayConfig;
+/** An app name: 1-64 characters, no control characters. */
+export declare function isAppName(value: unknown): value is string;
+/** The instance-wide limits, the defaults of every site. */
+export declare function defaultLimits(config: RelayConfig): SiteLimits;
+/**
+ * The site for a page origin, or `undefined` if the relay does not serve it.
+ * Configured sites win; `allowedOrigins` origins and, on an open relay, any
+ * other origin get the instance-wide defaults.
+ */
+export declare function siteFor(config: RelayConfig, origin: string | null): Site | undefined;
+/** The largest message limit of any site (Bun's server-wide limits). */
+export declare function largestMessageBytes(config: RelayConfig): number;
+type Env = Record<string, string | undefined>;
+/** Read `TAB_MCP_*` variables (and `NODE_ENV`) into a partial config. */
+export declare function configFromEnv(env: Env): Partial<RelayConfig>;
+export {};

package/exchange.d.ts

@@ -0,0 +1,69 @@
+import type { HttpResponseMessage, HttpResponseStartMessage } from "./protocol.js";
+/**
+ * One tunnelled MCP request: the AI app's HTTP response, built from the tab's
+ * `http.response*` messages, with the request timer, SSE keep-alives (DEC-020)
+ * and the relay-started event stream (DEC-039).
+ */
+export type RpcId = string | number | null;
+/** JSON-RPC error codes the relay itself uses (outside the reserved range). */
+export declare const RelayErrorCode: {
+    readonly pageNotOpen: -31001;
+    readonly timeout: -31002;
+    readonly tabGone: -31003;
+    readonly overloaded: -31004;
+    readonly sendFailed: -31005;
+    readonly tooLarge: -31006;
+    readonly badResponse: -31007;
+    readonly storeUnavailable: -31008;
+};
+export type CancelReason = "client_closed" | "timeout" | "error";
+export interface ExchangeOptions {
+    id: string;
+    /** JSON-RPC id of the request; `undefined` for a notification. */
+    rpcId: RpcId | undefined;
+    /** `subscriptions/listen`: exempt from the request timer. */
+    isListen: boolean;
+    requestTimeoutMs: number;
+    keepAliveMs: number;
+    /**
+     * Limit for the response body the tab sends (not for listen streams), and
+     * the bound for bytes queued towards an AI app that does not read.
+     */
+    maxBodyBytes: number;
+    /** Extra headers for every response (CORS). */
+    extraHeaders: Record<string, string>;
+    /** Tell the tab to stop working on this request. */
+    cancel: (reason: CancelReason) => void;
+    /** Called once when the exchange is over. */
+    onDone: (exchange: Exchange) => void;
+}
+/** One SSE `message` event carrying `data` (split into `data:` lines). */
+export declare function sseEvent(data: string): string;
+export declare function rpcErrorBody(rpcId: RpcId | undefined, code: number, message: string, data?: unknown): string;
+export declare class Exchange {
+    #private;
+    readonly id: string;
+    readonly isListen: boolean;
+    readonly response: Promise<Response>;
+    /** HTTP status sent to the AI app (for logs); 0 while waiting. */
+    status: number;
+    /** How the exchange ended (for logs). */
+    outcome: string;
+    /** Why the tab's response was refused, for the tab's `error` message. */
+    badResponseReason: string | undefined;
+    constructor(options: ExchangeOptions);
+    get done(): boolean;
+    /** A complete response from the tab. */
+    onResponse(msg: HttpResponseMessage): void;
+    onStart(msg: HttpResponseStartMessage): void;
+    onChunk(data: string): void;
+    onEnd(): void;
+    /** The AI app went away: tell the tab, send nothing more. */
+    clientClosed(): void;
+    /**
+     * End the exchange with an error the AI app can read: an HTTP error while
+     * nothing was sent, else a JSON-RPC error event if the stream is at an
+     * event boundary.
+     */
+    fail(status: number, code: number, message: string, cancelTab: boolean): void;
+}

package/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `@ractive-ch/tab-mcp`: the relay that lets AI apps call MCP tools offered by
+ * a web page open in a browser tab.
+ */
+export { addressIdFromSecret, newSecret } from "./address.js";
+export { ConfigError, configFromEnv, DEFAULT_CONFIG, type LogLevel, type RelayConfig, resolveConfig, type StoreKind, type TrustProxy, } from "./config.js";
+export { createLogger, type LogFields, type Logger } from "./log.js";
+export { SUBPROTOCOL } from "./protocol.js";
+export { type CreateRelayOptions, createRelay, type Relay, VERSION, } from "./relay.js";
+export { MemoryTokenStore } from "./store/memory.js";
+export { SqliteTokenStore } from "./store/sqlite.js";
+export type { GrantSummary, RevokeSelector, TokenKind, TokenRecord, TokenStore, } from "./store/types.js";