@peers-app/peers-sdk 0.25.13 → 0.25.15

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

@@ -0,0 +1,91 @@
+import { z } from "zod";
+import { type ISignedObject } from "../keys";
+/** Purpose string a holder of the key on record signs to object to a recovery. */
+export declare const KEY_CONTEST_PURPOSE: "peers-key-contest";
+/** Statement that says the key on record did not ask for `pendingKey`. */
+export declare const keyContestStatementSchema: z.ZodObject<{
+    purpose: z.ZodLiteral<"peers-key-contest">;
+    userId: z.ZodEffects<z.ZodString, string, string>;
+    /** Key on record. The signature must be this key. */
+    publicKey: z.ZodString;
+    /** Key the anchors are offering without this key's co-signature. */
+    pendingKey: z.ZodString;
+    at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    at: string;
+    publicKey: string;
+    purpose: "peers-key-contest";
+    userId: string;
+    pendingKey: string;
+}, {
+    at: string;
+    publicKey: string;
+    purpose: "peers-key-contest";
+    userId: string;
+    pendingKey: string;
+}>;
+/** Statement that says the key on record did not ask for a recovery. */
+export type IKeyContestStatement = z.infer<typeof keyContestStatementSchema>;
+/** Signed contest carried in a handshake and posted to an anchor. */
+export declare const keyContestSignedSchema: z.ZodObject<{
+    contents: z.ZodObject<{
+        purpose: z.ZodLiteral<"peers-key-contest">;
+        userId: z.ZodEffects<z.ZodString, string, string>;
+        /** Key on record. The signature must be this key. */
+        publicKey: z.ZodString;
+        /** Key the anchors are offering without this key's co-signature. */
+        pendingKey: z.ZodString;
+        at: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        at: string;
+        publicKey: string;
+        purpose: "peers-key-contest";
+        userId: string;
+        pendingKey: string;
+    }, {
+        at: string;
+        publicKey: string;
+        purpose: "peers-key-contest";
+        userId: string;
+        pendingKey: string;
+    }>;
+    signature: z.ZodString;
+    publicKey: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    publicKey: string;
+    signature: string;
+    contents: {
+        at: string;
+        publicKey: string;
+        purpose: "peers-key-contest";
+        userId: string;
+        pendingKey: string;
+    };
+}, {
+    publicKey: string;
+    signature: string;
+    contents: {
+        at: string;
+        publicKey: string;
+        purpose: "peers-key-contest";
+        userId: string;
+        pendingKey: string;
+    };
+}>;
+/**
+ * Signs a contest with the key on record.
+ *
+ * @param statement The user, the key on record, and the key being refused
+ * @param recordSecretKey Secret half of the key on record
+ */
+export declare function signKeyContest(statement: IKeyContestStatement, recordSecretKey: string): ISignedObject<IKeyContestStatement>;
+/**
+ * Checks that `signed` is the key on record objecting to `pendingKey`.
+ * A different signer, user, or pending key is not a contest.
+ */
+export declare function verifyKeyContest(params: {
+    signed: ISignedObject<IKeyContestStatement>;
+    userId: string;
+    recordPublicKey: string;
+    pendingKey: string;
+}): boolean;

