@volter/twin-xidentity 0.1.0 → 0.1.2

package/README.md

@@ -41,10 +41,10 @@ with X's consent descriptions; the **docs.x.com OAuth 2.0 guides** for the autho
 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 **82 done / 131 covered** (49 `todo`, and the login leg is not an API surface: it is the seeded session, so it is not in that
+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
-surface this twin does not model — most notably **OAuth 1.0a three-legged sign-in**, the **v1.1
-app-only bearer flow**, the unmodelled `user.fields` (entities, withheld, subscription, the
+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
 twin models from RFC 6749/7009 or widely-reported captures because no fetched official artefact
 states them (exact token error wording, the authorize error channel, refresh-token rotation, the
@@ -74,6 +74,37 @@ 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`)
+
+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
+through `twitter-api-v2`:
+
+- `POST oauth/request_token`, signed by a registered App with HMAC-SHA1, answers `oauth_token`,
+  `oauth_token_secret` and `oauth_callback_confirmed=true`; a callback the App does not list is
+  code 415, `oob` is the PIN flow, and `x_auth_access_type=read` narrows a Read-and-write App.
+- `GET oauth/authorize` and `GET oauth/authenticate` (served on `api.x.com`, where X serves them)
+  show the screen naming the App and the signed-in account, listing what its permission allows;
+  its form posts back to `POST oauth/authorize` on the same host, as X's screen does (on api.x.com,
+  which the `x` pack shares, that path and the screen's `/_twin/assets/consent.{js,css}` are this
+  pack's). Authorize app returns to the callback with exactly `oauth_token` + `oauth_verifier`, Cancel with
+  `denied=<request token>`. `authenticate` skips the screen once the person approved the App
+  (unless `force_login=true`).
+- `POST oauth/access_token` trades the approved request token and verifier, once, for
+  `<user id>-<token>`, its secret, `user_id` and `screen_name`; approving the same App again returns
+  the token already held. `POST 1.1/oauth/invalidate_token` revokes it.
+- The access token signs `GET /2/users/me` here and the posting surface in the `x` pack (which
+  reads this pack's `oauth1_token` rows). An unknown consumer key or a signature that does not
+  verify is code 32 at the legs and the `about:blank` 401 on `/2`.
+- The **World's own App** is the pair the World's env names (`X_API_KEY` / `X_API_SECRET`, or
+  `TWITTER_API_KEY` / `TWITTER_API_SECRET`), read with `worldEnvValue`, named for the World and
+  accepting any callback — the slack pack's World-app rule. Other Apps are registered through
+  `POST /_twin/oauth1_apps`.
+
+Not modelled (manifest todos): the timestamp window and nonce replay (the twin's clock is the
+World's, an app signs with its host's), request-token expiry, the login step `force_login` and
+`screen_name` would show, and the live wording of several refusals, each pinned by name.
+
 ### What is not
 
 The twin **authenticates nobody**: no password, no 2FA, no risk engine. The
@@ -86,7 +117,9 @@ service-areas to add within this same pack; they are not a reason to create a se
 
 `GET /_twin/consent` (re-render a pending authorize screen by request handle) and
 `POST /_twin/consent` (the Authorize/Cancel form post — X's real form posts to an undocumented
-internal endpoint), `POST /_twin/clients`, `POST /_twin/accounts`, `POST /_twin/session`,
+internal endpoint; the OAuth 1.0a screen's posts to `POST oauth/authorize`, above),
+`POST /_twin/oauth1_apps` (register an OAuth 1.0a App: consumer key and secret, callback URLs,
+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`.

package/client/xidentity-consent.tsx

@@ -44,8 +44,12 @@ export type ConsentView = {
   /** The x.com session this browser is signed in as — the account that will consent. */
   account: ConsentAccount;
   scopes: ConsentScopeRow[];
-  /** Host of the validated redirect_uri, shown in the "you'll be redirected to" notice. */
+  /** Host of the validated redirect_uri, shown in the "you'll be redirected to" notice. Empty for
+   *  an OAuth 1.0a out-of-band (PIN) request, which redirects nowhere. */
   redirectHost: string;
+  /** Where the decision posts, under `origin`: `/_twin/consent` for an OAuth 2.0 authorize screen,
+   *  `/oauth/authorize` for an OAuth 1.0a one, as X's own screen posts (the request token is the handle). */
+  decisionPath?: string;
 };
 
 /** The X mark, drawn rather than fetched — a twin never reaches out to a vendor CDN. */
@@ -96,7 +100,7 @@ export function ConsentPage({ view }: { view: ConsentView }) {
       <ScopeSection heading={`Things ${appName} can view`} rows={view.scopes.filter((s) => s.group === 'view')} />
       <ScopeSection heading={`Things ${appName} can do`} rows={view.scopes.filter((s) => s.group === 'do')} />
       <ScopeSection heading="Until you revoke access" rows={view.scopes.filter((s) => s.group === 'session')} />
-      <form method="POST" action={`${view.origin}/_twin/consent`} className="consent-form">
+      <form method="POST" action={`${view.origin}${view.decisionPath ?? '/_twin/consent'}`} className="consent-form">
         <input type="hidden" name="auth_request" value={view.requestId} />
         <div className="actions">
           <button className="btn btn-primary" type="submit" name="decision" value="allow">
@@ -108,8 +112,41 @@ export function ConsentPage({ view }: { view: ConsentView }) {
         </div>
       </form>
       <p className="legal">
-        You&apos;ll be redirected to <strong className="redirect-host">{view.redirectHost}</strong>. You can revoke
-        access to any app at any time from the Apps and sessions section of your X settings.
+        {view.redirectHost ? (
+          <>
+            You&apos;ll be redirected to <strong className="redirect-host">{view.redirectHost}</strong>.{' '}
+          </>
+        ) : null}
+        You can revoke access to any app at any time from the Apps and sessions section of your X settings.
+      </p>
+    </div>
+  );
+}
+
+export type PinPageProps = {
+  appName: string;
+  /** The oauth_verifier, shown as the PIN the person types into the app (out-of-band flow). */
+  pin: string;
+};
+
+/**
+ * The OAuth 1.0a out-of-band ending: an app that registered `oauth_callback=oob` gets no redirect,
+ * so X shows the verifier as a PIN for the person to type into the app (docs.x.com PIN-based
+ * authorization). The layout follows the classic screen as widely screenshotted; its live DOM was
+ * not captured (`xidentity.oauth1.consent_wording`, todo).
+ */
+export function PinPage({ appName, pin }: PinPageProps) {
+  return (
+    <div className="card">
+      <header className="x-header">
+        <XMark />
+      </header>
+      <h1 className="title">
+        You&apos;ve granted access to <strong className="app-name">{appName}</strong>!
+      </h1>
+      <p className="legal">Next, return to {appName} and enter this PIN to complete the authorization process:</p>
+      <p className="title">
+        <code className="oauth-pin">{pin}</code>
       </p>
     </div>
   );