@hearth-auth/node 0.0.1

package/dist/authorize.js

@@ -0,0 +1,68 @@
+/** §7 — AuthorizeClient: per-request permission decisions via POST /oauth/authorize. */
+import { AuthorizeError } from "./errors.js";
+/**
+ * Calls `POST /oauth/authorize` to make a per-request permission decision.
+ *
+ * This client is fail-closed: network errors and non-OK responses return
+ * `{ allowed: false }` rather than throwing, so middleware cannot accidentally
+ * grant access on infrastructure failures.
+ *
+ * Misconfiguration (no endpoint) throws `AuthorizeError` before any network call.
+ */
+export class AuthorizeClient {
+    endpoint;
+    realmId;
+    timeout;
+    constructor(config) {
+        this.endpoint = config.authorize_endpoint ?? `${config.issuer_url}/oauth/authorize`;
+        // If authorize_endpoint was explicitly set to null (no issuer_url fallback possible),
+        // keep null so decide() can throw a typed error.
+        if (config.authorize_endpoint === null && !config.issuer_url) {
+            this.endpoint = null;
+        }
+        this.realmId = config.realm_id;
+        this.timeout = config.http_timeout;
+    }
+    /**
+     * Check whether the bearer token holder has `permission`.
+     *
+     * Fail-closed: returns `{ allowed: false }` on any network or server error.
+     * Throws `AuthorizeError` only when the endpoint is not configured.
+     */
+    async decide(token, permission, opts) {
+        if (!this.endpoint) {
+            throw new AuthorizeError("authorize_endpoint is not configured and issuer_url is unavailable");
+        }
+        const headers = {
+            "Content-Type": "application/json",
+            "Authorization": `Bearer ${token}`,
+        };
+        if (this.realmId)
+            headers["X-Realm-ID"] = this.realmId;
+        const body = { permission };
+        if (opts?.organization_id)
+            body["organization_id"] = opts.organization_id;
+        if (opts?.resource)
+            body["resource"] = opts.resource;
+        try {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), this.timeout);
+            const res = await fetch(this.endpoint, {
+                method: "POST",
+                headers,
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+            clearTimeout(timer);
+            if (!res.ok)
+                return { allowed: false };
+            const json = await res.json();
+            return { allowed: json["allowed"] === true };
+        }
+        catch {
+            // Fail-closed: any network error → deny
+            return { allowed: false };
+        }
+    }
+}
+//# sourceMappingURL=authorize.js.map

package/dist/authorize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorize.js","sourceRoot":"","sources":["../src/authorize.ts"],"names":[],"mappings":"AAAA,wFAAwF;AAExF,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAe7C;;;;;;;;GAQG;AACH,MAAM,OAAO,eAAe;IACT,QAAQ,CAAgB;IACxB,OAAO,CAAgB;IACvB,OAAO,CAAS;IAEjC,YAAY,MAAsB;QAChC,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,kBAAkB,IAAI,GAAG,MAAM,CAAC,UAAU,kBAAkB,CAAC;QACpF,sFAAsF;QACtF,iDAAiD;QACjD,IAAI,MAAM,CAAC,kBAAkB,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;YAC7D,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACvB,CAAC;QACD,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,QAAQ,CAAC;QAC/B,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,YAAY,CAAC;IACrC,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,MAAM,CAAC,KAAa,EAAE,UAAkB,EAAE,IAAuB;QACrE,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACnB,MAAM,IAAI,cAAc,CACtB,oEAAoE,CACrE,CAAC;QACJ,CAAC;QAED,MAAM,OAAO,GAA2B;YACtC,cAAc,EAAE,kBAAkB;YAClC,eAAe,EAAE,UAAU,KAAK,EAAE;SACnC,CAAC;QACF,IAAI,IAAI,CAAC,OAAO;YAAE,OAAO,CAAC,YAAY,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC;QAEvD,MAAM,IAAI,GAA2B,EAAE,UAAU,EAAE,CAAC;QACpD,IAAI,IAAI,EAAE,eAAe;YAAE,IAAI,CAAC,iBAAiB,CAAC,GAAG,IAAI,CAAC,eAAe,CAAC;QAC1E,IAAI,IAAI,EAAE,QAAQ;YAAE,IAAI,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC;QAErD,IAAI,CAAC;YACH,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;YACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;YACjE,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE;gBACrC,MAAM,EAAE,MAAM;gBACd,OAAO;gBACP,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;gBAC1B,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC,CAAC;YACH,YAAY,CAAC,KAAK,CAAC,CAAC;YAEpB,IAAI,CAAC,GAAG,CAAC,EAAE;gBAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;YAEvC,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAA6B,CAAC;YACzD,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,IAAI,EAAE,CAAC;QAC/C,CAAC;QAAC,MAAM,CAAC;YACP,wCAAwC;YACxC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC5B,CAAC;IACH,CAAC;CACF"}

package/dist/authorize.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=authorize.test.d.ts.map

