@volter/twin-xidentity 0.1.0 → 0.1.2

package/dist/src/xidentity-conformance.js

@@ -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';
@@ -41,6 +42,68 @@ const authQuery = `response_type=code&client_id=${encodeURIComponent(DEFAULT_CLI
     + `&state=probe-state&code_challenge=${pkceS256(VERIFIER)}&code_challenge_method=S256`;
 const form = (params) => 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) => 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, url, consumer, token, signed = {}) {
+    const [baseUrl, query = ''] = url.split('?');
+    const oauth = {
+        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;
+export function oauth1Fixtures(call) {
+    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) => new URLSearchParams(typeof b === 'string' ? b : '');
 /** A representative request per declared endpoint, with the outcome a LIVE handler produces. */
 const PROBES = {
     'GET /i/oauth2/authorize': {
@@ -89,6 +152,82 @@ const PROBES = {
             && 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,
+    },
 };
 /**
  * Every VENDOR method/path pair a reader of `routeXIdentityTwinRequest` can see the router branch
@@ -112,6 +251,18 @@ const ROUTER_SURFACE = [
     ['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) => res.status === 404
     && isObject(res.body)
@@ -190,6 +341,32 @@ export async function checkXIdentityConformance(opts = {}) {
         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?.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)) {
@@ -231,12 +408,19 @@ export async function checkXIdentityConformance(opts = {}) {
                 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)}`);
@@ -309,6 +493,29 @@ export async function checkXIdentityConformance(opts = {}) {
                 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?.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) {