### Quick Start: Generate Keys, Build Discovery, Issue and Verify Credentials

Source: https://github.com/thirdkeyai/agentpin/blob/main/python/README.md

Demonstrates a full workflow using AgentPin: generating key pairs, creating a discovery document, issuing a capability-scoped credential, and verifying it offline. This example showcases core functionalities for AI agent identity management.

```python
from agentpin import (
    generate_key_pair,
    generate_key_id,
    pem_to_jwk,
    issue_credential,
    verify_credential_offline,
    build_discovery_document,
    KeyPinStore,
    Capability,
)

# Generate keys
private_key_pem, public_key_pem = generate_key_pair()
kid = generate_key_id(public_key_pem)
jwk = pem_to_jwk(public_key_pem, kid)

# Build discovery document
discovery = build_discovery_document(
    "example.com", "maker", [jwk],
    [{
        "agent_id": "urn:agentpin:example.com:my-agent",
        "name": "My Agent",
        "capabilities": ["read:data", "write:reports"],
        "status": "active",
    }],
    2,
)

# Issue credential
credential = issue_credential(
    private_key_pem=private_key_pem,
    kid=kid,
    issuer="example.com",
    agent_id="urn:agentpin:example.com:my-agent",
    audience="verifier.com",
    capabilities=[
        Capability.create("read", "data"),
        Capability.create("write", "reports"),
    ],
    constraints=None,
    delegation_chain=None,
    ttl_secs=3600,
)

# Verify credential
result = verify_credential_offline(
    credential_jwt=credential,
    discovery=discovery,
    revocation=None,
    pin_store=KeyPinStore(),
    audience="verifier.com",
)

if result.valid:
    print(f"Agent: {result.agent_id}")
    print(f"Capabilities: {result.capabilities}")
    print(f"Key pinning: {result.key_pinning}")
else:
    print(f"Failed: {result.error_code} - {result.error_message}")
```

--------------------------------

### AgentPin CLI Usage Examples

Source: https://context7.com/thirdkeyai/agentpin/llms.txt

This section provides command-line examples for using the AgentPin CLI tool. It covers generating ECDSA P-256 key pairs, issuing JWT credentials with specified capabilities and TTL, and verifying credentials offline using discovery and revocation information. No external dependencies are required beyond the AgentPin CLI installation.

```bash
# Generate ECDSA P-256 keypair
agentpin keygen --domain example.com --kid key-2026-01 --output-dir ./keys
# Outputs:
#   ./keys/key-2026-01.private.pem
#   ./keys/key-2026-01.public.pem
#   ./keys/key-2026-01.public.jwk.json

# Issue a credential
agentpin issue \
  --private-key ./keys/key-2026-01.private.pem \
  --kid key-2026-01 \
  --issuer example.com \
  --agent-id "urn:agentpin:example.com:scout" \
  --capabilities "read:codebase,write:reports,execute:analysis" \
  --audience customer.com \
  --ttl 3600
# Outputs: JWT to stdout

# Verify a credential offline
agentpin verify \
  --credential "eyJhbGciOiJFUzI1NiI..." \
  --discovery ./agent-identity.json \
  --revocation ./revocations.json \
  --pin-store ./pins.json
# Outputs: JSON verification result

```

--------------------------------

### Quick Start: AgentPin JavaScript Example

Source: https://github.com/thirdkeyai/agentpin/blob/main/javascript/README.md

This JavaScript code snippet demonstrates the core functionalities of agentpin, including key generation, discovery document creation, credential issuance, and offline verification. It utilizes various functions from the agentpin library to manage cryptographic identities and credentials.

