@hearth-auth/node 0.0.1

package/dist/introspect.test.js

@@ -0,0 +1,109 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { IntrospectionClient } from "./introspect.js";
+import { IntrospectionError } from "./errors.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",
+    http_timeout: 10_000,
+    clock_skew_seconds: 60,
+    realm_id: null,
+    authorize_endpoint: null,
+};
+const DISCOVERY = {
+    issuer: "https://auth.example.com",
+    jwks_uri: "https://auth.example.com/jwks",
+    introspection_endpoint: "https://auth.example.com/introspect",
+};
+function makeClient(overrides = {}) {
+    return new IntrospectionClient({ ...CONFIG, ...overrides }, async () => DISCOVERY);
+}
+describe("IntrospectionClient", () => {
+    afterEach(() => vi.restoreAllMocks());
+    it("returns active IntrospectionResult with all required fields", async () => {
+        const raw = {
+            active: true,
+            sub: "user123",
+            iss: "https://auth.example.com",
+            aud: ["api.example.com"],
+            exp: 1_700_003_600,
+            iat: 1_700_000_000,
+            scope: "openid profile",
+            custom_field: "value",
+        };
+        vi.spyOn(globalThis, "fetch").mockResolvedValue({
+            ok: true,
+            json: async () => raw,
+        });
+        const result = await makeClient().introspect("token123");
+        expect(result.active).toBe(true);
+        expect(result.sub).toBe("user123");
+        expect(result.iss).toBe("https://auth.example.com");
+        expect(result.aud).toEqual(["api.example.com"]);
+        expect(result.exp).toBe(1_700_003_600);
+        expect(result.iat).toBe(1_700_000_000);
+        expect(result.scope).toBe("openid profile");
+        expect(result.extra.custom_field).toBe("value");
+    });
+    it("returns inactive result when active=false", async () => {
+        vi.spyOn(globalThis, "fetch").mockResolvedValue({
+            ok: true,
+            json: async () => ({ active: false }),
+        });
+        const result = await makeClient().introspect("dead-token");
+        expect(result.active).toBe(false);
+        expect(result.sub).toBeUndefined();
+    });
+    it("uses configured introspection_endpoint without discovery", async () => {
+        const spy = vi.spyOn(globalThis, "fetch").mockResolvedValue({
+            ok: true,
+            json: async () => ({ active: true }),
+        });
+        await makeClient().introspect("tok");
+        expect(spy).toHaveBeenCalledWith("https://auth.example.com/introspect", expect.objectContaining({ method: "POST" }));
+    });
+    it("discovers introspection endpoint when not configured", async () => {
+        const spy = vi.spyOn(globalThis, "fetch").mockResolvedValue({
+            ok: true,
+            json: async () => ({ active: true }),
+        });
+        const client = new IntrospectionClient({ ...CONFIG, introspection_endpoint: null }, async () => DISCOVERY);
+        await client.introspect("tok");
+        expect(spy.mock.calls[0][0]).toBe("https://auth.example.com/introspect");
+    });
+    it("throws IntrospectionError on non-OK HTTP response", async () => {
+        vi.spyOn(globalThis, "fetch").mockResolvedValue({
+            ok: false,
+            status: 401,
+        });
+        await expect(makeClient().introspect("tok")).rejects.toBeInstanceOf(IntrospectionError);
+    });
+    it("throws IntrospectionError on network failure", async () => {
+        vi.spyOn(globalThis, "fetch").mockRejectedValue(new Error("ECONNREFUSED"));
+        await expect(makeClient().introspect("tok")).rejects.toBeInstanceOf(IntrospectionError);
+    });
+    it("throws IntrospectionError on invalid JSON response", async () => {
+        vi.spyOn(globalThis, "fetch").mockResolvedValue({
+            ok: true,
+            json: async () => { throw new Error("bad json"); },
+        });
+        await expect(makeClient().introspect("tok")).rejects.toBeInstanceOf(IntrospectionError);
+    });
+    it("throws IntrospectionError when endpoint missing from discovery", async () => {
+        const client = new IntrospectionClient({ ...CONFIG, introspection_endpoint: null }, async () => ({ issuer: "https://auth.example.com", jwks_uri: "https://auth.example.com/jwks" }));
+        await expect(client.introspect("tok")).rejects.toBeInstanceOf(IntrospectionError);
+    });
+    it("passes token_type_hint when provided", async () => {
+        const spy = vi.spyOn(globalThis, "fetch").mockResolvedValue({
+            ok: true,
+            json: async () => ({ active: true }),
+        });
+        await makeClient().introspect("tok", "refresh_token");
+        const body = spy.mock.calls[0][1]?.body;
+        expect(String(body)).toContain("token_type_hint=refresh_token");
+    });
+});
+//# sourceMappingURL=introspect.test.js.map

