@joe-broadhead/messaging 0.7.1 → 0.8.0

package/dist/types/core/conversation/event.d.ts

@@ -1,6 +1,6 @@
 import type { Identity } from "../identity.js";
 import { type Hash } from "../schema/common.js";
-import { type ConvEvent, type ConvEventHeader, type ConvId, type UnsignedConvEvent } from "../schema/conversation.js";
+import { type ConvAnyEvent, type ConvEventHeader, type ConvId, type UnsignedConvEvent } from "../schema/conversation.js";
 /** h(0) of `cid`'s log: SHA-256(DOMAIN.convGenesis ‖ JCS(cid)), base64url. */
 export declare function convGenesisHash(cid: ConvId): Hash;
 /** SHA-256(JCS(event)), the raw digest, as the chain links it. Throws `invalid_request` for non-I-JSON. */
@@ -10,13 +10,13 @@ export declare function convEntryHash(prev: Hash, event: unknown): Hash;
 /** `convEntryHash` from the event's digest: what a member checks for an entry whose content has expired. */
 export declare function convLinkHash(prev: Hash, digest: Uint8Array): Hash;
 /** The header of an event: everything but `body` and `sig`. JCS of it is the AAD of a sealed body. */
-export declare function convEventHeader(event: ConvEvent | Omit<ConvEvent, "sig"> | ConvEventHeader): ConvEventHeader;
+export declare function convEventHeader(event: ConvAnyEvent | Omit<ConvAnyEvent, "sig"> | ConvEventHeader): ConvEventHeader;
 /**
  * Checks that `raw` is I-JSON within `LIMITS.jsonDepth` and at most `LIMITS.convEventBytes` (`too_large`), that it
- * matches `ConvEvent`, and that `by.device` is a usable Ed25519 key. Returns a frozen JSON copy of the raw value, so
+ * matches `ConvAnyEvent` (an op, a msg or a key share), and that `by.device` is a usable Ed25519 key. Returns a frozen JSON copy of the raw value, so
  * the signature and the hash cover exactly what was received. The signature is not checked.
  */
-export declare function admitConvEvent(raw: unknown): ConvEvent;
+export declare function admitConvEvent(raw: unknown): ConvAnyEvent;
 /**
  * Signs an event (spec §16.4): `sig = Ed25519(by.device, DOMAIN.convEvent ‖ JCS(event without sig))`. `by.device`
  * must be `identity`'s machine. Refuses an event that fails the schema (`invalid_request`) or is over
@@ -26,11 +26,11 @@ export declare function signConvEvent<E extends UnsignedConvEvent>(identity: Ide
     sig: string;
 };
 /** True only for a valid signature by `event.by.device` over the event without `sig`. Never throws. */
-export declare function convEventSigned(event: ConvEvent): boolean;
+export declare function convEventSigned(event: ConvAnyEvent): boolean;
 /**
  * Admits `raw` (`admitConvEvent`) and checks its signature over the raw value (`bad_signature`). Membership and
  * authority are `ConvLog.apply`'s. Throws only MessagingError.
  */
-export declare function verifyConvEvent(raw: unknown): ConvEvent;
+export declare function verifyConvEvent(raw: unknown): ConvAnyEvent;
 /** Freezes a JSON value and everything in it, iteratively. */
 export declare function deepFreeze<T>(value: T): T;

package/dist/types/core/conversation/guest-invitation.d.ts

@@ -0,0 +1,8 @@
+import type { Identity } from "../identity.js";
+import { GuestInvitation } from "../schema/guest-invitation.js";
+import type { ConvLog } from "./log.js";
+/** The inviting device seals this preview to the invitee. No history or sender keys accompany it. */
+export declare function createGuestInvitation(log: ConvLog, to: string, identity: Identity, issuedAt: number, expiresAt: number): GuestInvitation;
+/** The accept event signs this same preview. Changed audience/policy/head requires a fresh preview. */
+export declare function verifyGuestInvitation(log: ConvLog, raw: unknown, to: string, at: number): GuestInvitation;
+export declare function guestHistoryExposure(history: "none" | "shared"): string;

package/dist/types/core/conversation/log.d.ts

@@ -1,7 +1,8 @@
 import type { AnchorRelation } from "../realm.js";
 import { type Hash, type MachineId, type PersonId } from "../schema/common.js";
