@axiom-lattice/pg-stores 5.0.2 → 5.1.0

package/src/stores/PostgreSQLOidcProviderConfigStore.ts

@@ -0,0 +1,222 @@
+import { safeDecrypt, encrypt } from "@axiom-lattice/core";
+import {
+  OidcProviderConfigConflictError,
+  type CreateOidcProviderConfigInput,
+  type OidcProviderConfig,
+  type OidcProviderConfigStore,
+  type UpdateOidcProviderConfigInput,
+} from "@axiom-lattice/protocols";
+import type { Pool } from "pg";
+
+const TABLE = "lattice_oidc_provider_configs";
+
+interface ProviderRow {
+  id: string;
+  display_name: string;
+  issuer: string;
+  client_id: string;
+  client_secret: string;
+  scopes: string;
+  enabled: boolean;
+  jit_provisioning: boolean;
+  auto_link_email: boolean;
+  default_tenant_id: string | null;
+  allowed_private_hosts: string[] | null;
+  created_at: Date;
+  updated_at: Date;
+}
+
+function parseAllowedPrivateHosts(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  return value.filter((entry): entry is string => typeof entry === "string");
+}
+
+function serializeAllowedPrivateHosts(
+  value: readonly string[] | undefined,
+): string | null {
+  return value === undefined ? null : JSON.stringify(value);
+}
+
+function normalizeTenantId(value: string | null | undefined): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function mapRow(row: ProviderRow): OidcProviderConfig {
+  if (
+    typeof row.id !== "string" ||
+    typeof row.display_name !== "string" ||
+    typeof row.issuer !== "string" ||
+    typeof row.client_id !== "string" ||
+    typeof row.client_secret !== "string" ||
+    typeof row.scopes !== "string" ||
+    typeof row.enabled !== "boolean" ||
+    typeof row.jit_provisioning !== "boolean" ||
+    typeof row.auto_link_email !== "boolean" ||
+    !(row.created_at instanceof Date) ||
+    !(row.updated_at instanceof Date)
+  ) {
+    throw new Error("Invalid OIDC provider config row");
+  }
+  const allowedPrivateHosts = parseAllowedPrivateHosts(
+    row.allowed_private_hosts,
+  );
+  return {
+    id: row.id,
+    displayName: row.display_name,
+    issuer: row.issuer,
+    clientId: row.client_id,
+    clientSecret: safeDecrypt(
+      row.client_secret,
+      `OIDC provider config "${row.id}" client secret`,
+    ),
+    scopes: row.scopes,
+    enabled: row.enabled,
+    jitProvisioning: row.jit_provisioning,
+    autoLinkEmail: row.auto_link_email,
+    ...(typeof row.default_tenant_id === "string"
+      ? { defaultTenantId: row.default_tenant_id }
+      : {}),
+    ...(allowedPrivateHosts !== undefined ? { allowedPrivateHosts } : {}),
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+function isUniqueViolation(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    (error as { code?: unknown }).code === "23505"
+  );
+}
+
+/**
+ * PostgreSQL implementation of {@link OidcProviderConfigStore}.
+ *
+ * Persists OIDC provider configurations in `lattice_oidc_provider_configs`,
+ * encrypting the client secret at rest and using the database clock for
+ * `updated_at` on writes.
+ */
+export class PostgreSQLOidcProviderConfigStore implements OidcProviderConfigStore {
+  private readonly pool: Pool;
+
+  constructor(options: { pool: Pool }) {
+    this.pool = options.pool;
+  }
+
+  async list(): Promise<OidcProviderConfig[]> {
+    const result = await this.pool.query<ProviderRow>(
+      `SELECT * FROM ${TABLE} ORDER BY created_at ASC, id ASC`,
+    );
+    return result.rows.map(mapRow);
+  }
+
+  async get(id: string): Promise<OidcProviderConfig | null> {
+    const result = await this.pool.query<ProviderRow>(
+      `SELECT * FROM ${TABLE} WHERE id = $1`,
+      [id],
+    );
+    return result.rows[0] ? mapRow(result.rows[0]) : null;
+  }
+
+  async create(
+    id: string,
+    input: CreateOidcProviderConfigInput,
+  ): Promise<OidcProviderConfig> {
+    const tenantId = normalizeTenantId(input.defaultTenantId);
+    try {
+      await this.pool.query(
+        `INSERT INTO ${TABLE}
+         (id, display_name, issuer, client_id, client_secret, scopes,
+          enabled, jit_provisioning, auto_link_email, default_tenant_id,
+          allowed_private_hosts)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)`,
+        [
+          id,
+          input.displayName,
+          input.issuer,
+          input.clientId,
+          encrypt(input.clientSecret),
+          input.scopes,
+          input.enabled,
+          input.jitProvisioning,
+          input.autoLinkEmail,
+          tenantId ?? null,
+          serializeAllowedPrivateHosts(input.allowedPrivateHosts),
+        ],
+      );
+    } catch (error) {
+      if (isUniqueViolation(error)) {
+        throw new OidcProviderConfigConflictError(id);
+      }
+      throw error;
+    }
+
+    const created = await this.get(id);
+    if (!created) {
+      throw new Error(`OIDC provider config "${id}" was not persisted`);
+    }
+    return created;
+  }
+
+  async update(
+    id: string,
+    updates: UpdateOidcProviderConfigInput,
+  ): Promise<OidcProviderConfig | null> {
+    const existing = await this.get(id);
+    if (!existing) return null;
+
+    const setClauses: string[] = [];
+    const values: unknown[] = [];
+    let paramIndex = 1;
+
+    const set = (column: string, value: unknown): void => {
+      setClauses.push(`${column} = $${paramIndex++}`);
+      values.push(value);
+    };
+
+    if (updates.displayName !== undefined) set("display_name", updates.displayName);
+    if (updates.issuer !== undefined) set("issuer", updates.issuer);
+    if (updates.clientId !== undefined) set("client_id", updates.clientId);
+    if (updates.clientSecret !== undefined && updates.clientSecret !== "") {
+      set("client_secret", encrypt(updates.clientSecret));
+    }
+    if (updates.scopes !== undefined) set("scopes", updates.scopes);
+    if (updates.enabled !== undefined) set("enabled", updates.enabled);
+    if (updates.jitProvisioning !== undefined) {
+      set("jit_provisioning", updates.jitProvisioning);
+    }
+    if (updates.autoLinkEmail !== undefined) {
+      set("auto_link_email", updates.autoLinkEmail);
+    }
+    if (updates.defaultTenantId !== undefined) {
+      set("default_tenant_id", normalizeTenantId(updates.defaultTenantId) ?? null);
+    }
+    if (updates.allowedPrivateHosts !== undefined) {
+      set(
+        "allowed_private_hosts",
+        serializeAllowedPrivateHosts(updates.allowedPrivateHosts),
+      );
+    }
+
+    if (setClauses.length === 0) return existing;
+
+    setClauses.push("updated_at = NOW()");
+    values.push(id);
+
+    await this.pool.query(
+      `UPDATE ${TABLE} SET ${setClauses.join(", ")} WHERE id = $${paramIndex}`,
+      values,
+    );
+
+    return this.get(id);
+  }
+
+  async delete(id: string): Promise<boolean> {
+    const result = await this.pool.query(`DELETE FROM ${TABLE} WHERE id = $1`, [id]);
+    return (result.rowCount ?? 0) > 0;
+  }
+}

package/src/stores/PostgreSQLPlatformInvitationStore.ts

@@ -0,0 +1,133 @@
+import {
+  normalizePlatformInvitationEmail,
+  type PlatformInvitation,
+  type PlatformInvitationStore,
+  type PlatformRole,
+} from "@axiom-lattice/protocols";
+import type { Pool } from "pg";
+
+const TABLE = "lattice_platform_invitations";
+const ROLES: readonly PlatformRole[] = ["owner", "admin", "auditor"];
+
+interface InvitationRow {
+  email: string;
+  role: string;
+  invited_by: string | null;
+  created_at: Date;
+  expires_at: Date | null;
+  consumed_at: Date | null;
+}
+
+function isPlatformRole(value: string): value is PlatformRole {
+  return (ROLES as readonly string[]).includes(value);
+}
+
+function mapRow(row: InvitationRow): PlatformInvitation {
+  if (
+    typeof row.email !== "string" ||
+    typeof row.role !== "string" ||
+    !isPlatformRole(row.role) ||
+    !(row.created_at instanceof Date)
+  ) {
+    throw new Error("Invalid platform invitation row");
+  }
+  return {
+    email: row.email,
+    role: row.role,
+    ...(typeof row.invited_by === "string" ? { invitedBy: row.invited_by } : {}),
+    createdAt: row.created_at,
+    ...(row.expires_at instanceof Date ? { expiresAt: row.expires_at } : {}),
+    ...(row.consumed_at instanceof Date ? { consumedAt: row.consumed_at } : {}),
+  };
+}
+
+/**
+ * PostgreSQL implementation of {@link PlatformInvitationStore}.
+ *
+ * Persists invitations in `lattice_platform_invitations`, keyed by normalized
+ * email.
+ */
+export class PostgreSQLPlatformInvitationStore
+  implements PlatformInvitationStore
+{
+  private readonly pool: Pool;
+
+  constructor(options: { pool: Pool }) {
+    this.pool = options.pool;
+  }
+
+  /** Lists every invitation ordered by normalized email. */
+  async list(): Promise<PlatformInvitation[]> {
+    const result = await this.pool.query<InvitationRow>(
+      `SELECT * FROM ${TABLE} ORDER BY email ASC`,
+    );
+    return result.rows.map(mapRow);
+  }
+
+  /** Returns the invitation for an email, or null. */
+  async get(email: string): Promise<PlatformInvitation | null> {
+    const result = await this.pool.query<InvitationRow>(
+      `SELECT * FROM ${TABLE} WHERE email = $1`,
+      [normalizePlatformInvitationEmail(email)],
+    );
+    return result.rows[0] ? mapRow(result.rows[0]) : null;
+  }
+
+  /**
+   * Inserts or replaces an invitation keyed by normalized email.
+   *
+   * The supplied invitation replaces any existing row in full (last write wins),
+   * including `expiresAt` and `consumedAt`.
+   */
+  async upsert(invitation: PlatformInvitation): Promise<PlatformInvitation> {
+    const result = await this.pool.query<InvitationRow>(
+      `INSERT INTO ${TABLE}
+         (email, role, invited_by, created_at, expires_at, consumed_at)
+       VALUES ($1, $2, $3, $4, $5, $6)
+       ON CONFLICT (email) DO UPDATE SET
+         role = EXCLUDED.role,
+         invited_by = EXCLUDED.invited_by,
+         created_at = EXCLUDED.created_at,
+         expires_at = EXCLUDED.expires_at,
+         consumed_at = EXCLUDED.consumed_at
+       RETURNING *`,
+      [
+        normalizePlatformInvitationEmail(invitation.email),
+        invitation.role,
+        invitation.invitedBy ?? null,
+        invitation.createdAt,
+        invitation.expiresAt ?? null,
+        invitation.consumedAt ?? null,
+      ],
+    );
+    return mapRow(result.rows[0]);
+  }
+
+  /** Deletes an invitation. Returns whether a row was removed. */
+  async delete(email: string): Promise<boolean> {
+    const result = await this.pool.query(
+      `DELETE FROM ${TABLE} WHERE email = $1`,
+      [normalizePlatformInvitationEmail(email)],
+    );
+    return (result.rowCount ?? 0) > 0;
+  }
+
+  /**
+   * Atomically consumes a pending, unexpired invitation.
+   *
+   * Returns the consumed invitation, or null when the row is missing, already
+   * consumed, or expired.
+   */
+  async consume(email: string, at: Date): Promise<PlatformInvitation | null> {
+    const result = await this.pool.query<InvitationRow>(
+      `UPDATE ${TABLE}
+       SET consumed_at = $1
+       WHERE email = $2
+         AND consumed_at IS NULL
+         AND (expires_at IS NULL OR expires_at > $1)
+       RETURNING *`,
+      [at, normalizePlatformInvitationEmail(email)],
+    );
+    return result.rows[0] ? mapRow(result.rows[0]) : null;
+  }
+}

package/src/stores/PostgreSQLPlatformMemberStore.ts

@@ -0,0 +1,105 @@
+import type {
+  PlatformMember,
+  PlatformMemberStore,
+  PlatformRole,
+} from "@axiom-lattice/protocols";
+import type { Pool } from "pg";
+
+const TABLE = "lattice_platform_members";
+const ROLES: readonly PlatformRole[] = ["owner", "admin", "auditor"];
+
+interface MemberRow {
+  user_id: string;
+  role: string;
+  granted_by: string | null;
+  granted_at: Date;
+  updated_at: Date;
+}
+
+function isPlatformRole(value: string): value is PlatformRole {
+  return (ROLES as readonly string[]).includes(value);
+}
+
+function mapRow(row: MemberRow): PlatformMember {
+  if (
+    typeof row.user_id !== "string" ||
+    typeof row.role !== "string" ||
+    !isPlatformRole(row.role) ||
+    !(row.granted_at instanceof Date) ||
+    !(row.updated_at instanceof Date)
+  ) {
+    throw new Error("Invalid platform member row");
+  }
+  return {
+    userId: row.user_id,
+    role: row.role,
+    ...(typeof row.granted_by === "string" ? { grantedBy: row.granted_by } : {}),
+    grantedAt: row.granted_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+/**
+ * PostgreSQL implementation of {@link PlatformMemberStore}.
+ *
+ * Persists platform grants in `lattice_platform_members`, keyed by user id.
+ */
+export class PostgreSQLPlatformMemberStore implements PlatformMemberStore {
+  private readonly pool: Pool;
+
+  constructor(options: { pool: Pool }) {
+    this.pool = options.pool;
+  }
+
+  /** Lists every platform member ordered by user id. */
+  async list(): Promise<PlatformMember[]> {
+    const result = await this.pool.query<MemberRow>(
+      `SELECT * FROM ${TABLE} ORDER BY user_id ASC`,
+    );
+    return result.rows.map(mapRow);
+  }
+
+  /** Returns the platform member for a user, or null. */
+  async get(userId: string): Promise<PlatformMember | null> {
+    const result = await this.pool.query<MemberRow>(
+      `SELECT * FROM ${TABLE} WHERE user_id = $1`,
+      [userId],
+    );
+    return result.rows[0] ? mapRow(result.rows[0]) : null;
+  }
+
+  /**
+   * Inserts or replaces a member keyed by user id.
+   *
+   * The supplied grant replaces any existing row in full (last write wins),
+   * including `grantedAt` and `updatedAt`.
+   */
+  async upsert(member: PlatformMember): Promise<PlatformMember> {
+    const result = await this.pool.query<MemberRow>(
+      `INSERT INTO ${TABLE} (user_id, role, granted_by, granted_at, updated_at)
+       VALUES ($1, $2, $3, $4, $5)
+       ON CONFLICT (user_id) DO UPDATE SET
+         role = EXCLUDED.role,
+         granted_by = EXCLUDED.granted_by,
+         granted_at = EXCLUDED.granted_at,
+         updated_at = EXCLUDED.updated_at
+       RETURNING *`,
+      [
+        member.userId,
+        member.role,
+        member.grantedBy ?? null,
+        member.grantedAt,
+        member.updatedAt,
+      ],
+    );
+    return mapRow(result.rows[0]);
+  }
+
+  /** Deletes a member. Returns whether a row was removed. */
+  async delete(userId: string): Promise<boolean> {
+    const result = await this.pool.query(`DELETE FROM ${TABLE} WHERE user_id = $1`, [
+      userId,
+    ]);
+    return (result.rowCount ?? 0) > 0;
+  }
+}

package/src/stores/PostgreSQLPlatformSettingsStore.ts

@@ -0,0 +1,98 @@
+import {
+  PlatformSettingsVersionConflictError,
+  type PlatformSettingsDocument,
+  type PlatformSettingsRecord,
+  type PlatformSettingsStore,
+} from "@axiom-lattice/protocols";
+import type { Pool } from "pg";
+
+const TABLE = "lattice_platform_settings";
+const SETTINGS_ID = "default";
+const COLUMNS = "id, document, version, updated_by, updated_at";
+
+function normalizeUpdatedBy(updatedBy?: string): string | null {
+  const trimmed = updatedBy?.trim();
+  return trimmed ? trimmed : null;
+}
+
+interface SettingsRow {
+  id: string;
+  document: PlatformSettingsDocument;
+  version: number;
+  updated_by: string | null;
+  updated_at: Date;
+}
+
+function mapRow(row: SettingsRow): PlatformSettingsRecord {
+  return {
+    ...row.document,
+    version: Number(row.version),
+    ...(row.updated_by !== null ? { updatedBy: row.updated_by } : {}),
+    updatedAt: row.updated_at,
+  };
+}
+
+/** PostgreSQL implementation of {@link PlatformSettingsStore}. */
+export class PostgreSQLPlatformSettingsStore implements PlatformSettingsStore {
+  constructor(private readonly options: { pool: Pool }) {}
+
+  private get pool(): Pool {
+    return this.options.pool;
+  }
+
+  async get(): Promise<PlatformSettingsRecord | null> {
+    const result = await this.pool.query<SettingsRow>(
+      `SELECT ${COLUMNS} FROM ${TABLE} WHERE id = $1`,
+      [SETTINGS_ID],
+    );
+    return result.rows[0] ? mapRow(result.rows[0]) : null;
+  }
+
+  async save(
+    document: PlatformSettingsDocument,
+    expectedVersion: number,
+    updatedBy?: string,
+  ): Promise<PlatformSettingsRecord> {
+    const version = expectedVersion + 1;
+    const result =
+      expectedVersion === 0
+        ? await this.pool.query<SettingsRow>(
+            `INSERT INTO ${TABLE} (id, document, version, updated_by, updated_at)
+             VALUES ($1, $2::jsonb, $3, $4, NOW())
+             ON CONFLICT (id) DO NOTHING
+             RETURNING ${COLUMNS}`,
+            [
+              SETTINGS_ID,
+              JSON.stringify(document),
+              version,
+              normalizeUpdatedBy(updatedBy),
+            ],
+          )
+        : await this.pool.query<SettingsRow>(
+            `UPDATE ${TABLE}
+             SET document = $2::jsonb, version = $3, updated_by = $4, updated_at = NOW()
+             WHERE id = $1 AND version = $5
+             RETURNING ${COLUMNS}`,
+            [
+              SETTINGS_ID,
+              JSON.stringify(document),
+              version,
+              normalizeUpdatedBy(updatedBy),
+              expectedVersion,
+            ],
+          );
+
+    if (result.rows[0]) {
+      return mapRow(result.rows[0]);
+    }
+
+    const actual = await this.pool.query<{ version: number }>(
+      `SELECT version FROM ${TABLE} WHERE id = $1`,
+      [SETTINGS_ID],
+    );
+    throw new PlatformSettingsVersionConflictError(
+      expectedVersion,
+      actual.rows[0] ? Number(actual.rows[0].version) : 0,
+    );
+  }
+}

package/src/stores/PostgreSQLUserExternalIdentityStore.ts

@@ -0,0 +1,134 @@
+import {
+  ExternalIdentityConflictError,
+  ExternalIdentityPersistError,
+  type UserExternalIdentity,
+  type UserExternalIdentityStore,
+} from "@axiom-lattice/protocols";
+import type { Pool } from "pg";
+
+/**
+ * Raised when a row read from `lattice_user_identities` does not match the
+ * expected column types.
+ */
+export class InvalidUserExternalIdentityRowError extends Error {
+  readonly code = "INVALID_USER_EXTERNAL_IDENTITY_ROW";
+
+  constructor() {
+    super("Invalid user external identity row");
+    this.name = "InvalidUserExternalIdentityRowError";
+  }
+}
+
+interface Row {
+  user_id: unknown;
+  provider_id: unknown;
+  issuer: unknown;
+  subject: unknown;
+  email: unknown;
+  linked_at: unknown;
+}
+
+const columns = "user_id, provider_id, issuer, subject, email, linked_at";
+
+function mapRow(row: Row): UserExternalIdentity {
+  if (
+    typeof row.user_id !== "string" ||
+    typeof row.provider_id !== "string" ||
+    typeof row.issuer !== "string" ||
+    typeof row.subject !== "string" ||
+    !(row.linked_at instanceof Date) ||
+    Number.isNaN(row.linked_at.getTime())
+  ) {
+    throw new InvalidUserExternalIdentityRowError();
+  }
+  return {
+    userId: row.user_id,
+    providerId: row.provider_id,
+    issuer: row.issuer,
+    subject: row.subject,
+    ...(typeof row.email === "string" ? { email: row.email } : {}),
+    linkedAt: row.linked_at,
+  };
+}
+
+export class PostgreSQLUserExternalIdentityStore implements UserExternalIdentityStore {
+  private readonly pool: Pool;
+
+  constructor(options: { pool: Pool }) {
+    this.pool = options.pool;
+  }
+
+  async getByProviderSubject(
+    providerId: string,
+    issuer: string,
+    subject: string,
+  ): Promise<UserExternalIdentity | null> {
+    const result = await this.pool.query<Row>(
+      `SELECT ${columns} FROM lattice_user_identities
+       WHERE provider_id = $1 AND issuer = $2 AND subject = $3`,
+      [providerId, issuer, subject],
+    );
+    return result.rows[0] ? mapRow(result.rows[0]) : null;
+  }
+
+  async listByUser(userId: string): Promise<UserExternalIdentity[]> {
+    const result = await this.pool.query<Row>(
+      `SELECT ${columns} FROM lattice_user_identities WHERE user_id = $1 ORDER BY linked_at ASC`,
+      [userId],
+    );
+    return result.rows.map(mapRow);
+  }
+
+  async link(identity: UserExternalIdentity): Promise<void> {
+    const inserted = await this.pool.query<Row>(
+      `INSERT INTO lattice_user_identities (${columns})
+       VALUES ($1, $2, $3, $4, $5, $6)
+       ON CONFLICT (provider_id, issuer, subject) DO NOTHING
+       RETURNING ${columns}`,
+      [
+        identity.userId,
+        identity.providerId,
+        identity.issuer,
+        identity.subject,
+        identity.email ?? null,
+        identity.linkedAt,
+      ],
+    );
+    if (inserted.rows[0]) return;
+
+    const existing = await this.getByProviderSubject(
+      identity.providerId,
+      identity.issuer,
+      identity.subject,
+    );
+    if (!existing) {
+      throw new ExternalIdentityPersistError(
+        identity.providerId,
+        identity.issuer,
+        identity.subject,
+      );
+    }
+    if (existing.userId !== identity.userId) {
+      throw new ExternalIdentityConflictError(
+        identity.providerId,
+        identity.issuer,
+        identity.subject,
+      );
+    }
+    if (identity.email !== undefined && identity.email !== existing.email) {
+      await this.pool.query(
+        `UPDATE lattice_user_identities SET email = $1
+         WHERE provider_id = $2 AND issuer = $3 AND subject = $4`,
+        [identity.email, identity.providerId, identity.issuer, identity.subject],
+      );
+    }
+  }
+
+  async unlink(providerId: string, issuer: string, subject: string): Promise<void> {
+    await this.pool.query(
+      `DELETE FROM lattice_user_identities
+       WHERE provider_id = $1 AND issuer = $2 AND subject = $3`,
+      [providerId, issuer, subject],
+    );
+  }
+}

package/src/stores/PostgreSQLUserStore.ts

@@ -119,9 +119,10 @@ export class PostgreSQLUserStore implements UserStore {
       `
         SELECT id, email, name, status, metadata, created_at, updated_at
         FROM lattice_users
-        WHERE email = $1
+        WHERE lower(email) = lower($1)
+        LIMIT 1
       `,
-      [email]
+      [email.trim()]
     );
 
     if (result.rows.length === 0) return null;