@volter/twin-github 2.0.0 → 2.0.2

package/dist/src/semantics/users.js

@@ -1,10 +1,16 @@
 // GitHub's users family: a user by login or account id, the authenticated user and their profile,
 // the follow graph, emails, SSH and GPG keys, blocks, and the activity streams scoped to a user.
-// The twin models one follow actor, the authenticated `octocat`.
+// Each account's profile and email addresses are its own: GET /user, PATCH /user and /user/emails answer and change the
+// account the request's token names (a personal token, or the token an OAuth app got from the person who consented,
+// src/screens/oauth.tsx); the World's shared token is octocat's. The follow graph is per account too. SSH and GPG keys
+// and blocks are still ONE list whoever asks (todo rows github.users.own_keys, github.users.own_blocks).
 import { me } from "./activity.js";
 import { createHash } from 'node:crypto';
-import { githubActivityEvents, githubNotFound, paginate, seedUser, toGithubOrg, toGithubRepo, toGithubUser, toGithubUserEmail, toGithubUserGpgKey, toGithubUserSshKey, toSimpleUser, twinUserId, } from "../github-twin.js";
-import { asView, gh, nextSeq, put, send } from "./shared.js";
+import { accountOf, canonicalLogin, emailsOf, githubActivityEvents, githubNotFound, paginate, seedUser, toGithubOrg, toGithubRepo, toGithubUser, toGithubUserEmail, toGithubUserGpgKey, toGithubUserSshKey, toSimpleUser, twinUserId, } from "../github-twin.js";
+import { asView, atomic, gh, nextSeq, put, send } from "./shared.js";
+/** An app's installation token speaks for the app, which has no profile or addresses of its own to change: GitHub
+ *  answers its writes to the authenticated user 403 "Resource not accessible by integration". */
+const asApp = (ctx) => (gh(ctx).caller ?? '').endsWith('[bot]') ? ctx.reply({ message: 'Resource not accessible by integration', documentation_url: 'https://docs.github.com/rest/users/users#update-the-authenticated-user' }, 403) : undefined;
 /** GET /users/:login/events[/public] and /users/:login/received_events[/public]: events = activity the
  *  user PERFORMED (actor); received_events = activity in repos the user OWNS. Both filter the SAME
  *  modeled stream. */
