Package com.tnsai.identity

Class LocalIdentityProvider

java.lang.Object

com.tnsai.identity.LocalIdentityProvider

All Implemented Interfaces:

AgentPrincipalProvider

public final class LocalIdentityProvider
extends Object
implements AgentPrincipalProvider

Process-local AgentPrincipalProvider (TNS-298). UUID-based identities, no external trust root, no cryptographic attestation. Suitable for single-tenant deployments where the framework itself is the trust boundary.

What it produces

• AgentPrincipal.id() — UUID v4 minted once per AgentDescriptor (cached, so calling issue(com.tnsai.identity.AgentDescriptor) twice with the same spec returns the same id).
• AgentPrincipal.version() — SHA-256 of the spec's behaviour-relevant fields (system prompt, tool names, model) hex-truncated to 16 chars; changes when behaviour changes.
• AgentPrincipal.runtimeFingerprint() — SHA-256 of the spec's full content (including buildHash + metadata) hex-truncated to 16 chars; changes when ANY field changes.
• AgentPrincipal.attestation() — empty; this provider has no trust root to bind against.

Verification

verify(java.lang.String, byte[]) treats the signature as a HMAC-SHA-256 over the (id + version + fingerprint) tuple keyed by a process-local secret (random at construction, not exported). Verifies signatures issued by the SAME instance only — cross-process verification needs a shared-secret variant or a real attestation backend.

Since:

0.10.0 (TNS-298)

Nested Class Summary

Nested classes/interfaces inherited from interface com.tnsai.identity.AgentPrincipalProvider

AgentPrincipalProvider.IdentityIssueException

Constructor Summary

Constructors

Constructor	Description
LocalIdentityProvider()
LocalIdentityProvider(byte[] hmacKey)	Test / debug constructor — pin the HMAC key for reproducibility.

Method Summary

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

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

LocalIdentityProvider

public LocalIdentityProvider()

LocalIdentityProvider

public LocalIdentityProvider(byte[] hmacKey)

Test / debug constructor — pin the HMAC key for reproducibility.

Method Details

issue

public AgentPrincipal issue(AgentDescriptor spec)

Description copied from interface: AgentPrincipalProvider

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.

Specified by:

issue in interface AgentPrincipalProvider

verify

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

Description copied from interface: AgentPrincipalProvider

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.

Specified by:

verify in interface AgentPrincipalProvider

sign

public byte[] sign(AgentPrincipal identity)

Sign an identity issued by this provider. Used by callers that want to attach a signature to an AgentLiabilityRecord.