sealkeep 0.9.0 → 0.11.0

package/dist/src/team-publication-policy.d.ts

@@ -0,0 +1,20 @@
+import { type ManagedIndexReceipt } from "./cloud.js";
+export declare const TEAM_PUBLICATION_POLICY = 1;
+type Identity = {
+    origin: string;
+    accountId: number;
+    vaultId: string;
+};
+export type TeamPublicationPolicyAttempt = Identity & {
+    spaceKey: string;
+    membershipVersion: number;
+    authGeneration: string | null;
+};
+export declare function teamPublicationPolicyCurrent(dataDir: string, attempt: TeamPublicationPolicyAttempt): Promise<boolean>;
+/** Capture before native publication; an executable upgrade never fabricates a receipt. */
+export declare function beginTeamPublicationPolicy(dataDir: string, spaceKey: string, membershipVersion: number, signal?: AbortSignal): Promise<TeamPublicationPolicyAttempt>;
+/** Called only after native CAS read-back and exact local publication obligations succeed. */
+export declare function completeTeamPublicationPolicy(dataDir: string, attempt: TeamPublicationPolicyAttempt, receipt: ManagedIndexReceipt, expectedCoverage: Readonly<Record<string, string>>, requiredRefs: Iterable<string>, signal?: AbortSignal): Promise<void>;
+/** Runs on the independent indexing lane. Failed checks remain pending for its bounded retry. */
+export declare function teamPublicationPolicyNeedsUpgrade(dataDir: string): Promise<boolean>;
+export {};

package/dist/src/team-publication-policy.js

