sealkeep 0.5.0

package/dist/src/passkey.js

@@ -0,0 +1,54 @@
+import { createPublicKey, hkdfSync, randomBytes } from "node:crypto";
+import { fail } from "./errors.js";
+import { x25519PrivateKeyFromRaw } from "../packages/vaultline-crypto/src/index.js";
+/**
+ * Touch ID as a second way into a vault, built on the WebAuthn PRF extension.
+ *
+ * The recovery phrase is the thing people lose. It is written down once, months
+ * before it matters, and a vault with exactly one key is a vault that a bad
+ * afternoon can destroy. A passkey fixes that without weakening anything: it is
+ * an *additional* recipient on the envelope, so forgetting the phrase stops
+ * being fatal while the phrase remains the way back when the machine is gone.
+ *
+ * The mechanism is the PRF extension. An authenticator that supports it will,
+ * given a fixed salt, return the same 32 secret bytes every time the user
+ * presents their finger — and will not return them to any other origin, or to
+ * anyone who cannot pass the biometric. Those bytes are not used as a key
+ * directly; they are run through HKDF into an X25519 private key, whose public
+ * half is registered as an ordinary recipient. Nothing new appears in the
+ * envelope format, and a vault with a passkey is readable by a build that has
+ * never heard of one.
+ *
+ * What is deliberately *not* stored anywhere is the private key. It exists only
+ * for as long as it takes to unwrap, and it is re-derived from the finger each
+ * time. Losing the machine loses the passkey, which is exactly why the phrase
+ * still exists.
+ */
+/** Domain separation, so the same authenticator used elsewhere cannot collide with this. */
+const INFO = Buffer.from("vaultline-passkey-recipient:v1");
+export const PRF_SECRET_BYTES = 32;
+/** A fresh per-vault salt, evaluated by the authenticator to produce the secret. */
+export function generatePrfSalt() {
+    return randomBytes(32).toString("base64");
+}
+/**
+ * The X25519 identity that a given passkey secret always produces.
+ *
+ * Deterministic on purpose: enrolment registers the public half, and every
+ * later unlock re-derives the private half from the same finger. If this were
+ * random, a passkey could enrol but never open anything.
+ */
+export function keysFromPrfSecret(secret) {
+    if (secret.length !== PRF_SECRET_BYTES) {
+        fail("invalid_argument", `A passkey secret must be ${PRF_SECRET_BYTES} bytes, got ${secret.length}`);
+    }
+    const material = Buffer.from(hkdfSync("sha256", secret, Buffer.alloc(0), INFO, 32));
+    const privateKey = x25519PrivateKeyFromRaw(material);
+    const publicKeyBase64 = createPublicKey(privateKey).export({ type: "spki", format: "der" }).subarray(-32).toString("base64");
+    return { publicKeyBase64, privateKeyRaw: material };
+}
+export function isPasskeyRecord(value) {
+    const record = value;
+    return !!record && typeof record.credentialId === "string" && typeof record.prfSalt === "string"
+        && typeof record.label === "string" && typeof record.recipientId === "string";
+}

package/dist/src/password-lock.d.ts

@@ -0,0 +1,19 @@
+import { VaultlineError } from "./errors.js";
+export declare const passwordLockPath: (dataDir: string) => string;
+/**
+ * Structural damage, as opposed to a wrong password. Carries no hint about
+ * either secret, and its message is written for the window: what stopped
+ * working, what did not, and the way back in.
+ */
+export declare class PasswordLockCorruptError extends VaultlineError {
+    constructor(path: string, reason: string);
+}
+/** Seals the canonical phrase under a password, replacing any previous lock in one atomic step. */
+export declare function wrapPhrase(dataDir: string, phrase: string, password: string): Promise<void>;
+/**
+ * Trades a password for the phrase. Null means exactly one thing — the
+ * password does not open this lock — so callers can say so without hedging;
+ * a file that is damaged in any detectable way throws instead.
+ */
+export declare function unwrapPhrase(dataDir: string, password: string): Promise<string | null>;
+export declare function hasPasswordLock(dataDir: string): Promise<boolean>;

