@ractive-ch/tab-mcp 0.2.0 → 0.3.0

package/README.md

@@ -10,7 +10,7 @@ and gets an MCP address. The user adds that address to an AI app and pairs it by
 a code from the page on the relay's sign-in page. The relay then forwards the AI app's
 requests to the page. It knows nothing about the tools themselves.
 
-**Status: 0.2.0.** Until 1.0, a new minor version can still change settings and the API.
+**Status: 0.3.0.** Until 1.0, a new minor version can still change settings and the API.
 The relay speaks MCP revision 2026-07-28 only and accepts AI apps that register through
 OAuth Client ID Metadata Documents; see [compatibility](https://github.com/ractive/tab-mcp/blob/main/docs/compatibility.md)
 for which apps work.
@@ -32,7 +32,7 @@ Or with Docker (linux/amd64 and linux/arm64):
 docker run -d -p 127.0.0.1:8080:8080 -v tab-mcp-data:/data \
   -e TAB_MCP_PUBLIC_URL=https://relay.example.com \
   -e TAB_MCP_ALLOWED_ORIGINS=https://app.example.com \
-  ractive/tab-mcp:0.2.0
+  ractive/tab-mcp:0.3.0
 ```
 
 The image is also on `ghcr.io/ractive/tab-mcp`. Put the relay behind a reverse proxy
@@ -62,6 +62,7 @@ The most important:
 | `TAB_MCP_SQLITE_PATH` | `tab-mcp.db` | the SQLite file for grants and token hashes |
 | `TAB_MCP_TRUST_PROXY` | `none` | `x-real-ip` or `x-forwarded-for` behind a proxy |
 | `TAB_MCP_PORT` | `8080` | listen port |
+| `TAB_MCP_IDENTITY` | `code` | `oidc` pairs AI apps by the same sign-in at your OpenID Connect provider instead of a code (identity binding; needs the `TAB_MCP_OIDC_*` and `TAB_MCP_TAB_ASSERTION_*` settings) |
 
 `GET /healthz` answers `200` with the version, for health checks.
 

package/config.d.ts

@@ -7,9 +7,27 @@ 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.
+ * the 6-digit code shown in the tab (DEC-028), or identity binding at an
+ * OpenID Connect provider (DEC-075).
  */
 export type PairingKind = "code" | "oidc";
+/** Claims the relay may compare as the subject (DEC-079); never mutable ones. */
+export type SubjectClaim = "sub" | "oid";
+/** The OpenID Connect provider and the tab assertion signer (DEC-079). */
+export interface OidcConfig {
+    /** The provider's issuer (discovery at `/.well-known/openid-configuration`). */
+    issuer: string;
+    /** The relay's client at the provider. */
+    clientId: string;
+    /** Its secret; absent for a public client (PKCE only). */
+    clientSecret?: string;
+    /** The ID token claim compared with the tab's subject; default `sub`. */
+    subjectClaim?: SubjectClaim;
+    /** Expected `iss` of the tab assertions (the web app's backend). */
+    assertionIssuer: string;
+    /** JWKS of the web app's backend that signs tab assertions. */
+    assertionJwksUrl: string;
+}
 /** The limits a site may set for its own tab sessions (DEC-045). */
 export interface SiteLimits {
     maxMessageBytes: number;
@@ -26,7 +44,7 @@ export interface SiteConfig {
     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 method; default `identity` of the instance (`code`). */
     pairing?: PairingKind;
     /** Overrides of the instance-wide limits for this site's sessions. */
     limits?: Partial<SiteLimits>;
@@ -61,6 +79,13 @@ export interface RelayConfig {
     allowedOrigins: string[] | "*";
     /** Sites with their own name, pairing method or limits (DEC-045). */
     sites: SiteConfig[];
+    /**
+     * The pairing of sites without their own (`allowedOrigins` included):
+     * `code` (default, DEC-028) or `oidc` (identity binding, DEC-079).
+     */
+    identity: PairingKind;
+    /** The provider and assertion signer; required when a site uses `oidc`. */
+    oidc?: OidcConfig;
     /** Hosts whose Client ID Metadata Documents are accepted; empty = any. */
     clientIdHosts: string[];
     trustProxy: TrustProxy;

package/exchange.d.ts

@@ -15,6 +15,7 @@ export declare const RelayErrorCode: {
     readonly tooLarge: -31006;
     readonly badResponse: -31007;
     readonly storeUnavailable: -31008;
+    readonly signedOut: -31009;
 };
 export type CancelReason = "client_closed" | "timeout" | "error";
 /**

package/identity.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Identity binding (DEC-075 to DEC-079): the tab assertion the web app's
+ * backend signs for its user, and the key an address is bound to.
+ */
+import type { OidcConfig } from "./config.js";
+import { type KeySource } from "./jwt.js";
+/** The `typ` header of a tab assertion (explicit typing, RFC 8725 §3.11). */
+export declare const TAB_ASSERTION_TYP = "tab-mcp-identity+jwt";
+/** Longest lifetime of a tab assertion. */
+export declare const TAB_ASSERTION_MAX_LIFETIME_MS = 60000;
+/** Clock leeway for `exp`, `iat` and `nbf`. */
+export declare const CLOCK_LEEWAY_MS = 5000;
+/** The text for a person other than the page's user (DEC-077, DEC-079). */
+export declare const MISMATCH_TEXT = "This AI tool is logged in as someone other than the page.";
+/**
+ * The binding key: SHA-256 over the provider's issuer and the subject, so the
+ * subject is never stored in the clear (DEC-077).
+ */
+export declare function identityKey(issuer: string, subject: string): string;
+/** Verifies tab assertions (DEC-076) and remembers used `jti`s. */
+export declare class TabAssertionVerifier {
+    #private;
+    constructor(oidc: OidcConfig, keys?: KeySource);
+    /**
+     * Check an assertion for an MCP address; returns the binding key. Throws
+     * `JwtError` with a short reason for the log.
+     */
+    verify(token: string, address: string, now?: number): Promise<string>;
+}

package/index.d.ts

@@ -3,7 +3,8 @@
  * 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 { ConfigError, configFromEnv, DEFAULT_CONFIG, type LogLevel, type OidcConfig, type PairingKind, type RelayConfig, resolveConfig, type StoreKind, type SubjectClaim, type TrustProxy, } from "./config.js";
+export { TAB_ASSERTION_TYP } from "./identity.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";