@hearth-auth/sdk 0.0.1 → 1.0.0

package/dist/introspection-client.js

@@ -0,0 +1,36 @@
+/**
+ * Low-level RFC 7662 token introspection client.
+ *
+ * Results are never cached — per RFC 7662 §2.1, token state can change
+ * at any time. Full error taxonomy will be added in §3.
+ */
+export class IntrospectionClient {
+    endpoint;
+    clientId;
+    clientSecret;
+    httpTimeout;
+    constructor(config) {
+        this.endpoint = config.introspectionEndpoint;
+        this.clientId = config.clientId;
+        this.clientSecret = config.clientSecret;
+        this.httpTimeout = config.httpTimeout ?? 10_000;
+    }
+    /** Introspect a token. Never cached per RFC 7662 §2.1. */
+    async introspect(token) {
+        const credentials = btoa(`${this.clientId}:${this.clientSecret}`);
+        const resp = await fetch(this.endpoint, {
+            method: "POST",
+            headers: {
+                Authorization: `Basic ${credentials}`,
+                "Content-Type": "application/x-www-form-urlencoded",
+            },
+            body: new URLSearchParams({ token }),
+            signal: AbortSignal.timeout(this.httpTimeout),
+        });
+        if (!resp.ok) {
+            throw new Error(`Introspection endpoint returned HTTP ${resp.status}`);
+        }
+        return resp.json();
+    }
+}
+//# sourceMappingURL=introspection-client.js.map

package/dist/introspection-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"introspection-client.js","sourceRoot":"","sources":["../src/introspection-client.ts"],"names":[],"mappings":"AA8CA;;;;;GAKG;AACH,MAAM,OAAO,mBAAmB;IACb,QAAQ,CAAS;IACjB,QAAQ,CAAS;IACjB,YAAY,CAAS;IAC7B,WAAW,CAAS;IAE7B,YAAY,MAAiC;QAC3C,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,qBAAqB,CAAC;QAC7C,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;QAChC,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,YAAY,CAAC;QACxC,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,WAAW,IAAI,MAAM,CAAC;IAClD,CAAC;IAED,0DAA0D;IAC1D,KAAK,CAAC,UAAU,CAAC,KAAa;QAC5B,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC;QAClE,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE;YACtC,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,aAAa,EAAE,SAAS,WAAW,EAAE;gBACrC,cAAc,EAAE,mCAAmC;aACpD;YACD,IAAI,EAAE,IAAI,eAAe,CAAC,EAAE,KAAK,EAAE,CAAC;YACpC,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC;SAC9C,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,wCAAwC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QACzE,CAAC;QACD,OAAO,IAAI,CAAC,IAAI,EAAkC,CAAC;IACrD,CAAC;CACF"}

package/dist/jwks-client.d.ts

@@ -0,0 +1,28 @@
+import type { JsonWebKey } from "./types.js";
+/** Configuration for {@link JwksClient}. */
+export interface JwksClientConfig {
+    /** URL of the JWKS endpoint (e.g. from OIDC discovery `jwks_uri`). */
+    jwksUri: string;
+    /**
+     * Override cache TTL in milliseconds.
+     * When absent, the client respects `Cache-Control: max-age` from the JWKS
+     * response and falls back to 5 minutes.
+     */
+    ttl?: number;
+    /** Timeout for outbound HTTP calls in milliseconds. Default: 10 000. */
+    httpTimeout?: number;
+}
+/**
+ * Low-level JWKS fetcher.
+ *
+ * Fetches the JSON Web Key Set from the configured endpoint.
+ * Full caching and rotation logic will be added in §2.
+ */
+export declare class JwksClient {
+    private readonly jwksUri;
+    readonly ttl: number | undefined;
+    readonly httpTimeout: number;
+    constructor(config: JwksClientConfig);
+    /** Fetch the current JWKS keys from the endpoint. */
+    fetchKeys(): Promise<JsonWebKey[]>;
+}

package/dist/jwks-client.js

