fix(rest): the authenticated identity is the recorded actor on /meta writes (#7941) (#9119)

X-Actor no longer outranks the authenticated identity when stamping
sys_metadata_audit.actor and sys_metadata_history.recorded_by. The header
limb is removed rather than reordered, so a caller cannot choose the name
an audit row records in any shape.

The ordering was inert until #7749 fixed the producer; once the second
limb produced a value, any holder of manage_metadata could sign somebody
else's name to a metadata write. Attribution now reads the same
resolveExecCtx the route's own capability gate reads, so it cannot drift
from authorization.

Maintainer ruling 2026-08-12, re-confirmed 2026-08-15, premised on a
consumer census coming back empty. Census re-run over objectstack and
objectui: no caller sets the header. The ruling's conditional carve-out
for machine/system callers is therefore not taken.


Claude-Session: https://claude.ai/code/session_01Y26DJEHSBhhAQ6wwfsHNza

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-project-manager

.changeset/meta-write-actor-identity-wins.md

@@ -0,0 +1,17 @@
+---
+'@objectstack/rest': minor
+---
+
+**Audit attribution change — the recorded actor on `/meta` writes is now the authenticated identity, and `X-Actor` is ignored.** All five `/meta` write sites (save, delete/reset, publish, rollback, compound save) stamp `sys_metadata_audit.actor` and `sys_metadata_history.recorded_by` with the identity the request was actually authorized as. A request that sends `X-Actor` is recorded against its own authenticated caller, not the header's value. Maintainer ruling 2026-08-12 on #7941, re-confirmed 2026-08-15.
+
+Why: the header used to outrank the authenticated identity. That ordering was inert for as long as the other limb produced nothing — `req.user` / `req.userId` are never set on this transport — so nothing depended on it. Fixing that producer (#7749) made the precedence load-bearing for the first time, and what it then meant was that any caller already holding `manage_metadata` could sign somebody else's name to a metadata write: the compliance trail answered "who *claimed* to change this" rather than "who changed this", which is the question #7749 was filed to make answerable. Attribution now cannot drift from authorization, because both read the same `resolveExecCtx` the route's own capability gate reads.
+
+The header limb is **removed rather than reordered**. The ruling permitted keeping it for genuine machine/system callers with no authenticated user, but only if a consumer census showed that shape exists — it does not, so a caller cannot choose the recorded name in any shape, including on the machine-write path where there is no identity for the header to lose to.
+
+Deliberately unchanged:
+
+- **Real impersonation still attributes correctly.** The platform's impersonation is session-level (better-auth admin plugin, `sys_session.impersonated_by`), so `resolveExecCtx` already resolves to the impersonated user and their metadata writes are recorded against them. Nothing in that path went through `X-Actor`.
+- **Machine and anonymous writes.** No resolved principal still means no actor, so the protocol's own `'system'` / `NULL` defaults apply exactly as before — a machine write is never stamped with a real user.
+- **Sending `X-Actor` is not an error.** It is ignored, not rejected; no request that succeeds today starts failing.
+
+Who is affected: any caller that relied on `X-Actor` to attribute a `/meta` write to somebody other than itself. The census over `objectstack` and `objectui` found no such caller — `objectui`'s `MetadataClient` can send the header through an optional `options.actor`, but nothing in that repo ever passes one, leaving that option inert against this server.

packages/rest/src/meta-write-actor-identity.test.ts

@@ -37,14 +37,27 @@
  *  2. an internal system write (`isSystem`, no principal) still records
  *     `'system'` / `NULL` — the fix must not stamp a real user onto machine
  *     writes, and an anonymous caller is still refused outright;
- *  3. an explicit `X-Actor` behaves exactly as it did before, so this change
- *     stays separable from the precedence question the issue raises (the
- *     header still outranks the session identity — deliberately unchanged
- *     here, see `resolveMetaWriteActor`).
+ *  3. [#7941] an explicit `X-Actor` does NOT outrank the authenticated
+ *     identity — the admin's id is recorded, not the header's value;
+ *  4. [#7941] and `X-Actor` is inert on the machine-write path too, where
+ *     there is no authenticated user for it to lose to.
  *
- * The final case closes the loop the other three stub: that a bearer token
- * really does land on `resolveExecCtx().userId` for this route, driven through
- * a real `authServiceProvider` with no stub in the identity path at all.
+ * ## The precedence, and why cases 3–4 read the way they do
+ *
+ * This file originally pinned the OPPOSITE of case 3: the header won, pinned
+ * as-is and explicitly not endorsed, labelled as the test to change once the
+ * ordering was ruled on. Maintainer ruling #7941 (2026-08-12, re-confirmed
+ * 2026-08-15) removed the header limb rather than reordering it — the recorded
+ * actor is the identity the request was authorized as, so attribution cannot
+ * drift from authorization and an audit row answers "who changed this" rather
+ * than "who claimed to". Case 4 exists because the ruling allowed keeping the
+ * header for genuine machine/system callers ONLY if a consumer census showed
+ * that shape exists; it did not (nothing in `objectstack` or `objectui` sets
+ * the header), so the carve-out was not taken and its absence is pinned.
+ *
+ * The final case closes the loop the others stub: that a bearer token really
+ * does land on `resolveExecCtx().userId` for this route, driven through a real
+ * `authServiceProvider` with no stub in the identity path at all.
  */
 
 import { describe, it, expect, afterEach } from 'vitest';
@@ -238,23 +251,44 @@ describe('[#7749] PUT /meta/:type/:name records the authenticated caller as the
         expect(rows).toHaveLength(0);
     }, 60_000);
 
-    it('an explicit X-Actor still wins over the session identity — precedence unchanged', async () => {
-        // ⚠️ Pinned as-is, NOT endorsed: with the producer fixed this ordering
-        // is live for the first time, so an authenticated caller can attribute
-        // a write to somebody else. Changing whose name lands in an audit row
-        // is a security-semantics decision for the audit contract, tracked
-        // separately on #7749 — this test exists to keep that decision
-        // separable from this fix, and it is the test to CHANGE when the
-        // maintainer rules on the ordering.
+    it('[#7941] an explicit X-Actor does NOT outrank the authenticated identity', async () => {
+        // The flip. This test previously pinned the opposite — the header won,
+        // pinned as-is and explicitly NOT endorsed, as the test to change when
+        // the ordering was ruled on. It has been (#7941, 2026-08-12,
+        // re-confirmed 2026-08-15): the recorded actor is the identity the
+        // request was authorized as, so an admin holding `manage_metadata` can
+        // no longer sign somebody else's name to a metadata write.
         const { engine, route } = await boot({
             userId: ADMIN, systemPermissions: ['manage_metadata'],
         });
 
         const res = await putMeta(route, 'header_probe_view', { 'x-actor': 'user_42' });
         expect(res._json?.success).toBe(true);
 
-        expect(await auditActor(engine, 'header_probe_view')).toBe('user_42');
-        expect(await historyActor(engine, 'header_probe_view')).toBe('user_42');
+        // Both rows, together in one object for the same reason as the first
+        // test: `user_42` must appear in NEITHER, and a flip that fixed only
+        // one of the two defaults would otherwise pass on the first assertion.
+        expect({
+            audit: await auditActor(engine, 'header_probe_view'),
+            history: await historyActor(engine, 'header_probe_view'),
+        }).toEqual({ audit: ADMIN, history: ADMIN });
+    }, 60_000);
+
+    it('[#7941] X-Actor cannot attribute a write that has NO authenticated user either', async () => {
+        // The carve-out the ruling permitted only if the census showed the
+        // shape exists — honouring the header for genuine machine/system
+        // callers with no authenticated user. The census found no caller that
+        // sets `X-Actor` at all, so the carve-out is not taken, and this pins
+        // that: the header is inert on the machine-write path too, rather than
+        // surviving as a fallback that reintroduces caller-chosen attribution
+        // wherever the identity happens to be absent.
+        const { engine, route } = await boot({ isSystem: true });
+
+        const res = await putMeta(route, 'system_header_probe_view', { 'x-actor': 'user_42' });
+        expect(res._json?.success).toBe(true);
+
+        expect(await auditActor(engine, 'system_header_probe_view')).toBe('system');
+        expect(await historyActor(engine, 'system_header_probe_view')).toBeFalsy();
     }, 60_000);
 
     it('the identity comes from the REAL bearer→session→execCtx chain, no stub', async () => {
@@ -289,5 +323,20 @@ describe('[#7749] PUT /meta/:type/:name records the authenticated caller as the
         // falls through to the protocol's `'system'` / NULL defaults.
         const anon = await (rest as any).resolveMetaWriteActor(undefined, { headers: {} });
         expect(anon).toBeUndefined();
+
+        // [#7941] …and a header cannot fill that gap. Asserted at the producer
+        // as well as through the route, because this is the seam where the
+        // removed limb used to live: an `X-Actor` on an uncredentialed request
+        // still resolves to nobody, and one sent ALONGSIDE a valid bearer
+        // resolves to the bearer's identity, never the header's value.
+        const headerOnly = await (rest as any).resolveMetaWriteActor(undefined, {
+            headers: { 'x-actor': 'user_42' },
+        });
+        expect(headerOnly).toBeUndefined();
+
+        const headerVsBearer = await (rest as any).resolveMetaWriteActor(undefined, {
+            headers: { authorization: `Bearer token-for-${ADMIN}`, 'x-actor': 'user_42' },
+        });
+        expect(headerVsBearer).toBe(ADMIN);
     }, 60_000);
 });

packages/rest/src/rest-server.ts

@@ -1388,16 +1388,38 @@ export class RestServer {
      * is memoized per request, so the three routes that already resolved a
      * context for their gate pay nothing extra for this.
      *
-     * ## Precedence — deliberately unchanged (#7749)
+     * ## Precedence — ruled on #7941: the authenticated identity wins
      *
-     * `X-Actor` still outranks the authenticated identity, exactly as the
-     * expression above read. That ordering was masked while the other limbs
-     * were always `undefined`; it becomes load-bearing the moment this method
-     * produces one. Whether an authenticated caller may keep attributing a
-     * metadata write to somebody else by sending a header is a security
-     * semantics question for the audit contract, not something to settle as a
-     * side effect of fixing the producer — so it is measured and reported on
-     * the issue rather than quietly reordered here.
+     * `X-Actor` used to outrank the authenticated identity, as the expression
+     * above read. That ordering was masked while the other limbs were always
+     * `undefined`; fixing the producer made it load-bearing, and it meant any
+     * caller already holding `manage_metadata` could sign somebody else's name
+     * to a metadata write — `sys_metadata_audit.actor` and
+     * `sys_metadata_history.recorded_by` would name that other person.
+     *
+     * Maintainer ruling (2026-08-12, re-confirmed 2026-08-15), premised on a
+     * consumer census coming back empty: **the header limb is removed, not
+     * reordered.** The recorded actor is the identity the request was actually
+     * authorized as — the SAME `resolveExecCtx` the route's own
+     * `manage_metadata` gate reads a few lines earlier — so attribution can
+     * never drift from authorization, and the audit trail answers "who changed
+     * this" rather than "who claimed to".
+     *
+     * The census (`objectstack` + `objectui`, all paths) found no caller that
+     * sets the header: `objectui`'s `MetadataClient` can send it via an
+     * optional `options.actor`, but nothing in that repo ever passes one. So
+     * the ruling's conditional carve-out — keep honouring the header for
+     * genuine machine/system callers that have no authenticated user — is
+     * deliberately NOT taken: the census did not show that shape exists, and a
+     * limb nothing produces is the "declared but never written" shape
+     * Prime Directive #10 exists to keep out. A delegation path, if one is ever
+     * genuinely needed, is option C on #7941 (an explicit impersonation
+     * capability), not an ambient header.
+     *
+     * Note this does not disturb the platform's REAL impersonation: that is
+     * session-level (better-auth admin plugin, `sys_session.impersonated_by`),
+     * so `resolveExecCtx` already resolves to the impersonated user and an
+     * impersonated metadata write is still attributed to them.
      *
      * Anonymous / internal writes are unaffected: no resolved principal → no
      * context → `undefined` → the protocol's `'system'` / `NULL` defaults still
@@ -1407,13 +1429,10 @@ export class RestServer {
         environmentId: string | undefined,
         req: any,
     ): Promise<string | undefined> {
-        const header = req?.headers?.['x-actor'] ?? req?.headers?.['X-Actor'];
-        // A well-formed header wins, as before. A PRESENT-but-unusable header
-        // (repeated → array, or empty) falls through to the session rather than
-        // suppressing attribution: recording the real caller beats recording
-        // `'system'` for a malformed request, and it keeps "no usable header →
-        // the authenticated identity" a single rule.
-        if (typeof header === 'string' && header) return header;
+        // [#7941] No header limb, by ruling. `X-Actor` on the request is
+        // ignored outright — it is not consulted for user principals, and not
+        // as a fallback for unauthenticated ones either, so there is no shape
+        // in which a caller can choose the name the audit row records.
         const ctx = await this.resolveExecCtx(environmentId, req).catch(() => undefined);
         const userId = (ctx as any)?.userId;
         return typeof userId === 'string' && userId ? userId : undefined;
@@ -4911,8 +4930,9 @@ export class RestServer {
                     const parentVersion = typeof ifMatchHeader === 'string'
                         ? ifMatchHeader.replace(/^"|"$/g, '') // strip ETag-style quotes
                         : undefined;
-                    // [#7749] Header, else the request's authenticated identity — one
-                    // producer, shared by every `/meta` write (see resolveMetaWriteActor).
+                    // [#7749 producer, #7941 precedence] The request's authenticated
+                    // identity — one producer, shared by every `/meta` write (see
+                    // resolveMetaWriteActor). `X-Actor` is not consulted.
                     const actor = await this.resolveMetaWriteActor(environmentId, req);
                     // Phase 3a-destructive: `?force=true` opts past the
                     // destructive-change safety check. Accept any truthy
@@ -5075,15 +5095,16 @@ export class RestServer {
                     // Mirror saveMetaItem's OCC + actor plumbing (ADR-0008
                     // PR-10d wiring): `If-Match` pins the expected current
                     // version so concurrent edits get a 409 instead of a
-                    // silent reset; `X-Actor` — or, since #7749, the request's
-                    // authenticated identity — flows into the history
-                    // tombstone row.
+                    // silent reset; the request's authenticated identity flows
+                    // into the history tombstone row (#7749 producer; #7941
+                    // dropped the `X-Actor` limb that used to outrank it).
                     const ifMatchHeader = req.headers?.['if-match'] ?? req.headers?.['If-Match'];
                     const parentVersion = typeof ifMatchHeader === 'string'
                         ? ifMatchHeader.replace(/^"|"$/g, '')
                         : undefined;
-                    // [#7749] Header, else the request's authenticated identity — one
-                    // producer, shared by every `/meta` write (see resolveMetaWriteActor).
+                    // [#7749 producer, #7941 precedence] The request's authenticated
+                    // identity — one producer, shared by every `/meta` write (see
+                    // resolveMetaWriteActor). `X-Actor` is not consulted.
                     const actor = await this.resolveMetaWriteActor(environmentId, req);
 
                     // [#6877] `?state=` and the destructive `?dropStorage=`
@@ -5314,8 +5335,9 @@ export class RestServer {
                         });
                         return;
                     }
-                    // [#7749] Header, else the request's authenticated identity — one
-                    // producer, shared by every `/meta` write (see resolveMetaWriteActor).
+                    // [#7749 producer, #7941 precedence] The request's authenticated
+                    // identity — one producer, shared by every `/meta` write (see
+                    // resolveMetaWriteActor). `X-Actor` is not consulted.
                     const actor = await this.resolveMetaWriteActor(environmentId, req);
                     const body = (req.body && typeof req.body === 'object') ? req.body : {};
                     const message = typeof body.message === 'string' ? body.message : undefined;
@@ -5424,8 +5446,9 @@ export class RestServer {
                         });
                         return;
                     }
-                    // [#7749] Header, else the request's authenticated identity — one
-                    // producer, shared by every `/meta` write (see resolveMetaWriteActor).
+                    // [#7749 producer, #7941 precedence] The request's authenticated
+                    // identity — one producer, shared by every `/meta` write (see
+                    // resolveMetaWriteActor). `X-Actor` is not consulted.
                     const actor = await this.resolveMetaWriteActor(environmentId, req);
                     const message = typeof body.message === 'string' ? body.message : undefined;
                     // [#8805] The rollback half. Same argument as publish, one
@@ -5908,8 +5931,9 @@ export class RestServer {
                     const parentVersion = typeof ifMatchHeader === 'string'
                         ? ifMatchHeader.replace(/^"|"$/g, '')
                         : undefined;
-                    // [#7749] Header, else the request's authenticated identity — one
-                    // producer, shared by every `/meta` write (see resolveMetaWriteActor).
+                    // [#7749 producer, #7941 precedence] The request's authenticated
+                    // identity — one producer, shared by every `/meta` write (see
+                    // resolveMetaWriteActor). `X-Actor` is not consulted.
                     const actor = await this.resolveMetaWriteActor(environmentId, req);
 
                     // [#6877] The `typeof` guard below dropped a repeated

packages/rest/src/rest.test.ts

@@ -1806,7 +1806,8 @@ describe('createRestApiPlugin', () => {
 });
 
 // ---------------------------------------------------------------------------
-// PUT /meta/:type/:name — If-Match → parentVersion / X-Actor → actor (PR-10d.4)
+// PUT /meta/:type/:name — If-Match → parentVersion (PR-10d.4); the actor comes
+// from the authenticated identity, never a header (#7941)
 // ---------------------------------------------------------------------------
 
 describe('PUT /meta/:type/:name handler — header → request plumbing (PR-10d.4)', () => {
@@ -1835,12 +1836,18 @@ describe('PUT /meta/:type/:name handler — header → request plumbing (PR-10d.
 
     await route.handler(req, res);
 
+    // [#7941] `actor` is the authenticated identity, NOT the `x-actor` header
+    // this request also sends. The header is retained in the fixture on
+    // purpose: it is the one assertion that shows the header is ignored even
+    // when present, which is the whole content of the ruling. Asserting
+    // `parentVersion` and `actor` together also keeps the If-Match plumbing
+    // this test is named for covered by the same call.
     expect(protocol.saveMetaItem).toHaveBeenCalledWith(
       expect.objectContaining({
         type: 'view',
         name: 'cases',
         parentVersion: 'sha256:abc',
-        actor: 'user_42',
+        actor: 'test-user',
       }),
     );
   });