@zeno-lib/db 0.3.2 → 0.4.0

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>()
+})

package/src/query.test.ts

@@ -0,0 +1,261 @@
+import { defineRelations, type SQL } from "drizzle-orm"
+import { PgDialect, text } from "drizzle-orm/pg-core"
+import { drizzle } from "drizzle-orm/postgres-js"
+import { describe, expect, it } from "vitest"
+import {
+  definedValues,
+  excludedSet,
+  functionPermissionTables,
+  maybeOne,
+  one,
+  type QueryExecutor,
+  selectFunctionPermissions,
+} from "./query.ts"
+import { primaryId, schema, table, view } from "./schema.ts"
+
+// No connection anywhere: `drizzle.mock()` builds statements for `.toSQL()`,
+// and `PgDialect` renders a bare `SQL` the way the driver would receive it.
+const db = drizzle.mock()
+const dialect = new PgDialect()
+const render = (query: SQL) => dialect.sqlToQuery(query)
+
+const contacts = table("contacts", {
+  displayName: text(),
+  email: text(),
+  id: primaryId("sequential"),
+})
+
+const dealsProperties = table("deals_properties", {
+  dealId: text().notNull(),
+  propertyId: text().notNull(),
+})
+
+describe("one", () => {
+  it("returns the only row", () => {
+    expect(one([{ id: 1 }])).toEqual({ id: 1 })
+  })
+
+  it("throws on none and on several", () => {
+    expect(() => one([])).toThrow("Expected exactly one row, received 0")
+    expect(() => one([1, 2])).toThrow("Expected exactly one row, received 2")
+  })
+})
+
+describe("maybeOne", () => {
+  it("returns the row, or undefined for none", () => {
+    expect(maybeOne([{ id: 1 }])).toEqual({ id: 1 })
+    expect(maybeOne([])).toBeUndefined()
+  })
+
+  it("throws on several", () => {
+    expect(() => maybeOne([1, 2])).toThrow(
+      "Expected at most one row, received 2"
+    )
+  })
+})
+
+describe("definedValues", () => {
+  it("drops undefined keys and keeps null", () => {
+    expect(definedValues({ a: 1, b: undefined, c: null })).toEqual({
+      a: 1,
+      c: null,
+    })
+  })
+})
+
+describe("excludedSet", () => {
+  const upsert = (values: Record<string, unknown>, set: Record<string, SQL>) =>
+    db
+      .insert(contacts)
+      .values({ id: 1, ...values })
+      .onConflictDoUpdate({ set, target: contacts.id })
+      .toSQL().sql
+
+  it("writes back every supplied column by its database name, never the target", () => {
+    const values = { displayName: "Ada", email: "ada@example.com", id: 1 }
+
+    expect(upsert(values, excludedSet(contacts, values))).toContain(
+      'do update set "display_name" = excluded."display_name", "email" = excluded."email"'
+    )
+  })
+
+  it("skips a key carrying undefined", () => {
+    const values = { displayName: undefined, email: "ada@example.com" }
+    const set = excludedSet(contacts, values)
+
+    expect(Object.keys(set)).toEqual(["email"])
+  })
+
+  it("falls back to id = excluded.id when nothing else is supplied", () => {
+    const set = excludedSet(contacts, { displayName: undefined, id: 1 })
+
+    expect(upsert({}, set)).toContain('do update set "id" = excluded."id"')
+  })
+
+  it("takes another conflict target", () => {
+    const values = { displayName: "Ada", email: "ada@example.com" }
+    const set = excludedSet(contacts, values, { target: "email" })
+
+    expect(Object.keys(set)).toEqual(["displayName"])
+    expect(render(one(Object.values(set))).sql).toBe('excluded."display_name"')
+  })
+
+  it("falls back to the first target column that exists", () => {
+    const set = excludedSet(
+      dealsProperties,
+      { dealId: "d", propertyId: "p" },
+      { target: ["dealId", "propertyId"] }
+    )
+
+    expect(Object.keys(set)).toEqual(["dealId"])
+    expect(render(one(Object.values(set))).sql).toBe('excluded."deal_id"')
+  })
+
+  it("stays empty for a table without the default id target", () => {
+    expect(excludedSet(dealsProperties, {})).toEqual({})
+  })
+})
+
+const billing = schema("billing")
+const invoices = billing.table("invoices", { id: primaryId("sequential") })
+const privateNotes = schema("private").table("notes", {
+  id: primaryId("sequential"),
+})
+const contactNames = view("contact_names").as((qb) =>
+  qb.select({ displayName: contacts.displayName }).from(contacts)
+)
+
+describe("functionPermissionTables", () => {
+  const schemaObject = {
+    billing,
+    contactNames,
+    contacts,
+    invoices,
+    privateNotes,
+    relationsHelper: () => undefined,
+  }
+
+  it("includes only public tables by default", () => {
+    expect([...functionPermissionTables(schemaObject)]).toEqual([
+      ["contacts", "public"],
+    ])
+  })
+
+  it("maps each table to its own schema", () => {
+    expect(
+      new Map(
+        functionPermissionTables(schemaObject, {
+          schemas: ["public", "billing"],
+        })
+      )
+    ).toEqual(
+      new Map([
+        ["contacts", "public"],
+        ["invoices", "billing"],
+      ])
+    )
+  })
+
+  it("accepts the result of defineRelations", () => {
+    const relations = defineRelations({ contacts, invoices })
+
+    expect([
+      ...functionPermissionTables(relations, { schemas: ["billing"] }),
+    ]).toEqual([["invoices", "billing"]])
+  })
+
+  it("rejects a bare name that two included schemas share", () => {
+    const publicInvoices = table("invoices", { id: primaryId("sequential") })
+
+    expect(() =>
+      functionPermissionTables(
+        { invoices, publicInvoices },
+        { schemas: ["public", "billing"] }
+      )
+    ).toThrow('Table "invoices" exists in both')
+  })
+})
+
+describe("selectFunctionPermissions", () => {
+  const tables = functionPermissionTables(
+    { contacts, invoices },
+    { schemas: ["public", "billing"] }
+  )
+
+  // Records the statement and answers with a canned row: no database.
+  const fakeDb = (row: Record<string, boolean | null>) => {
+    const queries: SQL[] = []
+    const executor: QueryExecutor = {
+      execute: (query) => {
+        queries.push(query)
+        return Promise.resolve([row])
+      },
+    }
+    return { executor, queries }
+  }
+
+  it("calls all four functions in one statement, id to all but insert", async () => {
+    const { executor, queries } = fakeDb({
+      delete: false,
+      insert: true,
+      select: true,
+      update: null,
+    })
+
+    const permissions = await selectFunctionPermissions(executor, {
+      id: 7,
+      table: "invoices",
+      tables,
+    })
+
+    expect(permissions).toEqual({
+      delete: false,
+      insert: true,
+      select: true,
+      update: false,
+    })
+    const query = render(one(queries))
+    expect(query.sql).toBe(
+      'select "billing"."can_select_invoices"("id" => $1) as "select", "billing"."can_insert_invoices"() as "insert", "billing"."can_update_invoices"("id" => $2) as "update", "billing"."can_delete_invoices"("id" => $3) as "delete"'
+    )
+    expect(query.params).toEqual([7, 7, 7])
+  })
+
+  it("calls every function bare without an id, honouring prefix and schema", async () => {
+    const { executor, queries } = fakeDb({
+      delete: true,
+      insert: true,
+      select: true,
+      update: true,
+    })
+
+    await selectFunctionPermissions(executor, {
+      functionSchema: "private",
+      prefix: "may",
+      table: "contacts",
+      tables,
+    })
+
+    expect(render(one(queries)).sql).toBe(
+      'select "private"."may_select_contacts"() as "select", "private"."may_insert_contacts"() as "insert", "private"."may_update_contacts"() as "update", "private"."may_delete_contacts"() as "delete"'
+    )
+  })
+
+  it("rejects a table outside the allowlist before building anything", async () => {
+    const { executor, queries } = fakeDb({})
+
+    await expect(
+      selectFunctionPermissions(executor, {
+        table: 'contacts"; drop table contacts; --',
+        tables,
+      })
+    ).rejects.toThrow("No permission functions for table")
+    expect(queries).toHaveLength(0)
+  })
+
+  it("accepts a real Drizzle client", () => {
+    // Compile-time only: the structural type fits a postgres-js database.
+    const executor: QueryExecutor = db
+    expect(executor.execute).toBeTypeOf("function")
+  })
+})