sealkeep 0.5.0

package/dist/src/cloud.d.ts

@@ -0,0 +1,434 @@
+import { type BackendName } from "./secrets.js";
+import { type Envelope } from "../packages/vaultline-crypto/src/index.js";
+/**
+ * Sealkeep Cloud: the managed tier.
+ *
+ * The trade for paying is that you configure nothing — no bucket, no IAM, no
+ * credentials. What you do not trade away is control of your data: this module
+ * asks the control plane for permission to write one object, then talks to
+ * storage directly. Ciphertext never passes through our servers, and the
+ * control plane is never sent a key that opens it.
+ */
+export declare const DEFAULT_CLOUD_URL = "https://shared.spala.ai/p04946/api";
+/**
+ * Where this vault's cloud token lives in the keystore.
+ *
+ * Keyed by vault as well as by cloud URL. Keying on the URL alone made the
+ * token machine-global: every vault on the machine inherited whichever account
+ * happened to be signed in, so a brand-new free-tier vault reported itself
+ * signed in as someone else, showed a green sealed-key check it had no claim
+ * to, and — because `resolveSyncRules` reads that account — silently applied a
+ * stranger's sync rules. On this machine that held back 659 of 662 sessions on
+ * a vault that had never logged in to anything.
+ *
+ * Exported because `enroll` stores a token at this same location. Two copies of
+ * a key format that must agree is how `access_key_id` drifted from `akid` and
+ * would have signed every managed upload with an undefined credential — one
+ * definition, imported, so a change here cannot leave the other behind.
+ */
+export declare function tokenRefFor(vaultId: string, env?: NodeJS.ProcessEnv): {
+    service: string;
+    account: string;
+};
+export type CloudAccount = {
+    id: number;
+    email: string;
+    label: string;
+    plan: "free" | "pro_lite" | "pro";
+    state: string;
+    quota_bytes: number;
+    used_bytes: number;
+};
+/**
+ * A lease says where this archive goes and how to get it there.
+ *
+ * Two shapes, because the two families of provider delegate differently:
+ *
+ * - `upload_url` — the control plane presigned a single object. GCS works this
+ *   way, and so would S3 if we signed centrally.
+ * - `vended` — the control plane handed back a short-lived credential scoped to
+ *   this account's own prefix, and this machine signs its own request. That is
+ *   how B2 and R2 are reached: their scoping lives in the credential rather
+ *   than in a URL, so tenant isolation is the provider's job instead of ours.
+ *
+ * The client does not care which arrives. Nothing above `putCiphertext` knows
+ * or needs to know which provider is holding the bytes, which is the whole
+ * point — we can move managed storage between providers without shipping a new
+ * CLI, because an archive already carries everything needed to open it.
+ */
+export type VendedCredential = {
+    provider: "s3" | "r2" | "b2";
+    bucket: string;
+    region: string;
+    /** Omitted for AWS, where the host is derived from bucket and region. */
+    host?: string;
+    /** For self-hosted S3-compatible endpoints. Managed leases are always https on 443. */
+    port?: number;
+    protocol?: "https" | "http";
+    /**
+     * Named `akid`, not `access_key_id`, because Spala's response filter redacts
+     * the latter — it replaces the value with "[REDACTED]" while passing
+     * `secret_access_key` and `session_token` through untouched. The client would
+     * receive a literal "[REDACTED]" to sign with. See SPALA_BACKEND.md issue 27.
+     */
+    akid: string;
+    secret_access_key: string;
+    session_token?: string;
+    /**
+     * When the vended key stops working, ISO-8601. Checked before every signing
+     * so a stalled or resumed run re-leases instead of shipping requests the
+     * provider will 403 — absent (older planes) falls back to the lease's own
+     * expires_at, which every lease already carries.
+     */
+    expires_at?: string;
+};
+export type UploadLease = {
+    lease_id: number;
+    vault_ref: string;
+    object_key: string;
+    expires_at: string;
+    upload_url?: {
+        url: string;
+        method: string;
+        headers: Record<string, string>;
+    };
+    vended?: VendedCredential;
+};
+export declare function register(dataDir: string, input: {
+    email: string;
+    password: string;
+    label: string;
+}, preferred?: BackendName): Promise<CloudAccount>;
+/** The token lives in the OS keychain, never in a config file on disk. */
+export declare function login(dataDir: string, input: {
+    email: string;
+    password: string;
+}, preferred?: BackendName): Promise<CloudAccount>;
+/**
+ * Sign in with a one-time code from the web panel instead of a password.
+ *
+ * An account created through Google has no password anybody knows — the server
+ * stores a bcrypt of a random string it never shows. Without this, every Google
+ * customer would have a working dashboard and an unusable CLI. The code is
+ * single-use and the server clears it on redemption.
+ */
+export declare function loginWithCode(dataDir: string, input: {
+    email: string;
+    token: string;
+}, preferred?: BackendName): Promise<CloudAccount>;
+export declare function logout(dataDir: string, preferred?: BackendName): Promise<void>;
+export declare function cloudToken(dataDir: string, preferred?: BackendName): Promise<string>;
+export declare function accountStatus(dataDir: string, preferred?: BackendName): Promise<CloudAccount>;
+/**
+ * Recovery without custody.
+ *
+ * The escrow blob is the vault's secret material sealed with the recovery
+ * phrase, exactly like an archive. We store it so a lost machine is not a lost
+ * vault, but it is ciphertext to us: without the phrase it is noise, and the
+ * phrase is never transmitted. Losing the phrase still loses the data — that is
+ * the point, and the signup flow has to say so plainly.
+ */
+/**
+ * A way back into the escrow blob, beyond the recovery phrase.
+ *
+ * Each one is an independent recipient: any single unlock opens the blob, so
+ * adding one is adding a key, not a factor. That is worth stating in those
+ * words because it is the thing most easily got wrong — "password *and* phrase"
+ * sounds stronger than either alone, and as separate recipients it is exactly
+ * as strong as the weaker of the two.
+ *
+ * - `password` derives its key with scrypt, like the phrase does. It makes a
+ *   new machine reachable with something a person remembers, and it makes the
+ *   password the whole key. A weak one is a weak vault, and no amount of
+ *   wording elsewhere changes that.
+ * - `publicKey` is an X25519 recipient: a passkey's PRF-derived identity (see
+ *   src/passkey.ts), or an organisation's escrow key. Nothing secret is needed
+ *   to *add* one, only to use it.
+ *
+ * What is never here is anything we could derive ourselves. The server stores
+ * the envelope as an opaque string, so recipients can be added without it
+ * learning anything, and without a server change.
+ */
+export type EscrowUnlock = {
+    kind: "password";
+    password: string;
+} | {
+    kind: "publicKey";
+    publicKeyBase64: string;
+    label?: string;
+};
+/**
+ * Refuses an escrow password that is also the account password.
+ *
+ * `login` sends the account password to the control plane, where it is bcrypted
+ * — which is ordinary and fine for authentication, and fatal here. An escrow
+ * password is a key that opens the blob on its own, so if it is the same string
+ * the account is authenticated with, then we have been handed that key, and so
+ * has anyone who takes the database or compels us to produce it. The product's
+ * central claim — that we cannot open your archives — would be false, and
+ * false in a way no customer could detect.
+ *
+ * Enforced rather than documented, because a rule that only exists in prose is
+ * a rule people break by pasting the password they already use. The comparison
+ * is deliberately naive: this is a mistake-catcher, not a policy engine, and
+ * the caller is the only place both strings are ever in hand at once.
+ *
+ * The real fix is for authentication to stop sending the raw password at all —
+ * send one derivation to log in, keep another for encryption, so reuse becomes
+ * harmless instead of forbidden. That is a control-plane change; until it
+ * happens, this keeps the guarantee true.
+ */
+export declare function assertEscrowPasswordDistinct(accountPassword: string, escrowPassword: string): void;
+export declare function sealEscrow(secretMaterial: Record<string, unknown>, rawPhrase: string, also?: readonly EscrowUnlock[]): {
+    envelope: Envelope;
+    ciphertext: Buffer;
+};
+export declare function openEscrow(envelope: Envelope, ciphertext: Buffer, rawPhrase: string): Record<string, unknown>;
+/**
+ * Opens the blob with a password that was registered as an unlock.
+ *
+ * Separate from `openEscrow` so the two cannot be confused at a call site: this
+ * one is reached by typing something memorable, which is the convenience the
+ * paid tier is for and also the weaker of the two doors. The failure message
+ * says password rather than phrase, because being told your recovery phrase is
+ * wrong when you typed a password is how people conclude they have lost
+ * everything.
+ */
+export declare function openEscrowWithPassword(envelope: Envelope, ciphertext: Buffer, password: string): Record<string, unknown>;
+/**
+ * Opens the blob with a key: a passkey's derived identity, or an org's escrow
+ * key. The private half is never stored by us and never travels — it is
+ * re-derived from the authenticator, or held by whoever owns the org key.
+ */
+export declare function openEscrowWithKey(envelope: Envelope, ciphertext: Buffer, privateKeyRaw: Buffer): Record<string, unknown>;
+export type EscrowBlob = {
+    envelope: Envelope;
+    sealed: string;
+    created_at?: string;
+};
+/**
+ * Hand the sealed blob to the control plane.
+ *
+ * What crosses the wire is ciphertext plus the envelope needed to unwrap it
+ * *given the phrase*. The phrase itself is never sent, so possession of this
+ * record — by us, or by anyone who takes the database — does not open it.
+ */
+export declare function pushEscrow(dataDir: string, secretMaterial: Record<string, unknown>, rawPhrase: string, preferred?: BackendName, also?: readonly EscrowUnlock[]): Promise<{
+    stored: true;
+}>;
+/** Fetch and open the escrow blob. Requires the phrase; nothing else will do. */
+/** Whether a sealed copy exists, without needing the phrase to find out. */
+export declare function hasSealedCopy(dataDir: string, preferred?: BackendName): Promise<boolean>;
+export declare function pullEscrow(dataDir: string, rawPhrase: string, preferred?: BackendName): Promise<Record<string, unknown>>;
+/** Asks for permission to write exactly one object. The key is chosen server-side. */
+export declare function requestUpload(dataDir: string, input: {
+    vaultRef: string;
+    ciphertextSha256: string;
+    bytes: number;
+}, preferred?: BackendName): Promise<UploadLease>;
+/**
+ * Straight to storage, whichever way the lease delegated.
+ *
+ * A presigned lease is obeyed verbatim — the signer chose the method and the
+ * headers, and changing either invalidates the signature. A vended lease is
+ * signed here with the same SigV4 code the bring-your-own-bucket path uses, so
+ * managed B2 and a customer's own S3 bucket travel through one tested signer
+ * rather than two. A lease naming a delegation this build does not know is
+ * refused before a single byte or signature leaves the machine.
+ */
+export declare function putCiphertext(lease: UploadLease, ciphertext: Buffer, signal?: AbortSignal): Promise<void>;
+export declare function completeUpload(dataDir: string, leaseId: number, bytes: number, preferred?: BackendName): Promise<unknown>;
+export type PushResult = {
+    archiveId: string;
+    objectKey: string;
+    bytes: number;
+    durable: boolean;
+    note?: string;
+};
+/**
+ * Push one already-encrypted archive to managed storage.
+ *
+ * Completion is reported separately from the upload because the bytes are
+ * already safe in storage by then. If metering fails we say so rather than
+ * claiming the archive is not stored, which would be false and would invite a
+ * pointless re-upload.
+ */
+/**
+ * Fetch an archive's ciphertext back from managed storage.
+ *
+ * The server hands out a short-lived signed GET and never sees the plaintext;
+ * the hash it records is verified here before anything is written, so a
+ * truncated or substituted object is refused rather than decrypted.
+ */
+export type CloudArchive = {
+    vault_ref: string;
+    bytes: number;
+    state: string;
+    durable_at?: string;
+    created_at?: string;
+    object_key?: string;
+};
+/** What managed storage is holding for this account. The ref is what `sealkeep open` takes. */
+/**
+ * The managed index slot: one sealed content index per account, moved through
+ * control-plane-signed URLs exactly like archive objects — known lengths, the
+ * signer the plane already has. `kind` is "meta" (the tiny envelope, read
+ * first to decide freshness) or "blob" (the sealed index itself). The plane
+ * sees ciphertext sizes and update times; tokens never leave the machines.
+ */
+/**
+ * Drive OAuth on the account's shared Google client, Paul's way: reuse the
+ * client the backend already owns, keep its secret THERE, and let this
+ * machine hold only its own tokens. The CLI opens the consent URL, a loopback
+ * listener on the registered fixed port catches the code, and the plane —
+ * authenticated as this account — exchanges it. Nothing is stored server-side.
+ */
+export declare function gdriveOauthConfig(dataDir: string, preferred?: BackendName): Promise<{
+    client_id: string;
+    redirect_uri: string;
+    scope: string;
+}>;
+export declare function gdriveExchange(dataDir: string, input: {
+    code: string;
+    redirectUri: string;
+}, preferred?: BackendName): Promise<{
+    refresh_token: string;
+    access_token: string;
+    expires_in: number;
+}>;
+export declare function gdriveRefresh(dataDir: string, refreshToken: string, preferred?: BackendName): Promise<{
+    accessToken: string;
+    expiresIn: number;
+}>;
+export declare function gdriveClaim(dataDir: string, state: string, preferred?: BackendName): Promise<{
+    refresh_token: string;
+    access_token: string;
+    expires_in: number;
+} | null>;
+/**
+ * The consent flow for the shared client. Two shapes, decided by the server's
+ * registered redirect: a REMOTE https callback (the plane exchanges and parks
+ * the tokens; this machine polls its one-time state — works even when the
+ * browser lives on another device), or a loopback listener that catches the
+ * code here and exchanges through the authed endpoint.
+ */
+export declare function connectGdriveViaCloud(dataDir: string, options?: {
+    onConsentUrl?: (url: string) => void;
+    opener?: (url: string) => unknown;
+    timeoutMs?: number;
+    preferred?: BackendName;
+    pollMs?: number;
+}): Promise<{
+    kind: "gdrive";
+    refreshToken: string;
+    clientId: string;
+    exchange: "cloud";
+}>;
+export declare function pushIndexObject(dataDir: string, kind: "meta" | "blob", body: Buffer, preferred?: BackendName): Promise<void>;
+export declare function pullIndexObject(dataDir: string, kind: "meta" | "blob", preferred?: BackendName): Promise<Buffer | null>;
+export declare function listCloudArchives(dataDir: string, preferred?: BackendName): Promise<CloudArchive[]>;
+/**
+ * Really deletes one stored object from managed storage.
+ *
+ * Goes through the control plane rather than storage directly, because it is
+ * the same call the account panel's Archives section makes — one delete path,
+ * so the product and the panel cannot come to mean different things by
+ * "deleted". The control plane removes the object and its row, and billing
+ * follows the row.
+ */
+export declare function deleteCloudArchive(dataDir: string, vaultRef: string, preferred?: BackendName): Promise<void>;
+export type DownloadLease = {
+    vault_ref: string;
+    bytes: number;
+    ciphertext_sha256: string;
+    object_key?: string;
+    download?: {
+        url: string;
+        method?: string;
+        headers?: Record<string, string>;
+    };
+    vended?: VendedCredential;
+};
+/**
+ * A byte range of a stored object, for chunk-granular reads. The whole-object
+ * hash cannot be checked on a slice — that is the point of a slice — so the
+ * caller's integrity comes from the per-chunk hashes and AEAD tags inside
+ * (see vaultline-crypto/chunk-access). Only the presigned-URL lease shape
+ * supports ranges today; a vended-credential lease falls back to whole-object.
+ */
+export declare function pullCiphertextRange(dataDir: string, vaultRef: string, storedOffset: number, storedLength: number, preferred?: BackendName): Promise<Buffer>;
+/**
+ * Existence and stored size of a managed object, proven against STORAGE, not
+ * the plane's row: the row is minted by metering and a metering row is not an
+ * object. A one-byte ranged GET on the download URL answers both questions
+ * for the cost of a header — the Content-Range total is the provider's own
+ * count. This is what lets chunk-folder verification and resume treat managed
+ * storage with exactly the discipline `verifyStored` demands of it.
+ */
+export declare function statCiphertext(dataDir: string, vaultRef: string, preferred?: BackendName): Promise<{
+    exists: boolean;
+    bytes: number;
+}>;
+export declare function pullCiphertext(dataDir: string, vaultRef: string, preferred?: BackendName): Promise<{
+    ciphertext: Buffer;
+    bytes: number;
+}>;
+export declare function frameObject(envelope: unknown, ciphertext: Buffer): Buffer;
+export declare function unframeObject(blob: Buffer): {
+    envelope: any | null;
+    ciphertext: Buffer;
+};
+/**
+ * Fetch one archive and open it, on any machine.
+ *
+ * This is the whole disaster-recovery story in one call: the recovery phrase
+ * unwraps the archive key from the envelope the object carries, so a fresh
+ * laptop with nothing but the phrase can read the archive back. The plaintext
+ * hash recorded at seal time is checked inside decryptArchive, after the AEAD
+ * has authenticated every chunk.
+ */
+export declare function openFromCloud(dataDir: string, vaultRef: string, destination: string, rawPhrase: string, preferred?: BackendName): Promise<{
+    output: string;
+    bytes: number;
+}>;
+export type ArchiveCheck = {
+    vaultRef: string;
+    bytes: number;
+    ok: boolean;
+    problem?: string;
+};
+/**
+ * The judgement, kept separate from the fetching so it can be tested honestly.
+ *
+ * `recorded` is what the control plane says the archive is; `got` is what
+ * storage actually returned, or the error it failed with. A raw status code is
+ * not an explanation, so a missing object is named in words a customer can act
+ * on.
+ */
+export declare function classifyArchive(recorded: {
+    vault_ref: string;
+    bytes: number;
+}, got: {
+    length: number;
+} | {
+    error: string;
+}): ArchiveCheck;
+/**
+ * Proves the archives really are retrievable.
+ *
+ * A backup nobody has tested is a hope, not a backup. This fetches each durable
+ * archive back and checks it against the hash recorded at upload, so the two
+ * ways an archive can quietly rot are both caught: the object is missing from
+ * storage, or the bytes no longer match what was sealed.
+ *
+ * It deliberately re-downloads rather than trusting a HEAD. Size alone would
+ * pass an object that was truncated and re-padded, and the whole point of the
+ * exercise is to distrust the happy path.
+ */
+export declare function verifyArchives(dataDir: string, options?: {
+    limit?: number;
+    onProgress?: (check: ArchiveCheck) => void;
+}, preferred?: BackendName): Promise<ArchiveCheck[]>;
+export declare function pushArchive(dataDir: string, archiveId: string, preferred?: BackendName, options?: {
+    signal?: AbortSignal;
+}): Promise<PushResult>;