sealkeep 0.9.0 → 0.11.0

package/dist/src/project-repair.d.ts

@@ -0,0 +1,55 @@
+/** A project identity already detected from a live, currently existing folder. */
+export type DetectedProject = {
+    project: string;
+    projectKey: string;
+    projectPath: string;
+};
+export type HistoricalProjectRepairCandidate = {
+    /** Stable identity recorded by the archive, when one was available. */
+    historicalProjectKey: string | null;
+    /** Display-only label recorded by the archive. */
+    historicalProject: string | null;
+    /** The old identity is not among the supplied live folder identities. */
+    originalFolderAvailable: false;
+    reason: "folder-not-detected" | "no-stable-project-key" | "already-scoped";
+    archiveCount: number;
+    /** Distinct source transcript paths, not snapshots/delta links. */
+    sessionCount: number;
+    /** Exact choices; labels never select a replacement. Empty for legacy rows. */
+    replacementOptions: DetectedProject[];
+    repairable: boolean;
+};
+export type HistoricalProjectRepairRequest = {
+    historicalProjectKey: string;
+    replacementProjectKey: string;
+};
+export type HistoricalProjectRepairPreview = {
+    candidate: HistoricalProjectRepairCandidate;
+    replacement: DetectedProject;
+    /** True only when the replacement already belongs to a local team space. */
+    teamSpaceBound: true;
+    /** The exact opaque space id used by the alias; not archive key material. */
+    spaceKey: string;
+};
+export type HistoricalProjectRepairResult = HistoricalProjectRepairPreview & {
+    applied: true;
+};
+/**
+ * Finds archive identities that are no longer represented by a live folder.
+ *
+ * The caller supplies the same exact-key detections used by the dashboard's
+ * project picker. This function deliberately does not derive a replacement
+ * from a label, path basename, or nearest folder. Legacy archives without a
+ * stable key are surfaced for review but are never repairable automatically.
+ */
+export declare function listHistoricalProjectRepairCandidates(dataDir: string, detectedProjects: readonly DetectedProject[]): Promise<HistoricalProjectRepairCandidate[]>;
+/** Builds a no-write impact preview for one exact historical-to-live mapping. */
+export declare function previewHistoricalProjectRepair(dataDir: string, request: HistoricalProjectRepairRequest, detectedProjects: readonly DetectedProject[]): Promise<HistoricalProjectRepairPreview>;
+/**
+ * Adds the old stable key as a local alias of the replacement's existing team
+ * space. Confirmation is mandatory; no archive sidecar or ciphertext is
+ * opened or rewritten. The normal team backfill then handles encrypted copies.
+ */
+export declare function applyHistoricalProjectRepair(dataDir: string, request: HistoricalProjectRepairRequest, detectedProjects: readonly DetectedProject[], options: {
+    confirm: boolean;
+}): Promise<HistoricalProjectRepairResult>;

package/dist/src/project-repair.js

