Operator identity

An operator identity is the attribution recorded on a document a user publishes: a name, an email, and an Ed25519 signing key. It says who published something and never what they may do — a signature is attribution, never authorization.

Identity is per-user state. The signing keys live under config_home()/"keys" and the named-identity configuration lives in config_home()/"identity.json", both honouring HTTK_CONFIG_HOME through httk.core.userdirs.config_home(). Redirecting that one environment variable relocates the entire per-user identity store, which is how tests and isolated runs keep out of a real user’s configuration.

Named identities

from httk.core.identity import add_identity, resolve_operator_identity

add_identity("alice", "Alice", "alice@example.test")   # the first becomes default
add_identity("ci_bot", "CI", "ci@example.test", make_default=True)

resolve_operator_identity(None).short         # "ci_bot" — the default
resolve_operator_identity("alice").label      # "Alice <alice@example.test>"

add_identity, set_default_identity, and remove_identity maintain identity.json; initialize_identity(name, email) records a bare (un-named) identity and its default key. resolve_operator_identity also accepts a literal Name <email> selector for one-off attribution.

Signing documents

Signing is optional by construction: a caller with no identity key returns the document unchanged, and a verifier accepts an unsigned document. That is what keeps a mixed deployment — some installations with keys, some without — working.

from httk.core.identity import sign_document, verify_document

signed = sign_document({"format": "outcome", "value": 1})
result = verify_document(signed)
assert result.present and result.valid

sign_document adds an operator_key and a detached signature covering the canonical JSON of every other member, domain-separated so a signature made for one purpose cannot be replayed against another. verify_document reports whether a signature was present and whether it was valid; an absent signature is reported as absent rather than as a failure.