Contributing to Krypteia
Position
Krypteia is an AI-assisted cryptographic library, by design and not by accident. Every line in this repository was produced through a deliberate collaboration between a human cryptographer — years of experience in embedded cryptography, side-channel analysis, and standards work — and a large language model. The human owns the architecture, the threat model, the validation strategy, and the conformance to published standards. The model owns the keystrokes and the mechanical execution.
This is a pragmatic and scientific stance, not an ideological one. The maintainer is a working cryptographer, not an AI evangelist. AI is a powerful tool with real failure modes — hallucinated APIs, subtle constant-time violations, plausibly-wrong cryptographic intuitions, silent drift between modules over long sessions — and we use it knowing both its strengths and its dangers. The aim is to use the tool at its best, with eyes open to its worst.
What we measure ourselves against is the outcome: a usable post-quantum and classical Rust library, embedded-friendly, side-channel-hardened, conformant to published standards, and open to independent audit.
At the time of writing, the core of Krypteia is developed with
Claude Code (Anthropic’s Claude Opus). The principles in this
document are tool-agnostic; the specific tool used for each commit is
recorded in the Co-Authored-By: trailer of that commit. The Git
history is the source of truth on this point, not a sanitized version
of it.
Why this document exists
Many open-source projects today reject AI-generated contributions outright. We understand that reaction and share the underlying concern: drive-by pull requests from non-experts who do not understand what they submit, who waste maintainers’ time, and who introduce subtle bugs they cannot defend. The harm is real, and the reaction is reasonable.
Applied uniformly, however, the same posture would also reject this entire project. The problem is not the use of AI. The problem is the abdication of responsibility that often comes with it. This document draws the line — explicitly, so that contributors and maintainers (including us) can be held to a public standard.
Five principles
1. Domain expertise is the price of admission
Krypteia is cryptographic code, aimed at high-grade evaluation and embedded deployment. You cannot meaningfully contribute without understanding the math, the relevant standards (FIPS, NIST SP, RFCs, ePrint papers), and the attack surface (timing, power, EM, fault). AI does not substitute for this knowledge. If you do not know what a side-channel is, this is not the project on which to learn it by submitting pull requests. Read first; contribute later.
2. You own what you submit
By opening a pull request, you assert that:
You have read every line of the diff.
You understand every non-trivial decision and can defend it under review.
You can engage substantively with detailed questions about the change. Re-consulting references — including the AI — to refresh specifics is fine; understanding a derivation is not the same as being able to recite it from memory. What is not fine is treating the AI’s output as a black box you cannot defend on your own terms.
“The AI wrote it” is not a valid response to a review comment. You may have used AI to produce the code; the responsibility is yours alone.
3. Validate against ground truth, not vibes
Generated code that “looks right” is not enough. Every change must be anchored to an external authority:
A FIPS / NIST specification, a published RFC, or a peer-reviewed paper (ePrint, TCHES, CHES, COSADE, …).
Known-Answer Tests, ACVP / Wycheproof vectors, or an equivalent recognized vector set.
A constant-time verifier (dudect, ctgrind) for any change touching side-channel-sensitive code paths.
The existing test suite, run and passing on your machine.
Cite the authority in your PR description. If no such authority exists for what you are proposing, open an issue first. The issue must contain a substantive argument: the security claim being made, a proof or proof sketch where applicable, references to related work, and the reasoning that led you to this design. We will discuss whether and how it belongs in Krypteia on that basis.
4. Trace your reasoning
Tell us why, not just what. Your PR description should contain:
The problem you are solving and the standard, paper, or threat that motivates it.
Alternatives you considered and rejected, with a one-line reason each.
The validation you ran: which vectors, which dudect runs, which targets compiled.
Optionally: the major directives you imposed on the AI — required properties (constant-time,
no_std, RAM budget), the spec section being implemented, the references the AI was asked to follow, the constraints you set. Modern AI-assisted coding rarely fits a single “prompt” — what we are interested in is the discipline you imposed on the tool, not a verbatim transcript.
When you include such directives, we treat them as documentation of intent, not proof of practice — there is no way to verify which directives were actually used during the session, and a polished retrospective rewrite is neither detectable nor, in honest hands, dishonest. We ask for them because they communicate what you were trying to achieve and what discipline you imposed on the tool, not because they constitute audit evidence. The principles above (read your diff, defend it, validate against ground truth) are what carry the actual weight.
We do not require you to publish your AI conversation logs. We do require evidence of the thinking.
5. Be honest about your tools
We do not hide our use of AI; we structure the project around it. We expect the same honesty from contributors:
Declare the AI tools you used in the PR description.
Declare your own competence level on the topic if it is not obvious from the change.
Concealment of AI usage, when discovered in review, is grounds for rejection. Honest “I am learning” is grounds for guidance — if the change is small enough to mentor.
Pre-submission checklist
Before opening a pull request, verify that you can answer yes to all of the following:
I have read every line of my own diff.
I can explain in my own words why each non-trivial line exists. (Re-consulting references or the AI to refresh specifics is fine; relying on the AI to explain my own diff is not.)
My change is anchored to a specific spec, paper, or test vector, cited in the PR description.
All existing tests pass locally (
cargo test --workspace).If my change touches a constant-time primitive, I have run the dudect verifier on the affected path and report the outcome in the PR.
If my change adds a new side-channel-sensitive primitive, I have proposed a Tier classification (see
arcana/doc/sca/andquantica/doc/).My PR description names the AI tools I used (if any) and the alternatives I rejected.
I have not introduced any external Rust crate dependency. (See the zero-deps rule in
README.md.)
What we will reject without lengthy review
Pull requests that add features without a prior issue discussing scope. Krypteia is a security artifact, not a feature playground.
Pull requests whose author cannot answer questions about their own diff.
Pull requests that introduce an external Rust crate dependency.
Pull requests that change side-channel-sensitive code without dudect / ctgrind evidence.
Pull requests that conceal AI usage when concealment becomes apparent in review.
AI slop: generated code submitted with no engagement from the contributor — no reasoning, no validation, no testing, just a pasted diff.
These rejections are not personal. The bar is set by the project’s target — high-grade cryptographic evaluation, embedded deployment, side-channel resistance — not by the convenience of contribution.
What we hold ourselves to
The bar applies to the maintainer first. Concretely, this means an ongoing discipline that does not stop at code generation:
Re-reading generated code on a recurring basis, not only at the moment it is produced. Code that was correct in isolation can become wrong as the surrounding context evolves; modules that looked clean on day one drift on day thirty. We re-read.
Auditing the rendered documentation, not just the source: how it looks in the generated docs, whether it makes sense as a navigable reference, whether the examples still compile and still illustrate what they claim to illustrate.
Refactoring file and module layout to keep the project clean and navigable, even when the AI has produced something that “works”. Generated code tends to drift toward localized cohesion at the expense of overall structure; we counter that explicitly.
Integrating tests, KAT vectors, dudect runs, and external verifiers as part of the routine, not as a one-time validation. The validation discipline is continuous and visible in the tree.
Reading carefully any pull request that follows this process, and engaging with the reasoning, not just the code.
Acknowledging AI use in metadata. Commits produced with AI assistance carry a
Co-Authored-By:trailer naming the model. The Git history is the truth.Documenting our validation strategy publicly — test vectors, side-channel verification protocols, conformance evidence — so that our claims can be audited rather than taken on faith.
Refusing contributions, including our own, that fail the discipline outlined here.
Krypteia treats AI as a power tool, not a judgment substitute. This document is the safety guard.