cursedbelt-server 4.13.1 → 4.15.0

package/dist/server/d1/index.d.ts

@@ -16,7 +16,7 @@
  */
 export { type BackupPoint, createTimeTravelBackup, type DatabaseBackup, type TimeTravelOpts, } from './backup.js';
 export { createPendingWrites, type InvocationD1, type PendingWrites, perInvocation, type WriteCollector } from './invocation.js';
-export { assertBatchSize, assertWithinLimits, chunkForBind, LIMITS } from './limits.js';
+export { assertBatchSize, assertWithinLimits, chunkForBind, inArray, LIMITS } from './limits.js';
 export { createLocalD1, refuseInteractiveTransaction } from './local.js';
 export { createRemoteD1, type D1BindingLike, type D1BindingMeta, type D1BindingResult, type D1BindingStatement, } from './remote.js';
 export { classifySchedule, cronFieldCount, jobsForCron, type PortableJob, type PortableJobContext, type ScheduleVerdict, toCronTriggers, toFiveField, type TriggerShape, type WorkersPrimitive, } from './scheduling.js';

package/dist/server/d1/index.js

@@ -34,7 +34,7 @@ export { createTimeTravelBackup, } from './backup.js';
 // of them, since business tables stay on raw statements. Measured 2026-09-18 against the
 // published 4.3.0 tarball. `barrelsReachNoOptionalPeer.spec.ts` is what keeps it out.
 export { createPendingWrites, perInvocation } from './invocation.js';
-export { assertBatchSize, assertWithinLimits, chunkForBind, LIMITS } from './limits.js';
+export { assertBatchSize, assertWithinLimits, chunkForBind, inArray, LIMITS } from './limits.js';
 export { createLocalD1, refuseInteractiveTransaction } from './local.js';
 export { createRemoteD1, } from './remote.js';
 export { classifySchedule, cronFieldCount, jobsForCron, toCronTriggers, toFiveField, } from './scheduling.js';

package/dist/server/d1/limits.d.ts

