@zeno-lib/db 0.3.1 → 0.4.0

package/src/errors.ts

@@ -0,0 +1,133 @@
+// Recognising Postgres errors through Drizzle. Runtime code, not a test helper:
+// mapping a unique violation to a form error is ordinary request handling.
+import type { PostgresError } from "postgres"
+
+/**
+ * SQLSTATE codes worth naming. The full list is Postgres's "Error Codes"
+ * appendix; these are the ones an application branches on.
+ */
+export const SqlState = {
+  /** `check_violation`. */
+  checkViolation: "23514",
+  /** `exclusion_violation`. */
+  exclusionViolation: "23P01",
+  /** `foreign_key_violation`. */
+  foreignKeyViolation: "23503",
+  /** `insufficient_privilege`: an RLS policy or a missing grant refused it. */
+  insufficientPrivilege: "42501",
+  /**
+   * `invalid_column_reference`, which is what an `ON CONFLICT` target that no
+   * unique index can arbitrate raises. It is raised while the statement is
+   * planned, so it fires on the first insert, not on the first conflict.
+   */
+  invalidColumnReference: "42P10",
+  /** `not_null_violation`. */
+  notNullViolation: "23502",
+  /** `undefined_function`: a function missing, or called with the wrong signature. */
+  undefinedFunction: "42883",
+  /** `unique_violation`. */
+  uniqueViolation: "23505",
+} as const
+
+export type SqlStateCode = (typeof SqlState)[keyof typeof SqlState]
+
+/** SQLSTATE class 23, every `integrity_constraint_violation`. */
+const INTEGRITY_CONSTRAINT_CLASS = "23"
+
+// Drizzle wraps once, and a failure inside `db.transaction()` can nest one
+// more level. The bound only stops a cyclic `cause` chain.
+const MAX_CAUSE_DEPTH = 5
+
+/**
+ * The postgres.js error underneath whatever Drizzle threw, or `undefined`.
+ *
+ * Drizzle wraps **every** driver error in a `DrizzleQueryError` whose own
+ * `code` is `undefined`, so `error.code === "23505"` is always false:
+ *
+ * ```
+ * depth 0: DrizzleQueryError  code=undefined  "Failed query: insert into …"
+ * depth 1: PostgresError      code=23505      "duplicate key value violates …"
+ * ```
+ *
+ * Matched by `name` rather than `instanceof`, so a second copy of `postgres`
+ * in the tree cannot make it miss.
+ */
+export const toPostgresError = (error: unknown): PostgresError | undefined => {
+  let current: unknown = error
+
+  for (
+    let depth = 0;
+    current instanceof Error && depth < MAX_CAUSE_DEPTH;
+    depth += 1
+  ) {
+    if (current.name === "PostgresError") {
+      return current as PostgresError
+    }
+    // `Error.cause` is ES2022, past this package's `lib`.
+    current = (current as Error & { cause?: unknown }).cause
+  }
+
+  return
+}
+
+export type ConstraintViolationOptions = {
+  /**
+   * The SQLSTATE to require, e.g. `SqlState.uniqueViolation`. Defaults to any
+   * code in class 23 (`integrity_constraint_violation`).
+   */
+  code?: string
+}
+
+/**
+ * Whether `error` is an integrity-constraint violation, optionally one of the
+ * named constraints. Returns the `PostgresError` so a caller can read its
+ * `constraint_name` or `detail`, or `undefined` when it does not match.
+ *
+ * ```ts
+ * try {
+ *   await db.insert(contacts).values(row)
+ * } catch (error) {
+ *   if (isConstraintViolation(error, ["contacts_email_key"], { code: SqlState.uniqueViolation })) {
+ *     return { error: "That email is already a contact" }
+ *   }
+ *   throw error
+ * }
+ * ```
+ */
+export const isConstraintViolation = (
+  error: unknown,
+  constraints?: Iterable<string>,
+  { code }: ConstraintViolationOptions = {}
+): PostgresError | undefined => {
+  const postgresError = toPostgresError(error)
+
+  if (!postgresError) {
+    return
+  }
+
+  const matchesCode = code
+    ? postgresError.code === code
+    : postgresError.code.startsWith(INTEGRITY_CONSTRAINT_CLASS)
+
+  if (!matchesCode) {
+    return
+  }
+
+  if (constraints === undefined) {
+    return postgresError
+  }
+
+  const name = postgresError.constraint_name
+
+  if (name === undefined) {
+    return
+  }
+
+  for (const constraint of constraints) {
+    if (constraint === name) {
+      return postgresError
+    }
+  }
+
+  return
+}

package/src/function-names.ts

