threshold-elgamal 1.0.0-beta.8 → 1.0.0

package/README.md

@@ -41,6 +41,18 @@ npm install threshold-elgamal
 - Authentication signatures require Web Crypto `Ed25519`.
 - Transport share exchange requires Web Crypto `X25519`.
 
+## 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/)
+- 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/)
+- 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:
@@ -80,6 +92,12 @@ There is no supported `n-of-n` mode and no supported public `k-of-n` configurati
 
 Transcript verification requires key-derivation confirmations from every qualified participant.
 
+## Choose your entry point
+
+- Verifying a public board: start with the hosted guide for `tryVerifyElectionCeremony(...)` and `verifyElectionCeremony(...)`.
+- Browser and worker usage: start with the browser guide for key generation, manifest setup, and encrypted transport envelopes.
+- Payload shapes and storage: start with the payload examples guide if you need concrete JSON, posting, or persistence patterns.
+
 ## Getting started
 
 ```typescript
@@ -126,6 +144,34 @@ console.log(majorityThreshold(3)); // 2
 console.log(sessionId.length); // 64
 ```
 
+If your application consumes a complete public board, the shortest safe verifier entry point is:
+
+```typescript
+import {
+    tryVerifyElectionCeremony,
+    type VerifyElectionCeremonyInput,
+} from "threshold-elgamal";
+
+const bundle: VerifyElectionCeremonyInput = {
+    manifest,
+    sessionId,
+    dkgTranscript,
+    ballotPayloads,
+    ballotClosePayload,
+    decryptionSharePayloads,
+    tallyPublications,
+};
+
+const result = await tryVerifyElectionCeremony(bundle);
+
+if (!result.ok) {
+    console.error(result.error.stage, result.error.code, result.error.reason);
+} else {
+    console.log(result.verified.perOptionTallies);
+    console.log(result.verified.boardAudit.overall.fingerprint);
+}
+```
+
 The root package also exposes public builders for:
 
 - manifest publication
@@ -140,7 +186,7 @@ The root package also exposes public builders for:
 - decryption shares
 - tally publication
 
-For a full executable ceremony example, use the public node integration tests in this repository.
+For concrete integration examples, start with the hosted guides below. The repository integration harness exercises the same workflow, but it is not part of the supported public API.
 
 ## Security boundary
 
@@ -167,15 +213,6 @@ What it does not claim:
 
 For a production-threat-model verdict that maps these boundaries to the shipped verifier and tests, read the production voting safety review in the hosted docs.
 
