p2party 0.14.2 → 0.14.7

package/lib/blindRendezvous/admissionPolicy.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Internal, pure Section 4.8 admission-policy semantics.
+ *
+ * This module deliberately does not implement `Admit()`, trusted snapshot or
+ * custody capture, provenance brands, pair opening/binding, effectful
+ * persistence, outbound-intent atomicity, or the pre-SDP runtime gate. Its
+ * canonical codecs only preserve already-validated structural values; decoding
+ * bytes does not make a lease trusted or current. Structural inputs are useful
+ * only after a future trusted constructor has obtained the same facts
+ * atomically. Nothing here may turn a caller-supplied authority availability
+ * bit, digest, or revocation list into trusted state.
+ *
+ * The helpers do own the deterministic policy order and lease arithmetic once
+ * those facts are available. This file is not exported from the package barrel.
+ */
+import type { LibCrypto } from "../cryptography/libcrypto";
+import type { CoreFaultV1, CoreRevocationFloorV1 } from "./coreReduce";
+import type { AdmissionGrantV1 } from "./operationPayload";
+import type { RoomPolicyV4 } from "./roomPolicyV4";
+export type CanonicalBytes32SetV1 = readonly Uint8Array[];
+export interface FrontendRoomControlsV1 {
+    readonly version: 1;
+    readonly policyGeneration: bigint;
+    readonly onlyConnectWithKnownPeers: boolean;
+    readonly allowedStableIdentityKeys: CanonicalBytes32SetV1;
+    readonly deniedStableIdentityKeys: CanonicalBytes32SetV1;
+    readonly deniedRoomIdentityCommitments: CanonicalBytes32SetV1;
+}
+export interface AuthorityWindowFaultV1 {
+    readonly logicalWindow: bigint;
+    readonly proofOperationIds: readonly Uint8Array[];
+}
+/**
+ * Structural policy projection only. A future private authority-view
+ * constructor must derive this from a branded atomic snapshot. This interface
+ * and its digest field do not establish provenance.
+ */
+export interface AuthorityAdmissionPolicyViewV1 {
+    readonly version: 1;
+    readonly roomContextId: Uint8Array;
+    readonly stableIdentityCommitment: Uint8Array;
+    readonly referenceWindow: bigint;
+    readonly status: "available" | "unavailable";
+    readonly revocationFacts: readonly CoreRevocationFloorV1[];
+    readonly authorityAdmissionStateDigest: Uint8Array;
+}
+export interface PairAttemptLeaseV1 {
+    readonly version: 1;
+    readonly helloOperationId: Uint8Array;
+    readonly pairEdgeId: Uint8Array;
+    readonly endpointPresenceOperationIds: readonly [Uint8Array, Uint8Array];
+    readonly attemptMode: "planner" | "explicit";
+    readonly helloLogicalWindow: bigint;
+    readonly validThroughLogicalWindow: bigint;
+}
+export interface BootstrapAdmissionDecisionLeaseV1 {
+    readonly version: 1;
+    readonly roomContextId: Uint8Array;
+    readonly stableEd25519PublicKey: Uint8Array;
+    readonly stableIdentityCommitment: Uint8Array;
+    readonly grantId: Uint8Array | null;
+    readonly grantGeneration: bigint | null;
+    readonly localPolicyGeneration: bigint;
+    readonly authorityAdmissionStateDigest: Uint8Array | null;
+    readonly admittedPresenceOperationId: Uint8Array;
+    readonly admittedIdentityOperationId: Uint8Array;
+    readonly decidedAtLogicalWindow: bigint;
+    readonly validThroughLogicalWindow: bigint;
+}
+export interface StableEdgeAdmissionLeaseV1 {
+    readonly version: 1;
+    readonly roomContextId: Uint8Array;
+    readonly stableEdgeId: Uint8Array;
+    readonly confirmedPairTranscriptId: Uint8Array;
+    readonly rendezvousChannelId: Uint8Array;
+    readonly v4WireBinding: Uint8Array;
+    readonly remoteStableEd25519PublicKey: Uint8Array;
+    readonly remoteStableIdentityCommitment: Uint8Array;
+    readonly grantId: Uint8Array | null;
+    readonly grantGeneration: bigint | null;
+    readonly localPolicyGeneration: bigint;
+    readonly authorityAdmissionStateDigest: Uint8Array | null;
+    readonly decidedAtLogicalWindow: bigint;
+    readonly validThroughLogicalWindow: bigint | null;
+}
+export type AdmissionAllowReason = "open" | "address-book" | "authority-grant";
+export type AdmissionDenyReason = "blacklisted" | "not-in-address-book" | "missing-grant" | "invalid-grant" | "revoked" | "policy-unavailable";
+export interface AllowedPeerAdmissionPolicyV1 {
+    readonly result: "allow";
+    readonly reason: AdmissionAllowReason;
+    readonly localPolicyGeneration: bigint;
+    readonly grantId: Uint8Array | null;
+    readonly grantGeneration: bigint | null;
+    readonly authorityAdmissionStateDigest: Uint8Array | null;
+    readonly grantValidThroughLogicalWindow: bigint | null;
+}
+export interface DeniedPeerAdmissionPolicyV1 {
+    readonly result: "deny";
+    readonly reason: AdmissionDenyReason;
+}
+export type PeerAdmissionPolicyDecisionV1 = AllowedPeerAdmissionPolicyV1 | DeniedPeerAdmissionPolicyV1;
+export type PairAdmissionDecision = {
+    readonly result: "allow";
+    readonly reason: AdmissionAllowReason;
+    readonly bootstrapLease: BootstrapAdmissionDecisionLeaseV1;
+    readonly pairAttemptLease: PairAttemptLeaseV1;
+} | DeniedPeerAdmissionPolicyV1;
+export type StableEdgeAdmissionDecision = {
+    readonly result: "allow";
+    readonly reason: AdmissionAllowReason;
+    readonly lease: StableEdgeAdmissionLeaseV1;
+} | DeniedPeerAdmissionPolicyV1;
+/**
+ * Unbranded facts consumed by the semantic policy helper. Production code must
+ * obtain the corresponding values from `TrustedAdmissionSnapshotV1`; this type
+ * is intentionally not named or presented as that trusted snapshot.
+ */
+export interface PeerAdmissionPolicySemanticInputV1 {
+    readonly roomContextId: Uint8Array;
+    readonly roomPolicy: RoomPolicyV4;
+    readonly referenceWindow: bigint;
+    readonly frontendControls: FrontendRoomControlsV1 | null;
+    readonly authorityView: AuthorityAdmissionPolicyViewV1 | null;
+    readonly stableEd25519PublicKey: Uint8Array;
+    readonly stableIdentityCommitment: Uint8Array;
+    readonly optionalGrant: AdmissionGrantV1 | null;
+    readonly grantCarriedAtLogicalWindow: bigint | null;
+}
+export interface BootstrapAdmissionLeaseSemanticInputV1 {
+    readonly policy: AllowedPeerAdmissionPolicyV1;
+    readonly roomContextId: Uint8Array;
+    readonly stableEd25519PublicKey: Uint8Array;
+    readonly stableIdentityCommitment: Uint8Array;
+    readonly admittedPresenceOperationId: Uint8Array;
+    readonly admittedIdentityOperationId: Uint8Array;
+    readonly admittedIdentityOperationLogicalWindow: bigint;
+    readonly admittedIdentityOperationValidThroughLogicalWindow: bigint;
+    readonly admittedPresenceEvidenceRetainThroughLogicalWindow: bigint;
+    readonly basePairAttemptLease: PairAttemptLeaseV1;
+    readonly referenceWindow: bigint;
+}
+export interface StableEdgeAdmissionLeaseSemanticInputV1 {
+    readonly policy: AllowedPeerAdmissionPolicyV1;
+    readonly roomContextId: Uint8Array;
+    readonly stableEdgeId: Uint8Array;
+    readonly confirmedPairTranscriptId: Uint8Array;
+    readonly rendezvousChannelId: Uint8Array;
+    readonly v4WireBinding: Uint8Array;
+    readonly remoteStableEd25519PublicKey: Uint8Array;
+    readonly remoteStableIdentityCommitment: Uint8Array;
+    readonly referenceWindow: bigint;
+}
+export declare class AdmissionPolicySemanticError extends Error {
+    readonly name = "AdmissionPolicySemanticError";
+    constructor(message: string);
+}
+export declare const validateAndCopyFrontendRoomControlsV1: (value: unknown) => FrontendRoomControlsV1;
+/** Canonical bytes for one already-local frontend policy snapshot. */
+export declare const encodeFrontendRoomControlsV1: (value: unknown) => Uint8Array;
+/**
+ * Restore an owned structural snapshot. This does not establish frontend
+ * provenance or make the policy generation current.
+ */
+export declare const decodeFrontendRoomControlsV1: (bytes: Uint8Array) => FrontendRoomControlsV1;
+/** Membership over an already validated canonical byte set. */
+export declare const canonicalBytes32SetHas: (values: CanonicalBytes32SetV1, candidate: Uint8Array) => boolean;
+/**
+ * `ApplicableRevocationFacts(commitment, referenceWindow)` from Section 4.8.
+ * Input order and exact duplicate delivery do not affect the result.
+ */
+export declare const selectApplicableRevocationFacts: (facts: readonly CoreRevocationFloorV1[], stableIdentityCommitment: Uint8Array, referenceWindow: bigint) => readonly CoreRevocationFloorV1[];
+export declare const authorityFaultValidThrough: (roomPolicy: RoomPolicyV4, faultWindow: bigint) => bigint;
+export interface BlockingAuthorityWindowFaultSelectionV1 {
+    readonly blockingAuthorityWindowFaults: readonly AuthorityWindowFaultV1[];
+    readonly unavailableThroughLogicalWindow: bigint | null;
+}
+/**
+ * Select every still-blocking pinned-authority author-window fault. Custody
+ * saturation is intentionally absent; the future trusted view constructor must
+ * combine this selection with its protected custody projection.
+ */
+export declare const selectBlockingAuthorityWindowFaults: (faults: readonly CoreFaultV1[], roomPolicy: RoomPolicyV4, referenceWindow: bigint) => BlockingAuthorityWindowFaultSelectionV1;
+export declare const authorityGenerationAllowed: (generation: bigint, authorityView: Pick<AuthorityAdmissionPolicyViewV1, "status" | "revocationFacts">) => boolean;
+/**
+ * The one semantic policy order shared by future bootstrap and stable-edge
+ * wrappers. It intentionally does not verify trusted snapshot/view provenance.
+ */
+export declare const evaluatePeerAdmissionPolicySemantics: (input: PeerAdmissionPolicySemanticInputV1, module?: LibCrypto) => Promise<PeerAdmissionPolicyDecisionV1>;
+export declare const validateAndCopyPairAttemptLeaseV1: (value: unknown) => PairAttemptLeaseV1;
+/** Canonical durable bytes for one structurally valid pair-attempt lease. */
+export declare const encodePairAttemptLeaseV1: (value: unknown) => Uint8Array;
+/**
+ * Restore an owned structural pair-attempt lease. Callers must still bind it
+ * to the fresh trusted pair state before treating it as authority to act.
+ */
+export declare const decodePairAttemptLeaseV1: (bytes: Uint8Array) => PairAttemptLeaseV1;
+export declare const validateAndCopyBootstrapAdmissionDecisionLeaseV1: (value: unknown) => BootstrapAdmissionDecisionLeaseV1;
+/** Canonical durable bytes for one bootstrap admission decision lease. */
+export declare const encodeBootstrapAdmissionDecisionLeaseV1: (value: unknown) => Uint8Array;
+/**
+ * Restore an owned structural bootstrap lease. The decoded record is not a
+ * trusted admission decision until its bindings and freshness are rechecked.
+ */
+export declare const decodeBootstrapAdmissionDecisionLeaseV1: (bytes: Uint8Array) => BootstrapAdmissionDecisionLeaseV1;
+export declare const validateAndCopyAllowedPeerAdmissionPolicyV1: (value: unknown) => AllowedPeerAdmissionPolicyV1;
+/**
+ * Narrow the authenticated base pair-attempt horizon by the admitted grant,
+ * then construct both immutable bootstrap leases. A future trusted wrapper
+ * must verify every pair/presence coordinate before calling this semantic
+ * helper and must persist only this returned pair-attempt lease.
+ */
+export declare const constructBootstrapAdmissionDecisionLease: (input: BootstrapAdmissionLeaseSemanticInputV1) => PairAdmissionDecision;
+/**
+ * Construct only the stable-edge lease/result after a future branded stable
+ * context and fresh trusted snapshot have passed the shared policy helper.
+ */
+export declare const constructStableEdgeAdmissionLease: (input: StableEdgeAdmissionLeaseSemanticInputV1) => StableEdgeAdmissionDecision;

