@hearth-auth/sdk 0.0.1 → 1.0.1

package/src/jwks-client.ts

@@ -1,45 +0,0 @@
-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 class JwksClient {
-  private readonly jwksUri: string;
-  readonly ttl: number | undefined;
-  readonly httpTimeout: number;
-
-  constructor(config: JwksClientConfig) {
-    this.jwksUri = config.jwksUri;
-    this.ttl = config.ttl;
-    this.httpTimeout = config.httpTimeout ?? 10_000;
-  }
-
-  /** Fetch the current JWKS keys from the endpoint. */
-  async fetchKeys(): Promise<JsonWebKey[]> {
-    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()) as { keys: JsonWebKey[] };
-    return doc.keys;
-  }
-}

package/src/middleware.ts

@@ -1,82 +0,0 @@
-import { decodeJwt } from "jose";
-import { AuthorizationModeMismatchError } from "./errors.js";
-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 function requirePermission(
-  permission: string,
-  opts: RequirePermissionOptions,
-): PermissionChecker {
-  const { mode, client, organizationId, resource } = opts;
-
-  switch (mode) {
-    case "embedded":
-      return async (token: string): Promise<boolean> => {
-        let claims: Record<string, unknown> | null = null;
-        try {
-          claims = decodeJwt(token) as Record<string, unknown>;
-        } catch {
-          return false;
-        }
-        const perms = claims["permissions"];
-        return Array.isArray(perms) && perms.includes(permission);
-      };
-
-    case "decision":
-      return async (token: string): Promise<boolean> =>
-        client.authorize(token, permission, { organizationId, resource });
-
-    case "introspection":
-      return async (token: string): Promise<boolean> => {
-        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)
-        );
-      };
-  }
-}

package/src/pkce.ts

@@ -1,129 +0,0 @@
-/** 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 function generateCodeVerifier(): string {
-  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: string): Promise<string> {
-  const data = new TextEncoder().encode(verifier);
-  const hash = await crypto.subtle.digest("SHA-256", data);
-  return base64urlEncode(new Uint8Array(hash));
-}
-
-/** 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 function buildAuthorizationUrl(
-  opts: BuildAuthorizationUrlOptions,
-): AuthorizationUrlResult {
-  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 };
-}
-
-/** 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 async function startLogin(
-  client: DiscoverySource,
-  opts: StartLoginOptions,
-): Promise<StartLoginResult> {
-  const doc = await client.discovery();
-  const authorizationEndpoint = doc["authorization_endpoint"] as string | undefined;
-  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(): string {
-  const bytes = new Uint8Array(16);
-  crypto.getRandomValues(bytes);
-  return base64urlEncode(bytes);
-}
-
-function base64urlEncode(input: Uint8Array): string {
-  let binary = "";
-  for (const byte of input) {
-    binary += String.fromCharCode(byte);
-  }
-  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
-}

package/src/react.tsx

@@ -1,57 +0,0 @@
-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 const HearthContext = React.createContext<HearthFacade | null>(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 function HearthProvider(props: HearthProviderProps): React.ReactElement {
-  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: string): boolean {
-  const client = React.useContext(HearthContext);
-  return client !== null && client.hasPermission(permission);
-}
-
-/** Returns `true` iff the JWT `roles` claim contains `role`. */
-export function useHasRole(role: string): boolean {
-  const client = React.useContext(HearthContext);
-  return client !== null && client.hasRole(role);
-}
-
-/** Returns `true` iff the JWT `groups` claim contains `group`. */
-export function useInGroup(group: string): boolean {
-  const client = React.useContext(HearthContext);
-  return client !== null && client.inGroup(group);
-}
-
-/** Returns `true` iff the JWT `oid` claim equals `org`. */
-export function useInOrg(org: string): boolean {
-  const client = React.useContext(HearthContext);
-  return client !== null && client.inOrg(org);
-}

package/src/session-version-cache.ts

@@ -1,167 +0,0 @@
-import type { SessionVersionConfig } from "./types.js";
-import {
-  SessionVersionCacheStaleError,
-  SessionVersionRevokedError,
-} from "./errors.js";
-
-interface SnapshotResponse {
-  realm: string;
-  current_seq: number;
-  versions: Record<string, number>;
-}
-
-interface DeltaEntry {
-  seq: number;
-  session_id: string;
-  min_sv: number;
-  bumped_at: number;
-}
-
-interface DeltaFeedResponse {
-  realm: string;
-  next_seq: number;
-  deltas: DeltaEntry[];
-}
-
-/**
- * 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 {
-  private readonly baseUrl: string;
-  private readonly realmId: string;
-  private readonly cfg: SessionVersionConfig;
-  private readonly versions = new Map<string, bigint>();
-  private lastRefreshed = 0;
-  private seq = 0;
-  private pollTimer: ReturnType<typeof setTimeout> | null = null;
-
-  constructor(baseUrl: string, realmId: string, cfg: SessionVersionConfig) {
-    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(): void {
-    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(): void {
-    if (this.pollTimer !== null) {
-      clearTimeout(this.pollTimer);
-      this.pollTimer = null;
-    }
-  }
-
-  /** Returns milliseconds since the cache was last successfully refreshed. */
-  age(): number {
-    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: bigint | undefined, sessionId: string | undefined): void {
-    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 ─────────────────────────────────────────────────────────────────
-
-  private async fetchSnapshot(): Promise<void> {
-    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()) as SnapshotResponse;
-    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();
-  }
-
-  private schedulePoll(): void {
-    this.pollTimer = setTimeout(() => {
-      void this.poll()
-        .catch(() => undefined)
-        .finally(() => this.schedulePoll());
-    }, this.cfg.pollIntervalMs);
-  }
-
-  private async poll(): Promise<void> {
-    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()) as DeltaFeedResponse;
-    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();
-  }
-}

