@hearth-auth/sdk 0.0.1 → 1.0.0

package/dist/types.d.ts

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

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,14 +1,23 @@
 {
   "name": "@hearth-auth/sdk",
-  "version": "0.0.1",
+  "version": "1.0.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hearth-auth/hearth.git",
+    "directory": "sdks/typescript"
+  },
   "type": "module",
-  "types": "./src/index.ts",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./src/index.ts",
-      "default": "./src/index.ts"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     }
   },
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "tsc",
     "test": "vitest run",

package/CHANGELOG.md

@@ -1,12 +0,0 @@
-# Changelog
-
-All notable changes to `@hearth-auth/browser` and `@hearth-auth/node` are documented here.
-
-## [Unreleased]
-
-### Changed
-- SDK brought into conformance with the [Hearth SDK Common Specification](../../docs/specs/SDK.md).
-- All 9 required error types from spec §5 are now exported.
-- Full Claims API (spec §4) implemented on verified token objects.
-- JWKS caching follows the 5-rule contract from spec §2.
-- README updated with installation, quickstart, and troubleshooting sections (spec §10).

package/src/admin.ts

@@ -1,157 +0,0 @@
-import { HearthError } from "./client.js";
-import type {
-  CreateRealmParams,
-  CreateUserParams,
-  PageResponse,
-  Realm,
-  UpdateRealmParams,
-  UpdateUserParams,
-  User,
-} from "./types.js";
-
-/**
- * Admin API client for Hearth.
- *
- * Requires a valid admin access token. All operations go through
- * the /admin/* endpoints which enforce RBAC admin role checks.
- */
-export class AdminClient {
-  constructor(
-    private readonly baseUrl: string,
-    private readonly realmId: string,
-    private readonly accessToken: string,
-  ) {}
-
-  // === Users ===
-
-  /** POST /admin/users — create a user. */
-  async createUser(params: CreateUserParams): Promise<User> {
-    return this.post("/admin/users", {
-      email: params.email,
-      display_name: params.displayName,
-    });
-  }
-
-  /** GET /admin/users — list users with pagination. */
-  async listUsers(options?: {
-    limit?: number;
-    cursor?: string;
-  }): Promise<PageResponse<User>> {
-    const q = new URLSearchParams();
-    if (options?.limit) q.set("limit", String(options.limit));
-    if (options?.cursor) q.set("cursor", options.cursor);
-    return this.get(`/admin/users?${q}`);
-  }
-
-  /** GET /admin/users/:id — get a user by ID. */
-  async getUser(userId: string): Promise<User> {
-    return this.get(`/admin/users/${userId}`);
-  }
-
-  /** PUT /admin/users/:id — update a user. */
-  async updateUser(userId: string, params: UpdateUserParams): Promise<User> {
-    return this.request("PATCH", `/admin/users/${userId}`, {
-      email: params.email,
-      display_name: params.displayName,
-      status: params.status,
-    });
-  }
-
-  /** DELETE /admin/users/:id — delete a user. */
-  async deleteUser(userId: string): Promise<void> {
-    const resp = await fetch(`${this.baseUrl}/admin/users/${userId}`, {
-      method: "DELETE",
-      headers: this.headers(),
-    });
-    if (!resp.ok) {
-      throw new HearthError(resp.status, await resp.json());
-    }
-  }
-
-  // === Realms ===
-
-  /** POST /admin/realms — create a realm. */
-  async createRealm(params: CreateRealmParams): Promise<Realm> {
-    return this.post("/admin/realms", {
-      name: params.name,
-      config: params.config,
-    });
-  }
-
-  /** GET /admin/realms — list realms with pagination. */
-  async listRealms(options?: {
-    limit?: number;
-    cursor?: string;
-  }): Promise<PageResponse<Realm>> {
-    const q = new URLSearchParams();
-    if (options?.limit) q.set("limit", String(options.limit));
-    if (options?.cursor) q.set("cursor", options.cursor);
-    return this.get(`/admin/realms?${q}`);
-  }
-
-  /** GET /admin/realms/:id — get a realm by ID. */
-  async getRealm(realmId: string): Promise<Realm> {
-    return this.get(`/admin/realms/${realmId}`);
-  }
-
-  /** PUT /admin/realms/:id — update a realm. */
-  async updateRealm(
-    realmId: string,
-    params: UpdateRealmParams,
-  ): Promise<Realm> {
-    return this.request("PATCH", `/admin/realms/${realmId}`, {
-      name: params.name,
-      status: params.status,
-      config: params.config,
-    });
-  }
-
-  /** DELETE /admin/realms/:id — delete a realm. */
-  async deleteRealm(realmId: string): Promise<void> {
-    const resp = await fetch(`${this.baseUrl}/admin/realms/${realmId}`, {
-      method: "DELETE",
-      headers: this.headers(),
-    });
-    if (!resp.ok) {
-      throw new HearthError(resp.status, await resp.json());
-    }
-  }
-
-  private headers(): Record<string, string> {
-    return {
-      "X-Realm-ID": this.realmId,
-      Authorization: `Bearer ${this.accessToken}`,
-      "Content-Type": "application/json",
-    };
-  }
-
-  private async get<T>(path: string): Promise<T> {
-    const resp = await fetch(`${this.baseUrl}${path}`, {
-      headers: this.headers(),
-    });
-    if (!resp.ok) {
-      throw new HearthError(resp.status, await resp.json());
-    }
-    return resp.json() as Promise<T>;
-  }
-
-  private async post<T>(path: string, body: unknown): Promise<T> {
-    return this.request("POST", path, body);
-  }
-
-  private async request<T>(
-    method: string,
-    path: string,
-    body: unknown,
-  ): Promise<T> {
-    const resp = await fetch(`${this.baseUrl}${path}`, {
-      method,
-      headers: this.headers(),
-      body: JSON.stringify(body),
-    });
-    if (!resp.ok) {
-      throw new HearthError(resp.status, await resp.json());
-    }
-    return resp.json() as Promise<T>;
-  }
-}

