@hearth-auth/node 0.0.1

package/dist/token.d.ts

@@ -0,0 +1,68 @@
+/** §4 — VerifiedToken: typed claims accessors and helpers. */
+/**
+ * Controls how authorization data is delivered to resource servers.
+ * Mirrors the server-side `AccessTokenAuthorization` enum (HEA-922).
+ */
+export type AccessTokenAuthorizationMode = "embedded" | "introspection" | "decision";
+import type { JWTPayload } from "jose";
+interface RawPayload extends JWTPayload {
+    scope?: string;
+    scopes?: string[];
+    roles?: string[];
+    permissions?: string[];
+    groups?: string[];
+    oid?: string;
+    org_groups?: string[];
+    token_type?: string;
+    required_actions?: string[];
+    [key: string]: unknown;
+}
+export declare class VerifiedToken {
+    private readonly _payload;
+    private readonly _header;
+    constructor(payload: JWTPayload, header: Record<string, unknown>);
+    /** The `sub` claim. Returns empty string if absent. */
+    subject(): string;
+    /** The `iss` claim. Returns empty string if absent. */
+    issuer(): string;
+    /** The `aud` claim normalized to an array. */
+    audiences(): string[];
+    /** The `iat` claim as a Date, or null if absent. */
+    issuedAt(): Date | null;
+    /** The `exp` claim as a Date, or null if absent. */
+    expiry(): Date | null;
+    /** The `nbf` claim as a Date, or null if absent. */
+    notBefore(): Date | null;
+    /** The `jti` (JWT ID) claim. Returns empty string if absent. */
+    jwtID(): string;
+    /** The raw `scope` string claim (space-separated). Returns empty string if absent. */
+    scope(): string;
+    /** The `scope` claim split into individual values, or the `scopes` array if present. */
+    scopes(): string[];
+    /** Get an arbitrary claim by key. */
+    get(key: string): unknown;
+    /** Return the raw JWT payload object. */
+    raw(): Readonly<RawPayload>;
+    /** Timing-safe check: returns true if the token contains the given scope. */
+    hasScope(s: string): boolean;
+    /** Timing-safe check: returns true if the token's `roles` claim contains the given role. */
+    hasRole(r: string): boolean;
+    /** Timing-safe check: returns true if the token's `permissions` claim contains the given permission. */
+    hasPermission(p: string): boolean;
+    /** Returns true if the token's `groups` claim contains the given group id. */
+    inGroup(groupId: string): boolean;
+    /** Returns true if the token's `oid` claim exactly matches the given org id. */
+    inOrg(orgId: string): boolean;
+    /** The `token_type` claim (`"access"`, `"refresh"`, `"required_action"`). Returns empty string if absent. */
+    tokenType(): string;
+    /** The `oid` (organization ID) claim, or undefined if absent. */
+    organizationId(): string | undefined;
+    /** The `org_groups` claim (Keycloak-style group paths). Returns empty array if absent. */
+    orgGroups(): string[];
+    /** The `required_actions` claim. Returns empty array if absent. */
+    requiredActions(): string[];
+    /** @internal Expose header for downstream use (e.g. kid extraction). */
+    get _rawHeader(): Record<string, unknown>;
+}
+export {};
+//# sourceMappingURL=token.d.ts.map

