IdentiKey alongside KERI
IdentiKey , from Identikey Inc., is an open protocol suite. Four of its pieces match jobs a personal AI needs done: proving who you are with a key, saying what an agent may do, sharing encrypted data, and keeping a signed history. Companion Memory has a plan to take them one at a time, beside its KERI-shaped peer identity and not in place of it. Only the first has been written. This page explains it and says what is built and what is not.
Status. The IdentiKey Phase 1 challenge/response authentication endpoints
are mounted in Companion Memory at /auth/identikey/challenge and
/auth/identikey/verify (IdentikeyModule / IdentikeyController).
The feature is off by default behind the ENABLE_AUTH_IDENTIKEY=true
feature flag. When disabled, all endpoints return 404 Not Found.
Why it sits beside KERI
Companion Memory identifies a peer Companion by an Ed25519 key, written did:keri:D<key>, and checks the RFC 9421 signature on each request against it. The KERI design says where that identity is meant to go. It names a Companion. It does not give you four things:
- A way to prove yourself to your own Companion with a hardware-backed or post-quantum key, by answering a challenge the Companion issues instead of presenting a token anyone could copy.
- Permission tokens that the holder can narrow without asking. An agent can hand a weaker copy of its token to a tool.
- Encrypted sharing that you can revoke.
- A tamper-evident history of grants and revocations on your own Companion.
IdentiKey has a protocol for each. The plan keeps KERI as the layer for identifiers and for trust between Companions. IdentiKey adds no identifier that competes with a KERI identifier, and it stays off the signed ask route (/agent/v1/ask): that route accepts exactly one signature label, and a post-quantum co-signature would be a second signature.
How the sign-in works
A sign-in is a challenge and a response. The side that checks, the verifier, issues the challenge. The side that holds the key signs it. In the plan for phase 2, the verifier is your Companion and the key holder is you or one of your devices.
sequenceDiagram
participant K as Key holder<br/>(person or device)
participant C as Verifier<br/>(your Companion)
C->>K: Challenge: who it is for, when it expires,<br/>and a random one-time value
Note over K: Check the challenge is for the Companion<br/>I meant to reach, then sign its bytes<br/>(Ed25519 or P-256, and optionally ML-DSA)
K->>C: Response: the challenge, the public key,<br/>and the signature or signatures
Note over C: 1. Is it for me, and inside its time window?<br/>2. Did I issue it, and does it have an attempt left?<br/>3. Does the Ed25519 or P-256 signature verify?<br/>4. If there is an ML-DSA signature, is it from the<br/>key enrolled for this identity, and does it verify?<br/>5. Spend the one-time value, last
C-->>K: Accepted, or refusedThree details carry most of the safety:
- A challenge is single-use and for one audience. The verifier names itself in the challenge (the audience) and remembers the random value (the nonce) that it issued. Replaying a response fails because the value is already spent.
- The key holder checks the audience before it signs. That check is the only defense against a relay, in which a hostile site hands your key a challenge it collected from your Companion. Only the key holder can make it, so the library refuses to sign unless the caller says which verifier it means to reach.
- A challenge allows a few attempts and one success. The verifier counts an attempt before it checks any signature, and allows three by default. A caller cannot make it do expensive work again and again on one challenge, and a challenge it never issued costs it very little. It spends the one-time value only after every check passes, so a failed response cannot use up somebody else’s good challenge.
The library returns a reason code for every refusal, for logs. A route built on it is meant to answer every refusal the same way, so a caller cannot learn which check failed.
Algorithms and the post-quantum signature
A response is signed with Ed25519 or P-256. P-256 is there for keys that live in secure hardware, which usually offers that curve. A response can also carry a second signature from ML-DSA, a signature algorithm designed to resist forgery by a quantum computer. The verifier chooses a policy: check the second signature when one is present, or require one.
Why the library remembers the post-quantum key
In the reference protocol, a response carries its own ML-DSA public key, and nothing ties that key to the identity. The identity’s fingerprint covers only the classical key, and the classical signature covers only the challenge, not the ML-DSA key in the response. So two kinds of attacker can swap in an ML-DSA key pair of their own and pass: someone who can change one response on its way, with no cryptanalysis at all, and someone who can forge the classical signature. Forging the classical signature is what a quantum computer makes possible, and it is the reason for the second signature.
So the Companion Memory library asks the caller which post-quantum key belongs to each fingerprint, and refuses a different one. Three limits follow:
- The library cannot store that memory. The code that uses it must keep it in a database, which is part of phase 2. With no memory, requiring the second signature proves only that some valid ML-DSA signature exists, not whose. Each result says whether the key matched a remembered one.
- The memory must come from enrolling the key, never from a sign-in. A verifier that remembered the key from the first good sign-in would remember an attacker’s key if that sign-in was changed on its way, and would then lock the real owner out. Enrolling is a separate step in which both keys sign one message that names both of them. Phase 2 builds it.
- A remembered key protects an identity that was enrolled before an attacker could forge classical signatures. It does not protect an enrollment made by one. Only how a Companion decides who may enroll can.
Compared with the peer identity today
| Peer identity today | IdentiKey sign-in (phase 1) | |
|---|---|---|
| What it names | A Companion, by its Ed25519 key | A key holder: a person, a device or a Companion |
| How it proves | Signs each HTTP request (RFC 9421) | Signs a challenge that the verifier issued, once |
| Algorithms | Ed25519 | Ed25519 or P-256, plus an optional ML-DSA signature |
| Replay protection | The signature is accepted only once | The one-time value is spent only once |
| Identifier | did:keri:D<key>, the key itself | A BLAKE3 fingerprint of the algorithm and key, in base58 |
| Rotation and history | Not built | Not built |
Both identifiers can be computed from the same Ed25519 public key, so one key can answer both ways. The library converts between its key type and the JWK format that the peer signing key already uses. Whether a Companion should answer both ways is a phase 2 decision.
What is built and what is not
| Phase | What it is | Status |
|---|---|---|
| 1 | The sign-in ceremony as a library: challenge, response, Ed25519, P-256 and optional ML-DSA | Built, as a library that nothing calls |
| 2 | Enrolling a key and its post-quantum key in one signed step, database storage for one-time values and remembered post-quantum keys, a sign-in route behind a setting that is off by default with a limit on challenges, and an encrypted key file | Not built. Needs decisions about who may enroll a key, and a security review |
| 3 | Permission tokens (Biscuit) for what an agent may do on its own Companion | Not built |
| 4 | Encrypted sharing | Not built. Needs a product decision first |
| 5 | A signed log of grants, revocations and audit events | Not built. Depends on whether a KERI revocation log is built first |
Permissions that one Companion grants to another stay on the design that the KERI page describes. Phase 3 covers only what an agent holding a key may do on its own Companion.
What it does not do
- It does not replace or change the peer identity.
did:keri:D<key>and its request signatures work as before. - It does not bind a sign-in to a network connection. The audience ties a response to a verifier, not to a TLS session.
- It does not share state between servers. The one-time values live in the memory of one process. Two copies of the API would need a shared store.
- It does not limit how many challenges one caller can ask for. Anyone may ask, because the person asking has no credential yet. A route built on it needs a rate limit. Without one, a single caller can fill the space for challenges and stop everyone else from signing in.
- It does not make a P-256 signature a safe identifier. Hardware signers do not normalize their signatures, so a valid P-256 signature has a second valid form. Identify a response by its challenge nonce, not by its signature.
How far it has been checked
Checked:
- The reference implementation’s published test messages verify, and the library rebuilds the Ed25519 one byte for byte from its seed.
- ML-DSA keys and signatures at all three sizes (44, 65 and 87) match a second, unrelated implementation byte for byte.
- Ed25519 verification is stricter than the verifier built into Node.js (OpenSSL), as the reference’s strict verifier is. The tests build the forged signatures that OpenSSL accepts and the library refuses.
- A review by a second AI agent that was told to attack the code. It was not a person. It reported four problems, and a test reproduced each before anything changed. The checks now run in order of cost, with the one-time value checked before any signature. Unexpected answers from the storage or lookup code are refused instead of read as success. The post-quantum key must come from enrollment, as above. The need for a rate limit is documented.
Not checked:
- ML-DSA against the reference’s own code. The reference publishes no ML-DSA test messages to compare with.
- Any Node.js version other than 22.23.4. The repository pins 22.15.1, and the production image uses 26.13.0.
- Behavior under load, or across more than one process.
- Any review by a person.
For developers
The code is in backend/apps/api/src/domains/identikey/ in the Companion Memory repository . Its guide, docs/identikey.md, has a worked example that the test suite runs, the wire format, the order of the checks, and each place where the library is stricter than the Rust reference. The reference is identikey-protocol, and the library follows its commit e4fe668 of 4 November 2026.
Standards
- RFC 8949, section 4.2.1 : deterministic CBOR, the encoding that is signed
- RFC 8032 : Ed25519
- FIPS 186-5 : ECDSA, used with the P-256 curve
- FIPS 204 : ML-DSA
- RFC 9421 : HTTP message signatures, used by the peer identity this sits beside
Related
- Decentralized trust (KERI and ToIP) — the design this sits beside
- Asking and sharing architecture — how a signed ask is authenticated, and what a peer may see
- Asking other Companions — what a signed ask looks like in
/asks