fix(dev): eliminate three fixed startup log warnings so official examples boot clean (#3420)

`os dev` on the stock showcase printed three fixed noise sources on every
boot, training users to ignore warnings (cry-wolf). Clear all three:

1. field-zoo password warning — ObjectSchema.create() warned that
   showcase_field_zoo.f_password declares `password` on a non-auth object,
   yet offered no way to express the "this is intended" its own text invited.
   Add a field-level `ackPlaintextMasking: true` opt-out (ADR-0100) that skips
   the warning for a deliberately-masked field, and set it on field-zoo's demo
   field. The warning text now points authors at the flag.

2. Better Auth well-known warning (printed twice) — @better-auth/oauth-provider
   warned "Please ensure '/.well-known/oauth-authorization-server/api/v1/auth'
   exists…" even though registerOidcDiscoveryRoutes already mounts those
   documents at the issuer root (RFC 8414 §3). Silence the false positive with
   the documented `silenceWarnings.oauthAuthServerConfig` option; gating the
   emitter also removes the duplicate print.

3. Registry re-register output — `[Registry] Overwriting package…` and
   `Re-registering owned object…` are normal rebuild/HMR/seed-replay paths but
   were emitted via console.warn (always on). Route them through a new
   debug-only SchemaRegistry.debug() so they stay out of the default 'info'
   boot log while remaining available at logLevel 'debug'.

Adds spec tests for the ackPlaintextMasking opt-out (suppress, partial-ack,
warning-text hint); updates ADR-0100 §B5 to record the opt-out.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TXHXXHnquzVUjeQYPs9bmy

Author: claude

docs/adr/0100-credential-field-channels.md

@@ -95,6 +95,15 @@ rest but masked on read**:
    would be self-inflicted breakage. Raw `.parse()` stays silent, since it also
    loads persisted metadata and `create()` is the authoring surface (ADR-0077).
 
+   **Opt-out — `ackPlaintextMasking: true` (#3420).** A deliberate `password`
+   field (like field-zoo's `f_password`) can affirm intent with a field-level
+   `ackPlaintextMasking: true`; the warning then skips that field. The original
+   text said the warning was "safe to ignore" but offered no way to *express*
+   that intent, so the official showcase booted with an unavoidable warning —
+   training users to ignore warnings. The flag is the documented affirmation and
+   lets the stock example start warning-free. It is diagnostic-only: masking,
+   the echoed-mask guard, and the better-auth exemption are all unchanged by it.
+
 ### C. Shared mechanism
 
 Both channels share one read-mask collector — `collectMaskedReadFields`

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

@@ -35,7 +35,10 @@ 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 (masked on read)' }),
+    // field-zoo intentionally exercises every field type, so the generic
+    // `password` contract (plaintext at rest, masked on read — ADR-0100) is
+    // deliberate here. Affirm it so the official example boots warning-free (#3420).
+    f_password: Field.password({ label: 'Password (masked on read)', ackPlaintextMasking: true }),
     f_secret: Field.secret({ label: 'Secret (encrypted at rest)' }),
 
     // ── Rich content ─────────────────────────────────────────────────────

packages/objectql/src/registry.ts

@@ -539,6 +539,17 @@ export class SchemaRegistry {
     console.log(msg);
   }
 
+  /**
+   * Debug-only diagnostic: emitted solely when `logLevel === 'debug'`, so it
+   * stays out of the default (`'info'`) boot log. Use for expected-but-noisy
+   * housekeeping — e.g. re-registration on a metadata rebuild / HMR reload,
+   * which looks like an error (`console.warn`) but is a normal path (#3420).
+   */
+  private debug(msg: string): void {
+    if (this._logLevel !== 'debug') return;
+    console.debug(msg);
+  }
+
   // ==========================================
   // Object-specific storage (Ownership Model)
   // ==========================================
@@ -731,7 +742,10 @@ export class SchemaRegistry {
       const idx = contributors.findIndex(c => c.packageId === packageId && c.ownership === 'own');
       if (idx !== -1) {
         contributors.splice(idx, 1);
-        console.warn(`[Registry] Re-registering owned object: ${fqn} from ${packageId}`);
+        // Normal path (metadata rebuild / HMR / multi-project seed replays the
+        // same owned object), not an error — keep it at debug so a stock boot
+        // stays warning-free (#3420).
+        this.debug(`[Registry] Re-registering owned object: ${fqn} from ${packageId}`);
       }
     } else {
       // extend mode: remove existing extension from same package
@@ -1329,7 +1343,9 @@ export class SchemaRegistry {
     }
     const collection = this.metadata.get('package')!;
     if (collection.has(manifest.id)) {
-      console.warn(`[Registry] Overwriting package: ${manifest.id}`);
+      // Re-install of an already-registered package manifest (rebuild / HMR) is
+      // a normal path, not an error — keep it at debug (#3420).
+      this.debug(`[Registry] Overwriting package: ${manifest.id}`);
     }
     collection.set(manifest.id, pkg);
     this.log(`[Registry] Installed package: ${manifest.id} (${manifest.name})`);

packages/plugins/plugin-auth/src/auth-manager.ts

@@ -1849,6 +1849,16 @@ export class AuthManager {
         loginPage: this.getConsolePageUrl('/login'),
         consentPage: this.getConsolePageUrl('/oauth/consent'),
         schema: buildOauthProviderPluginSchema(),
+        // better-auth's oauth-provider cannot see the well-known documents we
+        // mount ourselves at the issuer ROOT (RFC 8414 §3 requires them there,
+        // not under the auth basePath) — registerOidcDiscoveryRoutes serves
+        // /.well-known/oauth-authorization-server AND the path-insertion variant
+        // (`…/api/v1/auth`) the notice names. Its boot-time "Please ensure …
+        // exists" reminder is therefore a false positive that fires on every
+        // stock example (twice — jwt+oauthProvider init runs it per instance);
+        // silence the one requirement we've already satisfied so an official
+        // dev boot stays warning-free (#3420).
+        silenceWarnings: { oauthAuthServerConfig: true },
         // ── MCP OAuth track (#2698) ────────────────────────────────
         // Coarse tool-family scopes for the platform's own MCP endpoint,
         // advertised alongside the standard OIDC scopes. Names are

packages/spec/src/data/field.zod.ts

@@ -511,6 +511,18 @@ export const FieldSchema = lazySchema(() => z.object({
    * over permission-set field grants. Enforced by plugin-security's FieldMasker.
    */
   requiredPermissions: z.array(z.string()).optional().describe('[ADR-0066 D3] Capabilities required to read/edit this field (mask on read, deny on write; AND-gate).'),
+
+  /**
+   * [ADR-0100] Author's explicit acknowledgment that a generic (non-auth)
+   * `password` field is stored PLAINTEXT at rest and masked to SECRET_MASK on
+   * read — it is NOT one-way hashed (that lives only in the auth subsystem).
+   * Set `true` to affirm the masking contract is intended; this is the
+   * documented way to express "this is intended" and silences the non-fatal
+   * `ObjectSchema.create()` author-time warning so a deliberate demo/design
+   * starts clean (#3420). No runtime effect beyond the diagnostic; ignored on
+   * non-`password` fields.
+   */
+  ackPlaintextMasking: z.boolean().optional().describe("[ADR-0100] Affirm a generic `password` field's plaintext-at-rest / masked-on-read contract is intended, silencing the author-time warning (#3420). No effect on non-password fields."),
   system: z.boolean().optional().describe('Auto-injected system/audit field (e.g. created_at, updated_by, organization_id). Tools that surface system fields separately from author-declared business fields should branch on this flag.'),
   sortable: z.boolean().optional().default(true).describe('Whether field is sortable in list views'),
   inlineHelpText: z.string().optional().describe('Help text displayed below the field in forms'),

packages/spec/src/data/object.test.ts

@@ -1486,4 +1486,38 @@ describe('ObjectSchema.create() password-field author warning (ADR-0100)', () =>
     });
     expect(warn).not.toHaveBeenCalled();
   });
+
+  it('does NOT warn when the field affirms intent with ackPlaintextMasking (#3420)', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    ObjectSchema.create({
+      name: 'adr0100_acked_pw',
+      fields: { admin_password: { type: 'password', ackPlaintextMasking: true } },
+    });
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it('still warns about un-acknowledged password fields when only some opt in', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    ObjectSchema.create({
+      name: 'adr0100_partial_ack',
+      fields: {
+        acked_pw: { type: 'password', ackPlaintextMasking: true },
+        raw_pw: { type: 'password' },
+      },
+    });
+    expect(warn).toHaveBeenCalledTimes(1);
+    const msg = warn.mock.calls[0]?.[0] as string;
+    expect(msg).toContain('raw_pw');
+    expect(msg).not.toContain('acked_pw');
+  });
+
+  it('points authors at the ackPlaintextMasking opt-out in the warning text', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    ObjectSchema.create({
+      name: 'adr0100_hint_pw',
+      fields: { pw: { type: 'password' } },
+    });
+    const msg = warn.mock.calls[0]?.[0] as string;
+    expect(msg).toContain('ackPlaintextMasking');
+  });
 });

packages/spec/src/data/object.zod.ts

@@ -1262,7 +1262,10 @@ const warnedPasswordObjects = new Set<string>();
  * A warning, not an error: `password` now has a defined generic-path contract,
  * and the field-zoo example intentionally exercises every field type — a hard
  * error would be self-inflicted breakage. Deduped per object name so a schema
- * imported many times warns once. `managedBy: 'better-auth'` objects are exempt.
+ * imported many times warns once. `managedBy: 'better-auth'` objects are exempt,
+ * as are fields that opt in with `ackPlaintextMasking: true` — the author's
+ * explicit "this is intended" acknowledgment (#3420), which lets a deliberate
+ * demo/design (e.g. the showcase field-zoo) start with zero warnings.
  */
 function warnGenericPasswordFields(
   objectName: unknown,
@@ -1271,8 +1274,10 @@ function warnGenericPasswordFields(
 ): void {
   if (managedBy === 'better-auth') return;
   if (!fields || typeof fields !== 'object') return;
-  const passwordFields = Object.entries(fields as Record<string, { type?: string }>)
-    .filter(([, def]) => def && def.type === 'password')
+  const passwordFields = Object.entries(
+    fields as Record<string, { type?: string; ackPlaintextMasking?: boolean }>,
+  )
+    .filter(([, def]) => def && def.type === 'password' && def.ackPlaintextMasking !== true)
     .map(([fieldName]) => fieldName);
   if (passwordFields.length === 0) return;
   const name = typeof objectName === 'string' && objectName.length > 0 ? objectName : '<unnamed>';
@@ -1285,7 +1290,7 @@ function warnGenericPasswordFields(
     'it is NOT one-way hashed (that is owned by the auth subsystem, for its identity ' +
     "tables only). Use `Field.secret(...)` for reversible machine credentials, or model " +
     'login credentials on the auth user object. If this is intended, the masking contract ' +
-    'now applies and this warning is safe to ignore.',
+    'applies — affirm it with `ackPlaintextMasking: true` on the field to silence this warning.',
   );
 }