identity

package
v1.9.0 Latest Latest
Warning

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

Go to latest
Published: Nov 10, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package identity signs and verifies identity.v1 Claims on top of the payload-agnostic client/utils/jws package.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Check

func Check(claim *identityv1.Claim, recordCID, expectedSubject string) error

Check runs the checks of Verify that need no key: that claim is for recordCID, that its subject is expectedSubject, and that it has not expired. A caller that must look keys up over the network can run it first, so a claim that cannot verify is rejected before any lookup.

func NeedsCertificate

func NeedsCertificate(subject string) bool

NeedsCertificate reports whether a claim for subject must carry a certificate: see Scheme.NeedsCertificate. A subject in no known scheme needs none; the resolver refuses it anyway.

func Sign

func Sign(claim *identityv1.Claim, recordCID string, signer jws.Signer, opts ...SignOption) error

Sign signs claim for recordCID using signer, setting RecordCid, SignedAt and Signature, plus Certificate when WithCertificate is given.

func Verify

func Verify(claim *identityv1.Claim, recordCID, expectedSubject string, keys ...crypto.PublicKey) (bool, error)

Verify checks that claim was validly signed for recordCID and that its subject matches expectedSubject (the record's own "agntcy.dir/identity" or "agntcy.dir/owner" annotation, matching claim's role).

keys are the already-resolved candidate public keys for claim's subject (e.g. a DNS TXT record set or a JWKS); the claim verifies if any one of them validates its signature. Resolving those keys (a DNS/DID/JWKS lookup, or the validation of an embedded certificate for spiffe:// and ans://) is a separate concern, not this package's job.

Types

type Scheme

type Scheme string

Scheme is the way a claim's subject names the key material that proves the claim. It is read off the subject's spelling, and it decides which resolver finds the keys and whether the claim carries a certificate.

const (
	// SchemeDNS is "dns:<host>", or a bare host name: the key is published in
	// a DNS TXT record.
	SchemeDNS Scheme = "dns"

	// SchemeDID is "did:web:..." or "did:key:...": the key is in the DID document.
	SchemeDID Scheme = "did"

	// SchemeWellKnown is "https://...": the key is in a well-known JWKS.
	SchemeWellKnown Scheme = "https"

	// SchemeSPIFFE is "spiffe://...": the key is the X.509-SVID the claim carries.
	SchemeSPIFFE Scheme = "spiffe"

	// SchemeANS is "ans://...": the key is the identity certificate the claim
	// carries, attested by the agent's transparency log.
	SchemeANS Scheme = "ans"

	// SchemeAGNTCY is an agent subject verified by an external authority.
	SchemeAGNTCY Scheme = "agntcy"
)

The schemes a subject can be spelled in.

func SchemeOf

func SchemeOf(subject string) (Scheme, bool)

SchemeOf returns the scheme a subject is spelled in. A subject without a scheme is a bare host name and reads as SchemeDNS; one spelled in an unknown scheme reports false.

func Schemes

func Schemes() []Scheme

Schemes lists every scheme, in the order messages name them.

func (Scheme) NeedsCertificate

func (s Scheme) NeedsCertificate() bool

NeedsCertificate reports whether a claim for the scheme carries the certificate its key comes from. Every other scheme publishes its key, and a claim for it must not carry one.

func (Scheme) Prefix

func (s Scheme) Prefix() string

Prefix returns the spelling that selects the scheme, e.g. "ans://".

type SignOption

type SignOption func(*signOptions)

SignOption customizes Sign.

func WithCertificate

func WithCertificate(cert []byte) SignOption

WithCertificate embeds the signer's X.509 certificate (PEM or DER) in the claim. Sign fails unless the certificate belongs to the signer's key and carries the claim's subject as a URI SAN.

Directories

Path Synopsis
Package resolvers defines what an identity key resolver is.
Package resolvers defines what an identity key resolver is.
agntcy
Package agntcy implements authenticated key resolution and record-specific Agent Badge verification for agntcy:// subjects.
Package agntcy implements authenticated key resolution and record-specific Agent Badge verification for agntcy:// subjects.
ans
Package ansresolver resolves "ans://" subjects.
Package ansresolver resolves "ans://" subjects.
did
dns

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL