@antasphere/chassis-server 1.0.0

package/dist/identity/hub-grant.d.ts

@@ -0,0 +1,182 @@
+import { Counter } from 'prom-client';
+import { symmetricEncrypt } from 'better-auth/crypto';
+import { type Db } from '@antasphere/chassis-db';
+import type { Logger } from '../logger.js';
+/** Headroom the lock watchdog keeps beyond probe + presentation (row reads/writes, lock latency). */
+export declare const LOCK_WATCHDOG_HEADROOM_MS = 2000;
+export interface HubGrantDials {
+    /** Serve cached/stored access tokens only while exp − now exceeds this. */
+    accessSkewMs: number;
+    /** Token-endpoint fetch timeout. */
+    tokenTimeoutMs: number;
+    /** Introspection-probe fetch timeout (the unanswered-presentation path). */
+    introspectTimeoutMs: number;
+    /** Watchdog cutting the dedicated lock connection (wedged-refresh bound). */
+    lockWatchdogMs: number;
+}
+export declare const DEFAULT_GRANT_DIALS: HubGrantDials;
+/**
+ * One answer about a user's hub access.
+ *  - 'ok': a hub-callable access token.
+ *  - 'no_link': the user holds no hub identity at all (a purely local user)
+ *    — nothing to refresh, and that IS the definitive answer.
+ *  - 'grant_dead': the stored refresh token is gone (revoked / expired /
+ *    reuse-torn-down, or never granted — e.g. a cli-connect JIT without the
+ *    Stage F grant channel). Only a browser SSO login heals this.
+ *  - 'inconclusive': transient failure; nothing was destroyed.
+ */
+export type GrantAccess = {
+    kind: 'ok';
+    accessToken: string;
+} | {
+    kind: 'no_link';
+} | {
+    kind: 'grant_dead';
+} | {
+    kind: 'inconclusive';
+};
+/** Key material for the symmetric token encryption (Better Auth's own). */
+type SecretKeyMaterial = Parameters<typeof symmetricEncrypt>[0]['key'];
+export interface HubGrantServiceOptions {
+    db: Db;
+    /** Hub OIDC issuer (HUB_ISSUER_URL) — the token endpoint derives from it. */
+    issuerUrl: string;
+    clientId: string;
+    clientSecret: string;
+    /**
+     * RFC 8707 `resource` sent on every refresh — `<hub>/mcp`, so the hub
+     * mints a JWT its own /api/v1 accepts. THE seam constant: boot passes the
+     * same value into the SSO code exchange (hub-sso.ts), and flipping it to
+     * null here (if the hub ever accepts opaque tokens) is a one-line change.
+     */
+    tokenResource: string | null;
+    /**
+     * Better Auth's token-encryption key material — `(await
+     * auth.$context).secretConfig`. Lazy because the auth context resolves
+     * async; with our config it equals the boot AUTH_SECRET.
+     */
+    key: () => Promise<SecretKeyMaterial>;
+    /** Dedicated advisory-lock connections (the migrate.ts / deletion.ts pattern). */
+    connectionString: string;
+    logger: Logger;
+    dials: HubGrantDials;
+    /** Test seams. */
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+}
+/**
+ * Mirror of Better Auth 1.6.15's `isLikelyEncrypted` (dist/oauth2/utils.mjs):
+ * its decrypt path passes LEGACY PLAINTEXT tokens through untouched, and so
+ * must ours — enabling encryption must never brick pre-existing grants.
+ * Exported for hub-logout.ts, whose id_token read mirrors the same
+ * tolerant rule. Re-verify on any Better Auth bump.
+ */
+export declare function isLikelyEncrypted(token: string): boolean;
+export declare class HubGrantService {
+    private readonly opts;
+    /** userId → fresh access token (in-memory only; the row is the durable store). */
+    private readonly cache;
+    private readonly inFlight;
+    private readonly tokenUrl;
+    private readonly introspectUrl;
+    private readonly fetchImpl;
+    private readonly now;
+    readonly dials: HubGrantDials;
+    /** Registered into the Prometheus registry by boot (cloud only). */
+    readonly promMetrics: Counter[];
+    private readonly refreshes;
+    constructor(opts: HubGrantServiceOptions);
+    /**
+     * Store the H3 offline grant — the raw one-time `hubRefreshToken` from
+     * the hub's `POST /sso/tool-token` response, delivered through
+     * `/sso/cli-connect` — on the user's `antasphere` account row, encrypted
+     * with the SAME primitive + key as every Better Auth write, so the
+     * ordinary refresh path consumes it exactly like a browser-SSO grant.
+     * This is what gives a HEADLESS CLI user live as-the-user org reads
+     * between browser logins (and replaces the Stage E interim, where a
+     * connect-minted key answered 401 hub_grant_expired until one browser
+     * SSO).
+     *
+     * Overwrites any previous grant unconditionally: the H3 mint is the
+     * NEWEST valid credential, and the replaced family simply idles to expiry
+     * at the hub. The stored access token is cleared (the new grant has none
+     * yet); the caller VALIDATES the grant end-to-end by running the
+     * fail-closed connect reconcile right after — a garbage token surfaces as
+     * `grant_dead` there and no key is minted.
+     *
+     * Throws when the user holds no `antasphere` account row — the connect
+     * flow provisions the link BEFORE acquiring the grant, so that is a
+     * wiring bug, never a user state.
+     */
+    acquireFromConnect(userId: string, rawRefreshToken: string): Promise<void>;
+    /**
+     * Whether a stored (possibly stale) grant exists — the connect route's
+     * born-dead guard for requests that carry no hubRefreshToken: with no
+     * stored grant either, minting a key would strand it on
+     * hub_grant_expired, so the connect refuses with steering instead.
+     */
+    hasStoredGrant(userId: string): Promise<boolean>;
+    /**
+     * Seed the in-memory cache with the SSO callback's access token (already
+     * hub-audienced — the code exchange sends the same `resource`), so the
+     * login-path reads and the first post-login requests need no refresh.
+     */
+    prime(userId: string, accessToken: string, expiresAt: Date | null): void;
+    /** Drop the cached access token (e.g. the hub just refused it). */
+    invalidateAccess(userId: string): void;
+    /** A hub-callable access token for the user, refresh-on-demand. */
+    accessToken(userId: string): Promise<GrantAccess>;
+    /**
+     * Force a refresh (the caller saw the hub refuse the current token).
+     * Serialized behind any in-flight acquisition; the advisory lock +
+     * re-read-after-lock still guarantee at most one live rotation.
+     */
+    refresh(userId: string): Promise<GrantAccess>;
+    private acquire;
+    private doAcquire;
+    /** The user's hub account link, tokens as stored (possibly encrypted). */
+    /**
+     * Null the tokens (dead marker = refreshToken IS NULL) — CONDITIONAL on
+     * the ciphertext we hold, so a browser login that re-seeded the row
+     * mid-flight is never wiped.
+     */
+    private markDead;
+    /** Whether an earlier presentation of THIS ciphertext is still unanswered. */
+    private hasUnansweredPresentation;
+    private recordPresentation;
+    private clearPresentation;
+    /**
+     * RFC 7662 probe of a refresh token whose last presentation went
+     * unanswered. Read-only at the hub: the pinned oauth-provider plugin's
+     * introspection answers `active:false` for a rotated-out, expired, or
+     * unknown refresh token and never touches the family. Anything but a
+     * definite answer is transient — a probe must never be the reason a
+     * grant dies.
+     */
+    private introspect;
+    private readRow;
+    /** Decrypt-and-cache the row's access token when it is still fresh. */
+    private storedAccess;
+    /**
+     * Persist a rotation's result on the row, Better-Auth-compatible
+     * (encrypted with the same key + primitive setTokenUtil uses).
+     * Conditional on the ciphertext we rotated FROM: if a concurrent browser
+     * login re-wrote the row, its (equally valid, same-family) tokens win and
+     * our rotation is only served from memory.
+     */
+    private writeRotation;
+    private decrypt;
+    /** One refresh_token grant POST, classified per the failure taxonomy. */
+    private postRefresh;
+    /**
+     * Session-scoped pg_advisory_lock on a dedicated client — never the pool
+     * (a session lock parked on a pooled connection would poison the pool).
+     * The watchdog cuts the connection after lockWatchdogMs; a session lock
+     * dies with its session, so a wedged refresh is strictly bounded.
+     */
+    private acquireLock;
+    /** Idempotent; closing the client guarantees the session lock dies with it. */
+    private releaseLock;
+}
+export {};
+//# sourceMappingURL=hub-grant.d.ts.map

package/dist/identity/hub-grant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hub-grant.d.ts","sourceRoot":"","sources":["../../src/identity/hub-grant.ts"],"names":[],"mappings":"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"}