@volter/world-core 3.0.158 → 3.0.160

package/dist/generated/pack-facts.json

@@ -1208,16 +1208,34 @@
       "resources": [
         "client",
         "account",
-        "access_token"
+        "access_token",
+        "api_key"
       ],
       "endpointEnvNone": "Google's OAuth libraries read no base-URL variable: the endpoints are the discovery document's, claimed by the host rules.",
       "credentialDoor": {
-        "path": "/_twin/service-accounts",
+        "path": "/_twin/credentials",
         "body": {
-          "client_email": "world@world-project.iam.gserviceaccount.com"
+          "client_email": "world@world-project.iam.gserviceaccount.com",
+          "client": {
+            "redirect_uris": [
+              "http://localhost:3000/oauth2callback"
+            ],
+            "name": "World App"
+          },
+          "account": {
+            "sub": "100000000000000000001",
+            "email": "person@world.example",
+            "name": "World Person"
+          },
+          "api_key": {
+            "name": "API key 1"
+          }
         },
         "fill": {
-          "GOOGLE_APPLICATION_CREDENTIALS": "file:credentials"
+          "GOOGLE_APPLICATION_CREDENTIALS": "file:credentials",
+          "GOOGLE_CLIENT_ID": "client_id",
+          "GOOGLE_CLIENT_SECRET": "client_secret",
+          "YOUTUBE_API_KEY": "api_key"
         }
       },
       "serveExport": "createGoogleoauthTwinServer"
@@ -1370,6 +1388,53 @@
       },
       "serveExport": "createHuggingfaceTwinServer"
     },
+    "instagram": {
+      "adoption": {
+        "sdks": [],
+        "envStems": [
+          "INSTAGRAM"
+        ]
+      },
+      "hosts": [
+        {
+          "host": "graph.instagram.com"
+        },
+        {
+          "host": "api.instagram.com"
+        },
+        {
+          "host": "www.instagram.com",
+          "pathPattern": "^/oauth/authorize"
+        },
+        {
+          "host": "scontent.cdninstagram.com"
+        }
+      ],
+      "archetype": "crud",
+      "protocol": {
+        "declared": "3",
+        "major": 3,
+        "standing": "current"
+      },
+      "transport": "rest",
+      "resources": [
+        "container",
+        "media",
+        "comment"
+      ],
+      "endpointEnvNone": "an app calls graph.instagram.com and api.instagram.com and sends people to www.instagram.com; the World claims the hosts",
+      "credentialDoor": {
+        "path": "/_twin/app-credentials",
+        "body": {},
+        "fill": {
+          "INSTAGRAM_APP_ID": "app_id",
+          "INSTAGRAM_APP_SECRET": "app_secret",
+          "INSTAGRAM_ACCESS_TOKEN": "access_token",
+          "INSTAGRAM_USER_ID": "user_id"
+        }
+      },
+      "serveExport": "createInstagramTwinServer"
+    },
     "intercom": {
       "adoption": {
         "sdks": [
@@ -3383,6 +3448,71 @@
         }
       },
       "serveExport": "createXaiTwinServer"
+    },
+    "youtube": {
+      "adoption": {
+        "sdks": [
+          "@googleapis/youtube"
+        ],
+        "envStems": [
+          "YOUTUBE"
+        ]
+      },
+      "hosts": [
+        {
+          "host": "www.googleapis.com",
+          "pathPattern": "^/(upload/|resumable/upload/)?youtube/v3(/|$)"
+        },
+        {
+          "host": "youtube.googleapis.com",
+          "pathPattern": "^/(upload/|resumable/upload/)?youtube/v3(/|$)|^/_twin/"
+        }
+      ],
+      "archetype": "crud",
+      "protocol": {
+        "declared": "3",
+        "major": 3,
+        "standing": "current"
+      },
+      "transport": "rest",
+      "resources": [
+        "channel",
+        "video",
+        "liveBroadcast",
+        "liveStream",
+        "liveChatMessage",
+        "commentThread",
+        "comment",
+        "_upload_session",
+        "_live_chat",
+        "_comment_ban",
+        "_live",
+        "_live_segment"
+      ],
+      "endpointEnvNone": "Google's generated clients take rootUrl in code (googleapis: https://youtube.googleapis.com/); the World routes the declared YouTube paths on both API hosts",
+      "credentialDoor": {
+        "path": "/_twin/channels",
+        "body": {
+          "sub": "100000000000000000001",
+          "title": "World Channel",
+          "handle": "worldchannel"
+        },
+        "fill": {
+          "YOUTUBE_CHANNEL_ID": "id"
+        }
+      },
+      "credentialIssuer": "googleoauth",
+      "sidePorts": [
+        {
+          "name": "ingest",
+          "option": "ingestPort",
+          "flag": "--ingest-port",
+          "scheme": "rtmp",
+          "path": "/live2",
+          "note": "YouTube's RTMP ingest (<ingestionAddress>/<streamName>): an encoder publishes a liveStream's video here"
+        }
+      ],
+      "serveExport": "createYoutubeTwinServer"
     }
   },
   "undeclared": []

package/dist/src/actions.d.ts