@@ -0,0 +1,131 @@
+import { stat } from "node:fs/promises";
+import { listArchives, bindTeamSpace, readConfig, teamSpaceOf } from "./vault.js";
+import { projectIdentityOfRecord } from "./adapters.js";
+import { fail } from "./errors.js";
+const STABLE_PROJECT_KEY = /^(?:g1|p1):[a-f0-9]{64}$/;
+function assertStableProjectKey(value, label) {
+    if (!STABLE_PROJECT_KEY.test(value))
+        fail("invalid_argument", `${label} must be a stable project key`);
+}
+function projectOfRecord(record) {
+    const project = "project" in record.source && typeof record.source.project === "string"
+        ? record.source.project
+        : null;
+    const projectKey = "projectKey" in record.source && typeof record.source.projectKey === "string"
+        ? record.source.projectKey
+        : null;
+    return { project, projectKey };
+}
+/**
+ * Finds archive identities that are no longer represented by a live folder.
+ *
+ * The caller supplies the same exact-key detections used by the dashboard's
+ * project picker. This function deliberately does not derive a replacement
+ * from a label, path basename, or nearest folder. Legacy archives without a
+ * stable key are surfaced for review but are never repairable automatically.
+ */
+export async function listHistoricalProjectRepairCandidates(dataDir, detectedProjects) {
+    const detected = (await Promise.all(detectedProjects
+        .filter((item) => STABLE_PROJECT_KEY.test(item.projectKey) && item.project.trim() && item.projectPath.trim())
+        .map(async (item) => await stat(item.projectPath).then((entry) => entry.isDirectory() ? item : null).catch(() => null))))
+        .filter((item) => item !== null);
+    const detectedKeys = new Set(detected.map((item) => item.projectKey));
+    const archives = await listArchives(dataDir);
+    const groups = new Map();
+    for (const record of archives) {
+        const recorded = projectOfRecord(record);
+        const identity = recorded.projectKey
+            ? recorded
+            : await projectIdentityOfRecord(record).catch(() => ({ project: recorded.project, projectKey: null, projectPath: null }));
+        const project = identity.project ?? recorded.project;
+        const projectKey = identity.projectKey && STABLE_PROJECT_KEY.test(identity.projectKey)
+            ? identity.projectKey
+            : null;
+        if (projectKey && detectedKeys.has(projectKey))
+            continue;
+        const groupKey = projectKey ?? `legacy:${project ?? ""}`;
+        const group = groups.get(groupKey) ?? {
+            project,
+            projectKey,
+            hasProjectScope: false,
+            archiveCount: 0,
+            sourcePaths: new Set(),
+        };
+        if ("projectScope" in record.source && typeof record.source.projectScope === "string" && record.source.projectScope) {
+            group.hasProjectScope = true;
+        }
+        group.archiveCount += 1;
+        group.sourcePaths.add(record.source.path);
+        groups.set(groupKey, group);
+    }
+    return [...groups.values()]
+        .map((group) => ({
+        historicalProjectKey: group.projectKey,
+        historicalProject: group.project,
+        originalFolderAvailable: false,
+        reason: !group.projectKey ? "no-stable-project-key" : group.hasProjectScope ? "already-scoped" : "folder-not-detected",
+        archiveCount: group.archiveCount,
+        sessionCount: group.sourcePaths.size,
+        replacementOptions: group.projectKey && !group.hasProjectScope ? detected : [],
+        repairable: Boolean(group.projectKey && !group.hasProjectScope && detected.length > 0),
+    }))
+        .sort((left, right) => (left.historicalProject ?? "").localeCompare(right.historicalProject ?? "")
+        || (left.historicalProjectKey ?? "").localeCompare(right.historicalProjectKey ?? ""));
+}
+async function resolvePreview(dataDir, request, detectedProjects) {
+    assertStableProjectKey(request.historicalProjectKey, "Historical project key");
+    assertStableProjectKey(request.replacementProjectKey, "Replacement project key");
+    if (request.historicalProjectKey === request.replacementProjectKey) {
+        fail("invalid_argument", "The replacement must be a different exact project key");
+    }
+    const candidates = await listHistoricalProjectRepairCandidates(dataDir, detectedProjects);
+    const candidate = candidates.find((item) => item.historicalProjectKey === request.historicalProjectKey);
+    if (!candidate) {
+        fail("invalid_argument", "That historical project is not awaiting repair, or is already represented by a detected folder");
+    }
+    if (!candidate.repairable) {
+        fail("invalid_argument", candidate.reason === "already-scoped"
+            ? "This history already carries a shared-project scope and cannot be reassigned locally"
+            : "This history has no stable project key, so it cannot be reassigned safely");
+    }
+    const replacement = candidate.replacementOptions.find((item) => item.projectKey === request.replacementProjectKey);
+    if (!replacement || !STABLE_PROJECT_KEY.test(replacement.projectKey)) {
+        fail("invalid_argument", "Choose an exact currently detected folder for the replacement");
+    }
+    const config = await readConfig(dataDir);
+    const binding = teamSpaceOf(config, replacement.project, replacement.projectKey);
+    if (!binding) {
+        fail("invalid_argument", "The exact replacement folder is not connected to a shared project yet; connect it first");
+    }
+    const existing = teamSpaceOf(config, candidate.historicalProject, candidate.historicalProjectKey);
+    if (existing && existing.spaceKey !== binding.spaceKey) {
+        fail("invalid_argument", "This historical identity is already bound to a different shared project");
+    }
+    return {
+        candidate,
+        replacement,
+        teamSpaceBound: true,
+        spaceKey: binding.spaceKey,
+    };
+}
+/** Builds a no-write impact preview for one exact historical-to-live mapping. */
+export async function previewHistoricalProjectRepair(dataDir, request, detectedProjects) {
+    return resolvePreview(dataDir, request, detectedProjects);
+}
+/**
+ * Adds the old stable key as a local alias of the replacement's existing team
+ * space. Confirmation is mandatory; no archive sidecar or ciphertext is
+ * opened or rewritten. The normal team backfill then handles encrypted copies.
+ */
+export async function applyHistoricalProjectRepair(dataDir, request, detectedProjects, options) {
+    if (options.confirm !== true)
+        fail("invalid_argument", "Confirm this exact historical-project repair after reviewing its archive and session counts");
+    const preview = await resolvePreview(dataDir, request, detectedProjects);
+    const config = await readConfig(dataDir);
+    const binding = teamSpaceOf(config, preview.replacement.project, preview.replacement.projectKey);
+    if (!binding)
+        fail("invalid_argument", "The replacement folder's shared-project binding changed; review again");
+    const aliasBinding = { ...binding, localConfirmed: true };
+    await bindTeamSpace(dataDir, preview.candidate.historicalProject ?? preview.replacement.project, aliasBinding, preview.candidate.historicalProjectKey);
+    return { ...preview, applied: true };
+}

