p2party 0.14.2 → 0.14.7

package/lib/blindRendezvous/identityHelloOpen.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Reservation-gated identity HELLO opener.
+ *
+ * This module is the sole current path from a committed pair-open reservation
+ * to HPKE work. It derives every transcript input from opaque trial
+ * provenance, authenticates the complete HELLO identity bundle, and retains
+ * HelloRoot only inside an opaque process-local result.
+ *
+ * The only next-state transition consumes the open into an opaque admission
+ * claim while leaving HelloRoot in this module's private custody.
+ * Pair-ledger persistence, ACCEPT construction, and any release of HelloRoot
+ * remain deliberately out of scope. This module is absent from the package
+ * barrel.
+ */
+import type { LibCrypto } from "../cryptography/libcrypto";
+import type { ActivePairOperationCandidateSnapshotV1, VerifiedHistoricalPairPresenceSnapshotV1 } from "./coreReduce";
+import type { ExpectedIdentityHelloTrialV1, LocalHelloReceiverCustodySnapshotV1 } from "./identityHelloTrial";
+import type { PairAttemptLeaseV1 } from "./admissionPolicy";
+import type { AdmissionGrantV1 } from "./operationPayload";
+import type { PairOuterBindingV1, PairPlaintextV1 } from "./pairPlaintext";
+import type { ReservedIdentityHelloOpenV1 } from "./pairOpenReservation";
+import type { RoomPolicyV4 } from "./roomPolicyV4";
+declare const verifiedIdentityHelloOpenBrand: unique symbol;
+declare const identityHelloAdmissionClaimBrand: unique symbol;
+declare const consumedIdentityHelloAdmissionClaimBrand: unique symbol;
+/** Opaque authenticated HELLO result. HelloRoot is never structurally exposed. */
+export interface VerifiedIdentityHelloOpenV1 {
+    readonly [verifiedIdentityHelloOpenBrand]: true;
+}
+/**
+ * Process-local claim on one authenticated HELLO and its root custody.
+ *
+ * This is deliberately not `VerifiedAdmissionContextV1`: that fact may only
+ * be minted after the admission boundary has atomically captured and
+ * correlated every trusted state fence. This internal type is absent from the
+ * package barrel and never exposes HelloRoot.
+ */
+export interface IdentityHelloAdmissionClaimV1 {
+    readonly [identityHelloAdmissionClaimBrand]: true;
+}
+/**
+ * Internal one-use transfer of an admission claim into asynchronous
+ * verification custody. It exposes no fields and retains the same private
+ * HelloRoot allocation; no secret is copied across this transition.
+ */
+export interface ConsumedIdentityHelloAdmissionClaimV1 {
+    readonly [consumedIdentityHelloAdmissionClaimBrand]: true;
+}
+export interface IdentityHelloAdmissionClaimSnapshotV1 {
+    readonly version: 1;
+    readonly roomContextId: Uint8Array;
+    readonly roomPolicy: RoomPolicyV4;
+    /** Current-Core fence at the successful open; a later capture may advance. */
+    readonly exactOpenedCoreStateBytes: Uint8Array;
+    /** Exact HELLO-time Core row selecting the complete evidence bundle. */
+    readonly exactHistoricalEvidenceCoreStateBytes: Uint8Array;
+    /** Canonical Core + remote/local PRESENCE + author-prefix evidence. */
+    readonly exactHistoricalEvidenceBundleBytes: Uint8Array;
+    readonly openedAtReferenceWindow: bigint;
+    readonly receiverKeyRecordRevision: bigint;
+    readonly localIdentityKeyRecordRevision: bigint;
+    readonly localStableEd25519PublicKey: Uint8Array;
+    readonly decisionRole: "hello-responder";
+    readonly operationId: Uint8Array;
+    readonly kind: "IDENTITY_HELLO";
+    readonly logicalWindow: bigint;
+    readonly validThroughLogicalWindow: bigint;
+    readonly pairEdgeId: Uint8Array;
+    readonly endpointPresenceOperationIds: readonly [Uint8Array, Uint8Array];
+    readonly direction: 0;
+    readonly pairSequence: 0n;
+    readonly previousPairOperationId: null;
+    readonly pairDependencies: readonly [];
+    readonly stableEd25519PublicKey: Uint8Array;
+    readonly claimedStableIdentityCommitment: Uint8Array;
+    readonly optionalGrant: AdmissionGrantV1 | null;
+    readonly pairIdentitySignatureHash: Uint8Array;
+    readonly admittedPresenceOperationId: Uint8Array;
+    readonly admittedPresenceEvidenceRetainThroughLogicalWindow: bigint;
+    readonly basePairAttemptLease: PairAttemptLeaseV1;
+}
+export interface VerifiedIdentityHelloOpenSnapshotV1 {
+    readonly version: 1;
+    readonly helloOperationId: Uint8Array;
+    readonly activeCandidate: ActivePairOperationCandidateSnapshotV1;
+    readonly pairOuterBinding: PairOuterBindingV1;
+    readonly plaintext: PairPlaintextV1;
+    readonly localPresenceEvidence: VerifiedHistoricalPairPresenceSnapshotV1;
+    readonly remotePresenceEvidence: VerifiedHistoricalPairPresenceSnapshotV1;
+    readonly pairIdentitySignatureHash: Uint8Array;
+    /**
+     * Pre-admission base lease. Sole Admit may validate a carried grant, narrow
+     * this horizon, and persist the result atomically; this opener may not.
+     */
+    readonly basePairAttemptLease: PairAttemptLeaseV1;
+    readonly trialOrdinal: number;
+    readonly receiverKeyRecordRevision: bigint;
+    readonly localIdentityKeyRecordRevision: bigint;
+    readonly localStableEd25519PublicKey: Uint8Array;
+}
+export type OpenReservedIdentityHelloResultV1 = {
+    readonly kind: "opened";
+    readonly value: VerifiedIdentityHelloOpenV1;
+} | {
+    readonly kind: "not-this-trial";
+} | {
+    readonly kind: "rejected";
+} | {
+    readonly kind: "deferred";
+    readonly reason: "missing-presence-evidence";
+};
+export declare class IdentityHelloOpenError extends Error {
+    readonly name = "IdentityHelloOpenError";
+    constructor(message: string);
+}
+/**
+ * Consume one committed reservation and try its exact expected HELLO trial.
+ *
+ * Reservation and trial consumption happen synchronously before the first
+ * await. `not-this-trial` means the routing tag or HPKE authentication did not
+ * match. `rejected` means authenticated bytes failed the closed HELLO identity
+ * gate. Provenance, programming, storage, or cryptographic infrastructure
+ * failures throw.
+ */
+export declare const openReservedIdentityHelloV1: (capability: ReservedIdentityHelloOpenV1, trial: ExpectedIdentityHelloTrialV1, module: LibCrypto) => Promise<OpenReservedIdentityHelloResultV1>;
+/** Return a fresh deeply owned snapshot containing no HelloRoot. */
+export declare const snapshotVerifiedIdentityHelloOpenV1: (value: VerifiedIdentityHelloOpenV1) => VerifiedIdentityHelloOpenSnapshotV1;
+/**
+ * Consume one authenticated HELLO into the only admission-claim handle.
+ *
+ * The transition is synchronous and moves, rather than copies, the private
+ * state. The old handle becomes unusable before control returns, and no root
+ * bytes cross the API.
+ */
+export declare const takeVerifiedIdentityHelloOpenForAdmissionV1: (value: VerifiedIdentityHelloOpenV1) => IdentityHelloAdmissionClaimV1;
+/** @internal Fresh deeply owned claim projection containing no HelloRoot. */
+export declare const snapshotIdentityHelloAdmissionClaimV1: (value: IdentityHelloAdmissionClaimV1) => IdentityHelloAdmissionClaimSnapshotV1;
+/**
+ * Synchronously spend one admission claim into in-flight verification custody.
+ *
+ * The source entry is deleted before return, so reentrancy and concurrent
+ * verification cannot reuse it. The private state and HelloRoot allocation are
+ * moved without copying. A minting failure wipes the transferred root.
+ *
+ * @internal
+ */
+export declare const takeIdentityHelloAdmissionClaimForVerificationV1: (value: IdentityHelloAdmissionClaimV1) => ConsumedIdentityHelloAdmissionClaimV1;
+/** @internal Fresh owned non-secret projection of one live consumed claim. */
+export declare const snapshotConsumedIdentityHelloAdmissionClaimV1: (value: ConsumedIdentityHelloAdmissionClaimV1) => IdentityHelloAdmissionClaimSnapshotV1;
+/**
+ * Assert and project the exact live receiver/stable custody carried through
+ * the authenticated HELLO transition.
+ *
+ * This internal accessor returns no capability or secret. Its only caller is
+ * the admission capture verifier, which compares both persisted revisions and
+ * the captured local-ownership row before minting trusted policy context.
+ *
+ * @internal
+ */
+export declare const snapshotConsumedIdentityHelloAdmissionLocalCustodyV1: (value: ConsumedIdentityHelloAdmissionClaimV1) => LocalHelloReceiverCustodySnapshotV1;
+/** Wipe in-flight HelloRoot custody. Idempotent for a genuine handle. */
+export declare const destroyConsumedIdentityHelloAdmissionClaimV1: (value: ConsumedIdentityHelloAdmissionClaimV1) => void;
+/** Wipe the retained HelloRoot. Idempotent for a genuine claim handle. */
+export declare const destroyIdentityHelloAdmissionClaimV1: (value: IdentityHelloAdmissionClaimV1) => void;
+/** Wipe the retained HelloRoot. Idempotent for a genuine handle. */
+export declare const destroyVerifiedIdentityHelloOpenV1: (value: VerifiedIdentityHelloOpenV1) => void;
+export {};

