@hearth-auth/sdk 0.0.1

package/src/hearth-client.ts

@@ -0,0 +1,288 @@
+import {
+  AuthorizationModeMismatchError,
+  ConfigurationError,
+  DiscoveryError,
+} from "./errors.js";
+import { JwksClient } from "./jwks-client.js";
+import {
+  IntrospectionClient,
+  type IntrospectionResult,
+} from "./introspection-client.js";
+import type { AccessTokenAuthorizationMode, AuthorizePermissionOptions } from "./types.js";
+
+/** Configuration for {@link HearthClient}. */
+export interface HearthClientConfig {
+  /**
+   * Root URL of the Hearth instance, e.g. `https://auth.example.com`.
+   * Required. Must be a valid HTTPS URL.
+   */
+  issuerUrl: string;
+  /**
+   * OAuth 2.0 client ID.
+   * Required for flows that need a client identity (e.g. introspection).
+   */
+  clientId?: string;
+  /**
+   * OAuth 2.0 client secret.
+   * Required for confidential client flows (e.g. introspection).
+   */
+  clientSecret?: string;
+  /**
+   * Override JWKS cache TTL in milliseconds.
+   * Default: respect `Cache-Control: max-age` from the JWKS endpoint,
+   * falling back to 5 minutes.
+   */
+  jwksTtl?: number;
+  /**
+   * Override the introspection endpoint URL discovered via OIDC discovery.
+   * When absent, the URL is taken from `introspection_endpoint` in the
+   * OIDC discovery document.
+   */
+  introspectionEndpoint?: string;
+  /**
+   * Timeout for all outbound HTTP calls in milliseconds.
+   * Default: 10 000 (10 seconds).
+   */
+  httpTimeout?: number;
+  /**
+   * Realm ID sent as `X-Realm-ID` on realm-scoped requests.
+   * Required for `authorize()` and the `requirePermission()` middleware in
+   * `decision` mode.
+   */
+  realmId?: string;
+  /**
+   * Expected access-token authorization mode for this resource server.
+   *
+   * When set, `introspect()` validates the `mode` field echoed in the
+   * introspection response and throws {@link AuthorizationModeMismatchError}
+   * if they differ.
+   */
+  expectedMode?: AccessTokenAuthorizationMode;
+}
+
+interface OidcConfiguration {
+  issuer: string;
+  jwks_uri: string;
+  introspection_endpoint?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Primary entry point for the Hearth Node.js SDK.
+ *
+ * Accepts a single configuration object, auto-discovers all endpoint URLs
+ * from `{issuerUrl}/.well-known/openid-configuration` on first use, and
+ * applies `httpTimeout` to every outbound fetch call.
+ *
+ * Lower-level access is available via {@link JwksClient} and
+ * {@link IntrospectionClient}.
+ */
+export class HearthClient {
+  /** Issuer URL, trailing slash removed. */
+  readonly issuerUrl: string;
+  readonly clientId: string | undefined;
+  readonly clientSecret: string | undefined;
+  readonly jwksTtl: number | undefined;
+  readonly introspectionEndpointOverride: string | undefined;
+  /** HTTP timeout in milliseconds applied to all outbound fetch calls. */
+  readonly httpTimeout: number;
+  /** Realm ID for realm-scoped endpoints (e.g. `/oauth/authorize`). */
+  readonly realmId: string | undefined;
+  /** Expected authorization mode; validated on `introspect()` when present. */
+  readonly expectedMode: AccessTokenAuthorizationMode | undefined;
+
+  private _discovery: OidcConfiguration | null = null;
+  private _jwksClient: JwksClient | null = null;
+  private _introspectionClient: IntrospectionClient | null = null;
+
+  constructor(config: HearthClientConfig) {
+    if (!config.issuerUrl) {
+      throw new ConfigurationError("issuerUrl is required");
+    }
+    try {
+      new URL(config.issuerUrl);
+    } catch {
+      throw new ConfigurationError(
+        `issuerUrl "${config.issuerUrl}" is not a valid URL`,
+      );
+    }
+
+    this.issuerUrl = config.issuerUrl.replace(/\/$/, "");
+    this.clientId = config.clientId;
+    this.clientSecret = config.clientSecret;
+    this.jwksTtl = config.jwksTtl;
+    this.introspectionEndpointOverride = config.introspectionEndpoint;
+    this.httpTimeout = config.httpTimeout ?? 10_000;
+    this.realmId = config.realmId;
+    this.expectedMode = config.expectedMode;
+  }
+
+  /**
+   * Fetches and caches the OIDC discovery document from
+   * `{issuerUrl}/.well-known/openid-configuration`.
+   *
+   * Throws {@link DiscoveryError} when the endpoint is unreachable,
+   * returns a non-2xx status, or returns invalid JSON.
+   */
+  async discover(): Promise<OidcConfiguration> {
+    if (this._discovery) return this._discovery;
+
+    const url = `${this.issuerUrl}/.well-known/openid-configuration`;
+    let resp: Response;
+    try {
+      resp = await fetch(url, {
+        signal: AbortSignal.timeout(this.httpTimeout),
+      });
+    } catch (err) {
+      throw new DiscoveryError(
+        `OIDC discovery endpoint unreachable: ${url}`,
+        { cause: err },
+      );
+    }
+
+    if (!resp.ok) {
+      throw new DiscoveryError(
+        `OIDC discovery returned HTTP ${resp.status}`,
+      );
+    }
+
+    let doc: OidcConfiguration;
+    try {
+      doc = (await resp.json()) as OidcConfiguration;
+    } catch (err) {
+      throw new DiscoveryError(`OIDC discovery returned invalid JSON`, {
+        cause: err,
+      });
+    }
+
+    if (!doc.jwks_uri) {
+      throw new DiscoveryError(
+        "OIDC discovery document is missing required field: jwks_uri",
+      );
+    }
+
+    this._discovery = doc;
+    return doc;
+  }
+
+  /**
+   * Returns a {@link JwksClient} bound to the `jwks_uri` discovered from
+   * the OIDC configuration. The client is created once and reused.
+   */
+  async jwksClient(): Promise<JwksClient> {
+    if (this._jwksClient) return this._jwksClient;
+    const doc = await this.discover();
+    this._jwksClient = new JwksClient({
+      jwksUri: doc.jwks_uri,
+      ttl: this.jwksTtl,
+      httpTimeout: this.httpTimeout,
+    });
+    return this._jwksClient;
+  }
+
+  /**
+   * Returns an {@link IntrospectionClient} bound to the introspection
+   * endpoint. The endpoint is taken from `introspectionEndpoint` config
+   * (if provided) or from the OIDC discovery document.
+   *
+   * Throws {@link ConfigurationError} when:
+   * - `clientId` or `clientSecret` are absent (required for introspection)
+   * - No introspection endpoint is configured or discoverable
+   */
+  async introspectionClient(): Promise<IntrospectionClient> {
+    if (this._introspectionClient) return this._introspectionClient;
+
+    if (!this.clientId || !this.clientSecret) {
+      throw new ConfigurationError(
+        "clientId and clientSecret are required for token introspection",
+      );
+    }
+
+    const endpoint =
+      this.introspectionEndpointOverride ??
+      (await this.discover()).introspection_endpoint;
+
+    if (!endpoint) {
+      throw new ConfigurationError(
+        "introspection_endpoint is not present in the OIDC discovery document " +
+          "and no introspectionEndpoint override was provided in config",
+      );
+    }
+
+    this._introspectionClient = new IntrospectionClient({
+      introspectionEndpoint: endpoint,
+      clientId: this.clientId,
+      clientSecret: this.clientSecret,
+      httpTimeout: this.httpTimeout,
+    });
+    return this._introspectionClient;
+  }
+
+  /**
+   * Calls `POST {issuerUrl}/oauth/authorize` to get a per-request permission
+   * decision for the given bearer token (Decision mode, HEA-922).
+   *
+   * Requires `realmId` in config. Fail-closed: returns `false` on any network
+   * or server error so authorization cannot be accidentally granted.
+   *
+   * @throws {@link ConfigurationError} when `realmId` is not configured.
+   */
+  async authorize(
+    token: string,
+    permission: string,
+    opts?: AuthorizePermissionOptions,
+  ): Promise<boolean> {
+    if (!this.realmId) {
+      throw new ConfigurationError("realmId is required for authorize()");
+    }
+    const body: Record<string, string> = { permission };
+    if (opts?.organizationId) body["organization_id"] = opts.organizationId;
+    if (opts?.resource) body["resource"] = opts.resource;
+
+    try {
+      const resp = await fetch(`${this.issuerUrl}/oauth/authorize`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-Realm-ID": this.realmId,
+          Authorization: `Bearer ${token}`,
+        },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(this.httpTimeout),
+      });
+      if (!resp.ok) return false;
+      const data = (await resp.json()) as { allowed?: boolean };
+      return data.allowed === true;
+    } catch {
+      return false; // fail-closed on network/timeout errors
+    }
+  }
+
+  /**
+   * Introspects a token via RFC 7662 and optionally validates the echoed
+   * `mode` field against `expectedMode` from config.
+   *
+   * Throws {@link AuthorizationModeMismatchError} when `expectedMode` is set
+   * and the server echoes a different mode. This catches misconfigured
+   * deployments where the resource server and the issuing client disagree on
+   * the permission delivery strategy.
+   *
+   * @throws {@link ConfigurationError} when `clientId`/`clientSecret` are absent.
+   * @throws {@link AuthorizationModeMismatchError} on mode echo mismatch.
+   */
+  async introspect(token: string): Promise<IntrospectionResult> {
+    const ic = await this.introspectionClient();
+    const result = await ic.introspect(token);
+    if (
+      this.expectedMode !== undefined &&
+      result.mode !== undefined &&
+      result.mode !== this.expectedMode
+    ) {
+      throw new AuthorizationModeMismatchError(
+        this.expectedMode,
+        String(result.mode),
+      );
+    }
+    return result;
+  }
+}

