@aiguru/google-web-operations 0.6.4

package/packages/connectors/google/src/gtm.js

@@ -0,0 +1,261 @@
+/**
+ * Google Tag Manager API v2.
+ *
+ * Reads (v0.3): accounts, containers, workspaces, version headers, the live
+ * version, and a compact diffable snapshot of it.
+ *
+ * Writes (v0.4): staged only. Every change lands in a workspace whose name
+ * starts with the policy prefix, the workspace is diffed against the live
+ * version, and publishing requires both the operator's approval token and a
+ * review token computed from that diff, so nothing publishes that was not
+ * seen. Functions here are transport only; the write loop, policy and
+ * verification live in packages/core/src/gtm-ops.ts.
+ */
+import { createHash } from 'node:crypto';
+import { googleJson } from "./auth.js";
+const V2 = 'https://tagmanager.googleapis.com/tagmanager/v2';
+export const ID_FIELD = { tag: 'tagId', trigger: 'triggerId', variable: 'variableId' };
+const COLLECTION = { tag: 'tags', trigger: 'triggers', variable: 'variables' };
+/** Fields the API owns. Never sent on create or update. */
+const READ_ONLY = new Set(['path', 'accountId', 'containerId', 'workspaceId', 'tagId', 'triggerId', 'variableId', 'fingerprint', 'tagManagerUrl']);
+/** Triggers every container has without creating them. Names as GTM shows them. */
+export const BUILT_IN_TRIGGERS = {
+    'All Pages': '2147479553',
+    'Consent Initialization - All Pages': '2147479572',
+    'Initialization - All Pages': '2147479573',
+};
+const containerPath = (a, c) => `${V2}/accounts/${a}/containers/${c}`;
+const wsPath = (a, c, w) => `${containerPath(a, c)}/workspaces/${w}`;
+export async function listAccounts() {
+    return (await googleJson(`${V2}/accounts`)).account ?? [];
+}
+export async function listContainers(accountId) {
+    return (await googleJson(`${V2}/accounts/${accountId}/containers`)).container ?? [];
+}
+/** Every container the account can see, across all GTM accounts. */
+export async function listAllContainers() {
+    const out = [];
+    for (const a of await listAccounts())
+        out.push(...(await listContainers(a.accountId)));
+    return out;
+}
+export async function listWorkspaces(accountId, containerId) {
+    return (await googleJson(`${containerPath(accountId, containerId)}/workspaces`)).workspace ?? [];
+}
+export async function listVersionHeaders(accountId, containerId) {
+    return (await googleJson(`${containerPath(accountId, containerId)}/version_headers`)).containerVersionHeader ?? [];
+}
+export async function getLiveVersion(accountId, containerId) {
+    return googleJson(`${containerPath(accountId, containerId)}/versions:live`);
+}
+// ---------------------------------------------------------------- workspaces (write side)
+export function createWorkspace(accountId, containerId, name, description) {
+    return googleJson(`${containerPath(accountId, containerId)}/workspaces`, { method: 'POST', body: JSON.stringify({ name, description }) });
+}
+/** What the workspace would change relative to its base version, straight from GTM. */
+export function workspaceStatus(accountId, containerId, workspaceId) {
+    return googleJson(`${wsPath(accountId, containerId, workspaceId)}/status`);
+}
+/** Bring the workspace up to the latest container version. Needed before creating a version when others published meanwhile. */
+export function syncWorkspace(accountId, containerId, workspaceId) {
+    return googleJson(`${wsPath(accountId, containerId, workspaceId)}:sync`, { method: 'POST' });
+}
+export async function listEntities(accountId, containerId, workspaceId, kind) {
+    const out = [];
+    let pageToken;
+    do {
+        const url = `${wsPath(accountId, containerId, workspaceId)}/${COLLECTION[kind]}${pageToken ? `?pageToken=${encodeURIComponent(pageToken)}` : ''}`;
+        const page = (await googleJson(url)) ?? {};
+        out.push(...(page[kind] ?? []));
+        pageToken = page['nextPageToken'];
+    } while (pageToken);
+    return out;
+}
+/** Strip API-owned fields so a body can be sent on create or update. */
+export function writableBody(entity) {
+    return Object.fromEntries(Object.entries(entity).filter(([k]) => !READ_ONLY.has(k)));
+}
+export function createEntity(accountId, containerId, workspaceId, kind, body) {
+    return googleJson(`${wsPath(accountId, containerId, workspaceId)}/${COLLECTION[kind]}`, { method: 'POST', body: JSON.stringify(writableBody(body)) });
+}
+/** Full replace, as the API requires. The fingerprint guards against overwriting a concurrent edit. */
+export function updateEntity(accountId, containerId, workspaceId, kind, id, body, fingerprint) {
+    const q = fingerprint ? `?fingerprint=${encodeURIComponent(fingerprint)}` : '';
+    return googleJson(`${wsPath(accountId, containerId, workspaceId)}/${COLLECTION[kind]}/${id}${q}`, { method: 'PUT', body: JSON.stringify(writableBody(body)) });
+}
+/** Turn the workspace into a container version. GTM deletes the workspace and opens a fresh one in its place. */
+export function createVersion(accountId, containerId, workspaceId, body) {
+    return googleJson(`${wsPath(accountId, containerId, workspaceId)}:create_version`, { method: 'POST', body: JSON.stringify(body) });
+}
+export function publishVersion(accountId, containerId, versionId) {
+    return googleJson(`${containerPath(accountId, containerId)}/versions/${versionId}:publish`, { method: 'POST' });
+}
+// ---------------------------------------------------------------- pure helpers for staging
+/** Merge a patch over an existing entity for a PUT. Read-only fields are dropped; explicit null removes a field. */
+export function mergeEntity(existing, patch) {
+    const merged = { ...writableBody(existing) };
+    for (const [k, v] of Object.entries(writableBody(patch))) {
+        if (v === null)
+            delete merged[k];
+        else
+            merged[k] = v;
+    }
+    return merged;
+}
+const paramMap = (ps) => Object.fromEntries((ps ?? []).filter((p) => p.key).map((p) => [p.key, JSON.stringify({ t: p.type, v: p.value ?? null, l: p.list ?? null, m: p.map ?? null })]));
+/**
+ * Did the API store what was sent? Compares the fields a request can set and
+ * this system cares about. Returns a description of the first mismatch, or null.
+ */
+export function entityMatches(sent, stored) {
+    if (!stored)
+        return 'entity not found after write';
+    for (const k of ['name', 'type', 'paused']) {
+        if (sent[k] !== undefined && sent[k] !== stored[k])
+            return `${k}: sent ${JSON.stringify(sent[k])}, stored ${JSON.stringify(stored[k])}`;
+    }
+    for (const k of ['firingTriggerId', 'blockingTriggerId']) {
+        if (sent[k] !== undefined && JSON.stringify([...sent[k] ?? []].sort()) !== JSON.stringify([...stored[k] ?? []].sort()))
+            return `${k}: sent ${JSON.stringify(sent[k])}, stored ${JSON.stringify(stored[k] ?? [])}`;
+    }
+    if (sent.parameter) {
+        const want = paramMap(sent.parameter), got = paramMap(stored.parameter);
+        for (const [key, v] of Object.entries(want))
+            if (got[key] !== v)
+                return `parameter ${key} differs after write`;
+    }
+    return null;
+}
+function changedFields(live, ws) {
+    if (!live)
+        return [];
+    const out = [];
+    for (const k of ['name', 'type', 'paused'])
+        if ((live[k] ?? null) !== (ws[k] ?? null))
+            out.push(k);
+    for (const k of ['firingTriggerId', 'blockingTriggerId'])
+        if (JSON.stringify(live[k] ?? []) !== JSON.stringify(ws[k] ?? []))
+            out.push(k);
+    if (JSON.stringify(paramMap(live.parameter)) !== JSON.stringify(paramMap(ws.parameter)))
+        out.push('parameter');
+    return out;
+}
+/** Shape a workspace status against the live version into a reviewable diff. Pure. */
+export function shapeWorkspaceDiff(status, live) {
+    const liveById = {
+        tag: new Map((live.tag ?? []).map((t) => [t.tagId, t])),
+        trigger: new Map((live.trigger ?? []).map((t) => [t.triggerId, t])),
+        variable: new Map((live.variable ?? []).map((v) => [v.variableId, v])),
+    };
+    const changes = [];
+    for (const c of status.workspaceChange ?? []) {
+        if (c.changeStatus === 'none')
+            continue;
+        const kind = c.tag ? 'tag' : c.trigger ? 'trigger' : c.variable ? 'variable' : null;
+        if (kind) {
+            const e = c[kind];
+            const id = e[ID_FIELD[kind]] ?? null;
+            changes.push({
+                kind, changeStatus: c.changeStatus, id, name: e.name, type: e.type ?? null, fingerprint: e.fingerprint ?? null,
+                fields: c.changeStatus === 'updated' && id ? changedFields(liveById[kind].get(id), e) : [],
+            });
+        }
+        else {
+            const other = c.folder ?? c.client ?? c.transformation ?? c.template ?? c.zone ?? c.gtagConfig;
+            changes.push({ kind: 'other', changeStatus: c.changeStatus, id: null, name: other?.name ?? '(unnamed)', type: null, fingerprint: null, fields: [] });
+        }
+    }
+    changes.sort((a, b) => a.kind.localeCompare(b.kind) || a.name.localeCompare(b.name));
+    const count = (s) => changes.filter((c) => c.changeStatus === s).length;
+    return {
+        liveVersionId: live.containerVersionId, changes,
+        counts: { added: count('added'), updated: count('updated'), deleted: count('deleted'), other: changes.filter((c) => c.kind === 'other').length },
+        conflicts: status.mergeConflict?.length ?? 0,
+    };
+}
+/**
+ * Short token bound to exactly this set of changes. Any further edit in the
+ * workspace, or a new live version, changes the token, so a publish that
+ * carries a token proves the operator reviewed the diff that will ship.
+ */
+export function reviewToken(diff) {
+    const material = JSON.stringify({ live: diff.liveVersionId, changes: diff.changes.map((c) => [c.kind, c.changeStatus, c.id, c.name, c.fingerprint]) });
+    return createHash('sha256').update(material).digest('hex').slice(0, 12);
+}
+export function renderWorkspaceDiff(diff, workspace) {
+    const lines = [
+        `# GTM workspace "${workspace.name}" (${workspace.workspaceId}) vs live version ${diff.liveVersionId}`,
+        `${diff.counts.added} added, ${diff.counts.updated} updated, ${diff.counts.deleted} deleted${diff.conflicts ? `, ${diff.conflicts} MERGE CONFLICT(S)` : ''}`,
+    ];
+    if (!diff.changes.length)
+        lines.push('', 'No changes. Nothing to publish.');
+    for (const c of diff.changes) {
+        lines.push(`- ${c.changeStatus.toUpperCase()} ${c.kind} "${c.name}"${c.type ? ` (${c.type})` : ''}${c.fields.length ? `: ${c.fields.join(', ')}` : ''}`);
+    }
+    lines.push('', `review token: ${reviewToken(diff)}`);
+    return lines.join('\n');
+}
+/** Shape a live version into a compact, diffable record. Pure. */
+export function shapeSnapshot(v, ids) {
+    const triggerName = new Map((v.trigger ?? []).map((t) => [t.triggerId, t.name]));
+    const tags = (v.tag ?? []).map((t) => ({
+        id: t.tagId, name: t.name, type: t.type ?? '', paused: !!t.paused,
+        firing: (t.firingTriggerId ?? []).map((id) => triggerName.get(id) ?? id),
+        blocking: (t.blockingTriggerId ?? []).map((id) => triggerName.get(id) ?? id),
+    }));
+    return {
+        at: new Date().toISOString(),
+        accountId: ids.accountId, containerId: ids.containerId, publicId: ids.publicId ?? null,
+        versionId: v.containerVersionId, versionName: v.name ?? null, fingerprint: v.fingerprint ?? null,
+        counts: { tags: tags.length, triggers: v.trigger?.length ?? 0, variables: v.variable?.length ?? 0, builtIns: v.builtInVariable?.length ?? 0, paused: tags.filter((t) => t.paused).length },
+        tags,
+        triggers: (v.trigger ?? []).map((t) => ({ id: t.triggerId, name: t.name, type: t.type ?? '' })),
+        variables: (v.variable ?? []).map((x) => ({ id: x.variableId, name: x.name, type: x.type ?? '' })),
+    };
+}
+/** What changed between two snapshots. Pure. */
+export function diffSnapshots(before, after) {
+    const byId = (xs) => new Map(xs.map((x) => [x.id, x]));
+    const b = byId(before.tags), a = byId(after.tags);
+    const changed = [];
+    for (const [id, t] of a) {
+        const p = b.get(id);
+        if (!p)
+            continue;
+        const fields = [];
+        if (p.name !== t.name)
+            fields.push('name');
+        if (p.type !== t.type)
+            fields.push('type');
+        if (p.paused !== t.paused)
+            fields.push('paused');
+        if (JSON.stringify(p.firing) !== JSON.stringify(t.firing))
+            fields.push('firing');
+        if (JSON.stringify(p.blocking) !== JSON.stringify(t.blocking))
+            fields.push('blocking');
+        if (fields.length)
+            changed.push({ name: t.name, fields });
+    }
+    const names = (xs, other) => xs.filter((x) => !other.has(x.id)).map((x) => x.name);
+    const bt = byId(before.triggers), at = byId(after.triggers), bv = byId(before.variables), av = byId(after.variables);
+    return {
+        versionChanged: before.versionId !== after.versionId,
+        before: { versionId: before.versionId, versionName: before.versionName },
+        after: { versionId: after.versionId, versionName: after.versionName },
+        tags: { added: names(after.tags, b), removed: names(before.tags, a), changed },
+        triggers: { added: names(after.triggers, bt), removed: names(before.triggers, at) },
+        variables: { added: names(after.variables, bv), removed: names(before.variables, av) },
+    };
+}
+/** Human-sized rendering of a snapshot. */
+export function renderSnapshot(s) {
+    const lines = [
+        `# GTM ${s.publicId ?? s.containerId}: version ${s.versionId}${s.versionName ? ` "${s.versionName}"` : ''}`,
+        `${s.counts.tags} tags (${s.counts.paused} paused), ${s.counts.triggers} triggers, ${s.counts.variables} variables, ${s.counts.builtIns} built-ins`,
+        '',
+        '## Tags',
+    ];
+    for (const t of s.tags)
+        lines.push(`- ${t.paused ? '[PAUSED] ' : ''}${t.name} (${t.type}) fires on: ${t.firing.join(', ') || 'nothing'}${t.blocking.length ? `; blocked by: ${t.blocking.join(', ')}` : ''}`);
+    return lines.join('\n');
+}