package/lib/blindRendezvous/canonicalSchema.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Canonical binary schema: the single source of truth for blind-rendezvous
+ * wire bytes.
+ *
+ * Section 4 of the L2/L3 blind-rendezvous specification writes `Canonical(x)`
+ * for "the unique encoding in the companion binary-schema artifact". This
+ * module is that artifact's executable form. It owns field order, integer
+ * widths, enum values, collection ordering, and bounds, so no other module may
+ * hand-roll a second encoding of the same value.
+ *
+ * Status: PROPOSED, NOT FROZEN. Phase 0 of the delivery roadmap freezes these
+ * widths and publishes deterministic vectors under one release-registry hash.
+ * Until that freeze and its external review, no hash derived from this module
+ * may be published as a v0.4 release artifact, and no interoperability claim
+ * follows from two implementations agreeing with it.
+ *
+ * The codec is descriptor-driven rather than hand-written per type. A
+ * descriptor is the SSOT: encoders, decoders, key tables, and bound checks are
+ * all derived from it, which is what makes the generated projections in
+ * `projections.ts` mechanically checkable instead of hand-maintained.
+ */
+export type Bytes32 = Uint8Array;
+/** Maximum entries in any bounded collection with a 16-bit count prefix. */
+export declare const MAX_U16_COLLECTION_ENTRIES = 65535;
+/** Bound on any canonical NFC text field, in UTF-8 bytes. */
+export declare const MAX_CANONICAL_TEXT_BYTES = 4096;
+/** Bound on a single canonically encoded value, in bytes. */
+export declare const MAX_CANONICAL_ENCODING_BYTES: number;
+export declare class CanonicalSchemaError extends Error {
+    readonly name = "CanonicalSchemaError";
+    readonly path: string;
+    constructor(path: string, message: string);
+}
+export interface FieldDescriptor {
+    readonly name: string;
+    readonly type: TypeDescriptor;
+}
+export type TypeDescriptor = {
+    readonly kind: "u8";
+} | {
+    readonly kind: "u16";
+} | {
+    readonly kind: "u32";
+} | {
+    readonly kind: "u64";
+} | {
+    readonly kind: "bool";
+} | {
+    readonly kind: "fixedBytes";
+    readonly length: number;
+} | {
+    readonly kind: "varBytes";
+    readonly maxLength: number;
+} | {
+    readonly kind: "text";
+    readonly maxBytes: number;
+} | {
+    readonly kind: "enum";
+    readonly name: string;
+    readonly values: readonly string[];
+} | {
+    readonly kind: "array";
+    readonly item: TypeDescriptor;
+    readonly maxEntries: number;
+    readonly ordering: "sorted-unique" | "sequence";
+} | {
+    readonly kind: "optional";
+    readonly value: TypeDescriptor;
+} | {
+    readonly kind: "record";
+    readonly name: string;
+    readonly fields: readonly FieldDescriptor[];
+} | {
+    readonly kind: "union";
+    readonly name: string;
+    readonly discriminant: string;
+    readonly variants: readonly {
+        readonly tag: string;
+        readonly type: TypeDescriptor;
+    }[];
+};
+export declare const u8: TypeDescriptor;
+export declare const u16: TypeDescriptor;
+export declare const u32: TypeDescriptor;
+export declare const u64: TypeDescriptor;
+export declare const bool: TypeDescriptor;
+export declare const fixedBytes: (length: number) => TypeDescriptor;
+export declare const bytes32: TypeDescriptor;
+export declare const bytes64: TypeDescriptor;
+export declare const varBytes: (maxLength: number) => TypeDescriptor;
+export declare const text: (maxBytes?: number) => TypeDescriptor;
+export declare const enumOf: (name: string, values: readonly string[]) => TypeDescriptor;
+export declare const array: (item: TypeDescriptor, maxEntries: number, ordering?: "sorted-unique" | "sequence") => TypeDescriptor;
+export declare const optional: (value: TypeDescriptor) => TypeDescriptor;
+export declare const record: (name: string, fields: readonly FieldDescriptor[]) => TypeDescriptor;
+export declare const union: (name: string, discriminant: string, variants: readonly {
+    readonly tag: string;
+    readonly type: TypeDescriptor;
+}[]) => TypeDescriptor;
+export declare const bytesEqual: (left: Uint8Array, right: Uint8Array) => boolean;
+/** The unique canonical encoding of `value` under `descriptor`. */
+export declare const encodeCanonical: (descriptor: TypeDescriptor, value: unknown, path?: string) => Uint8Array;
+/**
+ * Decode exactly one canonical value. Trailing bytes, non-minimal encodings,
+ * unknown enum/union tags, unsorted collections, and out-of-bound lengths are
+ * rejected rather than repaired.
+ */
+export declare const decodeCanonical: (descriptor: TypeDescriptor, bytes: Uint8Array, path?: string) => unknown;
+/**
+ * Decode, then prove the result re-encodes to the exact input bytes. Callers
+ * at a security boundary use this so a value that decodes but is not the
+ * unique encoding of itself can never be accepted.
+ */
+export declare const decodeCanonicalStrict: (descriptor: TypeDescriptor, bytes: Uint8Array, path?: string) => unknown;
+export declare const descriptorName: (descriptor: TypeDescriptor) => string;
+/**
+ * The exact field-name projection of a record descriptor, in wire order.
+ *
+ * Section 1.4 makes generated projections mandatory: a hand-maintained key
+ * table that disagrees with the schema is a release failure. Consumers import
+ * this instead of restating field names.
+ */
+export declare const recordFieldNames: (descriptor: TypeDescriptor) => readonly string[];
+/**
+ * The complete field list of a record descriptor.
+ *
+ * A signed wire type is its body plus a signature, so it reuses the body's
+ * fields rather than restating them — the signature transcript is exactly the
+ * body encoding, and a divergence between the two lists would be silent.
+ */
+export declare const recordFields: (descriptor: TypeDescriptor) => readonly FieldDescriptor[];
+/** The descriptor of one named field of a record descriptor. */
+export declare const recordFieldType: (descriptor: TypeDescriptor, fieldName: string) => TypeDescriptor;
+/** The descriptor of one named variant of a union descriptor. */
+export declare const unionVariantType: (descriptor: TypeDescriptor, tag: string) => TypeDescriptor;
+/** The exact enum-value projection, in wire-byte order. */
+export declare const enumValues: (descriptor: TypeDescriptor) => readonly string[];
+/** The wire byte assigned to one enum member. */
+export declare const enumByte: (descriptor: TypeDescriptor, value: string) => number;

