@volter/twin-xidentity 0.1.2 → 0.1.4

package/README.md

@@ -68,7 +68,10 @@ code TTL). Each such `done` names its evidence boundary in the manifest and its
 - **The identity read** — `GET /2/users/me` with the OpenAPI's scope demands (`tweet.read` +
   `users.read`), the 24-value `user.fields` enum with the wire's invalid-parameter envelope, the
   documented `x-rate-limit-*` headers, 75/15min per-user accounting, and the documented
-  429 + legacy code 88 refusal.
+  429 + legacy code 88 refusal. `user.fields=profile_image_url` is the seeded photo, or X's default
+  avatar URL (`abs.twimg.com/…/default_profile_normal.png`) for a persona seeded without one — the
+  same answer the `x` pack gives for the same person; a pulled persona whose reply withheld the field
+  is not given one.
 - **SDK fidelity** — the unmodified current official SDK (`@xdevplatform/xdk`) drives
   `users.getMe()` against the twin through its own public `baseUrl` config
   (`xidentity-sdk.integration.test.ts`); the OAuth legs its hardcoded hosts cannot re-aim are

package/dist/src/xidentity-capabilities.js

@@ -52,7 +52,7 @@ import { XIdentityBudgetError, XIDENTITY_BUDGET_BURST_CEILING } from "./xidentit
 import { liveXIdentityExecute, mapUsersMeAccount, pullXIdentity, pushPendingXIdentityActions, syncXIdentityFromReal, } from "./xidentity-connector.js";
 import { pkceS256 } from "./xidentity-pkce.js";
 import { DEFAULT_ACCOUNTS, DEFAULT_CLIENT_ID, DEFAULT_CLIENT_SECRET, DEFAULT_PUBLIC_CLIENT_ID, defaultRedirectUris } from "./xidentity-store.js";