package/dist/token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../src/token.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAE9D;;;GAGG;AACH,MAAM,MAAM,4BAA4B,GAAG,UAAU,GAAG,eAAe,GAAG,UAAU,CAAC;AAGrF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAQvC,UAAU,UAAW,SAAQ,UAAU;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAa;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;gBAEtC,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAKhE,uDAAuD;IACvD,OAAO,IAAI,MAAM;IAIjB,uDAAuD;IACvD,MAAM,IAAI,MAAM;IAIhB,8CAA8C;IAC9C,SAAS,IAAI,MAAM,EAAE;IAMrB,oDAAoD;IACpD,QAAQ,IAAI,IAAI,GAAG,IAAI;IAIvB,oDAAoD;IACpD,MAAM,IAAI,IAAI,GAAG,IAAI;IAIrB,oDAAoD;IACpD,SAAS,IAAI,IAAI,GAAG,IAAI;IAIxB,gEAAgE;IAChE,KAAK,IAAI,MAAM;IAIf,sFAAsF;IACtF,KAAK,IAAI,MAAM;IAIf,wFAAwF;IACxF,MAAM,IAAI,MAAM,EAAE;IAOlB,qCAAqC;IACrC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIzB,yCAAyC;IACzC,GAAG,IAAI,QAAQ,CAAC,UAAU,CAAC;IAI3B,6EAA6E;IAC7E,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO;IAI5B,4FAA4F;IAC5F,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO;IAI3B,wGAAwG;IACxG,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO;IAIjC,8EAA8E;IAC9E,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAIjC,gFAAgF;IAChF,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAM7B,6GAA6G;IAC7G,SAAS,IAAI,MAAM;IAInB,iEAAiE;IACjE,cAAc,IAAI,MAAM,GAAG,SAAS;IAIpC,0FAA0F;IAC1F,SAAS,IAAI,MAAM,EAAE;IAIrB,mEAAmE;IACnE,eAAe,IAAI,MAAM,EAAE;IAI3B,wEAAwE;IACxE,IAAI,UAAU,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAExC;CACF"}

package/dist/token.js

@@ -0,0 +1,111 @@
+/** §4 — VerifiedToken: typed claims accessors and helpers. */
+import { timingSafeEqual } from "node:crypto";
+function timingSafeStringEqual(a, b) {
+    const bufA = Buffer.from(a.padEnd(Math.max(a.length, b.length), "\0"));
+    const bufB = Buffer.from(b.padEnd(Math.max(a.length, b.length), "\0"));
+    return timingSafeEqual(bufA, bufB);
+}
+export class VerifiedToken {
+    _payload;
+    _header;
+    constructor(payload, header) {
+        this._payload = payload;
+        this._header = header;
+    }
+    /** The `sub` claim. Returns empty string if absent. */
+    subject() {
+        return this._payload.sub ?? "";
+    }
+    /** The `iss` claim. Returns empty string if absent. */
+    issuer() {
+        return this._payload.iss ?? "";
+    }
+    /** The `aud` claim normalized to an array. */
+    audiences() {
+        const aud = this._payload.aud;
+        if (!aud)
+            return [];
+        return Array.isArray(aud) ? aud : [aud];
+    }
+    /** The `iat` claim as a Date, or null if absent. */
+    issuedAt() {
+        return this._payload.iat !== undefined ? new Date(this._payload.iat * 1000) : null;
+    }
+    /** The `exp` claim as a Date, or null if absent. */
+    expiry() {
+        return this._payload.exp !== undefined ? new Date(this._payload.exp * 1000) : null;
+    }
+    /** The `nbf` claim as a Date, or null if absent. */
+    notBefore() {
+        return this._payload.nbf !== undefined ? new Date(this._payload.nbf * 1000) : null;
+    }
+    /** The `jti` (JWT ID) claim. Returns empty string if absent. */
+    jwtID() {
+        return this._payload.jti ?? "";
+    }
+    /** The raw `scope` string claim (space-separated). Returns empty string if absent. */
+    scope() {
+        return this._payload.scope ?? "";
+    }
+    /** The `scope` claim split into individual values, or the `scopes` array if present. */
+    scopes() {
+        if (this._payload.scopes)
+            return [...this._payload.scopes];
+        const sc = this._payload.scope;
+        if (!sc)
+            return [];
+        return sc.split(/\s+/).filter(Boolean);
+    }
+    /** Get an arbitrary claim by key. */
+    get(key) {
+        return this._payload[key];
+    }
+    /** Return the raw JWT payload object. */
+    raw() {
+        return Object.freeze({ ...this._payload });
+    }
+    /** Timing-safe check: returns true if the token contains the given scope. */
+    hasScope(s) {
+        return this.scopes().some((sc) => timingSafeStringEqual(sc, s));
+    }
+    /** Timing-safe check: returns true if the token's `roles` claim contains the given role. */
+    hasRole(r) {
+        return (this._payload.roles ?? []).some((role) => timingSafeStringEqual(role, r));
+    }
+    /** Timing-safe check: returns true if the token's `permissions` claim contains the given permission. */
+    hasPermission(p) {
+        return (this._payload.permissions ?? []).some((perm) => timingSafeStringEqual(perm, p));
+    }
+    /** Returns true if the token's `groups` claim contains the given group id. */
+    inGroup(groupId) {
+        return (this._payload.groups ?? []).some((g) => timingSafeStringEqual(g, groupId));
+    }
+    /** Returns true if the token's `oid` claim exactly matches the given org id. */
+    inOrg(orgId) {
+        const oid = this._payload.oid;
+        if (!oid)
+            return false;
+        return timingSafeStringEqual(oid, orgId);
+    }
+    /** The `token_type` claim (`"access"`, `"refresh"`, `"required_action"`). Returns empty string if absent. */
+    tokenType() {
+        return this._payload.token_type ?? "";
+    }
+    /** The `oid` (organization ID) claim, or undefined if absent. */
+    organizationId() {
+        return this._payload.oid;
+    }
+    /** The `org_groups` claim (Keycloak-style group paths). Returns empty array if absent. */
+    orgGroups() {
+        return this._payload.org_groups ? [...this._payload.org_groups] : [];
+    }
+    /** The `required_actions` claim. Returns empty array if absent. */
+    requiredActions() {
+        return this._payload.required_actions ? [...this._payload.required_actions] : [];
+    }
+    /** @internal Expose header for downstream use (e.g. kid extraction). */
+    get _rawHeader() {
+        return this._header;
+    }
+}
+//# sourceMappingURL=token.js.map

