sealkeep 0.5.0

package/dist/src/start.js

@@ -0,0 +1,101 @@
+import { generateKeyPairSync } from "node:crypto";
+import { addRecipient, initialize } from "./vault.js";
+import { recoveryKit } from "./recovery.js";
+import { register, sealEscrow } from "./cloud.js";
+import { setupPlan } from "./storage-setup.js";
+import { fail, isVaultlineError } from "./errors.js";
+/** An X25519 keypair for this machine. The private half never leaves it unsealed. */
+export function generateDeviceKeys() {
+    const { publicKey, privateKey } = generateKeyPairSync("x25519");
+    return {
+        publicKeyBase64: publicKey.export({ type: "spki", format: "der" }).subarray(-32).toString("base64"),
+        privateKeyBase64: privateKey.export({ type: "pkcs8", format: "der" }).toString("base64")
+    };
+}
+/**
+ * Free tier: the vault is local and the bucket is theirs.
+ *
+ * We do not ask for cloud credentials and we cannot see their data. The reward
+ * for that is that they do the bucket setup — so we generate the exact console
+ * links, commands, and least-privilege policy rather than leaving them to guess.
+ */
+export async function startFree(dataDir, choice) {
+    const { config, phrase } = await initialize(dataDir);
+    const storageSetup = setupPlan({ provider: choice.provider, bucket: choice.bucket, prefix: choice.prefix, region: choice.region, accountId: choice.accountId, project: choice.project });
+    return {
+        mode: "free", vaultId: config.vaultId, phrase, recoveryKit: recoveryKit(config), storageSetup,
+        nextSteps: [
+            "Write down the recovery phrase. It is the only way to open your archives.",
+            "Follow the storage steps to create your bucket and a scoped credential.",
+            "Then run: sealkeep autopilot"
+        ]
+    };
+}
+/**
+ * Paid tier: they configure nothing.
+ *
+ * We hold the bucket and the bill; they hold the only key that opens the data.
+ * The escrow blob makes a lost machine survivable without making us able to
+ * read anything — it is sealed with the phrase before it leaves here.
+ */
+export async function startPaid(dataDir, choice) {
+    if (!choice.email.includes("@"))
+        fail("invalid_argument", "A real email address is required to recover a paid account");
+    if (choice.password.length < 12)
+        fail("invalid_argument", "Use a password of at least 12 characters");
+    const { config, phrase } = await initialize(dataDir);
+    const keys = generateDeviceKeys();
+    await addRecipient(dataDir, choice.label || "this machine", keys.publicKeyBase64);
+    const account = await register(dataDir, { email: choice.email, password: choice.password, label: choice.label });
+    // This is the only moment the device private key exists: it is generated
+    // above, its public half is registered as a recipient, and the private half
+    // is never written to disk. Sealing it and dropping the result — which is
+    // what used to happen here — left the escrow empty, made every archive's
+    // device wrap unopenable by anyone, and made the promise below false.
+    const material = { vaultId: config.vaultId, devicePrivateKey: keys.privateKeyBase64, createdAt: new Date().toISOString() };
+    const escrow = sealEscrow(material, phrase);
+    let sealed = true;
+    let escrowNote;
+    try {
+        const { pushEscrow } = await import("./cloud.js");
+        await pushEscrow(dataDir, material, phrase);
+    }
+    catch (error) {
+        // Do not fail the whole signup over this. The phrase alone still opens
+        // every archive, so the vault is usable — but say so plainly rather than
+        // printing a promise we did not keep.
+        sealed = false;
+        escrowNote = `The sealed copy of your key could not be stored (${isVaultlineError(error) ? error.code : "unexpected error"}). Run \`sealkeep recovery seal\` once you are online.`;
+    }
+    return {
+        mode: "paid", vaultId: config.vaultId, phrase, recoveryKit: recoveryKit(config), account, escrow,
+        nextSteps: [
+            sealed
+                ? "Write down the recovery phrase. We store a sealed copy of your key, but only this phrase opens it."
+                : "Write down the recovery phrase. It is the only thing that opens your archives.",
+            "If you lose the phrase, nobody — including us — can recover your archives.",
+            ...(escrowNote ? [escrowNote] : []),
+            "Then run: sealkeep autopilot"
+        ]
+    };
+}
+export async function start(dataDir, choice) {
+    return choice.mode === "paid" ? startPaid(dataDir, choice) : startFree(dataDir, choice);
+}
+/** What the first-run UI offers, before anything is created. */
+export function modeOptions() {
+    return [
+        {
+            mode: "free", title: "Free — your own storage",
+            summary: "No account, no bill. You set up the bucket; the setup time is yours.",
+            youProvide: ["A bucket you create yourself", "Its credential, pasted once", "The time it takes to get IAM right"],
+            weProvide: ["Encryption, archiving, search, retention", "Commands and a least-privilege policy if you want them"]
+        },
+        {
+            mode: "paid", title: "Paid — we run the storage",
+            summary: "You configure nothing. We create and run the bucket; you pick a GB package.",
+            youProvide: ["An email and password", "A recovery phrase you keep safe"],
+            weProvide: ["The bucket, the quota, the durability", "No IAM, no keys, no console — nothing to set up", "A sealed backup of your key that only your phrase opens"]
+        }
+    ];
+}