@@ -0,0 +1,28 @@
+/**
+ * Low-level JWKS fetcher.
+ *
+ * Fetches the JSON Web Key Set from the configured endpoint.
+ * Full caching and rotation logic will be added in §2.
+ */
+export class JwksClient {
+    jwksUri;
+    ttl;
+    httpTimeout;
+    constructor(config) {
+        this.jwksUri = config.jwksUri;
+        this.ttl = config.ttl;
+        this.httpTimeout = config.httpTimeout ?? 10_000;
+    }
+    /** Fetch the current JWKS keys from the endpoint. */
+    async fetchKeys() {
+        const resp = await fetch(this.jwksUri, {
+            signal: AbortSignal.timeout(this.httpTimeout),
+        });
+        if (!resp.ok) {
+            throw new Error(`JWKS fetch failed with HTTP ${resp.status}`);
+        }
+        const doc = (await resp.json());
+        return doc.keys;
+    }
+}
+//# sourceMappingURL=jwks-client.js.map

package/dist/jwks-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwks-client.js","sourceRoot":"","sources":["../src/jwks-client.ts"],"names":[],"mappings":"AAgBA;;;;;GAKG;AACH,MAAM,OAAO,UAAU;IACJ,OAAO,CAAS;IACxB,GAAG,CAAqB;IACxB,WAAW,CAAS;IAE7B,YAAY,MAAwB;QAClC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAC9B,IAAI,CAAC,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC;QACtB,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,WAAW,IAAI,MAAM,CAAC;IAClD,CAAC;IAED,qDAAqD;IACrD,KAAK,CAAC,SAAS;QACb,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE;YACrC,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC;SAC9C,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,+BAA+B,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QAChE,CAAC;QACD,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI,CAAC,IAAI,EAAE,CAA2B,CAAC;QAC1D,OAAO,GAAG,CAAC,IAAI,CAAC;IAClB,CAAC;CACF"}

package/dist/middleware.d.ts

@@ -0,0 +1,38 @@
+import type { HearthClient } from "./hearth-client.js";
+import type { AccessTokenAuthorizationMode, AuthorizePermissionOptions } from "./types.js";
+/** Options for {@link requirePermission}. */
+export interface RequirePermissionOptions extends AuthorizePermissionOptions {
+    /**
+     * Which permission delivery mode the resource server expects.
+     *
+     * MUST be set explicitly — the middleware MUST NOT auto-detect the mode from
+     * JWT claim presence. Absence of a `permissions` claim in the token does not
+     * change behavior (per HEA-923 design constraint).
+     */
+    mode: AccessTokenAuthorizationMode;
+    /** HearthClient instance used for network calls in decision/introspection modes. */
+    client: HearthClient;
+}
+/**
+ * A synchronous-or-async gate that returns `true` iff the token holder has
+ * the given permission under the configured mode.
+ */
+export type PermissionChecker = (token: string) => Promise<boolean>;
+/**
+ * Returns a mode-aware permission checker for the given `permission`.
+ *
+ * Behaviour by mode:
+ * - **embedded** — decodes the JWT locally and checks the `permissions` claim.
+ *   No network traffic. Returns `false` when the claim is absent; DOES NOT
+ *   fall back to network (design constraint: absence of claims ≠ switch mode).
+ * - **decision** — calls `client.authorize(token, permission, opts)` which
+ *   POSTs to `POST /oauth/authorize`. Fail-closed on network/server errors.
+ * - **introspection** — calls `client.introspectionClient().introspect(token)`,
+ *   validates the echoed `mode` field if present, then checks the returned
+ *   `permissions` array. Throws {@link AuthorizationModeMismatchError} if the
+ *   server echoes a mode that differs from `opts.mode`.
+ *
+ * @param permission - The permission string to check (e.g. `"docs.write"`).
+ * @param opts - Mode, client reference, and optional scoping parameters.
+ */
+export declare function requirePermission(permission: string, opts: RequirePermissionOptions): PermissionChecker;

package/dist/middleware.js