package/dist/src/password-lock.js

@@ -0,0 +1,156 @@
+import { randomBytes, scryptSync } from "node:crypto";
+import { chmod, mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { aeadCipher, aeadDecipher } from "../packages/vaultline-crypto/src/aead.js";
+import { TAG_BYTES } from "../packages/vaultline-crypto/src/format.js";
+import { fail, VaultlineError } from "./errors.js";
+/**
+ * A password in front of the phrase, never instead of it.
+ *
+ * Free users get to unlock with something they can remember, but the archive
+ * format and its guarantees do not move an inch: the password seals this
+ * vault's canonical 24-word phrase into a file on this machine, and unwrapping
+ * it yields that same phrase for the keystore. Losing the password loses
+ * nothing archival — the written-down phrase still opens everything, here or
+ * on a machine that has never seen this file. The lock never leaves this
+ * machine and is deliberately excluded from what a vault backup means.
+ *
+ * The scrypt cost matches every other phrase-derived key in this repo
+ * (crypto.ts, vaultline-crypto/recipients.ts), so config.json's history does
+ * not repeat: the file guarding the phrase must never be cheaper to attack
+ * than the envelopes sitting next to it.
+ */
+const SCRYPT = { N: 1 << 15, r: 8, p: 1 };
+/** 128·N·r for these params is exactly Node's default cap, so state the budget explicitly like crypto.ts does. */
+const MAXMEM = 128 * 1024 * 1024;
+const KEY_BYTES = 32;
+const SALT_BYTES = 16;
+const NONCE_BYTES = 12;
+const AAD = Buffer.from("vaultline-phrase-lock:v1");
+export const passwordLockPath = (dataDir) => join(dataDir, "phrase.lock");
+/**
+ * Structural damage, as opposed to a wrong password. Carries no hint about
+ * either secret, and its message is written for the window: what stopped
+ * working, what did not, and the way back in.
+ */
+export class PasswordLockCorruptError extends VaultlineError {
+    constructor(path, reason) {
+        super("ciphertext_integrity_failed", "The saved password lock on this machine is damaged, so a password cannot unlock this vault. Your archives and your recovery phrase are unaffected — unlock with the phrase, then choose a password again.", { path, reason });
+        this.name = "PasswordLockCorruptError";
+    }
+}
+function corrupt(path, reason) {
+    throw new PasswordLockCorruptError(path, reason);
+}
+/**
+ * Everything detectably wrong with the file is rejected here, by name, because
+ * past this point the AEAD tag cannot tell a flipped ciphertext bit from a
+ * wrong password — so this parse is the entire basis for the null-vs-throw
+ * contract `unwrapPhrase` promises its callers.
+ */
+function parseEnvelope(raw, path) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        corrupt(path, "not JSON");
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        corrupt(path, "not an object");
+    const envelope = parsed;
+    if (envelope.v !== 1) {
+        if (typeof envelope.v === "number" && envelope.v > 1)
+            fail("config_unsupported_version", "This password lock was written by a newer Sealkeep. Update Sealkeep on this machine, or unlock with your recovery phrase.", { path, version: envelope.v });
+        corrupt(path, "unrecognised version");
+    }
+    const kdf = envelope.kdf;
+    if (typeof kdf !== "object" || kdf === null || kdf.name !== "scrypt")
+        corrupt(path, "unrecognised kdf");
+    const { N, r, p } = kdf;
+    // Bounds double as a memory guard: parameters are honoured from the file for
+    // forward compatibility, so a doctored file must not be able to turn scrypt
+    // into a memory bomb or into something cheap enough to brute-force.
+    if (typeof N !== "number" || !Number.isInteger(N) || N < 1 << 14 || N > 1 << 20 || (N & (N - 1)) !== 0)
+        corrupt(path, "scrypt N out of range");
+    if (typeof r !== "number" || !Number.isInteger(r) || r < 1 || r > 64)
+        corrupt(path, "scrypt r out of range");
+    if (typeof p !== "number" || !Number.isInteger(p) || p < 1 || p > 16)
+        corrupt(path, "scrypt p out of range");
+    if (128 * N * r * p > MAXMEM)
+        corrupt(path, "scrypt cost exceeds the memory budget");
+    for (const field of ["salt", "nonce", "box"]) {
+        if (typeof envelope[field] !== "string")
+            corrupt(path, `${field} is not a string`);
+    }
+    const salt = Buffer.from(envelope.salt, "base64");
+    const nonce = Buffer.from(envelope.nonce, "base64");
+    const box = Buffer.from(envelope.box, "base64");
+    if (salt.length !== SALT_BYTES)
+        corrupt(path, "salt is the wrong length");
+    if (nonce.length !== NONCE_BYTES)
+        corrupt(path, "nonce is the wrong length");
+    if (box.length <= TAG_BYTES)
+        corrupt(path, "box is too short to hold anything");
+    return envelope;
+}
+function derive(password, salt, params) {
+    // NFKD for the same reason recoveryKey normalizes the phrase: the same
+    // characters typed through different keyboards must derive the same key.
+    return scryptSync(password.normalize("NFKD"), salt, KEY_BYTES, { ...params, maxmem: MAXMEM });
+}
+/** Seals the canonical phrase under a password, replacing any previous lock in one atomic step. */
+export async function wrapPhrase(dataDir, phrase, password) {
+    // The same bounds the setup endpoint declares, enforced where the sealing
+    // happens so no caller can create a lock the wizard would have refused.
+    if (password.length < 8 || password.length > 1024)
+        fail("invalid_argument", "The vault password must be between 8 and 1024 characters.");
+    const salt = randomBytes(SALT_BYTES);
+    const nonce = randomBytes(NONCE_BYTES);
+    const cipher = aeadCipher("chacha20-poly1305", derive(password, salt, SCRYPT), nonce);
+    cipher.setAAD(AAD);
+    const box = Buffer.concat([cipher.update(Buffer.from(phrase, "utf8")), cipher.final(), cipher.getAuthTag()]);
+    const envelope = {
+        v: 1,
+        kdf: { name: "scrypt", ...SCRYPT },
+        salt: salt.toString("base64"),
+        nonce: nonce.toString("base64"),
+        box: box.toString("base64")
+    };
+    const path = passwordLockPath(dataDir);
+    // Temp-and-rename so a crash mid-write can only ever leave the old lock (or
+    // none), never a half-written file that would read as damage later.
+    const temp = `${path}.${randomBytes(6).toString("hex")}.tmp`;
+    await mkdir(dataDir, { recursive: true, mode: 0o700 });
+    await writeFile(temp, `${JSON.stringify(envelope)}\n`, { mode: 0o600 });
+    await chmod(temp, 0o600);
+    await rename(temp, path);
+}
+/**
+ * Trades a password for the phrase. Null means exactly one thing — the
+ * password does not open this lock — so callers can say so without hedging;
+ * a file that is damaged in any detectable way throws instead.
+ */
+export async function unwrapPhrase(dataDir, password) {
+    const path = passwordLockPath(dataDir);
+    const raw = await readFile(path, "utf8").catch(() => null);
+    if (raw === null)
+        fail("recovery_phrase_missing", "This vault has no password lock on this machine.", { path });
+    const envelope = parseEnvelope(raw, path);
+    const box = Buffer.from(envelope.box, "base64");
+    const decipher = aeadDecipher("chacha20-poly1305", derive(password, Buffer.from(envelope.salt, "base64"), envelope.kdf), Buffer.from(envelope.nonce, "base64"));
+    decipher.setAAD(AAD);
+    decipher.setAuthTag(box.subarray(box.length - TAG_BYTES));
+    try {
+        return Buffer.concat([decipher.update(box.subarray(0, box.length - TAG_BYTES)), decipher.final()]).toString("utf8");
+    }
+    catch {
+        // The one failure the tag cannot attribute: an undamaged-looking box that
+        // does not authenticate. Anything an attacker could learn from splitting
+        // this further is an oracle, so it stays a single answer: not this password.
+        return null;
+    }
+}
+export async function hasPasswordLock(dataDir) {
+    return (await stat(passwordLockPath(dataDir)).catch(() => null)) !== null;
+}

