@volter/twin-xidentity 0.1.0

package/dist/src/xidentity-connector.js

@@ -0,0 +1,239 @@
+// X identity CONNECTOR — the live-vendor pull path.
+//
+// PULL (real → twin): the twin's persona registry is only as useful as the identities in it, and
+// this surface exposes exactly ONE authenticated read: `GET /2/users/me`. A pull observes the real
+// account behind the operator's own user access token (every modelled user.field requested) and
+// folds it into the observed log.
+//
+// WHAT A PULL CANNOT OBSERVE, recorded as reasoned gaps rather than faked:
+//   • the OAuth CLIENT registry — X Apps are created in the developer portal; no API reads them
+//     (`xidentity.connector.pull_clients`, todo);
+//   • the GRANT (which scopes this token holds) — X has no tokeninfo/introspection endpoint; a
+//     users/me success evidences tweet.read+users.read but cannot enumerate the rest
+//     (`xidentity.connector.pull_grants`, todo).
+//
+// PUSH IS AN HONEST GAP, not an omission: X exposes NO write API for this identity surface —
+// clients live in the developer portal, and a user's app authorizations are managed at
+// x.com/settings. `pushPendingXIdentityActions` exists only to report that; filed as
+// `xidentity.connector.push` (todo). ADDING_A_TWIN.md §10 sanctions exactly this for a vendor
+// with no write path.
+//
+// The vendor I/O is an INJECTED executor (the auth boundary): the kernel and this pack hold NO X
+// credential and import NO network client. Offline/tests pass a fake executor; live runs pass
+// `liveXIdentityExecute(accessToken)`. Same code path either way.
+import { assertBudgetGuardIntact, deployableEntries, observeResources } from '@volter/world-core';
+import { XIdentityBudget, XIdentityBudgetError, xIdentityBudgetPath, xIdentityCallWeight } from "./xidentity-budget.js";
+const SERVICE = 'xidentity';
+/** X's real hosts — the live executor's routing table. ONLY mapped paths may be called live.
+ *  The token/revoke paths are mapped so a live BYOT rehearsal can refresh or revoke the
+ *  operator's OWN token through the guarded path — nothing else on api.x.com is reachable. */
+const HOSTS = {
+    '/2/users/me': 'https://api.x.com',
+    '/2/oauth2/token': 'https://api.x.com',
+    '/2/oauth2/revoke': 'https://api.x.com',
+};
+/** The modelled user.fields a pull requests — every field the twin's account rows can hold. */
+export const PULL_USER_FIELDS = [
+    'created_at',
+    'description',
+    'location',
+    'profile_image_url',
+    'protected',
+    'public_metrics',
+    'url',
+    'verified',
+    'verified_type',
+    'confirmed_email',
+];
+/**
+ * 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 function liveXIdentityExecute(accessToken, opts = {}) {
+    const doFetch = opts.fetchImpl ?? fetch;
+    const budget = opts.budget !== undefined && opts.budget !== null
+        ? assertBudgetGuardIntact(opts.budget, XIdentityBudget, 'liveXIdentityExecute')
+        : new XIdentityBudget({ ...(opts.budgetOptions ?? {}), token: accessToken });
+    const explicitLedger = opts.budgetOptions?.path !== undefined || opts.budgetOptions?.root !== undefined;
+    if (opts.budget && !explicitLedger && budget.path !== xIdentityBudgetPath({ token: accessToken })) {
+        throw new Error('liveXIdentityExecute: injected budget is not keyed to the credential this client will send');
+    }
+    return async (method, path, init) => {
+        const bare = path.split('?')[0] ?? path;
+        const host = HOSTS[bare];
+        if (!host)
+            throw new Error(`liveXIdentityExecute: refusing to call an unmapped X path: ${bare}`);
+        const weight = xIdentityCallWeight(method, path);
+        if (Object.keys(init?.headers ?? {}).some((name) => name.toLowerCase() === 'authorization')) {
+            throw new Error('liveXIdentityExecute: refusing an injected Authorization header; the guarded credential is fixed at construction');
+        }
+        // THROWS instead of calling. Nothing below this line runs when the budget refuses.
+        const reservation = budget.checkBudget(weight);
+        const res = await doFetch(`${host}${path}`, {
+            method,
+            headers: { ...(init?.headers ?? {}), Authorization: `Bearer ${accessToken}` },
+            ...(init?.body !== undefined ? { body: init.body } : {}),
+        });
+        const resHeaders = {};
+        res.headers.forEach((v, k) => {
+            resHeaders[k.toLowerCase()] = v;
+        });
+        // Settles the reservation and, on a back-off signal, arms the cooldown. The cooldown is
+        // persisted before body parsing or any throw, so even an HTML/plain-text 429 survives it.
+        // recordCall may THROW after arming the cooldown (a back-off beyond the cap). On a refused
+        // call that louder refusal wins; an answer X ACCEPTED is kept, so a write that landed is
+        // never recorded as failed and performed again on retry.
+        try {
+            budget.recordCall(weight, resHeaders, { status: res.status, reservation });
+        }
+        catch (error) {
+            if (!(error instanceof XIdentityBudgetError) || !res.ok)
+                throw error;
+        }
+        const raw = await res.text();
+        let parsed;
+        try {
+            parsed = raw === '' ? {} : JSON.parse(raw);
+        }
+        catch {
+            throw new Error(`x identity returned non-JSON for ${method} ${bare}: HTTP ${res.status}`);
+        }
+        // A REFUSED pull is NOT an empty account. X can answer failures with a problem envelope
+        // (`title`/`type`), a legacy `errors` array, OR a 200 whose body carries partial `errors` —
+        // a status check alone cannot tell refusal from emptiness, so every refusal shape throws.
+        if (res.status >= 400)
+            throw new Error(`x identity refused ${method} ${bare}: HTTP ${res.status} ${JSON.stringify(parsed)}`);
+        if (parsed && typeof parsed === 'object' && !('data' in parsed) && ('errors' in parsed || 'title' in parsed)) {
+            throw new Error(`x identity refused ${method} ${bare}: ${JSON.stringify(parsed)}`);
+        }
+        return parsed;
+    };
+}
+/** 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 function mapUsersMeAccount(body) {
+    const data = (body?.data ?? {});
+    return {
+        type: 'account',
+        id: String(data.id ?? ''),
+        fields: {
+            ...(typeof data.username === 'string' ? { username: data.username } : {}),
+            ...(typeof data.name === 'string' ? { name: data.name } : {}),
+            ...(typeof data.created_at === 'string' ? { createdAt: data.created_at } : {}),
+            ...(typeof data.description === 'string' ? { description: data.description } : {}),
+            ...(typeof data.location === 'string' ? { location: data.location } : {}),
+            ...(typeof data.profile_image_url === 'string' ? { profileImageUrl: data.profile_image_url } : {}),
+            ...(typeof data.protected === 'boolean' ? { protectedAccount: data.protected } : {}),
+            ...(data.public_metrics && typeof data.public_metrics === 'object' ? { publicMetrics: data.public_metrics } : {}),
+            ...(typeof data.url === 'string' ? { url: data.url } : {}),
+            ...(typeof data.verified === 'boolean' ? { verified: data.verified } : {}),
+            ...(typeof data.verified_type === 'string' ? { verifiedType: data.verified_type } : {}),
+            ...(typeof data.confirmed_email === 'string' ? { confirmedEmail: data.confirmed_email } : {}),
+            pulled: true,
+        },
+    };
+}
+/**
+ * A MOVING pull timestamp, forced strictly increasing within the process — never a pinned
+ * constant (ADDING_A_TWIN.md §6: under a fixed poll time a vendor value that REVERTS across polls
+ * collides with its own earlier observation and the delta silently vanishes).
+ */
+let lastPollMs = 0;
+function pollTimestamp() {
+    const now = Date.now();
+    lastPollMs = now > lastPollMs ? now : lastPollMs + 1;
+    return new Date(lastPollMs).toISOString();
+}
+async function collectXIdentity(execute) {
+    const body = await execute('GET', `/2/users/me?user.fields=${PULL_USER_FIELDS.join(',')}`);
+    // The refusal check lives HERE, not only in the live executor: an injected executor (or a
+    // vendor 200 carrying a problem envelope) must never fold an empty account over observed state.
+    // A reply without `data`, or whose id is not an X-shaped NUMERIC string, is a refusal or a
+    // malformed body, and either one THROWS. The numeric check also keeps a foreign id out of the
+    // `clientId:sub` grant-key space (§9 round two: the scaffolding refuses ":" but the pull path
+    // is where foreign ids enter).
+    const id = body?.['data']?.id;
+    if (!body || typeof body !== 'object' || typeof id !== 'string' || !/^\d+$/.test(id)) {
+        throw new Error(`x identity pull refused or malformed: ${JSON.stringify(body).slice(0, 200)}`);
+    }
+    return [mapUsersMeAccount(body)];
+}
+/** PULL the operator's own identity into the twin's observed log (idempotent). */
+export async function pullXIdentity(execute, root, occurredAt) {
+    const resources = await collectXIdentity(execute);
+    ((__at) => observeResources(SERVICE, resources, { ...(root !== undefined ? { root } : {}), at: __at, batch: `obs:${SERVICE}:${__at}` }))(occurredAt ?? pollTimestamp());
+    return resources.length;
+}
+/**
+ * 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 async function syncXIdentityFromReal(execute, opts = {}) {
+    const occurredAt = opts.occurredAt ?? pollTimestamp();
+    const resources = await collectXIdentity(execute);
+    const result = ((__at) => observeResources(SERVICE, resources, { ...(opts.root !== undefined ? { root: opts.root } : {}), at: __at, batch: `obs:${SERVICE}:${__at}` }))(occurredAt);
+    return { observed: resources.length, deltasAppended: result.appended };
+}
+/**
+ * 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 function pushPendingXIdentityActions(root) {
+    return { pushed: 0, unpushable: deployableEntries(SERVICE, root).length };
+}
+// ── PROTOCOL 2: the pack's half of the real state system ────────────────────────────────────
+/** 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 function xIdentityExecuteOver(execute) {
+    return async (method, path, init) => {
+        const res = await execute({
+            method,
+            path,
+            headers: { accept: 'application/json', authorization: 'Bearer twin', ...(init?.headers ?? {}) },
+            ...(init?.body === undefined ? {} : { body: init.body }),
+        });
+        try {
+            return JSON.parse(res.body || '{}');
+        }
+        catch {
+            return {};
+        }
+    };
+}
+/** 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 async function syncXIdentityFromRemote(execute, opts = {}) {
+    return syncXIdentityFromReal(xIdentityExecuteOver(execute), {
+        ...(opts.root !== undefined ? { root: opts.root } : {}),
+        occurredAt: opts.occurredAt ?? new Date().toISOString(),
+    });
+}
+/**
+ * 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 async function performXIdentityAction(execute, action, _ctx) {
+    void execute;
+    const op = action.operation ?? `${action.subject.type}.update`;
+    return {
+        externalId: action.subject.id,
+        data: { performed: false, reason: `${op} has nowhere to go: X creates OAuth Apps, users and scope grants in the developer portal and in account settings, and publishes no API for any of them` },
+    };
+}