@@ -0,0 +1,21 @@
+// The naming convention `functionPolicies` writes policies against and
+// `selectFunctionPermissions` calls: `<prefix>_<operation>_<table>`. Shared so
+// the two cannot drift apart.
+
+export const FUNCTION_POLICY_OPERATIONS = [
+  "select",
+  "insert",
+  "update",
+  "delete",
+] as const
+
+export type FunctionPolicyOperation =
+  (typeof FUNCTION_POLICY_OPERATIONS)[number]
+
+export const DEFAULT_FUNCTION_PREFIX = "can"
+
+export const functionPolicyName = (
+  prefix: string,
+  operation: FunctionPolicyOperation,
+  tableName: string
+) => `${prefix}_${operation}_${tableName}`

package/src/index.ts

@@ -7,5 +7,7 @@ export {
   createServiceClient,
   createSupabaseClient,
   type DrizzleClient,
+  type ResolveDatabaseUrlOptions,
+  resolveDatabaseUrl,
   type SupabaseToken,
 } from "./clients.ts"

package/src/next.test-d.ts

@@ -0,0 +1,32 @@
+import type { JwtPayload } from "@supabase/supabase-js"
+import { expectTypeOf, test } from "vitest"
+import { z } from "zod"
+import type { DrizzleClient } from "./clients.ts"
+import { createRequestDb } from "./next.ts"
+
+const { defineAction } = createRequestDb({
+  supabase: () => ({
+    auth: {
+      getClaims: () => Promise.resolve({ data: null, error: null }),
+    },
+  }),
+})
+
+test("the action takes the schema's input and resolves to the handler's result", () => {
+  const schema = z.object({ id: z.string().transform(Number) })
+  const action = defineAction(schema, (db, input, context) => {
+    expectTypeOf(db).toEqualTypeOf<DrizzleClient>()
+    expectTypeOf(input).toEqualTypeOf<{ id: number }>()
+    expectTypeOf(context.claims).toEqualTypeOf<JwtPayload>()
+    return Promise.resolve(input.id)
+  })
+
+  expectTypeOf(action).parameter(0).toEqualTypeOf<{ id: string }>()
+  expectTypeOf(action).returns.toEqualTypeOf<Promise<number>>()
+})
+
+test("a synchronous handler still yields an async action", () => {
+  const action = defineAction(z.number(), (_db, input) => input > 0)
+
+  expectTypeOf(action).returns.toEqualTypeOf<Promise<boolean>>()
+})

package/src/next.test.ts