package/dist/authorize.test.d.ts.map

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

package/dist/authorize.test.js

@@ -0,0 +1,93 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { AuthorizeClient } from "./authorize.js";
+const CONFIG = {
+    issuer_url: "https://auth.example.com",
+    client_id: "client1",
+    client_secret: "secret1",
+    audience: [],
+    jwks_ttl: 300_000,
+    introspection_endpoint: "https://auth.example.com/introspect",
+    authorize_endpoint: "https://auth.example.com/oauth/authorize",
+    realm_id: "11111111-1111-1111-1111-111111111111",
+    http_timeout: 10_000,
+    clock_skew_seconds: 60,
+};
+function makeClient(overrides = {}) {
+    return new AuthorizeClient({ ...CONFIG, ...overrides });
+}
+describe("AuthorizeClient", () => {
+    afterEach(() => vi.restoreAllMocks());
+    it("returns allowed=true when server grants permission", async () => {
+        vi.spyOn(globalThis, "fetch").mockResolvedValue({
+            ok: true,
+            json: async () => ({ allowed: true }),
+        });
+        const result = await makeClient().decide("tok123", "docs.write");
+        expect(result.allowed).toBe(true);
+    });
+    it("returns allowed=false when server denies permission", async () => {
+        vi.spyOn(globalThis, "fetch").mockResolvedValue({
+            ok: true,
+            json: async () => ({ allowed: false }),
+        });
+        const result = await makeClient().decide("tok123", "docs.write");
+        expect(result.allowed).toBe(false);
+    });
+    it("sends Authorization header with Bearer token and X-Realm-ID", async () => {
+        const spy = vi.spyOn(globalThis, "fetch").mockResolvedValue({
+            ok: true,
+            json: async () => ({ allowed: true }),
+        });
+        await makeClient().decide("mytoken", "files.delete");
+        const [url, init] = spy.mock.calls[0];
+        expect(url).toBe("https://auth.example.com/oauth/authorize");
+        const headers = init?.headers;
+        expect(headers["Authorization"]).toBe("Bearer mytoken");
+        expect(headers["X-Realm-ID"]).toBe("11111111-1111-1111-1111-111111111111");
+    });
+    it("sends permission in request body", async () => {
+        const spy = vi.spyOn(globalThis, "fetch").mockResolvedValue({
+            ok: true,
+            json: async () => ({ allowed: false }),
+        });
+        await makeClient().decide("tok", "users.admin");
+        const body = JSON.parse(spy.mock.calls[0][1]?.body);
+        expect(body.permission).toBe("users.admin");
+    });
+    it("passes optional organization_id and resource", async () => {
+        const spy = vi.spyOn(globalThis, "fetch").mockResolvedValue({
+            ok: true,
+            json: async () => ({ allowed: true }),
+        });
+        await makeClient().decide("tok", "docs.read", {
+            organization_id: "org_abc",
+            resource: "https://api.example.com",
+        });
+        const body = JSON.parse(spy.mock.calls[0][1]?.body);
+        expect(body.organization_id).toBe("org_abc");
+        expect(body.resource).toBe("https://api.example.com");
+    });
+    it("fail-closed: returns allowed=false on network error (does not throw)", async () => {
+        vi.spyOn(globalThis, "fetch").mockRejectedValue(new Error("ECONNREFUSED"));
+        const result = await makeClient().decide("tok", "docs.write");
+        expect(result.allowed).toBe(false);
+    });
+    it("fail-closed: returns allowed=false on non-OK HTTP response", async () => {
+        vi.spyOn(globalThis, "fetch").mockResolvedValue({
+            ok: false,
+            status: 502,
+        });
+        const result = await makeClient().decide("tok", "docs.write");
+        expect(result.allowed).toBe(false);
+    });
+    it("falls back to {issuer_url}/oauth/authorize when authorize_endpoint is null", async () => {
+        const spy = vi.spyOn(globalThis, "fetch").mockResolvedValue({
+            ok: true,
+            json: async () => ({ allowed: true }),
+        });
+        const client = makeClient({ authorize_endpoint: null });
+        await client.decide("tok", "perm");
+        expect(spy.mock.calls[0][0]).toBe("https://auth.example.com/oauth/authorize");
+    });
+});
+//# sourceMappingURL=authorize.test.js.map

package/dist/authorize.test.js.map

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

package/dist/client.d.ts

