@volter/twin-xidentity 0.1.0 → 0.1.2

package/src/xidentity-conformance.ts

@@ -14,6 +14,7 @@
 // authorization request, a real consent, a real 302 carrying a real code+state, that code redeemed
 // (PKCE verified) for a real token, and that token answering GET /2/users/me with the consenting
 // persona. A router that dispatches every route while folding nothing cannot pass that.
+import { createHmac } from 'node:crypto';
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
@@ -34,6 +35,8 @@ type Probe = {
   path: string;
   body?: string;
   headers?: Record<string, string>;
+  /** An OAuth 1.0a probe is signed per request against a fresh fixture, so it builds its request. */
+  build?: (fx: OAuth1Fixtures) => Promise<{ path: string; body?: string; headers: Record<string, string> }>;
   /** The status(es) a WORKING handler answers with. */
   status: number[];
   /** What a working handler's body must look like. */
@@ -66,6 +69,90 @@ const authQuery = `response_type=code&client_id=${encodeURIComponent(DEFAULT_CLI
 const form = (params: Record<string, string>) => new URLSearchParams(params).toString();
 const basic = `Basic ${Buffer.from(`${DEFAULT_CLIENT_ID}:${DEFAULT_CLIENT_SECRET}`).toString('base64')}`;
 
+// ── an OAuth 1.0a CLIENT, written here from docs.x.com's creating-a-signature guide ─────────────
+// Deliberately NOT the handler's verifier (xidentity-oauth1.ts): a check that signs with the same
+// code it verifies with would agree with itself. The consumer library (twitter-api-v2) is the
+// third, independent party in xidentity-oauth1.integration.test.ts.
+const enc = (s: string) => encodeURIComponent(s).replace(/[!'()*]/g, (c) => '%' + c.charCodeAt(0).toString(16).toUpperCase());
+let nonceCounter = 0;
+/** The Authorization header for `method url` with these extra signed params (query + form body). */
+export function oauth1Header(
+  method: string,
+  url: string,
+  consumer: { key: string; secret: string },
+  token: { key: string; secret: string } | null,
+  signed: Record<string, string> = {},
+): string {
+  const [baseUrl, query = ''] = url.split('?');
+  const oauth: Record<string, string> = {
+    oauth_consumer_key: consumer.key,
+    oauth_nonce: `probe${(nonceCounter += 1)}`,
+    oauth_signature_method: 'HMAC-SHA1',
+    oauth_timestamp: '1769904000',
+    oauth_version: '1.0',
+    ...(token ? { oauth_token: token.key } : {}),
+  };
+  const params = [...Object.entries(oauth), ...Object.entries(signed), ...new URLSearchParams(query).entries()]
+    .map(([k, v]) => `${enc(k)}=${enc(v)}`)
+    .sort();
+  const base = `${method.toUpperCase()}&${enc(baseUrl!)}&${enc(params.join('&'))}`;
+  oauth['oauth_signature'] = createHmac('sha1', `${enc(consumer.secret)}&${enc(token?.secret ?? '')}`).update(base).digest('base64');
+  return 'OAuth ' + Object.entries(oauth).map(([k, v]) => `${enc(k)}="${enc(v)}"`).join(', ');
+}
+
+/** The App the OAuth 1.0a probes run under, registered through the twin door. */
+export const OAUTH1_PROBE_APP = { key: 'ProbeConsumerKey000000001', secret: 'ProbeConsumerSecret00000000000000000000000000001' };
+export const OAUTH1_PROBE_CALLBACK = 'https://probe-app.local/x/callback';
+const FORM_TYPE = { 'content-type': 'application/x-www-form-urlencoded' };
+/** This check reaches the twin at the World's origin, so its client signs that URL (a client the
+ *  injector re-aims signs https://api.x.com and the twin reads the host it named — proven by the
+ *  twitter-api-v2 test). */
+const API = DEMO_ORIGIN;
+
+type Call = (method: string, path: string, body?: string, headers?: Record<string, string>) => Promise<XResponse>;
+export type OAuth1Fixtures = {
+  /** A fresh request token (and its secret) from step 1. */
+  requestToken(): Promise<{ key: string; secret: string }>;
+  /** A fresh request token whose screen the person has open (the decision is still to make). */
+  presented(): Promise<{ key: string; secret: string }>;
+  /** A request token taken through the screen and approved: its verifier. */
+  approved(): Promise<{ key: string; secret: string; verifier: string }>;
+  /** A usable access token for the signed-in persona. */
+  accessToken(): Promise<{ key: string; secret: string }>;
+};
+
+export function oauth1Fixtures(call: Call): OAuth1Fixtures {
+  const requestToken = async () => {
+    const body = new URLSearchParams({ oauth_callback: OAUTH1_PROBE_CALLBACK }).toString();
+    const r = await call('POST', '/oauth/request_token', body, { ...FORM_TYPE, authorization: oauth1Header('POST', `${API}/oauth/request_token`, OAUTH1_PROBE_APP, null, { oauth_callback: OAUTH1_PROBE_CALLBACK }) });
+    const got = new URLSearchParams(String(r.body));
+    return { key: got.get('oauth_token') ?? '', secret: got.get('oauth_token_secret') ?? '' };
+  };
+  const presented = async () => {
+    const t = await requestToken();
+    await call('GET', `/oauth/authorize?oauth_token=${encodeURIComponent(t.key)}`);
+    return t;
+  };
+  const approved = async () => {
+    const t = await requestToken();
+    const screen = await call('GET', `/oauth/authorize?oauth_token=${encodeURIComponent(t.key)}`);
+    const handle = /name="auth_request" value="([^"]+)"/.exec(String(screen.body))?.[1] ?? '';
+    const d = await call('POST', '/oauth/authorize', new URLSearchParams({ auth_request: handle, decision: 'allow' }).toString(), FORM_TYPE);
+    const verifier = new URL(d.headers?.location ?? 'http://invalid.test/').searchParams.get('oauth_verifier') ?? '';
+    return { ...t, verifier };
+  };
+  const accessToken = async () => {
+    const t = await approved();
+    const body = new URLSearchParams({ oauth_verifier: t.verifier }).toString();
+    const r = await call('POST', '/oauth/access_token', body, { ...FORM_TYPE, authorization: oauth1Header('POST', `${API}/oauth/access_token`, OAUTH1_PROBE_APP, t, { oauth_verifier: t.verifier }) });
+    const got = new URLSearchParams(String(r.body));
+    return { key: got.get('oauth_token') ?? '', secret: got.get('oauth_token_secret') ?? '' };
+  };
+  return { requestToken, presented, approved, accessToken };
+}
+
+const formOf = (b: unknown) => new URLSearchParams(typeof b === 'string' ? b : '');
+
 /** A representative request per declared endpoint, with the outcome a LIVE handler produces. */
 const PROBES: Record<string, Probe> = {
   'GET /i/oauth2/authorize': {
@@ -116,6 +203,82 @@ const PROBES: Record<string, Probe> = {
       && b.data['username'] === ADA.username
       && b.data['name'] === ADA.name,
   },
+  'POST /oauth/request_token': {
+    method: 'POST',
+    path: '/oauth/request_token',
+    build: async () => ({
+      path: '/oauth/request_token',
+      body: new URLSearchParams({ oauth_callback: OAUTH1_PROBE_CALLBACK }).toString(),
+      headers: { ...FORM_TYPE, authorization: oauth1Header('POST', `${API}/oauth/request_token`, OAUTH1_PROBE_APP, null, { oauth_callback: OAUTH1_PROBE_CALLBACK }) },
+    }),
+    status: [200],
+    // The documented response: oauth_token, oauth_token_secret and oauth_callback_confirmed=true.
+    expect: (b) => formOf(b).get('oauth_callback_confirmed') === 'true' && (formOf(b).get('oauth_token') ?? '') !== '' && (formOf(b).get('oauth_token_secret') ?? '') !== '',
+  },
+  'GET /oauth/authorize': {
+    method: 'GET',
+    path: '/oauth/authorize',
+    build: async (fx) => ({ path: `/oauth/authorize?oauth_token=${encodeURIComponent((await fx.requestToken()).key)}`, headers: {} }),
+    status: [200],
+    // The screen names the registered App, the signed-in persona, and what Read-and-write allows.
+    expect: htmlContaining('Authorize app', 'Cancel', '>Probe App<', `@${ADA.username}`, 'Post and delete Posts for you', 'probe-app.local'),
+  },
+  'POST /oauth/authorize': {
+    method: 'POST',
+    path: '/oauth/authorize',
+    // The screen's Authorize app button: its form posts here, on the host that served the screen.
+    build: async (fx) => ({
+      path: '/oauth/authorize',
+      body: new URLSearchParams({ auth_request: (await fx.presented()).key, decision: 'allow' }).toString(),
+      headers: FORM_TYPE,
+    }),
+    status: [302],
+  },
+  'GET /oauth/authenticate': {
+    method: 'GET',
+    path: '/oauth/authenticate',
+    // After the round trip below the persona has approved Probe App, so Sign in with X skips the
+    // screen: the answer is the callback itself, carrying a verifier (checked after the call) —
+    // only a projected grant can say so.
+    build: async (fx) => ({ path: `/oauth/authenticate?oauth_token=${encodeURIComponent((await fx.requestToken()).key)}`, headers: {} }),
+    status: [302],
+  },
+  'POST /oauth/access_token': {
+    method: 'POST',
+    path: '/oauth/access_token',
+    build: async (fx) => {
+      const t = await fx.approved();
+      return {
+        path: '/oauth/access_token',
+        body: new URLSearchParams({ oauth_verifier: t.verifier }).toString(),
+        headers: { ...FORM_TYPE, authorization: oauth1Header('POST', `${API}/oauth/access_token`, OAUTH1_PROBE_APP, t, { oauth_verifier: t.verifier }) },
+      };
+    },
+    status: [200],
+    // The documented example's shape: `<user id>-<40 alnum>`, a secret, user_id and screen_name.
+    expect: (b) => new RegExp(`^${ADA.id}-[A-Za-z0-9]{40}$`).test(formOf(b).get('oauth_token') ?? '')
+      && (formOf(b).get('oauth_token_secret') ?? '') !== '' && formOf(b).get('user_id') === ADA.id && formOf(b).get('screen_name') === ADA.username,
+  },
+  'POST /1.1/oauth/invalidate_token': {
+    method: 'POST',
+    path: '/1.1/oauth/invalidate_token',
+    build: async (fx) => {
+      const t = await fx.accessToken();
+      return { path: '/1.1/oauth/invalidate_token', headers: { authorization: oauth1Header('POST', `${API}/1.1/oauth/invalidate_token`, OAUTH1_PROBE_APP, t) } };
+    },
+    status: [200],
+    expect: (b) => isObject(b) && new RegExp(`^${ADA.id}-[A-Za-z0-9]{40}$`).test(String(b['access_token'])) && Object.keys(b).length === 1,
+  },
+  'POST /1.1/oauth/invalidate_token.json': {
+    method: 'POST',
+    path: '/1.1/oauth/invalidate_token.json',
+    build: async (fx) => {
+      const t = await fx.accessToken();
+      return { path: '/1.1/oauth/invalidate_token.json', headers: { authorization: oauth1Header('POST', `${API}/1.1/oauth/invalidate_token.json`, OAUTH1_PROBE_APP, t) } };
+    },
+    status: [200],
+    expect: (b) => isObject(b) && new RegExp(`^${ADA.id}-[A-Za-z0-9]{40}$`).test(String(b['access_token'])) && Object.keys(b).length === 1,
+  },
 };
 
 /**
@@ -140,6 +303,18 @@ const ROUTER_SURFACE: Array<[string, string]> = [
   ['GET', '/2/oauth2/authorize'],
   ['GET', '/2/users/by'],
   ['GET', '/oauth2/token'],
+  ['POST', '/oauth/request_token'],
+  ['GET', '/oauth/request_token'],
+  ['GET', '/oauth/authorize'],
+  ['POST', '/oauth/authorize'],
+  ['GET', '/oauth/authenticate'],
+  ['POST', '/oauth/authenticate'],
+  ['POST', '/oauth/access_token'],
+  ['GET', '/oauth/access_token'],
+  ['POST', '/1.1/oauth/invalidate_token'],
+  ['POST', '/1.1/oauth/invalidate_token.json'],
+  ['GET', '/1.1/oauth/invalidate_token'],
+  ['POST', '/oauth/invalidate_token'],
 ];
 
 const isNotFoundEnvelope = (res: XResponse): boolean =>
@@ -225,6 +400,30 @@ export async function checkXIdentityConformance(opts: { root?: string } = {}): P
     const spent = await call('POST', '/2/oauth2/token', form({ grant_type: 'refresh_token', refresh_token: String(tokens?.refresh_token), client_id: DEFAULT_CLIENT_ID }), { authorization: basic });
     if (spent.status !== 400) violations.push(`a spent refresh token was accepted a second time: ${spent.status}`);
 
+    // ── the OAuth 1.0a round trip: request_token → screen → callback → access_token → users/me ──
+    await call('POST', '/_twin/oauth1_apps', JSON.stringify({ consumer_key: OAUTH1_PROBE_APP.key, consumer_secret: OAUTH1_PROBE_APP.secret, name: 'Probe App', callback_urls: [OAUTH1_PROBE_CALLBACK] }));
+    const fx = oauth1Fixtures(call);
+    const rt = await fx.requestToken();
+    if (!rt.key || !rt.secret) violations.push('OAuth 1.0a: request_token did not issue a request token for a registered App');
+    const screen = await call('GET', `/oauth/authorize?oauth_token=${encodeURIComponent(rt.key)}`);
+    const rtHandle = /name="auth_request" value="([^"]+)"/.exec(String(screen.body))?.[1] ?? '';
+    if (rtHandle !== rt.key) violations.push('OAuth 1.0a: the authorize screen did not carry the request token as its handle');
+    const approval = await call('POST', '/oauth/authorize', form({ auth_request: rtHandle, decision: 'allow' }), FORM_TYPE);
+    const cb = new URL(approval.headers?.location ?? 'http://invalid.test/');
+    if (approval.status !== 302 || `${cb.origin}${cb.pathname}` !== OAUTH1_PROBE_CALLBACK || cb.searchParams.get('oauth_token') !== rt.key
+      || [...cb.searchParams.keys()].sort().join(',') !== 'oauth_token,oauth_verifier') {
+      violations.push(`OAuth 1.0a: approval did not 302 to the callback with exactly oauth_token + oauth_verifier: ${approval.status} ${cb}`);
+    }
+    const verifierParam = cb.searchParams.get('oauth_verifier') ?? '';
+    const exchanged = await call('POST', '/oauth/access_token', form({ oauth_verifier: verifierParam }), { ...FORM_TYPE, authorization: oauth1Header('POST', `${API}/oauth/access_token`, OAUTH1_PROBE_APP, rt, { oauth_verifier: verifierParam }) });
+    const at1 = { key: formOf(exchanged.body).get('oauth_token') ?? '', secret: formOf(exchanged.body).get('oauth_token_secret') ?? '' };
+    const me1 = await call('GET', '/2/users/me', undefined, { authorization: oauth1Header('GET', `${API}/2/users/me`, OAUTH1_PROBE_APP, at1) });
+    if (me1.status !== 200 || (me1.body as Record<string, any>)?.data?.username !== ADA.username) {
+      violations.push(`OAuth 1.0a: the access token did not answer /2/users/me as the consenting persona: ${me1.status} ${JSON.stringify(me1.body).slice(0, 160)}`);
+    }
+    const forged = await call('GET', '/2/users/me', undefined, { authorization: oauth1Header('GET', `${API}/2/users/me`, OAUTH1_PROBE_APP, { key: at1.key, secret: 'forged' }) });
+    if (forged.status !== 401) violations.push(`OAuth 1.0a: a signature made with the wrong token secret was accepted at /2/users/me: ${forged.status}`);
+
     // ── the endpoint census, THREE ways ──
     const claimed = new Set(snapshot.implementedEndpoints);
     for (const key of Object.keys(PROBES)) {
@@ -269,12 +468,19 @@ export async function checkXIdentityConformance(opts: { root?: string } = {}): P
         violations.push(`probe '${endpoint}' drives ${probe.path}, which is not the claimed path ${claimedPath}`);
         continue;
       }
-      const path = substitute(probe.path);
-      const body = endpoint === 'POST /2/oauth2/revoke'
+      const built = probe.build ? await probe.build(fx) : undefined;
+      const path = built ? built.path : substitute(probe.path);
+      const body = built ? built.body : endpoint === 'POST /2/oauth2/revoke'
         ? form({ token: String(revokeFixture?.access_token ?? ''), client_id: DEFAULT_CLIENT_ID, token_type_hint: 'access_token' })
         : probe.body === undefined ? undefined : substitute(probe.body);
-      const headers = probe.headers ? Object.fromEntries(Object.entries(probe.headers).map(([k, v]) => [k, substitute(v)])) : undefined;
+      const headers = built ? built.headers : probe.headers ? Object.fromEntries(Object.entries(probe.headers).map(([k, v]) => [k, substitute(v)])) : undefined;
       const res = await call(probe.method, path, body, headers);
+      if (endpoint === 'GET /oauth/authenticate' && res.status === 302) {
+        const back = new URL(res.headers?.location ?? 'http://invalid.test/');
+        if (`${back.origin}${back.pathname}` !== OAUTH1_PROBE_CALLBACK || !/^[A-Za-z0-9]{32}$/.test(back.searchParams.get('oauth_verifier') ?? '')) {
+          violations.push(`endpoint '${endpoint}' did not skip the approved screen to the callback with a verifier: ${res.headers?.location}`);
+        }
+      }
       probed += 1;
       if (!probe.status.includes(res.status)) {
         violations.push(`endpoint '${endpoint}' answered ${res.status} (expected ${probe.status.join('/')}): ${JSON.stringify(res.body).slice(0, 160)}`);
@@ -348,6 +554,29 @@ export async function checkXIdentityConformance(opts: { root?: string } = {}): P
         return r.status === 429 && Array.isArray(errs) && errs[0]?.code === 88;
       },
     };
+    // OAuth 1.0a: each row type is witnessed by a value only its projection can produce.
+    witness['oauth1_app'] = async () => {
+      // the registered App's NAME is on the screen only if its row projected
+      const t = await fx.requestToken();
+      return String((await call('GET', `/oauth/authorize?oauth_token=${encodeURIComponent(t.key)}`)).body).includes('>Probe App<');
+    };
+    witness['oauth1_request_token'] = async () => {
+      // an access_token exchange succeeds only for a request token whose secret projected
+      const t = await fx.approved();
+      const r = await call('POST', '/oauth/access_token', form({ oauth_verifier: t.verifier }), { ...FORM_TYPE, authorization: oauth1Header('POST', `${API}/oauth/access_token`, OAUTH1_PROBE_APP, t, { oauth_verifier: t.verifier }) });
+      return r.status === 200 && formOf(r.body).get('user_id') === ADA.id;
+    };
+    witness['oauth1_token'] = async () => {
+      const t = await fx.accessToken();
+      const r = await call('GET', '/2/users/me', undefined, { authorization: oauth1Header('GET', `${API}/2/users/me`, OAUTH1_PROBE_APP, t) });
+      return r.status === 200 && (r.body as Record<string, any>)?.data?.id === ADA.id;
+    };
+    witness['oauth1_grant'] = async () => {
+      // Sign in with X skips the screen only when a projected grant says the persona approved
+      const t = await fx.requestToken();
+      const r = await call('GET', `/oauth/authenticate?oauth_token=${encodeURIComponent(t.key)}`);
+      return r.status === 302 && (r.headers?.location ?? '').startsWith(OAUTH1_PROBE_CALLBACK);
+    };
     for (const type of snapshot.resourceTypes) {
       const probe = witness[type];
       if (!probe) {