package/packages/connectors/google/src/index.js

@@ -0,0 +1,8 @@
+export { googleJson, setTokenProvider, tokenProvider, envTokenProvider, GoogleApiError } from "./auth.js";
+export { login, logout, makeOauthProvider, loadClientConfig, pkcePair, refresh, buildAuthUrl, DEFAULT_SCOPES, SCOPES_FOR, CLIENT_FILE } from "./oauth.js";
+export { defaultTokenStore, dpapiStore, aesStore, SECRETS_DIR } from "./token-store.js";
+export { discover, fetchInventory, matchInventory, applyMatches, hostOf } from "./discover.js";
+export * as gtm from "./gtm.js";
+export * as gsc from "./gsc.js";
+export * as ga4 from "./ga4.js";
+export * as pagespeed from "./pagespeed.js";

package/packages/connectors/google/src/oauth.js

@@ -0,0 +1,198 @@
+/**
+ * Durable Google OAuth for the company operations account.
+ *
+ * One consent, once, on the operator's machine:
+ *   login()  -> browser consent with PKCE -> refresh token -> encrypted store
+ * After that, every process refreshes access tokens silently:
+ *   oauthTokenProvider.accessToken()
+ *
+ * The client configuration is the "Desktop app" JSON downloaded from Google
+ * Cloud Console, placed at secrets/oauth-client.json. It is not a secret in
+ * the strict sense for desktop clients, but it is gitignored anyway.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { defaultTokenStore, SECRETS_DIR } from "./token-store.js";
+export const CLIENT_FILE = path.join(SECRETS_DIR, 'oauth-client.json');
+/** Least privilege for v0.3 reads plus the one auto write (sitemap submit). */
+export const DEFAULT_SCOPES = [
+    'openid',
+    'https://www.googleapis.com/auth/userinfo.email',
+    'https://www.googleapis.com/auth/webmasters', // Search Console read + sitemap submit
+    'https://www.googleapis.com/auth/analytics.readonly', // GA4 Data + Admin read
+    'https://www.googleapis.com/auth/tagmanager.readonly', // GTM read
+];
+/** Scopes needed later, by capability. login({ scopes }) can add them when a write is enabled. */
+export const SCOPES_FOR = {
+    ga4_write: 'https://www.googleapis.com/auth/analytics.edit',
+    gtm_edit: 'https://www.googleapis.com/auth/tagmanager.edit.containers',
+    gtm_publish: 'https://www.googleapis.com/auth/tagmanager.publish',
+};
+export function loadClientConfig(file = CLIENT_FILE) {
+    if (!existsSync(file)) {
+        throw new Error(`OAuth client file not found: ${file}\n` +
+            'Create a "Desktop app" OAuth client in Google Cloud Console, download its JSON, and save it there.');
+    }
+    const raw = JSON.parse(readFileSync(file, 'utf8'));
+    const c = raw.installed ?? raw.web;
+    if (!c?.client_id || !c.token_uri)
+        throw new Error(`${file}: not a Google OAuth client JSON (expected "installed" with client_id and token_uri).`);
+    return {
+        client_id: c.client_id, client_secret: c.client_secret ?? '',
+        auth_uri: c.auth_uri ?? 'https://accounts.google.com/o/oauth2/v2/auth',
+        token_uri: c.token_uri,
+    };
+}
+// ---------------------------------------------------------------- PKCE
+const b64url = (b) => b.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+export function pkcePair() {
+    const verifier = b64url(randomBytes(32));
+    return { verifier, challenge: b64url(createHash('sha256').update(verifier).digest()) };
+}
+async function tokenRequest(cfg, params, fetchImpl = fetch) {
+    const res = await fetchImpl(cfg.token_uri, {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({ client_id: cfg.client_id, client_secret: cfg.client_secret, ...params }).toString(),
+    });
+    const body = await res.text();
+    if (!res.ok)
+        throw new Error(`Google token endpoint ${res.status}: ${body.slice(0, 400)}`);
+    return JSON.parse(body);
+}
+export async function refresh(cfg, refreshToken, fetchImpl = fetch) {
+    const t = await tokenRequest(cfg, { grant_type: 'refresh_token', refresh_token: refreshToken }, fetchImpl);
+    return { accessToken: t.access_token, expiresAt: Date.now() + Math.max(0, (t.expires_in - 60)) * 1000 };
+}
+// ---------------------------------------------------------------- consent flow
+/**
+ * Open a URL in the default browser.
+ * On Windows we must not go through cmd.exe: it treats "&" as a command
+ * separator and truncates the query string. rundll32 passes the URL intact.
+ */
+function openBrowser(url) {
+    const [cmd, args] = process.platform === 'win32' ? ['rundll32', ['url.dll,FileProtocolHandler', url]] :
+        process.platform === 'darwin' ? ['open', [url]] : ['xdg-open', [url]];
+    try {
+        spawn(cmd, args, { detached: true, stdio: 'ignore' }).unref();
+    }
+    catch { /* user can paste the URL */ }
+}
+/** Build the consent URL. Pure, so it can be tested. */
+export function buildAuthUrl(cfg, p) {
+    const u = new URL(cfg.auth_uri);
+    const params = {
+        client_id: cfg.client_id, redirect_uri: p.redirectUri, response_type: 'code', scope: p.scopes.join(' '),
+        code_challenge: p.challenge, code_challenge_method: 'S256', state: p.state, access_type: 'offline', prompt: 'consent',
+    };
+    for (const [k, v] of Object.entries(params))
+        u.searchParams.set(k, v);
+    return u.toString();
+}
+/**
+ * Start a loopback server for the OAuth redirect. Resolves once listening
+ * with the redirect URI and a promise for the authorisation code.
+ */
+function startLoopback(expectedState) {
+    return new Promise((resolveStart, rejectStart) => {
+        let resolveCode;
+        let rejectCode;
+        const code = new Promise((res, rej) => { resolveCode = res; rejectCode = rej; });
+        const server = http.createServer((req, res) => {
+            const u = new URL(req.url ?? '/', 'http://127.0.0.1');
+            const got = u.searchParams.get('code'), state = u.searchParams.get('state'), err = u.searchParams.get('error');
+            const page = (msg) => {
+                res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
+                res.end(`<!doctype html><meta charset="utf-8"><body style="font-family:system-ui;padding:2rem"><h2>Google Web Operations</h2><p>${msg}</p></body>`);
+            };
+            if (err) {
+                page(`Authorisation failed: ${err}. You can close this tab.`);
+                server.close();
+                rejectCode(new Error(err));
+                return;
+            }
+            if (!got || state !== expectedState) {
+                page('Unexpected request. You can close this tab.');
+                return;
+            }
+            page('Authorised. You can close this tab and return to the terminal.');
+            server.close();
+            resolveCode(got);
+        });
+        server.on('error', rejectStart);
+        server.listen(0, '127.0.0.1', () => {
+            const a = server.address();
+            const port = typeof a === 'object' && a ? a.port : 0;
+            resolveStart({ redirectUri: `http://127.0.0.1:${port}`, code });
+        });
+    });
+}
+/** Run the consent flow once and persist the refresh token. Returns non-secret status. */
+export async function login(opts = {}) {
+    const cfg = loadClientConfig(opts.clientFile);
+    const store = opts.store ?? defaultTokenStore();
+    const log = opts.log ?? ((s) => console.error(s));
+    const scopes = [...new Set([...DEFAULT_SCOPES, ...(opts.scopes ?? [])])];
+    const { verifier, challenge } = pkcePair();
+    const state = b64url(randomBytes(16));
+    const { redirectUri, code: codePromise } = await startLoopback(state);
+    const authUrl = buildAuthUrl(cfg, { redirectUri, scopes, challenge, state });
+    if (opts.open === false) {
+        log('Open this URL in a browser signed in as the operations account:\n' + authUrl);
+    }
+    else {
+        log('Opening the browser for Google consent. If it does not open, visit:\n' + authUrl);
+        openBrowser(authUrl);
+    }
+    const code = await codePromise;
+    const t = await tokenRequest(cfg, { grant_type: 'authorization_code', code, redirect_uri: redirectUri, code_verifier: verifier });
+    if (!t.refresh_token)
+        throw new Error('Google did not return a refresh token. Revoke the app at myaccount.google.com/permissions and log in again.');
+    let email = null;
+    try {
+        const ui = await fetch('https://openidconnect.googleapis.com/v1/userinfo', { headers: { authorization: `Bearer ${t.access_token}` } });
+        if (ui.ok)
+            email = (await ui.json()).email ?? null;
+    }
+    catch { /* email is cosmetic */ }
+    const record = {
+        refresh_token: t.refresh_token, client_id: cfg.client_id,
+        scopes: (t.scope ?? scopes.join(' ')).split(' ').filter(Boolean), email, obtained_at: new Date().toISOString(),
+    };
+    store.save(record);
+    return { email, scopes: record.scopes, store: store.describe() };
+}
+// ---------------------------------------------------------------- provider
+/** Token provider backed by the encrypted store. Refreshes silently; caches in memory. */
+export function makeOauthProvider(store = defaultTokenStore(), clientFile, fetchImpl = fetch) {
+    let cached = null;
+    let record;
+    const load = () => (record === undefined ? (record = store.load()) : record);
+    return {
+        async accessToken() {
+            const r = load();
+            if (!r)
+                throw new Error('No Google authorisation stored. Run: npm run cli -- auth login');
+            if (cached && Date.now() < cached.expiresAt)
+                return cached.accessToken;
+            cached = await refresh(loadClientConfig(clientFile), r.refresh_token, fetchImpl);
+            return cached.accessToken;
+        },
+        describe() {
+            const r = load();
+            return r ? `OAuth refresh token for ${r.email ?? 'unknown account'} (${store.describe()})` : `no stored authorisation (${store.describe()})`;
+        },
+        status() {
+            const r = load();
+            return {
+                authorised: !!r, email: r?.email ?? null, scopes: r?.scopes ?? [], obtainedAt: r?.obtained_at ?? null,
+                store: store.describe(), clientFile: existsSync(clientFile ?? CLIENT_FILE) ? (clientFile ?? CLIENT_FILE) : null,
+                accessTokenCached: !!cached && Date.now() < cached.expiresAt,
+            };
+        },
+    };
+}
+export function logout(store = defaultTokenStore()) { store.clear(); }

