aeo

README

aeo-sdk-go

Go SDK for the AEO Protocol v0.1 — parse, build, validate, and fetch AEO declaration documents. Zero non-stdlib dependencies.

Install

go get github.com/mizcausevic-dev/aeo-sdk-go

Quickstart

package main

import (
    "context"
    "fmt"
    "log"

    aeo "github.com/mizcausevic-dev/aeo-sdk-go"
)

func main() {
    // Fetch and parse from a live well-known URL
    doc, err := aeo.FetchWellKnown("https://mizcausevic-dev.github.io")
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(doc.Entity.Name)                              // "Miz Causevic"
    fmt.Println(doc.ClaimIDs())                               // [current-role location ...]
    fmt.Println(doc.FindClaim("years-experience").Value)      // 30

    // Parse from bytes
    doc2, _ := aeo.ParseDocumentString(`{"aeo_version":"0.1", ...}`)

    // Custom HTTP client with context
    ctx := context.Background()
    client := aeo.DefaultClient()
    _, _ = client.FetchWellKnown(ctx, "https://example.com")

    _ = doc2
}

What it does

• Parse — ParseDocument(bytes), ParseDocumentString(s), LoadDocument(path) — all use json.DisallowUnknownFields for strict conformance
• Build — Document, Entity, Authority, Claim, Verification, CitationPreferences, AnswerConstraints, Audit are all exported struct types with proper JSON tags
• Serialize — doc.Marshal() returns pretty-printed JSON
• Fetch — aeo.FetchWellKnown(origin) does HTTP discovery against /.well-known/aeo.json with Accept: application/aeo+json, application/json. Custom Client lets you bring your own *http.Client and pass a context.Context.
• Query — doc.ClaimIDs() and doc.FindClaim(id) helpers

Conformance

Supports the AEO Protocol at conformance Level 1 (Declare). Signature verification (L2) and audit-endpoint posting (L3) deferred to v0.2.

Dependencies

None. Uses only the standard library: encoding/json, net/http, context, io.

Development

go vet ./...
go test -race -v ./...
go build ./...

Specification

Full spec at github.com/mizcausevic-dev/aeo-protocol-spec.

License

MIT-licensed. Free for commercial and non-commercial use with attribution. The AEO Protocol specification this SDK implements is also MIT (see aeo-protocol-spec).

Kinetic Gain Protocol Suite

Spec	Implementation
AEO Protocol	aeo-sdk-python · aeo-sdk-typescript · aeo-sdk-rust · aeo-sdk-go (this) · aeo-cli · aeo-crawler
Prompt Provenance	—
Agent Cards	—
AI Evidence Format	—
MCP Tool Cards	—

---

Connect: LinkedIn · Kinetic Gain · Medium · Skills

Documentation

Overview

Package aeo provides parse, build, and serialization support for AEO Protocol v0.1 declaration documents.

Specification: https://github.com/mizcausevic-dev/aeo-protocol-spec

Index

• Constants
• func IsHTTPStatusError(err error) bool
• func WellKnownURL(origin string) string
• type AnswerConstraints
• type Audit
• type AuditMode
• type Authority
• type CitationPreferences
• type Claim
• type Client
  • func DefaultClient() *Client
  • func (c *Client) FetchWellKnown(ctx context.Context, origin string) (*Document, error)
• type Confidence
• type Document
  • func FetchWellKnown(origin string) (*Document, error)
  • func LoadDocument(path string) (*Document, error)
  • func ParseDocument(raw []byte) (*Document, error)
  • func ParseDocumentString(raw string) (*Document, error)
  • func (d *Document) ClaimIDs() []string
  • func (d *Document) FindClaim(id string) *Claim
  • func (d *Document) Marshal() ([]byte, error)
• type Entity
• type EntityType
• type HTTPStatusError
  • func (e *HTTPStatusError) Error() string
• type Verification
• type VerificationType

Constants

const AcceptHeader = "application/aeo+json, application/json"

AcceptHeader is the value the SDK sends in the HTTP Accept header.

const DefaultTimeout = 10 * time.Second

DefaultTimeout is the HTTP timeout used by the default client.

const ProtocolVersion = "0.1"

ProtocolVersion is the AEO Protocol version this SDK targets.

const SDKVersion = "0.1.0"

SDKVersion is the version of this SDK module.

const WellKnownPath = "/.well-known/aeo.json"

WellKnownPath is the canonical well-known URL path for AEO declarations.

Functions

func IsHTTPStatusError

func IsHTTPStatusError(err error) bool

IsHTTPStatusError reports whether the error is an HTTPStatusError.

func WellKnownURL

func WellKnownURL(origin string) string

WellKnownURL returns the canonical well-known URL for the given origin. Trailing slashes on the origin are stripped before appending the path.

Types

type AnswerConstraints

type AnswerConstraints struct {
	MustInclude         []string `json:"must_include,omitempty"`
	MustNotInclude      []string `json:"must_not_include,omitempty"`
	FreshnessWindowDays int      `json:"freshness_window_days,omitempty"`
}

AnswerConstraints expresses soft constraints for answer engines.

type Audit

type Audit struct {
	Mode           AuditMode `json:"mode"`
	SigningKeyURI  string    `json:"signing_key_uri,omitempty"`
	Signature      string    `json:"signature,omitempty"`
	EndpointURI    string    `json:"endpoint_uri,omitempty"`
	EndpointSchema string    `json:"endpoint_schema,omitempty"`
}

