mcp-google-multi 6.0.0-beta.2 → 6.0.0-beta.4

package/dist/mcp-token.d.ts

@@ -1,7 +1,7 @@
 export declare const ACCESS_TTL_DEFAULT = 600;
 export declare const STATE_TTL_DEFAULT = 600;
 export declare const CODE_TTL_DEFAULT = 60;
-export declare const REPLAY_CAP_DEFAULT = 10000;
+export declare const REPLAY_CAP_DEFAULT = 100000;
 /** Derive the HS256 secret (32 bytes) from the provisioned MCP_JWT_KEY string. */
 export declare function jwtSecretFrom(jwtKey: string): Uint8Array;
 export interface AccessTokenParams {
@@ -9,6 +9,7 @@ export interface AccessTokenParams {
     secret: Uint8Array;
     ttlSec?: number;
     iat: number;
+    sub: string;
 }
 export declare function signAccessToken(p: AccessTokenParams): Promise<string>;
 export interface AccessClaims {
@@ -19,63 +20,169 @@ export interface AccessClaims {
 /** Verify an access token for `/mcp`. Throws on bad sig / aud / iss / exp. */
 export declare function verifyAccessToken(token: string, base: string, secret: Uint8Array): Promise<AccessClaims>;
 export interface StatePayload {
-    flow: 'owner_gate' | 'alias_reauth';
+    flow: 'owner_gate' | 'alias_reauth' | 'alias_add';
     client_id: string;
     redirect_uri: string;
     code_challenge: string;
     client_state?: string;
     resource: string;
     alias?: string;
+    /** alias_add only: the tenant the new alias binds under. Signed server-side
+     * at mint time — never caller-supplied at /authorize or /callback. */
+    tenantId?: string;
+    /** alias_add only: scope bundles chosen when the link was minted. */
+    bundles?: string[];
+    /** alias_add only: an opaque value the minting caller chose, signed like
+     * tenantId and handed back to its binder (e.g. a server-side link record). */
+    nonce?: string;
+    /** owner_gate only: base64url sha256 of the browser-binding cookie the
+     * Google redirect set; /callback refuses a browser that lacks it. */
+    bind?: string;
 }
 export interface CodePayload {
     redirect_uri: string;
     code_challenge: string;
     resource: string;
-    sub: 'owner';
+    sub: string;
 }
 export declare function signState(payload: StatePayload, base: string, secret: Uint8Array, iat: number, ttlSec?: number): Promise<string>;
-export declare function verifyState(token: string, base: string, secret: Uint8Array): Promise<StatePayload & {
+export declare function verifyState(token: string, base: string, secret: Uint8Array, nowSec?: number): Promise<StatePayload & {
     jti: string;
+    exp: number;
 }>;
+/** A re-auth link is handed out in a tool error, so it has to survive until
+ * the user clicks it; an hour, not the 10-minute state TTL. */
+export declare const REAUTH_LINK_TTL_SEC = 3600;
+/** Query string of a server-issued alias_reauth link: the alias, an expiry and
+ * an HMAC over both. Synchronous, so the error hints that carry it stay so. */
+export declare function signReauthLink(base: string, secret: Uint8Array, alias: string, nowSec: number): string;
+/** The alias a link was issued for, or null when it is missing, forged or expired. */
+export declare function verifyReauthLink(base: string, secret: Uint8Array, params: {
+    alias: string;
+    exp: string;
+    sig: string;
+}, nowSec: number): string | null;
 /** A pending-authorization artifact for the DCR consent interstitial (same
  * shape as `state`, distinct purpose so the two can't be confused). */
 export declare function signPending(payload: StatePayload, base: string, secret: Uint8Array, iat: number, ttlSec?: number): Promise<string>;
-export declare function verifyPending(token: string, base: string, secret: Uint8Array): Promise<StatePayload & {
+export declare function verifyPending(token: string, base: string, secret: Uint8Array, nowSec?: number): Promise<StatePayload & {
     jti: string;
+    exp: number;
 }>;
 export declare function signAuthzCode(payload: CodePayload, base: string, secret: Uint8Array, iat: number, ttlSec?: number): Promise<string>;
-export declare function verifyAuthzCode(token: string, base: string, secret: Uint8Array): Promise<CodePayload & {
+export declare function verifyAuthzCode(token: string, base: string, secret: Uint8Array, nowSec?: number): Promise<CodePayload & {
     jti: string;
+    exp: number;
 }>;
+/** `full`: there is no room without forgetting a jti that is still live. */
+export type ReplaySpend = 'ok' | 'replay' | 'full';
 export declare class ReplayGuard {
     private readonly cap;
     private readonly seen;
+    private earliest;
+    private sweptAt;
     constructor(cap?: number);
-    /** Record a jti as spent. Returns false if it was already spent (replay). */
+    /** Hold a slot for an artifact about to be handed out, so its spend can
+     * never meet a full guard. The flood then lands where the artifact is
+     * minted, and refusing there loses nothing. */
+    reserve(jti: string, ttlMs: number, nowMs: number): 'ok' | 'full';
+    /** Record a jti as spent. A full guard refuses instead of evicting a live
+     * jti: a flood of spends would otherwise make a spent artifact usable again,
+     * such as a callback the browser binding refused. `artifactExpMs`
+     * keeps the record alive as long as the artifact itself, even when the clock
+     * stepped back between its signing and this spend. */
+    spend(jti: string, ttlMs: number, nowMs: number, artifactExpMs?: number): ReplaySpend;
+    /** Undo a spend whose next step could not go ahead. The slot stays held, so
+     * nothing is forgotten, and the artifact can be spent once more. */
+    unspend(jti: string): void;
+    /** `spend` as a boolean: false for a replay and for a full guard alike. */
     consume(jti: string, ttlMs: number, nowMs: number): boolean;
     get size(): number;
-    private evictExpired;
+    private record;
+    private room;
 }
+/** An earlier release's record, keyed by its live token. */
 export interface RefreshRecord {
-    sub: 'owner';
+    sub: string;
     issuedAt: number;
     family: string;
 }
 /**
- * Persisted (encrypted under MASTER_KEY) opaque refresh-token store. Rotates on
- * every use (a stolen token is usable at most once), and detects REUSE of a
- * rotated-away token as theft: the whole token family is revoked (#7 / C14).
- * All read-modify-write goes through a file lock so concurrent stdio+HTTP
- * processes can't lost-update or double-spend (#12).
+ * The family tag of a refresh token this `masterKey`'s store minted, or null
+ * for anything else. Derives the key once; the returned function does no I/O,
+ * so a host can key a pre-auth rate limit on it.
+ */
+export declare function refreshFamilyTagger(masterKey: string): (token: string) => string | null;
+/** Boot check for a refresh store file: returns when it is absent or this
+ * release can read it; throws when it does not decrypt under `masterKey`
+ * (E_REFRESH_STORE_UNREADABLE) or a newer release wrote it
+ * (E_REFRESH_STORE_FORMAT). */
+export declare function assertRefreshStoreReadable(file: string, masterKey: string): void;
+export interface RefreshStoreOptions {
+    /** Absolute family lifetime in seconds, counted from the sign-in. Unset: unlimited. */
+    maxAgeSec?: number;
+    /** Idle lifetime in seconds, counted from the last issue or rotation. Unset: unlimited. */
+    idleSec?: number;
+    /** Max live refresh-token families per subject (both formats). Unset:
+     * unlimited (default; the single-owner server passes none). When issuing a
+     * new family would put a subject over this, that subject's own
+     * least-recently-used family is dropped (by its last issue or rotation
+     * time) until it fits; a dropped family behaves exactly like a revoked
+     * one. Only the subject signing in ever triggers it, and only its own
+     * families are ever touched. */
+    maxFamiliesPerSub?: number;
+    /** Server-side log for a revoked, dropped or expired family. Never given a token or a subject. */
+    log?: (line: string) => void;
+}
+/**
+ * Persisted (encrypted under MASTER_KEY) refresh-token store. Rotates on every
+ * use, and a token carries its family and generation under a MAC, so
+ * presenting any generation the family has rotated past is REUSE: the family
+ * is revoked for the rest of its life. The store keeps one
+ * record per family, whatever its rotation count. Every read-modify-write goes
+ * through a file lock so concurrent stdio+HTTP processes can't lost-update or
+ * double-spend. See docs/internals.md.
  */
 export declare class RefreshStore {
     private readonly path;
     private readonly masterKey;
-    constructor(path: string, masterKey: string);
+    private readonly log;
+    private readonly maxAgeMs;
+    private readonly idleMs;
+    private readonly maxFamiliesPerSub;
+    private macKey;
+    private legacyEmpty;
+    constructor(path: string, masterKey: string, options?: RefreshStoreOptions);
+    private get timed();
+    private live;
+    /** Drop expired sessions in both formats; the count of those dropped. */
+    private prune;
+    /** A session written while the clock ran ahead would otherwise outlive its
+     * limit by the size of the jump. */
+    private clamp;
+    private key;
+    /** With `nowMs` (every issue and rotation), also clamps and prunes. */
     private load;
     private save;
-    issue(nowMs: number, family?: string): string;
-    /** Rotate a presented refresh token; null if unknown OR if the presented
-     * token was already rotated away (reuse => the family is revoked). */
-    rotate(oldToken: string, nowMs: number): string | null;
+    private emit;
+    private enforceFamilyCap;
+    private newFamilyId;
+    issue(nowMs: number, sub: string): string;
+    /** Rotate a presented refresh token; null if it is unknown, malformed, or
+     * rotated away (reuse => the family is revoked). The record's sub is copied
+     * forward and returned so the caller can mint the matching access token
+     * without trusting anything client-supplied.
+     *
+     * `accept` (optional) is called inside the store lock, before any mutation,
+     * with the record's sub. false: every session of that sub is dropped and
+     * null returned. A throw: nothing is written and the error propagates, so
+     * the presented token stays valid. Absent: unchanged. */
+    rotate(oldToken: string, nowMs: number, accept?: (sub: string) => boolean): {
+        token: string;
+        sub: string;
+    } | null;
+    /** Drop every session minted under `sub`, in both formats (linear scan under
+     * the store lock); the save then drops the earlier-release spent entries of
+     * the families that died with them. Returns the number of sessions dropped. */
+    purgeTenant(sub: string): number;
 }