package/lib/blindRendezvous/carrierEnvelope.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Carrier-separated envelope framing (Section 4.5).
+ *
+ * The same logical operation is wrapped independently for every carrier
+ * context, with carrier-domain-separated keys and nonce material, so two
+ * stores never receive byte-identical ciphertext or a common object
+ * identifier. A client deduplicates the rewrapped copies by the private
+ * `OperationId` after decryption — an identifier a store never sees.
+ *
+ * ## The sealing primitive
+ *
+ * `carrierAeadSuite = 1` is the frozen XChaCha20-Poly1305 construction from
+ * `draft-irtf-cfrg-xchacha-03` with a 32-byte key, 24-byte nonce, and 16-byte
+ * tag. `createCarrierAeadProvider` binds it from the pinned libsodium build.
+ *
+ * The AEAD stays an injected provider rather than a direct import for two
+ * reasons: a caller must supply an initialized WASM module anyway, and a build
+ * that lacks the export fails closed with a typed error instead of silently
+ * sealing under some other construction. Substituting a different AEAD, or
+ * composing XChaCha20 in TypeScript, remains forbidden by SEC-002 and SEC-019.
+ */
+import type { LibCrypto } from "../cryptography/libcrypto";
+import type { CarrierEnvelopeCoordinates } from "./derivations";
+export declare const CARRIER_ENVELOPE_VERSION = 1;
+export declare const CARRIER_AEAD_SUITE_1_KEY_BYTES = 32;
+export declare const CARRIER_AEAD_SUITE_1_NONCE_BYTES = 24;
+export declare const CARRIER_AEAD_SUITE_1_TAG_BYTES = 16;
+export interface CarrierEnvelopeV1 {
+    version: 1;
+    deliveryProfileHash: Uint8Array;
+    ingressWindow: bigint;
+    sizeClass: number;
+    carrierContextId: Uint8Array;
+    nonce: Uint8Array;
+    ciphertextAndTag: Uint8Array;
+}
+export interface CarrierPlaintextV1 {
+    /** Exact canonical signed operation bytes, identical across carriers. */
+    operationBytes: Uint8Array;
+    /** Fills this profile's carrier size class. */
+    carrierPadding: Uint8Array;
+}
+/**
+ * The exact AEAD required by `carrierAeadSuite = 1`.
+ *
+ * An implementation must be XChaCha20-Poly1305 with the stated key, nonce, and
+ * tag sizes. `open` returns null — never a partial or unauthenticated
+ * plaintext — on any tag, length, or associated-data failure.
+ */
+export interface CarrierAeadProvider {
+    readonly suite: 1;
+    seal(key: Uint8Array, nonce: Uint8Array, associatedData: Uint8Array, plaintext: Uint8Array): Promise<Uint8Array>;
+    open(key: Uint8Array, nonce: Uint8Array, associatedData: Uint8Array, ciphertextAndTag: Uint8Array): Promise<Uint8Array | null>;
+}
+export declare class CarrierAeadUnavailableError extends Error {
+    readonly name = "CarrierAeadUnavailableError";
+    readonly code = "carrier-aead-suite-1-unavailable";
+    readonly suite = 1;
+    constructor();
+}
+export declare class CarrierEnvelopeError extends Error {
+    readonly name = "CarrierEnvelopeError";
+    constructor(message: string);
+}
+/**
+ * The conforming `carrierAeadSuite = 1` provider, bound to an initialized
+ * cryptography module.
+ */
+export declare const createCarrierAeadProvider: (module: LibCrypto) => CarrierAeadProvider;
+/**
+ * Build the canonical carrier plaintext, padded to the profile's size class.
+ *
+ * Padding is what makes real and dummy objects the same length; a caller that
+ * skipped it would publish a length that varies with the operation.
+ */
+export declare const buildCarrierPlaintext: (operationBytes: Uint8Array, fixedCarrierObjectBytes: number) => CarrierPlaintextV1;
+/**
+ * Seal one operation for one carrier context.
+ *
+ * The nonce is sampled by the caller per `(OperationId, profile, context,
+ * ingressWindow, sizeClass)` wrap slot and persisted with the envelope before
+ * first publication, so an exact retry resends the same bytes rather than
+ * re-encrypting under a fresh nonce.
+ */
+export declare const sealCarrierEnvelope: (roomRootBytes: Uint8Array, coordinates: CarrierEnvelopeCoordinates, nonce: Uint8Array, plaintext: CarrierPlaintextV1, provider: CarrierAeadProvider | null) => Promise<CarrierEnvelopeV1>;
+/**
+ * Open an envelope, returning null when it is not for this room.
+ *
+ * A dummy is indistinguishable from a real object at this layer by
+ * construction: it has the same public header and body length and simply fails
+ * authentication, so the caller must treat null as "not mine", never as
+ * evidence of a fault.
+ */
+export declare const openCarrierEnvelope: (roomRootBytes: Uint8Array, envelope: CarrierEnvelopeV1, provider: CarrierAeadProvider | null) => Promise<CarrierPlaintextV1 | null>;
+/** The exact canonical encoding of an envelope, as published to a carrier. */
+export declare const encodeCarrierEnvelope: (envelope: CarrierEnvelopeV1) => Uint8Array;
+export declare const decodeCarrierEnvelope: (encoded: Uint8Array) => CarrierEnvelopeV1;
+/** `CarrierObjectId`, meaningful only inside one carrier context. */
+export declare const deriveCarrierObjectId: (envelope: CarrierEnvelopeV1) => Promise<Uint8Array>;
+/**
+ * Two envelopes of the same operation for different carrier contexts must not
+ * share ciphertext or object identifier. Exposed so the carrier-separation
+ * requirement is testable rather than assumed.
+ */
+export declare const envelopesAreCarrierSeparated: (left: CarrierEnvelopeV1, right: CarrierEnvelopeV1) => boolean;

