@volter/twin-googleoauth 0.1.0

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+// world-googleoauth CLI: serve the Google OAuth 2.0 / OIDC twin, or run conformance.
+//
+// `serve` and `mirror` start the SAME server, because the consent screen is served by the twin at
+// the vendor's own path — there is no second renderer to start. `mirror` additionally prints a
+// ready-to-open authorization URL, which is the thing an operator actually wants when they ask to
+// "see the UI".
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { createGoogleOAuthTwinServer } from "./googleoauth-server.js";
+import { DEFAULT_CLIENT_ID, defaultRedirectUris } from "./googleoauth-store.js";
+const [cmd, ...rest] = process.argv.slice(2);
+const port = Number(optionValue(rest, '--port', '0')) || undefined;
+const root = optionValue(rest, '--root') || undefined;
+const readOnly = hasFlag(rest, '--read-only'); // a twin accepts writes unless started read-only
+if (cmd === 'serve' || cmd === 'mirror') {
+    const s = await createGoogleOAuthTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}) });
+    const origin = `http://127.0.0.1:${s.port}`;
+    process.stdout.write(`googleoauth twin (OAuth 2.0 / OIDC)${readOnly ? ' [read-only]' : ''} at ${origin}\n`);
+    if (cmd === 'mirror') {
+        const url = new URL(`${origin}/o/oauth2/v2/auth`);
+        url.searchParams.set('client_id', DEFAULT_CLIENT_ID);
+        url.searchParams.set('redirect_uri', defaultRedirectUris(origin)[0]);
+        url.searchParams.set('response_type', 'code');
+        url.searchParams.set('scope', 'openid email profile https://www.googleapis.com/auth/calendar.readonly');
+        url.searchParams.set('state', 'twin-demo-state');
+        url.searchParams.set('access_type', 'offline');
+        process.stdout.write(`consent screen: ${url.toString()}\n`);
+    }
+    await keepProcessAlive();
+}
+else if (cmd === 'conformance') {
+    // dev-only; lazy so the bin runs without @volter/world-tooling in the runtime graph
+    const { checkGoogleOAuthConformance } = await import("./googleoauth-conformance.js");
+    const report = await checkGoogleOAuthConformance({ ...(root ? { root } : {}) });
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    if (!report.ok)
+        process.exitCode = 1;
+}
+else {
+    process.stdout.write('Usage: world-googleoauth serve|mirror|conformance [--port N] [--root DIR] [--read-only]\n');
+}

package/dist/src/googleoauth-autherror.d.ts

@@ -0,0 +1,25 @@
+export declare const ERROR_PAGE_PATH = "/signin/oauth/error";
+/** Google puts this on every OAuth error-page URL; a real capture always carries it. */
+export declare const FLOW_NAME = "GeneralOAuthFlow";
+export type AuthError = {
+    /** The OAuth error code (protobuf field 1). */
+    code: string;
+    /** The human-readable message (field 2). */
+    message: string;
+    /** The documentation URL Google links (field 3). */
+    docUrl?: string;
+    /** The HTTP status the page NAMES in its "Error <status>: <code>" line (field 4). */
+    status: number;
+    /** The offending parameter, echoed back (field 5). */
+    param?: string;
+};
+/** Encode an AuthError as the base64url protobuf Google puts in `?authError=`. */
+export declare function encodeAuthError(e: AuthError): string;
+/** Decode a `?authError=` payload back into its fields. Returns null on anything unparseable. */
+export declare function decodeAuthError(encoded: string): AuthError | null;
+/** The full error-page URL an authorization request is bounced to. */
+export declare function authErrorRedirect(origin: string, e: AuthError, clientId?: string): string;
+/** The two headline strings Google's error pages use, chosen by error code (captured verbatim). */
+export declare function errorHeadline(code: string): string;
+/** Google's documentation URLs, per error code (captured from real `authError` payloads). */
+export declare const ERROR_DOC_URLS: Record<string, string>;

package/dist/src/googleoauth-autherror.js