@@ -0,0 +1,178 @@
+import { AuthError, type JwtPayload } from "@supabase/supabase-js"
+import { beforeEach, describe, expect, it, vi } from "vitest"
+import { z } from "zod"
+import { createDefineAction } from "./define-action.ts"
+
+// No database: the RLS client factory is replaced by a stub that returns a
+// marker object, so nothing here builds a pool or opens a connection. What
+// that client does with the claims is covered by test/rls.integration.test.ts.
+const { createSupabaseClientMock } = vi.hoisted(() => ({
+  createSupabaseClientMock: vi.fn((claims: unknown) => ({
+    claims,
+    fake: true,
+  })),
+}))
+
+vi.mock("./clients.ts", () => ({
+  createSupabaseClient: createSupabaseClientMock,
+}))
+
+import {
+  type ClaimsSource,
+  createRequestDb,
+  UnauthenticatedError,
+} from "./next.ts"
+
+const claims: JwtPayload = {
+  aal: "aal1",
+  aud: "authenticated",
+  exp: 0,
+  iat: 0,
+  iss: "test",
+  role: "authenticated",
+  roles: ["admin"],
+  session_id: "session",
+  sub: "11111111-1111-1111-1111-111111111111",
+}
+
+type GetClaimsResult = Awaited<ReturnType<ClaimsSource["auth"]["getClaims"]>>
+
+function getClaimsResult(
+  payload: JwtPayload | null,
+  error: AuthError | null
+): GetClaimsResult {
+  if (payload) {
+    return {
+      data: {
+        claims: payload,
+        header: { alg: "HS256", kid: "test", typ: "JWT" },
+        signature: new Uint8Array(),
+      },
+      error: null,
+    }
+  }
+  return error ? { data: null, error } : { data: null, error: null }
+}
+
+function supabaseReturning(result: GetClaimsResult): () => ClaimsSource {
+  return () => ({ auth: { getClaims: () => Promise.resolve(result) } })
+}
+
+beforeEach(() => {
+  createSupabaseClientMock.mockClear()
+})
+
+describe("defineAction", () => {
+  const schema = z.object({ id: z.number().int().positive() }).strict()
+
+  it("parses the input, then calls the handler with db, parsed input and context", async () => {
+    const context = { claims: { sub: "user-1" }, db: { name: "db" } }
+    const getContext = vi.fn(() => Promise.resolve(context))
+    const handler = vi.fn((db: { name: string }, input: { id: number }) =>
+      Promise.resolve(`${db.name}:${input.id}`)
+    )
+
+    const action = createDefineAction(getContext)(schema, handler)
+
+    await expect(action({ id: 7 })).resolves.toBe("db:7")
+    expect(handler).toHaveBeenCalledWith(context.db, { id: 7 }, context)
+  })
+
+  it("hands the handler the claims for authorship", async () => {
+    const context = { claims: { sub: "user-1" }, db: {} }
+    const action = createDefineAction(() => Promise.resolve(context))(
+      schema,
+      (_db, input, { claims: { sub } }) => ({ createdBy: sub, ...input })
+    )
+
+    await expect(action({ id: 1 })).resolves.toEqual({
+      createdBy: "user-1",
+      id: 1,
+    })
+  })
+
+  it("rejects invalid input before resolving the context or calling the handler", async () => {
+    const getContext = vi.fn(() => Promise.resolve({ db: {} }))
+    const handler = vi.fn()
+    const action = createDefineAction(getContext)(schema, handler)
+
+    await expect(action({ id: -1 })).rejects.toBeInstanceOf(z.ZodError)
+    expect(getContext).not.toHaveBeenCalled()
+    expect(handler).not.toHaveBeenCalled()
+  })
+
+  it("propagates a context failure without calling the handler", async () => {
+    const handler = vi.fn()
+    const action = createDefineAction(() =>
+      Promise.reject(new UnauthenticatedError())
+    )(schema, handler)
+
+    await expect(action({ id: 1 })).rejects.toBeInstanceOf(UnauthenticatedError)
+    expect(handler).not.toHaveBeenCalled()
+  })
+})
+
+describe("createRequestDb", () => {
+  it("builds the RLS client from the whole verified claims object", async () => {
+    const { getRequestContext, getRequestDb } = createRequestDb({
+      connectionString: () => "postgresql://lazy",
+      supabase: supabaseReturning(getClaimsResult(claims, null)),
+    })
+
+    const context = await getRequestContext()
+
+    expect(context.claims).toBe(claims)
+    expect(createSupabaseClientMock).toHaveBeenCalledWith(claims, {
+      connectionString: "postgresql://lazy",
+    })
+    await expect(getRequestDb()).resolves.toEqual({ claims, fake: true })
+  })
+
+  it("throws UnauthenticatedError when there is no session", async () => {
+    const { getRequestDb } = createRequestDb({
+      supabase: supabaseReturning(getClaimsResult(null, null)),
+    })
+
+    const error = await getRequestDb().catch((caught: unknown) => caught)
+
+    expect(error).toBeInstanceOf(UnauthenticatedError)
+    expect(error).toHaveProperty("name", "UnauthenticatedError")
+    expect(createSupabaseClientMock).not.toHaveBeenCalled()
+  })
+
+  it("throws UnauthenticatedError for claims without a subject", async () => {
+    const { getRequestDb } = createRequestDb({
+      supabase: supabaseReturning(
+        getClaimsResult({ ...claims, sub: "" }, null)
+      ),
+    })
+
+    await expect(getRequestDb()).rejects.toBeInstanceOf(UnauthenticatedError)
+  })
+
+  it("rethrows a getClaims error as is", async () => {
+    const failure = new AuthError("jwks unreachable")
+    const { getRequestDb } = createRequestDb({
+      supabase: supabaseReturning(getClaimsResult(null, failure)),
+    })
+
+    await expect(getRequestDb()).rejects.toBe(failure)
+  })
+
+  it("binds defineAction to the request context", async () => {
+    const { defineAction } = createRequestDb({
+      supabase: supabaseReturning(getClaimsResult(claims, null)),
+    })
+    const action = defineAction(z.string(), (db, input, context) => ({
+      db,
+      input,
+      sub: context.claims.sub,
+    }))
+
+    await expect(action("hello")).resolves.toEqual({
+      db: { claims, fake: true },
+      input: "hello",
+      sub: claims.sub,
+    })
+  })
+})

package/src/next.ts

