@volter/twin-googleoauth 0.1.0

package/dist/src/googleoauth-connector.js

@@ -0,0 +1,244 @@
+// Google OAuth CONNECTOR — the live-vendor pull path.
+//
+// PULL (real → twin): the twin's account chooser is only as useful as the identities in it, and
+// its client registry is only as useful as the client_ids an app really holds. So a pull seeds BOTH
+// from the operator's OWN real Google credentials, using the three read endpoints that exist on
+// this surface:
+//   • GET /tokeninfo?access_token=…    → the real `azp`/`aud` (the OAuth CLIENT the token belongs
+//                                        to), the real `sub`, and the real granted `scope`
+//   • GET /v1/userinfo                 → the real persona behind that `sub` (email, name, picture)
+//   • GET /.well-known/openid-configuration → the vendor's own endpoint list, observed rather than
+//                                        assumed (this is how the twin can SAY the endpoints it
+//                                        serves are the endpoints Google publishes)
+//
+// PUSH IS AN HONEST GAP, not an omission: Google exposes NO write API for this surface. OAuth
+// clients are created in the Cloud Console, and a user's grants are managed at
+// myaccount.google.com — neither is an API a connector could call. `pushPendingGoogleOAuthActions`
+// therefore exists only to report that, and the gap is filed as `googleoauth.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
+// Google credential and import NO network client. Offline/tests pass a fake executor; live runs
+// pass `liveGoogleOAuthExecute(accessToken)`. Same code path either way.
+import { assertBudgetGuardIntact, deployableEntries, observeResources } from '@volter/world-core';
+import { GoogleOAuthBudget, GoogleOAuthBudgetError, googleOAuthCallWeight } from "./googleoauth-budget.js";
+const SERVICE = 'googleoauth';
+/** Google's real hosts, one per endpoint family — the live executor's routing table. */
+const HOSTS = {
+    '/tokeninfo': 'https://oauth2.googleapis.com',
+    '/revoke': 'https://oauth2.googleapis.com',
+    '/v1/userinfo': 'https://openidconnect.googleapis.com',
+    '/oauth2/v3/certs': 'https://www.googleapis.com',
+    '/.well-known/openid-configuration': 'https://accounts.google.com',
+};
+/**
+ * A live executor against the real Google OAuth endpoints, holding the operator's OWN access token.
+ *
+ * THIS IS THE ONE PLACE this pack issues a live Google 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 `Retry-After` / 429 becomes a PERSISTED
+ * cooldown that makes every later call fail fast WITHOUT touching Google. There is deliberately no
+ * option to disable the guard and no value of `budget` that yields an unguarded client — a
+ * duck-typed stand-in, a SUBCLASS overriding `checkBudget`, and a Proxy trapping it are all refused
+ * (`assertBudgetGuardIntact`). What this cannot stop is deliberate sabotage from inside the process
+ * (an injected clock, a throwaway ledger path); the kernel's header states that limit rather than
+ * pretending otherwise.
+ */
+export function liveGoogleOAuthExecute(accessToken, opts = {}) {
+    const doFetch = opts.fetchImpl ?? fetch;
+    const budget = opts.budget !== undefined && opts.budget !== null
+        ? assertBudgetGuardIntact(opts.budget, GoogleOAuthBudget, 'liveGoogleOAuthExecute')
+        : new GoogleOAuthBudget({ token: accessToken, ...(opts.budgetOptions ?? {}) });
+    return async (method, path, init) => {
+        const bare = path.split('?')[0] ?? path;
+        const host = HOSTS[bare];
+        if (!host)
+            throw new Error(`liveGoogleOAuthExecute: refusing to call an unmapped Google path: ${bare}`);
+        const weight = googleOAuthCallWeight(method, path);
+        // 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: { Authorization: `Bearer ${accessToken}`, ...(init?.headers ?? {}) },
+            ...(init?.body !== undefined ? { body: init.body } : {}),
+        });
+        const resHeaders = {};
+        res.headers.forEach((v, k) => {
+            resHeaders[k.toLowerCase()] = v;
+        });
+        const parsed = (await res.json());
+        // Settles the reservation and, on a back-off signal, arms the cooldown. The cooldown is
+        // persisted before any throw, so the refusal 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 Google 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 GoogleOAuthBudgetError) || !res.ok)
+                throw error;
+        }
+        // A REFUSED pull is NOT an empty account: Google answers a bad token with an `error` envelope
+        // (sometimes under HTTP 200 on the tokeninfo endpoint), and mapping that to "no data" would let
+        // the fold put an empty account OVER real observed state. Throw instead.
+        if (parsed && typeof parsed === 'object' && 'error' in parsed) {
+            const err = parsed.error;
+            const detail = typeof err === 'string' ? err : JSON.stringify(err);
+            throw new Error(`google oauth refused ${method} ${bare}: ${detail}`);
+        }
+        if (res.status >= 400)
+            throw new Error(`google oauth refused ${method} ${bare}: HTTP ${res.status}`);
+        return parsed;
+    };
+}
+/** Map a real `tokeninfo` response → the OAuth client SyncResource it names. */
+export function mapTokenInfoClient(info) {
+    const clientId = String(info.azp ?? info.aud ?? '');
+    return {
+        type: 'oauth_client',
+        id: clientId,
+        fields: {
+            // NOTHING HERE IS INVENTED. /tokeninfo discloses the client_id and nothing else about the
+            // client, so every other field records that absence rather than filling it in:
+            //   • `secret: null`  — the API never returns a client secret; a placeholder would be a
+            //     fabricated credential, and the token endpoint therefore treats a pulled-only client as
+            //     a public (`installed`) one until an operator registers the real thing.
+            //   • `name` — an earlier version used `clientId.split('-')[0]`, which put the bare numeric
+            //     project prefix ("1044839207") on the consent screen as if it were the app's name. It is
+            //     not a name; it is half an id. The row now says so, and the screen shows that (§9 round
+            //     one).
+            //   • `verified: null` — this flag drives the "Google hasn't verified this app" interstitial.
+            //     tokeninfo does not disclose it, and claiming `true` would silently SUPPRESS a warning
+            //     the real screen might show. Unknown reads as unverified, which is the safe direction.
+            name: `Pulled client ${clientId}`,
+            secret: null,
+            redirectUris: [],
+            clientType: 'installed',
+            supportEmail: null,
+            verified: null,
+            pulled: true,
+        },
+    };
+}
+/** Map a real `userinfo` response → the account (persona) SyncResource. */
+export function mapUserInfoAccount(profile) {
+    return {
+        type: 'account',
+        id: String(profile.sub ?? ''),
+        fields: {
+            email: profile.email ?? null,
+            emailVerified: profile.email_verified === true,
+            name: profile.name ?? null,
+            givenName: profile.given_name ?? null,
+            familyName: profile.family_name ?? null,
+            picture: profile.picture ?? null,
+            ...(profile.hd ? { hd: profile.hd } : {}),
+            pulled: true,
+        },
+    };
+}
+/** Map a real `tokeninfo` response → the (client, user) grant SyncResource it evidences. */
+export function mapTokenInfoGrant(info) {
+    const clientId = String(info.azp ?? info.aud ?? '');
+    const sub = String(info.sub ?? '');
+    return {
+        type: 'grant',
+        id: `${clientId}:${sub}`,
+        fields: {
+            clientId,
+            sub,
+            scopes: typeof info.scope === 'string' ? info.scope.split(/\s+/).filter(Boolean) : [],
+            pulled: true,
+        },
+    };
+}
+/**
+ * A MOVING pull timestamp, forced strictly increasing within the process.
+ *
+ * NOT a pinned constant (the hazard ADDING_A_TWIN.md §6 names, and which `calcom-connector.ts`'s
+ * `PULL_AT` is a live instance of): the kernel hashes an observed event over (`occurredAt` +
+ * post-state), so under a fixed poll time a vendor value that REVERTS across polls — a scope
+ * granted, revoked and re-granted; a display name changed back — collides with its own earlier
+ * observation and the fold reports `deltasAppended: 1` while nothing lands.
+ */
+let lastPollMs = 0;
+function pollTimestamp() {
+    const now = Date.now();
+    lastPollMs = now > lastPollMs ? now : lastPollMs + 1;
+    return new Date(lastPollMs).toISOString();
+}
+/** Fetch + map the identity behind the operator's own token (no fold). */
+async function collectGoogleOAuthIdentity(execute) {
+    const info = await execute('GET', '/tokeninfo');
+    const profile = await execute('GET', '/v1/userinfo');
+    const resources = [];
+    const clientId = String(info.azp ?? info.aud ?? '');
+    if (clientId)
+        resources.push(mapTokenInfoClient(info));
+    if (profile.sub)
+        resources.push(mapUserInfoAccount(profile));
+    if (clientId && info.sub)
+        resources.push(mapTokenInfoGrant(info));
+    return resources;
+}
+/** PULL the operator's own identity + client into the twin's observed log (idempotent). */
+export async function pullGoogleOAuthIdentity(execute, root, occurredAt) {
+    const resources = await collectGoogleOAuthIdentity(execute);
+    fold(resources, { occurredAt: occurredAt ?? pollTimestamp(), ...(root !== undefined ? { root } : {}) });
+    return resources.length;
+}
+/**
+ * D7 consumer-facing pull entry point: pull everything readable from the real Google OAuth surface
+ * and fold it into the tree in ONE observed batch, returning the standard
+ * `{ observed, deltasAppended }`. Idempotent — a re-pull of identical state appends nothing.
+ */
+/** One fold onto the head: protocol 2's observe, one batch, one instant. */
+function fold(resources, opts) {
+    return observeResources(SERVICE, resources.map((r) => ({ type: r.type, id: r.id, fields: r.fields })), {
+        ...(opts.root !== undefined ? { root: opts.root } : {}), at: opts.occurredAt, batch: `obs:${SERVICE}:${opts.occurredAt}`,
+    });
+}
+export async function syncGoogleOAuthFromReal(execute, opts = {}) {
+    const occurredAt = opts.occurredAt ?? pollTimestamp();
+    const resources = await collectGoogleOAuthIdentity(execute);
+    const result = fold(resources, { occurredAt, ...(opts.root !== undefined ? { root: opts.root } : {}) });
+    return { observed: result.observed, deltasAppended: result.appended };
+}
+// ── PROTOCOL 2: the pack's half of the real state system ────────────────────────────────────
+/** The pack's executor over the kernel's. */
+export function googleOAuthExecuteOver(execute) {
+    return async (method, path, init) => {
+        const res = await execute({ method, path, headers: { accept: 'application/json', ...(init?.headers ?? {}) }, ...(init?.body === undefined ? {} : { body: String(init.body) }) });
+        let data = {};
+        if (res.body) {
+            try {
+                data = JSON.parse(res.body);
+            }
+            catch {
+                data = { error: res.body };
+            }
+        }
+        return { status: res.status, data };
+    };
+}
+/** The refresh adapter: read the account this credential names (its identity and granted scopes). */
+export async function syncGoogleOAuthFromRemote(execute, opts = {}) {
+    return syncGoogleOAuthFromReal(googleOAuthExecuteOver(execute), {
+        ...(opts.root !== undefined ? { root: opts.root } : {}),
+        ...(opts.occurredAt !== undefined ? { occurredAt: opts.occurredAt } : {}),
+    });
+}
+/** The perform adapter — and the honest answer is that NOTHING here can cross. Google publishes no API
+ *  that creates an OAuth client, seeds a user or grants a scope: those are Cloud Console and
+ *  myaccount.google.com actions a person takes in a browser. So every entry settles with that reason,
+ *  which is exactly what the v1 push reported by refusing to confirm anything. */
+export async function performGoogleOAuthAction(_execute, action, _ctx) {
+    return { externalId: action.subject.id, data: { performed: false, reason: `${action.operation ?? action.subject.type}: Google publishes no API that creates an OAuth client, seeds a user or grants a scope — those are console actions, so nothing can cross` } };
+}
+/** How much local state has no upstream home — the count the v1 push reported, kept for the claim that
+ *  states this vendor's bound honestly. */
+export function unpushableGoogleOAuthEntries(root) {
+    return { pushed: 0, unpushable: deployableEntries(SERVICE, root).length };
+}