package/src/hearth.ts

@@ -0,0 +1,224 @@
+import { decodeJwt } from "jose";
+import { HearthApiClient } from "./client.js";
+import { SessionVersionCache } from "./session-version-cache.js";
+import type { MePermissionsResponse, SessionVersionConfig } from "./types.js";
+
+/** Options for creating a {@link HearthFacade} via {@link createHearth}. */
+export interface HearthOptions {
+  /** Base URL of the Hearth server, e.g. `https://hearth.example.com`. */
+  baseUrl: string;
+  /** Realm ID to scope all requests to. */
+  realmId: string;
+  /**
+   * Called synchronously on every `hasPermission` / `hasRole` /
+   * `inGroup` / `inOrg` check. Return `null`/`undefined` when the
+   * caller is unauthenticated.
+   */
+  getToken: () => string | null | undefined;
+  /**
+   * Optional session-version cache configuration (RFC HEA-930 § 13).
+   *
+   * When `enabled: true` the SDK fetches a session-version snapshot on
+   * startup and polls the delta feed at `pollIntervalMs` intervals.
+   * Every `hasPermission` / `hasRole` / `inGroup` / `inOrg` call then
+   * validates the token's `sv` claim against the local cache — no
+   * per-request network hop required.
+   *
+   * Tokens without an `sv` claim pass through unchanged (backward compat).
+   */
+  sessionVersions?: SessionVersionConfig;
+}
+
+/**
+ * Minimum HTTP surface exposed by the facade.
+ *
+ * For the full API (auth code flow, admin, JWKS, etc.) construct a
+ * {@link HearthClient} directly.
+ */
+export interface HearthHttpClient {
+  /**
+   * Calls `GET /v1/me/permissions` and returns the freshly-resolved
+   * RBAC claim set for the current bearer token.
+   */
+  permissions(): Promise<MePermissionsResponse>;
+}
+
+/**
+ * RBAC claim-oriented facade over the Hearth SDK.
+ *
+ * When `sessionVersions` is not configured all boolean predicates are
+ * synchronous, lock-free, and decode the JWT returned by `getToken()` on
+ * every call. No network traffic, no cache. When the token is absent or
+ * malformed every predicate returns `false`.
+ *
+ * When `sessionVersions.enabled` is `true`, the predicates additionally
+ * validate the `sv` claim and may throw {@link SessionVersionRevokedError}
+ * or {@link SessionVersionCacheStaleError} (see RFC HEA-930 § 8).
+ */
+export interface HearthFacade {
+  /**
+   * Returns `true` iff the JWT `permissions` claim contains `permission`.
+   *
+   * May throw {@link SessionVersionRevokedError} or
+   * {@link SessionVersionCacheStaleError} when session-version tracking
+   * is enabled and the token's `sv` claim fails validation.
+   */
+  hasPermission(permission: string): boolean;
+  /**
+   * Returns `true` iff the JWT `roles` claim contains `role`.
+   *
+   * Same session-version throw semantics as {@link hasPermission}.
+   */
+  hasRole(role: string): boolean;
+  /**
+   * Returns `true` iff the JWT `groups` claim contains `group`.
+   *
+   * Same session-version throw semantics as {@link hasPermission}.
+   */
+  inGroup(group: string): boolean;
+  /**
+   * Returns `true` iff the JWT `oid` claim equals `org`.
+   *
+   * Same session-version throw semantics as {@link hasPermission}.
+   */
+  inOrg(org: string): boolean;
+  /**
+   * Returns the age of the session-version cache in milliseconds.
+   *
+   * Returns `Infinity` when session-version tracking is not configured or
+   * the cache has never been successfully seeded. Use this in health-check
+   * endpoints to confirm the cache is fresh before accepting requests.
+   */
+  sessionVersionCacheAge(): number;
+  /**
+   * Stops the background session-version poll loop.
+   *
+   * Call this when disposing the facade in long-running Node.js services
+   * to avoid keeping the event loop alive.
+   */
+  stop(): void;
+  /** Narrow HTTP surface for live RBAC resolution. */
+  client: HearthHttpClient;
+}
+
+interface RbacJwtClaims {
+  permissions?: unknown;
+  roles?: unknown;
+  groups?: unknown;
+  oid?: unknown;
+  /** Session version — `u64` emitted when session_version.enabled=true. */
+  sv?: unknown;
+  /** Session ID — present on all session-bearing access tokens. */
+  sid?: unknown;
+}
+
+/**
+ * Decode the middle JWT segment using `jose.decodeJwt`. Returns `null`
+ * when the token is missing, malformed, or cannot be parsed as JSON.
+ * Signature is NOT verified — the app trusts its own token.
+ */
+function safeDecode(token: string | null | undefined): RbacJwtClaims | null {
+  if (!token || typeof token !== "string") return null;
+  try {
+    return decodeJwt(token) as RbacJwtClaims;
+  } catch {
+    return null;
+  }
+}
+
+function arrayContains(claim: unknown, value: string): boolean {
+  return Array.isArray(claim) && claim.includes(value);
+}
+
+/** Extract the `sv` claim as `bigint`, or `undefined` if absent/non-numeric. */
+function extractSv(c: RbacJwtClaims): bigint | undefined {
+  if (c.sv === undefined || c.sv === null) return undefined;
+  if (typeof c.sv === "number") return BigInt(Math.trunc(c.sv));
+  if (typeof c.sv === "bigint") return c.sv;
+  return undefined;
+}
+
+/** Extract the `sid` claim as `string`, or `undefined` if absent. */
+function extractSid(c: RbacJwtClaims): string | undefined {
+  return typeof c.sid === "string" ? c.sid : undefined;
+}
+
+/**
+ * Create a {@link HearthFacade} over the RBAC claim set embedded in the
+ * JWT returned by `opts.getToken()`.
+ *
+ * When `opts.sessionVersions.enabled` is `true` the facade additionally
+ * starts a background session-version poll loop. Call `facade.stop()` to
+ * tear it down.
+ */
+export function createHearth(opts: HearthOptions): HearthFacade {
+  const http = new HearthApiClient({
+    baseUrl: opts.baseUrl,
+    realmId: opts.realmId,
+  });
+
+  let svCache: SessionVersionCache | null = null;
+  if (opts.sessionVersions?.enabled) {
+    svCache = new SessionVersionCache(
+      opts.baseUrl,
+      opts.realmId,
+      opts.sessionVersions,
+    );
+    svCache.start();
+  }
+
+  function claims(): RbacJwtClaims | null {
+    return safeDecode(opts.getToken());
+  }
+
+  /** Runs the sv check; throws on revoked or stale. No-op when sv absent. */
+  function assertSv(c: RbacJwtClaims): void {
+    if (svCache !== null) {
+      svCache.validateSv(extractSv(c), extractSid(c));
+    }
+  }
+
+  return {
+    hasPermission(permission: string): boolean {
+      const c = claims();
+      if (c === null) return false;
+      assertSv(c);
+      return arrayContains(c.permissions, permission);
+    },
+    hasRole(role: string): boolean {
+      const c = claims();
+      if (c === null) return false;
+      assertSv(c);
+      return arrayContains(c.roles, role);
+    },
+    inGroup(group: string): boolean {
+      const c = claims();
+      if (c === null) return false;
+      assertSv(c);
+      return arrayContains(c.groups, group);
+    },
+    inOrg(org: string): boolean {
+      const c = claims();
+      if (c === null) return false;
+      assertSv(c);
+      return typeof c.oid === "string" && c.oid === org;
+    },
+    sessionVersionCacheAge(): number {
+      return svCache?.age() ?? Number.POSITIVE_INFINITY;
+    },
+    stop(): void {
+      svCache?.stop();
+    },
+    client: {
+      permissions(): Promise<MePermissionsResponse> {
+        const token = opts.getToken();
+        if (!token) {
+          return Promise.reject(
+            new Error("getToken() returned no token; cannot call permissions()"),
+          );
+        }
+        return http.permissions(token);
+      },
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,106 @@
+// Primary entry point — recommended for all new integrations.
+export { HearthClient } from "./hearth-client.js";
+
+// PKCE browser utilities (RFC 7636).
+export {
+  generateCodeVerifier,
+  generateCodeChallenge,
+  buildAuthorizationUrl,
+  startLogin,
+} from "./pkce.js";
+export type {
+  BuildAuthorizationUrlOptions,
+  AuthorizationUrlResult,
+  StartLoginOptions,
+  StartLoginResult,
+} from "./pkce.js";
+export type { HearthClientConfig } from "./hearth-client.js";
+
+// Lower-level primitives (JWKS and introspection).
+export { JwksClient } from "./jwks-client.js";
+export type { JwksClientConfig } from "./jwks-client.js";
+export { IntrospectionClient } from "./introspection-client.js";
+export type {
+  IntrospectionClientConfig,
+  IntrospectionResult,
+} from "./introspection-client.js";
+
+// Error types (spec §5).
+export {
+  AuthorizationModeMismatchError,
+  ConfigurationError,
+  DiscoveryError,
+  HearthSdkError,
+  IntrospectionError,
+  JWKSFetchError,
+  RequiredActionError,
+  SessionVersionCacheStaleError,
+  SessionVersionRevokedError,
+  TokenAudienceError,
+  TokenExpiredError,
+  TokenInvalidError,
+  TokenIssuerError,
+  TokenNotYetValidError,
+} from "./errors.js";
+
+// Mode-aware middleware (HEA-923).
+export { requirePermission } from "./middleware.js";
+export type { PermissionChecker, RequirePermissionOptions } from "./middleware.js";
+
+// Claims API (spec §4).
+export { Claims } from "./claims.js";
+
+// Lower-level API client (kept for backwards-compatibility).
+export { HearthApiClient, HearthError } from "./client.js";
+export type { HearthApiClientConfig, HandleCallbackParams } from "./client.js";
+export { AdminClient } from "./admin.js";
+export { createHearth } from "./hearth.js";
+export type {
+  HearthFacade,
+  HearthHttpClient,
+  HearthOptions,
+} from "./hearth.js";
+export {
+  HearthContext,
+  HearthProvider,
+  useHasPermission,
+  useHasRole,
+  useInGroup,
+  useInOrg,
+} from "./react.js";
+export type { HearthProviderProps } from "./react.js";
+export type {
+  AccessTokenAuthorizationMode,
+  AuthorizeParams,
+  AuthorizePermissionOptions,
+  AuthorizeResponse,
+  BootstrapResponse,
+  CreateRealmParams,
+  CreateUserParams,
+  JwksDocument,
+  JsonWebKey,
+  MePermissionsResponse,
+  OAuthClient,
+  PageResponse,
+  RegisterClientParams,
+  Realm,
+  SessionVersionConfig,
+  TokenExchangeParams,
+  TokenResponse,
+  UpdateRealmParams,
+  UpdateUserParams,
+  User,
+  UserInfoResponse,
+} from "./types.js";
+export { SessionVersionCache } from "./session-version-cache.js";
+
+// Browser auth: token store + PKCE login facade for SPAs.
+export {
+  getAccessToken,
+  getRefreshToken,
+  getIdToken,
+  isAuthenticated,
+  clearTokens,
+  createHearthAuth,
+} from "./browser-auth.js";
+export type { AuthConfig, HearthBrowserAuth } from "./browser-auth.js";

package/src/introspection-client.ts

@@ -0,0 +1,83 @@
+/** RFC 7662 §2.2 — result of a token introspection request. */
+export interface IntrospectionResult {
+  /** Whether the token is currently active. */
+  active: boolean;
+  /** Subject identifier (when active). */
+  sub?: string;
+  /** Expiration time as Unix seconds (when active). */
+  exp?: number;
+  /** Issued-at time as Unix seconds (when active). */
+  iat?: number;
+  /** Issuer identifier (when active). */
+  iss?: string;
+  /** Intended audience (when active). */
+  aud?: string | string[];
+  /** Space-separated scope string (when active and present). */
+  scope?: string;
+  /** OAuth client that requested the token (when active and present). */
+  client_id?: string;
+  /**
+   * Access-token authorization mode echoed from the issuing client config.
+   * Present only when the Hearth server is HEA-922+.
+   * Values: `"embedded"` | `"introspection"` | `"decision"`.
+   */
+  mode?: string;
+  /** Live permission strings (present in introspection/decision mode). */
+  permissions?: string[];
+  /** Live role names (present in introspection/decision mode). */
+  roles?: string[];
+  /** Live group slugs (present in introspection/decision mode). */
+  groups?: string[];
+  /** All non-standard claims. */
+  [key: string]: unknown;
+}
+
+/** Configuration for {@link IntrospectionClient}. */
+export interface IntrospectionClientConfig {
+  /** RFC 7662 introspection endpoint URL. */
+  introspectionEndpoint: string;
+  /** Client ID used for HTTP Basic authentication. */
+  clientId: string;
+  /** Client secret used for HTTP Basic authentication. */
+  clientSecret: string;
+  /** Timeout for outbound HTTP calls in milliseconds. Default: 10 000. */
+  httpTimeout?: number;
+}
+
+/**
+ * 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 {
+  private readonly endpoint: string;
+  private readonly clientId: string;
+  private readonly clientSecret: string;
+  readonly httpTimeout: number;
+
+  constructor(config: IntrospectionClientConfig) {
+    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: string): Promise<IntrospectionResult> {
+    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() as Promise<IntrospectionResult>;
+  }
+}