@@ -0,0 +1,51 @@
+import { decodeJwt } from "jose";
+import { AuthorizationModeMismatchError } from "./errors.js";
+/**
+ * Returns a mode-aware permission checker for the given `permission`.
+ *
+ * Behaviour by mode:
+ * - **embedded** — decodes the JWT locally and checks the `permissions` claim.
+ *   No network traffic. Returns `false` when the claim is absent; DOES NOT
+ *   fall back to network (design constraint: absence of claims ≠ switch mode).
+ * - **decision** — calls `client.authorize(token, permission, opts)` which
+ *   POSTs to `POST /oauth/authorize`. Fail-closed on network/server errors.
+ * - **introspection** — calls `client.introspectionClient().introspect(token)`,
+ *   validates the echoed `mode` field if present, then checks the returned
+ *   `permissions` array. Throws {@link AuthorizationModeMismatchError} if the
+ *   server echoes a mode that differs from `opts.mode`.
+ *
+ * @param permission - The permission string to check (e.g. `"docs.write"`).
+ * @param opts - Mode, client reference, and optional scoping parameters.
+ */
+export function requirePermission(permission, opts) {
+    const { mode, client, organizationId, resource } = opts;
+    switch (mode) {
+        case "embedded":
+            return async (token) => {
+                let claims = null;
+                try {
+                    claims = decodeJwt(token);
+                }
+                catch {
+                    return false;
+                }
+                const perms = claims["permissions"];
+                return Array.isArray(perms) && perms.includes(permission);
+            };
+        case "decision":
+            return async (token) => client.authorize(token, permission, { organizationId, resource });
+        case "introspection":
+            return async (token) => {
+                const ic = await client.introspectionClient();
+                const result = await ic.introspect(token);
+                // Validate mode echo when present — catches misconfigured deployments.
+                if (result.mode !== undefined && result.mode !== "introspection") {
+                    throw new AuthorizationModeMismatchError("introspection", String(result.mode));
+                }
+                if (!result.active)
+                    return false;
+                return (Array.isArray(result.permissions) && result.permissions.includes(permission));
+            };
+    }
+}
+//# sourceMappingURL=middleware.js.map

package/dist/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,MAAM,CAAC;AACjC,OAAO,EAAE,8BAA8B,EAAE,MAAM,aAAa,CAAC;AAwB7D;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,UAAkB,EAClB,IAA8B;IAE9B,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC;IAExD,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,UAAU;YACb,OAAO,KAAK,EAAE,KAAa,EAAoB,EAAE;gBAC/C,IAAI,MAAM,GAAmC,IAAI,CAAC;gBAClD,IAAI,CAAC;oBACH,MAAM,GAAG,SAAS,CAAC,KAAK,CAA4B,CAAC;gBACvD,CAAC;gBAAC,MAAM,CAAC;oBACP,OAAO,KAAK,CAAC;gBACf,CAAC;gBACD,MAAM,KAAK,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC;gBACpC,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;YAC5D,CAAC,CAAC;QAEJ,KAAK,UAAU;YACb,OAAO,KAAK,EAAE,KAAa,EAAoB,EAAE,CAC/C,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,cAAc,EAAE,QAAQ,EAAE,CAAC,CAAC;QAEtE,KAAK,eAAe;YAClB,OAAO,KAAK,EAAE,KAAa,EAAoB,EAAE;gBAC/C,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,mBAAmB,EAAE,CAAC;gBAC9C,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;gBAE1C,uEAAuE;gBACvE,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,KAAK,eAAe,EAAE,CAAC;oBACjE,MAAM,IAAI,8BAA8B,CAAC,eAAe,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;gBACjF,CAAC;gBAED,IAAI,CAAC,MAAM,CAAC,MAAM;oBAAE,OAAO,KAAK,CAAC;gBACjC,OAAO,CACL,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,UAAU,CAAC,CAC7E,CAAC;YACJ,CAAC,CAAC;IACN,CAAC;AACH,CAAC"}

package/dist/pkce.d.ts

