@hearth-auth/sdk 0.0.1 → 1.0.1

package/src/hearth-client.ts

@@ -1,288 +0,0 @@
-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

@@ -1,224 +0,0 @@
-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

@@ -1,106 +0,0 @@
-// 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

@@ -1,83 +0,0 @@
-/** 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>;
-  }
-}