dexterm-cli 0.0.0-stage → 0.1.1

package/dist/packages/data/src/x/mock-server.js

@@ -0,0 +1,217 @@
+// @dexterm/data — a loopback MOCK of X's OAuth2 + the v2 read endpoints dexterm uses (task-1357). Test
+// support only: the default test suites and `dexterm x` tests run the whole login + feed flow against this
+// server and never touch x.com. It validates what the real X validates (client id, redirect uri, PKCE S256,
+// single-use 30-s codes, bearer, refresh rotation, revoke) and can simulate rate limits (429 + x-rate-limit-*),
+// expired tokens (401) and a Free-tier app (403 on search). Zero dependencies.
+import { createServer } from 'node:http';
+import { randomBytes } from 'node:crypto';
+import { pkceMatches } from "./pkce.js";
+/** Start the mock on an ephemeral loopback port. */
+export function startMockX(options = {}) {
+    const now = options.now ?? (() => Date.now());
+    const opts = {
+        clientId: 'mock-client-id-1357',
+        me: { id: '1001', username: 'dexterm_tester', name: 'dexterm tester', created_at: '2020-01-01T00:00:00.000Z' },
+        tier: 'basic',
+        consent: 'approve',
+        expiresIn: 7200,
+        ...options,
+    };
+    const users = new Map([[opts.me.id, opts.me], ...(opts.users ?? []).map((u) => [u.id, u])]);
+    const tweets = [...(opts.tweets ?? [])];
+    const lists = [...(opts.lists ?? [])];
+    const state = { access: new Map(), refresh: new Map(), codes: new Map(), log: [], calls: {}, rateLimitNext: null, unauthorized: false, windows: {} };
+    const rid = () => randomBytes(12).toString('base64url');
+    const windowFor = (key, limit) => {
+        const w = state.windows[key] ?? (state.windows[key] = { limit, remaining: limit, reset: Math.floor(now() / 1000) + 900 });
+        if (Math.floor(now() / 1000) >= w.reset) {
+            w.remaining = w.limit;
+            w.reset = Math.floor(now() / 1000) + 900;
+        }
+        return w;
+    };
+    return new Promise((resolve) => {
+        const server = createServer((req, res) => {
+            const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+            const key = `${req.method} ${url.pathname}`;
+            state.log.push(key);
+            state.calls[url.pathname] = (state.calls[url.pathname] ?? 0) + 1;
+            const chunks = [];
+            req.on('data', (c) => chunks.push(c));
+            req.on('end', () => {
+                const body = Buffer.concat(chunks).toString('utf8');
+                const json = (status, obj, headers = {}) => { res.writeHead(status, { 'content-type': 'application/json', ...headers }); res.end(JSON.stringify(obj)); };
+                // ---- authorize: the "consent screen". Redirects to the app's callback with code+state (or error).
+                if (req.method === 'GET' && url.pathname === '/i/oauth2/authorize') {
+                    const q = url.searchParams;
+                    const bad = (reason) => json(400, { error: 'invalid_request', error_description: reason });
+                    if (q.get('response_type') !== 'code')
+                        return bad('response_type');
+                    if (q.get('client_id') !== opts.clientId)
+                        return bad('client_id');
+                    if (q.get('code_challenge_method') !== 'S256' || !q.get('code_challenge'))
+                        return bad('pkce');
+                    const redirect = q.get('redirect_uri') ?? '';
+                    if (opts.redirectUri && redirect !== opts.redirectUri)
+                        return bad('redirect_uri');
+                    if (!/^http:\/\/127\.0\.0\.1:\d+\/callback$/.test(redirect))
+                        return bad('redirect_uri must be http://127.0.0.1:<port>/callback');
+                    const scope = q.get('scope') ?? '';
+                    if (/\.write\b|\bdm\./.test(scope))
+                        return bad('scope: write/dm scopes are refused by this mock (dexterm never asks for them)');
+                    const back = new URL(redirect);
+                    back.searchParams.set('state', q.get('state') ?? '');
+                    if (opts.consent === 'deny')
+                        back.searchParams.set('error', 'access_denied');
+                    else {
+                        const code = rid();
+                        state.codes.set(code, { challenge: q.get('code_challenge'), redirectUri: redirect, scope, issuedAt: now(), used: false });
+                        back.searchParams.set('code', code);
+                    }
+                    res.writeHead(302, { location: back.toString() });
+                    res.end();
+                    return;
+                }
+                // ---- token: authorization_code (PKCE) and refresh_token grants, public client
+                if (req.method === 'POST' && url.pathname === '/2/oauth2/token') {
+                    const f = new URLSearchParams(body);
+                    if (f.get('client_id') !== opts.clientId)
+                        return json(400, { error: 'invalid_client', error_description: 'Value passed for the client id was invalid.' });
+                    const issue = (user, scope) => {
+                        const access = `at-${rid()}`, refresh = scope.includes('offline.access') ? `rt-${rid()}` : null;
+                        state.access.set(access, { user, scope, expiresAt: now() + opts.expiresIn * 1000, revoked: false });
+                        if (refresh)
+                            state.refresh.set(refresh, { user, scope, revoked: false });
+                        return json(200, { token_type: 'bearer', expires_in: opts.expiresIn, access_token: access, scope, ...(refresh ? { refresh_token: refresh } : {}) });
+                    };
+                    if (f.get('grant_type') === 'authorization_code') {
+                        const c = state.codes.get(f.get('code') ?? '');
+                        if (!c || c.used)
+                            return json(400, { error: 'invalid_grant', error_description: 'Value passed for the authorization code was invalid.' });
+                        if (now() - c.issuedAt > 30_000)
+                            return json(400, { error: 'invalid_grant', error_description: 'authorization code expired' });
+                        if (f.get('redirect_uri') !== c.redirectUri)
+                            return json(400, { error: 'invalid_grant', error_description: 'redirect_uri mismatch' });
+                        if (!pkceMatches(f.get('code_verifier') ?? '', c.challenge))
+                            return json(400, { error: 'invalid_grant', error_description: 'PKCE verification failed' });
+                        c.used = true;
+                        return issue(opts.me, c.scope);
+                    }
+                    if (f.get('grant_type') === 'refresh_token') {
+                        const r = state.refresh.get(f.get('refresh_token') ?? '');
+                        if (!r || r.revoked)
+                            return json(400, { error: 'invalid_request', error_description: 'Value passed for the token was invalid.' });
+                        r.revoked = true; // X rotates refresh tokens
+                        return issue(r.user, r.scope);
+                    }
+                    return json(400, { error: 'unsupported_grant_type' });
+                }
+                if (req.method === 'POST' && url.pathname === '/2/oauth2/revoke') {
+                    const f = new URLSearchParams(body);
+                    if (f.get('client_id') !== opts.clientId)
+                        return json(400, { error: 'invalid_client' });
+                    const t = f.get('token') ?? '';
+                    const a = state.access.get(t);
+                    if (a)
+                        a.revoked = true;
+                    const r = state.refresh.get(t);
+                    if (r)
+                        r.revoked = true;
+                    return json(200, { revoked: true });
+                }
+                // ---- v2 reads: bearer required
+                const auth = req.headers.authorization ?? '';
+                const bearer = auth.startsWith('Bearer ') ? auth.slice(7) : '';
+                const a = state.access.get(bearer);
+                if (!a || a.revoked || a.expiresAt <= now() || state.unauthorized)
+                    return json(401, { title: 'Unauthorized', type: 'about:blank', status: 401, detail: 'Unauthorized' });
+                if (state.rateLimitNext && state.rateLimitNext.n > 0) {
+                    state.rateLimitNext.n -= 1;
+                    return json(429, { title: 'Too Many Requests', detail: 'Too Many Requests', type: 'about:blank', status: 429 }, { 'x-rate-limit-limit': '1', 'x-rate-limit-remaining': '0', 'x-rate-limit-reset': String(state.rateLimitNext.resetAt) });
+                }
+                const limited = (key, limit, fn) => {
+                    const w = windowFor(key, limit);
+                    if (w.remaining <= 0)
+                        return json(429, { title: 'Too Many Requests', status: 429 }, { 'x-rate-limit-limit': String(w.limit), 'x-rate-limit-remaining': '0', 'x-rate-limit-reset': String(w.reset) });
+                    w.remaining -= 1;
+                    res.setHeader('x-rate-limit-limit', String(w.limit));
+                    res.setHeader('x-rate-limit-remaining', String(w.remaining));
+                    res.setHeader('x-rate-limit-reset', String(w.reset));
+                    fn();
+                };
+                const userObj = (u) => ({ id: u.id, username: u.username, name: u.name ?? u.username, created_at: u.created_at ?? '2021-01-01T00:00:00.000Z' });
+                const tweetsPayload = (rows, max) => {
+                    const data = rows.slice(0, max).map((t) => ({ id: t.id, text: t.text, author_id: t.author_id, created_at: t.created_at, lang: t.lang ?? 'en', public_metrics: t.public_metrics ?? { like_count: 0, retweet_count: 0, reply_count: 0 } }));
+                    const ids = [...new Set(data.map((t) => t.author_id))];
+                    return { data, includes: { users: ids.map((id) => users.get(id)).filter((u) => !!u).map(userObj) }, meta: { result_count: data.length, ...(data.length ? { newest_id: data[0].id, oldest_id: data[data.length - 1].id } : {}) } };
+                };
+                const notEnrolled = () => json(403, { client_id: opts.clientId, detail: 'When authenticating requests to the Twitter API v2 endpoints, you must use keys and tokens from a Twitter developer App that is attached to a Project. You can create a project via the Developer Portal.', registration_url: 'https://developer.twitter.com/en/docs/projects/overview', title: 'Client Forbidden', required_enrollment: 'Appropriate Level of API Access', reason: 'client-not-enrolled', type: 'https://api.twitter.com/2/problems/client-forbidden' });
+                if (req.method === 'GET' && url.pathname === '/2/users/me')
+                    return limited('me', 75, () => json(200, { data: userObj(a.user) }));
+                if (req.method === 'GET' && url.pathname === '/2/tweets/search/recent') {
+                    if (opts.tier === 'free')
+                        return notEnrolled();
+                    return limited('search', 300, () => {
+                        const q = (url.searchParams.get('query') ?? '').toLowerCase();
+                        const terms = q.replace(/-is:\w+|lang:\w+|[()]/g, ' ').split(/\s+or\s+|\s+/).map((s) => s.trim()).filter((s) => s && s !== 'or');
+                        const sinceId = url.searchParams.get('since_id');
+                        const rows = tweets.filter((t) => terms.some((term) => t.text.toLowerCase().includes(term.replace(/^\$/, '').replace(/^from:/, '')) || (term.startsWith('from:') && users.get(t.author_id)?.username.toLowerCase() === term.slice(5))))
+                            .filter((t) => !sinceId || BigInt(t.id) > BigInt(sinceId))
+                            .sort((x, y) => (BigInt(y.id) > BigInt(x.id) ? 1 : -1));
+                        json(200, tweetsPayload(rows, Math.min(100, Number(url.searchParams.get('max_results') ?? 10))));
+                    });
+                }
+                const listTweets = url.pathname.match(/^\/2\/lists\/(\d+)\/tweets$/);
+                if (req.method === 'GET' && listTweets) {
+                    if (opts.tier === 'free')
+                        return notEnrolled();
+                    return limited('list-tweets', 900, () => {
+                        const l = lists.find((x) => x.id === listTweets[1]);
+                        if (!l)
+                            return json(404, { errors: [{ detail: 'Could not find list' }] });
+                        const members = new Set(l.member_ids);
+                        const rows = tweets.filter((t) => members.has(t.author_id)).sort((x, y) => (BigInt(y.id) > BigInt(x.id) ? 1 : -1));
+                        json(200, tweetsPayload(rows, Math.min(100, Number(url.searchParams.get('max_results') ?? 10))));
+                    });
+                }
+                const owned = url.pathname.match(/^\/2\/users\/(\d+)\/owned_lists$/);
+                if (req.method === 'GET' && owned)
+                    return limited('owned-lists', 15, () => json(200, { data: lists.filter((l) => l.owner_id === owned[1]).map((l) => ({ id: l.id, name: l.name, member_count: l.member_ids.length })), meta: { result_count: lists.filter((l) => l.owner_id === owned[1]).length } }));
+                const members = url.pathname.match(/^\/2\/lists\/(\d+)\/members$/);
+                if (req.method === 'GET' && members)
+                    return limited('list-members', 900, () => {
+                        const l = lists.find((x) => x.id === members[1]);
+                        if (!l)
+                            return json(404, { errors: [{ detail: 'Could not find list' }] });
+                        json(200, { data: l.member_ids.map((id) => users.get(id)).filter((u) => !!u).map(userObj), meta: { result_count: l.member_ids.length } });
+                    });
+                json(404, { title: 'Not Found', status: 404 });
+            });
+        });
+        server.listen(0, '127.0.0.1', () => {
+            const addr = server.address();
+            const port = typeof addr === 'object' && addr ? addr.port : 0;
+            const base = `http://127.0.0.1:${port}`;
+            resolve({
+                url: base, port, state, opts,
+                endpoints: { authorize: `${base}/i/oauth2/authorize`, token: `${base}/2/oauth2/token`, revoke: `${base}/2/oauth2/revoke`, api: base },
+                close: () => new Promise((r) => { server.closeAllConnections?.(); server.close(() => r()); }),
+            });
+        });
+    });
+}
+/**
+ * A browser stand-in: GET the authorize URL and follow the mock's 302 to the app's loopback callback.
+ * Uses node:http (not fetch) so test files that block `globalThis.fetch` can still drive the flow.
+ */
+export async function mockBrowser(authorizeUrl) {
+    const { request } = await import('node:http');
+    const get = (u) => new Promise((resolve, reject) => {
+        const r = request(u, { method: 'GET' }, (res) => { res.resume(); res.on('end', () => resolve({ status: res.statusCode ?? 0, location: typeof res.headers.location === 'string' ? res.headers.location : null })); });
+        r.on('error', reject);
+        r.end();
+    });
+    const first = await get(authorizeUrl);
+    if (first.status === 302 && first.location)
+        await get(first.location);
+}

