Skip to content

AGENTS.md

Latest commit

 

History

History
215 lines (167 loc) · 8.07 KB

AGENTS.md

File metadata and controls

215 lines (167 loc) · 8.07 KB
Raw

AI Development Workflows for pqcrypto

Last updated: 2026-06-15

This file tells coding agents how to work in this repository. Ground every claim in the live code, CHANGELOG.md, and the canonical documentation root doc/.

Current Truth

  • Package version: 0.4.0.
  • Runtime dependencies: none. FIPS 202 SHA3/SHAKE and FIPS 180-4 SHA-2 are vendored in lib/src/common/.
  • ML-KEM: supported for ML-KEM-512/768/1024 with checked-in KAT vectors, focused unit tests, web tests, and OpenSSL interop.
  • ML-DSA: FIPS 204-aligned for ML-DSA-44/65/87 and byte-exact against the checked-in KAT corpus (test/data/MLDSA) across raw/pure/hashed × det/hedged (300 key generations + 1800 signatures). The full dart test suite is green. This is KAT/regression evidence, not a CMVP/FIPS 140 validation claim.
  • SLH-DSA: FIPS 205-aligned for all 12 parameter sets (SHAKE and SHA-2 families). Algorithms 1-25 are implemented, and test/slhdsa_kat_test.dart is byte-exact on the 1,248 cases in the pinned official NIST ACVP sample corpus. The external API (SlhDsa) is exported at the package root; verify-after-sign, BUFF/performance docs, OpenSSL/liboqs interop, and VM/dart2js/dart2wasm benchmark baselines are complete; the decomposed VM matrix and both web compiler suites are green. SLH-DSA ships in 0.4.0 alongside ML-KEM and ML-DSA. This is KAT/ACVP/regression evidence, not a CMVP/FIPS 140 validation claim.
  • Documentation root: doc/; the older documentation directory has been retired.

Exploration Phase

Start here:

  1. Read README.md.
  2. Read doc/INDEX.md.
  3. Read doc/ARCHITECTURE.md.
  4. Read doc/PROGRESS_TRACKER.md and doc/ROADMAP.md.
  5. Read doc/SECURITY_AUDIT.md and doc/FIPS_COMPLIANCE.md.
  6. For ML-DSA work, read doc/MLDSA_FIPS204_RELEASE_GUIDE.md.
  7. For SLH-DSA work, read doc/SLHDSA_FIPS205_RELEASE_GUIDE.md and test/data/SLHDSA/README.md.
  8. For multi-agent Serverpod/Flutter or tool-native workflow planning, read doc/UNIVERSAL_MULTI_AGENT_PQC_FRAMEWORK.md and tool/agent_framework/pqc_framework.yaml.
  9. Inspect lib/src/, test/, and tool/openssl_interop/.

Run:

dart analyze
dart test test/kat_evaluator_test.dart
dart test test/mldsa_kat_test.dart
dart test test/slhdsa_kat_test.dart
dart test

Expected current boundary: dart analyze exits 0, the ML-KEM and ML-DSA KAT runners pass, and the SLH-DSA SHAKE ACVP runner passes. The SLH-DSA runner is intentionally expensive because it includes all three s sets.

Implementation Phase

Before editing:

  • Identify whether the change touches ML-KEM, ML-DSA, common primitives, tests, tooling, or docs.
  • For ML-KEM arithmetic/serialization, run the focused ML-KEM test set before and after the change.
  • For ML-DSA, the deterministic core and external/HashML-DSA APIs are KAT-validated; keep any change byte-exact against test/data/MLDSA by running dart test test/mldsa_kat_test.dart. Use doc/MLDSA_FIPS204_RELEASE_GUIDE.md as the controlling implementation/Definition-of-Done checklist, and never upgrade claim wording past KAT/regression evidence (no CMVP/FIPS 140 claims).

Conventions:

  • Use the existing parameter objects.
  • Keep ML-KEM and ML-DSA polynomial types separate.
  • Keep runtime package dependencies at zero unless a package-boundary decision is explicitly made.
  • Avoid print() in lib/.
  • Validate public inputs.
  • Add or update tests with every behavior change.

Testing Phase

Useful commands:

# Static analysis
dart analyze

# ML-KEM KAT corpus
dart test test/kat_evaluator_test.dart

