Randonnee

Randonnee is an OpenAPI-first Go REST API for generating random numbers, strings, IDs, tokens, fixtures, and other structured data from explicit, versioned recipes. The current contract is v3.3.0 and covers secure generation, deterministic replay, commit-reveal fairness sessions, signed receipts, tenant-scoped controls, public audit artifacts, SDK helper artifacts, and bounded v3.3 audit and operations APIs.

This repository is designed for auditability, but it does not claim FIPS, NIST, CMVP, lottery, gambling, wallet, wager, settlement, payment, anonymity, operator-honesty, or jurisdictional compliance certification.

Documentation Map

Use this map as the source-of-truth router:

Task	Start here	Source of truth
Run the service locally	Local Development	docker-compose.yml, Dockerfile, .env.example, Makefile
Build against the HTTP API	API Surface	openapi.yaml; served at GET /openapi.json and GET /openapi.yaml
Use SDK helper artifacts	SDK Artifacts	sdk/README.md, sdk/openapi.yaml, language directories under sdk/
Operate a deployment	Operations	docs/operations.md, .env.example, ops/grafana/, ops/prometheus/
Prepare public audit evidence	Public Auditability	docs/public-auditability.md, testvectors/README.md, testvectors/*/index.json
Review release evidence	release evidence template	make release-acceptance, docs/release-evidence-template.md; versioned evidence files are archival
Prepare external security review	security review package	docs/security-review-package.md, release evidence, OpenAPI, test vectors, operations docs
Understand licensing and paid use	Commercial Licensing	LICENSE, COMMERCIAL.md, CONTRIBUTING.md, GOVERNANCE.md
Get support or report security issues	Support, Security Policy	SUPPORT.md, SECURITY.md
Understand product intent	Current contracts and code	openapi.yaml, tests, migrations, and operations docs; local design notes are not tracked
Run documentation checks	Checks	make docs-check, make openapi-check, make test-vectors-check, make sdk-check

License And Commercial Use

Randonnee is available under the GNU Affero General Public License version 3.0 (AGPL-3.0-only). Commercial license exceptions are available for organizations that need proprietary use, closed deployments, commercial support, self-hosted enterprise packaging, or signed release evidence without relying on a hosted Randonnee service.

Start with:

• LICENSE
• COMMERCIAL.md
• SUPPORT.md
• SECURITY.md
• CONTRIBUTING.md
• GOVERNANCE.md

For commercial licensing or paid support, contact Aatu Harju through LinkedIn: https://www.linkedin.com/in/aatu-harju.

Local Development

Prerequisites: Go, Docker, and Docker Compose.

cp .env.example .env
docker compose up --build

.env.example contains local development placeholders for signing, VRF, fairness seed encryption, and API key pepper material. Change FAIRNESS_SEED_ENCRYPTION_KEY_B64, SIGNING_PRIVATE_KEY_B64, VRF_PRIVATE_KEY_B64, and API_KEY_PEPPER for any non-local environment. Production must not use SIGNER_BACKEND=local_env; configure vault_transit or a tagged pkcs11 build and keep private material out of logs, receipts, metrics, and exports.

Bootstrap a tenant and API key after migrations are available:

go run ./cmd/admin create-tenant --tenant-id ten_local --name "Local Tenant"
go run ./cmd/admin create-api-key --tenant-id ten_local --name "local dev" \
  --scopes random.generate,random.generate.deterministic,random.generate.batch,random.generate.multi,random.generate.fairness,fairness.create,fairness.read,fairness.reveal,receipt.read,receipt.verify,primitive.read,primitive.register,primitive.approve,tenant.admin

Use the returned API key as Authorization: Bearer <key>.

API Surface

The canonical endpoint list, schemas, scopes, Problem Details responses, operation tags, summaries, and examples are in openapi.yaml.

Core workflows:

• Generate values with POST /v1/generate, POST /v1/generate/batch, POST /v1/generate/multi, or POST /v1/generate/deterministic.
• Create, use, report, and reveal fairness sessions under /v1/fairness/sessions.
• Verify receipts, fairness reports, VRF evidence, transparency exports, and proof bundles with the public verification endpoints and CLI.
• Manage tenant configuration, approvals, retention, SIEM export, marketplace allowlists, anchors, attestations, privacy generation, and finite streams through the tenant-scoped admin and v3.3 operations APIs.

Enterprise controls include static OIDC JWKS validation, signed XML SAML, SAML assertion replay enforcement, mTLS revocation checks, Vault Transit signing metadata, and build-tagged PKCS#11 backend boundaries.

Implemented modes are secure, deterministic, and session-scoped verifiable_fairness. fast_non_crypto is unsafe, disabled by default, and requires both tenant enablement and the random.generate.fast_non_crypto scope. It must not be used for secrets, games, lotteries, fairness-sensitive flows, auth tokens, passwords, keys, or security decisions.

Built-in primitive names and schemas are exposed through GET /v1/primitives and GET /v1/primitives/{name}/versions/{version}/schema; the OpenAPI contract is the stable reference for request and response shapes.

SDK Artifacts

SDK-ready artifacts live in sdk/. The root openapi.yaml remains the source of truth for production client generation, and make sdk-generate refreshes the checked-in SDK copy at sdk/openapi.yaml.

See sdk/README.md for language directories, generation rules, compatibility limits, minimal usage examples, and redaction expectations.

Public Auditability

Receipts, fairness reports, transparency checkpoints, anchors, attestations, proof bundles, and test vectors are evidence artifacts. They support external inspection of declared process and hashes; they do not certify operator honesty, cryptographic module validation, or regulatory compliance.

For audit package workflow, see docs/public-auditability.md. For committed fixture layout and compatibility expectations, see testvectors/README.md.

Documentation Maintenance

Keep updates close to their source of truth:

• Change openapi.yaml for HTTP behavior, schemas, scopes, examples, tags, or Problem Details. Then run make sdk-generate and make openapi-check.
• Change sdk/README.md or language helpers when SDK usage or artifacts change. Then run make sdk-check.
• Change testvectors/README.md and the relevant testvectors/*/index.json when fixture sets or replay compatibility evidence change. Then run make test-vectors-check.
• Change docs/operations.md, .env.example, or ops/ assets when operator behavior, metrics, key backends, or deployment controls change.
• Add new release evidence only after rerunning the listed gates for that build; older docs/release-evidence-*.md files are archival.
• Keep private design notes local-only. Current contracts, tests, migrations, and operations docs take precedence in the repository.

Checks

Use make docs-check for non-mutating documentation-adjacent validation:

make docs-check

Expected result: OpenAPI route checks pass, the committed test vectors validate, SDK artifacts match the root contract, crypto inventory evidence is present, and deployment-profile non-claims remain documented.

Useful narrower checks:

make openapi-check
make test-vectors-check
make sdk-check
make fuzz-smoke
make fast-check
make finalize
make release-acceptance

make finalize runs the broader QA path and may install tools or rewrite formatted/tidy files through its dependencies. make release-acceptance additionally starts live Docker Compose dependencies, bootstraps a throwaway tenant/API key, runs generation/replay/receipt verification smokes, checks /openapi.json, scans logs/metrics for secrets, and tears the stack down. Set RANDONNEE_RELEASE_DATABASE_URL only when the release acceptance Compose database is intentionally exposed on a non-default local port.