@volter/twin-github 2.0.0 → 2.0.2

package/src/github-twin.ts

@@ -814,8 +814,9 @@ export type GithubRuleSuite = { id: number; repository: string; ref: string; act
   rules: { ruleset_id: number; ruleset_name: string; rule_type: string; enforcement: string; result: 'pass' | 'fail'; details: string | null }[] };
 
 // ── User niche families: emails / SSH+GPG keys / blocking ──────────────────────────────────
-// An authenticated-user EMAIL (list/add/delete + primary/visibility). LOCAL, email-keyed.
-export type GithubUserEmail = { email: string; primary: boolean; verified: boolean; visibility: string | null };
+// An account's EMAIL (list/add/delete + primary/visibility). LOCAL, email-keyed: an address belongs to one account
+// (`login`; a row written before accounts held their own addresses is the World's user's, octocat's).
+export type GithubUserEmail = { email: string; primary: boolean; verified: boolean; visibility: string | null; login: string };
 // A user SSH public KEY (id-keyed, title + key text). LOCAL.
 export type GithubUserSshKey = { id: number; key: string; title: string; created_at?: string };
 // A user GPG KEY (id-keyed, key_id + armored public key). LOCAL.
@@ -914,7 +915,7 @@ function licenseOf(file: GithubContentFile | undefined): Record<string, unknown>
 const edgesOf = (m: Map<string, boolean>): GithubEdge[] => [...m.entries()].filter(([, on]) => on).map(([k]) => { const i = k.indexOf('|'); return { from: k.slice(0, i), to: k.slice(i + 1) }; });
 /** The World's user's side of the edges, as the set its own endpoints read. */
 const pairsOf = (m: Map<string, boolean>, login: string): Set<string> => new Set(edgesOf(m).filter((e) => e.from === login).map((e) => e.to));