@@ -0,0 +1,64 @@
+/** Minimal interface required by {@link startLogin} — satisfied by {@link HearthApiClient}. */
+interface DiscoverySource {
+    discovery(): Promise<Record<string, unknown>>;
+}
+/** Generate a cryptographically random RFC 7636 code verifier (256-bit / 32 bytes). */
+export declare function generateCodeVerifier(): string;
+/** Derive the S256 code challenge from a verifier (RFC 7636 §4.2). */
+export declare function generateCodeChallenge(verifier: string): Promise<string>;
+/** Options for {@link buildAuthorizationUrl}. */
+export interface BuildAuthorizationUrlOptions {
+    /** OIDC `authorization_endpoint` from the discovery document. */
+    authorizationEndpoint: string;
+    /** OAuth 2.0 client ID. */
+    clientId: string;
+    /** Redirect URI registered for this client. */
+    redirectUri: string;
+    /** Base64url-encoded S256 code challenge (from {@link generateCodeChallenge}). */
+    codeChallenge: string;
+    /** OAuth 2.0 scope string. Default: `"openid profile email"`. */
+    scope?: string;
+    /** CSRF state token. Auto-generated (16 random bytes) when absent. */
+    state?: string;
+}
+/** Return value of {@link buildAuthorizationUrl}. */
+export interface AuthorizationUrlResult {
+    /** Full authorization redirect URL to navigate the browser to. */
+    url: string;
+    /** State value embedded in the URL — persist for CSRF validation in the callback. */
+    state: string;
+}
+/** Build the full authorization redirect URL for an RFC 7636 PKCE flow. */
+export declare function buildAuthorizationUrl(opts: BuildAuthorizationUrlOptions): AuthorizationUrlResult;
+/** Options for {@link startLogin}. */
+export interface StartLoginOptions {
+    /** OAuth 2.0 client ID. */
+    clientId: string;
+    /** Redirect URI registered for this client. */
+    redirectUri: string;
+    /** OAuth 2.0 scope string. Default: `"openid profile email"`. */
+    scope?: string;
+    /** CSRF state token. Auto-generated when absent. */
+    state?: string;
+}
+/** Return value of {@link startLogin}. */
+export interface StartLoginResult {
+    /** Full authorization URL — redirect the browser here to begin login. */
+    url: string;
+    /** OAuth 2.0 state value — persist for CSRF validation in the callback. */
+    state: string;
+    /**
+     * RFC 7636 code verifier — persist (e.g. `sessionStorage`) and pass as
+     * `codeVerifier` to `handleCallback()` during the token exchange step.
+     */
+    codeVerifier: string;
+}
+/**
+ * One-shot PKCE login initiation: discovers the authorization endpoint,
+ * generates a code verifier/challenge, and builds the redirect URL.
+ *
+ * The caller MUST persist `codeVerifier` and `state` (e.g. in `sessionStorage`)
+ * before navigating to `url`, and pass them to `handleCallback()` on return.
+ */
+export declare function startLogin(client: DiscoverySource, opts: StartLoginOptions): Promise<StartLoginResult>;
+export {};

package/dist/pkce.js

