Skip to content
Active Record
Esc
↑↓navigate↵open⌘Jpreview
On this page

Security

Active Record prevents SQL injection and casts what a request sends, but authorization and which fields a request may set are up to your app.

What Active Record protects against

  • SQL injection. Every value is bound as a parameter, never written into SQL text. Identifiers come only from a Model’s declared attributes, and are quoted. Raw SQL is only possible through the sql tagged template, which binds every value it’s given.
  • Values that aren’t what TypeScript says. A value from JSON, a form, or a query string is cast to its attribute’s type when it’s assigned or used in a condition, and anything ambiguous is refused: "false" can’t save true. See Attribute types.
  • Prototype pollution and inherited names. Attributes and associations are looked up only by the Model’s own names, so __proto__, constructor, and other names every object has are unknown names, and Object.prototype is never written to.
  • Secrets in logs and errors. Values of attributes named like passwords, tokens, keys, and emails are hidden from onQuery listeners and from error messages. See Logging.
  • One request’s data reaching another. Nothing about a request (a D1 Session, a listener) is ever stored on a Model class. See Database resolution.
  • Passwords kept in clear. A secure password is saved only as a salted digest. toJSON() leaves out the password, its digest, and a secure token, and authenticateBy takes as long whether or not a record matches, so its timing doesn’t tell anyone which accounts exist.
  • Forged or reused links. A signed id, a token for a purpose, or a reset token is signed with HMAC-SHA256, so a changed or made-up one finds nothing. It finds its record only for its purpose, until it expires, and through a Relation’s conditions and default scopes. A token holds a fingerprint of the value it depends on, never the value, and a reset token stops working once the password changes.
  • Denial of service through parsing. The patterns that read numbers and dates are linear, so a long value can’t use up a Worker’s CPU time.

What’s left to your app

  • Choosing which fields a request may set, with permit, destructuring, or a schema. See Untrusted input.
  • An untrusted null in a condition. findBy({ token: null }) matches rows whose token is NULL. Check a value’s type before querying with it.
  • How strong your password hash is. The default, PBKDF2-SHA256, runs 100,000 iterations, the most Workers allow and about a sixth of OWASP’s 600,000. Each hash also takes about 10–40 ms of CPU time, more than the Workers Free plan’s 10 ms. For a stronger hash, give securePassword an algorithm of your own, as Choosing the hash shows, on a plan with the CPU time it needs.
  • Keeping the signing secret secret. Anyone with SECRET_KEY_BASE can sign tokens for any record. Set it with wrangler secret put, never in wrangler.jsonc or the repository, and rotate it if it leaks. A signed id or a token can be used again until it expires, so give one that grants access a short expiresIn. A token isn’t tied to a database, so with a database per tenant, put the tenant in its purpose or dependsOn.
  • Authorization. Whether this user may read or change this record is your app’s decision.
  • Formats and ranges. Casting checks types, not meaning: use validations.
  • Bare values inside sql fragments. A value with no attribute isn’t hidden from listeners. Write it as column("token").value(token), and it’s filtered like the attribute’s other values.
  • Which associations a request may include. A name from ?include= only matches a Model’s own associations, but each level of a chain adds a subquery. Allow only the include paths you mean.

Guarantees, and the tests that check them

The library’s guarantees are tested against a real D1 database (through Miniflare), and CI’s by a test that reads its workflows. CI runs every test on every change.

Guarantee Tests
Values are bound, identifiers are quoted, and plain strings are refused as SQL sql-safety
Assigned and condition values are cast, or refused, in linear time attribute-casting
Naming an attribute, table or key takes linear time in the name’s length naming
Only a Model’s own names are attributes or associations name-lookups
permit keeps only the named attributes, reading own keys only permit
Passwords are saved only as digests, never sent by toJSON(), and checked in the same time whether a record matches or not secure-password
Signed ids and tokens find their record only when unchanged, for their purpose, before they expire, and through a Relation’s conditions signed-ids, token-for
Filtered attributes’ values never reach listeners or errors filter-attributes
A request’s database stays with that request current-database
Names, assigned values, conditions, bound text, permitted keys, and JSON hold for any input, not only chosen ones properties (*-properties.test.ts, generated with fast-check)
The tests cover at least 90% of the library’s and command line’s branches, and CI fails below that coverage
CI’s actions are pinned, and release jobs run no install scripts ci-workflows

