@axiom-lattice/pg-stores 5.0.3 → 5.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiom-lattice/pg-stores",
-  "version": "5.0.3",
+  "version": "5.1.0",
   "description": "PG stores implementation for Axiom Lattice framework",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -25,8 +25,8 @@
     "@langchain/core": "1.3.2",
     "pg": "^8.16.3",
     "uuid": "^9.0.1",
-    "@axiom-lattice/core": "12.1.1",
-    "@axiom-lattice/protocols": "7.1.0"
+    "@axiom-lattice/core": "12.2.0",
+    "@axiom-lattice/protocols": "7.2.0"
   },
   "devDependencies": {
     "@types/jest": "^29.5.14",

package/src/__tests__/PostgreSQLInviteLinkStore.test.ts

@@ -0,0 +1,63 @@
+import { randomUUID } from "node:crypto";
+import { Pool } from "pg";
+
+jest.mock("@axiom-lattice/core", () => ({
+  ...jest.requireActual("../../../core/src/util/encryption"),
+}));
+
+import { createInviteLinksTable } from "../migrations/invite_link_migration";
+import { PostgreSQLInviteLinkStore } from "../stores/PostgreSQLInviteLinkStore";
+
+process.env.LATTICE_ENCRYPTION_KEY ??= "test-invite-link-encryption-key";
+
+const databaseUrl = process.env.TEST_DATABASE_URL;
+const describeIfDatabase = databaseUrl ? describe : describe.skip;
+
+describeIfDatabase("PostgreSQLInviteLinkStore", () => {
+  let pool: Pool;
+  let store: PostgreSQLInviteLinkStore;
+  const marker = randomUUID();
+  beforeAll(async () => {
+    pool = new Pool({ connectionString: databaseUrl });
+    const client = await pool.connect();
+    try {
+      await createInviteLinksTable.up(client);
+    } finally {
+      client.release();
+    }
+    store = new PostgreSQLInviteLinkStore({ pool });
+  });
+  afterEach(async () => {
+    await pool.query("DELETE FROM lattice_invite_links WHERE email LIKE $1", [`${marker}%`]);
+  });
+  afterAll(async () => {
+    await pool.query("DELETE FROM lattice_invite_links WHERE email LIKE $1", [`${marker}%`]);
+    await pool.end();
+  });
+  it("persists, consumes once, and revokes", async () => {
+    const created = await store.create({
+      id: randomUUID(),
+      scope: "tenant",
+      token: "secret-token",
+      tokenHash: `${marker}-hash`,
+      email: `${marker}@example.com`,
+      tenantId: "tenant-1",
+      tenantRole: "member",
+      expiresAt: new Date("2030-01-01T00:00:00.000Z"),
+      maxUses: 1,
+    });
+    await expect(store.getByTokenHash(created.tokenHash)).resolves.toMatchObject({
+      token: "secret-token",
+      usedCount: 0,
+    });
+    await expect(
+      store.consume(created.tokenHash, new Date("2026-01-01T00:00:00.000Z")),
+    ).resolves.toMatchObject({ usedCount: 1 });
+    await expect(
+      store.consume(created.tokenHash, new Date("2026-01-01T00:00:00.000Z")),
+    ).resolves.toBeNull();
+    await expect(
+      store.revoke(created.id, new Date("2026-01-01T00:00:00.000Z")),
+    ).resolves.toMatchObject({ id: created.id });
+  });
+});

package/src/__tests__/PostgreSQLOidcIdentityClaimStore.test.ts

@@ -0,0 +1,123 @@
+import { randomUUID } from "node:crypto";
+import { Pool } from "pg";
+import {
+  OidcIdentityClaimConflictError,
+  type CreateOidcIdentityClaimInput,
+} from "@axiom-lattice/protocols";
+import { createOidcIdentityClaimsTable } from "../migrations/oidc_identity_claim_migration";
+import { addOidcIdentityClaimInviteFields } from "../migrations/oidc_identity_claim_invite_migration";
+import { PostgreSQLOidcIdentityClaimStore } from "../stores/PostgreSQLOidcIdentityClaimStore";
+
+const databaseUrl = process.env.TEST_DATABASE_URL;
+const describeIfDatabase = databaseUrl ? describe : describe.skip;
+
+const NOW = new Date("2026-01-01T00:00:00.000Z");
+
+function input(
+  overrides: Partial<CreateOidcIdentityClaimInput> = {},
+): CreateOidcIdentityClaimInput {
+  return {
+    id: randomUUID(),
+    providerId: "logto",
+    issuer: "https://idp.example.com/oidc",
+    subject: `subject-${randomUUID()}`,
+    email: "User@Example.com",
+    name: "User",
+    expiresAt: new Date("2030-01-08T00:00:00.000Z"),
+    ...overrides,
+  };
+}
+
+describeIfDatabase("PostgreSQLOidcIdentityClaimStore", () => {
+  let pool: Pool;
+  let store: PostgreSQLOidcIdentityClaimStore;
+  const marker = randomUUID();
+
+  beforeAll(async () => {
+    pool = new Pool({ connectionString: databaseUrl });
+    const client = await pool.connect();
+    try {
+      await createOidcIdentityClaimsTable.up(client);
+      await addOidcIdentityClaimInviteFields.up(client);
+    } finally {
+      client.release();
+    }
+    store = new PostgreSQLOidcIdentityClaimStore({ pool });
+  });
+
+  afterEach(async () => {
+    await pool.query(
+      `DELETE FROM lattice_oidc_identity_claims WHERE subject LIKE $1`,
+      [`${marker}%`],
+    );
+  });
+
+  afterAll(async () => {
+    await pool.query(
+      `DELETE FROM lattice_oidc_identity_claims WHERE subject LIKE $1`,
+      [`${marker}%`],
+    );
+    await pool.end();
+  });
+
+  const subject = (local: string) => `${marker}-${local}`;
+
+  it("creates, finds, updates, and approves a claim", async () => {
+    const created = await store.create(
+      input({ subject: subject("one") }),
+    );
+    expect(created).toMatchObject({
+      email: "user@example.com",
+      status: "pending",
+    });
+    await expect(
+      store.getPendingBySubject(
+        "logto",
+        "https://idp.example.com/oidc",
+        subject("one"),
+        NOW,
+      ),
+    ).resolves.toMatchObject({ id: created.id });
+
+    await expect(
+      store.updatePending(created.id, { email: "new@example.com" }, NOW),
+    ).resolves.toMatchObject({ email: "new@example.com" });
+    await expect(
+      store.approve(
+        created.id,
+        { reviewedBy: "admin-1", linkedUserId: "user-1" },
+        NOW,
+      ),
+    ).resolves.toMatchObject({
+      status: "approved",
+      linkedUserId: "user-1",
+    });
+    await expect(
+      store.updatePending(created.id, { email: "late@example.com" }, NOW),
+    ).resolves.toBeNull();
+  });
+
+  it("rejects a duplicate live pending subject and allows an expired retry", async () => {
+    const subjectId = subject("duplicate");
+    await store.create(input({ subject: subjectId }));
+    await expect(
+      store.create(input({ subject: subjectId })),
+    ).rejects.toBeInstanceOf(OidcIdentityClaimConflictError);
+
+    const expiredSubject = subject("expired");
+    await store.create(
+      input({
+        subject: expiredSubject,
+        expiresAt: new Date("2020-01-01T00:00:00.000Z"),
+      }),
+    );
+    await expect(
+      store.create(input({ subject: expiredSubject })),
+    ).resolves.toMatchObject({ status: "pending" });
+    expect(await store.list("expired")).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ subject: expiredSubject, status: "expired" }),
+      ]),
+    );
+  });
+});

