@volter/twin-xidentity 0.1.0

package/dist/src/xidentity-conformance.d.ts

@@ -0,0 +1,10 @@
+export type XIdentityConformanceReport = {
+    ok: boolean;
+    endpointsChecked: number;
+    endpointsProbed: number;
+    resourceTypesChecked: number;
+    violations: string[];
+};
+export declare function checkXIdentityConformance(opts?: {
+    root?: string;
+}): Promise<XIdentityConformanceReport>;

package/dist/src/xidentity-conformance.js

@@ -0,0 +1,332 @@
+// X identity conformance (dev-only; lazy-imported by the CLI, NEVER from index.ts/runtime — E2).
+//
+// ── THIS CHECK DRIVES THE ROUTER AND ASSERTS WHAT CAME BACK ─────────────────────────────────────
+// Held to ADDING_A_TWIN.md §6's bar, and to the two escalating false-greens the tinybird reviews
+// found there:
+//   • two constants asserting about each other is not a check — every expectation below is a
+//     LITERAL, never a value read back out of the handler's own module;
+//   • "not the router's own miss" has teeth at the dispatch and nowhere deeper — each probe
+//     declares the STATUS SET and a PREDICATE over the body a live handler produces, the endpoint
+//     census is a two-way bijection with the snapshot, and a hand-enumerated ROUTER_SURFACE
+//     catches served-but-unclaimed surface (the direction probes⇄snapshot is blind to).
+//
+// And the whole point of this pack — the ROUND TRIP — is checked as a round trip: a real
+// 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 { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { pkceS256 } from "./xidentity-pkce.js";
+import { DEFAULT_ACCOUNTS, DEFAULT_CLIENT_ID, DEFAULT_CLIENT_SECRET, DEFAULT_PUBLIC_CLIENT_ID, defaultRedirectUris } from "./xidentity-store.js";
+import { handleXIdentityTwinRequest, xIdentityTwinSnapshot } from "./xidentity-twin.js";
+const isObject = (b) => !!b && typeof b === 'object';
+const htmlContaining = (...needles) => (b) => typeof b === 'string' && needles.every((n) => b.includes(n));
+/** The origin this harness's world serves the twin at. The seeded demo clients' callbacks are
+ *  DERIVED from it (runtime contract R7: the port belongs to the caller's world, never to the
+ *  twin's source), so the probes below name no port of their own. */
+const DEMO_ORIGIN = 'http://localhost:3000';
+const REDIRECT_URIS = defaultRedirectUris(DEMO_ORIGIN);
+const REDIRECT_URI = REDIRECT_URIS[0];
+const SCOPE = 'tweet.read users.read offline.access';
+const AT = '2026-02-01T00:00:00.000Z';
+const VERIFIER = 'probe-verifier-0123456789-0123456789-0123456789';
+const ADA = DEFAULT_ACCOUNTS[0];
+/** Placeholders substituted with values the live flow actually minted. */
+const CODE = 'PROBE_CODE';
+const ACCESS = 'PROBE_ACCESS_TOKEN';
+const REFRESH = 'PROBE_REFRESH_TOKEN';
+const authQuery = `response_type=code&client_id=${encodeURIComponent(DEFAULT_CLIENT_ID)}`
+    + `&redirect_uri=${encodeURIComponent(REDIRECT_URI)}&scope=${encodeURIComponent(SCOPE)}`
+    + `&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')}`;
+/** A representative request per declared endpoint, with the outcome a LIVE handler produces. */
+const PROBES = {
+    'GET /i/oauth2/authorize': {
+        method: 'GET',
+        path: `/i/oauth2/authorize?${authQuery}`,
+        status: [200],
+        // The authorize surface is HTML, and its content is the claim: the app name from the client
+        // registry, the signed-in persona, both buttons, and a scope's consent wording — X's own,
+        // from the OpenAPI scope catalog — must all be ON the page.
+        expect: htmlContaining('Authorize app', 'Cancel', 'Twin Demo App', `@${ADA.username}`, 'View all posts you can see'),
+    },
+    'POST /2/oauth2/token': {
+        method: 'POST',
+        path: '/2/oauth2/token',
+        body: form({ grant_type: 'authorization_code', code: CODE, client_id: DEFAULT_CLIENT_ID, redirect_uri: REDIRECT_URI, code_verifier: VERIFIER }),
+        headers: { authorization: basic },
+        status: [200],
+        // Literals, deliberately (the token shape both official SDKs type): lowercase bearer, the
+        // documented 2-hour expiry, an X-shaped base64url token, and a refresh_token because the
+        // grant carries offline.access.
+        expect: (b) => isObject(b)
+            && b.token_type === 'bearer'
+            && b.expires_in === 7200
+            && typeof b.access_token === 'string'
+            && Buffer.from(String(b.access_token), 'base64url').toString('utf8').includes(':at:')
+            && b.scope === SCOPE
+            && typeof b.refresh_token === 'string'
+            && Buffer.from(String(b.refresh_token), 'base64url').toString('utf8').includes(':rt:'),
+    },
+    'POST /2/oauth2/revoke': {
+        method: 'POST',
+        path: '/2/oauth2/revoke',
+        body: form({ token: ACCESS, client_id: DEFAULT_CLIENT_ID, token_type_hint: 'access_token' }),
+        headers: { authorization: basic },
+        status: [200],
+        expect: (b) => isObject(b) && b.revoked === true && Object.keys(b).length === 1,
+    },
+    'GET /2/users/me': {
+        method: 'GET',
+        path: '/2/users/me',
+        headers: { authorization: `Bearer ${ACCESS}` },
+        status: [200],
+        expect: (b) => isObject(b)
+            && isObject(b.data)
+            && b.data['id'] === ADA.id
+            && b.data['username'] === ADA.username
+            && b.data['name'] === ADA.name,
+    },
+};
+/**
+ * Every VENDOR method/path pair a reader of `routeXIdentityTwinRequest` can see the router branch
+ * on, PLUS near-miss pairs (wrong method on a claimed path, the OpenAPI's alternate authorize
+ * host path, a sibling /2 users route) that must answer the vendor-shaped not-found envelope.
+ * Written by hand from the router, so the census can catch VENDOR surface that is served without
+ * being claimed. The `/_twin/*` control routes `twinControl` dispatches are DELIBERATELY outside
+ * this census: they are twin-only scaffolding (ADDING_A_TWIN.md §6), answer non-404 by design,
+ * and are never claimable — so this check is blind to them BY CONSTRUCTION, and a §9 reader must
+ * compare `twinControl`'s branches against the scaffolding list in the README instead.
+ */
+const ROUTER_SURFACE = [
+    ['GET', `/i/oauth2/authorize?${authQuery}`],
+    ['POST', '/i/oauth2/authorize'],
+    ['POST', '/2/oauth2/token'],
+    ['GET', '/2/oauth2/token'],
+    ['POST', '/2/oauth2/revoke'],
+    ['GET', '/2/oauth2/revoke'],
+    ['GET', '/2/users/me'],
+    ['POST', '/2/users/me'],
+    ['GET', '/2/oauth2/authorize'],
+    ['GET', '/2/users/by'],
+    ['GET', '/oauth2/token'],
+];
+const isNotFoundEnvelope = (res) => res.status === 404
+    && isObject(res.body)
+    && res.body['title'] === 'Not Found Error'
+    && res.body['type'] === 'about:blank';
+export async function checkXIdentityConformance(opts = {}) {
+    void opts;
+    const snapshot = xIdentityTwinSnapshot();
+    const violations = [];
+    // Always a THROWAWAY root, even when a caller passes one: the check mints and then REVOKES
+    // credentials, and doing that in an operator's world would log them out of their own twin.
+    const root = mkdtempSync(join(tmpdir(), 'xidentity-conformance-'));
+    const call = (method, path, body, headers) => handleXIdentityTwinRequest({ method, path, ...(body !== undefined ? { body } : {}), ...(headers ? { headers } : {}), root, origin: DEMO_ORIGIN, occurredAt: AT });
+    /** Drive a full consent and return the minted code (empty string on any failure). */
+    const mintCode = async (scope = SCOPE) => {
+        const q = authQuery.replace(`scope=${encodeURIComponent(SCOPE)}`, `scope=${encodeURIComponent(scope)}`);
+        const a = await call('GET', `/i/oauth2/authorize?${q}`);
+        const rid = /name="auth_request" value="([^"]+)"/.exec(String(a.body))?.[1] ?? '';
+        const d = await call('POST', '/_twin/consent', form({ auth_request: rid, decision: 'allow' }));
+        return new URL(d.headers?.location ?? 'http://invalid.test/').searchParams.get('code') ?? '';
+    };
+    const redeem = (code) => call('POST', '/2/oauth2/token', form({ grant_type: 'authorization_code', code, client_id: DEFAULT_CLIENT_ID, redirect_uri: REDIRECT_URI, code_verifier: VERIFIER }), { authorization: basic });
+    let probed = 0;
+    try {
+        // ── the ROUND TRIP, driven for real, before any probing ──
+        const authRes = await call('GET', `/i/oauth2/authorize?${authQuery}`);
+        const requestId = /name="auth_request" value="([^"]+)"/.exec(String(authRes.body))?.[1] ?? '';
+        if (!requestId)
+            violations.push('the authorize endpoint did not render a consent form carrying an auth_request handle');
+        const decision = await call('POST', '/_twin/consent', form({ auth_request: requestId, decision: 'allow' }));
+        const location = decision.headers?.location ?? '';
+        if (decision.status !== 302 || !location.startsWith(REDIRECT_URI)) {
+            violations.push(`consent did not 302 back to the registered redirect_uri: ${decision.status} ${location}`);
+        }
+        const back = new URL(location || 'http://invalid.test/');
+        const code = back.searchParams.get('code') ?? '';
+        if (back.searchParams.get('state') !== 'probe-state') {
+            violations.push(`the redirect did not echo the caller's state verbatim: ${back.searchParams.get('state')}`);
+        }
+        if (!Buffer.from(code, 'base64url').toString('utf8').includes(':ac:')) {
+            violations.push(`the redirect did not carry an X-shaped authorization code: ${code}`);
+        }
+        const extras = [...back.searchParams.keys()].filter((k) => k !== 'state' && k !== 'code');
+        if (extras.length > 0) {
+            // The documented callback carries EXACTLY state and code; an invented parameter is surface
+            // an integration could come to depend on and then break against the real vendor.
+            violations.push(`the success redirect carries parameters X's documented callback does not: ${extras.join(', ')}`);
+        }
+        const tokenRes = await redeem(code);
+        const tokens = tokenRes.body;
+        if (tokenRes.status !== 200 || typeof tokens?.access_token !== 'string') {
+            violations.push(`the minted code was not redeemable at the token endpoint: ${tokenRes.status} ${JSON.stringify(tokenRes.body).slice(0, 160)}`);
+        }
+        // …and the token is USABLE: it answers /2/users/me with the consenting persona and the
+        // documented rate headers.
+        const me = await call('GET', '/2/users/me', undefined, { authorization: `Bearer ${tokens?.access_token}` });
+        const meBody = me.body;
+        if (me.status !== 200 || meBody?.data?.id !== ADA.id || meBody?.data?.username !== ADA.username) {
+            violations.push(`the minted token did not answer /2/users/me with the consenting persona: ${me.status} ${JSON.stringify(me.body).slice(0, 160)}`);
+        }
+        if (me.headers?.['x-rate-limit-limit'] !== '75' || typeof me.headers?.['x-rate-limit-remaining'] !== 'string' || typeof me.headers?.['x-rate-limit-reset'] !== 'string') {
+            violations.push(`/2/users/me did not carry the documented x-rate-limit-* headers: ${JSON.stringify(me.headers)}`);
+        }
+        // A redeemed code must be DEAD. This is the security property, so it is checked here and not
+        // only in the manifest.
+        const replay = await redeem(code);
+        if (replay.status !== 400 || replay.body?.['error'] !== 'invalid_request') {
+            violations.push(`a replayed authorization code was not refused: ${replay.status} ${JSON.stringify(replay.body).slice(0, 120)}`);
+        }
+        // The refresh token ROTATES: the replacement works, the spent one is refused.
+        const refresh1 = await call('POST', '/2/oauth2/token', form({ grant_type: 'refresh_token', refresh_token: String(tokens?.refresh_token), client_id: DEFAULT_CLIENT_ID }), { authorization: basic });
+        const refreshed = refresh1.body;
+        if (refresh1.status !== 200 || typeof refreshed?.refresh_token !== 'string' || refreshed.refresh_token === tokens?.refresh_token) {
+            violations.push(`the refresh grant did not rotate the refresh token: ${refresh1.status} ${JSON.stringify(refresh1.body).slice(0, 120)}`);
+        }
+        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 endpoint census, THREE ways ──
+        const claimed = new Set(snapshot.implementedEndpoints);
+        for (const key of Object.keys(PROBES)) {
+            if (!claimed.has(key))
+                violations.push(`probe '${key}' does not correspond to any claimed endpoint — the probe table has drifted`);
+        }
+        for (const [method, probePath] of ROUTER_SURFACE) {
+            const res = await call(method, probePath);
+            const key = `${method} ${probePath.split('?')[0]}`;
+            if (!isNotFoundEnvelope(res) && !claimed.has(key)) {
+                violations.push(`the router answers '${key}' (${res.status}) but the snapshot does not claim it — served surface outside the census is deletable without this check noticing`);
+            }
+        }
+        // Fixtures per destructive probe, so probe ORDER cannot make this check lie: the revoke probe
+        // kills a WHOLE (client, user) grant family, which would take the users/me probe's token with
+        // it if the two fixtures shared a user. The revoke fixture is therefore minted under the
+        // SECOND persona's session (switched and restored via the twin-only session control).
+        const probeTokens = async () => (await redeem(await mintCode())).body;
+        await call('POST', '/_twin/session', JSON.stringify({ account_id: DEFAULT_ACCOUNTS[1].id }));
+        const revokeFixture = await probeTokens();
+        await call('POST', '/_twin/session', JSON.stringify({ account_id: ADA.id }));
+        const meFixture = await probeTokens();
+        const tokenProbeCode = await mintCode();
+        const substitute = (s) => s.replace(CODE, tokenProbeCode)
+            .replace(ACCESS, String(meFixture?.access_token ?? ''))
+            .replace(REFRESH, String(meFixture?.refresh_token ?? ''));
+        for (const endpoint of snapshot.implementedEndpoints) {
+            const probe = PROBES[endpoint];
+            if (!probe) {
+                violations.push(`endpoint '${endpoint}' is claimed but has no conformance probe — the claim is unverified`);
+                continue;
+            }
+            const [claimedMethod, claimedPath] = endpoint.split(' ');
+            if (probe.method !== claimedMethod) {
+                violations.push(`probe '${endpoint}' drives ${probe.method}, not ${claimedMethod}`);
+                continue;
+            }
+            if ((probe.path.split('?')[0] ?? '') !== claimedPath) {
+                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'
+                ? 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 res = await call(probe.method, path, body, headers);
+            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)}`);
+                continue;
+            }
+            if (probe.expect && !probe.expect(res.body)) {
+                violations.push(`endpoint '${endpoint}' answered ${res.status} but the body is not the shape this route returns: ${JSON.stringify(res.body).slice(0, 200)}`);
+            }
+        }
+        // Every grant type the snapshot claims must actually dispatch — an unsupported one answers
+        // `unsupported_grant_type`, so a claimed-but-missing grant is caught by name.
+        for (const grantType of snapshot.grantTypes) {
+            const res = await call('POST', '/2/oauth2/token', form({ grant_type: grantType, client_id: DEFAULT_PUBLIC_CLIENT_ID }));
+            const err = res.body?.['error'];
+            if (err === 'unsupported_grant_type')
+                violations.push(`grant type '${grantType}' is claimed but the token endpoint does not dispatch it`);
+        }
+        // Every resource type the twin projects must be reachable through the protocol — a type with
+        // no observable effect is state a consumer can never see. Each witness reads a VALUE only a
+        // live handler that genuinely projects that type can produce (never a bare status, and never
+        // the snapshot asserting about itself).
+        const witness = {
+            // the app's registered NAME is only on the screen if the oauth_client row projected
+            oauth_client: async () => String((await call('GET', `/i/oauth2/authorize?${authQuery}`)).body).includes('Twin Demo App'),
+            // the persona's username comes back only if the account row projected
+            account: async () => {
+                const t = await probeTokens();
+                const r = await call('GET', '/2/users/me', undefined, { authorization: `Bearer ${t?.access_token}` });
+                return r.status === 200 && r.body?.data?.username === ADA.username;
+            },
+            // switching the session changes WHO the authorize screen consents as
+            session: async () => {
+                const grace = DEFAULT_ACCOUNTS[1];
+                await call('POST', '/_twin/session', JSON.stringify({ account_id: grace.id }));
+                const shows = String((await call('GET', `/i/oauth2/authorize?${authQuery}`)).body).includes(`@${grace.username}`);
+                await call('POST', '/_twin/session', JSON.stringify({ account_id: ADA.id }));
+                return shows;
+            },
+            // an auth_request that did not project could not have carried a settleable handle
+            auth_request: async () => /name="auth_request" value="ar_[0-9a-f]{32}"/.test(String((await call('GET', `/i/oauth2/authorize?${authQuery}`)).body)),
+            // a code that did not project could not be REDEEMED — the witness is the SUCCESS, because
+            // the refusal is exactly what a twin projecting nothing would also say
+            authorization_code: async () => {
+                const r = await redeem(await mintCode());
+                return r.status === 200 && typeof r.body?.['access_token'] === 'string';
+            },
+            access_token: async () => {
+                const t = await probeTokens();
+                return (await call('GET', '/2/users/me', undefined, { authorization: `Bearer ${t?.access_token}` })).status === 200;
+            },
+            refresh_token: async () => {
+                const t = await probeTokens();
+                return (await call('POST', '/2/oauth2/token', form({ grant_type: 'refresh_token', refresh_token: String(t?.refresh_token), client_id: DEFAULT_CLIENT_ID }), { authorization: basic })).status === 200;
+            },
+            // the grant row is what revocation resolves: revoking the ACCESS half must kill the
+            // REFRESH half too, and only a projected grant makes that pair-wide sweep possible
+            grant: async () => {
+                const t = await probeTokens();
+                await call('POST', '/2/oauth2/revoke', form({ token: String(t?.access_token), client_id: DEFAULT_CLIENT_ID }), { authorization: basic });
+                const r = await call('POST', '/2/oauth2/token', form({ grant_type: 'refresh_token', refresh_token: String(t?.refresh_token), client_id: DEFAULT_CLIENT_ID }), { authorization: basic });
+                return r.status === 400;
+            },
+            // an armed rate window turns the NEXT read into the documented 429 + code 88
+            rate_window: async () => {
+                const t = await probeTokens();
+                await call('POST', '/_twin/rate_limit', JSON.stringify({ account_id: ADA.id, used: 75 }));
+                const r = await call('GET', '/2/users/me', undefined, { authorization: `Bearer ${t?.access_token}` });
+                await call('POST', '/_twin/rate_limit', JSON.stringify({ account_id: ADA.id, used: 0 }));
+                const errs = r.body?.errors;
+                return r.status === 429 && Array.isArray(errs) && errs[0]?.code === 88;
+            },
+        };
+        for (const type of snapshot.resourceTypes) {
+            const probe = witness[type];
+            if (!probe) {
+                violations.push(`resource type '${type}' has no reachability witness — the claim is unverified`);
+                continue;
+            }
+            if (!(await probe()))
+                violations.push(`resource type '${type}' is not reachable through any served endpoint`);
+        }
+    }
+    finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+    return {
+        ok: violations.length === 0,
+        endpointsChecked: snapshot.implementedEndpoints.length,
+        endpointsProbed: probed,
+        resourceTypesChecked: snapshot.resourceTypes.length,
+        violations,
+    };
+}

package/dist/src/xidentity-connector.d.ts

@@ -0,0 +1,84 @@
+import type { PerformContext, PushOutcome, RemoteExecute, TwinAction, SyncResource } from '@volter/world-core';
+import { XIdentityBudget, type XIdentityBudgetOptions } from './xidentity-budget.js';
+/** The modelled user.fields a pull requests — every field the twin's account rows can hold. */
+export declare const PULL_USER_FIELDS: readonly ["created_at", "description", "location", "profile_image_url", "protected", "public_metrics", "url", "verified", "verified_type", "confirmed_email"];
+/**
+ * The injected real-X boundary. `execute` issues ONE request and returns the parsed JSON body.
+ * A real client (a raw fetch wrapper) is structurally assignable; tests pass a fake.
+ */
+export type XIdentityExecute = (method: 'GET' | 'POST', path: string, init?: {
+    headers?: Record<string, string>;
+    body?: string;
+}) => Promise<Record<string, any>>;
+export type LiveXIdentityOptions = {
+    /** Injected `fetch`, so a test can COUNT the requests the guard did or did not let through. */
+    fetchImpl?: typeof fetch;
+    /** An existing budget to share across executors. Omit and one is constructed. Cannot be null. */
+    budget?: XIdentityBudget;
+    /** Construction options for the default budget (ledger path, clock). Cannot loosen it. */
+    budgetOptions?: XIdentityBudgetOptions;
+};
+/**
+ * A live executor against the real X API, holding the operator's OWN user access token.
+ *
+ * THIS IS THE ONE PLACE this pack issues a live X request, and therefore the one place the rate
+ * budget has to be enforced. EVERY call is guarded: the budget is charged BEFORE the request goes
+ * out (`checkBudget`, which THROWS instead of returning when the ceiling or a cooldown says stop)
+ * and the response is fed back (`recordCall`) so a 429 / `Retry-After` becomes a PERSISTED
+ * cooldown that makes every later call fail fast WITHOUT touching X. There is deliberately no
+ * option to disable the guard and no value of `budget` that yields an unguarded client
+ * (`assertBudgetGuardIntact`).
+ */
+export declare function liveXIdentityExecute(accessToken: string, opts?: LiveXIdentityOptions): XIdentityExecute;
+/** Map a real `GET /2/users/me` response → the account (persona) SyncResource. Nothing invented:
+ *  a field the response omits records NOTHING rather than a placeholder — including username and
+ *  name (§9 round one: a `?? null` there let a partial-errors reply fold null over a previously
+ *  pulled persona's real values). */
+export declare function mapUsersMeAccount(body: Record<string, any>): SyncResource;
+/** PULL the operator's own identity into the twin's observed log (idempotent). */
+export declare function pullXIdentity(execute: XIdentityExecute, root?: string, occurredAt?: string): Promise<number>;
+/**
+ * D7 consumer-facing pull entry point: pull everything readable from the real X identity surface
+ * and fold it into the twin in ONE observation, returning the standard
+ * `{ observed, deltasAppended }`. Idempotent — a re-pull of identical state appends nothing.
+ */
+export declare function syncXIdentityFromReal(execute: XIdentityExecute, opts?: {
+    root?: string;
+    occurredAt?: string;
+}): Promise<{
+    observed: number;
+    deltasAppended: number;
+}>;
+/**
+ * PUSH — structurally impossible on this vendor, and reported as such rather than faked. X has no
+ * API that creates an OAuth App, seeds a user, or grants a scope: those are developer-portal and
+ * x.com/settings actions. This never confirms an action and never pretends to have pushed one; it
+ * returns the pending count so a caller can see exactly how much local state has no upstream home.
+ */
+export declare function pushPendingXIdentityActions(root?: string): {
+    pushed: 0;
+    unpushable: number;
+};
+/** An `XIdentityExecute` over the kernel's executor. At a REAL boundary the kernel sets the sealed
+ *  credential over these headers (executor.ts); at the twin's own wire any credential is one. */
+export declare function xIdentityExecuteOver(execute: RemoteExecute): XIdentityExecute;
+/** The refresh adapter: `GET /2/users/me` is a real read of the real account, so the operator's own
+ *  identity comes back from X itself. It is also the ONLY thing this vendor lets a client read
+ *  about its own identity surface — Apps, grants and scopes are portal state, not API state. */
+export declare function syncXIdentityFromRemote(execute: RemoteExecute, opts?: {
+    root?: string;
+    origin?: string;
+    occurredAt?: string;
+}): Promise<{
+    observed: number;
+    deltasAppended: number;
+}>;
+/**
+ * The perform adapter — and its answer is always the same, honestly.
+ *
+ * X publishes NO API that creates an OAuth App, seeds a user, or grants a scope: those are
+ * developer-portal and x.com/settings actions a person takes in a browser. So nothing a world
+ * writes here has an upstream home, and saying so is the whole point — the pack's push has always
+ * reported the unpushable count rather than confirming an action it never made.
+ */
+export declare function performXIdentityAction(execute: RemoteExecute, action: TwinAction, _ctx: PerformContext): Promise<PushOutcome>;