# bytemare/cpace architecture

> Architecture diagram of the GitHub repository bytemare/cpace, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bytemare/cpace
- Repository: https://github.com/bytemare/cpace

## Overview

1. **Repository purpose**
   - This is a Go library, not an application service.
   - Its core responsibility is implementing the CPace password-authenticated key exchange protocol for two peers that share a pre-shared secret/password.

2. **Public API surface**
   - The main exported package is the module root: `github.com/bytemare/cpace`.
   - The key public concepts are `Parameters`, peer roles (`Initiator` / `Responder`), and the protocol flow `Init -> New -> Start -> Finish`.
   - The README indicates the API is intentionally small and designed for offline parameter setup plus per-session execution.

3. **Protocol orchestration layer**
   - `cpace.go` likely contains the main protocol state machine and the exported peer methods.
   - This layer coordinates the two-message exchange:
     - `Start()` emits the peer’s public share and session identifier handling.
     - `Finish()` consumes the counterpart share and derives the session key.
   - The repo’s architecture centers on this orchestration layer, with minimal exposed surface beyond it.

4. **Parameter and context management**
   - `parameters.go` is the configuration boundary for cryptographic and peer-specific setup.
   - It likely holds the selected group/ciphersuite, hash, client/server identities, and associated data.
   - The README shows this configuration can be serialized/deserialized, so parameters are treated as reusable session context rather than ephemeral runtime state.

5. **Cryptographic dependency boundary**
   - The implementation delegates actual cryptographic operations to external packages, especially `github.com/bytemare/ecc` and `github.com/bytemare/hash`.
   - The README explicitly says the cryptographic operations are in the `ecc` package, so this repo mainly composes protocol logic around those primitives rather than implementing curve math itself.
   - That makes the architectural boundary clear: this repo owns CPace protocol logic; the external libraries own group and hash primitives.

6. **Error and validation layer**
   - `errors.go` likely centralizes protocol-specific failures such as bad inputs, missing session IDs, invalid peer shares, or mismatched protocol state.
   - This is an important boundary because the package must reject malformed or inconsistent protocol inputs without leaking secret-dependent information.

7. **Internal helpers**
   - `internal/misc.go` suggests small unexported utilities used by the protocol and parameter code.
   - Keeping these helpers under `internal/` indicates they are implementation details, not part of the supported API.
   - This separation keeps public package semantics narrow and stable.

8. **Protocol data flow**
   - Typical flow is: configure parameters once, create initiator/responder instances, exchange ephemeral public values, then derive a shared session key on both sides.
   - The README shows the initiator can generate the session ID if one is not provided, while the responder must use the same ID.
   - The shared password is only used during this exchange; the resulting session key is the product of both shares, identities, associated data, and the chosen cryptographic suite.

9. **Examples and documentation**
   - `doc.go` and `cpace_example_test.go` provide package-level documentation and runnable usage examples.
   - These files are part of the public-facing developer experience and mirror the intended protocol lifecycle.
   - The README is effectively a high-level architectural guide for consumers.

10. **Test strategy**
   - `tests/cpace_test.go` and `tests/vectors/allVectors.json` show the repo is validated with known-answer test vectors.
   - That implies a strong compatibility and correctness focus, which is important for a cryptographic protocol implementation.
   - The `tests/vectors` directory acts as a fixture boundary between the implementation and canonical protocol outputs.

11. **Tooling and CI**
   - The `.github/workflows` directory contains analysis, Go tests, verification, release, and fuzzing workflows.
   - This signals the repository emphasizes static analysis, regression testing, and supply-chain/release hygiene.
   - The presence of nightly fuzzing is especially relevant for a crypto protocol library, since input validation and state handling are security-sensitive.

12. **Repository maturity and packaging**
   - The presence of `CHANGELOG.md`, `LICENSE`, `CITATION.cff`, and release workflows indicates a published reusable module with versioned releases.
   - The module files `go.mod` and `go.sum` confirm standard Go dependency management.
   - The README’s warning that it is a proof of concept based on an internet draft is an important architectural constraint: the implementation follows a moving spec rather than a frozen standard.