@@ -54,3 +54,34 @@ export declare function assertBatchSize(count: number): void;
  * ```
  */
 export declare function chunkForBind<T>(items: readonly T[], paramsPerItem: number): T[][];
+/**
+ * `column IN (…)` over a list of ANY length, as ONE bound parameter.
+ *
+ * ```ts
+ * const ids = inArray(itemIds);
+ * await db.prepare(`UPDATE items SET deleted_at = ? WHERE id ${ids.sql}`).bind(now, ids.param).run();
+ * ```
+ *
+ * 🔴 **Why this and not {@link chunkForBind} for a set of ids.** An `IN (?, ?, …)` built by
+ * `ids.map(() => '?')` binds one parameter per id, so it is green on every fixture and a 500 on
+ * the 101st id — the cap is asserted on both drivers, and real D1 enforces the same one.
+ * Chunking fixes a bulk INSERT, but it cannot fix a READ that must be one statement (a
+ * `WHERE … ORDER BY … LIMIT ? OFFSET ?` page and the `COUNT(*)` beside it), and on a write
+ * it trades one atomic statement for a batch that is atomic only per chunk. `json_each`
+ * over a JSON array is one parameter however long the list is, keeps the statement whole,
+ * and SQLite still drives the column's index through the materialised set.
+ *
+ * The array travels as one TEXT value, so the ceiling moves from 100 ids to
+ * `LIMITS.valueBytes` (2 MB) of JSON — about 70,000 of this fleet's 25-character ids — and
+ * past that `assertWithinLimits` refuses it at `bind()` with the byte count, on both drivers.
+ * An empty list is valid SQL and matches nothing, so no caller needs an `IN ()` special case.
+ *
+ * Only strings and finite numbers: `json_each` yields TEXT for a string and INTEGER/REAL for
+ * a number, which is what makes `id IN …` compare like `id = ?` would. Anything else would
+ * compare as something the caller did not write, so it is refused here rather than matched
+ * silently against nothing.
+ */
+export declare function inArray(values: readonly (string | number)[]): {
+    sql: string;
+    param: string;
+};

package/dist/server/d1/limits.js

@@ -94,3 +94,40 @@ export function chunkForBind(items, paramsPerItem) {
         out.push(items.slice(i, i + size));
     return out;
 }
+/**
+ * `column IN (…)` over a list of ANY length, as ONE bound parameter.
+ *
+ * ```ts
+ * const ids = inArray(itemIds);
+ * await db.prepare(`UPDATE items SET deleted_at = ? WHERE id ${ids.sql}`).bind(now, ids.param).run();
+ * ```
+ *
+ * 🔴 **Why this and not {@link chunkForBind} for a set of ids.** An `IN (?, ?, …)` built by
+ * `ids.map(() => '?')` binds one parameter per id, so it is green on every fixture and a 500 on
+ * the 101st id — the cap is asserted on both drivers, and real D1 enforces the same one.
+ * Chunking fixes a bulk INSERT, but it cannot fix a READ that must be one statement (a
+ * `WHERE … ORDER BY … LIMIT ? OFFSET ?` page and the `COUNT(*)` beside it), and on a write
+ * it trades one atomic statement for a batch that is atomic only per chunk. `json_each`
+ * over a JSON array is one parameter however long the list is, keeps the statement whole,
+ * and SQLite still drives the column's index through the materialised set.
+ *
+ * The array travels as one TEXT value, so the ceiling moves from 100 ids to
+ * `LIMITS.valueBytes` (2 MB) of JSON — about 70,000 of this fleet's 25-character ids — and
+ * past that `assertWithinLimits` refuses it at `bind()` with the byte count, on both drivers.
+ * An empty list is valid SQL and matches nothing, so no caller needs an `IN ()` special case.
+ *
+ * Only strings and finite numbers: `json_each` yields TEXT for a string and INTEGER/REAL for
+ * a number, which is what makes `id IN …` compare like `id = ?` would. Anything else would
+ * compare as something the caller did not write, so it is refused here rather than matched
+ * silently against nothing.
+ */
+export function inArray(values) {
+    for (const v of values) {
+        if (typeof v === 'string')
+            continue;
+        if (typeof v === 'number' && Number.isFinite(v))
+            continue;
+        throw new TypeError(`inArray takes strings and finite numbers, got ${typeof v}: ${String(v)}`);
+    }
+    return { sql: 'IN (SELECT value FROM json_each(?))', param: JSON.stringify(values) };
+}

package/dist/server/google-oauth/googleOAuth.d.ts

@@ -0,0 +1,303 @@
+export declare const GOOGLE_TOKEN_ENDPOINT = "https://oauth2.googleapis.com/token";
+export declare const GOOGLE_AUTH_ENDPOINT = "https://accounts.google.com/o/oauth2/v2/auth";
+export declare const GOOGLE_REVOKE_ENDPOINT = "https://oauth2.googleapis.com/revoke";
+/**
+ * Deliberately looser than `typeof fetch`.
+ *
+ * Every caller here passes one URL string and an init, and `typeof fetch` also carries Bun's
+ * `preconnect` property — so typing the seam as `typeof fetch` makes `async () =>
+ * Response.json(…)` a compile error in every test that fakes it, for a capability no code
+ * path uses.
+ */
+export type FetchLike = (url: string, init?: RequestInit) => Promise<Response>;
+/**
+ * An environment to read credentials from. `process.env` satisfies it, and so does a plain
+ * object in a test — deliberately not `NodeJS.ProcessEnv`, so a consumer's declarations do not
+ * need `@types/node` to type-check against this one.
+ */
+export type EnvLike = Readonly<Record<string, string | undefined>>;
+export interface GoogleCredentials {
+    clientId: string;
+    clientSecret: string;
+    refreshToken: string;
+}
+/**
+ * WHICH KIND of `unavailable`, structurally rather than by reading the sentence.
+ *
+ * 🔴 A caller that treats these two alike rings the wrong alarm. `refused` is Google saying no
+ * to a credential the owner has to act on; `transport` is a machine that could not reach
+ * Google — a laptop on a train — and a bell claiming a dead grant every time the wifi drops is
+ * how a real credential alarm gets ignored.
+ */
+export type UnavailableCause = 'transport' | 'refused';
+/** Everything below `ok` carries the exact remedy — never a quiet empty result. */
+export type TokenResult = {
+    status: 'ok';
+    accessToken: string;
+    grantedScopes: string[];
+} | {
+    status: 'unconfigured';
+    reason: string;
+    fix: string;
+} | {
+    status: 'unavailable';
+    reason: string;
+    fix: string;
+    cause?: UnavailableCause;
+};
+/** `~/x` → `<home>/x`. Anything else is returned unchanged. */
+export declare const expandTilde: (p: string) => string;
+/**
+ * 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 declare function parseEnvFile(text: string): Record<string, string>;
+/** Read any other key — env first, then the same secrets file (an API key, an address). */
+export declare function readSecret(name: string, options?: {
+    env?: EnvLike;
+    secretsFile?: string;
+}): string;
+/**
+ * The env-var names a caller will accept for each half of the credential, most canonical
+ * FIRST. A consumer with historical aliases lists them after its canonical names; a new
+ * consumer passes one name each.
+ */
+export interface CredentialKeys {
+    clientId: readonly string[];
+    clientSecret: readonly string[];
+    refreshToken: readonly string[];
+}
+export declare const CANONICAL_CREDENTIAL_KEYS: CredentialKeys;
+export interface ReadCredentialsOptions {
+    env?: EnvLike;
+    /** A 0600 file outside every checkout. `~` is expanded. The caller decides where it is. */
+    secretsFile?: string;
+    keys?: CredentialKeys;
+}
+/** Which name supplied one half of a credential, and where that name was read from. */
+export interface CredentialSource {
+    name: string;
+    from: 'env' | 'file';
+}
+/**
+ * WHICH NAMES a credential actually came out of.
+ *
+ * 🔴 Why this is not a debugging nicety. A credential list is a PREFERENCE order, so a value
+ * under the preferred name wins merely by existing — it is never checked against the value
+ * under the alias. Measured 2026-09-15: one 0600 file held two different refresh tokens for
+ * the identical client and account, the canonical name was dead (`invalid_grant`) and the
+ * alias beside it exchanged fine. Every call took the dead one and reported "the grant has
+ * been revoked, re-consent" — a sentence that was false, sent the owner to a browser, and
+ * cost forty minutes of not believing it. `shadowed` makes that a five-second diagnosis.
+ */
+export interface GoogleCredentialResolution {
+    /** The same value `readGoogleCredentials` returns — null if any half is missing. */
+    credentials: GoogleCredentials | null;
+    /** The name that supplied each half, or null when no listed name had a value. */
+    used: {
+        clientId: CredentialSource | null;
+        clientSecret: CredentialSource | null;
+        refreshToken: CredentialSource | null;
+    };
+    /** Names holding a value that lost to an earlier one. Never a value, only a name. */
+    shadowed: {
+        clientId: string[];
+        clientSecret: string[];
+        refreshToken: string[];
+    };
+    /** Every listed name for a half that nothing supplied — the `unconfigured` detail. */
+    missing: string[];
+}
+/**
+ * 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 declare function resolveGoogleCredentials(options?: ReadCredentialsOptions): GoogleCredentialResolution;
+/**
+ * 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 declare function readGoogleCredentials(options?: ReadCredentialsOptions): GoogleCredentials | null;
+export interface ConsentUrlOptions {
+    clientId: string;
+    /**
+     * Must match an Authorized redirect URI on the OAuth client EXACTLY — Google compares the
+     * string, not the URL. A trailing slash is a different URI.
+     */
+    redirectUri: string;
+    scopes: readonly string[];
+    /** The caller's CSRF/binding token. Google hands it back on the callback verbatim. */
+    state: string;
+    /**
+     * `consent` (the default) forces Google to re-issue a refresh token.
+     *
+     * 🔴 Not a preference. Google issues `refresh_token` only on the FIRST consent for a
+     * client+account pair; a second connect without this returns an access token and nothing
+     * else, so an app that stored only what arrived would be connected for an hour and then
+     * permanently unable to refresh.
+     */
+    prompt?: 'consent' | 'select_account' | 'none';
+}
+/** The URL to send the browser to. Pure — no network, so a caller can test its own wiring. */
+export declare function buildConsentUrl(options: ConsentUrlOptions): string;
+export interface ExchangeOptions {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    code: string;
+    fetchImpl?: FetchLike;
+    timeoutMs?: number;
+}
+export type AuthCodeResult = {
+    status: 'ok';
+    accessToken: string;
+    /**
+     * Absent when Google chose not to re-issue one. A caller that already holds a refresh
+     * token for this account must KEEP it rather than storing an empty string — see
+     * {@link ConsentUrlOptions.prompt}.
+     */
+    refreshToken?: string;
+    expiresInSeconds: number;
+    grantedScopes: string[];
+} | {
+    status: 'unavailable';
+    reason: string;
+    fix: string;
+    /** See {@link UnavailableCause}. Always set by this module; optional in the type. */
+    cause?: UnavailableCause;
+};
+/** Trade the `?code=` Google sent to the callback for tokens. */
+export declare function exchangeAuthCode(options: ExchangeOptions): Promise<AuthCodeResult>;
+export interface RefreshOptions {
+    clientId: string;
+    clientSecret: string;
+    refreshToken: string;
+    fetchImpl?: FetchLike;
+    timeoutMs?: number;
+    /** What to tell the owner when Google refuses the token — usually "re-consent". */
+    refusalFix?: string;
+}
+/**
+ * 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 declare function refreshAccessToken(options: RefreshOptions): Promise<AuthCodeResult>;
+/**
+ * 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 declare function revokeGoogleToken(token: string, options?: {
+    fetchImpl?: FetchLike;
+    timeoutMs?: number;
+}): Promise<boolean>;
+export interface TokenMinterOptions {
+    /**
+     * Supplied directly (a consenting app's stored refresh token). `null` means "there are
+     * none"; `undefined` means "read them from `env` + `secretsFile` under `keys`".
+     */
+    credentials?: GoogleCredentials | null;
+    env?: EnvLike;
+    secretsFile?: string;
+    keys?: CredentialKeys;
+    fetchImpl?: FetchLike;
+    timeoutMs?: number;
+    now?: () => number;
+    /**
+     * What to tell the owner when the credential is missing or Google refuses it. Each consumer
+     * mints its token a different way, so the remedy is theirs.
+     */
+    setupFix?: string;
+    /** Named in the failure sentences, e.g. "the digest" or "the YouTube connection". */
+    label?: string;
+}
+export interface GoogleTokenMinter {
+    /** A valid access token, or a typed failure carrying the remedy. */
+    token(): Promise<TokenResult>;
+    /**
+     * The scopes Google says this grant actually has. Empty when the token could not be minted
+     * at all — callers must distinguish "no scopes" from "could not ask".
+     */
+    grantedScopes(): Promise<string[]>;
+    /** Drop the cached token — for a test, or after a 401 that suggests a stale one. */
+    invalidate(): void;
+}
+/**
+ * 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 declare function createGoogleTokenMinter(options?: TokenMinterOptions): GoogleTokenMinter;
+/**
+ * What an EXCHANGE of the credential a caller is about to use actually did.
+ *
+ * Deliberately not a `TokenResult`: no access token comes out of here, because a probe that
+ * handed one back would become a second minting path with its own cache.
+ */
+export interface CredentialProbe {
+    /**
+     * FOUR states, and the split between the last two is the load-bearing one: `refused` is
+     * Google saying no to this credential and is the owner's to fix; `unreachable` is this
+     * machine's network and fixes itself.
+     */
+    status: 'ok' | 'unconfigured' | 'refused' | 'unreachable';
+    /** The env name whose refresh token was exchanged. "" when none was found or credentials were supplied. */
+    refreshTokenName: string;
+    /** Other names for the refresh token that hold a value and were NOT used. */
+    shadowedRefreshTokenNames: string[];
+    /** What Google says this grant carries. Empty unless `status` is "ok". */
+    grantedScopes: string[];
+    /** One sentence for a bell, a boot log or a health body. Never a credential value. */
+    summary: string;
+    /** The exact next action. "" when `status` is "ok". */
+    fix: string;
+}
+/**
+ * 🔴 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 declare function probeCredentialExchange(options?: TokenMinterOptions): Promise<CredentialProbe>;
+/**
+ * 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 declare function describeScopeFailure(options: {
+    api: string;
+    needed: string;
+    granted: readonly string[];
+    httpStatus: number;
+    /** The command that re-runs consent, e.g. `bun run google:consent`. */
+    consentCommand: string;
+}): {
+    reason: string;
+    fix: string;
+};