-## 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/)
-- 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/)
-- 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/)
-
 ## Development
 
 ```bash

package/dist/index.d.ts

@@ -17,14 +17,14 @@ export type { DecryptionShare, Share, VerifiedAggregateCiphertext, } from './thr
 export { deriveJointPublicKey, deriveTranscriptVerificationKey, verifyDKGTranscript, } from './dkg/verification.js';
 export { decodePedersenShareEnvelope, encodePedersenShareEnvelope, } from './dkg/pedersen-share-codec.js';
 export type { VerifyDKGTranscriptInput, VerifiedDKGTranscript, } from './dkg/verification.js';
-export { generateFeldmanCommitments, verifyFeldmanShare, } from './vss/feldman.js';
+export { generateFeldmanCommitments, verifyFeldmanShare } from './vss/feldman.js';
 export { derivePedersenShares, generatePedersenCommitments, verifyPedersenShare, } from './vss/pedersen.js';
 export type { FeldmanCommitments, PedersenCommitments, PedersenShare, } from './vss/types.js';
 export { createBallotClosePayload, createBallotSubmissionPayload, createDecryptionSharePayload, createEncryptedDualSharePayload, createFeldmanCommitmentPayload, createKeyDerivationConfirmationPayload, createManifestAcceptancePayload, createManifestPublicationPayload, createPedersenCommitmentPayload, createPhaseCheckpointPayload, createRegistrationPayload, createTallyPublicationPayload, signProtocolPayload, } from './protocol/builders.js';
 export { canonicalizeElectionManifest, createElectionManifest, deriveSessionId, hashElectionManifest, SHIPPED_PROTOCOL_VERSION, validateElectionManifest, } from './protocol/manifest.js';
 export { hashRosterEntries } from './protocol/verification.js';
 export { hashProtocolTranscript } from './protocol/transcript.js';
-export { verifyElectionCeremony, tryVerifyElectionCeremony, type ElectionVerificationErrorCode, type ElectionVerificationFailure, type ElectionVerificationResult, type ElectionVerificationStage, type VerifiedElectionCeremony, type VerifyElectionCeremonyInput, } from './protocol/voting-verification.js';
+export { verifyElectionCeremony, tryVerifyElectionCeremony, type ElectionVerificationErrorCode, type ElectionVerificationFailure, type ElectionVerificationResult, type ElectionVerificationStage, type VerifiedElectionCeremony, } from './protocol/voting-verification.js';
 export { verifyBallotSubmissionPayloadsByOption } from './protocol/voting-ballots.js';
 export { scoreVotingDomain } from './protocol/voting-codecs.js';
-export type { BallotClosePayload, BallotSubmissionPayload, DecryptionSharePayload, ElectionManifest, EncodedCiphertext, EncodedCompactProof, EncodedDisjunctiveProof, EncryptedDualSharePayload, FeldmanCommitmentPayload, KeyDerivationConfirmation, ManifestAcceptancePayload, ManifestPublicationPayload, PedersenCommitmentPayload, PhaseCheckpointPayload, ProtocolMessageType, ProtocolPayload, RegistrationPayload, SignedPayload, TallyPublicationPayload, } from './protocol/types.js';
+export type { BallotClosePayload, BallotSubmissionPayload, DecryptionSharePayload, ElectionManifest, EncodedCiphertext, EncodedCompactProof, EncodedDisjunctiveProof, EncryptedDualSharePayload, FeldmanCommitmentPayload, KeyDerivationConfirmation, ManifestAcceptancePayload, ManifestPublicationPayload, PedersenCommitmentPayload, PhaseCheckpointPayload, ProtocolMessageType, ProtocolPayload, RegistrationPayload, SignedPayload, TallyPublicationPayload, VerifyElectionCeremonyInput, } from './protocol/types.js';

package/dist/index.js

@@ -12,7 +12,7 @@ export { exportTransportPublicKey, generateTransportKeyPair, } from './transport
 export { combineDecryptionShares } from './threshold/decrypt.js';
 export { deriveJointPublicKey, deriveTranscriptVerificationKey, verifyDKGTranscript, } from './dkg/verification.js';
 export { decodePedersenShareEnvelope, encodePedersenShareEnvelope, } from './dkg/pedersen-share-codec.js';
-export { generateFeldmanCommitments, verifyFeldmanShare, } from './vss/feldman.js';
+export { generateFeldmanCommitments, verifyFeldmanShare } from './vss/feldman.js';
 export { derivePedersenShares, generatePedersenCommitments, verifyPedersenShare, } from './vss/pedersen.js';
 export { createBallotClosePayload, createBallotSubmissionPayload, createDecryptionSharePayload, createEncryptedDualSharePayload, createFeldmanCommitmentPayload, createKeyDerivationConfirmationPayload, createManifestAcceptancePayload, createManifestPublicationPayload, createPedersenCommitmentPayload, createPhaseCheckpointPayload, createRegistrationPayload, createTallyPublicationPayload, signProtocolPayload, } from './protocol/builders.js';
 export { canonicalizeElectionManifest, createElectionManifest, deriveSessionId, hashElectionManifest, SHIPPED_PROTOCOL_VERSION, validateElectionManifest, } from './protocol/manifest.js';

package/dist/protocol/board-audit.js

@@ -1,7 +1,7 @@
 import { InvalidPayloadError } from '../core/index.js';
 import { compareProtocolPayloads } from './ordering.js';
 import { classifySlotConflict, payloadSlotKey } from './payloads.js';
-import { formatSessionFingerprint, hashProtocolTranscript, } from './transcript.js';
+import { formatSessionFingerprint, hashProtocolTranscript } from './transcript.js';
 const compareSignedPayloads = (left, right) => {
     const payloadOrder = compareProtocolPayloads(left.payload, right.payload);
     if (payloadOrder !== 0) {

package/dist/protocol/types.d.ts

@@ -191,8 +191,8 @@ export type VerifyDecryptionSharePayloadsByOptionInput = {
     readonly manifest: ElectionManifest;
     readonly sessionId: string;
 };
-/** Input bundle for verifying one full published tally set across all options. */
-export type VerifyPublishedVotingResultsInput = {
+/** Input bundle for full ceremony verification across all published options. */
+export type VerifyElectionCeremonyInput = {
     readonly manifest: ElectionManifest;
     readonly sessionId: string;
     readonly dkgTranscript: readonly SignedPayload[];

package/dist/protocol/verification.js

@@ -1,6 +1,6 @@
 import { InvalidPayloadError, assertValidParticipantIndex, sha256, utf8ToBytes, } from '../core/index.js';
 import { bytesToHex } from '../serialize/index.js';
-import { importAuthPublicKey, verifyPayloadSignature, } from '../transport/auth.js';
+import { importAuthPublicKey, verifyPayloadSignature } from '../transport/auth.js';
 import { assertSupportedTransportPublicKeyEncoding } from '../transport/key-agreement.js';
 import { canonicalizeJson } from './canonical-json.js';
 import { canonicalUnsignedPayloadBytes } from './payloads.js';

package/dist/protocol/voting-shared.js

@@ -1,5 +1,5 @@
 import { assertPositiveParticipantIndex, InvalidPayloadError, RISTRETTO_GROUP, } from '../core/index.js';
-import { importAuthPublicKey, verifyPayloadSignature, } from '../transport/auth.js';
+import { importAuthPublicKey, verifyPayloadSignature } from '../transport/auth.js';
 import { hashElectionManifest, SHIPPED_PROTOCOL_VERSION, validateElectionManifest, } from './manifest.js';
 import { canonicalUnsignedPayloadBytes } from './payloads.js';
 import { scoreVotingDomain } from './voting-codecs.js';

package/dist/protocol/voting-verification.d.ts

@@ -1,6 +1,6 @@
 import { type VerifiedDKGTranscript } from '../dkg/verification.js';
 import { type BoardAudit } from './board-audit.js';
-import type { BallotClosePayload, BallotSubmissionPayload, DecryptionSharePayload, ElectionManifest, VerifiedPublishedOptionVotingResult, VerifyPublishedVotingResultsInput, TallyPublicationPayload } from './types.js';
+import type { BallotClosePayload, BallotSubmissionPayload, DecryptionSharePayload, ElectionManifest, VerifyElectionCeremonyInput, VerifiedPublishedOptionVotingResult, TallyPublicationPayload } from './types.js';
 /** Stable high-level failure codes for full ceremony verification. */
 export type ElectionVerificationErrorCode = 'MANIFEST_INVALID' | 'BOARD_INVALID' | 'DKG_INVALID' | 'SIGNATURE_INVALID' | 'BALLOT_INVALID' | 'DECRYPTION_INVALID' | 'TALLY_INVALID';
 /** Named verification stage used by the high-level ceremony verifier. */
@@ -38,8 +38,6 @@ export type VerifiedElectionCeremony = {
     readonly dkg: VerifiedDKGTranscript;
     readonly options: readonly VerifiedPublishedOptionVotingResult[];
 };
-/** Input bundle for full ceremony verification across all published options. */
-export type VerifyElectionCeremonyInput = VerifyPublishedVotingResultsInput;
 /** Non-throwing result shape for full ceremony verification. */
 export type ElectionVerificationResult = {
     readonly ok: true;
@@ -55,6 +53,15 @@ export type ElectionVerificationResult = {
  *
  * @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);
+ * ```
  */
 export declare const verifyElectionCeremony: (input: VerifyElectionCeremonyInput) => Promise<VerifiedElectionCeremony>;
 /**
@@ -63,5 +70,17 @@ export declare const verifyElectionCeremony: (input: VerifyElectionCeremonyInput
  *
  * @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);
+ * ```
  */
 export declare const tryVerifyElectionCeremony: (input: VerifyElectionCeremonyInput) => Promise<ElectionVerificationResult>;