package/src/browser-auth.ts

@@ -1,130 +0,0 @@
-import { HearthApiClient } from "./client.js";
-import { startLogin } from "./pkce.js";
-import type { TokenResponse } from "./types.js";
-
-// ── Token store ─────────────────────────────────────────────────────────────
-// Access token lives in memory only. Refresh + ID tokens survive page reloads
-// via localStorage. For stricter XSS safety, swap for an HttpOnly-cookie BFF.
-
-const REFRESH_KEY = "hearth_refresh_token";
-const ID_KEY = "hearth_id_token";
-
-let _accessToken: string | null = null;
-let _expiresAt: number | null = null;
-let _refreshTimer: ReturnType<typeof setTimeout> | null = null;
-
-export function getAccessToken(): string | null { return _accessToken; }
-export function getRefreshToken(): string | null { return localStorage.getItem(REFRESH_KEY); }
-export function getIdToken(): string | null { return localStorage.getItem(ID_KEY); }
-
-/** True iff an access token is present and not yet expired. */
-export function isAuthenticated(): boolean {
-  return _accessToken !== null && _expiresAt !== null && Date.now() / 1000 < _expiresAt;
-}
-
-export function clearTokens(): void {
-  _accessToken = null;
-  _expiresAt = null;
-  localStorage.removeItem(REFRESH_KEY);
-  localStorage.removeItem(ID_KEY);
-  if (_refreshTimer !== null) { clearTimeout(_refreshTimer); _refreshTimer = null; }
-}
-
-function storeTokens(tokens: TokenResponse, fallbackRefresh?: string): void {
-  _accessToken = tokens.access_token;
-  _expiresAt = Date.now() / 1000 + (tokens.expires_in ?? 3600);
-  const rt = tokens.refresh_token ?? fallbackRefresh;
-  if (rt) localStorage.setItem(REFRESH_KEY, rt);
-  if (tokens.id_token) localStorage.setItem(ID_KEY, tokens.id_token);
-}
-
-function scheduleRefresh(expiresIn: number, doRefresh: () => Promise<void>): void {
-  if (_refreshTimer !== null) clearTimeout(_refreshTimer);
-  const delayMs = Math.max(expiresIn * 0.8, expiresIn - 60) * 1000;
-  _refreshTimer = setTimeout(() => { void doRefresh().catch(() => { /* re-auth on next action */ }); }, delayMs);
-}
-
-// ── Auth config ──────────────────────────────────────────────────────────────
-
-/** Configuration for {@link createHearthAuth}. */
-export interface AuthConfig {
-  /** OAuth 2.0 client ID. */
-  clientId: string;
-  /** Redirect URI registered for this client. */
-  redirectUri: string;
-  /** Hearth server base URL, e.g. `http://localhost:8420`. */
-  hearthUrl: string;
-  /** Realm name (slug), e.g. `"demo"`. */
-  realmSlug: string;
-}
-
-/** Auth facade returned by {@link createHearthAuth}. */
-export interface HearthBrowserAuth {
-  startLogin(): Promise<void>;
-  handleCallback(code: string, state: string): Promise<void>;
-  refreshAccessToken(): Promise<void>;
-  logout(): Promise<void>;
-}
-
-const VERIFIER_KEY = "hearth_pkce_verifier";
-const STATE_KEY = "hearth_oauth_state";
-
-/**
- * Create a browser-side Hearth auth facade backed entirely by the SDK.
- *
- * Handles the full PKCE login flow, token storage, silent refresh, and
- * RP-initiated logout. No custom crypto or OIDC endpoint logic required.
- */
-export function createHearthAuth(
-  client: HearthApiClient,
-  config: AuthConfig,
-): HearthBrowserAuth {
-  async function refreshAccessToken(): Promise<void> {
-    const rt = getRefreshToken();
-    if (!rt) throw new Error("No refresh token stored");
-    const tokens = await client.refreshTokens(config.clientId, rt);
-    storeTokens(tokens, rt);
-    scheduleRefresh(tokens.expires_in ?? 3600, refreshAccessToken);
-  }
-
-  return {
-    async startLogin(): Promise<void> {
-      const { url, state, codeVerifier } = await startLogin(client, {
-        clientId: config.clientId,
-        redirectUri: config.redirectUri,
-      });
-      sessionStorage.setItem(VERIFIER_KEY, codeVerifier);
-      sessionStorage.setItem(STATE_KEY, state);
-      window.location.href = url;
-    },
-
-    async handleCallback(_code: string, state: string): Promise<void> {
-      const storedState = sessionStorage.getItem(STATE_KEY);
-      const codeVerifier = sessionStorage.getItem(VERIFIER_KEY) ?? undefined;
-      sessionStorage.removeItem(STATE_KEY);
-      sessionStorage.removeItem(VERIFIER_KEY);
-      if (storedState !== state) throw new Error("State mismatch — possible CSRF");
-      const tokens = await client.handleCallback({
-        callbackUrl: window.location.href,
-        clientId: config.clientId,
-        redirectUri: config.redirectUri,
-        codeVerifier,
-      });
-      storeTokens(tokens);
-      scheduleRefresh(tokens.expires_in ?? 3600, refreshAccessToken);
-    },
-
-    refreshAccessToken,
-
-    async logout(): Promise<void> {
-      const idToken = getIdToken();
-      clearTokens();
-      const doc = await client.discovery().catch(() => null);
-      const end = (doc?.["end_session_endpoint"] as string | undefined)
-        ?? `${config.hearthUrl}/realms/${config.realmSlug}/end_session`;
-      const params = new URLSearchParams({ post_logout_redirect_uri: window.location.origin });
-      if (idToken) params.set("id_token_hint", idToken);
-      window.location.href = `${end}?${params}`;
-    },
-  };
-}