package/dist/src/storage-setup.d.ts

@@ -0,0 +1,49 @@
+import type { ProviderKind } from "./control-plane.js";
+/**
+ * Getting a bucket and a scoped credential is the step where people give up.
+ *
+ * So the product does the tedious part: it writes the exact console link, the exact
+ * commands with your own bucket and prefix already filled in, and a policy that
+ * grants the least it can — write and read inside your prefix, and nothing else.
+ *
+ * Nothing here runs anything or touches an account. It produces text you read,
+ * check, and paste yourself, which is the only honest way to hand someone an IAM
+ * policy.
+ */
+/** Providers the guided setup covers. "gdrive" is wider than control-plane's ProviderKind, which is frozen in this change. */
+export type SetupProviderKind = ProviderKind | "gdrive";
+export type SetupInput = {
+    provider: SetupProviderKind;
+    /** Bucket name — or, for Google Drive, the folder archives live in. */
+    bucket: string;
+    prefix: string;
+    region?: string;
+    /** Cloudflare account id, needed for the R2 endpoint. */
+    accountId?: string;
+    /** Google Cloud project id. */
+    project?: string;
+};
+export type SetupStep = {
+    title: string;
+    /** Why this step exists, in one line. */
+    why: string;
+    /** A link that opens the right page already scoped where possible. */
+    link?: string;
+    /** Commands to paste, with the user's own values filled in. */
+    commands?: string[];
+    /** A policy or config document to paste into a form. */
+    document?: {
+        name: string;
+        body: string;
+    };
+};
+export type SetupPlan = {
+    provider: SetupProviderKind;
+    bucket: string;
+    prefix: string;
+    steps: SetupStep[];
+    /** What to run once the credential exists. */
+    finish: string[];
+    notes: string[];
+};
+export declare function setupPlan(input: SetupInput): SetupPlan;

package/dist/src/storage-setup.js