@@ -0,0 +1,140 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, open, readFile, rename, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { accountStatus, cloudAuthGeneration, cloudUrl, getTeamRoster } from "./cloud.js";
+import { readConfig } from "./vault.js";
+import { withProgressDeadline } from "./progress-deadline.js";
+import { fail } from "./errors.js";
+// Separate from extraction and per-archive retention ledger versions. A code
+// correction to scoped catalog selection must also reach fully indexed vaults.
+export const TEAM_PUBLICATION_POLICY = 1;
+const directory = (dataDir) => join(dataDir, "index", "team-publication-policy");
+const hash = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+const key = (attempt) => hash([
+    attempt.origin, attempt.accountId, attempt.vaultId, attempt.spaceKey, attempt.membershipVersion,
+]);
+const pathFor = (dataDir, attempt) => join(directory(dataDir), `${key(attempt)}.json`);
+const coverageDigest = (coverage) => hash(Object.entries(coverage).sort(([a], [b]) => a.localeCompare(b)));
+async function identity(dataDir, signal) {
+    const origin = cloudUrl();
+    const authGeneration = await cloudAuthGeneration(dataDir);
+    const vaultId = (await readConfig(dataDir)).vaultId;
+    const account = await accountStatus(dataDir, undefined, { signal, renewToken: false });
+    if (!Number.isSafeInteger(account.id) || account.id <= 0)
+        fail("cloud_account_unavailable", "Cannot identify the current publication account");
+    if (cloudUrl() !== origin || await cloudAuthGeneration(dataDir) !== authGeneration
+        || (await readConfig(dataDir)).vaultId !== vaultId)
+        fail("cloud_account_unavailable", "The publication account changed; retry safely");
+    return { origin, accountId: account.id, vaultId, authGeneration };
+}
+export async function teamPublicationPolicyCurrent(dataDir, attempt) {
+    try {
+        const raw = await readFile(pathFor(dataDir, attempt), "utf8");
+        if (raw.length > 16_384)
+            return false;
+        const value = JSON.parse(raw);
+        return value.version === 1 && value.policy === TEAM_PUBLICATION_POLICY && value.scope === key(attempt)
+            && value.state === "complete" && Number.isSafeInteger(value.revision) && value.revision > 0
+            && typeof value.generationId === "string" && /^[a-f0-9]{64}$/.test(value.coverageDigest)
+            && /^[a-f0-9]{64}$/.test(value.ciphertextSha256);
+    }
+    catch {
+        return false;
+    }
+}
+async function ensurePending(dataDir, attempt) {
+    if (await teamPublicationPolicyCurrent(dataDir, attempt))
+        return;
+    await mkdir(directory(dataDir), { recursive: true, mode: 0o700 });
+    let file;
+    try {
+        file = await open(pathFor(dataDir, attempt), "wx", 0o600);
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            return;
+        throw error;
+    }
+    try {
+        await file.writeFile(JSON.stringify({ version: 1, policy: TEAM_PUBLICATION_POLICY, scope: key(attempt), state: "pending" }) + "\n");
+        await file.sync();
+    }
+    finally {
+        await file.close();
+    }
+}
+/** Capture before native publication; an executable upgrade never fabricates a receipt. */
+export async function beginTeamPublicationPolicy(dataDir, spaceKey, membershipVersion, signal) {
+    return withProgressDeadline("Preparing shared index policy migration", 15_000, signal, async (bounded) => {
+        const attempt = { ...await identity(dataDir, bounded), spaceKey, membershipVersion };
+        await ensurePending(dataDir, attempt);
+        return attempt;
+    });
+}
+/** Called only after native CAS read-back and exact local publication obligations succeed. */
+export async function completeTeamPublicationPolicy(dataDir, attempt, receipt, expectedCoverage, requiredRefs, signal) {
+    if (receipt.membershipVersion !== attempt.membershipVersion
+        || coverageDigest(receipt.coverageJson) !== coverageDigest(expectedCoverage)
+        || [...requiredRefs].some((ref) => !Object.hasOwn(receipt.coverageJson, ref))) {
+        fail("ciphertext_integrity_failed", "The current shared index policy has not covered its required grants");
+    }
+    await withProgressDeadline("Confirming shared index policy migration", 15_000, signal, async (bounded) => {
+        const current = await identity(dataDir, bounded);
+        const roster = await getTeamRoster(dataDir, attempt.spaceKey, undefined, { signal: bounded, renewToken: false });
+        if (key({ ...current, spaceKey: attempt.spaceKey, membershipVersion: roster.membership_version }) !== key(attempt)
+            || current.authGeneration !== attempt.authGeneration || await cloudAuthGeneration(dataDir) !== attempt.authGeneration) {
+            fail("team_state_changed", "Shared index policy migration changed scope; retry in the current account and team");
+        }
+        await mkdir(directory(dataDir), { recursive: true, mode: 0o700 });
+        const target = pathFor(dataDir, attempt);
+        const temporary = `${target}.${randomUUID()}.tmp`;
+        try {
+            const file = await open(temporary, "wx", 0o600);
+            try {
+                await file.writeFile(JSON.stringify({ version: 1, policy: TEAM_PUBLICATION_POLICY, scope: key(attempt), state: "complete",
+                    revision: receipt.revision, generationId: receipt.generationId, coverageDigest: coverageDigest(receipt.coverageJson),
+                    ciphertextSha256: receipt.blob.sha256, committedAt: receipt.committedAt }) + "\n");
+                await file.sync();
+            }
+            finally {
+                await file.close();
+            }
+            bounded.throwIfAborted();
+            if (cloudUrl() !== attempt.origin || await cloudAuthGeneration(dataDir) !== attempt.authGeneration
+                || (await readConfig(dataDir)).vaultId !== attempt.vaultId) {
+                fail("cloud_account_unavailable", "Publication sign-in changed before its policy receipt was saved");
+            }
+            await rename(temporary, target);
+        }
+        finally {
+            await rm(temporary, { force: true }).catch(() => undefined);
+        }
+    });
+}
+/** Runs on the independent indexing lane. Failed checks remain pending for its bounded retry. */
+export async function teamPublicationPolicyNeedsUpgrade(dataDir) {
+    const config = await readConfig(dataDir);
+    const spaces = [...new Set(Object.values(config.teamSpaces ?? {}).map((binding) => binding.spaceKey))];
+    if (!spaces.length)
+        return false;
+    try {
+        return await withProgressDeadline("Checking shared index publication policy", 15_000, undefined, async (signal) => {
+            const current = await identity(dataDir, signal);
+            let pending = false;
+            for (const spaceKey of spaces) {
+                const roster = await getTeamRoster(dataDir, spaceKey, undefined, { signal, renewToken: false });
+                const attempt = { ...current, spaceKey, membershipVersion: roster.membership_version };
+                if (!await teamPublicationPolicyCurrent(dataDir, attempt)) {
+                    await ensurePending(dataDir, attempt);
+                    pending = true;
+                }
+            }
+            if (await cloudAuthGeneration(dataDir) !== current.authGeneration || cloudUrl() !== current.origin)
+                return true;
+            return pending;
+        });
+    }
+    catch {
+        return true;
+    }
+}

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

