aci

type Array ¶

type Array []Value

Array is an ordered list of values; order is preserved on emit.

type Attestation ¶

type Attestation struct {
	Vendor            string            `json:"vendor"`
	TEEType           string            `json:"tee_type"`
	Keyset            Keyset            `json:"workload_keyset"`
	ReportDataHex     string            `json:"report_data"`
	KeysetEndorsement KeysetEndorsement `json:"keyset_endorsement"`
	SourceProvenance  SourceProvenance  `json:"source_provenance"`
	Freshness         Freshness         `json:"freshness"`
	Evidence          Evidence          `json:"evidence"`
}

Attestation is the report's attestation envelope: the workload keyset, the report_data the quote binds to, the keyset endorsement, build provenance, freshness window, and the TEE evidence (quote + event log + custody).

type Bool ¶

type Bool bool

Bool is a JSON boolean.

type Client ¶

type Client struct {
	// contains filtered or unexported fields
}

Client is the ACI confidential-inference client. It attests each model (cached), seals requests E2EE to the attested model key, POSTs them, opens the sealed response, and verifies the signed receipt before decoding — returning a provider-neutral *inference.Response only when every check passes.

It implements inference.Client. It is safe for concurrent use: the only mutable shared state is the session cache, which is internally synchronized.

Connection-binding note (fail-safe asymmetry): unlike the generic transport.Client — which binds one Endpoint and rejects a request whose Model.Provider/BaseURL differs with a pre-I/O *failure.ModelMismatchError — this client binds its gateway endpoint at construction (New's baseURL) and enforces model identity per request via TEE attestation. A provider/endpoint mismatch therefore surfaces as an *AttestationError (attestation cannot succeed against the wrong model/gateway), not a *failure.ModelMismatchError. This is fail-safe: the request is never sent when the check fails; only the error type differs.

func (c *Client) Invoke(ctx context.Context, req inference.Request) (*inference.Response, error)

func (c *Client) Stream(ctx context.Context, req inference.Request) (*stream.StreamReader[content.Chunk], error)

type EventLogEntry ¶

type EventLogEntry struct {
	IMR          uint32 `json:"imr"`
	EventType    uint32 `json:"event_type"`
	Digest       string `json:"digest"`
	Event        string `json:"event"`
	EventPayload string `json:"event_payload"`
}

EventLogEntry is one parsed event-log record. evidence.event_log is a raw JSON-in-string at THIS layer; this type is modeled now so Task 2.5 can decode the log into it. The serde rename type -> EventType applies here (Go has no "type" field name and the wire key stays "event_type").

type Evidence ¶

type Evidence struct {
	Quote                string     `json:"quote"`
	QuoteReportData      string     `json:"quote_report_data"`
	EventLog             string     `json:"event_log"`
	VMConfig             string     `json:"vm_config"`
	KeyCustody           KeyCustody `json:"key_custody"`
	DownstreamTLSBinding TLSBinding `json:"downstream_tls_binding"`
}

Evidence is the TEE evidence: the TDX quote and its report_data, the raw (double-encoded) event log and VM config strings, the KMS key-custody chain, and the downstream TLS binding. quote/event_log/vm_config stay raw strings at this layer; later tasks parse them.

type Float ¶

type Float float64

Float is a NON-integer JSON number used ONLY by the compact body serializer (CompactJSON), not by the JCS canonical path. Real chat-request bodies carry fractional sampling params (temperature/top_p, e.g. 0.7, 0.9), so the body hash must serialize floats; the constrained JCS profile forbids them. Float therefore lives in the shared Value union but is REJECTED by Canonicalize (it surfaces *FloatNotAllowedError there) and accepted only by CompactJSON. See body.go for the emission rules and their validated serde_json domain.

type FloatNotAllowedError ¶

type FloatNotAllowedError struct {
	// Literal is the offending JSON number literal (e.g. "1.5", "1e5", "+1",
	// "01"). It is a numeric token only and carries no secret material.
	Literal string
}

FloatNotAllowedError reports a JSON number that is not an acceptable integer under the constrained JCS profile: a fraction, an exponent, a value outside the i64 ∪ u64 range, OR a literal that is not in canonical JSON-integer form (a leading '+' or a leading zero such as "01"). It carries the offending decimal literal so callers can inspect the cause; it is the Go analogue of the Rust CanonicalError variant FloatNotAllowed. It is an internal canonicalization failure, distinct from the protocol-level *llm.AttestationError reasons.

The grammar gate matters off the JSON-parse path: serde_json (and Go's json.Decoder) only ever produce grammar-valid number literals, so on the parse path the looser cases never occur. But a programmatically-constructed Number("+1") / Number("01") must fail closed rather than be silently normalized — a digest validator must reject anything it would not have emitted.

func (e *FloatNotAllowedError) Error() string

type FloatOutOfDomainError ¶

type FloatOutOfDomainError struct {
	// Value is the shortest decimal form of the offending magnitude (e.g.
	// "1e+16"). It is a numeric label and carries no payload bytes.
	Value string
}

FloatOutOfDomainError reports a finite Float whose magnitude falls in the range where serde_json (ryu) emits EXPONENT form rather than plain decimal — |x| >= 1e16 or 0 < |x| < 1e-5. In that range serde's spelling (e.g. "1e+16", "1e-6") cannot be reproduced by Go's shortest-float emitter without re-deriving ryu's exact exponent rules, so this serializer REFUSES to emit such a value rather than risk a wrong body hash. The realistic sampling-parameter domain (temperature/top_p ∈ [0,2]) lies entirely inside the decimal-form window, so this never fires on a real body; it is the runtime form of Task 1.3's "blocker #2: STOP and report" rule — a value here must be re-pinned against a fresh Rust vector before its hash can be trusted.

It carries the offending value's shortest decimal form (a numeric label, no secret material) so the caller can identify it.

func (e *FloatOutOfDomainError) Error() string

type Freshness ¶

type Freshness struct {
	FetchedAt  int64 `json:"fetched_at"`
	StaleAfter int64 `json:"stale_after"`
}

Freshness is the report's validity window in Unix seconds. Both bounds fit int64 comfortably (they are wall-clock seconds, not the epoch sentinel).

type Int ¶

type Int int64

Int is a signed-integer JSON number (the i64 arm of the number rule).

type InvalidUTF8Error ¶

type InvalidUTF8Error struct {
	// Where names the location of the fault: "string" for a String value or
	// "object key" for a member key. It is a fixed label, never external data.
	Where string
}

InvalidUTF8Error reports a String value or object key that is not valid UTF-8. The emitter writes string bytes verbatim while the key sort decodes them via []rune (which folds invalid sequences to U+FFFD); those two views diverge on malformed input, so a digest validator must reject it rather than risk an order/encoding mismatch. On the JSON-parse path this never occurs (json guarantees valid UTF-8), but Task 1.3 builds String values programmatically.

It deliberately does NOT echo the offending bytes (they may be arbitrary, possibly secret-adjacent payload); it reports only where the fault was found.

func (e *InvalidUTF8Error) Error() string

type KeyCustody ¶

type KeyCustody struct {
	Provider string            `json:"provider"`
	Keys     []KeyCustodyEntry `json:"keys"`
}

KeyCustody is the KMS custody record: which provider holds the workload keys and, per key, the signature chain proving custody back to the KMS root.

type KeyCustodyEntry ¶

type KeyCustodyEntry struct {
	Role           string   `json:"role"`
	Path           string   `json:"path"`
	Purpose        string   `json:"purpose"`
	Algo           string   `json:"algo"`
	PublicKeyHex   string   `json:"public_key"`
	SignatureChain []string `json:"signature_chain"`
}

KeyCustodyEntry is one custody record: the key's role/path/purpose, its algorithm and hex public key, and the signature chain (hex links) binding it to the KMS root. public_key -> PublicKeyHex applies the serde rename.

type KeyEntry ¶

type KeyEntry struct {
	KeyID        string `json:"key_id"`
	Algo         string `json:"algo"`
	PublicKeyHex string `json:"public_key"`
}

KeyEntry is one entry in the receipt-signing and E2EE key lists: a key id, its algorithm, and the hex-encoded public key. The two lists share this shape, so they share the type. public_key -> PublicKeyHex applies the serde rename.

type Keyset ¶

type Keyset struct {
	Identity           WorkloadIdentity `json:"workload_identity"`
	Epoch              KeysetEpoch      `json:"keyset_epoch"`
	ReceiptSigningKeys []KeyEntry       `json:"receipt_signing_keys"`
	E2EEPublicKeys     []KeyEntry       `json:"e2ee_public_keys"`
	TLSPublicKeys      []TLSBinding     `json:"tls_public_keys"`
}

Keyset is the workload's published key material: the workload identity key, the epoch (version + expiry), and the receipt/E2EE/TLS key lists the gateway uses to sign receipts, accept E2EE envelopes, and bind TLS endpoints.

type KeysetEndorsement ¶

type KeysetEndorsement struct {
	Algo     string `json:"algo"`
	ValueHex string `json:"value"`
}

KeysetEndorsement is the signature over the workload keyset by the KMS root. value -> ValueHex applies the serde rename.

type KeysetEpoch ¶

type KeysetEpoch struct {
	Version  uint64 `json:"version"`
	NotAfter uint64 `json:"not_after"`
}

KeysetEpoch is the keyset's monotonic epoch and its expiry. NotAfter is uint64 because the fixture carries 2^64-1 (a "never expires" sentinel) which does not fit int64. Version is uint64 for symmetry with the unsigned epoch.

type NonFiniteFloatError ¶

type NonFiniteFloatError struct {
	// Repr is the Go string form of the non-finite value ("NaN", "+Inf",
	// "-Inf"). It is a fixed numeric label and carries no payload bytes.
	Repr string
}

NonFiniteFloatError reports a Float value that is NaN or ±Inf. JSON has no representation for non-finite numbers (serde_json's Number cannot even hold them — Number::from_f64 returns None), so a non-finite Float can never appear in a real body and must fail closed rather than emit a non-JSON token. It is typed (per CLAUDE.md's no-bare-error rule) and carries the Go textual form of the offending value ("NaN", "+Inf", "-Inf") — a numeric label, never secret material.

func (e *NonFiniteFloatError) Error() string

type Null ¶

type Null struct{}

Null is the JSON null literal.

type Number ¶

type Number json.Number

Number is an integer JSON number carried verbatim as the source decimal literal (e.g. produced by the parser, which defers the i64-then-u64 check to emit time). Canonicalize validates it: a non-integer or out-of-range literal yields a *FloatNotAllowedError, matching the Rust reference's as_i64/as_u64 fallthrough.

type Object ¶

type Object struct {
	// contains filtered or unexported fields
}

Object is a JSON object stored as ordered key/value pairs in insertion order. JCS key sorting is applied by the emitter, not by this type, so the same Object can be emitted in insertion order by a non-sorting serializer.

func NewObject() *Object

func (o *Object) KeyAt(i int) string

func (o *Object) Len() int

func (o *Object) Set(key string, val Value) *Object

func (o *Object) ValueAt(i int) Value

type Option ¶

type Option func(*Client)

Option configures a Client at construction. Only the knobs production or tests actually use are exposed; nothing speculative.

func WithAttestFunc(attest attestFunc) Option

func WithHTTPDoer(d httpDoer) Option

func WithNonceFunc(newNonce func() string) Option

func WithNow(now func() time.Time) Option

func WithQuoteVerifier(v quoteVerifier) Option

type Policy ¶

type Policy struct {
	// AcceptedWorkloadIDs is the set of accepted workload_id strings
	// ("sha256:<hex>"). Commonly left EMPTY: the workload_id is a digest of the
	// keyset, which ROTATES with each keyset epoch, so pinning it would reject a
	// legitimately rotated keyset. Trust is instead anchored by app-id +
	// provenance + KMS-root custody (the fields below), which are stable across
	// rotations. Populate this only to pin one exact keyset.
	AcceptedWorkloadIDs map[string]struct{}

	// AcceptedSourceProvenance is the set of accepted {repo_url, repo_commit}
	// build-provenance pairs (rtmr.go's ProvenanceKey). Checked in step 5.
	AcceptedSourceProvenance map[ProvenanceKey]struct{}

	// AcceptedAppIDs is the set of accepted workload app-ids as lowercase hex of
	// the app-id bytes (encoding/hex form). Checked in step 5.
	AcceptedAppIDs map[string]struct{}

	// AcceptedKMSRootPubKeys is the set of accepted KMS-root public keys as
	// compressed-SEC1 hex. Checked in step 7 (key custody recovers the root and
	// requires membership).
	AcceptedKMSRootPubKeys map[string]struct{}
	// contains filtered or unexported fields
}

Policy is the attestation acceptance allow-list set: which app-ids, source provenances, KMS roots, and workload_ids VerifyReport will accept. A nil/empty field skips its check ("when configured"); a non-empty field requires membership. At the LOW-LEVEL verifyReport (verify.go) a zero value Policy{} still accepts any genuine, quote-backed report (no allow-listing) — that is the mechanism. The PUBLIC entry points (New and VerifyReport both call requireAcceptable) instead FAIL CLOSED: an unpinned Policy is rejected with *UnpinnedPolicyError unless the caller opts in with UnpinnedPolicy(). Callers narrow trust by populating fields.

func UnpinnedPolicy() Policy

func (p Policy) IsPinned() bool

type ProvenanceKey ¶

type ProvenanceKey struct {
	RepoURL    string
	RepoCommit string
}

ProvenanceKey is the comparable allow-list key for source provenance: the {repo_url, repo_commit} pair. A Policy's AcceptedSourceProvenance set uses this exact key form so checkProvenancePolicy can do a single map lookup. It is a struct (not a joined string) so neither field can be confused with a delimiter inside the other. It is exported so callers outside this package (a provider's pinned-policy constructor) can populate AcceptedSourceProvenance directly.

type PublicKey ¶

type PublicKey struct {
	Algo         string `json:"algo"`
	PublicKeyHex string `json:"public_key"`
}

PublicKey is an algorithm-tagged public key (algo + hex-encoded key bytes). public_key -> PublicKeyHex applies the serde rename; the wire key stays "public_key".

type Receipt ¶

type Receipt struct {
	APIVersion           string           `json:"api_version"`
	ReceiptID            string           `json:"receipt_id"`
	ChatID               *string          `json:"chat_id"`
	WorkloadID           string           `json:"workload_id"`
	WorkloadKeysetDigest string           `json:"workload_keyset_digest"`
	Endpoint             string           `json:"endpoint"`
	Method               string           `json:"method"`
	ServedAt             uint64           `json:"served_at"`
	EventLog             []ReceiptEvent   `json:"event_log"`
	Signature            ReceiptSignature `json:"signature"`
}

Receipt is a parsed ACI §9 receipt: the per-request signed event log plus its metadata and the signature over the canonical projection. ChatID is a pointer because the wire field is nullable (Rust Option<String>): nil when absent/null, a string when present — the two project to different canonical bytes. ServedAt and ReceiptEvent.Seq are uint64 (the Rust u64 arm).

func ParseReceipt(data []byte) (*Receipt, error)

type ReceiptEvent ¶

type ReceiptEvent struct {
	Seq       uint64          `json:"seq"`
	EventType string          `json:"type"`
	Fields    json.RawMessage `json:"-"`
}

ReceiptEvent is one event in the receipt's event log. The wire shape flattens seq and type to the top of the object alongside any type-specific fields; this struct keeps Fields as RAW JSON (an object), parsed into a jcs.Value only when building the canonical projection. EventType reads the wire key "type".

type ReceiptExpect ¶

type ReceiptExpect struct {
	Endpoint          string
	Method            string
	Vendor            string
	ModelID           string
	ReqBody           []byte
	RespBodyCleartext []byte
	RespWireBytes     []byte
}

ReceiptExpect carries the caller-supplied expectations VerifyReceipt binds the receipt against. The request body is supplied as the ALREADY-COMPACT serde_json bytes (the caller — Task 5.2 — computes CompactJSON over the decrypted cleartext request body); VerifyReceipt hashes those bytes directly with Sha256HexBytes. The response cleartext and wire fields are likewise already-serialized bytes.

RespBodyCleartext is nil to SKIP the cleartext_hash check. The non-streaming caller (Invoke) supplies it, so cleartext_hash is enforced; the STREAMING caller (Stream — Task 5.3) passes nil, because the client only sees the sealed WIRE bytes and cannot reconstruct the raw upstream framing the gateway hashed for cleartext_hash. For streaming, wire_hash (over the exact wire bytes) plus the E2EE-authenticated open of each delta cover content authenticity instead.

RespWireBytes is nil to SKIP the wire_hash check (the wire-bytes hash is optional in the design doc). The two response-hash checks are independent: a nil preimage skips only its own hash. Vendor is the upstream provider TYPE (the design doc's "vendor" maps to the event's `provider` field); an empty Vendor skips the provider check, binding the upstream event on result + model_id alone.

type ReceiptSignature ¶

type ReceiptSignature struct {
	Algo     string `json:"algo"`
	KeyID    string `json:"key_id"`
	ValueHex string `json:"value"`
}

ReceiptSignature is the receipt's signature block: the algorithm, the key id naming the attested receipt-signing key, and the hex signature value. ValueHex reads the wire key "value"; it is OMITTED from the canonical projection (it is the signed thing).

type Report ¶

type Report struct {
	APIVersion           string              `json:"api_version"`
	WorkloadID           string              `json:"workload_id"`
	WorkloadKeysetDigest string              `json:"workload_keyset_digest"`
	Attestation          Attestation         `json:"attestation"`
	ServiceCapabilities  ServiceCapabilities `json:"service_capabilities"`
}

Report is a decoded Dstack ACI attestation report. It is the root of the model every Phase 2 verification step consumes.

func ParseReport(data []byte) (*Report, error)

type ServiceCapabilities ¶

type ServiceCapabilities struct {
	SupportedE2EEVersions []string `json:"supported_e2ee_versions"`
}

ServiceCapabilities advertises which E2EE protocol versions the gateway supports. Versions are wire strings ("2").

type SourceProvenance ¶

type SourceProvenance struct {
	RepoURL         string  `json:"repo_url"`
	RepoCommit      string  `json:"repo_commit"`
	ImageDigest     *string `json:"image_digest"`
	ImageProvenance *string `json:"image_provenance"`
}

SourceProvenance is the build provenance of the workload image. ImageDigest and ImageProvenance are null in the fixture, so both are optional pointers.

type String ¶

type String string

String is a JSON string value.

type TLSBinding ¶

type TLSBinding struct {
	Domain        string `json:"domain"`
	SPKISHA256Hex string `json:"spki_sha256"`
}

TLSBinding binds a domain to the SHA-256 of its TLS SubjectPublicKeyInfo. It is reused by both tls_public_keys and evidence.downstream_tls_binding. spki_sha256 -> SPKISHA256Hex applies the serde rename.

type Uint ¶

type Uint uint64

Uint is an unsigned-integer JSON number (the u64 tail above the i64 range).

type UnpinnedPolicyError ¶

type UnpinnedPolicyError struct{}

UnpinnedPolicyError is returned by the public aci entry points when a Policy pins no acceptance set and did not explicitly opt into unpinned mode via UnpinnedPolicy(). Fail-secure: attestation refuses to run allow-list-free unless the caller asks for it. Like apiVersionMismatchError it uses a pointer receiver and is returned as *UnpinnedPolicyError so callers can errors.As it.

func (e *UnpinnedPolicyError) Error() string

type Value ¶

type Value interface {
	// contains filtered or unexported methods
}

Value is the sealed union of canonicalizable JSON values. The unexported marker method keeps the set of concrete types closed to this package.

func ParseBodyValue(data []byte) (Value, error)

func ParseValue(data []byte) (Value, error)

type VerifiedReport ¶

type VerifiedReport struct {
	// WorkloadID is the validated workload_id ("sha256:<hex>"), recomputed and
	// matched in step 2.
	WorkloadID string
	// WorkloadKeysetDigest is the validated workload_keyset_digest
	// ("sha256:<hex>"), recomputed and matched in step 2.
	WorkloadKeysetDigest string
	// Keyset is the full validated keyset: identity, epoch, and the
	// receipt-signing / E2EE / TLS key lists Phase 3/4/5 consume. It is the value
	// whose digest step 2 verified, so its keys are attestation-backed.
	Keyset Keyset
}

VerifiedReport is the validated output of a passing attestation chain: the workload identity (workload_id + keyset digest) and the FULL validated keyset. Phase 3 (E2EE sealing) reads Keyset.E2EEPublicKeys; Phase 4 (receipt verification) reads Keyset.ReceiptSigningKeys; both get their key ids, algos, and public keys from the embedded Keyset, which is the exact value whose digest was recomputed and matched in step 2 (so the keys are the attested ones, not merely claimed). Returned only on a fully successful chain; nil on any failure.

func VerifyReport(reportJSON []byte, nonce *string, now time.Time, policy Policy) (*VerifiedReport, error)

type WorkloadIdentity ¶

type WorkloadIdentity struct {
	PublicKey PublicKey `json:"public_key"`
	Subject   *string   `json:"subject"`
}

WorkloadIdentity is the workload's identity key plus an optional subject. The fixture's subject is null, so Subject is a pointer that stays nil when absent.