feat(auth): thread the real better-auth actor into identity writes for attribution (#4586)

better-auth owns every write to the identity tables and its ObjectQL adapter
runs them `isSystem: true` on purpose — the route already authorized the
action under better-auth's own ACL. The human who clicked *make admin* was
known exactly once, in the hook layer, then discarded, so every
`trackHistory` transition on `sys_member` recorded "system" as its actor.

W1 — a general seam, not a `sys_member` special case: a request-scoped
attribution store opened at `AuthManager.handleRequest`, filled lazily from
better-auth's global before-hook, surfaced as
`ExecutionContext.attributedUserId` → `HookContext.provenance.attributedUserId`
and read by the audit writer.

W2 — `auto-org-admin-grant` stamps the attributed human into the `granted_by`
column it always wrote null into, plus a machine-provenance `reason` naming
the writer and the triggering `sys_member` row.

W3 — covered at the real routes (invite-accept, update-member-role, the
reconciler bind, demotion) in a dogfood test over the live HTTP stack.

ATTRIBUTION ONLY: the threaded actor never becomes the authorization subject.
It rides `provenance`, which no security middleware reads; `isSystem` stays
the unconditional authorization half. Re-authorizing as the human would open
the second adjudication track ADR-0095 D3 closed — pinned by tests at the
engine seam, the adapter, and the live route.

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

Author: claude

content/docs/references/data/data-engine.mdx

@@ -39,7 +39,7 @@ const result = BaseEngineOptionsSchema.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **context** | `{ userId?: string; actor?: string; email?: string; tenantId?: string; … }` | optional |  |
+| **context** | `{ userId?: string; actor?: string; attributedUserId?: string; email?: string; … }` | optional |  |
 
 
 ---
@@ -52,7 +52,7 @@ Options for DataEngine.aggregate operations
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **context** | `{ userId?: string; actor?: string; email?: string; tenantId?: string; … }` | optional |  |
+| **context** | `{ userId?: string; actor?: string; attributedUserId?: string; email?: string; … }` | optional |  |
 | **filter** | `Record<string, any> \| any` | optional | Data Engine query filter conditions |
 | **groupBy** | `string[]` | optional |  |
 | **aggregations** | `{ field: string; method: Enum<'count' \| 'sum' \| 'avg' \| 'min' \| 'max' \| 'count_distinct'>; alias?: string }[]` | optional |  |
@@ -94,7 +94,7 @@ Options for DataEngine.count operations
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **context** | `{ userId?: string; actor?: string; email?: string; tenantId?: string; … }` | optional |  |
+| **context** | `{ userId?: string; actor?: string; attributedUserId?: string; email?: string; … }` | optional |  |
 | **filter** | `Record<string, any> \| any` | optional | Data Engine query filter conditions |
 
 
@@ -121,7 +121,7 @@ Options for DataEngine.delete operations
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **context** | `{ userId?: string; actor?: string; email?: string; tenantId?: string; … }` | optional |  |
+| **context** | `{ userId?: string; actor?: string; attributedUserId?: string; email?: string; … }` | optional |  |
 | **filter** | `Record<string, any> \| any` | optional | Data Engine query filter conditions |
 | **multi** | `boolean` | optional |  |
 
@@ -212,7 +212,7 @@ Options for DataEngine.insert operations
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **context** | `{ userId?: string; actor?: string; email?: string; tenantId?: string; … }` | optional |  |
+| **context** | `{ userId?: string; actor?: string; attributedUserId?: string; email?: string; … }` | optional |  |
 | **returning** | `boolean` | optional |  |
 
 
@@ -240,7 +240,7 @@ Query options for IDataEngine.find() operations
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **context** | `{ userId?: string; actor?: string; email?: string; tenantId?: string; … }` | optional |  |
+| **context** | `{ userId?: string; actor?: string; attributedUserId?: string; email?: string; … }` | optional |  |
 | **filter** | `Record<string, any> \| any` | optional | Data Engine query filter conditions |
 | **select** | `string[]` | optional |  |
 | **sort** | `Record<string, Enum<'asc' \| 'desc'>> \| Record<string, '1' \| '-1'> \| { field: string; order: Enum<'asc' \| 'desc'> }[]` | optional | Sort order definition |
@@ -428,7 +428,7 @@ Options for DataEngine.update operations
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **context** | `{ userId?: string; actor?: string; email?: string; tenantId?: string; … }` | optional |  |
+| **context** | `{ userId?: string; actor?: string; attributedUserId?: string; email?: string; … }` | optional |  |
 | **filter** | `Record<string, any> \| any` | optional | Data Engine query filter conditions |
 | **upsert** | `boolean` | optional |  |
 | **multi** | `boolean` | optional |  |
@@ -492,7 +492,7 @@ QueryAST-aligned options for DataEngine.aggregate operations
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **context** | `{ userId?: string; actor?: string; email?: string; tenantId?: string; … }` | optional |  |
+| **context** | `{ userId?: string; actor?: string; attributedUserId?: string; email?: string; … }` | optional |  |
 | **where** | `Record<string, any> \| any` | optional |  |
 | **groupBy** | `string[]` | optional |  |
 | **aggregations** | `{ function: Enum<'count' \| 'sum' \| 'avg' \| 'min' \| 'max' \| 'count_distinct' \| 'array_agg' \| 'string_agg'>; field?: string; alias: string; distinct?: boolean; … }[]` | optional |  |
@@ -510,7 +510,7 @@ QueryAST-aligned options for DataEngine.count operations
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **context** | `{ userId?: string; actor?: string; email?: string; tenantId?: string; … }` | optional |  |
+| **context** | `{ userId?: string; actor?: string; attributedUserId?: string; email?: string; … }` | optional |  |
 | **where** | `Record<string, any> \| any` | optional |  |
 
 
@@ -524,7 +524,7 @@ QueryAST-aligned options for DataEngine.delete operations
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **context** | `{ userId?: string; actor?: string; email?: string; tenantId?: string; … }` | optional |  |
+| **context** | `{ userId?: string; actor?: string; attributedUserId?: string; email?: string; … }` | optional |  |
 | **where** | `Record<string, any> \| any` | optional |  |
 | **multi** | `boolean` | optional |  |
 
@@ -539,7 +539,7 @@ QueryAST-aligned query options for IDataEngine.find() operations
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **context** | `{ userId?: string; actor?: string; email?: string; tenantId?: string; … }` | optional |  |
+| **context** | `{ userId?: string; actor?: string; attributedUserId?: string; email?: string; … }` | optional |  |
 | **where** | `Record<string, any> \| any` | optional |  |
 | **fields** | `string[]` | optional |  |
 | **orderBy** | `{ field: string; order: Enum<'asc' \| 'desc'> }[]` | optional |  |
@@ -563,7 +563,7 @@ QueryAST-aligned options for DataEngine.update operations
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **context** | `{ userId?: string; actor?: string; email?: string; tenantId?: string; … }` | optional |  |
+| **context** | `{ userId?: string; actor?: string; attributedUserId?: string; email?: string; … }` | optional |  |
 | **where** | `Record<string, any> \| any` | optional |  |
 | **upsert** | `boolean` | optional |  |
 | **multi** | `boolean` | optional |  |

content/docs/references/data/hook.mdx

@@ -38,7 +38,7 @@ const result = HookContextSchema.parse(data);
 | **result** | `any` | optional | Operation result (After hooks only) |
 | **previous** | `Record<string, any>` | optional | Record state before operation |
 | **session** | `{ userId?: string; actor?: string; organizationId?: string; roles?: string[]; … }` | optional | Current session context |
-| **provenance** | `{ flowRunId?: string }` | optional | Server-stamped write provenance (never client-supplied, never an authorization input) |
+| **provenance** | `{ flowRunId?: string; attributedUserId?: string }` | optional | Server-stamped write provenance (never client-supplied, never an authorization input) |
 | **transaction** | `any` | optional | Database transaction handle |
 | **ql** | `any` | ✅ | ObjectQL Engine Reference |
 | **api** | `any` | optional | Cross-object data access (ScopedContext) |

content/docs/references/kernel/execution-context.mdx

@@ -49,6 +49,7 @@ const result = ExecutionContextSchema.parse(data);
 | :--- | :--- | :--- | :--- |
 | **userId** | `string` | optional |  |
 | **actor** | `string` | optional |  |
+| **attributedUserId** | `string` | optional |  |
 | **email** | `string` | optional |  |
 | **tenantId** | `string` | optional |  |
 | **timezone** | `string` | optional |  |

packages/objectql/src/engine.test.ts

@@ -632,6 +632,82 @@ describe('ObjectQL Engine', () => {
         });
     });
 
