@hearth-auth/sdk 0.0.1 → 1.0.1

package/tests/jwks.test.ts

@@ -1,62 +0,0 @@
-import { describe, it, expect, beforeAll, afterAll } from "vitest";
-import * as jose from "jose";
-import { ensureBinary, startServer, stopServer, type TestServer } from "./helpers.js";
-
-describe("TypeScript SDK: JWKS Validation", () => {
-  let server: TestServer;
-
-  beforeAll(async () => {
-    ensureBinary();
-    server = await startServer();
-  });
-
-  afterAll(() => {
-    if (server) stopServer(server);
-  });
-
-  it("verifies token signatures using JWKS-fetched public keys", async () => {
-    const { client, bootstrap } = server;
-
-    // 1. Fetch the JWKS document
-    const jwks = await client.jwks();
-    expect(jwks.keys).toBeTruthy();
-    expect(jwks.keys.length).toBeGreaterThan(0);
-
-    // Verify the key is an Ed25519 (OKP) key
-    const key = jwks.keys[0];
-    expect(key.kty).toBe("OKP");
-    expect(key.crv).toBe("Ed25519");
-    expect(key.x).toBeTruthy();
-    expect(key.alg).toBe("EdDSA");
-    expect(key.use).toBe("sig");
-    expect(key.kid).toBeTruthy();
-
-    // 2. Import the public key for verification
-    const publicKey = await jose.importJWK(key as jose.JWK, "EdDSA");
-
-    // 3. The bootstrap access token is signed with the global key (same as /jwks)
-    //    Verify it directly against the JWKS-fetched key
-    const { payload: accessPayload } = await jose.jwtVerify(
-      bootstrap.access_token,
-      publicKey,
-    );
-    expect(accessPayload.sub).toBeTruthy();
-    expect(accessPayload.exp).toBeTruthy();
-
-    // 4. Verify the OIDC discovery document references the JWKS endpoint
-    const discovery = await client.discovery();
-    expect(discovery.jwks_uri).toBeTruthy();
-
-    // 5. Verify the JWT header contains the correct kid and alg
-    const header = jose.decodeProtectedHeader(bootstrap.access_token);
-    expect(header.alg).toBe("EdDSA");
-    expect(header.kid).toBe(key.kid);
-    expect(header.typ).toBe("JWT");
-
-    // 6. Verify a tampered token fails verification
-    const tampered = bootstrap.access_token.slice(0, -4) + "XXXX";
-    await expect(
-      jose.jwtVerify(tampered, publicKey),
-    ).rejects.toThrow();
-  });
-});

package/tests/pkce.test.ts

