@hearth-auth/sdk 3.0.0 → 3.1.0

package/README.md

@@ -35,23 +35,30 @@ const client = new HearthClient({
   clientId: "<client-id>",
   clientSecret: "<client-secret>", // confidential clients only
   realmId: "<your-realm-id>",
+  audience: "https://api.example.com", // expected `aud`; default "hearth"
 });
 
 const claims = await client.verifyToken(accessToken); // throws on a bad token
 claims.subject();
 claims.hasPermission("docs.write");
 
-// RBAC facade — local, synchronous permission checks from the JWT
+// RBAC facade — verifies the token, then checks its claims
 const hearth = createHearth({
   baseUrl: "https://hearth.example.com",
   realmId: "<your-realm-id>",
-  getToken: () => localStorage.getItem("access_token"),
+  issuerUrl: "https://hearth.example.com/realms/<realm-slug>",
+  getToken: () => currentAccessToken,
 });
+await hearth.hasPermission("docs.write");
 ```
 
 `HearthClient` reads every endpoint URL from `{issuerUrl}/.well-known/openid-configuration` on first use and caches it. `httpTimeout` (default 10 000 ms) applies to every request it makes. Call `client.invalidateCache()` to drop the cached discovery document, JWKS and introspection client.
 
-`createHearth` gives you a zero-network RBAC facade that reads claims from the JWT in memory.
+`createHearth` gives you an RBAC facade over the token `getToken()` returns. Each check verifies that token against the realm JWKS (fetched once, then cached) before it reads a claim.
+
+### Audience
+
+`verifyToken` always checks `aud` (RFC 9068 §4); the check cannot be turned off. The expected audience is the `audience` option, default `"hearth"` (exported as `DEFAULT_AUDIENCE`): the audience Hearth mints when a client names no resource. An API registered as a protected resource sets its resource URI. The client ID is not the audience: only ID tokens are checked against a client ID (OIDC Core). An empty `audience` throws `ConfigurationError`; a token whose `aud` does not contain the expected audience throws `TokenAudienceError`. `JwksClient` takes the same option, and `VerifyOptions.audience` overrides it for one `verify()` call.
 
 ---
 
@@ -106,69 +113,93 @@ Every token-endpoint failure throws `OAuthFlowError` with `statusCode` and the O
 
 A single-page app has no server session to hold the verifier. Use `createHearthAuth`, or build the flow from `generateCodeVerifier`, `generateCodeChallenge` and `buildAuthorizationUrl`.
 
+```typescript
+import { createHearthAuth, HearthApiClient } from "@hearth-auth/sdk";
+
+const auth = createHearthAuth(
+  new HearthApiClient({ baseUrl: "https://hearth.example.com", realmId: "<realm-id>" }),
+  {
+    clientId: "<client-id>",
+    redirectUri: "https://app.example.com/callback",
+    hearthUrl: "https://hearth.example.com",
+    realmSlug: "<realm-slug>",
+    // storage: "sessionStorage" (default) | "localStorage" | "memory" | { getItem, setItem, removeItem }
+    // storageKeyPrefix: "hearth_" (default)
+  },
+);
+
+await auth.startLogin();
+// on the callback page: await auth.handleCallback(code, state);
+auth.getAccessToken(); // also getRefreshToken(), getIdToken(), isAuthenticated(), clearTokens()
+```
+
+The access token stays in memory. The refresh token, ID token and the PKCE verifier and `state` of a login in flight go to the configured `storage`, `sessionStorage` by default (scoped to one tab, cleared when it closes). `"memory"` does not survive the login redirect. At creation the facade removes `hearth_refresh_token` and `hearth_id_token` from `localStorage` unless `localStorage` is the configured store.
+
 ---
 
 ## RBAC capabilities
 
-All synchronous helpers decode the JWT returned by `getToken()` **locally** — no network call, no cache, no lock. When the token is absent or malformed, every predicate returns `false`.
+Every predicate verifies the token returned by `getToken()` before it reads a claim: the EdDSA signature against the realm JWKS (fetched from `issuerUrl` once, then cached), plus `exp`, `nbf`, `iat`, `iss` (must equal `issuerUrl`) and `aud` (must contain `audience`, default `"hearth"`). When the token is absent or does not verify, every predicate resolves `false`. With `sessionVersions` enabled, a predicate may reject with `SessionVersionRevokedError` or `SessionVersionCacheStaleError`.
 
 ```typescript
 const hearth = createHearth({
   baseUrl: "https://hearth.example.com",
   realmId: "<your-realm-id>",
-  getToken: () => sessionStorage.getItem("access_token"),
+  issuerUrl: "https://hearth.example.com/realms/<realm-slug>", // required: the realm issuer
+  audience: "hearth",                                           // optional; this is the default
+  getToken: () => auth.getAccessToken(), // may also return a Promise
 });
 ```
 
-### `hasPermission(permission: string): boolean`
+### `hasPermission(permission: string): Promise<boolean>`
 
-Returns `true` iff the JWT `permissions` claim contains `permission`. Use this for feature gates and API guards.
+Resolves `true` iff the token verifies and its `permissions` claim contains `permission`. Use this for feature gates and API guards.
 
 ```typescript