Supply chain

  • No runtime dependencies in your Worker. The library is one package, @forestfuture/active-record, with its adapters inside it. On D1 it imports no other package, so no other package’s compromise can reach your Worker through it. On Postgres it imports pg, the driver your app installs itself. The command line, a development tool, depends on jiti to load your Models; installing the library installs it, and your Worker doesn’t bundle it.
  • The command line runs your Model files. active-record schema, the generators, and the console load them to find your Models, so code at a Model file’s top level runs each time, active-record schema --check in CI included.
  • Releases are built by CI. The npm package is built and published by the repository’s release workflow, never from a laptop, so what’s on npm is what’s in the repository. Publishing uses npm’s trusted publishing, so no npm token is stored anywhere, and each version carries a provenance attestation linking it to its commit. Version 0.1.0 was published before that was set up, with a one-time token, and has no attestation (#109); 0.1.1 and later do.
  • CI is pinned. Every third-party GitHub Action is pinned to a commit, not a tag that could be moved, because a moved tag would run someone else’s code in the job that publishes. A test fails if one isn’t.
  • Release jobs run no install scripts. The jobs that decide, build, version, and publish a release install dependencies without running their install scripts and without a shared cache, so a compromised development dependency can’t change what’s built or published.
  • Dependencies are watched. Dependabot proposes updates weekly, waiting a week after each release, since a compromised release is usually caught within days. pnpm audit is part of each security review.

Review log

Each security review adds an entry here: what it covered, how, what it found, and what it didn’t cover. These are the project’s own reviews, not an independent audit.

2026-10-04: the library, its command line, and CI

Scope: the library (src/), the command line (cli/), the CI and release workflows, and the development dependencies.

Method:

  • a security review of the whole codebase with Sentry’s security-review skill (OWASP-based), briefed on a library’s risks: what happens when an app passes untrusted input into it;
  • untrusted inputs probed against a real D1 database: prototype keys, wrong types, null, long values;
  • a dependency audit with Trail of Bits’ supply-chain-risk-auditor and pnpm audit;
  • each fix then reviewed with Trail of Bits’ differential-review.

Findings, all fixed:

Severity Finding Issue
High Assigned values weren’t checked at runtime: "false" saved as true for a boolean #81
High The publish job used actions pinned by movable tags, and ran install scripts #80
High Found while fixing #81: a pattern that backtracked on long numbers (ReDoS) #81
Medium No protection against mass assignment, and no guidance on an untrusted null #82
Medium Bound values, secrets included, reached onQuery listeners and errors #83
Low Inherited names (constructor, __proto__) caused errors instead of being unknown names #84
Low Development dependency advisories, and unescaped config values in generated code #85

Not covered: the source of the third-party Actions at their pinned commits; D1 and workerd themselves; isolation between concurrent requests beyond the existing tests; apps’ own code.

2026-10-10: CodeQL’s alerts on the public repository

Scope: the library (src/), the command line (cli/) and the tests, as CodeQL’s default setup (JavaScript/TypeScript and Actions) scans them on every push and weekly.

Method: each alert from the first scans of main, read against the code, then either fixed with a test or dismissed with a written reason on the alert. Property-based tests (#122) then generated inputs for the places untrusted input reaches the library.

Findings:

Severity Finding Outcome Link
High Naming an attribute, table or key took quadratic time in the name’s length (ReDoS) Fixed test-first, and checked against the old rule on every short string #116, alert 1
High A test helper strips HTML tags from the guide’s own pages with a regular expression Dismissed: test-only code, and its output is never rendered alert 2
Medium The command line writes a column’s default into generated source (two alerts) Dismissed as false positives: every value goes through JSON.stringify or an identifier check, then is only data alert 3, alert 4
Low Found while triaging alert 4: a __proto__ key in a JSON column default is lost from the generated schema Fixed, with a generated property as its test #119
Low Found by the generated tests: refusing a value with no JSON form and no string form threw Cannot convert object to primitive value first (only code can assign one) Fixed, with the property that found it #122

Not covered: the Scorecard findings, which are about the project’s practices, not its code, and the dependencies’ own code.

2026-10-25: before 0.5.0

Scope: the changes to the library (src/), the command line (cli/), and CI since the 2026-10-04 review: Models extending ApplicationRecord (#232), withSession (#220), preloading in one batch (#217), stored dates (#73, #159, #216), error messages (#88), column().value() (#142), and the console (#104).

Method:

  • a security review of those changes with Sentry’s security-review skill (OWASP-based), tracing each untrusted input (a request’s cookie or header, ?include= names, assigned values, stored cells) to where the library uses it;
  • Trail of Bits’ differential-review of #232’s change before it merged.

Findings:

Severity Finding Outcome Link
Low active-record schema wrote a class’s name into generated source unchecked Fixed before merging: a name that isn’t an identifier is refused #234
Low active-record schema --check wrote a placeholder schema when there was none Fixed before merging: --check writes nothing #234
Low A chain of includes named in a request nests a subquery per level Documented: allow only the include paths you mean #235
Low A bookmark D1 can’t use, in a forged or planted cookie, failed every request carrying it Fixed: the Session starts again from start, checked against a real D1 #237

Not covered: D1 and workerd themselves; the dependencies’ code; apps’ own code.

Reporting a vulnerability

Please report a security problem privately, as the security policy describes, never in a public issue.

Last updated on