@@ -0,0 +1,68 @@
+/**
+ * Push wake-ups for encrypted cross-account presence.
+ *
+ * REST remains the durable append log and cursor catch-up path. The daemon
+ * keeps one Socket.IO connection per machine, multiplexes every locally bound
+ * opaque team-space id over it, and writes received ciphertext rows to a
+ * bounded local inbox. Agent hooks read that inbox at tool boundaries, so a
+ * busy team does not turn "is anyone already touching this?" into continuous
+ * HTTP polling.
+ *
+ * No user setting is involved: the realtime origin/path are derived from the
+ * same hosted API URL the signed-in client already uses, and the bearer stays
+ * in the native keystore/in-memory Socket.IO handshake.
+ */
+import { type TeamPresenceRow } from "./cloud.js";
+import type { BackendName } from "./secrets.js";
+export type TeamRealtimeStatus = {
+    version: 1;
+    connected: boolean;
+    updatedAt: string;
+    subscribedSpaces: string[];
+    /** Changes on every successful connection, so hooks know to run one durable catch-up. */
+    connectionId?: string;
+    lastError?: string;
+};
+export type TeamRealtimeListener = {
+    /** Resolves after every space present at startup has an acknowledged subscription. */
+    ready: Promise<void>;
+    refresh(): Promise<void>;
+    close(): Promise<void>;
+    status(): TeamRealtimeStatus;
+};
+export type TeamRealtimeRows = {
+    rows: TeamPresenceRow[];
+    cursor: number;
+    gap: boolean;
+};
+/**
+ * Cache one validated wire row in its own immutable file. This is O(event),
+ * not O(all spaces × inbox size), and atomic hard links make overlapping daemon handoffs
+ * converge on the first complete row instead of overwriting one another.
+ */
+export declare function cacheRealtimeTeamPresence(dataDir: string, spaceKey: string, value: unknown): Promise<boolean>;
+/** Read only local ciphertext rows newer than a durable cursor. */
+export declare function readRealtimeTeamPresence(dataDir: string, spaceKey: string, after: number): Promise<TeamRealtimeRows>;
+export declare function teamRealtimeChannel(routeKey: string): string;
+export declare function teamRealtimeEndpoint(env?: NodeJS.ProcessEnv): {
+    origin: string;
+    path: string;
+};
+export declare function readTeamRealtimeStatus(dataDir: string): Promise<TeamRealtimeStatus | null>;
+export declare function teamRealtimeStatusHealthy(status: TeamRealtimeStatus | null, spaceKey: string, options?: {
+    now?: number;
+    maxAgeMs?: number;
+}): boolean;
+export declare function teamRealtimeHealthy(dataDir: string, spaceKey: string, options?: {
+    now?: number;
+    maxAgeMs?: number;
+}): Promise<boolean>;
+/**
+ * Start the package-owned machine listener. It is deliberately fail-open:
+ * missing sign-in, no team spaces, network failures, and auth expiry leave the
+ * durable REST path intact and never stop the preservation daemon.
+ */
+export declare function startTeamRealtime(dataDir: string, options?: {
+    preferred?: BackendName;
+    refreshMs?: number;
+}): Promise<TeamRealtimeListener>;