```javascript
import {
    generateKeyPair,
    generateKeyId,
    pemToJwk,
    issueCredential,
    verifyCredentialOffline,
    buildDiscoveryDocument,
    KeyPinStore,
    Capability,
} from 'agentpin';

// Generate keys
const { privateKeyPem, publicKeyPem } = generateKeyPair();
const kid = generateKeyId(publicKeyPem);
const jwk = pemToJwk(publicKeyPem, kid);

// Build discovery document
const discovery = buildDiscoveryDocument(
    'example.com', 'maker', [jwk],
    [{
        agent_id: 'urn:agentpin:example.com:my-agent',
        name: 'My Agent',
        capabilities: ['read:data', 'write:reports'],
        status: 'active',
    }],
    2, new Date().toISOString()
);

// Issue credential
const credential = issueCredential(
    privateKeyPem, kid, 'example.com',
    'urn:agentpin:example.com:my-agent', 'verifier.com',
    [new Capability('read:data'), new Capability('write:reports')],
    null, null, 3600
);

// Verify credential
const result = verifyCredentialOffline(
    credential, discovery, null, new KeyPinStore(), 'verifier.com',
    { clockSkewSecs: 60, maxTtlSecs: 86400 }
);

if (result.valid) {
    console.log('Agent:', result.agent_id);
    console.log('Capabilities:', result.capabilities);
    console.log('Key pinning:', result.key_pinning);
} else {
    console.error('Failed:', result.error_code, result.error_message);
}
```

--------------------------------

### Install agentpin using npm

Source: https://github.com/thirdkeyai/agentpin/blob/main/javascript/README.md

This command installs the agentpin package using npm. Ensure you have Node.js and npm installed on your system.

```bash
npm install agentpin
```

--------------------------------

### Development Build and Test

Source: https://github.com/thirdkeyai/agentpin/blob/main/SKILL.md

Instructions for building, testing, and linting the AgentPin project.

```APIDOC
## Development

### Build and Test

```bash
# Build all crates
cargo build --workspace

# Run all tests
cargo test --workspace

# Lint
cargo clippy --workspace

# Format check
cargo fmt --check
```
```

--------------------------------

### Install AgentPin

Source: https://github.com/thirdkeyai/agentpin/blob/main/python/README.md

Installs the agentpin Python package using pip. Requires Python version 3.8 or higher.

```bash
pip install agentpin
```

--------------------------------

### Key Concepts

Source: https://github.com/thirdkeyai/agentpin/blob/main/SKILL.md

Explanation of core concepts and security principles employed by AgentPin.

```APIDOC
## Key Concepts

### ES256 Only

AgentPin exclusively uses ES256 (ECDSA P-256). All other algorithms are rejected. This is enforced inline without an external JWT crate.

### 12-Step Verification

The credential verification flow includes:
1. JWT structure parsing
2. Header algorithm validation (ES256 only)
3. Signature verification
4. Issuer domain extraction
5. Discovery document resolution
6. Domain binding verification
7. Key matching (issuer key vs discovery)
8. TOFU key pinning check
9. Expiration validation
10. Revocation checking
11. Capability validation
12. Delegation chain verification (if present)

### TOFU Key Pinning

On first credential verification for a domain, the agent's public key (JWK thumbprint) is pinned. Subsequent verifications reject different keys for the same domain — detecting key substitution attacks.

### Delegation Chains

Agents can delegate capabilities to sub-agents. The delegation chain is validated to ensure:
- Each link is signed by the delegator
- Capabilities only narrow (never widen) down the chain
- Chain depth limits are respected

### Mutual Authentication

Challenge-response protocol with 128-bit nonces for bidirectional agent identity verification.
```

--------------------------------

### Load Trust Bundle (Python)

Source: https://github.com/thirdkeyai/agentpin/blob/main/SKILL.md

Demonstrates loading a trust bundle in Python for offline verification. It shows how to retrieve discovery and revocation data for a specific domain.

```python
from agentpin.bundle import TrustBundle

bundle = TrustBundle.from_json(bundle_json_str)
discovery = bundle.find_discovery("example.com")
revocation = bundle.find_revocation("example.com")
```

--------------------------------

### AgentPin Capability Scoping Examples

Source: https://github.com/thirdkeyai/agentpin/blob/main/AGENTPIN_TECHNICAL_SPECIFICATION.md

