threshold-elgamal 1.0.9 → 2.0.0

package/dist/protocol/voting-verification.js

@@ -1,3 +1,10 @@
+/**
+ * Top-level full-ceremony verification for the supported voting workflow.
+ *
+ * This module is the shortest path for auditors and bulletin-board readers who
+ * want one call that replays manifest validation, board audit, DKG, ballots,
+ * decryption shares, and tally checks.
+ */
 import { InvalidPayloadError } from '../core/index.js';
 import { decodeScalar } from '../core/ristretto.js';
 import { verifyDKGTranscript, } from '../dkg/verification.js';
@@ -30,7 +37,7 @@ const recomputePublishedTally = (input) => {
         sessionId: input.sessionId,
         optionIndex: input.ballots.optionIndex,
     });
-    return combineDecryptionShares(preparedAggregate.ciphertext, input.decryptionShares.map((entry) => entry.share), BigInt(input.ballots.aggregate.ballotCount) * 10n);
+    return combineDecryptionShares(preparedAggregate.ciphertext, input.decryptionShares.map((entry) => entry.share), BigInt(input.ballots.aggregate.ballotCount) * input.scoreRangeMax);
 };
 const verifyPublishedTallyPayload = (payload, optionIndex, ballots, decryptionShares, tally) => {
     if (payload.transcriptHash !== ballots.aggregate.transcriptHash) {
@@ -123,17 +130,8 @@ const verifyBallotClosePayload = (input) => {
  * DKG verification, ballot verification, decryption-share verification, and
  * per-option tally checks.
  *
- * @param input Full public ceremony input bundle.
- * @returns Detailed verified ceremony output.
- *
- * @example
- * ```ts
- * const verified = await verifyElectionCeremony(bundle);
- *
- * console.log(verified.boardAudit.overall.fingerprint);
- * console.log(verified.countedParticipantIndices);
- * console.log(verified.perOptionTallies);
- * ```
+ * This is the main verifier entry point for callers that want failures to
+ * abort immediately.
  */
 export const verifyElectionCeremony = async (input) => {
     let context;
@@ -282,6 +280,7 @@ export const verifyElectionCeremony = async (input) => {
                 jointPublicKey: dkg.jointPublicKey,
                 protocolVersion: context.protocolVersion,
                 manifestHash: context.manifestHash,
+                scoreRangeMax: context.scoreRangeMax,
                 sessionId: context.sessionId,
             });
             const publication = tallyPublicationMap.get(optionIndex);
@@ -333,20 +332,8 @@ export const verifyElectionCeremony = async (input) => {
  * Runs the full ceremony verifier and returns a structured success-or-failure
  * result without throwing.
  *
- * @param input Full public ceremony input bundle.
- * @returns Verified ceremony output or a stable structured failure.
- *
- * @example
- * ```ts
- * const result = await tryVerifyElectionCeremony(bundle);
- *
- * if (!result.ok) {
- *     console.error(result.error.stage, result.error.code, result.error.reason);
- *     return;
- * }
- *
- * console.log(result.verified.qualifiedParticipantIndices);
- * ```
+ * This is the preferred integration point for applications that want stable
+ * failure stages and codes instead of exception handling.
  */
 export const tryVerifyElectionCeremony = async (input) => {
     try {

package/dist/serialize/encoding.js

@@ -1,3 +1,7 @@
+/**
+ * Deterministic byte encoders used for transcript hashing, proof challenges,
+ * session identifiers, and other canonical digest inputs.
+ */
 import { bytesToBigInt, hexToBytes } from '../core/bytes.js';
 import { utf8ToBytes } from '../core/crypto.js';
 import { InvalidPayloadError, InvalidScalarError } from '../core/errors.js';

package/dist/threshold/decrypt.d.ts

@@ -10,20 +10,28 @@ import { type AggregateDecryptionPreparationInput, type DecryptionShare, type Sh
  */
 export declare const lagrangeCoefficient: (participantIndex: bigint, allIndices: readonly bigint[], q: bigint) => bigint;
 /**
- * Creates a partial decryption share `d_i = x_i C_1`.
+ * Creates one trustee's partial decryption share `d_i = x_i C_1`.
+ *
+ * This is the low-level share value that applications typically prove with
+ * DLEQ and then publish inside a signed `decryption-share` payload.
  */
 export declare const createDecryptionShare: (ciphertext: ElGamalCiphertext, share: Share) => DecryptionShare;
 /**
- * Prepares a verified aggregate for decryption.
+ * Prepares a verified aggregate for decryption-share generation and DLEQ
+ * proving.
  *
  * When the accepted aggregate has identity `c1`, the raw DLEQ statement would
  * degenerate because every participant would obtain the same identity-valued
- * partial share. This helper deterministically adds a public encryption of zero
- * in that corner case so the plaintext stays unchanged while the decryption
- * proof statement remains meaningful.
+ * partial share. This helper deterministically adds a public encryption of
+ * zero in that corner case so the plaintext stays unchanged while the
+ * decryption proof statement remains meaningful.
  */
 export declare const prepareAggregateForDecryption: (input: AggregateDecryptionPreparationInput) => AggregateDecryptionPreparationInput["aggregate"];
 /**
  * Combines indexed decryption shares via Lagrange interpolation at `x = 0`.
+ *
+ * This is the final bounded plaintext-recovery step. In the supported voting
+ * workflow it runs only after the transcript, ballot aggregation, and
+ * decryption-share proofs have already been verified.
  */
 export declare const combineDecryptionShares: (ciphertext: ElGamalCiphertext, decryptionShares: readonly DecryptionShare[], bound: bigint) => bigint;

package/dist/threshold/decrypt.js

@@ -1,3 +1,10 @@
+/**
+ * Threshold decryption and bounded tally-recovery helpers.
+ *
+ * These functions are used after ballot aggregation has produced a verified
+ * additive ciphertext and before tally publication or verifier-side tally
+ * recomputation.
+ */
 import { hexToBytes } from '../core/bytes.js';
 import { assertInSubgroupOrIdentity, assertScalarInZq, assertValidPublicKey, IndexOutOfRangeError, InvalidShareError, PlaintextDomainError, RISTRETTO_GROUP, modInvQ, modQ, } from '../core/index.js';
 import { decodePoint, encodePoint, hashChallengeToScalar, pointAdd, pointMultiply, pointSubtract, RISTRETTO_ZERO, } from '../core/ristretto.js';
@@ -57,7 +64,10 @@ export const lagrangeCoefficient = (participantIndex, allIndices, q) => {
     return modQ(numerator * modInvQ(denominator, q), q);
 };
 /**
- * Creates a partial decryption share `d_i = x_i C_1`.
+ * Creates one trustee's partial decryption share `d_i = x_i C_1`.
+ *
+ * This is the low-level share value that applications typically prove with
+ * DLEQ and then publish inside a signed `decryption-share` payload.
  */
 export const createDecryptionShare = (ciphertext, share) => {
     assertPositiveIndex(share.index, 'Share');
@@ -69,13 +79,14 @@ export const createDecryptionShare = (ciphertext, share) => {
     };
 };
 /**
- * Prepares a verified aggregate for decryption.
+ * Prepares a verified aggregate for decryption-share generation and DLEQ
+ * proving.
  *
  * When the accepted aggregate has identity `c1`, the raw DLEQ statement would
  * degenerate because every participant would obtain the same identity-valued
- * partial share. This helper deterministically adds a public encryption of zero
- * in that corner case so the plaintext stays unchanged while the decryption
- * proof statement remains meaningful.
+ * partial share. This helper deterministically adds a public encryption of
+ * zero in that corner case so the plaintext stays unchanged while the
+ * decryption proof statement remains meaningful.
  */
 export const prepareAggregateForDecryption = (input) => {
     assertVerifiedAggregate(input.aggregate);
@@ -92,6 +103,10 @@ export const prepareAggregateForDecryption = (input) => {
 };
 /**
  * Combines indexed decryption shares via Lagrange interpolation at `x = 0`.
+ *
+ * This is the final bounded plaintext-recovery step. In the supported voting
+ * workflow it runs only after the transcript, ballot aggregation, and
+ * decryption-share proofs have already been verified.
  */
 export const combineDecryptionShares = (ciphertext, decryptionShares, bound) => {
     if (decryptionShares.length === 0) {

package/dist/threshold/public.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Threshold-share and bounded tally-reconstruction helpers.
+ *
+ * Use this module when you need to prepare aggregates, create decryption
+ * shares, or reconstruct tallies directly.
+ *
+ * @module threshold-elgamal/threshold
+ * @packageDocumentation
+ */
+export { combineDecryptionShares, createDecryptionShare, prepareAggregateForDecryption, } from './decrypt.js';
+export type { AggregateDecryptionPreparationInput, DecryptionShare, Share, VerifiedAggregateCiphertext, } from './types.js';

package/dist/threshold/public.js

@@ -0,0 +1,10 @@
+/**
+ * Threshold-share and bounded tally-reconstruction helpers.
+ *
+ * Use this module when you need to prepare aggregates, create decryption
+ * shares, or reconstruct tallies directly.
+ *
+ * @module threshold-elgamal/threshold
+ * @packageDocumentation
+ */
+export { combineDecryptionShares, createDecryptionShare, prepareAggregateForDecryption, } from './decrypt.js';

package/dist/threshold/types.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Threshold-decryption types that bridge verified ballot aggregates, indexed
+ * shares, and the final bounded plaintext reconstruction step.
+ */
 import type { EncodedPoint } from '../core/types.js';
 import type { ElGamalCiphertext } from '../elgamal/types.js';
 /** A single indexed Shamir share over `Z_q`. */
@@ -7,7 +11,12 @@ export type Share = {
     /** Share value `f(index) mod q`. */
     readonly value: bigint;
 };
-/** A participant's partial decryption contribution. */
+/**
+ * A participant's partial decryption contribution for one verified aggregate.
+ *
+ * These values are the low-level shares later wrapped into signed
+ * `decryption-share` protocol payloads.
+ */
 export type DecryptionShare = {
     /** 1-based participant index matching the source share. */
     readonly index: number;
@@ -15,7 +24,12 @@ export type DecryptionShare = {
     readonly value: EncodedPoint;
 };
 declare const verifiedAggregateBrand: unique symbol;
-/** A threshold aggregate tied to a verified additive ciphertext. */
+/**
+ * A threshold aggregate tied to a verified additive ciphertext.
+ *
+ * The branding step prevents callers from skipping ballot verification and
+ * constructing arbitrary objects that merely look like verified aggregates.
+ */
 export type VerifiedAggregateCiphertext = {
     /** Canonical transcript hash that anchors the accepted ballot log. */
     readonly transcriptHash: string;
@@ -26,13 +40,18 @@ export type VerifiedAggregateCiphertext = {
     /** Opaque brand preventing arbitrary object-literal construction. */
     readonly [verifiedAggregateBrand]: true;
 };
-/** Public context needed to prepare a verified aggregate for decryption. */
+/**
+ * Public context needed to prepare a verified aggregate for decryption.
+ *
+ * This binds the rerandomization corner case to the exact ceremony, manifest,
+ * and option slot being processed.
+ */
 export type AggregateDecryptionPreparationInput = {
     /** Verified aggregate recomputed from the accepted ballot transcript. */
     readonly aggregate: VerifiedAggregateCiphertext;
     /** Joint public key used to encrypt the original ballots. */
     readonly publicKey: EncodedPoint;
-    /** Bound protocol version carried by the ceremony transcript. */
+    /** Protocol namespace carried by the ceremony transcript. */
     readonly protocolVersion: string;
     /** Manifest hash that anchors the ceremony context. */
     readonly manifestHash: string;

package/dist/transport/auth.d.ts

@@ -7,38 +7,32 @@ type GenerateAuthKeyPairOptions = {
 /**
  * Generates a fresh per-ceremony authentication key pair.
  *
- * @returns Authentication key pair. The private key is extractable only when requested.
+ * Trustees use this key pair to sign every public payload they publish during
+ * setup, DKG, voting, and tally publication.
  */
 export declare const generateAuthKeyPair: (options?: GenerateAuthKeyPairOptions) => Promise<CryptoKeyPair>;
 /**
- * Exports an authentication public key as SPKI hex.
- *
- * @param publicKey Authentication public key.
- * @returns Lowercase hexadecimal SPKI bytes.
+ * Exports an authentication public key as SPKI hex so it can be published in a
+ * registration payload and later imported by verifiers.
  */
 export declare const exportAuthPublicKey: (publicKey: CryptoKey) => Promise<EncodedAuthPublicKey>;
 /**
- * Imports an authentication public key from SPKI hex.
- *
- * @param spkiHex Lowercase hexadecimal SPKI bytes.
- * @returns Imported public key.
+ * Imports an authentication public key from the canonical published SPKI
+ * encoding.
  */
 export declare const importAuthPublicKey: (spkiHex: EncodedAuthPublicKey) => Promise<CryptoKey>;
 /**
  * Signs canonical payload bytes with an authentication private key.
  *
- * @param privateKey Authentication private key.
- * @param payloadBytes Canonical unsigned payload bytes.
- * @returns Lowercase hexadecimal raw Ed25519 signature bytes.
+ * Protocol builders call this after they have frozen the payload shape and
+ * canonical serialization.
  */
 export declare const signPayloadBytes: (privateKey: CryptoKey, payloadBytes: Uint8Array) => Promise<string>;
 /**
  * Verifies canonical payload bytes against an authentication signature.
  *
- * @param publicKey Authentication public key.
- * @param payloadBytes Canonical unsigned payload bytes.
- * @param signatureHex Lowercase hexadecimal raw Ed25519 signature bytes.
- * @returns `true` when the signature verifies.
+ * Signature verification for published board payloads ultimately routes
+ * through this helper.
  */
 export declare const verifyPayloadSignature: (publicKey: CryptoKey, payloadBytes: Uint8Array, signatureHex: string) => Promise<boolean>;
 export {};

package/dist/transport/auth.js

@@ -1,25 +1,28 @@
+/**
+ * Ed25519 authentication-key and signature helpers.
+ *
+ * Every published protocol payload is signed through this layer, either
+ * directly or via the higher-level protocol builders.
+ */
 import { bytesToHex, hexToBytes, toBufferSource } from '../core/bytes.js';
 import { getWebCrypto } from '../core/index.js';
 /**
  * Generates a fresh per-ceremony authentication key pair.
  *
- * @returns Authentication key pair. The private key is extractable only when requested.
+ * Trustees use this key pair to sign every public payload they publish during
+ * setup, DKG, voting, and tally publication.
  */
 export const generateAuthKeyPair = async (options = {}) => getWebCrypto().subtle.generateKey({
     name: 'Ed25519',
 }, options.extractable ?? false, ['sign', 'verify']);
 /**
- * Exports an authentication public key as SPKI hex.
- *
- * @param publicKey Authentication public key.
- * @returns Lowercase hexadecimal SPKI bytes.
+ * Exports an authentication public key as SPKI hex so it can be published in a
+ * registration payload and later imported by verifiers.
  */
 export const exportAuthPublicKey = async (publicKey) => bytesToHex(new Uint8Array(await getWebCrypto().subtle.exportKey('spki', publicKey)));
 /**
- * Imports an authentication public key from SPKI hex.
- *
- * @param spkiHex Lowercase hexadecimal SPKI bytes.
- * @returns Imported public key.
+ * Imports an authentication public key from the canonical published SPKI
+ * encoding.
  */
 export const importAuthPublicKey = async (spkiHex) => getWebCrypto().subtle.importKey('spki', toBufferSource(hexToBytes(spkiHex)), {
     name: 'Ed25519',
@@ -27,17 +30,14 @@ export const importAuthPublicKey = async (spkiHex) => getWebCrypto().subtle.impo
 /**
  * Signs canonical payload bytes with an authentication private key.
  *
- * @param privateKey Authentication private key.
- * @param payloadBytes Canonical unsigned payload bytes.
- * @returns Lowercase hexadecimal raw Ed25519 signature bytes.
+ * Protocol builders call this after they have frozen the payload shape and
+ * canonical serialization.
  */
 export const signPayloadBytes = async (privateKey, payloadBytes) => bytesToHex(new Uint8Array(await getWebCrypto().subtle.sign('Ed25519', privateKey, toBufferSource(payloadBytes))));
 /**
  * Verifies canonical payload bytes against an authentication signature.
  *
- * @param publicKey Authentication public key.
- * @param payloadBytes Canonical unsigned payload bytes.
- * @param signatureHex Lowercase hexadecimal raw Ed25519 signature bytes.
- * @returns `true` when the signature verifies.
+ * Signature verification for published board payloads ultimately routes
+ * through this helper.
  */
 export const verifyPayloadSignature = async (publicKey, payloadBytes, signatureHex) => getWebCrypto().subtle.verify('Ed25519', publicKey, toBufferSource(hexToBytes(signatureHex)), toBufferSource(payloadBytes));

package/dist/transport/complaints.d.ts

@@ -8,10 +8,8 @@ type ComplaintResolution = {
  * Resolves a dealer challenge using only public transcript material plus the
  * dealer-revealed sender-ephemeral private key.
  *
- * @param envelope Committed encrypted envelope.
- * @param recipientPublicKeyHex Registered recipient transport public key.
- * @param revealedEphemeralPrivateKeyHex Revealed sender-ephemeral private key.
- * @returns Complaint resolution result.
+ * The DKG verifier uses this to decide whether a complaint indicates dealer
+ * misconduct or a complaining recipient that published an invalid accusation.
  */
 export declare const resolveDealerChallengeFromPublicKey: (envelope: EncryptedEnvelope, recipientPublicKeyHex: EncodedTransportPublicKey, revealedEphemeralPrivateKeyHex: EncodedTransportPrivateKey) => Promise<ComplaintResolution>;
 export {};

package/dist/transport/complaints.js

@@ -1,3 +1,9 @@
+/**
+ * Complaint-resolution helpers for the encrypted share-transport layer.
+ *
+ * DKG transcript verification uses this module when it needs to reconstruct
+ * the expected public challenge material for a dealer complaint.
+ */
 import { hexToBytes, toBufferSource } from '../core/bytes.js';
 import { getWebCrypto } from '../core/index.js';
 import { deriveEnvelopeKey, encodeEnvelopeContext } from './envelopes.js';
@@ -14,10 +20,8 @@ const decryptEnvelopeFromSharedSecret = async (envelope, sharedSecret) => {
  * Resolves a dealer challenge using only public transcript material plus the
  * dealer-revealed sender-ephemeral private key.
  *
- * @param envelope Committed encrypted envelope.
- * @param recipientPublicKeyHex Registered recipient transport public key.
- * @param revealedEphemeralPrivateKeyHex Revealed sender-ephemeral private key.
- * @returns Complaint resolution result.
+ * The DKG verifier uses this to decide whether a complaint indicates dealer
+ * misconduct or a complaining recipient that published an invalid accusation.
  */
 export const resolveDealerChallengeFromPublicKey = async (envelope, recipientPublicKeyHex, revealedEphemeralPrivateKeyHex) => {
     const ephemeralKeyMatches = await verifyLocalTransportKey(revealedEphemeralPrivateKeyHex, envelope.ephemeralPublicKey);

package/dist/transport/envelopes.d.ts

@@ -4,10 +4,9 @@ export declare const deriveEnvelopeKey: (sharedSecret: Uint8Array, context: Enve
 /**
  * Encrypts a payload into a sender-ephemeral authenticated envelope.
  *
- * @param plaintext Raw payload bytes to encrypt.
- * @param recipientPublicKeyHex Recipient transport public key.
- * @param context Envelope binding context.
- * @returns Envelope plus the sender-ephemeral private key for complaint recovery.
+ * DKG dealers use this when publishing encrypted Pedersen shares for one
+ * recipient. The returned ephemeral private key is retained so complaint
+ * resolution can later prove what was sent.
  */
 export declare const encryptEnvelope: (plaintext: Uint8Array, recipientPublicKeyHex: EncodedTransportPublicKey, context: EnvelopeContext) => Promise<{
     readonly envelope: EncryptedEnvelope;
@@ -16,8 +15,7 @@ export declare const encryptEnvelope: (plaintext: Uint8Array, recipientPublicKey
 /**
  * Decrypts an authenticated envelope with the recipient transport private key.
  *
- * @param envelope Authenticated encrypted envelope.
- * @param recipientPrivateKey Recipient transport private key.
- * @returns Decrypted plaintext bytes.
+ * This is the recipient-side counterpart to {@link encryptEnvelope} and is
+ * typically followed by Pedersen share decoding.
  */
 export declare const decryptEnvelope: (envelope: EncryptedEnvelope, recipientPrivateKey: CryptoKey | EncodedTransportPrivateKey) => Promise<Uint8Array>;

package/dist/transport/envelopes.js

@@ -1,3 +1,7 @@
+/**
+ * Authenticated sender-ephemeral envelope helpers for dealer-to-recipient
+ * transport during DKG share distribution.
+ */
 import { bytesToHex, hexToBytes, toBufferSource } from '../core/bytes.js';
 import { getWebCrypto, hkdfSha256, randomBytes } from '../core/index.js';
 import { encodeForChallenge } from '../serialize/encoding.js';
@@ -8,10 +12,9 @@ export const deriveEnvelopeKey = async (sharedSecret, context, usages = ['encryp
 /**
  * Encrypts a payload into a sender-ephemeral authenticated envelope.
  *
- * @param plaintext Raw payload bytes to encrypt.
- * @param recipientPublicKeyHex Recipient transport public key.
- * @param context Envelope binding context.
- * @returns Envelope plus the sender-ephemeral private key for complaint recovery.
+ * DKG dealers use this when publishing encrypted Pedersen shares for one
+ * recipient. The returned ephemeral private key is retained so complaint
+ * resolution can later prove what was sent.
  */
 export const encryptEnvelope = async (plaintext, recipientPublicKeyHex, context) => {
     const ephemeral = await generateTransportKeyPair({
@@ -39,9 +42,8 @@ export const encryptEnvelope = async (plaintext, recipientPublicKeyHex, context)
 /**
  * Decrypts an authenticated envelope with the recipient transport private key.
  *
- * @param envelope Authenticated encrypted envelope.
- * @param recipientPrivateKey Recipient transport private key.
- * @returns Decrypted plaintext bytes.
+ * This is the recipient-side counterpart to {@link encryptEnvelope} and is
+ * typically followed by Pedersen share decoding.
  */
 export const decryptEnvelope = async (envelope, recipientPrivateKey) => {
     const resolvedRecipientPrivateKey = typeof recipientPrivateKey === 'string'

package/dist/transport/key-agreement.d.ts

@@ -14,53 +14,45 @@ export declare const assertNonZeroSharedSecret: (sharedSecret: Uint8Array) => vo
 /**
  * Generates an X25519 transport key pair.
  *
- * @param options Generation options.
- * @returns Transport key pair tagged with the shipped X25519 suite.
+ * Trustees publish the public half in their registration payloads and keep the
+ * private half for decrypting inbound dealer envelopes.
  */
 export declare const generateTransportKeyPair: (options?: GenerateTransportKeyPairOptions) => Promise<TransportKeyPair>;
 /**
- * Exports a transport public key as raw lowercase hexadecimal bytes.
- *
- * @param publicKey Transport public key.
- * @returns Lowercase hexadecimal public key bytes.
+ * Exports a transport public key as raw lowercase hexadecimal bytes so it can
+ * be published in a registration payload.
  */
 export declare const exportTransportPublicKey: (publicKey: CryptoKey) => Promise<EncodedTransportPublicKey>;
 /**
  * Exports a transport private key as PKCS#8 lowercase hexadecimal bytes.
  *
- * @param privateKey Transport private key.
- * @returns Lowercase hexadecimal PKCS#8 bytes.
+ * This is mainly useful for persistence and tests.
  */
 export declare const exportTransportPrivateKey: (privateKey: CryptoKey) => Promise<EncodedTransportPrivateKey>;
 /**
- * Imports a transport public key from raw hexadecimal bytes.
- *
- * @param publicKeyHex Lowercase hexadecimal public key bytes.
- * @returns Imported transport public key.
+ * Imports a transport public key from the canonical raw hexadecimal encoding
+ * published on the board.
  */
 export declare const importTransportPublicKey: (publicKeyHex: EncodedTransportPublicKey) => Promise<CryptoKey>;
 export declare const assertSupportedTransportPublicKeyEncoding: (publicKeyHex: EncodedTransportPublicKey, label?: string) => void;
 /**
- * Imports a transport private key from PKCS#8 hexadecimal bytes.
- *
- * @param privateKeyHex Lowercase hexadecimal PKCS#8 bytes.
- * @returns Imported transport private key.
+ * Imports a transport private key from the canonical PKCS#8 hexadecimal
+ * encoding.
  */
 export declare const importTransportPrivateKey: (privateKeyHex: EncodedTransportPrivateKey) => Promise<CryptoKey>;
 /**
  * Derives a raw shared secret for X25519.
  *
- * @param privateKey Local transport private key.
- * @param publicKey Peer transport public key.
- * @returns Raw shared secret bytes.
+ * Envelope encryption and decryption both route through this shared-secret
+ * derivation step before expanding the result with HKDF.
  */
 export declare const deriveTransportSharedSecret: (privateKey: CryptoKey, publicKey: CryptoKey) => Promise<Uint8Array>;
 /**
- * Verifies that a local transport private key matches the registered public key.
+ * Verifies that a local transport private key matches the registered public
+ * key.
  *
- * @param privateKey Local transport private key.
- * @param expectedPublicKeyHex Registered public key bytes.
- * @returns `true` when the private key expands to `expectedPublicKeyHex`.
+ * This is useful when loading persisted local key material for an already
+ * published registration record.
  */
 export declare const verifyLocalTransportKey: (privateKey: CryptoKey | EncodedTransportPrivateKey, expectedPublicKeyHex: EncodedTransportPublicKey) => Promise<boolean>;
 export {};

package/dist/transport/key-agreement.js

@@ -1,3 +1,9 @@
+/**
+ * X25519 transport-key helpers used for encrypted DKG share delivery.
+ *
+ * These functions stay lower-level than the protocol builders so applications
+ * and tests can manage key export, import, and local verification directly.
+ */
 import { bytesToHex, hexToBytes, toBufferSource } from '../core/bytes.js';
 import { InvalidPayloadError, getWebCrypto } from '../core/index.js';
 const X25519_BASE_POINT = (() => {
@@ -30,8 +36,8 @@ export const assertNonZeroSharedSecret = (sharedSecret) => {
 /**
  * Generates an X25519 transport key pair.
  *
- * @param options Generation options.
- * @returns Transport key pair tagged with the shipped X25519 suite.
+ * Trustees publish the public half in their registration payloads and keep the
+ * private half for decrypting inbound dealer envelopes.
  */
 export const generateTransportKeyPair = async (options = {}) => {
     const keyPair = await getWebCrypto().subtle.generateKey(x25519Algorithm, options.extractable ?? false, ['deriveBits']);
@@ -42,24 +48,19 @@ export const generateTransportKeyPair = async (options = {}) => {
     };
 };
 /**
- * Exports a transport public key as raw lowercase hexadecimal bytes.
- *
- * @param publicKey Transport public key.
- * @returns Lowercase hexadecimal public key bytes.
+ * Exports a transport public key as raw lowercase hexadecimal bytes so it can
+ * be published in a registration payload.
  */
 export const exportTransportPublicKey = async (publicKey) => bytesToHex(new Uint8Array(await getWebCrypto().subtle.exportKey('raw', publicKey)));
 /**
  * Exports a transport private key as PKCS#8 lowercase hexadecimal bytes.
  *
- * @param privateKey Transport private key.
- * @returns Lowercase hexadecimal PKCS#8 bytes.
+ * This is mainly useful for persistence and tests.
  */
 export const exportTransportPrivateKey = async (privateKey) => bytesToHex(new Uint8Array(await getWebCrypto().subtle.exportKey('pkcs8', privateKey)));
 /**
- * Imports a transport public key from raw hexadecimal bytes.
- *
- * @param publicKeyHex Lowercase hexadecimal public key bytes.
- * @returns Imported transport public key.
+ * Imports a transport public key from the canonical raw hexadecimal encoding
+ * published on the board.
  */
 export const importTransportPublicKey = async (publicKeyHex) => {
     const publicKeyBytes = hexToBytes(publicKeyHex);
@@ -77,18 +78,15 @@ export const assertSupportedTransportPublicKeyEncoding = (publicKeyHex, label =
     assertValidX25519PublicKeyBytes(publicKeyBytes, label);
 };
 /**
- * Imports a transport private key from PKCS#8 hexadecimal bytes.
- *
- * @param privateKeyHex Lowercase hexadecimal PKCS#8 bytes.
- * @returns Imported transport private key.
+ * Imports a transport private key from the canonical PKCS#8 hexadecimal
+ * encoding.
  */
 export const importTransportPrivateKey = async (privateKeyHex) => getWebCrypto().subtle.importKey('pkcs8', toBufferSource(hexToBytes(privateKeyHex)), x25519Algorithm, true, ['deriveBits']);
 /**
  * Derives a raw shared secret for X25519.
  *
- * @param privateKey Local transport private key.
- * @param publicKey Peer transport public key.
- * @returns Raw shared secret bytes.
+ * Envelope encryption and decryption both route through this shared-secret
+ * derivation step before expanding the result with HKDF.
  */
 export const deriveTransportSharedSecret = async (privateKey, publicKey) => {
     const sharedSecret = new Uint8Array(await getWebCrypto().subtle.deriveBits({
@@ -109,11 +107,11 @@ const deriveTransportPublicKey = async (privateKey) => {
     return bytesToHex(await deriveTransportSharedSecret(privateKey, basePoint));
 };
 /**
- * Verifies that a local transport private key matches the registered public key.
+ * Verifies that a local transport private key matches the registered public
+ * key.
  *
- * @param privateKey Local transport private key.
- * @param expectedPublicKeyHex Registered public key bytes.
- * @returns `true` when the private key expands to `expectedPublicKeyHex`.
+ * This is useful when loading persisted local key material for an already
+ * published registration record.
  */
 export const verifyLocalTransportKey = async (privateKey, expectedPublicKeyHex) => {
     try {