package/lib/blindRendezvous/identityHelloTrial.d.ts

@@ -0,0 +1,271 @@
+/**
+ * Provenance-checked local custody and receiver trial for identity HELLO.
+ *
+ * Expensive local ownership and hybrid-key verification happen exactly once
+ * when trusted room/key storage creates `LocalHelloReceiverCustodyV1`.
+ * Per-candidate `ExpectedIdentityHelloTrialV1` construction is synchronous,
+ * bounded, and cryptography-free. A later durable budget reservation binds
+ * the exact opaque candidate and trial objects. The opener can additionally
+ * assert the custody identity sealed inside that trial before it invokes the
+ * explicitly internal one-use secret transfer below.
+ *
+ * This module deliberately does not reserve work, run HPKE, authorize a peer,
+ * mutate a pair ledger, or publish a response. It is absent from the package
+ * barrel.
+ */
+import type { LibCrypto } from "../cryptography/libcrypto";
+import type { ActivePairOperationCandidateSnapshotV1, ActivePairOperationCandidateV1, VerifiedHistoricalPairPresenceEvidenceV1, VerifiedHistoricalPairPresenceSnapshotV1 } from "./coreReduce";
+import type { ReservedIdentityHelloOpenV1 } from "./pairOpenReservation";
+import type { RoomPolicyV4 } from "./roomPolicyV4";
+import type { LocalStableIdentityCustodyV1 } from "./localStableIdentityCustody";
+declare const localHelloReceiverCustodyBrand: unique symbol;
+declare const historicalIdentityHelloEvidenceViewBrand: unique symbol;
+declare const expectedIdentityHelloTrialBrand: unique symbol;
+/**
+ * Opaque room-specific custody for one local presence receiver key.
+ *
+ * The current constructor is an interim trusted local-storage boundary:
+ * `receiverKeyRecordRevision` and `roomRoot` have no independent storage
+ * provenance yet. Stable identity ownership is already sealed by an exact
+ * `LocalStableIdentityCustodyV1` handle. The future atomic room/key adapter
+ * must be the sole caller. None of these values become per-trial inputs.
+ */
+export interface LocalHelloReceiverCustodyV1 {
+    readonly [localHelloReceiverCustodyBrand]: true;
+}
+/**
+ * Opaque bounded endpoint-evidence lookup for one exact HELLO-time Core view.
+ *
+ * It is not admission or topology authority. The trusted caller supplies the
+ * locally selected subset; the later planner/explicit-state fence decides
+ * whether an authenticated endpoint may receive a response.
+ */
+export interface HistoricalIdentityHelloEvidenceViewV1 {
+    readonly [historicalIdentityHelloEvidenceViewBrand]: true;
+}
+/** Opaque, process-local, one-use candidate trial. */
+export interface ExpectedIdentityHelloTrialV1 {
+    readonly [expectedIdentityHelloTrialBrand]: true;
+}
+export interface CreateLocalHelloReceiverCustodyOptionsV1 {
+    readonly module: LibCrypto;
+    readonly localPresenceEvidence: VerifiedHistoricalPairPresenceEvidenceV1;
+    /** Suite-1 MLKEM768-X25519 deterministic receiver seed. */
+    readonly recipientHybridKemSecretSeed: Uint8Array;
+    /** Exact room-specific HPKE PSK derived by trusted initialized-room state. */
+    readonly roomRoot: Uint8Array;
+    readonly localStableIdentityCustody: LocalStableIdentityCustodyV1;
+    readonly receiverKeyRecordRevision: bigint;
+}
+export interface LocalHelloReceiverCustodySnapshotV1 {
+    readonly version: 1;
+    readonly localPresenceOperationId: Uint8Array;
+    readonly exactPresenceOperationBytes: Uint8Array;
+    readonly sourceEvidenceCoreStateBytes: Uint8Array;
+    readonly sourceEvidenceLogicalWindow: bigint;
+    readonly roomContextId: Uint8Array;
+    readonly roomPolicy: RoomPolicyV4;
+    readonly advertisedReceiverHybridKemPublicKey: Uint8Array;
+    readonly receiverKeyValidThroughLogicalWindow: bigint;
+    readonly receiverEvidenceRetainThroughLogicalWindow: bigint;
+    readonly localStableEd25519PublicKey: Uint8Array;
+    readonly localIdentityKeyRecordRevision: bigint;
+    readonly receiverKeyRecordRevision: bigint;
+}
+export interface CreateHistoricalIdentityHelloEvidenceViewOptionsV1 {
+    /**
+     * A nonempty bounded subset of observed PRESENCE evidence from one genuine
+     * HELLO-time Core result. Production supplies the Project-selected subset
+     * needed by local receiver trials, never the whole raw overcapacity roster.
+     */
+    readonly historicalPresenceEvidence: readonly VerifiedHistoricalPairPresenceEvidenceV1[];
+}
+/**
+ * Compact, deeply owned metadata for one bounded historical evidence view.
+ *
+ * Presence operation IDs are sufficient for deterministic membership and
+ * lookup. Exact operation/prefix snapshots are resolved one at a time only
+ * after a durable pair-open reservation has been consumed.
+ */
+export interface HistoricalIdentityHelloEvidenceViewSnapshotV1 {
+    readonly version: 1;
+    readonly exactCoreStateBytes: Uint8Array;
+    readonly roomContextId: Uint8Array;
+    readonly roomPolicy: RoomPolicyV4;
+    readonly helloLogicalWindow: bigint;
+    readonly minimumRetainThroughLogicalWindow: bigint;
+    readonly presenceOperationIds: readonly Uint8Array[];
+}
+export interface CreateExpectedIdentityHelloTrialOptionsV1 {
+    readonly activeCandidate: ActivePairOperationCandidateV1;
+    readonly receiverCustody: LocalHelloReceiverCustodyV1;
+    readonly historicalEvidenceView: HistoricalIdentityHelloEvidenceViewV1;
+    readonly trialOrdinal: number;
+}
+/**
+ * Deeply owned non-secret view for durable reservation/CAS binding.
+ *
+ * `exactCoreStateBytes` is the current active-operation fence.
+ * `exactEvidenceCoreStateBytes` is the potentially older, exact HELLO-window
+ * presence-proof fence. They intentionally need not be equal.
+ */
+export interface ExpectedIdentityHelloTrialSnapshotV1 {
+    readonly version: 1;
+    readonly activeOperationId: Uint8Array;
+    readonly exactCoreStateBytes: Uint8Array;
+    readonly exactEvidenceCoreStateBytes: Uint8Array;
+    readonly roomContextId: Uint8Array;
+    readonly roomPolicy: RoomPolicyV4;
+    readonly helloLogicalWindow: bigint;
+    readonly localPresenceOperationId: Uint8Array;
+    readonly advertisedReceiverHybridKemPublicKey: Uint8Array;
+    readonly receiverKeyValidThroughLogicalWindow: bigint;
+    readonly receiverEvidenceRetainThroughLogicalWindow: bigint;
+    readonly trialOrdinal: number;
+    readonly receiverKeyRecordRevision: bigint;
+    readonly localIdentityKeyRecordRevision: bigint;
+    readonly activeCandidate: ActivePairOperationCandidateSnapshotV1;
+    readonly receiverCustody: LocalHelloReceiverCustodySnapshotV1;
+    readonly localPresenceEvidence: VerifiedHistoricalPairPresenceSnapshotV1;
+    readonly historicalEvidenceView: HistoricalIdentityHelloEvidenceViewSnapshotV1;
+}
+/**
+ * Small private-to-the-pair-kernel projection used before work is charged.
+ *
+ * It contains no decoded room roster, presence operation, author prefix,
+ * receiver secret, RoomRoot, or caller-controlled coordinate.
+ *
+ * @internal
+ */
+export interface ExpectedIdentityHelloTrialReservationProjectionV1 {
+    readonly version: 1;
+    readonly activeOperationId: Uint8Array;
+    readonly exactCurrentCoreStateBytes: Uint8Array;
+    readonly exactEvidenceCoreStateBytes: Uint8Array;
+    readonly roomContextId: Uint8Array;
+    readonly localPresenceOperationId: Uint8Array;
+    readonly receiverKeyRecordRevision: bigint;
+    readonly capturedReferenceWindow: bigint;
+    readonly completeEnvelopeBytes: number;
+}
+/**
+ * Internal one-use transfer returned only after consuming a genuine durable
+ * reservation.
+ *
+ * Both returned secrets are fresh owned copies and MUST be wiped by the
+ * consumer in a `finally` block. The reusable custody master remains live
+ * until explicitly destroyed because concurrent HELLO trials may need it.
+ *
+ * @internal
+ */
+export interface ConsumedExpectedIdentityHelloTrialV1 {
+    readonly snapshot: ExpectedIdentityHelloTrialSnapshotV1;
+    readonly activeCandidate: ActivePairOperationCandidateV1;
+    readonly receiverCustody: LocalHelloReceiverCustodyV1;
+    readonly localPresenceEvidence: VerifiedHistoricalPairPresenceEvidenceV1;
+    /**
+     * Exact-ID lookup over the bounded fenced view. This function exists only
+     * after the durable reservation is consumed; it returns an opaque genuine
+     * evidence handle, never a caller-assembled structural proof.
+     */
+    readonly resolveHistoricalPresenceEvidence: (presenceOperationId: Uint8Array) => VerifiedHistoricalPairPresenceEvidenceV1 | null;
+    readonly recipientHybridKemSecretSeed: Uint8Array;
+    readonly roomRoot: Uint8Array;
+}
+export declare class IdentityHelloTrialError extends Error {
+    readonly name = "IdentityHelloTrialError";
+    constructor(message: string);
+}
+/**
+ * Capture one bounded exact-Core evidence subset.
+ *
+ * The O(selected-member-count) provenance work and canonical Core decode
+ * happen once here. Every later receiver-key trial reuses the opaque result
+ * and performs no raw-roster walk. A view may omit an otherwise valid Core
+ * presence because Project did not select it; a HELLO naming an omitted
+ * endpoint is deferred and can never bypass later planner/admission fences.
+ */
+export declare const createHistoricalIdentityHelloEvidenceViewV1: (options: CreateHistoricalIdentityHelloEvidenceViewOptionsV1) => Promise<HistoricalIdentityHelloEvidenceViewV1>;
+/** Return fresh compact metadata, never per-presence operation snapshots. */
+export declare const snapshotHistoricalIdentityHelloEvidenceViewV1: (view: HistoricalIdentityHelloEvidenceViewV1) => HistoricalIdentityHelloEvidenceViewSnapshotV1;
+/**
+ * Create reusable local receiver custody.
+ *
+ * All caller bytes and execution dependencies are captured before the first
+ * await. Expensive verification occurs here once per persisted key record,
+ * never once per attacker-supplied PAIR_STEP.
+ */
+export declare const createLocalHelloReceiverCustodyV1: (options: CreateLocalHelloReceiverCustodyOptionsV1) => Promise<LocalHelloReceiverCustodyV1>;
+/** Return a fresh non-secret custody projection. */
+export declare const snapshotLocalHelloReceiverCustodyV1: (custody: LocalHelloReceiverCustodyV1) => LocalHelloReceiverCustodySnapshotV1;
+/**
+ * Create one cheap expected trial from already-verified local custody.
+ *
+ * This function is intentionally synchronous and performs no signature, KEM,
+ * KDF, AEAD, or storage work.
+ */
+export declare const createExpectedIdentityHelloTrialV1: (options: CreateExpectedIdentityHelloTrialOptionsV1) => ExpectedIdentityHelloTrialV1;
+/** Return a fresh, independently owned, non-secret trial snapshot. */
+export declare const snapshotExpectedIdentityHelloTrialV1: (trial: ExpectedIdentityHelloTrialV1) => ExpectedIdentityHelloTrialSnapshotV1;
+/**
+ * Return the only pre-budget projection used by reservation.
+ *
+ * All fields were captured once when the trial was constructed. In
+ * particular, this function performs no Core decode, roster walk, evidence
+ * snapshot, operation decode, signature work, KEM work, or secret copy.
+ *
+ * @internal
+ */
+export declare const snapshotExpectedIdentityHelloTrialReservationProjectionV1: (trial: ExpectedIdentityHelloTrialV1, activeCandidate: ActivePairOperationCandidateV1) => ExpectedIdentityHelloTrialReservationProjectionV1;
+/**
+ * Recheck all opaque dependencies without materializing structural data.
+ *
+ * @internal
+ */
+export declare const assertExpectedIdentityHelloTrialReservationLivenessV1: (trial: ExpectedIdentityHelloTrialV1, activeCandidate: ActivePairOperationCandidateV1) => void;
+/**
+ * Bind reservation to the exact opaque active-candidate object.
+ *
+ * Custody is deliberately not a reservation input: its identity is sealed
+ * inside the trial, so the reservation caller cannot substitute one.
+ *
+ * @internal
+ */
+export declare const assertExpectedIdentityHelloTrialCandidateBindingV1: (trial: ExpectedIdentityHelloTrialV1, activeCandidate: ActivePairOperationCandidateV1) => void;
+/**
+ * Bind the future opener to the exact opaque candidate and custody objects.
+ *
+ * Matching structural bytes are insufficient.
+ *
+ * @internal
+ */
+export declare const assertExpectedIdentityHelloTrialBindingsV1: (trial: ExpectedIdentityHelloTrialV1, activeCandidate: ActivePairOperationCandidateV1, receiverCustody: LocalHelloReceiverCustodyV1) => void;
+/**
+ * Consume one genuine committed reservation, then transfer trial secrets.
+ *
+ * The reservation capability is deleted before this function can copy either
+ * secret. Its privately bound candidate must be the exact candidate sealed
+ * inside the trial; no caller-supplied candidate participates in this check.
+ *
+ * This explicit import creates a narrow cycle with `pairOpenReservation.ts`.
+ * Neither module performs top-level work, so the cycle contains bindings only.
+ *
+ * @internal
+ */
+export declare const consumeReservedExpectedIdentityHelloTrialForPairOpenV1: (capability: ReservedIdentityHelloOpenV1, trial: ExpectedIdentityHelloTrialV1) => ConsumedExpectedIdentityHelloTrialV1;
+/** Invalidate one unused trial. Idempotent for a genuine handle. */
+export declare const destroyExpectedIdentityHelloTrialV1: (trial: ExpectedIdentityHelloTrialV1) => void;
+/**
+ * Invalidate one reusable historical evidence view.
+ *
+ * Destruction is idempotent for a genuine handle. Any dependent unconsumed
+ * trial subsequently fails closed at reservation or consumption.
+ */
+export declare const destroyHistoricalIdentityHelloEvidenceViewV1: (view: HistoricalIdentityHelloEvidenceViewV1) => void;
+/**
+ * Wipe reusable receiver custody after its key record is retired.
+ *
+ * Destruction is idempotent for a genuine handle.
+ */
+export declare const destroyLocalHelloReceiverCustodyV1: (custody: LocalHelloReceiverCustodyV1) => void;
+export {};

