@hearth-auth/sdk 0.0.1

package/src/client.ts

@@ -0,0 +1,251 @@
+import { decodeJwt } from "jose";
+import { RequiredActionError } from "./errors.js";
+import type {
+  AuthorizeParams,
+  AuthorizeResponse,
+  BootstrapResponse,
+  JwksDocument,
+  MePermissionsResponse,
+  RegisterClientParams,
+  OAuthClient,
+  TokenExchangeParams,
+  TokenResponse,
+  UserInfoResponse,
+} from "./types.js";
+
+/** Parameters for the PKCE authorization-code callback handler (spec §7). */
+export interface HandleCallbackParams {
+  /** Full callback URL including query parameters (`code`, `state`, etc.). */
+  callbackUrl: string;
+  /** OAuth 2.0 client ID. */
+  clientId: string;
+  /** Redirect URI registered for this client. */
+  redirectUri: string;
+  /** PKCE code verifier generated during `login()` (RFC 7636). */
+  codeVerifier?: string;
+}
+
+/** Error thrown when the Hearth API returns an error. */
+export class HearthError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly body: unknown,
+  ) {
+    super(`Hearth API error ${status}: ${JSON.stringify(body)}`);
+    this.name = "HearthError";
+  }
+}
+
+/** Configuration for HearthApiClient. */
+export interface HearthApiClientConfig {
+  baseUrl: string;
+  realmId: string;
+}
+
+/**
+ * Low-level Hearth HTTP API client for auth code flows, token management,
+ * JWKS retrieval, and live RBAC claim resolution.
+ *
+ * @deprecated Use {@link HearthClient} from `hearth-client.js` as the
+ * recommended entry point. This class is kept as a lower-level primitive.
+ */
+export class HearthApiClient {
+  private readonly baseUrl: string;
+  private readonly realmId: string;
+
+  constructor(config: HearthApiClientConfig) {
+    this.baseUrl = config.baseUrl.replace(/\/$/, "");
+    this.realmId = config.realmId;
+  }
+
+  /** POST /admin/bootstrap — create realm, admin user, tokens (dev mode only). */
+  static async bootstrap(baseUrl: string): Promise<BootstrapResponse> {
+    const url = `${baseUrl.replace(/\/$/, "")}/admin/bootstrap`;
+    const resp = await fetch(url, { method: "POST" });
+    if (!resp.ok) {
+      throw new HearthError(resp.status, await resp.json());
+    }
+    return resp.json() as Promise<BootstrapResponse>;
+  }
+
+  /** POST /clients — register an OAuth 2.0 client. */
+  async registerClient(params: RegisterClientParams): Promise<OAuthClient> {
+    return this.post("/clients", {
+      client_name: params.clientName,
+      redirect_uris: params.redirectUris,
+    });
+  }
+
+  /** POST /authorize — initiate an authorization code flow. */
+  async authorize(params: AuthorizeParams): Promise<AuthorizeResponse> {
+    return this.post("/authorize", {
+      client_id: params.clientId,
+      redirect_uri: params.redirectUri,
+      scope: params.scope,
+      state: params.state,
+      response_type: params.responseType ?? "code",
+      user_id: params.userId,
+      code_challenge: params.codeChallenge,
+      code_challenge_method: params.codeChallengeMethod,
+      nonce: params.nonce,
+    });
+  }
+
+  /** POST /token — exchange an authorization code for tokens. */
+  async exchangeCode(params: TokenExchangeParams): Promise<TokenResponse> {
+    return this.post("/token", {
+      client_id: params.clientId,
+      code: params.code,
+      redirect_uri: params.redirectUri,
+      code_verifier: params.codeVerifier,
+    });
+  }
+
+  /**
+   * Handle a PKCE authorization-code callback (spec §7).
+   *
+   * Extracts the `code` from `callbackUrl`, exchanges it for tokens, then
+   * inspects the JWT's `token_type` claim before returning:
+   *
+   * - If `token_type === "required_action"`: throws {@link RequiredActionError}
+   *   with `requiredActions` populated from the JWT's `required_actions` claim.
+   * - If the callback URL contains `required_action_redirect_uri`: throws
+   *   {@link RequiredActionError} with `redirectUri` set to that value.
+   * - Otherwise: returns the token response normally.
+   */
+  async handleCallback(params: HandleCallbackParams): Promise<TokenResponse> {
+    const url = new URL(params.callbackUrl);
+    const code = url.searchParams.get("code");
+    const requiredActionRedirectUri = url.searchParams.get(
+      "required_action_redirect_uri",
+    );
+
+    if (!code) {
+      throw new Error("handleCallback: no authorization code found in callback URL");
+    }
+
+    const tokens = await this.exchangeCode({
+      clientId: params.clientId,
+      code,
+      redirectUri: params.redirectUri,
+      codeVerifier: params.codeVerifier,
+    });
+
+    // Decode the access token to read Hearth-specific claims.
+    let jwtPayload: Record<string, unknown> = {};
+    try {
+      jwtPayload = decodeJwt(tokens.access_token) as Record<string, unknown>;
+    } catch {
+      // Non-JWT access tokens (opaque) skip required-action detection.
+    }
+
+    const tokenType = jwtPayload["token_type"];
+    const requiredActions = Array.isArray(jwtPayload["required_actions"])
+      ? (jwtPayload["required_actions"] as string[])
+      : [];
+
+    if (tokenType === "required_action") {
+      throw new RequiredActionError(
+        requiredActions,
+        requiredActionRedirectUri ?? undefined,
+      );
+    }
+
+    if (requiredActionRedirectUri !== null) {
+      throw new RequiredActionError([], requiredActionRedirectUri);
+    }
+
+    return tokens;
+  }
+
+  /** POST /token — refresh tokens using a refresh token. */
+  async refreshTokens(
+    clientId: string,
+    refreshToken: string,
+  ): Promise<TokenResponse> {
+    return this.post("/token", {
+      client_id: clientId,
+      grant_type: "refresh_token",
+      refresh_token: refreshToken,
+    });
+  }
+
+  /**
+   * GET /v1/me/permissions — fetch the freshly-resolved RBAC claim set
+   * for the bearer-token user.
+   *
+   * Unlike `hasPermission()` on a `createHearth()` client (which reads
+   * the cached set from the JWT), this call queries the server and
+   * reflects any role/group assignments made since the token was issued.
+   */
+  async permissions(accessToken: string): Promise<MePermissionsResponse> {
+    const resp = await fetch(`${this.baseUrl}/v1/me/permissions`, {
+      headers: {
+        "X-Realm-ID": this.realmId,
+        Authorization: `Bearer ${accessToken}`,
+      },
+    });
+    if (!resp.ok) {
+      throw new HearthError(resp.status, await resp.json());
+    }
+    return resp.json() as Promise<MePermissionsResponse>;
+  }
+
+  /** GET /userinfo — retrieve user claims using an access token. */
+  async userinfo(accessToken: string): Promise<UserInfoResponse> {
+    const resp = await fetch(`${this.baseUrl}/userinfo`, {
+      headers: {
+        "X-Realm-ID": this.realmId,
+        Authorization: `Bearer ${accessToken}`,
+      },
+    });
+    if (!resp.ok) {
+      throw new HearthError(resp.status, await resp.json());
+    }
+    return resp.json() as Promise<UserInfoResponse>;
+  }
+
+  /** GET /jwks — retrieve the JWKS document. */
+  async jwks(): Promise<JwksDocument> {
+    const resp = await fetch(`${this.baseUrl}/jwks`);
+    if (!resp.ok) {
+      throw new HearthError(resp.status, await resp.json());
+    }
+    return resp.json() as Promise<JwksDocument>;
+  }
+
+  /** GET /.well-known/openid-configuration — OIDC discovery document. */
+  async discovery(): Promise<Record<string, unknown>> {
+    const resp = await fetch(
+      `${this.baseUrl}/.well-known/openid-configuration`,
+    );
+    if (!resp.ok) {
+      throw new HearthError(resp.status, await resp.json());
+    }
+    return resp.json() as Promise<Record<string, unknown>>;
+  }
+
+  /** Creates an AdminClient using the given access token. */
+  admin(accessToken: string): AdminClient {
+    return new AdminClient(this.baseUrl, this.realmId, accessToken);
+  }
+
+
+  private async post<T>(path: string, body: unknown): Promise<T> {
+    const resp = await fetch(`${this.baseUrl}${path}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Realm-ID": this.realmId,
+      },
+      body: JSON.stringify(body),
+    });
+    if (!resp.ok) {
+      throw new HearthError(resp.status, await resp.json());
+    }
+    return resp.json() as Promise<T>;
+  }
+}
+
+// AdminClient is imported here to avoid circular deps — it's re-exported from index.
+import { AdminClient } from "./admin.js";

package/src/errors.ts

@@ -0,0 +1,173 @@
+/**
+ * Spec §5 — Hearth SDK error hierarchy.
+ *
+ * All SDK-specific errors extend HearthSdkError so callers can catch
+ * the entire category with a single `instanceof HearthSdkError` check.
+ */
+
+/** Base class for all Hearth SDK errors. */
+export class HearthSdkError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = this.constructor.name;
+  }
+}
+
+/** Thrown when the client is misconfigured (missing baseUrl, realmId, etc.). */
+export class ConfigurationError extends HearthSdkError {
+  constructor(message: string) {
+    super(message);
+  }
+}
+
+/** Thrown when the OIDC discovery document cannot be fetched or parsed. */
+export class DiscoveryError extends HearthSdkError {
+  constructor(
+    message: string,
+    public readonly cause?: unknown,
+  ) {
+    super(message);
+  }
+}
+
+/** Thrown when fetching or parsing the JWKS document fails. */
+export class JWKSFetchError extends HearthSdkError {
+  constructor(
+    message: string,
+    public readonly cause?: unknown,
+  ) {
+    super(message);
+  }
+}
+
+/** Thrown when a token's `exp` claim is in the past. */
+export class TokenExpiredError extends HearthSdkError {
+  constructor(
+    public readonly expiredAt: Date,
+    message = `Token expired at ${expiredAt.toISOString()}`,
+  ) {
+    super(message);
+  }
+}
+
+/** Thrown when a token's `nbf` claim is in the future. */
+export class TokenNotYetValidError extends HearthSdkError {
+  constructor(
+    public readonly notBefore: Date,
+    message = `Token not yet valid until ${notBefore.toISOString()}`,
+  ) {
+    super(message);
+  }
+}
+
+/** Thrown when a token fails signature or structural validation. */
+export class TokenInvalidError extends HearthSdkError {
+  constructor(message: string) {
+    super(message);
+  }
+}
+
+/** Thrown when the token's `iss` claim does not match the expected issuer. */
+export class TokenIssuerError extends HearthSdkError {
+  constructor(
+    public readonly expected: string,
+    public readonly actual: string,
+    message = `Token issuer mismatch: expected "${expected}", got "${actual}"`,
+  ) {
+    super(message);
+  }
+}
+
+/** Thrown when the token's `aud` claim does not include the expected audience. */
+export class TokenAudienceError extends HearthSdkError {
+  constructor(
+    public readonly expected: string,
+    public readonly actual: string[],
+    message = `Token audience mismatch: expected "${expected}", got [${actual.join(", ")}]`,
+  ) {
+    super(message);
+  }
+}
+
+/**
+ * Thrown when a token has `token_type === "required_action"`, indicating the
+ * user must complete pending actions before the token can be used for general
+ * API access. Also thrown when the callback URL contains
+ * `required_action_redirect_uri` (spec §5, §7).
+ */
+export class RequiredActionError extends HearthSdkError {
+  constructor(
+    /** Pending action names from the token's `required_actions` claim. */
+    public readonly requiredActions: string[],
+    /** Optional URL to the Hearth interstitial page for completing the actions. */
+    public readonly redirectUri?: string,
+    message = `Required actions pending: ${requiredActions.join(", ")}`,
+  ) {
+    super(message);
+  }
+}
+
+/** Thrown when a token introspection request fails or returns inactive. */
+export class IntrospectionError extends HearthSdkError {
+  constructor(
+    message: string,
+    public readonly cause?: unknown,
+  ) {
+    super(message);
+  }
+}
+
+/**
+ * Thrown when the `mode` field echoed in an introspection response does not
+ * match the SDK's configured `expectedMode`.
+ *
+ * Per HEA-923 design constraint: mode must be validated explicitly; the SDK
+ * MUST NOT silently tolerate a server returning a different mode than the one
+ * configured for the resource server.
+ */
+export class AuthorizationModeMismatchError extends HearthSdkError {
+  constructor(
+    public readonly expected: string,
+    public readonly actual: string,
+    message = `Authorization mode mismatch: expected "${expected}", got "${actual}"`,
+  ) {
+    super(message);
+  }
+}
+
+/**
+ * Thrown when a token's `sv` claim is below the minimum accepted session
+ * version for the session (RFC HEA-930 § 8).
+ *
+ * Resource servers should translate this into an HTTP 401 response.
+ */
+export class SessionVersionRevokedError extends HearthSdkError {
+  constructor(
+    public readonly sessionId: string,
+    public readonly tokenSv: bigint,
+    public readonly minSv: bigint,
+    message = `Session version revoked: sid=${sessionId}, sv=${tokenSv} < min=${minSv}`,
+  ) {
+    super(message);
+  }
+}
+
+/**
+ * Thrown when the session-version cache has not been refreshed within
+ * `staleThresholdMs` (RFC HEA-930 § 8.1).
+ *
+ * When `onStale` is `"reject"`, resource servers should translate this into
+ * an HTTP 401 response with `error=session_version_cache_stale`.
+ * When `onStale` is `"introspect"`, catch this error and fall back to the
+ * introspection endpoint.
+ */
+export class SessionVersionCacheStaleError extends HearthSdkError {
+  constructor(
+    /** Cache age in milliseconds, or -1 if the cache has never been seeded. */
+    public readonly ageMs: number,
+    public readonly onStale: "reject" | "introspect" = "reject",
+    message = `Session version cache stale: age=${ageMs < 0 ? "never seeded" : `${ageMs}ms`}`,
+  ) {
+    super(message);
+  }
+}

package/src/generated/google/api/annotations_pb.ts

@@ -0,0 +1,44 @@
+// Copyright 2015 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Vendored from github.com/googleapis/googleapis (Apache-2.0).
+// Kept minimal: only annotations.proto + http.proto are needed for
+// google.api.http method annotations.  Replaces the buf.build remote
+// dependency so CI never needs the buf module cache hydrated.
+
+// @generated by protoc-gen-es v2.12.0 with parameter "target=ts"
+// @generated from file google/api/annotations.proto (package google.api, syntax proto3)
+/* eslint-disable */
+
+import type { GenExtension, GenFile } from "@bufbuild/protobuf/codegenv2";
+import { extDesc, fileDesc } from "@bufbuild/protobuf/codegenv2";
+import type { HttpRule } from "./http_pb";
+import { file_google_api_http } from "./http_pb";
+import type { MethodOptions } from "@bufbuild/protobuf/wkt";
+import { file_google_protobuf_descriptor } from "@bufbuild/protobuf/wkt";
+
+/**
+ * Describes the file google/api/annotations.proto.
+ */
+export const file_google_api_annotations: GenFile = /*@__PURE__*/
+  fileDesc("Chxnb29nbGUvYXBpL2Fubm90YXRpb25zLnByb3RvEgpnb29nbGUuYXBpOksKBGh0dHASHi5nb29nbGUucHJvdG9idWYuTWV0aG9kT3B0aW9ucxiwyrwiIAEoCzIULmdvb2dsZS5hcGkuSHR0cFJ1bGVSBGh0dHBCbgoOY29tLmdvb2dsZS5hcGlCEEFubm90YXRpb25zUHJvdG9QAVpBZ29vZ2xlLmdvbGFuZy5vcmcvZ2VucHJvdG8vZ29vZ2xlYXBpcy9hcGkvYW5ub3RhdGlvbnM7YW5ub3RhdGlvbnOiAgRHQVBJYgZwcm90bzM", [file_google_api_http, file_google_protobuf_descriptor]);
+
+/**
+ * See `HttpRule`.
+ *
+ * @generated from extension: google.api.HttpRule http = 72295728;
+ */
+export const http: GenExtension<MethodOptions, HttpRule> = /*@__PURE__*/
+  extDesc(file_google_api_annotations, 0);
+