Illustrates how AgentPin capabilities can be scoped using dot-notation on resource types for more granular access control. Examples include scoping to specific repositories, databases, and tools.

```text
read:codebase.github.com/org/repo
write:database.production.users
execute:tool.mcp.file-manager
```

--------------------------------

### Key Modules Overview

Source: https://github.com/thirdkeyai/agentpin/blob/main/SKILL.md

An overview of the core modules within the AgentPin library and their respective purposes.

```APIDOC
## Key Modules

| Module | Purpose |
|---|---|
| `crypto` | ECDSA P-256 signing/verification (no external JWT crate) |
| `types` | Core data structures (agents, credentials, capabilities) |
| `credential` | JWT issuance and parsing |
| `discovery` | Publishing and resolving agent identity documents |
| `verification` | 12-step credential validation flow |
| `revocation` | Checking revoked credentials/agents/keys |
| `pinning` | TOFU key pinning with JWK thumbprints |
| `delegation` | Delegation chain validation |
| `mutual` | Challenge-response mutual authentication (128-bit nonces) |
| `jwk` | JWK handling and thumbprint computation |
| `resolver` | Pluggable discovery resolution |
```

--------------------------------

### Serve discovery endpoints

Source: https://context7.com/thirdkeyai/agentpin/llms.txt

Starts a server to serve discovery and revocation endpoints for AI agents.

```APIDOC
## AgentPin Server

### Description
Starts a server that exposes discovery and revocation endpoints, allowing other agents to fetch identity and revocation information.

### Method
`agentpin-server` (CLI command to start server)

### Endpoint
- `GET /.well-known/agent-identity.json` (Cache-Control: max-age=3600)
- `GET /.well-known/agent-identity-revocations.json` (Cache-Control: max-age=300)
- `GET /health`

### Parameters
#### Command Line Arguments
- **--discovery** (string) - Required - Path to the agent identity JSON file.
- **--revocation** (string) - Required - Path to the revocation JSON file.
- **--port** (integer) - Optional - The port to run the server on. Defaults to 8080.

### Request Example
```bash
agentpin-server \
  --discovery ./agent-identity.json \
  --revocation ./revocations.json \
  --port 8080
```

### Response
#### Success Response (200 for GET requests)
- **/.well-known/agent-identity.json**: Returns the agent's identity document.
- **/.well-known/agent-identity-revocations.json**: Returns the agent's revocation list.
- **/health**: Returns a health status.

#### Response Example (for /.well-known/agent-identity.json)
```json
{
  "id": "did:example:123",
  "version": "1.0",
  "publicKeys": [
    {
      "id": "key-1",
      "type": "EcdsaSecp256k1VerificationKey2019",
      "publicKeyPem": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
    }
  ],
  "services": [
    {
      "id": "service-1",
      "type": "AgentService",
      "endpoint": "https://agent.example.com/"
    }
  ]
}
```
```

--------------------------------

### Build and Test (Bash)

Source: https://github.com/thirdkeyai/agentpin/blob/main/SKILL.md

Commands for building, testing, linting, and formatting the AgentPin Rust project. These are essential for development and maintaining code quality.

```bash
# Build all crates
cargo build --workspace

# Run all tests
cargo test --workspace

# Lint
cargo clippy --workspace

# Format check
cargo fmt --check
```

--------------------------------

### AgentPin Example Credential Header (JSON)

Source: https://github.com/thirdkeyai/agentpin/blob/main/AGENTPIN_TECHNICAL_SPECIFICATION.md

The header of an example AgentPin credential, specifying the signing algorithm ('alg'), token type ('typ'), and key identifier ('kid').

```json
{
  "alg": "ES256",
  "typ": "agentpin-credential+jwt",
  "kid": "tarnover-2026-01"
}
```

--------------------------------

### Development Conventions

Source: https://github.com/thirdkeyai/agentpin/blob/main/SKILL.md

Coding standards and conventions followed in the AgentPin project.

