sealkeep 0.5.0

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

@@ -0,0 +1,156 @@
+import type { ProviderKind, ProviderUploadClient, UploadLease } from "../control-plane.js";
+/**
+ * Google Drive as a bring-your-own storage provider (Drive API v3).
+ *
+ * The privacy story lives in the scope. Sealkeep asks Google for
+ * `drive.file` ONLY: in Google's permission model that grant lets an app see
+ * and touch just the files it created itself — never the rest of the Drive,
+ * not even file names. So connecting Sealkeep exposes nothing a person
+ * already keeps in Drive, and what Sealkeep does create there is ciphertext
+ * sealed on this machine before any byte leaves it.
+ *
+ * Authentication is the OAuth desktop flow with PKCE and a loopback redirect
+ * (RFC 8252): a local one-shot server on 127.0.0.1 receives the code, and the
+ * PKCE verifier — not a client secret, desktop apps cannot keep one — proves
+ * the exchange. The only long-lived secret is the refresh token, which goes
+ * into the OS keystore via secrets.ts and never into a config file.
+ */
+export declare const GDRIVE_SCOPE = "https://www.googleapis.com/auth/drive.file";
+/** Placeholder until a first-party client id ships. Point VAULTLINE_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 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";
+export declare const GDRIVE_API_BASE = "https://www.googleapis.com";
+/** What the keystore holds for a connected Drive. Restated nowhere: secrets.ts imports this into its union. */
+export type GdriveCredentials = {
+    kind: "gdrive";
+    refreshToken: string;
+    clientId: 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. */
+    refresher?: (refreshToken: string) => Promise<{
+        accessToken: string;
+        expiresIn: number;
+    }>;
+};
+export type GdriveEndpoint = {
+    /** Drive has no buckets; archives live in one folder with this name at the Drive root. */
+    folderName: string;
+    /** Store in the hidden per-app `appDataFolder` space instead of a visible folder. */
+    appData?: boolean;
+    /** Test overrides. When host is set, the token endpoint is `<base>/token` on the same stub. */
+    host?: string;
+    port?: number;
+    protocol?: "https" | "http";
+};
+/** RFC 7636 verifier/challenge pair: 32 random bytes → 43-char verifier, S256 challenge. */
+export declare function createPkcePair(random?: () => Buffer): {
+    verifier: string;
+    challenge: string;
+    method: "S256";
+};
+export declare function gdriveConsentUrl(input: {
+    clientId: string;
+    redirectUri: string;
+    challenge: string;
+    state: string;
+    authUrl?: string;
+}): string;
+export declare function exchangeCodeForTokens(input: {
+    code: string;
+    verifier: string;
+    clientId: string;
+    redirectUri: string;
+    tokenUrl?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<{
+    refreshToken: string;
+    accessToken: string;
+    expiresIn: number;
+}>;
+/**
+ * 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
+ * mirrors ui-server's opener rules (BROWSER wins, `none` means don't) without
+ * importing that module: ui-server reaches local-api, and a provider that
+ * pulled the whole API surface into every upload would be an import cycle.
+ */
+export declare function launchBrowser(url: string, env?: NodeJS.ProcessEnv, platformName?: NodeJS.Platform): void;
+export type ConnectOptions = {
+    clientId?: string;
+    env?: NodeJS.ProcessEnv;
+    /** Called with the consent URL before anything waits on the browser; the CLI prints it here. */
+    onConsentUrl?: (url: string) => void;
+    /** Replaces the platform browser launch; tests drive the loopback redirect from here. */
+    opener?: (url: string) => void | Promise<void>;
+    fetchImpl?: typeof fetch;
+    authUrl?: string;
+    tokenUrl?: 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;
+};
+/**
+ * The whole consent dance: loopback server, consent URL, code, PKCE exchange.
+ * Returns the credential shape the keystore stores. Everything slow or
+ * environment-shaped (fetch, browser, endpoints) is injectable so the entire
+ * flow runs offline under test.
+ */
+export declare function connectGdrive(options?: ConnectOptions): Promise<GdriveCredentials>;
+/**
+ * Drive upload client.
+ *
+ * A lease's objectKey (e.g. `vaultline/<id>.vlarchive`) 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
+ * property — never by name, which Drive does not keep unique.
+ */
+export declare class GdriveUploadClient implements ProviderUploadClient {
+    private readonly endpoint;
+    private readonly credentials;
+    readonly kind: ProviderKind;
+    private folderId?;
+    private accessToken?;
+    private readonly chunkBytes;
+    private readonly fetchImpl;
+    private readonly now;
+    constructor(endpoint: GdriveEndpoint, credentials: GdriveCredentials, options?: {
+        chunkBytes?: number;
+        fetchImpl?: typeof fetch;
+        now?: () => number;
+    });
+    private base;
+    private tokenUrl;
+    private space;
+    /** Access token minted from the refresh token, cached until shortly before expiry so it never dies mid-chunk. */
+    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. */
+    private findByKey;
+    /** Finds or creates the archive folder; the id is cached per instance. */
+    private parentId;
+    /**
+     * Starts a resumable session (create, or in-place update when the key already
+     * has a file — re-uploading must never mint a same-named duplicate, or the
+     * appProperties lookup stops being exact). The session URI is a bearer
+     * capability: used immediately, never persisted, never logged.
+     */
+    private initiateResumable;
+    upload(lease: UploadLease, ciphertext: Buffer): 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>;
+}

package/dist/src/providers/gdrive.js

@@ -0,0 +1,335 @@
+import { createHash, randomBytes } from "node:crypto";
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+import { fail, VaultlineError } from "../errors.js";
+/**
+ * Google Drive as a bring-your-own storage provider (Drive API v3).
+ *
+ * The privacy story lives in the scope. Sealkeep asks Google for
+ * `drive.file` ONLY: in Google's permission model that grant lets an app see
+ * and touch just the files it created itself — never the rest of the Drive,
+ * not even file names. So connecting Sealkeep exposes nothing a person
+ * already keeps in Drive, and what Sealkeep does create there is ciphertext
+ * sealed on this machine before any byte leaves it.
+ *
+ * Authentication is the OAuth desktop flow with PKCE and a loopback redirect
+ * (RFC 8252): a local one-shot server on 127.0.0.1 receives the code, and the
+ * PKCE verifier — not a client secret, desktop apps cannot keep one — proves
+ * the exchange. The only long-lived secret is the refresh token, which goes
+ * into the OS keystore via secrets.ts and never into a config file.
+ */
+export const GDRIVE_SCOPE = "https://www.googleapis.com/auth/drive.file";
+/** Placeholder until a first-party client id ships. Point VAULTLINE_GDRIVE_CLIENT_ID at your own Desktop-app OAuth client to connect today. */
+export const GDRIVE_CLIENT_ID_PLACEHOLDER = "000000000000-vaultline-placeholder.apps.googleusercontent.com";
+export function gdriveClientId(env = process.env) {
+    return env.VAULTLINE_GDRIVE_CLIENT_ID?.trim() || GDRIVE_CLIENT_ID_PLACEHOLDER;
+}
+export const GDRIVE_AUTH_URL = "https://accounts.google.com/o/oauth2/v2/auth";
+export const GDRIVE_TOKEN_URL = "https://oauth2.googleapis.com/token";
+export const GDRIVE_API_BASE = "https://www.googleapis.com";
+const base64url = (buffer) => buffer.toString("base64url");
+/** RFC 7636 verifier/challenge pair: 32 random bytes → 43-char verifier, S256 challenge. */
+export function createPkcePair(random = () => randomBytes(32)) {
+    const verifier = base64url(random());
+    return { verifier, challenge: base64url(createHash("sha256").update(verifier).digest()), method: "S256" };
+}
+export function gdriveConsentUrl(input) {
+    const url = new URL(input.authUrl ?? GDRIVE_AUTH_URL);
+    url.searchParams.set("client_id", input.clientId);
+    url.searchParams.set("redirect_uri", input.redirectUri);
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("scope", GDRIVE_SCOPE);
+    url.searchParams.set("code_challenge", input.challenge);
+    url.searchParams.set("code_challenge_method", "S256");
+    url.searchParams.set("state", input.state);
+    // A refresh token is only issued for offline access, and only reliably when
+    // consent is re-prompted; without both, a reconnect can come back token-less.
+    url.searchParams.set("access_type", "offline");
+    url.searchParams.set("prompt", "consent");
+    return url.toString();
+}
+export async function exchangeCodeForTokens(input) {
+    const fetchImpl = input.fetchImpl ?? fetch;
+    const response = await fetchImpl(input.tokenUrl ?? GDRIVE_TOKEN_URL, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+            grant_type: "authorization_code",
+            code: input.code,
+            client_id: input.clientId,
+            redirect_uri: input.redirectUri,
+            code_verifier: input.verifier
+        }).toString()
+    });
+    if (!response.ok)
+        fail("unauthorized", `Google rejected the authorization code: ${response.status} ${response.statusText}`, { status: response.status });
+    const data = await response.json();
+    const refreshToken = data.refresh_token
+        ?? fail("unauthorized", "Google returned no refresh token. Remove Sealkeep at https://myaccount.google.com/permissions and connect again.");
+    return { refreshToken, accessToken: data.access_token ?? "", expiresIn: data.expires_in ?? 0 };
+}
+/**
+ * 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
+ * mirrors ui-server's opener rules (BROWSER wins, `none` means don't) without
+ * importing that module: ui-server reaches local-api, and a provider that
+ * pulled the whole API surface into every upload would be an import cycle.
+ */
+export function launchBrowser(url, env = process.env, platformName = process.platform) {
+    const preference = env.BROWSER?.trim();
+    if (preference?.toLowerCase() === "none")
+        return;
+    const opener = preference ? { command: preference, args: [url] }
+        : platformName === "darwin" ? { command: "open", args: [url] }
+            : platformName === "win32" ? { command: "cmd", args: ["/c", "start", "", url] }
+                : { command: "xdg-open", args: [url] };
+    try {
+        const child = spawn(opener.command, opener.args, { detached: true, stdio: "ignore", windowsHide: true });
+        child.once("error", () => { });
+        child.unref();
+    }
+    catch { /* same: the printed URL is the fallback */ }
+}
+/**
+ * The whole consent dance: loopback server, consent URL, code, PKCE exchange.
+ * Returns the credential shape the keystore stores. Everything slow or
+ * environment-shaped (fetch, browser, endpoints) is injectable so the entire
+ * flow runs offline under test.
+ */
+export async function connectGdrive(options = {}) {
+    const clientId = options.clientId ?? gdriveClientId(options.env);
+    const { verifier, challenge } = createPkcePair();
+    const state = base64url(randomBytes(16));
+    const server = createServer();
+    await new Promise((ready, refuse) => { server.once("error", refuse); server.listen(options.port ?? 0, "127.0.0.1", ready); });
+    const port = server.address().port;
+    const redirectUri = `http://127.0.0.1:${port}/callback`;
+    const consentUrl = gdriveConsentUrl({ clientId, redirectUri, challenge, state, authUrl: options.authUrl });
+    let timer;
+    const code = new Promise((resolve, reject) => {
+        timer = setTimeout(() => reject(new VaultlineError("unauthorized", `No response from the browser within ${Math.round((options.timeoutMs ?? 300_000) / 1000)}s. Run the connect command again.`)), options.timeoutMs ?? 300_000);
+        server.on("request", (request, response) => {
+            const url = new URL(request.url ?? "/", `http://127.0.0.1:${port}`);
+            if (url.pathname !== "/callback") {
+                response.writeHead(404);
+                response.end();
+                return;
+            }
+            const deny = (message) => {
+                response.writeHead(400, { "content-type": "text/html; charset=utf-8" });
+                response.end("<p>Sealkeep could not finish connecting. Return to the terminal.</p>");
+                reject(new VaultlineError("unauthorized", message));
+            };
+            if (url.searchParams.get("error"))
+                return deny(`Google reported: ${url.searchParams.get("error")}`);
+            // A code arriving under the wrong state was not minted for this attempt;
+            // accepting it would let anything that can reach 127.0.0.1 splice its own
+            // account into this vault's uploads.
+            if (url.searchParams.get("state") !== state)
+                return deny("The browser reply did not match this connection attempt (state mismatch)");
+            const received = url.searchParams.get("code");
+            if (!received)
+                return deny("The browser reply carried no authorization code");
+            response.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+            response.end("<p>Sealkeep is connected to Google Drive. You can close this tab.</p>");
+            resolve(received);
+        });
+    });
+    // A denial can land while the opener is still being awaited, before anything
+    // awaits `code`; without a handler already attached that early rejection is
+    // "unhandled" and can bring the process down instead of failing the command.
+    code.catch(() => { });
+    try {
+        options.onConsentUrl?.(consentUrl);
+        await Promise.resolve((options.opener ?? launchBrowser)(consentUrl)).catch(() => { });
+        const authorizationCode = await code;
+        const tokens = await exchangeCodeForTokens({ code: authorizationCode, verifier, clientId, redirectUri, tokenUrl: options.tokenUrl, fetchImpl: options.fetchImpl });
+        return { kind: "gdrive", refreshToken: tokens.refreshToken, clientId };
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        server.close();
+    }
+}
+/** Drive query strings quote values with single quotes; backslash-escape the two characters that break out. */
+const escapeQuery = (value) => value.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+const FOLDER_MIME = "application/vnd.google-apps.folder";
+/**
+ * Drive upload client.
+ *
+ * A lease's objectKey (e.g. `vaultline/<id>.vlarchive`) 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
+ * property — never by name, which Drive does not keep unique.
+ */
+export class GdriveUploadClient {
+    endpoint;
+    credentials;
+    // "gdrive" is not yet in control-plane's ProviderKind union — that file (and its
+    // restatements in types.ts / local-api.ts) is frozen in this change, so the new
+    // kind rides through under a cast contained to this one line. Remove the cast
+    // when the union learns "gdrive".
+    kind = "gdrive";
+    folderId;
+    accessToken;
+    chunkBytes;
+    fetchImpl;
+    now;
+    constructor(endpoint, credentials, options = {}) {
+        this.endpoint = endpoint;
+        this.credentials = credentials;
+        this.chunkBytes = options.chunkBytes ?? 8 * 1024 * 1024;
+        // Drive rejects resumable chunks that are not 256 KiB multiples (except the last).
+        if (this.chunkBytes % (256 * 1024) !== 0 || this.chunkBytes <= 0) {
+            fail("invalid_argument", `Drive resumable chunks must be positive multiples of 256 KiB, not ${this.chunkBytes} bytes`);
+        }
+        this.fetchImpl = options.fetchImpl ?? fetch;
+        this.now = options.now ?? Date.now;
+    }
+    base() {
+        const { host, port, protocol } = this.endpoint;
+        if (!host)
+            return GDRIVE_API_BASE;
+        return `${protocol ?? "https"}://${host}${port ? `:${port}` : ""}`;
+    }
+    tokenUrl() { return this.endpoint.host ? `${this.base()}/token` : GDRIVE_TOKEN_URL; }
+    space() { return this.endpoint.appData ? "appDataFolder" : "drive"; }
+    /** Access token minted from the refresh token, cached until shortly before expiry so it never dies mid-chunk. */
+    async token() {
+        if (this.accessToken && this.now() < this.accessToken.expiresAt)
+            return this.accessToken.token;
+        // A cloud-exchanged credential refreshes through the account's server —
+        // the web client's secret lives there, never in this process.
+        if (this.credentials.refresher) {
+            const fresh = await this.credentials.refresher(this.credentials.refreshToken);
+            this.accessToken = { token: fresh.accessToken, expiresAt: this.now() + Math.max(fresh.expiresIn - 60, 60) * 1000 };
+            return fresh.accessToken;
+        }
+        const response = await this.fetchImpl(this.tokenUrl(), {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({ grant_type: "refresh_token", refresh_token: this.credentials.refreshToken, client_id: this.credentials.clientId }).toString()
+        });
+        if (!response.ok)
+            fail("unauthorized", `Google Drive refused to mint an access token (${response.status}). Reconnect with: sealkeep storage connect gdrive`, { status: response.status });
+        const data = await response.json();
+        const token = data.access_token ?? fail("unauthorized", "Google Drive's token response carried no access token");
+        this.accessToken = { token, expiresAt: this.now() + Math.max((data.expires_in ?? 0) - 60, 60) * 1000 };
+        return token;
+    }
+    async api(path, init = {}) {
+        const token = await this.token();
+        return this.fetchImpl(`${this.base()}${path}`, { ...init, headers: { authorization: `Bearer ${token}`, ...init.headers } });
+    }
+    async list(query) {
+        const params = new URLSearchParams({ q: query, spaces: this.space(), fields: "files(id,name,size,md5Checksum)", pageSize: "10" });
+        const response = await this.api(`/drive/v3/files?${params.toString()}`);
+        if (!response.ok)
+            fail("internal", `Google Drive file lookup failed: ${response.status} ${response.statusText}`, { status: response.status });
+        const data = await response.json();
+        return data.files ?? [];
+    }
+    /** Exact lookup by the appProperties key. Two files claiming one key is a state we refuse to guess about. */
+    async findByKey(objectKey) {
+        const files = await this.list(`appProperties has { key = 'vaultlineKey' and value = '${escapeQuery(objectKey)}' } and trashed = false`);
+        if (files.length > 1)
+            fail("internal", `Google Drive holds ${files.length} files claiming ${objectKey}; refusing to pick one`, { objectKey, count: files.length });
+        return files[0] ?? null;
+    }
+    /** Finds or creates the archive folder; the id is cached per instance. */
+    async parentId() {
+        if (this.endpoint.appData)
+            return "appDataFolder";
+        if (this.folderId)
+            return this.folderId;
+        const name = this.endpoint.folderName;
+        const existing = (await this.list(`name = '${escapeQuery(name)}' and mimeType = '${FOLDER_MIME}' and trashed = false`))[0]?.id;
+        if (existing) {
+            this.folderId = existing;
+            return existing;
+        }
+        const response = await this.api("/drive/v3/files?fields=id", {
+            method: "POST",
+            headers: { "content-type": "application/json; charset=UTF-8" },
+            body: JSON.stringify({ name, mimeType: FOLDER_MIME })
+        });
+        if (!response.ok)
+            fail("internal", `Could not create the "${name}" folder in Google Drive: ${response.status} ${response.statusText}`, { status: response.status });
+        const created = await response.json();
+        this.folderId = created.id ?? fail("internal", "Drive created a folder but returned no id");
+        return this.folderId;
+    }
+    /**
+     * Starts a resumable session (create, or in-place update when the key already
+     * has a file — re-uploading must never mint a same-named duplicate, or the
+     * appProperties lookup stops being exact). The session URI is a bearer
+     * capability: used immediately, never persisted, never logged.
+     */
+    async initiateResumable(objectKey, existingFileId, totalBytes) {
+        const metadata = existingFileId
+            ? { appProperties: { vaultlineKey: objectKey } }
+            : { name: objectKey.split("/").pop() ?? objectKey, parents: [await this.parentId()], appProperties: { vaultlineKey: objectKey } };
+        const response = await this.api(existingFileId ? `/upload/drive/v3/files/${existingFileId}?uploadType=resumable` : "/upload/drive/v3/files?uploadType=resumable", {
+            method: existingFileId ? "PATCH" : "POST",
+            headers: { "content-type": "application/json; charset=UTF-8", "x-upload-content-length": String(totalBytes) },
+            body: JSON.stringify(metadata)
+        });
+        if (!response.ok)
+            fail("internal", `Could not start a Drive resumable upload for ${objectKey}: ${response.status} ${response.statusText}`, { objectKey, status: response.status });
+        return response.headers.get("location") ?? fail("internal", `Drive's resumable initiation for ${objectKey} returned no session URI`, { objectKey });
+    }
+    async upload(lease, ciphertext) {
+        const objectKey = lease.objectKey;
+        const existing = await this.findByKey(objectKey);
+        const session = await this.initiateResumable(objectKey, existing?.id ?? null, ciphertext.length);
+        for (let offset = 0; offset < Math.max(ciphertext.length, 1); offset += this.chunkBytes) {
+            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 this.fetchImpl(session, { method: "PUT", body: new Uint8Array(slice), headers: { "content-range": range } });
+            // 308 is "resume incomplete", the expected status between chunks.
+            if (!response.ok && !(response.status === 308 && !last)) {
+                fail("internal", `Drive resumable upload for ${objectKey} failed at ${range}: ${response.status} ${response.statusText}`, { objectKey, status: response.status });
+            }
+            if (last)
+                break;
+        }
+        // The whole-object proof Drive reports back is `md5Checksum` in file
+        // metadata, as lowercase hex — it computes no SHA-256, and unlike GCS's
+        // base64 header this one is hex. The verifier in upload.ts compares this
+        // value against head()'s, so both sides must speak that same hex dialect;
+        // MD5 here is transport proof, not trust — the ciphertext is
+        // AEAD-authenticated and restore re-checks its SHA-256 independently.
+        return { remoteChecksum: createHash("md5").update(ciphertext).digest("hex"), bytes: ciphertext.length };
+    }
+    async head(lease) {
+        const file = await this.findByKey(lease.objectKey);
+        if (!file)
+            return { exists: false, bytes: 0 };
+        // `md5Checksum` (hex) is absent for Google-native docs but always present
+        // for binary content we wrote. If it is ever missing the object cannot be
+        // proven from here, and undefined makes the verifier refuse rather than pretend.
+        return { exists: true, bytes: Number(file.size ?? "0"), checksum: file.md5Checksum };
+    }
+    /** 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. */
+    async deleteByKey(objectKey) {
+        const existing = await this.findByKey(objectKey);
+        if (!existing)
+            return;
+        const response = await this.api(`/drive/v3/files/${existing.id}`, { method: "DELETE" });
+        if (!response.ok && response.status !== 404) {
+            fail("internal", `Drive refused the delete: ${response.status} ${response.statusText}. The stored copy may still be there.`);
+        }
+    }
+    async download(lease) {
+        const file = await this.findByKey(lease.objectKey)
+            ?? fail("archive_not_found", `Google Drive holds no file for ${lease.objectKey}`, { key: lease.objectKey });
+        const response = await this.api(`/drive/v3/files/${file.id}?alt=media`);
+        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());
+    }
+}

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