@@ -0,0 +1,144 @@
+// Google's OAuth ERROR-PAGE mechanism, reproduced.
+//
+// THE FACT THIS FILE EXISTS FOR: when Google's authorization endpoint rejects a request for a
+// configuration or parameter reason, it does NOT answer with an HTML body and it does NOT redirect
+// to the caller's `redirect_uri`. It 302s to ITS OWN error page:
+//
+//   https://accounts.google.com/signin/oauth/error
+//     ?authError=<base64url protobuf>&flowName=GeneralOAuthFlow&client_id=<id>
+//
+// and that page renders "Access blocked: …" plus the "Error <status>: <code>" line every integrator
+// ends up searching for. The `authError` payload is a base64url-encoded protobuf with five fields:
+//
+//   1 (string) the OAuth error code          e.g. "redirect_uri_mismatch"
+//   2 (string) the human message             e.g. "The OAuth client was not found."
+//   3 (string) a documentation URL
+//   4 (varint) the HTTP status the page names e.g. 401
+//   5 (string) the echoed parameter           e.g. "redirect_uri=https://evil.test/steal"
+//
+// Reproducing the REDIRECT (rather than serving HTML inline) is what makes the twin's browser
+// behaviour match: the address bar changes to accounts.google.com/signin/oauth/error, which is
+// exactly what a developer sees and screenshots when they file a bug.
+//
+// Grounded by a read-only live capture of the real endpoint on 2026-08-20 (the field numbering was
+// decoded from real `authError` payloads); recorded in spec-sources.json.
+//
+// UNCONFIRMED, and therefore not asserted anywhere: the HTTP STATUS the rendered error page itself
+// is served with. The status in field 4 is the one the page DISPLAYS. The twin serves the page as a
+// normal 200 document and puts the status in the text, which is what the capture shows the page
+// saying; `googleoauth.errors.error_page_http_status` is the filed todo.
+export const ERROR_PAGE_PATH = '/signin/oauth/error';
+/** Google puts this on every OAuth error-page URL; a real capture always carries it. */
+export const FLOW_NAME = 'GeneralOAuthFlow';
+function varint(n) {
+    const out = [];
+    let v = n;
+    while (v > 0x7f) {
+        out.push((v & 0x7f) | 0x80);
+        v >>>= 7;
+    }
+    out.push(v);
+    return out;
+}
+function stringField(field, value) {
+    const bytes = Array.from(Buffer.from(value, 'utf8'));
+    return [(field << 3) | 2, ...varint(bytes.length), ...bytes];
+}
+/** Encode an AuthError as the base64url protobuf Google puts in `?authError=`. */
+export function encodeAuthError(e) {
+    const out = [
+        ...stringField(1, e.code),
+        ...stringField(2, e.message),
+        ...(e.docUrl ? stringField(3, e.docUrl) : []),
+        (4 << 3) | 0,
+        ...varint(e.status),
+        ...(e.param ? stringField(5, e.param) : []),
+    ];
+    return Buffer.from(Uint8Array.from(out)).toString('base64url');
+}
+/** Decode a `?authError=` payload back into its fields. Returns null on anything unparseable. */
+export function decodeAuthError(encoded) {
+    let buf;
+    try {
+        buf = Buffer.from(encoded, 'base64url');
+    }
+    catch {
+        return null;
+    }
+    const out = {};
+    let i = 0;
+    const readVarint = () => {
+        let result = 0;
+        let shift = 0;
+        while (i < buf.length) {
+            const byte = buf[i++];
+            result |= (byte & 0x7f) << shift;
+            if ((byte & 0x80) === 0)
+                return result >>> 0;
+            shift += 7;
+            if (shift > 28)
+                return -1;
+        }
+        return -1;
+    };
+    while (i < buf.length) {
+        const tag = readVarint();
+        if (tag < 0)
+            return null;
+        const field = tag >>> 3;
+        const wire = tag & 7;
+        if (wire === 0) {
+            const value = readVarint();
+            if (value < 0)
+                return null;
+            if (field === 4)
+                out.status = value;
+        }
+        else if (wire === 2) {
+            const len = readVarint();
+            if (len < 0 || i + len > buf.length)
+                return null;
+            const value = buf.subarray(i, i + len).toString('utf8');
+            i += len;
+            if (field === 1)
+                out.code = value;
+            else if (field === 2)
+                out.message = value;
+            else if (field === 3)
+                out.docUrl = value;
+            else if (field === 5)
+                out.param = value;
+        }
+        else {
+            return null; // a wire type Google's payload never uses
+        }
+    }
+    if (!out.code || out.message === undefined || out.status === undefined)
+        return null;
+    return out;
+}
+/** The full error-page URL an authorization request is bounced to. */
+export function authErrorRedirect(origin, e, clientId) {
+    const url = new URL(`${origin}${ERROR_PAGE_PATH}`);
+    url.searchParams.set('authError', encodeAuthError(e));
+    url.searchParams.set('flowName', FLOW_NAME);
+    if (clientId)
+        url.searchParams.set('client_id', clientId);
+    return url.toString();
+}
+/** The two headline strings Google's error pages use, chosen by error code (captured verbatim). */
+export function errorHeadline(code) {
+    // `redirect_uri_mismatch` is an app-configuration failure, and Google words it as one; every
+    // other code lands on the generic authorization-error headline.
+    return code === 'redirect_uri_mismatch'
+        ? "Access blocked: This app's request is invalid"
+        : 'Access blocked: Authorization Error';
+}
+/** Google's documentation URLs, per error code (captured from real `authError` payloads). */
+export const ERROR_DOC_URLS = {
+    redirect_uri_mismatch: 'https://developers.google.com/identity/protocols/oauth2/web-server#uri-validation',
+    invalid_client: 'https://developers.google.com/identity/protocols/oauth2',
+    invalid_request: 'https://developers.google.com/identity/protocols/oauth2/web-server',
+    invalid_scope: 'https://developers.google.com/identity/protocols/oauth2/scopes',
+    unsupported_response_type: 'https://developers.google.com/identity/protocols/oauth2/web-server',
+};

