@peers-app/peers-sdk 0.25.13 → 0.25.15

package/dist/identity/key-change.js

@@ -0,0 +1,472 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.identityRecoveryNoticesVar = exports.identityRotatedAwayVar = exports.identityRotatedAwayEvent = exports.DEFAULT_RECOVERY_DELAY_MS = void 0;
+exports.recoveryDelayMs = recoveryDelayMs;
+exports.setContestFetcher = setContestFetcher;
+exports.peekLocalKeyContest = peekLocalKeyContest;
+exports.setLocalKeyContest = setLocalKeyContest;
+exports.holdKeyContest = holdKeyContest;
+exports.evaluatePresentedKey = evaluatePresentedKey;
+exports.detectIdentityRotatedAway = detectIdentityRotatedAway;
+exports.clearRotatedAwayNotice = clearRotatedAwayNotice;
+exports.acceptRecovery = acceptRecovery;
+exports.applyKeyContest = applyKeyContest;
+exports.evaluatePresentedAnchors = evaluatePresentedAnchors;
+const user_context_singleton_1 = require("../context/user-context-singleton");
+const persistent_vars_1 = require("../data/persistent-vars");
+const users_1 = require("../data/users");
+const events_1 = require("../events");
+const keys_1 = require("../keys");
+const utils_1 = require("../utils");
+const anchor_resolution_1 = require("./anchor-resolution");
+const key_contest_1 = require("./key-contest");
+const key_resolutions_1 = require("./key-resolutions");
+/** How long a recovery waits before peers adopt it. Not a user setting. */
+exports.DEFAULT_RECOVERY_DELAY_MS = 72 * 60 * 60 * 1000;
+/**
+ * Delay before a confirmed recovery replaces the key on record.
+ * `PEERS_RECOVERY_DELAY_MS` shortens it for tests. Unset means {@link DEFAULT_RECOVERY_DELAY_MS}.
+ */
+function recoveryDelayMs() {
+    const override = Number(process.env.PEERS_RECOVERY_DELAY_MS);
+    if (Number.isFinite(override) && override >= 0)
+        return override;
+    return exports.DEFAULT_RECOVERY_DELAY_MS;
+}
+/**
+ * Fired on a device whose own key is no longer the key the anchors confirm.
+ * The device must be paired again. Hosts subscribe to show the notice.
+ */
+exports.identityRotatedAwayEvent = new events_1.Emitter("identityRotatedAway");
+/**
+ * Device-scoped record of the rotated-away state so the UI can show it after a restart.
+ */
+exports.identityRotatedAwayVar = (0, persistent_vars_1.deviceVar)("identityRotatedAway", { defaultValue: null });
+/**
+ * Recoveries waiting on the delay or on a contest.
+ * The own-device banner and a contact's decision both read this.
+ */
+exports.identityRecoveryNoticesVar = (0, persistent_vars_1.deviceVar)("identityRecoveryNotices", { defaultValue: [] });
+let contestFetcher;
+/**
+ * The contest this device signed. Device-scoped and persisted: with services off the
+ * handshake is the only carrier, and a restart must not silence it.
+ */
+const localKeyContestVar = (0, persistent_vars_1.deviceVar)("identityLocalKeyContest", { defaultValue: null });
+const heldContests = [];
+const recoveryTimers = new Map();
+/** Installs the contest lookup {@link evaluatePresentedKey} uses. */
+function setContestFetcher(fetcher) {
+    contestFetcher = fetcher;
+}
+/** The contest this device is carrying in its handshake, if it has signed one. */
+function peekLocalKeyContest() {
+    return localKeyContestVar() ?? undefined;
+}
+/** Remembers a contest this device signed, so later handshakes carry it, across restarts. */
+async function setLocalKeyContest(signed) {
+    await localKeyContestVar.loadingPromise;
+    localKeyContestVar(signed ?? null);
+    // The write is chained onto loadingPromise; wait for it so the contest survives a restart
+    // that follows straight after.
+    await localKeyContestVar.loadingPromise;
+}
+/** Remembers a contest received from a peer or an anchor. */
+function holdKeyContest(signed) {
+    heldContests.push(signed);
+}
+function boxMatches(publicKey, publicBoxKey) {
+    return (0, keys_1.derivePublicBoxKey)(publicKey) === publicBoxKey;
+}
+function cacheFresh(row, now) {
+    const checked = Date.parse(row.lastCheckedAt);
+    if (Number.isNaN(checked))
+        return false;
+    return now - checked < row.cacheSeconds * 1000;
+}
+function decisionFromState(state, recoveryPending = false) {
+    if (state === "confirmed-rotation")
+        return { accepted: true, state: "confirmed-rotation" };
+    if (state === "vetoed")
+        return { accepted: false, state: "vetoed" };
+    if (recoveryPending || state === "confirmed-recovery") {
+        return { accepted: false, state: "recovery-pending" };
+    }
+    return { accepted: false, state: "pending" };
+}
+function recoveryDue(row, now) {
+    if (row.contested)
+        return false;
+    const seen = Date.parse(row.firstSeenAt);
+    return Number.isFinite(seen) && now - seen >= recoveryDelayMs();
+}
+function contestsMatch(userId, recordPublicKey, pendingKey, contests) {
+    return contests.some((signed) => (0, key_contest_1.verifyKeyContest)({ signed, userId, recordPublicKey, pendingKey }));
+}
+async function loadContests(userId) {
+    const remote = contestFetcher ? await contestFetcher(userId).catch(() => []) : [];
+    return [...heldContests, ...remote];
+}
+function clearRecoveryTimer(userId, presentedKey) {
+    const key = `${userId}:${presentedKey}`;
+    const timer = recoveryTimers.get(key);
+    if (timer)
+        clearTimeout(timer);
+    recoveryTimers.delete(key);
+}
+function scheduleRecovery(params, firstSeenAt) {
+    const key = `${params.userId}:${params.presentedKey}`;
+    clearRecoveryTimer(params.userId, params.presentedKey);
+    const wait = Math.max(0, Date.parse(firstSeenAt) + recoveryDelayMs() - Date.now());
+    const timer = setTimeout(() => {
+        recoveryTimers.delete(key);
+        void evaluatePresentedKey(params).catch((err) => {
+            console.warn(`Recovery check failed for ${params.userId}`, err);
+        });
+    }, wait);
+    timer.unref?.();
+    recoveryTimers.set(key, timer);
+}
+async function rememberResolution(dataContext, existing, next) {
+    const nowIso = new Date().toISOString();
+    await (0, key_resolutions_1.KeyResolutions)(dataContext).save({
+        resolutionId: existing?.resolutionId ?? (0, utils_1.newid)(),
+        userId: next.userId,
+        presentedKey: next.presentedKey,
+        firstSeenAt: existing?.firstSeenAt ?? next.firstSeenAt ?? nowIso,
+        lastCheckedAt: next.lastCheckedAt,
+        state: next.state,
+        successionByRecordKey: next.successionByRecordKey,
+        contested: Boolean(existing?.contested || next.contested),
+        cacheSeconds: next.cacheSeconds,
+    });
+}
+async function switchPersonalKey(dataContext, user, presentedKey, presentedBoxKey) {
+    if (user.publicKey === presentedKey && user.publicBoxKey === presentedBoxKey)
+        return;
+    // The row was signed by the key being replaced; the new key's signed row arrives by sync.
+    const { signature: _signature, ...profile } = user;
+    await (0, users_1.writeResolvedUserKey)(dataContext, {
+        ...profile,
+        publicKey: presentedKey,
+        publicBoxKey: presentedBoxKey,
+    });
+}
+/**
+ * Decides whether `presentedKey` may replace the key on record for `userId`.
+ *
+ * The anchors already stored for the user are fetched (or a fresh cached answer is reused).
+ * A confirmed rotation updates the personal `Users` row immediately. A confirmed recovery
+ * waits out {@link recoveryDelayMs} and is held if a holder of the key on record contests
+ * it. A veto or no answer leaves the key on record in place.
+ */
+async function evaluatePresentedKey(params) {
+    const personal = await (0, users_1.Users)(params.dataContext).get(params.userId);
+    const record = params.record ?? personal;
+    if (!record?.publicKey)
+        return { accepted: false, state: "no-record" };
+    if (params.presentedKey === record.publicKey) {
+        if (params.presentedBoxKey !== record.publicBoxKey) {
+            return { accepted: false, state: "box-mismatch" };
+        }
+        return { accepted: true, state: "current" };
+    }
+    if (!boxMatches(params.presentedKey, params.presentedBoxKey)) {
+        return { accepted: false, state: "box-mismatch" };
+    }
+    const existing = (await (0, key_resolutions_1.KeyResolutions)(params.dataContext).findOne({
+        userId: params.userId,
+        presentedKey: params.presentedKey,
+    })) ?? null;
+    const now = Date.now();
+    if (existing && cacheFresh(existing, now) && existing.state !== "confirmed-recovery") {
+        if (existing.state === "confirmed-rotation" && personal && params.adopt !== false) {
+            await switchPersonalKey(params.dataContext, personal, params.presentedKey, params.presentedBoxKey);
+        }
+        return decisionFromState(existing.state);
+    }
+    if (existing?.state === "confirmed-recovery" && cacheFresh(existing, now)) {
+        // The anchor was asked for contests when this row was last checked. The recovering device
+        // handshakes often and each handshake lands here, so within the cache window only contests
+        // that reached this device directly are considered, except at the moment the delay is up:
+        // the anchor is asked once more before the key is adopted.
+        let row = existing;
+        if (!row.contested) {
+            const contests = recoveryDue(row, now) ? await loadContests(params.userId) : heldContests;
+            const matched = contestsMatch(params.userId, record.publicKey, params.presentedKey, contests);
+            if (matched) {
+                row = { ...row, contested: true };
+                await rememberResolution(params.dataContext, existing, { ...row, contested: true });
+                clearRecoveryTimer(params.userId, params.presentedKey);
+            }
+        }
+        return finishRecovery(params, personal ?? null, record.publicKey, row, now);
+    }
+    const anchors = record.anchors ?? [];
+    const fetcher = (0, anchor_resolution_1.getAnchorFetcher)();
+    let outcomes = anchors.map(() => ({ outcome: "abstain" }));
+    if (fetcher && anchors.length > 0) {
+        outcomes = await Promise.all(anchors.map(async (anchor) => {
+            try {
+                return await fetcher(anchor, params.userId);
+            }
+            catch (err) {
+                console.warn(`Anchor ${anchor.url} failed for ${params.userId}`, err);
+                return { outcome: "abstain" };
+            }
+        }));
+    }
+    const resolution = (0, anchor_resolution_1.resolvePresentedKey)({
+        userId: params.userId,
+        recordPublicKey: record.publicKey,
+        presentedPublicKey: params.presentedKey,
+        outcomes,
+    });
+    const contested = resolution.state === "confirmed-recovery" &&
+        contestsMatch(params.userId, record.publicKey, params.presentedKey, await loadContests(params.userId));
+    const firstSeenAt = existing?.firstSeenAt ?? new Date(now).toISOString();
+    await rememberResolution(params.dataContext, existing, {
+        userId: params.userId,
+        presentedKey: params.presentedKey,
+        firstSeenAt,
+        lastCheckedAt: new Date(now).toISOString(),
+        state: resolution.state,
+        successionByRecordKey: resolution.successionByRecordKey,
+        contested,
+        cacheSeconds: resolution.cacheSeconds,
+    });
+    if (resolution.state === "confirmed-rotation" && personal && params.adopt !== false) {
+        await switchPersonalKey(params.dataContext, personal, params.presentedKey, params.presentedBoxKey);
+        return { accepted: true, state: "confirmed-rotation" };
+    }
+    if (resolution.state !== "confirmed-recovery") {
+        return decisionFromState(resolution.state);
+    }
+    const saved = await (0, key_resolutions_1.KeyResolutions)(params.dataContext).findOne({
+        userId: params.userId,
+        presentedKey: params.presentedKey,
+    });
+    return finishRecovery(params, personal ?? null, record.publicKey, saved ?? {
+        resolutionId: "",
+        userId: params.userId,
+        presentedKey: params.presentedKey,
+        firstSeenAt,
+        lastCheckedAt: new Date(now).toISOString(),
+        state: "confirmed-recovery",
+        successionByRecordKey: false,
+        contested,
+        cacheSeconds: resolution.cacheSeconds,
+    }, now);
+}
+async function finishRecovery(params, personal, recordPublicKey, row, now) {
+    if (row.contested || !recoveryDue(row, now)) {
+        if (!row.contested)
+            scheduleRecovery(params, row.firstSeenAt);
+        await publishRecoveryNotice(params, recordPublicKey, row);
+        return { accepted: false, state: "recovery-pending" };
+    }
+    clearRecoveryTimer(params.userId, params.presentedKey);
+    // With `adopt: false` the caller (detectIdentityRotatedAway) records that this device
+    // holds the old key; it knows the device's key, which the row may no longer match.
+    if (personal && params.adopt !== false) {
+        await switchPersonalKey(params.dataContext, personal, params.presentedKey, params.presentedBoxKey);
+    }
+    await clearRecoveryNotice(params.userId, params.presentedKey);
+    return { accepted: true, state: "confirmed-recovery" };
+}
+async function publishRecoveryNotice(params, recordPublicKey, row) {
+    const userContext = (0, user_context_singleton_1.peekUserContext)();
+    const notice = {
+        userId: params.userId,
+        recordPublicKey,
+        pendingPublicKey: params.presentedKey,
+        firstSeenAt: row.firstSeenAt,
+        readyAt: new Date(Date.parse(row.firstSeenAt) + recoveryDelayMs()).toISOString(),
+        contested: row.contested,
+        own: userContext?.userId === params.userId,
+    };
+    try {
+        await exports.identityRecoveryNoticesVar.loadingPromise;
+        const current = (0, exports.identityRecoveryNoticesVar)() ?? [];
+        const next = current.filter((item) => !(item.userId === notice.userId && item.pendingPublicKey === notice.pendingPublicKey));
+        next.push(notice);
+        (0, exports.identityRecoveryNoticesVar)(next);
+    }
+    catch (err) {
+        console.warn("Could not persist a recovery notice", err);
+    }
+}
+async function clearRecoveryNotice(userId, pendingPublicKey) {
+    try {
+        await exports.identityRecoveryNoticesVar.loadingPromise;
+        const current = (0, exports.identityRecoveryNoticesVar)() ?? [];
+        (0, exports.identityRecoveryNoticesVar)(current.filter((item) => !(item.userId === userId && item.pendingPublicKey === pendingPublicKey)));
+    }
+    catch {
+        // The notice is a display aid. The Users row is the record.
+    }
+}
+/**
+ * When another device of this user presents a key the anchors confirm, records that this
+ * device holds the old key and must be paired again. A pending or vetoed key does not.
+ */
+async function detectIdentityRotatedAway(me, evidence) {
+    if (evidence.userId !== me.userId || evidence.publicKey === me.publicKey)
+        return undefined;
+    // A handshake can run in a process with no user context (connection unit tests,
+    // and anything that has not finished startup). Waiting here would stall the handshake.
+    const userContext = (0, user_context_singleton_1.peekUserContext)();
+    if (!userContext)
+        return undefined;
+    await userContext.loadingPromise;
+    const decision = await evaluatePresentedKey({
+        dataContext: userContext.userDataContext,
+        userId: me.userId,
+        presentedKey: evidence.publicKey,
+        presentedBoxKey: evidence.publicBoxKey,
+        adopt: false,
+    });
+    if (!decision.accepted)
+        return undefined;
+    if (decision.state !== "confirmed-rotation" && decision.state !== "confirmed-recovery") {
+        return undefined;
+    }
+    const payload = {
+        userId: me.userId,
+        oldPublicKey: me.publicKey,
+        newPublicKey: evidence.publicKey,
+        ...(evidence.deviceId ? { seenFromDeviceId: evidence.deviceId } : {}),
+        detectedAt: new Date().toISOString(),
+    };
+    console.error(`This device's key for user ${me.userId} was confirmed rotated away${evidence.deviceId ? ` by device ${evidence.deviceId}` : ""}; pair this device again`);
+    try {
+        await exports.identityRotatedAwayVar.loadingPromise;
+        (0, exports.identityRotatedAwayVar)(payload);
+    }
+    catch (err) {
+        console.warn("Could not persist identityRotatedAway state", err);
+    }
+    await exports.identityRotatedAwayEvent.emit(payload);
+    return payload;
+}
+/**
+ * Drops the rotated-away notice when it no longer describes this device: it now holds the
+ * key the notice named, or a key the anchors have since confirmed (`anchorsConfirmed`).
+ * A device that still holds the retired key keeps its notice.
+ */
+async function clearRotatedAwayNotice(params) {
+    // The notice lives in a device-scoped pvar, which loads through the process-wide user
+    // context. A context that is not installed as the singleton (tests, tooling) has none.
+    if (!(0, user_context_singleton_1.peekUserContext)())
+        return;
+    try {
+        await exports.identityRotatedAwayVar.loadingPromise;
+        const notice = (0, exports.identityRotatedAwayVar)();
+        if (!notice || notice.userId !== params.userId)
+            return;
+        if (notice.newPublicKey === params.deviceKey || params.anchorsConfirmed) {
+            (0, exports.identityRotatedAwayVar)(null);
+        }
+    }
+    catch (err) {
+        console.warn("Could not clear identityRotatedAway state", err);
+    }
+}
+/**
+ * Adopts a recovery before the delay when the person at this device says to.
+ * A contest keeps the change pending until this runs.
+ */
+async function acceptRecovery(dataContext, userId, pendingKey) {
+    const row = await (0, key_resolutions_1.KeyResolutions)(dataContext).findOne({ userId, presentedKey: pendingKey });
+    if (!row || row.state !== "confirmed-recovery") {
+        throw new Error("No recovery is waiting for that key");
+    }
+    const personal = await (0, users_1.Users)(dataContext).get(userId);
+    if (!personal)
+        throw new Error("No profile is stored for that user");
+    const boxKey = (0, keys_1.derivePublicBoxKey)(pendingKey);
+    if (!boxKey)
+        throw new Error("The recovered key is not a signing key");
+    clearRecoveryTimer(userId, pendingKey);
+    await switchPersonalKey(dataContext, personal, pendingKey, boxKey);
+    await clearRecoveryNotice(userId, pendingKey);
+}
+/**
+ * Records a contest against `pendingKey` and holds the recovery.
+ * Returns false when the signature is not the key on record.
+ */
+async function applyKeyContest(dataContext, signed) {
+    const statement = signed.contents;
+    if (!statement?.userId || !statement.pendingKey)
+        return false;
+    const personal = await (0, users_1.Users)(dataContext).get(statement.userId);
+    const recordPublicKey = personal?.publicKey;
+    if (!recordPublicKey)
+        return false;
+    if (!(0, key_contest_1.verifyKeyContest)({
+        signed,
+        userId: statement.userId,
+        recordPublicKey,
+        pendingKey: statement.pendingKey,
+    })) {
+        return false;
+    }
+    holdKeyContest(signed);
+    const existing = await (0, key_resolutions_1.KeyResolutions)(dataContext).findOne({
+        userId: statement.userId,
+        presentedKey: statement.pendingKey,
+    });
+    if (existing) {
+        await rememberResolution(dataContext, existing, { ...existing, contested: true });
+    }
+    clearRecoveryTimer(statement.userId, statement.pendingKey);
+    const pendingBoxKey = (0, keys_1.derivePublicBoxKey)(statement.pendingKey);
+    if (existing && pendingBoxKey) {
+        await publishRecoveryNotice({
+            dataContext,
+            userId: statement.userId,
+            presentedKey: statement.pendingKey,
+            presentedBoxKey: pendingBoxKey,
+        }, recordPublicKey, { ...existing, contested: true });
+    }
+    return true;
+}
+/**
+ * Decides whether `presentedAnchors` may replace the list on record.
+ * The anchors already stored are fetched. On confirmation the personal row's list is updated.
+ * The signing key is left as it is.
+ */
+async function evaluatePresentedAnchors(params) {
+    if ((0, anchor_resolution_1.sameAnchorList)(params.recordAnchors, params.presentedAnchors))
+        return "confirmed";
+    if (params.recordAnchors.length === 0)
+        return "vetoed";
+    const fetcher = (0, anchor_resolution_1.getAnchorFetcher)();
+    if (!fetcher)
+        return "vetoed";
+    const outcomes = await Promise.all(params.recordAnchors.map(async (anchor) => {
+        try {
+            return await fetcher(anchor, params.userId);
+        }
+        catch (err) {
+            console.warn(`Anchor ${anchor.url} failed for ${params.userId}`, err);
+            return { outcome: "abstain" };
+        }
+    }));
+    const decision = (0, anchor_resolution_1.resolvePresentedAnchors)({
+        userId: params.userId,
+        presented: params.presentedAnchors,
+        outcomes,
+    });
+    if (decision !== "confirmed")
+        return decision;
+    const personal = await (0, users_1.Users)(params.dataContext).get(params.userId);
+    if (personal?.publicKey) {
+        // The list is not under the row's signature, so a signed row stays signed.
+        await (0, users_1.writeResolvedUserKey)(params.dataContext, {
+            ...personal,
+            anchors: params.presentedAnchors,
+        });
+    }
+    return "confirmed";
+}

package/dist/identity/key-change.test.d.ts

@@ -0,0 +1 @@
+import "./user-row-change";