-import { handleXIdentityTwinRequest } from "./xidentity-twin.js";
+import { handleXIdentityTwinRequest, X_DEFAULT_PROFILE_IMAGE_URL } from "./xidentity-twin.js";
 const AT = '2026-02-01T00:00:00.000Z';
 const atPlus = (seconds) => new Date(Date.parse(AT) + seconds * 1000).toISOString();
 /** The origin this harness's world serves the twin at. The seeded demo clients' callbacks are
@@ -502,17 +502,41 @@ export const XIDENTITY_CAPABILITIES = [
             && d['created_at'] === ADA.createdAt
             && d['description'] === ADA.description
             && d['location'] === ADA.location
-            && d['profile_image_url'] === ADA.profileImageUrl
+            && d['profile_image_url'] === X_DEFAULT_PROFILE_IMAGE_URL // Ada is seeded without a photo
             && d['protected'] === false
             && d['url'] === ADA.url
             && d['verified'] === true
             && d['verified_type'] === 'blue';
     })),
-    // The x pack answers user.fields=profile_image_url with X's default avatar for an account seeded
-    // without a photo (every X account has one); this pack omits it, because a PARTIALLY-pulled persona
-    // cannot tell "no photo" from "not pulled" (renderUser). Serving the default for a seeded persona
-    // needs that distinction recorded on the row — until then the two packs answer differently (§9).
-    todo('xidentity.users_me.default_profile_image', 'users_me', "user.fields=profile_image_url for a persona seeded without a photo: X's default avatar URL (abs.twimg.com default_profile_normal.png), as the x pack serves it, rather than omission", 'api', 'common'),
+    // Every X account has a profile image: X's default avatar until the person sets a photo (the x pack's
+    // `X_DEFAULT_PROFILE_IMAGE_URL`; X's own payload example serves it for a photo-less user). Postiz's X
+    // connect reads it from v2.me and recorded an empty picture for @acmeshoes while the x pack, asked
+    // for the same person, answered the default. A PULLED persona the reply told nothing about stays
+    // without one (the pull asked; a withheld field is not "no photo"). That both packs answer one person
+    // alike is xidentity-x-avatar.integration.test.ts: both packs on one root, which a shipped verify
+    // does not reach (A3).
+    done('xidentity.users_me.default_profile_image', 'users_me', "user.fields=profile_image_url for a persona seeded without a photo is X's default avatar URL (abs.twimg.com default_profile_normal.png), the same answer the x pack gives for the same person; a seeded photo is served as set, the field stays out unless asked for, and a pulled persona whose reply withheld it is not given one (the x pack's answer for the same person: xidentity-x-avatar.integration.test.ts)", 'api', 'common', () => withRoot(async (h) => {
+        const PLAIN = { id: '1790000000000000001', username: 'acmeshoes', name: 'Acme Shoes' };
+        const PHOTO = { id: '1790000000000000002', username: 'pictured', name: 'Pictured', profile_image_url: 'https://pbs.twimg.com/profile_images/1/pictured_normal.jpg' };
+        await h({ m: 'GET', p: '/i/oauth2/authorize' }); // seed the world (clients, session)
+        for (const person of [PLAIN, PHOTO])
+            await h({ m: 'POST', p: '/_twin/accounts', b: JSON.stringify(person) });
+        await pullXIdentity(async () => ({ data: { id: '4444', username: 'withheld' } }), h.root, '2026-02-01T00:00:01.000Z');
+        const meOf = async (accountId, query) => {
+            await h({ m: 'POST', p: '/_twin/session', b: JSON.stringify({ account_id: accountId }) });
+            const { tokens } = await fullFlow(h);
+            const r = await h({ m: 'GET', p: `/2/users/me${query}`, h: { authorization: `Bearer ${tokens['access_token']}` } });
+            return r.status === 200 ? body(r).data : undefined;
+        };
+        const plain = await meOf(PLAIN.id, '?user.fields=profile_image_url');
+        const plainBare = await meOf(PLAIN.id, '');
+        const photo = await meOf(PHOTO.id, '?user.fields=profile_image_url,name');
+        const withheld = await meOf('4444', '?user.fields=profile_image_url');
+        return plain?.['profile_image_url'] === X_DEFAULT_PROFILE_IMAGE_URL
+            && plainBare !== undefined && !('profile_image_url' in plainBare)
+            && photo?.['profile_image_url'] === PHOTO.profile_image_url
+            && withheld?.['id'] === '4444' && !('profile_image_url' in withheld);
+    })),
     done('xidentity.users_me.public_metrics', 'users_me', 'user.fields=public_metrics returns the metrics object with the vendor\'s six counters', 'api', 'common', () => withRoot(async (h) => {
         const { tokens } = await fullFlow(h);
         const r = await h({ m: 'GET', p: '/2/users/me?user.fields=public_metrics', h: { authorization: `Bearer ${tokens['access_token']}` } });

package/dist/src/xidentity-twin.d.ts

@@ -41,6 +41,15 @@ export type XIdentityResponse = XResponse;
 export declare const USER_FIELDS: readonly ["confirmed_email", "connection_status", "created_at", "description", "entities", "id", "is_identity_verified", "location", "name", "parody", "profile_banner_url", "profile_image_url", "protected", "public_metrics", "receives_your_dm", "subscribes_to_you", "subscription", "subscription_type", "url", "username", "verified", "verified_followers_count", "verified_type", "withheld"];
 /** The `expansions` enum — UserExpansionsParameter (2.167), verbatim. */
 export declare const USER_EXPANSIONS: readonly ["affiliation", "most_recent_post_id", "pinned_post_id"];
+/** The picture X shows for an account that never uploaded one. Every X account has a profile image;
+ *  until the person sets a photo it is this URL — the `profile_image_url_https` X serves for such a
+ *  user (docs.x.com/x-api/account-activity/introduction, its payload example's "Harrison Test",
+ *  fetched 2026-09-28), and the URL answers X's grey silhouette (observed 2026-09-28:
+ *  `curl -sS -o /dev/null -w '%{http_code} %{content_type}'` over it gives `200 image/png`, 48×48).
+ *  TRANSCRIBED from the x pack's `X_DEFAULT_PROFILE_IMAGE_URL` (packages/twin/x/src/x-twin.ts), not
+ *  imported (A3); xidentity-x-avatar.integration.test.ts asks both packs for the same person
+ *  on one root and fails if they part. */
+export declare const X_DEFAULT_PROFILE_IMAGE_URL = "https://abs.twimg.com/sticky/default_profile_images/default_profile_normal.png";
 /** The scopes GET /2/users/me demands — the OpenAPI operation's OAuth2UserToken entry lists BOTH. */
 export declare const USERS_ME_REQUIRED_SCOPES: readonly ["tweet.read", "users.read"];
 /** Every VENDOR endpoint this twin claims to serve. The conformance check drives one real request

package/dist/src/xidentity-twin.js

@@ -558,12 +558,31 @@ export const USER_FIELDS = [
 ];
 /** The `expansions` enum — UserExpansionsParameter (2.167), verbatim. */
 export const USER_EXPANSIONS = ['affiliation', 'most_recent_post_id', 'pinned_post_id'];
