sealkeep 0.5.0

package/dist/src/update.js

@@ -0,0 +1,56 @@
+import { createHash, createPrivateKey, createPublicKey, sign as edSign, verify as edVerify } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { fail } from "./errors.js";
+/** Deterministic bytes to sign: object keys sorted, no incidental whitespace. */
+export function canonicalize(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value) ?? "null";
+    if (Array.isArray(value))
+        return `[${value.map(canonicalize).join(",")}]`;
+    const entries = Object.entries(value).filter(([, item]) => item !== undefined).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${canonicalize(item)}`).join(",")}}`;
+}
+export function signManifest(manifest, privateKeyPem, keyId) {
+    const key = createPrivateKey(privateKeyPem);
+    if (key.asymmetricKeyType !== "ed25519")
+        fail("invalid_argument", "Release manifests must be signed with an ed25519 key");
+    return { manifest, keyId, algorithm: "ed25519", signature: edSign(null, Buffer.from(canonicalize(manifest)), key).toString("base64") };
+}
+/**
+ * Verifies a release manifest against a pinned key set. An unknown key id fails
+ * closed: a signature is only meaningful against a key the client already trusts.
+ */
+export function verifyManifest(signed, trustedKeys) {
+    if (signed.algorithm !== "ed25519")
+        fail("invalid_argument", `Unsupported signature algorithm: ${String(signed.algorithm)}`);
+    const publicKeyPem = trustedKeys[signed.keyId];
+    if (!publicKeyPem)
+        fail("forbidden", `Release signed by untrusted key id ${signed.keyId}`, { keyId: signed.keyId });
+    const valid = edVerify(null, Buffer.from(canonicalize(signed.manifest)), createPublicKey(publicKeyPem), Buffer.from(signed.signature, "base64"));
+    if (!valid)
+        fail("forbidden", "Release manifest signature does not verify", { keyId: signed.keyId });
+    return signed.manifest;
+}
+function parseRelease(release) {
+    const parts = release.replace(/^v/, "").split(/[.-]/).slice(0, 3).map((part) => Number.parseInt(part, 10));
+    if (parts.length !== 3 || parts.some((part) => !Number.isInteger(part)))
+        fail("invalid_argument", `Unreadable release version: ${release}`);
+    return parts;
+}
+/** Blocks rollback: a signed but older manifest must never be applied automatically. */
+export function assertNotDowngrade(candidate, current) {
+    const [a, b, c] = parseRelease(candidate);
+    const [x, y, z] = parseRelease(current);
+    const newer = a > x || (a === x && (b > y || (b === y && c > z)));
+    if (!newer)
+        fail("forbidden", `Refusing to apply release ${candidate} over installed ${current}`, { candidate, current });
+}
+/** Confirms a downloaded artifact matches the signed manifest entry byte for byte. */
+export async function verifyArtifact(path, entry) {
+    const bytes = await readFile(path).catch(() => fail("source_unreadable", `Release artifact is not readable: ${path}`, { path }));
+    if (bytes.length !== entry.bytes)
+        fail("ciphertext_integrity_failed", `Artifact ${entry.name} is ${bytes.length} bytes; the manifest says ${entry.bytes}`, { artifact: entry.name });
+    const digest = createHash("sha256").update(bytes).digest("hex");
+    if (digest !== entry.sha256)
+        fail("ciphertext_integrity_failed", `Artifact ${entry.name} failed its checksum`, { artifact: entry.name });
+}

package/dist/src/upload.d.ts