@@ -22,8 +28,9 @@ const userEvents = (received, only) => async (ctx) => {
 export function usersSemantics() {
     const usersGetByUsername = async (ctx) => {
         const { seg, state } = gh(ctx);
-        const login = decodeURIComponent(seg[1]);
-        return ctx.reply(toGithubUser(login === 'octocat' ? { ...seedUser('octocat'), ...state().userProfile, login } : seedUser(login)));
+        // a login in another case names the same account, answered as it is spelled (and with its id)
+        const login = canonicalLogin(decodeURIComponent(seg[1]), ctx.root);
+        return ctx.reply(toGithubUser(accountOf(state(), login)));
     };
     const reposListForAuthenticatedUser = async (ctx) => {
         const { caller, query, state } = gh(ctx);
@@ -90,11 +97,11 @@ export function usersSemantics() {
     };
     const usersListEmailsForAuthenticatedUser = async (ctx) => {
         const { query, state } = gh(ctx);
-        return ctx.reply(paginate(state().userEmails, query).map(toGithubUserEmail));
+        return ctx.reply(paginate(emailsOf(state(), me(ctx)), query).map(toGithubUserEmail));
     };
     const usersListPublicEmailsForAuthenticatedUser = async (ctx) => {
         const { query, state } = gh(ctx);
-        return ctx.reply(paginate(state().userEmails.filter((e) => e.visibility === 'public'), query).map(toGithubUserEmail));
+        return ctx.reply(paginate(emailsOf(state(), me(ctx)).filter((e) => e.visibility === 'public'), query).map(toGithubUserEmail));
     };
     const usersListPublicSshKeysForAuthenticatedUser = async (ctx) => {
         const { query, state } = gh(ctx);
@@ -123,19 +130,29 @@ export function usersSemantics() {
         return send(ctx, state().blockedUsers.has(decodeURIComponent(seg[2])) ? { status: 204, body: undefined } : githubNotFound());
     };
     const usersGetAuthenticated = async (ctx) => {
-        const { caller, state } = gh(ctx);
-        if (caller)
-            return ctx.reply(toGithubUser(seedUser(caller)));
-        return ctx.reply(toGithubUser({ ...seedUser('octocat'), ...state().userProfile, login: 'octocat' }));
+        const { state } = gh(ctx);
+        return ctx.reply(toGithubUser(accountOf(state(), me(ctx))));
     };
     const usersUpdateAuthenticated = async (ctx) => {
+        const refused = asApp(ctx);
+        if (refused)
+            return refused;
         const { body, state } = gh(ctx);
         const fields = {};
         for (const k of ['name', 'bio', 'company', 'blog', 'location', 'email'])
             if (body[k] !== undefined)
                 fields[k] = body[k];
-        await put(ctx, { operation: 'user_profile.update', subjectType: 'user_profile', subjectId: 'user_profile:octocat', fields });
-        return ctx.reply(toGithubUser({ ...seedUser('octocat'), ...state().userProfile, login: 'octocat' }));
+        const login = me(ctx);
+        // the public email is one of the account's own verified addresses (GitHub's profile settings offer only those; the
+        // REST docs name the field "The publicly visible email address of the user" and a 422 for a validation failure);
+        // empty or null shows none. The 422's wording is the twin's.
+        if (typeof fields.email === 'string' && fields.email !== '' && !emailsOf(state(), login).some((e) => e.verified && e.email.toLowerCase() === String(fields.email).toLowerCase())) {
+            return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'User', code: 'custom', field: 'email', message: 'email must be one of your verified email addresses' }], documentation_url: 'https://docs.github.com/rest/users/users#update-the-authenticated-user' }, 422);
+        }
+        if (fields.email !== undefined && fields.email !== null && typeof fields.email !== 'string')
+            return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'User', code: 'invalid', field: 'email' }] }, 422);
+        await put(ctx, { operation: 'user_profile.update', subjectType: 'user_profile', subjectId: `user_profile:${login.toLowerCase()}`, fields: { ...fields, login } });
+        return ctx.reply(toGithubUser(accountOf(state(), login)));
     };
     const usersCreatePublicSshKeyForAuthenticatedUser = async (ctx) => {
         const { body, occurredAt, state } = gh(ctx);
@@ -204,11 +221,12 @@ export function usersSemantics() {
         'users/list-blocked-by-authenticated-user': usersListBlockedByAuthenticatedUser,
         // "Check if a user is blocked by the authenticated user" → 204 blocked / 404 not.
         'users/check-blocked': usersCheckBlocked,
-        // the token's own user when the twin's user door minted it; else the deterministic octocat
+        // the token's own account (a personal token, an OAuth app's token for the person who consented) under the
+        // profile that person edited; the World's shared token is octocat's
         'users/get-authenticated': usersGetAuthenticated,
         'users/update-authenticated': usersUpdateAuthenticated,
-        'users/add-email-for-authenticated-user': async (ctx) => emails(ctx, false),
-        'users/delete-email-for-authenticated-user': async (ctx) => emails(ctx, true),
+        'users/add-email-for-authenticated-user': async (ctx) => asApp(ctx) ?? emails(ctx, false),
+        'users/delete-email-for-authenticated-user': async (ctx) => asApp(ctx) ?? emails(ctx, true),
         'users/create-public-ssh-key-for-authenticated-user': usersCreatePublicSshKeyForAuthenticatedUser,
         'users/delete-public-ssh-key-for-authenticated-user': usersDeletePublicSshKeyForAuthenticatedUser,
         'users/create-gpg-key-for-authenticated-user': usersCreateGpgKeyForAuthenticatedUser,
@@ -221,27 +239,51 @@ export function usersSemantics() {
         'users/unfollow': async (ctx) => follow(ctx, false),
     };
 }
-/** POST /user/emails adds, DELETE removes; both take `{emails}` or a bare array. The first address a
- *  user adds is primary and public. */
+/** POST /user/emails adds, DELETE removes, on the caller's own account; both take `{emails}` or a bare array. The
+ *  first address an account adds is primary and public. An address is one account's: adding one another account holds
+ *  is refused (422, the twin's wording: GitHub's docs name only the status), each address checked and claimed in one
+ *  atomic step, and removing one leaves every other account's addresses alone. The primary address is not removed
+ *  (422): GitHub has its person make another address primary first (github.com/orgs/community/discussions/62557; the
+ *  wording is the twin's). */
 async function emails(ctx, remove) {
     const { body, state } = gh(ctx);
+    const login = me(ctx);
     const list = Array.isArray(body.emails) ? body.emails.map(String) : Array.isArray(body) ? body.map(String) : [];
     if (!list.length)
         return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'Email', field: 'emails', code: 'missing_field' }] }, 422);
     const st = state();
