feat(objectql): mask password fields on the generic read path (#2036)

A `password`-typed field on a non-auth object round-tripped plaintext
through the generic CRUD engine — neither hashed nor masked the way
`secret` is. Someone modeling a `password` field on a custom object
reasonably expects credential-grade handling; they silently got plaintext
storage and plaintext reads.

Mask `password` to SECRET_MASK on the generic read path (find/findOne, and
$expand which re-enters find), mirroring `secret`. Unlike `secret`, a
password value stays plaintext at rest — no encryption, no sys_secret row,
no CryptoProvider required. An echoed mask is dropped on write so a form
round-trip does not overwrite the stored value. Objects marked
`managedBy: 'better-auth'` are exempt so the auth subsystem's own reads
(which go through the engine) still see the stored value; a platform-objects
pin asserts no shipped identity object even declares a `password` field
today. `ObjectSchema.create()` now warns (non-fatally, deduped per object)
when a `password` field is declared on a non-auth object, steering authors
to `secret` or the auth subsystem.

Decision and rationale recorded in ADR-0100; the aggregate() masking gap
(pre-existing for `secret` too) is noted there as a follow-up.

- objectql: add collectMaskedReadFields; wire mask/echoed-mask paths
- spec: author-time warning in ObjectSchema.create(); correct field.zod docs
- tests: password-masking units, warning units, platform-objects pin,
  dogfood field-zoo f_password upgraded present -> masked
- examples: field-zoo label 'Password (one-way hash)' -> '(masked on read)'

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QJrKxe1jXGudFT3nUks1yN

Author: claude

docs/adr/0100-password-field-masking-in-generic-read-path.md

@@ -0,0 +1,96 @@
+# ADR-0100: Mask `password` Fields on the Generic Read Path
+
+- **Status**: Accepted
+- **Date**: 2026-07-18
+- **Issue**: #2036 (found via #2033 / #2025 / #2028 field-type round-trip work)
+- **Relates to**: ADR-0077 (authoring-surface boundary), ADR-0078 (no silently
+  inert metadata), ADR-0069 (enterprise authentication hardening)
+
+## Context
+
+A `password`-typed field declared on a **non-auth** object (e.g.
+`showcase_field_zoo.f_password`) round-tripped **plaintext** through the generic
+CRUD engine: it was stored as-is and read back verbatim over the data API. This
+is unlike the `secret` field channel, which encrypts on write into `sys_secret`
+and masks to `SECRET_MASK` (`••••••••`) on read, so plaintext never leaves the
+engine outside a privileged `resolveSecret` call.
+
+This is a low-code platform where field types are author-driven (often by an AI).
+Someone modeling a `password` field on a custom object reasonably expects
+credential-grade handling; today they silently got plaintext storage and
+plaintext reads, a runtime/security trap the static gates do not catch. The
+real one-way hashing lives entirely in the auth subsystem (better-auth endpoints,
+the hashed `sys_account.password` `text` column) and never touches an authored
+`password` field.
+
+The issue framed four options: (1) mask on read like `secret`; (2) hash on write
+in the generic path; (3) an author-time guard; (4) document as auth-only. Option
+2 is the wrong fit — one-way hashing only makes sense for credential
+*verification*, which a non-auth object never does, and doing it in the engine
+would stand up a second, unmanaged credential store that violates the
+"auth subsystem owns credentials" boundary. Option 4 leaves the silent trap in
+place. This ADR adopts **1 + 3**.
+
+## Decision
+
+1. **Mask on read, everywhere the generic path returns rows.** A `password`
+   field on a generic object is masked to `SECRET_MASK` in `find` / `findOne`
+   (and therefore in `$expand`, which re-enters `find`). The read set is computed
+   by `collectMaskedReadFields` (`packages/objectql/src/secret-fields.ts`), which
+   returns every `secret` field plus every `password` field; `maskSecretFields`
+   in `engine.ts` consumes it. `secret` behavior is unchanged.
+
+2. **Plaintext at rest, by design.** Unlike `secret`, a `password` value is
+   **not** encrypted and gets **no** `sys_secret` row — it is stored verbatim.
+   Masking is a read-path transform only. This keeps the change minimal and
+   avoids standing up a second credential store; it also means a `password`
+   field needs no `CryptoProvider` (no fail-closed throw). Authors who need
+   reversible encryption-at-rest should use `secret`.
+
+3. **Echoed-mask write guard.** Because a read now returns `SECRET_MASK`, a
+   client that reads a record and PATCHes it back would otherwise overwrite the
+   stored value with the literal mask. `encryptSecretFields` drops any masked
+   field (secret or password) whose incoming value equals `SECRET_MASK`, so an
+   unchanged round-trip is a no-op. The one accepted cost: the literal string
+   `••••••••` cannot itself be stored as a password via an echoing client.
+
+4. **`managedBy: 'better-auth'` exemption.** The auth subsystem reads its
+   identity rows through the engine's `find`/`findOne` (the better-auth ObjectQL
+   adapter). Masking a credential column there would break login. Objects marked
+   `managedBy: 'better-auth'` are therefore exempt from password masking. Today
+   this is a safety net, not load-bearing: no shipped identity object even
+   declares a `password`-typed field (`sys_account.password` is a hashed `text`
+   column), pinned by a platform-objects test so retyping it becomes a
+   deliberate decision rather than a silent login break.
+
+5. **Non-fatal author-time warning (ADR-0077/0078).** `ObjectSchema.create()`
+   emits a `console.warn` (deduped per object name) when a `password` field is
+   declared on a non-`better-auth` object, steering authors to `Field.secret`
+   for reversible machine credentials or to the auth subsystem for login
+   credentials. It is a *warning*, not a build error: `password` now has a
+   defined generic-path contract (so ADR-0078 does not compel an error), and the
+   field-zoo example intentionally exercises every field type — a hard error
+   would be self-inflicted breakage. Raw `.parse()` stays silent, since it also
+   loads persisted metadata and `create()` is the authoring surface (ADR-0077).
+
+## Consequences
+
+- Edit forms that prefill from a read now show the mask for `password` fields —
+  identical to the existing `secret` UX. Unchanged-value saves are protected by
+  the echoed-mask guard (Decision 3).
+- The generic read path no longer leaks credential plaintext for `password`
+  fields; the field-zoo HTTP round-trip pins this (`f_password` upgraded from
+  `present` to `masked`).
+- This ADR also retroactively documents the `secret` field channel, resolving
+  the dangling "ADR (secret field channel)" references in `field.zod.ts` and
+  `secret-fields.ts`.
+
+## Non-goals / follow-ups
+
+- **`aggregate()` masking gap.** `aggregate()` masks neither `secret` nor
+  `password` — a pre-existing gap for `secret`. Post-hoc masking of aggregate
+  output would corrupt group keys; the correct fix is to *reject* aggregations
+  that reference a credential field. Tracked as a separate follow-up issue, not
+  addressed here.
+- **Hashing / verification for authored `password` fields** — explicitly out of
+  scope (Decision 2). Credential verification belongs to the auth subsystem.

