# IAM Open Protocol for Identity and Trust Graphs

**iam-core 1.1** uses record wire version `2` and preserves identity KDF v1.

Start with the [security limits](SECURITY.md), [threat model](THREAT-MODEL.md)
and [review provenance](reviews/README.md). Project reviews and reference
artifacts were developed with Codex agents; no completed independent security
audit is established by these materials.

## 1. Scope

IAM defines reproducible identity keys and signed ACCEPT and REVOKE records for
personal and community membership graphs, with LEAVE for community departure.
An identity is an Ed25519 public key. Membership is evaluated from selected
records and a community bootstrap or an implicit personal root. Operational
permissions and access decisions belong to the runtime.

## 2. Specification

The published specification is available at [openiam.org](https://openiam.org/).

- [IAM.md](IAM.md): normative iam-core 1.1 specification and canonical wordlist.
- [ANCHORING.md](ANCHORING.md): optional single-publisher snapshot profile.
- [CHANGELOG.md](CHANGELOG.md): changes from 1.0 and migration requirements.
- [conformance/vectors.json](conformance/vectors.json): cryptographic and graph
  conformance vectors.

The document version, record wire version, and identity derivation are distinct:
iam-core **1.1** selects records with **`v = 2`** and the `IAM2:*` hash/signature
domains. Identity derivation retains **KDF v1**, including its parameters and
`iam:v1:name:` salt prefix. Existing derived keys can therefore be retained;
wire-1 records and community tree identifiers are not silently reinterpreted
under the new rules. See the migration guidance in CHANGELOG.md.

## 3. Terms and Definitions

- **Identity**: An Ed25519 public key.
- **ACCEPT**: A signed, directed acceptance of another key.
- **REVOKE**: A signed removal of the actor's acceptance edge.
- **LEAVE**: A signed departure from a community graph.
- **Context**: The personal or community graph context used for evaluation.

## 4. Deterministic Evaluation

IAM's determinism guarantee concerns the same `known_trees` registry and
`anchored_set`, evaluated for the same `tree` and `context` under the same
protocol rules. These inputs determine the graph state. Runtime policies select
the authoritative records, distribute updates, and decide how membership is
used. Different selected inputs can produce different states.

## 5. Conformance

Conformance requirements belong to the protocol specification. This README is
an explanatory overview and adds no requirements of its own.

The standard-library Python reference code provides strict cryptographic
verification in [reference/iam_verify.py](reference/iam_verify.py) and core graph
evaluation in [reference/iam_graph.py](reference/iam_graph.py). The
[tests](https://github.com/mathorn1973/iam/tree/main/tests) exercise those components against the checked-in vectors and
failure cases. These tools do not implement the anchoring profile or a network
runtime.

From the repository root, run:

```sh
python -m unittest discover -s tests -v
node tools/generate_vectors.mjs --check
```

The Node command checks that the checked-in vectors match their deterministic
generator without rewriting them. It requires a Node runtime with the built-in
Argon2 API used by [tools/generate_vectors.mjs](tools/generate_vectors.mjs).

Node and Python provide distinct implementation paths within the same project
workflow. Their agreement and the finite vectors do not prove that the
specification is complete. The [outside implementation brief](proposals/independent-implementation.md)
defines a contribution from the specification without access to our reference
code, with additional independently designed tests and disclosed authorship.

## 6. Status and scope

IAM is an open, public protocol intended for long-term archival and interoperable
evaluation across implementations. Version 1.1 specifies stricter verification
and explicit graph rules under a new record wire version, while preserving
identity derivation. The optional anchoring profile authenticates one
publisher's selections; it does not provide distributed consensus or prove that
an offline snapshot is the newest one.

The [derivation-profile proposal](proposals/derivation-profiles.md) is an open
decision for production identity enrollment. P0/P1/P2 are not defined or
supported profiles; KDF v1 remains the published derivation.