API Reference¶

Complete reference for the aims package.

SPIFFE ID¶

Types¶

SPIFFEID¶

type SPIFFEID struct {
    TrustDomain string  // e.g., "example.com"
    Path        string  // e.g., "/agent/calendar-bot"
}

Functions¶

ParseSPIFFEID¶

func ParseSPIFFEID(uri string) (*SPIFFEID, error)

Parses a SPIFFE ID string into its components.

MustParseSPIFFEID¶

func MustParseSPIFFEID(uri string) *SPIFFEID

Parses a SPIFFE ID string, panicking on error. Use for constants.

NewSPIFFEID¶

func NewSPIFFEID(trustDomain, path string) (*SPIFFEID, error)

Creates a SPIFFE ID from trust domain and path components.

Methods¶

String¶

func (s *SPIFFEID) String() string

Returns the SPIFFE ID as a URI string.

URI¶

func (s *SPIFFEID) URI() *url.URL

Returns the SPIFFE ID as a *url.URL.

IsAgent / IsWorkload / IsService / IsUser¶

func (s *SPIFFEID) IsAgent() bool
func (s *SPIFFEID) IsWorkload() bool
func (s *SPIFFEID) IsService() bool
func (s *SPIFFEID) IsUser() bool

Returns true if the path indicates the identity type.

Name¶

func (s *SPIFFEID) Name() string

Returns the final component of the path (workload name).

Equal¶

func (s *SPIFFEID) Equal(other *SPIFFEID) bool

Returns true if two SPIFFE IDs are equal.

InTrustDomain¶

func (s *SPIFFEID) InTrustDomain(domain string) bool

Returns true if this SPIFFE ID belongs to the given trust domain.

Constants¶

const SPIFFEScheme = "spiffe"

const (
    PathPrefixAgent    = "/agent/"
    PathPrefixWorkload = "/workload/"
    PathPrefixService  = "/service/"
    PathPrefixUser     = "/user/"
)

Workload Identity Token (WIT)¶

Types¶

WorkloadIdentityToken¶

type WorkloadIdentityToken struct {
    Issuer    string    `json:"iss"`    // Trust domain issuer
    Subject   string    `json:"sub"`    // SPIFFE ID
    Audience  []string  `json:"aud"`    // Intended recipients
    Expiry    time.Time `json:"exp"`
    IssuedAt  time.Time `json:"iat"`
    NotBefore time.Time `json:"nbf,omitempty"`
    JWTID     string    `json:"jti,omitempty"`
    CNF       *CNF      `json:"cnf,omitempty"`  // Confirmation key
}

CNF¶

type CNF struct {
    JWK json.RawMessage `json:"jwk,omitempty"`     // Embedded JWK
    Kid string          `json:"kid,omitempty"`     // Key ID reference
    X5T string          `json:"x5t#S256,omitempty"` // X.509 thumbprint
}

Functions¶

NewWIT¶

func NewWIT(spiffeID *SPIFFEID, audience []string, ttl time.Duration, opts ...WITOption) *WorkloadIdentityToken

Creates a new Workload Identity Token.

GenerateJTI¶

func GenerateJTI() string

Generates a random JWT ID.

WITOption Functions¶

func WithWITJTI(jti string) WITOption
func WithWITNotBefore(nbf time.Time) WITOption
func WithWITCNF(cnf *CNF) WITOption

Methods¶

Sign¶

func (w *WorkloadIdentityToken) Sign(signer crypto.Signer, keyID string) (string, error)

Creates a signed JWT string from this WIT.

Validate¶

func (w *WorkloadIdentityToken) Validate() error

Checks if the WIT has all required fields and is temporally valid.

SPIFFEID¶

func (w *WorkloadIdentityToken) SPIFFEID() (*SPIFFEID, error)

Returns the SPIFFE ID from the subject claim.

IsExpired¶

func (w *WorkloadIdentityToken) IsExpired() bool

Returns true if the token has expired.

TimeToExpiry¶

func (w *WorkloadIdentityToken) TimeToExpiry() time.Duration

Returns the duration until this token expires.

WIMSE Proof Token (WPT)¶

Types¶

WIMSEProofToken¶