@@ -1,210 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import {
-  generateCodeVerifier,
-  generateCodeChallenge,
-  buildAuthorizationUrl,
-  startLogin,
-} from "../src/pkce.js";
-import { HearthApiClient } from "../src/client.js";
-
-// RFC 7636 Appendix B test vector.
-const RFC_VERIFIER = "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk";
-const RFC_CHALLENGE = "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM";
-
-const BASE64URL_RE = /^[A-Za-z0-9\-_]+$/;
-
-// ---------------------------------------------------------------------------
-// generateCodeVerifier
-// ---------------------------------------------------------------------------
-
-describe("generateCodeVerifier", () => {
-  it("returns a 43-character base64url string (32 bytes of entropy)", () => {
-    const verifier = generateCodeVerifier();
-    expect(verifier).toHaveLength(43);
-    expect(verifier).toMatch(BASE64URL_RE);
-  });
-
-  it("contains no padding characters", () => {
-    const verifier = generateCodeVerifier();
-    expect(verifier).not.toContain("=");
-    expect(verifier).not.toContain("+");
-    expect(verifier).not.toContain("/");
-  });
-
-  it("produces unique values (entropy check)", () => {
-    const values = new Set(Array.from({ length: 20 }, () => generateCodeVerifier()));
-    expect(values.size).toBe(20);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// generateCodeChallenge
-// ---------------------------------------------------------------------------
-
-describe("generateCodeChallenge", () => {
-  it("derives the correct S256 challenge from the RFC 7636 Appendix B vector", async () => {
-    const challenge = await generateCodeChallenge(RFC_VERIFIER);
-    expect(challenge).toBe(RFC_CHALLENGE);
-  });
-
-  it("produces a 43-character base64url string (SHA-256 = 32 bytes)", async () => {
-    const challenge = await generateCodeChallenge(generateCodeVerifier());
-    expect(challenge).toHaveLength(43);
-    expect(challenge).toMatch(BASE64URL_RE);
-  });
-
-  it("produces distinct challenges for distinct verifiers", async () => {
-    const a = await generateCodeChallenge("verifier-a");
-    const b = await generateCodeChallenge("verifier-b");
-    expect(a).not.toBe(b);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// buildAuthorizationUrl
-// ---------------------------------------------------------------------------
-
-describe("buildAuthorizationUrl", () => {
-  const BASE_OPTS = {
-    authorizationEndpoint: "https://auth.example.com/oauth/authorize",
-    clientId: "my-client",
-    redirectUri: "https://app.example.com/callback",
-    codeChallenge: RFC_CHALLENGE,
-  };
-
-  it("includes all required PKCE and OIDC parameters", () => {
-    const { url } = buildAuthorizationUrl(BASE_OPTS);
-    const p = new URL(url).searchParams;
-    expect(p.get("response_type")).toBe("code");
-    expect(p.get("client_id")).toBe("my-client");
-    expect(p.get("redirect_uri")).toBe("https://app.example.com/callback");
-    expect(p.get("code_challenge")).toBe(RFC_CHALLENGE);
-    expect(p.get("code_challenge_method")).toBe("S256");
-  });
-
-  it("defaults scope to 'openid profile email' when omitted", () => {
-    const { url } = buildAuthorizationUrl(BASE_OPTS);
-    expect(new URL(url).searchParams.get("scope")).toBe("openid profile email");
-  });
-
-  it("uses the caller-supplied scope", () => {
-    const { url } = buildAuthorizationUrl({ ...BASE_OPTS, scope: "openid offline_access" });
-    expect(new URL(url).searchParams.get("scope")).toBe("openid offline_access");
-  });
-
-  it("auto-generates a non-empty state when not provided", () => {
-    const { url, state } = buildAuthorizationUrl(BASE_OPTS);
-    expect(state).toBeTruthy();
-    expect(state).toMatch(BASE64URL_RE);
-    expect(new URL(url).searchParams.get("state")).toBe(state);
-  });
-
-  it("auto-generates unique states on successive calls", () => {
-    const states = new Set(
-      Array.from({ length: 10 }, () => buildAuthorizationUrl(BASE_OPTS).state),
-    );
-    expect(states.size).toBe(10);
-  });
-
-  it("echoes back a provided state value", () => {
-    const { url, state } = buildAuthorizationUrl({ ...BASE_OPTS, state: "csrf-token-xyz" });
-    expect(state).toBe("csrf-token-xyz");
-    expect(new URL(url).searchParams.get("state")).toBe("csrf-token-xyz");
-  });
-
-  it("uses the authorization endpoint as the URL base", () => {
-    const { url } = buildAuthorizationUrl(BASE_OPTS);
-    const parsed = new URL(url);
-    expect(`${parsed.origin}${parsed.pathname}`).toBe(
-      "https://auth.example.com/oauth/authorize",
-    );
-  });
-});
-
-// ---------------------------------------------------------------------------
-// startLogin — integration (mocked discovery doc)
-// ---------------------------------------------------------------------------
-
-describe("startLogin", () => {
-  const DISCOVERY_DOC = {
-    issuer: "https://auth.example.com",
-    authorization_endpoint: "https://auth.example.com/oauth/authorize",
-    jwks_uri: "https://auth.example.com/jwks",
-    token_endpoint: "https://auth.example.com/token",
-  };
-
-  function mockFetch(body: unknown, status = 200): void {
-    vi.mocked(fetch).mockResolvedValueOnce(
-      new Response(JSON.stringify(body), {
-        status,
-        headers: { "Content-Type": "application/json" },
-      }),
-    );
-  }
-
-  beforeEach(() => vi.stubGlobal("fetch", vi.fn()));
-  afterEach(() => vi.unstubAllGlobals());
-
-  it("returns a valid redirect URL with all required PKCE parameters", async () => {
-    mockFetch(DISCOVERY_DOC);
-    const client = new HearthApiClient({
-      baseUrl: "https://auth.example.com",
-      realmId: "realm_1",
-    });
-    const result = await startLogin(client, {
-      clientId: "my-spa",
-      redirectUri: "https://app.example.com/callback",
-    });
-
-    const p = new URL(result.url).searchParams;
-    expect(new URL(result.url).origin + new URL(result.url).pathname).toBe(
-      "https://auth.example.com/oauth/authorize",
-    );
-    expect(p.get("response_type")).toBe("code");
-    expect(p.get("client_id")).toBe("my-spa");
-    expect(p.get("redirect_uri")).toBe("https://app.example.com/callback");
-    expect(p.get("code_challenge_method")).toBe("S256");
-    expect(p.get("code_challenge")).toBeTruthy();
-    expect(p.get("state")).toBe(result.state);
-  });
-
-  it("returns a 43-char codeVerifier the caller can store for token exchange", async () => {
-    mockFetch(DISCOVERY_DOC);
-    const client = new HearthApiClient({
-      baseUrl: "https://auth.example.com",
-      realmId: "realm_1",
-    });
-    const result = await startLogin(client, {
-      clientId: "my-spa",
-      redirectUri: "https://app.example.com/callback",
-    });
-    expect(result.codeVerifier).toHaveLength(43);
-    expect(result.codeVerifier).toMatch(BASE64URL_RE);
-  });
-
-  it("propagates a caller-supplied state to the URL", async () => {
-    mockFetch(DISCOVERY_DOC);
-    const client = new HearthApiClient({
-      baseUrl: "https://auth.example.com",
-      realmId: "realm_1",
-    });
-    const result = await startLogin(client, {
-      clientId: "my-spa",
-      redirectUri: "https://app.example.com/callback",
-      state: "custom-csrf-state",
-    });
-    expect(result.state).toBe("custom-csrf-state");
-    expect(new URL(result.url).searchParams.get("state")).toBe("custom-csrf-state");
-  });
-
-  it("throws when authorization_endpoint is absent from the discovery doc", async () => {
-    mockFetch({ issuer: "https://auth.example.com", jwks_uri: "https://auth.example.com/jwks" });
-    const client = new HearthApiClient({
-      baseUrl: "https://auth.example.com",
-      realmId: "realm_1",
-    });
-    await expect(
-      startLogin(client, { clientId: "spa", redirectUri: "https://app.example.com/cb" }),
-    ).rejects.toThrow("authorization_endpoint not found");
-  });
-});

package/tests/react-useHasPermission.test.tsx

@@ -1,92 +0,0 @@
-// @vitest-environment jsdom
-import { afterEach, describe, expect, it } from "vitest";
-import { cleanup, render, screen } from "@testing-library/react";
-import * as React from "react";
-import { createHearth } from "../src/hearth.js";
-import {
-  HearthProvider,
-  useHasPermission,
-  useHasRole,
-  useInGroup,
-  useInOrg,
-} from "../src/react.js";
-
-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}`;
-}
-
-function Probe(): React.ReactElement {
-  const canEdit = useHasPermission("docs.edit");
-  const isAdmin = useHasRole("admin");
-  const inEng = useInGroup("engineering");
-  const inOrg42 = useInOrg("org_42");
-  return (
-    <div>
-      <span data-testid="perm">{String(canEdit)}</span>
-      <span data-testid="role">{String(isAdmin)}</span>
-      <span data-testid="group">{String(inEng)}</span>
-      <span data-testid="org">{String(inOrg42)}</span>
-    </div>
-  );
-}
-
-describe("react hooks", () => {
-  afterEach(() => {
-    cleanup();
-  });
-
-  it("reads RBAC claims from the provider client", () => {
-    const token = forgeJwt({
-      permissions: ["docs.edit"],
-      roles: ["admin"],
-      groups: ["engineering"],
-      oid: "org_42",
-    });
-    const hearth = createHearth({
-      baseUrl: "http://localhost",
-      realmId: "r1",
-      getToken: () => token,
-    });
-    render(
-      <HearthProvider client={hearth}>
-        <Probe />
-      </HearthProvider>,
-    );
-    expect(screen.getByTestId("perm").textContent).toBe("true");
-    expect(screen.getByTestId("role").textContent).toBe("true");
-    expect(screen.getByTestId("group").textContent).toBe("true");
-    expect(screen.getByTestId("org").textContent).toBe("true");
-  });
-
-  it("returns false when the JWT lacks the requested claims", () => {
-    const token = forgeJwt({ sub: "user_1" });
-    const hearth = createHearth({
-      baseUrl: "http://localhost",
-      realmId: "r1",
-      getToken: () => token,
-    });
-    render(
-      <HearthProvider client={hearth}>
-        <Probe />
-      </HearthProvider>,
-    );
-    expect(screen.getByTestId("perm").textContent).toBe("false");
-    expect(screen.getByTestId("role").textContent).toBe("false");
-    expect(screen.getByTestId("group").textContent).toBe("false");
-    expect(screen.getByTestId("org").textContent).toBe("false");
-  });
-
-  it("returns false when no HearthProvider is mounted", () => {
-    render(<Probe />);
-    expect(screen.getByTestId("perm").textContent).toBe("false");
-    expect(screen.getByTestId("role").textContent).toBe("false");
-    expect(screen.getByTestId("group").textContent).toBe("false");
-    expect(screen.getByTestId("org").textContent).toBe("false");
-  });
-});

package/tests/required-action.test.ts

@@ -1,276 +0,0 @@
-/**
- * Unit tests for RequiredActionError (spec §5) and handleCallback
- * required-action detection (spec §7).
- * Tests are written before implementation (TDD).
- */
-
-import { describe, it, expect, vi, afterEach } from "vitest";
-import { RequiredActionError } from "../src/errors.js";
-import { HearthApiClient } from "../src/client.js";
-
-// ── RequiredActionError ────────────────────────────────────────────────────
-
-describe("RequiredActionError", () => {
-  it("is a subclass of Error", () => {
-    const err = new RequiredActionError(["VERIFY_EMAIL"]);
-    expect(err).toBeInstanceOf(Error);
-  });
-
-  it("exposes requiredActions array", () => {
-    const err = new RequiredActionError(["VERIFY_EMAIL", "UPDATE_PASSWORD"]);
-    expect(err.requiredActions).toEqual(["VERIFY_EMAIL", "UPDATE_PASSWORD"]);
-  });
-
-  it("has a human-readable message", () => {
-    const err = new RequiredActionError(["VERIFY_EMAIL"]);
-    expect(err.message).toBeTruthy();
-    expect(typeof err.message).toBe("string");
-  });
-
-  it("has name 'RequiredActionError'", () => {
-    const err = new RequiredActionError(["VERIFY_EMAIL"]);
-    expect(err.name).toBe("RequiredActionError");
-  });
-
-  it("redirectUri is undefined when not provided", () => {
-    const err = new RequiredActionError(["VERIFY_EMAIL"]);
-    expect(err.redirectUri).toBeUndefined();
-  });
-
-  it("accepts an optional redirectUri", () => {
-    const err = new RequiredActionError(
-      ["VERIFY_EMAIL"],
-      "https://auth.example.com/ui/required-actions/verify-email",
-    );
-    expect(err.redirectUri).toBe(
-      "https://auth.example.com/ui/required-actions/verify-email",
-    );
-  });
-
-  it("works with empty required actions list", () => {
-    const err = new RequiredActionError([]);
-    expect(err.requiredActions).toEqual([]);
-  });
-});
-
-// ── handleCallback() ───────────────────────────────────────────────────────
-
-/** Build a minimal JWT with the given payload. */
-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}`;
-}
-
-function makeClient(): HearthApiClient {
-  return new HearthApiClient({
-    baseUrl: "https://auth.example.com",
-    realmId: "realm_test",
-  });
-}
-
-describe("HearthApiClient.handleCallback()", () => {
-  afterEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  it("returns token response when token_type is 'access'", async () => {
-    const accessJwt = forgeJwt({
-      sub: "user_1",
-      token_type: "access",
-      exp: Math.floor(Date.now() / 1000) + 3600,
-    });
-    const mockResponse = {
-      access_token: accessJwt,
-      id_token: "id_token_value",
-      token_type: "Bearer",
-      expires_in: 3600,
-      refresh_token: "refresh_token_value",
-    };
-    vi.spyOn(globalThis, "fetch").mockResolvedValue(
-      new Response(JSON.stringify(mockResponse), { status: 200 }),
-    );
-
-    const client = makeClient();
-    const result = await client.handleCallback({
-      callbackUrl: "https://app.example.com/callback?code=abc123&state=xyz",
-      clientId: "client_1",
-      redirectUri: "https://app.example.com/callback",
-    });
-    expect(result.access_token).toBe(accessJwt);
-    expect(result.token_type).toBe("Bearer");
-  });
-
-  it("throws RequiredActionError when JWT token_type is 'required_action'", async () => {
-    const requiredActionJwt = forgeJwt({
-      sub: "user_1",
-      token_type: "required_action",
-      required_actions: ["VERIFY_EMAIL", "UPDATE_PASSWORD"],
-      exp: Math.floor(Date.now() / 1000) + 300,
-    });
-    const mockResponse = {
-      access_token: requiredActionJwt,
-      id_token: "id_token_value",
-      token_type: "Bearer",
-      expires_in: 300,
-      refresh_token: "",
-    };
-    vi.spyOn(globalThis, "fetch").mockResolvedValue(
-      new Response(JSON.stringify(mockResponse), { status: 200 }),
-    );
-
-    const client = makeClient();
-    await expect(
-      client.handleCallback({
-        callbackUrl: "https://app.example.com/callback?code=abc123",
-        clientId: "client_1",
-        redirectUri: "https://app.example.com/callback",
-      }),
-    ).rejects.toBeInstanceOf(RequiredActionError);
-  });
-
-  it("populates requiredActions from JWT required_actions claim", async () => {
-    const requiredActionJwt = forgeJwt({
-      sub: "user_1",
-      token_type: "required_action",
-      required_actions: ["VERIFY_EMAIL", "UPDATE_PASSWORD"],
-      exp: Math.floor(Date.now() / 1000) + 300,
-    });
-    vi.spyOn(globalThis, "fetch").mockResolvedValue(
-      new Response(
-        JSON.stringify({
-          access_token: requiredActionJwt,
-          id_token: "",
-          token_type: "Bearer",
-          expires_in: 300,
-          refresh_token: "",
-        }),
-        { status: 200 },
-      ),
-    );
-
-    const client = makeClient();
-    try {
-      await client.handleCallback({
-        callbackUrl: "https://app.example.com/callback?code=abc123",
-        clientId: "client_1",
-        redirectUri: "https://app.example.com/callback",
-      });
-      expect.fail("should have thrown");
-    } catch (err) {
-      expect(err).toBeInstanceOf(RequiredActionError);
-      expect((err as RequiredActionError).requiredActions).toEqual([
-        "VERIFY_EMAIL",
-        "UPDATE_PASSWORD",
-      ]);
-    }
-  });
-
-  it("throws RequiredActionError with redirectUri from required_action_redirect_uri param", async () => {
-    const normalJwt = forgeJwt({
-      sub: "user_1",
-      token_type: "access",
-      exp: Math.floor(Date.now() / 1000) + 3600,
-    });
-    vi.spyOn(globalThis, "fetch").mockResolvedValue(
-      new Response(
-        JSON.stringify({
-          access_token: normalJwt,
-          id_token: "",
-          token_type: "Bearer",
-          expires_in: 3600,
-          refresh_token: "rt",
-        }),
-        { status: 200 },
-      ),
-    );
-
-    const client = makeClient();
-    const redirectUri = "https://auth.example.com/ui/required-actions/verify-email";
-    const callbackUrl = `https://app.example.com/callback?code=abc123&required_action_redirect_uri=${encodeURIComponent(redirectUri)}`;
-
-    try {
-      await client.handleCallback({
-        callbackUrl,
-        clientId: "client_1",
-        redirectUri: "https://app.example.com/callback",
-      });
-      expect.fail("should have thrown");
-    } catch (err) {
-      expect(err).toBeInstanceOf(RequiredActionError);
-      expect((err as RequiredActionError).redirectUri).toBe(redirectUri);
-    }
-  });
-
-  it("token_type=required_action sets redirectUri from JWT if required_action_redirect_uri also in URL", async () => {
-    const redirectUri = "https://auth.example.com/ui/actions";
-    const requiredActionJwt = forgeJwt({
-      sub: "user_1",
-      token_type: "required_action",
-      required_actions: ["VERIFY_EMAIL"],
-      exp: Math.floor(Date.now() / 1000) + 300,
-    });
-    vi.spyOn(globalThis, "fetch").mockResolvedValue(
-      new Response(
-        JSON.stringify({
-          access_token: requiredActionJwt,
-          id_token: "",
-          token_type: "Bearer",
-          expires_in: 300,
-          refresh_token: "",
-        }),
-        { status: 200 },
-      ),
-    );
-
-    const callbackUrl = `https://app.example.com/callback?code=abc123&required_action_redirect_uri=${encodeURIComponent(redirectUri)}`;
-    const client = makeClient();
-    try {
-      await client.handleCallback({
-        callbackUrl,
-        clientId: "client_1",
-        redirectUri: "https://app.example.com/callback",
-      });
-      expect.fail("should have thrown");
-    } catch (err) {
-      expect(err).toBeInstanceOf(RequiredActionError);
-      expect((err as RequiredActionError).requiredActions).toEqual(["VERIFY_EMAIL"]);
-      expect((err as RequiredActionError).redirectUri).toBe(redirectUri);
-    }
-  });
-
-  it("passes codeVerifier to the token exchange when provided", async () => {
-    const accessJwt = forgeJwt({ sub: "user_1", token_type: "access" });
-    const fetchSpy = vi
-      .spyOn(globalThis, "fetch")
-      .mockResolvedValue(
-        new Response(
-          JSON.stringify({
-            access_token: accessJwt,
-            id_token: "",
-            token_type: "Bearer",
-            expires_in: 3600,
-            refresh_token: "rt",
-          }),
-          { status: 200 },
-        ),
-      );
-
-    const client = makeClient();
-    await client.handleCallback({
-      callbackUrl: "https://app.example.com/callback?code=abc123",
-      clientId: "client_1",
-      redirectUri: "https://app.example.com/callback",
-      codeVerifier: "pkce_verifier_value",
-    });
-
-    const body = JSON.parse(fetchSpy.mock.calls[0][1]?.body as string);
-    expect(body.code_verifier).toBe("pkce_verifier_value");
-  });
-});