@@ -0,0 +1,36 @@
+/** §1 — HearthClient: unified entry point for the @hearth-auth/node SDK. */
+import type { HearthConfig } from "./config.js";
+import type { IntrospectionResult } from "./introspect.js";
+import type { AuthorizeOptions, AuthorizeResult } from "./authorize.js";
+import type { VerifiedToken } from "./token.js";
+export declare class HearthClient {
+    private readonly verifier;
+    private readonly introspectionClient;
+    private readonly authorizeClient;
+    private readonly discovery;
+    constructor(config: HearthConfig);
+    /**
+     * Verify a JWT using JWKS.
+     * Supports RS256 and ES256. Validates exp, iss, aud, iat (with clock skew tolerance).
+     * On key miss, re-fetches the JWKS once before failing (handles key rotation).
+     */
+    verifyToken(token: string): Promise<VerifiedToken>;
+    /**
+     * Introspect a token per RFC 7662.
+     * Returns IntrospectionResult with active, sub, iss, aud, exp, iat, scope, extra.
+     */
+    introspect(token: string, tokenTypeHint?: "access_token" | "refresh_token"): Promise<IntrospectionResult>;
+    /**
+     * Per-request permission decision via `POST /oauth/authorize` (Decision mode).
+     *
+     * Fail-closed: returns `{ allowed: false }` on network errors.
+     * Throws `AuthorizeError` when the endpoint is misconfigured.
+     */
+    authorize(token: string, permission: string, opts?: AuthorizeOptions): Promise<AuthorizeResult>;
+    /**
+     * Force eviction of the JWKS and discovery caches.
+     * Call this after receiving a 401 from a resource server protected by the same issuer.
+     */
+    invalidateCache(): void;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAE5E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAKhD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAE3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACxE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAsB;IAC1D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkB;gBAEhC,MAAM,EAAE,YAAY;IAQhC;;;;OAIG;IACG,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAIxD;;;OAGG;IACG,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,cAAc,GAAG,eAAe,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAI/G;;;;;OAKG;IACG,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC;IAIrG;;;OAGG;IACH,eAAe,IAAI,IAAI;CAGxB"}

package/dist/client.js

@@ -0,0 +1,51 @@
+/** §1 — HearthClient: unified entry point for the @hearth-auth/node SDK. */
+import { resolveConfig } from "./config.js";
+import { DiscoveryClient } from "./discovery.js";
+import { JwksVerifier } from "./jwks.js";
+import { IntrospectionClient } from "./introspect.js";
+import { AuthorizeClient } from "./authorize.js";
+export class HearthClient {
+    verifier;
+    introspectionClient;
+    authorizeClient;
+    discovery;
+    constructor(config) {
+        const resolved = resolveConfig(config);
+        this.discovery = new DiscoveryClient(resolved.issuer_url, resolved.http_timeout);
+        this.verifier = new JwksVerifier(resolved, this.discovery);
+        this.introspectionClient = new IntrospectionClient(resolved, () => this.discovery.discover());
+        this.authorizeClient = new AuthorizeClient(resolved);
+    }
+    /**
+     * Verify a JWT using JWKS.
+     * Supports RS256 and ES256. Validates exp, iss, aud, iat (with clock skew tolerance).
+     * On key miss, re-fetches the JWKS once before failing (handles key rotation).
+     */
+    async verifyToken(token) {
+        return this.verifier.verifyToken(token);
+    }
+    /**
+     * Introspect a token per RFC 7662.
+     * Returns IntrospectionResult with active, sub, iss, aud, exp, iat, scope, extra.
+     */
+    async introspect(token, tokenTypeHint) {
+        return this.introspectionClient.introspect(token, tokenTypeHint);
+    }
+    /**
+     * Per-request permission decision via `POST /oauth/authorize` (Decision mode).
+     *
+     * Fail-closed: returns `{ allowed: false }` on network errors.
+     * Throws `AuthorizeError` when the endpoint is misconfigured.
+     */
+    async authorize(token, permission, opts) {
+        return this.authorizeClient.decide(token, permission, opts);
+    }
+    /**
+     * Force eviction of the JWKS and discovery caches.
+     * Call this after receiving a 401 from a resource server protected by the same issuer.
+     */
+    invalidateCache() {
+        this.verifier.invalidateCache();
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAG5E,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAEtD,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAIjD,MAAM,OAAO,YAAY;IACN,QAAQ,CAAe;IACvB,mBAAmB,CAAsB;IACzC,eAAe,CAAkB;IACjC,SAAS,CAAkB;IAE5C,YAAY,MAAoB;QAC9B,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;QACvC,IAAI,CAAC,SAAS,GAAG,IAAI,eAAe,CAAC,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,YAAY,CAAC,CAAC;QACjF,IAAI,CAAC,QAAQ,GAAG,IAAI,YAAY,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QAC3D,IAAI,CAAC,mBAAmB,GAAG,IAAI,mBAAmB,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC9F,IAAI,CAAC,eAAe,GAAG,IAAI,eAAe,CAAC,QAAQ,CAAC,CAAC;IACvD,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,WAAW,CAAC,KAAa;QAC7B,OAAO,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;IAC1C,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,UAAU,CAAC,KAAa,EAAE,aAAgD;QAC9E,OAAO,IAAI,CAAC,mBAAmB,CAAC,UAAU,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;IACnE,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,SAAS,CAAC,KAAa,EAAE,UAAkB,EAAE,IAAuB;QACxE,OAAO,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,CAAC,CAAC;IAC9D,CAAC;IAED;;;OAGG;IACH,eAAe;QACb,IAAI,CAAC,QAAQ,CAAC,eAAe,EAAE,CAAC;IAClC,CAAC;CACF"}

package/dist/config.d.ts

@@ -0,0 +1,47 @@
+/** §1 — HearthConfig: spec-compliant configuration for HearthClient. */
+export interface HearthConfig {
+    /** OIDC issuer URL. JWKS and introspection endpoints are auto-discovered from here. */
+    issuer_url: string;
+    /** OAuth2 client ID used for introspection. */
+    client_id: string;
+    /** OAuth2 client secret used for introspection. */
+    client_secret: string;
+    /** Optional accepted audience (string or array). Omit to skip audience validation. */
+    audience?: string | string[];
+    /** JWKS cache TTL in milliseconds. Defaults to 5 minutes; hard cap 24 hours. */
+    jwks_ttl?: number;
+    /** Override introspection endpoint URL (auto-discovered if omitted). */
+    introspection_endpoint?: string;
+    /** HTTP request timeout in milliseconds. Default: 10 000. */
+    http_timeout?: number;
+    /** Clock skew tolerance in seconds for exp/iat validation. Default: 60. */
+    clock_skew_seconds?: number;
+    /**
+     * Realm UUID. Required for endpoints that need `X-Realm-ID` (introspection mode,
+     * decision mode via `POST /oauth/authorize`).
+     */
+    realm_id?: string;
+    /**
+     * Override the decision endpoint URL. Defaults to `{issuer_url}/oauth/authorize`.
+     * Only used when `expectedMode` is `"decision"`.
+     */
+    authorize_endpoint?: string;
+}
+export declare const JWKS_TTL_DEFAULT_MS: number;
+export declare const JWKS_TTL_MAX_MS: number;
+export declare const HTTP_TIMEOUT_DEFAULT_MS = 10000;
+export declare const CLOCK_SKEW_DEFAULT_S = 60;
+export interface ResolvedConfig {
+    issuer_url: string;
+    client_id: string;
+    client_secret: string;
+    audience: string[];
+    jwks_ttl: number;
+    introspection_endpoint: string | null;
+    http_timeout: number;
+    clock_skew_seconds: number;
+    realm_id: string | null;
+    authorize_endpoint: string | null;
+}
+export declare function resolveConfig(config: HearthConfig): ResolvedConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,wEAAwE;AAIxE,MAAM,WAAW,YAAY;IAC3B,uFAAuF;IACvF,UAAU,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,aAAa,EAAE,MAAM,CAAC;IACtB,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC7B,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,6DAA6D;IAC7D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,eAAO,MAAM,mBAAmB,QAAgB,CAAC;AACjD,eAAO,MAAM,eAAe,QAAsB,CAAC;AACnD,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAC9C,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,cAAc,CAwBlE"}

package/dist/config.js

@@ -0,0 +1,33 @@
+/** §1 — HearthConfig: spec-compliant configuration for HearthClient. */
+import { ConfigurationError } from "./errors.js";
+export const JWKS_TTL_DEFAULT_MS = 5 * 60 * 1000; // 5 min
+export const JWKS_TTL_MAX_MS = 24 * 60 * 60 * 1000; // 24 h
+export const HTTP_TIMEOUT_DEFAULT_MS = 10_000;
+export const CLOCK_SKEW_DEFAULT_S = 60;
+export function resolveConfig(config) {
+    if (!config.issuer_url)
+        throw new ConfigurationError("issuer_url is required");
+    if (!config.client_id)
+        throw new ConfigurationError("client_id is required");
+    if (!config.client_secret)
+        throw new ConfigurationError("client_secret is required");
+    let jwks_ttl = config.jwks_ttl ?? JWKS_TTL_DEFAULT_MS;
+    if (jwks_ttl > JWKS_TTL_MAX_MS)
+        jwks_ttl = JWKS_TTL_MAX_MS;
+    const audience = config.audience
+        ? Array.isArray(config.audience) ? config.audience : [config.audience]
+        : [];
+    return {
+        issuer_url: config.issuer_url.replace(/\/$/, ""),
+        client_id: config.client_id,
+        client_secret: config.client_secret,
+        audience,
+        jwks_ttl,
+        introspection_endpoint: config.introspection_endpoint ?? null,
+        http_timeout: config.http_timeout ?? HTTP_TIMEOUT_DEFAULT_MS,
+        clock_skew_seconds: config.clock_skew_seconds ?? CLOCK_SKEW_DEFAULT_S,
+        realm_id: config.realm_id ?? null,
+        authorize_endpoint: config.authorize_endpoint ?? null,
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,wEAAwE;AAExE,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AA+BjD,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAI,QAAQ;AAC7D,MAAM,CAAC,MAAM,eAAe,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAE,OAAO;AAC5D,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC;AAC9C,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAC;AAevC,MAAM,UAAU,aAAa,CAAC,MAAoB;IAChD,IAAI,CAAC,MAAM,CAAC,UAAU;QAAE,MAAM,IAAI,kBAAkB,CAAC,wBAAwB,CAAC,CAAC;IAC/E,IAAI,CAAC,MAAM,CAAC,SAAS;QAAE,MAAM,IAAI,kBAAkB,CAAC,uBAAuB,CAAC,CAAC;IAC7E,IAAI,CAAC,MAAM,CAAC,aAAa;QAAE,MAAM,IAAI,kBAAkB,CAAC,2BAA2B,CAAC,CAAC;IAErF,IAAI,QAAQ,GAAG,MAAM,CAAC,QAAQ,IAAI,mBAAmB,CAAC;IACtD,IAAI,QAAQ,GAAG,eAAe;QAAE,QAAQ,GAAG,eAAe,CAAC;IAE3D,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ;QAC9B,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC;QACtE,CAAC,CAAC,EAAE,CAAC;IAEP,OAAO;QACL,UAAU,EAAE,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC;QAChD,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,aAAa,EAAE,MAAM,CAAC,aAAa;QACnC,QAAQ;QACR,QAAQ;QACR,sBAAsB,EAAE,MAAM,CAAC,sBAAsB,IAAI,IAAI;QAC7D,YAAY,EAAE,MAAM,CAAC,YAAY,IAAI,uBAAuB;QAC5D,kBAAkB,EAAE,MAAM,CAAC,kBAAkB,IAAI,oBAAoB;QACrE,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,IAAI;QACjC,kBAAkB,EAAE,MAAM,CAAC,kBAAkB,IAAI,IAAI;KACtD,CAAC;AACJ,CAAC"}

package/dist/config.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=config.test.d.ts.map

package/dist/config.test.d.ts.map

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

package/dist/config.test.js

@@ -0,0 +1,36 @@
+import { describe, it, expect } from "vitest";
+import { resolveConfig, JWKS_TTL_MAX_MS, JWKS_TTL_DEFAULT_MS, CLOCK_SKEW_DEFAULT_S, HTTP_TIMEOUT_DEFAULT_MS } from "./config.js";
+import { ConfigurationError } from "./errors.js";
+describe("resolveConfig", () => {
+    const base = { issuer_url: "https://auth.example.com", client_id: "cid", client_secret: "sec" };
+    it("applies defaults", () => {
+        const r = resolveConfig(base);
+        expect(r.jwks_ttl).toBe(JWKS_TTL_DEFAULT_MS);
+        expect(r.http_timeout).toBe(HTTP_TIMEOUT_DEFAULT_MS);
+        expect(r.clock_skew_seconds).toBe(CLOCK_SKEW_DEFAULT_S);
+        expect(r.audience).toEqual([]);
+        expect(r.introspection_endpoint).toBeNull();
+    });
+    it("strips trailing slash from issuer_url", () => {
+        const r = resolveConfig({ ...base, issuer_url: "https://auth.example.com/" });
+        expect(r.issuer_url).toBe("https://auth.example.com");
+    });
+    it("caps jwks_ttl at 24h", () => {
+        const r = resolveConfig({ ...base, jwks_ttl: JWKS_TTL_MAX_MS + 1 });
+        expect(r.jwks_ttl).toBe(JWKS_TTL_MAX_MS);
+    });
+    it("normalizes audience string to array", () => {
+        const r = resolveConfig({ ...base, audience: "api.example.com" });
+        expect(r.audience).toEqual(["api.example.com"]);
+    });
+    it("throws ConfigurationError on missing issuer_url", () => {
+        expect(() => resolveConfig({ ...base, issuer_url: "" })).toThrow(ConfigurationError);
+    });
+    it("throws ConfigurationError on missing client_id", () => {
+        expect(() => resolveConfig({ ...base, client_id: "" })).toThrow(ConfigurationError);
+    });
+    it("throws ConfigurationError on missing client_secret", () => {
+        expect(() => resolveConfig({ ...base, client_secret: "" })).toThrow(ConfigurationError);
+    });
+});
+//# sourceMappingURL=config.test.js.map

package/dist/config.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.test.js","sourceRoot":"","sources":["../src/config.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC;AACjI,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD,QAAQ,CAAC,eAAe,EAAE,GAAG,EAAE;IAC7B,MAAM,IAAI,GAAG,EAAE,UAAU,EAAE,0BAA0B,EAAE,SAAS,EAAE,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC;IAEhG,EAAE,CAAC,kBAAkB,EAAE,GAAG,EAAE;QAC1B,MAAM,CAAC,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;QAC9B,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;QAC7C,MAAM,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;QACrD,MAAM,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;QACxD,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC/B,MAAM,CAAC,CAAC,CAAC,sBAAsB,CAAC,CAAC,QAAQ,EAAE,CAAC;IAC9C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,uCAAuC,EAAE,GAAG,EAAE;QAC/C,MAAM,CAAC,GAAG,aAAa,CAAC,EAAE,GAAG,IAAI,EAAE,UAAU,EAAE,2BAA2B,EAAE,CAAC,CAAC;QAC9E,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC;IACxD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sBAAsB,EAAE,GAAG,EAAE;QAC9B,MAAM,CAAC,GAAG,aAAa,CAAC,EAAE,GAAG,IAAI,EAAE,QAAQ,EAAE,eAAe,GAAG,CAAC,EAAE,CAAC,CAAC;QACpE,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,qCAAqC,EAAE,GAAG,EAAE;QAC7C,MAAM,CAAC,GAAG,aAAa,CAAC,EAAE,GAAG,IAAI,EAAE,QAAQ,EAAE,iBAAiB,EAAE,CAAC,CAAC;QAClE,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC;IAClD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iDAAiD,EAAE,GAAG,EAAE;QACzD,MAAM,CAAC,GAAG,EAAE,CAAC,aAAa,CAAC,EAAE,GAAG,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACvF,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gDAAgD,EAAE,GAAG,EAAE;QACxD,MAAM,CAAC,GAAG,EAAE,CAAC,aAAa,CAAC,EAAE,GAAG,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACtF,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oDAAoD,EAAE,GAAG,EAAE;QAC5D,MAAM,CAAC,GAAG,EAAE,CAAC,aAAa,CAAC,EAAE,GAAG,IAAI,EAAE,aAAa,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAC1F,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/discovery.d.ts

@@ -0,0 +1,22 @@
+/** §1 — OIDC auto-discovery from {issuer_url}/.well-known/openid-configuration */
+export interface OidcDiscovery {
+    issuer: string;
+    jwks_uri: string;
+    introspection_endpoint?: string;
+    authorization_endpoint?: string;
+    token_endpoint?: string;
+    userinfo_endpoint?: string;
+    [key: string]: unknown;
+}
+export declare class DiscoveryClient {
+    private readonly issuerUrl;
+    private readonly httpTimeout;
+    private cache;
+    private fetchPromise;
+    constructor(issuerUrl: string, httpTimeout: number);
+    discover(): Promise<OidcDiscovery>;
+    private fetchDiscovery;
+    /** Reset cached discovery document (e.g. for testing or after key rotation). */
+    reset(): void;
+}
+//# sourceMappingURL=discovery.d.ts.map

package/dist/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAIlF,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,qBAAa,eAAe;IAKxB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,WAAW;IAL9B,OAAO,CAAC,KAAK,CAA8B;IAC3C,OAAO,CAAC,YAAY,CAAuC;gBAGxC,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM;IAGhC,QAAQ,IAAI,OAAO,CAAC,aAAa,CAAC;YAgB1B,cAAc;IA0B5B,gFAAgF;IAChF,KAAK,IAAI,IAAI;CAGd"}

package/dist/discovery.js

@@ -0,0 +1,60 @@
+/** §1 — OIDC auto-discovery from {issuer_url}/.well-known/openid-configuration */
+import { DiscoveryError } from "./errors.js";
+export class DiscoveryClient {
+    issuerUrl;
+    httpTimeout;
+    cache = null;
+    fetchPromise = null;
+    constructor(issuerUrl, httpTimeout) {
+        this.issuerUrl = issuerUrl;
+        this.httpTimeout = httpTimeout;
+    }
+    async discover() {
+        if (this.cache)
+            return this.cache;
+        // Deduplicate concurrent calls
+        if (!this.fetchPromise) {
+            this.fetchPromise = this.fetchDiscovery().then((doc) => {
+                this.cache = doc;
+                this.fetchPromise = null;
+                return doc;
+            }).catch((err) => {
+                this.fetchPromise = null;
+                throw err;
+            });
+        }
+        return this.fetchPromise;
+    }
+    async fetchDiscovery() {
+        const url = `${this.issuerUrl}/.well-known/openid-configuration`;
+        let res;
+        try {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), this.httpTimeout);
+            res = await fetch(url, { signal: controller.signal });
+            clearTimeout(timer);
+        }
+        catch (err) {
+            throw new DiscoveryError(`OIDC discovery fetch failed: ${url}`, { cause: err });
+        }
+        if (!res.ok) {
+            throw new DiscoveryError(`OIDC discovery returned HTTP ${res.status}: ${url}`);
+        }
+        let doc;
+        try {
+            doc = await res.json();
+        }
+        catch (err) {
+            throw new DiscoveryError("OIDC discovery response is not valid JSON", { cause: err });
+        }
+        if (!doc.jwks_uri) {
+            throw new DiscoveryError("OIDC discovery document missing required field: jwks_uri");
+        }
+        return doc;
+    }
+    /** Reset cached discovery document (e.g. for testing or after key rotation). */
+    reset() {
+        this.cache = null;
+    }
+}
+//# sourceMappingURL=discovery.js.map

package/dist/discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../src/discovery.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAElF,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAY7C,MAAM,OAAO,eAAe;IAKP;IACA;IALX,KAAK,GAAyB,IAAI,CAAC;IACnC,YAAY,GAAkC,IAAI,CAAC;IAE3D,YACmB,SAAiB,EACjB,WAAmB;QADnB,cAAS,GAAT,SAAS,CAAQ;QACjB,gBAAW,GAAX,WAAW,CAAQ;IACnC,CAAC;IAEJ,KAAK,CAAC,QAAQ;QACZ,IAAI,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC,KAAK,CAAC;QAClC,+BAA+B;QAC/B,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC;YACvB,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,cAAc,EAAE,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE;gBACrD,IAAI,CAAC,KAAK,GAAG,GAAG,CAAC;gBACjB,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;gBACzB,OAAO,GAAG,CAAC;YACb,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;gBACf,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;gBACzB,MAAM,GAAG,CAAC;YACZ,CAAC,CAAC,CAAC;QACL,CAAC;QACD,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAEO,KAAK,CAAC,cAAc;QAC1B,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,SAAS,mCAAmC,CAAC;QACjE,IAAI,GAAa,CAAC;QAClB,IAAI,CAAC;YACH,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;YACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;YACrE,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC;YACtD,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,cAAc,CAAC,gCAAgC,GAAG,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;QAClF,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,MAAM,IAAI,cAAc,CAAC,gCAAgC,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC,CAAC;QACjF,CAAC;QACD,IAAI,GAAkB,CAAC;QACvB,IAAI,CAAC;YACH,GAAG,GAAG,MAAM,GAAG,CAAC,IAAI,EAAmB,CAAC;QAC1C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,cAAc,CAAC,2CAA2C,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;QACxF,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;YAClB,MAAM,IAAI,cAAc,CAAC,0DAA0D,CAAC,CAAC;QACvF,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,gFAAgF;IAChF,KAAK;QACH,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;CACF"}

package/dist/discovery.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=discovery.test.d.ts.map

package/dist/discovery.test.d.ts.map

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

package/dist/discovery.test.js

@@ -0,0 +1,77 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { DiscoveryClient } from "./discovery.js";
+import { DiscoveryError } from "./errors.js";
+const ISSUER = "https://auth.example.com";
+const DISCOVERY_DOC = {
+    issuer: ISSUER,
+    jwks_uri: `${ISSUER}/jwks`,
+    authorization_endpoint: `${ISSUER}/authorize`,
+    token_endpoint: `${ISSUER}/token`,
+    introspection_endpoint: `${ISSUER}/introspect`,
+};
+function mockFetch(response) {
+    return vi.spyOn(globalThis, "fetch").mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: async () => DISCOVERY_DOC,
+        ...response,
+    });
+}
+describe("DiscoveryClient", () => {
+    afterEach(() => vi.restoreAllMocks());
+    it("fetches and returns discovery document", async () => {
+        mockFetch({});
+        const client = new DiscoveryClient(ISSUER, 10_000);
+        const doc = await client.discover();
+        expect(doc.jwks_uri).toBe(`${ISSUER}/jwks`);
+        expect(doc.introspection_endpoint).toBe(`${ISSUER}/introspect`);
+    });
+    it("caches discovery document on second call (no re-fetch)", async () => {
+        const spy = mockFetch({});
+        const client = new DiscoveryClient(ISSUER, 10_000);
+        await client.discover();
+        await client.discover();
+        expect(spy).toHaveBeenCalledTimes(1);
+    });
+    it("deduplicates concurrent discover() calls", async () => {
+        const spy = mockFetch({});
+        const client = new DiscoveryClient(ISSUER, 10_000);
+        await Promise.all([client.discover(), client.discover(), client.discover()]);
+        expect(spy).toHaveBeenCalledTimes(1);
+    });
+    it("re-fetches after reset()", async () => {
+        const spy = mockFetch({});
+        const client = new DiscoveryClient(ISSUER, 10_000);
+        await client.discover();
+        client.reset();
+        await client.discover();
+        expect(spy).toHaveBeenCalledTimes(2);
+    });
+    it("throws DiscoveryError on non-OK response", async () => {
+        vi.spyOn(globalThis, "fetch").mockResolvedValue({ ok: false, status: 500 });
+        const client = new DiscoveryClient(ISSUER, 10_000);
+        await expect(client.discover()).rejects.toBeInstanceOf(DiscoveryError);
+    });
+    it("throws DiscoveryError on network failure", async () => {
+        vi.spyOn(globalThis, "fetch").mockRejectedValue(new Error("ECONNREFUSED"));
+        const client = new DiscoveryClient(ISSUER, 10_000);
+        await expect(client.discover()).rejects.toBeInstanceOf(DiscoveryError);
+    });
+    it("throws DiscoveryError when jwks_uri is missing from document", async () => {
+        vi.spyOn(globalThis, "fetch").mockResolvedValue({
+            ok: true,
+            json: async () => ({ issuer: ISSUER }),
+        });
+        const client = new DiscoveryClient(ISSUER, 10_000);
+        await expect(client.discover()).rejects.toBeInstanceOf(DiscoveryError);
+    });
+    it("throws DiscoveryError on invalid JSON response", async () => {
+        vi.spyOn(globalThis, "fetch").mockResolvedValue({
+            ok: true,
+            json: async () => { throw new Error("invalid json"); },
+        });
+        const client = new DiscoveryClient(ISSUER, 10_000);
+        await expect(client.discover()).rejects.toBeInstanceOf(DiscoveryError);
+    });
+});
+//# sourceMappingURL=discovery.test.js.map

package/dist/discovery.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.test.js","sourceRoot":"","sources":["../src/discovery.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C,MAAM,MAAM,GAAG,0BAA0B,CAAC;AAC1C,MAAM,aAAa,GAAG;IACpB,MAAM,EAAE,MAAM;IACd,QAAQ,EAAE,GAAG,MAAM,OAAO;IAC1B,sBAAsB,EAAE,GAAG,MAAM,YAAY;IAC7C,cAAc,EAAE,GAAG,MAAM,QAAQ;IACjC,sBAAsB,EAAE,GAAG,MAAM,aAAa;CAC/C,CAAC;AAEF,SAAS,SAAS,CAAC,QAA+D;IAChF,OAAO,EAAE,CAAC,KAAK,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,iBAAiB,CAAC;QACrD,EAAE,EAAE,IAAI;QACR,MAAM,EAAE,GAAG;QACX,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,aAAa;QAC/B,GAAG,QAAQ;KACA,CAAC,CAAC;AACjB,CAAC;AAED,QAAQ,CAAC,iBAAiB,EAAE,GAAG,EAAE;IAC/B,SAAS,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,eAAe,EAAE,CAAC,CAAC;IAEtC,EAAE,CAAC,wCAAwC,EAAE,KAAK,IAAI,EAAE;QACtD,SAAS,CAAC,EAAE,CAAC,CAAC;QACd,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACnD,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,QAAQ,EAAE,CAAC;QACpC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,GAAG,MAAM,OAAO,CAAC,CAAC;QAC5C,MAAM,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC,IAAI,CAAC,GAAG,MAAM,aAAa,CAAC,CAAC;IAClE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,wDAAwD,EAAE,KAAK,IAAI,EAAE;QACtE,MAAM,GAAG,GAAG,SAAS,CAAC,EAAE,CAAC,CAAC;QAC1B,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACnD,MAAM,MAAM,CAAC,QAAQ,EAAE,CAAC;QACxB,MAAM,MAAM,CAAC,QAAQ,EAAE,CAAC;QACxB,MAAM,CAAC,GAAG,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0CAA0C,EAAE,KAAK,IAAI,EAAE;QACxD,MAAM,GAAG,GAAG,SAAS,CAAC,EAAE,CAAC,CAAC;QAC1B,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACnD,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,QAAQ,EAAE,EAAE,MAAM,CAAC,QAAQ,EAAE,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;QAC7E,MAAM,CAAC,GAAG,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0BAA0B,EAAE,KAAK,IAAI,EAAE;QACxC,MAAM,GAAG,GAAG,SAAS,CAAC,EAAE,CAAC,CAAC;QAC1B,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACnD,MAAM,MAAM,CAAC,QAAQ,EAAE,CAAC;QACxB,MAAM,CAAC,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,CAAC,QAAQ,EAAE,CAAC;QACxB,MAAM,CAAC,GAAG,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0CAA0C,EAAE,KAAK,IAAI,EAAE;QACxD,EAAE,CAAC,KAAK,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,iBAAiB,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAc,CAAC,CAAC;QACxF,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACnD,MAAM,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,OAAO,CAAC,cAAc,CAAC,cAAc,CAAC,CAAC;IACzE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0CAA0C,EAAE,KAAK,IAAI,EAAE;QACxD,EAAE,CAAC,KAAK,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,iBAAiB,CAAC,IAAI,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC;QAC3E,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACnD,MAAM,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,OAAO,CAAC,cAAc,CAAC,cAAc,CAAC,CAAC;IACzE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,8DAA8D,EAAE,KAAK,IAAI,EAAE;QAC5E,EAAE,CAAC,KAAK,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,iBAAiB,CAAC;YAC9C,EAAE,EAAE,IAAI;YACR,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;SAC3B,CAAC,CAAC;QACf,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACnD,MAAM,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,OAAO,CAAC,cAAc,CAAC,cAAc,CAAC,CAAC;IACzE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gDAAgD,EAAE,KAAK,IAAI,EAAE;QAC9D,EAAE,CAAC,KAAK,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,iBAAiB,CAAC;YAC9C,EAAE,EAAE,IAAI;YACR,IAAI,EAAE,KAAK,IAAI,EAAE,GAAG,MAAM,IAAI,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;SAChC,CAAC,CAAC;QAC1B,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACnD,MAAM,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,OAAO,CAAC,cAAc,CAAC,cAAc,CAAC,CAAC;IACzE,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}