```APIDOC
### Conventions

- Rust edition 2021, MSRV 1.70
- `cargo clippy --workspace` must pass with zero warnings
- `cargo fmt --check` must pass
- Inline tests in source files (`#[cfg(test)] mod tests`)
- ES256 only — reject all other algorithms
- Feature-gated HTTP: `fetch` feature enables reqwest
```

--------------------------------

### Rust CLI: Generate Keys, Issue, Verify, and Bundle Credentials

Source: https://github.com/thirdkeyai/agentpin/blob/main/SKILL.md

This snippet demonstrates using the AgentPin Rust CLI for core operations. It covers generating keypairs, issuing JWT credentials with specified capabilities and TTL, verifying credentials offline against a discovery document, verifying online by fetching from .well-known endpoints, and creating trust bundles for air-gapped environments.

```bash
# Generate keys
cargo run -p agentpin-cli -- keygen \
    --output-dir ./keys --agent-name "my-agent"

# Issue a credential (ES256 JWT, 1-hour TTL)
cargo run -p agentpin-cli -- issue \
    --key ./keys/my-agent.private.pem \
    --issuer "https://example.com" \
    --agent-id "my-agent" \
    --capabilities read,write --ttl 3600

# Verify offline
cargo run -p agentpin-cli -- verify \
    --credential ./credential.jwt \
    --discovery ./agent-identity.json

# Verify online (fetches from .well-known)
cargo run -p agentpin-cli -- verify \
    --credential ./credential.jwt --domain example.com

# Create trust bundle for air-gapped environments
cargo run -p agentpin-cli -- bundle \
    --discovery ./agent-identity.json \
    --revocation ./revocations.json --output ./bundle.json
```

--------------------------------

### v0.2.0 Features

Source: https://github.com/thirdkeyai/agentpin/blob/main/SKILL.md

Highlights new features introduced in version 0.2.0, including Trust Bundles and Pluggable Discovery Resolvers.

```APIDOC
## v0.2.0 Features

### Trust Bundles (Offline / Air-Gapped)

Pre-package discovery + revocation data for environments without internet:

```python
from agentpin.bundle import TrustBundle

bundle = TrustBundle.from_json(bundle_json_str)
discovery = bundle.find_discovery("example.com")
revocation = bundle.find_revocation("example.com")
```

### Pluggable Discovery Resolvers

```python
from agentpin.discovery import (
    WellKnownResolver,    # HTTP .well-known lookups
    DnsTxtResolver,       # DNS TXT record lookups
    ManualResolver,       # Pre-configured discovery data
)
```

### Directory Listing

Domains can advertise all their agents via `"directory_listing": true` in the discovery document. Verifiers can enumerate available agents before issuing challenges.
```

--------------------------------

### Pluggable Discovery Resolvers (Python)

Source: https://github.com/thirdkeyai/agentpin/blob/main/SKILL.md

Illustrates the use of pluggable discovery resolvers in Python. These allow for different methods of discovering agent identity documents, such as HTTP or DNS.

```python
from agentpin.discovery import (
    WellKnownResolver,    # HTTP .well-known lookups
    DnsTxtResolver,       # DNS TXT record lookups
    ManualResolver,       # Pre-configured discovery data
)
```

--------------------------------

### Example Discovery Document (AgentPin)

Source: https://github.com/thirdkeyai/agentpin/blob/main/AGENTPIN_TECHNICAL_SPECIFICATION.md

An example of a discovery document used in the AgentPin protocol. This document typically contains endpoint information, schema definitions, field specifications, public key formats, and agent declarations.

```json
{
  "@context": "https://schema.pin.thirdkey.ai/v1/context.jsonld",
  "id": "did:example:agent1",
  "type": "AgentPinDiscoveryDocument",
  "endpoints": {
    "agentPinService": "https://agent.example.com/pin/v1"
  },
  "publicKeys": [
    {
      "id": "did:example:agent1#key1",
      "type": "EcdsaSecp256k1VerificationKey2019",
      "controller": "did:example:agent1",
      "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...\n-----END PUBLIC KEY-----"
    }
  ],
  "agentDeclaration": {
    "name": "Example Agent",
    "version": "1.0.0",
    "capabilities": [
      "credentialIssuance",
      "credentialVerification"
    ]
  }
}
```

--------------------------------

### Language API Reference

Source: https://github.com/thirdkeyai/agentpin/blob/main/SKILL.md

A cross-language reference for common operations provided by AgentPin.

```APIDOC
## Language API Reference