@@ -0,0 +1,64 @@
+/** Generate a cryptographically random RFC 7636 code verifier (256-bit / 32 bytes). */
+export function generateCodeVerifier() {
+    const bytes = new Uint8Array(32);
+    crypto.getRandomValues(bytes);
+    return base64urlEncode(bytes);
+}
+/** Derive the S256 code challenge from a verifier (RFC 7636 §4.2). */
+export async function generateCodeChallenge(verifier) {
+    const data = new TextEncoder().encode(verifier);
+    const hash = await crypto.subtle.digest("SHA-256", data);
+    return base64urlEncode(new Uint8Array(hash));
+}
+/** Build the full authorization redirect URL for an RFC 7636 PKCE flow. */
+export function buildAuthorizationUrl(opts) {
+    const state = opts.state ?? generateState();
+    const params = new URLSearchParams({
+        response_type: "code",
+        client_id: opts.clientId,
+        redirect_uri: opts.redirectUri,
+        code_challenge: opts.codeChallenge,
+        code_challenge_method: "S256",
+        scope: opts.scope ?? "openid profile email",
+        state,
+    });
+    return { url: `${opts.authorizationEndpoint}?${params.toString()}`, state };
+}
+/**
+ * One-shot PKCE login initiation: discovers the authorization endpoint,
+ * generates a code verifier/challenge, and builds the redirect URL.
+ *
+ * The caller MUST persist `codeVerifier` and `state` (e.g. in `sessionStorage`)
+ * before navigating to `url`, and pass them to `handleCallback()` on return.
+ */
+export async function startLogin(client, opts) {
+    const doc = await client.discovery();
+    const authorizationEndpoint = doc["authorization_endpoint"];
+    if (!authorizationEndpoint) {
+        throw new Error("startLogin: authorization_endpoint not found in OIDC discovery document");
+    }
+    const codeVerifier = generateCodeVerifier();
+    const codeChallenge = await generateCodeChallenge(codeVerifier);
+    const { url, state } = buildAuthorizationUrl({
+        authorizationEndpoint,
+        clientId: opts.clientId,
+        redirectUri: opts.redirectUri,
+        codeChallenge,
+        scope: opts.scope,
+        state: opts.state,
+    });
+    return { url, state, codeVerifier };
+}
+function generateState() {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    return base64urlEncode(bytes);
+}
+function base64urlEncode(input) {
+    let binary = "";
+    for (const byte of input) {
+        binary += String.fromCharCode(byte);
+    }
+    return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+}
+//# sourceMappingURL=pkce.js.map

package/dist/pkce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkce.js","sourceRoot":"","sources":["../src/pkce.ts"],"names":[],"mappings":"AAKA,uFAAuF;AACvF,MAAM,UAAU,oBAAoB;IAClC,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC;IACjC,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;IAC9B,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC;AAChC,CAAC;AAED,sEAAsE;AACtE,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,QAAgB;IAC1D,MAAM,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAChD,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IACzD,OAAO,eAAe,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;AAC/C,CAAC;AA0BD,2EAA2E;AAC3E,MAAM,UAAU,qBAAqB,CACnC,IAAkC;IAElC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,aAAa,EAAE,CAAC;IAC5C,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC;QACjC,aAAa,EAAE,MAAM;QACrB,SAAS,EAAE,IAAI,CAAC,QAAQ;QACxB,YAAY,EAAE,IAAI,CAAC,WAAW;QAC9B,cAAc,EAAE,IAAI,CAAC,aAAa;QAClC,qBAAqB,EAAE,MAAM;QAC7B,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,sBAAsB;QAC3C,KAAK;KACN,CAAC,CAAC;IACH,OAAO,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,qBAAqB,IAAI,MAAM,CAAC,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;AAC9E,CAAC;AA2BD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,MAAuB,EACvB,IAAuB;IAEvB,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,SAAS,EAAE,CAAC;IACrC,MAAM,qBAAqB,GAAG,GAAG,CAAC,wBAAwB,CAAuB,CAAC;IAClF,IAAI,CAAC,qBAAqB,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CACb,yEAAyE,CAC1E,CAAC;IACJ,CAAC;IACD,MAAM,YAAY,GAAG,oBAAoB,EAAE,CAAC;IAC5C,MAAM,aAAa,GAAG,MAAM,qBAAqB,CAAC,YAAY,CAAC,CAAC;IAChE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,qBAAqB,CAAC;QAC3C,qBAAqB;QACrB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,aAAa;QACb,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,KAAK,EAAE,IAAI,CAAC,KAAK;KAClB,CAAC,CAAC;IACH,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC;AACtC,CAAC;AAED,SAAS,aAAa;IACpB,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC;IACjC,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;IAC9B,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC;AAChC,CAAC;AAED,SAAS,eAAe,CAAC,KAAiB;IACxC,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,IAAI,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC;IACD,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;AAChF,CAAC"}

package/dist/react.d.ts

