iam

Independent implementation review

Status: open contributor brief, 2026-09-14. No outside implementation or independent review is claimed by this document. Submit work through a pull request in proposals/; the implementer chooses the language and repository.

The question is whether another implementer can reproduce IAM’s behavior from the published specification, without learning its rules from our code. The current Node generator and Python verifier provide useful checks using different cryptographic implementations, but both were produced within the same author and agent workflow. They do not establish independent interpretation of the specification.

Inputs and independence

Before starting, record the exact repository commit, specification version, wire version, and derivation profile being implemented. Use that immutable revision throughout the comparison; do not silently follow main. A proposed derivation profile is not a published conformance target until its parameters and vectors are fixed.

Allowed inputs for the initial implementation are:

• IAM.md, its referenced normative standards, and the published vectors.json, including expected outputs.
• SECURITY.md and THREAT-MODEL.md as context, without treating explanatory text as additional protocol rules.
• General language, cryptographic library, and tool documentation. Existing cryptographic libraries are permitted; disclose the exact versions used.

Do not read or reuse reference/, vector generators in tools/, or repository test implementations before completing and recording the initial results. Do not have an assisting agent read them on your behalf. A vectors file is an allowed set of inputs and expected outputs, not permission to inspect its generator. Disclose any prior exposure to the excluded material; useful work with that exposure should be described accurately rather than presented as an independent reading.

Library use does not remove profile checks. IAM requires its exact Ed25519 acceptance set: canonical encodings, prime-order subgroups, a non-identity public key, S < L, and the specified uncofactored equation. Valid signatures with R=O are permitted. A backend rejecting every such signature cannot be made conforming by extra rejection checks alone. Select or implement a verification path that matches the specification, and test the wrapper rather than relying on a library’s “strict” label.

Scope and evidence

Start with core identity derivation, encoding and cryptographic verification, bootstrap validation, and graph evaluation. Label any omitted area explicitly; passing graph cases alone is not evidence for the KDF. The optional anchoring profile is a separate target and should have a separate result if implemented. Transport, user interfaces, and production deployment are outside this brief.

Run the published vectors and independently design additional cases before comparing behavior with the reference implementation. Include:

• Exact derivation bytes and boundaries, Argon2 parameters, HKDF Extract and Expand, seed interpretation, domain separation, and seal indexes. Test input validation without requiring allocation of the largest representable input.
• JSON duplicate names, including escaped duplicates; integer token forms and bounds; UTF-8 and string validity; unknown fields; canonical hex and base64.
• Invalid and noncanonical curve points, subgroup boundaries, identity points, scalar boundaries, wrong messages, and multiple valid signatures for one id.
• Bootstrap descriptor hashing, ordering and completeness; personal root validity; scope mismatches; missing predecessors; dependency cycles; forks; chain-invalid versus semantically failed records; and permanent LEAVE.
• Metamorphic and permutation checks: reordering input envelopes preserves the result; adding an authenticated duplicate does not add an operation; an unauthenticated signature variant cannot poison a valid copy. State each transformation’s preconditions instead of assuming arbitrary added records leave the result unchanged.

Commit the initial implementation, test cases, and observations before reading the reference code or discussing its internals. Record ambiguous passages and the interpretation chosen. Supply proposed new vectors with independently reasoned expected outcomes. Later comparison with the reference code is useful, but keep its findings distinguishable from the initial independent pass.

Passing a finite suite is evidence of agreement on those cases, not proof that the specification is complete or that an implementation is secure. Divergence may reveal ambiguous text, an incorrect vector, or an implementation error in either codebase. Do not decide the outcome merely by treating our reference code as authoritative.

Pull request contents

Add a report in proposals/ with the following metadata and reproducible evidence. Leave unknown fields explicitly unfilled until verified.

Author / review attribution:
Specification repository commit:
Specification version / wire version / derivation profile:
Implementation repository and initial-results commit:
Language / compiler or runtime / dependency versions:
Prior exposure to reference code, generators, or tests:
Human and tool assistance, including agent inputs and provenance:
Implemented scope and explicit omissions:
Commands and environment needed to reproduce results:
Published-vector results and independently designed test results:
Reference comparison performed after initial results, if any:

For each divergence, include the smallest input that reproduces it, actual and expected results, the exact specification passage supporting that expectation, and a proposed classification: text ambiguity, vector error, or implementation error. Use unresolved where evidence is insufficient. Attach test output and proposed corrections without replacing the original observation. A maintainer can then reproduce the finding and review a concrete change through the pull request.