feat(auth): identity write guard — enforce managedBy:'better-auth' at the engine (#2816)

ADR-0092 D2/D3/D6 implementation:

- identity-write-guard.ts: before{Insert,Update,Delete} hooks (priority 10)
  registered by plugin-auth at kernel:ready. User-context writes to any
  object whose schema declares managedBy:'better-auth' are rejected
  fail-closed (403 PERMISSION_DENIED with a pointer to the dedicated
  surfaces); better-auth adapter (no context) and isSystem writes bypass.
  Per-object update whitelist registry is the only opening; engine-stamped
  lifecycle columns (updated_at/updated_by) pass through but never satisfy
  the whitelist alone.
- sys-user-writable-fields.ts: shared field tiers — profile edit whitelist
  {name, image} and the import superset {+phone_number, role}
  (subset-by-construction, ADR-0092 D3); admin-import-users.ts now derives
  UPDATE_ALLOWED_FIELDS from it.
- D6: afterUpdate hook mirrors better-auth's refreshUserSessions — cached
  {session, user} snapshots in secondary storage are re-written (same TTL,
  never deleted) with the changed profile fields after a guarded edit.

Verified against a live --fresh CRM backend: profile PATCH persists with
fresh updated_at; email-only PATCH 403s; role/must_change_password are
stripped and not persisted; insert/delete 403; create-user /
set-user-password / self-service update-user / import upsert all work
unchanged. Call-site sweep: every existing identity-table write already
runs under SYSTEM_CTX or the adapter path.

Closes #2816

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

Author: claude

.changeset/identity-write-guard.md

@@ -0,0 +1,37 @@
+---
+"@objectstack/plugin-auth": minor
+---
+
+feat(auth): identity write guard — `managedBy: 'better-auth'` is now enforced at the engine (ADR-0092 D2/D3/D6)
+
+Every object whose schema declares `managedBy: 'better-auth'` (`sys_user`,
+`sys_member`, `sys_session`, `sys_api_key`, …) is now protected by engine
+`beforeInsert` / `beforeUpdate` / `beforeDelete` hooks registered by
+plugin-auth: **user-context** writes through the generic data path are
+rejected fail-closed with `403 PERMISSION_DENIED`, closing the hole where a
+wildcard admin permission set could raw-write any identity column (including
+`email` and credential stamps) via the data API. Internal writes are
+unaffected — the better-auth adapter, `isSystem` plugin/system contexts, and
+the identity import keep working unchanged.
+
+The only opening is a per-object update whitelist
+(`registerManagedUpdateWhitelist(object, fields)`): non-whitelisted fields are
+stripped from the payload, and a payload that strips to nothing throws. The
+first registration ships here: `sys_user → { name, image }` (pure profile
+fields), backed by the new shared `SYS_USER_PROFILE_EDIT_FIELDS` /
+`SYS_USER_IMPORT_UPDATE_FIELDS` constants — the import upsert's field
+discipline is now derived from the same module (subset-by-construction, no
+drift).
+
+After a guarded profile edit, an `afterUpdate` companion hook re-writes the
+user's cached `{session, user}` snapshots in better-auth's secondary storage
+(same TTL, mirror of better-auth's own `refreshUserSessions`) so session
+reads stay coherent; it rewrites rather than deletes, and no-ops when no
+secondary storage is wired.
+
+Migration note: server-side scripts that previously updated identity tables
+with a **user** execution context must either run with a system context
+(`{ isSystem: true }`) if they are genuinely internal, or move to the
+dedicated auth endpoints (invite / create-user / set-user-password / ban /
+better-auth APIs). Flows and automations that wrote non-profile `sys_user`
+columns under a user identity are now filtered the same way.

packages/plugins/plugin-auth/src/admin-import-users.ts

@@ -57,11 +57,17 @@ import type {
 import { prepareImportRequest, runImport } from '@objectstack/rest';
 import { generatePlaceholderEmail, isPlaceholderEmail } from './placeholder-email.js';
 import { generateTemporaryPassword, normalizePhoneNumber, isLikelyEmail, type AdminActor, type EndpointResult } from './admin-user-endpoints.js';
+import { SYS_USER_IMPORT_UPDATE_FIELDS } from './sys-user-writable-fields.js';
 
 export const IMPORT_USERS_MAX_ROWS = 500;
 
-/** Profile fields an upsert row may modify on an EXISTING user. */
-const UPDATE_ALLOWED_FIELDS = new Set(['name', 'phone_number', 'role']);
+/**
+ * Profile fields an upsert row may modify on an EXISTING user — shared with
+ * the identity write guard's Tier-1 whitelist via sys-user-writable-fields.ts
+ * (ADR-0092 D3: one file, one derivation; the import surface is a strict
+ * superset that additionally allows `phone_number` / `role`).
+ */
+const UPDATE_ALLOWED_FIELDS = SYS_USER_IMPORT_UPDATE_FIELDS;
 
 export interface IdentityImportEngine {
   find(objectName: string, query?: any): Promise<any[]>;

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

@@ -18,6 +18,12 @@ import {
   type AuthManagerOptions,
 } from './auth-manager.js';
 import { ensureDefaultOrganization } from './ensure-default-organization.js';
+import {
+  registerIdentityWriteGuard,
+  registerManagedUpdateWhitelist,
+  type SecondaryStorageLike,
+} from './identity-write-guard.js';
+import { SYS_USER_PROFILE_EDIT_FIELDS } from './sys-user-writable-fields.js';
 import { runSetInitialPassword } from './set-initial-password.js';
 import { runRegisterSsoProviderFromForm, runRegisterSamlProviderFromForm, runRequestDomainVerification, runVerifyDomain } from './register-sso-provider.js';
 import { runResendVerificationEmail } from './send-verification-email.js';
@@ -125,6 +131,10 @@ export class AuthPlugin implements Plugin {
   private options: AuthPluginOptions;
   private authManager: AuthManager | null = null;
   private configuredSocialProviders: SocialProviderConfig | undefined;
+  // ADR-0092 D6 — the EFFECTIVE better-auth secondaryStorage (host-supplied or
+  // the kernel-cache adapter wired in init). The identity write guard's
+  // session-snapshot refresh reads through this; undefined = refresh no-ops.
+  private effectiveSecondaryStorage: AuthManagerOptions['secondaryStorage'];
 
   constructor(options: AuthPluginOptions = {}) {
     this.options = {
@@ -221,6 +231,9 @@ export class AuthPlugin implements Plugin {
 
     // Initialize auth manager with data engine
     this.authManager = new AuthManager(authConfig);
+    // ADR-0092 D6 — remember the storage better-auth will actually use so the
+    // identity write guard can keep cached session snapshots coherent.
+    this.effectiveSecondaryStorage = authConfig.secondaryStorage;
 
     // Register auth service
     ctx.registerService('auth', this.authManager);
@@ -535,6 +548,29 @@ export class AuthPlugin implements Plugin {
       }
     });
 
+    // ADR-0092 D2/D6 — generic identity write guard. Every object whose
+    // schema declares `managedBy: 'better-auth'` gets fail-closed protection
+    // against USER-CONTEXT writes through the generic data path; the only
+    // opening is the per-object update whitelist (sys_user → profile fields).
+    // Internal writes (better-auth adapter, isSystem plugin/system contexts)
+    // bypass — see identity-write-guard.ts for the full contract.
+    ctx.hook('kernel:ready', async () => {
+      try {
+        const engine: any = ctx.getService<any>('objectql');
+        if (!engine || typeof engine.registerHook !== 'function') return;
+        registerManagedUpdateWhitelist(SystemObjectName.USER, SYS_USER_PROFILE_EDIT_FIELDS);
+        registerIdentityWriteGuard(engine, {
+          packageId: 'com.objectstack.plugin-auth.identity-write-guard',
+          logger: ctx.logger,
+          getSecondaryStorage: () =>
+            this.effectiveSecondaryStorage as SecondaryStorageLike | undefined,
+        });
+      } catch {
+        // Engine not available (mock mode) — permission-set defaults remain
+        // the only gate, exactly the pre-guard status quo.
+      }
+    });
+
     // Register auth middleware on ObjectQL engine (if available)
     try {
       const ql = ctx.getService<any>('objectql');