feat(appkit): add database mutations and transactional hooks

[ditadi]

Stack

• #525 — the database runtime
  • #526 — the typed plugin API
    • #527 — generated reads
      • #528 — mutations and hooks ← you are here
        • #529 — playground example

Each PR targets the one above it, so the diff shown here is only the delta on top of #527. Review in order.

What

Completes the plugin: the typed entity API and the generated routes from #527 gain create, update, upsert, and delete, and a table can declare before/after hooks that run inside the mutation's own transaction. A write a hook issues commits or rolls back with the mutation that triggered it — that is the whole point of the design, and it is what lets a hook call another plugin's write and still get all-or-nothing semantics.

database({
  schema,
  crudRoutes: { tables: ["notes"] },
  hooks: {
    notes: {
      beforeCreate(values) {
        if (values.body.length > 5_000) {
          throw new DatabaseValidationError("Note too long", [
            { path: ["body"], message: "Must be at most 5000 characters" },
          ]);
        }
        return { ...values, body: values.body.trim() };
      },
      async afterCreate(row, ctx) {
        await ctx.app.database.audit.create({ noteId: row.id });
      },
    },
  },
});

POST   /api/database/notes      → 201
PATCH  /api/database/notes/42   → 200
PUT    /api/database/notes/42   → 200
DELETE /api/database/notes/42   → 204

Changes

Hooks share the mutation's transaction (hooks.ts, scope.ts)

A mutation opens its transaction first, then runs before*, the write, and after* inside it. The transaction is published through an AsyncLocalStorage owned by the plugin instance, so ctx.app.database resolves to a client bound to that transaction without the caller threading it through. The storage is per-instance and per-async-context, so two plugin instances and two concurrent requests cannot observe each other's transaction.

The same scope bounds recursion: hook-issued mutations open frames, and a repeated entity/operation pair or a chain deeper than 8 frames is refused rather than allowed to run until the pool or the stack gives out.

A before* hook may return a replacement payload. It is revalidated against the trusted schema before it is persisted, so a hook cannot write a column the schema does not accept.

A hook can reject deliberately (errors/database-validation.ts)

DatabaseValidationError is exported from the root and answers a generated route with 422. Only the issues naming a public column are echoed, and at most 50 of them. Every other failure raised inside a hook stays an opaque server error, so a hook cannot accidentally turn an internal message into a client-visible one.

HTTP writes are narrower than trusted code's (crud/request.ts)

The write allowlist is derived per table and is deliberately smaller than what server code may set: the primary key, generated identities, and materialized stamps stay server-owned. A body naming an unknown or read-only field is refused rather than having the field silently dropped.

A rejection names the field only when that field is a public column of the table. Anything else — a private column, an unknown key, arbitrary caller markup — is answered against the generic ["body"] path, so an error response never reflects caller-controlled text back or confirms that a private column exists.

Failure responses carry the same byte budget (crud/response.ts)

sendError measures its encoded body like the success path does. If the issues would push the response past the limit, the answer keeps its status and its safe message and drops the details, so no error path can be used to return an unbounded body.

where() now binds every terminal operation (entity-client.ts)

update(id) and delete(id) narrow by the accumulated predicate the same way find(id) already did, so a scoped client cannot be used to change a row outside its scope. create and upsert do not select rows, so a predicate cannot apply to them — instead of ignoring it, they reject. No terminal operation silently discards fluent state anymore.

jsonb values with a __proto__ key (crud/contract.ts)

The row sanitizer builds its objects with a null prototype, so __proto__ inside a jsonb payload is carried as ordinary data and round-trips instead of reparenting the object it lands in.

Verification

• pnpm vitest run — 4162 passing, 1 skipped; new suites cover the hook lifecycle and its transaction, the recursion guard, the write allowlist, the response budgets, and an end-to-end CRUD integration path
• pnpm -r typecheck — clean across all packages
• pnpm run generate:types, pnpm run sync:template, and pnpm run docs:build produce no drift
• Each of the four security fixes above was verified by reverting it and confirming the new test fails

[MarioCadenas]

[High] Writes are not opt-in separately from reads. A single crudRoutes value registers GET and POST/PATCH/DELETE for each exposed table; there is no read-only mode and no per-operation gate. Combined with service-principal execution and no per-user/row authorization (see #527), any caller the app admits can create/update/delete any row of any exposed table — and a table opted into generated reads is silently upgraded to public destructive writes on adopting this PR. Consider a separate write opt-in plus an authorization/owner seam.

Automated review finding.

[MarioCadenas]

[Medium-High] Hooks run inside a transaction with no per-hook / per-transaction deadline. The transaction is opened via getDataPath().transaction() (not through ctx.execute), and directExecute runs each op with no interceptors — so there is no AppKit timeout, and there is no PG statement_timeout / idle_in_transaction_session_timeout. A slow or hanging before/after hook holds the pooled connection + row/index locks for its full duration (the pool's connectionTimeoutMillis bounds waiters, not the holder); enough concurrent slow-hook writes exhaust the pool. Bound hook/transaction wall-clock.

Automated review finding.

[MarioCadenas]

[Medium] The re-entrancy guard bounds nesting depth but not sibling fan-out. runMutation caps nesting (MAX_MUTATION_DEPTH=8) and refuses repeated (entity, operation) pairs, but sibling writes at one level do not accumulate frames — so a hook can issue an unbounded number of writes in a loop (e.g. beforeCreate iterating an attacker-controlled array field), all inside the single no-deadline transaction → an arbitrarily long-held transaction / lock set.

Automated review finding.

[MarioCadenas]

[Medium] Before-hook writes commit even when the update/delete matches no row and the route returns 404. beforeUpdate/beforeDelete run unconditionally inside the transaction and may write via ctx.app.database; when the primary op matches 0 rows it returns null/false without throwing, so the transaction commits the hook's side effects and the 404 is thrown afterward in the route handler. E.g. a beforeDelete that writes an audit row on DELETE /notes/9999 (nonexistent) commits the audit row, then the caller gets 404 — persisted state is inconsistent with the reported outcome. Throw NOT_FOUND inside the transaction on a no-match.

Automated review finding.

[MarioCadenas]

[Medium] creatable lets the client choose the primary key for natural / defaultRandom PKs. creatable excludes only serverGenerated columns, so a uuid().primaryKey().defaultRandom() (or any natural PK) is settable via the create body: POST /:table {id:"chosen-uuid", …} overrides the generated default and lets a caller pick primary keys (id-squatting / prediction) — which, with no per-user authz, any caller can do. id()/bigid() tables are safe. Consider excluding all primary keys from creatable.

Automated review finding.

[MarioCadenas]

[Medium] upsert PK-rewrite is reachable through the typed upsert (carry-forward from #526). beforeUpsert replacements are re-validated by $insertSchema, which still includes natural PKs, and the underlying DataPath.upsert reuses the full payload as ON CONFLICT DO UPDATE SET — so a natural PK + cross-column onConflict rewrites the existing row's PK. Not reachable over HTTP (no upsert route), but a real integrity hole in the programmatic upsert. Fix at the runtime (set should exclude the PK).

Automated review finding.