@@ -0,0 +1,32 @@
+import * as React from "react";
+import type { HearthFacade } from "./hearth.js";
+/**
+ * React context carrying a {@link HearthFacade} down the tree.
+ *
+ * The default value is `null`; the hooks treat a `null` context as
+ * unauthenticated and return `false`.
+ */
+export declare const HearthContext: React.Context<HearthFacade | null>;
+/** Props for {@link HearthProvider}. */
+export interface HearthProviderProps {
+    client: HearthFacade;
+    children: React.ReactNode;
+}
+/**
+ * Provides a {@link HearthFacade} to descendants via {@link HearthContext}.
+ *
+ * Wrap your React tree once with this after calling `createHearth(...)`.
+ */
+export declare function HearthProvider(props: HearthProviderProps): React.ReactElement;
+/**
+ * Returns `true` iff the nearest {@link HearthProvider} client reports
+ * the permission as present in the JWT claim set. Returns `false`
+ * when no provider is mounted.
+ */
+export declare function useHasPermission(permission: string): boolean;
+/** Returns `true` iff the JWT `roles` claim contains `role`. */
+export declare function useHasRole(role: string): boolean;
+/** Returns `true` iff the JWT `groups` claim contains `group`. */
+export declare function useInGroup(group: string): boolean;
+/** Returns `true` iff the JWT `oid` claim equals `org`. */
+export declare function useInOrg(org: string): boolean;

package/dist/react.js

@@ -0,0 +1,41 @@
+import * as React from "react";
+/**
+ * React context carrying a {@link HearthFacade} down the tree.
+ *
+ * The default value is `null`; the hooks treat a `null` context as
+ * unauthenticated and return `false`.
+ */
+export const HearthContext = React.createContext(null);
+/**
+ * Provides a {@link HearthFacade} to descendants via {@link HearthContext}.
+ *
+ * Wrap your React tree once with this after calling `createHearth(...)`.
+ */
+export function HearthProvider(props) {
+    return React.createElement(HearthContext.Provider, { value: props.client }, props.children);
+}
+/**
+ * Returns `true` iff the nearest {@link HearthProvider} client reports
+ * the permission as present in the JWT claim set. Returns `false`
+ * when no provider is mounted.
+ */
+export function useHasPermission(permission) {
+    const client = React.useContext(HearthContext);
+    return client !== null && client.hasPermission(permission);
+}
+/** Returns `true` iff the JWT `roles` claim contains `role`. */
+export function useHasRole(role) {
+    const client = React.useContext(HearthContext);
+    return client !== null && client.hasRole(role);
+}
+/** Returns `true` iff the JWT `groups` claim contains `group`. */
+export function useInGroup(group) {
+    const client = React.useContext(HearthContext);
+    return client !== null && client.inGroup(group);
+}
+/** Returns `true` iff the JWT `oid` claim equals `org`. */
+export function useInOrg(org) {
+    const client = React.useContext(HearthContext);
+    return client !== null && client.inOrg(org);
+}
+//# sourceMappingURL=react.js.map

package/dist/react.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.js","sourceRoot":"","sources":["../src/react.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,CAAC,aAAa,CAAsB,IAAI,CAAC,CAAC;AAQ5E;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,KAA0B;IACvD,OAAO,KAAK,CAAC,aAAa,CACxB,aAAa,CAAC,QAAQ,EACtB,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,EACvB,KAAK,CAAC,QAAQ,CACf,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,UAAkB;IACjD,MAAM,MAAM,GAAG,KAAK,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;IAC/C,OAAO,MAAM,KAAK,IAAI,IAAI,MAAM,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;AAC7D,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,MAAM,MAAM,GAAG,KAAK,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;IAC/C,OAAO,MAAM,KAAK,IAAI,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;AACjD,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,MAAM,MAAM,GAAG,KAAK,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;IAC/C,OAAO,MAAM,KAAK,IAAI,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAClD,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,QAAQ,CAAC,GAAW;IAClC,MAAM,MAAM,GAAG,KAAK,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;IAC/C,OAAO,MAAM,KAAK,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AAC9C,CAAC"}

