sealkeep 0.8.1 → 0.11.0

package/dist/src/cloud.d.ts

@@ -1,5 +1,7 @@
-import { type BackendName } from "./secrets.js";
-import { type Envelope } from "../packages/vaultline-crypto/src/index.js";
+import { type BackendName, type SecretBackend, type SecretRef } from "./secrets.js";
+import { type Envelope } from "../packages/sealkeep-crypto/src/index.js";
+import { type ByteStream } from "./byte-stream.js";
+import { type TeamIndexCacheIdentity } from "./team-index-cache.js";
 /**
  * Sealkeep Cloud: the managed tier.
  *
@@ -10,6 +12,40 @@ import { type Envelope } from "../packages/vaultline-crypto/src/index.js";
  * control plane is never sent a key that opens it.
  */
 export declare const DEFAULT_CLOUD_URL = "https://shared.spala.ai/p04946/api";
+export declare const cloudUrl: (env?: NodeJS.ProcessEnv) => string;
+export declare function signalCloudAuthChange(dataDir: string): Promise<void>;
+/** Cheap generation probe used by long-running services; contains no token. */
+export declare function cloudAuthGeneration(dataDir: string): Promise<string | null>;
+type CloudCredentialMutation = {
+    ref: SecretRef;
+    value: string | null;
+};
+type CloudAuthMutationDependencies = {
+    /** Fault-injection seam. Production always uses the atomic file writer above. */
+    writeGeneration?: (dataDir: string, value: string) => Promise<void>;
+    /** Compare-and-set fence for a network result produced under an earlier login. */
+    expectedAuthGeneration?: string | null;
+};
+/**
+ * Changes account credentials without ever publishing them under an old cache
+ * scope. The transition marker is durable and written before the first secret:
+ * readers refuse it. A second atomic write publishes the new stable scope only
+ * after every secret has been read back successfully.
+ *
+ * If a secret or the final generation write fails, every old secret is restored
+ * and a fresh rollback scope is published. If even that last write cannot land
+ * (for example a completely full disk), the transition marker deliberately
+ * remains: Cloud reads stay closed instead of guessing which account owns the
+ * credentials. A later successful login/logout can replace that marker.
+ */
+export declare function commitCloudAuthCredentials(dataDir: string, backend: SecretBackend, requested: readonly CloudCredentialMutation[], dependencies?: CloudAuthMutationDependencies): Promise<void>;
+/**
+ * Seqlock for credential readers. A reader which overlaps either edge of an
+ * auth transaction must retry; otherwise an old token can be paired with the
+ * new generation (or the reverse) even though both individual writes are
+ * atomic. Exported as a narrow test seam so the overlap is deterministic.
+ */
+export declare function readCloudAuthSnapshot<T>(dataDir: string, read: () => Promise<T>): Promise<T>;
 /**
  * Where this vault's cloud token lives in the keystore.
  *
@@ -30,15 +66,184 @@ export declare function tokenRefFor(vaultId: string, env?: NodeJS.ProcessEnv): {
     service: string;
     account: string;
 };
+/**
+ * A fresh install has no vault id yet. Its Cloud pairing therefore waits in
+ * the native secret backend under a data-directory-scoped bootstrap key until
+ * this machine either creates a new vault or adopts an approved existing one.
+ * The hash prevents two independent SealKeep homes on the same OS account from
+ * inheriting one another's login without putting the local path in keychain UI.
+ */
+export declare function bootstrapTokenRefFor(dataDir: string, env?: NodeJS.ProcessEnv): {
+    service: string;
+    account: string;
+};
+/**
+ * Where this machine's own credential lives, beside the account token.
+ *
+ * The account token says *which account* is calling and nothing more — every
+ * laptop paired to a company account presents an identical one. That is fine
+ * for reading and for adding, and wrong for destroying: without a second fact
+ * the control plane cannot tell one machine's delete from another's, so any
+ * laptop could erase a colleague's sealed history and the audit row would name
+ * only the account. The machine key is that second fact. It is minted once at
+ * pairing, the server keeps only a bcrypt of it, and it rides in the request
+ * body rather than a header because this control plane strips request headers
+ * before endpoint logic ever sees them — proven, not assumed.
+ */
+export declare function machineRefFor(vaultId: string, env?: NodeJS.ProcessEnv): {
+    service: string;
+    account: string;
+};
+export declare function bootstrapMachineRefFor(dataDir: string, env?: NodeJS.ProcessEnv): {
+    service: string;
+    account: string;
+};
+export type MachineCredential = {
+    device_id: number;
+    machine_key: string;
+};
+/**
+ * This machine's credential, claiming one if it does not have it yet.
+ *
+ * Machines that paired before machine keys existed hold only an account token.
+ * Left alone they would keep sealing archives nothing can attribute, and the
+ * protection would silently never switch on for them — the worst kind of
+ * security change, the sort that upgrades cleanly and does nothing. So the
+ * first call that needs an identity claims one. `claim` is false on paths
+ * where a network round trip would be a surprise.
+ */
+export declare function machineIdentity(dataDir: string, preferred?: BackendName, options?: {
+    signal?: AbortSignal;
+}): Promise<MachineCredential | null>;
+/** This machine's credential, or null when it paired before machine keys existed. */
+export declare function machineCredential(dataDir: string, preferred?: BackendName): Promise<MachineCredential | null>;
+/**
+ * This machine's credential as a read-only snapshot. Unlike
+ * `machineCredential`, this never migrates a pre-vault bootstrap alias and
+ * therefore cannot advance the Cloud auth generation. Advisory telemetry uses
+ * this path; operations which need a durable machine identity keep the normal
+ * healing behaviour above.
+ */
+export declare function peekMachineCredential(dataDir: string, preferred?: BackendName): Promise<MachineCredential | null>;
+/**
+ * Announce this machine and keep the key it is handed.
+ *
+ * Best-effort on purpose: a machine that cannot register is still signed in and
+ * still archives. It is merely anonymous to the control plane, which is exactly
+ * what every machine was before this existed — so failing here must never fail
+ * a sign-in.
+ */
+export declare function registerMachine(dataDir: string, token: string, preferred?: BackendName, options?: {
+    signal?: AbortSignal;
+}): Promise<MachineCredential | null>;
+/**
+ * Cloud coordinates fresh-machine approval but never receives a private key or
+ * vault secret. These wire records contain a target public key and, after an
+ * existing device approves, one opaque E2EE package for that key.
+ */
+export type CloudDeviceEnrollmentRequest = {
+    id: number;
+    target_device_id?: number;
+    label: string;
+    public_key: string;
+    state: "pending" | "approved" | "consumed" | "expired";
+    created_at: string;
+    expires_at: string;
+    approved_at?: string | null;
+};
+export declare function createCloudDeviceEnrollment(dataDir: string, input: {
+    label: string;
+    publicKey: string;
+    requestSecret: string;
+}, preferred?: BackendName): Promise<CloudDeviceEnrollmentRequest>;
+export declare function listPendingCloudDeviceEnrollments(dataDir: string, preferred?: BackendName): Promise<CloudDeviceEnrollmentRequest[]>;
+export declare function approveCloudDeviceEnrollment(dataDir: string, requestId: number, bundle: {
+    envelope: Envelope;
+    sealed: string;
+}, preferred?: BackendName): Promise<{
+    approved: true;
+}>;
+export declare function claimCloudDeviceEnrollment(dataDir: string, requestId: number, requestSecret: string, preferred?: BackendName): Promise<{
+    envelope: Envelope | string;
+    sealed: string;
+}>;
+export declare function completeCloudDeviceEnrollment(dataDir: string, requestId: number, requestSecret: string, preferred?: BackendName): Promise<{
+    consumed: true;
+}>;
+/**
+ * `seats` is the purchased machine allowance and is absent on accounts that
+ * run on their tier's default, so it is optional rather than zero — a zero
+ * here would read as "no machines allowed", which is a different thing.
+ */
 export type CloudAccount = {
     id: number;
     email: string;
     label: string;
-    plan: "free" | "pro_lite" | "pro";
+    plan: "free" | "pro_lite" | "pro" | "team";
     state: string;
     quota_bytes: number;
     used_bytes: number;
+    seats?: number | null;
+};
+/**
+ * Browser-approved authorization for a fresh machine.
+ *
+ * The verifier is created and retained by the local client. Cloud receives
+ * only its S256 challenge until the claim, so an approval URL copied from the
+ * browser cannot be exchanged by whoever happens to see it. `public_key` is
+ * the target's ephemeral X25519 enrollment key, not an archive or account key.
+ */
+export type CloudDeviceAuthorizationStart = {
+    request_id: string;
+    approval_url: string;
+    created_at?: string;
+    expires_at: string;
+    poll_after_ms?: number;
+};
+export type CloudDeviceAuthorizationMemory = {
+    preserved: boolean;
+    bytes: number;
+};
+export type CloudDeviceAuthorizationEnrollment = {
+    request_id: number;
+    request_secret: string;
+    created_at: string;
+    expires_at: string;
+};
+export type CloudDeviceAuthorizationClaim = {
+    /** `denied` is the current hosted contract; `declined` remains readable for
+     * an in-flight authorization created by an older hosted build. */
+    status: "pending" | "approved" | "denied" | "declined" | "expired";
+    expires_at?: string;
+    poll_after_ms?: number;
+    token?: string;
+    account_token?: string;
+    machine?: MachineCredential;
+    account?: CloudAccount;
+    memory?: CloudDeviceAuthorizationMemory;
+    enrollment?: CloudDeviceAuthorizationEnrollment | null;
 };
