@volter/world-runtime 2.0.38 → 2.0.40

package/dist/src/served-world.d.ts

@@ -268,6 +268,10 @@ export declare class WorldDoors {
     /** What this World issued, for world-access to decide a grant against: its two tokens, its named keys, its sessions. */
     private issued;
     private credential;
+    /** Who made a request, as this World names it: `key:<name>` for a named key, `person:<who>` for a browser's session
+     *  (`person` when it names no one), `token` / `token:read` for the World's own tokens; null when it presented nothing
+     *  this World issued. */
+    private callerOf;
     /** The session cookie's name where `url` reached this World, or null where a session opens nothing:
      *  on the World's own origin a host-only cookie (`__Host-` over https); without an origin of its own,
      *  the path-scoped cookie a shared origin has always carried. */
@@ -352,6 +356,10 @@ export declare class WorldDoors {
      *  twin, then position. The World keeps no order across twins finer than its clock, and this claims
      *  none. `before` is the cursor the previous page answered; `twin` and `trace` narrow it. */
     private timeline;
+    /** Each twin's callers by the World's span, from its request journal: its newest CALLER_SEGMENTS once, then from
+     *  where the last read stopped (readTwinRequestJournalFrom follows a rotation). The newest CALLERS_KEPT are kept. */
+    private readonly callersByTwin;
+    private callersOf;
     /** Each twin's timeline rows, kept until its logs change: a poll of an unchanged World reads no log
      *  (a twin is read again only when the size or time of its parent log, branch log or branch record
      *  moved), and the merged order is sorted again only when a twin was. */

package/dist/src/served-world.js

@@ -26,7 +26,7 @@ import { getActiveWorldStore, withAncestryLock, captureHistory, historyAtInstant
 // to `.volter/token` and `.volter/token.read` (0600).
 // One writer per world by construction: the doors run in this process, serialized per twin.
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
-import { assertSafeChangesetName, blobDigest, destinationOf, openSealedAt, getActiveBlobStore, journalTwinRequest, loadCheck, twinRequestJournalFailures, mirrorShellUnder, readTwinRequestJournal, serveHttp, twinRequestCredentials, TWIN_PREFIX_HEADER, validateRemoteOrigin } from '@volter/world-core';
+import { CALLER_HEADER, newTraceparent, parseTraceparent, traceparentForDelivery, readTwinRequestJournalFrom, assertSafeChangesetName, blobDigest, destinationOf, openSealedAt, getActiveBlobStore, journalTwinRequest, loadCheck, twinRequestJournalFailures, mirrorShellUnder, readTwinRequestJournal, serveHttp, twinRequestCredentials, TWIN_PREFIX_HEADER, validateRemoteOrigin } from '@volter/world-core';
 import { APP_READ_ENDPOINT_ENV } from "./init.js";
 import { grantOf, presentedSecrets, sameSecret, spentPasses, verifyPass } from '@volter/world-access';
 import { createHash } from 'node:crypto';
@@ -369,6 +369,11 @@ function traceIdOf(traceparent) {
     const m = typeof traceparent === 'string' ? /^[0-9a-f]{2}-([0-9a-f]{32})-[0-9a-f]{16}-[0-9a-f]{2}$/.exec(traceparent) : null;
     return m && !/^0+$/.test(m[1]) ? m[1] : null;
 }
+const CALLERS_KEPT = 50_000;
+/** The closed journal segments a World reads for callers when it first answers a timeline (~1 MB each): older entries show no caller. */
+const CALLER_SEGMENTS = 8;
+/** A W3C traceparent's parent-id (the span the World minted for the request), or null. */
+function spanOf(traceparent) { return parseTraceparent(traceparent)?.parentId ?? null; }
 /** Timeline order, newest first: by the entry's instant, then twin, then position. */
 function newerFirst(a, b) {
     return b.at.localeCompare(a.at) || b.twin.localeCompare(a.twin) || b.position - a.position;
@@ -653,6 +658,22 @@ export class WorldDoors {
             return { scope: grant.scope, via: 'session', token: null, session: grant.session, ...(grant.who ? { who: grant.who } : {}) };
         return { scope: grant.scope, via: grant.via === 'key' ? 'key' : 'token', token: grant.presented ?? null };
     }
+    /** Who made a request, as this World names it: `key:<name>` for a named key, `person:<who>` for a browser's session
+     *  (`person` when it names no one), `token` / `token:read` for the World's own tokens; null when it presented nothing
+     *  this World issued. */
+    callerOf(request) {
+        const cred = this.credential(request);
+        if (cred.scope === null)
+            return null;
+        if (cred.via === 'session')
+            return cred.who ? `person:${cred.who}` : 'person';
+        if (cred.via === 'key') {
+            const token = cred.token;
+            const held = token ? this.keys().find((k) => sameSecret(keyHash(token), k.hash)) : undefined;
+            return held ? `key:${held.name}` : 'key';
+        }
+        return cred.scope === 'read' ? 'token:read' : 'token';
+    }
     /** The session cookie's name where `url` reached this World, or null where a session opens nothing:
      *  on the World's own origin a host-only cookie (`__Host-` over https); without an origin of its own,
      *  the path-scoped cookie a shared origin has always carried. */
@@ -872,6 +893,14 @@ export class WorldDoors {
         headers.delete(TOKEN_HEADER);
         headers.delete(TWINS_KEY_HEADER);
         headers.delete('host');
+        // who made it is the World's word, never the caller's: the twin's request journal records it. The World is a hop of
+        // the request's trace: the caller's trace-id goes on (or a new one), under a parent-id the World mints, which the
+        // request's log entries carry, so each entry is joined to its caller by an id no caller chose
+        headers.delete(CALLER_HEADER);
+        const who = this.callerOf(request);
+        if (who)
+            headers.set(CALLER_HEADER, who);
+        headers.set('traceparent', traceparentForDelivery(headers.get('traceparent')) ?? newTraceparent());
         // at a twin that enforces the read scope, every request of the read token is marked read-only (a GET
         // that would write for its caller is refused too); at any other, its GET passes as it always has
         if (enforced)
@@ -942,7 +971,7 @@ export class WorldDoors {
         // what leaves for the vendor before the seal is applied: no World token in any header it can arrive
         // under (an SDK's own `Authorization: Bearer` included), no cookie, no routing headers of this World
         const caller = new Headers(request.headers);
-        for (const h of [TOKEN_HEADER, TWINS_KEY_HEADER, TWIN_PREFIX_HEADER, 'host', 'x-forwarded-host', 'x-forwarded-proto', 'cookie'])
+        for (const h of [TOKEN_HEADER, TWINS_KEY_HEADER, TWIN_PREFIX_HEADER, CALLER_HEADER, 'host', 'x-forwarded-host', 'x-forwarded-proto', 'cookie'])
             caller.delete(h);
         // a secret this World minted (`tok_…`, live, revoked or expired) or one that opens it never leaves
         const authorization = caller.get('authorization');
@@ -953,7 +982,10 @@ export class WorldDoors {
         // name, with the credential shape of what the caller sent on. As an audit device does, the request is
         // written before the real credential is used, and a request whose audit cannot be written is refused.
         const credentials = twinRequestCredentials(caller, url);
-        if (!journalTwinRequest(name, { phase: 'request', method: request.method, path: `/${rest}`, status: 0, credentials }, this.controlRoot(name))) {
+        const who = this.callerOf(request);
+        const trace = parseTraceparent(request.headers.get('traceparent'))?.traceId;
+        const by = { ...(who ? { caller: who } : {}), ...(trace ? { trace } : {}) };
+        if (!journalTwinRequest(name, { phase: 'request', method: request.method, path: `/${rest}`, status: 0, credentials, ...by }, this.controlRoot(name))) {
             return Response.json({ error: `the ${name} link's audit could not be written: nothing was sent` }, { status: 503 });
         }
         const startedAt = Date.now();
@@ -964,7 +996,7 @@ export class WorldDoors {
             return answer;
         }
         finally {
-            journalTwinRequest(name, { method: request.method, path: `/${rest}`, status, ms: Date.now() - startedAt, credentials }, this.controlRoot(name));
+            journalTwinRequest(name, { method: request.method, path: `/${rest}`, status, ms: Date.now() - startedAt, credentials, ...by }, this.controlRoot(name));
         }
     }
     async forwardSealed(request, caller, url, rest, name, origin) {
@@ -1705,7 +1737,33 @@ export class WorldDoors {
         const shown = page.slice(0, limit);
         const last = shown[shown.length - 1];
         const next = more && last ? Buffer.from(JSON.stringify([last.entry.occurredAt, last.twin, last.position])).toString('base64url') : null;
-        return Response.json({ world: this.served, entries: shown, next });
+        // who made each entry: the request it was written in (the World's span on it) as the twin's journal recorded it
+        const entries = shown.map((r) => { const by = this.callersOf(r.twin).get(spanOf(r.entry.traceparent) ?? ''); return by ? { ...r, caller: by } : r; });
+        return Response.json({ world: this.served, entries, next });
+    }
+    /** Each twin's callers by the World's span, from its request journal: its newest CALLER_SEGMENTS once, then from
+     *  where the last read stopped (readTwinRequestJournalFrom follows a rotation). The newest CALLERS_KEPT are kept. */
+    callersByTwin = new Map();
+    callersOf(twin) {
+        const root = this.controlRoot(twin);
+        let held = this.callersByTwin.get(twin);
+        if (!held || held.root !== root) {
+            held = { root, cursor: null, callers: new Map() };
+            this.callersByTwin.set(twin, held);
+        }
+        const read = readTwinRequestJournalFrom(twin, root, held.cursor, { segments: CALLER_SEGMENTS });
+        for (const e of read.entries)
+            if (e.span && e.caller) {
+                held.callers.delete(e.span);
+                held.callers.set(e.span, e.caller);
+            }
+        held.cursor = read.cursor;
+        for (const span of held.callers.keys()) {
+            if (held.callers.size <= CALLERS_KEPT)
+                break;
+            held.callers.delete(span);
+        }
+        return held.callers;
     }
     /** Each twin's timeline rows, kept until its logs change: a poll of an unchanged World reads no log
      *  (a twin is read again only when the size or time of its parent log, branch log or branch record

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-runtime",
-  "version": "2.0.38",
+  "version": "2.0.40",
   "description": "World configs for twins: boot named local runtimes, allocate ports, generate world.env/instance.json, and run apps against fake-key twin worlds.",
   "keywords": [
     "twin",
@@ -67,14 +67,14 @@
     "node": ">=22.3"
   },
   "peerDependencies": {
-    "@volter/world-core": "2.0.21",
+    "@volter/world-core": "2.0.22",
     "@volter/world-console": "2.0.13"
   },
   "dependencies": {
     "@electric-sql/pglite": "0.5.8",
     "@electric-sql/pglite-pgvector": "0.0.9",
     "@volter/world-access": "2.0.2",
-    "@volter/world-core": "2.0.21",
+    "@volter/world-core": "2.0.22",
     "pg-gateway": "0.3.0-beta.4",
     "smol-toml": "^1.8.0"
   },
@@ -84,6 +84,6 @@
     }
   },
   "optionalDependencies": {
-    "@volter/twin-mongodb": "0.1.21"
+    "@volter/twin-mongodb": "0.1.22"
   }
 }

package/src/served-world.ts

@@ -26,7 +26,7 @@ import { getActiveWorldStore, withAncestryLock, captureHistory, historyAtInstant
 // to `.volter/token` and `.volter/token.read` (0600).
 // One writer per world by construction: the doors run in this process, serialized per twin.
 import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync , rmSync} from 'node:fs';
-import { assertSafeChangesetName, blobDigest, destinationOf, openSealedAt, getActiveBlobStore, journalTwinRequest, loadCheck, twinRequestJournalFailures, mirrorShellUnder, readTwinRequestJournal, serveHttp, twinRequestCredentials, TWIN_PREFIX_HEADER, validateRemoteOrigin, type SealedCredential, type TwinStreamConnection, type TwinStreamSink } from '@volter/world-core';
+import { CALLER_HEADER, newTraceparent, parseTraceparent, traceparentForDelivery, readTwinRequestJournalFrom, type TwinRequestJournalCursor, assertSafeChangesetName, blobDigest, destinationOf, openSealedAt, getActiveBlobStore, journalTwinRequest, loadCheck, twinRequestJournalFailures, mirrorShellUnder, readTwinRequestJournal, serveHttp, twinRequestCredentials, TWIN_PREFIX_HEADER, validateRemoteOrigin, type SealedCredential, type TwinStreamConnection, type TwinStreamSink } from '@volter/world-core';
 import { APP_READ_ENDPOINT_ENV } from './init.ts';
 import { grantOf, presentedSecrets, sameSecret, spentPasses, verifyPass, type TrustedIssuer, type WorldCredentials } from '@volter/world-access';
 import { createHash } from 'node:crypto';
@@ -380,6 +380,11 @@ function traceIdOf(traceparent: unknown): string | null {
   return m && !/^0+$/.test(m[1]!) ? m[1]! : null;
 }
 type TimelineRow = { twin: string; position: number; entry: Entry };
+const CALLERS_KEPT = 50_000;
+/** The closed journal segments a World reads for callers when it first answers a timeline (~1 MB each): older entries show no caller. */
+const CALLER_SEGMENTS = 8;
+/** A W3C traceparent's parent-id (the span the World minted for the request), or null. */
+function spanOf(traceparent: unknown): string | null { return parseTraceparent(traceparent)?.parentId ?? null; }
 /** Timeline order, newest first: by the entry's instant, then twin, then position. */
 function newerFirst(a: { at: string; twin: string; position: number }, b: { at: string; twin: string; position: number }): number {
   return b.at.localeCompare(a.at) || b.twin.localeCompare(a.twin) || b.position - a.position;
@@ -590,6 +595,16 @@ export class WorldDoors {
     if (grant.via === 'session') return { scope: grant.scope, via: 'session', token: null, session: grant.session!, ...(grant.who ? { who: grant.who } : {}) };
     return { scope: grant.scope, via: grant.via === 'key' ? 'key' : 'token', token: grant.presented ?? null };
   }
+  /** Who made a request, as this World names it: `key:<name>` for a named key, `person:<who>` for a browser's session
+   *  (`person` when it names no one), `token` / `token:read` for the World's own tokens; null when it presented nothing
+   *  this World issued. */
+  private callerOf(request: Request): string | null {
+    const cred = this.credential(request);
+    if (cred.scope === null) return null;
+    if (cred.via === 'session') return cred.who ? `person:${cred.who}` : 'person';
+    if (cred.via === 'key') { const token = cred.token; const held = token ? this.keys().find((k) => sameSecret(keyHash(token), k.hash)) : undefined; return held ? `key:${held.name}` : 'key'; }
+    return cred.scope === 'read' ? 'token:read' : 'token';
+  }
   /** The session cookie's name where `url` reached this World, or null where a session opens nothing:
    *  on the World's own origin a host-only cookie (`__Host-` over https); without an origin of its own,
    *  the path-scoped cookie a shared origin has always carried. */
@@ -781,6 +796,12 @@ export class WorldDoors {
     const enforced = scope === 'read' && (await this.enforcesRead(vendor!, twin, url.origin));
     if (scope === 'read' && !reads && !enforced) return Response.json({ error: 'the read token opens only reads' }, { status: 403 });
     const headers = new Headers(request.headers); headers.delete(TOKEN_HEADER); headers.delete(TWINS_KEY_HEADER); headers.delete('host');
+    // who made it is the World's word, never the caller's: the twin's request journal records it. The World is a hop of
+    // the request's trace: the caller's trace-id goes on (or a new one), under a parent-id the World mints, which the
+    // request's log entries carry, so each entry is joined to its caller by an id no caller chose
+    headers.delete(CALLER_HEADER);
+    const who = this.callerOf(request); if (who) headers.set(CALLER_HEADER, who);
+    headers.set('traceparent', traceparentForDelivery(headers.get('traceparent')) ?? newTraceparent());
     // at a twin that enforces the read scope, every request of the read token is marked read-only (a GET
     // that would write for its caller is refused too); at any other, its GET passes as it always has
     if (enforced) headers.set(READ_ONLY_HEADER, '1');
@@ -843,7 +864,7 @@ export class WorldDoors {
     // what leaves for the vendor before the seal is applied: no World token in any header it can arrive
     // under (an SDK's own `Authorization: Bearer` included), no cookie, no routing headers of this World
     const caller = new Headers(request.headers);
-    for (const h of [TOKEN_HEADER, TWINS_KEY_HEADER, TWIN_PREFIX_HEADER, 'host', 'x-forwarded-host', 'x-forwarded-proto', 'cookie']) caller.delete(h);
+    for (const h of [TOKEN_HEADER, TWINS_KEY_HEADER, TWIN_PREFIX_HEADER, CALLER_HEADER, 'host', 'x-forwarded-host', 'x-forwarded-proto', 'cookie']) caller.delete(h);
     // a secret this World minted (`tok_…`, live, revoked or expired) or one that opens it never leaves
     const authorization = caller.get('authorization');
     const offered = authorization ? presentedSecrets(new Headers({ authorization }), { token: TOKEN_HEADER, twinsKey: TWINS_KEY_HEADER }) : [];
@@ -852,7 +873,9 @@ export class WorldDoors {
     // name, with the credential shape of what the caller sent on. As an audit device does, the request is
     // written before the real credential is used, and a request whose audit cannot be written is refused.
     const credentials = twinRequestCredentials(caller, url);
-    if (!journalTwinRequest(name, { phase: 'request', method: request.method, path: `/${rest}`, status: 0, credentials }, this.controlRoot(name))) {
+    const who = this.callerOf(request); const trace = parseTraceparent(request.headers.get('traceparent'))?.traceId;
+    const by = { ...(who ? { caller: who } : {}), ...(trace ? { trace } : {}) };
+    if (!journalTwinRequest(name, { phase: 'request', method: request.method, path: `/${rest}`, status: 0, credentials, ...by }, this.controlRoot(name))) {
       return Response.json({ error: `the ${name} link's audit could not be written: nothing was sent` }, { status: 503 });
     }
     const startedAt = Date.now(); let status = 500;
@@ -861,7 +884,7 @@ export class WorldDoors {
       status = answer.status;
       return answer;
     } finally {
-      journalTwinRequest(name, { method: request.method, path: `/${rest}`, status, ms: Date.now() - startedAt, credentials }, this.controlRoot(name));
+      journalTwinRequest(name, { method: request.method, path: `/${rest}`, status, ms: Date.now() - startedAt, credentials, ...by }, this.controlRoot(name));
     }
   }
 
@@ -1442,7 +1465,23 @@ export class WorldDoors {
     const more = page.length > limit; const shown = page.slice(0, limit);
     const last = shown[shown.length - 1];
     const next = more && last ? Buffer.from(JSON.stringify([last.entry.occurredAt, last.twin, last.position])).toString('base64url') : null;
-    return Response.json({ world: this.served, entries: shown, next });
+    // who made each entry: the request it was written in (the World's span on it) as the twin's journal recorded it
+    const entries = shown.map((r) => { const by = this.callersOf(r.twin).get(spanOf(r.entry.traceparent) ?? ''); return by ? { ...r, caller: by } : r; });
+    return Response.json({ world: this.served, entries, next });
+  }
+
+  /** Each twin's callers by the World's span, from its request journal: its newest CALLER_SEGMENTS once, then from
+   *  where the last read stopped (readTwinRequestJournalFrom follows a rotation). The newest CALLERS_KEPT are kept. */
+  private readonly callersByTwin = new Map<string, { root: string; cursor: TwinRequestJournalCursor | null; callers: Map<string, string> }>();
+  private callersOf(twin: string): Map<string, string> {
+    const root = this.controlRoot(twin);
+    let held = this.callersByTwin.get(twin);
+    if (!held || held.root !== root) { held = { root, cursor: null, callers: new Map() }; this.callersByTwin.set(twin, held); }
+    const read = readTwinRequestJournalFrom(twin, root, held.cursor, { segments: CALLER_SEGMENTS });
+    for (const e of read.entries) if (e.span && e.caller) { held.callers.delete(e.span); held.callers.set(e.span, e.caller); }
+    held.cursor = read.cursor;
+    for (const span of held.callers.keys()) { if (held.callers.size <= CALLERS_KEPT) break; held.callers.delete(span); }
+    return held.callers;
   }
 
   /** Each twin's timeline rows, kept until its logs change: a poll of an unchanged World reads no log