package/src/types.ts

@@ -1,188 +0,0 @@
-/** Response from the dev bootstrap endpoint. */
-export interface BootstrapResponse {
-  realm_id: string;
-  user_id: string;
-  access_token: string;
-  refresh_token: string;
-}
-
-/** Parameters for initiating an authorization code flow. */
-export interface AuthorizeParams {
-  clientId: string;
-  redirectUri: string;
-  scope: string;
-  state: string;
-  responseType?: string;
-  userId: string;
-  codeChallenge?: string;
-  codeChallengeMethod?: string;
-  nonce?: string;
-}
-
-/** Response from the authorize endpoint. */
-export interface AuthorizeResponse {
-  code: string;
-  state: string;
-}
-
-/** Parameters for exchanging an authorization code. */
-export interface TokenExchangeParams {
-  clientId: string;
-  code: string;
-  redirectUri: string;
-  codeVerifier?: string;
-}
-
-/** Response from the token exchange endpoint. */
-export interface TokenResponse {
-  access_token: string;
-  id_token: string;
-  token_type: string;
-  expires_in: number;
-  refresh_token: string;
-}
-
-/** UserInfo response from the OIDC UserInfo endpoint. */
-export interface UserInfoResponse {
-  sub: string;
-  name?: string;
-  email?: string;
-  email_verified?: boolean;
-}
-
-/** Parameters for creating a user. */
-export interface CreateUserParams {
-  email: string;
-  displayName: string;
-}
-
-/** User record from the API. */
-export interface User {
-  id: string;
-  email: string;
-  display_name: string;
-  status: string;
-  created_at?: number;
-  updated_at?: number;
-}
-
-/** Parameters for updating a user. */
-export interface UpdateUserParams {
-  email?: string;
-  displayName?: string;
-  status?: string;
-}
-
-/** Parameters for creating a realm. */
-export interface CreateRealmParams {
-  name: string;
-  config?: Record<string, unknown>;
-}
-
-/** Realm record from the API. */
-export interface Realm {
-  id: string;
-  name: string;
-  status: string;
-  config: Record<string, unknown> | null;
-  created_at?: number;
-  updated_at?: number;
-}
-
-/** Parameters for updating a realm. */
-export interface UpdateRealmParams {
-  name?: string;
-  status?: string;
-  config?: Record<string, unknown>;
-}
-
-/** Paginated list response. */
-export interface PageResponse<T> {
-  items: T[];
-  next_cursor: string | null;
-}
-
-/** Parameters for registering an OAuth client. */
-export interface RegisterClientParams {
-  clientName: string;
-  redirectUris: string[];
-}
-
-/** OAuth client record from the API. */
-export interface OAuthClient {
-  client_id: string;
-  client_name: string;
-  redirect_uris: string[];
-  grant_types: string[];
-  created_at?: number;
-}
-
-/** JWKS document containing public keys. */
-export interface JwksDocument {
-  keys: JsonWebKey[];
-}
-
-/** A single JWK entry. */
-export interface JsonWebKey {
-  kty: string;
-  crv?: string;
-  x?: string;
-  kid?: string;
-  use?: string;
-  alg?: string;
-}
-
-/**
- * Response from `GET /v1/me/permissions`.
- *
- * Returns the freshly-resolved RBAC claim set for the bearer-token user.
- */
-export interface MePermissionsResponse {
-  roles: string[];
-  groups: string[];
-  permissions: string[];
-  scope: string;
-}
-
-/** The three permission delivery modes introduced in HEA-922. */
-export type AccessTokenAuthorizationMode = "embedded" | "introspection" | "decision";
-
-/** Options for a per-request permission decision call to `POST /oauth/authorize`. */
-export interface AuthorizePermissionOptions {
-  /** Constrain the decision to a specific organization. */
-  organizationId?: string;
-  /** Constrain the decision to a specific resource. */
-  resource?: string;
-}
-
-/**
- * Configuration for the client-side session-version cache (RFC HEA-930 § 13).
- *
- * When enabled, the SDK fetches a snapshot of `{sessionId → minSv}` on startup,
- * polls `GET /oauth/session-versions` for deltas at `pollIntervalMs` intervals,
- * and validates the `sv` claim on every `hasPermission` / `hasRole` / `inGroup`
- * / `inOrg` call without any per-request network hop.
- */
-export interface SessionVersionConfig {
-  /** Whether session-version validation is enabled. */
-  enabled: boolean;
-  /** Delta feed poll interval in milliseconds. Recommended: 5 000. */
-  pollIntervalMs: number;
-  /**
-   * Maximum cache age before the cache is considered stale, in milliseconds.
-   * MUST be greater than `pollIntervalMs`. Recommended: `pollIntervalMs × 3`.
-   */
-  staleThresholdMs: number;
-  /**
-   * Action when the cache exceeds `staleThresholdMs`:
-   * - `"reject"` — throw {@link SessionVersionCacheStaleError} (fail-closed).
-   * - `"introspect"` — caller should catch {@link SessionVersionCacheStaleError}
-   *   and fall back to the introspection endpoint.
-   */
-  onStale: "reject" | "introspect";
-  /**
-   * Service-to-service access token with `hearth.sv_feed` scope.
-   * Required when `enabled` is `true`.
-   */
-  serviceToken: string;
-}