package/lib/blindRendezvous/localAdmissibleProject.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Pure local-admissible projection semantics.
+ *
+ * This module computes the diagnostic `LocalAdmissibleStateV1` from complete,
+ * deeply owned inputs. It deliberately does not mint topology, reservation,
+ * admission, persistence, or publication authority. The effectful HELLO path
+ * must later wrap this kernel behind an opaque handle tied by object identity
+ * to one genuine `TrustedAdmissionSnapshotV1` and its exact planner/CAS row.
+ *
+ * Authority-mode projection remains unavailable until the protected
+ * non-omission custody constructor is implemented. There is no fallback to
+ * address-book or open eligibility.
+ */
+import type { LibCrypto } from "../cryptography/libcrypto";
+import type { FrontendRoomControlsV1 } from "./admissionPolicy";
+import type { CoreRoomStateV1 } from "./coreReduce";
+import type { PlannerAndExplicitStateV1 } from "./plannerState";
+import type { RoomPolicyV4 } from "./roomPolicyV4";
+export type LocalPresenceEligibilityV1 = "open" | "local-address-book-proved" | "authority-permit-proved";
+export interface LocalAdmissiblePeerV1 {
+    readonly localPeerId: string;
+    readonly presenceOperationId: Uint8Array;
+    readonly stableIdentityCommitment: Uint8Array;
+    readonly rank: Uint8Array;
+    readonly eligibility: LocalPresenceEligibilityV1;
+    readonly desiredEdge: boolean;
+}
+export interface LocalAdmissibleStateV1 {
+    readonly version: 1;
+    readonly referenceWindow: bigint;
+    readonly coreOperationsDigest: Uint8Array;
+    readonly localPresenceOperationId: Uint8Array | null;
+    readonly localPresenceRank: Uint8Array | null;
+    readonly peers: readonly LocalAdmissiblePeerV1[];
+    readonly requestedExplicitPeerIds: readonly string[];
+}
+export type LocalAdmissibleProjectStatusV1 = "ready" | "policy-unavailable" | "projection-resource-overcapacity" | "no-unambiguous-local-presence";
+export type LocalAdmissiblePlannerStatusV1 = "ready" | "unavailable" | "full-mesh-overcapacity";
+/**
+ * Structural inputs for the pure semantic kernel.
+ *
+ * `maxPairLedgerEntriesPerRoom` is needed only to validate the captured
+ * planner row. A future trusted wrapper pins it from the room resource policy;
+ * accepting this structural object does not establish that provenance.
+ */
+export interface LocalAdmissibleProjectSemanticInputV1 {
+    readonly version: 1;
+    readonly roomContextId: Uint8Array;
+    readonly roomPolicy: RoomPolicyV4;
+    readonly referenceWindow: bigint;
+    readonly coreRoomState: CoreRoomStateV1;
+    readonly frontendControls: FrontendRoomControlsV1 | null;
+    /**
+     * Structural premise only. The trusted wrapper must replace this with a
+     * process-local brand that binds every exact owned Core fact and OperationId
+     * to one of these stable keys, a verified stable-ownership signature, and
+     * current local author, identity, and receiver-key custody.
+     */
+    readonly localPresenceOwnership: {
+        readonly version: 1;
+        readonly localPresenceOperationIds: readonly Uint8Array[];
+        readonly localStableIdentityKeys: readonly Uint8Array[];
+    };
+    readonly plannerAndExplicitState: PlannerAndExplicitStateV1;
+    readonly maxRetainedValidOperationsPerRoom: number;
+    readonly maxPairLedgerEntriesPerRoom: number;
+}
+export interface LocalAdmissibleProjectSemanticResultV1 {
+    readonly version: 1;
+    readonly projectionStatus: LocalAdmissibleProjectStatusV1;
+    readonly plannerStatus: LocalAdmissiblePlannerStatusV1;
+    readonly observedRosterHash: Uint8Array;
+    readonly state: LocalAdmissibleStateV1;
+    /**
+     * SSOT for the two distinct attempt origins. `state.peers[].desiredEdge` is
+     * only their UI-friendly OR and must never be used to enforce attemptMode.
+     */
+    readonly topologySelections: readonly LocalTopologySelectionFactV1[];
+}
+export interface LocalTopologySelectionFactV1 {
+    readonly presenceOperationId: Uint8Array;
+    readonly plannerSelected: boolean;
+    /**
+     * Local outbound intent only. An incoming signed `attemptMode="explicit"`
+     * does not require this bit; it requires the separately captured receiver
+     * `allowOnDemandEdges` gate.
+     */
+    readonly locallyRequestedExplicit: boolean;
+}
+export declare class LocalAdmissibleProjectError extends Error {
+    readonly name = "LocalAdmissibleProjectError";
+    constructor(message: string);
+}
+/**
+ * Evaluate the local Project rules over one owned structural snapshot.
+ *
+ * The return value is a diagnostic fact only. It is intentionally cloneable
+ * and therefore MUST NOT be accepted by a topology or admission transition as
+ * proof that a peer was selected.
+ */
+export declare const evaluateLocalAdmissibleProjectionSemanticsV1: (inputValue: unknown, module?: LibCrypto) => Promise<LocalAdmissibleProjectSemanticResultV1>;