package/dist/packages/data/src/x/oauth.js

@@ -0,0 +1,242 @@
+// @dexterm/data — Login with X: OAuth 2.0 Authorization Code + PKCE on a loopback callback (task-1357).
+//
+//   login():   pkce + state → one-shot listener on http://127.0.0.1:41287/callback (binds 127.0.0.1 only, checks
+//              Host, ignores wrong-state hits, 404s everything else) → opens the authorize URL in the user's
+//              browser through a mode-0600 launcher file (never `open <url>` on argv) → exchanges the code at once
+//              (X's code expires in 30 s) → stores the record → `/2/users/me` for the handle.
+//   refresh(): grant_type=refresh_token (public client: client_id, no secret); the whole record is rewritten
+//              because X may rotate the refresh token.
+//   revoke():  POST /2/oauth2/revoke for both tokens, then the file is deleted even if X answered an error
+//              (the user can also revoke at x.com/settings/connected_apps).
+//
+// Nothing here logs a token. Errors carry redacted text only. No `.write` / `dm.*` scope can be requested.
+import { createServer } from 'node:http';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { X_CALLBACK_PATH, X_CALLBACK_PORT, X_FORBIDDEN_SCOPE_RE, X_LIVE_ENDPOINTS, X_SCOPES, callbackUri, redactXSecrets } from "./config.js";
+import { oauthState, pkce, safeEqual } from "./pkce.js";
+import { XTokenStore } from "./token-store.js";
+import { formBody, nodeXTransport } from "./transport.js";
+const LOOPBACK = new Set(['127.0.0.1', '::ffff:127.0.0.1', '::1']);
+export class XAuthError extends Error {
+    kind;
+    constructor(kind, message) {
+        super(redactXSecrets(message));
+        this.name = 'XAuthError';
+        this.kind = kind;
+    }
+}
+/** The one-shot callback listener. Resolves with the code; everything else is ignored or 404. */
+export function waitForCallback(opts) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let server;
+        // closeAllConnections: a keep-alive socket from this login must never be reused by the browser for the
+        // NEXT login's redirect (it would land on this dead listener and be ignored as a state mismatch).
+        const finish = (fn) => { if (settled)
+            return; settled = true; clearTimeout(timer); try {
+            server.close();
+            server.closeAllConnections?.();
+        }
+        catch { /* ignore */ } fn(); };
+        const host = `127.0.0.1:${opts.port}`;
+        server = createServer((req, res) => {
+            const remote = req.socket.remoteAddress ?? '';
+            if (!LOOPBACK.has(remote) || req.headers.host !== host) {
+                res.writeHead(404);
+                res.end();
+                return;
+            }
+            const url = new URL(req.url ?? '/', `http://${host}`);
+            if (req.method !== 'GET' || url.pathname !== X_CALLBACK_PATH) {
+                res.writeHead(404);
+                res.end();
+                return;
+            }
+            const st = url.searchParams.get('state') ?? '';
+            const code = url.searchParams.get('code') ?? '';
+            const err = url.searchParams.get('error');
+            res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', 'referrer-policy': 'no-referrer', connection: 'close', 'content-security-policy': "default-src 'none'; style-src 'unsafe-inline'" });
+            if (!safeEqual(st, opts.state)) {
+                res.end(page('✗ state mismatch — this response was not for this login. Close the tab.'));
+                return;
+            } // not consumed; keep waiting
+            if (err) {
+                res.end(page(`✗ X returned: ${esc(err)}. Close the tab.`));
+                finish(() => reject(new XAuthError('denied', `authorization denied: ${err}`)));
+                return;
+            }
+            if (!code) {
+                res.end(page('✗ no code in the redirect. Close the tab.'));
+                return;
+            }
+            res.end(page('✓ dexterm is linked to your X account. You can close this tab.'));
+            finish(() => resolve({ code }));
+        });
+        server.headersTimeout = 5000;
+        server.requestTimeout = 10_000;
+        server.on('error', (e) => finish(() => reject(e.code === 'EADDRINUSE' ? new XAuthError('port-busy', `port ${opts.port} is busy (another login in progress, or another process squats it): retry in a moment`) : e)));
+        const timer = setTimeout(() => finish(() => reject(new XAuthError('timeout', `login timed out after ${Math.round(opts.timeoutMs / 1000)} s (no callback from the browser)`))), opts.timeoutMs);
+        timer.unref?.();
+        server.listen(opts.port, '127.0.0.1', () => opts.onListening?.());
+    });
+}
+function esc(s) { return String(s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c])); }
+function page(msg) { return `<!doctype html><meta charset="utf-8"><title>dexterm · X</title><body style="font:15px system-ui;background:#07090d;color:#d7dbe0;padding:2rem"><p>${msg}</p>`; }
+/** Default opener: a mode-0600 redirect page handed to `open`/`xdg-open` so the URL never sits on an argv. */
+export function defaultBrowserOpener(url) {
+    let dir = null;
+    try {
+        dir = mkdtempSync(join(tmpdir(), 'dexterm-x-'));
+        writeFileSync(join(dir, 'open.html'), `<!doctype html><meta charset="utf-8"><meta http-equiv="refresh" content="0;url=${esc(url)}">`, { mode: 0o600 });
+    }
+    catch {
+        dir = null;
+    }
+    const child = spawn(process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open', process.platform === 'win32' ? ['/c', 'start', '', dir ? join(dir, 'open.html') : url] : [dir ? join(dir, 'open.html') : url], { stdio: 'ignore', detached: true });
+    child.on('error', () => { });
+    child.unref();
+    if (dir) {
+        const d = dir;
+        const t = setTimeout(() => { try {
+            rmSync(d, { recursive: true, force: true });
+        }
+        catch { /* ignore */ } }, 20_000);
+        t.unref?.();
+    }
+}
+export class XOAuth {
+    store;
+    endpoints;
+    port;
+    transport;
+    open;
+    now;
+    loginTimeoutMs;
+    /** The authorize URL of the login in progress (the CLI prints it when the browser could not be opened). */
+    lastAuthorizeUrl = null;
+    constructor(opts) {
+        this.store = opts.store;
+        this.endpoints = opts.endpoints ?? X_LIVE_ENDPOINTS;
+        this.port = opts.port ?? X_CALLBACK_PORT;
+        this.transport = opts.transport ?? nodeXTransport();
+        this.open = opts.open ?? defaultBrowserOpener;
+        this.now = opts.now ?? (() => Date.now());
+        this.loginTimeoutMs = opts.loginTimeoutMs ?? 180_000;
+    }
+    get redirectUri() { return callbackUri(this.port); }
+    /** Build the authorize URL (public values only: client id, challenge, state). */
+    authorizeUrl(clientId, challenge, state, scopes = X_SCOPES) {
+        for (const s of scopes)
+            if (X_FORBIDDEN_SCOPE_RE.test(s))
+                throw new XAuthError('scope', `scope ${s} is never requested by dexterm`);
+        const url = new URL(this.endpoints.authorize);
+        url.search = new URLSearchParams({ response_type: 'code', client_id: clientId, redirect_uri: this.redirectUri, scope: scopes.join(' '), state, code_challenge: challenge, code_challenge_method: 'S256' }).toString();
+        return url.toString();
+    }
+    async tokenRequest(form) {
+        const res = await this.transport({ method: 'POST', url: this.endpoints.token, headers: { 'content-type': 'application/x-www-form-urlencoded' }, body: formBody(form) });
+        let j = null;
+        try {
+            j = JSON.parse(res.body);
+        }
+        catch {
+            j = null;
+        }
+        if (res.status < 200 || res.status >= 300) {
+            throw new Error(`token endpoint ${res.status}: ${String(j?.error ?? '')} ${String(j?.error_description ?? '')}`.trim());
+        }
+        if (!j || typeof j.access_token !== 'string')
+            throw new Error('token endpoint answered without an access_token');
+        return j;
+    }
+    /** Run the whole login. Requires a stored client id. */
+    async login(opts = {}) {
+        const clientId = this.store.clientId(opts.env ?? process.env);
+        if (!clientId)
+            throw new XAuthError('no-client-id', 'no X app Client ID stored: run `dexterm x set-client-id` first (see docs: Login with X)');
+        const { verifier, challenge } = pkce();
+        const state = oauthState();
+        const scopes = opts.scopes ?? X_SCOPES;
+        const url = this.authorizeUrl(clientId, challenge, state, scopes);
+        this.lastAuthorizeUrl = url;
+        const t0 = this.now();
+        const pending = waitForCallback({ state, port: this.port, timeoutMs: this.loginTimeoutMs, onListening: () => this.open(url) });
+        const { code } = await pending;
+        const tCallback = this.now();
+        let j;
+        try {
+            j = await this.tokenRequest({ code, grant_type: 'authorization_code', client_id: clientId, redirect_uri: this.redirectUri, code_verifier: verifier });
+        }
+        catch (e) {
+            throw new XAuthError('exchange', `code exchange failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        const rec = this.store.setTokens(j, null);
+        const user = await this.fetchMe(rec).catch(() => null);
+        if (user)
+            this.store.setUser(user);
+        return { user, scopes: rec.scope.split(/\s+/).filter(Boolean), expiresAt: rec.expires_at, hasRefresh: !!rec.refresh_token, callbackMs: tCallback - t0, exchangeMs: this.now() - tCallback };
+    }
+    /** Rotate the access token. Throws XAuthError('refresh') and clears nothing on failure (the caller decides). */
+    async refresh(env = process.env) {
+        const clientId = this.store.clientId(env);
+        const t = this.store.tokens();
+        if (!clientId || !t)
+            throw new XAuthError('not-logged-in', 'not logged in');
+        if (!t.refresh_token)
+            throw new XAuthError('refresh', 'no refresh token (login again with offline.access)');
+        let j;
+        try {
+            j = await this.tokenRequest({ grant_type: 'refresh_token', refresh_token: t.refresh_token, client_id: clientId });
+        }
+        catch (e) {
+            throw new XAuthError('refresh', `refresh failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        return this.store.setTokens(j, t.user);
+    }
+    /** A valid bearer, refreshing when within `skewMs` of expiry. Never logged by callers. */
+    async bearer(env = process.env, skewMs = 60_000) {
+        let t = this.store.tokens();
+        if (!t)
+            throw new XAuthError('not-logged-in', 'not logged in');
+        if (t.expires_at <= this.now() + skewMs)
+            t = await this.refresh(env);
+        return t.access_token;
+    }
+    /** Revoke both tokens at X (best effort) and delete the local record. Returns the HTTP statuses seen. */
+    async logout(env = process.env) {
+        const clientId = this.store.clientId(env);
+        const t = this.store.tokens();
+        const revoked = {};
+        if (t && clientId) {
+            for (const [k, v] of [['access_token', t.access_token], ['refresh_token', t.refresh_token]]) {
+                if (!v)
+                    continue;
+                try {
+                    const res = await this.transport({ method: 'POST', url: this.endpoints.revoke, headers: { 'content-type': 'application/x-www-form-urlencoded' }, body: formBody({ token: v, client_id: clientId, token_type_hint: k }) });
+                    revoked[k] = res.status;
+                }
+                catch {
+                    revoked[k] = 0;
+                }
+            }
+        }
+        const hadTokens = this.store.clearTokens();
+        return { revoked, hadTokens };
+    }
+    /** GET /2/users/me with a given record (login uses it before the adapter exists). */
+    async fetchMe(rec) {
+        const res = await this.transport({ method: 'GET', url: `${this.endpoints.api}/2/users/me`, headers: { authorization: `Bearer ${rec.access_token}` } });
+        if (res.status !== 200)
+            return null;
+        try {
+            const j = JSON.parse(res.body);
+            return j.data && typeof j.data.id === 'string' && typeof j.data.username === 'string' ? { id: j.data.id, username: j.data.username } : null;
+        }
+        catch {
+            return null;
+        }
+    }
+}

package/dist/packages/data/src/x/pkce.js

@@ -0,0 +1,21 @@
+// @dexterm/data — PKCE (RFC 7636, S256) + opaque state for the Login with X flow (task-1357).
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+const b64url = (b) => b.toString('base64url');
+/** 64-char verifier (48 random bytes) and its S256 challenge (43 chars). */
+export function pkce(rand = randomBytes) {
+    const verifier = b64url(rand(48));
+    return { verifier, challenge: b64url(createHash('sha256').update(verifier).digest()), method: 'S256' };
+}
+/** 32-char opaque state (24 random bytes). */
+export function oauthState(rand = randomBytes) {
+    return b64url(rand(24));
+}
+/** Constant-time string equality (length leak is fine: the lengths are public). */
+export function safeEqual(a, b) {
+    const x = Buffer.from(a), y = Buffer.from(b);
+    return x.length === y.length && timingSafeEqual(x, y);
+}
+/** What the mock server (and any PKCE verifier) checks: S256(verifier) === challenge. */
+export function pkceMatches(verifier, challenge) {
+    return safeEqual(b64url(createHash('sha256').update(verifier).digest()), challenge);
+}