@hearth-auth/sdk 2.0.3 → 3.0.0

package/dist/introspection-client.js

@@ -1,8 +1,9 @@
+import { IntrospectionError } from "./errors.js";
 /**
  * Low-level RFC 7662 token introspection client.
  *
  * Results are never cached — per RFC 7662 §2.1, token state can change
- * at any time. Full error taxonomy will be added in §3.
+ * at any time.
  */
 export class IntrospectionClient {
     endpoint;
@@ -15,22 +16,42 @@ export class IntrospectionClient {
         this.clientSecret = config.clientSecret;
         this.httpTimeout = config.httpTimeout ?? 10_000;
     }
-    /** Introspect a token. Never cached per RFC 7662 §2.1. */
-    async introspect(token) {
+    /**
+     * Introspect a token. Never cached per RFC 7662 §2.1.
+     *
+     * @param tokenTypeHint - Optional RFC 7662 `token_type_hint`.
+     * @throws {@link IntrospectionError} when the request fails, the endpoint
+     *   answers non-2xx, or the response is not JSON.
+     */
+    async introspect(token, tokenTypeHint) {
         const credentials = btoa(`${this.clientId}:${this.clientSecret}`);
-        const resp = await fetch(this.endpoint, {
-            method: "POST",
-            headers: {
-                Authorization: `Basic ${credentials}`,
-                "Content-Type": "application/x-www-form-urlencoded",
-            },
-            body: new URLSearchParams({ token }),
-            signal: AbortSignal.timeout(this.httpTimeout),
-        });
+        const body = new URLSearchParams({ token });
+        if (tokenTypeHint)
+            body.set("token_type_hint", tokenTypeHint);
+        let resp;
+        try {
+            resp = await fetch(this.endpoint, {
+                method: "POST",
+                headers: {
+                    Authorization: `Basic ${credentials}`,
+                    "Content-Type": "application/x-www-form-urlencoded",
+                },
+                body,
+                signal: AbortSignal.timeout(this.httpTimeout),
+            });
+        }
+        catch (err) {
+            throw new IntrospectionError("Introspection request failed", err);
+        }
         if (!resp.ok) {
-            throw new Error(`Introspection endpoint returned HTTP ${resp.status}`);
+            throw new IntrospectionError(`Introspection endpoint returned HTTP ${resp.status}`);
+        }
+        try {
+            return (await resp.json());
+        }
+        catch (err) {
+            throw new IntrospectionError("Introspection response is not valid JSON", err);
         }
-        return resp.json();
     }
 }
 //# sourceMappingURL=introspection-client.js.map

package/dist/introspection-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"introspection-client.js","sourceRoot":"","sources":["../src/introspection-client.ts"],"names":[],"mappings":"AA8CA;;;;;GAKG;AACH,MAAM,OAAO,mBAAmB;IACb,QAAQ,CAAS;IACjB,QAAQ,CAAS;IACjB,YAAY,CAAS;IAC7B,WAAW,CAAS;IAE7B,YAAY,MAAiC;QAC3C,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,qBAAqB,CAAC;QAC7C,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;QAChC,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,YAAY,CAAC;QACxC,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,WAAW,IAAI,MAAM,CAAC;IAClD,CAAC;IAED,0DAA0D;IAC1D,KAAK,CAAC,UAAU,CAAC,KAAa;QAC5B,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC;QAClE,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE;YACtC,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,aAAa,EAAE,SAAS,WAAW,EAAE;gBACrC,cAAc,EAAE,mCAAmC;aACpD;YACD,IAAI,EAAE,IAAI,eAAe,CAAC,EAAE,KAAK,EAAE,CAAC;YACpC,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC;SAC9C,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CAAC,wCAAwC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QACzE,CAAC;QACD,OAAO,IAAI,CAAC,IAAI,EAAkC,CAAC;IACrD,CAAC;CACF"}
+{"version":3,"file":"introspection-client.js","sourceRoot":"","sources":["../src/introspection-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAgDjD;;;;;GAKG;AACH,MAAM,OAAO,mBAAmB;IACb,QAAQ,CAAS;IACjB,QAAQ,CAAS;IACjB,YAAY,CAAS;IAC7B,WAAW,CAAS;IAE7B,YAAY,MAAiC;QAC3C,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,qBAAqB,CAAC;QAC7C,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;QAChC,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,YAAY,CAAC;QACxC,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,WAAW,IAAI,MAAM,CAAC;IAClD,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,UAAU,CACd,KAAa,EACb,aAAgD;QAEhD,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC;QAClE,MAAM,IAAI,GAAG,IAAI,eAAe,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;QAC5C,IAAI,aAAa;YAAE,IAAI,CAAC,GAAG,CAAC,iBAAiB,EAAE,aAAa,CAAC,CAAC;QAE9D,IAAI,IAAc,CAAC;QACnB,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE;gBAChC,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE;oBACP,aAAa,EAAE,SAAS,WAAW,EAAE;oBACrC,cAAc,EAAE,mCAAmC;iBACpD;gBACD,IAAI;gBACJ,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC;aAC9C,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,kBAAkB,CAAC,8BAA8B,EAAE,GAAG,CAAC,CAAC;QACpE,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;YACb,MAAM,IAAI,kBAAkB,CAAC,wCAAwC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QACtF,CAAC;QACD,IAAI,CAAC;YACH,OAAO,CAAC,MAAM,IAAI,CAAC,IAAI,EAAE,CAAwB,CAAC;QACpD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,kBAAkB,CAAC,0CAA0C,EAAE,GAAG,CAAC,CAAC;QAChF,CAAC;IACH,CAAC;CACF"}

package/dist/jwks-client.d.ts

@@ -6,7 +6,7 @@ export interface VerifyOptions {
     issuer?: string;
     /** Expected `aud` claim(s). Skipped when absent. */
     audience?: string | string[];
-    /** Clock skew tolerance in seconds. Default: 60. */
+    /** Clock skew tolerance in seconds, applied to `exp` and `nbf`. Default: 5. */
     clockSkewSeconds?: number;
 }
 /** Configuration for {@link JwksClient}. */
@@ -63,7 +63,9 @@ export declare class JwksClient {
      * 3. `iss` — always, against `options.issuer` or the client's configured
      *    `issuer`. Throws {@link ConfigurationError} when neither is set.
      * 4. `aud` — when `options.audience` or the client's configured `audience` is set.
-     * 5. `iat` — within clock skew tolerance.
+     * 5. `nbf` — when present, within clock skew tolerance.
+     *
+     * `jose` performs every check above; this method only maps its errors.
      *
      * @throws {@link TokenExpiredError} when the token is expired.
      * @throws {@link TokenInvalidError} when the signature or structure is invalid.
@@ -73,6 +75,10 @@ export declare class JwksClient {
      * @throws {@link ConfigurationError} when no expected issuer is configured.
      */
     verify(token: string, options?: VerifyOptions): Promise<Claims>;
+    /**
+     * Map a `jose` error onto the SDK error taxonomy (openspec/specs/sdk-support-contract/spec.md).
+     * `issuer` and `audience` are the values the check actually used.
+     */
     private mapJoseError;
     /** Fetch the current JWKS keys from the endpoint. */
     fetchKeys(): Promise<JsonWebKey[]>;

package/dist/jwks-client.js

@@ -1,6 +1,6 @@
 import { createLocalJWKSet, jwtVerify, errors as joseErrors } from "jose";
 import { Claims } from "./claims.js";
-import { ConfigurationError, JWKSFetchError, TokenExpiredError, TokenInvalidError, TokenIssuerError, TokenAudienceError, } from "./errors.js";
+import { ConfigurationError, JWKSFetchError, TokenExpiredError, TokenInvalidError, TokenIssuerError, TokenAudienceError, TokenNotYetValidError, } from "./errors.js";
 /**
  * JWKS-backed JWT verifier with key caching, automatic key rotation,
  * and full EdDSA / Ed25519 signature verification (spec §2).
@@ -46,7 +46,9 @@ export class JwksClient {
      * 3. `iss` — always, against `options.issuer` or the client's configured
      *    `issuer`. Throws {@link ConfigurationError} when neither is set.
      * 4. `aud` — when `options.audience` or the client's configured `audience` is set.
-     * 5. `iat` — within clock skew tolerance.
+     * 5. `nbf` — when present, within clock skew tolerance.
+     *
+     * `jose` performs every check above; this method only maps its errors.
      *
      * @throws {@link TokenExpiredError} when the token is expired.
      * @throws {@link TokenInvalidError} when the signature or structure is invalid.
@@ -56,7 +58,7 @@ export class JwksClient {
      * @throws {@link ConfigurationError} when no expected issuer is configured.
      */
     async verify(token, options) {
-        const clockTolerance = options?.clockSkewSeconds ?? 60;
+        const clockTolerance = options?.clockSkewSeconds ?? 5;
         // Pin the issuer: fall back to the one this client was constructed with,
         // and refuse outright when neither is available. Verifying a signature
         // without checking `iss` accepts any token from any realm that shares this
@@ -77,6 +79,8 @@ export class JwksClient {
                 // the RS256 key a realm JWKS may carry signs ID tokens only, and an ID
                 // token must never pass as an access token (task 26.55).
                 algorithms: ["EdDSA"],
+                // Hearth always sets `exp`; a token without one would never expire.
+                requiredClaims: ["exp"],
                 clockTolerance,
             });
             return new Claims(payload);
@@ -92,29 +96,35 @@ export class JwksClient {
                     return await doVerify(keySet);
                 }
                 catch (retryErr) {
-                    return this.mapJoseError(retryErr, options);
+                    return this.mapJoseError(retryErr, issuer, audience);
                 }
             }
-            return this.mapJoseError(firstErr, options);
+            return this.mapJoseError(firstErr, issuer, audience);
         }
     }
