sealkeep 0.8.1 → 0.11.0

package/dist/src/team-index-cache.d.ts

@@ -0,0 +1,16 @@
+import type { ManagedIndexReceipt } from "./cloud.js";
+/** Ciphertext transport cache only. A hit is never membership or index-semantic proof. */
+export type TeamIndexCacheIdentity = {
+    origin: string;
+    accountId: number;
+    vaultId: string;
+    spaceKey: string;
+    receipt: ManagedIndexReceipt;
+};
+export declare const TEAM_INDEX_CACHE_BYTES: number;
+export declare function readTeamIndexCache(dataDir: string, identity: TeamIndexCacheIdentity, maxBytes?: number): Promise<{
+    meta: Buffer;
+    ciphertext: Buffer;
+} | null>;
+/** Installs one verified encrypted pair atomically; the previous version survives interrupted refreshes. */
+export declare function writeTeamIndexCache(dataDir: string, identity: TeamIndexCacheIdentity, meta: Buffer, ciphertext: Buffer): Promise<void>;

package/dist/src/team-index-cache.js

@@ -0,0 +1,152 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { mkdir, open, readdir, rename, stat, unlink } from "node:fs/promises";
+import { join } from "node:path";
+export const TEAM_INDEX_CACHE_BYTES = 256 * 1024 * 1024;
+const MAX_ENTRIES = 32;
+const NAME = /^[a-f0-9]{64}\.checkpoint$/;
+const PARTIAL = /^\.(\d+)\.([a-f0-9-]{36})\.partial$/;
+const activePartials = new Set();
+const directory = (dataDir) => join(dataDir, "index", "team-generation-cache");
+const digest = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function cacheName(identity) {
+    const { receipt } = identity;
+    // No leases, tokens, key material or decoded index data are persisted. Include
+    // the complete immutable head, not merely a timestamp or an object basename.
+    const key = JSON.stringify([
+        "sealkeep-team-generation-cache-v1",
+        identity.origin, identity.accountId, identity.vaultId, identity.spaceKey,
+        receipt.membershipVersion, receipt.revision, receipt.generationId,
+        receipt.blob.objectKey, receipt.blob.bytes, receipt.blob.sha256,
+        receipt.meta.objectKey, receipt.meta.bytes, receipt.meta.sha256,
+        Object.entries(receipt.coverageJson).sort(([a], [b]) => a.localeCompare(b)), receipt.committedAt,
+    ]);
+    return `${createHash("sha256").update(key).digest("hex")}.checkpoint`;
+}
+function expectedBytes(identity) {
+    return identity.receipt.meta.bytes + identity.receipt.blob.bytes;
+}
+function verified(identity, meta, ciphertext) {
+    return meta.length === identity.receipt.meta.bytes && ciphertext.length === identity.receipt.blob.bytes
+        && digest(meta) === identity.receipt.meta.sha256 && digest(ciphertext) === identity.receipt.blob.sha256;
+}
+async function removeAbandonedPartials(dataDir) {
+    const dir = directory(dataDir);
+    for (const name of await readdir(dir).catch(() => [])) {
+        const match = PARTIAL.exec(name);
+        if (!match)
+            continue;
+        const path = join(dir, name);
+        const pid = Number(match[1]);
+        if (!Number.isSafeInteger(pid) || pid <= 0 || activePartials.has(path))
+            continue;
+        let alive = pid === process.pid;
+        if (!alive) {
+            try {
+                process.kill(pid, 0);
+                alive = true;
+            }
+            catch (error) {
+                alive = error.code !== "ESRCH";
+            }
+        }
+        // Same-PID leftovers cannot be ours unless present in activePartials. Other
+        // living processes retain their scratch files until their writer finishes.
+        if (!alive || pid === process.pid)
+            await unlink(path).catch(() => undefined);
+    }
+}
+export async function readTeamIndexCache(dataDir, identity, maxBytes = TEAM_INDEX_CACHE_BYTES) {
+    const size = expectedBytes(identity);
+    if (!Number.isSafeInteger(size) || size < 0 || size > Math.min(maxBytes, TEAM_INDEX_CACHE_BYTES))
+        return null;
+    const path = join(directory(dataDir), cacheName(identity));
+    try {
+        await removeAbandonedPartials(dataDir);
+        // An opened descriptor pins the inode while another reader evicts old files.
+        // Copying bytes into this request's Buffer also isolates later file changes.
+        const handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+        try {
+            const before = await handle.stat();
+            if (!before.isFile() || before.size !== size)
+                return null;
+            const body = Buffer.alloc(size);
+            let at = 0;
+            while (at < size) {
+                const read = await handle.read(body, at, size - at, at);
+                if (!read.bytesRead)
+                    return null;
+                at += read.bytesRead;
+            }
+            const after = await handle.stat();
+            if (after.size !== size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs)
+                return null;
+            const meta = body.subarray(0, identity.receipt.meta.bytes);
+            const ciphertext = body.subarray(identity.receipt.meta.bytes);
+            return verified(identity, meta, ciphertext) ? { meta, ciphertext } : null;
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch {
+        return null;
+    }
+}
+async function evict(dataDir, keep) {
+    const dir = directory(dataDir);
+    const rows = await Promise.all((await readdir(dir)).filter((name) => NAME.test(name)).map(async (name) => {
+        const entry = await stat(join(dir, name)).catch(() => null);
+        return entry?.isFile() ? { name, bytes: entry.size, at: entry.mtimeMs } : null;
+    }));
+    const ordered = rows.filter((row) => row !== null)
+        .sort((a, b) => Number(b.name === keep) - Number(a.name === keep) || b.at - a.at || a.name.localeCompare(b.name));
+    let bytes = 0;
+    let count = 0;
+    for (const row of ordered) {
+        bytes += row.bytes;
+        count += 1;
+        if (bytes > TEAM_INDEX_CACHE_BYTES || count > MAX_ENTRIES)
+            await unlink(join(dir, row.name)).catch(() => undefined);
+    }
+}
+/** Installs one verified encrypted pair atomically; the previous version survives interrupted refreshes. */
+export async function writeTeamIndexCache(dataDir, identity, meta, ciphertext) {
+    const size = expectedBytes(identity);
+    if (size > TEAM_INDEX_CACHE_BYTES || !verified(identity, meta, ciphertext))
+        return;
+    const dir = directory(dataDir);
+    const name = cacheName(identity);
+    const path = join(dir, name);
+    const temporary = join(dir, `.${process.pid}.${randomUUID()}.partial`);
+    try {
+        await mkdir(dir, { recursive: true, mode: 0o700 });
+        await removeAbandonedPartials(dataDir);
+        activePartials.add(temporary);
+        const handle = await open(temporary, "wx", 0o600);
+        try {
+            await handle.writeFile(meta);
+            await handle.writeFile(ciphertext);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        // Replacement is safe even when the previous same-key cache was corrupt:
+        // readers already hold an inode or an independent verified Buffer.
+        await rename(temporary, path);
+        const directoryHandle = await open(dir, "r").catch(() => null);
+        try {
+            await directoryHandle?.sync().catch(() => undefined);
+        }
+        finally {
+            await directoryHandle?.close();
+        }
+        await evict(dataDir, name);
+    }
+    catch { /* Derived cache failure must not fail an otherwise verified read. */ }
+    finally {
+        activePartials.delete(temporary);
+        await unlink(temporary).catch(() => undefined);
+    }
+}

package/dist/src/team-offboarding.d.ts

@@ -0,0 +1,38 @@
+import type { BackendName } from "./secrets.js";
+/** Only an explicitly bound team scope may enter a departure handoff. */
+export type TeamOffboardingScope = {
+    project: string;
+    projectKey?: string;
+    spaceKey: string;
+    targetAccountId: number;
+    /** Invitation captures share the machinery, never a departure journal. */
+    transition?: "invitation";
+    targetPublicKey?: string;
+};
+/**
+ * Pin already-shared history before the membership commit. Only ciphertext,
+ * wrapped keys and opaque references survive a process exit; transcript and
+ * searchable index plaintext are never written to the durable journal.
+ */
+export declare function prepareTeamOffboarding(dataDir: string, scope: TeamOffboardingScope, phrase: string, preferred?: BackendName): Promise<{
+    membershipVersion: number;
+    keyVersion?: number;
+    indexRevision: number;
+    archiveRefs: string[];
+}>;
+/**
+ * Resume after the authoritative removal, including a lost removal response.
+ * The surviving uploader owns new immutable aliases; old author-owned grants
+ * and old membership receipts are never promoted to the new epoch.
+ */
+export declare function completeTeamOffboarding(dataDir: string, scope: TeamOffboardingScope, phrase: string, preferred?: BackendName): Promise<void>;
+export declare function prepareTeamInvitationHistory(dataDir: string, scope: Omit<TeamOffboardingScope, "transition"> & {
+    targetPublicKey: string;
+}, phrase: string, preferred?: BackendName): Promise<{
+    membershipVersion: number;
+    keyVersion?: number;
+    indexRevision: number;
+    archiveRefs: string[];
+}>;
+/** Owner-side background continuation; pending invitations grant no access. */
+export declare function reconcileTeamInvitationHandoffs(dataDir: string, phrase: string, preferred?: BackendName): Promise<number>;