threshold-elgamal 1.0.9 → 2.0.0

package/dist/protocol/builders.js

@@ -1,3 +1,9 @@
+/**
+ * Public payload-builder façade for the supported ceremony.
+ *
+ * Application-facing code normally uses this module instead of hand-assembling
+ * protocol payload objects and signatures.
+ */
 import { encodeScalar } from '../core/ristretto.js';
 import { signPayloadBytes } from '../transport/auth.js';
 import { attachProtocolVersion, signedProtocolPayloadBytes } from './payloads.js';
@@ -7,7 +13,12 @@ import { assertUniqueSortedIndices, BALLOT_CLOSE_PHASE, BALLOT_SUBMISSION_PHASE,
 const isEncodedDisjunctiveProof = (proof) => typeof proof.branches[0]?.challenge === 'string';
 const isEncodedCompactProof = (proof) => typeof proof.challenge === 'string';
 const isEncodedFeldmanProofEntry = (proof) => typeof proof.challenge === 'string';
-/** Signs one canonical protocol payload with a participant auth key. */
+/**
+ * Signs one canonical protocol payload with a participant auth key.
+ *
+ * All specialized payload builders in this module eventually route through
+ * this helper after normalizing the payload shape.
+ */
 export const signProtocolPayload = async (privateKey, payload) => {
     const signedPayload = attachProtocolVersion(payload);
     return {
@@ -15,7 +26,12 @@ export const signProtocolPayload = async (privateKey, payload) => {
         signature: await signPayloadBytes(privateKey, signedProtocolPayloadBytes(signedPayload)),
     };
 };
-/** Creates a signed manifest-publication payload. */
+/**
+ * Creates a signed `manifest-publication` payload.
+ *
+ * This is the first public payload in the supported ceremony and anchors the
+ * explicit manifest on the board.
+ */
 export const createManifestPublicationPayload = async (privateKey, input) => signProtocolPayload(privateKey, {
     protocolVersion: input.protocolVersion,
     sessionId: input.sessionId,
@@ -25,7 +41,12 @@ export const createManifestPublicationPayload = async (privateKey, input) => sig
     messageType: 'manifest-publication',
     manifest: input.manifest,
 });
-/** Creates a signed registration payload for one participant. */
+/**
+ * Creates a signed `registration` payload for one participant.
+ *
+ * Registrations publish the participant's auth key and transport key and are
+ * the source of truth for the accepted roster.
+ */
 export const createRegistrationPayload = async (privateKey, input) => signProtocolPayload(privateKey, {
     protocolVersion: input.protocolVersion,
     sessionId: input.sessionId,
@@ -37,7 +58,12 @@ export const createRegistrationPayload = async (privateKey, input) => signProtoc
     authPublicKey: input.authPublicKey,
     transportPublicKey: input.transportPublicKey,
 });
-/** Creates a signed manifest-acceptance payload. */
+/**
+ * Creates a signed `manifest-acceptance` payload.
+ *
+ * This records that a participant accepted the frozen manifest and the roster
+ * hash under which they were assigned an index.
+ */
 export const createManifestAcceptancePayload = async (privateKey, input) => signProtocolPayload(privateKey, {
     protocolVersion: input.protocolVersion,
     sessionId: input.sessionId,
@@ -53,7 +79,12 @@ export const createManifestAcceptancePayload = async (privateKey, input) => sign
             accountIdHash: input.accountIdHash,
         }),
 });
-/** Creates a signed phase-checkpoint payload over one DKG phase snapshot. */
+/**
+ * Creates a signed `phase-checkpoint` payload over one DKG phase snapshot.
+ *
+ * Checkpoints let observers replay the DKG in coarse-grained epochs while
+ * preserving deterministic transcript commitments.
+ */
 export const createPhaseCheckpointPayload = async (privateKey, input) => signProtocolPayload(privateKey, {
     protocolVersion: input.protocolVersion,
     sessionId: input.sessionId,
@@ -65,20 +96,32 @@ export const createPhaseCheckpointPayload = async (privateKey, input) => signPro
     checkpointTranscriptHash: await hashProtocolPhaseSnapshot(input.transcript.map((entry) => entry.payload), input.checkpointPhase),
     qualifiedParticipantIndices: [...input.qualifiedParticipantIndices],
 });