-    mapJoseError(err, options) {
+    /**
+     * Map a `jose` error onto the SDK error taxonomy (openspec/specs/sdk-support-contract/spec.md).
+     * `issuer` and `audience` are the values the check actually used.
+     */
+    mapJoseError(err, issuer, audience) {
         if (err instanceof joseErrors.JWTExpired) {
             const exp = err.payload?.exp;
             throw new TokenExpiredError(exp ? new Date(exp * 1000) : new Date(0));
         }
         if (err instanceof joseErrors.JWTClaimValidationFailed) {
             const claim = err.claim;
+            if (claim === "nbf" && err.reason === "check_failed") {
+                const nbf = err.payload?.nbf;
+                throw new TokenNotYetValidError(new Date((nbf ?? 0) * 1000));
+            }
             if (claim === "iss") {
                 const actual = err.payload?.["iss"] ?? "";
-                throw new TokenIssuerError(options?.issuer ?? "", actual);
+                throw new TokenIssuerError(issuer, actual);
             }
             if (claim === "aud") {
                 const raw = err.payload?.["aud"];
                 const actual = Array.isArray(raw) ? raw : [String(raw ?? "")];
-                const expected = Array.isArray(options?.audience)
-                    ? options.audience[0]
-                    : (options?.audience ?? "");
+                const expected = Array.isArray(audience) ? (audience[0] ?? "") : (audience ?? "");
                 throw new TokenAudienceError(expected, actual);
             }
             throw new TokenInvalidError(`JWT claim validation failed (${claim}): ${err.message}`);

package/dist/jwks-client.js.map

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

package/dist/middleware.d.ts

@@ -1,3 +1,4 @@
+import type { Claims } from "./claims.js";
 import type { HearthClient } from "./hearth-client.js";
 import type { AccessTokenAuthorizationMode, AuthorizePermissionOptions } from "./types.js";
 /** Options for {@link requirePermission}. */
@@ -39,3 +40,119 @@ export type PermissionChecker = (token: string) => Promise<boolean>;
  * @param opts - Mode, client reference, and optional scoping parameters.
  */
 export declare function requirePermission(permission: string, opts: RequirePermissionOptions): PermissionChecker;
+/** Options for {@link hearthMiddleware}, {@link hearthFastifyHook} and the Next.js helpers. */
+export interface HearthMiddlewareOptions extends AuthorizePermissionOptions {
+    /** Client used to verify tokens and, in non-embedded modes, to call the server. */
+    client: HearthClient;
+    /**
+     * How the permission check is made. Defaults to the client's `expectedMode`,
+     * then to `"embedded"`.
+     *
+     * - `"embedded"` — read `permissions` from the verified JWT. No network call.
+     * - `"introspection"` — introspect the token on every request. An inactive
+     *   token answers 401; a missing live permission, a different echoed mode or
+     *   a failed introspection call answers 403.
+     * - `"decision"` — ask `POST /oauth/authorize` for `requiredPermission` on
+     *   every request. Any failure counts as a denial (403).
+     *
+     * A token without a `permissions` claim never changes the mode (HEA-923).
+     */
+    mode?: AccessTokenAuthorizationMode;
+    /** When `true` (default), a request without a usable bearer token answers 401. */
+    required?: boolean;
+    /** Answer 403 unless the token's `scope` contains this value. */
+    requiredScope?: string;
+    /** Answer 403 unless the token's `roles` claim contains this value. */
+    requiredRole?: string;
+    /** Answer 403 unless the token holder has this permission (checked per `mode`). */
+    requiredPermission?: string;
+}
+/** JSON error body sent with a 401 or 403. */
+export interface HearthAuthErrorBody {
+    error: "unauthorized" | "forbidden";
+    error_description: string;
+}
+/**
+ * Outcome of {@link authenticateRequest}.
+ *
+ * `ok: true` means the request may proceed; `claims` is `null` when no token
+ * was sent and `required` is `false`. `ok: false` carries the response to send.
+ */
+export type HearthAuthResult = {
+    ok: true;
+    claims: Claims | null;
+} | {
+    ok: false;
+    status: 401 | 403;
+    body: HearthAuthErrorBody;
+    headers: Record<string, string>;
+};
+/**
+ * Check at setup time that the client can serve the configured mode, so a
+ * misconfiguration fails at startup rather than on the first request. The
+ * middleware factories call it; call it yourself when building on
+ * {@link authenticateRequest}.
+ *
+ * @throws {@link ConfigurationError}
+ */
+export declare function assertMiddlewareOptions(opts: HearthMiddlewareOptions): void;
+/**
+ * Authenticate and authorize one request from its `Authorization` header.
+ *
+ * Framework-neutral core of {@link hearthMiddleware}, {@link hearthFastifyHook}
+ * and the Next.js helpers; use it to adapt Hearth to another framework.
+ *
+ * Steps: extract the bearer token, verify it (EdDSA signature, `exp`, `nbf`,
+ * `iss`, `aud`), refuse `required_action` tokens, check `requiredScope` and
+ * `requiredRole` against the JWT, then check `requiredPermission` per `mode`.
+ */
+export declare function authenticateRequest(authorization: string | null | undefined, opts: HearthMiddlewareOptions): Promise<HearthAuthResult>;
+declare global {
+    namespace Express {
+        interface Request {
+            /** Verified claims, set by `hearthMiddleware()`. */
+            hearthClaims?: Claims;
+        }
+    }
+}
+/** The request fields {@link hearthMiddleware} reads and writes (Express-compatible). */
+export interface MiddlewareRequest {
+    headers: Record<string, string | string[] | undefined>;
+    hearthClaims?: Claims;
+}
+/** The response methods {@link hearthMiddleware} calls (Express-compatible). */
+export interface MiddlewareResponse {
+    status(code: number): unknown;
+    setHeader(name: string, value: string): unknown;
+    json(body: unknown): unknown;
+}
+/**
+ * Express (or Connect-style) middleware.
+ *
+ * On success it sets `req.hearthClaims` and calls `next()`. Otherwise it
+ * answers 401 (with `WWW-Authenticate: Bearer realm="hearth"`) or 403 with a
+ * JSON body and does not call `next`. An unexpected error goes to `next(err)`.
+ *
+ * @throws {@link ConfigurationError} when the client cannot serve the mode.
+ */
+export declare function hearthMiddleware(opts: HearthMiddlewareOptions): (req: MiddlewareRequest, res: MiddlewareResponse, next: (err?: unknown) => void) => Promise<void>;
+/** The request fields {@link hearthFastifyHook} reads and writes. */
+export interface FastifyRequestLike {
+    headers: Record<string, string | string[] | undefined>;
+    hearthClaims?: Claims;
+}
+/** The reply methods {@link hearthFastifyHook} calls. */
+export interface FastifyReplyLike {
+    code(statusCode: number): FastifyReplyLike;
+    header(name: string, value: string): FastifyReplyLike;
+    send(body: unknown): unknown;
+}
+/**
+ * Fastify `onRequest` / `preHandler` hook.
+ *
+ * On success it sets `request.hearthClaims`. Otherwise it sends 401 or 403
+ * with a JSON body, which ends the request.
+ *
+ * @throws {@link ConfigurationError} when the client cannot serve the mode.
+ */
+export declare function hearthFastifyHook(opts: HearthMiddlewareOptions): (request: FastifyRequestLike, reply: FastifyReplyLike) => Promise<void>;

package/dist/middleware.js

@@ -1,4 +1,4 @@
-import { AuthorizationModeMismatchError } from "./errors.js";
+import { AuthorizationModeMismatchError, ConfigurationError, TokenVerificationError, } from "./errors.js";
 /**
  * Returns a mode-aware permission checker for the given `permission`.
  *
@@ -49,4 +49,174 @@ export function requirePermission(permission, opts) {
             };
     }
 }
+const WWW_AUTHENTICATE = 'Bearer realm="hearth"';
+function unauthorized(description) {
+    return {
+        ok: false,
+        status: 401,
+        body: { error: "unauthorized", error_description: description },
+        headers: { "WWW-Authenticate": WWW_AUTHENTICATE },
+    };
+}
+const FORBIDDEN = {
+    ok: false,
+    status: 403,
+    body: { error: "forbidden", error_description: "Insufficient scope, role, or permission" },
+    headers: {},
+};
+/** The token from an `Authorization: Bearer <token>` header, or `null`. */
+function bearerToken(header) {
+    const match = /^Bearer[ ]+(\S+)\s*$/i.exec(header ?? "");
+    return match ? match[1] : null;
+}
+/** The mode in force for `opts`, after defaults. */
+function resolveMode(opts) {
+    return opts.mode ?? opts.client.expectedMode ?? "embedded";
+}
+/**
+ * Check at setup time that the client can serve the configured mode, so a
+ * misconfiguration fails at startup rather than on the first request. The
+ * middleware factories call it; call it yourself when building on
+ * {@link authenticateRequest}.
+ *
+ * @throws {@link ConfigurationError}
+ */
+export function assertMiddlewareOptions(opts) {
+    const mode = resolveMode(opts);
+    const { client } = opts;
+    if (mode === "introspection" && (!client.clientId || !client.clientSecret)) {
+        throw new ConfigurationError("introspection mode needs a client with clientId and clientSecret");
+    }
+    if (mode === "decision" && opts.requiredPermission && !client.realmId) {
+        throw new ConfigurationError("decision mode needs a client with realmId");
+    }
+}
+/**
+ * Authenticate and authorize one request from its `Authorization` header.
+ *
+ * Framework-neutral core of {@link hearthMiddleware}, {@link hearthFastifyHook}
+ * and the Next.js helpers; use it to adapt Hearth to another framework.
+ *
+ * Steps: extract the bearer token, verify it (EdDSA signature, `exp`, `nbf`,
+ * `iss`, `aud`), refuse `required_action` tokens, check `requiredScope` and
+ * `requiredRole` against the JWT, then check `requiredPermission` per `mode`.
+ */
+export async function authenticateRequest(authorization, opts) {
+    const required = opts.required !== false;
+    const token = bearerToken(authorization);
+    if (!token) {
+        return required ? unauthorized("Bearer token required") : { ok: true, claims: null };
+    }
+    let claims;
+    try {
+        claims = await opts.client.verifyToken(token);
+    }
+    catch (err) {
+        if (!required)
+            return { ok: true, claims: null };
+        return unauthorized(err instanceof TokenVerificationError ? err.message : "Token verification failed");
+    }
+    // A required_action token is only good for completing the pending actions,
+    // never for general API access (spec §6 rule 6) — even on optional routes.
+    if (claims.tokenType() === "required_action") {
+        return unauthorized("Token requires completion of required actions");
+    }
+    if (opts.requiredScope && !claims.hasScope(opts.requiredScope))
+        return FORBIDDEN;
+    if (opts.requiredRole && !claims.hasRole(opts.requiredRole))
+        return FORBIDDEN;
+    switch (resolveMode(opts)) {
+        case "embedded":
+            if (opts.requiredPermission && !claims.hasPermission(opts.requiredPermission)) {
+                return FORBIDDEN;
+            }
+            return { ok: true, claims };
+        case "decision":
+            if (opts.requiredPermission) {
+                const allowed = await opts.client.authorize(token, opts.requiredPermission, {
+                    organizationId: opts.organizationId,
+                    resource: opts.resource,
+                });
+                if (!allowed)
+                    return FORBIDDEN;
+            }
+            return { ok: true, claims };
+        case "introspection": {
+            let result;
+            try {
+                const ic = await opts.client.introspectionClient();
+                result = await ic.introspect(token, "access_token");
+            }
+            catch {
+                return FORBIDDEN; // fail closed
+            }
+            if (!result.active)
+                return unauthorized("Token is no longer active");
+            if (result.mode !== undefined && result.mode !== "introspection")
+                return FORBIDDEN;
+            if (opts.requiredPermission &&
+                !(Array.isArray(result.permissions) && result.permissions.includes(opts.requiredPermission))) {
+                return FORBIDDEN;
+            }
+            return { ok: true, claims };
+        }
+    }
+}
+function headerValue(value) {
+    return Array.isArray(value) ? value[0] : value;
+}
+/**
+ * Express (or Connect-style) middleware.
+ *
+ * On success it sets `req.hearthClaims` and calls `next()`. Otherwise it
+ * answers 401 (with `WWW-Authenticate: Bearer realm="hearth"`) or 403 with a
+ * JSON body and does not call `next`. An unexpected error goes to `next(err)`.
+ *
+ * @throws {@link ConfigurationError} when the client cannot serve the mode.
+ */
+export function hearthMiddleware(opts) {
+    assertMiddlewareOptions(opts);
+    return async (req, res, next) => {
+        let result;
+        try {
+            result = await authenticateRequest(headerValue(req.headers["authorization"]), opts);
+        }
+        catch (err) {
+            next(err);
+            return;
+        }
+        if (!result.ok) {
+            for (const [name, value] of Object.entries(result.headers))
+                res.setHeader(name, value);
+            res.status(result.status);
+            res.json(result.body);
+            return;
+        }
+        if (result.claims)
+            req.hearthClaims = result.claims;
+        next();
+    };
+}
+/**
+ * Fastify `onRequest` / `preHandler` hook.
+ *
+ * On success it sets `request.hearthClaims`. Otherwise it sends 401 or 403
+ * with a JSON body, which ends the request.
+ *
+ * @throws {@link ConfigurationError} when the client cannot serve the mode.
+ */
+export function hearthFastifyHook(opts) {
+    assertMiddlewareOptions(opts);
+    return async (request, reply) => {
+        const result = await authenticateRequest(headerValue(request.headers["authorization"]), opts);
+        if (!result.ok) {
+            for (const [name, value] of Object.entries(result.headers))
+                reply.header(name, value);
+            reply.code(result.status).send(result.body);
+            return;
+        }
+        if (result.claims)
+            request.hearthClaims = result.claims;
+    };
+}
 //# sourceMappingURL=middleware.js.map

package/dist/middleware.js.map

@@ -1 +1 @@
-{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,8BAA8B,EAAE,MAAM,aAAa,CAAC;AAwB7D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,UAAkB,EAClB,IAA8B;IAE9B,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC;IAExD,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,UAAU;YACb,OAAO,KAAK,EAAE,KAAa,EAAoB,EAAE;gBAC/C,sEAAsE;gBACtE,+DAA+D;gBAC/D,IAAI,CAAC;oBACH,OAAO,CAAC,MAAM,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;gBACrE,CAAC;gBAAC,MAAM,CAAC;oBACP,OAAO,KAAK,CAAC;gBACf,CAAC;YACH,CAAC,CAAC;QAEJ,KAAK,UAAU;YACb,OAAO,KAAK,EAAE,KAAa,EAAoB,EAAE,CAC/C,MAAM,CAAC,SAAS,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,cAAc,EAAE,QAAQ,EAAE,CAAC,CAAC;QAEtE,KAAK,eAAe;YAClB,OAAO,KAAK,EAAE,KAAa,EAAoB,EAAE;gBAC/C,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,mBAAmB,EAAE,CAAC;gBAC9C,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;gBAE1C,uEAAuE;gBACvE,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,KAAK,eAAe,EAAE,CAAC;oBACjE,MAAM,IAAI,8BAA8B,CAAC,eAAe,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;gBACjF,CAAC;gBAED,IAAI,CAAC,MAAM,CAAC,MAAM;oBAAE,OAAO,KAAK,CAAC;gBACjC,OAAO,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;YACtF,CAAC,CAAC;IACN,CAAC;AACH,CAAC"}
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../src/middleware.ts"],"names":[],"mappings":"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"}

package/dist/nextjs/edge.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `@hearth-auth/sdk/nextjs/edge` — Next.js `middleware.ts` guard for the Edge
+ * Runtime.
+ *
+ * Uses only `fetch` and Web Crypto (through `jose`); it imports no `node:`
+ * module, so it runs in a V8 isolate.
+ */
+import type { HearthMiddlewareOptions } from "../middleware.js";
+/** A request whose headers have a `get()` accessor (`NextRequest`, `Request`). */
+export interface EdgeRequestLike {
+    headers: {
+        get(name: string): string | null;
+    };
+}
+/**
+ * Build a guard for Next.js `middleware.ts`.
+ *
+ * The guard resolves to `undefined` when the request may proceed (return
+ * `NextResponse.next()`), or to a 401/403 JSON `Response` to return as is.
+ * Create it once at module scope so the client's discovery and JWKS caches
+ * live as long as the isolate.
+ *
+ * @throws {@link ConfigurationError} when the client cannot serve the mode.
+ */
+export declare function hearthEdgeMiddleware(options: HearthMiddlewareOptions): (req: EdgeRequestLike) => Promise<Response | undefined>;
+export type { HearthMiddlewareOptions } from "../middleware.js";

package/dist/nextjs/edge.js

@@ -0,0 +1,31 @@
+/**
+ * `@hearth-auth/sdk/nextjs/edge` — Next.js `middleware.ts` guard for the Edge
+ * Runtime.
+ *
+ * Uses only `fetch` and Web Crypto (through `jose`); it imports no `node:`
+ * module, so it runs in a V8 isolate.
+ */
+import { assertMiddlewareOptions, authenticateRequest } from "../middleware.js";
+/**
+ * Build a guard for Next.js `middleware.ts`.
+ *
+ * The guard resolves to `undefined` when the request may proceed (return
+ * `NextResponse.next()`), or to a 401/403 JSON `Response` to return as is.
+ * Create it once at module scope so the client's discovery and JWKS caches
+ * live as long as the isolate.
+ *
+ * @throws {@link ConfigurationError} when the client cannot serve the mode.
+ */
+export function hearthEdgeMiddleware(options) {
+    assertMiddlewareOptions(options);
+    return async (req) => {
+        const result = await authenticateRequest(req.headers.get("authorization"), options);
+        if (result.ok)
+            return undefined;
+        return new Response(JSON.stringify(result.body), {
+            status: result.status,
+            headers: { ...result.headers, "Content-Type": "application/json" },
+        });
+    };
+}
+//# sourceMappingURL=edge.js.map

package/dist/nextjs/edge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge.js","sourceRoot":"","sources":["../../src/nextjs/edge.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAQhF;;;;;;;;;GASG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAgC;IAEhC,uBAAuB,CAAC,OAAO,CAAC,CAAC;IACjC,OAAO,KAAK,EAAE,GAAoB,EAAiC,EAAE;QACnE,MAAM,MAAM,GAAG,MAAM,mBAAmB,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC,CAAC;QACpF,IAAI,MAAM,CAAC,EAAE;YAAE,OAAO,SAAS,CAAC;QAChC,OAAO,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE;YAC/C,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,OAAO,EAAE,EAAE,GAAG,MAAM,CAAC,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE;SACnE,CAAC,CAAC;IACL,CAAC,CAAC;AACJ,CAAC"}

package/dist/nextjs/index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * `@hearth-auth/sdk/nextjs` — Next.js helpers for the Node.js runtime
+ * (Pages Router API routes and App Router Route Handlers).
+ *
+ * For `middleware.ts`, which runs on the Edge Runtime, import
+ * `hearthEdgeMiddleware` from `@hearth-auth/sdk/nextjs/edge`.
+ */
+import type { Claims } from "../claims.js";
+import type { HearthClient } from "../hearth-client.js";
+import type { HearthMiddlewareOptions } from "../middleware.js";
+/** A request whose headers have a `get()` accessor (`NextRequest`, `Request`). */
+export interface RequestLike {
+    headers: {
+        get(name: string): string | null;
+    };
+}
+/** The fields of `NextApiRequest` that {@link withHearthAuth} uses. */
+export interface ApiRequest {
+    headers: Record<string, string | string[] | undefined>;
+    /** Verified claims, set by {@link withHearthAuth} before the handler runs. */
+    hearthClaims?: Claims;
+}
+/** The methods of `NextApiResponse` that {@link withHearthAuth} uses. */
+export interface ApiResponse {
+    status(code: number): unknown;
+    setHeader(name: string, value: string): unknown;
+    json(body: unknown): unknown;
+}
+/** A Pages Router API route handler. */
+export type ApiHandler<Req extends ApiRequest = ApiRequest, Res extends ApiResponse = ApiResponse> = (req: Req, res: Res) => unknown | Promise<unknown>;
+/**
+ * Wrap a Pages Router API route with Hearth authentication.
+ *
+ * Verifies the `Authorization: Bearer` token, applies the guards in `options`,
+ * sets `req.hearthClaims` and calls `handler`. When the request fails it
+ * answers 401 or 403 and `handler` is not called.
+ *
+ * @throws {@link ConfigurationError} when the client cannot serve the mode.
+ */
+export declare function withHearthAuth<Req extends ApiRequest, Res extends ApiResponse>(handler: ApiHandler<Req, Res>, options: HearthMiddlewareOptions): (req: Req, res: Res) => Promise<void>;
+/**
+ * Verify the bearer token on an App Router Route Handler request.
+ *
+ * Returns the verified {@link Claims}, or `null` when the `Authorization`
+ * header is missing or not a bearer token, the token does not verify, or the
+ * token is a `required_action` token. Create the {@link HearthClient} once at
+ * module scope so its JWKS cache is shared across requests.
+ */
+export declare function getHearthClaims(req: RequestLike, client: HearthClient): Promise<Claims | null>;
+export type { HearthMiddlewareOptions } from "../middleware.js";