@hearth-auth/sdk 0.0.1

package/tests/claims.test.ts

@@ -0,0 +1,159 @@
+/**
+ * Unit tests for Claims class — spec §4.
+ * Tests are written before implementation (TDD).
+ */
+
+import { describe, it, expect } from "vitest";
+import { Claims } from "../src/claims.js";
+
+/** Build a fake JWT string with the given payload (no signature verification). */
+function forgeJwt(payload: Record<string, unknown>): string {
+  const header = Buffer.from(
+    JSON.stringify({ alg: "EdDSA", typ: "JWT" }),
+    "utf8",
+  ).toString("base64url");
+  const body = Buffer.from(JSON.stringify(payload), "utf8").toString(
+    "base64url",
+  );
+  const sig = Buffer.from("fake-sig").toString("base64url");
+  return `${header}.${body}.${sig}`;
+}
+
+// ── scope() ────────────────────────────────────────────────────────────────
+
+describe("Claims.scope()", () => {
+  it("returns the raw space-delimited scope string", () => {
+    const c = new Claims({ scope: "openid profile email" });
+    expect(c.scope()).toBe("openid profile email");
+  });
+
+  it("returns empty string when scope is absent", () => {
+    const c = new Claims({});
+    expect(c.scope()).toBe("");
+  });
+});
+
+// ── inGroup() ──────────────────────────────────────────────────────────────
+
+describe("Claims.inGroup()", () => {
+  it("returns true when groups claim contains the group", () => {
+    const c = new Claims({ groups: ["engineering", "security"] });
+    expect(c.inGroup("engineering")).toBe(true);
+    expect(c.inGroup("security")).toBe(true);
+  });
+
+  it("returns false when group is not in the list", () => {
+    const c = new Claims({ groups: ["engineering"] });
+    expect(c.inGroup("security")).toBe(false);
+  });
+
+  it("returns false when groups claim is absent", () => {
+    const c = new Claims({});
+    expect(c.inGroup("engineering")).toBe(false);
+  });
+
+  it("returns false when groups claim is not an array", () => {
+    const c = new Claims({ groups: "engineering" as unknown });
+    expect(c.inGroup("engineering")).toBe(false);
+  });
+});
+
+// ── inOrg() ────────────────────────────────────────────────────────────────
+
+describe("Claims.inOrg()", () => {
+  it("returns true when oid claim exactly matches", () => {
+    const c = new Claims({ oid: "org_abc123" });
+    expect(c.inOrg("org_abc123")).toBe(true);
+  });
+
+  it("returns false when oid claim does not match", () => {
+    const c = new Claims({ oid: "org_abc123" });
+    expect(c.inOrg("org_xyz")).toBe(false);
+  });
+
+  it("returns false when oid claim is absent", () => {
+    const c = new Claims({});
+    expect(c.inOrg("org_abc123")).toBe(false);
+  });
+});
+
+// ── tokenType() ────────────────────────────────────────────────────────────
+
+describe("Claims.tokenType()", () => {
+  it("returns the token_type claim value", () => {
+    const c = new Claims({ token_type: "access" });
+    expect(c.tokenType()).toBe("access");
+  });
+
+  it("returns 'required_action' for required-action tokens", () => {
+    const c = new Claims({ token_type: "required_action" });
+    expect(c.tokenType()).toBe("required_action");
+  });
+
+  it("returns 'refresh' for refresh tokens", () => {
+    const c = new Claims({ token_type: "refresh" });
+    expect(c.tokenType()).toBe("refresh");
+  });
+
+  it("returns empty string when token_type is absent", () => {
+    const c = new Claims({});
+    expect(c.tokenType()).toBe("");
+  });
+});
+
+// ── organizationId() ──────────────────────────────────────────────────────
+
+describe("Claims.organizationId()", () => {
+  it("returns the oid claim value", () => {
+    const c = new Claims({ oid: "org_abc123" });
+    expect(c.organizationId()).toBe("org_abc123");
+  });
+
+  it("returns undefined when oid is absent", () => {
+    const c = new Claims({});
+    expect(c.organizationId()).toBeUndefined();
+  });
+});
+
+// ── orgGroups() ────────────────────────────────────────────────────────────
+
+describe("Claims.orgGroups()", () => {
+  it("returns the org_groups claim array", () => {
+    const c = new Claims({
+      org_groups: ["/acme-corp/admins", "/acme-corp/engineering"],
+    });
+    expect(c.orgGroups()).toEqual(["/acme-corp/admins", "/acme-corp/engineering"]);
+  });
+
+  it("returns empty array when org_groups is absent", () => {
+    const c = new Claims({});
+    expect(c.orgGroups()).toEqual([]);
+  });
+
+  it("returns empty array when org_groups is not an array", () => {
+    const c = new Claims({ org_groups: "invalid" as unknown });
+    expect(c.orgGroups()).toEqual([]);
+  });
+});
+
+// ── decode() integration — all new claims survive round-trip ──────────────
+
+describe("Claims.decode() — new claims present in JWT", () => {
+  it("parses all new claims from a forged JWT", () => {
+    const jwt = forgeJwt({
+      sub: "user_1",
+      scope: "openid profile",
+      groups: ["eng"],
+      oid: "org_42",
+      token_type: "access",
+      org_groups: ["/org/eng"],
+    });
+    const c = Claims.decode(jwt);
+    expect(c.scope()).toBe("openid profile");
+    expect(c.inGroup("eng")).toBe(true);
+    expect(c.inOrg("org_42")).toBe(true);
+    expect(c.tokenType()).toBe("access");
+    expect(c.organizationId()).toBe("org_42");
+    expect(c.orgGroups()).toEqual(["/org/eng"]);
+  });
+});

