verdifax

package module
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 5, 2026 License: MIT Imports: 18 Imported by: 0

README

verdifax-sdk-go

The official Go SDK for the Verdifax orchestrator REST API.

Install

go get github.com/Verdifax/verdifax-sdk-go

Quickstart

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/Verdifax/verdifax-sdk-go"
)

func main() {
    client, err := verdifax.NewClient(verdifax.Config{
        BaseURL: "https://api.verdifax.com",
        APIKey:  os.Getenv("VERDIFAX_API_KEY"),
    })
    if err != nil {
        log.Fatal(err)
    }

    // Attest a decision through the pipeline.
    run, err := client.Execute(context.Background(), &verdifax.ExecuteRequest{
        ProgramID:          "1111111111111111111111111111111111111111111111111111111111111111",
        RouteID:            "demo-attestation",
        RegistryRecordHash: "2222222222222222222222222222222222222222222222222222222222222222",
        PayloadText:        "first attestation",
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Sealed run %d, manifest hash %s\n",
        run.RunID, run.Manifest.ManifestHash)

    // Verify the seal recomputes correctly.
    v, err := client.VerifyRun(context.Background(), run.RunID)
    if err != nil {
        log.Fatal(err)
    }
    if v.Verified {
        fmt.Println("✓ Manifest hash recomputes.")
    }
}

What this SDK covers

  • Health(ctx), /health, anonymous liveness probe + git SHA
  • Version(ctx), /version, deploy attestation surface
  • Execute(ctx, req), POST /execute, the core pipeline-execution flow
  • GetRun(ctx, id), GET /runs/{id}, fetch a sealed run
  • VerifyRun(ctx, id), GET /runs/{id}/verify, re-derive the seal
  • RegisterRequestKey(ctx), POST /keys/request-key, require request signatures
  • ClearRequestKey(ctx), DELETE /keys/request-key, stop requiring them

The full HTTP surface (every endpoint, deletion-receipt list, DCAE verify, admin endpoints) is documented in the OpenAPI spec. This SDK ships the canonical operations; broader coverage lands as integrators ask.

Authentication

Every authenticated endpoint expects the API key in the X-Verdifax-Key header. The Client injects it automatically when the Config carries APIKey.

Provision an API key via:

curl -X POST https://api.verdifax.com/admin/keys \
  -H "Content-Type: application/json" \
  -d '{"name": "go-sdk-prod"}'

The response carries the secret once, store it immediately. After that, the orchestrator stores only its hash.

Request signing

Request signing is optional. A client with no signing key sends the same requests as before.

You can register an Ed25519 public key on your API key, so that each run must also be signed with a private key that only you hold. The key pair is created on your machine, and Verdifax receives only the public key.

// Run once, then store privateKey as a secret. It is 32 raw bytes.
_, privateKey, err := verdifax.GenerateRequestKey()
if err != nil {
    log.Fatal(err)
}

client, err := verdifax.NewClient(verdifax.Config{
    APIKey:     os.Getenv("VERDIFAX_API_KEY"),
    SigningKey: privateKey,
})
if err != nil {
    log.Fatal(err)
}

ctx := context.Background()

// Sends the public key with its proof.
if _, err := client.RegisterRequestKey(ctx); err != nil {
    log.Fatal(err)
}

// Execute, Attest, AttestClaudeResponse and AttestOpenAIResponse now sign.
run, err := client.Execute(ctx, &verdifax.ExecuteRequest{
    ProgramID:          "1111111111111111111111111111111111111111111111111111111111111111",
    RouteID:            "demo-attestation",
    RegistryRecordHash: "2222222222222222222222222222222222222222222222222222222222222222",
    PayloadText:        "first signed attestation",
})

// Stops requiring signatures on this API key.
err = client.ClearRequestKey(ctx)

Config.SigningKey also accepts the 64 bytes of an ed25519.PrivateKey, converted with verdifax.SigningKey(key).

Registering a key changes that API key for every client that uses it: the server then refuses a run without a valid signature, so every caller on the key needs the private key. Each request carries the time and a fresh random nonce. The server refuses a repeated nonce and a time more than five minutes from its own clock.

The signature shows the holder of the key requested the run. It does not show the key holder accepted the outcome.

Trust model

This SDK only mediates HTTP I/O, it does NOT verify sealed manifests on its own. For offline verification with no Verdifax dependency, use the open-source verdifax-verify CLI, v0.17.2 or later (signed binaries with SLSA provenance on its GitHub Releases), which checks both audit bundles and deny or halt receipts.

License

MIT, see LICENSE.

Documentation

Overview

Package verdifax is the official Go SDK for the Verdifax orchestrator REST API.

Verdifax converts any digital action into a cryptographically sealed, hardware-verified, and legally admissible fact. This SDK wraps the orchestrator's HTTP surface with Go idioms so applications can attest decisions, verify sealed manifests, and fetch audit artifacts without hand-rolling JSON marshalling.

Quickstart 

import (
    "context"
    "fmt"
    "log"

    "github.com/Verdifax/verdifax-sdk-go/verdifax"
)

func main() {
    client, err := verdifax.NewClient(verdifax.Config{
        BaseURL: "https://api.verdifax.com",
        APIKey:  os.Getenv("VERDIFAX_API_KEY"),
    })
    if err != nil {
        log.Fatal(err)
    }

    run, err := client.Execute(context.Background(), &verdifax.ExecuteRequest{
        ProgramID:          "1111111111111111111111111111111111111111111111111111111111111111",
        RouteID:            "demo-attestation",
        RegistryRecordHash: "2222222222222222222222222222222222222222222222222222222222222222",
        PayloadText:        "first attestation",
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("Sealed run %d, manifest hash %s\n", run.RunID, run.Manifest.ManifestHash)
}

Authentication

Every authenticated endpoint expects the API key in the X-Verdifax-Key header. The Client injects it automatically when the Config carries APIKey.

Request signing

Set Config.SigningKey to sign every path to POST /execute with an Ed25519 private key held by the customer. GenerateRequestKey creates a key pair, and RegisterRequestKey and ClearRequestKey manage the public key on the API key.

Error model

Methods return one of three error kinds:

  • *AuthError on missing/invalid API key (HTTP 401)
  • *NotFoundError on missing resources (HTTP 404)
  • *APIError on every other non-2xx response, with the orchestrator's error message in .Message

Trust model

The SDK only mediates HTTP I/O, it does NOT verify sealed manifests on its own. Use the verdifax-pepg-verify CLI (or its Go library form once published) for offline verification.

Index

Constants

View Source 
const (
	DefaultBaseURL = "https://api.verdifax.com"
	// DefaultTimeout outlasts a slow sealed run: two public-log entries
	// and, when AI output is sent, an AI review can take longer than 30
	// seconds, and a client that gave up then reported an error for a run
	// the server went on to seal.
	DefaultTimeout = 90 * time.Second
	UserAgent      = "verdifax-sdk-go/0.3.0"

	// HeaderAPIKey is the canonical header name for API-key auth.
	// Verdifax uses this rather than Authorization: Bearer because
	// keys are not OAuth bearer tokens, they're long-lived
	// orchestrator-scoped secrets that don't fit OAuth's expiry
	// semantics.
	HeaderAPIKey = "X-Verdifax-Key"
)

Default values used by NewClient when not overridden in Config.

View Source 
const DefaultMaxRetries = 3

DefaultMaxRetries is the retry budget applied when Config.MaxRetries is zero. Three retries on top of the original request covers transient blips without amplifying real outages.

View Source 
const DefaultRetryBaseDelay = 200 * time.Millisecond

DefaultRetryBaseDelay is the first inter-retry sleep. Combined with exponential backoff: 200ms → 400ms → 800ms.

Variables

View Source 
var ErrAPIKeyRequired = errors.New("verdifax: APIKey is required for this endpoint")

ErrAPIKeyRequired is returned when an authenticated method is called on a client constructed without an APIKey.

View Source 
var ErrSigningKeyRequired = errors.New("verdifax: Config.SigningKey is required for this method")

ErrSigningKeyRequired is returned by RegisterRequestKey on a client constructed without a SigningKey.

Functions

func FormatProviderPayload 

func FormatProviderPayload(provider, prompt, response string) string

FormatProviderPayload exposes the canonical payload shape used by the AttestClaudeResponse / AttestOpenAIResponse helpers. Useful when callers want to construct the same payload without going through the helper (e.g. attesting via Execute directly).

func ValidateHex64 

func ValidateHex64(value, fieldName string) error

ValidateHex64 returns nil iff value is exactly 64 lowercase hex characters, the §0-canonical SHA-256 encoding the orchestrator expects for program_id, registry_record_hash, manifest_hash, ciphertext_hash, etc. Mirrors the Python SDK's `validate_hex64()` helper for cross-language parity.

func ValidateRouteID 

func ValidateRouteID(value string) error

ValidateRouteID returns nil iff value is a non-empty, printable-ASCII route identifier of bounded length. The orchestrator accepts a wider character set, but the SDK enforces the conservative subset by default to catch typos early.

Types

type APIError 

type APIError struct {
	Status  int
	Path    string
	Message string
}

APIError is returned on every other non-2xx response. Status carries the HTTP code; Path is the endpoint that errored; Message is the orchestrator's error message (when it returned a structured envelope) or the raw response body.

func (*APIError) Error 

func (e *APIError) Error() string

type AdminAPIKey 

type AdminAPIKey struct {
	ID         int64  `json:"id"`
	Name       string `json:"name"`
	CreatedAt  string `json:"created_at"`
	LastUsedAt string `json:"last_used_at,omitempty"`
	RunCount   int64  `json:"run_count"`
	Revoked    bool   `json:"revoked"`
}

AdminAPIKey is the projection returned by AdminListKeys. Secrets are NEVER surfaced, only metadata.

type AdminCreateKeyResponse 

type AdminCreateKeyResponse struct {
	OK     bool   `json:"ok"`
	ID     int64  `json:"id"`
	Name   string `json:"name"`
	Secret string `json:"secret"`
	Hint   string `json:"hint"`
}

AdminCreateKeyResponse is the body returned by POST /admin/keys. Secret is shown ONCE at creation; the orchestrator stores only its hash afterwards.

type AdminEraseRequest 

type AdminEraseRequest struct {
	RunID          int64  `json:"run_id"`
	FieldPath      string `json:"field_path"`
	CiphertextHash Hex64  `json:"ciphertext_hash"`
	DSARReference  string `json:"dsar_reference,omitempty"`
}

AdminEraseRequest is the body shape for AdminErase. CiphertextHash is the SHA-256 hex of the ciphertext that was sealed for the field at encryption time, the caller looks this up in their own records.

type AttestRequest 

type AttestRequest struct {
	// Payload is raw bytes that get base64-encoded internally
	// before posting. Use this for binary inputs (model
	// activation tensors, CBOR blobs, etc.).
	Payload []byte

	// PayloadText is the plain-text variant. The SDK forwards it
	// as-is. Use this for prompts, chat messages, JSON strings.
	PayloadText string

	ProgramID          Hex64
	RouteID            string
	RegistryRecordHash Hex64

	// AIOutputText, when non-empty, opts the request into the
	// AIVP governance pipeline.
	AIOutputText string

	// AttestedContext carries caller-attested actor + decision
	// metadata. Open schema; surfaces in the audit bundle.
	AttestedContext map[string]any
}

AttestRequest is the friendly shape for Attest. Mirrors the Python SDK's `attest()` signature so polyglot teams have parity.

Either Payload or PayloadText must be set, not both. ProgramID, RouteID, and RegistryRecordHash are required.

type AuthError 

type AuthError struct {
	Status  int
	Message string
}

AuthError is returned on HTTP 401 (missing or invalid API key).

func (*AuthError) Error 

func (e *AuthError) Error() string

type Client 

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

Client is the SDK entry point. Safe for concurrent use across goroutines.

func FromEnv 

func FromEnv() (*Client, error)

FromEnv constructs a Client using the canonical Verdifax SDK environment variables. The Python SDK exposes the same factory shape; the variable names are identical so a polyglot deployment can share a single .env file across SDK languages.

Variables consumed: 

VERDIFAX_BASE_URL    base URL (defaults to https://api.verdifax.com)
VERDIFAX_API_KEY     X-Verdifax-Key value (required for authed endpoints)
VERDIFAX_TIMEOUT_MS  per-request timeout in ms (defaults to 90000)
VERDIFAX_USER_AGENT  override the default User-Agent string
VERDIFAX_MAX_RETRIES retry budget for idempotent GETs (defaults to 3)

Returns an error when VERDIFAX_TIMEOUT_MS or VERDIFAX_MAX_RETRIES is set to a non-integer.

func NewClient 

func NewClient(cfg Config) (*Client, error)

NewClient validates the config and returns a Client. Returns an error when the config is missing required fields.

func (*Client) AdminCreateKey 

func (c *Client) AdminCreateKey(ctx context.Context, name string) (*AdminCreateKeyResponse, error)

AdminCreateKey provisions a new API key with the given name. Returns the secret exactly once, store it immediately.

func (*Client) AdminErase 

func (c *Client) AdminErase(ctx context.Context, req *AdminEraseRequest) (*DeletionReceipt, error)

AdminErase issues a CRES key-shred and returns the sealed DeletionReceipt. Auth-gated.

func (*Client) AdminListKeys 

func (c *Client) AdminListKeys(ctx context.Context) ([]AdminAPIKey, error)

AdminListKeys lists every API key in the deployment. Auth-gated.

func (*Client) AdminRevokeKey 

func (c *Client) AdminRevokeKey(ctx context.Context, keyID int64) error

AdminRevokeKey revokes an API key by ID. The key cannot be used for further authenticated requests after this returns.

func (*Client) Attest 

func (c *Client) Attest(ctx context.Context, req *AttestRequest) (*ExecuteResponse, error)

Attest is the high-level convenience wrapper around Execute. Handles base64 encoding for byte payloads, applies basic input validation, and returns the same ExecuteResponse the API surface emits. Recommended for app-level code; use Execute directly when you've already built the canonical request shape.

func (*Client) AttestClaudeResponse 

func (c *Client) AttestClaudeResponse(
	ctx context.Context,
	programID, routeID, registryRecordHash Hex64,
	prompt, response string,
) (*ExecuteResponse, error)

AttestClaudeResponse attests a Claude API response. Provider is hard-coded to "anthropic"; AIOutputText is wired so the orchestrator runs AIVP governance over the response text.

Recommended call shape: 

resp, err := claude.Messages.Create(...)
if err != nil { return err }
run, err := client.AttestClaudeResponse(ctx,
    "system-prompt-program-id", "support-conversation",
    "registry-record-hash", "user prompt that drove this",
    resp.Content[0].Text)

func (*Client) AttestOpenAIResponse 

func (c *Client) AttestOpenAIResponse(
	ctx context.Context,
	programID, routeID, registryRecordHash Hex64,
	prompt, response string,
) (*ExecuteResponse, error)

AttestOpenAIResponse attests an OpenAI API response. Same shape as AttestClaudeResponse but provider is "openai".

func (*Client) ClearRequestKey added in v0.3.0 

func (c *Client) ClearRequestKey(ctx context.Context) error

ClearRequestKey clears the registered public key, so the server stops requiring request signatures on this API key.

func (*Client) DCAEVerify 

func (c *Client) DCAEVerify(ctx context.Context, bundle *DCAEProofBundle) (*DCAEVerdict, error)

DCAEVerify submits a sealed ProofBundle to the orchestrator's stateless DCAE verifier and returns the verdict. No auth required; the endpoint is anonymous so any third party can use it.

func (*Client) DownloadAuditPDF 

func (c *Client) DownloadAuditPDF(ctx context.Context, runID int64, format PDFFormat, w io.Writer) error

DownloadAuditPDF streams the audit PDF bytes for a run. Caller owns the io.Writer (file, buffer, HTTP response). The PDF format defaults to FormatComprehensive when format is empty.

func (*Client) Execute 

func (c *Client) Execute(ctx context.Context, req *ExecuteRequest) (*ExecuteResponse, error)

Execute attests one decision through the orchestrator pipeline. Returns the sealed manifest + run id.

On success: HTTP 200 + an ExecuteResponse with a non-zero RunID. On policy denial (PEPG): HTTP 422 + an *APIError with the deny receipt in .Message; callers can inspect Manifest.PepgOutcome when they retrieve the run later. On budget halt (CCV/MACC): HTTP 422 + an *APIError; the run is still persisted and retrievable via GetRun.

func (*Client) GetAivpT4HaltReceipt 

func (c *Client) GetAivpT4HaltReceipt(ctx context.Context, runID int64) (map[string]any, error)

GetAivpT4HaltReceipt returns the sealed AIVP halt receipt for a run whose AIVP governance returned a non-RELEASE decision. Returns *NotFoundError on RELEASE outcomes.

func (*Client) GetAllowToken 

func (c *Client) GetAllowToken(ctx context.Context, runID int64) (map[string]any, error)

GetAllowToken returns the sealed PEPG AllowToken for an admitted run. Returns *NotFoundError when the run was denied or had no PEPG admission.

func (*Client) GetCCVHaltReceipt 

func (c *Client) GetCCVHaltReceipt(ctx context.Context, runID int64) (map[string]any, error)

GetCCVHaltReceipt returns the sealed CCVHaltReceipt for a run that breached its per-run runtime budget. Returns *NotFoundError for runs that didn't halt under CCV.

func (*Client) GetDenyReceipt 

func (c *Client) GetDenyReceipt(ctx context.Context, runID int64) (map[string]any, error)

GetDenyReceipt returns the sealed PEPG DenyReceipt for a denied run. Returns *NotFoundError when the run was admitted.

func (*Client) GetMACCHaltReceipt 

func (c *Client) GetMACCHaltReceipt(ctx context.Context, runID int64) (map[string]any, error)

GetMACCHaltReceipt returns the sealed MACCHaltReceipt for a run that breached its tenant cumulative budget. Returns *NotFoundError for runs that didn't halt under MACC.

func (*Client) GetRun 

func (c *Client) GetRun(ctx context.Context, runID int64) (*Run, error)

GetRun fetches a single run by its integer ID. Scoped to the authenticated key, returns *NotFoundError when the run was created by a different key (defense-in-depth: no enumeration leak).

func (*Client) Health 

func (c *Client) Health(ctx context.Context) (*Health, error)

Health pings GET /health. No auth required. Use as a liveness probe or to confirm the deployed binary's git SHA matches a known commit.

func (*Client) ListDeletionReceipts 

func (c *Client) ListDeletionReceipts(ctx context.Context, runID int64) ([]DeletionReceipt, error)

ListDeletionReceipts returns every CRES DeletionReceipt bound to a run, ordered by deletion_clock ascending. Empty slice when the run has no receipts.

func (*Client) ListRuns 

func (c *Client) ListRuns(ctx context.Context, params *ListRunsParams) ([]RunSummary, int64, error)

ListRuns fetches a page of runs scoped to the authenticated key. Returns a slice of summary records (without full ManifestJSON) plus the total count for pagination.

func (*Client) RegisterRequestKey added in v0.3.0 

func (c *Client) RegisterRequestKey(ctx context.Context) (*RequestKeyRegistration, error)

RegisterRequestKey registers this client's public key on its API key, with the proof that the client holds the private key. From then on the server refuses a run on this API key without a request signature. Returns ErrSigningKeyRequired without a SigningKey.

func (*Client) VerifyRun 

func (c *Client) VerifyRun(ctx context.Context, runID int64) (*VerifyResponse, error)

VerifyRun re-runs the same inputs through the manifest-hash formula and confirms the result matches the recorded seal. Returns Verified=true iff the recomputed hash matches the stored ManifestHash.

Use this for orchestrator-mediated verification. For offline verification with no Verdifax dependency, use the verdifax-pepg-verify CLI (signed binary distributed via GitHub Releases).

func (*Client) Version 

func (c *Client) Version(ctx context.Context) (*Version, error)

Version returns the deploy attestation surface from GET /version. Includes formula_version (current manifest era), the era table (every era this binary can verify), per-kernel preimage versions, and engine identifiers (DCAE, CRES). No auth required.

type Config 

type Config struct {
	// BaseURL is the orchestrator endpoint. Trailing slash is
	// optional. Defaults to DefaultBaseURL.
	BaseURL string

	// APIKey is the X-Verdifax-Key value. Required for every
	// endpoint except /health, /version, and /dcae/verify.
	APIKey string

	// HTTPClient is the underlying transport. When nil, the SDK
	// constructs an http.Client with Timeout. When set, the SDK
	// uses it as-is and does NOT wrap it with the retry transport
	// (the caller's client is assumed to own retry semantics).
	HTTPClient *http.Client

	// Timeout is the per-request deadline used when HTTPClient
	// is nil. Ignored when HTTPClient is set.
	Timeout time.Duration

	// UserAgent overrides the default User-Agent header. Useful
	// for telemetry attribution when Verdifax serves multiple
	// integrators.
	UserAgent string

	// MaxRetries is the budget for transient-error retries on
	// idempotent GETs. Defaults to DefaultMaxRetries when zero;
	// set negative to disable retries entirely. Only applied
	// when HTTPClient is nil (the SDK builds its own transport
	// stack and wraps it in the retry middleware).
	MaxRetries int

	// RetryBaseDelay is the first inter-retry sleep. The retry
	// transport doubles it on each subsequent retry (exponential
	// backoff with full jitter). Defaults to
	// DefaultRetryBaseDelay.
	RetryBaseDelay time.Duration

	// SigningKey, when set, signs every path to POST /execute with
	// this Ed25519 private key. It is never sent to the server. Leave
	// it nil for unsigned requests. See GenerateRequestKey and
	// RegisterRequestKey.
	SigningKey SigningKey
}

Config configures the Client. APIKey is required for every authenticated endpoint; BaseURL defaults to api.verdifax.com.

HTTPClient is exposed so applications can plug in their own transport (custom round-trippers, retry middleware, telemetry hooks). When unset, the SDK uses a default http.Client with the timeout from Timeout.

type DCAEEngineHint 

type DCAEEngineHint struct {
	AvailableAt   string `json:"available_at"`
	EngineVersion string `json:"engine_version"`
}

DCAEEngineHint surfaces the available DCAE engine version + path for clients that want to pivot to offline DCAE verification.

type DCAEProofBundle 

type DCAEProofBundle struct {
	PreimageVersion           string `json:"preimage_version,omitempty"`
	EnvelopeID                string `json:"envelope_id"`
	EnvelopeHash              Hex64  `json:"envelope_hash"`
	AerHash                   Hex64  `json:"aer_hash"`
	ZkspBindingHash           Hex64  `json:"zksp_binding_hash"`
	FormalVerifierStatus      string `json:"formal_verifier_status"`
	ManifestHash              Hex64  `json:"manifest_hash"`
	CanonicalManifestPreimage string `json:"canonical_manifest_preimage"`
}

DCAEProofBundle is the input shape POST /dcae/verify accepts.

type DCAEVerdict 

type DCAEVerdict struct {
	Verified            bool   `json:"verified"`
	FailureReason       string `json:"failure_reason,omitempty"`
	VerifiedClosureHash Hex64  `json:"verified_closure_hash,omitempty"`
	EngineVersion       string `json:"engine_version"`
}

DCAEVerdict is the output shape /dcae/verify returns.

type DeletionReceipt 

type DeletionReceipt struct {
	PreimageVersion       string `json:"preimage_version"`
	EnvelopeID            string `json:"envelope_id"`
	FieldPath             string `json:"field_path"`
	DeletionClock         string `json:"deletion_clock"`
	ActorID               string `json:"actor_id"`
	CiphertextHashAtShred Hex64  `json:"ciphertext_hash_at_shred"`
	DSARReference         string `json:"dsar_reference,omitempty"`
	EngineVersion         string `json:"engine_version"`
	ReceiptHash           Hex64  `json:"receipt_hash"`
	ID                    int64  `json:"id,omitempty"`
}

DeletionReceipt mirrors the orchestrator's CRES DeletionReceipt shape. JSON tags use lowercase_snake_case to match the API's /admin/erase + /runs/{id}/deletion-receipts response shape.

type ExecuteRequest 

type ExecuteRequest struct {
	Payload            string `json:"payload,omitempty"`
	PayloadText        string `json:"payload_text,omitempty"`
	ProgramID          Hex64  `json:"program_id"`
	RouteID            string `json:"route_id"`
	RegistryRecordHash Hex64  `json:"registry_record_hash"`

	// AIOutputText, when non-empty, opts the request into the
	// AIVP governance pipeline. The orchestrator runs AIVP
	// governance over this text and binds the resulting PIA hash
	// into the manifest.
	AIOutputText string `json:"ai_output_text,omitempty"`

	// AttestedContext carries caller-attested actor + decision
	// metadata. Schema is open, any JSON-serializable structure
	// the caller wants surfaced in the audit bundle.
	AttestedContext map[string]any `json:"attested_context,omitempty"`

	// RequestSignature is filled in on a copy of this request when
	// the client has a SigningKey.
	RequestSignature *RequestSignature `json:"request_signature,omitempty"`
}

ExecuteRequest is the body for POST /execute. ProgramID, RouteID, and RegistryRecordHash are required; either Payload (base64 bytes) or PayloadText (plain text) must be set, not both. Other fields are optional.

type ExecuteResponse 

type ExecuteResponse struct {
	OK         bool              `json:"ok"`
	RunID      int64             `json:"run_id"`
	Manifest   ExecutionManifest `json:"manifest"`
	DurationMS int64             `json:"duration_ms"`
}

ExecuteResponse is the body returned by POST /execute on a successful pipeline pass.

type ExecutionManifest 

type ExecutionManifest struct {
	EnvelopeID              string `json:"EnvelopeID"`
	EnvelopeHash            Hex64  `json:"EnvelopeHash"`
	ManifestHash            Hex64  `json:"ManifestHash"`
	DseCommitmentHash       Hex64  `json:"DseCommitmentHash,omitempty"`
	TokOrderingHash         Hex64  `json:"TokOrderingHash,omitempty"`
	DscFinalStateHash       Hex64  `json:"DscFinalStateHash,omitempty"`
	NrepActorID             string `json:"NrepActorID,omitempty"`
	NrepActorPublicKey      string `json:"NrepActorPublicKey,omitempty"`
	NrepSignature           string `json:"NrepSignature,omitempty"`
	AivpOutcome             string `json:"AivpOutcome,omitempty"`
	AivpPiaHash             Hex64  `json:"AivpPiaHash,omitempty"`
	AivpAdapterID           string `json:"AivpAdapterID,omitempty"`
	AivpDecision            string `json:"AivpDecision,omitempty"`
	EraseStatus             string `json:"EraseStatus,omitempty"`
	ExecutionRegion         string `json:"ExecutionRegion,omitempty"`
	FormalVerifierStatus    string `json:"FormalVerifierStatus,omitempty"`
	HardwareAttestationHash Hex64  `json:"HardwareAttestationHash,omitempty"`
	LedgerBackend           string `json:"LedgerBackend,omitempty"`
	LedgerLeafHash          Hex64  `json:"LedgerLeafHash,omitempty"`
	LedgerProofHash         Hex64  `json:"LedgerProofHash,omitempty"`
	LogEntryID              string `json:"LogEntryID,omitempty"`
}

ExecutionManifest is the sealed manifest. Every field contributes to the ManifestHash. Subset of the canonical fields , see the orchestrator's internal/pipeline/types.go for the full struct.

Field tags use the Go default (CapitalCamelCase) because that's what the orchestrator emits. SDK consumers reading these fields in idiomatic Go style should adopt their own snake_case mapping at the application layer if needed.

type FormulaEra 

type FormulaEra struct {
	Era   string `json:"era"`
	Label string `json:"label"`
}

FormulaEra describes one verifiable manifest era.

type Health 

type Health struct {
	OK                  bool   `json:"ok"`
	Service             string `json:"service"`
	Version             string `json:"version"`
	OrchestratorVersion string `json:"orchestrator_version,omitempty"`
	OrchestratorGitSHA  string `json:"orchestrator_git_sha,omitempty"`
	Time                string `json:"time"`
}

Health is the response shape for GET /health.

type Hex64 

type Hex64 = string

Hex64 is a 64-character lowercase hex string, the canonical §0 SHA-256 encoding. Provided as a type alias so signatures document intent without forcing strict newtypes on callers.

type ListRunsParams 

type ListRunsParams struct {
	Limit  int
	Offset int
}

ListRunsParams shapes the optional filters for ListRuns. Zero- value fields are omitted from the query string so the orchestrator applies its defaults.

type NotFoundError 

type NotFoundError struct {
	Path    string
	Message string
}

NotFoundError is returned on HTTP 404. Path is the endpoint that 404'd; Message is the orchestrator's response body when it's a JSON error envelope, otherwise the raw bytes.

func (*NotFoundError) Error 

func (e *NotFoundError) Error() string

type PDFFormat 

type PDFFormat string

PDFFormat selects which audit-PDF variant to render. Defaults to FormatComprehensive when unset. 

const (
	FormatBrief         PDFFormat = "brief"
	FormatAuditor       PDFFormat = "auditor"
	FormatLegal         PDFFormat = "legal"
	FormatComprehensive PDFFormat = "comprehensive"
)

type ProviderResponse 

type ProviderResponse struct {
	// Text is the plain string the provider returned. For
	// chat-completion APIs this is the .choices[0].message.content
	// field on OpenAI, the .content field on Anthropic, etc.
	Text string

	// JSON is the structured payload the provider returned, used
	// for tool-use / function-call results. SDK marshals it to a
	// canonical JSON string before sending.
	JSON any
}

ProviderResponse is the canonical shape AttestProviderResponse builds from. Either Text (for plain-text completions) or JSON (for tool-use / function-call payloads) must be set.

type RequestKeyRegistration added in v0.3.0 

type RequestKeyRegistration struct {
	OK        bool   `json:"ok"`
	PublicKey string `json:"public_key"`
}

RequestKeyRegistration is the body returned by RegisterRequestKey.

type RequestSignature added in v0.3.0 

type RequestSignature struct {
	// Signature is the base64 Ed25519 signature.
	Signature string `json:"signature"`

	// SignedAt is RFC 3339 UTC with whole seconds.
	SignedAt string `json:"signed_at"`

	// Nonce is 16 random bytes as 32 lowercase hex characters, fresh
	// per request.
	Nonce string `json:"nonce"`
}

RequestSignature is the request_signature block of an execute request. The public key comes from the registration, never from the request.

type Run 

type Run struct {
	OK           bool              `json:"ok"`
	ID           int64             `json:"id"`
	CreatedAt    string            `json:"created_at"`
	PayloadHash  Hex64             `json:"payload_hash"`
	ProgramID    Hex64             `json:"program_id"`
	RouteID      string            `json:"route_id"`
	ManifestHash Hex64             `json:"manifest_hash"`
	DurationMS   int64             `json:"duration_ms"`
	Status       string            `json:"status"`
	ErrorStage   string            `json:"error_stage,omitempty"`
	ErrorMessage string            `json:"error_message,omitempty"`
	Manifest     ExecutionManifest `json:"manifest"`
}

Run is the response shape for GET /runs/{id}. Carries the sealed manifest plus run-level metadata.

type RunSummary 

type RunSummary struct {
	ID           int64  `json:"id"`
	CreatedAt    string `json:"created_at"`
	ProgramID    Hex64  `json:"program_id"`
	RouteID      string `json:"route_id"`
	ManifestHash Hex64  `json:"manifest_hash"`
	Status       string `json:"status"`
	OutcomeKind  string `json:"outcome_kind,omitempty"`
}

RunSummary is the lightweight projection used in /runs and /runs/search responses. Excludes the heavy ManifestJSON; call GetRun for the full sealed manifest.

type SigningKey added in v0.3.0 

type SigningKey []byte

SigningKey holds an Ed25519 private key: the 32 raw bytes, which is the form the Node, Python and R SDKs use, or the 64 bytes of an ed25519.PrivateKey. It prints and marshals as [REDACTED], so a logged Config does not show the key.

func GenerateRequestKey added in v0.3.0 

func GenerateRequestKey() (ed25519.PublicKey, SigningKey, error)

GenerateRequestKey creates a new Ed25519 key pair on this machine, as raw bytes: a 32-byte public key and a 32-byte private key. Nothing is sent to the server. Store the private key as a secret.

func (SigningKey) Format added in v0.3.0 

func (SigningKey) Format(f fmt.State, _ rune)

Format writes [REDACTED] for every fmt verb.

func (SigningKey) MarshalJSON added in v0.3.0 

func (SigningKey) MarshalJSON() ([]byte, error)

MarshalJSON writes "[REDACTED]".

type VerifyResponse 

type VerifyResponse struct {
	OK               bool            `json:"ok"`
	Verified         bool            `json:"verified"`
	ManifestHash     Hex64           `json:"manifest_hash"`
	RecomputedHash   Hex64           `json:"recomputed_hash"`
	FormulaVersion   string          `json:"formula_version"`
	VerificationAt   string          `json:"verification_at"`
	VerificationKind string          `json:"verification_kind"`
	DCAEEngineHint   *DCAEEngineHint `json:"dcae_engine_hint,omitempty"`
}

VerifyResponse is the response shape for GET /runs/{id}/verify.

type Version 

type Version struct {
	Service             string            `json:"service"`
	APIContractVersion  string            `json:"api_contract_version,omitempty"`
	OrchestratorVersion string            `json:"orchestrator_version,omitempty"`
	OrchestratorGitSHA  string            `json:"orchestrator_git_sha,omitempty"`
	FormulaVersion      string            `json:"formula_version,omitempty"`
	FormulaEras         []FormulaEra      `json:"formula_eras,omitempty"`
	KernelVersions      map[string]string `json:"kernel_versions,omitempty"`
	EngineVersions      map[string]string `json:"engine_versions,omitempty"`
	AivpT4Mode          string            `json:"aivp_t4_mode,omitempty"`
	Region              string            `json:"region,omitempty"`
	Instance            string            `json:"instance,omitempty"`
	Time                string            `json:"time"`
}

Version is the response shape for GET /version. Surfaces deploy attestation: which binary, which formula era, which kernels.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.