+    const mine = (e) => e.login.toLowerCase() === login.toLowerCase();
+    const held = (email) => st.userEmails.find((e) => e.email.toLowerCase() === email.toLowerCase());
+    if (!remove && list.some((email) => { const h = held(email); return h && !mine(h); })) {
+        return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'UserEmail', code: 'custom', field: 'email', message: 'email is already in use' }] }, 422);
+    }
+    if (remove && list.some((email) => { const h = held(email); return h && mine(h) && h.primary; })) {
+        return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'UserEmail', code: 'custom', field: 'email', message: 'the primary email address cannot be removed' }] }, 422);
+    }
+    const hadNone = emailsOf(st, login).length === 0;
+    const claim = atomic(ctx);
     for (const email of list) {
-        const subjectId = `useremail:${email}`;
+        const h = held(email);
+        const subjectId = `useremail:${h?.email ?? email}`;
         if (remove) {
-            await put(ctx, { operation: 'user_email.delete', subjectType: 'user_email', subjectId, fields: { deleted: true, email } });
+            if (h && mine(h))
+                await put(ctx, { operation: 'user_email.delete', subjectType: 'user_email', subjectId, fields: { deleted: true, email: h.email } });
         }
-        else {
-            const isFirst = st.userEmails.length === 0 && email === list[0];
-            await put(ctx, { operation: 'user_email.upsert', subjectType: 'user_email', subjectId, fields: { email, primary: isFirst, verified: true, visibility: isFirst ? 'public' : 'private' } });
+        else if (!h) {
+            const isFirst = hadNone && email === list[0];
+            const lost = await claim(() => {
+                const now = state().userEmails.find((e) => e.email.toLowerCase() === email.toLowerCase());
+                if (now)
+                    return { value: !mine(now) };
+                return { value: false, write: { operation: 'user_email.upsert', subjectType: 'user_email', subjectId, fields: { email, primary: isFirst, verified: true, visibility: isFirst ? 'public' : 'private', login } } };
+            });
+            if (lost)
+                return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'UserEmail', code: 'custom', field: 'email', message: 'email is already in use' }] }, 422);
         }
     }
     if (remove)
         return send(ctx, { status: 204, body: undefined });
