sealkeep 0.9.0 → 0.11.0

package/dist/src/offload.d.ts

@@ -1,5 +1,6 @@
-import { type ArchiveRecord } from "./types.js";
-import { createActiveLease } from "./providers/index.js";
+import { type ArchiveRecord, type ArchiveRecordV2, type RemoteObject } from "./types.js";
+import { createActiveLease, type EndpointOverrides } from "./providers/index.js";
+import { type ByteStream } from "./byte-stream.js";
 /**
  * Removing the local copy of an archive that lives in a bucket.
  *
@@ -11,12 +12,15 @@ import { createActiveLease } from "./providers/index.js";
  *
  * Offloading finishes the job: once the bucket has a verified copy, the local
  * one is redundant, and restoring downloads it back. Nothing is lost — but the
- * archive stops being reachable while offline, which is a real trade and the
- * reason this is opt-in and never automatic.
+ * archive stops being reachable while offline, which is a real trade. The
+ * daemon runs it automatically once an upload VERIFIES — freeing the disk is
+ * that loop's whole purpose — so the safety here is the verification gate,
+ * not an opt-in. (This comment used to claim "never automatic" while
+ * heartbeat.ts called it on every successful upload.)
  *
- * The bar for removing a local archive is deliberately higher than for
- * reclaiming a source: a source that was reclaimed can still be recovered from
- * the trash, while an archive removed without a genuine remote copy is gone.
+ * Removing either a local archive or a native source requires a genuine,
+ * verified remote copy. Source reclaim is an explicit/opt-in permanent purge;
+ * the encrypted archive remains the recovery copy after local bytes are freed.
  */
 /**
  * Just enough of a provider client to read an archive back. Injectable for the
@@ -24,7 +28,12 @@ import { createActiveLease } from "./providers/index.js";
  * offloaded archive can be recovered has to be testable without a bucket.
  */
 export type FetchClient = {
-    download?: (lease: ReturnType<typeof createActiveLease>) => Promise<Buffer>;
+    download?: (lease: ReturnType<typeof createActiveLease>, options?: {
+        signal?: AbortSignal;
+    }) => Promise<Buffer>;
+    downloadStream?: (lease: ReturnType<typeof createActiveLease>, options?: {
+        signal?: AbortSignal;
+    }) => Promise<ByteStream>;
 };
 export type OffloadCandidate = {
     id: string;
@@ -32,19 +41,93 @@ export type OffloadCandidate = {
     path: string;
     /** What removing the local copy would give back. */
     localBytes: number;
+    /** Filesystem blocks released when this is the inode's final named link. */
+    allocatedBytes: number;
     provider: string;
     bucket: string;
     objectKey: string;
+    /** Exact verified copy selected as the restore source. */
+    copyId?: string;
 };
 export type OffloadBlocked = {
     id: string;
     reason: string;
 };
-export declare function offloadable(dataDir: string): Promise<{
+export type OffloadOptions = {
+    /** Narrow a sweep to records at least this many days old. */
+    olderThanDays?: number;
+    /** Clock used by the age policy; injectable for deterministic previews/tests. */
+    now?: number;
+    /** Narrow a sweep to these archive ids. */
+    only?: ReadonlySet<string>;
+    /** Lets the daemon stop a long read-back proof without deleting anything. */
+    signal?: AbortSignal;
+    /** Aggregate ceiling used only by automatic/background read-back proofs. */
+    maxBytesPerSecond?: number;
+    /** Deterministic transaction seams; production callers never provide them. */
+    operations?: {
+        afterJournal?: (transaction: OffloadTransaction) => void | Promise<void>;
+        afterLinked?: (transaction: OffloadTransaction) => void | Promise<void>;
+        afterRemoteVerified?: (transaction: OffloadTransaction) => void | Promise<void>;
+        afterMetadata?: (transaction: OffloadTransaction) => void | Promise<void>;
+        afterSourceUnlinked?: (transaction: OffloadTransaction) => void | Promise<void>;
+        afterPurgeAuthorized?: (transaction: OffloadTransaction) => void | Promise<void>;
+        beforeStagingUnlink?: (transaction: OffloadTransaction) => void | Promise<void>;
+        afterStagingPurged?: (transaction: OffloadTransaction) => void | Promise<void>;
+    };
+};
+/**
+ * The local-cache clock starts only after both facts are true: the archive
+ * exists and an off-machine copy has been verified. An old archive uploaded
+ * today therefore receives the same complete cache period as a new one.
+ */
+export declare function archiveCacheReferenceTime(record: ArchiveRecord): number;
+export declare function offloadable(dataDir: string, options?: OffloadOptions): Promise<{
     candidates: OffloadCandidate[];
     blocked: OffloadBlocked[];
     freeableBytes: number;
 }>;
+type OffloadStage = "prepared" | "linked" | "remote-verified" | "metadata-committed" | "source-unlinked" | "purge-authorized";
+type OffloadFileIdentity = {
+    bytes: number;
+    allocatedBytes: number;
+    links: number;
+    dev: string;
+    ino: string;
+};
+/** Durable intent for removing one immutable local encrypted archive. */
+export type OffloadTransaction = {
+    version: 1;
+    id: string;
+    archiveId: string;
+    objectPath: string;
+    stagingPath: string;
+    createdAt: string;
+    updatedAt: string;
+    stage: OffloadStage;
+    original: OffloadFileIdentity;
+    /** Exact final inode state authorised for the staged-name unlink. */
+    purgeSnapshot?: OffloadFileIdentity;
+    remote: {
+        copyId?: string;
+        destinationKey?: string;
+        provider: string;
+        bucket: string;
+        objectKey: string;
+    };
+};
+export declare function offloadJournalPath(dataDir: string, id: string): string;
+export declare function reconcileOffloadTransactions(dataDir: string, options?: OffloadOptions & {
+    client?: FetchClient;
+    overrides?: EndpointOverrides;
+}): Promise<{
+    completed: OffloadCandidate[];
+    failed: {
+        id: string;
+        error: string;
+    }[];
+    freedBytes: number;
+}>;
 /**
  * Removes local archives that a bucket has a verified copy of.
  *
@@ -52,10 +135,10 @@ export declare function offloadable(dataDir: string): Promise<{
  * accepted from a caller, so a page held open since yesterday cannot ask for
  * the deletion of something that has since become the only copy.
  */
-export declare function offloadArchives(dataDir: string, options?: {
+export declare function offloadArchives(dataDir: string, options?: OffloadOptions & {
     confirm?: boolean;
     client?: FetchClient;
-    only?: ReadonlySet<string>;
+    overrides?: EndpointOverrides;
     freshlyVerified?: ReadonlySet<string>;
 }): Promise<{
     mode: "preview";
@@ -75,13 +158,23 @@ export declare function offloadArchives(dataDir: string, options?: {
     freedBytes: number;
     wouldOffload?: undefined;
 }>;
+/**
+ * Downloads an archive's ciphertext from the bucket it was offloaded to.
+ *
+ * SEALKEEP_ENABLE_SIGNER gates *uploading*, and it is off unless the installed
+ * service turns it on. Reading back an archive in order to restore it is not
+ * uploading, and refusing it on that flag would mean an offloaded archive could
+ * not be recovered by the person who owns it — which would turn a space-saving
+ * feature into data loss. The flag is set for this call only.
+ */
+export declare function fetchCiphertextStream(dataDir: string, record: ArchiveRecordV2, client?: FetchClient, selectedCopy?: RemoteObject, overrides?: EndpointOverrides, signal?: AbortSignal, idleMs?: number, maxBytesPerSecond?: number): Promise<ByteStream>;
 /**
  * Asks the storage, right now, whether it still holds this archive.
  *
  * `remote.verifiedAt` says the copy was proven once; between then and now is
  * exactly where a bucket lifecycle rule or a fat-fingered console delete
  * lives. This is the question a person asks before trusting the cloud copy
- * enough to trash the original — so it goes to the provider, not to our own
+ * enough to reclaim the original — so it goes to the provider, not to our own
  * records, and it compares the size the provider reports against the size we
  * recorded. It does not re-download the object: the byte-level proof already
  * ran when the copy was verified, and runs again on any restore (AEAD refuses
@@ -94,7 +187,7 @@ export type CopyCheck = {
     checkedAt: string;
     detail: string;
 };
-export declare function checkRemoteCopy(dataDir: string, archiveId: string, client?: FetchClient): Promise<CopyCheck>;
+export declare function checkRemoteCopy(dataDir: string, archiveId: string, client?: FetchClient, copyId?: string): Promise<CopyCheck>;
 /**
  * The bulk form of `checkRemoteCopy`. Managed rows share ONE control-plane
  * listing instead of asking per archive — checking a 53-row vault is one call
@@ -105,6 +198,99 @@ export type Materialised = {
     path: string;
     release: () => Promise<void>;
 };
+export type MaterialiseOptions = {
+    /** Fetch this exact stored copy rather than whichever copy is primary. */
+    copyId?: string;
+    overrides?: EndpointOverrides;
+    /**
+     * Caller-owned scratch pathname. The transfer journal uses this so a
+     * restart knows exactly which temporary bytes it owns and may remove.
+     */
+    path?: string;
+    /** Cancels a queued or active scratch fetch. Historical indexing uses this
+     * when its owning daemon stops, so the partial is removed before the child
+     * exits whenever the provider is still making progress. */
+    signal?: AbortSignal;
+    /** Cumulative verified staging bytes, for the caller's idle deadline. */
+    onProgress?: (bytes: number) => void;
+    /** Background callers share the vault-wide transfer bucket; manual restores
+     * remain explicitly unpaced unless their caller requests this ceiling. */
+    maxBytesPerSecond?: number;
+    /** Cooperative CPU checkpoint while hashing/staging a remote body. */
+    onYield?: () => void | Promise<void>;
+    /** Test/embedding seam. Ordinary callers use the operating-system temp
+     * directory; the chosen directory must already exist. */
+    scratchRoot?: string;
+    /** Maximum time to wait for another process that owns archive-sized scratch
+     * space. The default is deliberately short enough for an interactive action
+     * to finish with a retryable answer instead of looking permanently stuck. */
+    scratchWaitMs?: number;
+};
+/**
+ * Processes from different vaults can still spend the same filesystem's free
+ * bytes. Key the well-known lease by the scratch directory's device id in a
+ * per-user temp namespace; fall back to this vault's trusted runtime directory
+ * only on platforms where that identity cannot be established.
+ */
+export declare function ensurePrivateScratchCoordination(baseDir: string, user: string, expectedUid?: number | undefined): Promise<string>;
+/**
+ * Restores the sealed archive blob itself to this machine without decrypting
+ * the session. This is the safe first half of a remote-to-remote move: once a
+ * verified local blob exists, the ordinary target upload can copy it anywhere
+ * without buffering two providers through the browser or risking the source.
+ */
+export declare function restoreArchiveLocal(dataDir: string, archiveId: string, options?: {
+    copyId?: string;
+    client?: FetchClient;
+    overrides?: EndpointOverrides;
+    signal?: AbortSignal;
+    onProgress?: (bytes: number) => void;
+}): Promise<{
+    restored: boolean;
+    alreadyPresent: boolean;
+    bytes: number;
+    path: string;
+}>;
+export type RestoreArchiveChainLocalResult = {
+    /** True when at least one encrypted chain link was downloaded. */
+    restored: boolean;
+    /** True only when every required link was already present and verified. */
+    alreadyPresent: boolean;
+    /** Total encrypted bytes the complete local chain occupies. */
+    bytes: number;
+    /** Encrypted bytes downloaded by this call. */
+    restoredBytes: number;
+    /** Canonical local path of the selected head. */
+    path: string;
+    /** Oldest complete base first, selected head last. */
+    chain: string[];
+    restoredArchiveIds: string[];
+    alreadyPresentArchiveIds: string[];
+};
+/**
+ * Restore one logical session's complete encrypted delta chain.
+ *
+ * Every missing link is downloaded into a private sibling temporary file and
+ * checked against its authenticated ciphertext length and digest first. Only
+ * after the *whole* chain passes are the files hard-linked into their canonical
+ * paths. A hard link gives us an exclusive publish operation: another process
+ * cannot race this restore into overwriting an existing archive. If any publish
+ * fails, every path published by this call is removed again, while all remote
+ * copies and archive records remain untouched.
+ *
+ * Metadata is changed only after every required local file exists. A metadata
+ * write failure deliberately keeps the complete verified local chain as an
+ * extra safe copy and leaves all remote copies in place; it can never expose a
+ * head without its base or authorize a provider delete.
+ */
+export declare function restoreArchiveChainLocal(dataDir: string, archiveId: string, options?: {
+    /** Exact source for the selected head. */
+    copyId?: string;
+    /** Exact sources selected by the caller for individual chain links. */
+    copyIds?: Readonly<Record<string, string>>;
+    client?: FetchClient;
+    overrides?: EndpointOverrides;
+}): Promise<RestoreArchiveChainLocalResult>;
 /**
  * Gives back a local path holding this archive's ciphertext, fetching it first
  * if the local copy was offloaded.
@@ -114,4 +300,5 @@ export type Materialised = {
  * one and removed afterwards, which keeps the disk saving intact: the bytes are
  * on this machine only for as long as the restore takes.
  */
-export declare function materialiseArchive(dataDir: string, record: ArchiveRecord, client?: FetchClient): Promise<Materialised>;
+export declare function materialiseArchive(dataDir: string, record: ArchiveRecord, client?: FetchClient, options?: MaterialiseOptions): Promise<Materialised>;
+export {};