@hearth-auth/node 0.0.1

package/dist/errors.d.ts

@@ -0,0 +1,120 @@
+/** §5 — Hearth Node SDK error taxonomy. */
+/** Base class for all @hearth-auth/node errors. Messages are sanitized to remove tokens/secrets. */
+export declare class HearthError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Thrown when the HearthClient is misconfigured (missing required fields, invalid URLs). */
+export declare class ConfigurationError extends HearthError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Thrown when OIDC discovery (/.well-known/openid-configuration) fails. */
+export declare class DiscoveryError extends HearthError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Thrown when fetching or parsing the JWKS document fails. */
+export declare class JWKSFetchError extends HearthError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Thrown when token signature verification fails or the token is structurally invalid. */
+export declare class TokenVerificationError extends HearthError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Thrown when token `exp` claim is in the past (beyond clock skew tolerance). */
+export declare class TokenExpiredError extends TokenVerificationError {
+    constructor(expiredAt: Date, options?: {
+        cause?: unknown;
+    });
+}
+/** Thrown when token `nbf` claim is in the future (beyond clock skew tolerance). */
+export declare class TokenNotYetValidError extends TokenVerificationError {
+    constructor(notBefore: Date, options?: {
+        cause?: unknown;
+    });
+}
+/** Thrown when token signature is invalid, the JWT is malformed, or the algorithm does not match. */
+export declare class TokenInvalidError extends TokenVerificationError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Thrown when the `iss` claim does not match the configured issuer URL. */
+export declare class TokenIssuerError extends TokenVerificationError {
+    constructor(actualIssuer: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Thrown when the `aud` claim does not contain the expected audience. */
+export declare class TokenAudienceError extends TokenVerificationError {
+    constructor(expectedAudience: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Thrown when a required claim is missing, wrong type, or fails validation (iss, aud, iat). */
+export declare class TokenClaimsError extends TokenVerificationError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Thrown when the introspection request fails or returns an unexpected response. */
+export declare class IntrospectionError extends HearthError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Thrown by Express/Fastify middleware when configuration is invalid or setup fails. */
+export declare class MiddlewareError extends HearthError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when the introspection response echoes an `access_token_authorization` mode
+ * that does not match the SDK's configured `expectedMode`.
+ */
+export declare class AuthorizationModeError extends HearthError {
+    readonly expected: string;
+    readonly actual: string;
+    constructor(expected: string, actual: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Thrown when the `POST /oauth/authorize` request cannot be made (misconfiguration). */
+export declare class AuthorizeError extends HearthError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Thrown when a token with `token_type === "required_action"` is presented as a regular access
+ * token, or when the server returns `error_code: "HEARTH_REQUIRED_ACTIONS_PENDING"`.
+ */
+export declare class RequiredActionError extends HearthError {
+    /** Pending action names from the token's `required_actions` claim. */
+    readonly requiredActions: string[];
+    /** Optional URL to the Hearth interstitial page for completing required actions. */
+    readonly redirectUri: string | undefined;
+    constructor(requiredActions: string[], redirectUri?: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Typed HTTP error for AdminClient operations that return 4xx/5xx responses
+ * not covered by the standard error taxonomy.
+ */
+export declare class AdminHttpError extends HearthError {
+    readonly status: number;
+    constructor(status: number, message: string, options?: {
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

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

package/dist/errors.js

@@ -0,0 +1,172 @@
+/** §5 — Hearth Node SDK error taxonomy. */
+const REDACTED = "[redacted]";
+// Charcode ranges for base64url alphabet — used by sanitize() to avoid a backtracking regex.
+function isB64UrlCode(code) {
+    return (code >= 65 && code <= 90) // A-Z
+        || (code >= 97 && code <= 122) // a-z
+        || (code >= 48 && code <= 57) // 0-9
+        || code === 95 // _
+        || code === 45; // -
+}
+function sanitize(value) {
+    // Linear O(n) scan — redacts JWT-shaped tokens (eyJ<seg>.<seg>.<seg>) without a
+    // backtracking regex (which is ReDoS-vulnerable on crafted inputs like "eyJeyJeyJ…").
+    let out = "";
+    let i = 0;
+    while (i < value.length) {
+        if (value[i] === "e" && value[i + 1] === "y" && value[i + 2] === "J") {
+            const start = i;
+            i += 3;
+            while (i < value.length && isB64UrlCode(value.charCodeAt(i)))
+                i++;
+            if (i < value.length && value[i] === ".") {
+                const dot1 = i++;
+                const seg2Start = i;
+                while (i < value.length && isB64UrlCode(value.charCodeAt(i)))
+                    i++;
+                if (i > seg2Start && i < value.length && value[i] === ".") {
+                    i++;
+                    while (i < value.length && isB64UrlCode(value.charCodeAt(i)))
+                        i++;
+                    out += REDACTED;
+                    continue;
+                }
+                // Two-segment prefix — not a JWT; emit up to and including the dot, re-scan remainder.
+                out += value.slice(start, dot1 + 1);
+                i = dot1 + 1;
+                continue;
+            }
+            out += value.slice(start, i);
+            continue;
+        }
+        out += value[i++];
+    }
+    return out;
+}
+/** Base class for all @hearth-auth/node errors. Messages are sanitized to remove tokens/secrets. */
+export class HearthError extends Error {
+    constructor(message, options) {
+        super(sanitize(message), options);
+        this.name = this.constructor.name;
+        if (Error.captureStackTrace)
+            Error.captureStackTrace(this, this.constructor);
+    }
+}
+/** Thrown when the HearthClient is misconfigured (missing required fields, invalid URLs). */
+export class ConfigurationError extends HearthError {
+    constructor(message, options) {
+        super(message, options);
+    }
+}
+/** Thrown when OIDC discovery (/.well-known/openid-configuration) fails. */
+export class DiscoveryError extends HearthError {
+    constructor(message, options) {
+        super(message, options);
+    }
+}
+/** Thrown when fetching or parsing the JWKS document fails. */
+export class JWKSFetchError extends HearthError {
+    constructor(message, options) {
+        super(message, options);
+    }
+}
+/** Thrown when token signature verification fails or the token is structurally invalid. */
+export class TokenVerificationError extends HearthError {
+    constructor(message, options) {
+        super(message, options);
+    }
+}
+/** Thrown when token `exp` claim is in the past (beyond clock skew tolerance). */
+export class TokenExpiredError extends TokenVerificationError {
+    constructor(expiredAt, options) {
+        super(`Token expired at ${expiredAt.toISOString()}`, options);
+    }
+}
+/** Thrown when token `nbf` claim is in the future (beyond clock skew tolerance). */
+export class TokenNotYetValidError extends TokenVerificationError {
+    constructor(notBefore, options) {
+        super(`Token not valid until ${notBefore.toISOString()}`, options);
+    }
+}
+/** Thrown when token signature is invalid, the JWT is malformed, or the algorithm does not match. */
+export class TokenInvalidError extends TokenVerificationError {
+    constructor(message, options) {
+        super(message, options);
+    }
+}
+/** Thrown when the `iss` claim does not match the configured issuer URL. */
+export class TokenIssuerError extends TokenVerificationError {
+    constructor(actualIssuer, options) {
+        super(`Token issuer "${actualIssuer}" does not match configured issuer`, options);
+    }
+}
+/** Thrown when the `aud` claim does not contain the expected audience. */
+export class TokenAudienceError extends TokenVerificationError {
+    constructor(expectedAudience, options) {
+        super(`Token audience does not contain expected value "${expectedAudience}"`, options);
+    }
+}
+/** Thrown when a required claim is missing, wrong type, or fails validation (iss, aud, iat). */
+export class TokenClaimsError extends TokenVerificationError {
+    constructor(message, options) {
+        super(message, options);
+    }
+}
+/** Thrown when the introspection request fails or returns an unexpected response. */
+export class IntrospectionError extends HearthError {
+    constructor(message, options) {
+        super(message, options);
+    }
+}
+/** Thrown by Express/Fastify middleware when configuration is invalid or setup fails. */
+export class MiddlewareError extends HearthError {
+    constructor(message, options) {
+        super(message, options);
+    }
+}
+/**
+ * Thrown when the introspection response echoes an `access_token_authorization` mode
+ * that does not match the SDK's configured `expectedMode`.
+ */
+export class AuthorizationModeError extends HearthError {
+    expected;
+    actual;
+    constructor(expected, actual, options) {
+        super(`Expected authorization mode "${expected}" but server echoed "${actual}"`, options);
+        this.expected = expected;
+        this.actual = actual;
+    }
+}
+/** Thrown when the `POST /oauth/authorize` request cannot be made (misconfiguration). */
+export class AuthorizeError extends HearthError {
+    constructor(message, options) {
+        super(message, options);
+    }
+}
+/**
+ * Thrown when a token with `token_type === "required_action"` is presented as a regular access
+ * token, or when the server returns `error_code: "HEARTH_REQUIRED_ACTIONS_PENDING"`.
+ */
+export class RequiredActionError extends HearthError {
+    /** Pending action names from the token's `required_actions` claim. */
+    requiredActions;
+    /** Optional URL to the Hearth interstitial page for completing required actions. */
+    redirectUri;
+    constructor(requiredActions, redirectUri, options) {
+        super(`Token requires completion of required actions: ${requiredActions.join(", ") || "(none)"}`, options);
+        this.requiredActions = requiredActions;
+        this.redirectUri = redirectUri;
+    }
+}
+/**
+ * Typed HTTP error for AdminClient operations that return 4xx/5xx responses
+ * not covered by the standard error taxonomy.
+ */
+export class AdminHttpError extends HearthError {
+    status;
+    constructor(status, message, options) {
+        super(message, options);
+        this.status = status;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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

package/dist/errors.test.d.ts

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

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

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

package/dist/errors.test.js

@@ -0,0 +1,89 @@
+import { describe, it, expect } from "vitest";
+import { HearthError, ConfigurationError, DiscoveryError, JWKSFetchError, TokenVerificationError, TokenExpiredError, TokenNotYetValidError, TokenInvalidError, TokenIssuerError, TokenAudienceError, TokenClaimsError, IntrospectionError, MiddlewareError, RequiredActionError, } from "./errors.js";
+describe("HearthError taxonomy", () => {
+    it("all error classes extend HearthError", () => {
+        const classes = [
+            ConfigurationError,
+            DiscoveryError,
+            JWKSFetchError,
+            TokenVerificationError,
+            TokenClaimsError,
+            IntrospectionError,
+            MiddlewareError,
+            TokenInvalidError,
+            TokenIssuerError,
+            TokenAudienceError,
+        ];
+        for (const Cls of classes) {
+            const err = new Cls("test");
+            expect(err).toBeInstanceOf(HearthError);
+            expect(err).toBeInstanceOf(Cls);
+            expect(err.name).toBe(Cls.name);
+        }
+    });
+    it("TokenExpiredError extends TokenVerificationError", () => {
+        const err = new TokenExpiredError(new Date());
+        expect(err).toBeInstanceOf(HearthError);
+        expect(err).toBeInstanceOf(TokenVerificationError);
+        expect(err).toBeInstanceOf(TokenExpiredError);
+    });
+    it("TokenNotYetValidError extends TokenVerificationError", () => {
+        const d = new Date("2099-01-01T00:00:00Z");
+        const err = new TokenNotYetValidError(d);
+        expect(err).toBeInstanceOf(HearthError);
+        expect(err).toBeInstanceOf(TokenVerificationError);
+        expect(err).toBeInstanceOf(TokenNotYetValidError);
+        expect(err.message).toContain("2099-01-01T00:00:00.000Z");
+        expect(err.name).toBe("TokenNotYetValidError");
+    });
+    it("TokenInvalidError extends TokenVerificationError", () => {
+        const err = new TokenInvalidError("bad signature");
+        expect(err).toBeInstanceOf(TokenVerificationError);
+        expect(err.name).toBe("TokenInvalidError");
+    });
+    it("TokenIssuerError extends TokenVerificationError", () => {
+        const err = new TokenIssuerError("https://wrong.example.com");
+        expect(err).toBeInstanceOf(TokenVerificationError);
+        expect(err.name).toBe("TokenIssuerError");
+        expect(err.message).toContain("https://wrong.example.com");
+    });
+    it("TokenAudienceError extends TokenVerificationError", () => {
+        const err = new TokenAudienceError("my-client");
+        expect(err).toBeInstanceOf(TokenVerificationError);
+        expect(err.name).toBe("TokenAudienceError");
+        expect(err.message).toContain("my-client");
+    });
+    it("RequiredActionError exposes requiredActions and optional redirectUri", () => {
+        const err = new RequiredActionError(["VERIFY_EMAIL", "UPDATE_PASSWORD"]);
+        expect(err).toBeInstanceOf(HearthError);
+        expect(err.name).toBe("RequiredActionError");
+        expect(err.requiredActions).toEqual(["VERIFY_EMAIL", "UPDATE_PASSWORD"]);
+        expect(err.redirectUri).toBeUndefined();
+    });
+    it("RequiredActionError accepts optional redirectUri", () => {
+        const err = new RequiredActionError(["VERIFY_EMAIL"], "https://auth.example.com/ui/required-actions");
+        expect(err.requiredActions).toEqual(["VERIFY_EMAIL"]);
+        expect(err.redirectUri).toBe("https://auth.example.com/ui/required-actions");
+    });
+    it("supports cause chaining", () => {
+        const cause = new Error("original");
+        const err = new DiscoveryError("wrapped", { cause });
+        expect(err.cause).toBe(cause);
+    });
+    it("sanitizes JWT-like strings from messages", () => {
+        const fakeJwt = "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ1c2VyMSJ9.abc123";
+        const err = new HearthError(`Token was: ${fakeJwt}`);
+        expect(err.message).not.toContain(fakeJwt);
+        expect(err.message).toContain("[redacted]");
+    });
+    it("TokenExpiredError formats expiry date in message", () => {
+        const date = new Date("2024-01-01T00:00:00Z");
+        const err = new TokenExpiredError(date);
+        expect(err.message).toContain("2024-01-01T00:00:00.000Z");
+    });
+    it("TokenVerificationError is instance of TokenVerificationError via TokenExpiredError", () => {
+        const err = new TokenExpiredError(new Date());
+        expect(err).toBeInstanceOf(TokenVerificationError);
+    });
+});
+//# sourceMappingURL=errors.test.js.map

package/dist/errors.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.test.js","sourceRoot":"","sources":["../src/errors.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,sBAAsB,EACtB,iBAAiB,EACjB,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAErB,QAAQ,CAAC,sBAAsB,EAAE,GAAG,EAAE;IACpC,EAAE,CAAC,sCAAsC,EAAE,GAAG,EAAE;QAC9C,MAAM,OAAO,GAAG;YACd,kBAAkB;YAClB,cAAc;YACd,cAAc;YACd,sBAAsB;YACtB,gBAAgB;YAChB,kBAAkB;YAClB,eAAe;YACf,iBAAiB;YACjB,gBAAgB;YAChB,kBAAkB;SACnB,CAAC;QACF,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;YAC1B,MAAM,GAAG,GAAG,IAAK,GAAsC,CAAC,MAAM,CAAC,CAAC;YAChE,MAAM,CAAC,GAAG,CAAC,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC;YACxC,MAAM,CAAC,GAAG,CAAC,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;YAChC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClC,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kDAAkD,EAAE,GAAG,EAAE;QAC1D,MAAM,GAAG,GAAG,IAAI,iBAAiB,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;QAC9C,MAAM,CAAC,GAAG,CAAC,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC;QACxC,MAAM,CAAC,GAAG,CAAC,CAAC,cAAc,CAAC,sBAAsB,CAAC,CAAC;QACnD,MAAM,CAAC,GAAG,CAAC,CAAC,cAAc,CAAC,iBAAiB,CAAC,CAAC;IAChD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sDAAsD,EAAE,GAAG,EAAE;QAC9D,MAAM,CAAC,GAAG,IAAI,IAAI,CAAC,sBAAsB,CAAC,CAAC;QAC3C,MAAM,GAAG,GAAG,IAAI,qBAAqB,CAAC,CAAC,CAAC,CAAC;QACzC,MAAM,CAAC,GAAG,CAAC,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC;QACxC,MAAM,CAAC,GAAG,CAAC,CAAC,cAAc,CAAC,sBAAsB,CAAC,CAAC;QACnD,MAAM,CAAC,GAAG,CAAC,CAAC,cAAc,CAAC,qBAAqB,CAAC,CAAC;QAClD,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,0BAA0B,CAAC,CAAC;QAC1D,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,uBAAuB,CAAC,CAAC;IACjD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kDAAkD,EAAE,GAAG,EAAE;QAC1D,MAAM,GAAG,GAAG,IAAI,iBAAiB,CAAC,eAAe,CAAC,CAAC;QACnD,MAAM,CAAC,GAAG,CAAC,CAAC,cAAc,CAAC,sBAAsB,CAAC,CAAC;QACnD,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iDAAiD,EAAE,GAAG,EAAE;QACzD,MAAM,GAAG,GAAG,IAAI,gBAAgB,CAAC,2BAA2B,CAAC,CAAC;QAC9D,MAAM,CAAC,GAAG,CAAC,CAAC,cAAc,CAAC,sBAAsB,CAAC,CAAC;QACnD,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;QAC1C,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,2BAA2B,CAAC,CAAC;IAC7D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,mDAAmD,EAAE,GAAG,EAAE;QAC3D,MAAM,GAAG,GAAG,IAAI,kBAAkB,CAAC,WAAW,CAAC,CAAC;QAChD,MAAM,CAAC,GAAG,CAAC,CAAC,cAAc,CAAC,sBAAsB,CAAC,CAAC;QACnD,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;QAC5C,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;IAC7C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sEAAsE,EAAE,GAAG,EAAE;QAC9E,MAAM,GAAG,GAAG,IAAI,mBAAmB,CAAC,CAAC,cAAc,EAAE,iBAAiB,CAAC,CAAC,CAAC;QACzE,MAAM,CAAC,GAAG,CAAC,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC;QACxC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;QAC7C,MAAM,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,OAAO,CAAC,CAAC,cAAc,EAAE,iBAAiB,CAAC,CAAC,CAAC;QACzE,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,aAAa,EAAE,CAAC;IAC1C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kDAAkD,EAAE,GAAG,EAAE;QAC1D,MAAM,GAAG,GAAG,IAAI,mBAAmB,CAAC,CAAC,cAAc,CAAC,EAAE,8CAA8C,CAAC,CAAC;QACtG,MAAM,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,OAAO,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC;QACtD,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,8CAA8C,CAAC,CAAC;IAC/E,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yBAAyB,EAAE,GAAG,EAAE;QACjC,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,UAAU,CAAC,CAAC;QACpC,MAAM,GAAG,GAAG,IAAI,cAAc,CAAC,SAAS,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;QACrD,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0CAA0C,EAAE,GAAG,EAAE;QAClD,MAAM,OAAO,GAAG,kDAAkD,CAAC;QACnE,MAAM,GAAG,GAAG,IAAI,WAAW,CAAC,cAAc,OAAO,EAAE,CAAC,CAAC;QACrD,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAC3C,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC;IAC9C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kDAAkD,EAAE,GAAG,EAAE;QAC1D,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,sBAAsB,CAAC,CAAC;QAC9C,MAAM,GAAG,GAAG,IAAI,iBAAiB,CAAC,IAAI,CAAC,CAAC;QACxC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,0BAA0B,CAAC,CAAC;IAC5D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,oFAAoF,EAAE,GAAG,EAAE;QAC5F,MAAM,GAAG,GAAG,IAAI,iBAAiB,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;QAC9C,MAAM,CAAC,GAAG,CAAC,CAAC,cAAc,CAAC,sBAAsB,CAAC,CAAC;IACrD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/** @hearth-auth/node — server-side Hearth SDK for Node.js. Public API surface. */
+export { HearthClient } from "./client.js";
+export type { HearthConfig } from "./config.js";
+export { JwksVerifier } from "./jwks.js";
+export { IntrospectionClient } from "./introspect.js";
+export type { IntrospectionResult } from "./introspect.js";
+export { VerifiedToken } from "./token.js";
+export type { AccessTokenAuthorizationMode } from "./token.js";
+export { HearthError, ConfigurationError, DiscoveryError, JWKSFetchError, TokenVerificationError, TokenExpiredError, TokenNotYetValidError, TokenInvalidError, TokenIssuerError, TokenAudienceError, TokenClaimsError, IntrospectionError, MiddlewareError, AuthorizationModeError, AuthorizeError, RequiredActionError, AdminHttpError, } from "./errors.js";
+export { hearthMiddleware, hearthFastifyHook } from "./middleware.js";
+export type { MiddlewareOptions } from "./middleware.js";
+export { AuthorizeClient } from "./authorize.js";
+export type { AuthorizeOptions, AuthorizeResult } from "./authorize.js";
+export { AdminClient } from "./admin.js";
+export type { AdminClientConfig, PageOptions, PageResponse } from "./admin.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAGlF,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGhD,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAGzC,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,YAAY,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAG3D,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,YAAY,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAC;AAG/D,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,sBAAsB,EACtB,iBAAiB,EACjB,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,sBAAsB,EACtB,cAAc,EACd,mBAAmB,EACnB,cAAc,GACf,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACtE,YAAY,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAGzD,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAGxE,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,18 @@
+/** @hearth-auth/node — server-side Hearth SDK for Node.js. Public API surface. */
+// §1 — Configuration & unified client
+export { HearthClient } from "./client.js";
+// §2 — Token verification
+export { JwksVerifier } from "./jwks.js";
+// §3 — Token introspection
+export { IntrospectionClient } from "./introspect.js";
+// §4 — Claims API
+export { VerifiedToken } from "./token.js";
+// §5 — Error taxonomy
+export { HearthError, ConfigurationError, DiscoveryError, JWKSFetchError, TokenVerificationError, TokenExpiredError, TokenNotYetValidError, TokenInvalidError, TokenIssuerError, TokenAudienceError, TokenClaimsError, IntrospectionError, MiddlewareError, AuthorizationModeError, AuthorizeError, RequiredActionError, AdminHttpError, } from "./errors.js";
+// §6 — Middleware
+export { hearthMiddleware, hearthFastifyHook } from "./middleware.js";
+// §7 — Decision client (POST /oauth/authorize)
+export { AuthorizeClient } from "./authorize.js";
+// §12 — Admin SDK
+export { AdminClient } from "./admin.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAElF,sCAAsC;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAG3C,0BAA0B;AAC1B,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAEzC,2BAA2B;AAC3B,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAGtD,kBAAkB;AAClB,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAG3C,sBAAsB;AACtB,OAAO,EACL,WAAW,EACX,kBAAkB,EAClB,cAAc,EACd,cAAc,EACd,sBAAsB,EACtB,iBAAiB,EACjB,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,sBAAsB,EACtB,cAAc,EACd,mBAAmB,EACnB,cAAc,GACf,MAAM,aAAa,CAAC;AAErB,kBAAkB;AAClB,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAGtE,+CAA+C;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAGjD,kBAAkB;AAClB,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}

package/dist/introspect.d.ts

@@ -0,0 +1,37 @@
+/** §3 — Token introspection per RFC 7662. */
+import type { ResolvedConfig } from "./config.js";
+import type { OidcDiscovery } from "./discovery.js";
+import type { AccessTokenAuthorizationMode } from "./token.js";
+/** RFC 7662 introspection response — required fields per spec §3. */
+export interface IntrospectionResult {
+    active: boolean;
+    sub?: string;
+    iss?: string;
+    aud?: string | string[];
+    exp?: number;
+    iat?: number;
+    scope?: string;
+    /**
+     * Access-token authorization mode echoed from the server (HEA-922).
+     * Present when the introspecting client has a non-Embedded mode configured.
+     */
+    mode?: AccessTokenAuthorizationMode;
+    /** Live permissions — populated for Introspection/Decision mode clients. */
+    permissions?: string[];
+    /** Live roles — populated for Introspection/Decision mode clients. */
+    roles?: string[];
+    /** Live group slugs — populated for Introspection/Decision mode clients. */
+    groups?: string[];
+    /** Catch-all for non-standard claims returned by the server. */
+    extra: Record<string, unknown>;
+}
+export declare class IntrospectionClient {
+    private readonly config;
+    private readonly getDiscovery;
+    private readonly credentials;
+    constructor(config: ResolvedConfig, getDiscovery: () => Promise<OidcDiscovery>);
+    private getIntrospectionEndpoint;
+    /** Introspect a token per RFC 7662. */
+    introspect(token: string, tokenTypeHint?: "access_token" | "refresh_token"): Promise<IntrospectionResult>;
+}
+//# sourceMappingURL=introspect.d.ts.map

package/dist/introspect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"introspect.d.ts","sourceRoot":"","sources":["../src/introspect.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAG7C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,YAAY,CAAC;AAE/D,qEAAqE;AACrE,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,IAAI,CAAC,EAAE,4BAA4B,CAAC;IACpC,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,sEAAsE;IACtE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,gEAAgE;IAChE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,qBAAa,mBAAmB;IAI5B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAJ/B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAGlB,MAAM,EAAE,cAAc,EACtB,YAAY,EAAE,MAAM,OAAO,CAAC,aAAa,CAAC;YAO/C,wBAAwB;IAWtC,uCAAuC;IACjC,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,cAAc,GAAG,eAAe,GAAG,OAAO,CAAC,mBAAmB,CAAC;CAmDhH"}

package/dist/introspect.js

@@ -0,0 +1,72 @@
+/** §3 — Token introspection per RFC 7662. */
+import { IntrospectionError } from "./errors.js";
+export class IntrospectionClient {
+    config;
+    getDiscovery;
+    credentials;
+    constructor(config, getDiscovery) {
+        this.config = config;
+        this.getDiscovery = getDiscovery;
+        this.credentials = Buffer.from(`${config.client_id}:${config.client_secret}`).toString("base64");
+    }
+    async getIntrospectionEndpoint() {
+        if (this.config.introspection_endpoint)
+            return this.config.introspection_endpoint;
+        const doc = await this.getDiscovery();
+        if (!doc.introspection_endpoint) {
+            throw new IntrospectionError("Introspection endpoint not found in OIDC discovery document and no override configured");
+        }
+        return doc.introspection_endpoint;
+    }
+    /** Introspect a token per RFC 7662. */
+    async introspect(token, tokenTypeHint) {
+        const endpoint = await this.getIntrospectionEndpoint();
+        const body = new URLSearchParams({ token });
+        if (tokenTypeHint)
+            body.set("token_type_hint", tokenTypeHint);
+        let res;
+        try {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), this.config.http_timeout);
+            res = await fetch(endpoint, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/x-www-form-urlencoded",
+                    Authorization: `Basic ${this.credentials}`,
+                },
+                body,
+                signal: controller.signal,
+            });
+            clearTimeout(timer);
+        }
+        catch (err) {
+            throw new IntrospectionError("Introspection request failed", { cause: err });
+        }
+        if (!res.ok) {
+            throw new IntrospectionError(`Introspection endpoint returned HTTP ${res.status}`);
+        }
+        let raw;
+        try {
+            raw = await res.json();
+        }
+        catch (err) {
+            throw new IntrospectionError("Introspection response is not valid JSON", { cause: err });
+        }
+        const { active, sub, iss, aud, exp, iat, scope, mode, permissions, roles, groups, ...rest } = raw;
+        return {
+            active: Boolean(active),
+            sub: typeof sub === "string" ? sub : undefined,
+            iss: typeof iss === "string" ? iss : undefined,
+            aud: typeof aud === "string" || Array.isArray(aud) ? aud : undefined,
+            exp: typeof exp === "number" ? exp : undefined,
+            iat: typeof iat === "number" ? iat : undefined,
+            scope: typeof scope === "string" ? scope : undefined,
+            mode: typeof mode === "string" ? mode : undefined,
+            permissions: Array.isArray(permissions) ? permissions.filter((p) => typeof p === "string") : undefined,
+            roles: Array.isArray(roles) ? roles.filter((r) => typeof r === "string") : undefined,
+            groups: Array.isArray(groups) ? groups.filter((g) => typeof g === "string") : undefined,
+            extra: rest,
+        };
+    }
+}
+//# sourceMappingURL=introspect.js.map

package/dist/introspect.js.map

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

package/dist/introspect.test.d.ts

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

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

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