package/dist/token.js.map

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

package/dist/token.test.d.ts

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

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

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

package/dist/token.test.js

@@ -0,0 +1,135 @@
+import { describe, it, expect } from "vitest";
+import { VerifiedToken } from "./token.js";
+function makeToken(overrides = {}) {
+    const payload = {
+        sub: "user123",
+        iss: "https://auth.example.com",
+        aud: ["api.example.com", "admin.example.com"],
+        iat: 1_700_000_000,
+        exp: 1_700_003_600,
+        nbf: 1_700_000_000,
+        ...overrides,
+    };
+    return new VerifiedToken(payload, { alg: "RS256", kid: "key-1" });
+}
+describe("VerifiedToken claims accessors", () => {
+    it("subject() returns sub", () => expect(makeToken().subject()).toBe("user123"));
+    it("issuer() returns iss", () => expect(makeToken().issuer()).toBe("https://auth.example.com"));
+    it("audiences() returns normalized array", () => expect(makeToken().audiences()).toEqual(["api.example.com", "admin.example.com"]));
+    it("audiences() returns [] when absent", () => expect(makeToken({ aud: undefined }).audiences()).toEqual([]));
+    it("audiences() wraps single string in array", () => expect(makeToken({ aud: "only.one" }).audiences()).toEqual(["only.one"]));
+    it("issuedAt() returns Date", () => expect(makeToken().issuedAt()).toEqual(new Date(1_700_000_000_000)));
+    it("expiry() returns Date", () => expect(makeToken().expiry()).toEqual(new Date(1_700_003_600_000)));
+    it("notBefore() returns Date", () => expect(makeToken().notBefore()).toEqual(new Date(1_700_000_000_000)));
+    it("issuedAt/expiry/notBefore return null when absent", () => {
+        const t = makeToken({ iat: undefined, exp: undefined, nbf: undefined });
+        expect(t.issuedAt()).toBeNull();
+        expect(t.expiry()).toBeNull();
+        expect(t.notBefore()).toBeNull();
+    });
+    it("jwtID() returns jti claim", () => {
+        const t = makeToken({ jti: "unique-jwt-id-123" });
+        expect(t.jwtID()).toBe("unique-jwt-id-123");
+    });
+    it("jwtID() returns empty string when absent", () => {
+        expect(makeToken().jwtID()).toBe("");
+    });
+    it("scope() returns raw scope string", () => {
+        const t = makeToken({ scope: "openid profile email" });
+        expect(t.scope()).toBe("openid profile email");
+    });
+    it("scopes() splits scope string", () => {
+        const t = makeToken({ scope: "openid profile email" });
+        expect(t.scopes()).toEqual(["openid", "profile", "email"]);
+    });
+    it("scopes() prefers scopes array over scope string", () => {
+        const t = makeToken({ scopes: ["a", "b"] });
+        expect(t.scopes()).toEqual(["a", "b"]);
+    });
+    it("get(key) returns arbitrary claim", () => {
+        const t = makeToken({ custom_claim: "hello" });
+        expect(t.get("custom_claim")).toBe("hello");
+    });
+    it("raw() returns frozen payload copy", () => {
+        const t = makeToken();
+        const r = t.raw();
+        expect(r.sub).toBe("user123");
+        expect(Object.isFrozen(r)).toBe(true);
+    });
+});
+describe("VerifiedToken hasScope / hasRole / hasPermission (timing-safe)", () => {
+    it("hasScope returns true for present scope", () => {
+        const t = makeToken({ scope: "openid read:users" });
+        expect(t.hasScope("openid")).toBe(true);
+        expect(t.hasScope("read:users")).toBe(true);
+    });
+    it("hasScope returns false for absent scope", () => {
+        const t = makeToken({ scope: "openid" });
+        expect(t.hasScope("admin")).toBe(false);
+    });
+    it("hasRole returns true/false correctly", () => {
+        const t = makeToken({ roles: ["admin", "viewer"] });
+        expect(t.hasRole("admin")).toBe(true);
+        expect(t.hasRole("superuser")).toBe(false);
+    });
+    it("hasPermission returns true/false correctly", () => {
+        const t = makeToken({ permissions: ["users:read", "users:write"] });
+        expect(t.hasPermission("users:read")).toBe(true);
+        expect(t.hasPermission("users:delete")).toBe(false);
+    });
+    it("hasScope handles empty scopes gracefully", () => {
+        const t = makeToken({});
+        expect(t.hasScope("anything")).toBe(false);
+    });
+});
+describe("VerifiedToken Hearth custom claims", () => {
+    it("inGroup() returns true when group is present", () => {
+        const t = makeToken({ groups: ["admins", "developers"] });
+        expect(t.inGroup("admins")).toBe(true);
+        expect(t.inGroup("developers")).toBe(true);
+    });
+    it("inGroup() returns false when group is absent", () => {
+        const t = makeToken({ groups: ["admins"] });
+        expect(t.inGroup("viewers")).toBe(false);
+    });
+    it("inGroup() returns false when groups claim is missing", () => {
+        expect(makeToken().inGroup("anything")).toBe(false);
+    });
+    it("inOrg() returns true when oid matches", () => {
+        const t = makeToken({ oid: "org_abc123" });
+        expect(t.inOrg("org_abc123")).toBe(true);
+    });
+    it("inOrg() returns false when oid does not match", () => {
+        const t = makeToken({ oid: "org_abc123" });
+        expect(t.inOrg("org_xyz789")).toBe(false);
+    });
+    it("inOrg() returns false when oid claim is missing", () => {
+        expect(makeToken().inOrg("org_abc123")).toBe(false);
+    });
+    it("tokenType() returns token_type claim", () => {
+        const t = makeToken({ token_type: "access" });
+        expect(t.tokenType()).toBe("access");
+    });
+    it("tokenType() returns empty string when absent", () => {
+        expect(makeToken().tokenType()).toBe("");
+    });
+    it("tokenType() returns required_action for required-action tokens", () => {
+        const t = makeToken({ token_type: "required_action" });
+        expect(t.tokenType()).toBe("required_action");
+    });
+    it("organizationId() returns oid claim", () => {
+        const t = makeToken({ oid: "org_abc123" });
+        expect(t.organizationId()).toBe("org_abc123");
+    });
+    it("organizationId() returns undefined when absent", () => {
+        expect(makeToken().organizationId()).toBeUndefined();
+    });
+    it("orgGroups() returns org_groups claim array", () => {
+        const t = makeToken({ org_groups: ["/acme/engineers", "/acme/admins"] });
+        expect(t.orgGroups()).toEqual(["/acme/engineers", "/acme/admins"]);
+    });
+    it("orgGroups() returns empty array when absent", () => {
+        expect(makeToken().orgGroups()).toEqual([]);
+    });
+});
+//# sourceMappingURL=token.test.js.map

package/dist/token.test.js.map

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

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@hearth-auth/node",
+  "version": "0.0.1",
+  "description": "Hearth server-side Node.js SDK — JWKS verification, token introspection, Express/Fastify middleware",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run --coverage",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "jose": "5.9.6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "^3.2.0",
+    "typescript": "^5.5.0",
+    "vitest": "^3.2.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}