@@ -0,0 +1,45 @@
+import { type BackendName, type ProviderCredentials } from "../secrets.js";
+import { type ProviderConfig, type ProviderKind, type ProviderUploadClient, type UploadLease } from "../control-plane.js";
+import { S3UploadClient } from "./s3.js";
+import { GcsUploadClient } from "./gcs.js";
+import { GdriveUploadClient } from "./gdrive.js";
+export type EndpointOverrides = {
+    host?: string;
+    port?: number;
+    protocol?: "https" | "http";
+    pathStyle?: boolean;
+    partBytes?: number;
+    allowSmallParts?: boolean;
+};
+/**
+ * "gdrive" rides alongside control-plane's ProviderKind rather than inside it:
+ * that union (and its restatements in types.ts and local-api.ts) is frozen in
+ * this change, so the widening lives here at the edge that accepts the new
+ * provider. Fold it into ProviderKind when the control-plane learns "gdrive".
+ */
+export type UploadProviderKind = ProviderKind | "gdrive";
+export type UploadProviderConfig = Omit<ProviderConfig, "provider"> & {
+    provider: UploadProviderKind;
+};
+/**
+ * Builds the client for a configured provider. This is the only place a credential
+ * is handed to a network client, and the feature flag is checked here rather than
+ * at import time so an operator can turn uploads off without a restart.
+ */
+export declare function createUploadClient(config: UploadProviderConfig, credentials: ProviderCredentials, overrides?: EndpointOverrides, env?: NodeJS.ProcessEnv): ProviderUploadClient;
+export declare function uploadClientFromStore(dataDir: string, storageConfigId: string, config: UploadProviderConfig, overrides?: EndpointOverrides, backend?: BackendName): Promise<ProviderUploadClient>;
+/**
+ * Mints a lease that a configured client may actually use.
+ *
+ * The object key is derived from the configured prefix and the archive id; a caller
+ * cannot choose it, which keeps one account's objects inside its own prefix.
+ */
+export declare function createActiveLease(config: UploadProviderConfig, input: {
+    archiveId?: string;
+    ciphertextSha256: string;
+    bytes: number;
+    now?: number;
+    ttlMs?: number;
+}, env?: NodeJS.ProcessEnv): UploadLease;
+export { S3UploadClient, GcsUploadClient, GdriveUploadClient };
+export type { ProviderKind };

