@hearth-auth/sdk 2.0.4 → 3.0.0

package/dist/generated/admin/schema.js

@@ -0,0 +1,6 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export {};
+//# sourceMappingURL=schema.js.map

package/dist/generated/admin/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/generated/admin/schema.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/hearth-client.d.ts

@@ -1,6 +1,6 @@
 import { JwksClient } from "./jwks-client.js";
 import { IntrospectionClient, type IntrospectionResult } from "./introspection-client.js";
-import type { AccessTokenAuthorizationMode, AuthorizePermissionOptions, DeviceAuthorizationResponse, TokenResponse } from "./types.js";
+import type { AccessTokenAuthorizationMode, AuthorizePermissionOptions, DeviceAuthorizationResponse, ExchangeCodeOptions, LoginBeginResult, MePermissionsResponse, SvDeltaResponse, SvSnapshotResponse, TokenResponse, UserInfoResponse } from "./types.js";
 import { Claims } from "./claims.js";
 /** Configuration for {@link HearthClient}. */
 export interface HearthClientConfig {
@@ -51,14 +51,19 @@ export interface HearthClientConfig {
      */
     expectedMode?: AccessTokenAuthorizationMode;
 }
-interface OidcConfiguration {
+/** The OIDC discovery document fields the SDK reads. */
+export interface OidcConfiguration {
     issuer: string;
     jwks_uri: string;
     introspection_endpoint?: string;
+    authorization_endpoint?: string;
+    token_endpoint?: string;
+    device_authorization_endpoint?: string;
+    userinfo_endpoint?: string;
     [key: string]: unknown;
 }
 /**
- * Primary entry point for the Hearth Node.js SDK.
+ * Primary entry point for the Hearth SDK.
  *
  * Accepts a single configuration object, auto-discovers all endpoint URLs
  * from `{issuerUrl}/.well-known/openid-configuration` on first use, and
@@ -81,6 +86,7 @@ export declare class HearthClient {
     /** Expected authorization mode; validated on `introspect()` when present. */
     readonly expectedMode: AccessTokenAuthorizationMode | undefined;
     private _discovery;
+    private _discoveryInFlight;
     private _jwksClient;
     private _introspectionClient;
     constructor(config: HearthClientConfig);
@@ -88,10 +94,20 @@ export declare class HearthClient {
      * Fetches and caches the OIDC discovery document from
      * `{issuerUrl}/.well-known/openid-configuration`.
      *
+     * Concurrent callers share one request. A failed fetch is not cached.
+     *
      * Throws {@link DiscoveryError} when the endpoint is unreachable,
      * returns a non-2xx status, or returns invalid JSON.
      */
     discover(): Promise<OidcConfiguration>;
+    /**
+     * Drop the cached discovery document, JWKS key set and introspection client.
+     * The next call fetches them again. Call it after the issuer rotates keys or
+     * changes endpoints, or after a resource server answers 401 for a token you
+     * believe is valid.
+     */
+    invalidateCache(): void;
+    private fetchDiscovery;
     /**
      * Returns a {@link JwksClient} bound to the `jwks_uri` discovered from
      * the OIDC configuration. The client is created once and reused.
@@ -126,10 +142,12 @@ export declare class HearthClient {
      * deployments where the resource server and the issuing client disagree on
      * the permission delivery strategy.
      *
+     * @param tokenTypeHint - Optional RFC 7662 `token_type_hint`.
      * @throws {@link ConfigurationError} when `clientId`/`clientSecret` are absent.
+     * @throws {@link IntrospectionError} when the introspection request fails.
      * @throws {@link AuthorizationModeMismatchError} on mode echo mismatch.
      */
-    introspect(token: string): Promise<IntrospectionResult>;
+    introspect(token: string, tokenTypeHint?: "access_token" | "refresh_token"): Promise<IntrospectionResult>;
     /**
      * Verify a JWT using JWKS-backed EdDSA/Ed25519 local signature verification (spec §2).
      *
@@ -143,7 +161,8 @@ export declare class HearthClient {
      * 3. `nbf` claim (rejects post-dated tokens).
      * 4. `iss` claim (must match configured `issuerUrl`).
      * 5. `aud` claim (validated when `clientId` is set in config).
-     * 6. `iat` claim (within 60-second clock skew tolerance).
+     *
+     * `exp` and `nbf` allow a 5-second clock skew.
      *
      * @throws {@link TokenExpiredError} — token is expired.
      * @throws {@link TokenInvalidError} — signature invalid or JWT malformed.
@@ -152,6 +171,56 @@ export declare class HearthClient {
      * @throws {@link JWKSFetchError} — JWKS endpoint unreachable.
      */
     verifyToken(token: string): Promise<Claims>;
+    /**
+     * Begin an authorization-code login with PKCE.
+     *
+     * Generates a code verifier and a `state` value and builds the URL of the
+     * discovered `authorization_endpoint`. Store `state` and `codeVerifier` in the
+     * server-side session, redirect the browser to `authorizationUrl`, then call
+     * {@link completeLogin} on the callback route.
+     *
+     * @param redirectUri - Callback URL registered for this client.
+     * @param scope - Space-delimited scopes. Default: `"openid"`.
+     * @throws {@link ConfigurationError} when `clientId` is absent or discovery has
+     *   no `authorization_endpoint`.
+     */
+    beginLogin(redirectUri: string, scope?: string): Promise<LoginBeginResult>;
+    /**
+     * Complete an authorization-code login: exchange the callback `code` for
+     * tokens. Check the callback's `state` against the stored one first.
+     *
+     * @param code - The `code` query parameter from the callback URL.
+     * @param codeVerifier - The verifier returned by {@link beginLogin}.
+     * @param redirectUri - The same redirect URI passed to {@link beginLogin}.
+     * @throws {@link OAuthFlowError} on a non-2xx response or a network failure.
+     */
+    completeLogin(code: string, codeVerifier: string, redirectUri: string): Promise<TokenResponse>;
+    /**
+     * Exchange an authorization code for tokens (RFC 6749 §4.1.3).
+     *
+     * Posts to the discovered `token_endpoint` as
+     * `application/x-www-form-urlencoded`. `client_secret` is sent only when
+     * configured, so public clients use PKCE alone.
+     *
+     * @param code - Authorization code from the callback URL.
+     * @param redirectUri - The redirect URI used in the authorization request.
+     * @param opts - `codeVerifier` for PKCE-protected flows.
+     * @throws {@link ConfigurationError} when `clientId` is absent.
+     * @throws {@link OAuthFlowError} on a non-2xx response or a network failure.
+     */
+    exchangeCode(code: string, redirectUri: string, opts?: ExchangeCodeOptions): Promise<TokenResponse>;
+    /**
+     * Exchange a refresh token for new tokens (RFC 6749 §6).
+     *
+     * The response may carry a rotated `refresh_token`; store it in place of the
+     * old one when present.
+     *
+     * @param refreshToken - Refresh token previously issued to this client.
+     * @param scope - Optional space-delimited scopes (must not widen the grant).
+     * @throws {@link ConfigurationError} when `clientId` is absent.
+     * @throws {@link OAuthFlowError} on a non-2xx response or a network failure.
+     */
+    refreshTokens(refreshToken: string, scope?: string): Promise<TokenResponse>;
     /**
      * Obtain a token via the Client Credentials grant (RFC 6749 §4.4).
      *
@@ -159,7 +228,7 @@ export declare class HearthClient {
      * body fields — NEVER as URL query parameters. The token endpoint is discovered
      * from the OIDC discovery document.
      *
-     * @throws {@link OAuthFlowError} on any non-2xx response.
+     * @throws {@link OAuthFlowError} on a non-2xx response or a network failure.
      */
     clientCredentials(scope?: string): Promise<TokenResponse>;
     /**
@@ -169,7 +238,7 @@ export declare class HearthClient {
      * Pass the returned `device_code` and `interval` to `pollDeviceToken()` to await approval.
      *
      * @throws {@link ConfigurationError} when `device_authorization_endpoint` is absent.
-     * @throws {@link OAuthFlowError} on any non-2xx response.
+     * @throws {@link OAuthFlowError} on a non-2xx response or a network failure.
      */
     startDeviceFlow(scope?: string): Promise<DeviceAuthorizationResponse>;
     /**
@@ -182,7 +251,7 @@ export declare class HearthClient {
      * @param deviceCode - The `device_code` from `startDeviceFlow()`.
      * @param intervalSeconds - Initial polling interval (from `startDeviceFlow().interval`).
      * @throws {@link TokenExpiredError} — device code has expired.
-     * @throws {@link OAuthFlowError} — non-recoverable error from the server.
+     * @throws {@link OAuthFlowError} — non-recoverable error from the server, or a network failure.
      */
     pollDeviceToken(deviceCode: string, intervalSeconds: number): Promise<TokenResponse>;
     /**
@@ -195,7 +264,7 @@ export declare class HearthClient {
      * Requires `realmId` in `HearthClientConfig`.
      *
      * @throws {@link ConfigurationError} when `realmId` is absent.
-     * @throws {@link OAuthFlowError} on non-2xx response.
+     * @throws {@link OAuthFlowError} on a non-2xx response or a network failure.
      */
     requestMagicLink(email: string): Promise<void>;
     /**
@@ -210,6 +279,56 @@ export declare class HearthClient {
      * @throws {@link OAuthFlowError} on any non-2xx response (e.g. expired/used token).
      */
     exchangeMagicLink(token: string): Promise<TokenResponse>;
+    /**
+     * Fetch the OIDC userinfo claims for an access token from the discovered
+     * `userinfo_endpoint`. Sends `X-Realm-ID` when `realmId` is configured.
+     *
+     * @throws {@link ConfigurationError} when discovery has no `userinfo_endpoint`.
+     * @throws {@link OAuthFlowError} on a non-2xx response or a network failure.
+     */
+    userinfo(accessToken: string): Promise<UserInfoResponse>;
+    /**
+     * Fetch the user's current roles, groups and permissions from
+     * `GET /v1/me/permissions`. Unlike the claims in the JWT, which are fixed
+     * when the token is issued, this reflects assignments made since.
+     *
+     * @throws {@link ConfigurationError} when `realmId` is absent.
+     * @throws {@link OAuthFlowError} on a non-2xx response or a network failure.
+     */
+    mePermissions(accessToken: string): Promise<MePermissionsResponse>;
+    /**
+     * Fetch the full session-version snapshot (RFC HEA-930): every
+     * `{sessionId → minSv}` pair in the realm. Use it to seed a cache, then
+     * follow {@link svDelta} from `current_seq`. {@link SessionVersionCache} does
+     * both for you.
+     *
+     * @param serviceToken - Token with the `hearth.sv_feed` scope.
+     * @throws {@link ConfigurationError} when `realmId` is absent.
+     * @throws {@link OAuthFlowError} on a non-2xx response or a network failure.
+     */
+    svSnapshot(serviceToken: string): Promise<SvSnapshotResponse>;
+    /**
+     * Fetch session-version changes with `seq > since` (RFC HEA-930).
+     *
+     * @param serviceToken - Token with the `hearth.sv_feed` scope.
+     * @param since - Return only events after this sequence number.
+     * @param limit - Maximum number of entries (server default when omitted).
+     * @returns The deltas, or `null` when there are none (HTTP 204).
+     * @throws {@link ConfigurationError} when `realmId` is absent.
+     * @throws {@link OAuthFlowError} on a non-2xx response or a network failure.
+     */
+    svDelta(serviceToken: string, since: number, limit?: number): Promise<SvDeltaResponse | null>;
+    private requireClientId;
+    private requireRealmId;
+    /** `client_id`, plus `client_secret` when this is a confidential client. */
+    private clientAuthParams;
+    /** Read an endpoint URL from the discovery document. */
+    private endpoint;
+    /** `fetch` with the configured timeout; a network failure becomes `OAuthFlowError(0)`. */
+    private send;
     private postForm;
+    /** GET with a bearer token, for endpoints that must return a body. */
+    private getRequired;
+    /** GET with a bearer token; `null` on 204 No Content. */
+    private getWithBearer;
 }
-export {};