niko_trust/docs/INVARIANTS.md

Protocol invariants

These are normative. Every stage of the implementation is checked against them, and several are enforced by tests that inspect the source tree so that a violation breaks the build rather than merely contradicting a comment.

The single sentence the whole design reduces to:

Cryptography establishes who said something. The application decides whether it trusts them and what their statement means.

The invariants

INV-1. A trust server compromise must never allow forging an identity, claim, approval or authorization response.

The server holds no signing key. Signing capability lives exclusively in internal/identity/signer, which server packages do not import. An attacker with full database and process control can read public data, delete it, delay it, censor it and deny service, but cannot produce a signature.

Enforced by TestNoSigningOutsideSigner, TestProtocolDoesNotImportSigner.

INV-2. trust.n1ko.dev is never an issuer of claims or approvals.

There is no server identity, no root key and no certificate authority. The server never appears as the issuer of a claim or the sender of a request. The only random material it produces is authentication challenge nonces, which are not protocol objects and carry no signature.

INV-3. Database identifiers are never security identifiers.

Security identity is always cryptographic: an Ed25519 public key, or a content-addressed hash of canonical object bytes. No autoincrement column, row id or server-assigned handle ever appears in a signed object or in an authorization-relevant comparison.

INV-4. An ApprovalResponse is valid only when its request_hash matches the exact canonical ApprovalRequest bytes.

The response commits to the full request, not to a sender-chosen label. Verification takes both objects, so there is no API that can check a response in isolation and no way to reuse a signed decision under a different request.

INV-5. Applications must perform their own authorization decisions.

The protocol authenticates statements and approvals. It never answers "is this allowed". No API returns a permission verdict, and no package contains a notion of role, capability or permission.

Enforced by TestNoApplicationSemantics.

INV-6. No implicit transitive trust.

If A trusts B, that says nothing about identities B trusts. The server never traverses a trust graph, never joins claims across issuers and never derives a statement that no one signed.

INV-7. Aliases are never security-sensitive.

An alias is a self-asserted display label. It is not unique, not verified, and must not participate in signature verification or authorization. Aliases are excluded from the canonical encoding of claims and approvals. User interfaces must never display an alias without its address.

Enforced by TestAliasNeverAffectsVerification, TestDisplayAlwaysShowsAddress.

INV-8. Every security-sensitive object has a precisely defined canonical representation, specified before it is implemented.

Signatures are computed over canonical bytes, never over JSON. Each object has exactly one valid encoding; any input with two possible spellings is either normalised to one or rejected.

INV-9. Protocol packages must not import application-specific packages.

The protocol layer depends only on the standard library and vetted cryptographic primitives. Storage, transport and application semantics stay outside it.

Enforced by TestProtocolLayerImports.

INV-10. Property and fuzz tests for all parsers, canonicalization, address decoding, TCE decoding and signature verification.

Every parser that touches untrusted input has a fuzz target asserting totality (no panic, no hang, no unbounded allocation) and the specific correctness properties of that parser.

The canonical pipeline

canonical object
      |
      v
     TCE            deterministic, length-prefixed binary encoding
      |
      v
   SHA-256
      |
      v
  object ID         content address; identifies and references the object
      |
      v
Ed25519 signature   computed over the TCE bytes, not over the ID

Consequences that follow from this pipeline and are treated as binding:

• The signature covers the TCE bytes. The hash is used for identification and reference only, never as the signing input.
• The object ID is a content address, so INV-3 holds by construction and the request_hash check in INV-4 is a byte comparison.
• The TCE encoding of an object excludes its own signature field.
• Canonicalization is total and rejecting: duplicate map keys, invalid UTF-8, unknown type tags and non-normalizable numbers are all refused rather than repaired.
• Decode(Encode(x)) == x and Encode(Decode(b)) == b are both fuzz properties. The second rules out malleability, where two distinct byte strings decode to the same object.

Additional rule adopted during Stage 1

Public keys must be canonical points of the prime-order subgroup.

crypto/ed25519.Verify follows RFC 8032 and performs no checks on the public key. That is not sufficient when the attacker chooses the key. The order-1 point admits a single signature that verifies against every message, which would give its holder an identity whose signature is valid on any claim or approval in existence: a direct break of INV-1.

Every public key entering the system is therefore validated as a canonically encoded, non-small-order curve point before it can become an address. The check happens once, at address construction, so that any Address or Identity value elsewhere in the program has already passed it.

Enforced by TestRejectsSmallOrderKeys, TestDegenerateKeyWouldForgeSignatures, TestParseRejectsEmbeddedSmallOrderKey.