package/dist/src/providers/gcs.d.ts

@@ -1,4 +1,6 @@
 import type { ProviderUploadClient, UploadLease } from "../control-plane.js";
+import { type ByteStream } from "../byte-stream.js";
+import type { StorageFetch } from "./safe-storage-fetch.js";
 /**
  * Google Cloud Storage V4 signing (`GOOG4-RSA-SHA256`) plus resumable uploads.
  *
@@ -55,6 +57,7 @@ export type GcsStreamOptions = {
     /** Awaited after every successful chunk PUT with the cumulative confirmed
      *  bytes. This call is the durability point a resume journal writes at. */
     onState?: (state: GcsStreamState) => void | Promise<void>;
+    signal?: AbortSignal;
 };
 /**
  * GCS resumable upload client.
@@ -66,22 +69,34 @@ export declare class GcsUploadClient implements ProviderUploadClient {
     private readonly endpoint;
     private readonly serviceAccount;
     private readonly chunkBytes;
+    private readonly fetchImpl;
     readonly kind: "gcs";
-    constructor(endpoint: GcsEndpoint, serviceAccount: ServiceAccount, chunkBytes?: number);
+    constructor(endpoint: GcsEndpoint, serviceAccount: ServiceAccount, chunkBytes?: number, fetchImpl?: StorageFetch);
     private sign;
     /** The chunk-folder layout's object verbs: plain signed single-object HTTP. */