package/tests/hasPermission.test.ts

@@ -0,0 +1,152 @@
+import { describe, expect, it } from "vitest";
+import { createHearth } from "../src/hearth.js";
+
+/**
+ * Build a syntactically valid three-segment JWT around the given claims.
+ * The signature segment is arbitrary — `jose.decodeJwt` does not verify
+ * it, which matches what `createHearth` does on every check.
+ */
+function forgeJwt(claims: Record<string, unknown>): string {
+  const header = Buffer.from(
+    JSON.stringify({ alg: "EdDSA", typ: "JWT" }),
+    "utf8",
+  ).toString("base64url");
+  const body = Buffer.from(JSON.stringify(claims), "utf8").toString("base64url");
+  const sig = Buffer.from("not-a-real-signature").toString("base64url");
+  return `${header}.${body}.${sig}`;
+}
+
+describe("createHearth — hasPermission", () => {
+  it("returns true when the JWT permissions claim contains the permission", () => {
+    const token = forgeJwt({
+      sub: "user_1",
+      permissions: ["docs.edit", "docs.view"],
+    });
+    const hearth = createHearth({
+      baseUrl: "http://localhost",
+      realmId: "r1",
+      getToken: () => token,
+    });
+    expect(hearth.hasPermission("docs.edit")).toBe(true);
+    expect(hearth.hasPermission("docs.view")).toBe(true);
+  });
+
+  it("returns false when the permission is absent", () => {
+    const token = forgeJwt({ permissions: ["docs.view"] });
+    const hearth = createHearth({
+      baseUrl: "http://localhost",
+      realmId: "r1",
+      getToken: () => token,
+    });
+    expect(hearth.hasPermission("docs.edit")).toBe(false);
+  });
+
+  it("returns false when the token is absent", () => {
+    const hearth = createHearth({
+      baseUrl: "http://localhost",
+      realmId: "r1",
+      getToken: () => null,
+    });
+    expect(hearth.hasPermission("docs.edit")).toBe(false);
+  });
+
+  it("returns false when the token is malformed", () => {
+    const hearth = createHearth({
+      baseUrl: "http://localhost",
+      realmId: "r1",
+      getToken: () => "not.a.jwt",
+    });
+    expect(hearth.hasPermission("docs.edit")).toBe(false);
+  });
+
+  it("returns false when the permissions claim is missing", () => {
+    const token = forgeJwt({ sub: "user_1" });
+    const hearth = createHearth({
+      baseUrl: "http://localhost",
+      realmId: "r1",
+      getToken: () => token,
+    });
+    expect(hearth.hasPermission("docs.edit")).toBe(false);
+  });
+
+  it("calls getToken on every invocation (no caching)", () => {
+    let current: string | null = null;
+    const hearth = createHearth({
+      baseUrl: "http://localhost",
+      realmId: "r1",
+      getToken: () => current,
+    });
+    expect(hearth.hasPermission("docs.edit")).toBe(false);
+    current = forgeJwt({ permissions: ["docs.edit"] });
+    expect(hearth.hasPermission("docs.edit")).toBe(true);
+    current = null;
+    expect(hearth.hasPermission("docs.edit")).toBe(false);
+  });
+});
+
+describe("createHearth — hasRole", () => {
+  it("returns true when the JWT roles claim contains the role", () => {
+    const token = forgeJwt({ roles: ["admin", "editor"] });
+    const hearth = createHearth({
+      baseUrl: "http://localhost",
+      realmId: "r1",
+      getToken: () => token,
+    });
+    expect(hearth.hasRole("admin")).toBe(true);
+    expect(hearth.hasRole("viewer")).toBe(false);
+  });
+
+  it("returns false when the roles claim is missing or malformed", () => {
+    const hearth = createHearth({
+      baseUrl: "http://localhost",
+      realmId: "r1",
+      getToken: () => forgeJwt({ roles: "admin" as unknown }),
+    });
+    expect(hearth.hasRole("admin")).toBe(false);
+  });
+});
+
+describe("createHearth — inGroup", () => {
+  it("returns true when the JWT groups claim contains the group", () => {
+    const token = forgeJwt({ groups: ["engineering", "security"] });
+    const hearth = createHearth({
+      baseUrl: "http://localhost",
+      realmId: "r1",
+      getToken: () => token,
+    });
+    expect(hearth.inGroup("engineering")).toBe(true);
+    expect(hearth.inGroup("marketing")).toBe(false);
+  });
+
+  it("returns false when no token", () => {
+    const hearth = createHearth({
+      baseUrl: "http://localhost",
+      realmId: "r1",
+      getToken: () => undefined,
+    });
+    expect(hearth.inGroup("engineering")).toBe(false);
+  });
+});
+
+describe("createHearth — inOrg", () => {
+  it("returns true when the JWT oid claim equals the org", () => {
+    const token = forgeJwt({ oid: "org_42" });
+    const hearth = createHearth({
+      baseUrl: "http://localhost",
+      realmId: "r1",
+      getToken: () => token,
+    });
+    expect(hearth.inOrg("org_42")).toBe(true);
+    expect(hearth.inOrg("org_7")).toBe(false);
+  });
+
+  it("returns false when oid is missing", () => {
+    const token = forgeJwt({ sub: "user_1" });
+    const hearth = createHearth({
+      baseUrl: "http://localhost",
+      realmId: "r1",
+      getToken: () => token,
+    });
+    expect(hearth.inOrg("org_42")).toBe(false);
+  });
+});

