What "off by default" actually means

"Your data never leaves your device — unless you turn on the optional account layer."
Every local-first product says some version of this sentence, and the sentence is
where the trust either starts or ends, because off by default can mean anything
from "we encrypted it before storing it" to "the endpoint exists and one env var
lights it up." This post takes the phrase apart at the file level: what has to be
true before the claim layer exists at all, what an unconfigured deployment actually
does when a request reaches a claim route, what would be stored if it were ever
enabled, and how anyone can check the claim instead of taking it.

It is a short post on purpose. The claim layer is a small, bounded thing with two
environment variables, a handful of routes and three database tables — small enough
to describe completely, which is the only version of this page worth writing.

1. 1minthe two-variable switch and the half-configured error.
2. 3minwhat each unconfigured path does, route by route.
3. 5minwhat "on" would store, so the off state has a concrete shape.

The switch is two variables, and they are fussy

The claim layer activates when DATABASE_URL is present — that is the code-level
switch — and the moment it is present, a non-empty CLAIM_SECRET becomes
mandatory: the secret lookup throws ('CLAIM_SECRET is required when DATABASE_URL is set') instead of falling back.¹ There is deliberately no
default secret, no generated-per-boot key, and no "works without it" mode. A
deployment can be fully off, or fully on; a half-configured deployment refuses to
run, which is the only safe failure direction for something that encrypts fields.

Both variables live in the local .env file (or the deployment host's environment),
and .env is gitignored — the secrets exist only where you put them, never in the
repository.² The stack has no server code beyond these routes: the
application is a client-side app plus claim-layer route handlers, which is why the
off state is so clean — there is no background worker, cron or queue that could
quietly need the database.

What unconfigured actually does, path by path

The off state is not a banner; it is behaviour at every layer that would otherwise
care:

• Routes. Each claim endpoint checks the feature flag first. Reaching

  POST /api/claim/login on an unconfigured deployment returns 503 with
  { ok: false, error: 'Accounts are not enabled on this deployment.' } — before any
  database access, before any hashing work.³ The guard runs structurally at
  the top of the handler, so an unconfigured deployment cannot leak a partial
  code path: there is nothing behind the 503.

• Crypto. The secret helper returns a sentinel while off — and the function that

  derives real encryption material throws if it is ever called in that state,
  so a bug that forgot to check the flag fails loudly instead of encrypting under a
  placeholder.⁴ This is the difference between a feature that is switched off
  and one that is absent: absent code paths raise.

• Database. No DATABASE_URL, no connection string, no driver instance. The

  claims-disabled world contains zero Postgres traffic — not "read-only", not
  "empty pool": no pool exists.

• UI. Sign-in surfaces render the claims-disabled notice rather than a working

  form; the rest of the app — parsing, analytics, the ask-anything engine — is
  unaffected, because none of it was ever server-dependent. The local-first post
  walks the processing side; this post is about the switch.

The verification is two requests wide: hit a claim route and read the 503; unset the
variables and confirm the app's full feature set still works. Neither needs trust —
they need a browser.

What "on" would store, so the off state has a shape

You cannot judge an off switch without knowing what it controls, so here is the
entire inventory of the layer it gates — three tables:⁵

Passwords are argon2id hashes; the encryption and HMAC keys derive from
CLAIM_SECRET with domain separation; profiles hold aggregates, never raw
message or contact content.⁶ The sync tier — a separate, additionally
opt-in feature — is a fourth kind of thing entirely (encrypted lean blobs, media
never stored) and is documented in the security post's custody section.

That is the whole thing the phrase "off by default" is withholding: not a shadow
profile, not a warm database, not a reserved ID — three tables' worth of account
plumbing that does not exist until you supply both keys. And the default posture,
for every deployment including this one you are reading, is the other column:
nothing configured, nothing listening, nothing stored.

Questions this comes up

The local-first post for what runs on the device; the security post for custody,
crypto and erasure in depth; the counting post for why none of the numbers depend on
this layer either.

¹: apps/web-next/src/lib/claim/env.ts — claimsEnabled() keys off
DATABASE_URL; the CLAIM_SECRET lookup throws 'CLAIM_SECRET is required when DATABASE_URL is set' when the layer is on but the secret is empty.
²: Root .gitignore — .env, .env.* excluded (!.env.example
excepted); no default secret values exist in source.
³: apps/web-next/src/app/api/claim/login/route.ts — feature flag checked
first; unconfigured deployments answer 503 'Accounts are not enabled on this deployment.' before any database access.
⁴: env.ts — the offline sentinel is never usable for real crypto: the
key-deriving helper throws while the layer is disabled, so a forgotten flag check
fails loudly.
⁵: db/schema.ts — users, sessions, profiles (plus the separately
opt-in sync tables, which are not part of the claim layer's three).
⁶: SECURITY.md claim-layer sections — argon2id password hashing,
AES-256-GCM field encryption with CLAIM_SECRET-derived keys and domain-separated
HMAC email index, opaque session tokens stored as hashes, profile packs containing
owner-side aggregates only.