cursedbelt-server 4.13.0 → 4.14.0

package/dist/server/google-oauth/googleOAuth.js

@@ -0,0 +1,465 @@
+/**
+ * `cursedbelt-server/google-oauth` — the ONE Google OAuth implementation in this generation:
+ * consent URL, authorization-code exchange, refresh-token exchange, revocation, credential
+ * reading from env + a 0600 env file, a cached access-token minter, a live credential probe
+ * and the 403-to-remedy sentence.
+ *
+ * ── Why it is here ──────────────────────────────────────────────────────────
+ * Two apps held byte-for-byte copies of it (task 099, census entry 407), one of which had
+ * already forked ahead of the other with the credential-resolution half. Two copies of a
+ * credential parser are two answers to "which env keys are canonical", and the drift costs a
+ * sign-in. This file is the union of both, with the stricter body wherever they differed.
+ *
+ * ── Nothing here knows who is calling ───────────────────────────────────────
+ * No app name, no hostname, no secrets path, no env-file location and no scope list is
+ * baked in. The caller supplies the secrets file, the env-var names it accepts
+ * ({@link CredentialKeys}), the label a failure sentence names and the remedy it offers.
+ *
+ * ── Two ways a refresh token arrives, one exchange ──────────────────────────
+ *   · {@link readGoogleCredentials} + {@link createGoogleTokenMinter} serve a consumer whose
+ *     refresh token is a 0600 file on the machine, minted once by hand.
+ *   · {@link buildConsentUrl} + {@link exchangeAuthCode} serve a consumer that obtains the
+ *     refresh token AT RUNTIME from a browser consent and stores it itself. Feed it straight
+ *     back in — `createGoogleTokenMinter({ credentials })` — so a consenting app still has
+ *     exactly one `grant_type=refresh_token` POST.
+ *
+ * ── Failure is always LOUD, and never a secret ──────────────────────────────
+ * Every failure is a typed result carrying the exact remedy; nothing here throws. A
+ * credential that cannot be read, a token Google refuses, or a scope that was never granted
+ * must NEVER look like "nothing to report". No credential value is ever logged, returned in
+ * an error string, or thrown — Google's `error_description` is echoed because it describes
+ * the REQUEST, never the secret.
+ *
+ * ── A leaf ──────────────────────────────────────────────────────────────────
+ * One file, node builtins only, listed in `leafSubpathsImportNothing.spec.ts`. It is one file
+ * on purpose: the leaf fixture copies exactly the exported file, so a sibling import would be
+ * a red, and a single module cannot have the import cycle the old three-file split existed to
+ * avoid.
+ */
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+// ─── Endpoints ───────────────────────────────────────────────────────────────
+export const GOOGLE_TOKEN_ENDPOINT = 'https://oauth2.googleapis.com/token';
+export const GOOGLE_AUTH_ENDPOINT = 'https://accounts.google.com/o/oauth2/v2/auth';
+export const GOOGLE_REVOKE_ENDPOINT = 'https://oauth2.googleapis.com/revoke';
+/** `process.env` where there is a `process`; an empty env where there is not. */
+const ambientEnv = () => (typeof process !== 'undefined' ? process.env : {});
+// ─── Env-file reading ────────────────────────────────────────────────────────
+/** `~/x` → `<home>/x`. Anything else is returned unchanged. */
+export const expandTilde = (p) => p.startsWith('~/') ? path.join(homedir(), p.slice(2)) : p;
+/**
+ * Parse a `KEY=value` env file, tolerating quotes, blanks, `export`, `#` comments and CRLF.
+ *
+ * 🔴 CRLF is split on, not trimmed afterwards. Both app copies split on `\n` alone, and `.`
+ * does not match `\r`, so `(.*)$` failed on EVERY line of a CRLF file: a secrets file saved by
+ * a Windows editor parsed to `{}` and read as "no credential on this machine" — `unconfigured`,
+ * with the setup remedy, for a file that held all three values. Pinned in the spec.
+ */
+export function parseEnvFile(text) {
+    const out = {};
+    for (const line of text.split(/\r?\n/)) {
+        if (/^\s*#/.test(line))
+            continue;
+        const m = /^\s*(?:export\s+)?([A-Z0-9_]+)\s*=\s*(.*)$/.exec(line);
+        if (m?.[1])
+            out[m[1]] = (m[2] ?? '').trim().replace(/^["']|["']$/g, '');
+    }
+    return out;
+}
+/** The parsed secrets file, or `{}` when there is none or it cannot be read. Never throws. */
+const readEnvFile = (secretsFile) => {
+    if (!secretsFile)
+        return {};
+    try {
+        return parseEnvFile(readFileSync(expandTilde(secretsFile), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+};
+/** Read any other key — env first, then the same secrets file (an API key, an address). */
+export function readSecret(name, options = {}) {
+    const fromEnv = (options.env ?? ambientEnv())[name]?.trim();
+    if (fromEnv)
+        return fromEnv;
+    return readEnvFile(options.secretsFile)[name]?.trim() ?? '';
+}
+export const CANONICAL_CREDENTIAL_KEYS = {
+    clientId: ['GOOGLE_OAUTH_CLIENT_ID'],
+    clientSecret: ['GOOGLE_OAUTH_CLIENT_SECRET'],
+    refreshToken: ['GOOGLE_OAUTH_REFRESH_TOKEN'],
+};
+/**
+ * Read a Google OAuth credential AND report which names carried it.
+ *
+ * Precedence: env overrides the secrets file, and earlier key names override later aliases.
+ */
+export function resolveGoogleCredentials(options = {}) {
+    const env = options.env ?? ambientEnv();
+    const keys = options.keys ?? CANONICAL_CREDENTIAL_KEYS;
+    const fromFile = readEnvFile(options.secretsFile);
+    const read = (names) => {
+        let used = null;
+        let value = '';
+        const shadowed = [];
+        for (const n of names) {
+            const fromEnv = env[n]?.trim();
+            const v = fromEnv || fromFile[n]?.trim();
+            if (!v)
+                continue;
+            // The FIRST name that has a value wins. The rest are recorded rather than discarded —
+            // that list is the whole diagnosis when Google refuses the winner.
+            if (used === null) {
+                used = { name: n, from: fromEnv ? 'env' : 'file' };
+                value = v;
+            }
+            else {
+                shadowed.push(n);
+            }
+        }
+        return { value, used, shadowed };
+    };
+    const clientId = read(keys.clientId);
+    const clientSecret = read(keys.clientSecret);
+    const refreshToken = read(keys.refreshToken);
+    const complete = Boolean(clientId.value && clientSecret.value && refreshToken.value);
+    return {
+        credentials: complete
+            ? { clientId: clientId.value, clientSecret: clientSecret.value, refreshToken: refreshToken.value }
+            : null,
+        used: { clientId: clientId.used, clientSecret: clientSecret.used, refreshToken: refreshToken.used },
+        shadowed: {
+            clientId: clientId.shadowed,
+            clientSecret: clientSecret.shadowed,
+            refreshToken: refreshToken.shadowed,
+        },
+        missing: [
+            ...(clientId.used ? [] : keys.clientId),
+            ...(clientSecret.used ? [] : keys.clientSecret),
+            ...(refreshToken.used ? [] : keys.refreshToken),
+        ],
+    };
+}
+/**
+ * Read a Google OAuth credential — env overriding the secrets file, and earlier key names
+ * overriding later aliases.
+ *
+ * Returns null when any of the three is missing. A PARTIAL credential is the same as none:
+ * two of three cannot mint a token, and treating it as present would turn a setup mistake
+ * into an `unavailable` ("Google refused it") instead of the `unconfigured` ("you have not
+ * finished setting it up") that names the real fix.
+ */
+export function readGoogleCredentials(options = {}) {
+    return resolveGoogleCredentials(options).credentials;
+}
+/** The URL to send the browser to. Pure — no network, so a caller can test its own wiring. */
+export function buildConsentUrl(options) {
+    const params = new URLSearchParams({
+        client_id: options.clientId,
+        redirect_uri: options.redirectUri,
+        response_type: 'code',
+        scope: options.scopes.join(' '),
+        // Without `offline` Google issues no refresh token at all and the grant dies with the
+        // first access token.
+        access_type: 'offline',
+        include_granted_scopes: 'true',
+        prompt: options.prompt ?? 'consent',
+        state: options.state,
+    });
+    return `${GOOGLE_AUTH_ENDPOINT}?${params.toString()}`;
+}
+/**
+ * The one POST to Google's token endpoint, whichever grant is being exercised.
+ *
+ * Both grants send form-encoded parameters to the same URL and get back the same body shape,
+ * so they share a reader. What differs is the SENTENCE a failure produces, which is why the
+ * remedies are parameters.
+ */
+async function postTokenRequest(params, options) {
+    const doFetch = options.fetchImpl ?? fetch;
+    let res;
+    try {
+        res = await doFetch(GOOGLE_TOKEN_ENDPOINT, {
+            method: 'POST',
+            headers: { 'content-type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams(params).toString(),
+            signal: AbortSignal.timeout(options.timeoutMs ?? 30_000),
+        });
+    }
+    catch (err) {
+        return {
+            status: 'unavailable',
+            cause: 'transport',
+            reason: `could not reach Google to ${options.what}: ${err instanceof Error ? err.message : String(err)}`,
+            fix: "check this machine's internet connection and try again",
+        };
+    }
+    /**
+     * 🔴 A parse failure must NEVER mask a refusal. Google answers a revoked refresh token with
+     * a 400 whose body is sometimes not JSON at all, and reporting that as "the response was
+     * not JSON" sends the owner looking at a transport problem for what is a re-consent. So the
+     * STATUS is read first and the body is only ever a source of detail.
+     */
+    const body = (await res.json().catch(() => null));
+    if (!res.ok || typeof body?.access_token !== 'string' || body.access_token.length === 0) {
+        const detail = (typeof body?.error_description === 'string' && body.error_description) ||
+            (typeof body?.error === 'string' && body.error) ||
+            `HTTP ${res.status}`;
+        return res.ok && body === null
+            ? {
+                status: 'unavailable',
+                cause: 'transport',
+                reason: "Google's token response was not JSON",
+                fix: 'try again; this is almost always transient',
+            }
+            : {
+                status: 'unavailable',
+                cause: 'refused',
+                reason: `Google refused the request: ${detail}`,
+                fix: options.refusalFix,
+            };
+    }
+    return {
+        status: 'ok',
+        accessToken: body.access_token,
+        ...(typeof body.refresh_token === 'string' && body.refresh_token ? { refreshToken: body.refresh_token } : {}),
+        expiresInSeconds: typeof body.expires_in === 'number' ? body.expires_in : 3600,
+        grantedScopes: typeof body.scope === 'string' ? body.scope.split(/\s+/).filter(Boolean) : [],
+    };
+}
+/** Trade the `?code=` Google sent to the callback for tokens. */
+export function exchangeAuthCode(options) {
+    return postTokenRequest({
+        code: options.code,
+        client_id: options.clientId,
+        client_secret: options.clientSecret,
+        redirect_uri: options.redirectUri,
+        grant_type: 'authorization_code',
+    }, {
+        ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
+        ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+        what: 'exchange the consent code',
+        // `invalid_grant` here almost always means the code was already used or the
+        // redirect_uri does not match the one registered.
+        refusalFix: "confirm this app's redirect URI is listed on the OAuth client, then press Connect again",
+    });
+}
+/**
+ * Trade a stored refresh token for a fresh access token, REPORTING ITS LIFETIME.
+ *
+ * The uncached half of {@link createGoogleTokenMinter}, exported because a consumer that
+ * PERSISTS the access token has to know when it dies — a caller that guesses an hour is a
+ * caller whose token is occasionally already dead when it is used.
+ */
+export function refreshAccessToken(options) {
+    return postTokenRequest({
+        client_id: options.clientId,
+        client_secret: options.clientSecret,
+        refresh_token: options.refreshToken,
+        grant_type: 'refresh_token',
+    }, {
+        ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
+        ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+        what: 'refresh the access token',
+        refusalFix: options.refusalFix ?? 'the refresh token may have been revoked — re-run consent',
+    });
+}
+/**
+ * Best-effort revocation on disconnect. NEVER throws and never reports failure as a blocker:
+ * the local record is deleted either way, and a disconnect that refuses because Google was
+ * unreachable leaves the owner holding a connection they asked to end. Google having already
+ * forgotten the token answers 400, which is the same outcome as success from here — `false`
+ * says only "Google did not confirm it".
+ */
+export async function revokeGoogleToken(token, options = {}) {
+    if (!token)
+        return false;
+    const doFetch = options.fetchImpl ?? fetch;
+    try {
+        const res = await doFetch(GOOGLE_REVOKE_ENDPOINT, {
+            method: 'POST',
+            headers: { 'content-type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({ token }).toString(),
+            signal: AbortSignal.timeout(options.timeoutMs ?? 15_000),
+        });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+const DEFAULT_LABEL = 'this app';
+const DEFAULT_SETUP_FIX = 're-run the one-time Google consent for this app';
+/** A token is never handed out so close to expiry that the call it is used for could land after it dies. */
+const EXPIRY_MARGIN_MS = 60_000;
+/**
+ * A short-lived access token, cached in memory until {@link EXPIRY_MARGIN_MS} before it
+ * expires.
+ *
+ * The refresh token is exchanged on demand rather than held as a long-lived bearer, and the
+ * cache exists because one caller makes several calls across several APIs — minting per call
+ * would make the caller's latency proportional to its call count.
+ */
+export function createGoogleTokenMinter(options = {}) {
+    const timeout = options.timeoutMs ?? 30_000;
+    const now = options.now ?? Date.now;
+    const label = options.label ?? DEFAULT_LABEL;
+    const fix = options.setupFix ?? DEFAULT_SETUP_FIX;
+    let cached = null;
+    const mint = async () => {
+        const creds = options.credentials !== undefined
+            ? options.credentials
+            : readGoogleCredentials({ env: options.env, secretsFile: options.secretsFile, keys: options.keys });
+        if (!creds) {
+            return {
+                status: 'unconfigured',
+                reason: `no Google OAuth credential for ${label} is on this machine yet`,
+                fix,
+            };
+        }
+        const refreshed = await refreshAccessToken({
+            clientId: creds.clientId,
+            clientSecret: creds.clientSecret,
+            refreshToken: creds.refreshToken,
+            ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
+            timeoutMs: timeout,
+            refusalFix: fix,
+        });
+        if (refreshed.status !== 'ok')
+            return refreshed;
+        cached = {
+            accessToken: refreshed.accessToken,
+            scopes: refreshed.grantedScopes,
+            expiresAt: now() + Math.max(0, refreshed.expiresInSeconds * 1000 - EXPIRY_MARGIN_MS),
+        };
+        return { status: 'ok', accessToken: cached.accessToken, grantedScopes: cached.scopes };
+    };
+    // Closures, not `this`: `const { token } = minter` must keep working.
+    const token = async () => {
+        if (cached && now() < cached.expiresAt) {
+            return { status: 'ok', accessToken: cached.accessToken, grantedScopes: cached.scopes };
+        }
+        return await mint();
+    };
+    return {
+        token,
+        async grantedScopes() {
+            const t = await token();
+            return t.status === 'ok' ? t.grantedScopes : [];
+        },
+        invalidate() {
+            cached = null;
+        },
+    };
+}
+/**
+ * 🔴 EXCHANGE the credential rather than assuming a present value is a working one.
+ *
+ * `readGoogleCredentials` cannot tell a dead value from a live one, because "present" is all
+ * it ever asked. The probe does the one thing that answers the question: a real
+ * `grant_type=refresh_token` POST, reported with the NAME it used and the names it shadowed.
+ * It is safe to run at boot — it mints a short-lived access token, drops it, and never throws.
+ */
+export async function probeCredentialExchange(options = {}) {
+    const label = options.label ?? DEFAULT_LABEL;
+    const setupFix = options.setupFix ?? DEFAULT_SETUP_FIX;
+    // A caller that supplied the credential directly has no names to report, and must not be
+    // told about env vars it never read.
+    const supplied = options.credentials !== undefined;
+    const resolution = supplied
+        ? null
+        : resolveGoogleCredentials({ env: options.env, secretsFile: options.secretsFile, keys: options.keys });
+    const credentials = supplied ? (options.credentials ?? null) : (resolution?.credentials ?? null);
+    const refreshTokenName = resolution?.used.refreshToken?.name ?? '';
+    const shadowed = resolution?.shadowed.refreshToken ?? [];
+    if (!credentials) {
+        const missing = resolution?.missing ?? [];
+        return {
+            status: 'unconfigured',
+            refreshTokenName,
+            shadowedRefreshTokenNames: shadowed,
+            grantedScopes: [],
+            summary: `no Google OAuth credential for ${label} is on this machine yet` +
+                (missing.length > 0 ? ` — nothing supplies ${missing.join(' or ')}` : ''),
+            fix: setupFix,
+        };
+    }
+    const refreshed = await refreshAccessToken({
+        clientId: credentials.clientId,
+        clientSecret: credentials.clientSecret,
+        refreshToken: credentials.refreshToken,
+        ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
+        timeoutMs: options.timeoutMs ?? 30_000,
+        refusalFix: setupFix,
+    });
+    // The name is on BOTH outcomes on purpose. A green probe that does not say which of two
+    // spellings it proved is a green probe that proves nothing about the other one.
+    const used = refreshTokenName ? ` using ${refreshTokenName}` : '';
+    const one = shadowed.length === 1;
+    if (refreshed.status === 'ok') {
+        const alsoSet = shadowed.length > 0
+            ? ` ${shadowed.join(' and ')} also hold${one ? 's' : ''} a value for the same credential and ${one ? 'is' : 'are'} never reached.`
+            : '';
+        return {
+            status: 'ok',
+            refreshTokenName,
+            shadowedRefreshTokenNames: shadowed,
+            grantedScopes: refreshed.grantedScopes,
+            summary: `Google exchanged ${label}'s refresh token${used} — ${refreshed.grantedScopes.length} scope(s) granted.${alsoSet}`,
+            fix: '',
+        };
+    }
+    // A machine that could not reach Google has proved nothing about the credential, and must
+    // not be reported as though it had.
+    if (refreshed.cause === 'transport') {
+        return {
+            status: 'unreachable',
+            refreshTokenName,
+            shadowedRefreshTokenNames: shadowed,
+            grantedScopes: [],
+            summary: `${refreshed.reason} — ${label}'s credential was NOT tested, so this says nothing about whether it works.`,
+            fix: refreshed.fix,
+        };
+    }
+    // 🔴 "The grant has been revoked" is the WRONG diagnosis when a second, untried value for
+    // the same credential is sitting in the same file.
+    const alsoUntried = shadowed.length > 0
+        ? ` ${shadowed.join(' and ')} also hold${one ? 's' : ''} a value for the same credential and ${one ? 'was' : 'were'} never tried.`
+        : '';
+    return {
+        status: 'refused',
+        refreshTokenName,
+        shadowedRefreshTokenNames: shadowed,
+        grantedScopes: [],
+        summary: `${refreshed.reason}${used} — ${label}'s Google calls will all fail until this is fixed.${alsoUntried}`,
+        fix: shadowed.length > 0
+            ? `Before re-consenting, check whether ${shadowed.join(' or ')} holds the live grant: the preferred name ${refreshTokenName} wins by being PRESENT, not by working. Leaving exactly one of those names set resolves it either way. Otherwise: ${setupFix}`
+            : setupFix,
+    };
+}
+// ─── 403 → remedy ────────────────────────────────────────────────────────────
+/**
+ * Turn a Google 403 into something the owner can act on.
+ *
+ * A missing scope is the single most likely failure after the owner consents once and the app
+ * later grows a capability. Naming the MISSING scope and the re-consent command is the
+ * difference between a two-minute fix and an evening.
+ *
+ * 🔴 The two branches say genuinely different things: `ACCESS_TOKEN_SCOPE_INSUFFICIENT` is a
+ * consent problem fixed in a browser, while a 403 on a granted scope is an API that is not
+ * ENABLED on the project, fixed in a different console page entirely.
+ */
+export function describeScopeFailure(options) {
+    const has = options.granted.includes(options.needed);
+    if (!has && options.granted.length > 0) {
+        return {
+            reason: `${options.api} refused the call (HTTP ${options.httpStatus}): the grant on this machine does NOT include ${options.needed}. It has: ${options.granted.join(', ')}`,
+            fix: `run ${options.consentCommand} and approve ${options.needed}. The existing token keeps working for everything it already covers, so nothing else breaks while you do it.`,
+        };
+    }
+    return {
+        reason: `${options.api} refused the call (HTTP ${options.httpStatus}) even though ${options.needed} appears to be granted — the API may be disabled for this Google Cloud project`,
+        fix: `open Google Cloud Console → APIs and Services → Library and confirm the ${options.api} API is ENABLED for the project that owns this OAuth client`,
+    };
+}

package/dist/server/guard/passwordVerifier.d.ts

@@ -14,7 +14,7 @@ export declare function sealPasswordVerifier(userId: string, password: Uint8Arra
  * stored envelope is corruption, not a wrong password, and re-throws.
  *
  * The comparison is constant-time in the sensitive part: argon2id derivation
- * dominates the timing, and GCM tag verification plus the final `timingSafeEqual`
+ * dominates the timing, and GCM tag verification plus the final `constantTimeEqualBytes`
  * are constant-time, so a right and a wrong password of equal length are
  * indistinguishable by timing.
  */

package/dist/server/guard/passwordVerifier.js

@@ -29,7 +29,7 @@
  *     every path including a thrown KDF. Callers hand over ownership and must not
  *     touch the buffer afterwards.
  */
-import { timingSafeEqual } from 'node:crypto';
+import { constantTimeEqualBytes } from 'cwip/constant-time';
 import { createSecretEnvelopeManager, mintEnvelopeSalt, parseSecretEnvelope, serializeSecretEnvelope, zeroize, } from 'cwip/guard';
 import { isAppError } from '../errors.js';
 /**
@@ -68,7 +68,7 @@ export function sealPasswordVerifier(userId, password, deriver) {
  * stored envelope is corruption, not a wrong password, and re-throws.
  *
  * The comparison is constant-time in the sensitive part: argon2id derivation
- * dominates the timing, and GCM tag verification plus the final `timingSafeEqual`
+ * dominates the timing, and GCM tag verification plus the final `constantTimeEqualBytes`
  * are constant-time, so a right and a wrong password of equal length are
  * indistinguishable by timing.
  */
@@ -90,7 +90,7 @@ export function verifyPasswordEnvelope(userId, envelopeJson, password, deriver)
         // openWithPassphrase re-derives a one-shot key from the envelope's own salt +
         // the presented password, opens, and zeroizes `password` on every path.
         opened = manager.openWithPassphrase(envelope, refFor(userId), password);
-        return opened.byteLength === VERIFIER_PLAINTEXT.byteLength && timingSafeEqual(opened, VERIFIER_PLAINTEXT);
+        return constantTimeEqualBytes(opened, VERIFIER_PLAINTEXT);
     }
     catch (error) {
         // GCM's rejection is the wrong-password verdict — the ONLY error we swallow.

package/dist/server/sync/tokens.d.ts

@@ -4,7 +4,7 @@
  * per capability, sha256 at rest so a database read never yields a usable credential).
  *
  * The plaintext token is returned exactly once, at mint. Verification compares sha256
- * digests via `timingSafeEqual` — length-independent, no oracle.
+ * digests via cwip's `constantTimeEqualBytes` — no length guard, no early exit.
  */
 import type { Database } from "bun:sqlite";
 export interface DeviceToken {

package/dist/server/sync/tokens.js

@@ -1,4 +1,5 @@
-import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
+import { constantTimeEqualBytes } from "cwip/constant-time";
 const sha256 = (value) => createHash("sha256").update(value).digest();
 export function createTokenStore(db) {
     db.exec(`
@@ -35,7 +36,7 @@ export function createTokenStore(db) {
             // the lookup timing depend on the presented value.
             for (const raw of allLive.all()) {
                 const want = Buffer.from(raw.token_sha256);
-                if (want.length === got.length && timingSafeEqual(want, got)) {
+                if (constantTimeEqualBytes(want, got)) {
                     if (raw.scope !== scope)
                         return null;
                     return toToken(raw);

package/package.json

@@ -1,9 +1,9 @@
 {
 	"name": "cursedbelt-server",
-	"version": "4.13.0",
+	"version": "4.14.0",
 	"license": "ISC",
 	"type": "module",
-	"description": "The app-facing Bun/Hono server tier of the cursedbelt split \u2014 storage, sharing, activity, guard, sync. React-free; cursedbelt-core below it.",
+	"description": "The app-facing Bun/Hono server tier of the cursedbelt split — storage, sharing, activity, guard, sync. React-free; cursedbelt-core below it.",
 	"cursed": {
 		"schemaVersion": 1,
 		"app": {
@@ -21,6 +21,7 @@
 		"test": "NODE_ENV=development bun test src",
 		"build": "bun run clean && tsc -p tsconfig.build.json",
 		"paths": "bun run scripts/paths.ts",
+		"surface": "public-surface",
 		"verify": "bun run paths && bun run typecheck && bun run build && bun run test",
 		"prepublishOnly": "bun run verify",
 		"test:pg": "bun run scripts/testPg.ts"
@@ -114,6 +115,12 @@
 			"source": "./src/server/errors.ts",
 			"import": "./dist/server/errors.js"
 		},
+		"./google-oauth": {
+			"types": "./dist/server/google-oauth/googleOAuth.d.ts",
+			"bun": "./src/server/google-oauth/googleOAuth.ts",
+			"source": "./src/server/google-oauth/googleOAuth.ts",
+			"import": "./dist/server/google-oauth/googleOAuth.js"
+		},
 		"./guard": {
 			"types": "./dist/server/guard/index.d.ts",
 			"bun": "./src/server/guard/index.ts",
@@ -276,7 +283,8 @@
 		"@node-rs/argon2": "^2.0.2",
 		"@types/bun": "^1.3.14",
 		"@types/node": "^24",
-		"cursedbelt": "^4.1.1",
+		"cursedbelt": "^4.5.0",
+		"cursedops": "^0.2.7",
 		"hono": "4.12.28",
 		"kysely": "^0.28.17",
 		"kysely-bun-sqlite": "^0.4.0",

package/src/leafSubpathsImportNothing.spec.ts

@@ -151,6 +151,16 @@ const LEAVES = [
      */
     evaluates: 'readBoundedJson',
   },
+  {
+    subpath: './google-oauth',
+    /**
+     * Google OAuth — consent URL, code exchange, refresh, revoke, the cached minter and the
+     * credential probe. Arrived in 4.14.0 from two app-side copies (task 099). Its promise is
+     * `node:fs`/`node:os`/`node:path` and nothing else: it is ONE file precisely so this
+     * fixture, which copies only the exported file, can prove it reaches no sibling either.
+     */
+    evaluates: 'createGoogleTokenMinter',
+  },
 ] as const;
 
 /**

package/src/publicSurface.spec.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'bun:test';
-import { run } from '../scripts/publicSurface.js';
+import { dirname } from 'node:path';
+import { run } from 'cursedops/public-surface';
 
 /**
  * The public-surface ratchet, wired into `bun run verify` at its cheapest correct
@@ -8,10 +9,15 @@ import { run } from '../scripts/publicSurface.js';
  *
  * WHY it exists, WHAT a symbol count includes and excludes, why the dependency list
  * and the used-vs-exported ratio are deliberately NOT computed here, and what
- * `--prune` may and may not do are all in the header of `scripts/publicSurface.ts` —
+ * `--prune` may and may not do are all in the header of `cursedops/src/publicSurface.ts` —
  * one check, one baseline (`publicSurface.baseline`), one place that explains itself.
  * This file is only the wiring.
  *
+ * Since 2026-09-22 (task 084) the measurement is ONE body, `cursedops/public-surface`, a
+ * devDependency: this package's own `scripts/publicSurface.ts` had forked from the other
+ * two libraries' copies. `bun run surface [--prune]` is the CLI. The probes below were
+ * run against that former copy; the shared body measured identical per-subpath counts.
+ *
  * 🔴 Verified failing, 2026-09-19, before it was trusted — every branch, not just the
  * easy one. Each probe was applied, observed, and removed again:
  *
@@ -48,11 +54,13 @@ import { run } from '../scripts/publicSurface.js';
  *       → "refuses: … already records 34 subpath(s)", exit 1
  *
  * Every probe was reverted with `git checkout -- <path>`; the tree afterwards held only
- * this file, `scripts/publicSurface.ts` and `publicSurface.baseline`.
+ * this file, the then `scripts/publicSurface.ts` and `publicSurface.baseline`.
  *
  * A ratchet nobody has seen red is a ratchet nobody knows is wired up.
  */
-const result = await run();
+// The package this spec lives in — resolved from this file, never from `process.cwd()`,
+// because `bun test` can be started from anywhere.
+const result = await run({ root: dirname(import.meta.dir) });
 
 describe('public surface', () => {
 	it('has measured a real surface', () => {
@@ -82,7 +90,7 @@ describe('public surface', () => {
 		// behind for the next one to grow into.
 		expect(
 			result.stale,
-			`surface came off and the ratchet was not tightened — run \`bun scripts/publicSurface.ts --prune\`:\n  ${result.stale.join('\n  ')}`,
+			`surface came off and the ratchet was not tightened — run \`bun run surface --prune\`:\n  ${result.stale.join('\n  ')}`,
 		).toEqual([]);
 	});
 });

package/src/server/auth/password.ts

@@ -1,4 +1,5 @@
-import { pbkdf2 as pbkdf2Cb, timingSafeEqual } from 'node:crypto';
+import { pbkdf2 as pbkdf2Cb } from 'node:crypto';
+import { constantTimeEqual } from 'cwip/constant-time';
 import { promisify } from 'node:util';
 
 /**
@@ -55,10 +56,8 @@ export async function verifyPassword(plain: string, stored: string): Promise<boo
   const derived = (
     await pbkdf2(plain, salt, LEGACY_ITERATIONS, LEGACY_KEYLEN, LEGACY_DIGEST)
   ).toString('hex');
-  // timingSafeEqual throws on length mismatch; a length diff is already a non-match
-  // and short-circuiting leaks nothing a compare wouldn't.
-  if (derived.length !== expectedHex.length) return false;
-  return timingSafeEqual(Buffer.from(derived), Buffer.from(expectedHex));
+  // cwip's fold: no length guard to own, no early exit (task 322).
+  return constantTimeEqual(derived, expectedHex);
 }
 
 /**