| Operation | Rust | JavaScript | Python |
|---|---|---|---|
| Generate keys | `crypto::generate_keypair()` | `generateKeypair()` | `generate_keypair()` |
| Issue credential | `CredentialBuilder::new().sign()` | `issueCredential()` | `issue_credential()` |
| Verify credential | `verify_credential()` | `verifyCredential()` | `verify_credential()` |
| Key pinning | `KeyPinStore` | `KeyPinStore` | `KeyPinStore` |
| Trust bundle | `TrustBundle::from_json()` | `TrustBundle.fromJson()` | `TrustBundle.from_json()` |
| Mutual auth | `MutualAuth::challenge()` | `createChallenge()` | `create_challenge()` |
```

--------------------------------

### Feature Flags

Source: https://github.com/thirdkeyai/agentpin/blob/main/SKILL.md

Details on available feature flags and their impact on the library's functionality.

```APIDOC
## Feature Flags

| Feature | Purpose |
|---|---|
| `fetch` | Enables HTTP via reqwest for online discovery |
| (default) | Core library with no HTTP dependency |
```

--------------------------------

### Rust Library: Generate Keypair, Build and Verify Credentials

Source: https://github.com/thirdkeyai/agentpin/blob/main/SKILL.md

This snippet shows how to use the AgentPin Rust library for cryptographic operations. It includes generating an ECDSA P-256 keypair, building and signing a JWT credential with specified issuer, agent ID, capabilities, and TTL, and verifying the credential against a discovery document and key pin store.

```rust
use agentpin::{
    crypto,
    credential::CredentialBuilder,
    verification::verify_credential,
    pinning::KeyPinStore,
};

let (private_key, public_key) = crypto::generate_keypair()?;

let credential = CredentialBuilder::new()
    .issuer("https://example.com")
    .agent_id("my-agent")
    .capability("read")
    .capability("write")
    .ttl_secs(3600)
    .sign(&private_key)?;

let result = verify_credential(&credential, &discovery_doc, &pin_store)?;
```

--------------------------------

### Serve AgentPin Discovery Endpoints (CLI)

Source: https://github.com/thirdkeyai/agentpin/blob/main/README.md

Starts an HTTP server to serve agent identity and revocation endpoints. Requires paths to the discovery and revocation JSON files and a port number. Serves `/.well-known/agent-identity.json`, `/.well-known/agent-identity-revocations.json`, and `/health`.

```bash
agentpin-server \
  --discovery ./agent-identity.json \
  --revocation ./revocations.json \
  --port 8080
```

--------------------------------

### Load Trust Bundle (Rust, JavaScript, Python)

Source: https://github.com/thirdkeyai/agentpin/blob/main/SKILL.md

Loads a trust bundle from a JSON string, enabling offline or air-gapped verification. Trust bundles contain pre-packaged discovery and revocation data.

```rust
TrustBundle::from_json()
```

```javascript
TrustBundle.fromJson()
```

```python
TrustBundle.from_json()
```

--------------------------------

### AgentPin Custom Capability Examples

Source: https://github.com/thirdkeyai/agentpin/blob/main/AGENTPIN_TECHNICAL_SPECIFICATION.md

Demonstrates the definition of custom capabilities in AgentPin using reverse-domain notation for resources. This allows organizations to define unique permissions beyond the core set.

```text
read:com.client-corp.internal-api
execute:com.tarnover.security-scan
```

--------------------------------

### Key Pinning Store (Rust, JavaScript, Python)

Source: https://github.com/thirdkeyai/agentpin/blob/main/SKILL.md

Manages the Trust-On-First-Use (TOFU) key pinning mechanism. This store is used to detect key substitution attacks by remembering the public key JWK thumbprint for a domain.

```rust
KeyPinStore
```

```javascript
KeyPinStore
```

```python
KeyPinStore
```

--------------------------------

### Rust Server: Serve .well-known Endpoints

Source: https://github.com/thirdkeyai/agentpin/blob/main/SKILL.md

This snippet shows how to run the AgentPin Rust server to host the necessary .well-known endpoints for agent identity and revocations. It configures the server to serve agent identity documents and revocation lists, making them discoverable for verification processes.

```bash
cargo run -p agentpin-server -- \
    --identity ./agent-identity.json \
    --revocation ./revocations.json \
    --port 3000

