Documentation
¶
Overview ¶
Package auditchain implements the byte-level primitives used by the audit hash chain. It contains no persistence or chain-state behavior.
Index ¶
- Constants
- func EncodeCanonical(row Row) ([]byte, error)
- func EncodeEnvelope(envelope Envelope) ([]byte, error)
- func EncodeTLV(items ...Item) ([]byte, error)
- func HMACSHA256Hex(key, envelope []byte) string
- func Hash(envelope, key []byte) string
- func HashEnvelope(envelope Envelope, encoded, key []byte) (string, error)
- func SHA256Hex(envelope []byte) string
- func ValidateTimestamp(value string) error
- type Envelope
- type Item
- type Row
- type Tag
Constants ¶
const ( DomainTag = "agentsql-audit-chain-v1" GenesisASCII = "AGENTSQL_AUDIT_CHAIN_GENESIS_V1" GenesisPrevHex = "1fedc65006f788f0d939bfb0fa153df1576be6daf8e4f447f0c6e895eea573d4" AlgorithmSHA256 = "sha256" AlgorithmHMACSHA256 = "hmac-sha256" ChainManagement = "management" ChainTraffic = "traffic" ChainFormatVersionV1 = int64(1) TimestampLayout = "2006-01-02T15:04:05.000000Z" )
Variables ¶
This section is empty.
Functions ¶
func EncodeCanonical ¶
EncodeCanonical serializes all 27 V1 fields in the frozen E3 order. String bytes are used verbatim; JSON and Unicode are never normalized.
func EncodeEnvelope ¶
EncodeEnvelope validates and serializes all nine E2 fields in frozen order.
func EncodeTLV ¶
EncodeTLV encodes items as TAG || uint32-big-endian-LEN || PAYLOAD. It rejects values that do not have the canonical representation for their tag, including invalid UTF-8 text and non-canonical integers.
func HMACSHA256Hex ¶
HMACSHA256Hex returns lowercase hex(HMAC-SHA256(key, envelope)).
func Hash ¶
Hash computes the keyless hash when key is nil and HMAC-SHA256 otherwise. A present but empty key is intentionally distinct from a nil key.
func HashEnvelope ¶
HashEnvelope selects the hash algorithm by the envelope mode and rejects a missing HMAC key or an unexpected key in keyless mode.
func ValidateTimestamp ¶
ValidateTimestamp checks the fixed-width UTC microsecond format required by E4. Encoding remains byte-preserving and does not call this function.
Types ¶
type Envelope ¶
type Envelope struct {
DomainTag string
InstanceID string
ChainID string
FormatVersion int64
AlgorithmMode string
KeyVersion int64
ChainSeq int64
PrevHash [32]byte
Canonical []byte
}
Envelope contains the nine frozen E2 fields. PrevHash has a compile-time fixed width so it is always encoded as exactly 32 raw bytes.
type Row ¶
type Row struct {
ID int64 `json:"id"`
TS string `json:"ts"`
AgentID *string `json:"agent_id"`
DatasourceID *string `json:"datasource_id"`
SessionID *string `json:"session_id"`
ConversationID *string `json:"conversation_id"`
MCPTool *string `json:"mcp_tool"`
DBType *string `json:"db_type"`
SQLRaw *string `json:"sql_raw"`
SQLNorm *string `json:"sql_norm"`
StmtType *string `json:"stmt_type"`
Objects *string `json:"objects"`
Decision string `json:"decision"`
RuleHits *string `json:"rule_hits"`
RiskLevel *int64 `json:"risk_level"`
EstRows *int64 `json:"est_rows"`
RowsReturned *int64 `json:"rows_returned"`
LatencyMS *int64 `json:"latency_ms"`
ClientIP *string `json:"client_ip"`
ModelName *string `json:"model_name"`
ErrorMsg *string `json:"error_msg"`
ErrorCode *string `json:"error_code"`
Action *string `json:"action"`
ActorType *string `json:"actor_type"`
ActorID *string `json:"actor_id"`
DetailsJSON *string `json:"details_json"`
EventUUID *string `json:"event_uuid"`
}
Row is the complete V1 canonical business row. Pointer fields distinguish SQL NULL from a present zero value (including an empty string or integer 0).
Source Files