@peers-app/peers-sdk 0.25.13 → 0.25.15

package/dist/identity/anchor-resolution.test.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("../index");
+const anchor_document_1 = require("./anchor-document");
+const anchor_resolution_1 = require("./anchor-resolution");
+const userId = (0, index_1.newid)();
+const record = (0, index_1.newKeys)();
+const next = (0, index_1.newKeys)();
+const anchor = {
+    type: "https",
+    url: "https://example.com/.well-known/peers-identity.json",
+};
+function document(keys) {
+    return {
+        version: 1,
+        userId,
+        keys,
+        anchors: [anchor],
+        updatedAt: "2026-10-03T18:00:00.000Z",
+    };
+}
+function confirm(entry) {
+    return { outcome: "document", document: document([entry]), maxAgeSeconds: 30 };
+}
+describe("resolvePresentedKey", () => {
+    const issuedAt = "2026-10-03T18:00:00.000Z";
+    it("confirms a rotation when the key on record co-signed and nobody vetoes", () => {
+        const signed = (0, anchor_document_1.signSuccession)({ purpose: "peers-key-succession", userId, publicKey: next.publicKey, issuedAt }, record.secretKey);
+        const resolution = (0, anchor_resolution_1.resolvePresentedKey)({
+            userId,
+            recordPublicKey: record.publicKey,
+            presentedPublicKey: next.publicKey,
+            outcomes: [
+                confirm({
+                    publicKey: next.publicKey,
+                    issuedAt,
+                    reason: "rotation",
+                    authorizedBy: { publicKey: signed.publicKey, signature: signed.signature },
+                }),
+                { outcome: "abstain" },
+            ],
+        });
+        expect(resolution.state).toBe("confirmed-rotation");
+        expect(resolution.successionByRecordKey).toBe(true);
+        expect(resolution.cacheSeconds).toBe(30);
+    });
+    it("treats a listed key without the record key's signature as recovery", () => {
+        const resolution = (0, anchor_resolution_1.resolvePresentedKey)({
+            userId,
+            recordPublicKey: record.publicKey,
+            presentedPublicKey: next.publicKey,
+            outcomes: [confirm({ publicKey: next.publicKey, issuedAt, reason: "lost" })],
+        });
+        expect(resolution.state).toBe("confirmed-recovery");
+    });
+    it("vetoes when any anchor omits the presented key", () => {
+        const resolution = (0, anchor_resolution_1.resolvePresentedKey)({
+            userId,
+            recordPublicKey: record.publicKey,
+            presentedPublicKey: next.publicKey,
+            outcomes: [
+                confirm({ publicKey: next.publicKey, issuedAt }),
+                confirm({ publicKey: record.publicKey, issuedAt }),
+            ],
+        });
+        expect(resolution.state).toBe("vetoed");
+    });
+    it("vetoes a document for another user and a 404", () => {
+        const other = document([{ publicKey: next.publicKey, issuedAt }]);
+        other.userId = (0, index_1.newid)();
+        const resolution = (0, anchor_resolution_1.resolvePresentedKey)({
+            userId,
+            recordPublicKey: record.publicKey,
+            presentedPublicKey: next.publicKey,
+            outcomes: [{ outcome: "document", document: other }, { outcome: "veto" }],
+        });
+        expect(resolution.state).toBe("vetoed");
+    });
+    it("stays pending when every anchor abstains", () => {
+        const resolution = (0, anchor_resolution_1.resolvePresentedKey)({
+            userId,
+            recordPublicKey: record.publicKey,
+            presentedPublicKey: next.publicKey,
+            outcomes: [{ outcome: "abstain" }, { outcome: "abstain" }],
+        });
+        expect(resolution.state).toBe("pending");
+    });
+    it("rejects a co-signature that is not the key on record", () => {
+        const imposter = (0, index_1.newKeys)();
+        const signed = (0, anchor_document_1.signSuccession)({ purpose: "peers-key-succession", userId, publicKey: next.publicKey, issuedAt }, imposter.secretKey);
+        const resolution = (0, anchor_resolution_1.resolvePresentedKey)({
+            userId,
+            recordPublicKey: record.publicKey,
+            presentedPublicKey: next.publicKey,
+            outcomes: [
+                confirm({
+                    publicKey: next.publicKey,
+                    issuedAt,
+                    authorizedBy: { publicKey: signed.publicKey, signature: signed.signature },
+                }),
+            ],
+        });
+        expect(resolution.state).toBe("confirmed-recovery");
+    });
+});
+describe("resolvePresentedAnchors", () => {
+    const next = [anchor, { type: "https", url: "https://example.com/other.json" }];
+    it("confirms when an anchor publishes the new list and none veto", () => {
+        const decision = (0, anchor_resolution_1.resolvePresentedAnchors)({
+            userId,
+            presented: next,
+            outcomes: [
+                { outcome: "document", document: { ...document([]), anchors: [...next].reverse() } },
+                { outcome: "abstain" },
+            ],
+        });
+        expect(decision).toBe("confirmed");
+    });
+    it("vetoes when an anchor still publishes a different list", () => {
+        const decision = (0, anchor_resolution_1.resolvePresentedAnchors)({
+            userId,
+            presented: next,
+            outcomes: [
+                { outcome: "document", document: document([]) },
+                { outcome: "document", document: { ...document([]), anchors: next } },
+            ],
+        });
+        expect(decision).toBe("vetoed");
+    });
+});

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