@@ -0,0 +1,222 @@
+import { fail } from "./errors.js";
+const clean = (value) => value.replace(/^\/+|\/+$/g, "");
+function requireValue(value, flag, why) {
+    if (!value?.trim())
+        fail("invalid_argument", `${flag} is required for this provider — ${why}`);
+    return value.trim();
+}
+/** Write, read, and finish multipart uploads inside one prefix. Nothing else. */
+function s3Policy(bucket, prefix) {
+    return JSON.stringify({
+        Version: "2012-10-17",
+        Statement: [
+            {
+                Sid: "SealkeepWriteAndReadOwnPrefix",
+                Effect: "Allow",
+                Action: ["s3:PutObject", "s3:GetObject", "s3:AbortMultipartUpload", "s3:ListMultipartUploadParts"],
+                Resource: `arn:aws:s3:::${bucket}/${prefix}/*`
+            },
+            {
+                Sid: "SealkeepListOwnPrefixOnly",
+                Effect: "Allow",
+                Action: ["s3:ListBucket", "s3:ListBucketMultipartUploads"],
+                Resource: `arn:aws:s3:::${bucket}`,
+                Condition: { StringLike: { "s3:prefix": [`${prefix}/*`] } }
+            }
+        ]
+    }, null, 2);
+}
+function s3Plan(input) {
+    const bucket = input.bucket;
+    const prefix = clean(input.prefix);
+    const region = input.region ?? "us-east-1";
+    const policyName = "SealkeepArchiveWriter";
+    return {
+        provider: "s3", bucket, prefix,
+        steps: [
+            {
+                title: "Create the bucket",
+                why: "Sealkeep only ever writes inside one prefix, but it needs a bucket to write into.",
+                link: `https://s3.console.aws.amazon.com/s3/bucket/create?region=${region}`,
+                commands: [
+                    `aws s3api create-bucket --bucket ${bucket} --region ${region}` + (region === "us-east-1" ? "" : ` \\\n  --create-bucket-configuration LocationConstraint=${region}`),
+                    `aws s3api put-public-access-block --bucket ${bucket} \\\n  --public-access-block-configuration BlockPublicAcls=true,IgnorePublicAcls=true,BlockPublicPolicy=true,RestrictPublicBuckets=true`
+                ]
+            },
+            {
+                title: "Create a least-privilege policy",
+                why: `This grants write and read under ${prefix}/ and nothing else — not the rest of the bucket, not other buckets.`,
+                link: "https://console.aws.amazon.com/iam/home#/policies$new?step=edit",
+                document: { name: "vaultline-policy.json", body: s3Policy(bucket, prefix) },
+                commands: [`aws iam create-policy --policy-name ${policyName} \\\n  --policy-document file://vaultline-policy.json`]
+            },
+            {
+                title: "Create a user and an access key",
+                why: "Sealkeep signs its own requests, so it needs a key rather than a role it cannot assume.",
+                link: "https://console.aws.amazon.com/iam/home#/users/create",
+                commands: [
+                    `aws iam create-user --user-name vaultline`,
+                    `aws iam attach-user-policy --user-name vaultline \\\n  --policy-arn arn:aws:iam::$(aws sts get-caller-identity --query Account --output text):policy/${policyName}`,
+                    `aws iam create-access-key --user-name vaultline`
+                ]
+            }
+        ],
+        finish: [
+            `sealkeep storage configure --provider s3 --bucket ${bucket} --prefix ${prefix} --region ${region}`,
+            `echo '{"accessKeyId":"AKIA…","secretAccessKey":"…"}' | sealkeep storage credentials set`,
+            `VAULTLINE_ENABLE_SIGNER=1 sealkeep upload --all`
+        ],
+        notes: [
+            "Enable versioning on the bucket if you want protection against an accidental overwrite.",
+            "The access key is stored in your OS keychain, never in a Sealkeep config file."
+        ]
+    };
+}
+function r2Plan(input) {
+    const bucket = input.bucket;
+    const prefix = clean(input.prefix);
+    const accountId = requireValue(input.accountId, "--account-id", "R2 endpoints are per account");
+    return {
+        provider: "r2", bucket, prefix,
+        steps: [
+            {
+                title: "Create the bucket",
+                why: "R2 has no egress fees, which suits archives you rarely read back.",
+                link: "https://dash.cloudflare.com/?to=/:account/r2/new",
+                commands: [`npx wrangler r2 bucket create ${bucket}`]
+            },
+            {
+                title: "Create an R2 API token",
+                why: "Choose Object Read & Write, and scope it to this one bucket.",
+                link: `https://dash.cloudflare.com/${accountId}/r2/api-tokens`,
+                commands: []
+            },
+            {
+                title: "Note the S3-compatible endpoint",
+                why: "R2 speaks the S3 protocol, so Sealkeep signs for it the same way.",
+                commands: [`# endpoint: https://${accountId}.r2.cloudflarestorage.com`]
+            }
+        ],
+        finish: [
+            `sealkeep storage configure --provider r2 --bucket ${bucket} --prefix ${prefix} --region auto`,
+            `echo '{"accessKeyId":"<R2 access key id>","secretAccessKey":"<R2 secret>"}' | sealkeep storage credentials set`,
+            `VAULTLINE_ENABLE_SIGNER=1 sealkeep upload --all --endpoint https://${accountId}.r2.cloudflarestorage.com`
+        ],
+        notes: [
+            "R2 tokens are scoped per bucket in the dashboard, so the prefix restriction is Sealkeep's own object-key discipline rather than an IAM condition.",
+            "Keep the token as Object Read & Write. Admin tokens are never needed."
+        ]
+    };
+}
+function gcsPlan(input) {
+    const bucket = input.bucket;
+    const prefix = clean(input.prefix);
+    const project = requireValue(input.project, "--project", "every Google Cloud resource belongs to a project");
+    const location = input.region ?? "US";
+    const account = `vaultline@${project}.iam.gserviceaccount.com`;
+    return {
+        provider: "gcs", bucket, prefix,
+        steps: [
+            {
+                title: "Create the bucket",
+                why: "Uniform bucket-level access keeps permissions in IAM rather than per-object ACLs.",
+                link: `https://console.cloud.google.com/storage/create-bucket?project=${project}`,
+                commands: [`gcloud storage buckets create gs://${bucket} --project=${project} --location=${location} --uniform-bucket-level-access`]
+            },
+            {
+                title: "Create a service account",
+                why: "Sealkeep signs upload URLs with this account's key; it never uses your own credentials.",
+                link: `https://console.cloud.google.com/iam-admin/serviceaccounts/create?project=${project}`,
+                commands: [`gcloud iam service-accounts create sealkeep --project=${project} \\\n  --display-name="Sealkeep archive writer"`]
+            },
+            {
+                title: "Grant access to the prefix only",
+                why: `The IAM condition limits this account to objects under ${prefix}/, so it cannot read the rest of the bucket.`,
+                document: {
+                    name: "vaultline-binding.txt",
+                    body: `role: roles/storage.objectAdmin\nmember: serviceAccount:${account}\ncondition:\n  title: vaultline-prefix-only\n  expression: |\n    resource.name.startsWith("projects/_/buckets/${bucket}/objects/${prefix}/")`
+                },
+                commands: [
+                    `gcloud storage buckets add-iam-policy-binding gs://${bucket} \\\n  --member="serviceAccount:${account}" \\\n  --role="roles/storage.objectAdmin" \\\n  --condition='expression=resource.name.startsWith("projects/_/buckets/${bucket}/objects/${prefix}/"),title=vaultline-prefix-only'`
+                ]
+            },
+            {
+                title: "Create a key for the service account",
+                why: "Sealkeep needs the private key to sign upload URLs. It is stored in your OS keychain.",
+                link: `https://console.cloud.google.com/iam-admin/serviceaccounts?project=${project}`,
+                commands: [`gcloud iam service-accounts keys create vaultline-key.json \\\n  --iam-account=${account} --project=${project}`]
+            }
+        ],
+        finish: [
+            `sealkeep storage configure --provider gcs --bucket ${bucket} --prefix ${prefix}`,
+            `node -e 'const k=require("./vaultline-key.json");process.stdout.write(JSON.stringify({clientEmail:k.client_email,privateKey:k.private_key}))' \\\n  | sealkeep storage credentials set`,
+            `rm vaultline-key.json   # the key now lives in your keychain`,
+            `VAULTLINE_ENABLE_SIGNER=1 sealkeep upload --all`
+        ],
+        notes: [
+            "Delete the downloaded key file once it is in your keychain. A key on disk is the usual way these leak.",
+            "IAM conditions need uniform bucket-level access, which the create command above sets."
+        ]
+    };
+}
+/**
+ * Google Drive is the no-bucket path: no console policies, no keys to paste.
+ * The whole grant is one OAuth consent for `drive.file`, which in Google's
+ * permission model shows Sealkeep only the files Sealkeep itself created.
+ * The tedious part a person still has to do — until a first-party OAuth
+ * client id ships — is minting a Desktop-app client id of their own.
+ */
+function gdrivePlan(input) {
+    const folder = input.bucket;
+    const prefix = clean(input.prefix);
+    return {
+        provider: "gdrive", bucket: folder, prefix,
+        steps: [
+            {
+                title: "Create a Desktop-app OAuth client",
+                why: "Sealkeep signs in as an app you control. A Desktop client has no secret to leak — the PKCE exchange proves each connection instead.",
+                link: "https://console.cloud.google.com/apis/credentials/oauthclient",
+                commands: ["# Application type: Desktop app. Copy the client id; there is no secret to copy."]
+            },
+            {
+                title: "Enable the Drive API on that project",
+                why: "The consent screen belongs to your project, and Google refuses tokens for an API the project has not enabled.",
+                link: "https://console.cloud.google.com/apis/library/drive.googleapis.com",
+                commands: [`gcloud services enable drive.googleapis.com`]
+            },
+            {
+                title: "Connect your Google account",
+                why: `Sealkeep asks for drive.file only: it can see files it created — a "${folder}" folder of ciphertext — and nothing else in the Drive.`,
+                commands: [
+                    `export VAULTLINE_GDRIVE_CLIENT_ID="<your-client-id>.apps.googleusercontent.com"`,
+                    `sealkeep storage connect gdrive`
+                ]
+            }
+        ],
+        finish: [
+            `# once the provider registry accepts gdrive targets:`,
+            `sealkeep storage configure --provider gdrive --bucket ${folder} --prefix ${prefix}`,
+            `VAULTLINE_ENABLE_SIGNER=1 sealkeep upload --all`
+        ],
+        notes: [
+            `Archives land in a "${folder}" folder as sealed ciphertext; a prefix of "appdata" uses Drive's hidden per-app area instead.`,
+            "The refresh token is stored in your OS keychain, never in a Sealkeep config file.",
+            "Selecting gdrive as the upload target (`storage configure`, and the panel) lands with the provider-registry update; the connection above is stored now and reused then."
+        ]
+    };
+}
+export function setupPlan(input) {
+    if (!input.bucket?.trim())
+        fail("invalid_argument", "--bucket is required");
+    if (!clean(input.prefix ?? ""))
+        fail("invalid_argument", "--prefix is required, so your objects stay in their own namespace");
+    if (input.provider === "s3")
+        return s3Plan(input);
+    if (input.provider === "r2")
+        return r2Plan(input);
+    if (input.provider === "gcs")
+        return gcsPlan(input);
+    if (input.provider === "gdrive")
+        return gdrivePlan(input);
+    return fail("provider_unsupported", `No guided setup for ${input.provider}. Use --provider s3, r2, gcs, or gdrive.`);
+}