+    /**
+     * #4586 — the ATTRIBUTED human rides provenance, never the session.
+     *
+     * better-auth owns every write to the identity tables and runs them
+     * `isSystem: true` ON PURPOSE: the route already authorized the action
+     * under better-auth's own ACL. Threading the real human through so
+     * `sys_member` history stops saying "system" must therefore change exactly
+     * one thing — who the write is CREDITED to — and nothing about who it is
+     * AUTHORIZED as. Re-authorizing as the human would open a second
+     * adjudication track at the boundary ADR-0095 D3 closed.
+     *
+     * These are the pins for that constraint at the engine seam, where the
+     * context is split into the envelopes hooks and middleware actually read.
+     */
+    describe('attributed actor is attribution, never authorization (#4586)', () => {
+        beforeEach(async () => {
+            engine.registerDriver(mockDriver, true);
+            await engine.init();
+            vi.mocked(SchemaRegistry.getObject).mockReturnValue({ name: 'task', fields: {} } as any);
+        });
+
+        const capture = () => {
+            const seen: { session?: any; provenance?: any; user?: any } = {};
+            engine.registerHook('beforeInsert', async (ctx: any) => {
+                seen.session = ctx.session;
+                seen.provenance = ctx.provenance;
+                seen.user = ctx.user;
+            }, { object: 'task' });
+            return seen;
+        };
+
+        it('a better-auth write surfaces the human on provenance and stays a SYSTEM session', async () => {
+            const seen = capture();
+
+            await engine.insert('task', { title: 'grade change' }, {
+                context: { isSystem: true, attributedUserId: 'usr_admin' } as any,
+            });
+
+            expect(seen.provenance).toEqual({ attributedUserId: 'usr_admin' });
+            // The authorization half is untouched: still system, still no caller.
+            expect(seen.session).toMatchObject({ isSystem: true });
+            expect(seen.session.userId).toBeUndefined();
+            // And the attributed human must NOT leak into any channel that a
+            // hook or middleware reads as "the acting user".
+            expect(seen.session).not.toHaveProperty('attributedUserId');
+            expect(seen.user).toBeUndefined();
+        });
+
+        it('attribution ALONE authorizes exactly like no context at all (ADR-0118 D2)', async () => {
+            // "Absence is never system": a context that names only who to credit
+            // establishes no principal, so it must not become one. Anything else
+            // would make forgetting `isSystem` an accidental elevation.
+            const seen = capture();
+
+            await engine.insert('task', { title: 'no authority' }, {
+                context: { attributedUserId: 'usr_admin' } as any,
+            });
+
+            expect(seen.provenance).toEqual({ attributedUserId: 'usr_admin' });
+            expect(seen.session).toBeUndefined();
+            expect(seen.user).toBeUndefined();
+        });
+
+        it('a real caller keeps their own session; the two envelopes never merge', async () => {
+            const seen = capture();
+
+            await engine.insert('task', { title: 'both' }, {
+                context: { userId: 'u1', attributedUserId: 'usr_admin', flowRunId: 'run_9' } as any,
+            });
+
+            expect(seen.session).toMatchObject({ userId: 'u1' });
+            expect(seen.user).toMatchObject({ id: 'u1' });
+            expect(seen.provenance).toEqual({ flowRunId: 'run_9', attributedUserId: 'usr_admin' });
+        });
+    });
+
     describe('execution context via the trailing options arg (read methods)', () => {
         // Regression: reads took context inside the query while writes took it in
         // a trailing options arg — so `find(obj, q, { context })` silently dropped

packages/objectql/src/engine.ts

@@ -1181,17 +1181,28 @@ export class ObjectQL implements IObjectQLEngine {
   }
 
   /**
-   * Build the HookContext.provenance envelope — WHAT produced this write.
+   * Build the HookContext.provenance envelope — WHERE this write came from.
    *
    * Deliberately separate from {@link buildSession}: provenance is server-
    * stamped, evaluated by no security middleware, and can exist with no
    * identity beside it. A schedule-triggered flow run resolves no principal
    * yet still owns its writes, and that is the case the approvals record lock
    * needs to recognize (#3456 / #3712).
+   *
+   * `attributedUserId` rides the SAME envelope for the same reason (#4586):
+   * a better-auth-originated write authorizes as the system, so the human who
+   * triggered it must reach the audit writer WITHOUT appearing in `session` —
+   * where every caller-gating hook would read them as the caller. Attribution
+   * here, authorization in `session`/`isSystem`, never the two mixed.
    */
   private buildProvenance(execCtx?: ExecutionContextInput): HookContext['provenance'] {
     const flowRunId = (execCtx as any)?.flowRunId;
-    return flowRunId ? { flowRunId: String(flowRunId) } : undefined;
+    const attributedUserId = (execCtx as any)?.attributedUserId;
+    if (!flowRunId && !attributedUserId) return undefined;
+    return {
+      ...(flowRunId ? { flowRunId: String(flowRunId) } : {}),
+      ...(attributedUserId ? { attributedUserId: String(attributedUserId) } : {}),
+    };
   }
 
   /**

packages/plugins/plugin-audit/src/audit-writers.test.ts

@@ -183,6 +183,63 @@ describe('audit writers — actor attribution (ADR-0014 D2, cloud#340)', () => {
     expect(audit?.row.actor).toBeNull();
     expect(audit?.row.user_id).toBeNull();
   });
+
+  /**
+   * [#4586] The `sys_member` case the issue is about: better-auth authorizes
+   * identity writes as the SYSTEM on purpose, so the session names no caller
+   * and every grade change used to record as "system". The human arrives on
+   * PROVENANCE instead — attribution, never authorization.
+   */
+  it('credits the attributed human when the write authorized as the system', async () => {
+    const { engine, fire, created } = makeEngine(SINGLE_TENANT);
+    installAuditWriters(engine as any, 'test.audit');
+    await fire('afterUpdate', {
+      object: 'sys_member',
+      input: { id: 'mem-1' },
+      __previous: { id: 'mem-1', role: 'member' },
+      result: { id: 'mem-1', role: 'admin' },
+      // Exactly the envelope `withSystemContext` produces for an
+      // `organization/update-member-role` call.
+      session: { isSystem: true },
+      provenance: { attributedUserId: 'user-admin' },
+    });
+    const audit = created.find((c) => c.object === 'sys_audit_log');
+    expect(audit?.row.action).toBe('update');
+    // WHO changed the grade — a real sys_user id, so the lookup still joins
+    // (ADR-0118 D1: an id or null, never a sentinel like 'system').
+    expect(audit?.row.user_id).toBe('user-admin');
+    expect(audit?.row.actor).toBe('user-admin');
+  });
+
+  it('a genuinely machine-originated write still records as the system (null)', async () => {
+    // Boot sync / migration / the kernel:ready backfill: no scope, no actor.
+    // Absence must stay absence — never upgraded into some ambient user.
+    const { engine, fire, created } = makeEngine(SINGLE_TENANT);
+    installAuditWriters(engine as any, 'test.audit');
+    await fire('afterInsert', {
+      object: 'sys_member',
+      input: { id: 'mem-2' },
+      result: { id: 'mem-2', role: 'member' },
+      session: { isSystem: true },
+    });
+    const audit = created.find((c) => c.object === 'sys_audit_log');
+    expect(audit?.row.user_id).toBeNull();
+    expect(audit?.row.actor).toBeNull();
+  });
+
+  it('a real caller outranks attribution — the session subject wins', async () => {
+    const { engine, fire, created } = makeEngine(SINGLE_TENANT);
+    installAuditWriters(engine as any, 'test.audit');
+    await fire('afterInsert', {
+      object: 'crm_lead',
+      input: { id: 'lead-3' },
+      result: { id: 'lead-3', name: 'Gamma' },
+      session: { userId: 'user-7' },
+      provenance: { attributedUserId: 'user-admin' },
+    });
+    const audit = created.find((c) => c.object === 'sys_audit_log');
+    expect(audit?.row.user_id).toBe('user-7');
+  });
 });
 
 describe('audit writers — declarative trackHistory activity (ADR-0052 §5b)', () => {

packages/plugins/plugin-audit/src/audit-writers.ts

@@ -476,7 +476,26 @@ export function installAuditWriters(
     if (recordId !== undefined) recordId = String(recordId);
 
     const sess: any = (ctx as any).session ?? {};
-    const userId: string | undefined = sess.userId;
+    // [#4586] Two channels can name a human, and they mean different things:
+    //
+    //   session.userId              — the subject the write was AUTHORIZED as.
+    //   provenance.attributedUserId — the human CREDITED for a write the
+    //                                 system authorized on their behalf.
+    //
+    // The second exists because better-auth owns every identity-table write
+    // and runs them `isSystem` on purpose (the route already authorized under
+    // its own ACL), which left every `sys_member` grade change recorded as
+    // "system". Reading it here is what makes the history row name the admin
+    // who clicked *make admin*. The session subject still WINS when present —
+    // attribution never overrides who actually acted — and neither channel
+    // widens what the write may touch (no security middleware reads
+    // provenance).
+    const attributedUserId: string | undefined =
+      typeof (ctx as any).provenance?.attributedUserId === 'string' &&
+      (ctx as any).provenance.attributedUserId
+        ? (ctx as any).provenance.attributedUserId
+        : undefined;
+    const userId: string | undefined = sess.userId ?? attributedUserId;
     // Principal label for attribution. Prefer the real user id; otherwise fall
     // back to a service/automation principal the host put on the context
     // (`ExecutionContext.actor`, e.g. `svc:<name>`). This is what makes a