package/dist/src/googleoauth-budget.d.ts

@@ -0,0 +1,48 @@
+import { RateBudget, type RateBudgetDeclaration, type RateBudgetOptions, type RateBudgetReservation, type RateBudgetSnapshot } from '@volter/world-core';
+/** Rolling window, in ms. Spend older than this is pruned. */
+export declare const GOOGLEOAUTH_BUDGET_WINDOW_MS = 60000;
+/**
+ * Weighted units allowed inside one window. 60/60s = 30 calls a minute at the default weight —
+ * EXACTLY the kernel fallback's burst, because Google publishes no rate this could be measured
+ * against. See the header.
+ */
+export declare const GOOGLEOAUTH_BUDGET_CEILING = 60;
+/** Seconds. A `Retry-After` above this means the client is throttled hard — fail loudly, don't sleep. */
+export declare const GOOGLEOAUTH_BUDGET_MAX_RETRY_AFTER_S = 300;
+/** Per-call cost, keyed by `"<METHOD> <path>"`. See the header for what is judged vs. documented. */
+export declare const GOOGLEOAUTH_CALL_WEIGHTS: {
+    /** `POST /revoke` — destroys a whole grant on a REAL account. The only destructive call here. */
+    readonly revoke: 10;
+    /** Everything else: discovery, certs, userinfo, tokeninfo. */
+    readonly other: 2;
+};
+/** THE PACK'S DECLARATION — pure data, the only Google-specific thing in the whole budget. */
+export declare const GOOGLEOAUTH_RATE_BUDGET: RateBudgetDeclaration;
+/**
+ * Price one call. The key is `"<METHOD> <path>"` with the query string split off. NORMALIZED
+ * (upper-cased method, collapsed trailing slash) because the anchored rules are otherwise trivially
+ * evaded by input variation: `fetch` upper-cases a known method before sending, so
+ * `execute('post', '/revoke')` really does issue the destructive call and must be priced as one.
+ */
+export declare function googleOAuthCallWeight(method: string, path: string): number;
+/** Where this vendor's ledger lives. Token-keyed and cwd-independent by default; pass `root` to opt
+ *  into world-scoped accounting. */
+export declare function googleOAuthBudgetPath(opts?: {
+    root?: string;
+    token?: string;
+} | string): string;
+/** Construction options. The vendor is fixed; everything else may only TIGHTEN. */
+export type GoogleOAuthBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
+/**
+ * This vendor's budget — the shared kernel guard bound to this declaration. A real subclass, not an
+ * alias, so `budget instanceof GoogleOAuthBudget` means "a budget that accounts against
+ * GOOGLEOAUTH's ledger under GOOGLEOAUTH's ceiling": another vendor's `RateBudget` (with its own,
+ * possibly larger, ceiling) is NOT assignable there.
+ */
+export declare class GoogleOAuthBudget extends RateBudget {
+    constructor(opts?: GoogleOAuthBudgetOptions);
+}
+export { RateBudgetError as GoogleOAuthBudgetError } from '@volter/world-core';
+export type { RateBudgetErrorKind as GoogleOAuthBudgetErrorKind } from '@volter/world-core';
+export type GoogleOAuthBudgetReservation = RateBudgetReservation;
+export type GoogleOAuthBudgetSnapshot = RateBudgetSnapshot;

package/dist/src/googleoauth-budget.js