@@ -309,8 +309,16 @@ export declare function revertAction(opts: {
 export declare function pendingActions(service: string, root?: string): TwinAction[];
 /** A twin's OWN bookkeeping in its action log — a subject type beginning with `_` (stripe's
  *  `_idempotency` store, for one): part of the overlay the twin serves from, never a change the
- *  app made. It is not in the log a user reads, not in a diff, not in a changeset, not pushed. */
+ *  app made. It is not pushed or deployed. It is not in the log a user reads, a diff or a changeset either, except the
+ *  World's people (`isWorldPerson`). */
 export declare function isTwinBookkeeping(action: Pick<TwinAction, 'subject'>): boolean;
+/** A person a twin's pages sign in (`_person`, people.ts): bookkeeping to the kernel, and the one bookkeeping the log
+ *  a user reads, the diff and every changeset carry, so an account replayed into another World signs in there. A
+ *  replay writes its committed row (the email, the password's hash and what the sign-up keeps), never the sign-up.
+ *  ADR 0025. */
+export declare function isWorldPerson(action: Pick<TwinAction, 'subject'>): boolean;
+/** Whether an action is in the World's history as a user reads it, diffs it and cuts changesets from it. */
+export declare function inWorldHistory(action: Pick<TwinAction, 'subject'>): boolean;
 /** The PUSHABLE suffix — `log origin..HEAD` as the push arm, the pending door, plans and the
  *  unpushed count read it: the overlay minus quarantined rows (an import is a copy, not a
  *  decision; releasing a quarantined row is an explicit act, never a scheduler's) and minus the

package/dist/src/actions.js

@@ -552,10 +552,22 @@ export function pendingActions(service, root) {
 }
 /** A twin's OWN bookkeeping in its action log — a subject type beginning with `_` (stripe's
  *  `_idempotency` store, for one): part of the overlay the twin serves from, never a change the
- *  app made. It is not in the log a user reads, not in a diff, not in a changeset, not pushed. */
+ *  app made. It is not pushed or deployed. It is not in the log a user reads, a diff or a changeset either, except the
+ *  World's people (`isWorldPerson`). */
 export function isTwinBookkeeping(action) {
     return action.subject.type.startsWith('_');
 }
+/** A person a twin's pages sign in (`_person`, people.ts): bookkeeping to the kernel, and the one bookkeeping the log
+ *  a user reads, the diff and every changeset carry, so an account replayed into another World signs in there. A
+ *  replay writes its committed row (the email, the password's hash and what the sign-up keeps), never the sign-up.
+ *  ADR 0025. */
+export function isWorldPerson(action) {
+    return action.subject.type === '_person';
+}
+/** Whether an action is in the World's history as a user reads it, diffs it and cuts changesets from it. */
+export function inWorldHistory(action) {
+    return !isTwinBookkeeping(action) || isWorldPerson(action);
+}
 /** The PUSHABLE suffix — `log origin..HEAD` as the push arm, the pending door, plans and the
  *  unpushed count read it: the overlay minus quarantined rows (an import is a copy, not a
  *  decision; releasing a quarantined row is an explicit act, never a scheduler's) and minus the

package/dist/src/changeset.js

@@ -58,7 +58,7 @@ import { worldPaths } from "./storage.js";
 // discovery and the CLI verbs; the state-level logic lives here, beside the ledgers it reads.
 import { createHash } from 'node:crypto';
 import { aliasesFrom, readTreeMapsAt, wholeLog } from "./log.js";
-import { appendActionIfAbsent, checkPrecondition, listActions, projectedPreconditionValue, projectResources, isTwinBookkeeping } from "./actions.js";
+import { appendActionIfAbsent, checkPrecondition, listActions, projectedPreconditionValue, projectResources, inWorldHistory, isWorldPerson } from "./actions.js";
 import { canonicalJson, diffSubjectFields, hashFieldValue } from "./hash.js";
 import { applyTwinWrite } from "./serve.js";
 export const MARKER_KIND = 'volter.world.marker.v1';
@@ -133,8 +133,8 @@ export function diffLedgers(opts) {
             }
         }
         rows.slice(from).forEach((action, offset) => {
-            if (isTwinBookkeeping(action))
-                return; // the twin's own store, never a change the app made
+            if (!inWorldHistory(action))
+                return; // the twin's own store, never a change the app made (a person is the World's: ADR 0025)
             ordered.push({ entry: { service: ledger.service, stateService: ledger.stateService, action }, ledgerIndex, rowIndex: from + offset });
         });
     });
@@ -181,10 +181,14 @@ export function describeActionFields(ledgers, actions) {
                 continue;
             const subject = trees.get(positions.get(action.id))?.get(`${action.subject.type}:${action.subject.id}`);
             const fields = subject?.fields ?? {};
-            fieldChanges[fieldDiffKey(service, stateService, action.id)] = diffSubjectFields({
+            const changes = diffSubjectFields({
                 subject: action.subject, fields, fieldHashes: Object.fromEntries(Object.entries(fields).map(([k, v]) => [k, hashFieldValue(v)])),
                 latestEventId: '', updatedAt: '',
             }, action.fields);
+            // a person's password hash is shown as set, never its value (ADR 0025)
+            if (isWorldPerson(action) && changes.password_sha256)
+                changes.password_sha256 = { before: changes.password_sha256.before === undefined ? undefined : '(set)', after: '(set)' };
+            fieldChanges[fieldDiffKey(service, stateService, action.id)] = changes;
         }
     }
     return fieldChanges;

package/dist/src/derived-core.js

@@ -696,6 +696,81 @@ async function keptFiles(m, call, root) {
 function provisioningInput(call) {
     return call.request.headers.get('x-volter-world-activity') === 'provisioning' ? { input: { activity: 'provisioning' } } : {};
 }
+/** Whether a field names a credential: a password under any name the packs' doors and screens give it (`password`,
+ *  `passwd`, `pw`, `pass`, `session_password`, `user[password]`…; a screen names its own field, world-ui's SignIn
+ *  `password.name`, so the rule reads the name, not a list), or a secret, an API key, an access, refresh or id token, a
+ *  PKCE verifier or a private key, alone or as the name's last part. ADR 0025. */
+const credentialKey = (key) => {
+    const k = key.toLowerCase();
+    return k.includes('password') || k.includes('passwd') || /(^|[[_.-])(pw|pass|secret|client_secret|api_?key|apikey|access_token|refresh_token|id_token|code_verifier|private_key)\]?$/.test(k);
+};
+/** A request header that carries a credential: never recorded, whatever a manifest names (the executor sends the real
+ *  system's own from custody). */
+const credentialHeader = (header) => {
+    const h = header.toLowerCase();
+    return h === 'authorization' || h === 'proxy-authorization' || h === 'cookie' || /(^|-)api-?key$/.test(h) || /token|secret|password|passwd/.test(h);
+};
+/** A form's text as a `<form method="post">` sends it (`a=1&password=…`), told apart from other text. */
+/** A posted form's fields without its credentials, or the text unchanged, byte for byte, when it carries none. */
+function formWithoutCredentials(text, removed) {
+    const form = new URLSearchParams(text);
+    const credentials = [...new Set(form.keys())].filter(credentialKey);
+    if (!credentials.length)
+        return text;
+    for (const key of credentials) {
+        removed.add(key);
+        form.delete(key);
+    }
+    return form.toString();
+}
+/** A multipart form's parts without one named for a credential, or the text unchanged when none is. */
+function multipartWithoutCredentials(text, boundary, removed) {
+    const parts = text.split(`--${boundary}`);
+    const kept = parts.filter((part) => {
+        const name = /name="([^"]*)"/.exec(part)?.[1] ?? '';
+        if (!credentialKey(name))
+            return true;
+        removed.add(name);
+        return false;
+    });
+    return kept.length === parts.length ? text : kept.join(`--${boundary}`);
+}
+/** A recorded request's body or query without its credentials, named in `removed`: fields named for one are taken out of
+ *  a JSON value at any depth. A body that is a posted form (its content type says so) is read as one: its text, as it
+ *  came or kept as `{ $text }`, loses its credential fields (re-encoded with URLSearchParams, the others in order), and a
+ *  multipart form loses a part named for one. Any other string, at any depth, is left as it was: a URL with a query in
+ *  a JSON body (a checkout's success_url) is a value, not a form. */
+function withoutCredentials(value, contentType = '', removed = new Set()) {
+    const form = /application\/x-www-form-urlencoded/i.test(contentType);
+    const boundary = /multipart\/form-data;.*boundary="?([^";]+)"?/i.exec(contentType)?.[1];
+    if (typeof value === 'string')
+        return form ? formWithoutCredentials(value, removed) : boundary ? multipartWithoutCredentials(value, boundary, removed) : value;
+    // (a body that came as text is kept as { $text }: the form is in it)
+    if (form && value && typeof value === 'object' && typeof value.$text === 'string') {
+        return { ...value, $text: formWithoutCredentials(value.$text, removed) };
+    }
+    return withoutCredentialFields(value, removed);
+}
+/** A JSON value without the fields named for a credential, at any depth; every other value is kept as it was. */
+function withoutCredentialFields(value, removed) {
+    if (Array.isArray(value))
+        return value.map((v) => withoutCredentialFields(v, removed));
+    if (!value || typeof value !== 'object')
+        return value;
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null)
+        return value;
+    return Object.fromEntries(Object.entries(value).filter(([key]) => {
+        if (!credentialKey(key))
+            return true;
+        removed.add(key);
+        return false;
+    }).map(([key, v]) => [key, withoutCredentialFields(v, removed)]));
+}
+/** What a write records of its request, with no credential in it on any branch (ADR 0025): the body (JSON, form text,
+ *  multipart), the declared query and the GraphQL variables lose their credential fields, and a header that carries one
+ *  is not recorded. A write whose body, query or a header lost a field names it in `withheld`, so a deploy, which
+ *  sends the recorded request again, refuses it rather than sending it without (derived-real.ts performOf). */
 function recordedInput(m, call, merged) {
     const id = call.operation.id;
     const sent = sentOf.get(call);
@@ -704,18 +779,30 @@ function recordedInput(m, call, merged) {
     const body = sent?.body ?? merged;
     const safeBody = door?.redactBody?.length && body && typeof body === 'object' && !Array.isArray(body)
         ? Object.fromEntries(Object.entries(body).filter(([key]) => !door.redactBody.includes(key))) : body;
-    const asSent = sent ? { ...activity, path: sent.path, query: sent.query, body: safeBody, headers: sent.headers, ...(sent.lane ? { lane: sent.lane } : {}), ...(sent.requestId ? { requestId: sent.requestId } : {}), ...(sent.type ? { contentType: sent.type } : {}) } : { ...activity, path: call.params, body: safeBody };
+    const withheld = new Set();
+    // (a header a manifest names that carries a credential is named too: a deploy would otherwise send the write without it)
+    const headers = (sentHeaders) => Object.fromEntries(Object.entries(sentHeaders).filter(([h]) => {
+        if (!credentialHeader(h))
+            return true;
+        withheld.add(`header:${h.toLowerCase()}`);
+        return false;
+    }));
+    const asSent = sent
+        ? { ...activity, path: sent.path, query: withoutCredentials(sent.query, '', withheld), body: withoutCredentials(safeBody, sent.type ?? '', withheld), headers: headers(sent.headers), ...(sent.lane ? { lane: sent.lane } : {}), ...(sent.requestId ? { requestId: sent.requestId } : {}), ...(sent.type ? { contentType: sent.type } : {}) }
+        : { ...activity, path: call.params, body: withoutCredentials(safeBody, '', withheld) };
+    const named = () => (withheld.size ? { withheld: [...withheld].sort() } : {});
     if (id === 'graphql') {
         const b = (sent?.body ?? {});
-        return { ...activity, graphql: { query: b.query, variables: b.variables ?? {}, ...(b.operationName ? { operationName: b.operationName } : {}) }, ...(sent?.lane ? { lane: sent.lane } : {}), headers: sent?.headers ?? {} };
+        const variables = withoutCredentials(b.variables ?? {}, '', withheld);
+        return { ...activity, graphql: { query: b.query, variables, ...(b.operationName ? { operationName: b.operationName } : {}) }, ...(sent?.lane ? { lane: sent.lane } : {}), headers: headers(sent?.headers ?? {}), ...named() };
     }
     if (id === 'clock')
         return { clock: true };
     if (id === 'unmatched')
-        return { gap: true, ...asSent };
+        return { gap: true, ...asSent, ...named() };
     if ((m.doors ?? []).some((d) => d.id === id) || (m.screens ?? []).some((sc) => sc.id === id) || (m.accountSetup ?? []).some((a) => a.operation === id) || id === 'machine-pool' || id.startsWith('socket:'))
-        return { door: id, ...asSent };
-    return { operationId: id, ...asSent };
+        return { door: id, ...asSent, ...named() };
+    return { operationId: id, ...asSent, ...named() };
 }
 /** The scope each call is served in (serveCore, contextFor), for the contexts a write opens for its hooks. */
 const scopeOfCall = new WeakMap();

package/dist/src/derived-real.js

@@ -348,6 +348,11 @@ function performOf(units) {
         const unit = unitOf(units, input);
         if (!unit)
             throw new RefusedWriteError('vendor', `the write records no operation of the vendor's surface (${String(input.operationId ?? 'none')})`, first.id);
+        // A credential the request carried was not kept (no World records one in plaintext: ADR 0025), so the request as
+        // recorded is not the request that was made; it is refused, never sent without it.
+        const withheld = Array.isArray(input.withheld) ? input.withheld.map(String) : [];
+        if (withheld.length)
+            throw new RefusedWriteError('vendor', `the write's ${withheld.join(', ')} ${withheld.length === 1 ? 'was' : 'were'} not kept (no World records a credential in plaintext), so it is not sent again; make it at the vendor`, first.id);
         const { manifest: m, surface } = unit;
         // ids the World minted are sent as the vendor's: every stored type's adopted aliases, tried in turn
         const types = [...new Set(Object.keys(m.resources).map((r) => storedType(m, r)))];

package/dist/src/index.d.ts

@@ -53,7 +53,7 @@ export { blobDigest } from './blob-store.js';
 export { gunzip, gzip } from './bytes.js';
 export { ownFields } from './log.js';
 export type { TwinResource } from './serve.js';
-export { passwordHash, personOf, personWith, recordPerson, type Person } from './people.js';
+export { passwordHash, personOf, personWith, recordPerson, shownPersonFields, type Person } from './people.js';
 export { EngineDatabaseError, EngineUnavailableError, quoteIdent } from './managed-database.js';
 export type { Batch as EngineBatch, ManagedDatabase, Statement as EngineStatement, StatementResult as EngineStatementResult } from './managed-database.js';
 export type { Mail, SmtpRoute } from './smtp.js';

package/dist/src/index.js

@@ -44,7 +44,7 @@ export { gunzip, gzip } from "./bytes.js";
 // a row's own fields, where the tree's reserved ones (id, type, updatedAt) shadow the vendor's of the same name
 export { ownFields } from "./log.js";
 // the people a vendor's pages sign in (a `_person` row with its password's hash)
-export { passwordHash, personOf, personWith, recordPerson } from "./people.js";
+export { passwordHash, personOf, personWith, recordPerson, shownPersonFields } from "./people.js";
 // the World's managed Postgres a handler reaches as `ctx.engine` (managed-database.ts), and a mail's route (`ctx.mail`)
 export { EngineDatabaseError, EngineUnavailableError, quoteIdent } from "./managed-database.js";
 // S3's wire (contract "S3's wire is a kernel library too") and the git plane (contract "The git plane is a kernel library")

package/dist/src/people.d.ts

@@ -9,5 +9,8 @@ export declare const passwordHash: (email: string, password: string) => string;
 export declare function recordPerson(ctx: HandlerContext, email: string, password: string, fields?: Record<string, unknown>): Promise<Person>;
 /** The person with this email, or undefined. */
 export declare const personOf: (ctx: HandlerContext, email: string) => Person | undefined;
+/** A person's fields as a reader shows them (the CLI's log and diff, a diff's field changes): the password's hash as
+ *  `(set)`, never its value. A changeset keeps the hash, which its replay writes (ADR 0025). */
+export declare function shownPersonFields(fields: Record<string, unknown>): Record<string, unknown>;
 /** The person whose email and password these are, or undefined. */
 export declare function personWith(ctx: HandlerContext, email: string, password: string): Person | undefined;

package/dist/src/people.js

@@ -11,6 +11,11 @@ export async function recordPerson(ctx, email, password, fields = {}) {
 }
 /** The person with this email, or undefined. */
 export const personOf = (ctx, email) => ctx.rowsRaw(PERSON).find((p) => p.email === email.trim().toLowerCase());
+/** A person's fields as a reader shows them (the CLI's log and diff, a diff's field changes): the password's hash as
+ *  `(set)`, never its value. A changeset keeps the hash, which its replay writes (ADR 0025). */
+export function shownPersonFields(fields) {
+    return 'password_sha256' in fields ? { ...fields, password_sha256: '(set)' } : fields;
+}
 /** The person whose email and password these are, or undefined. */
 export function personWith(ctx, email, password) {
     const person = personOf(ctx, email);

package/dist/src/runtime.d.ts

@@ -44,7 +44,8 @@ export { createTwinProxy } from './proxy.js';
 export type { TwinProxy, TwinProxyOptions, VendorRoute } from './proxy.js';
 export { forkTwin, isFork, readForkMeta, } from './fork.js';
 export type { ForkMeta } from './fork.js';
-export { appendAction, appendTransactionCommit, checkPrecondition, confirmAction, listActions, listTransactionCommits, pendingActions, pushablePendingActions, isTwinBookkeeping, pendingTransactionCommits, projectResources, projectOwnerResources, OwnerStoreAmbiguousError, revertAction, TwinActionPreconditionError, subjectAliases, resolveSubjectId, runWithCorrelationId, currentCorrelationId } from './actions.js';
+export { appendAction, appendTransactionCommit, checkPrecondition, confirmAction, listActions, listTransactionCommits, pendingActions, pushablePendingActions, isTwinBookkeeping, isWorldPerson, inWorldHistory, pendingTransactionCommits, projectResources, projectOwnerResources, OwnerStoreAmbiguousError, revertAction, TwinActionPreconditionError, subjectAliases, resolveSubjectId, runWithCorrelationId, currentCorrelationId } from './actions.js';
+export { shownPersonFields } from './people.js';
 export type { ActionProjection, ProjectedDelivery, ProjectedResource, ProjectedResourcePatch, ProjectedResourceRef, TwinAction, TwinActionOp, TwinActionPrecondition, TwinActionPreconditionOp, TwinActionRevertSpec, TwinTransactionCommit, TwinTransactionCommitOp, TwinTransactionPrecondition, TwinTransactionRevertSpec, } from './actions.js';
 export { approveChangeset, assertMarkerBelongsTo, assertSafeChangesetName, assertValidVerifiers, buildChangeset, captureMarker, changesetContentHash, changesetHashMatches, changesetReadiness, approverOf, CHANGESET_KIND, diffLedgers, describeActionFields, fieldDiffKey, formatApplication, formatChangeset, formatRebaseReport, narrateActions, narrationDrift, rebaseChangeset, formatChangesetStatus, formatLedgerDelta, formatReplayReport, formatVerification, MARKER_KIND, normalizeChangeset, parseVerifierExpression, replayChangeset, runChangesetVerifiers, summarizeByVendor, twinWriteShape, withApplication, withVerification, worldBootMarker, WORLD_BOOT_MARKER_ID, } from './changeset.js';
 export type { ApplyReceipt, RebaseActionResult, RebaseReport, RebaseTarget, Changeset, ChangesetAction, ChangesetApplication, CompensationEntry, ChangesetApproval, ChangesetReadiness, ChangesetVerification, ChangesetVerifier, ChangesetVerifierResult, LedgerDelta, LedgerPosition, LedgerRef, ReplayActionResult, ReplayReport, ReplayTarget, VendorSummary, WorldMarker, } from './changeset.js';

package/dist/src/runtime.js

@@ -58,7 +58,9 @@ export { FsBlobStore, MemoryBlobStore, blobDigest, getActiveBlobStore, setActive
 export { applyTwinWrite, applyTwinWrites, applyTwinWriteAtomic, createTwinServer, CALLER_HEADER, callerForHeader, callerFromHeader, journalTwinRequest, readTwinRequestJournalFrom, twinRequestJournalFailures, twinRequestCredentials, readTwinRequestJournal, recordedInput, resolveTwinRead, twinRequestJournalEnabled, twinRequestJournalPath, twinResources, } from "./serve.js";
 export { createTwinProxy } from "./proxy.js";
 export { forkTwin, isFork, readForkMeta, } from "./fork.js";
-export { appendAction, appendTransactionCommit, checkPrecondition, confirmAction, listActions, listTransactionCommits, pendingActions, pushablePendingActions, isTwinBookkeeping, pendingTransactionCommits, projectResources, projectOwnerResources, OwnerStoreAmbiguousError, revertAction, TwinActionPreconditionError, subjectAliases, resolveSubjectId, runWithCorrelationId, currentCorrelationId } from "./actions.js";
+export { appendAction, appendTransactionCommit, checkPrecondition, confirmAction, listActions, listTransactionCommits, pendingActions, pushablePendingActions, isTwinBookkeeping, isWorldPerson, inWorldHistory, pendingTransactionCommits, projectResources, projectOwnerResources, OwnerStoreAmbiguousError, revertAction, TwinActionPreconditionError, subjectAliases, resolveSubjectId, runWithCorrelationId, currentCorrelationId } from "./actions.js";
+// a person as a reader shows it, its password's hash as (set) (ADR 0025)
+export { shownPersonFields } from "./people.js";
 // ── Operator control plane (R19/R20): remote refs, queue lifecycle, push ledger,
 // apply leases, plan, status. (the twins architecture notes)
 // The CHANGESET primitive + the ledger DIFF (docs/concepts/the-model.md v0) — "commit" and

package/generated/pack-facts.json

@@ -1208,16 +1208,34 @@
       "resources": [
         "client",
         "account",
-        "access_token"
+        "access_token",
+        "api_key"
       ],
       "endpointEnvNone": "Google's OAuth libraries read no base-URL variable: the endpoints are the discovery document's, claimed by the host rules.",
       "credentialDoor": {
-        "path": "/_twin/service-accounts",
+        "path": "/_twin/credentials",
         "body": {
-          "client_email": "world@world-project.iam.gserviceaccount.com"
+          "client_email": "world@world-project.iam.gserviceaccount.com",
+          "client": {
+            "redirect_uris": [
+              "http://localhost:3000/oauth2callback"
+            ],
+            "name": "World App"
+          },
+          "account": {
+            "sub": "100000000000000000001",
+            "email": "person@world.example",
+            "name": "World Person"
+          },
+          "api_key": {
+            "name": "API key 1"
+          }
         },
         "fill": {
-          "GOOGLE_APPLICATION_CREDENTIALS": "file:credentials"
+          "GOOGLE_APPLICATION_CREDENTIALS": "file:credentials",
+          "GOOGLE_CLIENT_ID": "client_id",
+          "GOOGLE_CLIENT_SECRET": "client_secret",
+          "YOUTUBE_API_KEY": "api_key"
         }
       },
       "serveExport": "createGoogleoauthTwinServer"
@@ -1370,6 +1388,53 @@
       },
       "serveExport": "createHuggingfaceTwinServer"
     },
+    "instagram": {
+      "adoption": {
+        "sdks": [],
+        "envStems": [
+          "INSTAGRAM"
+        ]
+      },
+      "hosts": [
+        {
+          "host": "graph.instagram.com"
+        },
+        {
+          "host": "api.instagram.com"
+        },
+        {
+          "host": "www.instagram.com",
+          "pathPattern": "^/oauth/authorize"
+        },
+        {
+          "host": "scontent.cdninstagram.com"
+        }
+      ],
+      "archetype": "crud",
+      "protocol": {
+        "declared": "3",
+        "major": 3,
+        "standing": "current"
+      },
+      "transport": "rest",
+      "resources": [
+        "container",
+        "media",
+        "comment"
+      ],
+      "endpointEnvNone": "an app calls graph.instagram.com and api.instagram.com and sends people to www.instagram.com; the World claims the hosts",
+      "credentialDoor": {
+        "path": "/_twin/app-credentials",
+        "body": {},
+        "fill": {
+          "INSTAGRAM_APP_ID": "app_id",
+          "INSTAGRAM_APP_SECRET": "app_secret",
+          "INSTAGRAM_ACCESS_TOKEN": "access_token",
+          "INSTAGRAM_USER_ID": "user_id"
+        }
+      },
+      "serveExport": "createInstagramTwinServer"
+    },
     "intercom": {
       "adoption": {
         "sdks": [
@@ -3383,6 +3448,71 @@
         }
       },
       "serveExport": "createXaiTwinServer"
+    },
+    "youtube": {
+      "adoption": {
+        "sdks": [
+          "@googleapis/youtube"
+        ],
+        "envStems": [
+          "YOUTUBE"
+        ]
+      },
+      "hosts": [
+        {
+          "host": "www.googleapis.com",
+          "pathPattern": "^/(upload/|resumable/upload/)?youtube/v3(/|$)"
+        },
+        {
+          "host": "youtube.googleapis.com",
+          "pathPattern": "^/(upload/|resumable/upload/)?youtube/v3(/|$)|^/_twin/"
+        }
+      ],
+      "archetype": "crud",
+      "protocol": {
+        "declared": "3",
+        "major": 3,
+        "standing": "current"
+      },
+      "transport": "rest",
+      "resources": [
+        "channel",
+        "video",
+        "liveBroadcast",
+        "liveStream",
+        "liveChatMessage",
+        "commentThread",
+        "comment",
+        "_upload_session",
+        "_live_chat",
+        "_comment_ban",
+        "_live",
+        "_live_segment"
+      ],
+      "endpointEnvNone": "Google's generated clients take rootUrl in code (googleapis: https://youtube.googleapis.com/); the World routes the declared YouTube paths on both API hosts",
+      "credentialDoor": {
+        "path": "/_twin/channels",
+        "body": {
+          "sub": "100000000000000000001",
+          "title": "World Channel",
+          "handle": "worldchannel"
+        },
+        "fill": {
+          "YOUTUBE_CHANNEL_ID": "id"
+        }
+      },
+      "credentialIssuer": "googleoauth",
+      "sidePorts": [
+        {
+          "name": "ingest",
+          "option": "ingestPort",
+          "flag": "--ingest-port",
+          "scheme": "rtmp",
+          "path": "/live2",
+          "note": "YouTube's RTMP ingest (<ingestionAddress>/<streamName>): an encoder publishes a liveStream's video here"
+        }
+      ],
+      "serveExport": "createYoutubeTwinServer"
     }
   },
   "undeclared": []

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/world-core",
-  "version": "3.0.158",
+  "version": "3.0.160",
   "description": "The kernel of Volter World: one log per twin, branches as pointers, checkpoints, the fold that keeps a twin current, the head that performs a write against the vendor, references, and the git plane. A twin package builds on it; the runtime serves it.",
   "keywords": [
     "twin",

package/src/actions.ts

@@ -680,11 +680,25 @@ export function pendingActions(service: string, root?: string): TwinAction[] {
 
 /** A twin's OWN bookkeeping in its action log — a subject type beginning with `_` (stripe's
  *  `_idempotency` store, for one): part of the overlay the twin serves from, never a change the
- *  app made. It is not in the log a user reads, not in a diff, not in a changeset, not pushed. */
+ *  app made. It is not pushed or deployed. It is not in the log a user reads, a diff or a changeset either, except the
+ *  World's people (`isWorldPerson`). */
 export function isTwinBookkeeping(action: Pick<TwinAction, 'subject'>): boolean {
   return action.subject.type.startsWith('_');
 }
 
+/** A person a twin's pages sign in (`_person`, people.ts): bookkeeping to the kernel, and the one bookkeeping the log
+ *  a user reads, the diff and every changeset carry, so an account replayed into another World signs in there. A
+ *  replay writes its committed row (the email, the password's hash and what the sign-up keeps), never the sign-up.
+ *  ADR 0025. */
+export function isWorldPerson(action: Pick<TwinAction, 'subject'>): boolean {
+  return action.subject.type === '_person';
+}
+
+/** Whether an action is in the World's history as a user reads it, diffs it and cuts changesets from it. */
+export function inWorldHistory(action: Pick<TwinAction, 'subject'>): boolean {
+  return !isTwinBookkeeping(action) || isWorldPerson(action);
+}
+
 /** The PUSHABLE suffix — `log origin..HEAD` as the push arm, the pending door, plans and the
  *  unpushed count read it: the overlay minus quarantined rows (an import is a copy, not a
  *  decision; releasing a quarantined row is an explicit act, never a scheduler's) and minus the

package/src/changeset.ts

@@ -58,7 +58,7 @@ import { worldPaths } from './storage.ts';
 // discovery and the CLI verbs; the state-level logic lives here, beside the ledgers it reads.
 import { createHash } from 'node:crypto';
 import { aliasesFrom, parentEntries, readTreeMapsAt, wholeLog, type Entry } from './log.ts';
-import { appendActionIfAbsent, checkPrecondition, listActions, projectedPreconditionValue, projectResources, isTwinBookkeeping } from './actions.ts';
+import { appendActionIfAbsent, checkPrecondition, listActions, projectedPreconditionValue, projectResources, inWorldHistory, isWorldPerson } from './actions.ts';
 import type { TwinActionRevertSpec } from './actions.ts';
 import { touchedSubjects } from './actions.ts';
 import type { PerformAction } from './head.ts';
@@ -312,7 +312,7 @@ export function diffLedgers(opts: { world: string; ledgers: LedgerRef[]; base: W
       }
     }
     rows.slice(from).forEach((action, offset) => {
-      if (isTwinBookkeeping(action)) return; // the twin's own store, never a change the app made
+      if (!inWorldHistory(action)) return; // the twin's own store, never a change the app made (a person is the World's: ADR 0025)
       ordered.push({ entry: { service: ledger.service, stateService: ledger.stateService, action }, ledgerIndex, rowIndex: from + offset });
     });
   });
@@ -358,10 +358,13 @@ export function describeActionFields(ledgers: LedgerRef[], actions: ChangesetAct
       if (!action.fields) continue;
       const subject = trees.get(positions.get(action.id)!)?.get(`${action.subject.type}:${action.subject.id}`);
       const fields = subject?.fields ?? {};
-      fieldChanges[fieldDiffKey(service, stateService, action.id)] = diffSubjectFields({
+      const changes = diffSubjectFields({
         subject: action.subject, fields, fieldHashes: Object.fromEntries(Object.entries(fields).map(([k, v]) => [k, hashFieldValue(v)])),
         latestEventId: '', updatedAt: '',
       }, action.fields);
+      // a person's password hash is shown as set, never its value (ADR 0025)
+      if (isWorldPerson(action) && changes.password_sha256) changes.password_sha256 = { before: changes.password_sha256.before === undefined ? undefined : '(set)', after: '(set)' };
+      fieldChanges[fieldDiffKey(service, stateService, action.id)] = changes;
     }
   }
   return fieldChanges;

package/src/derived-core.ts

@@ -1201,6 +1201,72 @@ function provisioningInput(call: DerivedCall): { input?: { activity: 'provisioni
   return call.request.headers.get('x-volter-world-activity') === 'provisioning' ? { input: { activity: 'provisioning' } } : {};
 }
 
+/** Whether a field names a credential: a password under any name the packs' doors and screens give it (`password`,
+ *  `passwd`, `pw`, `pass`, `session_password`, `user[password]`…; a screen names its own field, world-ui's SignIn
+ *  `password.name`, so the rule reads the name, not a list), or a secret, an API key, an access, refresh or id token, a
+ *  PKCE verifier or a private key, alone or as the name's last part. ADR 0025. */
+const credentialKey = (key: string): boolean => {
+  const k = key.toLowerCase();
+  return k.includes('password') || k.includes('passwd') || /(^|[[_.-])(pw|pass|secret|client_secret|api_?key|apikey|access_token|refresh_token|id_token|code_verifier|private_key)\]?$/.test(k);
+};
+/** A request header that carries a credential: never recorded, whatever a manifest names (the executor sends the real
+ *  system's own from custody). */
+const credentialHeader = (header: string): boolean => {
+  const h = header.toLowerCase();
+  return h === 'authorization' || h === 'proxy-authorization' || h === 'cookie' || /(^|-)api-?key$/.test(h) || /token|secret|password|passwd/.test(h);
+};
+/** A form's text as a `<form method="post">` sends it (`a=1&password=…`), told apart from other text. */
+/** A posted form's fields without its credentials, or the text unchanged, byte for byte, when it carries none. */
+function formWithoutCredentials(text: string, removed: Set<string>): string {
+  const form = new URLSearchParams(text);
+  const credentials = [...new Set(form.keys())].filter(credentialKey);
+  if (!credentials.length) return text;
+  for (const key of credentials) { removed.add(key); form.delete(key); }
+  return form.toString();
+}
+/** A multipart form's parts without one named for a credential, or the text unchanged when none is. */
+function multipartWithoutCredentials(text: string, boundary: string, removed: Set<string>): string {
+  const parts = text.split(`--${boundary}`);
+  const kept = parts.filter((part) => {
+    const name = /name="([^"]*)"/.exec(part)?.[1] ?? '';
+    if (!credentialKey(name)) return true;
+    removed.add(name);
+    return false;
+  });
+  return kept.length === parts.length ? text : kept.join(`--${boundary}`);
+}
+/** A recorded request's body or query without its credentials, named in `removed`: fields named for one are taken out of
+ *  a JSON value at any depth. A body that is a posted form (its content type says so) is read as one: its text, as it
+ *  came or kept as `{ $text }`, loses its credential fields (re-encoded with URLSearchParams, the others in order), and a
+ *  multipart form loses a part named for one. Any other string, at any depth, is left as it was: a URL with a query in
+ *  a JSON body (a checkout's success_url) is a value, not a form. */
+function withoutCredentials(value: unknown, contentType = '', removed = new Set<string>()): unknown {
+  const form = /application\/x-www-form-urlencoded/i.test(contentType);
+  const boundary = /multipart\/form-data;.*boundary="?([^";]+)"?/i.exec(contentType)?.[1];
+  if (typeof value === 'string') return form ? formWithoutCredentials(value, removed) : boundary ? multipartWithoutCredentials(value, boundary, removed) : value;
+  // (a body that came as text is kept as { $text }: the form is in it)
+  if (form && value && typeof value === 'object' && typeof (value as { $text?: unknown }).$text === 'string') {
+    return { ...(value as object), $text: formWithoutCredentials((value as { $text: string }).$text, removed) };
+  }
+  return withoutCredentialFields(value, removed);
+}
+/** A JSON value without the fields named for a credential, at any depth; every other value is kept as it was. */
+function withoutCredentialFields(value: unknown, removed: Set<string>): unknown {
+  if (Array.isArray(value)) return value.map((v) => withoutCredentialFields(v, removed));
+  if (!value || typeof value !== 'object') return value;
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== Object.prototype && proto !== null) return value;
+  return Object.fromEntries(Object.entries(value).filter(([key]) => {
+    if (!credentialKey(key)) return true;
+    removed.add(key);
+    return false;
+  }).map(([key, v]) => [key, withoutCredentialFields(v, removed)]));
+}
+
+/** What a write records of its request, with no credential in it on any branch (ADR 0025): the body (JSON, form text,
+ *  multipart), the declared query and the GraphQL variables lose their credential fields, and a header that carries one
+ *  is not recorded. A write whose body, query or a header lost a field names it in `withheld`, so a deploy, which
+ *  sends the recorded request again, refuses it rather than sending it without (derived-real.ts performOf). */
 function recordedInput(m: DerivedManifest, call: DerivedCall, merged: Record<string, unknown>): Record<string, unknown> {
   const id = call.operation.id;
   const sent = sentOf.get(call);
@@ -1209,15 +1275,26 @@ function recordedInput(m: DerivedManifest, call: DerivedCall, merged: Record<str
   const body = sent?.body ?? merged;
   const safeBody = door?.redactBody?.length && body && typeof body === 'object' && !Array.isArray(body)
     ? Object.fromEntries(Object.entries(body).filter(([key]) => !door.redactBody!.includes(key))) : body;
-  const asSent = sent ? { ...activity, path: sent.path, query: sent.query, body: safeBody, headers: sent.headers, ...(sent.lane ? { lane: sent.lane } : {}), ...(sent.requestId ? { requestId: sent.requestId } : {}), ...(sent.type ? { contentType: sent.type } : {}) } : { ...activity, path: call.params, body: safeBody };
+  const withheld = new Set<string>();
+  // (a header a manifest names that carries a credential is named too: a deploy would otherwise send the write without it)
+  const headers = (sentHeaders: Record<string, string>): Record<string, string> => Object.fromEntries(Object.entries(sentHeaders).filter(([h]) => {
+    if (!credentialHeader(h)) return true;
+    withheld.add(`header:${h.toLowerCase()}`);
+    return false;
+  }));
+  const asSent = sent
+    ? { ...activity, path: sent.path, query: withoutCredentials(sent.query, '', withheld) as Record<string, string | string[]>, body: withoutCredentials(safeBody, sent.type ?? '', withheld), headers: headers(sent.headers), ...(sent.lane ? { lane: sent.lane } : {}), ...(sent.requestId ? { requestId: sent.requestId } : {}), ...(sent.type ? { contentType: sent.type } : {}) }
+    : { ...activity, path: call.params, body: withoutCredentials(safeBody, '', withheld) };
+  const named = (): { withheld?: string[] } => (withheld.size ? { withheld: [...withheld].sort() } : {});
   if (id === 'graphql') {
     const b = (sent?.body ?? {}) as { query?: unknown; variables?: unknown; operationName?: unknown };
-    return { ...activity, graphql: { query: b.query, variables: b.variables ?? {}, ...(b.operationName ? { operationName: b.operationName } : {}) }, ...(sent?.lane ? { lane: sent.lane } : {}), headers: sent?.headers ?? {} };
+    const variables = withoutCredentials(b.variables ?? {}, '', withheld);
+    return { ...activity, graphql: { query: b.query, variables, ...(b.operationName ? { operationName: b.operationName } : {}) }, ...(sent?.lane ? { lane: sent.lane } : {}), headers: headers(sent?.headers ?? {}), ...named() };
   }
   if (id === 'clock') return { clock: true };
-  if (id === 'unmatched') return { gap: true, ...asSent };
-  if ((m.doors ?? []).some((d) => d.id === id) || (m.screens ?? []).some((sc) => sc.id === id) || (m.accountSetup ?? []).some((a) => a.operation === id) || id === 'machine-pool' || id.startsWith('socket:')) return { door: id, ...asSent };
-  return { operationId: id, ...asSent };
+  if (id === 'unmatched') return { gap: true, ...asSent, ...named() };
+  if ((m.doors ?? []).some((d) => d.id === id) || (m.screens ?? []).some((sc) => sc.id === id) || (m.accountSetup ?? []).some((a) => a.operation === id) || id === 'machine-pool' || id.startsWith('socket:')) return { door: id, ...asSent, ...named() };
+  return { operationId: id, ...asSent, ...named() };
 }
 
 /** The scope each call is served in (serveCore, contextFor), for the contexts a write opens for its hooks. */

package/src/derived-real.ts

@@ -292,6 +292,10 @@ function performOf(units: Unit[]): PerformAction {
     const first = group[0]!;
     const unit = unitOf(units, input);
     if (!unit) throw new RefusedWriteError('vendor', `the write records no operation of the vendor's surface (${String(input.operationId ?? 'none')})`, first.id);
+    // A credential the request carried was not kept (no World records one in plaintext: ADR 0025), so the request as
+    // recorded is not the request that was made; it is refused, never sent without it.
+    const withheld = Array.isArray(input.withheld) ? (input.withheld as unknown[]).map(String) : [];
+    if (withheld.length) throw new RefusedWriteError('vendor', `the write's ${withheld.join(', ')} ${withheld.length === 1 ? 'was' : 'were'} not kept (no World records a credential in plaintext), so it is not sent again; make it at the vendor`, first.id);
     const { manifest: m, surface } = unit;
     // ids the World minted are sent as the vendor's: every stored type's adopted aliases, tried in turn
     const types = [...new Set(Object.keys(m.resources).map((r) => storedType(m, r)))];

package/src/index.ts

@@ -72,7 +72,7 @@ export { gunzip, gzip } from './bytes.ts';
 export { ownFields } from './log.ts';
 export type { TwinResource } from './serve.ts';
 // the people a vendor's pages sign in (a `_person` row with its password's hash)
-export { passwordHash, personOf, personWith, recordPerson, type Person } from './people.ts';
+export { passwordHash, personOf, personWith, recordPerson, shownPersonFields, type Person } from './people.ts';
 // the World's managed Postgres a handler reaches as `ctx.engine` (managed-database.ts), and a mail's route (`ctx.mail`)
 export { EngineDatabaseError, EngineUnavailableError, quoteIdent } from './managed-database.ts';
 export type { Batch as EngineBatch, ManagedDatabase, Statement as EngineStatement, StatementResult as EngineStatementResult } from './managed-database.ts';

package/src/people.ts

@@ -24,6 +24,12 @@ export async function recordPerson(ctx: HandlerContext, email: string, password:
 export const personOf = (ctx: HandlerContext, email: string): Person | undefined =>
   ctx.rowsRaw(PERSON).find((p) => p.email === email.trim().toLowerCase()) as Person | undefined;
 
+/** A person's fields as a reader shows them (the CLI's log and diff, a diff's field changes): the password's hash as
+ *  `(set)`, never its value. A changeset keeps the hash, which its replay writes (ADR 0025). */
+export function shownPersonFields(fields: Record<string, unknown>): Record<string, unknown> {
+  return 'password_sha256' in fields ? { ...fields, password_sha256: '(set)' } : fields;
+}
+
 /** The person whose email and password these are, or undefined. */
 export function personWith(ctx: HandlerContext, email: string, password: string): Person | undefined {
   const person = personOf(ctx, email);

package/src/runtime.ts

@@ -206,12 +206,16 @@ export {
   pendingActions,
   pushablePendingActions,
   isTwinBookkeeping,
+  isWorldPerson,
+  inWorldHistory,
   pendingTransactionCommits,
   projectResources,
   projectOwnerResources,
   OwnerStoreAmbiguousError,
   revertAction,
   TwinActionPreconditionError, subjectAliases, resolveSubjectId, runWithCorrelationId, currentCorrelationId } from './actions.ts';
+// a person as a reader shows it, its password's hash as (set) (ADR 0025)
+export { shownPersonFields } from './people.ts';
 export type {
   ActionProjection,
   ProjectedDelivery,