# Serves:
# - GET /.well-known/agent-identity.json (Cache-Control: max-age=3600)
# - GET /.well-known/agent-identity-revocations.json (Cache-Control: max-age=300)
# - GET /health
```

--------------------------------

### JavaScript: Generate Keypair, Issue and Verify Credentials

Source: https://github.com/thirdkeyai/agentpin/blob/main/SKILL.md

This snippet demonstrates using the AgentPin JavaScript library for identity management. It covers generating an ECDSA P-256 keypair, issuing a JWT credential with details like issuer, agent ID, capabilities, and TTL, and verifying the credential using a KeyPinStore.

```bash
npm install agentpin
```

```javascript
import {
    generateKeypair, issueCredential, verifyCredential,
    KeyPinStore
} from 'agentpin';

// Generate ECDSA P-256 keypair
const { privateKey, publicKey } = await generateKeypair();

// Issue a credential
const credential = await issueCredential(privateKey, {
    issuer: 'https://example.com',
    agentId: 'my-agent',
    capabilities: ['read', 'write'],
    ttlSecs: 3600,
});

// Verify
const pinStore = new KeyPinStore();
const result = await verifyCredential(credential, discoveryDoc, pinStore);
```

--------------------------------

### Discovery Document JSON

Source: https://github.com/thirdkeyai/agentpin/blob/main/SKILL.md

Example structure of an agent identity discovery document published at /.well-known/agent-identity.json. It includes agent details, public keys, and revocation endpoints.

```json
{
    "schema_version": "0.2",
    "domain": "example.com",
    "agents": [
        {
            "agent_id": "my-agent",
            "display_name": "My Agent",
            "description": "A helpful agent",
            "capabilities": ["read", "write"],
            "public_key_jwk": { ... },
            "constraints": {
                "max_ttl_secs": 86400,
                "allowed_scopes": ["api"]
            }
        }
    ],
    "revocation_endpoint": "https://example.com/.well-known/agent-identity-revocations.json",
    "directory_listing": true
}
```

--------------------------------

### AgentPin Example Credential Payload (JSON)

Source: https://github.com/thirdkeyai/agentpin/blob/main/AGENTPIN_TECHNICAL_SPECIFICATION.md

The payload of an example AgentPin credential, containing issuer, subject, audience, timestamps, version, capabilities, constraints, and delegation chain information.

```json
{
  "iss": "tarnover.com",
  "sub": "urn:agentpin:tarnover.com:scout-v2",
  "aud": "api.client-corp.com",
  "iat": 1738300800,
  "exp": 1738304400,
  "jti": "550e8400-e29b-41d4-a716-446655440000",
  "agentpin_version": "0.1",
  "capabilities": [
    "read:public-api",
    "read:codebase"
  ],
  "constraints": {
    "allowed_domains": ["api.client-corp.com"],
    "rate_limit": "50/hour",
    "data_classification_max": "internal"
  },
  "delegation_chain": [
    {
      "domain": "anthropic.com",
      "role": "maker",
      "agent_id": "urn:agentpin:anthropic.com:claude-agent-v4",
      "kid": "anthropic-2026-01",
      "attestation": "MEUCIQD7y2F8..."
    }
  ]
}
```

--------------------------------

### Example Agent Credential (AgentPin)

Source: https://github.com/thirdkeyai/agentpin/blob/main/AGENTPIN_TECHNICAL_SPECIFICATION.md

An example of an agent credential formatted as a JSON Web Token (JWT) within the AgentPin protocol. It includes header, payload with capability and constraint claims, and delegation chain information.

```jwt
eyJhbGciOiJFUzI1NiIsImtpZCI6ImRpZDpleGFtcGxlOmFnZW50MSNrZXkxIn0.eyJpc3MiOiJkaWQ6ZXhhbXBsZTphZ2VudDEiLCJhdWQiOiJkaWQ6ZXhhbXBsZTphZ2VudDIiLCJpYXQiOjE2NzgyNzIwMDAsImV4cCI6MTY3ODI3NTYwMCwiY2FwYWJpbGl0aWVzIjpbImNyZWRlbnRJZXNzdWFuY2UiXSwiY29uc3RhaW50cyI6eyJkb21haW4iOiJleGFtcGxlLmNvbSJ9LCJkZWxlZ2F0aW9uQ2hhaW4iOlsidGlkOmV4YW1wbGU6Z3JhbmRwYXJlbnRzZ3I0Il19.signature
```

--------------------------------

### Define, Parse, and Match Hierarchical Capabilities in JavaScript

Source: https://context7.com/thirdkeyai/agentpin/llms.txt

This snippet demonstrates how to create, parse, and match hierarchical capabilities using the `agentpin` library. It covers wildcard and scoped matching, as well as checking capability subsets and hashing capabilities for attestation. Dependencies include the `agentpin` library.

```javascript
import { Capability, capabilitiesSubset, capabilitiesHash } from 'agentpin';

