From 1e02f1473f33af84474118758c704b515da8e96f Mon Sep 17 00:00:00 2001 From: flemming-it Date: Sat, 31 Oct 2026 02:21:11 +0100 Subject: [PATCH] chore(proto): re-sync the chain.v1 copies after the evidence RPCs Signed-off-by: flemming-it --- proto/CHECKSUMS | 2 +- proto/chain/v1/hub.proto | 154 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 155 insertions(+), 1 deletion(-) diff --git a/proto/CHECKSUMS b/proto/CHECKSUMS index f85aead..fd25fb3 100644 --- a/proto/CHECKSUMS +++ b/proto/CHECKSUMS @@ -1,4 +1,4 @@ 98a68dd39de4f98d965baf87eca60acc53bb393bd90ae9feb2c07b98071823d9 chain/v1/common.proto -78964aaff179fc43d59776a0f81e57197aff3f1ae61fabdc4b186abfdb4279d6 chain/v1/hub.proto +0dc735d634ddd390dacbe91f4e4b2a6a5175cb0fe561a15786deba43636175c0 chain/v1/hub.proto 1b2742775d3abe0bcbdcb4a56c14b434e8547f672ea10a7f648ad14c7e14bef7 chain/v1/module.proto 47d3af9df026a40f5f5a76311965f719e3ceb49ad944c4393e02158a0bdb1873 chain/v1/federation.proto diff --git a/proto/chain/v1/hub.proto b/proto/chain/v1/hub.proto index 831d2a3..4c6eff8 100644 --- a/proto/chain/v1/hub.proto +++ b/proto/chain/v1/hub.proto @@ -171,6 +171,41 @@ service HubAdmin { // the CLI as `chain admin events clear`. rpc ClearEventLog(ClearEventLogRequest) returns (ClearEventLogResponse); + // Append events that happened OUTSIDE this hub to the audit + // chain: an application records its own decision trail here so a + // third party can check it against the hash chain, the actor + // signatures and the head anchors. Each event carries an + // idempotency key that is unique within its project, so a + // repeated submission answers with the first event id instead of + // appending twice. Narrow scope `record` (optionally + // `record:`); `admin` is a superset. + rpc RecordEvents(RecordEventsRequest) returns (RecordEventsResponse); + + // Register the public key of an actor that may record events. + // Re-registering the same id with the same key is idempotent; + // with a different key it is refused. + rpc RegisterSigningKey(RegisterSigningKeyRequest) returns (SigningKeyList); + + // Every registered signing key, revoked ones included, plus the + // hub's own service key. + rpc ListSigningKeys(google.protobuf.Empty) returns (SigningKeyList); + + // Mark a signing key invalid from now on. The key keeps its row + // so signatures it already made stay checkable. + rpc RevokeSigningKey(RevokeSigningKeyRequest) returns (SigningKeyList); + + // Sign the current chain head with the hub's service key and, + // when a timestamp authority is configured, have that signature + // timestamped per RFC 3161. Without an anchor a truncated tail + // is indistinguishable from a log that never grew. + rpc AnchorEventChain(AnchorEventChainRequest) returns (AnchorEventChainResponse); + + // Build the evidence package for an auditor: the chain, the + // actor signatures, the public keys, the anchors and a verifier + // that runs without this hub. Returns the package bytes; the CLI + // writes them to a file. + rpc ExportEvidence(ExportEvidenceRequest) returns (ExportEvidenceResponse); + // Read the operator's `default_scope:` (the ordered list of // provider segments the bare-form capability resolver tries // when a flow names a capability without `/` @@ -1490,6 +1525,125 @@ message ClearEventLogResponse { string channel = 2; } +// One event that happened outside the hub. +message ExternalEvent { + // Type tag. Must start with one of the external prefixes + // (`ai.`, `human.`, `decision.`, `compliance.`, `ext.`); the hub + // writes its own history and a client cannot add to it. + string event_type = 1; + // Caller-chosen key, unique within the project. Required. + string idempotency_key = 2; + // When the event happened in the calling system (ISO 8601 with a + // zone), or empty. The hub always records its own receipt time. + string occurred_at = 3; + // The event's fields as a JSON object, submitted and stored + // verbatim: the signature is over exactly these bytes, so + // re-serializing them would break it. The decision event types + // require `case` plus their own fields. + string detail_json = 4; + // Key id the signature belongs to. + string key_id = 5; + // Base64 Ed25519 signature over the domain tag + // `CHAIN-EXTERNAL-EVENT-V1`, a NUL byte, and then project, + // event_type, idempotency_key, occurred_at and detail_json, each + // prefixed with its byte length as little-endian uint32. + string signature_b64 = 6; +} + +message RecordEventsRequest { + // Project the events belong to. Empty means `general`. + string project = 1; + // The events, in the order they happened. An event may refer to + // another event of the same batch. + repeated ExternalEvent events = 2; +} + +message RecordedExternalEvent { + // Event id in the chain. + string event_id = 1; + // SHA-256 of the signed payload. + string content_sha256 = 2; + // True when the idempotency key was already recorded: this is + // the first submission's event id, nothing was appended. + bool replayed = 3; +} + +message RecordEventsResponse { + // One entry per submitted event, in request order. + repeated RecordedExternalEvent events = 1; +} + +message SigningKeyEntry { + string key_id = 1; + // Project glob the key may record into; `*` for every project. + string project = 2; + // Pseudonym of the actor. An event naming an actor must be + // signed with that actor's key. + string actor = 3; + // `service` for a machine, otherwise the person's role. + string role = 4; + // Always `ed25519` today. + string algorithm = 5; + // Raw 32-byte public key, base64. + string public_key = 6; + string added_at = 7; + // Empty while the key is valid. + string revoked_at = 8; +} + +message RegisterSigningKeyRequest { + SigningKeyEntry key = 1; +} + +message RevokeSigningKeyRequest { + string key_id = 1; +} + +message SigningKeyList { + repeated SigningKeyEntry keys = 1; + // The hub's own service key, base64. It signs the anchors. + string service_public_key = 2; +} + +message AnchorEventChainRequest { + // Timestamp authority to use for this anchor. Empty takes the + // operator's `audit.timestamp_authority`; the anchor is written + // with a signature but without a timestamp when neither is set. + string timestamp_authority = 1; +} + +message AnchorEventChainResponse { + string anchor_id = 1; + // Chain head the anchor covers. + string head_event_id = 2; + string head_sha256 = 3; + int64 event_count = 4; + // Base64 Ed25519 signature of the service key over the anchor + // payload. + string signature = 5; + // Authority that timestamped it, empty when none was configured. + string tsa_url = 6; + // The time the authority asserted, empty when none was used. + string tsa_time = 7; +} + +message ExportEvidenceRequest { + // Project whose events are exported with their payload. Other + // projects' rows travel as hashes only, so the chain still + // verifies without disclosing their content. Empty exports every + // project in full. + string project = 1; +} + +message ExportEvidenceResponse { + // The package as a gzipped tar archive. + bytes package = 1; + // File name the CLI suggests. + string filename = 2; + // Number of events in the package. + int64 event_count = 3; +} + message SetDefaultScopeRequest { // New `default_scope` value. The first entry is the // primary scope (the resolver consults the others in order