@hearth-auth/sdk 0.0.1 → 1.0.0

package/dist/client.js

@@ -0,0 +1,190 @@
+import { decodeJwt } from "jose";
+import { RequiredActionError } from "./errors.js";
+/** Error thrown when the Hearth API returns an error. */
+export class HearthError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(`Hearth API error ${status}: ${JSON.stringify(body)}`);
+        this.status = status;
+        this.body = body;
+        this.name = "HearthError";
+    }
+}
+/**
+ * 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 {
+    baseUrl;
+    realmId;
+    constructor(config) {
+        this.baseUrl = config.baseUrl.replace(/\/$/, "");
+        this.realmId = config.realmId;
+    }
+    /** POST /admin/bootstrap — create realm, admin user, tokens (dev mode only). */
+    static async bootstrap(baseUrl) {
+        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();
+    }
+    /** POST /clients — register an OAuth 2.0 client. */
+    async registerClient(params) {
+        return this.post("/clients", {
+            client_name: params.clientName,
+            redirect_uris: params.redirectUris,
+        });
+    }
+    /** POST /authorize — initiate an authorization code flow. */
+    async authorize(params) {
+        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) {
+        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) {
+        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 = {};
+        try {
+            jwtPayload = decodeJwt(tokens.access_token);
+        }
+        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"]
+            : [];
+        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, refreshToken) {
+        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) {
+        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();
+    }
+    /** GET /userinfo — retrieve user claims using an access token. */
+    async userinfo(accessToken) {
+        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();
+    }
+    /** GET /jwks — retrieve the JWKS document. */
+    async jwks() {
+        const resp = await fetch(`${this.baseUrl}/jwks`);
+        if (!resp.ok) {
+            throw new HearthError(resp.status, await resp.json());
+        }
+        return resp.json();
+    }
+    /** GET /.well-known/openid-configuration — OIDC discovery document. */
+    async discovery() {
+        const resp = await fetch(`${this.baseUrl}/.well-known/openid-configuration`);
+        if (!resp.ok) {
+            throw new HearthError(resp.status, await resp.json());
+        }
+        return resp.json();
+    }
+    /** Creates an AdminClient using the given access token. */
+    admin(accessToken) {
+        return new AdminClient(this.baseUrl, this.realmId, accessToken);
+    }
+    async post(path, body) {
+        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();
+    }
+}
+// AdminClient is imported here to avoid circular deps — it's re-exported from index.
+import { AdminClient } from "./admin.js";
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,114 @@
+/**
+ * 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 declare class HearthSdkError extends Error {
+    constructor(message: string);
+}
+/** Thrown when the client is misconfigured (missing baseUrl, realmId, etc.). */
+export declare class ConfigurationError extends HearthSdkError {
+    constructor(message: string);
+}
+/** Thrown when the OIDC discovery document cannot be fetched or parsed. */
+export declare class DiscoveryError extends HearthSdkError {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/** Thrown when fetching or parsing the JWKS document fails. */
+export declare class JWKSFetchError extends HearthSdkError {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/** Thrown when a token's `exp` claim is in the past. */
+export declare class TokenExpiredError extends HearthSdkError {
+    readonly expiredAt: Date;
+    constructor(expiredAt: Date, message?: string);
+}
+/** Thrown when a token's `nbf` claim is in the future. */
+export declare class TokenNotYetValidError extends HearthSdkError {
+    readonly notBefore: Date;
+    constructor(notBefore: Date, message?: string);
+}
+/** Thrown when a token fails signature or structural validation. */
+export declare class TokenInvalidError extends HearthSdkError {
+    constructor(message: string);
+}
+/** Thrown when the token's `iss` claim does not match the expected issuer. */
+export declare class TokenIssuerError extends HearthSdkError {
+    readonly expected: string;
+    readonly actual: string;
+    constructor(expected: string, actual: string, message?: string);
+}
+/** Thrown when the token's `aud` claim does not include the expected audience. */
+export declare class TokenAudienceError extends HearthSdkError {
+    readonly expected: string;
+    readonly actual: string[];
+    constructor(expected: string, actual: string[], message?: string);
+}
+/**
+ * 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 declare class RequiredActionError extends HearthSdkError {
+    /** Pending action names from the token's `required_actions` claim. */
+    readonly requiredActions: string[];
+    /** Optional URL to the Hearth interstitial page for completing the actions. */
+    readonly redirectUri?: string | undefined;
+    constructor(
+    /** Pending action names from the token's `required_actions` claim. */
+    requiredActions: string[], 
+    /** Optional URL to the Hearth interstitial page for completing the actions. */
+    redirectUri?: string | undefined, message?: string);
+}
+/** Thrown when a token introspection request fails or returns inactive. */
+export declare class IntrospectionError extends HearthSdkError {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/**
+ * 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 declare class AuthorizationModeMismatchError extends HearthSdkError {
+    readonly expected: string;
+    readonly actual: string;
+    constructor(expected: string, actual: string, message?: string);
+}
+/**
+ * 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 declare class SessionVersionRevokedError extends HearthSdkError {
+    readonly sessionId: string;
+    readonly tokenSv: bigint;
+    readonly minSv: bigint;
+    constructor(sessionId: string, tokenSv: bigint, minSv: bigint, message?: string);
+}
+/**
+ * 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 declare class SessionVersionCacheStaleError extends HearthSdkError {
+    /** Cache age in milliseconds, or -1 if the cache has never been seeded. */
+    readonly ageMs: number;
+    readonly onStale: "reject" | "introspect";
+    constructor(
+    /** Cache age in milliseconds, or -1 if the cache has never been seeded. */
+    ageMs: number, onStale?: "reject" | "introspect", message?: string);
+}

package/{src/errors.ts → dist/errors.js}

@@ -4,91 +4,77 @@
  * 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;
-  }
+    constructor(message) {
+        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);
-  }
+    constructor(message) {
+        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);
-  }
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+    }
 }