+/** The picture X shows for an account that never uploaded one. Every X account has a profile image;
+ *  until the person sets a photo it is this URL — the `profile_image_url_https` X serves for such a
+ *  user (docs.x.com/x-api/account-activity/introduction, its payload example's "Harrison Test",
+ *  fetched 2026-09-28), and the URL answers X's grey silhouette (observed 2026-09-28:
+ *  `curl -sS -o /dev/null -w '%{http_code} %{content_type}'` over it gives `200 image/png`, 48×48).
+ *  TRANSCRIBED from the x pack's `X_DEFAULT_PROFILE_IMAGE_URL` (packages/twin/x/src/x-twin.ts), not
+ *  imported (A3); xidentity-x-avatar.integration.test.ts asks both packs for the same person
+ *  on one root and fails if they part. */
+export const X_DEFAULT_PROFILE_IMAGE_URL = 'https://abs.twimg.com/sticky/default_profile_images/default_profile_normal.png';
+/** A persona's `profile_image_url`: the photo on the row, else X's default for a persona the twin
+ *  seeded (a seeded persona without a photo has none, and X answers the default for that); a PULLED
+ *  persona without one is undefined, because the pull asked for the field and a reply that withheld
+ *  it (partial errors) says nothing about the real account's picture. */
+function profileImageOf(account) {
+    if (typeof account.profileImageUrl === 'string' && account.profileImageUrl !== '')
+        return account.profileImageUrl;
+    return account.pulled === true ? undefined : X_DEFAULT_PROFILE_IMAGE_URL;
+}
 /** The scopes GET /2/users/me demands — the OpenAPI operation's OAuth2UserToken entry lists BOTH. */
 export const USERS_ME_REQUIRED_SCOPES = ['tweet.read', 'users.read'];
 /** Map an account row to the vendor's User object for a requested field set. Default fields are
  *  id, name, username (the OpenAPI/docs default); everything else appears only when asked for and
  *  only when the twin models it — a modelled-but-absent optional field is OMITTED, matching the
- *  spec (no User property is `required`). Unmodelled enum values (`connection_status`,
+ *  spec (no User property is `required`) — except `profile_image_url`, which every X account has
+ *  (X's default avatar until a photo is set; `profileImageOf`). Unmodelled enum values (`connection_status`,
  *  `receives_your_dm`, …) are accepted and omitted; each is a named manifest todo, not silent.
  *  `confirmed_email` additionally demands the `users.email` scope (X's April-2025 announcement —
  *  see xidentity-scopes.ts); OMISSION when the scope is missing is EXTRAPOLATION, pinned by
@@ -584,8 +603,11 @@ function renderUser(account, fields, heldScopes) {
         out['description'] = account.description;
     if (want.has('location') && typeof account.location === 'string')
         out['location'] = account.location;
-    if (want.has('profile_image_url') && typeof account.profileImageUrl === 'string')
-        out['profile_image_url'] = account.profileImageUrl;
+    if (want.has('profile_image_url')) {
+        const picture = profileImageOf(account);
+        if (picture !== undefined)
+            out['profile_image_url'] = picture;
+    }
     if (want.has('protected'))
         out['protected'] = account.protectedAccount === true;
     if (want.has('public_metrics') && account.publicMetrics && typeof account.publicMetrics === 'object')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/twin-xidentity",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Local X (Twitter) identity twin — the real x.com authorize screen, the full OAuth 2.0 authorization-code + PKCE round trip (token, refresh, revoke), and GET /2/users/me with X's real field/expansion/problem envelopes, so an unmodified X client completes sign-in-with-X against it. Built on @volter/world-core.",
   "keywords": [
     "twin",
@@ -56,10 +56,10 @@
     "react-dom": "^19.2.7"
   },
   "peerDependencies": {
-    "@volter/world-core": "2.0.2"
+    "@volter/world-core": "2.0.4"
   },
   "devDependencies": {
-    "@volter/world-core": "2.0.2",
+    "@volter/world-core": "2.0.4",
     "@volter/world-tooling": "0.1.0",
     "@xdevplatform/xdk": "^0.6.6",
     "@types/bun": "^1.2.20",

package/src/xidentity-capabilities.ts

@@ -59,7 +59,7 @@ import {
 } from './xidentity-connector.ts';
 import { pkceS256 } from './xidentity-pkce.ts';
 import { DEFAULT_ACCOUNTS, DEFAULT_CLIENT_ID, DEFAULT_CLIENT_SECRET, DEFAULT_PUBLIC_CLIENT_ID, defaultRedirectUris } from './xidentity-store.ts';
-import { handleXIdentityTwinRequest, USER_FIELDS, type XResponse } from './xidentity-twin.ts';
+import { handleXIdentityTwinRequest, USER_FIELDS, X_DEFAULT_PROFILE_IMAGE_URL, type XResponse } from './xidentity-twin.ts';
 
 type Step = { m: string; p: string; b?: string; h?: Record<string, string>; at?: string };
 type Body = Record<string, any>;
@@ -584,17 +584,41 @@ export const XIDENTITY_CAPABILITIES: CapabilitySpec[] = [
         && d['created_at'] === ADA.createdAt
         && d['description'] === ADA.description
         && d['location'] === ADA.location
-        && d['profile_image_url'] === ADA.profileImageUrl
+        && d['profile_image_url'] === X_DEFAULT_PROFILE_IMAGE_URL // Ada is seeded without a photo
         && d['protected'] === false
         && d['url'] === ADA.url
         && d['verified'] === true
         && d['verified_type'] === 'blue';
     })),
-  // The x pack answers user.fields=profile_image_url with X's default avatar for an account seeded
-  // without a photo (every X account has one); this pack omits it, because a PARTIALLY-pulled persona
-  // cannot tell "no photo" from "not pulled" (renderUser). Serving the default for a seeded persona
-  // needs that distinction recorded on the row — until then the two packs answer differently (§9).
-  todo('xidentity.users_me.default_profile_image', 'users_me', "user.fields=profile_image_url for a persona seeded without a photo: X's default avatar URL (abs.twimg.com default_profile_normal.png), as the x pack serves it, rather than omission", 'api', 'common'),
+  // Every X account has a profile image: X's default avatar until the person sets a photo (the x pack's
+  // `X_DEFAULT_PROFILE_IMAGE_URL`; X's own payload example serves it for a photo-less user). Postiz's X
+  // connect reads it from v2.me and recorded an empty picture for @acmeshoes while the x pack, asked
+  // for the same person, answered the default. A PULLED persona the reply told nothing about stays
+  // without one (the pull asked; a withheld field is not "no photo"). That both packs answer one person
+  // alike is xidentity-x-avatar.integration.test.ts: both packs on one root, which a shipped verify
+  // does not reach (A3).
+  done('xidentity.users_me.default_profile_image', 'users_me', "user.fields=profile_image_url for a persona seeded without a photo is X's default avatar URL (abs.twimg.com default_profile_normal.png), the same answer the x pack gives for the same person; a seeded photo is served as set, the field stays out unless asked for, and a pulled persona whose reply withheld it is not given one (the x pack's answer for the same person: xidentity-x-avatar.integration.test.ts)", 'api', 'common', () =>
+    withRoot(async (h) => {
+      const PLAIN = { id: '1790000000000000001', username: 'acmeshoes', name: 'Acme Shoes' };
+      const PHOTO = { id: '1790000000000000002', username: 'pictured', name: 'Pictured', profile_image_url: 'https://pbs.twimg.com/profile_images/1/pictured_normal.jpg' };
+      await h({ m: 'GET', p: '/i/oauth2/authorize' }); // seed the world (clients, session)
+      for (const person of [PLAIN, PHOTO]) await h({ m: 'POST', p: '/_twin/accounts', b: JSON.stringify(person) });
+      await pullXIdentity(async () => ({ data: { id: '4444', username: 'withheld' } }), h.root, '2026-02-01T00:00:01.000Z');
+      const meOf = async (accountId: string, query: string): Promise<Body | undefined> => {
+        await h({ m: 'POST', p: '/_twin/session', b: JSON.stringify({ account_id: accountId }) });
+        const { tokens } = await fullFlow(h);
+        const r = await h({ m: 'GET', p: `/2/users/me${query}`, h: { authorization: `Bearer ${tokens['access_token']}` } });
+        return r.status === 200 ? body(r).data : undefined;
+      };
+      const plain = await meOf(PLAIN.id, '?user.fields=profile_image_url');
+      const plainBare = await meOf(PLAIN.id, '');
+      const photo = await meOf(PHOTO.id, '?user.fields=profile_image_url,name');
+      const withheld = await meOf('4444', '?user.fields=profile_image_url');
+      return plain?.['profile_image_url'] === X_DEFAULT_PROFILE_IMAGE_URL
+        && plainBare !== undefined && !('profile_image_url' in plainBare)
+        && photo?.['profile_image_url'] === PHOTO.profile_image_url
+        && withheld?.['id'] === '4444' && !('profile_image_url' in withheld);
+    })),
   done('xidentity.users_me.public_metrics', 'users_me', 'user.fields=public_metrics returns the metrics object with the vendor\'s six counters', 'api', 'common', () =>
     withRoot(async (h) => {
       const { tokens } = await fullFlow(h);

package/src/xidentity-twin.ts

@@ -639,13 +639,33 @@ export const USER_FIELDS = [
 /** The `expansions` enum — UserExpansionsParameter (2.167), verbatim. */
 export const USER_EXPANSIONS = ['affiliation', 'most_recent_post_id', 'pinned_post_id'] as const;
 