package/src/__tests__/PostgreSQLOidcProviderConfigStore.test.ts

@@ -0,0 +1,233 @@
+import { randomUUID } from "node:crypto";
+import { Pool } from "pg";
+
+// The @axiom-lattice/core barrel cannot load under jest in this package (ESM-only
+// transitive deps), so mock it with the real encryption module — node:crypto only.
+jest.mock("@axiom-lattice/core", () => ({
+  ...jest.requireActual("../../../core/src/util/encryption"),
+}));
+
+import { decrypt } from "@axiom-lattice/core";
+import {
+  OidcProviderConfigConflictError,
+  type CreateOidcProviderConfigInput,
+} from "@axiom-lattice/protocols";
+import { createOidcProviderConfigsTable } from "../migrations/oidc_provider_config_migration";
+import { addOidcProviderAllowedHosts } from "../migrations/oidc_provider_allowed_hosts_migration";
+import { PostgreSQLOidcProviderConfigStore } from "../stores/PostgreSQLOidcProviderConfigStore";
+
+process.env.LATTICE_ENCRYPTION_KEY ??= "test-oidc-encryption-key";
+
+const databaseUrl = process.env.TEST_DATABASE_URL;
+const describeIfDatabase = databaseUrl ? describe : describe.skip;
+
+const input: CreateOidcProviderConfigInput = {
+  displayName: "Contoso Entra",
+  issuer: "https://login.microsoftonline.com/tenant-id/v2.0",
+  clientId: "client-id",
+  clientSecret: "super-secret",
+  scopes: "openid profile email",
+  enabled: true,
+  jitProvisioning: true,
+  autoLinkEmail: false,
+  defaultTenantId: "tenant-1",
+};
+
+describeIfDatabase("PostgreSQLOidcProviderConfigStore", () => {
+  let pool: Pool;
+  let store: PostgreSQLOidcProviderConfigStore;
+  const prefix = `oidc-${randomUUID()}`;
+
+  beforeAll(async () => {
+    pool = new Pool({ connectionString: databaseUrl });
+    const client = await pool.connect();
+    try {
+      await createOidcProviderConfigsTable.up(client);
+      await addOidcProviderAllowedHosts.up(client);
+    } finally {
+      client.release();
+    }
+    store = new PostgreSQLOidcProviderConfigStore({ pool });
+  });
+
+  afterEach(async () => {
+    await pool.query(
+      `DELETE FROM lattice_oidc_provider_configs WHERE id LIKE $1`,
+      [`${prefix}%`],
+    );
+  });
+
+  afterAll(async () => {
+    await pool.query(
+      `DELETE FROM lattice_oidc_provider_configs WHERE id LIKE $1`,
+      [`${prefix}%`],
+    );
+    await pool.end();
+  });
+
+  it("creates, reads and lists provider configs by created_at", async () => {
+    const created = await store.create(`${prefix}-a`, input);
+
+    expect(created).toMatchObject({ id: `${prefix}-a`, ...input });
+    expect(created.createdAt).toBeInstanceOf(Date);
+    expect(created.updatedAt).toBeInstanceOf(Date);
+
+    await store.create(`${prefix}-m`, { ...input, displayName: "Mike" });
+    await store.create(`${prefix}-z`, { ...input, displayName: "Zulu" });
+
+    // Make created_at order intentionally differ from both insertion and
+    // alphabetical id order.
+    const timestamps: Record<string, string> = {
+      [`${prefix}-z`]: "2020-01-01T00:00:01.000Z",
+      [`${prefix}-a`]: "2020-01-01T00:00:02.000Z",
+      [`${prefix}-m`]: "2020-01-01T00:00:03.000Z",
+    };
+    for (const [id, createdAt] of Object.entries(timestamps)) {
+      await pool.query(
+        `UPDATE lattice_oidc_provider_configs SET created_at = $1 WHERE id = $2`,
+        [createdAt, id],
+      );
+    }
+
+    const listed = (await store.list()).filter((item) => item.id.startsWith(prefix));
+    expect(listed.map((item) => item.id)).toEqual([
+      `${prefix}-z`,
+      `${prefix}-a`,
+      `${prefix}-m`,
+    ]);
+    await expect(store.get("missing")).resolves.toBeNull();
+  });
+
+  it("encrypts the client secret at rest and decrypts it on read", async () => {
+    const id = `${prefix}-enc`;
+    await store.create(id, input);
+
+    const raw = await pool.query<{ client_secret: string }>(
+      `SELECT client_secret FROM lattice_oidc_provider_configs WHERE id = $1`,
+      [id],
+    );
+    expect(raw.rows[0].client_secret).not.toBe("super-secret");
+    expect(decrypt(raw.rows[0].client_secret)).toBe("super-secret");
+
+    await expect(store.get(id)).resolves.toMatchObject({
+      clientSecret: "super-secret",
+    });
+    const listed = (await store.list()).find((item) => item.id === id);
+    expect(listed?.clientSecret).toBe("super-secret");
+  });
+
+  it("returns an empty secret for undecryptable ciphertext without crashing", async () => {
+    const id = `${prefix}-corrupt`;
+    await store.create(id, input);
+
+    const corrupt = Buffer.alloc(80, 7).toString("base64");
+    await pool.query(
+      `UPDATE lattice_oidc_provider_configs SET client_secret = $1 WHERE id = $2`,
+      [corrupt, id],
+    );
+
+    await expect(store.get(id)).resolves.toMatchObject({
+      id,
+      clientSecret: "",
+    });
+    const listed = (await store.list()).find((item) => item.id === id);
+    expect(listed?.clientSecret).toBe("");
+  });
+
+  it("updates fields, preserves secrets and rejects duplicate ids", async () => {
+    const id = `${prefix}-update`;
+    await store.create(id, input);
+
+    await expect(store.create(id, input)).rejects.toBeInstanceOf(
+      OidcProviderConfigConflictError,
+    );
+
+    const omitted = await store.update(id, {
+      displayName: "Contoso Updated",
+      enabled: false,
+      defaultTenantId: null,
+    });
+    expect(omitted).toMatchObject({
+      id,
+      displayName: "Contoso Updated",
+      enabled: false,
+      clientSecret: "super-secret",
+    });
+    expect(omitted?.defaultTenantId).toBeUndefined();
+
+    const empty = await store.update(id, { clientSecret: "" });
+    expect(empty?.clientSecret).toBe("super-secret");
+
+    const replaced = await store.update(id, {
+      clientSecret: "next-secret",
+      scopes: "openid email",
+    });
+    expect(replaced).toMatchObject({
+      clientSecret: "next-secret",
+      scopes: "openid email",
+    });
+
+    const raw = await pool.query<{ client_secret: string }>(
+      `SELECT client_secret FROM lattice_oidc_provider_configs WHERE id = $1`,
+      [id],
+    );
+    expect(raw.rows[0].client_secret).not.toBe("next-secret");
+    expect(decrypt(raw.rows[0].client_secret)).toBe("next-secret");
+
+    await expect(store.update("missing", { enabled: false })).resolves.toBeNull();
+  });
+
+  it("round-trips undefined and empty allowedPrivateHosts distinctly", async () => {
+    const undefinedId = `${prefix}-hosts-undefined`;
+    const createdUndefined = await store.create(undefinedId, input);
+    expect(createdUndefined.allowedPrivateHosts).toBeUndefined();
+    const rawUndefined = await pool.query<{
+      allowed_private_hosts: string[] | null;
+    }>(
+      `SELECT allowed_private_hosts FROM lattice_oidc_provider_configs WHERE id = $1`,
+      [undefinedId],
+    );
+    expect(rawUndefined.rows[0].allowed_private_hosts).toBeNull();
+
+    const emptyId = `${prefix}-hosts-empty`;
+    const createdEmpty = await store.create(emptyId, {
+      ...input,
+      allowedPrivateHosts: [],
+    });
+    expect(createdEmpty.allowedPrivateHosts).toEqual([]);
+    const rawEmpty = await pool.query<{
+      allowed_private_hosts: string[] | null;
+    }>(
+      `SELECT allowed_private_hosts FROM lattice_oidc_provider_configs WHERE id = $1`,
+      [emptyId],
+    );
+    expect(rawEmpty.rows[0].allowed_private_hosts).toEqual([]);
+    await expect(store.get(emptyId)).resolves.toMatchObject({
+      allowedPrivateHosts: [],
+    });
+
+    const listId = `${prefix}-hosts-list`;
+    await store.create(listId, {
+      ...input,
+      allowedPrivateHosts: ["internal-idp.example.com"],
+    });
+    await expect(store.get(listId)).resolves.toMatchObject({
+      allowedPrivateHosts: ["internal-idp.example.com"],
+    });
+
+    const cleared = await store.update(listId, { allowedPrivateHosts: [] });
+    expect(cleared?.allowedPrivateHosts).toEqual([]);
+    await expect(store.get(listId)).resolves.toMatchObject({
+      allowedPrivateHosts: [],
+    });
+  });
+
+  it("deletes provider configs", async () => {
+    const id = `${prefix}-delete`;
+    await store.create(id, input);
+
+    await expect(store.delete(id)).resolves.toBe(true);
+    await expect(store.get(id)).resolves.toBeNull();
+    await expect(store.delete(id)).resolves.toBe(false);
+  });
+});

