@hearth-auth/node 1.0.19 → 1.1.0

package/README.md

@@ -0,0 +1,320 @@
+# Hearth Node.js SDK
+
+> **SDK Specification:** This SDK must conform to the [Hearth SDK Common Specification](../../docs/specs/SDK.md).
+
+Server-side Node.js client for [Hearth](https://github.com/hearth-auth/hearth). Covers JWT verification, token introspection, Express/Fastify middleware, and the Admin API.
+
+**Use this SDK when:** you are building a Node.js server that must verify Hearth-issued tokens or enforce permission checks on incoming requests.
+
+**Use [`@hearth-auth/sdk`](../typescript/README.md) instead when:** you need a browser/React integration, PKCE authorization-code flow, or React hooks (`useHasPermission`, `HearthProvider`).
+
+---
+
+## Installation
+
+```bash
+npm install @hearth-auth/node
+# or
+yarn add @hearth-auth/node
+# or
+pnpm add @hearth-auth/node
+```
+
+| SDK version | Minimum Node.js | Minimum Hearth server |
+|-------------|-----------------|----------------------|
+| 1.0.x       | 18.0.0          | 1.0.0                |
+
+**Peer dependencies:** none. The SDK ships `jose` as a direct dependency for JWKS verification.
+
+---
+
+## Quick start
+
+```typescript
+import { HearthClient } from "@hearth-auth/node";
+
+const client = new HearthClient({
+  issuer_url: "https://hearth.example.com",
+  client_id: process.env.HEARTH_CLIENT_ID,      // required for audience validation
+  client_secret: process.env.HEARTH_CLIENT_SECRET, // required for introspection/Decision mode
+});
+
+// Verify an incoming Bearer token (JWKS-based, local, no network on cache hit)
+const token = await client.verifyToken(rawToken);
+// use your logger — avoid logging sub/email to stdout (PII in container logs)
+console.log("Has permission:", token.hasPermission("docs.write"));
+```
+
+`HearthClient` auto-discovers all endpoint URLs from `{issuer_url}/.well-known/openid-configuration` on first use.
+
+---
+
+## Token verification
+
+> **Audience validation:** always supply `client_id`. Without it the SDK has no audience to
+> compare the JWT `aud` claim against, leaving the server open to token-confusion attacks
+> (RFC 7519 §4.1.3). Omit `client_id` only when this server intentionally accepts tokens
+> issued for any client (e.g. a pure gateway that delegates authz downstream).
+
+```typescript
+import { HearthClient, TokenExpiredError, TokenInvalidError } from "@hearth-auth/node";
+
+const client = new HearthClient({
+  issuer_url: "https://hearth.example.com",
+  client_id: process.env.HEARTH_CLIENT_ID, // enables JWT `aud` validation
+});
+
+try {
+  const token = await client.verifyToken(rawToken);
+  // token is a VerifiedToken — typed access to all claims
+  token.subject();                           // JWT `sub`
+  token.issuer();                            // JWT `iss`
+  token.expiry();                            // Date | null
+  token.hasRole("admin");                    // reads `roles` claim
+  token.hasPermission("docs.write");         // reads `permissions` claim
+  token.inGroup("engineering");              // reads `groups` claim
+  token.inOrg("org_acme");                   // reads `oid` claim
+} catch (err) {
+  if (err instanceof TokenExpiredError) {
+    // 401 — ask client to refresh
+  } else if (err instanceof TokenInvalidError) {
+    // 401 — reject the request
+  }
+}
+```
+
+JWKS keys are cached by `kid`. On a cache miss the SDK re-fetches the JWKS once before
+failing — this handles transparent key rotation. Call `client.invalidateCache()` after
+receiving a `401` from a downstream service to force a re-fetch.
+
+---
+
+## Express middleware
+
+```typescript
+import express from "express";
+import { hearthMiddleware } from "@hearth-auth/node";
+
+const app = express();
+
+// Protect all routes — embedded mode (JWKS only, no network per request)
+app.use(
+  hearthMiddleware({
+    issuer_url: "https://hearth.example.com",
+    expectedMode: "embedded",
+  })
+);
+
+// Access the verified token downstream via req.hearthToken
+app.get("/me", (req, res) => {
+  res.json({ sub: req.hearthToken?.subject() });
+});
+
+// Require a specific permission on a single route
+app.post(
+  "/docs",
+  hearthMiddleware({
+    issuer_url: "https://hearth.example.com",
+    expectedMode: "embedded",
+    requiredPermission: "docs.write",
+  }),
+  docsHandler
+);
+```
+
+The middleware responds `401 Unauthorized` with `WWW-Authenticate: Bearer realm="hearth"` on
+missing or invalid tokens, and `403 Forbidden` on scope/role/permission failures. It never
+calls `next` on auth failure.
+
+---
+
+## Fastify hook
+
+```typescript
+import Fastify from "fastify";
+import { hearthFastifyHook } from "@hearth-auth/node";
+
+const app = Fastify();
+
+app.addHook(
+  "onRequest",
+  hearthFastifyHook({
+    issuer_url: "https://hearth.example.com",
+    expectedMode: "embedded",
+    requiredRole: "admin",
+  })
+);
+```
+
+The hook calls `reply.code(401).send(...)` on missing or invalid tokens and
+`reply.code(403).send(...)` on permission failures. It always calls `reply.hijack()` on
+failure so no downstream handler runs. It never resolves to `next` on auth failure.
+
+---
+
+## Permission delivery modes
+
+Hearth supports three modes for how RBAC data reaches your resource server. The mode must
+match the `access_token_authorization` setting on the registered OAuth client.
+
+| Mode | Strategy | Network per request |
+|------|----------|-------------------|
+| `embedded` (default) | RBAC claims baked into JWT at issuance; verify via JWKS | None |
+| `introspection` | Call `POST /introspect`; server re-resolves live RBAC | 1 |
+| `decision` | Call `POST /oauth/authorize`; server returns `allowed` | 1 |
+
+> **Design constraint:** the SDK never infers mode from whether `permissions` is present in
+> the token. Declare `expectedMode` explicitly; absence of `permissions` in `embedded` mode
+> means the user has no permissions, not that a different mode should be tried.
+
+### Introspection mode
+
+```typescript
+import { HearthClient } from "@hearth-auth/node";
+
+const client = new HearthClient({
+  issuer_url: "https://hearth.example.com",
+  client_id: "<resource-server-client-id>",
+  client_secret: process.env.RS_SECRET,
+});
+
+const result = await client.introspect(rawToken);
+if (result.active) {
+  console.log("Live permissions:", result.extra?.permissions);
+}
+```
+
+Or via middleware:
+
+```typescript
+app.use(
+  hearthMiddleware({
+    issuer_url: "https://hearth.example.com",
+    client_id: "<resource-server-client-id>",
+    client_secret: process.env.RS_SECRET,
+    expectedMode: "introspection",
+    requiredPermission: "docs.write",
+  })
+);
+```
+
+### Decision mode
+
+```typescript
+const result = await client.authorize(rawToken, "docs.write");
+if (result.allowed) {
+  // proceed
+}
+```
+
+Decision mode is fail-closed: network errors return `{ allowed: false }`.
+
+---
+
+## Token introspection (RFC 7662)
+
+```typescript
+const result = await client.introspect(rawToken);
+// result.active         — boolean
+// result.sub            — string (when active)
+// result.exp, iat, iss  — standard claims
+// result.scope          — space-delimited string
+// result.extra          — all non-standard claims (includes roles, permissions, groups)
+```
+
+Introspection results are **never cached** — per RFC 7662, token state can change at any time.
+
+Introspection mode is fail-closed: network errors or non-2xx responses from the introspection
+endpoint cause the middleware to respond `401 Unauthorized`. The request is never forwarded to
+the route handler on an indeterminate result.
+
+---
+
+## Admin API
+
+```typescript
+import { AdminClient } from "@hearth-auth/node";
+
+const admin = new AdminClient({
+  base_url: "https://hearth.example.com",
+  realm_id: "<realm-id>",
+  access_token: adminToken, // must carry hearth.admin permission
+});
+
+// Users
+const user = await admin.createUser({ email: "alice@example.com", display_name: "Alice" });
+const page = await admin.listUsers({ limit: 50 });
+// page.items: User[], page.next_cursor: string | null
+await admin.deleteUser(user.id);
+
+// Realms
+const realm = await admin.createRealm({ name: "acme-corp" });
+await admin.deleteRealm(realm.id);
+```
+
+---
+
+## Error types
+
+All SDK errors extend `HearthError`. Import typed errors for precise handling:
+
+| Error | When thrown |
+|-------|-------------|
+| `ConfigurationError` | Missing required config (e.g. `client_secret` needed for introspection) |
+| `DiscoveryError` | OIDC discovery endpoint unreachable or returned invalid JSON |
+| `JWKSFetchError` | JWKS endpoint unreachable or returned invalid response |
+| `TokenExpiredError` | `exp` claim is in the past |
+| `TokenNotYetValidError` | `nbf` claim is in the future |
+| `TokenInvalidError` | Signature invalid, malformed JWT |
+| `TokenIssuerError` | `iss` mismatch |
+| `TokenAudienceError` | `aud` does not contain expected audience |
+| `IntrospectionError` | Introspection endpoint unreachable or returned error |
+| `RequiredActionError` | Token `token_type` is `"required_action"` |
+| `AuthorizationModeError` | Server echoed a mode that differs from `expectedMode` |
+| `AdminHttpError` | Admin API returned non-2xx |
+
+```typescript
+import { HearthClient, TokenExpiredError, RequiredActionError } from "@hearth-auth/node";
+
+const client = new HearthClient({
+  issuer_url: "https://hearth.example.com",
+  client_id: process.env.HEARTH_CLIENT_ID,
+});
+
+try {
+  const token = await client.verifyToken(rawToken);
+} catch (err) {
+  if (err instanceof RequiredActionError) {
+    // Token is valid but requires user to complete actions before using the API
+    console.log("Pending actions:", err.requiredActions); // string[]
+    // Redirect to err.redirectUri if present
+  } else if (err instanceof TokenExpiredError) {
+    // Ask client to refresh
+  }
+}
+```
+
+---
+
+## Troubleshooting
+
+**`DiscoveryError`** — verify `issuer_url` is reachable and returns a valid `/.well-known/openid-configuration`.
+
+**`JWKSFetchError`** — check network connectivity to the JWKS endpoint. The SDK re-fetches
+once on a cache miss before returning this error.
+
+**`TokenExpiredError`** — the token's `exp` claim is in the past. Ask the client to refresh.
+
+**`TokenInvalidError`** — JWT signature does not match any key in the JWKS. If the server
+recently rotated keys, call `client.invalidateCache()` and retry once.
+
+**`TokenAudienceError`** — the token's `aud` claim does not contain the configured audience.
+Verify `client_id` matches what your authorization server issues.
+
+**`AuthorizationModeError`** — the server echoed a mode different from `expectedMode`. Verify
+the `access_token_authorization` setting on the registered OAuth client matches your SDK config.
+
+**`ConfigurationError: client_secret required`** — Introspection and Decision modes require
+`client_secret`. Pass it in the `HearthClient` constructor.
+
+See [docs/specs/SDK.md](../../docs/specs/SDK.md) Section 5 for the full error taxonomy.

package/dist/client.d.ts

@@ -2,17 +2,21 @@
 import type { HearthConfig } from "./config.js";
 import type { IntrospectionResult } from "./introspect.js";
 import type { AuthorizeOptions, AuthorizeResult } from "./authorize.js";
+import type { TokenResponse, DeviceAuthorizationResponse, UserInfoResponse, MePermissionsResponse, SvSnapshotResponse, SvDeltaResponse, ExchangeCodeOptions } from "./flows.js";
 import type { VerifiedToken } from "./token.js";
 export declare class HearthClient {
     private readonly verifier;
     private readonly introspectionClient;
     private readonly authorizeClient;
     private readonly discovery;
+    private readonly flows;
     constructor(config: HearthConfig);
     /**
-     * Verify a JWT using JWKS.
-     * Supports RS256 and ES256. Validates exp, iss, aud, iat (with clock skew tolerance).
+     * Verify a JWT using JWKS-backed EdDSA/Ed25519 local signature verification (spec §2).
+     *
+     * Performs all five mandatory validation steps: signature, exp, iss, aud, iat.
      * On key miss, re-fetches the JWKS once before failing (handles key rotation).
+     * Returns typed `VerifiedToken` on success; throws a typed §5 error on failure.
      */
     verifyToken(token: string): Promise<VerifiedToken>;
     /**
@@ -32,5 +36,85 @@ export declare class HearthClient {
      * Call this after receiving a 401 from a resource server protected by the same issuer.
      */
     invalidateCache(): void;
+    /**
+     * Exchange an authorization code for tokens (RFC 6749 §4.1.3).
+     *
+     * Discovers the token endpoint from OIDC discovery. Sends credentials as
+     * `application/x-www-form-urlencoded` — never as query parameters.
+     *
+     * @param code - Authorization code from the callback URL.
+     * @param redirectUri - Same redirect_uri used in the authorization request.
+     * @param opts - Optional PKCE verifier (`codeVerifier`) for PKCE-protected flows.
+     */
+    exchangeCode(code: string, redirectUri: string, opts?: ExchangeCodeOptions): Promise<TokenResponse>;
+    /**
+     * Obtain a token using the Client Credentials grant (RFC 6749 §4.4).
+     * Required for M2M authentication (services, daemons, admin tooling).
+     *
+     * @param scope - Optional space-delimited scope string.
+     */
+    clientCredentials(scope?: string): Promise<TokenResponse>;
+    /**
+     * Begin a Device Authorization Flow (RFC 8628).
+     *
+     * Returns the `device_code`, `user_code`, `verification_uri`, and polling `interval`.
+     * Pass `device_code` and `interval` to `pollDeviceToken()` to await user approval.
+     *
+     * @param scope - Optional space-delimited scope string.
+     */
+    startDeviceFlow(scope?: string): Promise<DeviceAuthorizationResponse>;
+    /**
+     * Poll the token endpoint until the device flow completes (RFC 8628 §3.5).
+     *
+     * Resolves with `TokenResponse` on user approval.
+     * Throws `TokenExpiredError` when the device code expires.
+     * Handles `authorization_pending` and `slow_down` internally — they are not surfaced.
+     *
+     * @param deviceCode - The `device_code` from `startDeviceFlow()`.
+     * @param intervalSeconds - Initial polling interval from `startDeviceFlow().interval`.
+     */
+    pollDeviceToken(deviceCode: string, intervalSeconds: number): Promise<TokenResponse>;
+    /**
+     * Send a magic-link email for passwordless sign-in (spec §4.5.3).
+     *
+     * Always succeeds on 202 — enumeration resistant (server returns 202 whether or not
+     * the email is registered). HTTP 429 is surfaced as `OAuthFlowError`.
+     *
+     * Requires `realm_id` in `HearthConfig`.
+     *
+     * @param email - Email address to send the magic link to.
+     */
+    requestMagicLink(email: string): Promise<void>;
+    /**
+     * Fetch the OIDC userinfo claims for the bearer token (discovered endpoint).
+     *
+     * @param token - Access token whose claims to retrieve.
+     */
+    userinfo(token: string): Promise<UserInfoResponse>;
+    /**
+     * Fetch the current user's live RBAC state from `GET /v1/me/permissions`.
+     *
+     * Unlike JWT embedded claims (cached at issuance), this reflects current server-side
+     * role and group assignments.
+     *
+     * @param token - Access token of the user whose permissions to retrieve.
+     */
+    mePermissions(token: string): Promise<MePermissionsResponse>;
+    /**
+     * Fetch the full session-version snapshot (HEA-930).
+     * Returns all current `{sessionId → minSV}` pairs. Seed a local cache on startup.
+     * Requires a token with the `hearth.sv_feed` scope.
+     */
+    svSnapshot(token: string): Promise<SvSnapshotResponse>;
+    /**
+     * Fetch session-version deltas since sequence number `since` (HEA-930).
+     * Returns `null` when there are no new deltas (HTTP 204 No Content).
+     * Requires a token with the `hearth.sv_feed` scope.
+     *
+     * @param token - Service token with `hearth.sv_feed` scope.
+     * @param since - Return only events with `seq > since`.
+     * @param limit - Maximum number of deltas to return.
+     */
+    svDelta(token: string, since: number, limit?: number): Promise<SvDeltaResponse | null>;
 }
 //# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAE5E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAKhD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAE3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACxE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAsB;IAC1D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkB;gBAEhC,MAAM,EAAE,YAAY;IAQhC;;;;OAIG;IACG,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAIxD;;;OAGG;IACG,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,cAAc,GAAG,eAAe,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAI/G;;;;;OAKG;IACG,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC;IAIrG;;;OAGG;IACH,eAAe,IAAI,IAAI;CAGxB"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAE5E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAKhD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAE3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAExE,OAAO,KAAK,EACV,aAAa,EACb,2BAA2B,EAC3B,gBAAgB,EAChB,qBAAqB,EACrB,kBAAkB,EAClB,eAAe,EACf,mBAAmB,EACpB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAsB;IAC1D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkB;IAC5C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmB;gBAE7B,MAAM,EAAE,YAAY;IAShC;;;;;;OAMG;IACG,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAIxD;;;OAGG;IACG,UAAU,CACd,KAAK,EAAE,MAAM,EACb,aAAa,CAAC,EAAE,cAAc,GAAG,eAAe,GAC/C,OAAO,CAAC,mBAAmB,CAAC;IAI/B;;;;;OAKG;IACG,SAAS,CACb,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,IAAI,CAAC,EAAE,gBAAgB,GACtB,OAAO,CAAC,eAAe,CAAC;IAI3B;;;OAGG;IACH,eAAe,IAAI,IAAI;IAMvB;;;;;;;;;OASG;IACG,YAAY,CAChB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,mBAAmB,GACzB,OAAO,CAAC,aAAa,CAAC;IAIzB;;;;;OAKG;IACG,iBAAiB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAI/D;;;;;;;OAOG;IACG,eAAe,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,2BAA2B,CAAC;IAI3E;;;;;;;;;OASG;IACG,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAI1F;;;;;;;;;OASG;IACG,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMpD;;;;OAIG;IACG,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAIxD;;;;;;;OAOG;IACG,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAMlE;;;;OAIG;IACG,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAI5D;;;;;;;;OAQG;IACG,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;CAG7F"}

package/dist/client.js

@@ -4,22 +4,27 @@ import { DiscoveryClient } from "./discovery.js";
 import { JwksVerifier } from "./jwks.js";
 import { IntrospectionClient } from "./introspect.js";
 import { AuthorizeClient } from "./authorize.js";
+import { OAuthFlowsClient } from "./flows.js";
 export class HearthClient {
     verifier;
     introspectionClient;
     authorizeClient;
     discovery;
+    flows;
     constructor(config) {
         const resolved = resolveConfig(config);
         this.discovery = new DiscoveryClient(resolved.issuer_url, resolved.http_timeout);
         this.verifier = new JwksVerifier(resolved, this.discovery);
         this.introspectionClient = new IntrospectionClient(resolved, () => this.discovery.discover());
         this.authorizeClient = new AuthorizeClient(resolved);
+        this.flows = new OAuthFlowsClient(resolved, () => this.discovery.discover());
     }
     /**
-     * Verify a JWT using JWKS.
-     * Supports RS256 and ES256. Validates exp, iss, aud, iat (with clock skew tolerance).
+     * Verify a JWT using JWKS-backed EdDSA/Ed25519 local signature verification (spec §2).
+     *
+     * Performs all five mandatory validation steps: signature, exp, iss, aud, iat.
      * On key miss, re-fetches the JWKS once before failing (handles key rotation).
+     * Returns typed `VerifiedToken` on success; throws a typed §5 error on failure.
      */
     async verifyToken(token) {
         return this.verifier.verifyToken(token);
@@ -47,5 +52,106 @@ export class HearthClient {
     invalidateCache() {
         this.verifier.invalidateCache();
     }
+    // ── §4.5 OAuth Flows ───────────────────────────────────────────────────────
+    /**
+     * Exchange an authorization code for tokens (RFC 6749 §4.1.3).
+     *
+     * Discovers the token endpoint from OIDC discovery. Sends credentials as
+     * `application/x-www-form-urlencoded` — never as query parameters.
+     *
+     * @param code - Authorization code from the callback URL.
+     * @param redirectUri - Same redirect_uri used in the authorization request.
+     * @param opts - Optional PKCE verifier (`codeVerifier`) for PKCE-protected flows.
+     */
+    async exchangeCode(code, redirectUri, opts) {
+        return this.flows.exchangeCode(code, redirectUri, opts);
+    }
+    /**
+     * Obtain a token using the Client Credentials grant (RFC 6749 §4.4).
+     * Required for M2M authentication (services, daemons, admin tooling).
+     *
+     * @param scope - Optional space-delimited scope string.
+     */
+    async clientCredentials(scope) {
+        return this.flows.clientCredentials(scope);
+    }
+    /**
+     * Begin a Device Authorization Flow (RFC 8628).
+     *
+     * Returns the `device_code`, `user_code`, `verification_uri`, and polling `interval`.
+     * Pass `device_code` and `interval` to `pollDeviceToken()` to await user approval.
+     *
+     * @param scope - Optional space-delimited scope string.
+     */
+    async startDeviceFlow(scope) {
+        return this.flows.startDeviceFlow(scope);
+    }
+    /**
+     * Poll the token endpoint until the device flow completes (RFC 8628 §3.5).
+     *
+     * Resolves with `TokenResponse` on user approval.
+     * Throws `TokenExpiredError` when the device code expires.
+     * Handles `authorization_pending` and `slow_down` internally — they are not surfaced.
+     *
+     * @param deviceCode - The `device_code` from `startDeviceFlow()`.
+     * @param intervalSeconds - Initial polling interval from `startDeviceFlow().interval`.
+     */
+    async pollDeviceToken(deviceCode, intervalSeconds) {
+        return this.flows.pollDeviceToken(deviceCode, intervalSeconds);
+    }
+    /**
+     * Send a magic-link email for passwordless sign-in (spec §4.5.3).
+     *
+     * Always succeeds on 202 — enumeration resistant (server returns 202 whether or not
+     * the email is registered). HTTP 429 is surfaced as `OAuthFlowError`.
+     *
+     * Requires `realm_id` in `HearthConfig`.
+     *
+     * @param email - Email address to send the magic link to.
+     */
+    async requestMagicLink(email) {
+        return this.flows.requestMagicLink(email);
+    }
+    // ── §4 UserInfo & Permissions ──────────────────────────────────────────────
+    /**
+     * Fetch the OIDC userinfo claims for the bearer token (discovered endpoint).
+     *
+     * @param token - Access token whose claims to retrieve.
+     */
+    async userinfo(token) {
+        return this.flows.userinfo(token);
+    }
+    /**
+     * Fetch the current user's live RBAC state from `GET /v1/me/permissions`.
+     *
+     * Unlike JWT embedded claims (cached at issuance), this reflects current server-side
+     * role and group assignments.
+     *
+     * @param token - Access token of the user whose permissions to retrieve.
+     */
+    async mePermissions(token) {
+        return this.flows.mePermissions(token);
+    }
+    // ── §HEA-930 Session-version feed ─────────────────────────────────────────
+    /**
+     * Fetch the full session-version snapshot (HEA-930).
+     * Returns all current `{sessionId → minSV}` pairs. Seed a local cache on startup.
+     * Requires a token with the `hearth.sv_feed` scope.
+     */
+    async svSnapshot(token) {
+        return this.flows.svSnapshot(token);
+    }
+    /**
+     * Fetch session-version deltas since sequence number `since` (HEA-930).
+     * Returns `null` when there are no new deltas (HTTP 204 No Content).
+     * Requires a token with the `hearth.sv_feed` scope.
+     *
+     * @param token - Service token with `hearth.sv_feed` scope.
+     * @param since - Return only events with `seq > since`.
+     * @param limit - Maximum number of deltas to return.
+     */
+    async svDelta(token, since, limit) {
+        return this.flows.svDelta(token, since, limit);
+    }
 }
 //# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAG5E,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAEtD,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAIjD,MAAM,OAAO,YAAY;IACN,QAAQ,CAAe;IACvB,mBAAmB,CAAsB;IACzC,eAAe,CAAkB;IACjC,SAAS,CAAkB;IAE5C,YAAY,MAAoB;QAC9B,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;QACvC,IAAI,CAAC,SAAS,GAAG,IAAI,eAAe,CAAC,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,YAAY,CAAC,CAAC;QACjF,IAAI,CAAC,QAAQ,GAAG,IAAI,YAAY,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QAC3D,IAAI,CAAC,mBAAmB,GAAG,IAAI,mBAAmB,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC9F,IAAI,CAAC,eAAe,GAAG,IAAI,eAAe,CAAC,QAAQ,CAAC,CAAC;IACvD,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,WAAW,CAAC,KAAa;QAC7B,OAAO,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;IAC1C,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,UAAU,CAAC,KAAa,EAAE,aAAgD;QAC9E,OAAO,IAAI,CAAC,mBAAmB,CAAC,UAAU,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;IACnE,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,SAAS,CAAC,KAAa,EAAE,UAAkB,EAAE,IAAuB;QACxE,OAAO,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,CAAC,CAAC;IAC9D,CAAC;IAED;;;OAGG;IACH,eAAe;QACb,IAAI,CAAC,QAAQ,CAAC,eAAe,EAAE,CAAC;IAClC,CAAC;CACF"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/client.test.js

@@ -3,6 +3,7 @@ import { HearthClient } from "./client.js";
 import { JwksVerifier } from "./jwks.js";
 import { IntrospectionClient } from "./introspect.js";
 import { AuthorizeClient } from "./authorize.js";
+import { OAuthFlowsClient } from "./flows.js";
 import { VerifiedToken } from "./token.js";
 const CONFIG = {
     issuer_url: "https://auth.example.com",
@@ -57,4 +58,86 @@ describe("HearthClient", () => {
         expect(spy).toHaveBeenCalledOnce();
     });
 });
+// ── OAuth flow delegation ─────────────────────────────────────────────────────
+const TOKEN_RESPONSE = {
+    access_token: "eyJ.at",
+    token_type: "Bearer",
+    expires_in: 3600,
+};
+const DEVICE_RESPONSE = {
+    device_code: "dev-code",
+    user_code: "WXYZ-1234",
+    verification_uri: "https://auth.example.com/activate",
+    expires_in: 600,
+    interval: 5,
+};
+describe("HearthClient — OAuth flow delegation", () => {
+    afterEach(() => vi.restoreAllMocks());
+    it("delegates exchangeCode to OAuthFlowsClient", async () => {
+        const spy = vi.spyOn(OAuthFlowsClient.prototype, "exchangeCode").mockResolvedValue(TOKEN_RESPONSE);
+        const client = new HearthClient(CONFIG);
+        const result = await client.exchangeCode("code-abc", "https://app.local/cb", { codeVerifier: "v3r" });
+        expect(spy).toHaveBeenCalledWith("code-abc", "https://app.local/cb", { codeVerifier: "v3r" });
+        expect(result).toBe(TOKEN_RESPONSE);
+    });
+    it("delegates clientCredentials to OAuthFlowsClient", async () => {
+        const spy = vi.spyOn(OAuthFlowsClient.prototype, "clientCredentials").mockResolvedValue(TOKEN_RESPONSE);
+        const client = new HearthClient(CONFIG);
+        const result = await client.clientCredentials("openid profile");
+        expect(spy).toHaveBeenCalledWith("openid profile");
+        expect(result).toBe(TOKEN_RESPONSE);
+    });
+    it("delegates startDeviceFlow to OAuthFlowsClient", async () => {
+        const spy = vi.spyOn(OAuthFlowsClient.prototype, "startDeviceFlow").mockResolvedValue(DEVICE_RESPONSE);
+        const client = new HearthClient(CONFIG);
+        const result = await client.startDeviceFlow("openid");
+        expect(spy).toHaveBeenCalledWith("openid");
+        expect(result).toBe(DEVICE_RESPONSE);
+    });
+    it("delegates pollDeviceToken to OAuthFlowsClient", async () => {
+        const spy = vi.spyOn(OAuthFlowsClient.prototype, "pollDeviceToken").mockResolvedValue(TOKEN_RESPONSE);
+        const client = new HearthClient(CONFIG);
+        const result = await client.pollDeviceToken("dev-code", 5);
+        expect(spy).toHaveBeenCalledWith("dev-code", 5);
+        expect(result).toBe(TOKEN_RESPONSE);
+    });
+    it("delegates requestMagicLink to OAuthFlowsClient", async () => {
+        const spy = vi.spyOn(OAuthFlowsClient.prototype, "requestMagicLink").mockResolvedValue(undefined);
+        const client = new HearthClient({ ...CONFIG, realm_id: "realm1" });
+        await client.requestMagicLink("user@example.com");
+        expect(spy).toHaveBeenCalledWith("user@example.com");
+    });
+    it("delegates userinfo to OAuthFlowsClient", async () => {
+        const uiResp = { sub: "user1", email: "user@example.com" };
+        const spy = vi.spyOn(OAuthFlowsClient.prototype, "userinfo").mockResolvedValue(uiResp);
+        const client = new HearthClient(CONFIG);
+        const result = await client.userinfo("access-tok");
+        expect(spy).toHaveBeenCalledWith("access-tok");
+        expect(result).toBe(uiResp);
+    });
+    it("delegates mePermissions to OAuthFlowsClient", async () => {
+        const permResp = { roles: ["admin"], groups: [], permissions: ["docs.write"] };
+        const spy = vi.spyOn(OAuthFlowsClient.prototype, "mePermissions").mockResolvedValue(permResp);
+        const client = new HearthClient(CONFIG);
+        const result = await client.mePermissions("access-tok");
+        expect(spy).toHaveBeenCalledWith("access-tok");
+        expect(result).toBe(permResp);
+    });
+    it("delegates svSnapshot to OAuthFlowsClient", async () => {
+        const snap = { realm: "r", current_seq: 10, versions: {} };
+        const spy = vi.spyOn(OAuthFlowsClient.prototype, "svSnapshot").mockResolvedValue(snap);
+        const client = new HearthClient(CONFIG);
+        const result = await client.svSnapshot("svc-tok");
+        expect(spy).toHaveBeenCalledWith("svc-tok");
+        expect(result).toBe(snap);
+    });
+    it("delegates svDelta to OAuthFlowsClient", async () => {
+        const delta = { realm: "r", next_seq: 5, deltas: [] };
+        const spy = vi.spyOn(OAuthFlowsClient.prototype, "svDelta").mockResolvedValue(delta);
+        const client = new HearthClient(CONFIG);
+        const result = await client.svDelta("svc-tok", 3, 50);
+        expect(spy).toHaveBeenCalledWith("svc-tok", 3, 50);
+        expect(result).toBe(delta);
+    });
+});
 //# sourceMappingURL=client.test.js.map