// Create capabilities
const cap1 = new Capability('read:codebase');
const cap2 = Capability.create('write', 'reports');

// Access parts
console.log(cap1.action);    // 'read'
console.log(cap1.resource);  // 'codebase'

// Parse capability string
const [action, resource] = Capability.parse('execute:analysis.security');
// ['execute', 'analysis.security']

// Wildcard matching: 'read:*' matches any read capability
const wildcard = new Capability('read:*');
console.log(wildcard.matches(new Capability('read:codebase')));     // true
console.log(wildcard.matches(new Capability('read:reports')));      // true
console.log(wildcard.matches(new Capability('write:reports')));     // false

// Scoped matching: 'read:codebase' matches 'read:codebase.github.com/org/repo'
const scoped = new Capability('read:codebase');
console.log(scoped.matches(new Capability('read:codebase')));                      // true
console.log(scoped.matches(new Capability('read:codebase.github.com/org/repo')));  // true
console.log(scoped.matches(new Capability('read:other')));                         // false

// Check if requested capabilities are subset of declared capabilities
const declared = [new Capability('read:*'), new Capability('write:reports')];
const requested = [new Capability('read:codebase'), new Capability('write:reports')];
console.log(capabilitiesSubset(declared, requested));  // true

// Hash capabilities for delegation attestation
const hash = capabilitiesHash(requested);
// SHA-256 of sorted JSON array, hex-encoded

```

--------------------------------

### Discovery Document Format

Source: https://github.com/thirdkeyai/agentpin/blob/main/SKILL.md

Defines the structure of the agent identity discovery document published at /.well-known/agent-identity.json.

```APIDOC
## Discovery Document Format

Published at `/.well-known/agent-identity.json`:

```json
{
    "schema_version": "0.2",
    "domain": "example.com",
    "agents": [
        {
            "agent_id": "my-agent",
            "display_name": "My Agent",
            "description": "A helpful agent",
            "capabilities": ["read", "write"],
            "public_key_jwk": { ... },
            "constraints": {
                "max_ttl_secs": 86400,
                "allowed_scopes": ["api"]
            }
        }
    ],
    "revocation_endpoint": "https://example.com/.well-known/agent-identity-revocations.json",
    "directory_listing": true
}
```
```

--------------------------------

### Create a trust bundle

Source: https://context7.com/thirdkeyai/agentpin/llms.txt

Commands for creating and managing trust bundles for offline or high-security deployments.

```APIDOC
## AgentPin Bundle Management

