@volter/twin-xidentity 0.1.10 → 0.1.12

package/README.md

@@ -17,7 +17,7 @@ X's OAuth 2.0 issues **opaque bearer tokens**: no `id_token`, no JWKS, no discov
 Identity is fetched from `GET /2/users/me` with the access token. That non-OIDC shape is the whole
 reason this vendor needs its own pack next to `googleoauth` — an integration built against an OIDC
 provider (id_token claims, `openid email profile` scopes) breaks against X in exactly the ways this
-twin reproduces: the scope model is X's own catalog (the OpenAPI's 24 scopes plus the announcement-added
+twin reproduces: the scope model is X's own catalog (the OpenAPI's 26 scopes plus the announcement-added
 `users.email`, which gates `confirmed_email` — a recorded intra-vendor discrepancy), the refresh
 token only arrives with `offline.access`, PKCE is **required**, and the only identity read is the
 API call.
@@ -31,18 +31,45 @@ bundle and stylesheet the twin serves are **committed text** (`src/xidentity-con
 written from `client/` by `bun scripts/consent-clients.ts` and drift-gated by
 `scripts/consent-clients.test.ts`): the serve path reads constants and never runs a bundler.
 
+## A derived pack (Protocol 3)
+
+The pack is derived ([architecture](../../../docs/contributing/architecture.md#protocol-3-the-derived-pack)) from
+X's own OpenAPI document, X API v2 version 2.168 (`spec/openapi.json.gz`, the same bytes the `x` pack vendors;
+provenance in `spec/SOURCE.md`), corrected by `spec/patches.json`: the `x` pack's corrections to the wire's names
+(`tweet.fields`, `pinned_tweet_id`, `most_recent_tweet_id`), and X's OAuth endpoints the document does not list,
+patched in from docs.x.com's Authorization Code Flow page and OAuth API reference. `bun scripts/derive-pack.ts
+xidentity` writes the wire (`src/generated/`). `GET /2/users/me`, `POST /2/oauth2/token`, `POST /2/oauth2/revoke`,
+`POST /oauth/request_token`, `POST /oauth/access_token` and `POST /1.1/oauth/invalidate_token` (and its `.json`
+form) are semantics handlers (`src/semantics/`); every other operation of the document is the gap, X's 404
+problem — in a World the `x` pack claims those paths on `api.x.com` and `api.twitter.com`. The authorize pages are
+screens (`src/screens/`), and the World's doors are `src/xidentity-doors.ts`. `src/manifest.ts` declares the
+state machines the handlers and screens ask on every move (a screen's settling, a code's redemption, a refresh
+token's rotation and revocation, an access token's revocation, an OAuth 1.0a request token's life, an OAuth 1.0a
+access token's invalidation).
+
+**A credential is bookkeeping, kept by its SHA-256** — an authorization code, an access token, a refresh token, an
+OAuth 1.0a request token and an OAuth 2.0 App's client secret live under `_` types, never as a subject id or a field
+of an entry that could be deployed or read in a changeset. A World that ran the protocol 1 pack keeps its
+credentials under the types they were written as; they still resolve, and the first move on one writes it as
+bookkeeping. Two rows keep a secret by contract: the OAuth 1.0a App (`oauth1_app`) and access token
+(`oauth1_token`), which the `x` pack reads by the token itself through the kernel's owner read
+(`xidentity-oauth1.ts` states the row shapes); moving them is that contract's change, on both packs at once.
+
+Not done by the Protocol 3 procedure yet: the customer life, the vendor's published examples and the report
+(`journeys/`); the capability manifest stays the pack's T0.
+
 ## Coverage
 
 Partial and honest. The manifest (`src/xidentity-capabilities.ts`) is the **enumerated identity
 service-area** denominator, not a claim to enumerate the whole X vendor surface. It is authored
-top-down from X's own artefacts (all fetched 2026-08-21): the **X API
-v2 OpenAPI document** (2.167) for `/2/users/me`, the Problem error family and the 24-scope catalog
-with X's consent descriptions; the **docs.x.com OAuth 2.0 guides** for the authorize/token/refresh/
+top-down from X's own artefacts (first fetched 2026-08-21): the **X API
+v2 OpenAPI document** (2.167 then; 2.168 vendored now) for `/2/users/me`, the Problem error family and the scope
+catalog with X's consent descriptions; the **docs.x.com OAuth 2.0 guides** for the authorize/token/refresh/
 revoke requests; the **docs.x.com rate-limit pages** for the `x-rate-limit-*` headers and the
 75/15-minute per-user figure; and the **official SDK sources** (`@xdevplatform/xdk`,
 `twitter-api-typescript-sdk`) for the token/revoke response shapes the docs never show as JSON.
-It currently reads **98 done / 160 covered** (62 `todo`, and the login leg is not an API surface: it is the seeded session, so it is not in that
-denominator). The `todo`s are real X identity
+It currently reads **103 done / 162 covered** (59 `todo`, and the login leg is not an API surface: it is the seeded
+session, so it is not in that denominator). The `todo`s are real X identity
 surface this twin does not model — most notably the **v1.1 app-only bearer flow**, OAuth 1.0a's
 timestamp window and nonce replay, the unmodelled `user.fields` (entities, withheld, subscription, the
 relational fields), expansion hydration — plus a family of **wire-pinning todos**: behaviours the
@@ -66,7 +93,8 @@ code TTL). Each such `done` names its evidence boundary in the manifest and its
 - **Vendor-shaped opaque credentials** — the twin's codes/tokens are base64url blobs whose decoded
   structure (`<opaque>:<unix-ms>:1:1:ac|at|rt:1`) matches what the docs' own examples decode to.
 - **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
+  `users.read`), the spec's `user.fields`, `expansions` and `tweet.fields` / `post.fields` enums with the wire's
+  invalid-parameter envelope (a query parameter the operation does not take is refused the same way), the
   documented `x-rate-limit-*` headers, 75/15min per-user accounting, and the documented
   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
@@ -77,7 +105,7 @@ code TTL). Each such `done` names its evidence boundary in the manifest and its
   (`xidentity-sdk.integration.test.ts`); the OAuth legs its hardcoded hosts cannot re-aim are
   proven over real transport in the docs' own curl shapes.
 
-### OAuth 1.0a (`src/xidentity-oauth1.ts`)
+### OAuth 1.0a (`src/semantics/oauth1.ts`, `src/screens/oauth1.ts`, `src/xidentity-oauth1.ts`)
 
 The three-legged flow as docs.x.com's API reference and "Obtaining access tokens using 3-legged
 OAuth flow" state it, which is what Postiz (`gitroomhq/postiz-app`) connects an X account with
@@ -112,9 +140,8 @@ World's, an app signs with its host's), request-token expiry, the login step `fo
 
 The twin **authenticates nobody**: no password, no 2FA, no risk engine. The
 x.com "signed in" session is a seeded persona row — `POST /_twin/session` switches it, which is the
-honest local equivalent of "the browser is already signed in". This is the **identity service-area**
-of the X vendor twin. Posts, timelines, DMs and the rest of the X content API are additional
-service-areas to add within this same pack; they are not a reason to create a second X vendor pack.
+honest local equivalent of "the browser is already signed in". This is X's **identity** surface; posts,
+timelines and media are the `x` pack's, which shares X's hosts with this one by path.
 
 ### Twin-only scaffolding (not vendor surface, not counted)
 
@@ -125,7 +152,7 @@ internal endpoint; the OAuth 1.0a screen's posts to `POST oauth/authorize`, abov
 permission), `POST /_twin/clients`, `POST /_twin/accounts`, `POST /_twin/session`,
 `POST /_twin/rate_limit` (arm a deterministic 429), and the `/_twin/assets/*` page assets. This
 list is the audit trail the conformance census deliberately excludes — keep it in lockstep with
-`twinControl`'s branches in `xidentity-twin.ts`.
+the doors in `xidentity-doors.ts`.
 
 ## The three operations
 
@@ -134,10 +161,11 @@ list is the audit trail the conformance census deliberately excludes — keep it
   `liveXIdentityExecute(accessToken)`, the ONE place a real X request may be issued, guarded by the
   fail-closed rate budget (`xidentity-budget.ts`: X's own 75/15min scheme, live-fetched
   2026-08-21). The client registry and the grant's scope set are **not observable** (no API reads
-  X Apps; X has no token introspection) — reasoned gaps, not fakes.
+  X Apps; X has no token introspection) — reasoned gaps, not fakes. The same read is the protocol 2
+  refresh adapter, `syncXIdentityFromRemote`, over the kernel's executor.
 - **write** — the default: local consent flows mint local credentials, no real calls.
 - **push** — structurally impossible (X exposes no write API for this surface) and reported as
-  such, never faked.
+  such, never faked: `performXIdentityAction` answers every entry `performed: false`.
 
 ## Serving