@dalgo/bigquery 0.0.0-stage → 0.3.0

package/dist/analytical/deadline.d.ts

@@ -0,0 +1,13 @@
+/** Millisecond timestamps from the trusted run ledger. This never starts a run.
+ * Only explicit status/cancel use control=true; cumulative bytes stay charged.
+ */
+export interface DeadlineInput {
+    readonly now: number;
+    readonly executionDeadline: number;
+    readonly callerDeadline?: number;
+    readonly httpLimitMs: number;
+    readonly control: boolean;
+    readonly bytesRemaining: bigint;
+}
+export declare function operationDeadline(input: DeadlineInput): number;
+//# sourceMappingURL=deadline.d.ts.map

package/dist/analytical/deadline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deadline.d.ts","sourceRoot":"","sources":["../../src/analytical/deadline.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAe9D"}

package/dist/analytical/deadline.js

@@ -0,0 +1,23 @@
+import { fail } from "./wire.js";
+export function operationDeadline(input) {
+    const { now, executionDeadline, callerDeadline, httpLimitMs, control, bytesRemaining } = input;
+    if (typeof bytesRemaining !== "bigint")
+        fail("invalid_input");
+    if (bytesRemaining <= 0n)
+        fail("response_limit");
+    if (![now, executionDeadline, httpLimitMs, ...(callerDeadline === undefined ? [] : [callerDeadline])].every(Number.isSafeInteger)
+        || httpLimitMs <= 0 || httpLimitMs > 15000 || typeof control !== "boolean"
+        || !Number.isSafeInteger(now + httpLimitMs))
+        fail("invalid_input");
+    let deadline = now + httpLimitMs;
+    if (!control) {
+        if (now >= executionDeadline)
+            fail("local_stopped");
+        deadline = Math.min(deadline, executionDeadline);
+    }
+    if (callerDeadline !== undefined)
+        deadline = Math.min(deadline, callerDeadline);
+    if (now >= deadline)
+        fail("local_stopped");
+    return deadline;
+}

package/dist/analytical/google-identity.d.ts

@@ -0,0 +1,40 @@
+import { type Principal } from "./protocol.js";
+import { type IdentityProvider, type SafeFetch, type TrustedIdentity } from "./transport.js";
+/** Pass to GIS initTokenClient; consent is triggered by the consumer's user gesture. */
+export declare function googleAuthorizationScopes(options?: {
+    email?: boolean;
+    cancellation?: boolean;
+}): string;
+/** Structural subset of GIS TokenResponse. Never store or log this object. */
+export interface GoogleTokenResponse {
+    readonly access_token?: string;
+    readonly token_type?: string;
+    readonly expires_in?: number;
+    readonly scope?: string;
+    readonly error?: string;
+}
+export interface GoogleIdentitySummary {
+    readonly principal: Principal;
+    readonly expiresAt: number;
+    readonly read: true;
+    readonly cancel: boolean;
+    /** Optional verified display label; never an identity or account-linkage key. */
+    readonly email?: string;
+}
+export interface GoogleIdentityConfig {
+    readonly fetch?: SafeFetch;
+    readonly now?: () => number;
+    readonly timeoutMs?: number;
+}
+/** Memory-only GIS token provider. It never prompts, refreshes, links Firebase
+ * accounts or chooses a project. Connect only from the real GIS callback; call
+ * disconnect on app sign-out, local disconnect and execution-account change.
+ */
+export declare class GoogleTokenIdentityProvider implements IdentityProvider {
+    #private;
+    constructor(config?: GoogleIdentityConfig);
+    disconnect(): void;
+    connect(response: GoogleTokenResponse, signal?: AbortSignal): Promise<GoogleIdentitySummary>;
+    authorize(signal: AbortSignal): Promise<TrustedIdentity>;
+}
+//# sourceMappingURL=google-identity.d.ts.map

package/dist/analytical/google-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"google-identity.d.ts","sourceRoot":"","sources":["../../src/analytical/google-identity.ts"],"names":[],"mappings":"AACA,OAAO,EAAyB,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAEtE,OAAO,EAAa,KAAK,gBAAgB,EAAE,KAAK,SAAS,EAAE,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAQxG,wFAAwF;AACxF,wBAAgB,yBAAyB,CAAC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,MAAM,CAE3G;AAED,8EAA8E;AAC9E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AACD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,iFAAiF;IACjF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AACD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;GAGG;AACH,qBAAa,2BAA4B,YAAW,gBAAgB;;gBAO/C,MAAM,GAAE,oBAAyB;IAM7C,UAAU,IAAI,IAAI;IAMZ,OAAO,CAAC,QAAQ,EAAE,mBAAmB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAkF5F,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC;CAOtE"}