-/** Creates a signed Pedersen-commitment payload for DKG phase 1. */
+/**
+ * Creates a signed `pedersen-commitment` payload for DKG phase 1.
+ */
 export const createPedersenCommitmentPayload = async (privateKey, input) => signProtocolPayload(privateKey, {
     ...input,
     phase: 1,
     messageType: 'pedersen-commitment',
     commitments: [...input.commitments],
 });
-/** Creates a signed encrypted dual-share payload for DKG phase 1. */
+/**
+ * Creates a signed `encrypted-dual-share` payload for DKG phase 1.
+ *
+ * The envelope contents are produced separately by the transport layer and are
+ * merely wrapped and signed here.
+ */
 export const createEncryptedDualSharePayload = async (privateKey, input) => signProtocolPayload(privateKey, {
     ...input,
     phase: 1,
     messageType: 'encrypted-dual-share',
 });
-/** Creates a signed Feldman-commitment payload for DKG phase 3. */
+/**
+ * Creates a signed `feldman-commitment` payload for DKG phase 3.
+ *
+ * This payload exposes the public Feldman commitments and their Schnorr proofs
+ * after the complaint phase has been resolved.
+ */
 export const createFeldmanCommitmentPayload = async (privateKey, input) => {
     const payload = {
         ...input,
@@ -97,13 +140,25 @@ export const createFeldmanCommitmentPayload = async (privateKey, input) => {
     };
     return signProtocolPayload(privateKey, payload);
 };
-/** Creates a signed key-derivation-confirmation payload for DKG phase 4. */
+/**
+ * Creates a signed `key-derivation-confirmation` payload for DKG phase 4.
+ *
+ * Trustees use this to confirm the final derived joint key and transcript
+ * digest they believe the DKG produced.
+ */
 export const createKeyDerivationConfirmationPayload = async (privateKey, input) => signProtocolPayload(privateKey, {
     ...input,
     phase: 4,
     messageType: 'key-derivation-confirmation',
 });
-/** Creates a signed ballot payload for one participant and one option slot. */
+/**
+ * Creates a signed `ballot-submission` payload for one participant and one
+ * option slot.
+ *
+ * Higher-level application code is expected to create the ciphertext and
+ * disjunctive proof first, then hand them to this builder for encoding and
+ * signing.
+ */
 export const createBallotSubmissionPayload = async (privateKey, input) => {
     const payload = {
         ...input,
@@ -116,7 +171,12 @@ export const createBallotSubmissionPayload = async (privateKey, input) => {
     };
     return signProtocolPayload(privateKey, payload);
 };
-/** Creates the organizer-signed ballot cutoff payload. */
+/**
+ * Creates the organizer-signed `ballot-close` payload.
+ *
+ * This freezes which complete ballots are counted for the tally and therefore
+ * determines the accepted aggregate seen by every later decryption step.
+ */
 export const createBallotClosePayload = async (privateKey, input) => {
     const countedParticipantIndices = [...input.countedParticipantIndices].sort((left, right) => left - right);
     assertUniqueSortedIndices(countedParticipantIndices, 'Ballot close participant');
@@ -127,7 +187,12 @@ export const createBallotClosePayload = async (privateKey, input) => {
         countedParticipantIndices,
     });
 };
-/** Creates a signed threshold decryption-share payload for one option slot. */
+/**
+ * Creates a signed `decryption-share` payload for one option slot.
+ *
+ * The caller is responsible for computing the share and DLEQ proof first; this
+ * helper encodes and signs the published object.
+ */
 export const createDecryptionSharePayload = async (privateKey, input) => {
     const payload = {
         ...input,
@@ -139,7 +204,12 @@ export const createDecryptionSharePayload = async (privateKey, input) => {
     };
     return signProtocolPayload(privateKey, payload);
 };
-/** Creates a signed tally-publication payload for one option slot. */
+/**
+ * Creates a signed `tally-publication` payload for one option slot.
+ *
+ * This is the final organizer-facing publication step after the accepted
+ * decryption shares have been combined into a bounded plaintext tally.
+ */
 export const createTallyPublicationPayload = async (privateKey, input) => {
     const decryptionParticipantIndices = [
         ...input.decryptionParticipantIndices,

package/dist/protocol/canonical-json.js

@@ -1,3 +1,7 @@
+/**
+ * Deterministic JSON serialization for manifests, protocol payloads, and
+ * other transcript-bound objects.
+ */
 import { InvalidPayloadError } from '../core/index.js';
 import { bigintToFixedHex } from '../serialize/encoding.js';
 const canonicalize = (value, options) => {

package/dist/protocol/manifest.d.ts

@@ -1,18 +1,38 @@
 import type { ElectionManifest } from './types.js';
-/** Fixed transcript version string for the shipped beta protocol. */
+/**
+ * Default protocol namespace used by the built-in helpers and verifier.
+ *
+ * The current verifier only accepts this namespace, so applications that want
+ * verifier-compatible payloads should treat this value as fixed.
+ */
 export declare const SHIPPED_PROTOCOL_VERSION = "v1";
-/** Validates that a protocol version string is present. */
+/**
+ * Validates that a protocol version string is present and non-empty.
+ *
+ * Builders use this to normalize explicit overrides before attaching them to
+ * published payloads.
+ */
 export declare const assertValidProtocolVersion: (protocolVersion: string, label?: string) => string;
-/** Validates that a protocol version matches the shipped verifier line. */
+/**
+ * Validates that a protocol version matches the verifier namespace.
+ *
+ * Verifier-facing paths call this when they need to reject protocol variants
+ * that are outside the package's supported public workflow.
+ */
 export declare const assertSupportedProtocolVersion: (protocolVersion: string, label?: string) => string;
 /**
- * Validates the supported election-manifest invariants for the shipped
- * score-voting workflow.
+ * Validates the supported election-manifest invariants for the score-voting
+ * workflow.
  *
- * @param manifest Election manifest to validate.
+ * The manifest is intentionally minimal: it fixes the frozen roster hash and
+ * option list together with one explicit global score range, while participant
+ * count and threshold are derived later from the accepted registration roster.
  */
 export declare const validateElectionManifest: (manifest: ElectionManifest) => ElectionManifest;
-/** Creates the minimal shipped election manifest. */
+/**
+ * Creates the explicit election manifest after validating the supported
+ * invariants.
+ */
 export declare const createElectionManifest: (manifest: ElectionManifest) => ElectionManifest;
 /**
  * Canonically serializes an election manifest.
@@ -24,18 +44,15 @@ export declare const canonicalizeElectionManifest: (manifest: ElectionManifest)
 /**
  * Hashes a canonical election manifest with SHA-256.
  *
- * @param manifest Election manifest to hash.
- * @returns Lowercase hexadecimal SHA-256 digest.
+ * The resulting digest is the manifest anchor reused by every later payload,
+ * proof context, and verifier stage.
  */
 export declare const hashElectionManifest: (manifest: ElectionManifest) => Promise<string>;
 /**
  * Derives a globally unique session identifier from the frozen setup values.
  *
- * @param manifestHash Canonical manifest hash.
- * @param rosterHash Canonical roster hash.
- * @param randomNonce Public random nonce.
- * @param timestamp Timestamp string included in the derivation.
- * @param protocolVersion Protocol version namespace for the derived session.
- * @returns Lowercase hexadecimal SHA-256 digest.
+ * Applications normally compute this once after freezing the manifest and
+ * roster so every later payload can bind itself to one concrete ceremony
+ * instance.
  */
 export declare const deriveSessionId: (manifestHash: string, rosterHash: string, randomNonce: string, timestamp: string, protocolVersion?: string) => Promise<string>;

package/dist/protocol/manifest.js

@@ -1,20 +1,59 @@
+/**
+ * Manifest validation, hashing, and session-derivation helpers.
+ *
+ * This is the entry point for freezing the ceremony root that every later DKG,
+ * ballot, decryption-share, and tally payload binds to.
+ */
 import { bytesToHex } from '../core/bytes.js';
 import { InvalidPayloadError, sha256, utf8ToBytes } from '../core/index.js';
 import { encodeForChallenge } from '../serialize/encoding.js';
 import { canonicalizeJson } from './canonical-json.js';
-/** Fixed transcript version string for the shipped beta protocol. */
+import { validateSupportedScoreRange } from './score-range.js';
+/**
+ * Default protocol namespace used by the built-in helpers and verifier.
+ *
+ * The current verifier only accepts this namespace, so applications that want
+ * verifier-compatible payloads should treat this value as fixed.
+ */
 export const SHIPPED_PROTOCOL_VERSION = 'v1';
 const assertNonEmptyString = (value, label) => {
     if (value.trim() === '') {
         throw new InvalidPayloadError(`${label} must be a non-empty string`);
     }
 };
-/** Validates that a protocol version string is present. */
+const validateScoreRange = (scoreRange) => {
+    if (typeof scoreRange !== 'object' ||
+        scoreRange === null ||
+        Array.isArray(scoreRange)) {
+        throw new InvalidPayloadError('Election manifest scoreRange must be an object with min and max bounds');
+    }
+    const scoreRangeRecord = scoreRange;
+    if (typeof scoreRangeRecord.min !== 'number' ||
+        typeof scoreRangeRecord.max !== 'number') {
+        throw new InvalidPayloadError('Election manifest scoreRange requires numeric min and max bounds');
+    }
+    return validateSupportedScoreRange(scoreRange, {
+        comparisonMax: 'scoreRange.max',
+        min: 'Election manifest scoreRange.min',
+        max: 'Election manifest scoreRange.max',
+    });
+};
+/**
+ * Validates that a protocol version string is present and non-empty.
+ *
+ * Builders use this to normalize explicit overrides before attaching them to
+ * published payloads.
+ */
 export const assertValidProtocolVersion = (protocolVersion, label = 'Protocol version') => {
     assertNonEmptyString(protocolVersion, label);
     return protocolVersion;
 };
-/** Validates that a protocol version matches the shipped verifier line. */
+/**
+ * Validates that a protocol version matches the verifier namespace.
+ *
+ * Verifier-facing paths call this when they need to reject protocol variants
+ * that are outside the package's supported public workflow.
+ */
 export const assertSupportedProtocolVersion = (protocolVersion, label = 'Protocol version') => {
     assertValidProtocolVersion(protocolVersion, label);
     if (protocolVersion !== SHIPPED_PROTOCOL_VERSION) {
@@ -23,14 +62,19 @@ export const assertSupportedProtocolVersion = (protocolVersion, label = 'Protoco
     return protocolVersion;
 };
 /**
- * Validates the supported election-manifest invariants for the shipped
- * score-voting workflow.
+ * Validates the supported election-manifest invariants for the score-voting
+ * workflow.
  *
- * @param manifest Election manifest to validate.
+ * The manifest is intentionally minimal: it fixes the frozen roster hash and
+ * option list together with one explicit global score range, while participant
+ * count and threshold are derived later from the accepted registration roster.
  */
 export const validateElectionManifest = (manifest) => {
     const manifestRecord = manifest;
     assertNonEmptyString(manifest.rosterHash, 'Roster hash');
+    if (!('scoreRange' in manifestRecord)) {
+        throw new InvalidPayloadError('Election manifest requires an explicit scoreRange');
+    }
     for (const legacyField of [
         'participantCount',
         'reconstructionThreshold',
@@ -48,7 +92,7 @@ export const validateElectionManifest = (manifest) => {
         'requiresAllOptions',
     ]) {
         if (legacyField in manifestRecord) {
-            throw new InvalidPayloadError(`Legacy manifest field "${legacyField}" is not supported on the Ristretto beta line`);
+            throw new InvalidPayloadError(`Legacy manifest field "${legacyField}" is not supported by the public manifest`);
         }
     }
     if (manifest.optionList.length === 0) {
@@ -62,9 +106,15 @@ export const validateElectionManifest = (manifest) => {
         }
         seenOptions.add(option);
     }
-    return manifest;
+    return {
+        ...manifest,
+        scoreRange: validateScoreRange(manifest.scoreRange),
+    };
 };
-/** Creates the minimal shipped election manifest. */
+/**
+ * Creates the explicit election manifest after validating the supported
+ * invariants.
+ */
 export const createElectionManifest = (manifest) => validateElectionManifest(manifest);
 /**
  * Canonically serializes an election manifest.
@@ -76,18 +126,15 @@ export const canonicalizeElectionManifest = (manifest) => canonicalizeJson(valid
 /**
  * Hashes a canonical election manifest with SHA-256.
  *
- * @param manifest Election manifest to hash.
- * @returns Lowercase hexadecimal SHA-256 digest.
+ * The resulting digest is the manifest anchor reused by every later payload,
+ * proof context, and verifier stage.
  */
 export const hashElectionManifest = async (manifest) => bytesToHex(await sha256(utf8ToBytes(canonicalizeElectionManifest(manifest))));
 /**
  * Derives a globally unique session identifier from the frozen setup values.
  *
- * @param manifestHash Canonical manifest hash.
- * @param rosterHash Canonical roster hash.
- * @param randomNonce Public random nonce.
- * @param timestamp Timestamp string included in the derivation.
- * @param protocolVersion Protocol version namespace for the derived session.
- * @returns Lowercase hexadecimal SHA-256 digest.
+ * Applications normally compute this once after freezing the manifest and
+ * roster so every later payload can bind itself to one concrete ceremony
+ * instance.
  */
-export const deriveSessionId = async (manifestHash, rosterHash, randomNonce, timestamp, protocolVersion = SHIPPED_PROTOCOL_VERSION) => bytesToHex(await sha256(encodeForChallenge(assertValidProtocolVersion(protocolVersion, 'Session protocol version'), manifestHash, rosterHash, randomNonce, timestamp)));
+export const deriveSessionId = async (manifestHash, rosterHash, randomNonce, timestamp, protocolVersion) => bytesToHex(await sha256(encodeForChallenge(assertValidProtocolVersion(protocolVersion ?? SHIPPED_PROTOCOL_VERSION, 'Session protocol version'), manifestHash, rosterHash, randomNonce, timestamp)));

package/dist/protocol/ordering.js

@@ -1,3 +1,9 @@
+/**
+ * Deterministic ordering helpers for protocol payloads.
+ *
+ * Transcript hashing and board audit both rely on this ordering so all
+ * observers hash the same payload set in the same way.
+ */
 import { bytesToHex } from '../core/bytes.js';
 import { canonicalUnsignedPayloadBytes, payloadSlotKey } from './payloads.js';
 const compareStrings = (left, right) => {

package/dist/protocol/payloads.d.ts

@@ -21,9 +21,9 @@ export declare const canonicalUnsignedPayloadBytes: (payload: ProtocolPayload, b
 /**
  * Serializes the payload bytes that are covered by the outer Ed25519 signature.
  *
- * The signature preimage is domain-separated and version-bound so that protocol
- * payload signatures are not re-used across transcript families or protocol
- * revisions.
+ * The signature preimage is domain-separated and protocol-bound so that
+ * protocol payload signatures are not re-used across transcript families or
+ * protocol namespaces.
  *
  * @param payload Unsigned protocol payload.
  * @param bigintByteLength Fixed byte width used for any bigint fields.

package/dist/protocol/payloads.js

@@ -1,3 +1,7 @@
+/**
+ * Canonical protocol-payload attachment, serialization, and slot-classification
+ * helpers shared by payload builders, board audit, and verification.
+ */
 import { bytesToHex } from '../core/bytes.js';
 import { utf8ToBytes } from '../core/index.js';
 import { encodeForChallenge } from '../serialize/encoding.js';
@@ -48,9 +52,9 @@ export const canonicalUnsignedPayloadBytes = (payload, bigintByteLength) => utf8
 /**
  * Serializes the payload bytes that are covered by the outer Ed25519 signature.
  *
- * The signature preimage is domain-separated and version-bound so that protocol
- * payload signatures are not re-used across transcript families or protocol
- * revisions.
+ * The signature preimage is domain-separated and protocol-bound so that
+ * protocol payload signatures are not re-used across transcript families or
+ * protocol namespaces.
  *
  * @param payload Unsigned protocol payload.
  * @param bigintByteLength Fixed byte width used for any bigint fields.

package/dist/protocol/public.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Low-level protocol helpers for transcript hashing, generic signed payloads,
+ * registration-roster hashing, signature verification, ballot proof
+ * verification, and protocol payload types.
+ *
+ * Use this module when you want protocol helpers grouped by subsystem instead
+ * of importing them from the root package.
+ *
+ * @module threshold-elgamal/protocol
+ * @packageDocumentation
+ */
+export { signProtocolPayload } from './builders.js';
+export { hashProtocolTranscript } from './transcript.js';
+export { hashRosterEntries, verifySignedProtocolPayloads, type RosterEntry, type VerifiedProtocolSignatures, } from './verification.js';
+export { verifyBallotSubmissionPayloadsByOption } from './voting-ballots.js';
+export { scoreRangeDomain } from './voting-codecs.js';
+export type { EncodedCiphertext, EncodedCompactProof, EncodedDisjunctiveProof, ProtocolMessageType, ProtocolPayload, ScoreRange, } from './types.js';

package/dist/protocol/public.js

@@ -0,0 +1,16 @@
+/**
+ * Low-level protocol helpers for transcript hashing, generic signed payloads,
+ * registration-roster hashing, signature verification, ballot proof
+ * verification, and protocol payload types.
+ *
+ * Use this module when you want protocol helpers grouped by subsystem instead
+ * of importing them from the root package.
+ *
+ * @module threshold-elgamal/protocol
+ * @packageDocumentation
+ */
+export { signProtocolPayload } from './builders.js';
+export { hashProtocolTranscript } from './transcript.js';
+export { hashRosterEntries, verifySignedProtocolPayloads, } from './verification.js';
+export { verifyBallotSubmissionPayloadsByOption } from './voting-ballots.js';
+export { scoreRangeDomain } from './voting-codecs.js';

package/dist/protocol/score-range.d.ts

@@ -0,0 +1,6 @@
+import type { ScoreRange } from './types.js';
+export declare const validateSupportedScoreRange: (scoreRange: ScoreRange, labels: {
+    readonly comparisonMax?: string;
+    readonly min: string;
+    readonly max: string;
+}) => ScoreRange;

package/dist/protocol/score-range.js

@@ -0,0 +1,24 @@
+import { InvalidPayloadError } from '../core/index.js';
+const MAX_SUPPORTED_SCORE_RANGE_MAX = 100;
+const assertSafeInteger = (value, label) => {
+    if (!Number.isSafeInteger(value)) {
+        throw new InvalidPayloadError(`${label} must be a safe integer`);
+    }
+};
+export const validateSupportedScoreRange = (scoreRange, labels) => {
+    assertSafeInteger(scoreRange.min, labels.min);
+    assertSafeInteger(scoreRange.max, labels.max);
+    if (scoreRange.min < 0) {
+        throw new InvalidPayloadError(`${labels.min} must be non-negative`);
+    }
+    if (scoreRange.max < 0) {
+        throw new InvalidPayloadError(`${labels.max} must be non-negative`);
+    }
+    if (scoreRange.min > scoreRange.max) {
+        throw new InvalidPayloadError(`${labels.min} must not exceed ${labels.comparisonMax ?? labels.max}`);
+    }
+    if (scoreRange.max > MAX_SUPPORTED_SCORE_RANGE_MAX) {
+        throw new InvalidPayloadError(`${labels.max} must not exceed ${MAX_SUPPORTED_SCORE_RANGE_MAX}`);
+    }
+    return scoreRange;
+};

package/dist/protocol/transcript.js

@@ -1,3 +1,7 @@
+/**
+ * Transcript hashing and fingerprint helpers for full protocol logs and
+ * individual phase snapshots.
+ */
 import { bytesToHex } from '../core/bytes.js';
 import { sha256, utf8ToBytes } from '../core/index.js';
 import { canonicalizeJson } from './canonical-json.js';