### Description
Commands for creating and managing trust bundles, which can include discovery information and revocation lists for offline or high-security deployments.

### Method
Various (CLI commands)

### Endpoints
- `agentpin bundle create --output <file>`
- `agentpin bundle add-discovery <bundle_file> <discovery_file>`
- `agentpin bundle add-revocation <bundle_file> <revocation_file>`

### Usage Examples

**Create a new trust bundle:**
```bash
agentpin bundle create --output trust-bundle.json
```

**Add discovery information to the bundle:**
```bash
agentpin bundle add-discovery trust-bundle.json ./agent-identity.json
```

**Add revocation information to the bundle:**
```bash
agentpin bundle add-revocation trust-bundle.json ./revocations.json
```

### Response
#### Success Response
- **Output**: Trust bundle file is created or updated.

#### Response Example
(No direct JSON response for CLI commands, output is file modification)
```

--------------------------------

### Build and Test Rust AgentPin

Source: https://github.com/thirdkeyai/agentpin/blob/main/README.md

Builds and tests the core AgentPin Rust library. The `fetch` feature flag enables network fetching capabilities.

```rust
cargo build --workspace
cargo test --workspace
```

```toml
[dependencies]
agentpin = { version = "0.1", features = ["fetch"] }
```

--------------------------------

### Generate Keypair (Rust, JavaScript, Python)

Source: https://github.com/thirdkeyai/agentpin/blob/main/SKILL.md

Generates a new cryptographic keypair for agent authentication. This is a fundamental operation for agent identity management.

```rust
crypto::generate_keypair()
```

```javascript
generateKeypair()
```

```python
generate_keypair()
```

--------------------------------

### AgentPin API: Key Pinning

Source: https://github.com/thirdkeyai/agentpin/blob/main/javascript/README.md

Demonstrates key pinning functionality using `KeyPinStore` in agentpin. This includes checking and pinning keys, adding keys to allow rotation, and persisting/restoring the pin store state.

```javascript
import { KeyPinStore } from 'agentpin/pinning';

const store = new KeyPinStore();
const result = store.checkAndPin(domain, jwk); // 'first_use' | 'matched' | 'changed'
store.addKey(domain, jwk);                      // allow key rotation
const json = store.toJson();                    // persist
const restored = KeyPinStore.fromJson(json);    // restore
```

--------------------------------

### Verify Credential (Rust, JavaScript, Python)

Source: https://github.com/thirdkeyai/agentpin/blob/main/SKILL.md

Verifies the authenticity and validity of a given credential. This involves a multi-step process including signature verification and revocation checks.

```rust
verify_credential()
```

```javascript
verifyCredential()
```

```python
verify_credential()
```

--------------------------------

### Issue Credential (Rust, JavaScript, Python)

Source: https://github.com/thirdkeyai/agentpin/blob/main/SKILL.md

Issues a new credential, typically involving signing with a private key. This function is central to the credential issuance process.

```rust
CredentialBuilder::new().sign()
```

```javascript
issueCredential()
```

```python
issue_credential()
```

--------------------------------

### AgentPin Credential Issuance and Verification (Python)

Source: https://github.com/thirdkeyai/agentpin/blob/main/README.md

Shows how to generate key pairs, issue a JWT credential, and perform offline verification using the AgentPin Python package. Requires Python 3.8+ and the `cryptography` library.

```python
from agentpin import (
    generate_key_pair, pem_to_jwk, issue_credential,
    verify_credential_offline, KeyPinStore, Capability,
    build_discovery_document, EntityType, AgentStatus,
)

private_key, public_key = generate_key_pair()
jwk = pem_to_jwk(public_key, "my-key-2026")

credential = issue_credential(
    private_key, "my-key-2026", "example.com",
    "urn:agentpin:example.com:agent", "verifier.com",
    [Capability("read:data")], None, None, 3600,
)

result = verify_credential_offline(
    credential, discovery, None, KeyPinStore(), "verifier.com"
);
```