package/dist/introspect.test.js.map

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

package/dist/jwks.d.ts

@@ -0,0 +1,26 @@
+/** §2 — JWKS-backed token verification with cache-control, background refresh, and 401 re-fetch. */
+import type { JWSHeaderParameters, FlattenedJWSInput, GetKeyFunction } from "jose";
+import { DiscoveryClient } from "./discovery.js";
+import { VerifiedToken } from "./token.js";
+import type { ResolvedConfig } from "./config.js";
+/** Key resolver type — the common base accepted by jwtVerify. */
+type JwkKeyArg = GetKeyFunction<JWSHeaderParameters, FlattenedJWSInput>;
+/** Testability hook: override how the JWK set is built (e.g. use createLocalJWKSet in tests). */
+export type JwkSetFactory = (jwksUri: string, ttlMs: number) => JwkKeyArg;
+export declare class JwksVerifier {
+    private readonly discovery;
+    private remoteJwkSet;
+    private readonly config;
+    private refreshTimer;
+    private readonly jwkSetFactory;
+    constructor(config: ResolvedConfig, discovery?: DiscoveryClient, jwkSetFactory?: JwkSetFactory);
+    private buildJwkSet;
+    private scheduleBackgroundRefresh;
+    private getJwkSet;
+    /** Verify a JWT using the JWKS endpoint. Supports RS256 and ES256. */
+    verifyToken(token: string): Promise<VerifiedToken>;
+    /** Force JWKS cache eviction (e.g. on receiving a 401 from a resource server). */
+    invalidateCache(): void;
+}
+export {};
+//# sourceMappingURL=jwks.d.ts.map

package/dist/jwks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jwks.d.ts","sourceRoot":"","sources":["../src/jwks.ts"],"names":[],"mappings":"AAAA,oGAAoG;AAGpG,OAAO,KAAK,EAAyC,mBAAmB,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,MAAM,CAAC;AAC1H,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEjD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,iEAAiE;AACjE,KAAK,SAAS,GAAG,cAAc,CAAC,mBAAmB,EAAE,iBAAiB,CAAC,CAAC;AAExE,iGAAiG;AACjG,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,SAAS,CAAC;AAE1E,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkB;IAC5C,OAAO,CAAC,YAAY,CAA0B;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,YAAY,CAA8C;IAClE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;gBAElC,MAAM,EAAE,cAAc,EAAE,SAAS,CAAC,EAAE,eAAe,EAAE,aAAa,CAAC,EAAE,aAAa;YAQhF,WAAW;IAgBzB,OAAO,CAAC,yBAAyB;YAcnB,SAAS;IAOvB,sEAAsE;IAChE,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAoDxD,kFAAkF;IAClF,eAAe,IAAI,IAAI;CAQxB"}

package/dist/jwks.js

