Package com.tnsai.identity

Interface AgentPrincipalProvider

All Known Implementing Classes:

LocalIdentityProvider

public interface AgentPrincipalProvider

SPI for issuing and verifying AgentPrincipal instances (TNS-298). Two contracts are deliberately separate so adapters can specialise:

• Issue — mint an identity from an AgentDescriptor during agent construction. The framework's default LocalIdentityProvider hashes the spec into a UUID; external providers (ERC-8004, KMS-backed certs, OIDC) reach out to their trust root and return a signed identity.
• Verify — check a presented identity (id + signature) is genuinely issued by this provider. Returns the materialised AgentPrincipal on success, empty on failure.

Implementations

Default LocalIdentityProvider ships with the framework — UUID-based, no external trust root, suitable for single-tenant deployments where the framework itself is the trust boundary. External providers (ERC-8004, AIUC-1, X.509 chain) ship as separate optional artefacts so tnsai-core stays free of crypto deps.

Since:

0.10.0 (TNS-298)

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	AgentPrincipalProvider.IdentityIssueException	Thrown by issue(com.tnsai.identity.AgentDescriptor) when the trust root refuses to mint an identity (revoked spec, blocked tenant, …).

Method Summary

Modifier and Type	Method	Description
AgentPrincipal	issue(AgentDescriptor spec)	Mint a new identity for an agent described by spec.
Optional<AgentPrincipal>	verify(String id, byte[] signature)	Verify signature attests to id according to this provider's trust root.

Method Details

issue

AgentPrincipal issue(AgentDescriptor spec)

Mint a new identity for an agent described by spec. Implementations typically:

1. Hash spec into a stable id (or look up an existing id keyed by spec hash, idempotent reissue);
2. Compute the runtime fingerprint from build hash + config;
3. Optionally produce an Attestation via the trust root.

Throws:

NullPointerException - if spec is null

AgentPrincipalProvider.IdentityIssueException - if the trust root rejects the spec

verify

Optional<AgentPrincipal> verify(String id,
 byte[] signature)

Verify signature attests to id according to this provider's trust root. Returns the materialised AgentPrincipal on success, empty on signature mismatch or unknown id.

The signature payload is opaque to the framework — providers decide what they sign over (id + version + fingerprint, the full attestation bundle, …). External verifiers re-derive the payload via the same provider's algorithm.

Throws:

NullPointerException - if any arg is null