type WIMSEProofToken struct {
    Issuer   string    `json:"iss"`   // Must match WIT subject
    Audience string    `json:"aud"`   // Target service
    IssuedAt time.Time `json:"iat"`
    Expiry   time.Time `json:"exp,omitempty"`
    JWTID    string    `json:"jti,omitempty"`
    Nonce    string    `json:"nonce,omitempty"`
    HTM      string    `json:"htm"`   // HTTP method
    HTU      string    `json:"htu"`   // HTTP URI
    ATH      string    `json:"ath,omitempty"` // Access token hash
}

Constants¶

const (
    HeaderWPT  = "Workload-Identity-Token"
    HeaderDPoP = "DPoP"
)

Functions¶

NewWPT¶

func NewWPT(issuer, audience, method, uri string, opts ...WPTOption) *WIMSEProofToken

Creates a new WIMSE Proof Token for an HTTP request.

NewWPTFromWIT¶

func NewWPTFromWIT(wit *WorkloadIdentityToken, audience, method, uri string, opts ...WPTOption) *WIMSEProofToken

Creates a WPT bound to a WIT.

NewWPTForRequest¶

func NewWPTForRequest(issuer, audience string, r *http.Request, opts ...WPTOption) *WIMSEProofToken

Creates a WPT bound to an http.Request.

WPTFromHeader¶

func WPTFromHeader(r *http.Request) string

Extracts a WPT JWT from an HTTP header.

WPTOption Functions¶

func WithWPTNonce(nonce string) WPTOption
func WithWPTJTI(jti string) WPTOption
func WithWPTExpiry(exp time.Time) WPTOption
func WithWPTAccessToken(accessToken string) WPTOption

Methods¶

Sign¶

func (p *WIMSEProofToken) Sign(signer crypto.Signer, keyID string) (string, error)

Creates a signed JWT string from this WPT.

BindToRequest¶

func (p *WIMSEProofToken) BindToRequest(r *http.Request, signer crypto.Signer, keyID string) error

Adds the WPT to an HTTP request header.

Validate¶

func (p *WIMSEProofToken) Validate() error

Checks if the WPT has all required fields.

MatchesRequest¶

func (p *WIMSEProofToken) MatchesRequest(r *http.Request) bool

Checks if this WPT matches the given HTTP request.

IsExpired¶

func (p *WIMSEProofToken) IsExpired() bool

Returns true if the proof token has expired.

Credentials¶

Interfaces¶

Credential¶

type Credential interface {
    Type() CredentialType
    SPIFFEID() *SPIFFEID
    IsExpired() bool
    ExpiresAt() time.Time
}

Types¶

CredentialType¶

type CredentialType string

const (
    CredentialX509SVID CredentialType = "x509-svid"
    CredentialJWTSVID  CredentialType = "jwt-svid"
    CredentialWIT      CredentialType = "wit"
)

X509SVID¶

type X509SVID struct {
    Certificates []*x509.Certificate
    PrivateKey   crypto.PrivateKey
}

X.509 SPIFFE Verifiable Identity Document for mTLS authentication.

JWTSVID¶

type JWTSVID struct {
    Token string
}

JWT-based SPIFFE Verifiable Identity Document.

Functions¶

NewX509SVID¶

func NewX509SVID(certs []*x509.Certificate, key crypto.PrivateKey) (*X509SVID, error)

Creates an X509SVID from a certificate chain and private key.

NewJWTSVID¶

func NewJWTSVID(token string, spiffeID *SPIFFEID, expiry time.Time) *JWTSVID

Creates a JWTSVID from its components.

X509SVID Methods¶

LeafCertificate¶

func (s *X509SVID) LeafCertificate() *x509.Certificate

Returns the leaf (end-entity) certificate.

Agent Identity¶

Types¶

AgentIdentity¶

type AgentIdentity struct {
    SPIFFEID    *SPIFFEID
    Credential  Credential
    Attestation *Attestation
    Metadata    map[string]string
    CreatedAt   time.Time
}

Represents a fully-attested agent identity.

Functions¶

NewAgentIdentity¶

func NewAgentIdentity(spiffeID *SPIFFEID, cred Credential, opts ...IdentityOption) *AgentIdentity

Creates an agent identity from a SPIFFE ID and credential.

IdentityOption Functions¶

func WithAttestation(att *Attestation) IdentityOption
func WithMetadata(key, value string) IdentityOption

Methods¶

IsValid¶