@@ -0,0 +1,106 @@
+/** §2 — JWKS-backed token verification with cache-control, background refresh, and 401 re-fetch. */
+import { createRemoteJWKSet, jwtVerify, errors as joseErrors } from "jose";
+import { DiscoveryClient } from "./discovery.js";
+import { JWKSFetchError, TokenVerificationError, TokenExpiredError, TokenClaimsError } from "./errors.js";
+import { VerifiedToken } from "./token.js";
+export class JwksVerifier {
+    discovery;
+    remoteJwkSet = null;
+    config;
+    refreshTimer = null;
+    jwkSetFactory;
+    constructor(config, discovery, jwkSetFactory) {
+        this.config = config;
+        this.discovery = discovery ?? new DiscoveryClient(config.issuer_url, config.http_timeout);
+        this.jwkSetFactory = jwkSetFactory ?? ((uri, ttl) => createRemoteJWKSet(new URL(uri), { cacheMaxAge: ttl, cooldownDuration: 30_000 }));
+    }
+    async buildJwkSet() {
+        let jwksUri;
+        try {
+            const doc = await this.discovery.discover();
+            jwksUri = doc.jwks_uri;
+        }
+        catch (err) {
+            if (err instanceof JWKSFetchError)
+                throw err;
+            throw new JWKSFetchError("Failed to discover JWKS URI", { cause: err });
+        }
+        const cacheMaxAge = Math.min(this.config.jwks_ttl, 24 * 60 * 60 * 1000);
+        const jwkSet = this.jwkSetFactory(jwksUri, cacheMaxAge);
+        this.scheduleBackgroundRefresh(cacheMaxAge);
+        return jwkSet;
+    }
+    scheduleBackgroundRefresh(ttlMs) {
+        if (this.refreshTimer)
+            clearTimeout(this.refreshTimer);
+        // Background refresh at 80% of TTL to warm cache before expiry
+        const delay = Math.max(ttlMs * 0.8, 60_000);
+        this.refreshTimer = setTimeout(() => {
+            this.remoteJwkSet = null;
+            // Fire-and-forget: re-prime the JWK set; errors are silently swallowed
+            // to avoid crashing background timers. The next verify() call will retry.
+            this.getJwkSet().catch(() => undefined);
+        }, delay);
+        // Don't block process exit
+        if (this.refreshTimer.unref)
+            this.refreshTimer.unref();
+    }
+    async getJwkSet() {
+        if (!this.remoteJwkSet) {
+            this.remoteJwkSet = await this.buildJwkSet();
+        }
+        return this.remoteJwkSet;
+    }
+    /** Verify a JWT using the JWKS endpoint. Supports RS256 and ES256. */
+    async verifyToken(token) {
+        const jwkSet = await this.getJwkSet();
+        const verifyOptions = {
+            issuer: this.config.issuer_url,
+            clockTolerance: this.config.clock_skew_seconds,
+            algorithms: ["RS256", "ES256", "RS384", "ES384", "RS512", "ES512", "EdDSA"],
+        };
+        if (this.config.audience.length > 0) {
+            verifyOptions.audience = this.config.audience;
+        }
+        try {
+            const result = await jwtVerify(token, jwkSet, verifyOptions);
+            return new VerifiedToken(result.payload, result.protectedHeader);
+        }
+        catch (err) {
+            if (err instanceof joseErrors.JWTExpired) {
+                const expiredAt = err.payload?.exp ? new Date(err.payload.exp * 1000) : new Date(0);
+                throw new TokenExpiredError(expiredAt, { cause: err });
+            }
+            if (err instanceof joseErrors.JWKSNoMatchingKey ||
+                err instanceof joseErrors.JWKSMultipleMatchingKeys) {
+                // JWKS key not found — re-fetch once and retry (handles key rotation / 401-like scenario)
+                this.remoteJwkSet = null;
+                const freshSet = await this.getJwkSet().catch((e) => {
+                    throw new JWKSFetchError("JWKS re-fetch after key miss failed", { cause: e });
+                });
+                try {
+                    const result = await jwtVerify(token, freshSet, verifyOptions);
+                    return new VerifiedToken(result.payload, result.protectedHeader);
+                }
+                catch (retryErr) {
+                    throw new TokenVerificationError("Token verification failed after JWKS refresh", { cause: retryErr });
+                }
+            }
+            if (err instanceof joseErrors.JWTClaimValidationFailed ||
+                err instanceof joseErrors.JWTInvalid) {
+                throw new TokenClaimsError(`Token claim validation failed: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+            }
+            throw new TokenVerificationError(`Token verification failed: ${err instanceof Error ? err.message : "unknown error"}`, { cause: err });
+        }
+    }
+    /** Force JWKS cache eviction (e.g. on receiving a 401 from a resource server). */
+    invalidateCache() {
+        this.remoteJwkSet = null;
+        this.discovery.reset();
+        if (this.refreshTimer) {
+            clearTimeout(this.refreshTimer);
+            this.refreshTimer = null;
+        }
+    }
+}
+//# sourceMappingURL=jwks.js.map

package/dist/jwks.js.map

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

package/dist/jwks.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * §9 — JWKS verification tests:
+ *   - key rotation integration (re-fetch after key miss)
+ *   - clock skew boundary (exp/iat at exact tolerance)
+ */
+export {};
+//# sourceMappingURL=jwks.test.d.ts.map

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

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

package/dist/jwks.test.js

@@ -0,0 +1,154 @@
+/**
+ * §9 — JWKS verification tests:
+ *   - key rotation integration (re-fetch after key miss)
+ *   - clock skew boundary (exp/iat at exact tolerance)
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import * as jose from "jose";
+import { JwksVerifier } from "./jwks.js";
+import { DiscoveryClient } from "./discovery.js";
+import { TokenExpiredError, JWKSFetchError } from "./errors.js";
+import { JWKS_TTL_DEFAULT_MS, HTTP_TIMEOUT_DEFAULT_MS, CLOCK_SKEW_DEFAULT_S } from "./config.js";
+const ISSUER = "https://auth.example.com";
+function makeConfig(overrides = {}) {
+    return {
+        issuer_url: ISSUER,
+        client_id: "test-client",
+        client_secret: "test-secret",
+        audience: [],
+        jwks_ttl: JWKS_TTL_DEFAULT_MS,
+        introspection_endpoint: null,
+        http_timeout: HTTP_TIMEOUT_DEFAULT_MS,
+        clock_skew_seconds: CLOCK_SKEW_DEFAULT_S,
+        realm_id: null,
+        authorize_endpoint: null,
+        ...overrides,
+    };
+}
+async function generateKeyPair(alg = "RS256") {
+    const { privateKey, publicKey } = await jose.generateKeyPair(alg);
+    const kid = `key-${alg}-${Date.now()}`;
+    const jwk = await jose.exportJWK(publicKey);
+    return { privateKey, publicKey, kid, jwk: { ...jwk, kid, alg, use: "sig" } };
+}
+async function signToken(payload, privateKey, alg, kid) {
+    return new jose.SignJWT(payload)
+        .setProtectedHeader({ alg, kid })
+        .sign(privateKey);
+}
+/** Build a JwkSetFactory that serves a local (in-memory) JWKS, no network needed. */
+function makeLocalFactory(jwks) {
+    return (_uri, _ttl) => jose.createLocalJWKSet(jwks);
+}
+/** Stub DiscoveryClient — never makes network calls. */
+function stubDiscovery() {
+    const d = new DiscoveryClient(ISSUER, HTTP_TIMEOUT_DEFAULT_MS);
+    vi.spyOn(d, "discover").mockResolvedValue({
+        issuer: ISSUER,
+        jwks_uri: `${ISSUER}/.well-known/jwks.json`,
+        introspection_endpoint: `${ISSUER}/introspect`,
+    });
+    return d;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Clock skew boundary tests (§9)
+// ─────────────────────────────────────────────────────────────────────────────
+describe("JwksVerifier — clock skew boundary (§9)", () => {
+    const NOW = 1_700_000_000;
+    beforeEach(() => {
+        vi.useFakeTimers();
+        vi.setSystemTime(NOW * 1000);
+    });
+    afterEach(() => {
+        vi.useRealTimers();
+        vi.restoreAllMocks();
+    });
+    it("accepts token with exp = now + skew_tolerance (boundary valid)", async () => {
+        const kp = await generateKeyPair("RS256");
+        // exp is now + clockSkew — still within tolerance (not yet expired)
+        const exp = NOW + CLOCK_SKEW_DEFAULT_S;
+        const token = await signToken({ sub: "u1", iss: ISSUER, exp, iat: NOW - 10 }, kp.privateKey, "RS256", kp.kid);
+        const verifier = new JwksVerifier(makeConfig(), stubDiscovery(), makeLocalFactory({ keys: [kp.jwk] }));
+        const verified = await verifier.verifyToken(token);
+        expect(verified.subject()).toBe("u1");
+    });
+    it("rejects token with exp = now - skew_tolerance - 1 (just outside tolerance)", async () => {
+        const kp = await generateKeyPair("RS256");
+        const exp = NOW - CLOCK_SKEW_DEFAULT_S - 1;
+        const token = await signToken({ sub: "u1", iss: ISSUER, exp, iat: NOW - 200 }, kp.privateKey, "RS256", kp.kid);
+        const verifier = new JwksVerifier(makeConfig(), stubDiscovery(), makeLocalFactory({ keys: [kp.jwk] }));
+        await expect(verifier.verifyToken(token)).rejects.toBeInstanceOf(TokenExpiredError);
+    });
+    it("accepts token with iat = now + skew_tolerance (future iat within tolerance)", async () => {
+        const kp = await generateKeyPair("RS256");
+        const iat = NOW + CLOCK_SKEW_DEFAULT_S;
+        const exp = NOW + 3600;
+        const token = await signToken({ sub: "u1", iss: ISSUER, exp, iat }, kp.privateKey, "RS256", kp.kid);
+        const verifier = new JwksVerifier(makeConfig(), stubDiscovery(), makeLocalFactory({ keys: [kp.jwk] }));
+        const verified = await verifier.verifyToken(token);
+        expect(verified.subject()).toBe("u1");
+    });
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// JWKS key rotation integration (§9)
+// ─────────────────────────────────────────────────────────────────────────────
+describe("JwksVerifier — JWKS key rotation integration (§9)", () => {
+    afterEach(() => vi.restoreAllMocks());
+    it("re-fetches JWKS on key miss and succeeds with rotated key", async () => {
+        const oldKey = await generateKeyPair("RS256");
+        const newKey = await generateKeyPair("RS256");
+        const NOW_REAL = Math.floor(Date.now() / 1000);
+        const token = await signToken({ sub: "u1", iss: ISSUER, exp: NOW_REAL + 3600, iat: NOW_REAL }, newKey.privateKey, "RS256", newKey.kid);
+        // First factory call: stale JWKS with only old key; second: rotated JWKS
+        let factoryCallCount = 0;
+        const rotatingFactory = (_uri, _ttl) => {
+            factoryCallCount++;
+            const keys = factoryCallCount === 1 ? [oldKey.jwk] : [newKey.jwk];
+            return jose.createLocalJWKSet({ keys });
+        };
+        const verifier = new JwksVerifier(makeConfig(), stubDiscovery(), rotatingFactory);
+        // First call: miss on old key → JwksVerifier invalidates and calls factory again
+        const verified = await verifier.verifyToken(token);
+        expect(verified.subject()).toBe("u1");
+        // Should have called factory at least twice (once for old, once for new)
+        expect(factoryCallCount).toBeGreaterThanOrEqual(2);
+    });
+    it("throws JWKSFetchError when OIDC discovery is unreachable", async () => {
+        const discovery = stubDiscovery();
+        vi.spyOn(discovery, "discover").mockRejectedValue(new Error("ECONNREFUSED"));
+        const verifier = new JwksVerifier(makeConfig(), discovery);
+        // JWKSFetchError is thrown when discovery/JWKS cannot be reached; it's a HearthError subtype
+        await expect(verifier.verifyToken("dummy.token.here")).rejects.toBeInstanceOf(JWKSFetchError);
+    });
+    it("invalidateCache forces new factory call on next verifyToken", async () => {
+        const kp = await generateKeyPair("ES256");
+        const NOW_REAL = Math.floor(Date.now() / 1000);
+        const token = await signToken({ sub: "u2", iss: ISSUER, exp: NOW_REAL + 3600, iat: NOW_REAL }, kp.privateKey, "ES256", kp.kid);
+        let factoryCallCount = 0;
+        const countingFactory = (_uri, _ttl) => {
+            factoryCallCount++;
+            return jose.createLocalJWKSet({ keys: [kp.jwk] });
+        };
+        const verifier = new JwksVerifier(makeConfig(), stubDiscovery(), countingFactory);
+        await verifier.verifyToken(token);
+        const afterFirst = factoryCallCount;
+        verifier.invalidateCache();
+        await verifier.verifyToken(token);
+        expect(factoryCallCount).toBeGreaterThan(afterFirst);
+    });
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// Algorithm support
+// ─────────────────────────────────────────────────────────────────────────────
+describe("JwksVerifier — algorithm support", () => {
+    afterEach(() => vi.restoreAllMocks());
+    it.each(["RS256", "ES256"])("verifies %s tokens", async (alg) => {
+        const kp = await generateKeyPair(alg);
+        const NOW_REAL = Math.floor(Date.now() / 1000);
+        const token = await signToken({ sub: `user-${alg}`, iss: ISSUER, exp: NOW_REAL + 3600, iat: NOW_REAL }, kp.privateKey, alg, kp.kid);
+        const verifier = new JwksVerifier(makeConfig(), stubDiscovery(), makeLocalFactory({ keys: [kp.jwk] }));
+        const verified = await verifier.verifyToken(token);
+        expect(verified.subject()).toBe(`user-${alg}`);
+    });
+});
+//# sourceMappingURL=jwks.test.js.map

package/dist/jwks.test.js.map

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

package/dist/middleware.d.ts

@@ -0,0 +1,61 @@
+/** §6 — Framework-decoupled Express and Fastify middleware for JWT verification. */
+import type { HearthConfig } from "./config.js";
+import type { VerifiedToken } from "./token.js";
+import type { AccessTokenAuthorizationMode } from "./token.js";
+export interface MiddlewareOptions extends HearthConfig {
+    /** If true (default), return 401 when no Bearer token is present. */
+    required?: boolean;
+    /** If provided, return 403 when the verified token is missing this scope. */
+    requiredScope?: string;
+    /** If provided, return 403 when the verified token is missing this role. */
+    requiredRole?: string;
+    /** If provided, return 403 when the verified token is missing this permission. */
+    requiredPermission?: string;
+    /**
+     * Authorization mode to enforce. Defaults to `"embedded"` (JWT claims only).
+     *
+     * - `"embedded"`: check permissions/roles from JWT claims — no network calls.
+     * - `"introspection"`: call `/introspect` for live RBAC data; reject on mode mismatch.
+     * - `"decision"`: call `POST /oauth/authorize` per-request; fail-closed on network errors.
+     *
+     * IMPORTANT: absence of `permissions` in a token MUST NOT silently fall back to
+     * a different mode. Set `expectedMode` explicitly for any non-embedded behavior.
+     */
+    expectedMode?: AccessTokenAuthorizationMode;
+}
+interface MinimalRequest {
+    headers: Record<string, string | string[] | undefined>;
+}
+interface MinimalResponse {
+    status(code: number): MinimalResponse;
+    setHeader?(name: string, value: string): void;
+    json(body: unknown): unknown;
+    send?(body: unknown): unknown;
+    header?(name: string, value: string): void;
+}
+declare global {
+    namespace Express {
+        interface Request {
+            hearthToken?: VerifiedToken;
+        }
+    }
+}
+type ExpressRequest = MinimalRequest & {
+    hearthToken?: VerifiedToken;
+};
+type NextFn = (err?: unknown) => void;
+/** Express-compatible middleware factory. Attaches verified token to `req.hearthToken`. */
+export declare function hearthMiddleware(options: MiddlewareOptions): (req: ExpressRequest, res: MinimalResponse, next: NextFn) => Promise<void>;
+interface FastifyRequest {
+    headers: Record<string, string | undefined>;
+    hearthToken?: VerifiedToken;
+}
+interface FastifyReply {
+    code(statusCode: number): FastifyReply;
+    header(name: string, value: string): FastifyReply;
+    send(body: unknown): void;
+}
+/** Fastify hook/plugin factory. Attaches verified token to `request.hearthToken`. */
+export declare function hearthFastifyHook(options: MiddlewareOptions): (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+export {};
+//# sourceMappingURL=middleware.d.ts.map

package/dist/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA,oFAAoF;AAGpF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAIhD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAC;AAK/D,MAAM,WAAW,iBAAkB,SAAQ,YAAY;IACrD,qEAAqE;IACrE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,6EAA6E;IAC7E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,4EAA4E;IAC5E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kFAAkF;IAClF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;;;OASG;IACH,YAAY,CAAC,EAAE,4BAA4B,CAAC;CAC7C;AAKD,UAAU,cAAc;IACtB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;CACxD;AAED,UAAU,eAAe;IACvB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAAC;IACtC,SAAS,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9C,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;IAC7B,IAAI,CAAC,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;IAC9B,MAAM,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5C;AAGD,OAAO,CAAC,MAAM,CAAC;IAEb,UAAU,OAAO,CAAC;QAChB,UAAU,OAAO;YACf,WAAW,CAAC,EAAE,aAAa,CAAC;SAC7B;KACF;CACF;AAED,KAAK,cAAc,GAAG,cAAc,GAAG;IAAE,WAAW,CAAC,EAAE,aAAa,CAAA;CAAE,CAAC;AACvE,KAAK,MAAM,GAAG,CAAC,GAAG,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;AA6FtC,2FAA2F;AAC3F,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,IAU3C,KAAK,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC,CAoDtF;AAID,UAAU,cAAc;IACtB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IAC5C,WAAW,CAAC,EAAE,aAAa,CAAC;CAC7B;AAED,UAAU,YAAY;IACpB,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,CAAC;IACvC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAAC;IAClD,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;CAC3B;AAED,qFAAqF;AACrF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,iBAAiB,IAU5C,SAAS,cAAc,EAAE,OAAO,YAAY,KAAG,OAAO,CAAC,IAAI,CAAC,CAoE3E"}