-import { type AgentContext, type BridgePolicy, type ConvEvent, type ConvHead, type ConvId, type ConvKind, type ConvLogEntry, type ConvRole, type HistoryPolicy, type MsgKind, type ParticipantId, type Permit, type RekeyCause, type RespondTo, type Visibility } from "../schema/conversation.js";
+import { type AgentContext, type BridgePolicy, type ConvEvent, type ConvExpiredEntry, type ConvHead, type ConvId, type ConvKeysEvent, type ConvKind, type ConvLogEntry, type ConvRole, type HistoryPolicy, type MsgKind, type ParticipantId, type Permit, type RekeyCause, type RespondTo, type Visibility } from "../schema/conversation.js";
 import type { RealmId } from "../schema/realm.js";
+import type { RequestBinding } from "./requests.js";
 /** A participant at one position. */
 export interface ConvParticipant {
     p: ParticipantId;
@@ -80,6 +81,10 @@ export interface ConvLiveChecks {
     skewMs?: number;
     /** True when `device` is a current device of `person` in the realm (`unknown_device` otherwise). */
     isDevice?: (person: PersonId, device: MachineId) => boolean;
+    /** True only when the verified realm has removed this device. */
+    isRemovedDevice?: (device: MachineId) => boolean;
+    /** Retained identity history for portable request proofs, including historical devices. */
+    requestBinding?: RequestBinding;
     /** The org of `person`, for `join`, and for an add of a person who is not a guest (`forbidden`). */
     orgOf?: (person: PersonId) => string | undefined;
 }
@@ -88,11 +93,11 @@ export interface ConvApplyOptions {
     body?: unknown;
     live?: ConvLiveChecks;
 }
-/** An entry whose content the relay expired: its seq, its prev and the digest SHA-256(JCS(event)). */
-export interface ConvExpiredEntry {
-    seq: number;
-    prev: Hash;
-    digest: Hash;
+/** Local admission metadata, never part of an entry's signed wire representation. */
+interface ReplayEntry {
+    entry: unknown;
+    body?: unknown;
+    held?: boolean;
 }
 /**
  * A verified conversation log. Every method throws only MessagingError. Entries are kept as frozen copies of the
@@ -105,17 +110,16 @@ export declare class ConvLog {
     private constructor();
     /** An empty log of `cid` in `realm`: its head is {0, h(0)}. */
     static open(cid: ConvId, realm: RealmId): ConvLog;
-    /** Replays `entries` (each with the opened body of a `msg`, when the caller has it). Throws the first failure. */
-    static fromEntries(cid: ConvId, realm: RealmId, entries: {
-        entry: unknown;
-        body?: unknown;
-    }[]): ConvLog;
+    /** Replays a prefix; callers with a verified realm supply its removed-device check for every device rekey. */
+    static fromEntries(cid: ConvId, realm: RealmId, entries: ReplayEntry[], checks?: Pick<ConvLiveChecks, "isRemovedDevice" | "requestBinding">, onInvalidBody?: (seq: number) => void): ConvLog;
     head(): ConvHead;
     /** The last op's seq and hash, or {0, h(0)}: what an author puts in `opHead`. */
     opHead(): ConvHead;
     /** h(seq), for 0 ≤ seq ≤ head. */
     hashAt(seq: number): Hash | undefined;
     entries(): (ConvLogEntry | ConvExpiredEntry)[];
+    /** Held links are in the hash chain, but contribute neither state nor messages. */
+    held(): number[];
     /** The state at the head; undefined before `create`. */
     state(): ConvSnapshot | undefined;
     /** The state after the entry at `seq`, as a log holding only entries 1..seq has it. */
@@ -135,8 +139,19 @@ export declare class ConvLog {
      */
     apply(raw: unknown, options?: ConvApplyOptions): Hash;
     /**
-     * Appends an entry whose content the relay expired (spec §16.4, "Retention"), by its digest: the chain stays
-     * verifiable and the state does not change. An op is never expired: a later op head that names this seq fails.
+     * Appends a `msg` entry whose content the relay expired (spec §16.4, "Retention"), by its digest: the chain stays
+     * verifiable and the state does not change. The create (seq 1) never expires (`invalid_request`), nor does any op:
+     * a later op head that names this seq fails.
      */
     applyExpired(raw: ConvExpiredEntry): Hash;
+    /**
+     * Checks a key share against this log (spec §16.6); a share is not an entry, so nothing changes. In order: I-JSON,
+     * size and schema, realm and cid (`invalid_request`, `too_large`); the signature (`bad_signature`); the live checks
+     * given (`expired`, `unknown_device`); `by.agent` absent (`forbidden`); `opHead` names an op of this log
+     * (`conv_conflict`); then, in the state at `opHead`, the author's person is a member participant person
+     * (`not_member`) and the recipient's person a participant person (`forbidden`), and live, the recipient device is a
+     * current device of that person (`unknown_device`). Returns the frozen event.
+     */
+    checkShare(raw: unknown, live?: ConvLiveChecks): ConvKeysEvent;
 }
+export {};

package/dist/types/core/conversation/request-log.d.ts

@@ -0,0 +1,24 @@
+import { type RequestActivation } from "../schema/contact-request.js";
+import { type ConvLogEntry } from "../schema/conversation.js";
+import { type ConvApplyOptions, type ConvLog } from "./log.js";
+import { type RequestBinding } from "./requests.js";
+export interface RequestReservation {
+    proof: RequestActivation;
+    completed?: {
+        seq: number;
+        digest: string;
+    };
+}
+export interface RequestLogState {
+    required: boolean;
+    active: boolean;
+    reservations: Map<string, RequestReservation>;
+}
+/** Rebuilds permanent activation state even when imported messages have expired. */
+export declare function requestLogState(log: ConvLog, binding: RequestBinding): RequestLogState;
+/** Checks before appending. The relay also checks live org admission on create. No mutation on failure. */
+export declare function checkRequestEvent(log: ConvLog, raw: unknown, binding: RequestBinding, body?: unknown): void;
+/** Member admission seam for the cut-over engine; preserves wrapper authorship and verifies source separately. */
+export declare function applyRequestEntry(log: ConvLog, entry: ConvLogEntry, binding: RequestBinding, options?: ConvApplyOptions): string;
+/** Public author for a verified import, never the importing device. The renderer uses this only after admission. */
+export declare function importedRequestAuthor(log: ConvLog, id: string, binding: RequestBinding): string | undefined;

package/dist/types/core/conversation/request-seal.d.ts

@@ -0,0 +1,6 @@
+import type { Identity } from "../identity.js";
+import { RequestImport } from "../schema/contact-request.js";
+import { type ConvMsgEvent } from "../schema/conversation.js";
+import type { UnsealedMsg } from "./seal.js";
+export declare function sealRequestImport(identity: Identity, header: UnsealedMsg, body: RequestImport, mk: Uint8Array): ConvMsgEvent;
+export declare function openRequestImport(raw: unknown, mk: Uint8Array): RequestImport;

package/dist/types/core/conversation/requests.d.ts

@@ -0,0 +1,14 @@
+import type { Identity } from "../identity.js";
+import { ContactAuthorization, PortableRequest, RequestActivation, RequestDecision, RequestDescriptor, RequestOpening } from "../schema/contact-request.js";
+/** Retained, verified identity history must bind every proof's device to its person; absence fails closed. */
+export type RequestBinding = (person: string, device: string) => boolean;
+export declare const requestCommitment: (opening: RequestOpening) => string;
+export declare const requestDigest: (descriptor: RequestDescriptor) => string;
+export declare function verifyRequestDescriptor(raw: unknown, binding: RequestBinding): RequestDescriptor;
+export declare function verifyPortableRequest(raw: unknown, binding: RequestBinding): PortableRequest;
+export declare function createPortableRequest(identity: Identity, args: Omit<RequestDescriptor, "by" | "sig" | "commitment">, text: string): PortableRequest;
+export declare function verifyRequestDecision(raw: unknown, descriptor: RequestDescriptor, binding: RequestBinding): RequestDecision;
+export declare function signRequestDecision(identity: Identity, d: RequestDescriptor, answer: RequestDecision["answer"], at: number): RequestDecision;
+export declare function verifyRequestActivation(raw: unknown, binding: RequestBinding): RequestActivation;
+export declare function signContactAuthorization(identity: Identity, args: Omit<ContactAuthorization, "sig" | "by">): ContactAuthorization;
+export declare function verifyContactAuthorization(raw: unknown, binding: RequestBinding): ContactAuthorization;

package/dist/types/core/conversation/seal.d.ts

@@ -1,6 +1,6 @@
 import type { Identity } from "../identity.js";
 import { type EncKey, type MachineId, type PersonId } from "../schema/common.js";
-import { type ConvKeysEvent, ConvMeta, type ConvMsgEvent, type ConvOpEvent, type KeyShare, MsgBody } from "../schema/conversation.js";
+import { type ConvKeysEvent, ConvMeta, type ConvMsgEvent, type ConvOp, type ConvOpEvent, type KeyShare, MsgBody, SettingBody } from "../schema/conversation.js";
 /** A message event before its body: the header its author signs, with `class: "msg"`. */
 export type UnsealedMsg = Omit<ConvMsgEvent, "body" | "sig">;
 /** A keys event before its body. */
@@ -33,15 +33,38 @@ export declare function sealConvMetaWith(header: Omit<ConvOpEvent, "body" | "sig
 /** Opens a `create` event's `sealedMeta`. Errors as for `openConvMsg`; `not_found` when it has none. */
 export declare function openConvMeta(event: ConvOpEvent, mk0: Uint8Array): ConvMeta;
 /**
- * Seals `shares` to each recipient device as the body of `unsealed`, and signs the event. One sealed share per
- * device; at most `LIMITS.keySharesPerEvent` devices and `LIMITS.keyShares` chain keys. Throws only MessagingError.
+ * Seals `shares` to one recipient device as the body of `unsealed`, and signs the event: one `keys` event per
+ * recipient device (spec §16.6), at most `LIMITS.keyShares` chain keys. Throws only MessagingError.
  */
-export declare function sealKeyShares(identity: Identity, unsealed: UnsealedKeys, recipients: ShareRecipient[], shares: KeyShare[]): ConvKeysEvent;
-/** `sealKeyShares` with fixed randomness per recipient, in order: for test vectors only. */
-export declare function sealKeySharesWith(identity: Identity, unsealed: UnsealedKeys, recipients: ShareRecipient[], shares: KeyShare[], randomness: ShareRandomness[]): ConvKeysEvent;
+export declare function sealKeyShare(identity: Identity, unsealed: UnsealedKeys, recipient: ShareRecipient, shares: KeyShare[]): ConvKeysEvent;
+/** `sealKeyShare` with fixed randomness: for test vectors only. */
+export declare function sealKeyShareWith(identity: Identity, unsealed: UnsealedKeys, recipient: ShareRecipient, shares: KeyShare[], randomness: ShareRandomness): ConvKeysEvent;
 /**
- * Opens the share sealed to `identity`'s device in a `keys` event: `not_found` when there is none, `bad_signature`
- * when it fails to open, `invalid_request` when the plaintext is not a share payload. The caller has verified the
- * event's signature and applied it to the log.
+ * Opens a `keys` event sealed to `identity`'s device: `not_found` when it is another device's, `bad_signature` when it
+ * fails to open, `invalid_request` when the plaintext is not a share payload. The caller has checked the event
+ * (`ConvLog.checkShare`).
  */
 export declare function openKeyShares(event: ConvKeysEvent, identity: Identity): KeyShare[];
+/** A sealed op as its author builds it: the op without `sealed`. */
+export type UnsealedStateOp = Omit<Extract<ConvOp, {
+    op: "meta";
+}>, "sealed"> | Omit<Extract<ConvOp, {
+    op: "setting";
+}>, "sealed">;
+/** An op event before its body is sealed: the header and the op without `sealed`. */
+export type UnsealedOpEvent = Omit<ConvOpEvent, "body" | "sig"> & {
+    body: UnsealedStateOp;
+};
+/**
+ * Seals `content` (a `ConvMeta` for `meta`, a `SettingBody` of the op's kind for `setting`) under `mk`, the author's
+ * message key at the op's (`epoch`, `idx`), and signs the op event. Throws only MessagingError.
+ */
+export declare function sealConvState(identity: Identity, unsealed: UnsealedOpEvent, content: unknown, mk: Uint8Array): ConvOpEvent;
+/** `sealConvState` with a caller-chosen nonce: for test vectors only. */
+export declare function sealConvStateWith(identity: Identity, unsealed: UnsealedOpEvent, content: unknown, mk: Uint8Array, nonce: Uint8Array): ConvOpEvent;
+/**
+ * Opens a `meta` or `setting` op with the author's message key at its (`epoch`, `idx`): a `ConvMeta`, or a
+ * `SettingBody` whose `s` is the op's `kind` (`invalid_request` otherwise). `not_found` for another op; errors as
+ * for `openConvMsg`. The caller has applied the event to the log.
+ */
+export declare function openConvState(event: ConvOpEvent, mk: Uint8Array): ConvMeta | SettingBody;