# Focused ML-KEM evidence set
dart test test/kat_evaluator_test.dart test/keccak_test.dart test/kem_validation_test.dart test/keygen_derivation_test.dart test/pack_test.dart test/poly_test.dart test/roundtrip_test.dart

# Full suite
dart test

# Web portable tests
dart test -p chrome
dart test -p chrome --compiler dart2wasm

The OpenSSL interop harness is a separate unpublished package:

cd tool/openssl_interop
dart pub get
dart test

The interop harness needs an OpenSSL >= 3.5 libcrypto with ML-KEM support.

Documentation Phase

Use doc/ paths everywhere. Update documentation when:

  • public APIs change;
  • validation evidence changes;
  • tests are added, removed, or renamed;
  • package dependencies or publish boundaries change;
  • readiness language changes.

Keep assurance wording scoped:

  • Good: "passes the checked-in ML-KEM KAT corpus."
  • Good: "OpenSSL interop A-G passes for ML-KEM-512/768/1024."
  • Good: "ML-DSA is byte-exact on the checked-in FIPS 204 KAT corpus."
  • Bad: "fully FIPS validated" / "CMVP validated" / "certified" without a record.
  • See doc/FIPS_140_BOUNDARY.md for the precise claim boundary and the acceptable/unacceptable wording list.

Universal PQC Agent Framework

Project-level native wrappers are committed for Codex, Claude Code, and Antigravity:

  • .codex/skills/universal-pqc-framework/SKILL.md
  • .claude/skills/universal-pqc-framework/SKILL.md
  • .gemini/antigravity/skills/universal-pqc-framework/SKILL.md

These wrappers are thin. The canonical source is doc/UNIVERSAL_MULTI_AGENT_PQC_FRAMEWORK.md plus tool/agent_framework/pqc_framework.yaml. Keep role output and implementation plans inside that evidence boundary.

Visibility and AI Discovery Surfaces

The GitHub Pages site, root AI discovery files, Copilot instructions, Cursor rule, and Windsurf rule are generated from tool/visibility/visibility_manifest.json. Do not edit generated outputs directly. Update the manifest, then run:

dart run tool/visibility/generate_visibility.dart
dart run tool/visibility/generate_visibility.dart --check

The generated outputs include:

  • site/ for GitHub Pages;
  • llms.txt, llms-full.txt, identity.json, developer-ai.txt, faq-ai.txt, ai.txt, robots-ai.txt, and robots.txt;
  • .github/copilot-instructions.md;
  • .github/instructions/pqcrypto-crypto.instructions.md;
  • .cursor/rules/pqcrypto.mdc;
  • .windsurfrules.

Security Auditing Phase

Focus areas:

  • cryptographic correctness against FIPS 203/204;
  • side-channel behavior in comparisons, rejection loops, and decapsulation;
  • secret-zeroization in finally blocks;
  • public input validation;
  • hardcoded local paths or secrets;
  • documentation that overstates evidence.

Resolved (regression-guarded; keep them closed):

  • ML-DSA packing and ExpandS (η=2) defects — fixed; covered by KATs.
  • Windows ML-DSA KAT paths and the debug-only test — removed; replaced by the discovered runner test/mldsa_kat_test.dart over test/data/MLDSA.
  • Missing repo-local ML-DSA KAT corpus — vendored under test/data/MLDSA.
  • _checkNorm early return — replaced by the no-early-exit _normExceeds.
  • Missing shared zeroization utilities — added lib/src/common/zeroize.dart.

Open priorities:

  • Deeper side-channel review (per-iteration branch directions in _normExceeds and rejection loops remain a best-effort, not constant-time, posture in Dart).
  • KEM decapsulation output-selection review.
  • HashML-DSA currently exposes the level-bound SHA-2 pre-hash only; other approved pre-hash functions (e.g. SHAKE) are not yet surfaced.

Common Pitfalls

  • Treating ML-KEM KAT success as ML-DSA readiness.
  • Reintroducing external or machine-local KAT paths.
  • Referring to the retired documentation directory instead of doc/.
  • Referring to the old non-discovered KAT runner path instead of test/kat_evaluator_test.dart.
  • Mentioning pointycastle as a runtime dependency; it has been replaced by vendored FIPS 202 code.
  • Updating roadmap/readiness docs without running the relevant verification commands.