+export declare function startCloudDeviceAuthorization(input: {
+    challenge: string;
+    label: string;
+    osFamily: "macos" | "linux" | "windows";
+    agents: string[];
+    publicKey: string;
+}): Promise<CloudDeviceAuthorizationStart>;
+export declare function claimCloudDeviceAuthorization(input: {
+    requestId: string;
+    verifier: string;
+}): Promise<CloudDeviceAuthorizationClaim>;
+/**
+ * Commits an approved hosted authorization to the same native secret backend
+ * used by ordinary Cloud login. Neither credential is ever written to config,
+ * returned to the browser, or put in a URL. If the second write fails, the
+ * first is rolled back so setup never reports a half-paired machine.
+ */
+export declare function rememberCloudDeviceAuthorization(dataDir: string, input: {
+    accountToken: string;
+    machine: MachineCredential;
+}, preferred?: BackendName): Promise<void>;
 /**
  * A lease says where this archive goes and how to get it there.
  *
@@ -94,6 +299,23 @@ export type UploadLease = {
     };
     vended?: VendedCredential;
 };
+export type CloudBackoff = {
+    version: 1;
+    until: number;
+    retryAfterMs: number;
+    updatedAt: string;
+    scope: "control-plane";
+};
+/**
+ * One cooldown shared by every transport that reaches the control plane.
+ *
+ * REST learns it from Retry-After, while the realtime listener may learn the
+ * same fact during a Socket.IO handshake. Keeping the high-water timestamp in
+ * one package-owned receipt prevents either transport (and a freshly started
+ * daemon) from bypassing the other one's server-requested quiet period.
+ */
+export declare function cloudBackoffUntil(dataDir: string, env?: NodeJS.ProcessEnv): Promise<number>;
+export declare function rememberCloudBackoff(dataDir: string, retryAfterMs: number, env?: NodeJS.ProcessEnv): Promise<CloudBackoff>;
 export declare function register(dataDir: string, input: {
     email: string;
     password: string;
@@ -117,8 +339,262 @@ export declare function loginWithCode(dataDir: string, input: {
     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>;
+export declare function cloudToken(dataDir: string, preferred?: BackendName, options?: {
+    renew?: boolean;
+    signal?: AbortSignal;
+}): Promise<string>;
+export declare function accountStatus(dataDir: string, preferred?: BackendName, options?: {
+    signal?: AbortSignal;
+    renewToken?: boolean;
+}): Promise<CloudAccount>;
+/** Explicit user reconnection reuses the existing device, never a new seat. */
+export declare function reconnectCloudSession(dataDir: string, preferred?: BackendName): Promise<{
+    reconnected: boolean;
+}>;
+/**
+ * The hosted team lane stores routing facts and ciphertext only. These wire
+ * types deliberately contain no plaintext project, task, person label, or
+ * recovery material.
+ */
+export type TeamIdentityWire = {
+    id?: number;
+    account_id?: number;
+    public_key: string;
+    key_box: string;
+    updated_at?: string;
+};
+export type TeamSpaceWire = {
+    id?: number;
+    space_id?: number;
+    space_key: string;
+    owner_account_id?: number;
+    key_version: number;
+    membership_version?: number;
+    /** Opaque Socket.IO room capability. Rotated with every feed-key epoch. */
+    realtime_key?: string;
+    role?: "owner" | "member" | string;
+    public_key?: string;
+    wrapped_key?: string;
+    joined_at?: string;
+    project_name?: string;
+};
+export type TeamInviteeWire = {
+    account_id: number;
+    public_key: string;
+    key_version?: number;
+};
+export type TeamMemberWire = {
+    id?: number;
+    space_id?: number;
+    space_key?: string;
+    account_id: number;
+    public_key: string;
+    wrapped_key: string;
+    key_version: number;
+    membership_version?: number;
+    realtime_key?: string;
+    display_email?: string;
+    role: "owner" | "member" | string;
+    joined_at?: string;
+    project_name?: string;
+};
+export type TeamRosterWire = {
+    members: TeamMemberWire[];
+    membership_version: number;
+    key_version?: number;
+};
+export type TeamPresenceRow = {
+    id: number;
+    space_id?: number;
+    account_id?: number;
+    sender: string;
+    sequence: number;
+    key_version: number;
+    ciphertext: string;
+    created_at?: string;
+};
+export type TeamRotationWrapWire = {
+    account_id: number;
+    public_key: string;
+    wrapped_key: string;
+};
+export type TeamRotationWire = {
+    removed_account_id: number;
+    history_fenced?: boolean;
+    key_version: number;
+    membership_version?: number;
+    realtime_key: string;
+    event?: TeamPresenceRow;
+};
+export type TeamArchiveWire = {
+    vault_ref: string;
+    membership_version?: number;
+    bytes: number;
+    ciphertext_sha256?: string;
+    uploader_account_id?: number;
+    created_at?: string;
+};
+export type TeamInvitationWire = {
+    id: number;
+    space_key: string;
+    inviter_account_id?: number;
+    invitee_account_id?: number;
+    invitee_email?: string;
+    inviter_email?: string;
+    project_name?: string;
+    public_key?: string;
+    state?: "preparing" | "ready";
+    status?: "pending" | "accepted" | "declined";
+    created_at?: string;
+    wrapped_key?: string;
+    key_version?: number;
+    history_fenced?: boolean;
+    history_membership_version?: number;
+    history_index_revision?: number;
+    history_archive_refs?: string;
+};
+export type TeamInvitationHistoryFence = {
+    expected_membership_version: number;
+    expected_index_revision: number;
+    expected_archive_refs: string;
+};
+export type TeamAccessRequestWire = {
+    id: number;
+    space_key: string;
+    account_id?: number;
+    target_account_id: number;
+    target_email?: string;
+    project_name?: string;
+    state: "requested" | "completed";
+    created_at?: string;
+};
+export type TeamProjectRequestWire = {
+    id: number;
+    account_id?: number;
+    project_name: string;
+    state: "requested" | "completed";
+    created_at?: string;
+    completed_at?: string;
+    space_key?: string;
+};
+export declare function getTeamIdentity(dataDir: string, preferred?: BackendName): Promise<TeamIdentityWire | null>;
+export declare function putTeamIdentity(dataDir: string, identity: Pick<TeamIdentityWire, "public_key" | "key_box">, preferred?: BackendName): Promise<TeamIdentityWire>;
+export declare function createTeamSpace(dataDir: string, input: {
+    space_key: string;
+    wrapped_key: string;
+    realtime_key: string;
+    project_name?: string;
+}, preferred?: BackendName): Promise<TeamSpaceWire>;
+export declare function listTeamSpaces(dataDir: string, preferred?: BackendName): Promise<TeamSpaceWire[]>;
+/** Cloud-owned intent; a connected machine creates and seals the project key. */
+export declare function listTeamProjectRequests(dataDir: string, preferred?: BackendName): Promise<TeamProjectRequestWire[]>;
+/** Create cloud-owned project intent; key creation still happens on a connected machine. */
+export declare function createTeamProjectRequest(dataDir: string, projectName: string, preferred?: BackendName): Promise<TeamProjectRequestWire>;
+/** Closes a project intent only after this account owns the prepared space. */
+export declare function completeTeamProjectRequest(dataDir: string, requestId: number, spaceKey: string, preferred?: BackendName): Promise<TeamProjectRequestWire>;
+export declare function getTeamMembership(dataDir: string, spaceKey: string, preferred?: BackendName): Promise<TeamMemberWire | null>;
+export declare function resolveTeamInvitee(dataDir: string, spaceKey: string, email: string, preferred?: BackendName): Promise<TeamInviteeWire>;
+export declare function addTeamMember(dataDir: string, spaceKey: string, input: {
+    email: string;
+    wrapped_key: string;
+    expected_key_version: number;
+}, preferred?: BackendName): Promise<TeamMemberWire>;
+/** Creates a pending invitation; membership is not granted until acceptance. */
+export declare function createTeamInvitation(dataDir: string, spaceKey: string, input: {
+    email: string;
+    wrapped_key?: string;
+    expected_key_version?: number;
+} & Partial<TeamInvitationHistoryFence>, preferred?: BackendName): Promise<TeamInvitationWire>;
+/** Invitations created in the hosted account that this signed-in account owns. */
+export declare function listOutgoingTeamInvitations(dataDir: string, preferred?: BackendName): Promise<TeamInvitationWire[]>;
+/** Submit ciphertext produced by the installed owner machine; plaintext keys never reach the browser. */
+export declare function prepareTeamInvitation(dataDir: string, invitationId: number, input: {
+    wrapped_key: string;
+    expected_key_version: number;
+} & TeamInvitationHistoryFence, preferred?: BackendName): Promise<TeamInvitationWire>;
+export declare function listTeamInvitations(dataDir: string, preferred?: BackendName): Promise<TeamInvitationWire[]>;
+export declare function acceptTeamInvitation(dataDir: string, invitationId: number, preferred?: BackendName): Promise<TeamMemberWire>;
+export declare function declineTeamInvitation(dataDir: string, invitationId: number, preferred?: BackendName): Promise<TeamInvitationWire>;
+export declare function listTeamMembers(dataDir: string, spaceKey: string, preferred?: BackendName): Promise<TeamMemberWire[]>;
+/** One server-consistent roster snapshot for CAS-sensitive sharing work. */
+export declare function getTeamRoster(dataDir: string, spaceKey: string, preferred?: BackendName, options?: {
+    signal?: AbortSignal;
+    renewToken?: boolean;
+}): Promise<TeamRosterWire>;
+/** Cloud-owned intent; a connected owner machine performs the key rotation. */
+export declare function createTeamRemovalRequest(dataDir: string, spaceKey: string, targetAccountId: number, preferred?: BackendName): Promise<TeamAccessRequestWire>;
+export declare function listOutgoingTeamAccessRequests(dataDir: string, preferred?: BackendName): Promise<TeamAccessRequestWire[]>;
+export declare function completeTeamAccessRequest(dataDir: string, requestId: number, preferred?: BackendName): Promise<TeamAccessRequestWire>;
+export declare function registerTeamArchive(dataDir: string, spaceKey: string, vaultRef: string, expectedMembershipVersion: number, preferred?: BackendName, options?: {
+    signal?: AbortSignal;
+}): Promise<TeamArchiveWire>;
+export declare function unregisterTeamArchive(dataDir: string, spaceKey: string, vaultRef: string, expectedMembershipVersion: number, preferred?: BackendName, options?: {
+    signal?: AbortSignal;
+}): Promise<void>;
+export declare function listTeamArchives(dataDir: string, spaceKey: string, preferred?: BackendName, options?: {
+    signal?: AbortSignal;
+    renewToken?: boolean;
+}): Promise<TeamArchiveWire[]>;
+export declare function teamArchiveDownload(dataDir: string, spaceKey: string, vaultRef: string, preferred?: BackendName, options?: {
+    signal?: AbortSignal;
+}): Promise<DownloadLease>;
+export type TeamReadGuard = {
+    assertCurrent(refs?: Iterable<string>): Promise<void>;
+};
+/** Pins local account identity while rechecking live membership and every exact grant.
+ * This guard carries no reusable permission: each assertion calls the Team plane. */
+export declare function createTeamReadGuard(dataDir: string, spaceKey: string, refs: Iterable<string>, membershipVersion: number, options?: {
+    signal?: AbortSignal;
+    preferred?: BackendName;
+}): Promise<TeamReadGuard>;
+/** Strict framed-object range transport. Integrity of a slice additionally
+ * requires the caller's authenticated envelope and per-chunk AEAD checks. */
+export declare function pullTeamCiphertextRange(dataDir: string, spaceKey: string, vaultRef: string, storedOffset: number, storedLength: number, preferred?: BackendName, options?: {
+    signal?: AbortSignal;
+    maxBytes?: number;
+    expectedMembershipVersion?: number;
+    /** One logical context read may share its identity pin. Its owner must call
+     * assertCurrent() after all ranges and before releasing any plaintext. */
+    readGuard?: TeamReadGuard;
+}): Promise<Buffer>;
+/** Streaming, integrity-checked read through the current project membership gate.
+ * Consumers must exhaust the stream before publishing any downloaded bytes. */
+export declare function pullTeamCiphertextStream(dataDir: string, spaceKey: string, vaultRef: string, preferred?: BackendName, options?: {
+    signal?: AbortSignal;
+    unframe?: boolean;
+    maxBytes?: number;
+}): Promise<ByteStream>;
+/** Download and verify a shared archive through the current membership gate. */
+export declare function pullTeamCiphertext(dataDir: string, spaceKey: string, vaultRef: string, preferred?: BackendName): Promise<{
+    ciphertext: Buffer;
+    bytes: number;
+}>;
+/**
+ * One owner-authorized, compare-and-swap epoch transition. The server removes
+ * the target, replaces every remaining wrap, advances the room capability and
+ * appends the encrypted discovery marker as one transaction.
+ */
+export declare function removeTeamMemberAndRotate(dataDir: string, spaceKey: string, targetAccountId: number, input: {
+    expected_key_version: number;
+    expected_membership_version?: number;
+    expected_index_revision?: number;
+    expected_archive_refs?: string;
+    realtime_key: string;
+    wraps: TeamRotationWrapWire[];
+    binding_sender: string;
+    binding_sequence: number;
+    binding_ciphertext: string;
+}, preferred?: BackendName, options?: {
+    signal?: AbortSignal;
+}): Promise<TeamRotationWire>;
+export declare function publishTeamPresence(dataDir: string, spaceKey: string, input: {
+    sender: string;
+    sequence: number;
+    key_version: number;
+    ciphertext: string;
+}, preferred?: BackendName): Promise<TeamPresenceRow>;
+export declare function pollTeamPresence(dataDir: string, spaceKey: string, after: number, preferred?: BackendName): Promise<TeamPresenceRow[]>;
+export declare function recentTeamPresence(dataDir: string, spaceKey: string, preferred?: BackendName): Promise<TeamPresenceRow[]>;
 /**
  * Recovery without custody.
  *
@@ -202,10 +678,25 @@ export declare function openEscrowWithPassword(envelope: Envelope, ciphertext: B
  */
 export declare function openEscrowWithKey(envelope: Envelope, ciphertext: Buffer, privateKeyRaw: Buffer): Record<string, unknown>;
 export type EscrowBlob = {
-    envelope: Envelope;
+    envelope: Envelope | string;
     sealed: string;
     created_at?: string;
+    id?: number;
+};
+export type RecoveryCodeCapsule = {
+    recipient_id: string;
+    envelope: Envelope | string;
+    sealed: string;
 };
+export type RecoveryKitCloudStatus = {
+    available: boolean;
+    remaining: number;
+    created_at?: string | null;
+};
+/** Upload an already-sealed escrow envelope without ever reconstructing it server-side. */
+export declare function pushEscrowBlob(dataDir: string, envelope: Envelope, ciphertext: Buffer, preferred?: BackendName): Promise<{
+    stored: true;
+}>;
 /**
  * Hand the sealed blob to the control plane.
  *
@@ -219,13 +710,60 @@ export declare function pushEscrow(dataDir: string, secretMaterial: Record<strin
 /** 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>;
+/** Latest append-only escrow revision; still ciphertext to every server involved. */
+export declare function pullEscrowBlob(dataDir: string, preferred?: BackendName): Promise<EscrowBlob | null>;
+/**
+ * Atomically replaces the phrase-only escrow copy and all one-time recovery
+ * capsules. Each capsule contains one opaque key wrap; Cloud never receives a
+ * code or phrase and normal escrow reads never expose a code-decryptable wrap.
+ */
+export declare function replaceCloudRecoveryKit(dataDir: string, master: {
+    envelope: Envelope;
+    ciphertext: Buffer;
+}, capsules: readonly RecoveryCodeCapsule[], preferred?: BackendName): Promise<{
+    stored: true;
+    remaining: number;
+    created_at?: string;
+}>;
+export declare function cloudRecoveryKitStatus(dataDir: string, preferred?: BackendName): Promise<RecoveryKitCloudStatus>;
+/**
+ * Atomically awards exactly one encrypted capsule to one random machine claim.
+ * A retry with the same claim is idempotent; a different claim gets no capsule.
+ */
+export declare function redeemCloudRecoveryCode(dataDir: string, recipientId: string, claimId: string, preferred?: BackendName): Promise<EscrowBlob & {
+    remaining: number;
+}>;
+/** Atomically spends one recovery recipient for this account. The code never crosses the wire. */
+export declare function consumeCloudRecoveryCode(dataDir: string, recipientId: string, claimId: string, preferred?: BackendName): Promise<{
+    consumed: true;
+}>;
+/**
+ * Resolves an ambiguous consume response without making a spent code reusable.
+ * Only the same random claim made by this machine is acknowledged.
+ */
+export declare function cloudRecoveryCodeClaimStatus(dataDir: string, recipientId: string, claimId: string, preferred?: BackendName): Promise<EscrowBlob & {
+    remaining: number;
+}>;
+/** Returns the awarded capsule only to the exact claim that spent the code. */
+export declare function claimCloudRecoveryCodeCapsule(dataDir: string, recipientId: string, claimId: string, preferred?: BackendName): Promise<EscrowBlob & {
+    remaining: number;
+}>;
 export declare function pullEscrow(dataDir: string, rawPhrase: string, preferred?: BackendName): Promise<Record<string, unknown>>;
+/** Process-local hint, never a cached permission or a serializable credential.
+ * Its only use is to require a fresh, descriptor-identical pending row before
+ * retrying the same frame. A completed object is never authorized by it. */
+export type IncompleteUpload = Readonly<{
+    status: "upload_incomplete";
+}>;
 /** 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>;
+}, preferred?: BackendName, options?: {
+    signal?: AbortSignal;
+    incompleteUpload?: IncompleteUpload;
+}): Promise<UploadLease>;
 /**
  * Straight to storage, whichever way the lease delegated.
  *
@@ -236,13 +774,29 @@ export declare function requestUpload(dataDir: string, input: {
  * 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 putCiphertextStream(lease: UploadLease, chunks: ByteStream, bytes: number, signal?: AbortSignal): Promise<{
+    bytes: number;
+    remoteChecksum: string | null;
+}>;
+/** Small-object compatibility (managed chunks/index); archives use the stream door. */
 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>;
+type BackgroundObjectReadOptions = {
+    signal?: AbortSignal;
+    maxBytesPerSecond?: number;
+    onProgress?: (bytes: number) => void;
+    onYield?: () => void | Promise<void>;
+    paceNow?: () => number;
+    paceSleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+};
+export declare function completeUpload(dataDir: string, leaseId: number, bytes: number, preferred?: BackendName, options?: {
+    signal?: AbortSignal;
+}): Promise<unknown>;
 export type PushResult = {
     archiveId: string;
     objectKey: string;
     bytes: number;
     durable: boolean;
+    checksum?: string;
     note?: string;
 };
 /**
@@ -261,6 +815,7 @@ export type PushResult = {
  * truncated or substituted object is refused rather than decrypted.
  */
 export type CloudArchive = {
+    id?: number;
     vault_ref: string;
     bytes: number;
     state: string;
@@ -268,6 +823,12 @@ export type CloudArchive = {
     created_at?: string;
     object_key?: string;
 };
+/** Array-compatible catalog result. `complete=false` is non-enumerable so
+ * existing JSON/iteration callers keep their contract while completeness-aware
+ * surfaces can avoid presenting a legacy capped listing as the whole account. */
+export type CloudArchiveList = CloudArchive[] & {
+    complete?: boolean;
+};
 /** 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
@@ -318,15 +879,162 @@ export declare function connectGdriveViaCloud(dataDir: string, options?: {
     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[]>;
+    /** Test seam; production resolves the opaque Drive permission id. */
+    accountIdResolver?: (accessToken: string) => Promise<string>;
+}): Promise<import("./providers/gdrive.js").GdriveCredentials>;
+export declare function pushIndexObject(dataDir: string, kind: "meta" | "blob", body: Buffer, preferred?: BackendName, options?: {
+    signal?: AbortSignal;
+    maxBytesPerSecond?: number;
+    onProgress?: (bytes: number) => void;
+}): Promise<void>;
+/** Publishes a large sealed index without reading the whole ciphertext back
+ * into the JS heap. The caller has already atomically committed this file. */
+export declare function pushIndexFile(dataDir: string, kind: "meta" | "blob", path: string, preferred?: BackendName, options?: {
+    signal?: AbortSignal;
+    maxBytesPerSecond?: number;
+    onProgress?: (bytes: number) => void;
+}): Promise<void>;
+export declare function pullIndexObject(dataDir: string, kind: "meta" | "blob", preferred?: BackendName, options?: {
+    signal?: AbortSignal;
+    renewToken?: boolean;
+    maxBytesPerSecond?: number;
+    onProgress?: (bytes: number) => void;
+}): Promise<Buffer | null>;
+export declare function pushTeamIndexObject(dataDir: string, spaceKey: string, kind: "meta" | "blob", body: Buffer, preferred?: BackendName, options?: {
+    signal?: AbortSignal;
+    maxBytesPerSecond?: number;
+    onProgress?: (bytes: number) => void;
+}): Promise<void>;
+export declare function pullTeamIndexObject(dataDir: string, spaceKey: string, kind: "meta" | "blob", preferred?: BackendName, options?: {
+    signal?: AbortSignal;
+    maxBytesPerSecond?: number;
+    onProgress?: (bytes: number) => void;
+}): Promise<Buffer | null>;
+/**
+ * A committed index generation is an immutable pair.  The durable receipt has
+ * no signed URLs: those are short-lived bearer capabilities and must never be
+ * copied into the publication ledger.  `ManagedIndexHead` carries the same
+ * receipt plus transient download leases returned by one `/head` request.
+ */
+export type ManagedIndexCoverage = Record<string, string>;
+export type ManagedIndexObjectReceipt = {
+    objectKey: string;
+    bytes: number;
+    sha256: string;
+};
+export type ManagedIndexReceipt = {
+    revision: number;
+    generationId: string;
+    blob: ManagedIndexObjectReceipt;
+    meta: ManagedIndexObjectReceipt;
+    coverageJson: ManagedIndexCoverage;
+    membershipVersion?: number;
+    committedAt: string;
+};
+export type ManagedIndexDownloadLease = {
+    url: string;
+    method?: string;
+    headers?: Record<string, string>;
+};
+export type ManagedIndexHead = {
+    receipt: ManagedIndexReceipt;
+    downloads: {
+        blob: ManagedIndexDownloadLease;
+        meta: ManagedIndexDownloadLease;
+    };
+};
+export type ManagedIndexV2Unsupported = {
+    status: "unsupported";
+    reason: "endpoint_unsupported";
+};
+export type ManagedIndexV2HeadResult = ManagedIndexV2Unsupported | {
+    status: "ok";
+    head: ManagedIndexHead | null;
+};
+export type ManagedIndexV2Snapshot = {
+    receipt: ManagedIndexReceipt;
+    /** Transient leases used for this exact snapshot; never persist this field. */
+    head: ManagedIndexHead;
+    envelope: Envelope;
+    ciphertext: Buffer;
+};
+/** Only native current-head snapshots can identify a derived source-facts cache.
+ * The identity contains no lease or permission and is independently copied. */
+export declare function teamSnapshotCacheIdentity(snapshot: ManagedIndexV2Snapshot): TeamIndexCacheIdentity | undefined;
+export type ManagedIndexV2SnapshotResult = ManagedIndexV2Unsupported | {
+    status: "ok";
+    snapshot: ManagedIndexV2Snapshot | null;
+};
+export type ManagedIndexV2PublishResult = ManagedIndexV2Unsupported | {
+    status: "conflict";
+    head: ManagedIndexHead | null;
+} | {
+    status: "committed";
+    receipt: ManagedIndexReceipt;
+    /** Transient post-commit head; its signed URLs must not be persisted. */
+    head: ManagedIndexHead;
+    /** Both immutable objects were fetched and hash-checked after commit. */
+    verifiedReadBack: true;
+    envelope: Envelope;
+};
+export type ManagedIndexV2PublishInput = {
+    expectedRevision: number;
+    coverageJson: ManagedIndexCoverage;
+    envelope: Envelope;
+    ciphertext: Buffer | {
+        path: string;
+    };
+    expectedMembershipVersion?: number;
+};
+export declare const INDEX_REVISION_CONFLICT_REMOTE_CODE: "INDEX_REVISION_CONFLICT";
+/** The hosted v2 finalizer currently uses one S3 CopyObject (<5 GiB). */
+export declare const MAX_MANAGED_INDEX_V2_BLOB_BYTES: number;
+export declare function headIndexGenerationV2(dataDir: string, preferred?: BackendName, options?: {
+    signal?: AbortSignal;
+    renewToken?: boolean;
+}): Promise<ManagedIndexV2HeadResult>;
+export declare function headTeamIndexGenerationV2(dataDir: string, spaceKey: string, preferred?: BackendName, options?: {
+    signal?: AbortSignal;
+    renewToken?: boolean;
+}): Promise<ManagedIndexV2HeadResult>;
+export declare function publishIndexGenerationV2(dataDir: string, input: Omit<ManagedIndexV2PublishInput, "expectedMembershipVersion">, preferred?: BackendName, options?: {
+    signal?: AbortSignal;
+    maxBytesPerSecond?: number;
+    onProgress?: (bytes: number) => void;
+}): Promise<ManagedIndexV2PublishResult>;
+export declare function publishTeamIndexGenerationV2(dataDir: string, spaceKey: string, input: ManagedIndexV2PublishInput & {
+    expectedMembershipVersion: number;
+}, preferred?: BackendName, options?: {
+    signal?: AbortSignal;
+    maxBytesPerSecond?: number;
+    onProgress?: (bytes: number) => void;
+}): Promise<ManagedIndexV2PublishResult>;
+export declare function pullIndexGenerationV2(dataDir: string, preferred?: BackendName, options?: {
+    signal?: AbortSignal;
+    renewToken?: boolean;
+    maxBytesPerSecond?: number;
+    onProgress?: (bytes: number) => void;
+    maxBytes?: number;
+}): Promise<ManagedIndexV2SnapshotResult>;
+export declare function pullTeamIndexGenerationV2(dataDir: string, spaceKey: string, preferred?: BackendName, options?: {
+    signal?: AbortSignal;
+    renewToken?: boolean;
+    maxBytesPerSecond?: number;
+    onProgress?: (bytes: number) => void;
+    maxBytes?: number;
+}): Promise<ManagedIndexV2SnapshotResult>;
+export declare function listCloudArchives(dataDir: string, preferred?: BackendName, options?: {
+    signal?: AbortSignal;
+    renewToken?: boolean;
+    token?: string;
+}): Promise<CloudArchiveList>;
+/**
+ * Cheap first-run question: does this signed-in account already preserve any
+ * archive? It deliberately fetches only the first cursor page instead of using
+ * `listCloudArchives`, because setup needs a branch, not a thousand-row index.
+ * Older control planes fall back to their capped flat listing.
+ */
+export declare function hasCloudArchives(dataDir: string, preferred?: BackendName): Promise<boolean>;
 /**
  * Really deletes one stored object from managed storage.
  *
@@ -336,7 +1044,22 @@ export declare function listCloudArchives(dataDir: string, preferred?: BackendNa
  * "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>;
+/** One account/token/device snapshot shared by every object in one destructive
+ * managed operation. It is intentionally not serialisable or returned by an
+ * API: the token remains inside this process. */
+export type ManagedDeleteContext = {
+    authGeneration: string | null;
+    token: string;
+    machine: MachineCredential | null;
+};
+export declare function managedDeleteContext(dataDir: string, preferred?: BackendName, options?: {
+    expectedAuthGeneration?: string | null;
+    signal?: AbortSignal;
+}): Promise<ManagedDeleteContext>;
+export declare function deleteCloudArchive(dataDir: string, vaultRef: string, preferred?: BackendName, options?: {
+    context?: ManagedDeleteContext;
+    signal?: AbortSignal;
+}): Promise<void>;
 export type DownloadLease = {
     vault_ref: string;
     bytes: number;
@@ -349,14 +1072,26 @@ export type DownloadLease = {
     };
     vended?: VendedCredential;
 };
+/** Immutable native lease identity only; it does not authenticate a partial
+ * object. Range callers still need a trusted envelope and chunk AEAD. */
+export type PersonalRangeDescriptor = Readonly<{
+    vaultRef: string;
+    bytes: number;
+    ciphertextSha256: string;
+}>;
 /**
  * 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.
+ * (see sealkeep-crypto/chunk-access). Only the presigned-URL lease shape
+ * supports ranges today. A range request never falls back to a whole object:
+ * neither an unsupported lease nor a storage server's 200 can spend an
+ * unbounded amount of memory/bandwidth on a small search or metadata read.
  */
-export declare function pullCiphertextRange(dataDir: string, vaultRef: string, storedOffset: number, storedLength: number, preferred?: BackendName): Promise<Buffer>;
+export declare function pullCiphertextRange(dataDir: string, vaultRef: string, storedOffset: number, storedLength: number, preferred?: BackendName, options?: BackgroundObjectReadOptions & {
+    maxBytes?: number;
+    onDescriptor?: (descriptor: PersonalRangeDescriptor) => void | Promise<void>;
+}): 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
@@ -365,32 +1100,75 @@ export declare function pullCiphertextRange(dataDir: string, vaultRef: string, s
  * 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<{
+export declare function statCiphertext(dataDir: string, vaultRef: string, preferred?: BackendName, options?: {
+    signal?: AbortSignal;
+    allowIncomplete?: boolean;
+}): Promise<{
     exists: boolean;
     bytes: number;
+    incompleteUpload?: IncompleteUpload;
 }>;
-export declare function pullCiphertext(dataDir: string, vaultRef: string, preferred?: BackendName): Promise<{
+export declare function pullCiphertextStream(dataDir: string, vaultRef: string, preferred?: BackendName, options?: BackgroundObjectReadOptions & {
+    unframe?: boolean;
+    maxBytes?: number;
+}): Promise<ByteStream>;
+export declare function pullCiphertext(dataDir: string, vaultRef: string, preferred?: BackendName, options?: {
+    signal?: AbortSignal;
+}): Promise<{
     ciphertext: Buffer;
     bytes: number;
 }>;
+export declare function frameObjectHeader(envelope: unknown): Buffer;
 export declare function frameObject(envelope: unknown, ciphertext: Buffer): Buffer;
 export declare function unframeObject(blob: Buffer): {
     envelope: any | null;
     ciphertext: Buffer;
 };
+/** Every managed reference `vaultRef` occupies, so a caller can pull the raw parts. */
+export declare function managedArchiveParts(dataDir: string, vaultRef: string, preferred?: BackendName): Promise<{
+    chunked: boolean;
+    refs: string[];
+}>;
 /**
- * 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.
+ * `unlock` is a phrase, or a recipient's private key — the second is how an
+ * organisation reads what a colleague sealed without anybody sharing a vault
+ * phrase, which is the only workable shape for a team.
  */
-export declare function openFromCloud(dataDir: string, vaultRef: string, destination: string, rawPhrase: string, preferred?: BackendName): Promise<{
+export declare function openFromCloud(dataDir: string, vaultRef: string, destination: string, unlock: string | {
+    privateKey: string;
+}, preferred?: BackendName): Promise<{
     output: string;
     bytes: number;
 }>;
+/**
+ * Tells the account's security feed what the local scanner found.
+ *
+ * The scan itself happens on this machine, on the plaintext, because this is
+ * the only place the plaintext exists — the plane holds ciphertext and could
+ * not scan it if it wanted to. What travels is the rule that matched, how
+ * often, this machine, and the archive: never the matched text, never the
+ * surrounding line, never the project name. A leak report that repeated the
+ * leak would be a second leak, and one sent to a server that was designed
+ * never to see the first would be worse than that.
+ *
+ * Best-effort by construction. An account that is not on a team plan answers
+ * 402 and we say nothing; a network failure loses a report, not a seal. The
+ * one thing this must never do is prevent an archive from being sealed.
+ */
+export declare function reportSecurityFindings(dataDir: string, input: {
+    vaultRef?: string;
+    findings: {
+        kind: string;
+        severity: "high" | "medium";
+    }[];
+}, preferred?: BackendName): Promise<{
+    reported: number;
+}>;
+/** What the company's own rules say, for machines to apply before sealing. */
+export declare function securityPolicy(dataDir: string, preferred?: BackendName): Promise<{
+    blockOnHigh: boolean;
+    rules: unknown[];
+} | null>;
 export type ArchiveCheck = {
     vaultRef: string;
     bytes: number;
@@ -429,6 +1207,38 @@ export declare function verifyArchives(dataDir: string, options?: {
     limit?: number;
     onProgress?: (check: ArchiveCheck) => void;
 }, preferred?: BackendName): Promise<ArchiveCheck[]>;
+export type FramedArchiveUpload = {
+    vaultRef: string;
+    envelope: Envelope;
+    ciphertextPath: string;
+    ciphertextSha256: string;
+    ciphertextBytes: number;
+};
+/**
+ * Store one already-sealed archive under an explicit managed-storage ref.
+ *
+ * Unlike `pushArchive`, this deliberately does not update a vault record.  It
+ * is the narrow primitive used by the team-history backfill: the original
+ * private record and every one of its copies remain untouched while a second,
+ * membership-wrapped object is uploaded, read back, and hash verified.  The
+ * caller may publish a team grant only after `durable` is true.
+ */
+export declare function pushFramedArchive(dataDir: string, input: FramedArchiveUpload, preferred?: BackendName, options?: {
+    signal?: AbortSignal;
+    incompleteUpload?: IncompleteUpload;
+    onProgress?: (bytes: number) => void;
+    onYield?: () => void | Promise<void>;
+    maxBytesPerSecond?: number;
+    paceNow?: () => number;
+    paceSleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}): Promise<PushResult>;
 export declare function pushArchive(dataDir: string, archiveId: string, preferred?: BackendName, options?: {
     signal?: AbortSignal;
+    ciphertextPath?: string;
+    onProgress?: (bytes: number) => void;
+    onYield?: () => void | Promise<void>;
+    maxBytesPerSecond?: number;
+    paceNow?: () => number;
+    paceSleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
 }): Promise<PushResult>;
+export {};