package/dist/protocol/voting-verification.js

@@ -55,6 +55,15 @@ const findOptionDecryptionShares = (decryptionShares, optionIndex) => {
  *
  * @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);
+ * ```
  */
 export const verifyElectionCeremony = async (input) => {
     let context;
@@ -249,6 +258,18 @@ export const verifyElectionCeremony = async (input) => {
  *
  * @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);
+ * ```
  */
 export const tryVerifyElectionCeremony = async (input) => {
     try {

package/dist/transport/envelopes.js

@@ -1,6 +1,6 @@
 import { toBufferSource } from '../core/bytes.js';
 import { getWebCrypto, hkdfSha256, randomBytes } from '../core/index.js';
-import { bytesToHex, encodeForChallenge, hexToBytes, } from '../serialize/index.js';
+import { bytesToHex, encodeForChallenge, hexToBytes } from '../serialize/index.js';
 import { deriveTransportSharedSecret, exportTransportPrivateKey, exportTransportPublicKey, generateTransportKeyPair, importTransportPrivateKey, importTransportPublicKey, } from './key-agreement.js';
 const envelopeKeySalt = (rosterHash) => new TextEncoder().encode(rosterHash);
 export const encodeEnvelopeContext = (context) => encodeForChallenge(context.sessionId, BigInt(context.phase), BigInt(context.dealerIndex), BigInt(context.recipientIndex), context.envelopeId, context.payloadType, context.protocolVersion, context.suite);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "threshold-elgamal",
-    "version": "1.0.0-beta.8",
+    "version": "1.0.0",
     "description": "A browser-native TypeScript ElGamal library for Ristretto255-based research prototypes, shipping additive ElGamal, threshold decryption, protocol helpers, board auditing, transport primitives, and log-driven DKG state machines.",
     "author": "Piotr Piech <piotr@piech.dev>",
     "license": "MPL-2.0",
@@ -23,7 +23,7 @@
         "coverage:badge": "pnpm run coverage:node && tsx ./tools/generate-coverage-badge.ts",
         "smoke:pack": "tsx ./tools/ci/verify-packed-package.ts",
         "prebuild": "pnpm run lint && tsc && knip && tsx ./tools/ci/verify-vectors.ts && pnpm run test",
-        "build": "pnpm exec del-cli dist && tsc --project tsconfig.build.json",
+        "build": "pnpm exec del-cli dist && tsc --project tsconfig.build.json && tsx ./tools/build/rewrite-dist-relative-imports.ts",
         "vectors:threshold": "tsx ./tools/generate-threshold-vectors.ts",
         "vectors:protocol": "tsx ./tools/generate-protocol-vectors.ts",
         "bench:micro": "tsx ./tools/benchmarks/microbench.ts",