func (ai *AgentIdentity) IsValid() bool

Checks if the identity is currently valid.

ExpiresAt¶

func (ai *AgentIdentity) ExpiresAt() time.Time

Returns when this identity expires.

TimeToExpiry¶

func (ai *AgentIdentity) TimeToExpiry() time.Duration

Returns the duration until this identity expires.

Attestation¶

Types¶

AttestationType¶

type AttestationType string

const (
    AttestationTPM        AttestationType = "tpm"
    AttestationSGX        AttestationType = "sgx"
    AttestationSEVSNP     AttestationType = "sev-snp"
    AttestationTDX        AttestationType = "tdx"
    AttestationKubernetes AttestationType = "kubernetes"
    AttestationAWS        AttestationType = "aws"
    AttestationGCP        AttestationType = "gcp"
    AttestationAzure      AttestationType = "azure"
    AttestationGitHub     AttestationType = "github"
    AttestationUnix       AttestationType = "unix"
    AttestationDocker     AttestationType = "docker"
)

Attestation¶

type Attestation struct {
    Type       AttestationType
    Evidence   []byte
    Timestamp  time.Time
    Attributes map[string]string
}

Functions¶

NewAttestation¶

func NewAttestation(attestType AttestationType, evidence []byte) *Attestation

Creates a new attestation with the given type and evidence.

NewAttestationWithOptions¶

func NewAttestationWithOptions(attestType AttestationType, evidence []byte, opts ...AttestationOption) *Attestation

Creates an attestation with options.

AttestationOption Functions¶

func WithAttestationTimestamp(t time.Time) AttestationOption
func WithAttribute(key, value string) AttestationOption

Methods¶

Age¶

func (a *Attestation) Age() time.Duration

Returns how old the attestation is.

IsFresh¶

func (a *Attestation) IsFresh(maxAge time.Duration) bool

Returns true if the attestation is younger than the given duration.

GetAttribute¶

func (a *Attestation) GetAttribute(key string) (string, bool)

Returns an attestation attribute value.

AttestationType Methods¶

Description¶

func (at AttestationType) Description() string

Returns a human-readable description.

IsHardware¶

func (at AttestationType) IsHardware() bool

Returns true for hardware-based attestation (TPM, SGX, SEV-SNP, TDX).

IsCloud¶

func (at AttestationType) IsCloud() bool

Returns true for cloud provider attestation (AWS, GCP, Azure).

Attribute Keys¶

const (
    AttrInstanceID     = "instance-id"
    AttrRegion         = "region"
    AttrAccountID      = "account-id"
    AttrNamespace      = "namespace"
    AttrServiceAccount = "service-account"
    AttrPodName        = "pod-name"
    AttrContainerID    = "container-id"
    AttrImageDigest    = "image-digest"
    AttrPCR0           = "pcr0"
    AttrMRENCLAVE      = "mrenclave"
    AttrMRSIGNER       = "mrsigner"
)

AIMS Layers¶

Types¶

Layer¶

type Layer int

const (
    LayerIdentifiers    Layer = iota + 1
    LayerCredentials
    LayerAttestation
    LayerProvisioning
    LayerAuthentication
    LayerAuthorization
    LayerMonitoring
    LayerPolicy
    LayerCompliance
)

Functions¶

AllLayers¶

func AllLayers() []Layer

Returns all 9 AIMS layers in order.

Methods¶

String¶

func (l Layer) String() string

Returns the human-readable name of the layer.

Description¶

func (l Layer) Description() string

Returns a brief description of the layer's purpose.

Errors¶

var (
    // SPIFFE ID errors
    ErrInvalidSPIFFEID        error
    ErrEmptyTrustDomain       error
    ErrInvalidScheme          error
    ErrPathContainsQuery      error
    ErrPathContainsFragment   error
    ErrTrustDomainHasPort     error
    ErrTrustDomainHasUserInfo error

    // WIT errors
    ErrWITMissingSubject  error
    ErrWITMissingIssuer   error
    ErrWITMissingAudience error
    ErrWITExpired         error
    ErrWITNotYetValid     error

    // WPT errors
    ErrWPTMissingIssuer   error
    ErrWPTMissingAudience error
    ErrWPTMissingHTM      error
    ErrWPTMissingHTU      error
    ErrWPTExpired         error
)