@@ -0,0 +1,46 @@
+import { type ProviderUploadClient, type UploadLease } from "./control-plane.js";
+import { type EndpointOverrides } from "./providers/index.js";
+export type UploadOptions = {
+    /** Routed multi-target override: upload to THIS storage instead of config.remoteStorage. */
+    remoteStorage?: {
+        provider: "s3" | "r2" | "b2" | "gcs" | "gdrive";
+        bucket: string;
+        prefix: string;
+        region?: string;
+    };
+    /** Stamped into the record's remote for per-target usage accounting. */
+    targetId?: string;
+    /** Supply a client directly (tests, or an already-authenticated session). */
+    client?: ProviderUploadClient;
+    storageConfigId?: string;
+    overrides?: EndpointOverrides;
+    now?: number;
+    ttlMs?: number;
+};
+export type UploadOutcome = {
+    archiveId: string;
+    objectKey: string;
+    bytes: number;
+    checksum: string;
+    verified: boolean;
+    provider: string;
+};
+/**
+ * Uploads one archive's ciphertext and verifies it landed intact.
+ *
+ * The archive is only marked durable after the provider reports back the same byte
+ * count and the same SHA-256 the client computed locally. Anything else quarantines
+ * the attempt and leaves the source untouched: retention reads `remote.verifiedAt`,
+ * so an unverified upload can never make a local file reclaimable.
+ */
+export declare function uploadArchive(dataDir: string, archiveId: string, options?: UploadOptions): Promise<UploadOutcome>;
+/** Uploads every archive that has no verified remote object yet. */
+export declare function uploadPending(dataDir: string, options?: UploadOptions): Promise<{
+    uploaded: UploadOutcome[];
+    failed: {
+        archiveId: string;
+        error: string;
+    }[];
+    skipped: number;
+}>;
+export type { UploadLease };

package/dist/src/upload.js

@@ -0,0 +1,80 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { assertLeaseUsable } from "./control-plane.js";
+import { fail } from "./errors.js";
+import { recordAudit } from "./audit.js";
+import { createActiveLease } from "./providers/index.js";
+import { uploadClientFromStore } from "./providers/index.js";
+import { isV2 } from "./types.js";
+import { listArchives, readConfig, writeRecord } from "./vault.js";
+/**
+ * Uploads one archive's ciphertext and verifies it landed intact.
+ *
+ * The archive is only marked durable after the provider reports back the same byte
+ * count and the same SHA-256 the client computed locally. Anything else quarantines
+ * the attempt and leaves the source untouched: retention reads `remote.verifiedAt`,
+ * so an unverified upload can never make a local file reclaimable.
+ */
+export async function uploadArchive(dataDir, archiveId, options = {}) {
+    const config = await readConfig(dataDir);
+    const remoteStorage = options.remoteStorage ?? config.remoteStorage ?? fail("storage_not_configured", "No remote target configured. Run: sealkeep storage configure ...");
+    const record = (await listArchives(dataDir)).find((item) => item.id === archiveId);
+    if (!record)
+        fail("archive_not_found", `Archive not found: ${archiveId}`, { archiveId });
+    if (!isV2(record))
+        fail("invalid_argument", `Archive ${archiveId} uses format v1. Run: sealkeep migrate`, { archiveId });
+    const ciphertext = await readFile(record.objectPath);
+    const localChecksum = createHash("sha256").update(ciphertext).digest("base64");
+    const providerConfig = remoteStorage;
+    const lease = createActiveLease(providerConfig, { archiveId, ciphertextSha256: record.cipher.ciphertextSha256, bytes: ciphertext.length, now: options.now, ttlMs: options.ttlMs });
+    assertLeaseUsable(lease, options.now);
+    const client = options.client ?? await uploadClientFromStore(dataDir, options.storageConfigId ?? config.vaultId, providerConfig, options.overrides);
+    const uploaded = await client.upload(lease, ciphertext);
+    const head = await client.head(lease);
+    // What the provider should be holding. For a single-part object that is the
+    // whole-object SHA-256; for a multipart one it is S3's composite of the part
+    // digests, which `upload` returns. Comparing the stored checksum against
+    // `localChecksum` unconditionally would fail every multipart archive.
+    const expected = uploaded.remoteChecksum;
+    const problems = [];
+    if (!head.exists)
+        problems.push("the provider does not report the object as present");
+    if (head.bytes !== ciphertext.length)
+        problems.push(`the provider stored ${head.bytes} bytes; ${ciphertext.length} were sent`);
+    if (head.checksum === undefined) {
+        // Previously this case silently skipped the comparison, which left byte
+        // count as the only real check — an endpoint returning the right length of
+        // wrong bytes verified clean. Reclaim depends on this verdict, so an
+        // unprovable upload is a failed upload.
+        problems.push("the provider did not report a stored checksum, so the bytes it holds cannot be proven");
+    }
+    else if (head.checksum !== expected) {
+        problems.push(`the provider's stored checksum ${head.checksum} does not match the ${expected} we uploaded`);
+    }
+    if (problems.length > 0) {
+        await recordAudit(dataDir, "upload.verify", "denied", { archiveId, objectKey: lease.objectKey, problems: problems.length });
+        fail("ciphertext_integrity_failed", `Refusing to mark ${archiveId} durable: ${problems.join("; ")}`, { archiveId, objectKey: lease.objectKey });
+    }
+    const remote = { provider: lease.provider, bucket: remoteStorage.bucket, objectKey: lease.objectKey, bytes: ciphertext.length, checksum: localChecksum, verifiedAt: new Date(options.now ?? Date.now()).toISOString(), ...(options.targetId ? { targetId: options.targetId } : {}) };
+    const next = { ...record, remote };
+    await writeRecord(config.storage.root, next);
+    await recordAudit(dataDir, "upload.verify", "allowed", { archiveId, objectKey: lease.objectKey, bytes: ciphertext.length, provider: lease.provider });
+    return { archiveId, objectKey: lease.objectKey, bytes: ciphertext.length, checksum: localChecksum, verified: true, provider: lease.provider };
+}
+/** Uploads every archive that has no verified remote object yet. */
+export async function uploadPending(dataDir, options = {}) {
+    const records = await listArchives(dataDir);
+    const uploaded = [];
+    const failed = [];
+    for (const record of records) {
+        if (isV2(record) && record.remote?.verifiedAt)
+            continue;
+        try {
+            uploaded.push(await uploadArchive(dataDir, record.id, options));
+        }
+        catch (error) {
+            failed.push({ archiveId: record.id, error: error instanceof Error ? error.message : "upload failed" });
+        }
+    }
+    return { uploaded, failed, skipped: records.length - uploaded.length - failed.length };
+}