package/packages/connectors/google/src/pagespeed.js

@@ -0,0 +1,48 @@
+/**
+ * PageSpeed Insights v5: Lighthouse lab data plus CrUX field data.
+ *
+ * Quota is attributed to whoever the request identifies as. Keyless calls
+ * share Google's default project, whose daily quota is routinely exhausted.
+ * So we identify as our own project: an API key if configured, otherwise the
+ * stored OAuth token. Either needs "PageSpeed Insights API" enabled in the
+ * Google Cloud project; Google's error says so if it is not.
+ */
+import { tokenProvider } from "./auth.js";
+export async function runPageSpeed(url, strategy = 'mobile') {
+    const api = new URL('https://www.googleapis.com/pagespeedonline/v5/runPagespeed');
+    api.searchParams.set('url', url);
+    api.searchParams.set('strategy', strategy);
+    for (const c of ['performance', 'seo', 'accessibility', 'best-practices'])
+        api.searchParams.append('category', c);
+    const headers = {};
+    const key = process.env['GOOGLE_PAGESPEED_API_KEY']?.trim();
+    if (key)
+        api.searchParams.set('key', key);
+    else {
+        try {
+            headers['authorization'] = `Bearer ${await tokenProvider().accessToken()}`;
+        }
+        catch { /* no credentials: fall back to the shared anonymous quota */ }
+    }
+    const res = await fetch(api, { headers });
+    if (!res.ok)
+        throw new Error(`PageSpeed ${res.status}: ${(await res.text()).slice(0, 600)}`);
+    return res.json();
+}
+/** The handful of numbers an operator actually reads. */
+export async function summarisePageSpeed(url, strategy = 'mobile') {
+    const raw = (await runPageSpeed(url, strategy));
+    const lh = raw['lighthouseResult'];
+    const cats = (lh?.['categories'] ?? {});
+    const audits = (lh?.['audits'] ?? {});
+    const field = raw['loadingExperience']?.['metrics'];
+    const score = (k) => (cats[k]?.score != null ? Math.round(cats[k]?.score * 100) : null);
+    const lab = (k) => audits[k]?.displayValue ?? null;
+    const cwv = (k) => (field?.[k] ? { p75: field[k]?.percentile ?? null, category: field[k]?.category ?? null } : null);
+    return {
+        url, strategy,
+        scores: { performance: score('performance'), seo: score('seo'), accessibility: score('accessibility'), bestPractices: score('best-practices') },
+        lab: { lcp: lab('largest-contentful-paint'), cls: lab('cumulative-layout-shift'), tbt: lab('total-blocking-time'), fcp: lab('first-contentful-paint'), ttfb: lab('server-response-time') },
+        field: field ? { lcp: cwv('LARGEST_CONTENTFUL_PAINT_MS'), cls: cwv('CUMULATIVE_LAYOUT_SHIFT_SCORE'), inp: cwv('INTERACTION_TO_NEXT_PAINT') } : null,
+    };
+}