Audit configures the audit surface for the declaration.

type AuditMode

type AuditMode string

AuditMode enumerates the document audit modes.

const (
	AuditNone      AuditMode = "none"
	AuditSignature AuditMode = "signature"
	AuditEndpoint  AuditMode = "endpoint"
)

Permitted AuditMode values.

type Authority

type Authority struct {
	PrimarySources []string       `json:"primary_sources"`
	EvidenceLinks  []string       `json:"evidence_links,omitempty"`
	Verifications  []Verification `json:"verifications,omitempty"`
}

Authority captures what the entity considers authoritative about itself.

type CitationPreferences

type CitationPreferences struct {
	PreferredAttribution string   `json:"preferred_attribution,omitempty"`
	CanonicalLinks       []string `json:"canonical_links,omitempty"`
	DoNotCite            []string `json:"do_not_cite,omitempty"`
}

CitationPreferences expresses how the entity prefers to be cited.

type Claim

type Claim struct {
	ID         string      `json:"id"`
	Predicate  string      `json:"predicate"`
	Value      interface{} `json:"value"`
	Evidence   []string    `json:"evidence,omitempty"`
	ValidFrom  string      `json:"valid_from,omitempty"`
	ValidUntil *string     `json:"valid_until,omitempty"`
	Confidence Confidence  `json:"confidence,omitempty"`
}

Claim is a single asserted fact about the entity.

type Client

type Client struct {
	HTTPClient *http.Client
}

Client is a configurable HTTP fetcher for AEO declarations.

func DefaultClient

func DefaultClient() *Client

DefaultClient returns a Client with a sensible default timeout.

func (*Client) FetchWellKnown

func (c *Client) FetchWellKnown(ctx context.Context, origin string) (*Document, error)

FetchWellKnown fetches and parses the AEO declaration at origin's well-known URL using this client.

type Confidence

type Confidence string

Confidence enumerates a claim's confidence level.

const (
	ConfidenceHigh   Confidence = "high"
	ConfidenceMedium Confidence = "medium"
	ConfidenceLow    Confidence = "low"
)

Permitted Confidence values.

type Document

type Document struct {
	AEOVersion          string               `json:"aeo_version"`
	Entity              Entity               `json:"entity"`
	Authority           Authority            `json:"authority"`
	Claims              []Claim              `json:"claims"`
	CitationPreferences *CitationPreferences `json:"citation_preferences,omitempty"`
	AnswerConstraints   *AnswerConstraints   `json:"answer_constraints,omitempty"`
	Audit               *Audit               `json:"audit,omitempty"`
}

Document is a complete AEO Protocol v0.1 declaration document.

func FetchWellKnown

func FetchWellKnown(origin string) (*Document, error)

FetchWellKnown fetches and parses the AEO declaration at origin's well-known URL using the package-level default client.

func LoadDocument

func LoadDocument(path string) (*Document, error)

LoadDocument reads and parses a document from a file path.

func ParseDocument

func ParseDocument(raw []byte) (*Document, error)

ParseDocument parses a byte slice into a Document. It rejects unknown top-level fields and unknown fields anywhere in the structure.

func ParseDocumentString

func ParseDocumentString(raw string) (*Document, error)

ParseDocumentString is a convenience wrapper around ParseDocument.

func (*Document) ClaimIDs

func (d *Document) ClaimIDs() []string

ClaimIDs returns the IDs of all claims in the document.

func (*Document) FindClaim

func (d *Document) FindClaim(id string) *Claim

FindClaim returns a pointer to the claim with the given ID, or nil.

func (*Document) Marshal

func (d *Document) Marshal() ([]byte, error)

Marshal serializes the document to pretty-printed JSON.

type Entity

type Entity struct {
	ID           string     `json:"id"`
	Type         EntityType `json:"type"`
	Name         string     `json:"name"`
	Aliases      []string   `json:"aliases,omitempty"`
	CanonicalURL string     `json:"canonical_url"`
}

Entity is the subject of an AEO declaration.

type EntityType

type EntityType string

EntityType enumerates the entity kinds the AEO Protocol defines.

const (
	EntityPerson       EntityType = "Person"
	EntityOrganization EntityType = "Organization"
	EntityProduct      EntityType = "Product"
	EntityPlace        EntityType = "Place"
	EntityConcept      EntityType = "Concept"
)

Permitted EntityType values.

type HTTPStatusError

type HTTPStatusError struct {
	Status int
	URL    string
}

HTTPStatusError is returned when an origin responds with a non-2xx status.

func (*HTTPStatusError) Error

func (e *HTTPStatusError) Error() string

Error implements the error interface.

type Verification

type Verification struct {
	Type     VerificationType `json:"type"`
	Value    string           `json:"value"`
	ProofURI string           `json:"proof_uri,omitempty"`
}

Verification is a proof of ownership or control over an identifier.

type VerificationType

type VerificationType string

VerificationType enumerates the verification mechanisms an authority block can declare.

const (
	VerificationDomain       VerificationType = "domain"
	VerificationDNS          VerificationType = "dns"
	VerificationGitHub       VerificationType = "github"
	VerificationLinkedIn     VerificationType = "linkedin"
	VerificationGPG          VerificationType = "gpg"
	VerificationWellKnownURI VerificationType = "well-known-uri"
)

Permitted VerificationType values.