package/dist/session-version-cache.d.ts

@@ -0,0 +1,50 @@
+import type { SessionVersionConfig } from "./types.js";
+/**
+ * Client-side cache of per-session minimum accepted `sv` values.
+ *
+ * Polls `GET /oauth/session-versions` at `cfg.pollIntervalMs` intervals and
+ * applies delta entries to an in-memory `Map<sessionId, bigint>`. Used by
+ * `createHearth()` to validate the `sv` claim in access tokens without any
+ * per-request network call.
+ *
+ * Background poll errors are swallowed; the cache age then grows and eventually
+ * trips the stale threshold, triggering fail-closed behaviour (§ 8.1).
+ */
+export declare class SessionVersionCache {
+    private readonly baseUrl;
+    private readonly realmId;
+    private readonly cfg;
+    private readonly versions;
+    private lastRefreshed;
+    private seq;
+    private pollTimer;
+    constructor(baseUrl: string, realmId: string, cfg: SessionVersionConfig);
+    /**
+     * Kicks off the initial snapshot fetch (async, non-blocking) and starts the
+     * background poll loop. Call once after construction.
+     *
+     * If `staleThresholdMs <= pollIntervalMs` a console warning is emitted.
+     * Until the first snapshot completes, `age()` returns `Infinity` which
+     * will trip the stale threshold if `staleThresholdMs` is finite.
+     */
+    start(): void;
+    /** Stops the background poll timer. Call when disposing the Hearth facade. */
+    stop(): void;
+    /** Returns milliseconds since the cache was last successfully refreshed. */
+    age(): number;
+    /**
+     * Validates the `sv` claim against the local cache.
+     *
+     * - Absent `sv` or absent `sid` → no-op (backward compat, RFC § 8.2).
+     * - Cache age > `staleThresholdMs` → throws {@link SessionVersionCacheStaleError}.
+     * - `sv < minSv` → throws {@link SessionVersionRevokedError}.
+     *
+     * When `onStale` is `"introspect"`, callers should catch
+     * {@link SessionVersionCacheStaleError} and fall back to the introspection
+     * endpoint, which performs a fresh server-side check.
+     */
+    validateSv(sv: bigint | undefined, sessionId: string | undefined): void;
+    private fetchSnapshot;
+    private schedulePoll;
+    private poll;
+}

package/dist/session-version-cache.js