Main entry points: [`cpace.go`](https://github.com/bytemare/cpace/blob/main/cpace.go) (cpace), [`.github/workflows`](https://github.com/bytemare/cpace/blob/main/.github/workflows) (CI workflows), [`parameters.go`](https://github.com/bytemare/cpace/blob/main/parameters.go) (Parameters), [`go.mod`](https://github.com/bytemare/cpace/blob/main/go.mod) (Module files)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public_api["Public API"]
  node_n1["cpace<br/>public API package<br/>[cpace.go]"]
  node_n5["Package docs<br/>api docs<br/>[doc.go]"]
  node_n6["Example flow<br/>usage example"]
end

subgraph group_protocol_core["Protocol Core"]
  node_n2["Parameters<br/>config model<br/>[parameters.go]"]
  node_n3["Errors<br/>[errors.go]"]
  node_n4["Misc helpers<br/>internal utils<br/>[misc.go]"]
end

subgraph group_validation["Validation"]
  node_n7["Tests<br/>[cpace_test.go]"]
  node_n8["Vectors<br/>test fixtures<br/>[allVectors.json]"]
end

subgraph group_docs_release["Docs & Release"]
  node_n9["README<br/>overview docs<br/>[README.md]"]
  node_n10["Module files<br/>go module<br/>[go.mod]"]
  node_n15["Release meta<br/>repo metadata<br/>[CHANGELOG.md]"]
  node_n16["Governance<br/>repo metadata"]
end

subgraph group_tooling_ci["Tooling & CI"]
  node_n11["CI workflows<br/>automation<br/>[workflows]"]
end

subgraph group_external_deps["External Dependencies"]
  node_n12(("ecc<br/>crypto primitives"))
  node_n13(("hash"))
  node_n14(("bytemare libs<br/>go dependencies"))
end

node_n9 -->|"describes"| node_n1
node_n6 -->|"demonstrates"| node_n1
node_n1 -->|"uses"| node_n2
node_n1 -->|"raises"| node_n3
node_n1 -->|"relies on"| node_n4
node_n1 -->|"calls"| node_n12
node_n1 -->|"calls"| node_n13
node_n2 -->|"selects"| node_n12
node_n2 -->|"binds"| node_n13
node_n7 -->|"verifies against"| node_n8
node_n7 -->|"exercises"| node_n1
node_n11 -->|"runs"| node_n7
node_n11 -->|"checks"| node_n8
node_n11 -->|"analyzes"| node_n1
node_n15 -->|"tracks"| node_n9
node_n16 -->|"supports"| node_n10
node_n10 -->|"imports"| node_n12
node_n10 -->|"imports"| node_n13
node_n14 -.->|"supports"| node_n1

click node_n1 "https://github.com/bytemare/cpace/blob/main/cpace.go"
click node_n2 "https://github.com/bytemare/cpace/blob/main/parameters.go"
click node_n3 "https://github.com/bytemare/cpace/blob/main/errors.go"
click node_n4 "https://github.com/bytemare/cpace/blob/main/internal/misc.go"
click node_n5 "https://github.com/bytemare/cpace/blob/main/doc.go"
click node_n6 "https://github.com/bytemare/cpace/blob/main/cpace_example_test.go"
click node_n7 "https://github.com/bytemare/cpace/blob/main/tests/cpace_test.go"
click node_n8 "https://github.com/bytemare/cpace/blob/main/tests/vectors/allVectors.json"
click node_n9 "https://github.com/bytemare/cpace/blob/main/README.md"
click node_n10 "https://github.com/bytemare/cpace/blob/main/go.mod"
click node_n11 "https://github.com/bytemare/cpace/blob/main/.github/workflows"
click node_n15 "https://github.com/bytemare/cpace/blob/main/CHANGELOG.md"
click node_n16 "https://github.com/bytemare/cpace/tree/main/LICENSE"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n1,node_n5,node_n6 toneBlue
class node_n2,node_n3,node_n4 toneAmber
class node_n7,node_n8 toneMint
class node_n9,node_n10,node_n15,node_n16 toneRose
class node_n11 toneIndigo
class node_n12,node_n13,node_n14 toneTeal
```

## Components

### Public API

Exported package surface and consumer-facing documentation.

- [cpace](https://github.com/bytemare/cpace/blob/main/cpace.go): public API package · Main exported CPace package and protocol entry points. · `cpace.go`
- [Package docs](https://github.com/bytemare/cpace/blob/main/doc.go): api docs · Package-level documentation for the library contract. · `doc.go`
- [Example flow](https://github.com/bytemare/cpace/blob/main/cpace_example_test.go): usage example · Runnable example of the intended CPace lifecycle. · `cpace_example_test.go`

### Protocol Core

State machine, parameter handling, and internal helpers for CPace.

- [Parameters](https://github.com/bytemare/cpace/blob/main/parameters.go): config model · Reusable protocol configuration and peer context. · `parameters.go`
- [Errors](https://github.com/bytemare/cpace/blob/main/errors.go): protocol errors · Centralized protocol validation and failure definitions. · `errors.go`
- [Misc helpers](https://github.com/bytemare/cpace/blob/main/internal/misc.go): internal utils · Unexported support code for protocol and parameter logic. · `internal/misc.go`

### Validation

Known-answer tests and vector fixtures.

- [Tests](https://github.com/bytemare/cpace/blob/main/tests/cpace_test.go): protocol tests · Integration-style tests for protocol behavior. · `tests/cpace_test.go`
- [Vectors](https://github.com/bytemare/cpace/blob/main/tests/vectors/allVectors.json): test fixtures · Canonical known-answer vectors used for compatibility checks. · `tests/vectors/allVectors.json`

### Docs & Release

Examples, package docs, and repository packaging artifacts.

- [README](https://github.com/bytemare/cpace/blob/main/README.md): overview docs · High-level architectural and usage guide for consumers. · `README.md`
- [Module files](https://github.com/bytemare/cpace/blob/main/go.mod): go module · Go dependency and module metadata. · `go.mod`
- [Release meta](https://github.com/bytemare/cpace/blob/main/CHANGELOG.md): repo metadata · Versioning and publication metadata for the library. · `CHANGELOG.md`
- [Governance](https://github.com/bytemare/cpace/tree/main/LICENSE): repo metadata · License, citation, and ownership metadata. · `LICENSE`

### Tooling & CI

Automation for analysis, tests, release, and fuzzing.

- [CI workflows](https://github.com/bytemare/cpace/blob/main/.github/workflows): automation · Analysis, tests, verification, release, and fuzzing workflows. · `.github/workflows`

### External Dependencies

Cryptographic primitives and other third-party libraries used by the protocol implementation.

- **ecc**: crypto primitives · External elliptic-curve and group operations used by CPace.
- **hash**: hash primitives · External hashing and transcript support used by the protocol.
- **bytemare libs**: go dependencies · Other imported libraries that support the implementation and tests.

## Connections

- README → cpace: describes · Documents the main API and protocol flow.
- Example flow → cpace: demonstrates · Shows the intended public usage pattern.
- cpace → Parameters: uses · Protocol instances are created from reusable parameters.
- cpace → Errors: raises · State and input validation errors originate here.
- cpace → Misc helpers: relies on · Shares small unexported helpers with the core implementation.
- cpace → ecc: calls · Delegates group operations to external ECC primitives.
- cpace → hash: calls · Uses hashing primitives for transcript and key derivation.
- Parameters → ecc: selects · Configures the underlying cryptographic group/ciphersuite.
- Parameters → hash: binds · Carries hash and transcript-related configuration.
- Tests → Vectors: verifies against · Checks implementation outputs against canonical vectors.
- Tests → cpace: exercises · Tests the exported protocol behavior end to end.
- CI workflows → Tests: runs · Automation executes the test suite.
- CI workflows → Vectors: checks · Ensures fixture-based regression coverage remains valid.
- CI workflows → cpace: analyzes · CI includes static analysis and verification for the library.
- Release meta → README: tracks · Changelog documents release history referenced by consumers.
- Governance → Module files: supports · Repository governance and packaging metadata accompany the module.
- Module files → ecc: imports · Module dependencies include cryptographic primitives.
- Module files → hash: imports · Module dependencies include hashing support.
- bytemare libs → cpace: supports · Auxiliary libraries help implement and validate the package.