package/dist/src/paths.d.ts

@@ -0,0 +1,9 @@
+export declare const localApiTokenPath: (dataDir: string) => string;
+/**
+ * Finds the bundled `web/` directory by walking up from this module.
+ *
+ * The compiled layout (`dist/src/…`) and the `tsx` layout (`src/…`) sit at different
+ * depths, and the published package flattens things again, so the marker file is
+ * located rather than assumed.
+ */
+export declare function findWebRoot(from?: string): string;

package/dist/src/paths.js

@@ -0,0 +1,24 @@
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+export const localApiTokenPath = (dataDir) => join(dataDir, "local-api-token");
+/**
+ * Finds the bundled `web/` directory by walking up from this module.
+ *
+ * The compiled layout (`dist/src/…`) and the `tsx` layout (`src/…`) sit at different
+ * depths, and the published package flattens things again, so the marker file is
+ * located rather than assumed.
+ */
+export function findWebRoot(from = dirname(fileURLToPath(import.meta.url))) {
+    let directory = resolve(from);
+    for (let depth = 0; depth < 6; depth += 1) {
+        const candidate = join(directory, "web");
+        if (existsSync(join(candidate, "index.html")))
+            return candidate;
+        const parent = dirname(directory);
+        if (parent === directory)
+            break;
+        directory = parent;
+    }
+    return join(resolve(from), "..", "web");
+}

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

