sealkeep 0.8.1 → 0.11.0

package/dist/src/team-presence.js

@@ -0,0 +1,904 @@
+/**
+ * Cross-account live presence.
+ *
+ * The hosted plane sees an opaque space id, sender/sequence replay guards and
+ * ciphertext. A single random feed key makes every event O(1): inviting a new
+ * member wraps that key once to their X25519 identity instead of copying every
+ * event once per teammate. Identity and feed private material are cached in the
+ * strongest OS keystore available and can be recovered on another machine from
+ * phrase-sealed server data.
+ */
+import { createHash, createHmac, createPublicKey, randomBytes } from "node:crypto";
+import { aeadCipher, aeadDecipher } from "../packages/sealkeep-crypto/src/aead.js";
+import { decryptArchive, encryptArchive, rawPublicKey, unwrapArchiveKey, wrapForKey, x25519PrivateKeyFromRaw, x25519PublicKeyFromRaw, zeroize, } from "../packages/sealkeep-crypto/src/index.js";
+import { cloudUrl, cloudToken, completeTeamAccessRequest, completeTeamProjectRequest, createTeamInvitation, createTeamSpace, frameObject, getTeamIdentity, getTeamMembership, listOutgoingTeamAccessRequests, listOutgoingTeamInvitations, listTeamMembers, listTeamProjectRequests, listTeamSpaces, pollTeamPresence, prepareTeamInvitation, publishTeamPresence, putTeamIdentity, recentTeamPresence, removeTeamMemberAndRotate, resolveTeamInvitee, unframeObject, } from "./cloud.js";
+import { fail, isSealkeepError } from "./errors.js";
+import { canonicalPhrase } from "./mnemonic.js";
+import { chooseBackend } from "./secrets.js";
+import { bindTeamSpace, readConfig, removeTeamProjectDraft, revokeTeamSpaceBindings, teamSpaceOf, unbindTeamSpace, updateTeamSpaceBindings, } from "./vault.js";
+import { readRealtimeTeamPresence } from "./team-realtime.js";
+import { withProgressDeadline } from "./progress-deadline.js";
+const SUITE = "chacha20-poly1305";
+const NONCE_BYTES = 12;
+const TAG_BYTES = 16;
+const SPACE_RE = /^[A-Za-z0-9_-]{43}$/;
+const PROJECT_KEY_RE = /^(?:g1|p1):[a-f0-9]{64}$/;
+const identityRef = (publicKey) => ({
+    service: "sealkeep-team-identity",
+    account: createHash("sha256").update(`${cloudUrl()}|${publicKey}`).digest("hex"),
+});
+const identityPointerRef = (vaultId) => ({
+    service: "sealkeep-team-identity-pointer",
+    account: createHash("sha256").update(`${cloudUrl()}|${vaultId}`).digest("hex"),
+});
+const feedRef = (spaceKey) => ({
+    service: "sealkeep-team-space",
+    account: createHash("sha256").update(`${cloudUrl()}|${spaceKey}`).digest("hex"),
+});
+// Public, domain-separated marker ID that the hosted workflow can recompute.
+// It classifies rotation markers; it is not an authentication credential.
+const bindingSender = (spaceKey) => createHmac("sha256", "sealkeep-team-binding").update(spaceKey).digest("hex").slice(0, 8);
+function deterministicIdentity(phrase) {
+    const privateRaw = createHash("sha256")
+        .update("sealkeep-team-identity:v1\0")
+        .update(canonicalPhrase(phrase), "utf8")
+        .digest();
+    const privateKey = x25519PrivateKeyFromRaw(privateRaw);
+    const publicKey = rawPublicKey(createPublicKey(privateKey)).toString("base64");
+    return { version: 1, publicKey, privateKey: privateRaw.toString("base64") };
+}
+function sealIdentity(secret, phrase) {
+    const { envelope, ciphertext } = encryptArchive(Buffer.from(JSON.stringify(secret)), {
+        recipients: [{ kind: "phrase", phrase: canonicalPhrase(phrase) }],
+        adapter: { agent: "sealkeep-team-identity", version: "1" },
+    });
+    return frameObject(envelope, ciphertext).toString("base64");
+}
+function openIdentity(identity, phrase) {
+    try {
+        const { envelope, ciphertext } = unframeObject(Buffer.from(identity.key_box, "base64"));
+        if (!envelope)
+            throw new Error("unframed identity");
+        const value = JSON.parse(decryptArchive(envelope, ciphertext, { phrase: canonicalPhrase(phrase) }).toString("utf8"));
+        const privateRaw = Buffer.from(value.privateKey, "base64");
+        const publicKey = rawPublicKey(createPublicKey(x25519PrivateKeyFromRaw(privateRaw))).toString("base64");
+        if (value.version !== 1 || publicKey !== identity.public_key || value.publicKey !== identity.public_key)
+            throw new Error("identity mismatch");
+        return value;
+    }
+    catch {
+        return fail("recovery_phrase_mismatch", "This recovery phrase cannot open the account's team identity. Team data was not changed.");
+    }
+}
+async function cacheIdentity(dataDir, secret, preferred) {
+    const backend = await chooseBackend(dataDir, preferred);
+    await backend.set(identityRef(secret.publicKey), JSON.stringify(secret));
+    await backend.set(identityPointerRef((await readConfig(dataDir)).vaultId), secret.publicKey);
+}
+async function cachedIdentity(dataDir, publicKey, preferred) {
+    const raw = await (await chooseBackend(dataDir, preferred)).get(identityRef(publicKey));
+    if (!raw)
+        return null;
+    try {
+        const value = JSON.parse(raw);
+        return value.version === 1 && value.publicKey === publicKey && Buffer.from(value.privateKey, "base64").length === 32 ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Called during visible team setup, or lazily on a newly signed-in machine. */
+export async function ensureTeamIdentity(dataDir, phrase, preferred) {
+    const backend = await chooseBackend(dataDir, preferred);
+    const pointer = await backend.get(identityPointerRef((await readConfig(dataDir)).vaultId));
+    if (pointer) {
+        const cached = await cachedIdentity(dataDir, pointer, preferred);
+        if (cached)
+            return cached;
+    }
+    const remote = await getTeamIdentity(dataDir, preferred);
+    if (remote?.public_key && remote.key_box) {
+        const cached = await cachedIdentity(dataDir, remote.public_key, preferred);
+        if (cached)
+            return cached;
+        const opened = openIdentity(remote, phrase);
+        await cacheIdentity(dataDir, opened, preferred);
+        return opened;
+    }
+    // Phrase-derived identity makes simultaneous first use on Mac and VPS settle
+    // on the same public key. The random feed keys remain random and wrapped.
+    const created = deterministicIdentity(phrase);
+    await putTeamIdentity(dataDir, { public_key: created.publicKey, key_box: sealIdentity(created, phrase) }, preferred);
+    const settled = await getTeamIdentity(dataDir, preferred);
+    const identity = settled?.public_key === created.publicKey ? created : settled ? openIdentity(settled, phrase) : created;
+    await cacheIdentity(dataDir, identity, preferred);
+    return identity;
+}
+async function cachedFeed(dataDir, spaceKey, preferred) {
+    const raw = await (await chooseBackend(dataDir, preferred)).get(feedRef(spaceKey));
+    if (!raw)
+        return null;
+    try {
+        const value = JSON.parse(raw);
+        return value.version === 1
+            && value.spaceKey === spaceKey
+            && Number.isSafeInteger(value.keyVersion) && value.keyVersion > 0
+            && Buffer.from(value.key, "base64").length === 32
+            && (value.realtimeKey === undefined || SPACE_RE.test(value.realtimeKey))
+            ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Legacy epoch one used the opaque space id directly; every rotation binds its version too. */
+function feedWrapContext(spaceKey, keyVersion) {
+    return keyVersion <= 1 ? spaceKey : `sealkeep-team-feed:v2\0${spaceKey}\0${keyVersion}`;
+}
+async function saveFeed(dataDir, value, preferred) {
+    const existing = await cachedFeed(dataDir, value.spaceKey, preferred);
+    if (existing && existing.keyVersion > value.keyVersion) {
+        return fail("internal", `Refusing to replace team key epoch ${existing.keyVersion} with older epoch ${value.keyVersion}`);
+    }
+    if (existing && existing.keyVersion === value.keyVersion && existing.key !== value.key) {
+        return fail("internal", `Team key epoch ${value.keyVersion} has conflicting key material`);
+    }
+    const settled = existing && existing.keyVersion === value.keyVersion
+        ? { ...existing, ...(value.realtimeKey ? { realtimeKey: value.realtimeKey } : {}) }
+        : value;
+    await (await chooseBackend(dataDir, preferred)).set(feedRef(value.spaceKey), JSON.stringify(settled));
+    return settled;
+}
+function wrapFeed(spaceKey, keyVersion, feedKey, publicKey) {
+    const raw = Buffer.from(publicKey, "base64");
+    if (raw.length !== 32)
+        fail("invalid_argument", "A team identity public key must be 32 bytes");
+    return JSON.stringify(wrapForKey(feedKey, x25519PublicKeyFromRaw(raw), SUITE, feedWrapContext(spaceKey, keyVersion), { nonce: randomBytes(NONCE_BYTES) }));
+}
+function unwrapFeed(spaceKey, member, identity) {
+    if (member.public_key !== identity.publicKey)
+        fail("forbidden", "This team membership belongs to a different account identity");
+    const privateRaw = Buffer.from(identity.privateKey, "base64");
+    try {
+        const wrapped = JSON.parse(member.wrapped_key);
+        const key = unwrapArchiveKey([wrapped], SUITE, feedWrapContext(spaceKey, member.key_version), {
+            privateKey: x25519PrivateKeyFromRaw(privateRaw),
+        });
+        try {
+            return {
+                version: 1, spaceKey, keyVersion: member.key_version, key: key.toString("base64"),
+                realtimeKey: SPACE_RE.test(member.realtime_key ?? "") ? member.realtime_key : spaceKey,
+            };
+        }
+        finally {
+            zeroize(key);
+        }
+    }
+    catch {
+        return fail("recipient_key_mismatch", "This account cannot open the team-space key. Ask the space owner to remove and invite the account again.");
+    }
+    finally {
+        zeroize(privateRaw);
+    }
+}
+/** Remove a revoked epoch key without exposing it to config or another process. */
+export async function forgetTeamSpaceFeed(dataDir, spaceKey, preferred) {
+    if (!SPACE_RE.test(spaceKey))
+        return;
+    const backend = await chooseBackend(dataDir, preferred);
+    await backend.delete(feedRef(spaceKey));
+}
+async function revokeLocalMembership(dataDir, spaceKey, preferred) {
+    await Promise.allSettled([
+        forgetTeamSpaceFeed(dataDir, spaceKey, preferred),
+        revokeTeamSpaceBindings(dataDir, spaceKey),
+    ]);
+}
+/** Fetch and unwrap the authoritative current epoch, never trusting a stale cache. */
+async function refreshFeed(dataDir, spaceKey, phrase, preferred, minimumVersion = 0) {
+    let member;
+    try {
+        member = await getTeamMembership(dataDir, spaceKey, preferred);
+    }
+    catch (error) {
+        if (isSealkeepError(error) && error.code === "team_membership_revoked") {
+            await revokeLocalMembership(dataDir, spaceKey, preferred);
+        }
+        throw error;
+    }
+    if (!member) {
+        await revokeLocalMembership(dataDir, spaceKey, preferred);
+        return fail("team_membership_revoked", "This account is no longer a member of that team space");
+    }
+    if (!Number.isSafeInteger(Number(member.key_version)) || Number(member.key_version) <= 0) {
+        return fail("internal", "Sealkeep Cloud returned an invalid team key epoch");
+    }
+    member.key_version = Number(member.key_version);
+    if (member.key_version < minimumVersion) {
+        return fail("team_state_changed", `Team space is at epoch ${member.key_version}, below observed epoch ${minimumVersion}`, { currentKeyVersion: member.key_version });
+    }
+    const existing = await cachedFeed(dataDir, spaceKey, preferred);
+    if (existing && existing.keyVersion > member.key_version) {
+        return fail("internal", `Sealkeep Cloud attempted to roll team key epoch ${existing.keyVersion} back to ${member.key_version}`);
+    }
+    let feed;
+    if (existing && existing.keyVersion === member.key_version) {
+        feed = {
+            ...existing,
+            realtimeKey: SPACE_RE.test(member.realtime_key ?? "") ? member.realtime_key : existing.realtimeKey ?? spaceKey,
+        };
+    }
+    else {
+        const identity = await ensureTeamIdentity(dataDir, phrase, preferred);
+        feed = unwrapFeed(spaceKey, member, identity);
+    }
+    feed = await saveFeed(dataDir, feed, preferred);
+    await updateTeamSpaceBindings(dataDir, spaceKey, {
+        keyVersion: feed.keyVersion,
+        realtimeKey: feed.realtimeKey ?? spaceKey,
+    });
+    return feed;
+}
+async function loadFeed(dataDir, spaceKey, phrase, preferred) {
+    const cached = await cachedFeed(dataDir, spaceKey, preferred);
+    if (cached)
+        return cached;
+    return refreshFeed(dataDir, spaceKey, phrase, preferred);
+}
+/**
+ * Reconcile one project's hosted epoch at a normal agent lifecycle boundary.
+ * Push remains the fast path; this authoritative read is the crash-safe path
+ * when a committed rotation's best-effort socket notice was lost.
+ */
+export async function reconcileProjectTeamSpace(dataDir, project, phrase, preferred, projectKey) {
+    const binding = teamSpaceOf(await readConfig(dataDir), project, projectKey);
+    if (!binding)
+        return null;
+    const feed = await refreshFeed(dataDir, binding.spaceKey, phrase, preferred);
+    return { keyVersion: feed.keyVersion, realtimeKey: feed.realtimeKey ?? binding.spaceKey };
+}
+export async function createProjectTeamSpace(dataDir, project, phrase, preferred, projectKey) {
+    if (!project.trim())
+        fail("invalid_argument", "Choose a project before enabling team mode");
+    const identity = await ensureTeamIdentity(dataDir, phrase, preferred);
+    const spaceKey = randomBytes(32).toString("base64url");
+    const realtimeKey = randomBytes(32).toString("base64url");
+    const key = randomBytes(32);
+    try {
+        const space = await createTeamSpace(dataDir, {
+            space_key: spaceKey,
+            wrapped_key: wrapFeed(spaceKey, 1, key, identity.publicKey),
+            realtime_key: realtimeKey,
+            project_name: project,
+        }, preferred);
+        const feed = {
+            version: 1, spaceKey, keyVersion: space.key_version || 1, key: key.toString("base64"),
+            realtimeKey: SPACE_RE.test(space.realtime_key ?? "") ? space.realtime_key : realtimeKey,
+        };
+        await saveFeed(dataDir, feed, preferred);
+        // Seed encrypted project metadata as part of the visible "enable Team mode"
+        // action. A newly installed second machine can now identify even a quiet
+        // space without copying config or asking the user for its opaque id.
+        const bindingEvent = {
+            project, kind: "note", line: "Team mode enabled", from: "Sealkeep",
+            sender: bindingSender(spaceKey),
+            seq: 0, at: new Date().toISOString(),
+            ...(projectKey ? { projectKey } : {}),
+        };
+        const ciphertext = encryptEvent(bindingEvent, spaceKey, feed);
+        // Do not report Team mode as enabled until its encrypted discovery seed is
+        // durable. Silently losing this row would strand a quiet project on a
+        // fresh machine. Normal setup already has a working authenticated plane;
+        // if that changes between the two writes, the visible action fails instead
+        // of leaving a false-success binding.
+        await publishTeamPresence(dataDir, spaceKey, {
+            sender: bindingEvent.sender, sequence: 0, key_version: feed.keyVersion, ciphertext,
+        }, preferred);
+        await bindTeamSpace(dataDir, project, {
+            spaceKey, role: "owner", keyVersion: feed.keyVersion, realtimeKey: feed.realtimeKey,
+        }, projectKey);
+        return { project, ...(projectKey ? { projectKey } : {}), spaceKey, role: "owner", keyVersion: feed.keyVersion, realtimeKey: feed.realtimeKey };
+    }
+    finally {
+        zeroize(key);
+    }
+}
+export async function joinProjectTeamSpace(dataDir, project, spaceKey, phrase, preferred, projectKey) {
+    if (!SPACE_RE.test(spaceKey))
+        fail("invalid_argument", "That team-space id is malformed");
+    let member = null;
+    try {
+        member = await getTeamMembership(dataDir, spaceKey, preferred);
+    }
+    catch (error) {
+        // A pending invitation is expected to have no membership yet; the
+        // structured revoked response is otherwise useful to callers.
+        if (!(isSealkeepError(error) && error.code === "team_membership_revoked"))
+            throw error;
+    }
+    // Joining a visible pending invitation is the invitee's explicit acceptance.
+    // The owner-side invite never creates membership; this compatibility path
+    // keeps the existing "join" action useful while routing through the new
+    // invitation acceptance endpoint.
+    if (!member) {
+        const invitation = (await (await import("./cloud.js")).listTeamInvitations(dataDir, preferred)).find((item) => item.space_key === spaceKey && item.status === "pending");
+        if (invitation)
+            member = await (await import("./cloud.js")).acceptTeamInvitation(dataDir, invitation.id, preferred);
+    }
+    if (!member)
+        return fail("forbidden", "This account has not been invited to that team space");
+    const feed = await refreshFeed(dataDir, spaceKey, phrase, preferred);
+    // Rejoining the same exact checkout refreshes membership, not folder consent.
+    // Never inherit confirmation from another binding key or hosted space.
+    const existing = teamSpaceOf(await readConfig(dataDir), project, projectKey);
+    const confirmed = existing?.spaceKey === spaceKey && existing.localConfirmed === true;
+    await bindTeamSpace(dataDir, project, {
+        spaceKey, role: member.role === "owner" ? "owner" : "member",
+        keyVersion: feed.keyVersion, realtimeKey: feed.realtimeKey ?? spaceKey,
+        ...(confirmed ? { localConfirmed: true, ...(existing.localProject ? { localProject: existing.localProject } : {}) } : {}),
+    }, projectKey);
+    return { project, ...(projectKey ? { projectKey } : {}), spaceKey, role: member.role, keyVersion: feed.keyVersion, realtimeKey: feed.realtimeKey ?? spaceKey };
+}
+export async function inviteProjectTeamMember(dataDir, project, email, phrase, preferred, projectKey) {
+    const binding = teamSpaceOf(await readConfig(dataDir), project, projectKey);
+    if (!binding)
+        fail("invalid_argument", `Project ${project} is not in team mode`);
+    const { prepareTeamInvitationHistory, reconcileTeamInvitationHandoffs } = await import("./team-offboarding.js");
+    await reconcileTeamInvitationHandoffs(dataDir, phrase, preferred);
+    // The created intent pins the authoritative account and encryption key.
+    // Resolving an email before a potentially long capture leaves a race with
+    // identity/account changes during the later invitation creation request.
+    const invitation = await createTeamInvitation(dataDir, binding.spaceKey, { email: email.trim() }, preferred);
+    const targetAccountId = Number(invitation.invitee_account_id);
+    const targetPublicKey = invitation.public_key;
+    if (invitation.space_key !== binding.spaceKey || !Number.isSafeInteger(targetAccountId) || targetAccountId <= 0
+        || typeof targetPublicKey !== "string" || Buffer.from(targetPublicKey, "base64").length !== 32) {
+        fail("provider_unsupported", "This backend did not identify the pending invitation's encryption recipient");
+    }
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        const feed = await refreshFeed(dataDir, binding.spaceKey, phrase, preferred);
+        const key = Buffer.from(feed.key, "base64");
+        try {
+            const captured = await prepareTeamInvitationHistory(dataDir, {
+                project, ...(projectKey ? { projectKey } : {}), spaceKey: binding.spaceKey,
+                targetAccountId, targetPublicKey,
+            }, phrase, preferred);
+            if (captured.keyVersion !== undefined && captured.keyVersion !== feed.keyVersion) {
+                fail("team_state_changed", "Team keys changed while invitation history was captured");
+            }
+            await prepareTeamInvitation(dataDir, invitation.id, {
+                wrapped_key: wrapFeed(binding.spaceKey, feed.keyVersion, key, targetPublicKey),
+                expected_key_version: feed.keyVersion,
+                expected_membership_version: captured.membershipVersion,
+                expected_index_revision: captured.indexRevision,
+                expected_archive_refs: JSON.stringify(captured.archiveRefs),
+            }, preferred);
+            return { project, invitationId: invitation.id, accountId: targetAccountId, role: "pending" };
+        }
+        catch (error) {
+            if (!(isSealkeepError(error) && error.code === "team_state_changed" && attempt === 0))
+                throw error;
+        }
+        finally {
+            zeroize(key);
+        }
+    }
+    return fail("team_state_changed", "The team changed again while this invitation was being prepared");
+}
+export async function listProjectTeamInvitations(dataDir, preferred) {
+    return (await import("./cloud.js")).listTeamInvitations(dataDir, preferred);
+}
+/**
+ * Complete folder selections made before their cloud project existed.
+ * Matching is deliberately an exact, case-insensitive display-name match and
+ * requires one unique space; an ambiguous name is left pending for the user to
+ * map from the visible project card instead of guessing an access boundary.
+ */
+export async function reconcileTeamProjectDrafts(dataDir, phrase, spaces, preferred) {
+    const drafts = (await readConfig(dataDir)).teamProjectDrafts ?? [];
+    let bound = 0;
+    for (const draft of drafts) {
+        const wanted = draft.projectName.trim().toLocaleLowerCase();
+        const matches = spaces.filter((space) => space.project_name?.trim().toLocaleLowerCase() === wanted);
+        if (matches.length !== 1)
+            continue;
+        const space = matches[0];
+        const selections = draft.projectSelections ?? draft.projects.map((project) => ({ project, projectKey: null }));
+        for (const selection of selections) {
+            await joinProjectTeamSpace(dataDir, selection.project, space.space_key, phrase, preferred, selection.projectKey);
+            const current = teamSpaceOf(await readConfig(dataDir), selection.project, selection.projectKey);
+            if (current)
+                await bindTeamSpace(dataDir, selection.project, { ...current, localConfirmed: true }, selection.projectKey);
+            bound += 1;
+        }
+        // Creating the hosted space initially uses its display name as a safe
+        // compatibility binding. For a combined project that label is not a real
+        // local folder, so remove it once the explicit folder set is connected.
+        const after = await readConfig(dataDir);
+        const implicit = after.teamSpaces?.[draft.projectName];
+        if (implicit?.spaceKey === space.space_key && !implicit.localConfirmed && !draft.projects.includes(draft.projectName)) {
+            await unbindTeamSpace(dataDir, draft.projectName);
+        }
+        await removeTeamProjectDraft(dataDir, draft.projectName);
+    }
+    return bound;
+}
+function accessFailureCode(error) {
+    if (isSealkeepError(error))
+        return error.code;
+    const code = error?.code;
+    return typeof code === "string" && /^[A-Za-z0-9_-]{1,64}$/.test(code) ? code : "team_access_retry";
+}
+export async function reconcileCloudTeamAccess(dataDir, phrase, preferred) {
+    let created = 0;
+    let prepared = 0;
+    let bound = 0;
+    let removed = 0;
+    const failures = [];
+    // A personal-only vault that has never connected Cloud has no access work.
+    // Distinguish absent local credentials from a real hosted authorization
+    // failure; the latter must still reach the daemon's attention state.
+    try {
+        await cloudToken(dataDir, preferred, { renew: false });
+    }
+    catch (error) {
+        const local = await readConfig(dataDir);
+        if (isSealkeepError(error) && error.code === "unauthorized"
+            && !Object.keys(local.teamSpaces ?? {}).length && !Object.keys(local.teamProjectDrafts ?? {}).length) {
+            return { created, prepared, bound, removed };
+        }
+        throw error;
+    }
+    // The website records only human intent and a project label. A connected
+    // machine owns the cryptographic work: it generates the random feed key,
+    // seals it, binds the local project, then acknowledges the cloud request.
+    // If the response from createTeamSpace was lost, the next list observes the
+    // already-created owner space and completes the same request idempotently.
+    let spaces = await listTeamSpaces(dataDir, preferred);
+    const projectRequests = await listTeamProjectRequests(dataDir, preferred);
+    for (const request of projectRequests) {
+        if (request.state !== "requested")
+            continue;
+        const project = typeof request.project_name === "string" ? request.project_name.trim() : "";
+        if (!project)
+            continue;
+        let space = spaces.find((item) => item.role === "owner" && item.project_name?.trim() === project);
+        if (!space) {
+            try {
+                const made = await createProjectTeamSpace(dataDir, project, phrase, preferred);
+                space = { space_key: made.spaceKey, role: "owner", key_version: made.keyVersion, realtime_key: made.realtimeKey, project_name: project };
+                spaces.push(space);
+                created += 1;
+            }
+            catch (error) {
+                spaces = await listTeamSpaces(dataDir, preferred);
+                space = spaces.find((item) => item.role === "owner" && item.project_name?.trim() === project);
+                if (!space)
+                    failures.push({ operation: "create_project", code: accessFailureCode(error) });
+            }
+        }
+        if (!space)
+            continue;
+        try {
+            await completeTeamProjectRequest(dataDir, request.id, space.space_key, preferred);
+        }
+        catch (error) {
+            failures.push({ operation: "complete_project", code: accessFailureCode(error) });
+        }
+    }
+    spaces = await listTeamSpaces(dataDir, preferred);
+    bound += await reconcileTeamProjectDrafts(dataDir, phrase, spaces, preferred);
+    const config = await readConfig(dataDir);
+    const localBySpace = new Map(Object.entries(config.teamSpaces ?? {}).map(([project, binding]) => [binding.spaceKey, { project, binding }]));
+    const locallyDisconnected = new Set(config.teamSpaceOptOuts ?? []);
+    const outgoing = await listOutgoingTeamInvitations(dataDir, preferred);
+    const { prepareTeamInvitationHistory, reconcileTeamInvitationHandoffs } = await import("./team-offboarding.js");
+    await reconcileTeamInvitationHandoffs(dataDir, phrase, preferred);
+    for (const invitation of outgoing) {
+        const local = localBySpace.get(invitation.space_key);
+        if (!local || local.binding.role !== "owner" || !invitation.public_key)
+            continue;
+        const feed = await refreshFeed(dataDir, invitation.space_key, phrase, preferred);
+        const targetAccountId = Number(invitation.invitee_account_id)
+            || (invitation.invitee_email ? (await resolveTeamInvitee(dataDir, invitation.space_key, invitation.invitee_email, preferred)).account_id : 0);
+        if (!Number.isSafeInteger(targetAccountId) || targetAccountId <= 0)
+            continue;
+        const captured = await prepareTeamInvitationHistory(dataDir, {
+            project: local.binding.localProject ?? local.project,
+            ...(PROJECT_KEY_RE.test(local.project) ? { projectKey: local.project } : {}),
+            spaceKey: invitation.space_key, targetAccountId, targetPublicKey: invitation.public_key,
+        }, phrase, preferred);
+        const refs = JSON.stringify(captured.archiveRefs);
+        if (invitation.wrapped_key && invitation.key_version === feed.keyVersion
+            && invitation.history_membership_version === captured.membershipVersion
+            && invitation.history_index_revision === captured.indexRevision
+            && invitation.history_archive_refs === refs)
+            continue;
+        const key = Buffer.from(feed.key, "base64");
+        try {
+            await prepareTeamInvitation(dataDir, invitation.id, {
+                wrapped_key: wrapFeed(invitation.space_key, feed.keyVersion, key, invitation.public_key),
+                expected_key_version: feed.keyVersion,
+                expected_membership_version: captured.membershipVersion,
+                expected_index_revision: captured.indexRevision,
+                expected_archive_refs: refs,
+            }, preferred);
+            prepared += 1;
+        }
+        finally {
+            zeroize(key);
+        }
+    }
+    // An accepted invitation is authoritative cloud membership. On every fresh
+    // machine, recover its wrapped feed key and bind the human project label
+    // without asking for an opaque space id or a local "join" command.
+    spaces = await listTeamSpaces(dataDir, preferred);
+    for (const space of spaces) {
+        if (!SPACE_RE.test(space.space_key) || localBySpace.has(space.space_key) || locallyDisconnected.has(space.space_key))
+            continue;
+        const project = typeof space.project_name === "string" ? space.project_name.trim() : "";
+        if (!project)
+            continue;
+        const feed = await refreshFeed(dataDir, space.space_key, phrase, preferred);
+        await bindTeamSpace(dataDir, project, {
+            spaceKey: space.space_key,
+            role: space.role === "owner" ? "owner" : "member",
+            keyVersion: feed.keyVersion,
+            realtimeKey: feed.realtimeKey ?? space.space_key,
+        });
+        localBySpace.set(space.space_key, { project, binding: {
+                spaceKey: space.space_key, role: space.role === "owner" ? "owner" : "member",
+                keyVersion: feed.keyVersion, realtimeKey: feed.realtimeKey ?? space.space_key,
+            } });
+        bound += 1;
+    }
+    // Membership decisions are made in SealKeep Cloud, while the operation
+    // that cuts a new feed key must run where the owner's private identity is.
+    // Requests are idempotent: if rotation landed but confirmation did not, the
+    // next tick observes that the target is already absent and closes the row.
+    const removals = await listOutgoingTeamAccessRequests(dataDir, preferred);
+    for (const request of removals) {
+        const local = localBySpace.get(request.space_key);
+        if (!local || local.binding.role !== "owner")
+            continue;
+        try {
+            let members = await listTeamMembers(dataDir, request.space_key, preferred);
+            if (members.some((member) => Number(member.account_id) === Number(request.target_account_id))) {
+                try {
+                    await removeProjectTeamMember(dataDir, local.project, Number(request.target_account_id), phrase, preferred);
+                }
+                catch (error) {
+                    if (!(isSealkeepError(error) && error.code === "invalid_argument"))
+                        throw error;
+                    members = await listTeamMembers(dataDir, request.space_key, preferred);
+                    if (members.some((member) => Number(member.account_id) === Number(request.target_account_id)))
+                        throw error;
+                }
+            }
+            await completeTeamAccessRequest(dataDir, request.id, preferred);
+            removed += 1;
+        }
+        catch (error) {
+            // Other projects still progress, but a failed removal is not success.
+            failures.push({ operation: "remove_member", code: accessFailureCode(error) });
+        }
+    }
+    return { created, prepared, bound, removed, ...(failures.length ? { failures } : {}) };
+}
+export async function acceptProjectTeamInvitation(dataDir, invitationId, project, phrase, preferred) {
+    const member = await (await import("./cloud.js")).acceptTeamInvitation(dataDir, invitationId, preferred);
+    if (!member.space_key)
+        return fail("internal", "Sealkeep Cloud accepted the invitation but returned no space key");
+    const feed = await refreshFeed(dataDir, member.space_key, phrase, preferred);
+    await bindTeamSpace(dataDir, project, { spaceKey: member.space_key, role: member.role === "owner" ? "owner" : "member", keyVersion: feed.keyVersion, realtimeKey: feed.realtimeKey ?? member.space_key });
+    return { project, spaceKey: member.space_key, role: member.role, keyVersion: feed.keyVersion, realtimeKey: feed.realtimeKey ?? member.space_key };
+}
+export async function declineProjectTeamInvitation(dataDir, invitationId, preferred) {
+    return (await import("./cloud.js")).declineTeamInvitation(dataDir, invitationId, preferred);
+}
+/**
+ * Remove one account and cut a fresh feed/realtime epoch for everyone left.
+ * The hosted operation is the commit point. If its response is lost, the
+ * caller's own wrapped membership is enough to prove and recover the result.
+ */
+export async function removeProjectTeamMember(dataDir, project, targetAccountId, phrase, preferred, projectKey) {
+    if (!Number.isSafeInteger(targetAccountId) || targetAccountId <= 0) {
+        fail("invalid_argument", "Choose a valid team member to remove");
+    }
+    const binding = teamSpaceOf(await readConfig(dataDir), project, projectKey);
+    if (!binding)
+        fail("invalid_argument", `Project ${project} is not in team mode`);
+    const { prepareTeamOffboarding, completeTeamOffboarding, reconcileTeamInvitationHandoffs } = await import("./team-offboarding.js");
+    await reconcileTeamInvitationHandoffs(dataDir, phrase, preferred);
+    const historyScope = { project, ...(projectKey ? { projectKey } : {}), spaceKey: binding.spaceKey, targetAccountId };
+    let originalFailure;
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        const feed = await refreshFeed(dataDir, binding.spaceKey, phrase, preferred);
+        const members = await listTeamMembers(dataDir, binding.spaceKey, preferred);
+        const target = members.find((member) => Number(member.account_id) === targetAccountId);
+        if (!target) {
+            // A process may have exited after the cloud committed removal but before
+            // its saved company-history handoff was published. Retry that exact work.
+            await completeTeamOffboarding(dataDir, historyScope, phrase, preferred);
+            return {
+                project, removedAccountId: targetAccountId, keyVersion: feed.keyVersion,
+                realtimeKey: feed.realtimeKey ?? binding.spaceKey, reconciled: true,
+            };
+        }
+        if (target.role === "owner")
+            fail("forbidden", "The project owner cannot be removed");
+        const owner = members.find((member) => member.role === "owner");
+        if (!owner)
+            return fail("internal", "This team space has no owner membership");
+        const captured = await prepareTeamOffboarding(dataDir, historyScope, phrase, preferred);
+        if (captured.keyVersion !== undefined && captured.keyVersion !== feed.keyVersion) {
+            fail("team_state_changed", "Team keys changed while its history was preserved; retry removal");
+        }
+        const nextVersion = feed.keyVersion + 1;
+        const nextKey = randomBytes(32);
+        const realtimeKey = randomBytes(32).toString("base64url");
+        const nextFeed = {
+            version: 1, spaceKey: binding.spaceKey, keyVersion: nextVersion,
+            key: nextKey.toString("base64"), realtimeKey,
+        };
+        const marker = {
+            project, kind: "note", line: "Team access updated", from: "Sealkeep",
+            sender: bindingSender(binding.spaceKey), seq: nextVersion, at: new Date().toISOString(),
+        };
+        try {
+            const wraps = members
+                .filter((member) => Number(member.account_id) !== targetAccountId)
+                .map((member) => ({
+                account_id: Number(member.account_id), public_key: member.public_key,
+                wrapped_key: wrapFeed(binding.spaceKey, nextVersion, nextKey, member.public_key),
+            }));
+            const receipt = await withProgressDeadline("Updating team membership", 60_000, undefined, (signal) => removeTeamMemberAndRotate(dataDir, binding.spaceKey, targetAccountId, {
+                expected_key_version: feed.keyVersion,
+                expected_membership_version: captured.membershipVersion,
+                expected_index_revision: captured.indexRevision,
+                expected_archive_refs: JSON.stringify(captured.archiveRefs),
+                realtime_key: realtimeKey,
+                wraps,
+                binding_sender: marker.sender,
+                binding_sequence: nextVersion,
+                binding_ciphertext: encryptEvent(marker, binding.spaceKey, nextFeed),
+            }, preferred, { signal }));
+            if (receipt.history_fenced !== true) {
+                fail("provider_unsupported", "This backend did not confirm the company-history handoff fence; upgrade the backend before continuing");
+            }
+            if (Number(receipt.key_version) !== nextVersion || receipt.realtime_key !== realtimeKey) {
+                return fail("internal", "Sealkeep Cloud returned a different team epoch than the one committed by this client");
+            }
+            await saveFeed(dataDir, nextFeed, preferred);
+            await updateTeamSpaceBindings(dataDir, binding.spaceKey, { keyVersion: nextVersion, realtimeKey });
+            await completeTeamOffboarding(dataDir, historyScope, phrase, preferred);
+            return { project, removedAccountId: targetAccountId, keyVersion: nextVersion, realtimeKey, reconciled: false };
+        }
+        catch (error) {
+            originalFailure = error;
+            if (isSealkeepError(error) && error.code === "provider_unsupported")
+                throw error;
+            // A CAS conflict is an ordinary concurrent owner action. A transport
+            // error may instead mean the commit landed and only its response was
+            // lost. In both cases, one authoritative read distinguishes them.
+            try {
+                const settled = await refreshFeed(dataDir, binding.spaceKey, phrase, preferred, nextVersion);
+                const settledMembers = await listTeamMembers(dataDir, binding.spaceKey, preferred);
+                if (!settledMembers.some((member) => Number(member.account_id) === targetAccountId)) {
+                    await completeTeamOffboarding(dataDir, historyScope, phrase, preferred);
+                    return {
+                        project, removedAccountId: targetAccountId, keyVersion: settled.keyVersion,
+                        realtimeKey: settled.realtimeKey ?? binding.spaceKey, reconciled: true,
+                    };
+                }
+            }
+            catch { /* the original named failure remains the useful answer */ }
+            if (!(isSealkeepError(error) && error.code === "team_state_changed" && attempt === 0))
+                throw error;
+        }
+        finally {
+            zeroize(nextKey);
+        }
+    }
+    throw originalFailure;
+}
+function aad(spaceKey, keyVersion) {
+    return Buffer.from(`sealkeep-team-presence:v1\0${spaceKey}\0${keyVersion}`, "utf8");
+}
+function encryptEvent(event, spaceKey, feed) {
+    const key = Buffer.from(feed.key, "base64");
+    const nonce = randomBytes(NONCE_BYTES);
+    try {
+        const cipher = aeadCipher(SUITE, key, nonce);
+        cipher.setAAD(aad(spaceKey, feed.keyVersion));
+        const ciphertext = Buffer.concat([cipher.update(Buffer.from(JSON.stringify(event))), cipher.final()]);
+        const value = {
+            version: 1,
+            nonce: nonce.toString("base64"),
+            ciphertext: ciphertext.toString("base64"),
+            tag: cipher.getAuthTag().toString("base64"),
+        };
+        return JSON.stringify(value);
+    }
+    finally {
+        zeroize(key);
+    }
+}
+function decryptEvent(row, spaceKey, feed) {
+    if (row.key_version !== feed.keyVersion)
+        return null;
+    const key = Buffer.from(feed.key, "base64");
+    try {
+        const cipherBlock = JSON.parse(row.ciphertext);
+        if (cipherBlock.version !== 1)
+            return null;
+        const decipher = aeadDecipher(SUITE, key, Buffer.from(cipherBlock.nonce, "base64"));
+        decipher.setAAD(aad(spaceKey, row.key_version));
+        decipher.setAuthTag(Buffer.from(cipherBlock.tag, "base64"));
+        const eventValue = JSON.parse(Buffer.concat([
+            decipher.update(Buffer.from(cipherBlock.ciphertext, "base64")), decipher.final(),
+        ]).toString("utf8"));
+        if (!eventValue || typeof eventValue !== "object" || Array.isArray(eventValue))
+            return null;
+        const event = eventValue;
+        if (event.sender !== row.sender || event.seq !== row.sequence || !["started", "finished", "note"].includes(String(event.kind)))
+            return null;
+        if (typeof event.project !== "string" || !event.project.trim() || event.project.length > 500)
+            return null;
+        if (event.projectKey !== undefined
+            && (typeof event.projectKey !== "string" || !PROJECT_KEY_RE.test(event.projectKey)))
+            return null;
+        if (typeof event.line !== "string" || event.line.length > 140)
+            return null;
+        if (typeof event.from !== "string" || !event.from.trim() || event.from.length > 160)
+            return null;
+        if (typeof event.at !== "string" || event.at.length > 80 || !Number.isFinite(Date.parse(event.at)))
+            return null;
+        const authorAccountId = Number(row.account_id);
+        if (!Number.isSafeInteger(authorAccountId) || authorAccountId <= 0)
+            return null;
+        return {
+            project: event.project, kind: event.kind, line: event.line,
+            from: event.from, sender: row.sender, seq: row.sequence, at: event.at,
+            ...(typeof event.projectKey === "string" ? { projectKey: event.projectKey } : {}),
+            authorAccountId, serverId: row.id,
+        };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        zeroize(key);
+    }
+}
+export async function publishTeamPresenceEvent(dataDir, spaceKey, event, phrase, preferred) {
+    let feed = await loadFeed(dataDir, spaceKey, phrase, preferred);
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        const ciphertext = encryptEvent(event, spaceKey, feed);
+        if (ciphertext.length > 4096)
+            fail("invalid_argument", "A team presence event is too large");
+        try {
+            await publishTeamPresence(dataDir, spaceKey, {
+                sender: event.sender, sequence: event.seq, key_version: feed.keyVersion, ciphertext,
+            }, preferred);
+            return;
+        }
+        catch (error) {
+            if (isSealkeepError(error) && error.code === "team_membership_revoked") {
+                await revokeLocalMembership(dataDir, spaceKey, preferred);
+            }
+            if (!(isSealkeepError(error) && error.code === "team_state_changed" && attempt === 0))
+                throw error;
+            const observed = Number(error.details.currentKeyVersion);
+            feed = await refreshFeed(dataDir, spaceKey, phrase, preferred, Number.isSafeInteger(observed) && observed > 0 ? observed : feed.keyVersion + 1);
+        }
+    }
+}
+export async function readTeamPresence(dataDir, spaceKey, phrase, options = {}) {
+    let feed = await loadFeed(dataDir, spaceKey, phrase, options.preferred);
+    let cursor = Math.max(0, Math.trunc(options.after ?? 0));
+    const rows = [];
+    let more = false;
+    if (options.after === undefined) {
+        rows.push(...await recentTeamPresence(dataDir, spaceKey, options.preferred));
+    }
+    else {
+        const maxPages = Math.max(1, Math.min(5, options.maxPages ?? 5));
+        for (let page = 0; page < maxPages; page++) {
+            const batch = await pollTeamPresence(dataDir, spaceKey, cursor, options.preferred);
+            rows.push(...batch);
+            for (const row of batch)
+                cursor = Math.max(cursor, Number(row.id) || 0);
+            if (batch.length < 200) {
+                more = false;
+                break;
+            }
+            more = page === maxPages - 1;
+        }
+    }
+    const observedVersion = rows.reduce((highest, row) => Math.max(highest, Number(row.key_version) || 0), 0);
+    if (observedVersion > feed.keyVersion) {
+        feed = await refreshFeed(dataDir, spaceKey, phrase, options.preferred, observedVersion);
+    }
+    for (const row of rows)
+        cursor = Math.max(cursor, Number(row.id) || 0);
+    const events = rows.flatMap((row) => {
+        const event = decryptEvent(row, spaceKey, feed);
+        return event && (options.includeBinding || row.sender !== bindingSender(spaceKey)) ? [event] : [];
+    }).sort((a, b) => b.at.localeCompare(a.at));
+    return { events, cursor, more };
+}
+/**
+ * Decrypt the daemon's bounded local push inbox without touching the network.
+ * `gap` tells the hook to preserve its old cursor and use REST before trusting
+ * the newer rows; it must never silently skip an evicted event.
+ */
+export async function readCachedTeamPresence(dataDir, spaceKey, phrase, after, preferred) {
+    const page = await readRealtimeTeamPresence(dataDir, spaceKey, after);
+    if (page.gap || page.rows.length === 0)
+        return { events: [], cursor: after, more: false, gap: page.gap };
+    let feed = await loadFeed(dataDir, spaceKey, phrase, preferred);
+    const observedVersion = page.rows.reduce((highest, row) => Math.max(highest, Number(row.key_version) || 0), 0);
+    if (observedVersion > feed.keyVersion) {
+        feed = await refreshFeed(dataDir, spaceKey, phrase, preferred, observedVersion);
+    }
+    const events = page.rows.flatMap((row) => {
+        const event = decryptEvent(row, spaceKey, feed);
+        return event && row.sender !== bindingSender(spaceKey) ? [event] : [];
+    }).sort((a, b) => b.at.localeCompare(a.at));
+    return { events, cursor: page.cursor, more: false, gap: page.gap };
+}
+/**
+ * On a fresh machine no local project→space binding exists yet. At session
+ * start we inspect only spaces this account belongs to, decrypt their bounded
+ * recent tails, and bind the one whose encrypted event names this project.
+ * This is what makes Mac→VPS and an accepted team invite continue without a
+ * command or a copied config file.
+ */
+export async function discoverProjectTeamSpace(dataDir, project, phrase, preferred, projectKey) {
+    const config = await readConfig(dataDir);
+    const existing = teamSpaceOf(config, project, projectKey);
+    if (existing)
+        return existing;
+    const spaces = await listTeamSpaces(dataDir, preferred);
+    if (!spaces.length)
+        return null;
+    const matches = [];
+    for (const space of spaces) {
+        if (!SPACE_RE.test(space.space_key))
+            continue;
+        try {
+            const page = await readTeamPresence(dataDir, space.space_key, phrase, { preferred, includeBinding: true });
+            const named = page.events.filter((event) => event.project === project);
+            if (!named.length)
+                continue;
+            const exact = Boolean(projectKey && named.some((event) => event.projectKey === projectKey));
+            // A stable key from another repository is positive evidence that this
+            // same-named space is not the caller's. Keyless events are legacy
+            // candidates and are considered only when no exact space exists.
+            if (projectKey && !exact && !named.some((event) => !event.projectKey))
+                continue;
+            const member = await getTeamMembership(dataDir, space.space_key, preferred);
+            if (!member)
+                continue;
+            matches.push({ spaceKey: space.space_key, member, exact });
+        }
+        catch { /* another encrypted project, stale membership, or temporary outage */ }
+    }
+    // A display label is not identity. If two spaces contain an "api" seed,
+    // silently choosing whichever the server listed first crosses an access
+    // boundary. Leave both unbound until an explicit cloud selection resolves
+    // the ambiguity.
+    const exactMatches = matches.filter((match) => match.exact);
+    const eligible = exactMatches.length > 0 ? exactMatches : matches;
+    if (eligible.length !== 1)
+        return null;
+    const [{ spaceKey, member }] = eligible;
+    await bindTeamSpace(dataDir, project, {
+        spaceKey,
+        role: member.role === "owner" ? "owner" : "member",
+        keyVersion: member.key_version,
+        realtimeKey: SPACE_RE.test(member.realtime_key ?? "") ? member.realtime_key : spaceKey,
+    }, projectKey);
+    return teamSpaceOf(await readConfig(dataDir), project, projectKey);
+}