@@ -0,0 +1,112 @@
+import type { JwtPayload, SupabaseClient } from "@supabase/supabase-js"
+import type { AnyRelations, EmptyRelations } from "drizzle-orm"
+import { cache } from "react"
+import {
+  type CreateClientConfig,
+  createSupabaseClient,
+  type DrizzleClient,
+} from "./clients.ts"
+import { createDefineAction, type DefineAction } from "./define-action.ts"
+
+export type {
+  ActionContext,
+  ActionHandler,
+  ActionSchema,
+  DefineAction,
+} from "./define-action.ts"
+
+/**
+ * Thrown when a request carries no verified session. A named class so a caller
+ * with a legitimate answer for that case (a permission check, where "not signed
+ * in" means "no") can tell it apart from a real failure with `instanceof`.
+ */
+export class UnauthenticatedError extends Error {
+  constructor(message = "Unauthorized: no verified session on this request") {
+    super(message)
+    this.name = "UnauthenticatedError"
+  }
+}
+
+/** The only part of a Supabase client the request context reads. */
+export type ClaimsSource = { auth: Pick<SupabaseClient["auth"], "getClaims"> }
+
+/** A verified request: the full `getClaims()` payload and the RLS client. */
+export type RequestContext<TRelations extends AnyRelations = EmptyRelations> = {
+  readonly claims: JwtPayload
+  readonly db: DrizzleClient<TRelations>
+}
+
+export type CreateRequestDbOptions<
+  TRelations extends AnyRelations = EmptyRelations,
+> = Omit<CreateClientConfig<TRelations>, "connectionString"> & {
+  /**
+   * Builds the request's Supabase client, e.g. `createClient` from
+   * `@zeno-lib/supabase/next-server` (cookie session via `next/headers`).
+   */
+  supabase: () => ClaimsSource | Promise<ClaimsSource>
+  /**
+   * Overrides `SUPABASE_DATABASE_URL`. A function is resolved per request, not
+   * at import, so a build without server secrets can still import the module.
+   */
+  connectionString?: string | (() => string)
+}
+
+export type RequestDb<TRelations extends AnyRelations = EmptyRelations> = {
+  /** Memoised per render: `{ claims, db }` for the verified caller. */
+  getRequestContext: () => Promise<RequestContext<TRelations>>
+  /** The common case: just the RLS-bound client. */
+  getRequestDb: () => Promise<DrizzleClient<TRelations>>
+  /** Wraps a handler into a `"use server"` export; see `DefineAction`. */
+  defineAction: DefineAction<RequestContext<TRelations>>
+}
+
+/**
+ * Request-scoped, RLS-bound Drizzle access for Next.js. Verifies the session
+ * with `getClaims()` (which checks the signature) and installs the **whole**
+ * claims object, so custom claims reach `auth.jwt()` in policies. There is no
+ * fallback to `anon`: a caller without a verified `sub` gets
+ * `UnauthenticatedError` rather than the empty result of a policy it never
+ * satisfied.
+ *
+ * `getRequestContext` is wrapped in React's `cache`, so one server render shares
+ * one verification and one handle. A server action invoked from the browser
+ * runs outside a render and resolves afresh on every call.
+ *
+ * Do not `close()` the handle: pools are shared and reference-counted.
+ */
+export function createRequestDb<
+  TRelations extends AnyRelations = EmptyRelations,
+>(options: CreateRequestDbOptions<TRelations>): RequestDb<TRelations> {
+  const { connectionString, supabase, ...config } = options
+
+  const getRequestContext = cache(
+    async (): Promise<RequestContext<TRelations>> => {
+      const client = await supabase()
+      const { data, error } = await client.auth.getClaims()
+
+      if (error) {
+        throw error
+      }
+      if (!data?.claims.sub) {
+        throw new UnauthenticatedError()
+      }
+
+      const url =
+        typeof connectionString === "function"
+          ? connectionString()
+          : connectionString
+      const db = createSupabaseClient<TRelations>(
+        data.claims,
+        url === undefined ? config : { ...config, connectionString: url }
+      )
+
+      return { claims: data.claims, db }
+    }
+  )
+
+  return {
+    defineAction: createDefineAction(getRequestContext),
+    getRequestContext,
+    getRequestDb: async () => (await getRequestContext()).db,
+  }
+}

package/src/query.test-d.ts

@@ -0,0 +1,20 @@
+import { defineRelations } from "drizzle-orm"
+import type { PgAsyncDatabase, PgAsyncTransaction } from "drizzle-orm/pg-core"
+import type { PostgresJsQueryResultHKT } from "drizzle-orm/postgres-js"
+import { expectTypeOf, test } from "vitest"
+import type { DrizzleClient } from "./clients.ts"
+import type { QueryExecutor } from "./query.ts"
+import { primaryId, table } from "./schema.ts"
+
+const posts = table("posts", { id: primaryId("sequential") })
+const relations = defineRelations({ posts })
+
+test("selectFunctionPermissions takes every client and transaction shape", () => {
+  expectTypeOf<DrizzleClient<typeof relations>>().toExtend<QueryExecutor>()
+  expectTypeOf<
+    PgAsyncDatabase<PostgresJsQueryResultHKT, typeof relations>
+  >().toExtend<QueryExecutor>()
+  expectTypeOf<
+    PgAsyncTransaction<PostgresJsQueryResultHKT, typeof relations>
+  >().toExtend<QueryExecutor>()
+})