feat(policy): add optional error code to @@allow/@@deny attributes

[Azzerty23]

What this PR does

Adds an optional errorCode argument to @@allow and @@deny policy attributes. When an operation is rejected, every matching rule's code is collected and surfaced on ORMError.policyCodes, giving callers a reliable way to handle specific policy violations programmatically.

Fixes #1723

Supersedes #2636 — same feature, reworked internals. See Changes since #2636 below.

---

Schema syntax

The third argument accepts a string literal or an enum value:

enum OrderError {
  OUT_OF_STOCK
  CREDIT_EXCEEDED
  INVALID_STATUS_TRANSITION
}

model Order {
  ...
  @@deny('create',        total > auth().creditLimit,                            CREDIT_EXCEEDED)
  @@deny('post-update',   stock < 0,                                             OUT_OF_STOCK)
  @@deny('post-update',   before().status == 'shipped' && status != 'delivered', INVALID_STATUS_TRANSITION)
  @@deny('create,update', auth().accountStatus == 'suspended',                   'ACCOUNT_SUSPENDED')
  @@deny('read',          archived == true,                                      'ARCHIVED_ORDER')
  @@deny('delete',        auth().role != 'admin',                                'ADMIN_ONLY')
}

Error surfacing

ORMError.policyCodes contains the codes of all matching rules (not just the first), so a single failed operation can carry multiple codes:

try {
  await db.order.create({ data: { ... } });
} catch (err) {
  if (err instanceof ORMError && err.reason === ORMErrorReason.REJECTED_BY_POLICY) {
    // err.policyCodes: e.g. ['CREDIT_EXCEEDED', 'ACCOUNT_SUSPENDED']
  }
}

Scope: which operations surface codes

Operation	Without error code	With error code
create / post-update	REJECTED_BY_POLICY (no codes)	REJECTED_BY_POLICY + policyCodes
update / delete / findFirstOrThrow / findUniqueOrThrow	NOT_FOUND	REJECTED_BY_POLICY + policyCodes
findFirst / findUnique	returns null	returns null (never throws)
findMany	returns []	returns [] (never throws)

create and post-update piggyback code collection on the policy checks that already run — no additional round-trips. update/delete/*OrThrow use filter-based enforcement, so distinguishing "not found" from "denied" requires a diagnostic query; it only runs when at least one rule on the model carries a code, so the opt-in is implicit via the schema.

Performance opt-out

// plugin-level: off for all queries on this client
new PolicyPlugin({ fetchPolicyCodes: false })

// query-level: off (or back on) for a single call
await db.order.update({ where: { id }, data: { ... }, fetchPolicyCodes: false });
await db.order.update({ where: { id }, data: { ... }, fetchPolicyCodes: true });  // overrides plugin-level false

Backward compatibility

Purely additive. No changes to the existing error message format or ORMError structure. Callers that don't use error codes see no behavioral change. policyCodes is undefined (not []) when no codes are present.

---

Changes since #2636

The feature surface is unchanged; the plumbing that carries per-call context (fetchPolicyCodes, originating ORM operation) from the client API down to onKyselyQuery hooks was rewritten:

• SQL-comment query context instead of an AsyncLocalStorage bridge. The ORM now serializes a QueryContext (model, CRUD kind, top-level ORM operation, plugin args) as a trailing -- $$context: comment on generated queries; the executor deserializes and strips it before plugins and the driver see the SQL. This removes the node:async_hooks dependency entirely (no browser-bundle concerns) and makes the context robust across transaction/executor boundaries.
• Fewer round-trips. Post-mutation rejection determination and diagnostics are merged into a single query where possible.
• MySQL update pre-load: selective read-policy bypass. On dialects without RETURNING, the ORM pre-loads entity IDs with a SELECT before a top-level UPDATE. That pre-load must bypass the policy read filter (otherwise a read-denied row silently becomes NOT_FOUND, masking update-deny codes) — but only the policy filter. It is now tagged with a bypassReadPolicy query context that the policy plugin honors, while every other onKyselyQuery plugin (e.g. soft-delete) still transforms the query.

🤖 Generated with Claude Code

https://claude.ai/code/session_011wibXxJtELqNeDYwu3gyTU

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 465204f5-fa7d-4311-8f21-f5194330574b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[gitguardian]

⚠️ GitGuardian has uncovered 2 secrets following the scan of your pull request.

Please consider investigating the findings and remediating the incidents. Failure to do so may lead to compromising the associated services or software components.

Since your pull request originates from a forked repository, GitGuardian is not able to associate the secrets uncovered with secret incidents on your GitGuardian dashboard.
Skipping this check run and merging your pull request will create secret incidents on your GitGuardian dashboard.

🔎 Detected hardcoded secrets in your pull request

GitGuardian id	GitGuardian status	Secret	Commit	Filename
33485392	Triggered	Generic Private Key	582b93b	packages/cli/test/proxy.test.ts	View secret
17897114	Triggered	Generic Password	23a8253	.github/workflows/build-test.yml	View secret

🛠 Guidelines to remediate hardcoded secrets

1. Understand the implications of revoking this secret by investigating where it is used in your code.
2. Replace and store your secrets safely. Learn here the best practices.
3. Revoke and rotate these secrets.
4. If possible, rewrite git history. Rewriting git history is not a trivial act. You might completely break other contributing developers' workflow and you risk accidentally deleting legitimate data.

To avoid such incidents in the future consider

• following these best practices for managing and storing secrets including API keys and other credentials
• install secret detection on pre-commit to catch secret before it leaves your machine and ease remediation.

---

^{🦉 GitGuardian detects secrets in your source code to help developers and security teams secure the modern development process. You are seeing this because you or someone else with access to this repository has authorized GitGuardian to scan your pull request.}