-if (hearth.hasPermission("docs.versions.read")) {
+if (await hearth.hasPermission("docs.versions.read")) {
   renderVersionHistory();
 }
 ```
 
-### `hasRole(role: string): boolean`
+### `hasRole(role: string): Promise<boolean>`
 
-Returns `true` iff the JWT `roles` claim contains `role`. Useful for UI personalization and coarse-grained access.
+Resolves `true` iff the token verifies and its `roles` claim contains `role`. Useful for UI personalization and coarse-grained access.
 
 ```typescript
-if (hearth.hasRole("billing-admin")) {
+if (await hearth.hasRole("billing-admin")) {
   renderBillingPanel();
 }
 ```
 
-### `inGroup(group: string): boolean`
+### `inGroup(group: string): Promise<boolean>`
 
-Returns `true` iff the JWT `groups` claim contains the group slug.
+Resolves `true` iff the token verifies and its `groups` claim contains the group slug.
 
 ```typescript
-if (hearth.inGroup("engineering")) {
+if (await hearth.inGroup("engineering")) {
   renderInternalToolingLink();
 }
 ```
 
-### `inOrg(org: string): boolean`
+### `inOrg(org: string): Promise<boolean>`
 
-Returns `true` iff the JWT `oid` claim equals the given org ID.
+Resolves `true` iff the token verifies and its `oid` claim equals the given org ID.
 
 ```typescript
-if (hearth.inOrg("org_acme")) {
+if (await hearth.inOrg("org_acme")) {
   renderAcmeContent();
 }
 ```
 
 ### `client.permissions(): Promise<MePermissionsResponse>`
 
-Calls `GET /v1/me/permissions` and returns the **freshly-resolved** RBAC claim set from the server. Unlike the synchronous helpers above, this reflects any role/group assignments made since the JWT was issued.
+Calls `GET /v1/me/permissions` and returns the **freshly-resolved** RBAC claim set from the server. Unlike the predicates above, this reflects any role/group assignments made since the JWT was issued.
 
 ```typescript
 const { roles, groups, permissions } = await hearth.client.permissions();
 ```
 
-Use `client.permissions()` when you need post-issuance accuracy (e.g., after an admin operation). For every other check, prefer the synchronous local helpers — they're faster and don't touch the network.
+Use `client.permissions()` when you need post-issuance accuracy (e.g., after an admin operation). For every other check, prefer the local predicates — once the JWKS is cached they make no network call.
 
 ---
 
@@ -190,7 +221,8 @@ import {
 const hearth = createHearth({
   baseUrl: "https://hearth.example.com",
   realmId: "<your-realm-id>",
-  getToken: () => localStorage.getItem("access_token"),
+  issuerUrl: "https://hearth.example.com/realms/<realm-slug>",
+  getToken: () => auth.getAccessToken(), // auth = createHearthAuth(...)
 });
 
 // 2. Mount the provider at the root of your React tree
@@ -220,7 +252,7 @@ function NavBar() {
 }
 ```
 
-All hooks return `false` when no `HearthProvider` is mounted, making them safe to call in tests without a provider.
+The hooks return `boolean`. Each runs the facade's asynchronous check after every render and returns its last result: `false` until the check resolves, and `false` when it rejects. All hooks return `false` when no `HearthProvider` is mounted, making them safe to call in tests without a provider.
 
 ---
 
@@ -259,7 +291,8 @@ const delta = await client.svDelta(serviceToken, snap.current_seq, 500); // null
 const discovery = await client.discover();
 
 // Verify an access token: EdDSA signature against the realm JWKS, then exp,
-// nbf, iss (must equal issuerUrl) and aud (must contain clientId, when set).
+// nbf, iat (not in the future), iss (must equal issuerUrl) and aud (must
+// contain `audience`, default "hearth").
 const claims = await client.verifyToken(accessToken);
 claims.subject();          // sub
 claims.scopes();           // scope split into an array
@@ -365,13 +398,13 @@ Errors raised by the SDK itself extend `HearthSdkError`:
 
 | Error | When |
 |---|---|
-| `ConfigurationError` | A required setting is missing (`clientId`, `realmId`, a discovery endpoint) |
+| `ConfigurationError` | A required setting is missing (`clientId`, `realmId`, a discovery endpoint) or `audience` is empty |
 | `DiscoveryError` | The discovery document cannot be fetched or is invalid |
 | `JWKSFetchError` | The JWKS cannot be fetched |
 | `TokenVerificationError` | Base class of every token failure below |
-| `TokenExpiredError`, `TokenNotYetValidError` | `exp` / `nbf` outside the clock-skew window |
+| `TokenExpiredError`, `TokenNotYetValidError` | `exp` / `nbf` or `iat` outside the clock-skew window |
 | `TokenInvalidError` | Bad signature, wrong algorithm, malformed JWT |
-| `TokenIssuerError`, `TokenAudienceError` | `iss` / `aud` mismatch |
+| `TokenIssuerError`, `TokenAudienceError` | `iss` mismatch / `aud` does not contain the configured `audience` |
 | `IntrospectionError` | The introspection request failed or returned non-JSON |
 | `OAuthFlowError` | A token, userinfo, permissions or session-version request failed (`statusCode`, `errorCode`) |
 | `AuthorizationModeMismatchError` | Introspection echoed a mode other than `expectedMode` |
@@ -416,7 +449,8 @@ const admin = new AdminClient("http://127.0.0.1:8420", realm_id, access_token);
 // HearthClientConfig — constructor argument for HearthClient
 interface HearthClientConfig {
   issuerUrl: string;            // e.g. "https://hearth.example.com"; endpoints are discovered from it
-  clientId?: string;            // needed for login flows, introspection; pins `aud` on verifyToken
+  clientId?: string;            // needed for login flows, introspection
+  audience?: string;            // expected `aud` on verifyToken; default "hearth"; always checked
   clientSecret?: string;        // confidential clients only
   realmId?: string;             // sent as X-Realm-ID; needed by authorize, mePermissions, sv feed, magic link
   httpTimeout?: number;         // ms, default 10 000
@@ -429,18 +463,47 @@ interface HearthClientConfig {
 interface HearthOptions {
   baseUrl: string;
   realmId: string;
-  getToken: () => string | null | undefined; // called on every predicate check
+  issuerUrl: string;            // the realm issuer, e.g. "https://hearth.example.com/realms/acme"
+  audience?: string;            // expected `aud`; default "hearth"
+  // called on every predicate check
+  getToken: () => string | null | undefined | Promise<string | null | undefined>;
+  sessionVersions?: SessionVersionConfig;
 }
 
-// HearthFacade — returned by createHearth()
+// HearthFacade — returned by createHearth(); each predicate verifies the token first
 interface HearthFacade {
-  hasPermission(permission: string): boolean;
-  hasRole(role: string): boolean;
-  inGroup(group: string): boolean;
-  inOrg(org: string): boolean;
+  hasPermission(permission: string): Promise<boolean>;
+  hasRole(role: string): Promise<boolean>;
+  inGroup(group: string): Promise<boolean>;
+  inOrg(org: string): Promise<boolean>;
+  sessionVersionCacheAge(): number;
+  stop(): void;
   client: { permissions(): Promise<MePermissionsResponse> };
 }
 
+// AuthConfig — second argument to createHearthAuth(client, config)
+interface AuthConfig {
+  clientId: string;
+  redirectUri: string;
+  hearthUrl: string;            // e.g. "https://hearth.example.com"
+  realmSlug: string;            // e.g. "acme"
+  storage?: "sessionStorage" | "localStorage" | "memory" | TokenStorage; // default "sessionStorage"
+  storageKeyPrefix?: string;    // default "hearth_"
+}
+
+// HearthBrowserAuth — returned by createHearthAuth()
+interface HearthBrowserAuth {
+  startLogin(): Promise<void>;
+  handleCallback(code: string, state: string): Promise<void>;
+  refreshAccessToken(): Promise<void>;
+  logout(): Promise<void>;
+  getAccessToken(): string | null; // held in memory
+  getRefreshToken(): string | null;
+  getIdToken(): string | null;
+  isAuthenticated(): boolean;
+  clearTokens(): void;
+}
+
 // AuthorizeParams
 interface AuthorizeParams {
   clientId: string;
@@ -550,7 +613,7 @@ class HearthError extends Error {
 
 **`TokenInvalidError`** — JWT signature does not match any key in the JWKS. If the server recently rotated keys the SDK will re-fetch once automatically; persistent failures indicate a key mismatch.
 
-**`TokenAudienceError`** — the token's `aud` claim does not contain the configured audience. Verify `clientId` matches the audience your authorization server issues.
+**`TokenAudienceError`** — the token's `aud` claim does not contain the configured `audience` (default `"hearth"`). Set `audience` to the resource URI the token was issued for; the client ID is not the audience.
 
 **`AuthorizationModeMismatchError`** — the server echoed an `access_token_authorization` mode
 that differs from the SDK's `expectedMode` config or the `mode` passed to `requirePermission`.
@@ -569,7 +632,7 @@ registering the OAuth client; the SDK validates you stay consistent.
 
 RBAC claims (`permissions`, `roles`, `groups`) are embedded in the JWT at issuance. The
 checker verifies the token first — EdDSA signature against the realm's JWKS, plus `exp`,
-`nbf`, `iss` and (when `clientId` is set) `aud` — and only then reads the claim. The JWKS
+`nbf`, `iat`, `iss` and `aud` — and only then reads the claim. The JWKS
 is cached, so after the first request there is no network traffic per check.
 
 A token that does not verify returns `false`; the checker never trusts an unverified
@@ -580,7 +643,7 @@ import { HearthClient, requirePermission } from "@hearth-auth/sdk";
 
 const client = new HearthClient({
   issuerUrl: "https://auth.example.com",
-  clientId: "<your-client-id>", // enables `aud` pinning
+  audience: "https://api.example.com", // expected `aud`; default "hearth"
 });
 
 const check = requirePermission("docs.write", { mode: "embedded", client });
@@ -659,7 +722,7 @@ const allowed = await check(accessToken);
 import express from "express";
 import { HearthClient, hearthMiddleware } from "@hearth-auth/sdk";
 
-const client = new HearthClient({ issuerUrl: "https://hearth.example.com", clientId: "my-api" });
+const client = new HearthClient({ issuerUrl: "https://hearth.example.com" });
 const app = express();
 
 app.get("/docs", hearthMiddleware({ client, requiredPermission: "docs.read" }), (req, res) => {

package/dist/browser-auth.d.ts

@@ -1,10 +1,17 @@
-import { HearthApiClient } from "./client.js";
-export declare function getAccessToken(): string | null;
-export declare function getRefreshToken(): string | null;
-export declare function getIdToken(): string | null;
-/** True iff an access token is present and not yet expired. */
-export declare function isAuthenticated(): boolean;
-export declare function clearTokens(): void;
+import type { HearthApiClient } from "./client.js";
+/** A key/value store for the SDK's browser state. `Storage` satisfies it. */
+export interface TokenStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/**
+ * Where {@link createHearthAuth} keeps its state: `"sessionStorage"`
+ * (default), `"localStorage"` (survives the tab closing; readable by any
+ * script on the origin), `"memory"` (lost on reload or redirect), or a custom
+ * {@link TokenStorage}.
+ */
+export type AuthStorage = "sessionStorage" | "localStorage" | "memory" | TokenStorage;
 /** Configuration for {@link createHearthAuth}. */
 export interface AuthConfig {
     /** OAuth 2.0 client ID. */
@@ -15,18 +22,44 @@ export interface AuthConfig {
     hearthUrl: string;
     /** Realm name (slug), e.g. `"demo"`. */
     realmSlug: string;
+    /**
+     * Where to keep the refresh token, ID token and in-flight login state.
+     * Default `"sessionStorage"`. `"memory"` does not survive the login
+     * redirect, so use it only with a custom flow that stays on the page.
+     */
+    storage?: AuthStorage;
+    /** Prefix of every storage key the SDK writes. Default `"hearth_"`. */
+    storageKeyPrefix?: string;
 }
 /** Auth facade returned by {@link createHearthAuth}. */
 export interface HearthBrowserAuth {
+    /** Redirect to the authorization endpoint with a fresh PKCE challenge. */
     startLogin(): Promise<void>;
+    /** Check `state`, then exchange the callback's code for tokens. */
     handleCallback(code: string, state: string): Promise<void>;
+    /** Exchange the stored refresh token for a new access token. */
     refreshAccessToken(): Promise<void>;
+    /** Clear the local session and redirect to the realm's end-session endpoint. */
     logout(): Promise<void>;
+    /** The current access token (held in memory), or `null`. */
+    getAccessToken(): string | null;
+    /** The stored refresh token, or `null`. */
+    getRefreshToken(): string | null;
+    /** The stored ID token, or `null`. */
+    getIdToken(): string | null;
+    /** True iff an access token is present and not yet expired. */
+    isAuthenticated(): boolean;
+    /** Drop every token, and cancel the scheduled refresh. */
+    clearTokens(): void;
 }
 /**
  * Create a browser-side Hearth auth facade backed entirely by the SDK.
  *
  * Handles the full PKCE login flow, token storage, silent refresh, and
  * RP-initiated logout. No custom crypto or OIDC endpoint logic required.
+ *
+ * At creation it removes the refresh and ID tokens earlier SDK releases kept
+ * in `localStorage`, unless `localStorage` is the configured store and those
+ * are its own keys.
  */
 export declare function createHearthAuth(client: HearthApiClient, config: AuthConfig): HearthBrowserAuth;

package/dist/browser-auth.js

@@ -1,70 +1,100 @@
 import { startLogin } from "./pkce.js";
-// ── Token store ─────────────────────────────────────────────────────────────
-// Access token lives in memory only. Refresh + ID tokens survive page reloads
-// via localStorage. For stricter XSS safety, swap for an HttpOnly-cookie BFF.
-const REFRESH_KEY = "hearth_refresh_token";
-const ID_KEY = "hearth_id_token";
-let _accessToken = null;
-let _expiresAt = null;
-let _refreshTimer = null;
-export function getAccessToken() {
-    return _accessToken;
-}
-export function getRefreshToken() {
-    return localStorage.getItem(REFRESH_KEY);
-}
-export function getIdToken() {
-    return localStorage.getItem(ID_KEY);
-}
-/** True iff an access token is present and not yet expired. */
-export function isAuthenticated() {
-    return _accessToken !== null && _expiresAt !== null && Date.now() / 1000 < _expiresAt;
-}
-export function clearTokens() {
-    _accessToken = null;
-    _expiresAt = null;
-    localStorage.removeItem(REFRESH_KEY);
-    localStorage.removeItem(ID_KEY);
-    if (_refreshTimer !== null) {
-        clearTimeout(_refreshTimer);
-        _refreshTimer = null;
-    }
-}
-function storeTokens(tokens, fallbackRefresh) {
-    _accessToken = tokens.access_token;
-    _expiresAt = Date.now() / 1000 + (tokens.expires_in ?? 3600);
-    const rt = tokens.refresh_token ?? fallbackRefresh;
-    if (rt)
-        localStorage.setItem(REFRESH_KEY, rt);
-    if (tokens.id_token)
-        localStorage.setItem(ID_KEY, tokens.id_token);
+/** Default prefix of every storage key the SDK writes. */
+const DEFAULT_PREFIX = "hearth_";
+/** Keys earlier SDK releases wrote to `localStorage`, removed at init. */
+const LEGACY_LOCAL_STORAGE_KEYS = ["hearth_refresh_token", "hearth_id_token"];
+function memoryStorage() {
+    const data = new Map();
+    return {
+        getItem: (key) => data.get(key) ?? null,
+        setItem: (key, value) => {
+            data.set(key, value);
+        },
+        removeItem: (key) => {
+            data.delete(key);
+        },
+    };
 }
-function scheduleRefresh(expiresIn, doRefresh) {
-    if (_refreshTimer !== null)
-        clearTimeout(_refreshTimer);
-    const delayMs = Math.max(expiresIn * 0.8, expiresIn - 60) * 1000;
-    _refreshTimer = setTimeout(() => {
-        void doRefresh().catch(() => {
-            /* re-auth on next action */
-        });
-    }, delayMs);
+function resolveStorage(option) {
+    if (option === undefined || option === "sessionStorage")
+        return sessionStorage;
+    if (option === "localStorage")
+        return localStorage;
+    if (option === "memory")
+        return memoryStorage();
+    return option;
 }
-const VERIFIER_KEY = "hearth_pkce_verifier";
-const STATE_KEY = "hearth_oauth_state";
 /**
  * Create a browser-side Hearth auth facade backed entirely by the SDK.
  *
  * Handles the full PKCE login flow, token storage, silent refresh, and
  * RP-initiated logout. No custom crypto or OIDC endpoint logic required.
+ *
+ * At creation it removes the refresh and ID tokens earlier SDK releases kept
+ * in `localStorage`, unless `localStorage` is the configured store and those
+ * are its own keys.
  */
 export function createHearthAuth(client, config) {
+    const store = resolveStorage(config.storage);
+    const prefix = config.storageKeyPrefix ?? DEFAULT_PREFIX;
+    const key = {
+        refresh: `${prefix}refresh_token`,
+        id: `${prefix}id_token`,
+        verifier: `${prefix}pkce_verifier`,
+        state: `${prefix}oauth_state`,
+    };
+    if (typeof localStorage !== "undefined") {
+        const ownKeys = store === localStorage ? [key.refresh, key.id] : [];
+        for (const legacy of LEGACY_LOCAL_STORAGE_KEYS) {
+            if (!ownKeys.includes(legacy))
+                localStorage.removeItem(legacy);
+        }
+    }
+    let accessToken = null;
+    let expiresAt = null;
+    let refreshTimer = null;
+    function getRefreshToken() {
+        return store.getItem(key.refresh);
+    }
+    function getIdToken() {
+        return store.getItem(key.id);
+    }
+    function clearTokens() {
+        accessToken = null;
+        expiresAt = null;
+        store.removeItem(key.refresh);
+        store.removeItem(key.id);
+        if (refreshTimer !== null) {
+            clearTimeout(refreshTimer);
+            refreshTimer = null;
+        }
+    }
+    function storeTokens(tokens, fallbackRefresh) {
+        accessToken = tokens.access_token;
+        expiresAt = Date.now() / 1000 + (tokens.expires_in ?? 3600);
+        const rt = tokens.refresh_token ?? fallbackRefresh;
+        if (rt)
+            store.setItem(key.refresh, rt);
+        if (tokens.id_token)
+            store.setItem(key.id, tokens.id_token);
+    }
+    function scheduleRefresh(expiresIn) {
+        if (refreshTimer !== null)
+            clearTimeout(refreshTimer);
+        const delayMs = Math.max(expiresIn * 0.8, expiresIn - 60) * 1000;
+        refreshTimer = setTimeout(() => {
+            void refreshAccessToken().catch(() => {
+                /* re-auth on next action */
+            });
+        }, delayMs);
+    }
     async function refreshAccessToken() {
         const rt = getRefreshToken();
         if (!rt)
             throw new Error("No refresh token stored");
         const tokens = await client.refreshTokens(config.clientId, rt);
         storeTokens(tokens, rt);
-        scheduleRefresh(tokens.expires_in ?? 3600, refreshAccessToken);
+        scheduleRefresh(tokens.expires_in ?? 3600);
     }
     return {
         async startLogin() {
@@ -72,15 +102,15 @@ export function createHearthAuth(client, config) {
                 clientId: config.clientId,
                 redirectUri: config.redirectUri,
             });
-            sessionStorage.setItem(VERIFIER_KEY, codeVerifier);
-            sessionStorage.setItem(STATE_KEY, state);
+            store.setItem(key.verifier, codeVerifier);
+            store.setItem(key.state, state);
             window.location.href = url;
         },
         async handleCallback(_code, state) {
-            const storedState = sessionStorage.getItem(STATE_KEY);
-            const codeVerifier = sessionStorage.getItem(VERIFIER_KEY) ?? undefined;
-            sessionStorage.removeItem(STATE_KEY);
-            sessionStorage.removeItem(VERIFIER_KEY);
+            const storedState = store.getItem(key.state);
+            const codeVerifier = store.getItem(key.verifier) ?? undefined;
+            store.removeItem(key.state);
+            store.removeItem(key.verifier);
             if (storedState !== state)
                 throw new Error("State mismatch — possible CSRF");
             const tokens = await client.handleCallback({
@@ -90,7 +120,7 @@ export function createHearthAuth(client, config) {
                 codeVerifier,
             });
             storeTokens(tokens);
-            scheduleRefresh(tokens.expires_in ?? 3600, refreshAccessToken);
+            scheduleRefresh(tokens.expires_in ?? 3600);
         },
         refreshAccessToken,
         async logout() {
@@ -104,6 +134,11 @@ export function createHearthAuth(client, config) {
                 params.set("id_token_hint", idToken);
             window.location.href = `${end}?${params}`;
         },
+        getAccessToken: () => accessToken,
+        getRefreshToken,
+        getIdToken,
+        isAuthenticated: () => accessToken !== null && expiresAt !== null && Date.now() / 1000 < expiresAt,
+        clearTokens,
     };
 }
 //# sourceMappingURL=browser-auth.js.map

package/dist/browser-auth.js.map

@@ -1 +1 @@
-{"version":3,"file":"browser-auth.js","sourceRoot":"","sources":["../src/browser-auth.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"browser-auth.js","sourceRoot":"","sources":["../src/browser-auth.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAyBvC,0DAA0D;AAC1D,MAAM,cAAc,GAAG,SAAS,CAAC;AAEjC,0EAA0E;AAC1E,MAAM,yBAAyB,GAAG,CAAC,sBAAsB,EAAE,iBAAiB,CAAC,CAAC;AAE9E,SAAS,aAAa;IACpB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAkB,CAAC;IACvC,OAAO;QACL,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI;QACvC,OAAO,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE;YACtB,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACvB,CAAC;QACD,UAAU,EAAE,CAAC,GAAG,EAAE,EAAE;YAClB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACnB,CAAC;KACF,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CAAC,MAA+B;IACrD,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,gBAAgB;QAAE,OAAO,cAAc,CAAC;IAC/E,IAAI,MAAM,KAAK,cAAc;QAAE,OAAO,YAAY,CAAC;IACnD,IAAI,MAAM,KAAK,QAAQ;QAAE,OAAO,aAAa,EAAE,CAAC;IAChD,OAAO,MAAM,CAAC;AAChB,CAAC;AA8CD;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAuB,EAAE,MAAkB;IAC1E,MAAM,KAAK,GAAG,cAAc,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAG,MAAM,CAAC,gBAAgB,IAAI,cAAc,CAAC;IACzD,MAAM,GAAG,GAAG;QACV,OAAO,EAAE,GAAG,MAAM,eAAe;QACjC,EAAE,EAAE,GAAG,MAAM,UAAU;QACvB,QAAQ,EAAE,GAAG,MAAM,eAAe;QAClC,KAAK,EAAE,GAAG,MAAM,aAAa;KAC9B,CAAC;IAEF,IAAI,OAAO,YAAY,KAAK,WAAW,EAAE,CAAC;QACxC,MAAM,OAAO,GAAa,KAAK,KAAK,YAAY,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9E,KAAK,MAAM,MAAM,IAAI,yBAAyB,EAAE,CAAC;YAC/C,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;gBAAE,YAAY,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;QACjE,CAAC;IACH,CAAC;IAED,IAAI,WAAW,GAAkB,IAAI,CAAC;IACtC,IAAI,SAAS,GAAkB,IAAI,CAAC;IACpC,IAAI,YAAY,GAAyC,IAAI,CAAC;IAE9D,SAAS,eAAe;QACtB,OAAO,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC;IAED,SAAS,UAAU;QACjB,OAAO,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC/B,CAAC;IAED,SAAS,WAAW;QAClB,WAAW,GAAG,IAAI,CAAC;QACnB,SAAS,GAAG,IAAI,CAAC;QACjB,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAC9B,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACzB,IAAI,YAAY,KAAK,IAAI,EAAE,CAAC;YAC1B,YAAY,CAAC,YAAY,CAAC,CAAC;YAC3B,YAAY,GAAG,IAAI,CAAC;QACtB,CAAC;IACH,CAAC;IAED,SAAS,WAAW,CAAC,MAAqB,EAAE,eAAwB;QAClE,WAAW,GAAG,MAAM,CAAC,YAAY,CAAC;QAClC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,UAAU,IAAI,IAAI,CAAC,CAAC;QAC5D,MAAM,EAAE,GAAG,MAAM,CAAC,aAAa,IAAI,eAAe,CAAC;QACnD,IAAI,EAAE;YAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QACvC,IAAI,MAAM,CAAC,QAAQ;YAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC9D,CAAC;IAED,SAAS,eAAe,CAAC,SAAiB;QACxC,IAAI,YAAY,KAAK,IAAI;YAAE,YAAY,CAAC,YAAY,CAAC,CAAC;QACtD,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,GAAG,GAAG,EAAE,SAAS,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC;QACjE,YAAY,GAAG,UAAU,CAAC,GAAG,EAAE;YAC7B,KAAK,kBAAkB,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE;gBACnC,4BAA4B;YAC9B,CAAC,CAAC,CAAC;QACL,CAAC,EAAE,OAAO,CAAC,CAAC;IACd,CAAC;IAED,KAAK,UAAU,kBAAkB;QAC/B,MAAM,EAAE,GAAG,eAAe,EAAE,CAAC;QAC7B,IAAI,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;QACpD,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QAC/D,WAAW,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACxB,eAAe,CAAC,MAAM,CAAC,UAAU,IAAI,IAAI,CAAC,CAAC;IAC7C,CAAC;IAED,OAAO;QACL,KAAK,CAAC,UAAU;YACd,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,YAAY,EAAE,GAAG,MAAM,UAAU,CAAC,MAAM,EAAE;gBAC5D,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,WAAW,EAAE,MAAM,CAAC,WAAW;aAChC,CAAC,CAAC;YACH,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;YAC1C,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;YAChC,MAAM,CAAC,QAAQ,CAAC,IAAI,GAAG,GAAG,CAAC;QAC7B,CAAC;QAED,KAAK,CAAC,cAAc,CAAC,KAAa,EAAE,KAAa;YAC/C,MAAM,WAAW,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YAC7C,MAAM,YAAY,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,SAAS,CAAC;YAC9D,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YAC5B,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YAC/B,IAAI,WAAW,KAAK,KAAK;gBAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;YAC7E,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,cAAc,CAAC;gBACzC,WAAW,EAAE,MAAM,CAAC,QAAQ,CAAC,IAAI;gBACjC,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,WAAW,EAAE,MAAM,CAAC,WAAW;gBAC/B,YAAY;aACb,CAAC,CAAC;YACH,WAAW,CAAC,MAAM,CAAC,CAAC;YACpB,eAAe,CAAC,MAAM,CAAC,UAAU,IAAI,IAAI,CAAC,CAAC;QAC7C,CAAC;QAED,kBAAkB;QAElB,KAAK,CAAC,MAAM;YACV,MAAM,OAAO,GAAG,UAAU,EAAE,CAAC;YAC7B,WAAW,EAAE,CAAC;YACd,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,SAAS,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;YACvD,MAAM,GAAG,GACN,GAAG,EAAE,CAAC,sBAAsB,CAAwB;gBACrD,GAAG,MAAM,CAAC,SAAS,WAAW,MAAM,CAAC,SAAS,cAAc,CAAC;YAC/D,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,EAAE,wBAAwB,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;YACzF,IAAI,OAAO;gBAAE,MAAM,CAAC,GAAG,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;YAClD,MAAM,CAAC,QAAQ,CAAC,IAAI,GAAG,GAAG,GAAG,IAAI,MAAM,EAAE,CAAC;QAC5C,CAAC;QAED,cAAc,EAAE,GAAG,EAAE,CAAC,WAAW;QACjC,eAAe;QACf,UAAU;QACV,eAAe,EAAE,GAAG,EAAE,CACpB,WAAW,KAAK,IAAI,IAAI,SAAS,KAAK,IAAI,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,GAAG,SAAS;QAC7E,WAAW;KACZ,CAAC;AACJ,CAAC"}

package/dist/generated/admin/schema.d.ts

@@ -1055,6 +1055,8 @@ export interface components {
             name: string;
             slug: string;
             description: string | null;
+            /** @description Declared in hearth.yaml; the admin API cannot change or delete it. */
+            yaml_managed: boolean;
             /**
              * Format: int64
              * @description Microseconds since the Unix epoch.

package/dist/hearth-client.d.ts

@@ -14,6 +14,14 @@ export interface HearthClientConfig {
      * Required for flows that need a client identity (e.g. introspection).
      */
     clientId?: string;
+    /**
+     * Expected `aud` of the access tokens {@link HearthClient.verifyToken}
+     * accepts: the name of this API (RFC 9068 §4), not the client ID.
+     * Default: `"hearth"`, the audience Hearth mints when a client names no
+     * resource. An API registered as a protected resource sets its resource URI.
+     * The check is always on.
+     */
+    audience?: string;
     /**
      * OAuth 2.0 client secret.
      * Required for confidential client flows (e.g. introspection).
@@ -77,6 +85,8 @@ export declare class HearthClient {
     readonly issuerUrl: string;
     readonly clientId: string | undefined;
     readonly clientSecret: string | undefined;
+    /** Expected `aud` of verified access tokens. Default `"hearth"`. */
+    readonly audience: string;
     readonly jwksTtl: number | undefined;
     readonly introspectionEndpointOverride: string | undefined;
     /** HTTP timeout in milliseconds applied to all outbound fetch calls. */
@@ -160,14 +170,16 @@ export declare class HearthClient {
      * 2. `exp` claim (rejects expired tokens).
      * 3. `nbf` claim (rejects post-dated tokens).
      * 4. `iss` claim (must match configured `issuerUrl`).
-     * 5. `aud` claim (validated when `clientId` is set in config).
+     * 5. `aud` claim (must contain the configured `audience`, default `"hearth"`).
+     * 6. `iat` claim (rejects a token issued in the future).
      *
-     * `exp` and `nbf` allow a 5-second clock skew.
+     * `exp`, `nbf` and `iat` allow a 5-second clock skew.
      *
      * @throws {@link TokenExpiredError} — token is expired.
+     * @throws {@link TokenNotYetValidError} — `nbf` or `iat` is in the future.
      * @throws {@link TokenInvalidError} — signature invalid or JWT malformed.
      * @throws {@link TokenIssuerError} — issuer does not match `issuerUrl`.
-     * @throws {@link TokenAudienceError} — audience does not include `clientId`.
+     * @throws {@link TokenAudienceError} — audience does not include `audience`.
      * @throws {@link JWKSFetchError} — JWKS endpoint unreachable.
      */
     verifyToken(token: string): Promise<Claims>;