package/lib/blindRendezvous/localPresenceKeyBinding.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Process-local custody for a room/window author epoch and a verified binding
+ * from one exact local PRESENCE to its live local key records.
+ *
+ * `VerifiedLocalPresenceKeyBindingV1` is intentionally only a per-presence key
+ * binding. It proves neither a complete/non-omitted local-presence set nor a
+ * current Core view, and it grants no topology, admission, lease, persistence,
+ * publication, or signaling authority. This internal module is absent from the
+ * package barrel.
+ */
+import type { LibCrypto } from "../cryptography/libcrypto";
+import type { VerifiedHistoricalPairPresenceEvidenceV1 } from "./coreReduce";
+import type { LocalHelloReceiverCustodyV1 } from "./identityHelloTrial";
+import type { OperationValidationContext } from "./operation";
+import type { RoomPolicyV4 } from "./roomPolicyV4";
+declare const localAuthorEpochCustodyBrand: unique symbol;
+declare const verifiedLocalPresenceKeyBindingBrand: unique symbol;
+/**
+ * Opaque live custody for one exact room/window author epoch key record.
+ *
+ * This capability is runtime-distinct from stable-identity custody. Possessing
+ * either handle can never be substituted for the other, even by a type cast.
+ */
+export interface LocalAuthorEpochCustodyV1 {
+    readonly [localAuthorEpochCustodyBrand]: true;
+}
+export interface CreateLocalAuthorEpochCustodyOptionsV1 {
+    readonly module: LibCrypto;
+    readonly authorEpochEd25519SecretKey: Uint8Array;
+    /** Non-reused revision of the persisted author-epoch key record. */
+    readonly authorEpochKeyRecordRevision: bigint;
+    readonly roomContextId: Uint8Array;
+    readonly logicalWindow: bigint;
+}
+export interface LocalAuthorEpochCustodySnapshotV1 {
+    readonly version: 1;
+    readonly authorEpochEd25519PublicKey: Uint8Array;
+    readonly authorEpochKeyRecordRevision: bigint;
+    readonly roomContextId: Uint8Array;
+    readonly logicalWindow: bigint;
+}
+/**
+ * Opaque proof that one genuine retained local PRESENCE matches live local
+ * stable-identity, receiver-key, and author-epoch custody.
+ *
+ * The handle is not a roster/set ownership proof. In particular, it says
+ * nothing about omitted presences, a current Core snapshot, or authorization.
+ */
+export interface VerifiedLocalPresenceKeyBindingV1 {
+    readonly [verifiedLocalPresenceKeyBindingBrand]: true;
+}
+export interface CreateVerifiedLocalPresenceKeyBindingOptionsV1 {
+    readonly localPresenceEvidence: VerifiedHistoricalPairPresenceEvidenceV1;
+    readonly receiverCustody: LocalHelloReceiverCustodyV1;
+    readonly authorEpochCustody: LocalAuthorEpochCustodyV1;
+    readonly initializedRoom: OperationValidationContext;
+}
+export interface VerifiedLocalPresenceKeyBindingSnapshotV1 {
+    readonly version: 1;
+    readonly localPresenceOperationId: Uint8Array;
+    readonly exactPresenceOperationBytes: Uint8Array;
+    readonly roomContextId: Uint8Array;
+    readonly roomPolicy: RoomPolicyV4;
+    readonly presenceLogicalWindow: bigint;
+    readonly provedAtLogicalWindow: bigint;
+    readonly authorEpochEd25519PublicKey: Uint8Array;
+    readonly authorEpochKeyRecordRevision: bigint;
+    readonly advertisedReceiverHybridKemPublicKey: Uint8Array;
+    readonly receiverKeyValidThroughLogicalWindow: bigint;
+    readonly receiverKeyRecordRevision: bigint;
+    readonly localStableEd25519PublicKey: Uint8Array;
+    readonly localIdentityKeyRecordRevision: bigint;
+}
+export declare class LocalPresenceKeyBindingError extends Error {
+    readonly name = "LocalPresenceKeyBindingError";
+    constructor(message: string);
+}
+/**
+ * Capture and validate one room/window author secret before minting custody.
+ */
+export declare const createLocalAuthorEpochCustodyV1: (options: CreateLocalAuthorEpochCustodyOptionsV1) => Promise<LocalAuthorEpochCustodyV1>;
+/** Return a fresh non-secret projection and assert that custody is live. */
+export declare const snapshotLocalAuthorEpochCustodyV1: (custody: LocalAuthorEpochCustodyV1) => LocalAuthorEpochCustodySnapshotV1;
+/**
+ * Wipe author-epoch custody after the corresponding local key record retires.
+ *
+ * Destruction is idempotent for a genuine handle. It neither owns nor retires
+ * the historical receiver or stable-identity custody used by a binding.
+ */
+export declare const destroyLocalAuthorEpochCustodyV1: (custody: LocalAuthorEpochCustodyV1) => void;
+/**
+ * Verify one exact local PRESENCE/key relation and mint an empty opaque handle.
+ *
+ * Every caller-controlled byte is captured through genuine handles before the
+ * ownership-signature await. The exact handles are then re-read, so retiring a
+ * nested author, receiver, or stable key during verification fails closed.
+ */
+export declare const createVerifiedLocalPresenceKeyBindingV1: (options: CreateVerifiedLocalPresenceKeyBindingOptionsV1) => Promise<VerifiedLocalPresenceKeyBindingV1>;
+/** Return fresh non-secret facts while every retained handle remains live. */
+export declare const snapshotVerifiedLocalPresenceKeyBindingV1: (binding: VerifiedLocalPresenceKeyBindingV1) => VerifiedLocalPresenceKeyBindingSnapshotV1;
+/**
+ * Invalidate one binding without dereferencing its nested custody handles.
+ *
+ * This remains safe and idempotent after author, receiver, or stable custody
+ * has already been retired and wiped.
+ */
+export declare const destroyVerifiedLocalPresenceKeyBindingV1: (binding: VerifiedLocalPresenceKeyBindingV1) => void;
+export {};