-
 /** Thrown when fetching or parsing the JWKS document fails. */
 export class JWKSFetchError extends HearthSdkError {
-  constructor(
-    message: string,
-    public readonly cause?: unknown,
-  ) {
-    super(message);
-  }
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+    }
 }
-
 /** 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);
-  }
+    expiredAt;
+    constructor(expiredAt, message = `Token expired at ${expiredAt.toISOString()}`) {
+        super(message);
+        this.expiredAt = expiredAt;
+    }
 }
-
 /** 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);
-  }
+    notBefore;
+    constructor(notBefore, message = `Token not yet valid until ${notBefore.toISOString()}`) {
+        super(message);
+        this.notBefore = notBefore;
+    }
 }
-
 /** Thrown when a token fails signature or structural validation. */
 export class TokenInvalidError extends HearthSdkError {
-  constructor(message: string) {
-    super(message);
-  }
+    constructor(message) {
+        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);
-  }
+    expected;
+    actual;
+    constructor(expected, actual, message = `Token issuer mismatch: expected "${expected}", got "${actual}"`) {
+        super(message);
+        this.expected = expected;
+        this.actual = actual;
+    }
 }
-
 /** 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);
-  }
+    expected;
+    actual;
+    constructor(expected, actual, message = `Token audience mismatch: expected "${expected}", got [${actual.join(", ")}]`) {
+        super(message);
+        this.expected = expected;
+        this.actual = actual;
+    }
 }
-
 /**
  * Thrown when a token has `token_type === "required_action"`, indicating the
  * user must complete pending actions before the token can be used for general
@@ -96,27 +82,26 @@ export class TokenAudienceError extends HearthSdkError {
  * `required_action_redirect_uri` (spec §5, §7).
  */
 export class RequiredActionError extends HearthSdkError {
-  constructor(
+    requiredActions;
+    redirectUri;
+    constructor(
     /** Pending action names from the token's `required_actions` claim. */
-    public readonly requiredActions: string[],
+    requiredActions, 
     /** Optional URL to the Hearth interstitial page for completing the actions. */
-    public readonly redirectUri?: string,
-    message = `Required actions pending: ${requiredActions.join(", ")}`,
-  ) {
-    super(message);
-  }
+    redirectUri, message = `Required actions pending: ${requiredActions.join(", ")}`) {
+        super(message);
+        this.requiredActions = requiredActions;
+        this.redirectUri = redirectUri;
+    }
 }
-
 /** Thrown when a token introspection request fails or returns inactive. */
 export class IntrospectionError extends HearthSdkError {
-  constructor(
-    message: string,
-    public readonly cause?: unknown,
-  ) {
-    super(message);
-  }
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+    }
 }
-
 /**
  * Thrown when the `mode` field echoed in an introspection response does not
  * match the SDK's configured `expectedMode`.
@@ -126,15 +111,14 @@ export class IntrospectionError extends HearthSdkError {
  * 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);
-  }
+    expected;
+    actual;
+    constructor(expected, actual, message = `Authorization mode mismatch: expected "${expected}", got "${actual}"`) {
+        super(message);
+        this.expected = expected;
+        this.actual = actual;
+    }
 }
-
 /**
  * Thrown when a token's `sv` claim is below the minimum accepted session
  * version for the session (RFC HEA-930 § 8).
@@ -142,16 +126,16 @@ export class AuthorizationModeMismatchError extends HearthSdkError {
  * 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);
-  }
+    sessionId;
+    tokenSv;
+    minSv;
+    constructor(sessionId, tokenSv, minSv, message = `Session version revoked: sid=${sessionId}, sv=${tokenSv} < min=${minSv}`) {
+        super(message);
+        this.sessionId = sessionId;
+        this.tokenSv = tokenSv;
+        this.minSv = minSv;
+    }
 }
-
 /**
  * Thrown when the session-version cache has not been refreshed within
  * `staleThresholdMs` (RFC HEA-930 § 8.1).
@@ -162,12 +146,14 @@ export class SessionVersionRevokedError extends HearthSdkError {
  * introspection endpoint.
  */
 export class SessionVersionCacheStaleError extends HearthSdkError {
-  constructor(
+    ageMs;
+    onStale;
+    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);
-  }
+    ageMs, onStale = "reject", message = `Session version cache stale: age=${ageMs < 0 ? "never seeded" : `${ageMs}ms`}`) {
+        super(message);
+        this.ageMs = ageMs;
+        this.onStale = onStale;
+    }
 }
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}