package/tests/hearth-client.test.ts

@@ -0,0 +1,243 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { HearthClient } from "../src/hearth-client.js";
+import { ConfigurationError, DiscoveryError } from "../src/errors.js";
+
+const DISCOVERY_DOC = {
+  issuer: "https://auth.example.com",
+  jwks_uri: "https://auth.example.com/jwks",
+  introspection_endpoint: "https://auth.example.com/introspect",
+};
+
+describe("HearthClient — construction", () => {
+  it("throws ConfigurationError when issuerUrl is absent", () => {
+    expect(
+      () => new HearthClient({ issuerUrl: "" }),
+    ).toThrow(ConfigurationError);
+  });
+
+  it("throws ConfigurationError when issuerUrl is not a valid URL", () => {
+    expect(
+      () => new HearthClient({ issuerUrl: "not-a-url" }),
+    ).toThrow(ConfigurationError);
+  });
+
+  it("normalises a trailing slash on issuerUrl", () => {
+    const client = new HearthClient({ issuerUrl: "https://auth.example.com/" });
+    expect(client.issuerUrl).toBe("https://auth.example.com");
+  });
+
+  it("defaults httpTimeout to 10 000 ms", () => {
+    const client = new HearthClient({ issuerUrl: "https://auth.example.com" });
+    expect(client.httpTimeout).toBe(10_000);
+  });
+
+  it("accepts a custom httpTimeout", () => {
+    const client = new HearthClient({
+      issuerUrl: "https://auth.example.com",
+      httpTimeout: 5_000,
+    });
+    expect(client.httpTimeout).toBe(5_000);
+  });
+});
+
+describe("HearthClient — OIDC discovery", () => {
+  beforeEach(() => {
+    vi.stubGlobal("fetch", vi.fn());
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  function mockFetch(body: unknown, status = 200): void {
+    const mockedFetch = vi.mocked(fetch);
+    mockedFetch.mockResolvedValueOnce(
+      new Response(JSON.stringify(body), {
+        status,
+        headers: { "Content-Type": "application/json" },
+      }),
+    );
+  }
+
+  it("fetches discovery from {issuerUrl}/.well-known/openid-configuration", async () => {
+    mockFetch(DISCOVERY_DOC);
+    const client = new HearthClient({ issuerUrl: "https://auth.example.com" });
+    await client.discover();
+    expect(vi.mocked(fetch)).toHaveBeenCalledWith(
+      "https://auth.example.com/.well-known/openid-configuration",
+      expect.objectContaining({ signal: expect.anything() }),
+    );
+  });
+
+  it("caches the discovery document on repeated calls", async () => {
+    mockFetch(DISCOVERY_DOC);
+    const client = new HearthClient({ issuerUrl: "https://auth.example.com" });
+    await client.discover();
+    await client.discover();
+    expect(vi.mocked(fetch)).toHaveBeenCalledTimes(1);
+  });
+
+  it("throws DiscoveryError when fetch rejects (network error)", async () => {
+    vi.mocked(fetch).mockRejectedValueOnce(new Error("ECONNREFUSED"));
+    const client = new HearthClient({ issuerUrl: "https://auth.example.com" });
+    await expect(client.discover()).rejects.toThrow(DiscoveryError);
+  });
+
+  it("throws DiscoveryError on non-2xx HTTP response", async () => {
+    mockFetch({ error: "not found" }, 404);
+    const client = new HearthClient({ issuerUrl: "https://auth.example.com" });
+    await expect(client.discover()).rejects.toThrow(DiscoveryError);
+  });
+
+  it("throws DiscoveryError when discovery document is missing jwks_uri", async () => {
+    mockFetch({ issuer: "https://auth.example.com" });
+    const client = new HearthClient({ issuerUrl: "https://auth.example.com" });
+    await expect(client.discover()).rejects.toThrow(DiscoveryError);
+  });
+});
+
+describe("HearthClient — jwksClient()", () => {
+  beforeEach(() => {
+    vi.stubGlobal("fetch", vi.fn());
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  function mockDiscovery(): void {
+    vi.mocked(fetch).mockResolvedValueOnce(
+      new Response(JSON.stringify(DISCOVERY_DOC), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      }),
+    );
+  }
+
+  it("returns a JwksClient bound to the discovered jwks_uri", async () => {
+    mockDiscovery();
+    const client = new HearthClient({
+      issuerUrl: "https://auth.example.com",
+      jwksTtl: 60_000,
+    });
+    const jwks = await client.jwksClient();
+    expect(jwks.ttl).toBe(60_000);
+  });
+
+  it("reuses the same JwksClient instance across calls", async () => {
+    mockDiscovery();
+    const client = new HearthClient({ issuerUrl: "https://auth.example.com" });
+    const a = await client.jwksClient();
+    const b = await client.jwksClient();
+    expect(a).toBe(b);
+    // Discovery fetched only once
+    expect(vi.mocked(fetch)).toHaveBeenCalledTimes(1);
+  });
+
+  it("passes httpTimeout to the JwksClient", async () => {
+    mockDiscovery();
+    const client = new HearthClient({
+      issuerUrl: "https://auth.example.com",
+      httpTimeout: 3_000,
+    });
+    const jwks = await client.jwksClient();
+    expect(jwks.httpTimeout).toBe(3_000);
+  });
+});
+
+describe("HearthClient — introspectionClient()", () => {
+  beforeEach(() => {
+    vi.stubGlobal("fetch", vi.fn());
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  function mockDiscovery(): void {
+    vi.mocked(fetch).mockResolvedValueOnce(
+      new Response(JSON.stringify(DISCOVERY_DOC), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      }),
+    );
+  }
+
+  it("throws ConfigurationError when clientId is absent", async () => {
+    const client = new HearthClient({
+      issuerUrl: "https://auth.example.com",
+      clientSecret: "secret",
+    });
+    await expect(client.introspectionClient()).rejects.toThrow(
+      ConfigurationError,
+    );
+  });
+
+  it("throws ConfigurationError when clientSecret is absent", async () => {
+    const client = new HearthClient({
+      issuerUrl: "https://auth.example.com",
+      clientId: "my-client",
+    });
+    await expect(client.introspectionClient()).rejects.toThrow(
+      ConfigurationError,
+    );
+  });
+
+  it("uses the introspection_endpoint from the discovery document", async () => {
+    mockDiscovery();
+    const client = new HearthClient({
+      issuerUrl: "https://auth.example.com",
+      clientId: "my-client",
+      clientSecret: "secret",
+    });
+    const ic = await client.introspectionClient();
+    expect(ic.httpTimeout).toBe(10_000);
+  });
+
+  it("prefers introspectionEndpoint override over discovered value", async () => {
+    const client = new HearthClient({
+      issuerUrl: "https://auth.example.com",
+      clientId: "my-client",
+      clientSecret: "secret",
+      introspectionEndpoint: "https://custom.example.com/introspect",
+    });
+    // No fetch mock needed — override bypasses discovery
+    const ic = await client.introspectionClient();
+    expect(ic).toBeDefined();
+    expect(vi.mocked(fetch)).not.toHaveBeenCalled();
+  });
+
+  it("reuses the same IntrospectionClient instance", async () => {
+    mockDiscovery();
+    const client = new HearthClient({
+      issuerUrl: "https://auth.example.com",
+      clientId: "my-client",
+      clientSecret: "secret",
+    });
+    const a = await client.introspectionClient();
+    const b = await client.introspectionClient();
+    expect(a).toBe(b);
+    expect(vi.mocked(fetch)).toHaveBeenCalledTimes(1);
+  });
+
+  it("throws ConfigurationError when discovery has no introspection_endpoint and no override", async () => {
+    const docWithoutIntrospect = {
+      issuer: "https://auth.example.com",
+      jwks_uri: "https://auth.example.com/jwks",
+    };
+    vi.mocked(fetch).mockResolvedValueOnce(
+      new Response(JSON.stringify(docWithoutIntrospect), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      }),
+    );
+    const client = new HearthClient({
+      issuerUrl: "https://auth.example.com",
+      clientId: "my-client",
+      clientSecret: "secret",
+    });
+    await expect(client.introspectionClient()).rejects.toThrow(
+      ConfigurationError,
+    );
+  });
+});

package/tests/helpers.ts

@@ -0,0 +1,90 @@
+import { execSync, spawn, type ChildProcess } from "node:child_process";
+import { HearthApiClient } from "../src/client.js";
+import type { BootstrapResponse } from "../src/types.js";
+
+const PROJECT_ROOT = new URL("../../..", import.meta.url).pathname.replace(
+  /\/$/,
+  "",
+);
+
+/** Resolve the hearth binary path, respecting CARGO_TARGET_DIR. */
+function hearthBinPath(): string {
+  const targetDir = process.env.CARGO_TARGET_DIR ?? `${PROJECT_ROOT}/target`;
+  return `${targetDir}/debug/hearth`;
+}
+
+/** Build the hearth binary if not already built. */
+export function ensureBinary(): void {
+  execSync("cargo build", { cwd: PROJECT_ROOT, stdio: "pipe" });
+}
+
+/** Find a free port by briefly binding to port 0. */
+async function findFreePort(): Promise<number> {
+  const net = await import("node:net");
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      if (!addr || typeof addr === "string") {
+        server.close();
+        reject(new Error("failed to get port"));
+        return;
+      }
+      const port = addr.port;
+      server.close(() => resolve(port));
+    });
+  });
+}
+
+export interface TestServer {
+  port: number;
+  baseUrl: string;
+  process: ChildProcess;
+  bootstrap: BootstrapResponse;
+  client: HearthApiClient;
+}
+
+/** Start a Hearth dev server and bootstrap admin credentials. */
+export async function startServer(): Promise<TestServer> {
+  const port = await findFreePort();
+  const baseUrl = `http://127.0.0.1:${port}`;
+
+  const proc = spawn(hearthBinPath(), ["serve", "--dev", "--port", String(port)], {
+    stdio: "pipe",
+    env: { ...process.env, RUST_LOG: "warn" },
+  });
+
+  // Wait for health endpoint
+  const maxWait = 15_000;
+  const start = Date.now();
+  while (Date.now() - start < maxWait) {
+    try {
+      const resp = await fetch(`${baseUrl}/health`);
+      if (resp.ok) break;
+    } catch {
+      // Not ready yet
+    }
+    await new Promise((r) => setTimeout(r, 100));
+  }
+
+  // Verify server is actually up
+  const healthResp = await fetch(`${baseUrl}/health`);
+  if (!healthResp.ok) {
+    proc.kill();
+    throw new Error("Hearth server failed to start");
+  }
+
+  // Bootstrap admin credentials
+  const bootstrap = await HearthApiClient.bootstrap(baseUrl);
+  const client = new HearthApiClient({
+    baseUrl,
+    realmId: bootstrap.realm_id,
+  });
+
+  return { port, baseUrl, process: proc, bootstrap, client };
+}
+
+/** Stop a running test server. */
+export function stopServer(server: TestServer): void {
+  server.process.kill("SIGTERM");
+}