@@ -0,0 +1,133 @@
+import type { ProviderUploadClient, UploadLease } from "../control-plane.js";
+/**
+ * Google Cloud Storage V4 signing (`GOOG4-RSA-SHA256`) plus resumable uploads.
+ *
+ * The canonical request has the same shape as AWS SigV4; the difference is the
+ * algorithm label, the `goog4_request` scope terminator, and an RSA-SHA256
+ * signature made with a service-account private key instead of an HMAC.
+ */
+export declare const GCS_ALGORITHM = "GOOG4-RSA-SHA256";
+export type ServiceAccount = {
+    clientEmail: string;
+    privateKey: string;
+};
+export type GcsEndpoint = {
+    bucket: string;
+    host?: string;
+    port?: number;
+    protocol?: "https" | "http";
+};
+export declare function gcsCredentialScope(date: string): string;
+export type GcsSignInput = {
+    method: string;
+    bucket: string;
+    object: string;
+    serviceAccount: ServiceAccount;
+    expiresInSeconds?: number;
+    headers?: Record<string, string>;
+    query?: Record<string, string>;
+    when?: Date;
+    host?: string;
+    port?: number;
+    protocol?: "https" | "http";
+};
+export declare function signGcsUrl(input: GcsSignInput): {
+    url: string;
+    signature: string;
+    canonicalRequest: string;
+    stringToSign: string;
+    expiresAt: string;
+};
+/** Everything a crashed resumable upload needs to continue. Journal exactly
+ *  this shape. The session URI inside is a bearer capability: the journal that
+ *  holds it must be protected like a credential, and it never belongs in logs
+ *  or error messages. */
+export type GcsStreamState = {
+    session: string;
+    confirmedBytes: number;
+};
+export type GcsStreamOptions = {
+    /** State from an earlier run's onState: skips initiation, asks the session
+     *  how much the provider confirmed, and requires the incoming stream to
+     *  start exactly there. `confirmedBytes` is how a mismatch — say, a PUT that
+     *  landed after the journal's last write — is caught before a byte is sent. */
+    resume?: GcsStreamState;
+    /** 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>;
+};
+/**
+ * GCS resumable upload client.
+ *
+ * Initiation returns a session URI which is itself a bearer capability: it is used
+ * immediately, never persisted, and never logged.
+ */
+export declare class GcsUploadClient implements ProviderUploadClient {
+    private readonly endpoint;
+    private readonly serviceAccount;
+    private readonly chunkBytes;
+    readonly kind: "gcs";
+    constructor(endpoint: GcsEndpoint, serviceAccount: ServiceAccount, chunkBytes?: number);
+    private sign;
+    /** The chunk-folder layout's object verbs: plain signed single-object HTTP. */
+    putObject(object: string, body: Buffer): Promise<{
+        checksum: string;
+    }>;
+    headObject(object: string): Promise<{
+        exists: boolean;
+        bytes: number;
+        checksum?: string;
+    }>;
+    getObject(object: string): Promise<Buffer>;
+    deleteObject(object: string): Promise<void>;
+    /** Starts a resumable session and returns its URI. */
+    initiateResumable(object: string): 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
+     * `bytes *\/*` answers 308 with a `Range: bytes=0-N` header — N+1 bytes are
+     * 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<{
+        confirmedBytes: number;
+    }>;
+    upload(lease: UploadLease, ciphertext: Buffer): Promise<{
+        remoteChecksum: string;
+        bytes: number;
+    }>;
+    /**
+     * Streams an object up without ever holding it whole: the seal loop hands
+     * over stored chunks as it produces them, and this accumulates just enough
+     * to satisfy GCS's rule that every non-final resumable PUT be a multiple of
+     * 256 KiB. Peak memory is one flush buffer; the disk holds nothing at all.
+     *
+     * The rolling MD5 is the same provider-language proof `upload` returns, so
+     * the verifier in upload.ts treats a streamed object exactly like a copied
+     * one. Total size is unknown until the source ends — every intermediate PUT
+     * says `bytes X-Y/*`, and the final one names the total.
+     *
+     * Resume: `options.resume` reuses an earlier run's session instead of
+     * initiating. The provider's confirmed byte count is queried first, and the
+     * incoming stream must start exactly at `resume.confirmedBytes` — when the
+     * two disagree the first flush would land at the wrong offset, so the run
+     * refuses before sending anything. `options.onState` is awaited after every
+     * successful chunk PUT with the cumulative confirmed bytes — the journal's
+     * durability point.
+     */
+    uploadStream(objectKey: string, chunks: AsyncIterable<Buffer>): Promise<{
+        remoteChecksum: string;
+        bytes: number;
+    }>;
+    uploadStream(objectKey: string, chunks: AsyncIterable<Buffer>, options: GcsStreamOptions): Promise<{
+        remoteChecksum: string | null;
+        bytes: number;
+    }>;
+    /** Reads an object back for restore or offload-proof: a signed GET, whole. */
+    download(lease: UploadLease): Promise<Buffer>;
+    head(lease: UploadLease): Promise<{
+        exists: boolean;
+        bytes: number;
+        checksum?: string;
+    }>;
+}

package/dist/src/providers/gcs.js

@@ -0,0 +1,235 @@
+import { createHash, createPrivateKey, createSign } from "node:crypto";
+import { fail } from "../errors.js";
+import { amzDates, canonicalHeaders, canonicalQuery, canonicalUri } from "./sigv4.js";
+/**
+ * Google Cloud Storage V4 signing (`GOOG4-RSA-SHA256`) plus resumable uploads.
+ *
+ * The canonical request has the same shape as AWS SigV4; the difference is the
+ * algorithm label, the `goog4_request` scope terminator, and an RSA-SHA256
+ * signature made with a service-account private key instead of an HMAC.
+ */
+export const GCS_ALGORITHM = "GOOG4-RSA-SHA256";
+const sha256hex = (value) => createHash("sha256").update(value).digest("hex");
+export function gcsCredentialScope(date) { return `${date}/auto/storage/goog4_request`; }
+export function signGcsUrl(input) {
+    const when = input.when ?? new Date();
+    const { amzDate, date } = amzDates(when);
+    const expires = input.expiresInSeconds ?? 900;
+    const host = input.host ?? "storage.googleapis.com";
+    const authority = input.port ? `${host}:${input.port}` : host;
+    const headers = { host: authority, ...input.headers };
+    const { canonical, signed } = canonicalHeaders(headers);
+    const query = new Map(Object.entries(input.query ?? {}));
+    query.set("X-Goog-Algorithm", GCS_ALGORITHM);
+    query.set("X-Goog-Credential", `${input.serviceAccount.clientEmail}/${gcsCredentialScope(date)}`);
+    query.set("X-Goog-Date", amzDate);
+    query.set("X-Goog-Expires", String(expires));
+    query.set("X-Goog-SignedHeaders", signed);
+    const path = `/${input.bucket}/${input.object}`;
+    const canonicalRequest = [input.method.toUpperCase(), canonicalUri(path), canonicalQuery(query), canonical, signed, "UNSIGNED-PAYLOAD"].join("\n");
+    const stringToSign = [GCS_ALGORITHM, amzDate, gcsCredentialScope(date), sha256hex(canonicalRequest)].join("\n");
+    let key;
+    try {
+        key = createPrivateKey(input.serviceAccount.privateKey);
+    }
+    catch {
+        return fail("invalid_argument", "The service-account private key is not a readable PEM key");
+    }
+    if (key.asymmetricKeyType !== "rsa")
+        fail("invalid_argument", `GCS V4 signing needs an RSA service-account key, not ${String(key.asymmetricKeyType)}`);
+    const signature = createSign("RSA-SHA256").update(stringToSign).sign(key, "hex");
+    const protocol = input.protocol ?? "https";
+    return { url: `${protocol}://${authority}${canonicalUri(path)}?${canonicalQuery(query)}&X-Goog-Signature=${signature}`, signature, canonicalRequest, stringToSign, expiresAt: new Date(when.getTime() + expires * 1000).toISOString() };
+}
+/**
+ * GCS resumable upload client.
+ *
+ * Initiation returns a session URI which is itself a bearer capability: it is used
+ * immediately, never persisted, and never logged.
+ */
+export class GcsUploadClient {
+    endpoint;
+    serviceAccount;
+    chunkBytes;
+    kind = "gcs";
+    constructor(endpoint, serviceAccount, chunkBytes = 8 * 1024 * 1024) {
+        this.endpoint = endpoint;
+        this.serviceAccount = serviceAccount;
+        this.chunkBytes = chunkBytes;
+    }
+    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) {
+        const { url } = this.sign("PUT", object);
+        const response = await fetch(url, { method: "PUT", body: new Uint8Array(body) });
+        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) {
+        const { url } = this.sign("HEAD", object);
+        const response = await fetch(url, { method: "HEAD" });
+        if (response.status === 404)
+            return { exists: false, bytes: 0 };
+        if (!response.ok)
+            fail("internal", `Could not read ${object}: ${response.status} ${response.statusText}`, { object, status: response.status });
+        const hash = response.headers.get("x-goog-hash") ?? "";
+        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) {
+        const { url } = this.sign("GET", object);
+        const response = await fetch(url);
+        if (!response.ok)
+            fail("internal", `Could not download ${object}: ${response.status} ${response.statusText}`, { object, status: response.status });
+        return Buffer.from(await response.arrayBuffer());
+    }
+    async deleteObject(object) {
+        const { url } = this.sign("DELETE", object);
+        const response = await fetch(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) {
+        const { url } = this.sign("POST", object, { "x-goog-resumable": "start" });
+        const response = await fetch(url, { method: "POST", headers: { "x-goog-resumable": "start" } });
+        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");
+        return session ?? fail("internal", `Resumable initiation for ${object} returned no session URI`, { object });
+    }
+    /**
+     * Asks a session how many bytes the provider has durably confirmed, speaking
+     * the protocol GCS actually implements: an empty PUT whose content-range is
+     * `bytes *\/*` answers 308 with a `Range: bytes=0-N` header — N+1 bytes are
+     * 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 */*" } });
+        // 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)
+            fail("invalid_argument", "This resumable session has already been finalized; verify the stored object instead of resuming the upload.");
+        if (response.status !== 308)
+            fail("internal", `The resumable session status query answered ${response.status} ${response.statusText} instead of 308.`, { status: response.status });
+        const range = response.headers.get("range");
+        if (!range)
+            return { confirmedBytes: 0 };
+        const match = /^bytes=0-(\d+)$/.exec(range);
+        if (!match)
+            return fail("internal", `The resumable session reported a Range header this client cannot read: ${range}`, { range });
+        return { confirmedBytes: Number(match[1]) + 1 };
+    }
+    async upload(lease, ciphertext) {
+        const object = lease.objectKey;
+        const session = await this.initiateResumable(object);
+        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 fetch(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 });
+            }
+            if (last)
+                break;
+        }
+        // The strongest whole-object proof GCS reports back over HEAD is the MD5 it
+        // stored (`x-goog-hash`); it does not compute SHA-256. The verifier in
+        // upload.ts compares this value against head()'s, so both must speak the
+        // provider's language — returning a locally computed SHA-256 here made the
+        // comparison fail for every object and no GCS upload could ever be marked
+        // durable. MD5 is transport proof, not trust: the ciphertext is already
+        // AEAD-authenticated, and restore re-checks its SHA-256 independently.
+        return { remoteChecksum: createHash("md5").update(ciphertext).digest("base64"), bytes: ciphertext.length };
+    }
+    async uploadStream(objectKey, chunks, options = {}) {
+        const QUANTUM = 256 * 1024;
+        const resume = options.resume;
+        let session;
+        let sent = 0;
+        if (resume) {
+            const { confirmedBytes } = await this.resumableStatus(resume.session);
+            // 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
+            // wrong position, so refuse while nothing has been sent yet.
+            if (confirmedBytes !== resume.confirmedBytes) {
+                fail("invalid_argument", `Cannot resume the upload of ${objectKey}: the provider has confirmed ${confirmedBytes} bytes but the incoming stream starts at byte ${resume.confirmedBytes}; query resumableStatus and re-seal from the provider's count.`, { object: objectKey, confirmedBytes, resumeFrom: resume.confirmedBytes });
+            }
+            session = resume.session;
+            sent = confirmedBytes;
+        }
+        else {
+            session = await this.initiateResumable(objectKey);
+        }
+        // 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
+        // checksum from this run". The whole-object proof for a resumed upload is
+        // the caller's own resumable SHA-256 over the sealed stream, verified via
+        // size plus our stored hash rather than the provider's md5.
+        const md5 = resume ? null : createHash("md5");
+        let held = [];
+        let heldBytes = 0;
+        const putPiece = async (piece, final) => {
+            // A body-less finalize names the total as `bytes *\/N` — the shape GCS
+            // expects when the stream ends exactly on a flush boundary, and the N=0
+            // case doubles as the empty-object write.
+            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 } });
+            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 });
+            }
+            sent += piece.length;
+            // The journal's durability point: the provider now holds every byte
+            // below `sent`, so a crash after this callback can resume from here.
+            if (options.onState)
+                await options.onState({ session, confirmedBytes: sent });
+        };
+        for await (const chunk of chunks) {
+            md5?.update(chunk);
+            held.push(chunk);
+            heldBytes += chunk.length;
+            if (heldBytes >= Math.max(this.chunkBytes, QUANTUM)) {
+                const flushBytes = Math.floor(heldBytes / QUANTUM) * QUANTUM;
+                const buffered = Buffer.concat(held);
+                await putPiece(buffered.subarray(0, flushBytes), false);
+                held = flushBytes < buffered.length ? [buffered.subarray(flushBytes)] : [];
+                heldBytes = buffered.length - flushBytes;
+            }
+        }
+        await putPiece(Buffer.concat(held), true);
+        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 head(lease) {
+        const { url } = this.sign("HEAD", lease.objectKey);
+        const response = await fetch(url, { method: "HEAD" });
+        if (response.status === 404)
+            return { exists: false, bytes: 0 };
+        if (!response.ok)
+            fail("internal", `Could not read ${lease.objectKey}: ${response.status} ${response.statusText}`, { key: lease.objectKey, status: response.status });
+        // `x-goog-hash` carries `crc32c=…` and, for non-composite objects, `md5=…`
+        // (base64 values; the header may arrive as one joined value or two). Our
+        // resumable uploads are single-stream, so MD5 is always present for objects
+        // we wrote. When it is absent the object cannot be proven from here, and
+        // returning undefined makes the verifier refuse rather than pretend.
+        const hash = response.headers.get("x-goog-hash") ?? "";
+        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 };
+    }
+}