package/dist/identity/key-contest.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.keyContestSignedSchema = exports.keyContestStatementSchema = exports.KEY_CONTEST_PURPOSE = void 0;
+exports.signKeyContest = signKeyContest;
+exports.verifyKeyContest = verifyKeyContest;
+const zod_1 = require("zod");
+const keys_1 = require("../keys");
+const zod_types_1 = require("../types/zod-types");
+/** Purpose string a holder of the key on record signs to object to a recovery. */
+exports.KEY_CONTEST_PURPOSE = "peers-key-contest";
+/** Statement that says the key on record did not ask for `pendingKey`. */
+exports.keyContestStatementSchema = zod_1.z.object({
+    purpose: zod_1.z.literal(exports.KEY_CONTEST_PURPOSE),
+    userId: zod_types_1.zodPeerId,
+    /** Key on record. The signature must be this key. */
+    publicKey: zod_1.z.string().min(1),
+    /** Key the anchors are offering without this key's co-signature. */
+    pendingKey: zod_1.z.string().min(1),
+    at: zod_1.z.string().min(1),
+});
+/** Signed contest carried in a handshake and posted to an anchor. */
+exports.keyContestSignedSchema = zod_1.z.object({
+    contents: exports.keyContestStatementSchema,
+    signature: zod_1.z.string(),
+    publicKey: zod_1.z.string(),
+});
+/**
+ * Signs a contest with the key on record.
+ *
+ * @param statement The user, the key on record, and the key being refused
+ * @param recordSecretKey Secret half of the key on record
+ */
+function signKeyContest(statement, recordSecretKey) {
+    const parsed = exports.keyContestStatementSchema.parse(statement);
+    return (0, keys_1.signObjectWithSecretKey)(parsed, recordSecretKey);
+}
+/**
+ * Checks that `signed` is the key on record objecting to `pendingKey`.
+ * A different signer, user, or pending key is not a contest.
+ */
+function verifyKeyContest(params) {
+    if (params.signed.publicKey !== params.recordPublicKey)
+        return false;
+    try {
+        const contents = (0, keys_1.openSignedObject)(params.signed);
+        const parsed = exports.keyContestStatementSchema.safeParse(contents);
+        return (parsed.success &&
+            parsed.data.userId === params.userId &&
+            parsed.data.publicKey === params.recordPublicKey &&
+            parsed.data.pendingKey === params.pendingKey);
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,55 @@
+import { z } from "zod";
+import type { DataContext } from "../context/data-context";
+/**
+ * Local memory of a key this device has been shown and has not yet accepted.
+ * `firstSeenAt` is when *this* device first saw the presented key. The table is
+ * `localOnly` so that moment is not copied to another device.
+ */
+export declare const keyResolutionSchema: z.ZodObject<{
+    resolutionId: z.ZodEffects<z.ZodString, string, string>;
+    userId: z.ZodEffects<z.ZodString, string, string>;
+    presentedKey: z.ZodString;
+    /** ISO 8601. When this device first saw `presentedKey`. */
+    firstSeenAt: z.ZodString;
+    /** ISO 8601. When the anchors were last fetched for this row. */
+    lastCheckedAt: z.ZodString;
+    state: z.ZodEnum<["pending", "vetoed", "confirmed-rotation", "confirmed-recovery"]>;
+    successionByRecordKey: z.ZodBoolean;
+    contested: z.ZodBoolean;
+    /** How long this answer may be reused, in seconds. */
+    cacheSeconds: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    state: "pending" | "vetoed" | "confirmed-rotation" | "confirmed-recovery";
+    userId: string;
+    resolutionId: string;
+    presentedKey: string;
+    firstSeenAt: string;
+    lastCheckedAt: string;
+    successionByRecordKey: boolean;
+    contested: boolean;
+    cacheSeconds: number;
+}, {
+    state: "pending" | "vetoed" | "confirmed-rotation" | "confirmed-recovery";
+    userId: string;
+    resolutionId: string;
+    presentedKey: string;
+    firstSeenAt: string;
+    lastCheckedAt: string;
+    successionByRecordKey: boolean;
+    contested: boolean;
+    cacheSeconds: number;
+}>;
+/** One local resolution of a presented key. */
+export type IKeyResolution = z.infer<typeof keyResolutionSchema>;
+/** Returns the local key-resolution table for a data context. */
+export declare function KeyResolutions(dataContext?: DataContext): import("..").Table<{
+    state: "pending" | "vetoed" | "confirmed-rotation" | "confirmed-recovery";
+    userId: string;
+    resolutionId: string;
+    presentedKey: string;
+    firstSeenAt: string;
+    lastCheckedAt: string;
+    successionByRecordKey: boolean;
+    contested: boolean;
+    cacheSeconds: number;
+}>;

package/dist/identity/key-resolutions.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.keyResolutionSchema = void 0;
+exports.KeyResolutions = KeyResolutions;
+const zod_1 = require("zod");
+const user_context_singleton_1 = require("../context/user-context-singleton");
+const table_definitions_system_1 = require("../data/orm/table-definitions.system");
+const types_1 = require("../data/orm/types");
+const zod_types_1 = require("../types/zod-types");
+const anchor_resolution_1 = require("./anchor-resolution");
+/**
+ * Local memory of a key this device has been shown and has not yet accepted.
+ * `firstSeenAt` is when *this* device first saw the presented key. The table is
+ * `localOnly` so that moment is not copied to another device.
+ */
+exports.keyResolutionSchema = zod_1.z.object({
+    resolutionId: zod_types_1.zodPeerId,
+    userId: zod_types_1.zodPeerId,
+    presentedKey: zod_1.z.string(),
+    /** ISO 8601. When this device first saw `presentedKey`. */
+    firstSeenAt: zod_1.z.string(),
+    /** ISO 8601. When the anchors were last fetched for this row. */
+    lastCheckedAt: zod_1.z.string(),
+    state: zod_1.z.enum(anchor_resolution_1.KEY_RESOLUTION_STATES),
+    successionByRecordKey: zod_1.z.boolean(),
+    contested: zod_1.z.boolean(),
+    /** How long this answer may be reused, in seconds. */
+    cacheSeconds: zod_1.z.number(),
+});
+const metaData = {
+    name: "KeyResolutions",
+    description: "Local cache of key changes waiting on anchors",
+    primaryKeyName: "resolutionId",
+    fields: (0, types_1.schemaToFields)(exports.keyResolutionSchema),
+    indexes: [{ fields: ["userId", "presentedKey"], unique: true }],
+    localOnly: true,
+};
+(0, table_definitions_system_1.registerSystemTableDefinition)(metaData, exports.keyResolutionSchema);
+/** Returns the local key-resolution table for a data context. */
+function KeyResolutions(dataContext) {
+    return (0, user_context_singleton_1.getTableContainer)(dataContext).getTable(metaData, exports.keyResolutionSchema);
+}

package/dist/identity/passkey.d.ts

@@ -0,0 +1,22 @@
+import { type ISignedObject } from "../keys";
+/** Purpose string the current key signs to start registering a passkey. */
+export declare const ACCOUNT_PASSKEY_REGISTER_PURPOSE: "peers-account-passkey-register";
+/** Statement the current key signs so a passkey can be bound. */
+export interface IAccountPasskeyRegisterStatement {
+    purpose: typeof ACCOUNT_PASSKEY_REGISTER_PURPOSE;
+    userId: string;
+    issuedAt: string;
+}
+/**
+ * Signs a request to start passkey registration for `userId`.
+ *
+ * @param statement The user and when the request was made
+ * @param secretKey Secret half of the key on record
+ */
+export declare function signPasskeyRegister(statement: IAccountPasskeyRegisterStatement, secretKey: string): ISignedObject<IAccountPasskeyRegisterStatement>;
+/** Checks that `signed` is the record key starting passkey registration. */
+export declare function verifyPasskeyRegister(params: {
+    signed: ISignedObject<IAccountPasskeyRegisterStatement>;
+    userId: string;
+    recordPublicKey: string;
+}): boolean;

package/dist/identity/passkey.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ACCOUNT_PASSKEY_REGISTER_PURPOSE = void 0;
+exports.signPasskeyRegister = signPasskeyRegister;
+exports.verifyPasskeyRegister = verifyPasskeyRegister;
+const keys_1 = require("../keys");
+/** Purpose string the current key signs to start registering a passkey. */
+exports.ACCOUNT_PASSKEY_REGISTER_PURPOSE = "peers-account-passkey-register";
+/**
+ * Signs a request to start passkey registration for `userId`.
+ *
+ * @param statement The user and when the request was made
+ * @param secretKey Secret half of the key on record
+ */
+function signPasskeyRegister(statement, secretKey) {
+    return (0, keys_1.signObjectWithSecretKey)({
+        purpose: exports.ACCOUNT_PASSKEY_REGISTER_PURPOSE,
+        userId: statement.userId,
+        issuedAt: statement.issuedAt,
+    }, secretKey);
+}
+/** Checks that `signed` is the record key starting passkey registration. */
+function verifyPasskeyRegister(params) {
+    if (params.signed.publicKey !== params.recordPublicKey)
+        return false;
+    try {
+        const contents = (0, keys_1.openSignedObject)(params.signed);
+        return (contents.purpose === exports.ACCOUNT_PASSKEY_REGISTER_PURPOSE && contents.userId === params.userId);
+    }
+    catch {
+        return false;
+    }
+}

package/dist/identity/user-row-change.d.ts

@@ -0,0 +1,45 @@
+import type { DataContext } from "../context/data-context";
+import { type IUser } from "../data/users";
+/**
+ * What to do with a `Users` row that differs from the one already stored.
+ *
+ * - `apply`: write `row`. Its `anchors` may have been replaced by the list on record.
+ * - `defer`: the anchors on record have not answered yet; keep the stored row and try again.
+ * - `refuse`: the anchors on record vetoed the key; keep the stored row and stop.
+ */
+export type UserRowChangeDecision = {
+    action: "apply";
+    row: IUser;
+} | {
+    action: "defer";
+    reason: string;
+} | {
+    action: "refuse";
+    reason: string;
+};
+/** Inputs for {@link resolveUserRowChange}. */
+export interface ResolveUserRowChangeParams {
+    /** Personal data context: where the on-record row and the resolution cache live. */
+    personalContext: DataContext;
+    /** The row already stored in the table being written, if any. */
+    existing: IUser | undefined;
+    /** The row that wants to replace it. Not mutated. */
+    incoming: IUser;
+}
+/**
+ * The one decision for every path that writes another user's `Users` row: a direct save, a
+ * group row, or a row reconstructed from a synced change log.
+ *
+ * The record is the personal `Users` row when it exists, else the row already stored in the
+ * table being written. The rule:
+ *
+ * - Nothing stored yet: the row is the bootstrap and is applied as it is.
+ * - A different key: the anchors on record decide ({@link evaluatePresentedKey}). The
+ *   presented anchor list is ignored; the applied row keeps the list on record.
+ * - The same key and a different list: when nothing is on record the list is accepted as the
+ *   bootstrap (an upgraded contact announcing its first anchors); when the personal record
+ *   already holds the list it is accepted; otherwise the anchors on record must publish it
+ *   ({@link evaluatePresentedAnchors}). A veto keeps the profile fields and the list on record,
+ *   because the row is still signed by the key on record and only the list is unproven.
+ */
+export declare function resolveUserRowChange(params: ResolveUserRowChangeParams): Promise<UserRowChangeDecision>;

package/dist/identity/user-row-change.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveUserRowChange = resolveUserRowChange;
+const users_1 = require("../data/users");
+const anchor_resolution_1 = require("./anchor-resolution");
+const key_change_1 = require("./key-change");
+function withAnchors(row, anchors) {
+    if ((0, anchor_resolution_1.sameAnchorList)(row.anchors, anchors))
+        return row;
+    if (!anchors?.length) {
+        const { anchors: _dropped, ...rest } = row;
+        return rest;
+    }
+    return { ...row, anchors };
+}
+/**
+ * The one decision for every path that writes another user's `Users` row: a direct save, a
+ * group row, or a row reconstructed from a synced change log.
+ *
+ * The record is the personal `Users` row when it exists, else the row already stored in the
+ * table being written. The rule:
+ *
+ * - Nothing stored yet: the row is the bootstrap and is applied as it is.
+ * - A different key: the anchors on record decide ({@link evaluatePresentedKey}). The
+ *   presented anchor list is ignored; the applied row keeps the list on record.
+ * - The same key and a different list: when nothing is on record the list is accepted as the
+ *   bootstrap (an upgraded contact announcing its first anchors); when the personal record
+ *   already holds the list it is accepted; otherwise the anchors on record must publish it
+ *   ({@link evaluatePresentedAnchors}). A veto keeps the profile fields and the list on record,
+ *   because the row is still signed by the key on record and only the list is unproven.
+ */
+async function resolveUserRowChange(params) {
+    const { existing, incoming, personalContext } = params;
+    if (!existing?.publicKey)
+        return { action: "apply", row: incoming };
+    const personal = await (0, users_1.Users)(personalContext).get(incoming.userId);
+    const record = personal?.publicKey ? personal : existing;
+    const recordAnchors = personal?.anchors?.length ? personal.anchors : (existing.anchors ?? []);
+    if (incoming.publicKey !== existing.publicKey) {
+        const decision = await (0, key_change_1.evaluatePresentedKey)({
+            dataContext: personalContext,
+            userId: incoming.userId,
+            presentedKey: incoming.publicKey,
+            presentedBoxKey: incoming.publicBoxKey,
+            record,
+        });
+        if (decision.accepted) {
+            // The resolver may have just stored a confirmed list on the personal row.
+            const confirmed = await (0, users_1.Users)(personalContext).get(incoming.userId);
+            const anchors = confirmed?.anchors?.length ? confirmed.anchors : recordAnchors;
+            return { action: "apply", row: withAnchors(incoming, anchors) };
+        }
+        if (decision.state === "pending" || decision.state === "recovery-pending") {
+            return { action: "defer", reason: "Key change is not confirmed by the anchors on record" };
+        }
+        return { action: "refuse", reason: "Key change is not confirmed by the anchors on record" };
+    }
+    if ((0, anchor_resolution_1.sameAnchorList)(existing.anchors, incoming.anchors))
+        return { action: "apply", row: incoming };
+    if (recordAnchors.length === 0)
+        return { action: "apply", row: incoming };
+    if ((0, anchor_resolution_1.sameAnchorList)(personal?.anchors, incoming.anchors)) {
+        return { action: "apply", row: incoming };
+    }
+    const verdict = await (0, key_change_1.evaluatePresentedAnchors)({
+        dataContext: personalContext,
+        userId: incoming.userId,
+        recordAnchors,
+        presentedAnchors: incoming.anchors ?? [],
+    });
+    if (verdict === "confirmed")
+        return { action: "apply", row: incoming };
+    if (verdict === "pending") {
+        return {
+            action: "defer",
+            reason: "Anchor list change is not confirmed by the anchors on record",
+        };
+    }
+    return { action: "apply", row: withAnchors(incoming, recordAnchors) };
+}
+(0, users_1.setUserRowChangeGuard)((personalContext, incoming, existing) => resolveUserRowChange({ personalContext, incoming, existing }));

package/dist/index.d.ts

@@ -17,6 +17,15 @@ export * from "./device/tx-encoding";
 export * from "./device-pairing";
 export * from "./events";
 export * from "./hlc";
+export * from "./host-credentials";
+export * from "./identity/account-email";
+export * from "./identity/anchor-document";
+export * from "./identity/anchor-resolution";
+export * from "./identity/key-change";
+export * from "./identity/key-contest";
+export * from "./identity/key-resolutions";
+export * from "./identity/passkey";
+export * from "./identity/user-row-change";
 export * from "./invites";
 export * from "./keys";
 export * from "./logging";

package/dist/index.js

@@ -38,6 +38,15 @@ __exportStar(require("./device/tx-encoding"), exports);
 __exportStar(require("./device-pairing"), exports);
 __exportStar(require("./events"), exports);
 __exportStar(require("./hlc"), exports);
+__exportStar(require("./host-credentials"), exports);
+__exportStar(require("./identity/account-email"), exports);
+__exportStar(require("./identity/anchor-document"), exports);
+__exportStar(require("./identity/anchor-resolution"), exports);
+__exportStar(require("./identity/key-change"), exports);
+__exportStar(require("./identity/key-contest"), exports);
+__exportStar(require("./identity/key-resolutions"), exports);
+__exportStar(require("./identity/passkey"), exports);
+__exportStar(require("./identity/user-row-change"), exports);
 __exportStar(require("./invites"), exports);
 __exportStar(require("./keys"), exports);
 __exportStar(require("./logging"), exports);