package/lib/blindRendezvous/coreReduce.d.ts

@@ -0,0 +1,199 @@
+/**
+ * Deterministic outer-layer reduction (Section 4.7).
+ *
+ * `Merge` is set union and `CoreReduce` is a pure function of the validated
+ * operation set, the immutable room policy, and an explicit reference window.
+ * It reads no arrival timestamp, server identity, fetch order, frontend
+ * allow/deny state, planner preference, wall clock, "first response" state,
+ * pair secret, or inner pair validity — that exclusion list is the whole
+ * reason two honest clients with the same delivered set derive byte-identical
+ * state no matter which carrier delivered what, in which order.
+ *
+ * The reducer consumes only process-private results of the validation ingress.
+ * It integrates payload facts only after arrival-independent author
+ * fork/quota classification, then applies semantic-slot/dependency rules and
+ * emits the exact CoreRoomStateV1 projections. Frontend admission, route
+ * activation, planner preference, and pair plaintext remain outside this
+ * room-wide state.
+ */
+import type { LibCrypto } from "../cryptography/libcrypto";
+import type { AuthenticatedRoomOperationV1, OperationValidationContext } from "./operation";
+import type { PresenceV1 } from "./operationPayload";
+import type { PairStepEnvelopeV1 } from "./pairStepEnvelope";
+import type { RoomPolicyV4 } from "./roomPolicyV4";
+import type { StoreDescriptorV1, StoreRouteV1 } from "./storeDescriptor";
+declare const outerValidatedIdentifiedOperationBrand: unique symbol;
+declare const activePairOperationCandidateBrand: unique symbol;
+/**
+ * Process-local proof that one exact PAIR_STEP was active in one genuine
+ * CoreReduce result. It intentionally exposes no structural fields.
+ */
+export interface ActivePairOperationCandidateV1 {
+    readonly [activePairOperationCandidateBrand]: true;
+}
+export interface PairAuthorChainPrefixEvidenceV1 {
+    readonly operationId: Uint8Array;
+    readonly exactOperationBytes: Uint8Array;
+}
+export interface ActivePairOperationCandidateSnapshotV1 {
+    readonly exactOperationBytes: Uint8Array;
+    readonly operationId: Uint8Array;
+    readonly operation: AuthenticatedRoomOperationV1;
+    readonly envelope: PairStepEnvelopeV1;
+    readonly roomContextId: Uint8Array;
+    readonly roomPolicy: RoomPolicyV4;
+    readonly referenceWindow: bigint;
+    readonly evidenceValidThroughWindow: bigint;
+    readonly exactCoreStateBytes: Uint8Array;
+    readonly authorChainPrefix: readonly PairAuthorChainPrefixEvidenceV1[];
+}
+declare const verifiedHistoricalPairPresenceBrand: unique symbol;
+/**
+ * Process-local proof that one exact signed PRESENCE was an observed roster
+ * fact in a genuine CoreReduce result. Generic author-prefix evidence cannot
+ * instantiate this capability.
+ */
+export interface VerifiedHistoricalPairPresenceEvidenceV1 {
+    readonly [verifiedHistoricalPairPresenceBrand]: true;
+}
+/** Exact durable record defined by Section 4.9. */
+export interface HistoricalPairPresenceEvidenceV1 {
+    readonly exactPresenceOperationBytes: Uint8Array;
+    readonly presenceOperationId: Uint8Array;
+    readonly retainThroughLogicalWindow: bigint;
+}
+export interface VerifiedHistoricalPairPresenceSnapshotV1 extends HistoricalPairPresenceEvidenceV1 {
+    readonly operation: AuthenticatedRoomOperationV1;
+    readonly presence: PresenceV1;
+    readonly provedAtLogicalWindow: bigint;
+    readonly roomContextId: Uint8Array;
+    readonly roomPolicy: RoomPolicyV4;
+    readonly exactCoreStateBytes: Uint8Array;
+    readonly authorChainPrefix: readonly PairAuthorChainPrefixEvidenceV1[];
+}
+/** One outer-authenticated candidate together with its private candidate ID. */
+export interface OuterValidatedIdentifiedOperationV1 {
+    readonly [outerValidatedIdentifiedOperationBrand]: true;
+    readonly operationId: Uint8Array;
+    readonly operation: AuthenticatedRoomOperationV1;
+}
+/**
+ * The sole ingress from untrusted decoded bytes into the reducer domain.
+ *
+ * The caller-owned object is canonically snapshotted before the first await;
+ * all validation and ID derivation use that private copy. OperationId is
+ * derived only after complete outer validation, including PAIR_STEP slot
+ * binding and the author signature. Non-pair nested signature work is
+ * deliberately deferred until CoreReduce has classified author quota/forks.
+ * The returned provenance brand is process-local and never persisted.
+ */
+export declare const validateAndIdentifyOperationCandidate: (operation: AuthenticatedRoomOperationV1, context: OperationValidationContext, module?: LibCrypto) => Promise<OuterValidatedIdentifiedOperationV1>;
+/**
+ * Capture one active, provenance-checked PAIR_STEP ingress.
+ *
+ * This is the only bridge from room-wide outer validation into pair opening.
+ * It requires both the candidate and the room state to be live results of
+ * their private validation/reduction entrypoints and rechecks their canonical
+ * bytes on every call. Persisted bytes must therefore pass validation and
+ * CoreReduce again after restart; a merely outer-valid future, forked,
+ * overquota, expired, or dependency-inert candidate cannot spend pair-open
+ * work or reach admission.
+ *
+ * The returned value is an opaque process-local capability. Pair-kernel code
+ * accepts that capability, never a caller-assembled snapshot or prebinding.
+ */
+export declare const captureActivePairOperationCandidate: (candidate: OuterValidatedIdentifiedOperationV1, roomState: CoreRoomStateV1) => Promise<ActivePairOperationCandidateV1>;
+/**
+ * Take an owned pair-kernel snapshot from a genuine active-operation handle.
+ *
+ * The returned bytes are data, not provenance: downstream state machines must
+ * continue accepting the opaque `ActivePairOperationCandidateV1` and call this
+ * accessor themselves. Exact Core bytes are included for the later durable
+ * compare-and-swap that prevents an asynchronous open from committing against
+ * a superseded room view.
+ */
+export declare const snapshotActivePairOperationCandidate: (candidate: ActivePairOperationCandidateV1) => ActivePairOperationCandidateSnapshotV1;
+/**
+ * Capture one current roster fact for bounded pair-private use after that
+ * presence leaves the live roster.
+ *
+ * Restore repeats operation validation and CoreReduce at the exact HELLO
+ * logical window before calling this constructor. That equality is
+ * load-bearing: a capability captured before an effective LEAVE cannot prove
+ * a HELLO created at or after the leave. Exact signed bytes alone, a decoded
+ * CoreRoomState, or generic author-prefix evidence are insufficient.
+ */
+export declare const captureHistoricalPairPresenceEvidence: (candidate: OuterValidatedIdentifiedOperationV1, roomState: CoreRoomStateV1, helloLogicalWindow: bigint) => Promise<VerifiedHistoricalPairPresenceEvidenceV1>;
+/**
+ * Return owned bytes from a genuine historical-presence capability.
+ *
+ * Downstream admission code accepts the opaque capability and calls this
+ * accessor itself. The structural result is suitable for persistence only; it
+ * cannot be passed back as proof after restart without validation and
+ * CoreReduce reconstructing a new capability.
+ */
+export declare const snapshotHistoricalPairPresenceEvidence: (evidence: VerifiedHistoricalPairPresenceEvidenceV1) => VerifiedHistoricalPairPresenceSnapshotV1;
+export type CoreFaultV1 = {
+    readonly kind: "author-fork-or-overquota";
+    readonly authorEpochEd25519Key: Uint8Array;
+    readonly logicalWindow: bigint;
+    readonly proofOperationIds: readonly Uint8Array[];
+} | {
+    readonly kind: "presence-or-leave-fork";
+    readonly semanticSlot: Uint8Array;
+    readonly proofOperationIds: readonly Uint8Array[];
+} | {
+    readonly kind: "store-generation-fork";
+    readonly storeId: Uint8Array;
+    readonly descriptorGeneration: bigint;
+    readonly descriptorHashes: readonly [Uint8Array, Uint8Array];
+};
+export interface CorePresenceFactV1 {
+    readonly presenceOperationId: Uint8Array;
+    readonly authorEpochEd25519Key: Uint8Array;
+    readonly logicalWindow: bigint;
+    readonly presence: PresenceV1;
+}
+export interface CoreStoreFactV1 {
+    readonly storeId: Uint8Array;
+    readonly descriptorGeneration: bigint;
+    readonly descriptorHash: Uint8Array;
+    readonly sourceOperationId: Uint8Array;
+    readonly descriptor: StoreDescriptorV1;
+    readonly routes: readonly StoreRouteV1[];
+    readonly hintValidThroughLogicalWindow: bigint;
+}
+export interface CoreRevocationFloorV1 {
+    readonly stableIdentityCommitment: Uint8Array;
+    readonly minimumAcceptedGeneration: bigint;
+    readonly effectiveLogicalWindow: bigint;
+    readonly validThroughLogicalWindow: bigint;
+    readonly revokeOperationId: Uint8Array;
+}
+export interface CoreRoomStateV1 {
+    readonly version: 1;
+    readonly referenceWindow: bigint;
+    readonly roomCapacityState: "within-policy" | "overcapacity";
+    readonly activeOperationIds: readonly Uint8Array[];
+    readonly observedPresences: readonly CorePresenceFactV1[];
+    readonly effectiveLeaveOperationIds: readonly Uint8Array[];
+    readonly storeCatalogFacts: readonly CoreStoreFactV1[];
+    readonly revocationFloors: readonly CoreRevocationFloorV1[];
+    readonly activePairOuterOperationIds: readonly Uint8Array[];
+    readonly faults: readonly CoreFaultV1[];
+    readonly operationsDigest: Uint8Array;
+}
+/** The unique canonical encoding of a reduced room state. */
+export declare const encodeCoreRoomStateV1: (state: CoreRoomStateV1) => Promise<Uint8Array>;
+/** Strictly decode one canonical reduced room state. */
+export declare const decodeCoreRoomStateV1: (bytes: Uint8Array) => Promise<CoreRoomStateV1>;
+export declare const mergeOperationCandidateSets: (left: readonly OuterValidatedIdentifiedOperationV1[], right: readonly OuterValidatedIdentifiedOperationV1[]) => OuterValidatedIdentifiedOperationV1[];
+/**
+ * Exact deterministic `CoreReduce`.
+ *
+ * Every decision is a function of privately snapshotted operation bytes and
+ * one immutable room context/reference window. Fork and overquota
+ * classification precedes payload reduction and is arrival-independent.
+ */
+export declare const coreReduce: (operations: readonly OuterValidatedIdentifiedOperationV1[], context: OperationValidationContext, module?: LibCrypto) => Promise<CoreRoomStateV1>;
+export {};