package/src/claims.ts

@@ -1,180 +0,0 @@
-/**
- * Spec §4 — Claims API.
- *
- * {@link Claims} wraps a decoded JWT payload and exposes typed accessors
- * for standard OIDC and Hearth-specific claims.  All reads are local —
- * no network call is made.  Signature verification is the caller's
- * responsibility (e.g. via the JWKS endpoint before constructing Claims).
- */
-
-import { decodeJwt } from "jose";
-import {
-  TokenExpiredError,
-  TokenInvalidError,
-  TokenNotYetValidError,
-} from "./errors.js";
-
-/** Raw JWT payload shape used internally. */
-interface RawPayload {
-  sub?: string;
-  iss?: string;
-  aud?: string | string[];
-  exp?: number;
-  nbf?: number;
-  iat?: number;
-  jti?: string;
-  scope?: string;
-  scopes?: string[];
-  roles?: string[];
-  permissions?: string[];
-  groups?: string[];
-  oid?: string;
-  org_groups?: string[];
-  token_type?: string;
-  [key: string]: unknown;
-}
-
-/**
- * Typed accessor for a decoded JWT's claims.
- *
- * Construct via {@link Claims.decode} (decodes without verifying signature)
- * or pass a pre-decoded payload to the constructor.
- */
-export class Claims {
-  private readonly payload: RawPayload;
-
-  constructor(payload: RawPayload) {
-    this.payload = payload;
-  }
-
-  /**
-   * Decode a JWT string into a {@link Claims} object.
-   * The signature is NOT verified — the caller must verify it separately.
-   *
-   * @throws {TokenInvalidError} if the string is not a valid JWT.
-   */
-  static decode(token: string): Claims {
-    try {
-      const payload = decodeJwt(token) as RawPayload;
-      return new Claims(payload);
-    } catch (err) {
-      throw new TokenInvalidError(
-        `Failed to decode JWT: ${err instanceof Error ? err.message : String(err)}`,
-      );
-    }
-  }
-
-  /**
-   * Assert the token is temporally valid (not expired, past nbf).
-   *
-   * @throws {TokenExpiredError} if exp is in the past.
-   * @throws {TokenNotYetValidError} if nbf is in the future.
-   */
-  assertValid(clockSkewSeconds = 0): void {
-    const now = Math.floor(Date.now() / 1000);
-    const exp = this.payload.exp;
-    if (exp !== undefined && now > exp + clockSkewSeconds) {
-      throw new TokenExpiredError(new Date(exp * 1000));
-    }
-    const nbf = this.payload.nbf;
-    if (nbf !== undefined && now < nbf - clockSkewSeconds) {
-      throw new TokenNotYetValidError(new Date(nbf * 1000));
-    }
-  }
-
-  /** The `sub` (subject) claim — identifies the principal that is the subject of the JWT. */
-  subject(): string {
-    return this.payload.sub ?? "";
-  }
-
-  /** The `iss` (issuer) claim — identifies the principal that issued the JWT. */
-  issuer(): string {
-    return this.payload.iss ?? "";
-  }
-
-  /** The `aud` (audiences) claim — normalized to an array. */
-  audiences(): string[] {
-    const aud = this.payload.aud;
-    if (!aud) return [];
-    return Array.isArray(aud) ? aud : [aud];
-  }
-
-  /** The `exp` (expiry) claim as a Date, or null if absent. */
-  expiry(): Date | null {
-    return this.payload.exp !== undefined
-      ? new Date(this.payload.exp * 1000)
-      : null;
-  }
-
-  /** The `iat` (issuedAt) claim as a Date, or null if absent. */
-  issuedAt(): Date | null {
-    return this.payload.iat !== undefined
-      ? new Date(this.payload.iat * 1000)
-      : null;
-  }
-
-  /** The `jti` (JWT ID) claim, or null if absent. */
-  jwtID(): string | null {
-    return this.payload.jti ?? null;
-  }
-
-  /** The `scope` claim split into individual scopes (or `scopes` array if present). */
-  scopes(): string[] {
-    if (this.payload.scopes) return this.payload.scopes;
-    const scope = this.payload.scope;
-    if (!scope) return [];
-    return scope.split(/\s+/).filter(Boolean);
-  }
-
-  /** Returns true iff the token contains the given scope. */
-  hasScope(scope: string): boolean {
-    return this.scopes().includes(scope);
-  }
-
-  /** Returns true iff the token's `roles` claim contains the given role. */
-  hasRole(role: string): boolean {
-    return (this.payload.roles ?? []).includes(role);
-  }
-
-  /** Returns true iff the token's `permissions` claim contains the given permission. */
-  hasPermission(permission: string): boolean {
-    return (this.payload.permissions ?? []).includes(permission);
-  }
-
-  /** The raw `scope` claim (space-delimited string), or empty string if absent. */
-  scope(): string {
-    return this.payload.scope ?? "";
-  }
-
-  /** Returns true iff the token's `groups` claim contains the given group. */
-  inGroup(groupId: string): boolean {
-    const groups = this.payload.groups;
-    return Array.isArray(groups) && groups.includes(groupId);
-  }
-
-  /** Returns true iff the token's `oid` claim exactly matches the given org ID. */
-  inOrg(orgId: string): boolean {
-    return typeof this.payload.oid === "string" && this.payload.oid === orgId;
-  }
-
-  /** The `token_type` claim (`"access"`, `"refresh"`, `"required_action"`), or empty string. */
-  tokenType(): string {
-    return this.payload.token_type ?? "";
-  }
-
-  /** The `oid` (organization ID) claim, or `undefined` if absent. */
-  organizationId(): string | undefined {
-    return this.payload.oid;
-  }
-
-  /** The `org_groups` claim (Keycloak-style org-scoped group paths), or empty array. */
-  orgGroups(): string[] {
-    const og = this.payload.org_groups;
-    return Array.isArray(og) ? og : [];
-  }
-
-  /** Access an arbitrary claim by key. */
-  get(key: string): unknown {
-    return this.payload[key];
-  }
-}