@@ -0,0 +1,129 @@
+import { SessionVersionCacheStaleError, SessionVersionRevokedError, } from "./errors.js";
+/**
+ * Client-side cache of per-session minimum accepted `sv` values.
+ *
+ * Polls `GET /oauth/session-versions` at `cfg.pollIntervalMs` intervals and
+ * applies delta entries to an in-memory `Map<sessionId, bigint>`. Used by
+ * `createHearth()` to validate the `sv` claim in access tokens without any
+ * per-request network call.
+ *
+ * Background poll errors are swallowed; the cache age then grows and eventually
+ * trips the stale threshold, triggering fail-closed behaviour (§ 8.1).
+ */
+export class SessionVersionCache {
+    baseUrl;
+    realmId;
+    cfg;
+    versions = new Map();
+    lastRefreshed = 0;
+    seq = 0;
+    pollTimer = null;
+    constructor(baseUrl, realmId, cfg) {
+        this.baseUrl = baseUrl.replace(/\/$/, "");
+        this.realmId = realmId;
+        this.cfg = cfg;
+    }
+    /**
+     * Kicks off the initial snapshot fetch (async, non-blocking) and starts the
+     * background poll loop. Call once after construction.
+     *
+     * If `staleThresholdMs <= pollIntervalMs` a console warning is emitted.
+     * Until the first snapshot completes, `age()` returns `Infinity` which
+     * will trip the stale threshold if `staleThresholdMs` is finite.
+     */
+    start() {
+        if (this.cfg.staleThresholdMs <= this.cfg.pollIntervalMs) {
+            console.warn("[hearth] sessionVersions.staleThresholdMs must be > pollIntervalMs " +
+                `(stale=${this.cfg.staleThresholdMs}ms, poll=${this.cfg.pollIntervalMs}ms). ` +
+                "Recommended: staleThresholdMs = pollIntervalMs × 3.");
+        }
+        void this.fetchSnapshot().catch(() => undefined);
+        this.schedulePoll();
+    }
+    /** Stops the background poll timer. Call when disposing the Hearth facade. */
+    stop() {
+        if (this.pollTimer !== null) {
+            clearTimeout(this.pollTimer);
+            this.pollTimer = null;
+        }
+    }
+    /** Returns milliseconds since the cache was last successfully refreshed. */
+    age() {
+        if (this.lastRefreshed === 0)
+            return Number.POSITIVE_INFINITY;
+        return Date.now() - this.lastRefreshed;
+    }
+    /**
+     * Validates the `sv` claim against the local cache.
+     *
+     * - Absent `sv` or absent `sid` → no-op (backward compat, RFC § 8.2).
+     * - Cache age > `staleThresholdMs` → throws {@link SessionVersionCacheStaleError}.
+     * - `sv < minSv` → throws {@link SessionVersionRevokedError}.
+     *
+     * When `onStale` is `"introspect"`, callers should catch
+     * {@link SessionVersionCacheStaleError} and fall back to the introspection
+     * endpoint, which performs a fresh server-side check.
+     */
+    validateSv(sv, sessionId) {
+        if (sv === undefined || sessionId === undefined)
+            return;
+        const ageMs = this.age();
+        if (ageMs > this.cfg.staleThresholdMs) {
+            throw new SessionVersionCacheStaleError(isFinite(ageMs) ? ageMs : -1, this.cfg.onStale);
+        }
+        const minSv = this.versions.get(sessionId) ?? 1n;
+        if (sv < minSv) {
+            throw new SessionVersionRevokedError(sessionId, sv, minSv);
+        }
+    }
+    // ── Private ─────────────────────────────────────────────────────────────────
+    async fetchSnapshot() {
+        const url = `${this.baseUrl}/oauth/session-versions/snapshot?realm=${encodeURIComponent(this.realmId)}`;
+        const resp = await fetch(url, {
+            headers: { Authorization: `Bearer ${this.cfg.serviceToken}` },
+        });
+        if (!resp.ok) {
+            throw new Error(`SV snapshot fetch failed: HTTP ${resp.status}`);
+        }
+        const data = (await resp.json());
+        this.versions.clear();
+        for (const [sid, minSv] of Object.entries(data.versions)) {
+            this.versions.set(sid, BigInt(minSv));
+        }
+        this.seq = data.current_seq;
+        this.lastRefreshed = Date.now();
+    }
+    schedulePoll() {
+        this.pollTimer = setTimeout(() => {
+            void this.poll()
+                .catch(() => undefined)
+                .finally(() => this.schedulePoll());
+        }, this.cfg.pollIntervalMs);
+    }
+    async poll() {
+        const url = `${this.baseUrl}/oauth/session-versions?since=${this.seq}` +
+            `&realm=${encodeURIComponent(this.realmId)}`;
+        const resp = await fetch(url, {
+            headers: { Authorization: `Bearer ${this.cfg.serviceToken}` },
+        });
+        if (resp.status === 204) {
+            this.lastRefreshed = Date.now();
+            return;
+        }
+        if (resp.status === 400) {
+            // Sequence predates retention window — must re-seed from snapshot.
+            await this.fetchSnapshot();
+            return;
+        }
+        if (!resp.ok) {
+            throw new Error(`SV delta poll failed: HTTP ${resp.status}`);
+        }
+        const data = (await resp.json());
+        for (const delta of data.deltas) {
+            this.versions.set(delta.session_id, BigInt(delta.min_sv));
+        }
+        this.seq = data.next_seq;
+        this.lastRefreshed = Date.now();
+    }
+}
+//# sourceMappingURL=session-version-cache.js.map

package/dist/session-version-cache.js.map

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