@@ -0,0 +1,142 @@
+import type { DataContext } from "../context/data-context";
+import { type IUser } from "../data/users";
+import { Emitter } from "../events";
+import { type ISignedObject } from "../keys";
+import type { IAnchorRef } from "./anchor-document";
+import { type IKeyContestStatement } from "./key-contest";
+/** How long a recovery waits before peers adopt it. Not a user setting. */
+export declare const DEFAULT_RECOVERY_DELAY_MS: number;
+/**
+ * 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}.
+ */
+export declare function recoveryDelayMs(): number;
+/** On-record identity used when the personal `Users` row is not the row being compared. */
+export type KeyRecord = Pick<IUser, "userId" | "publicKey" | "publicBoxKey" | "anchors">;
+/** Decision for a handshake or row that presents a key. */
+export type PresentedKeyDecision = {
+    accepted: true;
+    state: "current" | "confirmed-rotation" | "confirmed-recovery";
+} | {
+    accepted: false;
+    state: "pending" | "recovery-pending" | "vetoed" | "box-mismatch" | "no-record";
+};
+/** Inputs for {@link evaluatePresentedKey}. */
+export interface EvaluatePresentedKeyParams {
+    /** Personal data context, where the on-record row and the resolution cache live. */
+    dataContext: DataContext;
+    userId: string;
+    presentedKey: string;
+    presentedBoxKey: string;
+    /**
+     * Key and anchors to resolve against when the personal row is missing or still
+     * holds an older key. Defaults to the personal row.
+     */
+    record?: KeyRecord;
+    /**
+     * When false, a confirmed rotation is reported but the personal row is left
+     * alone. A device recognising that its own key was rotated away passes false
+     * so it does not store a key it cannot sign.
+     */
+    adopt?: boolean;
+}
+/** Payload of {@link identityRotatedAwayEvent}. */
+export interface IIdentityRotatedAway {
+    userId: string;
+    /** This device's key, which the anchors no longer list as current. */
+    oldPublicKey: string;
+    /** The key the anchors confirmed. */
+    newPublicKey: string;
+    /** Device that presented the new key, when the evidence was a handshake. */
+    seenFromDeviceId?: string;
+    detectedAt: string;
+}
+/**
+ * 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.
+ */
+export declare const identityRotatedAwayEvent: Emitter<IIdentityRotatedAway>;
+/**
+ * Device-scoped record of the rotated-away state so the UI can show it after a restart.
+ */
+export declare const identityRotatedAwayVar: import("../data/persistent-vars").PersistentVar<IIdentityRotatedAway | null>;
+/** A recovery this device has seen and not yet adopted. `own` is a key this device still holds. */
+export interface IIdentityRecoveryPending {
+    userId: string;
+    recordPublicKey: string;
+    pendingPublicKey: string;
+    firstSeenAt: string;
+    readyAt: string;
+    contested: boolean;
+    own: boolean;
+}
+/**
+ * Recoveries waiting on the delay or on a contest.
+ * The own-device banner and a contact's decision both read this.
+ */
+export declare const identityRecoveryNoticesVar: import("../data/persistent-vars").PersistentVar<IIdentityRecoveryPending[]>;
+/** Asks an anchor which contests it is holding. Installed by the host. */
+export type ContestFetcher = (userId: string) => Promise<ISignedObject<IKeyContestStatement>[]>;
+/** Installs the contest lookup {@link evaluatePresentedKey} uses. */
+export declare function setContestFetcher(fetcher: ContestFetcher | undefined): void;
+/** The contest this device is carrying in its handshake, if it has signed one. */
+export declare function peekLocalKeyContest(): ISignedObject<IKeyContestStatement> | undefined;
+/** Remembers a contest this device signed, so later handshakes carry it, across restarts. */
+export declare function setLocalKeyContest(signed: ISignedObject<IKeyContestStatement> | undefined): Promise<void>;
+/** Remembers a contest received from a peer or an anchor. */
+export declare function holdKeyContest(signed: ISignedObject<IKeyContestStatement>): void;
+/**
+ * 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.
+ */
+export declare function evaluatePresentedKey(params: EvaluatePresentedKeyParams): Promise<PresentedKeyDecision>;
+/** Evidence that another holder of our user id is using a different key. */
+export interface RotatedAwayEvidence {
+    userId: string;
+    publicKey: string;
+    publicBoxKey: string;
+    deviceId?: string;
+}
+/**
+ * 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.
+ */
+export declare function detectIdentityRotatedAway(me: {
+    userId: string;
+    publicKey: string;
+}, evidence: RotatedAwayEvidence): Promise<IIdentityRotatedAway | undefined>;
+/**
+ * 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.
+ */
+export declare function clearRotatedAwayNotice(params: {
+    userId: string;
+    deviceKey: string;
+    anchorsConfirmed: boolean;
+}): Promise<void>;
+/**
+ * Adopts a recovery before the delay when the person at this device says to.
+ * A contest keeps the change pending until this runs.
+ */
+export declare function acceptRecovery(dataContext: DataContext, userId: string, pendingKey: string): Promise<void>;
+/**
+ * Records a contest against `pendingKey` and holds the recovery.
+ * Returns false when the signature is not the key on record.
+ */
+export declare function applyKeyContest(dataContext: DataContext, signed: ISignedObject<IKeyContestStatement>): Promise<boolean>;
+/**
+ * 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.
+ */
+export declare function evaluatePresentedAnchors(params: {
+    dataContext: DataContext;
+    userId: string;
+    recordAnchors: IAnchorRef[];
+    presentedAnchors: IAnchorRef[];
+}): Promise<"confirmed" | "pending" | "vetoed">;