package/dist/analytical/google-identity.js

@@ -0,0 +1,158 @@
+import { AnalyticalError, fail, isObject, parseJSON } from "./wire.js";
+import { cloneFrozen, nonempty } from "./protocol.js";
+import { opaqueID } from "./ledger.js";
+import { abortable } from "./transport.js";
+const readonlyScope = "https://www.googleapis.com/auth/bigquery.readonly";
+const cancelScope = "https://www.googleapis.com/auth/bigquery";
+const discoveryURL = "https://accounts.google.com/.well-known/openid-configuration";
+const userInfoURL = "https://openidconnect.googleapis.com/v1/userinfo";
+const maxBodyBytes = 64 * 1024;
+/** Pass to GIS initTokenClient; consent is triggered by the consumer's user gesture. */
+export function googleAuthorizationScopes(options = {}) {
+    return ["openid", options.cancellation ? cancelScope : readonlyScope, ...(options.email ? ["email"] : [])].join(" ");
+}
+/** Memory-only GIS token provider. It never prompts, refreshes, links Firebase
+ * accounts or chooses a project. Connect only from the real GIS callback; call
+ * disconnect on app sign-out, local disconnect and execution-account change.
+ */
+export class GoogleTokenIdentityProvider {
+    #fetch;
+    #now;
+    #timeout;
+    #revision = 0;
+    #identity;
+    #pending;
+    constructor(config = {}) {
+        this.#fetch = config.fetch ?? ((url, init) => globalThis.fetch(url, init));
+        this.#now = config.now ?? Date.now;
+        this.#timeout = config.timeoutMs ?? 15000;
+        if (!Number.isSafeInteger(this.#timeout) || this.#timeout < 1 || this.#timeout > 15000)
+            fail("invalid_input");
+    }
+    disconnect() {
+        this.#revision += 1;
+        this.#identity = undefined;
+        this.#pending?.abort();
+        this.#pending = undefined;
+    }
+    async connect(response, signal) {
+        // A denied/failed token rotation must invalidate the previous approval too.
+        this.disconnect();
+        const revision = this.#revision;
+        const now = this.#now();
+        if (signal?.aborted)
+            fail("local_stopped");
+        if (!response || response.error !== undefined || typeof response.access_token !== "string" ||
+            response.access_token.length === 0 || response.access_token.length > 16384 || !/^[A-Za-z0-9._~+/-]+=*$/u.test(response.access_token) ||
+            typeof response.token_type !== "string" || response.token_type.toLowerCase() !== "bearer")
+            fail("auth_required");
+        const token = response.access_token;
+        if (!Number.isSafeInteger(now) || !Number.isSafeInteger(response.expires_in) ||
+            (response.expires_in ?? 0) < 1 || (response.expires_in ?? 0) > 86400)
+            fail("auth_expired");
+        const expiresAt = now + response.expires_in * 1000;
+        if (!Number.isSafeInteger(expiresAt))
+            fail("auth_expired");
+        if (typeof response.scope !== "string" || response.scope.length > 8192)
+            fail("scope_missing");
+        const grants = new Set(response.scope.split(/\s+/u));
+        if (!grants.has("openid") || !(grants.has(readonlyScope) || grants.has(cancelScope)))
+            fail("scope_missing");
+        const controller = new AbortController();
+        this.#pending = controller;
+        const abort = () => controller.abort();
+        signal?.addEventListener("abort", abort, { once: true });
+        const deadline = Math.min(now + this.#timeout, expiresAt);
+        const timer = setTimeout(abort, deadline - now);
+        let bytes = 0;
+        const get = async (url, authenticated) => {
+            if (controller.signal.aborted || this.#now() >= deadline)
+                fail("local_stopped");
+            const result = await abortable(this.#fetch(url, {
+                method: "GET", redirect: "error", credentials: "omit", cache: "no-store", signal: controller.signal,
+                headers: { Accept: "application/json", ...(authenticated ? { Authorization: `Bearer ${token}` } : {}) },
+            }), controller.signal);
+            if (result.redirected || result.status >= 300 && result.status < 400)
+                fail("auth_required");
+            const reader = result.body?.getReader();
+            if (!reader)
+                fail("malformed_wire");
+            const chunks = [];
+            let length = 0;
+            try {
+                while (true) {
+                    const chunk = await abortable(reader.read(), controller.signal);
+                    if (chunk.done)
+                        break;
+                    length += chunk.value.byteLength;
+                    bytes += chunk.value.byteLength;
+                    if (length > maxBodyBytes || bytes > 2 * maxBodyBytes)
+                        fail("response_limit");
+                    chunks.push(chunk.value);
+                }
+            }
+            finally {
+                void reader.cancel().catch(() => { });
+                reader.releaseLock();
+            }
+            if (controller.signal.aborted || this.#now() >= deadline)
+                fail("local_stopped");
+            if (!result.ok)
+                fail(result.status === 401 ? "auth_expired" : "auth_required");
+            const raw = new Uint8Array(length);
+            let offset = 0;
+            for (const chunk of chunks) {
+                raw.set(chunk, offset);
+                offset += chunk.length;
+            }
+            const body = parseJSON(raw, maxBodyBytes);
+            if (!isObject(body))
+                fail("malformed_wire");
+            return body;
+        };
+        try {
+            // Discovery is public and never receives the access token. Source metadata
+            // cannot override either endpoint, even with a Google-looking URL.
+            const discovery = await get(discoveryURL, false);
+            if (discovery.issuer !== "https://accounts.google.com" || discovery.userinfo_endpoint !== userInfoURL)
+                fail("auth_required");
+            const user = await get(userInfoURL, true);
+            if (typeof user.sub !== "string" || user.sub.trim().length === 0)
+                fail("auth_required");
+            nonempty(user.sub);
+            if (this.#now() >= expiresAt)
+                fail("auth_expired");
+            if (controller.signal.aborted || revision !== this.#revision)
+                fail("local_stopped");
+            const principal = { kind: "google-user", subject: user.sub, generation: opaqueID() };
+            const identity = cloneFrozen({ principal, accessToken: token, expiresAt, read: true, cancel: grants.has(cancelScope) });
+            this.#identity = identity;
+            return cloneFrozen({ principal, expiresAt, read: true, cancel: identity.cancel,
+                ...(typeof user.email === "string" && user.email.length <= 320 && user.email_verified === true ? { email: user.email } : {}),
+            });
+        }
+        catch (error) {
+            if (error instanceof AnalyticalError)
+                throw error;
+            return fail(controller.signal.aborted ? "local_stopped" : "auth_required");
+        }
+        finally {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", abort);
+            if (this.#pending === controller)
+                this.#pending = undefined;
+        }
+    }
+    async authorize(signal) {
+        if (signal.aborted)
+            fail("local_stopped");
+        const identity = this.#identity;
+        if (!identity)
+            fail("auth_required");
+        if (this.#now() >= identity.expiresAt) {
+            this.#identity = undefined;
+            fail("auth_expired");
+        }
+        return identity;
+    }
+}

package/dist/analytical/ledger.d.ts

@@ -0,0 +1,80 @@
+import type { Bounds, Execution, Observation, ReadPlan, Receipt, SchemaField } from "./protocol.js";
+export interface Preview {
+    readonly nonce: string;
+    readonly plan: ReadPlan;
+    readonly observation: Observation;
+    readonly policyDigest: string;
+    readonly execution: Execution;
+    readonly bounds: Bounds;
+    readonly estimatedBytes: string;
+    readonly createdAt: string;
+    readonly expiresAt: string;
+    readonly approvalDigest: string;
+}
+export interface CursorState {
+    version: 1;
+    runId: string;
+    job: NonNullable<Receipt["job"]>;
+    planDigest: string;
+    schemaDigest: string;
+    principal: Execution["principal"];
+    pageToken: string | null;
+    pageSize: number;
+    offset: number;
+    pageDigest: string;
+    ordinal: number;
+    counters: Receipt["counters"];
+    ledgerRef: string;
+}
+export interface RunRecord {
+    receipt: Receipt;
+    preview: Preview;
+    activePrincipal: Execution["principal"];
+    reservation: string;
+    pageToken: string | null;
+    nextToken: string | null;
+    pageDigest: string;
+    offset: number;
+    pageOrdinal: number;
+    pageDone: boolean;
+    schema: readonly SchemaField[];
+    totalRows?: string;
+    seenTokens: string[];
+    cursor: CursorState | null;
+}
+export interface LedgerState {
+    version: 1;
+    previews: Record<string, {
+        preview: Preview;
+        used: boolean;
+    }>;
+    runs: Record<string, RunRecord>;
+}
+/** Atomic synchronous mutators commit only on success; leases exclude concurrent
+ * network/delivery operations on one run across every participating tab/client.
+ * Implementations must persist the same session across deliberate Resume.
+ */
+export interface Ledger {
+    update<T>(mutator: (state: LedgerState) => T): Promise<T>;
+    withLease<T>(runId: string, signal: AbortSignal | undefined, operation: () => Promise<T>): Promise<T>;
+}
+/** Deterministic test-only ledger. Production callers must inject shared durable
+ * storage; the client never creates a fallback or silently renews a session.
+ */
+export declare class MemoryLedger implements Ledger {
+    #private;
+    update<T>(mutator: (state: LedgerState) => T): Promise<T>;
+    withLease<T>(runId: string, signal: AbortSignal | undefined, operation: () => Promise<T>): Promise<T>;
+}
+/** Browser durable session storage: one explicitly chosen database/session name
+ * shared by all tabs. IndexedDB serializes state updates; Web Locks own run
+ * operations and release them automatically when their tab exits.
+ */
+export declare class IndexedDBLedger implements Ledger {
+    #private;
+    constructor(sessionName: string);
+    update<T>(mutator: (state: LedgerState) => T): Promise<T>;
+    withLease<T>(runId: string, signal: AbortSignal | undefined, operation: () => Promise<T>): Promise<T>;
+}
+export declare function opaqueID(): string;
+//# sourceMappingURL=ledger.d.ts.map

package/dist/analytical/ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.d.ts","sourceRoot":"","sources":["../../src/analytical/ledger.ts"],"names":[],"mappings":"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"}

package/dist/analytical/ledger.js

@@ -0,0 +1,89 @@
+import { AnalyticalError, fail } from "./wire.js";
+const empty = () => ({
+    version: 1, previews: Object.create(null), runs: Object.create(null)
+});
+/** Deterministic test-only ledger. Production callers must inject shared durable
+ * storage; the client never creates a fallback or silently renews a session.
+ */
+export class MemoryLedger {
+    #state = empty();
+    #leases = new Set();
+    async update(mutator) {
+        const next = structuredClone(this.#state);
+        const result = mutator(next);
+        const returned = structuredClone(result);
+        this.#state = next;
+        return returned;
+    }
+    async withLease(runId, signal, operation) {
+        if (signal?.aborted || this.#leases.has(runId))
+            fail("local_stopped");
+        this.#leases.add(runId);
+        try {
+            return await operation();
+        }
+        finally {
+            this.#leases.delete(runId);
+        }
+    }
+}
+/** Browser durable session storage: one explicitly chosen database/session name
+ * shared by all tabs. IndexedDB serializes state updates; Web Locks own run
+ * operations and release them automatically when their tab exits.
+ */
+export class IndexedDBLedger {
+    #database;
+    #lockPrefix;
+    constructor(sessionName) {
+        if (typeof sessionName !== "string" || !/^[A-Za-z0-9_-]{1,128}$/u.test(sessionName) || !globalThis.indexedDB || !globalThis.navigator?.locks)
+            fail("invalid_input");
+        this.#lockPrefix = `dalgo-bigquery:${sessionName}:`;
+        this.#database = new Promise((resolve, reject) => {
+            const request = indexedDB.open(`dalgo-bigquery-${sessionName}`, 1);
+            request.onupgradeneeded = () => { request.result.createObjectStore("session"); };
+            request.onsuccess = () => { const database = request.result; database.onversionchange = () => database.close(); resolve(database); };
+            request.onerror = () => reject(new AnalyticalError("invalid_input"));
+            request.onblocked = () => reject(new AnalyticalError("invalid_input"));
+        });
+    }
+    async update(mutator) {
+        const database = await this.#database;
+        return new Promise((resolve, reject) => {
+            const transaction = database.transaction("session", "readwrite", {
+                durability: "strict"
+            });
+            const store = transaction.objectStore("session");
+            const request = store.get("state");
+            let result;
+            let failure;
+            request.onsuccess = () => {
+                try {
+                    const state = (request.result ?? empty());
+                    if (state.version !== 1 || !state.runs || !state.previews)
+                        fail("invalid_input");
+                    result = structuredClone(mutator(state));
+                    store.put(state, "state");
+                }
+                catch (error) {
+                    failure = error;
+                    transaction.abort();
+                }
+            };
+            transaction.oncomplete = () => resolve(result);
+            transaction.onabort = () => reject(failure ?? new AnalyticalError("invalid_input"));
+            transaction.onerror = () => reject(failure ?? new AnalyticalError("invalid_input"));
+        });
+    }
+    async withLease(runId, signal, operation) {
+        if (signal?.aborted || !/^[0-9a-f]{48}$/u.test(runId))
+            fail("local_stopped");
+        return navigator.locks.request(this.#lockPrefix + runId, {
+            ifAvailable: true
+        }, async (lock) => {
+            if (lock === null || signal?.aborted)
+                fail("local_stopped");
+            return operation();
+        });
+    }
+}
+export function opaqueID() { const bytes = crypto.getRandomValues(new Uint8Array(24)); return Array.from(bytes, byte => byte.toString(16).padStart(2, "0")).join(""); }

package/dist/analytical/metadata-client.d.ts

@@ -0,0 +1,66 @@
+import { type Bounds, type Principal } from "./protocol.js";
+import { type Clock, type IdentityProvider, type SafeFetch } from "./transport.js";
+import { type JsonValue } from "./wire.js";
+/** A trusted consumer allowlist, not a locator accepted from user input. */
+export interface MetadataSource {
+    readonly sourceId: string;
+    readonly sourceProject: string;
+    readonly datasetId: string;
+    readonly tableId: string;
+}
+/** The application owner's explicit metadata consent is distinct from Google
+ * OAuth grants. The protected callback must read current owner-scoped state. */
+export interface MetadataConsent {
+    readonly purpose: "metadata-only";
+    readonly ownerId: string;
+    readonly consentId: string;
+    readonly source: MetadataSource;
+    readonly principal: Principal;
+    readonly selectedJobProject: string;
+}
+/** One synchronous snapshot of current protected owner consent and verified
+ * Google identity. Invalidate it before sign-out/account/token changes begin.
+ * Never construct this from caller JSON, cached consent or an unverified token. */
+export interface MetadataCurrentBinding {
+    readonly consent: MetadataConsent;
+    readonly read: boolean;
+    readonly expiresAt: number;
+}
+export type MetadataLimits = Pick<Bounds, "responseBytes" | "totalResponseBytes" | "wallMs" | "httpMs">;
+export interface MetadataClientConfig {
+    readonly sources: readonly MetadataSource[];
+    readonly provider: IdentityProvider;
+    readonly authorizeMetadata: (source: MetadataSource, signal: AbortSignal) => Promise<MetadataConsent>;
+    readonly currentMetadataBinding: (source: MetadataSource) => MetadataCurrentBinding | undefined;
+    readonly limits?: Partial<MetadataLimits>;
+    readonly fetch?: SafeFetch;
+    readonly clock?: Clock;
+}
+export interface MetadataOptions {
+    readonly signal?: AbortSignal;
+    readonly deadline?: number;
+}
+/** Deliberately partial native metadata projection. Nested schema/configuration
+ * is preserved as lossless JSON; this is not an execution schema or rights proof. */
+export interface MetadataDiscovery {
+    readonly source: MetadataSource;
+    readonly consent: MetadataConsent;
+    readonly dataset: Readonly<Record<string, JsonValue>>;
+    readonly table: Readonly<Record<string, JsonValue>>;
+    readonly observedAt: string;
+    readonly responseBytes: number;
+    readonly status: "inactive";
+    readonly queryAdmission: "blocked";
+    readonly costAdmission: "not-granted";
+    readonly projectPermissions: "unverified";
+    readonly billing: "unverified";
+    readonly sourceRights: "unreviewed";
+    readonly providerRetentionAuthorization: "not-granted";
+}
+/** No query, dry-run, row, ledger, export or cost-admission method exists here. */
+export declare class BigQueryMetadataClient {
+    #private;
+    constructor(config: MetadataClientConfig);
+    discover(sourceId: string, options?: MetadataOptions): Promise<MetadataDiscovery>;
+}
+//# sourceMappingURL=metadata-client.d.ts.map

package/dist/analytical/metadata-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata-client.d.ts","sourceRoot":"","sources":["../../src/analytical/metadata-client.ts"],"names":[],"mappings":"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"}