threshold-elgamal 1.0.9 → 2.0.0

package/README.md

@@ -1,7 +1,6 @@
 # threshold-elgamal
 
-[![npm version](https://img.shields.io/npm/v/threshold-elgamal?color=5FA04E)](https://www.npmjs.com/package/threshold-elgamal)
-[![npm downloads](https://img.shields.io/npm/dm/threshold-elgamal?color=5FA04E)](https://www.npmjs.com/package/threshold-elgamal)
+[![npm version](https://img.shields.io/npm/v/threshold-elgamal?color=5FA04E)](https://www.npmjs.com/package/threshold-elgamal) [![npm downloads](https://img.shields.io/npm/dm/threshold-elgamal?color=5FA04E)](https://www.npmjs.com/package/threshold-elgamal)
 
 ---
 
@@ -11,15 +10,15 @@
 
 ---
 
-[![Node version](https://img.shields.io/badge/node-%E2%89%A524.14.1-5FA04E?logo=node.js&logoColor=white)](https://nodejs.org/)
 [![License](https://img.shields.io/github/license/Tenemo/threshold-elgamal)](LICENSE)
 
-`threshold-elgamal` is a browser-native TypeScript library for verifiable score-voting research prototypes. The shipped beta line is focused on one workflow only:
+`threshold-elgamal` is a browser-native TypeScript library for verifiable score-voting research prototypes. It focuses on one workflow:
 
 - additive ElGamal on `ristretto255`
 - honest-majority GJKR DKG
-- fixed score voting in `1..10`
-- one public manifest shape: `rosterHash` and `optionList`
+- one explicit global contiguous score range per ceremony
+- manifest `scoreRange.max` capped at `100` to keep proofs and tally recovery tractable
+- one public manifest shape: `rosterHash`, `optionList`, and `scoreRange`
 - organizer-signed `ballot-close` before decryption
 - full local recomputation and full ceremony verification from the public board
 
@@ -37,45 +36,40 @@ npm install threshold-elgamal
 
 - Use ESM imports such as `import { createElectionManifest } from 'threshold-elgamal'`.
 - Browsers need native `bigint` together with Web Crypto.
-- Node requires version `24.14.1` or newer with `globalThis.crypto`.
+- Node must satisfy the package `engines.node` requirement and expose `globalThis.crypto`.
 - Authentication signatures require Web Crypto `Ed25519`.
 - Transport share exchange requires Web Crypto `X25519`.
 
-See [Runtime and compatibility](https://tenemo.github.io/threshold-elgamal/guides/runtime-and-compatibility/) for the tested browser and Node matrix.
-
-## Start here
-
-- [Verifying a public board](https://tenemo.github.io/threshold-elgamal/guides/verifying-a-public-board/): start here for `tryVerifyElectionCeremony(...)` and `verifyElectionCeremony(...)`.
-- [Browser and worker usage](https://tenemo.github.io/threshold-elgamal/guides/browser-and-worker-usage/): start here for key generation, manifest setup, and encrypted transport envelopes.
-- [Published payload examples](https://tenemo.github.io/threshold-elgamal/guides/published-payload-examples/): start here if you need concrete JSON, posting, or persistence patterns.
-- [Honest-majority voting flow](https://tenemo.github.io/threshold-elgamal/guides/three-participant-voting-flow/): read this for the supported phase-by-phase transcript story.
+See [Runtime and compatibility](https://tenemo.github.io/threshold-elgamal/guides/runtime-and-compatibility/) for environment requirements.
 
 ## Documentation
 
-- Hosted documentation site: [tenemo.github.io/threshold-elgamal](https://tenemo.github.io/threshold-elgamal/)
-- Get started: [tenemo.github.io/threshold-elgamal/guides/getting-started](https://tenemo.github.io/threshold-elgamal/guides/getting-started/)
-- Verifying a public board: [tenemo.github.io/threshold-elgamal/guides/verifying-a-public-board](https://tenemo.github.io/threshold-elgamal/guides/verifying-a-public-board/)
+- Homepage: [tenemo.github.io/threshold-elgamal](https://tenemo.github.io/threshold-elgamal/)
+- Getting started: [tenemo.github.io/threshold-elgamal/guides/getting-started](https://tenemo.github.io/threshold-elgamal/guides/getting-started/)
+- Runtime and compatibility: [tenemo.github.io/threshold-elgamal/guides/runtime-and-compatibility](https://tenemo.github.io/threshold-elgamal/guides/runtime-and-compatibility/)
 - Browser and worker usage: [tenemo.github.io/threshold-elgamal/guides/browser-and-worker-usage](https://tenemo.github.io/threshold-elgamal/guides/browser-and-worker-usage/)
-- Published payload examples: [tenemo.github.io/threshold-elgamal/guides/published-payload-examples](https://tenemo.github.io/threshold-elgamal/guides/published-payload-examples/)
 - Honest-majority voting flow: [tenemo.github.io/threshold-elgamal/guides/three-participant-voting-flow](https://tenemo.github.io/threshold-elgamal/guides/three-participant-voting-flow/)
-- Runtime and compatibility: [tenemo.github.io/threshold-elgamal/guides/runtime-and-compatibility](https://tenemo.github.io/threshold-elgamal/guides/runtime-and-compatibility/)
+- Published payload examples: [tenemo.github.io/threshold-elgamal/guides/published-payload-examples](https://tenemo.github.io/threshold-elgamal/guides/published-payload-examples/)
+
+---
+
+- Verifying a public board: [tenemo.github.io/threshold-elgamal/guides/verifying-a-public-board](https://tenemo.github.io/threshold-elgamal/guides/verifying-a-public-board/)
 - Security boundary: [tenemo.github.io/threshold-elgamal/guides/security-and-non-goals](https://tenemo.github.io/threshold-elgamal/guides/security-and-non-goals/)
 - Production voting safety review: [tenemo.github.io/threshold-elgamal/guides/production-voting-safety-review](https://tenemo.github.io/threshold-elgamal/guides/production-voting-safety-review/)
+
+---
+
 - API docs: [tenemo.github.io/threshold-elgamal/api](https://tenemo.github.io/threshold-elgamal/api/)
 
 ## Browser support
 
-The shipped cryptographic browser path is fixed:
+The cryptographic browser path is fixed:
 
 - `Ed25519` for protocol payload signatures
 - `X25519` for encrypted share transport
 
-Practical browser baseline for the public workflow:
-
-- Chrome and Edge `137+`
-- Firefox `130+`
-- Safari `18.4+`
-- iOS and iPadOS browsers on the Safari `18.4+` WebKit generation
+- Use modern browsers that expose Web Crypto `Ed25519`, Web Crypto `X25519`, and native `bigint`
+- Validate your target environments with `pnpm exec tsx ./tools/ci/verify-browser-compat.ts` before deployment
 
 Older browsers, stale embedded webviews, and runtimes without Web Crypto `X25519` support are not supported.
 
@@ -84,10 +78,10 @@ Older browsers, stale embedded webviews, and runtimes without Web Crypto `X25519
 The supported boardroom flow is:
 
 1. Freeze the roster in the application and hash it with `hashRosterEntries(...)`.
-2. Build the minimal manifest with `createElectionManifest({ rosterHash, optionList })`.
+2. Build the manifest with `createElectionManifest({ rosterHash, optionList, scoreRange })`.
 3. Publish the manifest, registrations, and manifest acceptances.
 4. Run the honest-majority GJKR transcript.
-5. Post ballot payloads for complete `1..10` score ballots.
+5. Post ballot payloads for complete scores inside the manifest-declared range.
 6. Post one organizer-signed `ballot-close` payload that freezes which complete ballots are counted.
 7. Post threshold decryption shares and tally publications for the close-selected ballot set.
 8. Verify the whole ceremony with `verifyElectionCeremony(...)`.
@@ -136,6 +130,7 @@ const rosterHash = await hashRosterEntries([
 const manifest = createElectionManifest({
     rosterHash,
     optionList: ["Option A", "Option B"],
+    scoreRange: { min: 1, max: 10 },
 });
 
 const manifestHash = await hashElectionManifest(manifest);
@@ -178,7 +173,7 @@ if (!result.ok) {
 }
 ```
 
-The root package also exposes builders for the signed protocol payloads used across the shipped ceremony, including:
+The root package exposes the builders and lower-level helpers required for the documented ceremony, including:
 
 - manifest publication
 - registration
@@ -193,14 +188,17 @@ The root package also exposes builders for the signed protocol payloads used acr
 - decryption shares
 - tally publication
 
-For the reveal path, the public root surface is intentionally three-step:
+The reveal path also works from the root package:
 
 - prepare the accepted aggregate with `prepareAggregateForDecryption(...)`
 - compute each partial share with `createDecryptionShare(...)`
-- prove and publish it with `createDLEQProof(...)` and `createDecryptionSharePayload(...)`
+- prove it with `createDLEQProof(...)`
+- publish it with `createDecryptionSharePayload(...)`
 
 After collecting a threshold subset, recover the tally with `combineDecryptionShares(...)` against the prepared aggregate ciphertext.
 
+The grouped public submodules remain available when you prefer narrower imports by subsystem, but the supported full ceremony does not require them.
+
 For concrete posted JSON shapes, use [Published payload examples](https://tenemo.github.io/threshold-elgamal/guides/published-payload-examples/).
 
 ## Security boundary
@@ -210,7 +208,7 @@ The library is designed for an honest-origin, honest-client, static-adversary se
 What it tries to enforce:
 
 - additive-only tallying on `ristretto255`
-- fixed `1..10` score ballots
+- one explicit global contiguous manifest score range
 - grouped per-option ballot verification
 - mandatory local aggregate recomputation before decryption
 - organizer-visible and auditable ballot cutoff through `ballot-close`
@@ -224,9 +222,9 @@ What it does not claim:
 - constant-time JavaScript `bigint` execution
 - production readiness
 
-`ballot-close` is an auditable administrative cutoff, not a fairness proof about board arrival order. The library proves what was counted, not whether the organizer waited long enough before closing.
+`ballot-close` is an auditable administrative cutoff, not a fairness proof about board arrival order. The library proves which ballots count, not whether the organizer waited long enough before closing.
 
-For a production-threat-model verdict that maps these boundaries to the shipped verifier and tests, read the [production voting safety review](https://tenemo.github.io/threshold-elgamal/guides/production-voting-safety-review/).
+For a production-threat-model verdict that maps these boundaries to the verifier and tests, read the [production voting safety review](https://tenemo.github.io/threshold-elgamal/guides/production-voting-safety-review/).
 
 ## Development
 

package/dist/core/bigint.d.ts

@@ -7,7 +7,8 @@ export declare const mod: (value: bigint, modulus: bigint) => bigint;
 /**
  * Reduces a value into the range `0..q-1`.
  *
- * @throws {@link InvalidScalarError} When `q` is not positive.
+ * @throws {@link threshold-elgamal/core!InvalidScalarError | InvalidScalarError}
+ * When `q` is not positive.
  */
 export declare const modQ: (value: bigint, q: bigint) => bigint;
 /**

package/dist/core/bigint.js

@@ -1,3 +1,7 @@
+/**
+ * Finite-field arithmetic helpers shared by proofs, verifiable secret sharing,
+ * threshold reconstruction, and transcript verification.
+ */
 import { InvalidScalarError } from './errors.js';
 const assertPositiveModulus = (modulus) => {
     if (modulus <= 0n) {
@@ -66,7 +70,8 @@ const modP = (value, p) => mod(value, p);
 /**
  * Reduces a value into the range `0..q-1`.
  *
- * @throws {@link InvalidScalarError} When `q` is not positive.
+ * @throws {@link threshold-elgamal/core!InvalidScalarError | InvalidScalarError}
+ * When `q` is not positive.
  */
 export const modQ = (value, q) => mod(value, q);
 /**

package/dist/core/bytes.js

@@ -1,3 +1,7 @@
+/**
+ * Byte, hex, and buffer-shape conversion helpers used by hashing,
+ * serialization, signatures, and transport code throughout the package.
+ */
 import { InvalidPayloadError } from './errors.js';
 const hexPattern = /^[0-9a-f]+$/i;
 const defaultHexErrorMessage = 'Hex input must be a non-empty even-length hexadecimal string';

package/dist/core/crypto.js

@@ -1,3 +1,8 @@
+/**
+ * Runtime crypto helpers that normalize Web Crypto access for hashing,
+ * HKDF-based key derivation, and UTF-8 encoding across browser and Node
+ * runtimes.
+ */
 import { toBufferSource } from './bytes.js';
 import { InvalidScalarError, UnsupportedSuiteError } from './errors.js';
 const textEncoder = new TextEncoder();

package/dist/core/errors.d.ts

@@ -1,37 +1,76 @@
+/**
+ * Shared error taxonomy for the package.
+ *
+ * Public helpers throw these errors when callers violate mathematical,
+ * encoding, transcript, or workflow invariants.
+ */
 declare class ThresholdElGamalError extends Error {
     constructor(message: string);
 }
-/** Raised when a scalar value falls outside the expected mathematical domain. */
+/**
+ * Raised when a scalar value falls outside the expected field or subgroup
+ * domain for the current operation.
+ */
 export declare class InvalidScalarError extends ThresholdElGamalError {
 }
-/** Raised when a group element is not valid for the selected suite. */
+/**
+ * Raised when a point or public key is not a canonical member of the selected
+ * cryptographic group.
+ */
 export declare class InvalidGroupElementError extends ThresholdElGamalError {
 }
-/** Raised when a participant index falls outside the valid `1..n` range. */
+/**
+ * Raised when a participant index falls outside the supported `1..n`
+ * numbering scheme used across the protocol.
+ */
 export declare class IndexOutOfRangeError extends ThresholdElGamalError {
 }
-/** Raised when serialized payload bytes do not satisfy the required encoding. */
+/**
+ * Raised when a payload, transcript field, manifest field, or serialized value
+ * does not satisfy the package's canonical encoding rules.
+ */
 export declare class InvalidPayloadError extends ThresholdElGamalError {
 }
-/** Raised when a proof transcript or response fails verification. */
+/**
+ * Raised when a Schnorr, DLEQ, or disjunctive proof transcript fails
+ * structural checks or cryptographic verification.
+ */
 export declare class InvalidProofError extends ThresholdElGamalError {
 }
-/** Raised when the requested suite or runtime capability is unavailable. */
+/**
+ * Raised when the requested suite or required runtime capability is unavailable
+ * in the current environment.
+ */
 export declare class UnsupportedSuiteError extends ThresholdElGamalError {
 }
-/** Raised when a plaintext lies outside the allowed domain for the chosen mode. */
+/**
+ * Raised when an additive plaintext falls outside the explicitly bounded domain
+ * that the current workflow promised to support.
+ */
 export declare class PlaintextDomainError extends ThresholdElGamalError {
 }
-/** Raised when a serialized or reconstructed share fails validation. */
+/**
+ * Raised when a serialized share, decrypted share envelope, or reconstructed
+ * share set fails threshold-specific validation.
+ */
 export declare class InvalidShareError extends ThresholdElGamalError {
 }
-/** Raised when a protocol step transition violates the state machine rules. */
+/**
+ * Raised when a published payload claims to belong to a protocol phase that
+ * does not match the supported ceremony state machine.
+ */
 export declare class PhaseViolationError extends ThresholdElGamalError {
 }
-/** Raised when threshold parameters do not satisfy `1 <= k <= n`. */
+/**
+ * Raised when threshold parameters or participant counts violate the supported
+ * `1 <= k <= n` relationship or the package's honest-majority policy.
+ */
 export declare class ThresholdViolationError extends ThresholdElGamalError {
 }
-/** Raised when transcript hashes or canonical bytes do not match expectations. */
+/**
+ * Raised when transcript hashes, manifest hashes, or other canonical digest
+ * commitments do not match the values claimed by published payloads.
+ */
 export declare class TranscriptMismatchError extends ThresholdElGamalError {
 }
 export {};

package/dist/core/errors.js

@@ -1,3 +1,9 @@
+/**
+ * Shared error taxonomy for the package.
+ *
+ * Public helpers throw these errors when callers violate mathematical,
+ * encoding, transcript, or workflow invariants.
+ */
 class ThresholdElGamalError extends Error {
     constructor(message) {
         super(message);
@@ -5,36 +11,69 @@ class ThresholdElGamalError extends Error {
         Object.setPrototypeOf(this, new.target.prototype);
     }
 }
-/** Raised when a scalar value falls outside the expected mathematical domain. */
+/**
+ * Raised when a scalar value falls outside the expected field or subgroup
+ * domain for the current operation.
+ */
 export class InvalidScalarError extends ThresholdElGamalError {
 }
-/** Raised when a group element is not valid for the selected suite. */
+/**
+ * Raised when a point or public key is not a canonical member of the selected
+ * cryptographic group.
+ */
 export class InvalidGroupElementError extends ThresholdElGamalError {
 }
-/** Raised when a participant index falls outside the valid `1..n` range. */
+/**
+ * Raised when a participant index falls outside the supported `1..n`
+ * numbering scheme used across the protocol.
+ */
 export class IndexOutOfRangeError extends ThresholdElGamalError {
 }
-/** Raised when serialized payload bytes do not satisfy the required encoding. */
+/**
+ * Raised when a payload, transcript field, manifest field, or serialized value
+ * does not satisfy the package's canonical encoding rules.
+ */
 export class InvalidPayloadError extends ThresholdElGamalError {
 }
-/** Raised when a proof transcript or response fails verification. */
+/**
+ * Raised when a Schnorr, DLEQ, or disjunctive proof transcript fails
+ * structural checks or cryptographic verification.
+ */
 export class InvalidProofError extends ThresholdElGamalError {
 }
-/** Raised when the requested suite or runtime capability is unavailable. */
+/**
+ * Raised when the requested suite or required runtime capability is unavailable
+ * in the current environment.
+ */
 export class UnsupportedSuiteError extends ThresholdElGamalError {
 }
-/** Raised when a plaintext lies outside the allowed domain for the chosen mode. */
+/**
+ * Raised when an additive plaintext falls outside the explicitly bounded domain
+ * that the current workflow promised to support.
+ */
 export class PlaintextDomainError extends ThresholdElGamalError {
 }
-/** Raised when a serialized or reconstructed share fails validation. */
+/**
+ * Raised when a serialized share, decrypted share envelope, or reconstructed
+ * share set fails threshold-specific validation.
+ */
 export class InvalidShareError extends ThresholdElGamalError {
 }
-/** Raised when a protocol step transition violates the state machine rules. */
+/**
+ * Raised when a published payload claims to belong to a protocol phase that
+ * does not match the supported ceremony state machine.
+ */
 export class PhaseViolationError extends ThresholdElGamalError {
 }
-/** Raised when threshold parameters do not satisfy `1 <= k <= n`. */
+/**
+ * Raised when threshold parameters or participant counts violate the supported
+ * `1 <= k <= n` relationship or the package's honest-majority policy.
+ */
 export class ThresholdViolationError extends ThresholdElGamalError {
 }
-/** Raised when transcript hashes or canonical bytes do not match expectations. */
+/**
+ * Raised when transcript hashes, manifest hashes, or other canonical digest
+ * commitments do not match the values claimed by published payloads.
+ */
 export class TranscriptMismatchError extends ThresholdElGamalError {
 }

package/dist/core/groups.d.ts

@@ -1,4 +1,9 @@
 import type { CryptoGroup } from './types.js';
-/** Immutable definition of the shipped Ristretto255 tally group. */
+/**
+ * Immutable definition of the built-in `ristretto255` tally group.
+ *
+ * Every public cryptographic workflow in this package ultimately routes
+ * through this suite definition.
+ */
 export declare const RISTRETTO_GROUP: CryptoGroup;
 export declare const assertCanonicalRistrettoGroup: (group: CryptoGroup, label?: string) => void;

package/dist/core/groups.js

@@ -1,6 +1,17 @@
+/**
+ * Built-in group definitions and suite guard rails.
+ *
+ * The public API is intentionally tied to one canonical suite,
+ * `ristretto255`, and this module makes that choice explicit.
+ */
 import { UnsupportedSuiteError } from './errors.js';
 import { derivePedersenGenerator, RISTRETTO_BYTE_LENGTH } from './ristretto.js';
-/** Immutable definition of the shipped Ristretto255 tally group. */
+/**
+ * Immutable definition of the built-in `ristretto255` tally group.
+ *
+ * Every public cryptographic workflow in this package ultimately routes
+ * through this suite definition.
+ */
 export const RISTRETTO_GROUP = Object.freeze({
     name: 'ristretto255',
     byteLength: RISTRETTO_BYTE_LENGTH,
@@ -20,6 +31,6 @@ const sameCanonicalRistrettoGroup = (group) => group.name === RISTRETTO_GROUP.na
 export const assertCanonicalRistrettoGroup = (group, label = 'Group') => {
     const normalizedLabel = label.length > 0 ? `${label[0].toLowerCase()}${label.slice(1)}` : label;
     if (!sameCanonicalRistrettoGroup(group)) {
-        throw new UnsupportedSuiteError(`${normalizedLabel} must match the shipped canonical ristretto255 group definition`);
+        throw new UnsupportedSuiteError(`${normalizedLabel} must match the canonical ristretto255 group definition`);
     }
 };

package/dist/core/index.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Internal barrel for the core arithmetic, encoding, randomness, and
+ * validation primitives that higher-level modules compose.
+ */
 export { modInvQ, modQ } from './bigint.js';
 export * from './crypto.js';
 export * from './errors.js';

package/dist/core/index.js

@@ -1,3 +1,7 @@
+/**
+ * Internal barrel for the core arithmetic, encoding, randomness, and
+ * validation primitives that higher-level modules compose.
+ */
 export { modInvQ, modQ } from './bigint.js';
 export * from './crypto.js';
 export * from './errors.js';

package/dist/core/public.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Low-level core helpers for arithmetic, error handling, and group constants.
+ *
+ * Use this module when you need primitives that sit below the voting workflow
+ * surface exposed by the root package.
+ *
+ * @module threshold-elgamal/core
+ * @packageDocumentation
+ */
+export { IndexOutOfRangeError, InvalidGroupElementError, InvalidPayloadError, InvalidProofError, InvalidScalarError, InvalidShareError, PhaseViolationError, PlaintextDomainError, ThresholdViolationError, TranscriptMismatchError, UnsupportedSuiteError, } from './errors.js';
+export { modQ } from './bigint.js';
+export { RISTRETTO_GROUP } from './groups.js';
+export type { EncodedPoint } from './types.js';

package/dist/core/public.js

@@ -0,0 +1,12 @@
+/**
+ * Low-level core helpers for arithmetic, error handling, and group constants.
+ *
+ * Use this module when you need primitives that sit below the voting workflow
+ * surface exposed by the root package.
+ *
+ * @module threshold-elgamal/core
+ * @packageDocumentation
+ */
+export { IndexOutOfRangeError, InvalidGroupElementError, InvalidPayloadError, InvalidProofError, InvalidScalarError, InvalidShareError, PhaseViolationError, PlaintextDomainError, ThresholdViolationError, TranscriptMismatchError, UnsupportedSuiteError, } from './errors.js';
+export { modQ } from './bigint.js';
+export { RISTRETTO_GROUP } from './groups.js';

package/dist/core/random.js

@@ -1,3 +1,7 @@
+/**
+ * Randomness helpers used by proof generation, envelope encryption, and other
+ * cryptographic sampling paths.
+ */
 import { bytesToBigInt } from './bytes.js';
 import { getWebCrypto } from './crypto.js';
 import { InvalidScalarError } from './errors.js';

package/dist/core/ristretto.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Low-level Ristretto255 point and scalar operations.
+ *
+ * Higher-level modules such as additive ElGamal, proofs, VSS, and threshold
+ * reconstruction build on these wrappers instead of calling the curve library
+ * directly.
+ */
 import { ristretto255 } from '@noble/curves/ed25519.js';
 import type { EncodedPoint } from './types.js';
 type InternalPoint = InstanceType<typeof ristretto255.Point>;

package/dist/core/ristretto.js

@@ -1,3 +1,10 @@
+/**
+ * Low-level Ristretto255 point and scalar operations.
+ *
+ * Higher-level modules such as additive ElGamal, proofs, VSS, and threshold
+ * reconstruction build on these wrappers instead of calling the curve library
+ * directly.
+ */
 import { ristretto255, ristretto255_hasher } from '@noble/curves/ed25519.js';
 import { sha512 } from '@noble/hashes/sha2.js';
 import { bytesToBigInt, bytesToBigIntLE, bytesToHex, hexToBytes, } from './bytes.js';

package/dist/core/types.d.ts

@@ -1,3 +1,6 @@
+/**
+ * Foundational nominal and suite types shared across the package.
+ */
 /**
  * Nominal typing helper used to distinguish compatible runtime values in the
  * type system.
@@ -5,13 +8,18 @@
 export type Brand<T, TBrand extends string> = T & {
     readonly __brand: TBrand;
 };
-/** @internal Canonical name for the shipped Ristretto255 suite. */
+/** @internal Canonical name for the built-in Ristretto255 suite. */
 export type GroupName = 'ristretto255';
-/** @internal Accepted helper input identifiers for the shipped Ristretto suite. */
+/** @internal Accepted helper input identifiers for the built-in Ristretto suite. */
 export type GroupIdentifier = GroupName;
-/** Canonical 32-byte Ristretto point encoding exposed at the public boundary. */
+/**
+ * Canonical 32-byte Ristretto point encoding exposed at the public boundary.
+ *
+ * Public helpers use this branded string type to distinguish encoded points
+ * from ordinary hex strings.
+ */
 export type EncodedPoint = Brand<string, 'EncodedPoint'>;
-/** @internal Immutable built-in group definition for the shipped suite. */
+/** @internal Immutable group definition for the built-in suite. */
 export type CryptoGroup = {
     /** Canonical suite name. */
     readonly name: GroupName;
@@ -29,7 +37,7 @@ export type CryptoGroup = {
     readonly securityEstimate: number;
 };
 /**
- * Random byte source injected into sampling helpers for deterministic testing
- * or custom runtime integration.
+ * Random byte source injected into sampling helpers for deterministic tests,
+ * reproducible vectors, or custom runtime integration.
  */
 export type RandomBytesSource = (length: number) => Uint8Array;

package/dist/core/validation.d.ts

@@ -1,6 +1,16 @@
-/** Returns `true` when the value is a non-identity valid Ristretto point. */
+/**
+ * Returns `true` when the value is a canonical non-identity Ristretto point.
+ *
+ * This is the predicate used for public keys and most commitment elements.
+ */
 export declare const isInSubgroup: (value: string) => boolean;
-/** Returns `true` when the value is a valid Ristretto point, including identity. */
+/**
+ * Returns `true` when the value is a canonical Ristretto point, including the
+ * identity element.
+ *
+ * This variant is used for ciphertext components and transcript values that
+ * are allowed to land on the identity.
+ */
 export declare const isInSubgroupOrIdentity: (value: string) => boolean;
 /**
  * Validates that a scalar belongs to `Z_q`.
@@ -30,25 +40,48 @@ export declare const assertPlaintextAdditive: (value: bigint, bound: bigint, q:
  */
 export declare const assertThreshold: (threshold: number, participantCount: number) => void;
 /**
- * Derives the shipped GJKR honest-majority threshold `ceil(n / 2)`.
+ * Derives the supported honest-majority threshold `ceil(n / 2)`.
  *
- * For odd `n` this matches the usual strict-majority value. For even `n` the
- * shipped protocol uses the maximal honest-majority instantiation proved for
- * GJKR, which yields `k = n / 2`.
+ * This is the threshold policy used by the package's DKG and full voting flow.
+ * Callers do not choose a custom `k`; the verifier derives it from the
+ * accepted registration roster.
  */
 export declare const majorityThreshold: (participantCount: number) => number;
 /**
- * Validates that the supplied threshold matches the shipped GJKR
+ * Validates that the supplied threshold matches the library's GJKR
  * honest-majority policy.
  */
 export declare const assertMajorityThreshold: (threshold: number, participantCount: number) => number;
-/** Validates a 1-based participant index without assuming a fixed count. */
+/**
+ * Validates a 1-based participant index without assuming a fixed participant
+ * count.
+ *
+ * The package consistently numbers trustees and voters from `1`.
+ */
 export declare const assertPositiveParticipantIndex: (index: number) => void;
-/** Validates a 1-based participant index for a fixed participant count. */
+/**
+ * Validates a 1-based participant index against a fixed participant count.
+ *
+ * This is the usual check for published payloads that already sit inside a
+ * frozen roster.
+ */
 export declare const assertValidParticipantIndex: (index: number, participantCount: number) => void;
-/** Validates that a value is a non-identity valid Ristretto point. */
+/**
+ * Validates that a value is a canonical non-identity Ristretto point.
+ *
+ * This is the assertion form of {@link isInSubgroup}.
+ */
 export declare const assertInSubgroup: (value: string) => void;
-/** Validates that a value is a valid Ristretto point, including identity. */
+/**
+ * Validates that a value is a canonical Ristretto point, including identity.
+ *
+ * This is the assertion form of {@link isInSubgroupOrIdentity}.
+ */
 export declare const assertInSubgroupOrIdentity: (value: string) => void;
-/** Validates a public key as a non-identity Ristretto point. */
+/**
+ * Validates a public key as a canonical non-identity Ristretto point.
+ *
+ * Public keys, verification keys, and commitment generators all route through
+ * this helper.
+ */
 export declare const assertValidPublicKey: (value: string) => void;