package/packages/connectors/google/src/token-store.js

@@ -0,0 +1,89 @@
+/**
+ * Encrypted-at-rest storage for the Google refresh token.
+ *
+ * Windows: the record is protected with DPAPI (CurrentUser scope), so only
+ *          the same Windows user on the same machine can read it. No key
+ *          file exists anywhere.
+ * Other:   AES-256-GCM with a random key kept in secrets/.token-key (0600).
+ *
+ * Only the refresh token is stored. Access tokens live in process memory.
+ * Everything under secrets/ is gitignored.
+ */
+import { execFileSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+import path from 'node:path';
+import { SECRETS_DIR } from "../../../core/src/paths.js";
+export { SECRETS_DIR };
+function ensureDir() { mkdirSync(SECRETS_DIR, { recursive: true }); }
+// ---------------------------------------------------------------- Windows DPAPI
+const DPAPI_FILE = path.join(SECRETS_DIR, 'google-token.dpapi');
+/** Round-trip bytes through System.Security.Cryptography.ProtectedData via PowerShell. */
+function dpapi(mode, b64) {
+    const script = 'Add-Type -AssemblyName System.Security; ' +
+        '$in = [Convert]::FromBase64String(($input | Out-String).Trim()); ' +
+        `$out = [System.Security.Cryptography.ProtectedData]::${mode}($in, $null, 'CurrentUser'); ` +
+        '[Convert]::ToBase64String($out)';
+    return execFileSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script], {
+        input: b64, encoding: 'utf8', windowsHide: true,
+    }).trim();
+}
+export const dpapiStore = {
+    save(record) {
+        ensureDir();
+        const plain = Buffer.from(JSON.stringify(record), 'utf8').toString('base64');
+        writeFileSync(DPAPI_FILE, dpapi('Protect', plain), 'utf8');
+    },
+    load() {
+        if (!existsSync(DPAPI_FILE))
+            return null;
+        const plain = dpapi('Unprotect', readFileSync(DPAPI_FILE, 'utf8').trim());
+        return JSON.parse(Buffer.from(plain, 'base64').toString('utf8'));
+    },
+    clear() { rmSync(DPAPI_FILE, { force: true }); },
+    describe() { return `DPAPI (CurrentUser) at ${DPAPI_FILE}${existsSync(DPAPI_FILE) ? '' : ' (absent)'}`; },
+};
+// ---------------------------------------------------------------- portable AES-GCM
+const AES_FILE = path.join(SECRETS_DIR, 'google-token.enc');
+const KEY_FILE = path.join(SECRETS_DIR, '.token-key');
+function aesKey() {
+    ensureDir();
+    if (!existsSync(KEY_FILE)) {
+        writeFileSync(KEY_FILE, randomBytes(32));
+        try {
+            chmodSync(KEY_FILE, 0o600);
+        }
+        catch { /* not supported on this fs */ }
+    }
+    return readFileSync(KEY_FILE);
+}
+export const aesStore = {
+    save(record) {
+        const key = aesKey();
+        const iv = randomBytes(12);
+        const cipher = createCipheriv('aes-256-gcm', key, iv);
+        const ct = Buffer.concat([cipher.update(JSON.stringify(record), 'utf8'), cipher.final()]);
+        writeFileSync(AES_FILE, Buffer.concat([iv, cipher.getAuthTag(), ct]).toString('base64'), 'utf8');
+        try {
+            chmodSync(AES_FILE, 0o600);
+        }
+        catch { /* ignore */ }
+    },
+    load() {
+        if (!existsSync(AES_FILE))
+            return null;
+        const buf = Buffer.from(readFileSync(AES_FILE, 'utf8'), 'base64');
+        const iv = buf.subarray(0, 12), tag = buf.subarray(12, 28), ct = buf.subarray(28);
+        const decipher = createDecipheriv('aes-256-gcm', aesKey(), iv);
+        decipher.setAuthTag(tag);
+        return JSON.parse(Buffer.concat([decipher.update(ct), decipher.final()]).toString('utf8'));
+    },
+    clear() { rmSync(AES_FILE, { force: true }); },
+    describe() { return `AES-256-GCM at ${AES_FILE}${existsSync(AES_FILE) ? '' : ' (absent)'}`; },
+};
+/** The store for this platform. Override with GWO_TOKEN_STORE=aes to force the portable one. */
+export function defaultTokenStore() {
+    if (process.env['GWO_TOKEN_STORE'] === 'aes')
+        return aesStore;
+    return process.platform === 'win32' ? dpapiStore : aesStore;
+}