-export type GithubState = { prs: GithubPr[]; issues: GithubIssue[]; reviews: GithubReview[]; comments: GithubComment[]; statuses: GithubStatus[]; checkRuns: GithubCheckRun[]; milestones: GithubMilestone[]; workflows: GithubWorkflow[]; workflowRuns: GithubWorkflowRun[]; jobs: GithubJob[]; releases: GithubRelease[]; releaseAssets: GithubReleaseAsset[]; tags: GithubTag[]; discussions: GithubDiscussion[]; discussionComments: GithubDiscussionComment[]; reactions: GithubReaction[]; labels: GithubLabel[]; repos: GithubRepo[]; branches: GithubBranch[]; collaborators: GithubCollaborator[]; webhooks: GithubWebhook[]; contents: GithubContentFile[]; gists: GithubGist[]; notifications: GithubNotification[]; gitRefs: GithubGitRef[]; gitCommits: GithubGitCommit[]; gitTrees: GithubGitTree[]; gitBlobs: GithubGitBlob[]; gitTagObjects: GithubGitTagObject[]; deployments: GithubDeployment[]; deploymentStatuses: GithubDeploymentStatus[]; environments: GithubEnvironment[]; actionsSecrets: GithubActionsSecret[]; actionsVariables: GithubActionsVariable[]; actionsCaches: GithubActionsCache[]; actionsArtifacts: GithubActionsArtifact[]; orgs: GithubOrg[]; orgMembers: GithubOrgMembership[]; outsideCollaborators: GithubOutsideCollaborator[]; orgWebhooks: GithubOrgWebhook[]; teams: GithubTeam[]; teamMembers: GithubTeamMembership[]; teamRepos: GithubTeamRepo[]; commitComments: GithubCommitComment[]; issueTypes: GithubIssueType[]; deployKeys: GithubDeployKey[]; autolinks: GithubAutolink[]; rulesets: GithubRuleset[]; ruleSuites: GithubRuleSuite[]; userEmails: GithubUserEmail[]; userSshKeys: GithubUserSshKey[]; userGpgKeys: GithubUserGpgKey[]; blockedUsers: Set<string>; userProfile: Partial<GithubUser>; projects: GithubProject[]; projectFields: GithubProjectField[]; projectItems: GithubProjectItem[]; projectViews: GithubProjectView[]; stars: Set<string>; watching: Set<string>; following: Set<string>; starEdges: GithubEdge[]; watchEdges: GithubEdge[]; followEdges: GithubEdge[]; codeScanningAlerts: GithubCodeScanningAlert[]; codeScanningAnalyses: GithubCodeScanningAnalysis[]; dependabotAlerts: GithubDependabotAlert[]; secretScanningAlerts: GithubSecretScanningAlert[]; appInstallations: GithubAppInstallation[]; oauthGrants: GithubOAuthGrant[]; packages: GithubPackage[]; packageVersions: GithubPackageVersion[]; pagesSites: GithubPagesSite[]; pagesBuilds: GithubPagesBuild[]; codespaces: GithubCodespace[] };
+export type GithubState = { prs: GithubPr[]; issues: GithubIssue[]; reviews: GithubReview[]; comments: GithubComment[]; statuses: GithubStatus[]; checkRuns: GithubCheckRun[]; milestones: GithubMilestone[]; workflows: GithubWorkflow[]; workflowRuns: GithubWorkflowRun[]; jobs: GithubJob[]; releases: GithubRelease[]; releaseAssets: GithubReleaseAsset[]; tags: GithubTag[]; discussions: GithubDiscussion[]; discussionComments: GithubDiscussionComment[]; reactions: GithubReaction[]; labels: GithubLabel[]; repos: GithubRepo[]; branches: GithubBranch[]; collaborators: GithubCollaborator[]; webhooks: GithubWebhook[]; contents: GithubContentFile[]; gists: GithubGist[]; notifications: GithubNotification[]; gitRefs: GithubGitRef[]; gitCommits: GithubGitCommit[]; gitTrees: GithubGitTree[]; gitBlobs: GithubGitBlob[]; gitTagObjects: GithubGitTagObject[]; deployments: GithubDeployment[]; deploymentStatuses: GithubDeploymentStatus[]; environments: GithubEnvironment[]; actionsSecrets: GithubActionsSecret[]; actionsVariables: GithubActionsVariable[]; actionsCaches: GithubActionsCache[]; actionsArtifacts: GithubActionsArtifact[]; orgs: GithubOrg[]; orgMembers: GithubOrgMembership[]; outsideCollaborators: GithubOutsideCollaborator[]; orgWebhooks: GithubOrgWebhook[]; teams: GithubTeam[]; teamMembers: GithubTeamMembership[]; teamRepos: GithubTeamRepo[]; commitComments: GithubCommitComment[]; issueTypes: GithubIssueType[]; deployKeys: GithubDeployKey[]; autolinks: GithubAutolink[]; rulesets: GithubRuleset[]; ruleSuites: GithubRuleSuite[]; userEmails: GithubUserEmail[]; userSshKeys: GithubUserSshKey[]; userGpgKeys: GithubUserGpgKey[]; blockedUsers: Set<string>; userProfile: Partial<GithubUser>; userProfiles: Record<string, Partial<GithubUser>>; projects: GithubProject[]; projectFields: GithubProjectField[]; projectItems: GithubProjectItem[]; projectViews: GithubProjectView[]; stars: Set<string>; watching: Set<string>; following: Set<string>; starEdges: GithubEdge[]; watchEdges: GithubEdge[]; followEdges: GithubEdge[]; codeScanningAlerts: GithubCodeScanningAlert[]; codeScanningAnalyses: GithubCodeScanningAnalysis[]; dependabotAlerts: GithubDependabotAlert[]; secretScanningAlerts: GithubSecretScanningAlert[]; appInstallations: GithubAppInstallation[]; oauthGrants: GithubOAuthGrant[]; packages: GithubPackage[]; packageVersions: GithubPackageVersion[]; pagesSites: GithubPagesSite[]; pagesBuilds: GithubPagesBuild[]; codespaces: GithubCodespace[] };
 
 // The default Discussion categories every repo starts with (mirrors GitHub's defaults).
 // Only Q&A is answerable. Ids are deterministic (hash of repo+slug) — never random.