+/** The picture X shows for an account that never uploaded one. Every X account has a profile image;
+ *  until the person sets a photo it is this URL — the `profile_image_url_https` X serves for such a
+ *  user (docs.x.com/x-api/account-activity/introduction, its payload example's "Harrison Test",
+ *  fetched 2026-09-28), and the URL answers X's grey silhouette (observed 2026-09-28:
+ *  `curl -sS -o /dev/null -w '%{http_code} %{content_type}'` over it gives `200 image/png`, 48×48).
+ *  TRANSCRIBED from the x pack's `X_DEFAULT_PROFILE_IMAGE_URL` (packages/twin/x/src/x-twin.ts), not
+ *  imported (A3); xidentity-x-avatar.integration.test.ts asks both packs for the same person
+ *  on one root and fails if they part. */
+export const X_DEFAULT_PROFILE_IMAGE_URL = 'https://abs.twimg.com/sticky/default_profile_images/default_profile_normal.png';
+
+/** A persona's `profile_image_url`: the photo on the row, else X's default for a persona the twin
+ *  seeded (a seeded persona without a photo has none, and X answers the default for that); a PULLED
+ *  persona without one is undefined, because the pull asked for the field and a reply that withheld
+ *  it (partial errors) says nothing about the real account's picture. */
+function profileImageOf(account: Row): string | undefined {
+  if (typeof account.profileImageUrl === 'string' && account.profileImageUrl !== '') return account.profileImageUrl;
+  return account.pulled === true ? undefined : X_DEFAULT_PROFILE_IMAGE_URL;
+}
+
 /** The scopes GET /2/users/me demands — the OpenAPI operation's OAuth2UserToken entry lists BOTH. */
 export const USERS_ME_REQUIRED_SCOPES = ['tweet.read', 'users.read'] as const;
 
 /** Map an account row to the vendor's User object for a requested field set. Default fields are
  *  id, name, username (the OpenAPI/docs default); everything else appears only when asked for and
  *  only when the twin models it — a modelled-but-absent optional field is OMITTED, matching the
- *  spec (no User property is `required`). Unmodelled enum values (`connection_status`,
+ *  spec (no User property is `required`) — except `profile_image_url`, which every X account has
+ *  (X's default avatar until a photo is set; `profileImageOf`). Unmodelled enum values (`connection_status`,
  *  `receives_your_dm`, …) are accepted and omitted; each is a named manifest todo, not silent.
  *  `confirmed_email` additionally demands the `users.email` scope (X's April-2025 announcement —
  *  see xidentity-scopes.ts); OMISSION when the scope is missing is EXTRAPOLATION, pinned by
@@ -663,7 +683,10 @@ function renderUser(account: Row, fields: readonly string[], heldScopes: readonl
   if (want.has('created_at') && typeof account.createdAt === 'string') out['created_at'] = account.createdAt;
   if (want.has('description') && typeof account.description === 'string') out['description'] = account.description;
   if (want.has('location') && typeof account.location === 'string') out['location'] = account.location;
-  if (want.has('profile_image_url') && typeof account.profileImageUrl === 'string') out['profile_image_url'] = account.profileImageUrl;
+  if (want.has('profile_image_url')) {
+    const picture = profileImageOf(account);
+    if (picture !== undefined) out['profile_image_url'] = picture;
+  }
   if (want.has('protected')) out['protected'] = account.protectedAccount === true;
   if (want.has('public_metrics') && account.publicMetrics && typeof account.publicMetrics === 'object') out['public_metrics'] = account.publicMetrics;
   if (want.has('url') && typeof account.url === 'string') out['url'] = account.url;