# internal/core/trust

Package trust reads, validates and writes .scafld/trusted-keys.json, the allowlist of Ed25519 public keys that receipt signatures are checked against, revoked keys included.

## TrustedKeysVersion

```go
const (
	// TrustedKeysVersion is the current .scafld/trusted-keys.json schema version.
	TrustedKeysVersion = 1
	// AlgorithmEd25519 is the only signing algorithm supported by receipt keys.
	AlgorithmEd25519 = "ed25519"
)
```

## AlgorithmEd25519

```go
const (
	// TrustedKeysVersion is the current .scafld/trusted-keys.json schema version.
	TrustedKeysVersion = 1
	// AlgorithmEd25519 is the only signing algorithm supported by receipt keys.
	AlgorithmEd25519 = "ed25519"
)
```

## KeyIDFromRawEd25519PublicKey

```go
func KeyIDFromRawEd25519PublicKey(raw []byte) (string, error)
```

KeyIDFromRawEd25519PublicKey returns the stable receipt key id for a raw public key.

## MarshalTrustedKeys

```go
func MarshalTrustedKeys(keys TrustedKeys) ([]byte, error)
```

MarshalTrustedKeys validates and marshals trusted keys with deterministic key order.

## ParseTrustedKeys

```go
func ParseTrustedKeys(data []byte) (TrustedKeys, error)
```

ParseTrustedKeys parses and validates a trusted-key allowlist.

## KeyLifecycleSummary

```go
type KeyLifecycleSummary struct {
	Active  int
	Revoked int
	Expired int
}
```

KeyLifecycleSummary counts trusted-key states at one point in time.

- `Active: int`: 
- `Revoked: int`: 
- `Expired: int`: 

## TrustedKey

```go
type TrustedKey struct {
	KeyID     string `json:"key_id"`
	Alg       string `json:"alg"`
	PublicKey string `json:"public_key"`
	Revoked   bool   `json:"revoked,omitempty"`
	RevokedAt string `json:"revoked_at,omitempty"`
	ExpiresAt string `json:"expires_at,omitempty"`
}
```

TrustedKey is one raw Ed25519 public key allowlist entry.

- `KeyID: string` (json:"key_id"): 
- `Alg: string` (json:"alg"): 
- `PublicKey: string` (json:"public_key"): 
- `Revoked: bool` (json:"revoked,omitempty"): 
- `RevokedAt: string` (json:"revoked_at,omitempty"): 
- `ExpiresAt: string` (json:"expires_at,omitempty"): 

## LifecycleStateAt

```go
func (key TrustedKey) LifecycleStateAt(at time.Time) (state string, reason string, err error)
```

LifecycleStateAt reports whether key is active, revoked, or expired at at.

## PublicKeyBytes

```go
func (key TrustedKey) PublicKeyBytes() ([]byte, error)
```

PublicKeyBytes decodes the raw Ed25519 public key.

## TrustedKeys

```go
type TrustedKeys struct {
	Version int          `json:"version"`
	Keys    []TrustedKey `json:"keys"`
}
```

TrustedKeys is the .scafld/trusted-keys.json schema.

- `Version: int` (json:"version"): 
- `Keys: []TrustedKey` (json:"keys"): 

## ActiveKey

```go
func (keys TrustedKeys) ActiveKey(id string) (TrustedKey, error)
```

ActiveKey returns the non-revoked trusted key matching id. It is the single authority for receipt key lookup: an unknown id or a revoked key is rejected here so callers never re-implement revocation. Revoked entries remain valid in the allowlist file (so revoking one key does not brick the others); they are rejected only at the moment a receipt tries to use them.

## ActiveKeyAt

```go
func (keys TrustedKeys) ActiveKeyAt(id string, mintedAt string) (TrustedKey, error)
```

ActiveKeyAt returns the trusted key matching id when it was valid at mintedAt. mintedAt must be RFC3339 because receipt verification evaluates key lifecycle against the signed receipt time, not against wall-clock now.

## LifecycleSummary

```go
func (keys TrustedKeys) LifecycleSummary(at time.Time) KeyLifecycleSummary
```

LifecycleSummary returns active/revoked/expired key counts at one point in time.

## Validate

```go
func (keys TrustedKeys) Validate() error
```

Validate checks trusted-key schema and key identity integrity.