package/dist/src/storage-targets.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Multiple storage targets, one vault. Paul's shape: a pro account keeps the
+ * managed cloud AND a personal Drive (or a bucket) connected at once, with
+ * rules deciding where a session lands — a byte limit per target ("Drive
+ * holds at most 50 GB"), project pinning ("this project archives to Drive"),
+ * and an order of preference in which the managed cloud wins by default.
+ *
+ * Reads never consult this router: every record names its own provider and
+ * bucket, so restore, search, and delete follow the record wherever it went.
+ * Routing decides only where NEW seals go.
+ */
+import type { StorageTargetConfig } from "./types.js";
+export type StorageTarget = StorageTargetConfig;
+/**
+ * The effective target list. Explicit `storageTargets` in config wins;
+ * otherwise the single `remoteStorage` entry is the one target; otherwise a
+ * vault signed into the cloud account is managed-only — the same ladder the
+ * rest of the product climbs.
+ */
+export declare function resolveTargets(dataDir: string): Promise<StorageTarget[]>;
+/** Pushes the rules to the account so every other machine syncs them. Advisory: offline edits still apply locally. */
+export declare function pushTargetsToCloud(dataDir: string, targets: StorageTarget[]): Promise<boolean>;
+/** Bytes each target currently holds, from the records: targetId when stamped, provider+bucket for older records. */
+export declare function targetUsage(dataDir: string, targets: StorageTarget[]): Promise<Map<string, number>>;
+/**
+ * Where a new seal goes. Eligibility first (limit not blown, chunk-capable
+ * when the seal streams — Drive stores single objects), then order: targets
+ * pinning this session's project come first, then priority, managed ahead by
+ * default. Deterministic and explainable; no silent multi-target retries.
+ */
+export declare function chooseTarget(dataDir: string, input: {
+    project?: string | null;
+    bytes: number;
+    requireChunkCapable?: boolean;
+    targetId?: string;
+}): Promise<StorageTarget>;
+/** Persist an explicit target list. Empty array removes the setting (back to single remoteStorage / managed). */
+export declare function setStorageTargets(dataDir: string, targets: StorageTarget[], options?: {
+    push?: boolean;
+}): Promise<void>;

package/dist/src/storage-targets.js

@@ -0,0 +1,147 @@
+import { fail } from "./errors.js";
+import { readConfig, listArchives } from "./vault.js";
+import { isV2 } from "./types.js";
+const defaultPriority = (target) => target.priority ?? (target.provider === "vaultline" ? 0 : 10);
+/**
+ * The effective target list. Explicit `storageTargets` in config wins;
+ * otherwise the single `remoteStorage` entry is the one target; otherwise a
+ * vault signed into the cloud account is managed-only — the same ladder the
+ * rest of the product climbs.
+ */
+export async function resolveTargets(dataDir) {
+    const config = await readConfig(dataDir);
+    // The account is the source of truth: every machine of the vault syncs the
+    // SAME rules down, so a cap set on the laptop holds on the desktop too.
+    // The local config is the offline cache; an explicit local list still wins
+    // when the account cannot be reached.
+    const fromCloud = await pullTargetsFromCloud(dataDir).catch(() => null);
+    if (fromCloud && fromCloud.length > 0) {
+        if (JSON.stringify(fromCloud) !== JSON.stringify(config.storageTargets ?? null)) {
+            await setStorageTargets(dataDir, fromCloud, { push: false }).catch(() => undefined);
+        }
+        return fromCloud;
+    }
+    const declared = config.storageTargets;
+    if (declared && declared.length > 0)
+        return declared;
+    if (config.remoteStorage) {
+        return [{ id: "primary", provider: config.remoteStorage.provider, bucket: config.remoteStorage.bucket, prefix: config.remoteStorage.prefix, region: config.remoteStorage.region }];
+    }
+    try {
+        const { cloudToken } = await import("./cloud.js");
+        await cloudToken(dataDir);
+        return [{ id: "managed", provider: "vaultline" }];
+    }
+    catch {
+        return [];
+    }
+}
+/** The account's rules, or null when not signed in / none saved. */
+async function pullTargetsFromCloud(dataDir) {
+    const { cloudToken } = await import("./cloud.js");
+    const token = await cloudToken(dataDir).catch(() => null);
+    if (!token)
+        return null;
+    const { DEFAULT_CLOUD_URL } = await import("./cloud.js");
+    const base = (process.env.VAULTLINE_CLOUD_URL ?? DEFAULT_CLOUD_URL).replace(/\/+$/, "");
+    const response = await fetch(`${base}/v1/cloud/storage-targets`, { headers: { authorization: `Bearer ${token}` } });
+    if (!response.ok)
+        return null;
+    const body = await response.json();
+    if (!body.targets_json)
+        return null;
+    try {
+        const parsed = JSON.parse(body.targets_json);
+        return Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Pushes the rules to the account so every other machine syncs them. Advisory: offline edits still apply locally. */
+export async function pushTargetsToCloud(dataDir, targets) {
+    try {
+        const { cloudToken, DEFAULT_CLOUD_URL } = await import("./cloud.js");
+        const token = await cloudToken(dataDir);
+        const base = (process.env.VAULTLINE_CLOUD_URL ?? DEFAULT_CLOUD_URL).replace(/\/+$/, "");
+        const response = await fetch(`${base}/v1/cloud/storage-targets`, {
+            method: "PUT",
+            headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+            body: JSON.stringify({ targets_json: JSON.stringify(targets) })
+        });
+        return response.ok;
+    }
+    catch {
+        return false;
+    }
+}
+/** Bytes each target currently holds, from the records: targetId when stamped, provider+bucket for older records. */
+export async function targetUsage(dataDir, targets) {
+    const usage = new Map(targets.map((target) => [target.id, 0]));
+    const records = await listArchives(dataDir).catch(() => []);
+    for (const record of records) {
+        if (!isV2(record) || !record.remote)
+            continue;
+        const stamped = record.remote.targetId;
+        const match = (stamped && targets.find((target) => target.id === stamped))
+            ?? targets.find((target) => target.provider === record.remote.provider && (target.provider === "vaultline" || target.bucket === record.remote.bucket));
+        if (match)
+            usage.set(match.id, (usage.get(match.id) ?? 0) + (record.remote.bytes ?? 0));
+    }
+    return usage;
+}
+/**
+ * Where a new seal goes. Eligibility first (limit not blown, chunk-capable
+ * when the seal streams — Drive stores single objects), then order: targets
+ * pinning this session's project come first, then priority, managed ahead by
+ * default. Deterministic and explainable; no silent multi-target retries.
+ */
+export async function chooseTarget(dataDir, input) {
+    const targets = await resolveTargets(dataDir);
+    if (targets.length === 0)
+        fail("storage_not_configured", "No storage target configured. Run: sealkeep storage configure ... (or sign in to Sealkeep Cloud)");
+    if (input.targetId) {
+        const named = targets.find((target) => target.id === input.targetId);
+        if (!named)
+            fail("invalid_argument", `No storage target named "${input.targetId}". Targets: ${targets.map((target) => target.id).join(", ")}`);
+        return named;
+    }
+    const usage = await targetUsage(dataDir, targets);
+    const eligible = targets.filter((target) => {
+        if (input.requireChunkCapable && target.provider === "gdrive")
+            return false;
+        if (target.maxGb !== undefined && (usage.get(target.id) ?? 0) + input.bytes > target.maxGb * 1024 ** 3)
+            return false;
+        return true;
+    });
+    if (eligible.length === 0) {
+        fail("storage_not_configured", "Every storage target is either full (maxGb reached) or unable to take this seal. Raise a limit or add a target.");
+    }
+    const pinScore = (target) => (input.project && target.projects?.includes(input.project) ? 0 : 1);
+    eligible.sort((a, b) => pinScore(a) - pinScore(b) || defaultPriority(a) - defaultPriority(b));
+    return eligible[0];
+}
+/** Persist an explicit target list. Empty array removes the setting (back to single remoteStorage / managed). */
+export async function setStorageTargets(dataDir, targets, options = {}) {
+    const { readFile, writeFile } = await import("node:fs/promises");
+    const { join } = await import("node:path");
+    const path = join(dataDir, "config.json");
+    const config = JSON.parse(await readFile(path, "utf8"));
+    if (targets.length === 0)
+        delete config.storageTargets;
+    else {
+        const ids = new Set();
+        for (const target of targets) {
+            if (!target.id || ids.has(target.id))
+                fail("invalid_argument", "Every storage target needs a unique id");
+            ids.add(target.id);
+            if (target.provider !== "vaultline" && target.provider !== "gdrive" && !target.bucket) {
+                fail("invalid_argument", `Target "${target.id}" (${target.provider}) needs a bucket`);
+            }
+        }
+        config.storageTargets = targets;
+    }
+    await writeFile(path, JSON.stringify(config, null, 2) + "\n", { mode: 0o600 });
+    if (options.push !== false)
+        await pushTargetsToCloud(dataDir, targets);
+}

package/dist/src/stream-to-cloud.d.ts

@@ -0,0 +1,76 @@
+import type { ArchiveRecordV2 } from "./types.js";
+/**
+ * Seal straight into the bucket: read a slice, compress it, encrypt it, send
+ * it, forget it. The full ciphertext exists nowhere — not on this disk, not in
+ * this process — only in the bucket, chunk by chunk as it was made.
+ *
+ * This is the answer to "how much free space do I need to archive 5 GB":
+ * one chunk of it. The offload model (seal locally, upload, verify, delete)
+ * already keeps the disk clean *eventually*; this path never dirties it. The
+ * record is born offloaded — `objectPath` names a file that never existed —
+ * and every reader treats it exactly like an archive whose blob was offloaded
+ * after the fact: restore and search fetch from the bucket, ranged where the
+ * chunks allow it.
+ *
+ * Interruption is survivable. A spool journal (src/spool.ts) is written before
+ * the first byte leaves and updated at every provider durability point, so a
+ * crashed upload resumes from the last confirmed chunk instead of starting
+ * over — see `resumeSeal` for the safety argument.
+ *
+ * Own-bucket only, deliberately. A BYO provider takes our resumable/multipart
+ * streams with the machine's own credential. The managed tier's control plane
+ * vends one signed PUT for a known length — streaming there needs the signer
+ * to vend a resumable session or a scoped credential, which is control-plane
+ * work, not client work (docs/managed-streaming-contract.md); until then this
+ * refuses with the reason rather than pretending.
+ */
+export type StreamSealOutcome = {
+    record: ArchiveRecordV2;
+    objectKey: string;
+    storedBytes: number;
+    /** Peak bytes this machine ever held for the ciphertext: one part buffer. */
+    heldAtMostBytes: number;
+};
+/**
+ * What this module needs a provider client to be. The third `uploadStream`
+ * argument and `abortMultipart` are optional so the pre-resume clients (and
+ * tests built against them) keep compiling; a client that ignores them simply
+ * never journals provider state, and its uploads restart from zero on a crash
+ * — the pre-resume behavior, not a new failure mode.
+ */
+type StreamUploadOptions = {
+    resume?: unknown;
+    onState?: (state: unknown) => void | Promise<void>;
+};
+type StreamClient = {
+    uploadStream(objectKey: string, chunks: AsyncIterable<Buffer>, options?: StreamUploadOptions): Promise<{
+        remoteChecksum: string | null;
+        bytes: number;
+    }>;
+    head(lease: {
+        objectKey: string;
+    } & Record<string, unknown>): Promise<{
+        exists: boolean;
+        bytes: number;
+        checksum?: string;
+    }>;
+    abortMultipart?(objectKey: string, uploadId: string): Promise<void>;
+    /** The provider's own account of an in-flight multipart — resume's source of truth. */
+    listParts?(objectKey: string, uploadId: string): Promise<{
+        partNumber: number;
+        etag: string;
+        bytes: number;
+    }[]>;
+    /** The provider's own confirmed-byte count for a resumable session. */
+    resumableStatus?(session: string): Promise<{
+        confirmedBytes: number;
+    }>;
+};
+export declare function sealArchiveToCloud(dataDir: string, sourcePath: string, rawPhrase: string, agent: string, options?: {
+    /** Injected provider client, for tests against emulators. */
+    client?: StreamClient;
+    /** Resume an interrupted upload of this source when a journal for it exists. Defaults on; `--fresh` turns it off. */
+    resume?: boolean;
+    now?: number;
+}): Promise<StreamSealOutcome>;
+export {};