niko_trust/docs/TRUST-MODEL.md

Trust model

This document explains who is trusted to say what, and why the relay itself never makes a trust decision. Read this before assuming a missing signature check is a vulnerability.

Roles

Role	What it is
Issuer	Holds a signing key; makes a signed statement (a claim, a response).
Subject	The address a claim is about.
Approver	An address trusted to allow/deny an ApprovalRequest.
Relay	The HTTP server (internal/server). Stores signed objects. No keys.
Verifier	The consumer running internal/verify. Checks signatures, decides trust.

Objects are signed by their issuer

Every object on the wire is a transport.Envelope{TCE, Signature}. The TCE is a self-describing, content-addressed blob; the Signature is over the exact TCE bytes and is verified against the public key embedded inside the TCE (the issuer's key).

A claim therefore reads as:

issuer   = <key that signed it>
subject  = <address the claim is about>
claims   = { predicate: value }

The signature binds the statement to the issuer's key. There is no way to emit a record that appears to come from an issuer without holding that issuer's key.

Worked example

trust1abc says: trust1def has minecraft.op: true.

1. trust1abc builds a Claim{Issuer: trust1abc, Subject: trust1def, Claims: {"minecraft.op": true}}, encodes it to TCE, signs it with trust1abc's key.

2. PUT /v1/objects stores the envelope. The relay does not verify the signature — it only checks the envelope is well-formed and content-addressed.

3. Later, a consumer queries GET /v1/claims?subject=trust1def and receives a list of envelopes ({ "tce": "<base64>", "signature": "<base64>" }). The consumer decodes the TCE to read issuer / subject / claims.

4. The consumer runs verify.Graph.Add(env), which calls env.Verify() and confirms the signature matches trust1abc's key — i.e. trust1abc really said that.

An attacker cannot forge "from trust1abc": any record they produce carries their own key as issuer, so it shows up attributed to the attacker and is ignored by anyone who does not trust that key.

Why the relay does not verify signatures

The relay implements INV-5 ("who said what"), not "should I believe it". It is a content-addressed bulletin board:

• It accepts any well-formed envelope (PUT returns 200 even for a bad signature). Storing unverified data is correct and intentional.
• All cryptographic trust decisions live in internal/verify, which never talks to the network and never holds a key.

Consequence: signature verification is the verifier's job, not the server's. A PUT with a tampered signature is stored; verify.Graph.Add rejects it.

Who do you believe? (issuer anchoring)

Because any key can sign a claim about any subject, the verifier must decide which issuers it trusts. This is done out of band, by the consumer:

• verify.Result.Issuer is always returned (verify.go). The consumer compares it to the set of issuers it trusts, e.g. result.Issuer == trust1abc.
• For approvals, trust is anchored explicitly: Policy.Approvers lists the addresses whose Allow responses count, and Policy.Threshold is the k-of-n.

There is intentionally no Policy.Issuer filter: the model is "feed the verifier only the objects you retrieved, then trust based on Result.Issuer". If you need issuer restriction inside evaluation, add an Issuer/TrustedIssuers field to Policy — but that is a policy choice, not a relay concern.

Approval flow

1. Issuer sends ApprovalRequest{Recipient: approver, Action: predicate, ...}.
2. Approver sends ApprovalResponse{RequestHash, Decision: Allow, ...} signed by the approver. The response is bound to the request and verified together via protocol.VerifyApprovalResponse.
3. The relay enforces at most one response per request (422 on a second).
4. verify collects valid Allow responses from Policy.Approvers and checks the count against Policy.Threshold.

Revocation

• A claim is revoked by a Revocation signed by the claim's issuer (protocol.VerifyRevocationOf).
• An approval is withdrawn by a Revocation targeting the response's object id, signed by the responder (the approver revoking their own decision).