package/dist/src/vault.d.ts

@@ -0,0 +1,208 @@
+import { type Recipient } from "../packages/vaultline-crypto/src/index.js";
+import { type ArchiveRecord, type ArchiveRecordV2, type VaultConfig } from "./types.js";
+import type { ProviderConfig } from "./control-plane.js";
+/** Bumped when the adapter's preservation behaviour changes, recorded in every envelope. */
+/**
+ * Writes one archive record atomically.
+ *
+ * Written to a temporary file beside the target and renamed into place, so a
+ * crash never leaves a half-written record that would strand an archive. This
+ * lived as three byte-identical private copies in upload, migrate and
+ * retention; a fourth was about to be added for the managed push path.
+ */
+export declare function writeRecord(root: string, record: ArchiveRecord): Promise<void>;
+export declare const ADAPTER_VERSION = "1";
+export declare const CONFIG_VERSION = 1;
+/**
+ * ~/.sealkeep for new vaults; an existing ~/.Sealkeep keeps working forever —
+ * the rebrand must never strand a vault that predates it.
+ */
+export declare const defaultDataDir: () => string;
+/**
+ * Reads and version-gates the vault config. A config written by a newer build is
+ * refused rather than silently reinterpreted; migrations attach here when v2 lands.
+ */
+export declare function readConfig(dataDir: string): Promise<VaultConfig>;
+export declare function vaultStatus(dataDir: string): Promise<{
+    vaultId: string;
+    provider: "local";
+    storageMode: "sealed" | "plain";
+    remoteStorage: {
+        provider: "vaultline" | "s3" | "r2" | "b2" | "gcs" | "gdrive";
+        bucket: string;
+        prefix: string;
+        region?: string;
+    } | undefined;
+    archiveCount: number;
+    archivedBytes: number;
+}>;
+export declare function configureRemoteStorage(dataDir: string, remoteStorage: ProviderConfig): Promise<VaultConfig>;
+export declare function initialize(dataDir: string, providedPhrase?: string, opts?: {
+    storageMode?: "sealed" | "plain";
+}): Promise<{
+    config: VaultConfig;
+    phrase: string;
+}>;
+/**
+ * The archive whose bytes are still a prefix of this source, and how many.
+ *
+ * Agent transcripts are append-only JSONL, which is the property that makes
+ * incremental archiving possible at all: if the first N bytes have not changed,
+ * everything before N is already sealed and only the tail is new. "Have not
+ * changed" is *proved* here, not assumed — the prefix is re-read and hashed
+ * against what the archive recorded, in constant memory — because a wrong
+ * answer would produce an archive that cannot reconstruct the file.
+ *
+ * The longest proven prefix wins, so a transcript archived at 1 MB and again at
+ * 3 MB reports the 3 MB archive. Nothing is returned when the file was
+ * rewritten, truncated, or has never been archived.
+ */
+export declare function provenAppendOffset(archives: readonly ArchiveRecord[], sourcePath: string, currentBytes: number): Promise<{
+    archiveId: string;
+    bytes: number;
+} | null>;
+/**
+ * The pointer a delta archive seals from: which archive already covers the
+ * transcript's first `baseBytes` bytes.
+ *
+ * Stored on the record as `delta`. Records are plain JSON, so readers that do
+ * not know the field carry it through unchanged; `deltaOf` is how it is read.
+ */
+export type ArchiveDelta = {
+    baseArchiveId: string;
+    baseBytes: number;
+};
+export type DeltaArchiveRecord = ArchiveRecordV2 & {
+    delta: ArchiveDelta;
+};
+/**
+ * The delta pointer on a record, when the record is a delta archive.
+ *
+ * Defensive on purpose: the field is not in the typed record (types.ts is the
+ * wire contract and moves separately), so this is the one place its shape is
+ * checked before anything trusts it.
+ */
+export declare function deltaOf(record: ArchiveRecord): ArchiveDelta | null;
+export type ArchiveResult = ArchiveRecord & {
+    deduplicated: boolean;
+};
+/**
+ * Seals one transcript, reading and writing a chunk at a time.
+ *
+ * An existing archive is returned unchanged when the same source bytes are
+ * archived again, so a duplicate lifecycle event costs a hash rather than an
+ * archive.
+ *
+ * `hooks.delta` opts in to incremental sealing: when the newest archive of
+ * this path is a *proven* prefix of the live file, only the appended range is
+ * sealed and the record carries a `delta` pointer to its base. Off by default
+ * so every existing caller keeps writing complete, standalone archives; the
+ * queue worker turns it on, because re-sealing a growing session whole on
+ * every snapshot is exactly how 4 GB of transcript became 40 GB of storage.
+ */
+export declare function archiveFile(dataDir: string, sourcePath: string, rawPhrase: string, agent?: string, hooks?: {
+    onProgress?: (bytesRead: number) => void;
+    delta?: boolean;
+}): Promise<ArchiveResult>;
+/**
+ * The recovery phrase always gets a recipient, so a recovery kit alone can restore.
+ * Registered device and backup keys are added alongside it.
+ */
+export declare function configuredRecipients(config: VaultConfig, rawPhrase: string, group?: string): Recipient[];
+export declare function listArchives(dataDir: string): Promise<ArchiveRecord[]>;
+/**
+ * Registers an X25519 public key that may open future archives. Only the public
+ * key is stored; the matching private key stays on its own device.
+ */
+export declare function addRecipient(dataDir: string, label: string, publicKeyBase64: string, group?: string): Promise<VaultConfig>;
+/** Removes a recipient from future archives. Run `sealkeep rewrap` to revoke it on existing ones. */
+export declare function removeRecipient(dataDir: string, id: string): Promise<VaultConfig>;
+/** Persists a full config document after validation by the caller. */
+export declare function writeConfig(dataDir: string, config: VaultConfig): Promise<void>;
+export type RetentionCandidate = {
+    id: string;
+    agent: string;
+    path: string;
+    bytes: number;
+    createdAt: string;
+    eligible: false;
+    reason: string;
+};
+/** A non-mutating preview. Policy evaluation lives in `src/retention.ts`. */
+export declare function previewRetention(dataDir: string, olderThanDays?: number): Promise<{
+    mode: "preview";
+    policy: import("./retention.js").RetentionPolicy;
+    olderThanDays: number;
+    graceDays: number;
+    sourceIdleDays: number | null;
+    minSourceBytes: number | null;
+    deleteAfterDays: number | null;
+    reclaimableBytes: number;
+    candidates: import("./retention.js").Candidate[];
+}>;
+/** One archive by id, or a named failure. Callers that need the record before the bytes start here. */
+export declare function findArchive(dataDir: string, id: string): Promise<ArchiveRecord>;
+/**
+ * Proves the phrase opens this archive, before the caller creates anything for it.
+ *
+ * Restoring streams straight to disk, so by the time a chunk fails there is
+ * already a partial file — and a partial file in a directory that had to be
+ * created is worse than no restore at all. Unwrapping the archive key needs
+ * only the envelope, costs one scrypt, and catches the failure people actually
+ * hit, so `restoreArchive` does it before it touches the filesystem.
+ */
+export declare function assertPhraseOpens(config: VaultConfig, record: ArchiveRecord, rawPhrase: string): void;
+/**
+ * Restores one archive straight to a path, holding one chunk at a time.
+ *
+ * `destination` must be a path the caller is willing to see half-written: the
+ * whole-archive hashes are only proved once the last chunk has gone past, so a
+ * rejection can leave bytes behind. `restoreArchive` renames a temporary into
+ * place for exactly this reason.
+ */
+export declare function restoreRecordToFile(dataDir: string, record: ArchiveRecord, rawPhrase: string, destination: string, 
+/** Injectable so the offloaded-archive path can be proved without a bucket. */
+options?: {
+    client?: import("./offload.js").FetchClient;
+}): Promise<{
+    bytes: number;
+}>;
+/**
+ * The records that reproduce a delta archive's transcript, oldest first:
+ * one complete base archive, then every delta in append order, ending with
+ * `target` itself. A record that is not a delta resolves to just itself.
+ *
+ * Pure and synchronous so callers that only want to *show* a chain — a
+ * dashboard, `sealkeep list` — can resolve it without touching ciphertext.
+ * Every link is checked against the next one's claim: a missing base or a
+ * base whose recorded length is not what the delta sealed from is refused
+ * here, before any restore starts writing.
+ */
+export declare function resolveDeltaChain(archives: readonly ArchiveRecord[], target: ArchiveRecord): ArchiveRecord[];
+/**
+ * Restores a delta archive by reassembling its chain: the base archive first,
+ * then each delta's appended range, concatenated in order into `destination`.
+ *
+ * Like `restoreRecordToFile`, the destination is written as the chain streams
+ * past, so callers restore through a temporary path and rename into place.
+ * Each link proves itself before its bytes land — stored-object hash before
+ * decryption, the envelope's own range hash inside `openArchiveToFile` — and
+ * the finished file is then proved *whole* against the newest record's
+ * full-transcript hash. A chain that cannot reproduce the exact bytes it
+ * promised is an error, never a nearly-right transcript.
+ */
+export declare function restoreDeltaChainToFile(dataDir: string, record: ArchiveRecord, rawPhrase: string, destination: string, options?: {
+    client?: import("./offload.js").FetchClient;
+}): Promise<{
+    bytes: number;
+    chain: string[];
+}>;
+export declare function decryptRecord(dataDir: string, id: string, rawPhrase: string): Promise<{
+    record: ArchiveRecord;
+    plaintext: Buffer;
+}>;
+/** Kept for callers that name their own destination. Restore policy lives in `src/restore.ts`. */
+export declare function recoverArchive(dataDir: string, id: string, destination: string, phrase: string): Promise<{
+    record: ArchiveRecord;
+    output: string;
+}>;