@@ -962,6 +963,7 @@ export function githubState(root?: string): GithubState {
   const state = foldGithubState(root);
   for (const value of Object.values(state)) if (Array.isArray(value)) for (const row of value) Object.freeze(row);
   Object.freeze(state.userProfile);
+  for (const p of Object.values(state.userProfiles)) Object.freeze(p);
   memos.set(root ?? '', { stamp, state });
   return state;
 }
@@ -1096,7 +1098,8 @@ function foldGithubState(root?: string): GithubState {
   const userGpgKeysById = new Map<string, GithubUserGpgKey>();
   const deletedUserGpgKeys = new Set<string>();
   const blockedByLogin = new Map<string, boolean>();
-  const userProfile: Partial<GithubUser> = {};
+  // each account's profile as it edited it (PATCH /user), by lowercased login; octocat's is also `userProfile`
+  const userProfiles: Record<string, Partial<GithubUser>> = {};
   // Projects v2: projects / fields / items / views — LOCAL constructs keyed by subject id.
   const projectsById = new Map<string, GithubProject>();
   const deletedProjects = new Set<string>();
@@ -1778,12 +1781,15 @@ function foldGithubState(root?: string): GithubState {
         before_sha: String(f.before_sha ?? ''), after_sha: String(f.after_sha ?? ''), pushed_at: String(f.pushed_at ?? ''), result: (f.result ?? 'pass') as GithubRuleSuite['result'],
         rules: Array.isArray(f.rules) ? f.rules as GithubRuleSuite['rules'] : [] });
     } else if (a.subject.type === 'user_email') {
-      if (f.deleted === true) { deletedUserEmails.add(a.subject.id); continue; }
+      // a removed address is gone; added again (by its account or another) it starts afresh
+      if (f.deleted === true) { deletedUserEmails.add(a.subject.id); userEmailsByAddr.delete(a.subject.id); continue; }
+      deletedUserEmails.delete(a.subject.id);
       const prev = userEmailsByAddr.get(a.subject.id);
       userEmailsByAddr.set(a.subject.id, {
         email: String(f.email ?? prev?.email ?? ''), primary: f.primary !== undefined ? Boolean(f.primary) : (prev?.primary ?? false),
         verified: f.verified !== undefined ? Boolean(f.verified) : (prev?.verified ?? true),
         visibility: f.visibility !== undefined ? (f.visibility as string | null) : (prev?.visibility ?? null),
+        login: typeof f.login === 'string' ? f.login : (prev?.login ?? GITHUB_WORLD_USER),
       });
     } else if (a.subject.type === 'user_ssh_key') {
       if (f.deleted === true) { deletedUserSshKeys.add(a.subject.id); continue; }
@@ -1805,9 +1811,12 @@ function foldGithubState(root?: string): GithubState {
       // PUT sets, DELETE clears — boolean per login (last write per subject id wins).
       blockedByLogin.set(String(f.login ?? a.subject.id.replace(/^block:/, '')), f.deleted !== true);
     } else if (a.subject.type === 'user_profile') {
-      // PATCH /user — overlay the authenticated user's editable profile fields.
+      // PATCH /user — overlay the authenticated user's editable profile fields, on that user's own profile (a row
+      // without a login is from before profiles were per account: the World's user's).
+      const owner = (typeof f.login === 'string' ? f.login : a.subject.id === 'user_profile:octocat' ? GITHUB_WORLD_USER : a.subject.id.replace(/^user_profile:/, '')).toLowerCase();
+      const profile = userProfiles[owner] ?? (userProfiles[owner] = {});
       for (const k of ['name', 'bio', 'company', 'blog', 'location', 'email'] as const) {
-        if (f[k] !== undefined) (userProfile as Record<string, unknown>)[k] = f[k];
+        if (f[k] !== undefined) (profile as Record<string, unknown>)[k] = f[k];
       }
     } else if (a.subject.type === 'project_field' || a.subject.type === 'project_item' || a.subject.type === 'project_view') {
       // a project's fields, items and views: the fields as written, the id the subject's
@@ -2244,7 +2253,8 @@ function foldGithubState(root?: string): GithubState {
     userSshKeys,
     userGpgKeys,
     blockedUsers: new Set([...blockedByLogin.entries()].filter(([, on]) => on).map(([k]) => k)),
-    userProfile,
+    userProfile: userProfiles[GITHUB_WORLD_USER] ?? {},
+    userProfiles,
     projects,
     projectFields,
     projectItems,
@@ -3700,6 +3710,16 @@ export function toGithubRuleset(r: GithubRuleset): Record<string, unknown> {
 }
 
 // ── User niche serializers: emails / SSH keys / GPG keys ─────────────────────────────────
+/** An account as GET /user and GET /users/:login answer it: the login's deterministic account, under the profile its
+ *  person edited (PATCH /user). Nothing is invented for a person who has not filled it in: GitHub's `name` is null until
+ *  they set it. */
+export function accountOf(state: GithubState, login: string): GithubUser {
+  return { ...seedUser(login), ...(state.userProfiles[login.toLowerCase()] ?? {}), login };
+}
+/** The addresses an account holds, primary first (GET /user/emails). */
+export function emailsOf(state: GithubState, login: string): GithubUserEmail[] {
+  return state.userEmails.filter((e) => e.login.toLowerCase() === login.toLowerCase());
+}
 export function toGithubUserEmail(e: GithubUserEmail): Record<string, unknown> {
   return { email: e.email, primary: e.primary, verified: e.verified, visibility: e.visibility };
 }
@@ -4174,6 +4194,61 @@ export async function registerGithubApp(body: Record<string, any>, occurredAt: s
   return { response: { status: 201, body: toGithubApp(fields, 0, githubState(req.root)) }, app: fields };
 }
 
+/** Every account login the World already knows, lowercased → as it was first written: the World's user, whoever holds a
+ *  token or a password or an address or a profile, owns, collaborates on or is invited to a repository, is an organization
+ *  or one of its members. A tombstoned row still names an account that existed. Sign-up refuses these; a request naming one in another
+ *  case answers the account as it is spelled. */
+export function accountLoginsOf(resources: readonly Record<string, unknown>[]): Map<string, string> {
+  const out = new Map<string, string>([[GITHUB_WORLD_USER, GITHUB_WORLD_USER]]);
+  const add = (v: unknown) => { if (typeof v === 'string' && v && !out.has(v.toLowerCase())) out.set(v.toLowerCase(), v); };
+  for (const r of resources) {
+    switch (r.type) {
+      case 'user_credential': case 'user_email': case 'user_profile': case 'user_two_factor': case 'oauth_grant':
+      case 'collaborator': case 'outside_collaborator': case 'org_membership': case 'team_membership': case 'organization':
+        add(r.login); break;
+      case 'repository': add(r.owner); break;
+      // GitHub invites only an account that exists
+      case 'repo_invitation': add(r.invitee); break;
+    }
+  }
+  return out;
+}
+/** A login as the account it names is spelled (GitHub's logins are case-insensitive); a login no account holds as asked. */
+export function canonicalLogin(login: string, root?: string): string {
+  const store = getActiveWorldStore();
+  const memos = accountMemos.get(store) ?? accountMemos.set(store, new Map()).get(store)!;
+  const stamp = treeStamp(SERVICE, root);
+  let held = memos.get(root ?? '');
+  if (!held || held.stamp !== stamp) { held = { stamp, logins: accountLoginsOf(twinResources(SERVICE, root)) }; memos.set(root ?? '', held); }
+  return held.logins.get(login.toLowerCase()) ?? login;
+}
+const accountMemos = new WeakMap<object, Map<string, { stamp: string; logins: Map<string, string> }>>();
+
+/** A person signs up (POST /_twin/users, standing in for github.com/signup): the account's password and its primary
+ *  address, decided against the tree in one step so two sign-ups cannot take the same username or address. */
+async function signUp(body: Record<string, any>, occurredAt: string, root: string | undefined): Promise<{ response: GithubResponse }> {
+  const login = typeof body.login === 'string' ? body.login : '';
+  const email = typeof body.email === 'string' ? body.email.trim() : '';
+  const password = typeof body.password === 'string' ? body.password : '';
+  const invalid = (resource: string, field: string, code: string, message?: string) => ({ response: { status: 422, body: { message: 'Validation Failed', errors: [{ resource, field, code, ...(message ? { message } : {}) }] } } });
+  if (!/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/.test(login) || /--|-$/.test(login)) return invalid('User', 'login', 'invalid');
+  if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email)) return invalid('User', 'email', 'invalid');
+  if (!(password.length >= 15 || (password.length >= 8 && /[0-9]/.test(password) && /[a-z]/.test(password)))) return invalid('User', 'password', 'invalid', 'Password is too short or needs a number and a lowercase letter');
+  const lower = login.toLowerCase();
+  // The account is made by its address: the one write that claims both the username (the row names it, so every later
+  // sign-up sees it taken) and the address, decided against the tree it lands on, so of two sign-ups racing for either
+  // only one is made. Its password follows.
+  const { value: taken } = await applyTwinWriteAtomic<'login' | 'email' | undefined>(SERVICE, (resources) => {
+    if (accountLoginsOf(resources).has(lower)) return { kind: 'skip', value: 'login' };
+    if (resources.some((r) => r.deleted !== true && r.type === 'user_email' && String(r.email).toLowerCase() === email.toLowerCase())) return { kind: 'skip', value: 'email' };
+    return { kind: 'write', value: undefined, write: { operation: 'user_email.upsert', subjectType: 'user_email', subjectId: `useremail:${email}`, fields: { email, primary: true, verified: true, visibility: 'private', login }, occurredAt, actor: { kind: 'human', id: login } } };
+  }, root);
+  if (taken === 'login') return invalid('User', 'login', 'already_exists', 'Username is not available');
+  if (taken === 'email') return invalid('User', 'email', 'already_exists', 'Email is invalid or already taken');
+  await applyTwinWrite(SERVICE, { operation: 'user_credential.set', subjectType: 'user_credential', subjectId: `credential:${lower}`, fields: { login, hash: passwordHash(login, password), set_at: occurredAt }, occurredAt, actor: { kind: 'human', id: login } }, root);
+  return { response: { status: 201, body: { login, email } } };
+}
+
 /** The twin's own doors under /_twin/: what stands in for an act GitHub does in its web UI or its runners, which have
  *  no API. A request to any other path is not a door's (undefined). */
 export async function handleGithubDoor(request: Request, scope: { root?: string; now: () => string }): Promise<Response | undefined> {
@@ -4202,10 +4277,19 @@ export async function handleGithubDoor(request: Request, scope: { root?: string;
     //   {slug, name, owner, permissions, events, setup_url?, callback_url?, request_oauth_on_install?, hook_attributes?: {url},
     //   webhook_secret?}. It is installed through its page, github.com/apps/{slug}/installations/new (src/screens/app-installation.tsx).
     if (seg[1] === 'apps' && !seg[2]) return registerGithubApp(body, occurredAt, req.root);
+    // POST /_twin/users → {login, email, password}: GitHub's sign-up (github.com/signup; GitHub has no API to create an
+    //   account). As the page does, it takes a username, an email address and a password, and refuses a username or an
+    //   address another account holds and a password GitHub's rule refuses ("at least 15 characters OR at least 8
+    //   characters including a number and a lowercase letter", docs.github.com/authentication/keeping-your-account-and-
+    //   data-secure/creating-a-strong-password). The account's address is its primary one, verified (GitHub creates the
+    //   account only once the launch code it mails there is entered; that step is not modelled) and private, so
+    //   GET /user/emails lists it and GET /user's public `email` stays null. The person signs in at github.com/login;
+    //   their name and the rest of their profile are theirs to set (PATCH /user), empty until they do.
+    if (seg[1] === 'users' && !seg[2]) return signUp(body, occurredAt, req.root);
     // POST /_twin/users/:login/tokens → a personal access token for that user (GitHub mints these in its settings UI,
     //   which has no API). Requests carrying it are that user's: writes are attributed to them and GET /user names them.
     if (seg[1] === 'users' && seg[2] && seg[3] === 'tokens' && !seg[4]) {
-      const login = decodeURIComponent(seg[2]);
+      const login = canonicalLogin(decodeURIComponent(seg[2]), req.root);
       if (!/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/.test(login)) return { response: { status: 422, body: { message: 'Validation Failed', errors: [{ resource: 'User', field: 'login', code: 'invalid' }] } } };
       const token = `ghp_${createHash('sha256').update(`pat:${login}:${nextSeq('pat', req.root)}`).digest('hex').slice(0, 36)}`;
       const scopes = Array.isArray(body.scopes) ? body.scopes.map(String) : ['repo', 'read:org'];
@@ -4213,10 +4297,10 @@ export async function handleGithubDoor(request: Request, scope: { root?: string;
       return { response: { status: 201, body: { token, login, scopes } } };
     }
     // POST /_twin/users/:login/password → {password}: the password the World gives a person, with which they sign in at
-    //   github.com/login (src/screens/session.tsx). GitHub's sign-up and password pages are not modelled; the World keeps
-    //   the password's hash, never the password.
+    //   github.com/login (src/screens/session.tsx). It stands in for GitHub's password page (sign-up is POST /_twin/users
+    //   above); the World keeps the password's hash, never the password.
     if (seg[1] === 'users' && seg[2] && seg[3] === 'password' && !seg[4]) {
-      const login = decodeURIComponent(seg[2]);
+      const login = canonicalLogin(decodeURIComponent(seg[2]), req.root);
       const password = typeof body.password === 'string' ? body.password : '';
       if (!/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/.test(login) || password.length < 8) return { response: { status: 422, body: { message: 'Validation Failed', errors: [{ resource: 'User', field: password.length < 8 ? 'password' : 'login', code: 'invalid' }] } } };
       await applyTwinWrite(SERVICE, { operation: 'user_credential.set', subjectType: 'user_credential', subjectId: `credential:${login.toLowerCase()}`, fields: { login, hash: passwordHash(login, password), set_at: occurredAt }, occurredAt, actor: { kind: 'agent' } }, req.root);

package/src/index.ts

@@ -118,6 +118,9 @@ export const pack: TwinPack = {
     { host: 'uploads.github.com', pathPattern: '^/repos/[^/]+/[^/]+/releases/\\d+/assets$' },
     { host: 'github.com', pathPattern: '^/[^/]+/[^/]+/(info/refs|git-upload-pack|git-receive-pack)$' },
     { host: 'github.com', pathPattern: '^/login/oauth/(authorize|access_token)$' },
+    // the sign-in the consent and the other pages send a visitor who is not signed in to, and its two-factor step
+    // (src/screens/session.tsx); without these a browser following the redirect leaves the World
+    { host: 'github.com', pathPattern: '^/(login|session|sessions/two-factor(/app)?)$' },
     { host: 'github.com', pathPattern: '^/apps/[^/]+/installations/new$' },
     { host: 'github.com', pathPattern: '^/(organizations/[^/]+/)?settings/apps/new$' },
     { host: 'npm.pkg.github.com', pathPattern: '^/@' },

package/src/screens/session.tsx

@@ -13,8 +13,9 @@
 // (docs.github.com/authentication/securing-your-account-with-two-factor-authentication-2fa/about-mandatory-two-factor-
 // authentication) is the person's to turn on in the World; the twin does not enrol anyone.
 //
-// Where GitHub's documentation stops and the twin decides: a person's password is what the World gave them
-// (`POST /_twin/users/:login/password`; GitHub's sign-up and password pages are not modelled), an account is named by
+// Where GitHub's documentation stops and the twin decides: a person's password is the one they signed up with
+// (`POST /_twin/users`, standing in for github.com/signup) or the World gave them (`POST /_twin/users/:login/password`;
+// GitHub's password page is not modelled), an account is named by
 // its login (not its email), a refused sign-in shows the form again with GitHub's message (answered 200), a code is
 // taken for the current 30-second step or the one before (RFC 6238's one step of drift) and never twice, a pending
 // two-factor sign-in does not expire, and a session does not end: no person of a World signs out yet, and signing out is built when one does.
@@ -53,8 +54,15 @@ export function toSignIn(request: Request, suggested?: string, page?: string): R
   return new Response(null, { status: 302, headers: { location: `/login?return_to=${encodeURIComponent(page ?? url.pathname + url.search)}${suggested ? `&login=${encodeURIComponent(suggested)}` : ''}` } });
 }
 
-/** A return_to GitHub follows: a path on github.com, never another site. */
-const returnTo = (raw: string | undefined): string => (raw && raw.startsWith('/') && !raw.startsWith('//') ? raw : '/');
+/** A return_to GitHub follows: a path on github.com, never another site. Resolved as a browser resolves it (a backslash
+ *  or a control character can turn `/\evil.test` into another origin), and kept only when it stays on github.com. */
+function returnTo(raw: string | undefined): string {
+  if (!raw || !raw.startsWith('/') || /[\u0000-\u001f\\]/.test(raw)) return '/';
+  try {
+    const url = new URL(raw, 'https://github.com');
+    return url.origin === 'https://github.com' ? url.pathname + url.search : '/';
+  } catch { return '/'; }
+}
 
 function page(fields: { return_to: string; login?: string }, error?: string): Response {
   return flowPage({

package/src/semantics/graphql.ts

@@ -284,7 +284,12 @@ export function githubGraphql(): { resolvers: Record<string, FieldResolver>; sto
   };
   return {
     resolvers: {
-      'Query.viewer': (_s, _args, c) => ({ __typename: 'User', login: 'octocat', name: state(c).userProfile.name ?? 'The Octocat' }),
+      // the token's own account; the World's shared token is octocat's, named The Octocat until its profile says otherwise
+      'Query.viewer': (_s, _args, c) => {
+        const login = gh(ctxOf(c)).caller ?? GITHUB_WORLD_USER;
+        const name = state(c).userProfiles[login.toLowerCase()]?.name;
+        return { __typename: 'User', login, name: name ?? (login === GITHUB_WORLD_USER ? 'The Octocat' : null) };
+      },
       'Query.node': queryNode,
       'Query.repository': (_s, args, c) => {
         const repo = `${String(args.owner)}/${String(args.name)}`;
@@ -419,7 +424,7 @@ export function githubGraphql(): { resolvers: Record<string, FieldResolver>; sto
         const login = String(args.login ?? '');
         const st = state(c);
         const known = login === GITHUB_WORLD_USER || st.oauthGrants.some((g) => g.login === login) || st.orgMembers.some((m) => m.login === login) || st.collaborators.some((x) => x.login === login) || st.repos.some((r) => r.owner === login);
-        return known ? { __typename: 'User', login, name: null, id: `U_${login}` } : fail(`Could not resolve to a User with the login of '${login}'.`, 'NOT_FOUND');
+        return known ? { __typename: 'User', login, name: st.userProfiles[login.toLowerCase()]?.name ?? null, id: `U_${login}` } : fail(`Could not resolve to a User with the login of '${login}'.`, 'NOT_FOUND');
       },
       'Query.organization': (_s, args, c) => {
         const org = state(c).orgs.find((o) => o.login === String(args.login ?? ''));

package/src/semantics/shared.ts

@@ -176,6 +176,6 @@ export const writer = (ctx: SemanticsContext): GithubWrite => (w) => put(ctx, w)
  *  the noreply address GitHub gives an account that keeps its email private. */
 export function identityOf(g: Gh): { name: string; email: string } {
   const login = g.caller ?? 'octocat';
-  const profile = login === 'octocat' ? g.state().userProfile : undefined;
+  const profile = g.state().userProfiles[login.toLowerCase()];
   return { name: String(profile?.name ?? login), email: `${twinUserId(login)}+${login}@users.noreply.github.com` };
 }

package/src/semantics/users.ts

@@ -1,13 +1,21 @@
 // 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.ts';
 import { createHash } from 'node:crypto';
 import type { Semantics } from '@volter/world-core';
 import {
-  githubActivityEvents, githubNotFound, paginate, seedUser, toGithubOrg, toGithubRepo, toGithubUser, toGithubUserEmail, toGithubUserGpgKey, toGithubUserSshKey, toSimpleUser, twinUserId,
+  accountOf, canonicalLogin, emailsOf, githubActivityEvents, githubNotFound, paginate, seedUser, toGithubOrg, toGithubRepo, toGithubUser, toGithubUserEmail, toGithubUserGpgKey, toGithubUserSshKey, toSimpleUser, twinUserId,
 } from '../github-twin.ts';
-import { asView, gh, nextSeq, put, send } from './shared.ts';
+import { asView, atomic, gh, nextSeq, put, send } from './shared.ts';
+
+/** 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: Parameters<Semantics>[0]): Response | undefined =>
+  (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
@@ -26,8 +34,9 @@ const userEvents = (received: boolean, only: 'public' | undefined): Semantics =>
 export function usersSemantics(): Record<string, Semantics> {
   const usersGetByUsername: Semantics = 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: Semantics = async (ctx) => {
     const { caller, query, state } = gh(ctx);
@@ -94,11 +103,11 @@ export function usersSemantics(): Record<string, Semantics> {
   };
   const usersListEmailsForAuthenticatedUser: Semantics = 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: Semantics = 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: Semantics = async (ctx) => {
     const { query, state } = gh(ctx);
@@ -127,16 +136,25 @@ export function usersSemantics(): Record<string, Semantics> {
     return send(ctx, state().blockedUsers.has(decodeURIComponent(seg[2]!)) ? { status: 204, body: undefined } : githubNotFound());
   };
   const usersGetAuthenticated: Semantics = 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: Semantics = async (ctx) => {
+    const refused = asApp(ctx);
+    if (refused) return refused;
     const { body, state } = gh(ctx);
     const fields: Record<string, unknown> = {};
     for (const k of ['name', 'bio', 'company', 'blog', 'location', 'email'] as const) 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: Semantics = async (ctx) => {
     const { body, occurredAt, state } = gh(ctx);
@@ -201,11 +219,12 @@ export function usersSemantics(): Record<string, Semantics> {
     '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,
@@ -219,24 +238,45 @@ export function usersSemantics(): Record<string, Semantics> {
   };
 }
 
-/** 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: Parameters<Semantics>[0], remove: boolean): Promise<Response> {
   const { body, state } = gh(ctx);
+  const login = me(ctx);
   const list: string[] = Array.isArray(body.emails) ? body.emails.map(String) : Array.isArray(body) ? (body as string[]).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: { login: string }) => e.login.toLowerCase() === login.toLowerCase();
+  const held = (email: string) => 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 } });
-    } 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' } });
+      if (h && mine(h)) await put(ctx, { operation: 'user_email.delete', subjectType: 'user_email', subjectId, fields: { deleted: true, email: h.email } });
+    } 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: Parameters<Semantics>[0], blocking: boolean): Promise<Response> {