-    putObject(object: string, body: Buffer): Promise<{
+    putObject(object: string, body: Buffer, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
         checksum: string;
     }>;
-    headObject(object: string): Promise<{
+    headObject(object: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
         exists: boolean;
         bytes: number;
         checksum?: string;
     }>;
-    getObject(object: string): Promise<Buffer>;
+    getObject(object: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<Buffer>;
+    /** Object-key streaming counterpart used by the background index store. */
+    getObjectStream(object: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<ByteStream>;
+    private downloadObjectStream;
     deleteObject(object: string): Promise<void>;
     /** Starts a resumable session and returns its URI. */
-    initiateResumable(object: string): Promise<string>;
+    initiateResumable(object: string, signal?: AbortSignal): Promise<string>;
     /**
      * Asks a session how many bytes the provider has durably confirmed, speaking
      * the protocol GCS actually implements: an empty PUT whose content-range is
@@ -89,7 +104,7 @@ export declare class GcsUploadClient implements ProviderUploadClient {
      * confirmed — or 308 with no Range at all when nothing is confirmed yet.
      * (Error messages here never carry the session URI: it is a bearer token.)
      */
-    resumableStatus(session: string): Promise<{
+    resumableStatus(session: string, signal?: AbortSignal): Promise<{
         confirmedBytes: number;
     }>;
     upload(lease: UploadLease, ciphertext: Buffer): Promise<{
@@ -124,7 +139,13 @@ export declare class GcsUploadClient implements ProviderUploadClient {
         bytes: number;
     }>;
     /** Reads an object back for restore or offload-proof: a signed GET, whole. */
-    download(lease: UploadLease): Promise<Buffer>;
+    download(lease: UploadLease, options?: {
+        signal?: AbortSignal;
+    }): Promise<Buffer>;
+    /** The production restore/transfer door: response chunks flow straight to disk. */
+    downloadStream(lease: UploadLease, options?: {
+        signal?: AbortSignal;
+    }): Promise<ByteStream>;
     head(lease: UploadLease): Promise<{
         exists: boolean;
         bytes: number;

package/dist/src/providers/gcs.js

@@ -1,6 +1,7 @@
 import { createHash, createPrivateKey, createSign } from "node:crypto";
 import { fail } from "../errors.js";
 import { amzDates, canonicalHeaders, canonicalQuery, canonicalUri } from "./sigv4.js";
+import { collectChunks, responseBodyChunks } from "../byte-stream.js";
 /**
  * Google Cloud Storage V4 signing (`GOOG4-RSA-SHA256`) plus resumable uploads.
  *
@@ -51,26 +52,28 @@ export class GcsUploadClient {
     endpoint;
     serviceAccount;
     chunkBytes;
+    fetchImpl;
     kind = "gcs";
-    constructor(endpoint, serviceAccount, chunkBytes = 8 * 1024 * 1024) {
+    constructor(endpoint, serviceAccount, chunkBytes = 8 * 1024 * 1024, fetchImpl = fetch) {
         this.endpoint = endpoint;
         this.serviceAccount = serviceAccount;
         this.chunkBytes = chunkBytes;
+        this.fetchImpl = fetchImpl;
     }
     sign(method, object, headers = {}, query = {}) {
         return signGcsUrl({ method, bucket: this.endpoint.bucket, object, serviceAccount: this.serviceAccount, headers, query, host: this.endpoint.host, port: this.endpoint.port, protocol: this.endpoint.protocol });
     }
     /** The chunk-folder layout's object verbs: plain signed single-object HTTP. */
-    async putObject(object, body) {
+    async putObject(object, body, options = {}) {
         const { url } = this.sign("PUT", object);
-        const response = await fetch(url, { method: "PUT", body: new Uint8Array(body) });
+        const response = await this.fetchImpl(url, { method: "PUT", body: new Uint8Array(body), signal: options.signal });
         if (!response.ok)
             fail("internal", `Upload failed for ${object}: ${response.status} ${response.statusText}`, { object, status: response.status });
         return { checksum: createHash("md5").update(body).digest("base64") };
     }
-    async headObject(object) {
+    async headObject(object, options = {}) {
         const { url } = this.sign("HEAD", object);
-        const response = await fetch(url, { method: "HEAD" });
+        const response = await this.fetchImpl(url, { method: "HEAD", signal: options.signal });
         if (response.status === 404)
             return { exists: false, bytes: 0 };
         if (!response.ok)
@@ -79,23 +82,30 @@ export class GcsUploadClient {
         const md5 = /(?:^|[ ,])md5=([A-Za-z0-9+/]+={0,2})/.exec(hash)?.[1];
         return { exists: true, bytes: Number(response.headers.get("content-length") ?? "0"), checksum: md5 };
     }
-    async getObject(object) {
+    async getObject(object, options = {}) {
+        return collectChunks(await this.downloadObjectStream(object, options.signal), Number.MAX_SAFE_INTEGER);
+    }
+    /** Object-key streaming counterpart used by the background index store. */
+    async getObjectStream(object, options = {}) {
+        return this.downloadObjectStream(object, options.signal);
+    }
+    async downloadObjectStream(object, signal) {
         const { url } = this.sign("GET", object);
-        const response = await fetch(url);
+        const response = await this.fetchImpl(url, { signal });
         if (!response.ok)
             fail("internal", `Could not download ${object}: ${response.status} ${response.statusText}`, { object, status: response.status });
-        return Buffer.from(await response.arrayBuffer());
+        return responseBodyChunks(response);
     }
     async deleteObject(object) {
         const { url } = this.sign("DELETE", object);
-        const response = await fetch(url, { method: "DELETE" });
+        const response = await this.fetchImpl(url, { method: "DELETE" });
         if (!response.ok && response.status !== 404)
             fail("internal", `Could not delete ${object}: ${response.status} ${response.statusText}`, { object, status: response.status });
     }
     /** Starts a resumable session and returns its URI. */
-    async initiateResumable(object) {
+    async initiateResumable(object, signal) {
         const { url } = this.sign("POST", object, { "x-goog-resumable": "start" });
-        const response = await fetch(url, { method: "POST", headers: { "x-goog-resumable": "start" } });
+        const response = await this.fetchImpl(url, { method: "POST", headers: { "x-goog-resumable": "start" }, signal });
         if (!response.ok)
             fail("internal", `Could not start a resumable upload for ${object}: ${response.status} ${response.statusText}`, { object, status: response.status });
         const session = response.headers.get("location");
@@ -108,8 +118,8 @@ export class GcsUploadClient {
      * confirmed — or 308 with no Range at all when nothing is confirmed yet.
      * (Error messages here never carry the session URI: it is a bearer token.)
      */
-    async resumableStatus(session) {
-        const response = await fetch(session, { method: "PUT", headers: { "content-range": "bytes */*" } });
+    async resumableStatus(session, signal) {
+        const response = await this.fetchImpl(session, { method: "PUT", headers: { "content-range": "bytes */*" }, signal });
         // 2xx means the session already finalized its object; resuming would try
         // to append to something finished, so the caller should verify instead.
         if (response.ok)
@@ -131,7 +141,7 @@ export class GcsUploadClient {
             const slice = ciphertext.subarray(offset, Math.min(offset + this.chunkBytes, ciphertext.length));
             const last = offset + slice.length >= ciphertext.length;
             const range = ciphertext.length === 0 ? "bytes */0" : `bytes ${offset}-${offset + slice.length - 1}/${ciphertext.length}`;
-            const response = await fetch(session, { method: "PUT", body: new Uint8Array(slice), headers: { "content-range": range } });
+            const response = await this.fetchImpl(session, { method: "PUT", body: new Uint8Array(slice), headers: { "content-range": range } });
             // 308 means "resume incomplete" and is the expected status between chunks.
             if (!response.ok && !(response.status === 308 && !last)) {
                 fail("internal", `Resumable upload for ${object} failed at ${range}: ${response.status} ${response.statusText}`, { object, status: response.status });
@@ -154,7 +164,7 @@ export class GcsUploadClient {
         let session;
         let sent = 0;
         if (resume) {
-            const { confirmedBytes } = await this.resumableStatus(resume.session);
+            const { confirmedBytes } = await this.resumableStatus(resume.session, options.signal);
             // The caller re-sealed from the offset its journal recorded. If the
             // provider confirmed a different count — a PUT landed after the last
             // journal write, say — the very first flush would splice bytes at the
@@ -166,7 +176,7 @@ export class GcsUploadClient {
             sent = confirmedBytes;
         }
         else {
-            session = await this.initiateResumable(objectKey);
+            session = await this.initiateResumable(objectKey, options.signal);
         }
         // A resumed run never saw the bytes the earlier run sent, so it cannot
         // roll an MD5 over the whole object — null says "no provider-language
@@ -183,7 +193,7 @@ export class GcsUploadClient {
             const range = final
                 ? (piece.length === 0 ? `bytes */${sent}` : `bytes ${sent}-${sent + piece.length - 1}/${sent + piece.length}`)
                 : `bytes ${sent}-${sent + piece.length - 1}/*`;
-            const response = await fetch(session, { method: "PUT", body: new Uint8Array(piece), headers: { "content-range": range } });
+            const response = await this.fetchImpl(session, { method: "PUT", body: new Uint8Array(piece), headers: { "content-range": range }, signal: options.signal });
             if (!response.ok && !(response.status === 308 && !final)) {
                 fail("internal", `Resumable upload for ${objectKey} failed at ${range}: ${response.status} ${response.statusText}`, { object: objectKey, status: response.status });
             }
@@ -194,6 +204,7 @@ export class GcsUploadClient {
                 await options.onState({ session, confirmedBytes: sent });
         };
         for await (const chunk of chunks) {
+            options.signal?.throwIfAborted();
             md5?.update(chunk);
             held.push(chunk);
             heldBytes += chunk.length;
@@ -209,16 +220,16 @@ export class GcsUploadClient {
         return { remoteChecksum: md5 ? md5.digest("base64") : null, bytes: sent };
     }
     /** Reads an object back for restore or offload-proof: a signed GET, whole. */
-    async download(lease) {
-        const { url } = this.sign("GET", lease.objectKey);
-        const response = await fetch(url);
-        if (!response.ok)
-            fail("internal", `Could not download ${lease.objectKey}: ${response.status} ${response.statusText}`, { key: lease.objectKey, status: response.status });
-        return Buffer.from(await response.arrayBuffer());
+    async download(lease, options = {}) {
+        return collectChunks(await this.downloadStream(lease, options), Number.MAX_SAFE_INTEGER);
+    }
+    /** The production restore/transfer door: response chunks flow straight to disk. */
+    async downloadStream(lease, options = {}) {
+        return this.downloadObjectStream(lease.objectKey, options.signal);
     }
     async head(lease) {
         const { url } = this.sign("HEAD", lease.objectKey);
-        const response = await fetch(url, { method: "HEAD" });
+        const response = await this.fetchImpl(url, { method: "HEAD" });
         if (response.status === 404)
             return { exists: false, bytes: 0 };
         if (!response.ok)

package/dist/src/providers/gdrive.d.ts

@@ -1,4 +1,6 @@
 import type { ProviderKind, ProviderUploadClient, UploadLease } from "../control-plane.js";
+import { type ByteStream } from "../byte-stream.js";
+import type { StorageFetch } from "./safe-storage-fetch.js";
 /**
  * Google Drive as a bring-your-own storage provider (Drive API v3).
  *
@@ -17,7 +19,7 @@ import type { ProviderKind, ProviderUploadClient, UploadLease } from "../control
  */
 export declare const GDRIVE_SCOPE = "https://www.googleapis.com/auth/drive.file";
 /** Placeholder until a first-party client id ships. Point SEALKEEP_GDRIVE_CLIENT_ID at your own Desktop-app OAuth client to connect today. */
-export declare const GDRIVE_CLIENT_ID_PLACEHOLDER = "000000000000-vaultline-placeholder.apps.googleusercontent.com";
+export declare const GDRIVE_CLIENT_ID_PLACEHOLDER = "000000000000-sealkeep-placeholder.apps.googleusercontent.com";
 export declare function gdriveClientId(env?: NodeJS.ProcessEnv): string;
 export declare const GDRIVE_AUTH_URL = "https://accounts.google.com/o/oauth2/v2/auth";
 export declare const GDRIVE_TOKEN_URL = "https://oauth2.googleapis.com/token";
@@ -27,6 +29,14 @@ export type GdriveCredentials = {
     kind: "gdrive";
     refreshToken: string;
     clientId: string;
+    /**
+     * Stable, non-secret Drive grantee id returned by `about.get` as
+     * `user.permissionId`.  It binds a refresh token to the physical Drive
+     * account without persisting an email address or another bearer secret.
+     * Optional only so credentials written by older releases can be read and
+     * rejected safely until the person reconnects.
+     */
+    accountId?: string;
     /** "cloud" = the refresh needs the account's server (web-client secret lives there). */
     exchange?: "cloud";
     /** Runtime-only: attached at load time, never persisted. Refreshes through the plane. */
@@ -70,6 +80,18 @@ export declare function exchangeCodeForTokens(input: {
     accessToken: string;
     expiresIn: number;
 }>;
+/**
+ * Resolve the stable Drive identity represented by an access token.
+ *
+ * `about.get(fields=user(permissionId))` is available under the existing
+ * `drive.file` grant.  A permission id is an opaque grantee identifier, not a
+ * credential and not personally-readable account metadata, so it is safe to
+ * retain beside the refresh token and include in destination fingerprints.
+ */
+export declare function gdriveAccountId(accessToken: string, options?: {
+    apiBase?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<string>;
 /**
  * Fire-and-forget platform opener. Failing to open a browser is never failing
  * to connect — the consent URL is reported to the caller either way — so this
@@ -88,6 +110,8 @@ export type ConnectOptions = {
     fetchImpl?: typeof fetch;
     authUrl?: string;
     tokenUrl?: string;
+    /** Test seam for the post-consent `about.get` identity lookup. */
+    accountIdResolver?: (accessToken: string) => Promise<string>;
     /** Loopback port; 0 (the default) asks the OS for a random one, which is what Google's loopback flow expects. */
     port?: number;
     timeoutMs?: number;
@@ -99,10 +123,19 @@ export type ConnectOptions = {
  * flow runs offline under test.
  */
 export declare function connectGdrive(options?: ConnectOptions): Promise<GdriveCredentials>;
+export type GdriveStreamOptions = {
+    /**
+     * Drive requires the final object length when a resumable session starts.
+     * File-backed archive uploads measure this in a bounded first pass and pass
+     * it here; an unknown-length source must be staged before it can use Drive.
+     */
+    bytes?: number;
+    signal?: AbortSignal;
+};
 /**
  * Drive upload client.
  *
- * A lease's objectKey (e.g. `vaultline/<id>.vlarchive`) has no path meaning in
+ * A lease's objectKey (e.g. `vaultline/<id>.skarchive`) has no path meaning in
  * Drive, so the mapping is: files live flat in one folder (or the hidden
  * appDataFolder space), named by the key's basename, and each carries
  * `appProperties.vaultlineKey = <full objectKey>`. head/download locate by that
@@ -119,7 +152,7 @@ export declare class GdriveUploadClient implements ProviderUploadClient {
     private readonly now;
     constructor(endpoint: GdriveEndpoint, credentials: GdriveCredentials, options?: {
         chunkBytes?: number;
-        fetchImpl?: typeof fetch;
+        fetchImpl?: StorageFetch;
         now?: () => number;
     });
     private base;
@@ -129,9 +162,14 @@ export declare class GdriveUploadClient implements ProviderUploadClient {
     private token;
     private api;
     private list;
-    /** Exact lookup by the appProperties key. Two files claiming one key is a state we refuse to guess about. */
+    /**
+     * Exact lookup inside this configured physical destination. Object keys are
+     * intentionally reusable across Drive folders, so the immutable parent id
+     * and Drive space are part of every lookup rather than merely creation
+     * metadata.
+     */
     private findByKey;
-    /** Finds or creates the archive folder; the id is cached per instance. */
+    /** Resolves the archive folder to its immutable Drive id, creating it only for uploads. */
     private parentId;
     /**
      * Starts a resumable session (create, or in-place update when the key already
@@ -144,13 +182,38 @@ export declare class GdriveUploadClient implements ProviderUploadClient {
         remoteChecksum: string;
         bytes: number;
     }>;
+    /**
+     * Uploads a known-length object through Drive's resumable protocol while
+     * retaining at most one configured resumable part. The archive pipeline
+     * measures a file in a bounded first pass, then this second pass computes
+     * Drive's whole-object MD5 as bytes are copied into fixed-size PUTs.
+     *
+     * Drive requires every non-final chunk to be a positive multiple of 256 KiB.
+     * The configured `chunkBytes` already enforces that rule; the last PUT may be
+     * short. A 308 response is accepted only for a non-final PUT, and the final
+     * PUT must be a success, so an early-finalized or half-accepted session can
+     * never be reported as complete.
+     */
+    uploadStream(objectKey: string, chunks: ByteStream, options?: GdriveStreamOptions): Promise<{
+        remoteChecksum: string;
+        bytes: number;
+    }>;
     head(lease: UploadLease): Promise<{
         exists: boolean;
         bytes: number;
         checksum?: string;
     }>;
     /** Reads an object back for restore or offload-proof: locate by key, then `alt=media`. */
-    /** Removes the file holding this object key. Absent already means done. */
-    deleteByKey(objectKey: string): Promise<void>;
-    download(lease: UploadLease): Promise<Buffer>;
+    /**
+     * Removes the file holding this object key in this exact destination. An
+     * empty successful scoped listing proves absence. A DELETE 404 is rechecked
+     * in the same scope before callers may discard their ledger metadata.
+     */
+    deleteByKey(objectKey: string): Promise<"deleted" | "absent">;
+    download(lease: UploadLease, options?: {
+        signal?: AbortSignal;
+    }): Promise<Buffer>;
+    downloadStream(lease: UploadLease, options?: {
+        signal?: AbortSignal;
+    }): Promise<ByteStream>;
 }