@tempoxyz/id 0.0.0-stage → 0.0.0

package/src/internal/Realm.ts

@@ -0,0 +1,768 @@
+/**
+ * Realms: the sets of Tempo Accounts that apps reach. The `realms` table holds each realm, and its
+ * owner configurations live in their own tables: `realm_passkeys` for its passkey relying party,
+ * `realm_privy` for its Privy app, and `realm_secp256k1` for the secp256k1 owners that Tempo ID
+ * holds. The `app_realms` table maps each OAuth app to its realms, in order. An app without rows
+ * reaches the `default` realm.
+ * @module
+ */
+import type { PgDatabase, PgQueryResultHKT } from 'drizzle-orm/pg-core'
+import { symmetricDecrypt, symmetricEncrypt } from 'better-auth/crypto'
+import { and, asc, eq, inArray, or } from 'drizzle-orm'
+import * as Tldts from 'tldts'
+import { z } from 'zod'
+import * as Schema from '../app/db/schema.js'
+import type * as Privy from './Privy.js'
+
+/** An app names the realm, so the realm cannot be removed. */
+export class InUseError extends Error {
+  override readonly name = 'Realm.InUseError'
+
+  constructor(options: { id: string }) {
+    super(
+      `Realm ${options.id} is in use. Remove it from the realms of each app first.`,
+    )
+  }
+}
+
+/** A realm ID, a name, a Privy app, or a list of realms is not valid. */
+export class InvalidError extends Error {
+  override readonly name = 'Realm.InvalidError'
+}
+
+/** No OAuth app has the client ID. */
+export class NotFoundAppError extends Error {
+  override readonly name = 'Realm.NotFoundAppError'
+
+  constructor(options: { clientId: string }) {
+    super(`Unknown app ${options.clientId}. Name a registered OAuth app.`)
+  }
+}
+
+/** No realm has the ID. */
+export class NotFoundError extends Error {
+  override readonly name = 'Realm.NotFoundError'
+
+  constructor(options: { id: string }) {
+    super(`Unknown realm ${options.id}. Add it first.`)
+  }
+}
+
+/** A realm with the ID exists. */
+export class TakenError extends Error {
+  override readonly name = 'Realm.TakenError'
+
+  constructor(options: { id: string }) {
+    super(`Realm ${options.id} exists. Choose another ID.`)
+  }
+}
+
+/** Another realm holds the passkey relying party. A passkey belongs to exactly one relying party. */
+export class TakenPasskeysError extends Error {
+  override readonly name = 'Realm.TakenPasskeysError'
+
+  constructor(options: { rpId: string }) {
+    super(
+      `Relying party ${options.rpId} belongs to another realm. Give each realm its own relying party.`,
+    )
+  }
+}
+
+/** Another realm holds the Privy app. Realms that shared one would list the same accounts. */
+export class TakenPrivyAppError extends Error {
+  override readonly name = 'Realm.TakenPrivyAppError'
+
+  constructor(options: { appId: string }) {
+    super(
+      `Privy app ${options.appId} belongs to another realm. Give each realm its own Privy app.`,
+    )
+  }
+}
+
+/** A database with Tempo ID's tables, through any Postgres driver. */
+export type Database = PgDatabase<PgQueryResultHKT, typeof Schema>
+
+/** One set of Tempo Accounts, which only the apps that name it reach. */
+export type Realm = {
+  /** The realm ID, such as `default` or `tempo-cash`. */
+  id: string
+  /** The display name, which labels the realm's accounts, such as `Tempo Cash`. */
+  name: string
+  /** The passkey relying party whose passkeys own accounts in the realm. `undefined` when the realm has none. */
+  passkeys:
+    | {
+        /** The relying party ID, a registrable domain such as `tempo.xyz`. */
+        rpId: string
+      }
+    | undefined
+  /** The Privy app that holds the realm's Privy owners. `undefined` when the realm has none. */
+  privy:
+    | {
+        /** The Privy app ID. */
+        appId: string
+      }
+    | undefined
+  /** Whether Tempo ID holds the realm's secp256k1 owners itself, as in the suites and local development. */
+  secp256k1: boolean
+}
+
+/** The ID of the realm that every app without rows in `app_realms` reaches. */
+export const defaultId = 'default'
+
+/** Zod schemas for the values that define realms. */
+export namespace schema {
+  /** A realm ID, in lowercase kebab case. */
+  export const id = z.string().regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, {
+    message: 'Use lowercase kebab case, such as tempo-cash.',
+  })
+
+  /** A realm, as `add` receives it. */
+  export const realm = z.object({
+    id,
+    name: z.string().trim().min(1, { message: 'Set a name.' }),
+  })
+
+  /** A realm's passkey relying party, as `setPasskeys` receives it. */
+  export const passkeys = z.object({
+    realmId: id,
+    rpId: z
+      .string()
+      .regex(
+        /^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$/,
+        {
+          message: 'Use a lowercase domain, such as tempo.xyz.',
+        },
+      ),
+  })
+
+  /** A realm's Privy app, as `setPrivy` receives it. */
+  export const privy = z.object({
+    appId: z.string().trim().min(1, { message: 'Set a Privy app ID.' }),
+    appSecret: z.string().min(1, { message: 'Set a Privy app secret.' }),
+    realmId: id,
+  })
+
+  /** An app's realms, in order, each named once. */
+  export const realms = z
+    .array(id)
+    .refine((ids) => new Set(ids).size === ids.length, {
+      message: 'Name each realm once.',
+    })
+}
+
+/**
+ * Adds a realm without owner configurations, and returns it.
+ *
+ * Throws `InvalidError` for an invalid value, and `TakenError` when the ID exists.
+ */
+export async function add(db: Database, options: add.Options) {
+  const value = parse(options, { schema: schema.realm })
+
+  const inserted = await db
+    .insert(Schema.realms)
+    .values(value)
+    .onConflictDoNothing()
+    .returning({ id: Schema.realms.id })
+  if (inserted.length === 0) throw new TakenError({ id: value.id })
+
+  return from({
+    id: value.id,
+    name: value.name,
+    passkeys: undefined,
+    privy: undefined,
+    secp256k1: false,
+  })
+}
+
+export declare namespace add {
+  type Options = {
+    /** The realm ID, in lowercase kebab case, such as `tempo-cash`. */
+    id: string
+    /** The display name, such as `Tempo Cash`. */
+    name: string
+  }
+}
+
+/**
+ * Returns the realms of the app with `clientId`, in order, in one query. The first realm holds a
+ * user's first account. An app without rows, or an unknown client ID, reaches the `default` realm.
+ */
+export async function forApp(
+  db: Database,
+  options: forApp.Options,
+): Promise<readonly Realm[]> {
+  // The query returns the app's realms and the `default` realm. `position` is `null` on `default`
+  // when the app does not name it.
+  const rows = await db
+    .select({
+      appId: Schema.realmPrivy.appId,
+      id: Schema.realms.id,
+      name: Schema.realms.name,
+      position: Schema.appRealms.position,
+      rpId: Schema.realmPasskeys.rpId,
+      secp256k1: Schema.realmSecp256k1.realmId,
+    })
+    .from(Schema.realms)
+    .leftJoin(
+      Schema.appRealms,
+      and(
+        eq(Schema.appRealms.realmId, Schema.realms.id),
+        eq(Schema.appRealms.clientId, options.clientId),
+      ),
+    )
+    .leftJoin(
+      Schema.realmPasskeys,
+      eq(Schema.realmPasskeys.realmId, Schema.realms.id),
+    )
+    .leftJoin(
+      Schema.realmPrivy,
+      eq(Schema.realmPrivy.realmId, Schema.realms.id),
+    )
+    .leftJoin(
+      Schema.realmSecp256k1,
+      eq(Schema.realmSecp256k1.realmId, Schema.realms.id),
+    )
+    .where(
+      or(
+        eq(Schema.appRealms.clientId, options.clientId),
+        eq(Schema.realms.id, defaultId),
+      ),
+    )
+    .orderBy(asc(Schema.appRealms.position))
+
+  const named = rows.filter((row) => row.position !== null)
+  return (named.length > 0 ? named : rows).map(toRealm)
+}
+
+export declare namespace forApp {
+  type Options = {
+    /** The OAuth app's client ID. */
+    clientId: string
+  }
+}
+
+/**
+ * Returns the realms that a request reaches for the app with `clientId`, in order. A request that
+ * names no app reaches the `default` realm. So does a browser page that names an app from an origin
+ * none of the app's redirect URIs has, since a page cannot read another app's accounts. A native app
+ * sends no `Origin`, and Tempo ID's own pages send `own`.
+ */
+export async function forRequest(
+  db: Database,
+  options: forRequest.Options,
+): Promise<readonly Realm[]> {
+  const { clientId, origin, own } = options
+  if (!clientId) return [await get(db, { id: defaultId })]
+
+  if (origin && origin !== own) {
+    const [app] = await db
+      .select({ redirectUris: Schema.oauthClient.redirectUris })
+      .from(Schema.oauthClient)
+      .where(eq(Schema.oauthClient.clientId, clientId))
+    const origins = (app?.redirectUris ?? []).flatMap((uri) => {
+      const url = URL.parse(uri)
+      return url && (url.protocol === 'https:' || url.protocol === 'http:')
+        ? [url.origin]
+        : []
+    })
+    if (!origins.includes(origin)) return [await get(db, { id: defaultId })]
+  }
+
+  return await forApp(db, { clientId })
+}
+
+export declare namespace forRequest {
+  type Options = {
+    /** The client ID that the request names, if any. */
+    clientId?: string | undefined
+    /** The request's `Origin`, if any. */
+    origin?: string | undefined
+    /** Tempo ID's own origin. */
+    own: string
+  }
+}
+
+/**
+ * Instantiates a {@link Realm}.
+ *
+ * @example
+ * ```ts
+ * const realm = Realm.from({
+ *   id: 'tempo-cash',
+ *   name: 'Tempo Cash',
+ *   privy: { appId: 'cm…' },
+ *   secp256k1: false,
+ * })
+ * ```
+ */
+export function from(value: Realm): Realm {
+  return value
+}
+
+/** Returns the realm with `id`. Throws `NotFoundError` when no realm has it. */
+export async function get(db: Database, options: get.Options) {
+  const [row] = await db
+    .select({
+      appId: Schema.realmPrivy.appId,
+      id: Schema.realms.id,
+      name: Schema.realms.name,
+      rpId: Schema.realmPasskeys.rpId,
+      secp256k1: Schema.realmSecp256k1.realmId,
+    })
+    .from(Schema.realms)
+    .leftJoin(
+      Schema.realmPasskeys,
+      eq(Schema.realmPasskeys.realmId, Schema.realms.id),
+    )
+    .leftJoin(
+      Schema.realmPrivy,
+      eq(Schema.realmPrivy.realmId, Schema.realms.id),
+    )
+    .leftJoin(
+      Schema.realmSecp256k1,
+      eq(Schema.realmSecp256k1.realmId, Schema.realms.id),
+    )
+    .where(eq(Schema.realms.id, options.id))
+  if (!row) throw new NotFoundError({ id: options.id })
+  return toRealm(row)
+}
+
+export declare namespace get {
+  type Options = {
+    /** The realm ID, such as `tempo-cash`. */
+    id: string
+  }
+}
+
+/** Returns every realm: `default` first, then the others by ID. */
+export async function list(db: Database): Promise<readonly Realm[]> {
+  const rows = await db
+    .select({
+      appId: Schema.realmPrivy.appId,
+      id: Schema.realms.id,
+      name: Schema.realms.name,
+      rpId: Schema.realmPasskeys.rpId,
+      secp256k1: Schema.realmSecp256k1.realmId,
+    })
+    .from(Schema.realms)
+    .leftJoin(
+      Schema.realmPasskeys,
+      eq(Schema.realmPasskeys.realmId, Schema.realms.id),
+    )
+    .leftJoin(
+      Schema.realmPrivy,
+      eq(Schema.realmPrivy.realmId, Schema.realms.id),
+    )
+    .leftJoin(
+      Schema.realmSecp256k1,
+      eq(Schema.realmSecp256k1.realmId, Schema.realms.id),
+    )
+    .orderBy(asc(Schema.realms.id))
+
+  return rows
+    .toSorted((a, b) => Number(b.id === defaultId) - Number(a.id === defaultId))
+    .map(toRealm)
+}
+
+/**
+ * Returns the Privy apps of `realms`, by realm ID, with each app secret decrypted with `secret`. A
+ * realm without a Privy app has no entry. Reads every realm in one query.
+ */
+export async function privyApps(
+  db: Database,
+  options: privyApps.Options,
+): Promise<ReadonlyMap<string, Privy.App>> {
+  const ids = options.realms.flatMap((realm) => (realm.privy ? [realm.id] : []))
+  if (ids.length === 0) return new Map()
+
+  const rows = await db
+    .select()
+    .from(Schema.realmPrivy)
+    .where(inArray(Schema.realmPrivy.realmId, ids))
+  return new Map(
+    await Promise.all(
+      rows.map(
+        async (row) =>
+          [
+            row.realmId,
+            {
+              appId: row.appId,
+              appSecret: await symmetricDecrypt({
+                data: row.appSecret,
+                key: options.secret,
+              }),
+            },
+          ] as const,
+      ),
+    ),
+  )
+}
+
+export declare namespace privyApps {
+  type Options = {
+    /** The realms whose Privy apps to read. */
+    realms: readonly Realm[]
+    /** The `SECRET` variable, which encrypts each app secret. */
+    secret: string
+  }
+}
+
+/**
+ * Removes the realm with `id`, with its owner configurations.
+ *
+ * Throws `InvalidError` for an invalid ID or `default`, `NotFoundError` when no realm has the ID,
+ * and `InUseError` while an app names the realm.
+ */
+export async function remove(db: Database, options: remove.Options) {
+  const id = parse(options.id, { schema: schema.id })
+  if (id === defaultId)
+    throw new InvalidError(
+      `Invalid id: apps without realms reach the ${defaultId} realm. Remove another realm.`,
+    )
+
+  const deleted = await (async () => {
+    try {
+      return await db
+        .delete(Schema.realms)
+        .where(eq(Schema.realms.id, id))
+        .returning({ id: Schema.realms.id })
+    } catch (error) {
+      if (
+        violation(error, { code: '23503' }) ===
+        'app_realms_realm_id_realms_id_fk'
+      )
+        throw new InUseError({ id })
+      throw error
+    }
+  })()
+  if (deleted.length === 0) throw new NotFoundError({ id })
+}
+
+export declare namespace remove {
+  type Options = {
+    /** The realm ID, such as `tempo-cash`. */
+    id: string
+  }
+}
+
+/**
+ * Sets the realms of the app with `clientId`, in order, and returns them. An empty list removes the
+ * app's rows, so the app reaches the `default` realm.
+ *
+ * Throws `InvalidError` for an invalid ID or a repeated realm, `NotFoundAppError` when no OAuth app
+ * has the client ID, and `NotFoundError` when no realm has one of the IDs.
+ */
+export async function setForApp(db: Database, options: setForApp.Options) {
+  const { clientId } = options
+  const ids = parse(options.realms, { schema: schema.realms })
+
+  return await db.transaction(async (tx) => {
+    // The locks serialize concurrent changes to the app's realms, and hold each named realm until
+    // the transaction ends, so a concurrent `remove` waits and the result is this call's own.
+    const [app] = await tx
+      .select({ clientId: Schema.oauthClient.clientId })
+      .from(Schema.oauthClient)
+      .where(eq(Schema.oauthClient.clientId, clientId))
+      .for('update')
+    if (!app) throw new NotFoundAppError({ clientId })
+
+    const rows =
+      ids.length === 0
+        ? []
+        : await tx
+            .select({ id: Schema.realms.id })
+            .from(Schema.realms)
+            .where(inArray(Schema.realms.id, ids))
+            .for('share')
+    const known = new Set(rows.map((row) => row.id))
+    const missing = ids.find((id) => !known.has(id))
+    if (missing) throw new NotFoundError({ id: missing })
+
+    await tx
+      .delete(Schema.appRealms)
+      .where(eq(Schema.appRealms.clientId, clientId))
+    if (ids.length > 0)
+      await tx
+        .insert(Schema.appRealms)
+        .values(
+          ids.map((realmId, position) => ({ clientId, position, realmId })),
+        )
+
+    return await forApp(tx, { clientId })
+  })
+}
+
+export declare namespace setForApp {
+  type Options = {
+    /** The OAuth app's client ID. */
+    clientId: string
+    /** The realm IDs, in order, such as `['default', 'tempo-cash']`. Empty for the `default` realm alone. */
+    realms: readonly string[]
+  }
+}
+
+/**
+ * Sets the passkey relying party of the realm with `realmId`, and returns the realm. It replaces an
+ * earlier relying party. Passkeys of that relying party then own accounts in the realm.
+ *
+ * Throws `InvalidError` for an invalid value, `NotFoundError` when no realm has the ID, and
+ * `TakenPasskeysError` when another realm holds the relying party.
+ */
+export async function setPasskeys(db: Database, options: setPasskeys.Options) {
+  const value = parse(options, { schema: schema.passkeys })
+
+  try {
+    await db
+      .insert(Schema.realmPasskeys)
+      .values({ realmId: value.realmId, rpId: value.rpId })
+      .onConflictDoUpdate({
+        set: { rpId: value.rpId },
+        target: Schema.realmPasskeys.realmId,
+      })
+  } catch (error) {
+    if (violation(error, { code: '23505' }) === 'realm_passkeys_rp_id_unique')
+      throw new TakenPasskeysError({ rpId: value.rpId })
+    if (violation(error, { code: '23503' }))
+      throw new NotFoundError({ id: value.realmId })
+    throw error
+  }
+
+  return await get(db, { id: value.realmId })
+}
+
+export declare namespace setPasskeys {
+  type Options = {
+    /** The realm ID, such as `default`. */
+    realmId: string
+    /** The relying party ID, a registrable domain such as `tempo.xyz`. */
+    rpId: string
+  }
+}
+
+/**
+ * Sets the Privy app that holds the Privy owners of the realm with `realmId`, and returns the realm.
+ * It replaces an earlier Privy app. The row holds the app secret encrypted with `secret`.
+ *
+ * Throws `InvalidError` for an invalid value, `NotFoundError` when no realm has the ID, and
+ * `TakenPrivyAppError` when another realm holds the Privy app.
+ */
+export async function setPrivy(db: Database, options: setPrivy.Options) {
+  const value = parse(options, { schema: schema.privy })
+  const appSecret = await symmetricEncrypt({
+    data: value.appSecret,
+    key: options.secret,
+  })
+
+  const [realm] = await db
+    .select({ id: Schema.realms.id })
+    .from(Schema.realms)
+    .where(eq(Schema.realms.id, value.realmId))
+  if (!realm) throw new NotFoundError({ id: value.realmId })
+
+  try {
+    await db
+      .insert(Schema.realmPrivy)
+      .values({ appId: value.appId, appSecret, realmId: value.realmId })
+      .onConflictDoUpdate({
+        set: { appId: value.appId, appSecret },
+        target: Schema.realmPrivy.realmId,
+      })
+  } catch (error) {
+    if (violation(error, { code: '23505' }) === 'realm_privy_app_id_unique')
+      throw new TakenPrivyAppError({ appId: value.appId })
+    // A concurrent `remove` deleted the realm after the read.
+    if (violation(error, { code: '23503' }))
+      throw new NotFoundError({ id: value.realmId })
+    throw error
+  }
+
+  return await get(db, { id: value.realmId })
+}
+
+export declare namespace setPrivy {
+  type Options = {
+    /** The Privy app ID. */
+    appId: string
+    /** The Privy app secret, which the row holds only encrypted. */
+    appSecret: string
+    /** The realm ID, such as `tempo-cash`. */
+    realmId: string
+    /** The `SECRET` variable, which encrypts the app secret. */
+    secret: string
+  }
+}
+
+/**
+ * Sets whether Tempo ID holds the secp256k1 owners of the realm with `realmId`, and returns the
+ * realm. The realm then creates a user's first account with a key that Tempo ID holds. Turning it
+ * off keeps the realm's stored keys, and lists none of them.
+ *
+ * Throws `InvalidError` for an invalid ID, and `NotFoundError` when no realm has the ID.
+ */
+export async function setSecp256k1(
+  db: Database,
+  options: setSecp256k1.Options,
+) {
+  const realmId = parse(options.realmId, { schema: schema.id })
+
+  if (!options.enabled)
+    await db
+      .delete(Schema.realmSecp256k1)
+      .where(eq(Schema.realmSecp256k1.realmId, realmId))
+  else
+    try {
+      await db
+        .insert(Schema.realmSecp256k1)
+        .values({ realmId })
+        .onConflictDoNothing()
+    } catch (error) {
+      if (violation(error, { code: '23503' }))
+        throw new NotFoundError({ id: realmId })
+      throw error
+    }
+
+  return await get(db, { id: realmId })
+}
+
+export declare namespace setSecp256k1 {
+  type Options = {
+    /** Whether Tempo ID holds the realm's secp256k1 owners. */
+    enabled: boolean
+    /** The realm ID, such as `default`. */
+    realmId: string
+  }
+}
+
+/**
+ * Returns `realms` with the relying party that each one signs in with. The `default` realm without a
+ * `realm_passkeys` row signs in with passkeys of the registrable domain of `origin`, such as
+ * `tempo.xyz` for `https://id.tempo.xyz`, so every deployment offers passkeys without configuration. A row replaces that relying party. When another realm's row holds
+ * the host or a parent domain of it, `default` has none, since that realm's passkeys sign in at the
+ * same origin.
+ */
+export async function withDefaults(
+  db: Database,
+  options: withDefaults.Options,
+): Promise<readonly Realm[]> {
+  const { realms } = options
+  if (!realms.some((realm) => realm.id === defaultId && !realm.passkeys))
+    return realms
+
+  const host = new URL(options.origin).hostname
+  const parsed = Tldts.parse(host, { allowPrivateDomains: true })
+  // WebAuthn refuses an IP address as a relying party.
+  if (parsed.isIp) return realms
+
+  // A private suffix, such as `workers.dev`, is not a registrable domain, so the host keeps its own
+  // label there. `localhost` has no registrable domain, and keeps its host.
+  const rpId = parsed.domain ?? host
+  // A row for the host or a parent domain of it, such as `tempo.xyz` for `id.tempo.xyz`, signs in at
+  // the origin too, so the default would take that realm's sign-ins at an app that lists `default`
+  // first.
+  // A public suffix, such as `xyz`, is never a relying party, so the domains stop at `rpId`.
+  const labels = host.split('.')
+  const domains = labels
+    .map((_, index) => labels.slice(index).join('.'))
+    .filter((domain) => domain === rpId || domain.endsWith(`.${rpId}`))
+  // The realms come from an earlier read than the lookup below, so a change between the two reads
+  // could show the host as free while one of `realms` still holds it. Both checks together cover
+  // either order.
+  if (
+    realms.some(
+      (realm) => realm.passkeys && domains.includes(realm.passkeys.rpId),
+    )
+  )
+    return realms
+
+  const [taken] = await db
+    .select({ realmId: Schema.realmPasskeys.realmId })
+    .from(Schema.realmPasskeys)
+    .where(inArray(Schema.realmPasskeys.rpId, domains))
+  if (taken) return realms
+
+  return realms.map((realm) =>
+    realm.id === defaultId && !realm.passkeys
+      ? from({ ...realm, passkeys: { rpId } })
+      : realm,
+  )
+}
+
+export declare namespace withDefaults {
+  type Options = {
+    /** Tempo ID's origin, such as `https://id.tempo.xyz`. */
+    origin: string
+    /** The realms that a request reaches, in order. */
+    realms: readonly Realm[]
+  }
+}
+
+/** Parses `value` with `options.schema`, and throws `InvalidError` with the first issue's message. */
+function parse<const type extends z.ZodType>(
+  value: unknown,
+  options: parse.Options<type>,
+): z.output<type> {
+  const result = options.schema.safeParse(value)
+  if (result.success) return result.data
+
+  const issue = result.error.issues[0]!
+  const path = issue.path.join('.')
+  throw new InvalidError(
+    path
+      ? `Invalid ${path}: ${issue.message}`
+      : `Invalid realm: ${issue.message}`,
+  )
+}
+
+declare namespace parse {
+  type Options<type extends z.ZodType> = {
+    /** The schema that `value` must pass. */
+    schema: type
+  }
+}
+
+/** Returns a realm from a row of `realms` joined with its owner configurations. */
+function toRealm(row: toRealm.Row) {
+  return from({
+    id: row.id,
+    name: row.name,
+    passkeys: row.rpId === null ? undefined : { rpId: row.rpId },
+    privy: row.appId === null ? undefined : { appId: row.appId },
+    secp256k1: row.secp256k1 !== null,
+  })
+}
+
+declare namespace toRealm {
+  type Row = {
+    /** The Privy app ID, or `null` when the realm has no Privy app. */
+    appId: string | null
+    /** The realm ID. */
+    id: string
+    /** The display name. */
+    name: string
+    /** The passkey relying party ID, or `null` when the realm has none. */
+    rpId: string | null
+    /** The realm ID again when the realm holds secp256k1 owners, or `null`. */
+    secp256k1: string | null
+  }
+}
+
+/**
+ * Returns the constraint that a Postgres error with `code` names, such as `23505` for a unique
+ * violation, or `undefined` for any other error. Drizzle wraps the driver's error in `cause`.
+ */
+function violation(error: unknown, options: violation.Options) {
+  const { code } = options
+  const cause = error instanceof Error && error.cause ? error.cause : error
+  if (typeof cause !== 'object' || cause === null) return undefined
+  if (!('code' in cause) || cause.code !== code) return undefined
+  if (!('constraint' in cause) || typeof cause.constraint !== 'string')
+    return undefined
+  return cause.constraint
+}
+
+declare namespace violation {
+  type Options = {
+    /** The SQLSTATE code, such as `23503` for a foreign key violation. */
+    code: string
+  }
+}