-    return ctx.reply(state().userEmails.map(toGithubUserEmail), 201);
+    return ctx.reply(emailsOf(state(), login).map(toGithubUserEmail), 201);
 }
 async function block(ctx, blocking) {
     const login = decodeURIComponent(gh(ctx).seg[2]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/twin-github",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Local GitHub twin — PR-evidence REST; your real `@octokit/rest` talks to it unmodified. Mirror, simulate, and fork. Built on @volter/world-core.",
   "keywords": [
     "twin",
@@ -57,16 +57,16 @@
     "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
   },
   "dependencies": {
-    "@volter/world-ui": "0.1.0",
+    "@volter/world-ui": "0.1.2",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "graphql": "16.14.2"
   },
   "peerDependencies": {
-    "@volter/world-core": "2.0.0"
+    "@volter/world-core": "2.0.2"
   },
   "devDependencies": {
-    "@volter/world-core": "2.0.0",
+    "@volter/world-core": "2.0.2",
     "@volter/world-tooling": "0.1.0",
     "@octokit/rest": "^22.0.1",
     "playwright": "^1.61.0",

package/src/github-capabilities.ts

@@ -2469,6 +2469,100 @@ export const GITHUB_CAPABILITIES: CapabilitySpec[] = [
       const after = await handleGithubRequest({ method: 'GET', path: `/user/emails`, root });
       return del.response.status === 204 && isArr(after.body) && after.body.length === 1;
     })),
+  done('github.users.sign_up', 'users', 'Users: a person signs up (username, email, password) and signs in; a username or address another account holds, or a password GitHub\'s rule refuses, is refused', 'api', 'common', () =>
+    withRoot(async (root) => {
+      const signUp = async (body: Record<string, string>) => (await applyGithubWrite({ method: 'POST', path: '/_twin/users', body: JSON.stringify(body), root })).response;
+      const made = await signUp({ login: 'sam-friends', email: 'sam@friends.test', password: 'correct-horse-1' });
+      if (!(made.status === 201 && (made.body as { login?: string }).login === 'sam-friends')) return false;
+      for (const refused of [
+        { login: 'Sam-Friends', email: 'other@friends.test', password: 'correct-horse-1' }, // the username, any case
+        { login: 'octocat', email: 'o@friends.test', password: 'correct-horse-1' }, // the World's user
+        { login: 'ada', email: 'SAM@friends.test', password: 'correct-horse-1' }, // the address, any case
+        { login: 'ada', email: 'ada@friends.test', password: 'short1' }, // under 8
+        { login: 'ada', email: 'ada@friends.test', password: 'NOLOWERCASE123' }, // 8 to 14 without a lowercase letter
+        { login: 'ada', email: 'not-an-address', password: 'correct-horse-1' },
+        { login: '-ada', email: 'ada@friends.test', password: 'correct-horse-1' },
+      ]) if ((await signUp(refused)).status !== 422) return false;
+      if ((await signUp({ login: 'ada', email: 'ada@friends.test', password: 'fifteen chars ok' })).status !== 201) return false;
+      // a username the World already knows is taken, whatever named it: a token holder, a repository's owner or collaborator
+      await mintToken(root, 'grace');
+      await applyGithubWrite({ method: 'POST', path: '/user/repos', body: JSON.stringify({ name: 'shared' }), root });
+      await applyGithubWrite({ method: 'PUT', path: '/repos/octocat/shared/collaborators/rui', body: '{}', root });
+      for (const login of ['Grace', 'rui']) if ((await signUp({ login, email: `${login}@friends.test`, password: 'correct-horse-1' })).status !== 422) return false;
+      // two sign-ups racing for one address: one account is made, the other refused, and the address is the made one's
+      const raced = await Promise.all([signUp({ login: 'kim', email: 'shared@friends.test', password: 'correct-horse-1' }), signUp({ login: 'lee', email: 'shared@friends.test', password: 'correct-horse-1' })]);
+      const winner = raced.find((r) => r.status === 201)?.body as { login?: string } | undefined;
+      if (raced.filter((r) => r.status === 201).length !== 1 || raced.filter((r) => r.status === 422).length !== 1) return false;
+      const holders = twinResources('github', root).filter((r) => r.type === 'user_email' && r.email === 'shared@friends.test' && r.deleted !== true);
+      if (!(holders.length === 1 && holders[0]!.login === winner?.login)) return false;
+      // the password signs its person in; a wrong one does not
+      const form = (login: string, password: string) => githubSessionFlow({ root, now: () => '2026-01-01T00:00:00.000Z' })(new Request('https://github.com/session', { method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams({ login, password, return_to: '/' }).toString() }));
+      const wrong = await form('sam-friends', 'wrong-horse-1');
+      const right = await form('sam-friends', 'correct-horse-1');
+      return wrong?.status === 200 && right?.status === 302 && (right.headers.getSetCookie() ?? []).some((c) => c.startsWith('dotcom_user=sam-friends;'));
+    })),
+  done('github.users.oauth_person', 'users', 'Users: the token an OAuth app gets from the person who signed in and consented answers that person\'s account: GET /user their login, name and avatar, GET /user/emails their own addresses; the World\'s shared token stays octocat\'s', 'api', 'common', () =>
+    withRoot(async (root) => {
+      const at = '2026-01-01T00:00:00.000Z';
+      // octocat's own address, from before anyone signed up
+      await applyGithubWrite({ method: 'POST', path: '/user/emails', body: JSON.stringify({ emails: ['octocat@github.test'] }), root });
+      await applyGithubWrite({ method: 'PATCH', path: '/user', body: JSON.stringify({ name: 'The Octocat' }), root });
+      const tokenFor = async (login: string, email: string): Promise<string> => {
+        await applyGithubWrite({ method: 'POST', path: '/_twin/users', body: JSON.stringify({ login, email, password: 'correct-horse-1' }), root });
+        const signed = await githubSessionFlow({ root, now: () => at })(new Request('https://github.com/session', { method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams({ login, password: 'correct-horse-1', return_to: '/' }).toString() }));
+        const cookie = (signed?.headers.getSetCookie() ?? []).map((c) => c.split(';')[0]).join('; ');
+        const consent = { client_id: 'librechat', redirect_uri: 'http://chat.local/oauth/github/callback', scope: 'user:email', state: login };
+        if ((await applyGithubWrite({ method: 'POST', path: '/login/oauth/authorize', body: JSON.stringify({ ...consent, authorize: '1' }), root, cookie })).response.status !== 302) return '';
+        const code = String(twinResources('github', root).find((r) => r.type === 'oauth_code' && r.login === login)?.code ?? '');
+        const ex = await applyGithubWrite({ method: 'POST', path: '/login/oauth/access_token', body: JSON.stringify({ client_id: 'librechat', code }), root });
+        return new URLSearchParams(String(ex.response.body)).get('access_token') ?? '';
+      };
+      const sam = await tokenFor('sam-friends', 'sam@friends.test');
+      const ada = await tokenFor('ada', 'ada@friends.test');
+      if (!sam || !ada) return false;
+      type U = { login?: string; name?: string | null; avatar_url?: string; id?: number };
+      const user = async (token?: string) => (await handleGithubRequest({ method: 'GET', path: '/user', root, ...(token ? { token } : {}) })).body as U;
+      const emails = async (token?: string) => (await handleGithubRequest({ method: 'GET', path: '/user/emails', root, ...(token ? { token } : {}) })).body as Array<{ email: string; primary: boolean; verified: boolean }>;
+      // before he names himself, GitHub has no name for him
+      const before = await user(sam);
+      if (!(before.login === 'sam-friends' && before.name === null && before.avatar_url === `https://avatars.githubusercontent.com/u/${before.id}?v=4`)) return false;
+      if ((await applyGithubWrite({ method: 'PATCH', path: '/user', body: JSON.stringify({ name: 'Sam Friends' }), root, token: sam })).response.status !== 200) return false;
+      const [s, a, o] = [await user(sam), await user(ada), await user()];
+      if (!(s.login === 'sam-friends' && s.name === 'Sam Friends' && a.login === 'ada' && a.name === null && o.login === 'octocat' && o.name === 'The Octocat')) return false;
+      if (((await handleGithubRequest({ method: 'GET', path: '/users/sam-friends', root })).body as U).name !== 'Sam Friends') return false;
+      // a login in another case is the same account, as it is spelled
+      const upper = (await handleGithubRequest({ method: 'GET', path: '/users/SAM-FRIENDS', root })).body as U;
+      if (!(upper.login === 'sam-friends' && upper.id === s.id && upper.name === 'Sam Friends')) return false;
+      // his public email is one of his own verified addresses, never another's
+      const pub = (email: string, token: string) => applyGithubWrite({ method: 'PATCH', path: '/user', body: JSON.stringify({ email }), root, token });
+      if ((await pub('ada@friends.test', sam)).response.status !== 422 || (await pub('nobody@friends.test', sam)).response.status !== 422) return false;
+      if (!((await pub('sam@friends.test', sam)).response.status === 200 && ((await user(sam)) as { email?: string }).email === 'sam@friends.test')) return false;
+      // his primary address is not removed while it is primary
+      if ((await applyGithubWrite({ method: 'DELETE', path: '/user/emails', body: JSON.stringify({ emails: ['sam@friends.test'] }), root, token: sam })).response.status !== 422) return false;
+      const [se, oe] = [await emails(sam), await emails()];
+      if (!(se.length === 1 && se[0]!.email === 'sam@friends.test' && se[0]!.primary && se[0]!.verified)) return false;
+      if (!(oe.length === 1 && oe[0]!.email === 'octocat@github.test')) return false;
+      // an address is one account's: Ada cannot add Sam's, and removing it as Ada leaves it his
+      if ((await applyGithubWrite({ method: 'POST', path: '/user/emails', body: JSON.stringify({ emails: ['sam@friends.test'] }), root, token: ada })).response.status !== 422) return false;
+      await applyGithubWrite({ method: 'DELETE', path: '/user/emails', body: JSON.stringify({ emails: ['sam@friends.test'] }), root, token: ada });
+      if ((await emails(sam)).length !== 1) return false;
+      await applyGithubWrite({ method: 'POST', path: '/user/emails', body: JSON.stringify({ emails: ['sam2@friends.test'] }), root, token: sam });
+      // Sam removes his second address; Ada adds it afresh, and it is hers alone (not primary: her first address is)
+      await applyGithubWrite({ method: 'DELETE', path: '/user/emails', body: JSON.stringify({ emails: ['sam2@friends.test'] }), root, token: sam });
+      await applyGithubWrite({ method: 'POST', path: '/user/emails', body: JSON.stringify({ emails: ['sam2@friends.test'] }), root, token: ada });
+      const [se2, ae2] = [await emails(sam), await emails(ada)];
+      if (!(se2.length === 1 && ae2.length === 2 && ae2.some((e) => e.email === 'sam2@friends.test' && !e.primary) && ae2.some((e) => e.email === 'ada@friends.test' && e.primary))) return false;
+      // an app's installation token has no profile or addresses to change
+      const app = await ciToken(root, HISTORY_REPO);
+      const byApp = [
+        await applyGithubWrite({ method: 'PATCH', path: '/user', body: JSON.stringify({ name: 'bot' }), root, token: app }),
+        await applyGithubWrite({ method: 'POST', path: '/user/emails', body: JSON.stringify({ emails: ['bot@friends.test'] }), root, token: app }),
+        await applyGithubWrite({ method: 'DELETE', path: '/user/emails', body: JSON.stringify({ emails: ['octocat@github.test'] }), root, token: app }),
+      ];
+      return byApp.every((r) => r.response.status === 403 && (r.response.body as { message?: string }).message === 'Resource not accessible by integration') && (await emails()).length === 1;
+    })),
+  todo('github.users.own_keys', 'users', 'Users: each account its own SSH and GPG keys (today one list, whoever asks)', 'api', 'niche'),
+  todo('github.users.own_blocks', 'users', 'Users: each account its own blocked users (today one list, whoever asks)', 'api', 'niche'),
   done('github.user.keys', 'users', 'User: SSH + GPG keys CRUD', 'api', 'niche', () =>
     withRoot(async (root) => {
       // SSH: missing key 422s; create → 201; get/list; delete → 404. GPG: armored key required.

package/src/github-events.ts

@@ -1,9 +1,10 @@
 // Native repository hooks and delivery history live in the World's existing state.
 // Callback HTTP is the caller's webhook sink, never a credentialed GitHub API call.
 import { createHash, createHmac } from 'node:crypto';
-import { applyTwinWrite, applyTwinWriteAtomic, ownFields, twinResources, worldNow } from '@volter/world-core';
+import { applyTwinWrite, applyTwinWriteAtomic, ownFields, twinResources, worldNow, deliveryTraceHeaders } from '@volter/world-core';
 import { GITHUB_WORLD_USER, githubApps, githubState, handleGithubRequest, toGithubWebhook } from './github-twin.ts';
 import type { GithubWebhook as Hook, GithubWriteEvent } from './github-twin.ts';
+import { appDestination, appFetch } from '@volter/world-core/app-route';
 import { worldEgressRefusal } from '@volter/world-core/network-policy';
 
 export type GithubWebhook = Record<string, unknown>;
@@ -23,10 +24,11 @@ export function signGithubPayload(secret: string, body: string): string {
 }
 
 const httpDelivery: GithubWebhookDelivery = async (url, _event, _payload, headers, body) => {
-  // the World's egress rule: a refused hook URL fails as a transport failure, recorded on the delivery
-  const refusal = worldEgressRefusal(url);
+  // the World's egress rule: a refused hook URL fails as a transport failure, recorded on the delivery; the
+  // application's own hostnames reach it inside the World. GitHub follows no redirect: the 3xx is the delivery's answer.
+  const refusal = appDestination(url) ? null : worldEgressRefusal(url);
   if (refusal !== null) throw new Error(refusal);
-  const response = await fetch(url, { method: 'POST', headers, body, redirect: 'manual', signal: AbortSignal.timeout(10_000) });
+  const response = await appFetch(url, { method: 'POST', headers: { ...headers, ...deliveryTraceHeaders() }, body, redirect: 'manual', signal: AbortSignal.timeout(10_000) });
   return { status: response.status, headers: Object.fromEntries(response.headers), body: await response.text() };
 };
 

package/src/github-git-http.ts

@@ -30,7 +30,7 @@
 //
 // Offline + deterministic: everything here is the kernel's git library over the World's
 // blob store (no network, no rate budget, no `git` binary).
-import { applyTwinWrite, git } from '@volter/world-core';
+import { applyTwinWrite, git, worldNow } from '@volter/world-core';
 const { serveSmartHttp, serveSmartHttpPost } = git;
 import { ensureBareRepo, hasBareRepo, listGitPlaneRefs, planeRepo, type PlaneRef } from './github-git-plane.ts';
 import { closePrsForDeletedBranch, githubState, kernelAtomic, syncPrHeadsToBranchTip, type GithubWriteEvent } from './github-twin.ts';
@@ -161,7 +161,7 @@ export async function reconcileGitPlaneRefs(
   opts: { root?: string; occurredAt?: string } = {},
 ): Promise<GithubWriteEvent[]> {
   const root = opts.root;
-  const occurredAt = opts.occurredAt ?? new Date().toISOString();
+  const occurredAt = opts.occurredAt ?? worldNow();
   const after = await listGitPlaneRefs(repo, root);
   const beforeBy = new Map(before.map((r) => [r.ref, r]));
   const afterBy = new Map(after.map((r) => [r.ref, r]));

package/src/github-mirror-ui.ts

@@ -8,12 +8,12 @@
 // real GitHub client speaks, so the mirror renders a twin or a real account unchanged,
 // pointed at any origin by configuration. The client is the shared world UI-mirror design.
 import { readFile } from 'node:fs/promises';
-import { bundleClient, fileResponse } from '@volter/world-core';
+import { bundleClient, fileResponse, filePathOf } from '@volter/world-core';
 import { serveHttp } from '@volter/world-core';
 import { createGithubTwinFetch } from './github-server.ts';
 
-const CLIENT_ENTRY = () => new URL('../client/github-mirror.tsx', import.meta.url).pathname;  // lazy: workerd rejects top-level relative URL from import.meta.url (bundled via pack index)
-const CLIENT_CSS = () => new URL('../client/github-mirror.css', import.meta.url).pathname;  // lazy: workerd rejects top-level relative URL from import.meta.url (bundled via pack index)
+const CLIENT_ENTRY = () => filePathOf(new URL('../client/github-mirror.tsx', import.meta.url));  // lazy: workerd rejects top-level relative URL from import.meta.url (bundled via pack index)
+const CLIENT_CSS = () => filePathOf(new URL('../client/github-mirror.css', import.meta.url));  // lazy: workerd rejects top-level relative URL from import.meta.url (bundled via pack index)
 
 const APP_SHELL = `<!doctype html>
 <html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">

package/src/github-server.ts

@@ -6,7 +6,7 @@
 // FIRST — its routes (/:owner/:repo/info/refs, git-upload-pack, git-receive-pack) are
 // binary pkt-line streams over the kernel's git library (github-git-http.ts); a push is
 // announced as an API commit's is (semantics/shared.ts announce).
-import { bindSemantics, compileSurface, coreFor, createDerivedFetch, crossCutting, matchOperation, semanticsContext, serveHttp, vendorError } from '@volter/world-core';
+import { bindSemantics, compileSurface, coreFor, createDerivedFetch, crossCutting, derivedRequestScopes, matchOperation, semanticsContext, serveHttp, vendorError } from '@volter/world-core';
 import surface from './generated/surface.gen.json' with { type: 'json' };
 import { manifest, spanning } from './manifest.ts';
 import { githubSemantics } from './semantics/index.ts';
@@ -14,7 +14,7 @@ import { githubGraphql } from './semantics/graphql.ts';
 import { createGraphqlWire } from './graphql-wire.ts';
 import { githubState, handleGithubDoor, revokedToken } from './github-twin.ts';
 import { announce } from './semantics/shared.ts';
-import { answerVendorErrors, RefusedWriteError } from '@volter/world-core';
+import { answerVendorErrors, isReadOnlyRequest, RefusedWriteError } from '@volter/world-core';
 import { worldNow, statefulTwinManifest} from '@volter/world-core';
 import { createHash } from 'node:crypto';
 import { githubOAuthFlow } from './screens/oauth.tsx';
@@ -106,7 +106,8 @@ export function createGithubTwinFetch(options: GithubTwinOptions): (request: Req
         query: url.searchParams,
         ...(request.method === 'POST' ? { body: new Uint8Array(await request.arrayBuffer()) } : {}),
         ...(options.root !== undefined ? { root: options.root } : {}),
-        readOnly,
+        // a read-only request pushes nothing: git refuses it as it refuses a push to a read-only twin
+        readOnly: readOnly || isReadOnlyRequest(request),
         contentEncoding: request.headers.get('content-encoding') ?? '',
         gitProtocol: request.headers.get('git-protocol') ?? '',
         occurredAt,
@@ -204,8 +205,9 @@ export function createGithubTwinFetch(options: GithubTwinOptions): (request: Req
   // dated by the host's clock contradicts the World's time) and an x-github-request-id in GitHub's colon-separated hex
   // form, derived from the instant, the request and a counter so the same request twice gets two ids.
   let answered = 0;
-  // which part serves each spec operation (the derived dispatch's owners), for the pack's report
-  return Object.assign(async (request: Request): Promise<Response> => {
+  // which part serves each spec operation (the derived dispatch's owners), for the pack's report; a read-only request
+  // (x-volter-read-only) writes nothing — a GraphQL mutation or a git push included — answered with GitHub's read-only error
+  return derivedRequestScopes(manifest, Object.assign(async (request: Request): Promise<Response> => {
     const token = (request.headers.get('authorization') ?? '').replace(/^(?:bearer|token)\s+/i, '').trim() || undefined;
     const res = revokedToken(token, options.root) ? vendorError(manifest, { status: 401, message: 'Bad credentials' }) : await vended(request);
     const at = now();
@@ -216,7 +218,7 @@ export function createGithubTwinFetch(options: GithubTwinOptions): (request: Req
       headers.set('x-github-request-id', `${h.slice(0, 4)}:${h.slice(4, 9)}:${h.slice(9, 15)}:${h.slice(15, 21)}:${h.slice(21, 29)}`);
     }
     return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
-  }, { owners: inner.owners });
+  }, { owners: inner.owners }));
 }
 
 /** The GraphQL wire's requests, as the handler interface names them. */