package/dist/src/providers/index.js

@@ -0,0 +1,74 @@
+import { randomUUID } from "node:crypto";
+import { fail } from "../errors.js";
+import { loadProviderCredentials } from "../secrets.js";
+import { DEFAULT_LEASE_TTL_MS, signerEnabled } from "../control-plane.js";
+import { S3UploadClient } from "./s3.js";
+import { GcsUploadClient } from "./gcs.js";
+import { GdriveUploadClient } from "./gdrive.js";
+function isAwsStyle(credentials) {
+    return "accessKeyId" in credentials;
+}
+function isGdriveCredentials(credentials) {
+    return "kind" in credentials && credentials.kind === "gdrive";
+}
+/**
+ * Builds the client for a configured provider. This is the only place a credential
+ * is handed to a network client, and the feature flag is checked here rather than
+ * at import time so an operator can turn uploads off without a restart.
+ */
+export function createUploadClient(config, credentials, overrides = {}, env = process.env) {
+    if (!signerEnabled(env))
+        fail("signer_not_configured", "Uploads are disabled. Set VAULTLINE_ENABLE_SIGNER=1 to enable a configured provider client.", { provider: config.provider });
+    if (config.provider === "gdrive") {
+        if (!isGdriveCredentials(credentials))
+            fail("invalid_argument", "Google Drive needs an OAuth credential. Run: sealkeep storage connect gdrive");
+        // Drive has no buckets: the configured bucket names the archive folder, and
+        // a prefix of "appdata" selects the hidden per-app appDataFolder space.
+        return new GdriveUploadClient({ folderName: config.bucket, appData: config.prefix.replace(/^\/+|\/+$/g, "") === "appdata", host: overrides.host, port: overrides.port, protocol: overrides.protocol }, credentials);
+    }
+    if (config.provider === "gcs") {
+        if (isAwsStyle(credentials) || isGdriveCredentials(credentials))
+            fail("invalid_argument", "GCS needs a service-account credential, not an access key or OAuth token");
+        return new GcsUploadClient({ bucket: config.bucket, host: overrides.host, port: overrides.port, protocol: overrides.protocol }, credentials);
+    }
+    if (!isAwsStyle(credentials))
+        fail("invalid_argument", `${config.provider} needs an access key credential, not a service account or OAuth token`);
+    const endpoint = { provider: config.provider === "vaultline" ? "s3" : config.provider, region: config.region ?? "auto", bucket: config.bucket, host: overrides.host, port: overrides.port, protocol: overrides.protocol, pathStyle: overrides.pathStyle };
+    return new S3UploadClient(config.provider, endpoint, credentials, overrides.partBytes, overrides.allowSmallParts);
+}
+export async function uploadClientFromStore(dataDir, storageConfigId, config, overrides = {}, backend) {
+    const credentials = await loadProviderCredentials(dataDir, storageConfigId, backend);
+    // A Drive credential minted through the account's server refreshes there
+    // too — attach the (runtime-only) refresher with the dataDir it needs.
+    if (isGdriveCredentials(credentials) && credentials.exchange === "cloud") {
+        const { gdriveRefresh } = await import("../cloud.js");
+        credentials.refresher = (refreshToken) => gdriveRefresh(dataDir, refreshToken);
+    }
+    return createUploadClient(config, credentials, overrides);
+}
+/**
+ * Mints a lease that a configured client may actually use.
+ *
+ * The object key is derived from the configured prefix and the archive id; a caller
+ * cannot choose it, which keeps one account's objects inside its own prefix.
+ */
+export function createActiveLease(config, input, env = process.env) {
+    if (!signerEnabled(env))
+        fail("signer_not_configured", "Active leases require an enabled signer", { provider: config.provider });
+    if (!config.bucket || !config.prefix)
+        fail("invalid_argument", "bucket and prefix are required");
+    const archiveId = input.archiveId ?? randomUUID();
+    const issuedAt = input.now ?? Date.now();
+    return {
+        // UploadLease.provider is still control-plane's narrower union; the cast
+        // goes away with the UploadProviderKind widening above.
+        archiveId, provider: config.provider,
+        objectKey: `${config.prefix.replace(/^\/+|\/+$/g, "")}/${archiveId}.vlarchive`,
+        expiresAt: new Date(issuedAt + (input.ttlMs ?? DEFAULT_LEASE_TTL_MS)).toISOString(),
+        method: config.provider === "gcs" || config.provider === "gdrive" ? "RESUMABLE" : "MULTIPART",
+        uploadUrl: `${config.provider}://${config.bucket}/${config.prefix.replace(/^\/+|\/+$/g, "")}/${archiveId}.vlarchive`,
+        requiredHeaders: { "content-type": "application/vnd.vaultline.ciphertext", "x-vaultline-ciphertext-sha256": input.ciphertextSha256, "content-length": String(input.bytes) },
+        status: "active", uploadable: true
+    };
+}
+export { S3UploadClient, GcsUploadClient, GdriveUploadClient };