@@ -0,0 +1,121 @@
+// Google OAuth's CLIENT-SIDE RATE BUDGET — this pack's DECLARATION (the numbers) plus the thin
+// typed bindings `liveGoogleOAuthExecute` uses. The MECHANISM — the durable token-keyed ledger, the
+// rolling window, reserve-under-lock, the `Retry-After`/429 cooldown, fail-CLOSED on a corrupt
+// ledger — lives ONCE in the vendor-agnostic kernel (`@volter/world-core` → `rateBudget.ts`). Read that
+// module's header for the full rationale AND for the honest list of what the guard does not
+// guarantee (an injected clock or ledger path still defeats it — it guards carelessness, not
+// malice).
+//
+// ── HOW THE CEILING WAS CHOSEN ──────────────────────────────────────────────────────────────
+// GOOGLE PUBLISHES NO SCALAR PER-MINUTE RATE LIMIT for its OAuth 2.0 endpoints. That is the
+// honest finding, and it is the reason this declaration is NOT more permissive than the kernel's
+// undeclared fallback. What Google DOES publish about these endpoints is quota of a different
+// SHAPE entirely — per-user/per-client TOKEN COUNTS, not a request rate:
+//   • a Google Account can hold at most 100 refresh tokens per OAuth client; minting the 101st
+//     silently invalidates the oldest (developers.google.com/identity/protocols/oauth2, "Refresh
+//     token expiration");
+//   • a testing-mode app's refresh tokens expire after 7 days;
+//   • a client has a cap on unexpired refresh tokens across all users.
+// None of those is a per-minute rate, so none of them can anchor a rolling-window ceiling — and
+// dressing one up as one would be exactly the "never a guess presented as a vendor fact" failure
+// ADDING_A_TWIN.md warns about. The ceiling therefore sits AT the kernel fallback's burst (30 calls
+// a minute at the default weight), which is also why this pack needs no `VENDOR_BURST_ANCHOR`
+// entry in scripts/rate-budget-isolation.test.ts.
+//
+// ── HOW THE WEIGHTS WERE CHOSEN (a judgement call, stated as one) ────────────────────────────
+// The connector only ever READS (there is no OAuth write API — see the connector header), so every
+// call is a read and every read costs the same 2. Exactly ONE call is priced up:
+//   • `POST /revoke` costs 10. Revocation is the one destructive thing this surface can do to a
+//     real account, and it takes the WHOLE grant with it (every access and refresh token AND the
+//     grant record for that client+user). A loop that revokes is a loop that logs a human out of an
+//     app, which is a human blast radius rather than a throttle.
+// There is deliberately NO second rule. An earlier version carried `^GET /tokeninfo` at the DEFAULT
+// weight "so the rule exists to be found and re-priced" — but a rule whose weight equals the default
+// changes nothing and CANNOT BE PINNED: delete it and every assertion about it still passes, because
+// the fallback returns the same number (§9 round two). A rule no test can lose is not a rule; if
+// tokeninfo ever needs a different price, the rule arrives WITH the number that makes it testable.
+import { declareRateBudget, rateBudgetPath, rateBudgetWeight, RateBudget, } from '@volter/world-core';
+const VENDOR = 'googleoauth';
+/** Rolling window, in ms. Spend older than this is pruned. */
+export const GOOGLEOAUTH_BUDGET_WINDOW_MS = 60_000;
+/**
+ * Weighted units allowed inside one window. 60/60s = 30 calls a minute at the default weight —
+ * EXACTLY the kernel fallback's burst, because Google publishes no rate this could be measured
+ * against. See the header.
+ */
+export const GOOGLEOAUTH_BUDGET_CEILING = 60;
+/** Seconds. A `Retry-After` above this means the client is throttled hard — fail loudly, don't sleep. */
+export const GOOGLEOAUTH_BUDGET_MAX_RETRY_AFTER_S = 300;
+/** Per-call cost, keyed by `"<METHOD> <path>"`. See the header for what is judged vs. documented. */
+export const GOOGLEOAUTH_CALL_WEIGHTS = {
+    /** `POST /revoke` — destroys a whole grant on a REAL account. The only destructive call here. */
+    revoke: 10,
+    /** Everything else: discovery, certs, userinfo, tokeninfo. */
+    other: 2,
+};
+/** THE PACK'S DECLARATION — pure data, the only Google-specific thing in the whole budget. */
+export const GOOGLEOAUTH_RATE_BUDGET = {
+    windowMs: GOOGLEOAUTH_BUDGET_WINDOW_MS,
+    ceiling: GOOGLEOAUTH_BUDGET_CEILING,
+    defaultWeight: GOOGLEOAUTH_CALL_WEIGHTS.other,
+    maxRetryAfterSeconds: GOOGLEOAUTH_BUDGET_MAX_RETRY_AFTER_S,
+    rules: [{ match: '^POST /revoke$', weight: GOOGLEOAUTH_CALL_WEIGHTS.revoke }],
+    reason: 'Google publishes NO scalar per-minute rate limit for its OAuth 2.0 / OIDC endpoints '
+        + '(accounts.google.com, oauth2.googleapis.com, www.googleapis.com/oauth2/*). What it does '
+        + 'publish for this surface is quota of a different SHAPE — per-user/per-client TOKEN COUNTS, '
+        + 'not a request rate: at most 100 refresh tokens per Google Account per OAuth client (the '
+        + '101st silently invalidates the oldest), a 7-day refresh-token expiry for apps still in '
+        + 'testing status, and a per-client cap on unexpired refresh tokens '
+        + '(developers.google.com/identity/protocols/oauth2, "Refresh token expiration"). A token-count '
+        + 'cap cannot anchor a rolling-window rate, so this declaration does NOT claim it does and does '
+        + "NOT out-burst the kernel's undeclared fallback: 60 weighted units / 60s at defaultWeight 2 is "
+        + '30 calls a minute, exactly the fallback. POST /revoke costs 10 (it destroys the WHOLE grant '
+        + 'on a real account — every access and refresh token for that client+user — which is a human '
+        + 'blast radius, not a throttle). It is the ONLY rule: a rule at the default weight changes no '
+        + 'price and cannot be pinned by any test, so there is none. That price is a judgement call, not '
+        + 'a published cost. The window bounds the 60s AVERAGE and does not pace; the 429 / Retry-After '
+        + 'cooldown is the backstop for a sub-second burst.',
+};
+// Declared at module load, so merely importing this module (which `googleoauth-connector.ts` does)
+// is enough to arm the real ceiling.
+declareRateBudget(VENDOR, GOOGLEOAUTH_RATE_BUDGET);
+/**
+ * Price one call. The key is `"<METHOD> <path>"` with the query string split off. NORMALIZED
+ * (upper-cased method, collapsed trailing slash) because the anchored rules are otherwise trivially
+ * evaded by input variation: `fetch` upper-cases a known method before sending, so
+ * `execute('post', '/revoke')` really does issue the destructive call and must be priced as one.
+ */
+export function googleOAuthCallWeight(method, path) {
+    const { bare, query } = splitQuery(path);
+    return rateBudgetWeight(VENDOR, `${String(method).toUpperCase()} ${bare}`, query);
+}
+function splitQuery(path) {
+    const at = path.indexOf('?');
+    const query = {};
+    if (at !== -1)
+        for (const [k, v] of new URLSearchParams(path.slice(at + 1)))
+            query[k] = v;
+    const raw = at === -1 ? path : path.slice(0, at);
+    const bare = raw.length > 1 && raw.endsWith('/') ? raw.replace(/\/+$/, '') : raw;
+    return { bare, query };
+}
+/** Where this vendor's ledger lives. Token-keyed and cwd-independent by default; pass `root` to opt
+ *  into world-scoped accounting. */
+export function googleOAuthBudgetPath(opts = {}) {
+    const o = typeof opts === 'string' ? { root: opts } : opts;
+    // VENDOR spread LAST: a loosely-typed `{ vendor: 'other', … }` slipping through (TypeScript's
+    // excess-property check only catches object literals) must not redirect this pack's ledger.
+    return rateBudgetPath({ ...o, vendor: VENDOR });
+}
+/**
+ * This vendor's budget — the shared kernel guard bound to this declaration. A real subclass, not an
+ * alias, so `budget instanceof GoogleOAuthBudget` means "a budget that accounts against
+ * GOOGLEOAUTH's ledger under GOOGLEOAUTH's ceiling": another vendor's `RateBudget` (with its own,
+ * possibly larger, ceiling) is NOT assignable there.
+ */
+export class GoogleOAuthBudget extends RateBudget {
+    constructor(opts = {}) {
+        super({ ...opts, vendor: VENDOR });
+    }
+}
+export { RateBudgetError as GoogleOAuthBudgetError } from '@volter/world-core';

package/dist/src/googleoauth-capabilities.d.ts

@@ -0,0 +1,3 @@
+import { type CapabilityReport, type CapabilitySpec } from '@volter/world-tooling';
+export declare const GOOGLEOAUTH_CAPABILITIES: CapabilitySpec[];
+export declare function googleoauthCapabilities(): Promise<CapabilityReport>;