examples/app-showcase/src/data/objects/field-zoo.object.ts

@@ -35,7 +35,7 @@ export const FieldZoo = ObjectSchema.create({
     f_email: Field.email({ label: 'Email', searchable: true }),
     f_url: Field.url({ label: 'URL' }),
     f_phone: Field.phone({ label: 'Phone' }),
-    f_password: Field.password({ label: 'Password (one-way hash)' }),
+    f_password: Field.password({ label: 'Password (masked on read)' }),
     f_secret: Field.secret({ label: 'Secret (encrypted at rest)' }),
 
     // ── Rich content ─────────────────────────────────────────────────────

packages/objectql/src/core.ts

@@ -75,6 +75,7 @@ export {
   isSecretRef,
   parseSecretRef,
   collectSecretFields,
+  collectMaskedReadFields,
 } from './secret-fields.js';
 
 // Utilities

packages/objectql/src/engine.ts

@@ -19,6 +19,7 @@ import { IRealtimeService, RealtimeEventPayload } from '@objectstack/spec/contra
 import type { ICryptoProvider, CryptoHandle } from '@objectstack/spec/contracts';
 import {
   collectSecretFields,
+  collectMaskedReadFields,
   makeSecretRef,
   parseSecretRef,
   isSecretRef,
@@ -1363,19 +1364,28 @@ export class ObjectQL implements IDataEngine {
   }
 
   /**
-   * Encrypt any `secret`-typed fields on `row` in place before it reaches the
-   * driver. Each plaintext is wrapped by the ICryptoProvider, persisted as a
-   * `sys_secret` row, and replaced on `row` by an opaque ref. Cleartext never
-   * reaches the business table.
+   * Normalize credential fields on `row` in place before it reaches the driver.
+   *
+   * Two channels share the read mask ({@link SECRET_MASK}) but differ on write
+   * (see ADR-0100):
+   *
+   *  - **`secret`** — encrypted: each plaintext is wrapped by the ICryptoProvider,
+   *    persisted as a `sys_secret` row, and replaced on `row` by an opaque ref.
+   *    Cleartext never reaches the business table.
+   *  - **`password`** (generic, non-`better-auth`) — plaintext at rest: stored
+   *    verbatim, no encryption and no `sys_secret` row. Only the echoed-mask drop
+   *    below applies to it.
    *
    * Rules:
-   *  - No secret fields on the object ⇒ no-op (fast path, no crypto cost).
-   *  - `null`/`undefined` value ⇒ left as-is (clears the secret).
-   *  - Value already a ref (re-save of an unchanged ref) ⇒ left as-is.
-   *  - Value equal to the read mask ⇒ dropped, so a form round-trip that
-   *    echoes the mask does not overwrite the stored secret.
-   *  - **Fail-closed:** any other value with no CryptoProvider registered, or
-   *    no reachable `sys_secret` store, THROWS — never persists cleartext.
+   *  - Any masked field (secret or password) whose value equals the read mask ⇒
+   *    the key is dropped, so a form round-trip that echoes the mask does not
+   *    overwrite the stored value.
+   *  - No secret fields on the object ⇒ no further work (fast path, no crypto).
+   *  - `null`/`undefined` secret value ⇒ left as-is (clears the secret).
+   *  - Secret value already a ref (re-save of an unchanged ref) ⇒ left as-is.
+   *  - **Fail-closed:** any other secret value with no CryptoProvider registered,
+   *    or no reachable `sys_secret` store, THROWS — never persists cleartext.
+   *    (A `password` field needs no CryptoProvider — it is stored as-is.)
    */
   private async encryptSecretFields(
     object: string,
@@ -1385,6 +1395,17 @@ export class ObjectQL implements IDataEngine {
   ): Promise<void> {
     if (!row || typeof row !== 'object') return;
     const schema = this._registry.getObject(object);
+
+    // Echoed-mask drop for every field the read path masks (secret + generic
+    // password). The read path returns SECRET_MASK; a client that PATCHes it
+    // back means "unchanged", so drop the key rather than persist the literal
+    // mask. Doing this up front keeps the better-auth exemption in one place
+    // (collectMaskedReadFields) and covers objects that have a password field
+    // but no secret field. (#2036, ADR-0100)
+    for (const field of collectMaskedReadFields(schema)) {
+      if (field in row && row[field] === SECRET_MASK) delete row[field];
+    }
+
     const secretFields = collectSecretFields(schema);
     if (secretFields.length === 0) return;
 
@@ -1394,12 +1415,6 @@ export class ObjectQL implements IDataEngine {
 
       if (value === null || typeof value === 'undefined') continue; // clear
       if (isSecretRef(value)) continue; // already encrypted ref
-      if (value === SECRET_MASK) {
-        // The read path masks secrets to SECRET_MASK; a form that echoes it
-        // back means "unchanged". Drop the key so the stored secret survives.
-        delete row[field];
-        continue;
-      }
 
       if (!this.cryptoProvider) {
         throw new Error(
@@ -1446,20 +1461,23 @@ export class ObjectQL implements IDataEngine {
   }
 
   /**
-   * Mask `secret`-typed fields on read so plaintext never leaves the engine
-   * through the normal query path. A set secret becomes {@link SECRET_MASK};
-   * an unset one stays `null`. Privileged callers that genuinely need the
-   * plaintext use {@link resolveSecret} against the stored ref.
+   * Mask credential fields on read so plaintext never leaves the engine through
+   * the normal query path. Covers `secret` fields (always) and `password` fields
+   * on generic, non-`better-auth` objects (see {@link collectMaskedReadFields}
+   * and ADR-0100). A set value becomes {@link SECRET_MASK}; an unset one stays
+   * `null`. Privileged callers that genuinely need a secret's plaintext use
+   * {@link resolveSecret} against the stored ref; a `password` field is stored
+   * as plaintext at rest, so its cleartext is only ever reachable off this path.
    */
   private maskSecretFields(object: string, rows: any): void {
     if (!rows) return;
     const schema = this._registry.getObject(object);
-    const secretFields = collectSecretFields(schema);
-    if (secretFields.length === 0) return;
+    const maskedFields = collectMaskedReadFields(schema);
+    if (maskedFields.length === 0) return;
     const list = Array.isArray(rows) ? rows : [rows];
     for (const row of list) {
       if (!row || typeof row !== 'object') continue;
-      for (const field of secretFields) {
+      for (const field of maskedFields) {
         if (!(field in row)) continue;
         row[field] = row[field] == null ? null : SECRET_MASK;
       }

packages/objectql/src/index.ts

@@ -102,6 +102,7 @@ export {
   isSecretRef,
   parseSecretRef,
   collectSecretFields,
+  collectMaskedReadFields,
 } from './secret-fields.js';
 
 // Export Utilities

packages/objectql/src/secret-fields.test.ts

@@ -232,3 +232,91 @@ describe('objectql secret-field channel', () => {
     }
   });
 });
+
+// A generic (non-better-auth) object with a `password` field. Unlike `secret`,
+// it is plaintext at rest but masked on read — no crypto involved (ADR-0100).
+const deviceObject = {
+  name: 'device', label: 'Device',
+  fields: {
+    id: { name: 'id', label: 'ID', type: 'text' as const },
+    name: { name: 'name', label: 'Name', type: 'text' as const },
+    admin_password: { name: 'admin_password', label: 'Admin Password', type: 'password' as const },
+  },
+};
+
+// An identity table the auth subsystem owns: `managedBy: 'better-auth'` exempts
+// its `password` field from masking so better-auth's own reads see the value.
+const authUserObject = {
+  name: 'authy_user', label: 'Auth User', managedBy: 'better-auth' as const,
+  fields: {
+    id: { name: 'id', label: 'ID', type: 'text' as const },
+    password: { name: 'password', label: 'Password', type: 'password' as const },
+  },
+};
+
+async function buildPasswordEngine() {
+  // Deliberately NO CryptoProvider — a password field must not require one.
+  const engine = new ObjectQL();
+  const { driver, stores } = makeMemoryDriver();
+  engine.registerDriver(driver, true);
+  await engine.init();
+  engine.registry.registerObject(deviceObject as any);
+  engine.registry.registerObject(authUserObject as any);
+  return { engine, stores };
+}
+
+describe('objectql password-field masking (ADR-0100)', () => {
+  let ctx: Awaited<ReturnType<typeof buildPasswordEngine>>;
+  beforeEach(async () => { ctx = await buildPasswordEngine(); });
+
+  it('stores plaintext at rest (no crypto), but masks on find / findOne', async () => {
+    const created = await ctx.engine.insert('device', { name: 'router', admin_password: 'hunter2' });
+
+    // At rest: the driver row holds the verbatim plaintext, and nothing was
+    // written to sys_secret (no encryption channel for password).
+    const stored = ctx.stores.get('device')!.get(created.id) as any;
+    expect(stored.admin_password).toBe('hunter2');
+    expect(ctx.stores.get('sys_secret')?.size ?? 0).toBe(0);
+
+    // On read: the generic path never echoes the plaintext.
+    const viaFind = (await ctx.engine.find('device', { where: { id: created.id } }))[0] as any;
+    expect(viaFind.admin_password).toBe(SECRET_MASK);
+    const viaOne = await ctx.engine.findOne('device', { where: { id: created.id } }) as any;
+    expect(viaOne.admin_password).toBe(SECRET_MASK);
+  });
+
+  it('an unset password reads back as null, not the mask', async () => {
+    const created = await ctx.engine.insert('device', { name: 'router', admin_password: null });
+    const viaOne = await ctx.engine.findOne('device', { where: { id: created.id } }) as any;
+    expect(viaOne.admin_password).toBeNull();
+  });
+
+  it('echoing the read mask back does NOT overwrite the stored password', async () => {
+    const created = await ctx.engine.insert('device', { name: 'router', admin_password: 'keep-me' });
+
+    // Form round-trip: user renames the device, the masked field echoes back.
+    await ctx.engine.update('device', { id: created.id, name: 'gateway', admin_password: SECRET_MASK });
+
+    const stored = ctx.stores.get('device')!.get(created.id) as any;
+    expect(stored.name).toBe('gateway');
+    expect(stored.admin_password).toBe('keep-me'); // unchanged plaintext
+  });
+
+  it('updating with a real new value replaces the stored plaintext', async () => {
+    const created = await ctx.engine.insert('device', { name: 'router', admin_password: 'old-pw' });
+    await ctx.engine.update('device', { id: created.id, admin_password: 'new-pw' });
+
+    const stored = ctx.stores.get('device')!.get(created.id) as any;
+    expect(stored.admin_password).toBe('new-pw');
+    // And a read still masks it.
+    const viaOne = await ctx.engine.findOne('device', { where: { id: created.id } }) as any;
+    expect(viaOne.admin_password).toBe(SECRET_MASK);
+  });
+
+  it('better-auth identity tables are exempt: their password field is NOT masked on read', async () => {
+    const created = await ctx.engine.insert('authy_user', { password: 'hashed-by-auth' });
+    const viaOne = await ctx.engine.findOne('authy_user', { where: { id: created.id } }) as any;
+    // Masking here would break login — the auth subsystem must read its own value.
+    expect(viaOne.password).toBe('hashed-by-auth');
+  });
+});

packages/objectql/src/secret-fields.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 /**
- * Secret-field channel — helpers for the `secret` FieldType.
+ * Credential-field channels — helpers for the `secret` and `password` FieldTypes.
  *
  * A `secret` field (DB password, API key, token) is **reversible**: the engine
  * encrypts it on write via the registered `ICryptoProvider`, persists the
@@ -10,8 +10,19 @@
  * the Settings subsystem (`sys_setting.value_enc → sys_secret.id`), generalized
  * to object fields.
  *
- * Contrast with `password` — a one-way hash owned by the auth subsystem, never
- * decrypted. The two never share a code path.
+ * A `password` field on a **generic** (non-`better-auth`) object is **plaintext
+ * at rest** but **masked on read** — the engine stores the value verbatim (no
+ * encryption, no `sys_secret` row) yet returns {@link SECRET_MASK} through the
+ * normal query path, so cleartext never leaves the engine. This closes #2036,
+ * where a `password` field round-tripped plaintext. See ADR-0100. The two types
+ * share only the read mask ({@link collectMaskedReadFields}); their write paths
+ * differ (secret encrypts, password is left untouched).
+ *
+ * The auth subsystem's own credentials are a third, separate channel: better-auth
+ * one-way hashes them into identity tables (`sys_account.password`, a hashed
+ * `text` column) off the generic CRUD path. Objects it owns carry
+ * `managedBy: 'better-auth'` and are exempt from password masking so login reads
+ * still see the stored hash.
  */
 
 import type { ServiceObject } from '@objectstack/spec/data';
@@ -59,3 +70,30 @@ export function collectSecretFields(schema: ServiceObject | undefined | null): s
   }
   return out;
 }
+
+/**
+ * Collect the names of fields that must be masked to {@link SECRET_MASK} on the
+ * generic read path: every `secret` field, plus every `password` field — the
+ * latter only when the object is **not** `managedBy: 'better-auth'`.
+ *
+ * The better-auth exemption is deliberate: the auth subsystem reads its identity
+ * rows through the engine's find/findOne, and masking a credential column there
+ * would break login. Today no identity object even declares a `password`-typed
+ * field (`sys_account.password` is a hashed `text` column), but the guard keeps
+ * masking safe if that ever changes. See ADR-0100.
+ *
+ * Returns an empty array when the schema has no fields or no maskable fields, so
+ * callers can fast-path on `length === 0`.
+ */
+export function collectMaskedReadFields(schema: ServiceObject | undefined | null): string[] {
+  const fields = (schema as any)?.fields as Record<string, { type?: string }> | undefined;
+  if (!fields) return [];
+  const isBetterAuth = (schema as any)?.managedBy === 'better-auth';
+  const out: string[] = [];
+  for (const [name, def] of Object.entries(fields)) {
+    if (!def) continue;
+    if (def.type === 'secret') out.push(name);
+    else if (def.type === 'password' && !isBetterAuth) out.push(name);
+  }
+  return out;
+}