package/src/__tests__/PostgreSQLPlatformInvitationStore.test.ts

@@ -0,0 +1,222 @@
+import { randomUUID } from "node:crypto";
+import { Pool } from "pg";
+import type { PlatformInvitation } from "@axiom-lattice/protocols";
+import { createPlatformInvitationsTable } from "../migrations/platform_invitation_migration";
+import { PostgreSQLPlatformInvitationStore } from "../stores/PostgreSQLPlatformInvitationStore";
+
+const databaseUrl = process.env.TEST_DATABASE_URL;
+const describeIfDatabase = databaseUrl ? describe : describe.skip;
+
+function invitation(
+  email: string,
+  overrides: Partial<PlatformInvitation> = {},
+): PlatformInvitation {
+  return {
+    email,
+    role: "admin",
+    invitedBy: "owner-1",
+    createdAt: new Date("2026-01-01T00:00:00.000Z"),
+    ...overrides,
+  };
+}
+
+describeIfDatabase("PostgreSQLPlatformInvitationStore", () => {
+  let pool: Pool;
+  let store: PostgreSQLPlatformInvitationStore;
+  const marker = randomUUID();
+
+  beforeAll(async () => {
+    pool = new Pool({ connectionString: databaseUrl });
+    const client = await pool.connect();
+    try {
+      await createPlatformInvitationsTable.up(client);
+    } finally {
+      client.release();
+    }
+    store = new PostgreSQLPlatformInvitationStore({ pool });
+  });
+
+  afterEach(async () => {
+    await pool.query(
+      `DELETE FROM lattice_platform_invitations WHERE email LIKE $1`,
+      [`${marker}%`],
+    );
+  });
+
+  afterAll(async () => {
+    await pool.query(
+      `DELETE FROM lattice_platform_invitations WHERE email LIKE $1`,
+      [`${marker}%`],
+    );
+    await pool.end();
+  });
+
+  const email = (local: string) => `${marker}-${local}@example.com`;
+
+  it("upserts, reads and lists invitations by normalized email", async () => {
+    const bob = email("bob");
+    const alice = email("alice");
+
+    await store.upsert(invitation(bob, { role: "auditor" }));
+    await store.upsert(invitation(alice, { role: "owner" }));
+
+    await expect(store.get(alice)).resolves.toMatchObject({
+      email: alice,
+      role: "owner",
+      invitedBy: "owner-1",
+    });
+    await expect(store.get(email("missing"))).resolves.toBeNull();
+
+    const listed = (await store.list()).filter((entry) =>
+      entry.email.includes(marker),
+    );
+    expect(listed.map((entry) => entry.email)).toEqual([alice, bob]);
+  });
+
+  it("normalizes email on writes and lookups", async () => {
+    const local = email("normalized");
+    const upper = `${marker}-NORMALIZED@Example.COM`;
+
+    await store.upsert(invitation(`  ${upper}  `));
+
+    await expect(store.get(local)).resolves.toMatchObject({
+      email: local,
+    });
+    await expect(store.get(`  ${local.toUpperCase()} `)).resolves.toMatchObject({
+      email: local,
+    });
+    const listed = (await store.list()).filter((entry) =>
+      entry.email.includes(marker),
+    );
+    expect(listed).toHaveLength(1);
+    expect(listed[0]?.email).toBe(local);
+  });
+
+  it("replaces duplicates with last-write-wins semantics", async () => {
+    const target = email("duplicate");
+    await store.upsert(invitation(target, { role: "admin" }));
+
+    const updated = await store.upsert(
+      invitation(` ${target.toUpperCase()} `, {
+        role: "owner",
+        invitedBy: "owner-2",
+        createdAt: new Date("2026-02-01T00:00:00.000Z"),
+        expiresAt: new Date("2026-03-01T00:00:00.000Z"),
+      }),
+    );
+
+    expect(updated).toMatchObject({
+      email: target,
+      role: "owner",
+      invitedBy: "owner-2",
+    });
+    const listed = (await store.list()).filter((entry) =>
+      entry.email.includes(marker),
+    );
+    expect(listed).toHaveLength(1);
+    await expect(store.get(target)).resolves.toMatchObject({
+      role: "owner",
+      invitedBy: "owner-2",
+    });
+
+    const row = await pool.query<{
+      email: string;
+      role: string;
+      invited_by: string;
+    }>(
+      `SELECT email, role, invited_by FROM lattice_platform_invitations WHERE email = $1`,
+      [target],
+    );
+    expect(row.rows[0]).toEqual({
+      email: target,
+      role: "owner",
+      invited_by: "owner-2",
+    });
+  });
+
+  it("consumes pending unexpired invitations atomically", async () => {
+    const target = email("consume");
+    const at = new Date("2026-02-01T00:00:00.000Z");
+    await store.upsert(
+      invitation(target, {
+        expiresAt: new Date("2026-03-01T00:00:00.000Z"),
+      }),
+    );
+
+    const consumed = await store.consume(` ${target.toUpperCase()} `, at);
+
+    expect(consumed).toMatchObject({
+      email: target,
+      consumedAt: at,
+    });
+    await expect(store.get(target)).resolves.toMatchObject({
+      consumedAt: at,
+    });
+  });
+
+  it("does not consume an already-consumed invitation", async () => {
+    const target = email("consumed-noop");
+    const first = new Date("2026-02-01T00:00:00.000Z");
+    const second = new Date("2026-02-02T00:00:00.000Z");
+    await store.upsert(invitation(target));
+
+    await expect(store.consume(target, first)).resolves.toMatchObject({
+      consumedAt: first,
+    });
+    await expect(store.consume(target, second)).resolves.toBeNull();
+    await expect(store.get(target)).resolves.toMatchObject({
+      consumedAt: first,
+    });
+  });
+
+  it("does not consume an expired invitation", async () => {
+    const target = email("expired");
+    const expiresAt = new Date("2026-02-01T00:00:00.000Z");
+    await store.upsert(invitation(target, { expiresAt }));
+
+    await expect(store.consume(target, expiresAt)).resolves.toBeNull();
+    await expect(
+      store.consume(target, new Date("2026-01-31T23:59:59.000Z")),
+    ).resolves.toMatchObject({
+      consumedAt: new Date("2026-01-31T23:59:59.000Z"),
+    });
+  });
+
+  it("returns null when consuming a missing invitation", async () => {
+    await expect(store.consume(email("missing"), new Date())).resolves.toBeNull();
+  });
+
+  it("deletes invitations", async () => {
+    const target = email("delete");
+    await store.upsert(invitation(target));
+
+    await expect(store.delete(` ${target.toUpperCase()} `)).resolves.toBe(true);
+    await expect(store.get(target)).resolves.toBeNull();
+    await expect(store.delete(target)).resolves.toBe(false);
+  });
+
+  it("omits optional fields when they are not provided", async () => {
+    const target = email("optional");
+    const { invitedBy: _invitedBy, ...withoutInvitedBy } = invitation(target);
+
+    await store.upsert(withoutInvitedBy);
+
+    const stored = await store.get(target);
+    expect(stored?.invitedBy).toBeUndefined();
+    expect(stored?.expiresAt).toBeUndefined();
+    expect(stored?.consumedAt).toBeUndefined();
+  });
+
+  it("round-trips timestamps", async () => {
+    const target = email("timestamps");
+    const createdAt = new Date("2026-03-04T05:06:07.000Z");
+    const expiresAt = new Date("2026-04-05T06:07:08.000Z");
+
+    await store.upsert(invitation(target, { createdAt, expiresAt }));
+
+    const stored = await store.get(target);
+    expect(stored?.createdAt).toBeInstanceOf(Date);
+    expect(stored?.createdAt.getTime()).toBe(createdAt.getTime());
+    expect(stored?.expiresAt?.getTime()).toBe(expiresAt.getTime());
+  });
+});