@joe-broadhead/messaging 0.7.1 → 0.9.0

package/dist/types/core/consent.d.ts

@@ -1,6 +1,7 @@
 import type { Identity } from "./identity.js";
 import { type MachineId, type PersonId, type Ulid } from "./schema/common.js";
 import { type AgentMailLevel, type AskLevel, type ChatLevel, ConsentGrant, type GrantLevels, type GrantSubject } from "./schema/consent.js";
+import type { ReachValue } from "./schema/ipc/consent.js";
 import type { RealmId } from "./schema/realm.js";
 export interface ConsentGrantArgs {
     realm: RealmId;
@@ -25,6 +26,22 @@ export declare function verifyConsentGrant(raw: unknown, ctx: {
 }): ConsentGrant;
 /** The key one grant is stored under: its subject. One grant per subject. */
 export declare function grantSubjectKey(subject: GrantSubject): string;
+/**
+ * The person's two reach choices, from their relation grants. `message` ("Who can message you") is the `outside`
+ * grant's `chat`: `open`, `blocked` (Never), or a grant with no level (Ask me first). `ask` ("How agents may ask
+ * yours") is the `org` grant's `ask`: `open`, `request` (Ask me first), `no` (Never). Absent: no grant, the defaults.
+ */
+export interface ReachChoices {
+    message?: ReachValue;
+    ask?: ReachValue;
+}
+/** The choices a person's two relation grants make; a grant absent (or not current) leaves its choice unset. */
+export declare function reachChoices(outside: GrantLevels | undefined, org: GrantLevels | undefined): ReachChoices;
+/** The relation grant subject and levels that record one choice: the inverse of `reachChoices`. */
+export declare function reachGrant(group: keyof ReachChoices, value: ReachValue): {
+    subject: GrantSubject;
+    levels: GrantLevels;
+};
 /**
  * Of two copies of the grant for one subject, the one that counts (spec §6.9, "Merging"): the newer by `ts`, then
  * by `id`. Copies that tie on both are one grant signed twice: a copy whose signer is current beats one whose
@@ -67,10 +84,11 @@ export interface EffectivePolicy {
 }
 /**
  * Spec §6.9, "Effective policy": each level is the person grant's when it sets one; otherwise, for `ask` and
- * `agentMail`, the most permissive among the grants of channels the sender is in; otherwise the relation's
- * default. An expired `trustedUntil` reads as absent. The caller passes only grants whose signer is current.
+ * `agentMail`, the most permissive among the grants of channels the sender is in; otherwise the relation's level
+ * under the person's reach choices (`baseLevels`). An expired `trustedUntil` reads as absent. The caller passes only
+ * grants whose signer is current.
  */
-export declare function effectivePolicy(relation: Exclude<Relation, "self">, person: GrantLevels | undefined, channels: readonly GrantLevels[], now: number): EffectivePolicy;
+export declare function effectivePolicy(relation: Exclude<Relation, "self">, person: GrantLevels | undefined, channels: readonly GrantLevels[], now: number, reach?: ReachChoices): EffectivePolicy;
 /**
  * What arrived, classified by the receiver (spec §6.9, "Enforcement"):
  * - `answer`: a receipt, a task update or cancel, or a message the counterpart binding ties to this person's own
@@ -114,6 +132,8 @@ export interface DecideArgs {
     grant?: GrantLevels;
     /** Grants of channels the sender is in, in the receiver's own view, each with a current signer. */
     channels: readonly GrantLevels[];
+    /** The receiving person's reach choices (their current relation grants); absent, the relation defaults. */
+    reach?: ReachChoices;
     inbound: Inbound;
     now: number;
 }
@@ -121,12 +141,15 @@ export interface DecideArgs {
  * Spec §6.9, "Enforcement": step 10 of the receiver order (§5), before the inbound policy of §8.3.
  * - The person's own traffic is delivered as `self`.
  * - Answers to the person's own traffic are delivered whatever the grants, so a change never strands a task.
- * - A `blocked` chat level refuses every other class from the sender.
- * - A `stranger` reaches the person only through a level a grant opened; otherwise `request_required`.
+ * - A `blocked` chat level from the person grant refuses every other class from the sender.
+ * - A `blocked` chat level from the reach choice Never refuses the sender's lines, message requests and channel
+ *   changes, `refused`; agent mail and asks follow their own levels, so a grant that opened them still counts.
+ * - A `stranger` reaches the person only through a level a grant or a choice opened; otherwise `request_required`.
  * - Lines follow `chat` (person) or `agentMail` (agent); `muted` delivers silently.
  * - Asks follow `ask`: `open` delivers guarded, or trusted while the person grant trusts the sender and every person
  *   in the delegation chain is the sender or the receiver; `request` holds; `no` refuses, `request_required` when
- *   it is the default of a `contact` or a `stranger`.
- * - A message request from a `stranger` is held for the person to accept; from anyone else it is a DM line.
+ *   it is the default of a `contact` or a `stranger` and the person has not chosen Never for messages.
+ * - A message request is held for the person while `chat` is `request_required` (a `stranger` under Ask me first);
+ *   otherwise it is a DM line.
  */
 export declare function decide(args: DecideArgs): ConsentDecision;

package/dist/types/core/contact-card.d.ts

@@ -1,4 +1,4 @@
-import { type Relation } from "./consent.js";
+import { type ReachChoices, type Relation } from "./consent.js";
 import type { Identity } from "./identity.js";
 import { type PersonId, type Ulid } from "./schema/common.js";
 import { type CardCan, ContactCard, type GrantLevels } from "./schema/consent.js";
@@ -29,6 +29,6 @@ export declare function verifyContactCard(raw: unknown, ctx: {
 }): ContactCard;
 /**
  * What a card says for a sender of `relation` with the person grant `grant` (spec §6.9, "Contact cards"): the
- * person grant over the relation's defaults. Channel grants are not on a card: the sender knows its own channels.
+ * person grant over the relation's level under the person's reach choices. Channel grants are not on a card: the sender knows its own channels.
  */
-export declare function cardCan(relation: Exclude<Relation, "self">, grant: GrantLevels | undefined, now: number): CardCan;
+export declare function cardCan(relation: Exclude<Relation, "self">, grant: GrantLevels | undefined, now: number, reach?: ReachChoices): CardCan;

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;