{"_id":"@agentauth/core","_rev":"4-574bd05010ecdaaca635b9373a49468d","name":"@agentauth/core","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@agentauth/core","version":"0.1.0","keywords":["agentauth","authentication","identity","mcp","self-authenticating","cryptography","secp256k1","signatures","uuid","ai-agents","model-context-protocol"],"author":{"name":"AgentAuth Team"},"license":"MIT","_id":"@agentauth/core@0.1.0","maintainers":[{"name":"agentpaydev","email":"developers@agentpay.me"},{"name":"agentcoredev","email":"developers@agentcore.me"}],"homepage":"https://github.com/agentcorelabs/agentauth#readme","bugs":{"url":"https://github.com/agentcorelabs/agentauth/issues"},"dist":{"shasum":"57bf718597c14be17486d3a89e7a9b14a2fe9167","tarball":"https://registry.npmjs.org/@agentauth/core/-/core-0.1.0.tgz","fileCount":6,"integrity":"sha512-LJbrXIe0ESZO4CLKGyh6HAFIwQPW9nc0WU9E7UJsGIoSF1yK69RWwBuALr+azPHGrjIcv257xqlSTZUjX4eS4A==","signatures":[{"sig":"MEUCICKkcylYuGZAmPOkgbmky5Eaj/E32Z/iGMtcNS3ocCbCAiEA4vQOz1W3UMZgKx0wUIiVCXpsBJelN96Knx4SJ2Fr8UU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":33303},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"gitHead":"b16d39338eb279939fbf127a619ef323dee449b3","scripts":{"dev":"tsc -w","test":"vitest run","build":"tsc"},"_npmUser":{"name":"agentcoredev","actor":{"name":"agentcoredev","type":"user","email":"developers@agentcore.me"},"email":"developers@agentcore.me"},"repository":{"url":"git+https://github.com/agentcorelabs/agentauth.git","type":"git","directory":"packages/agentauth-core"},"_npmVersion":"10.9.0","description":"Core identity and cryptographic primitives for AgentAuth","directories":{},"_nodeVersion":"23.3.0","dependencies":{"uuid":"^10.0.0","buffer":"^6.0.3","@noble/hashes":"^1.8.0","@noble/secp256k1":"^2.1.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@types/uuid":"^10.0.0"},"_npmOperationalInternal":{"tmp":"tmp/core_0.1.0_1750628456187_0.17078739816686794","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@agentauth/core","version":"0.1.1","description":"Core identity and cryptographic primitives for AgentAuth","type":"module","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"import":"./dist/index.js","types":"./dist/index.d.ts"}},"scripts":{"build":"tsc","dev":"tsc -w","test":"vitest run"},"author":{"name":"AgentAuth Team"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/agentcorelabs/agentauth.git","directory":"packages/agentauth-core"},"homepage":"https://github.com/agentcorelabs/agentauth#readme","bugs":{"url":"https://github.com/agentcorelabs/agentauth/issues"},"keywords":["agentauth","agentauth-id","authentication","identity","self-authenticating","uuid","mcp","cryptography","secp256k1","signatures","ai-agents","model-context-protocol"],"dependencies":{"@noble/secp256k1":"^2.1.0","@noble/hashes":"^1.8.0","uuid":"^10.0.0"},"devDependencies":{"@types/uuid":"^10.0.0"},"engines":{"node":">=18.0.0"},"publishConfig":{"access":"public"},"_id":"@agentauth/core@0.1.1","gitHead":"bd9fb7af453d65d36762dc2b1de17a8159d1753c","_nodeVersion":"23.3.0","_npmVersion":"10.9.0","dist":{"integrity":"sha512-lpN9/S6omX4shCvigrp9TC31adAIXTd+yPiVkre0ZjcViV6Qt5V1EW0X0wQYZAoOnXW6LIBgPL81Y1WNVLLOCA==","shasum":"e06e204050c9fd4cf82dff1a026c9be806b7c16e","tarball":"https://registry.npmjs.org/@agentauth/core/-/core-0.1.1.tgz","fileCount":6,"unpackedSize":34397,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIDJttgZ+W6myoO920R7280DEuCDkD0v+b23x+V8R5fKSAiAj4NCsF+aFcbV1+U6M2McK1sdw8WU/7I9SmTIPY+yCOA=="}]},"_npmUser":{"name":"agentauthdev","email":"developers@agentauth.co","actor":{"name":"agentauthdev","email":"developers@agentauth.co","type":"user"}},"directories":{},"maintainers":[{"name":"agentcoredev","email":"developers@agentcore.me"},{"name":"agentauthdev","email":"developers@agentauth.co"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/core_0.1.1_1751572950416_0.04207873658089056"},"_hasShrinkwrap":false}},"time":{"created":"2025-06-22T21:40:56.102Z","modified":"2025-07-03T20:02:30.788Z","0.1.0":"2025-06-22T21:40:56.363Z","0.1.1":"2025-07-03T20:02:30.590Z"},"bugs":{"url":"https://github.com/agentcorelabs/agentauth/issues"},"author":{"name":"AgentAuth Team"},"license":"MIT","homepage":"https://github.com/agentcorelabs/agentauth#readme","keywords":["agentauth","agentauth-id","authentication","identity","self-authenticating","uuid","mcp","cryptography","secp256k1","signatures","ai-agents","model-context-protocol"],"repository":{"type":"git","url":"git+https://github.com/agentcorelabs/agentauth.git","directory":"packages/agentauth-core"},"description":"Core identity and cryptographic primitives for AgentAuth","maintainers":[{"name":"agentcoredev","email":"developers@agentcore.me"},{"name":"agentauthdev","email":"developers@agentauth.co"}],"readme":"# @agentauth/core: Core Identity and Cryptographic Primitives for AgentAuth ID\n\n[](https://www.npmjs.com/package/@agentauth/core)\n[](https://www.npmjs.com/package/@agentauth/core)\n[](https://www.npmjs.com/package/@agentauth/core)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/agentauthco/agentauth)\n\nCore identity primitive and cryptographic components for **AgentAuth ID** β the self-authenticating UUID for AI agents.\n\nThis package provides the low-level cryptographic foundation used by the AgentAuth ecosystem. It handles key generation, address derivation, signing, and verification using secp256k1 elliptic curve cryptography.\n\nLearn more about AgentAuth at https://github.com/agentauthco/agentauth.\n\n## Why @agentauth/core?\n\n- **π Complete Identity System** β Generate stable agent identities with one function call\n- **π Industry-standard Cryptography** β Uses secp256k1 and battle-tested industry standards throughout\n- **π Deterministic UUIDs** β Same private key always generates the same UUID\n- **βοΈ Sign & Verify** β Simple payload signing and verification for authentication flows\n- **π‘οΈ Minimal, Well-Audited Dependencies** β Built on Noble cryptographic libraries, UUID, and nothing else\n\n## Installation\n\n```bash\nnpm install @agentauth/core\n```\n\n## Quick Start\n\n### Generate a New Identity\n\nCreate a complete AgentAuth identity with one function call:\n\n```typescript\nimport { generateIdentity } from '@agentauth/core';\n\nconst identity = generateIdentity();\nconsole.log(identity);\n// {\n// agentauth_token: 'aa-2337b9fa957a201db466a58065529dc40362e008d3f41655651b96b2abbcb602',\n// agentauth_address: '0x9906322508aa2d8cbf24c33751015162d58285ce',\n// agentauth_id: '811ec2bf-b653-573a-b2ea-6ff4df9fdad7'\n// }\n```\n\nThe identity includes:\n- `agentauth_token`: The private key (with aa- prefix) β β οΈ keep this secret!\n- `agentauth_address`: An industry-standard address derived from `agentauth_token`, used for verification\n- `agentauth_id`: A stable UUID v5 derived from `agentauth_address`\n\n> [!TIP]\n> As you can see, all you actually need to re-derive the full identity primitive is the `agentauth_token`, which makes it super lightweight!\n\n> [!IMPORTANT]\n> That's also why it's so important to protect it during usage (e.g. by only using it locally), and for users to store it **SECURELY**!\n\n### Work with Existing Keys\n\nDerive address and ID from an existing private key:\n\n```typescript\nimport { deriveAddress, generateId } from '@agentauth/core';\n\n// Accepts any format: aa-, 0x, or raw hex\nconst privateKey = 'aa-2337b9fa957a201db466a58065529dc40362e008d3f41655651b96b2abbcb602';\n\nconst address = deriveAddress(privateKey);\nconst id = generateId(address);\n\nconsole.log(address); // '0x9906322508aa2d8cbf24c33751015162d58285ce'\nconsole.log(id); // '811ec2bf-b653-573a-b2ea-6ff4df9fdad7'\n```\n\n### Sign and Verify Payloads\n\nUse for authentication flows and message signing:\n\n```typescript\nimport { signPayload, verifySignature } from '@agentauth/core';\n\nconst payload = {\n timestamp: new Date().toISOString(),\n action: 'authenticate',\n data: { tool: 'weather-forecast' }\n};\n\n// Sign with private key\nconst signature = signPayload(payload, privateKey);\n\n// Verify with address\nconst isValid = verifySignature(signature, payload, address);\nconsole.log(isValid); // true\n```\n\n## Identity Primitive\n\nThe AgentAuth identity primitive consists of three components that work together to provide a complete, self-contained identity system. Each component serves a specific purpose and was chosen for both technical and practical reasons.\n\n### AgentAuth Token (`agentauth_token`)\n\n**What it is:** A secp256k1 private key with an `aa-` prefix, formatted as 64 characters of hex, used for signing and authentication.\n\n```\nFormat: aa-[64 hex characters]\nExample: aa-2337b9fa957a201db466a58065529dc40362e008d3f41655651b96b2abbcb602\n```\n\n**Why we chose this design:**\n\n- **Battle-tested cryptography:** Uses the same secp256k1 curve and key derivation as Bitcoin and Ethereum, securing billions of dollars in value\n- **Industry standard:** Developers already understand this format and its security properties, with many well-audited, compatible libraries\n- **Self-contained:** The token alone is sufficient to derive the complete identity\n- **Recognizable prefix:** The `aa-` prefix makes AgentAuth tokens immediately identifiable and prevents accidental mixing with other key formats\n- **Future compatibility:** Uses Bitcoin/Ethereum-compatible formats, enabling integration with existing cryptographic tooling\n\n**Security properties:**\n- 256 bits of entropy (same security level as Bitcoin/Ethereum private keys)\n- Generated using cryptographically secure random number generation\n- Should be treated like any private key: keep secret, store securely\n\nWe use [@noble/secp256k1](https://github.com/paulmillr/noble-secp256k1) for all cryptographic operations, chosen for its audit history and constant-time implementations.\n\n> [!NOTE]\n> While AgentAuth currently uses secp256k1 for its default identity system β chosen for its ecosystem maturity, developer familiarity, and audit-backed performance β future versions of AgentAuth will **also** support Ed25519-based tokens for broader cryptographic interoperability and enhanced performance characteristics.\n\n### AgentAuth Address (`agentauth_address`)\n\n**What it is:** A cryptographically stable and secure address derived from the private key using keccak256 derivation, used for signature verification\n\n```\nFormat: 0x[40 hex characters]\nExample: 0x9906322508aa2d8cbf24c33751015162d58285ce\n```\n\n**Why we chose this design:**\n\n- **Verification-ready:** Servers can verify signatures using the same battle-tested algorithms as Ethereum (ecrecover)\n- **Standard format:** 20-byte Ethereum/EVM-style addresses are well-understood by developers and ergonomic for users\n- **Tool compatibility:** Works with existing development tools and libraries for testing and debugging\n- **Efficient performance:** Enables efficient signature verification using proven ecrecover algorithms\n- **Future extensibility:** Uses Ethereum/EVM-compatible address format, enabling potential integrations without breaking changes\n\n**Role in the system:**\n- Used for cryptographic verification of signed payloads\n- Never sent aloneβalways accompanied by a signature proving ownership\n- Derived deterministically from the private key (same key = same address)\n\nThe derivation follows Ethereum's address derivation: keccak256(publicKey)[12:] where publicKey is the uncompressed secp256k1 public key.\n\n### AgentAuth ID (`agentauth_id`)\n\n**What it is:** A UUID v5 generated deterministically from the AgentAuth Address, used for stable identification across systems\n\n```\nFormat: [UUID v5]\nExample: 811ec2bf-b653-573a-b2ea-6ff4df9fdad7\n```\n\n**Why we chose this design:**\n\n- **Database-friendly:** UUIDs are a standard, well-supported identifier format\n- **Deterministic:** Same address always produces the same UUID\n- **Globally unique:** UUID v5 guarantees uniqueness across all systems\n- **Privacy-preserving:** Doesn't directly expose the cryptographic address\n- **Application-ready:** Perfect for use as primary keys, user IDs, and foreign keys\n\n**Role in the system:**\n- The stable, public identifier used by applications\n- Safe to store in databases, logs, and APIs\n- Enables user recognition across different MCP servers\n- Generated using a fixed namespace UUID to ensure consistency\n\nWe use a fixed, custom namespace UUID (`2f5a5c48-c283-4231-8975-9271fe11e86c`) to derive all AgentAuth UUIDs to ensure they are all unique and stable.\n\n## How AgentAuth Works\n\nUnderstanding how AgentAuth works with this library under the hood helps explain why it's both secure and simple. The system is built on four key processes that utilize this library, in conjunction with the identity primitive above.\n\n### Identity Generation Process\n\nWhen you call `generateIdentity()`, here's what happens:\n\n**1. Secure randomness:** We generate 32 bytes (256 bits) of cryptographically secure random data using the platform's secure random number generator.\n\n**2. Private key formatting:** The random bytes are encoded as hex and prefixed with `aa-` to create the AgentAuth Token.\n\n**3. Deterministic derivation:** The address and UUID are derived using the processes below.\n\n```typescript\n// Simplified conceptual flow\nconst randomBytes = secureRandom(32); // 256 bits of entropy\nconst privateKey = 'aa-' + toHex(randomBytes); // Format as AgentAuth Token\nconst address = deriveAddress(privateKey); // Ethereum-style derivation\nconst uuid = generateId(address); // UUID v5 generation\n```\n\n**Why this approach:**\n- **Maximum entropy:** Uses platform secure randomness for unpredictability\n- **No server dependency:** Identity generation works completely offline\n- **Deterministic rebuild:** The complete identity can be reconstructed from just the token\n\n### Primitive Derivation Process\n\nThe identity primitive's three components are mathematically related through a deterministic chain:\n\n```mermaid\nflowchart\n A[AgentAuth Token
Private Key - 32 bytes
aa-2337b9fa...] -- secp256k1 + keccak256 --> B[AgentAuth Address
Public Address - 20 bytes
0x99063225...]\n B -- UUIDv5 + Namespace --> C[AgentAuth ID
UUID v5
811ec2bf-b653...]\n```\n\n**Token β Address derivation:**\n1. Remove `aa-` prefix and convert hex to bytes\n2. Generate secp256k1 public key from private key ([handled by @noble/secp256k1](https://github.com/paulmillr/noble-secp256k1))\n3. Apply keccak256 hash to the uncompressed public key\n4. Take the last 20 bytes and format with `0x` prefix\n\n**Address β UUID derivation:**\n1. Use the address as input to UUID v5 generation\n2. Apply our fixed namespace UUID (`2f5a5c48-c283-4231-8975-9271fe11e86c`)\n3. Generate deterministic UUID following [RFC 4122](https://tools.ietf.org/html/rfc4122)\n\n**Why deterministic derivation:**\n- **Reproducible:** Same token always generates the same address and UUID\n- **Stateless:** No need to store mappings between primitives\n- **Verifiable:** Anyone can verify the relationships between primitives\n\n### Authentication Signature Process\n\nWhen an agent needs to authenticate (e.g., via @agentauth/mcp), here's the signature flow:\n\n**1. Payload construction:** Create a JSON object with timestamp\n```typescript\nconst payload = {\n timestamp: '2024-01-15T10:30:00.000Z'\n};\n```\n\n**2. Canonical JSON:** Convert to deterministic string representation\n```typescript\nconst message = JSON.stringify(payload); // Must be deterministic\n```\n\n**3. Signature generation:** Sign the message using ECDSA\n- Hash the message with keccak256\n- Sign the hash using secp256k1 ECDSA ([handled by @noble/secp256k1](https://github.com/paulmillr/noble-secp256k1))\n- Format as hex with recovery bit\n\n**4. Header transmission:** Send via HTTP headers\n- `x-agentauth-address`: The AgentAuth Address\n- `x-agentauth-signature`: The signature with `0x` prefix\n- `x-agentauth-payload`: Base64-encoded JSON payload\n\n**Why this design:**\n- **Standard cryptography:** Uses well-understood ECDSA signatures\n- **Stateless replay protection:** Timestamp provides replay protection without requiring stateful nonce storage (e.g. by the server)\n- **Efficient verification:** Verify without storing state or tracking used nonces\n- **HTTP compatible:** Works with standard HTTP header mechanisms\n\n**Note on nonces:** We deliberately chose timestamp-based replay protection over nonces to maintain statelessness:\n- Nonces would require servers to track used values, adding complexity and storage requirements\n- A freshness window provides adequate replay protection for most use cases while keeping verification completely stateless\n- Future versions of @agentauth/mcp and @agentauth/sdk may add optional nonce support for applications requiring additional stateful security measures\n- It's also worth noting that the @agentauth/core library itself is designed for maximum flexibility and is **unopinionated** about the payloads it signs\n\n**Industry precedent:** Timestamp-based authentication windows are widely used across the industry:\n- **AWS Signature V4:** 15-minute default window for signed requests\n- **Google Cloud APIs:** 15-minute window for OAuth token timestamps \n- **JWT tokens:** Configurable `exp` and `nbf` claims for time-based validation\n- **OAuth 2.0:** Timestamp validation in bearer token flows\n- **HMAC-based APIs:** Common pattern with 5-15 minute windows\n\nOur 60-second default strikes a balance between security (shorter than most) and practical network/clock tolerance.\n\n### Server Verification Process\n\nWhen an MCP server receives a request (e.g., via @agentauth/sdk), here's the verification flow:\n\n**1. Header extraction:** Parse the three AgentAuth headers\n```typescript\nconst address = headers['x-agentauth-address']; // 0x99063225...\nconst signature = headers['x-agentauth-signature']; // 0x1234abcd...\nconst payload = base64Decode(headers['x-agentauth-payload']);\n```\n\n**2. Signature verification:** Verify the signature matches the payload and address\n- Decode the base64 payload back to JSON\n- Hash the JSON string with keccak256\n- Use ecrecover to extract the signing address from the signature\n- Compare recovered address with provided address\n\n**3. Freshness check:** Ensure the request is recent\n```typescript\nconst payloadObj = JSON.parse(payload);\nconst timestamp = new Date(payloadObj.timestamp);\nconst now = new Date();\nconst isRecent = (now - timestamp) < 60000; // 60 second default window\n```\n\n**Configurable freshness window:** The 60-second window is configurable via the `VerifyOptions` parameter:\n```typescript\n// Default 60-second window\nconst result = verify({ headers });\n\n// Custom 2-minute window for high-latency networks\nconst result = verify({ headers }, { freshness: 120000 });\n\n// Stricter 30-second window for high-security applications \nconst result = verify({ headers }, { freshness: 30000 });\n```\n\nThis flexibility allows applications to adjust based on their network conditions, security requirements, and clock synchronization tolerance. Most applications can use the 60-second default, which is more conservative than industry standards (AWS: 15 minutes, Google: 15 minutes) while accommodating typical network latency and clock drift.\n\n**4. Identity extraction:** Generate the AgentAuth ID\n```typescript\nif (signatureValid && isRecent) {\n const agentId = generateId(address); // Deterministic UUID generation\n // Agent authenticated! Use agentId as user identifier\n}\n```\n\n**Why this approach:**\n- **Stateless verification:** No server-side session storage needed\n- **Standard cryptography:** Uses proven signature verification techniques\n- **Replay protection:** Timestamp validation prevents old requests\n- **Immediate identity:** Can extract stable UUID for database use\n\n### Complete Authentication Flow\n\nHere's how all the pieces work together in a real authentication scenario:\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant MCP_Proxy as @agentauth/mcp\n participant MCP_Server as @agentauth/sdk\n participant App as MCP Server App\n\n Agent->>MCP_Proxy: Request with AGENTAUTH_TOKEN\n MCP_Proxy->>MCP_Proxy: Generate timestamp payload\n MCP_Proxy->>MCP_Proxy: Sign payload with AgentAuth Token\n MCP_Proxy->>MCP_Server: HTTP request + AgentAuth headers\n MCP_Server->>MCP_Server: Verify signature & freshness using AgentAuth Address\n MCP_Server->>MCP_Server: Extract AgentAuth ID\n MCP_Server->>App: provide(agentauth_id: \"811ec2bf...\")\n App->>App: Use UUID for database operations\n App->>MCP_Server: Response based on agent identity\n MCP_Server->>MCP_Proxy: HTTP response\n MCP_Proxy->>Agent: Tool response\n```\n\nThis end-to-end flow ensures that:\n- Agents never send private keys over the network\n- Servers get a stable, verified identity for each agent\n- No centralized auth service is required\n- The system works entirely over standard HTTP\n\n## API Reference\n\n### `generateIdentity(algorithm?: Algorithm)`\n\nGenerates a complete AgentAuth identity including private key, address, and deterministic ID.\n\n**Parameters:**\n- `algorithm`: Currently only supports `'secp256k1'` (default)\n\n**Returns:**\n```typescript\n{\n agentauth_token: string; // Private key with aa- prefix\n agentauth_address: string; // Ethereum-compatible address with 0x prefix\n agentauth_id: string; // UUID v5\n}\n```\n\n**Example:**\n```typescript\nconst identity = generateIdentity();\n// Store identity.agentauth_token securely!\n// Use identity.agentauth_id as the public identifier\n```\n\n### `deriveAddress(privateKey: string)`\n\nDerives an Ethereum-compatible address from a private key.\n\n**Parameters:**\n- `privateKey`: Private key in any format (aa-, 0x, or raw hex)\n\n**Returns:**\n- Ethereum-compatible address with 0x prefix (20 bytes)\n\n**Example:**\n```typescript\nconst address = deriveAddress('aa-2337...');\n// '0x9906322508aa2d8cbf24c33751015162d58285ce'\n```\n\n### `generateId(address: string)`\n\nGenerates a deterministic UUID v5 from an address.\n\n**Parameters:**\n- `address`: Ethereum-compatible address (0x-prefixed)\n\n**Returns:**\n- UUID v5 string\n\n**Example:**\n```typescript\nconst id = generateId('0x9906322508aa2d8cbf24c33751015162d58285ce');\n// '811ec2bf-b653-573a-b2ea-6ff4df9fdad7'\n```\n\n### `signPayload(payload: object, privateKey: string)`\n\nSigns a JSON payload using a private key.\n\n**Parameters:**\n- `payload`: JSON object to sign\n- `privateKey`: Private key in any format\n\n**Returns:**\n- Hex-encoded signature with 0x prefix (65 bytes)\n\n**Example:**\n```typescript\nconst signature = signPayload({ msg: 'hello' }, privateKey);\n// '0x1234...abcd'\n```\n\n### `verifySignature(signature: string, payload: object, expectedAddress: string)`\n\nVerifies a signature against a payload and expected address.\n\n**Parameters:**\n- `signature`: Hex-encoded signature with 0x prefix\n- `payload`: Original JSON payload\n- `expectedAddress`: Expected Ethereum-compatible address\n\n**Returns:**\n- Boolean indicating validity\n\n**Example:**\n```typescript\nconst isValid = verifySignature(signature, payload, address);\n// true\n```\n\n### `parsePrivateKey(token: string)`\n\nUtility function to parse private keys from any supported format.\n\n**Parameters:**\n- `token`: Private key with aa-, 0x, or no prefix\n\n**Returns:**\n- Clean 32-byte hex string (64 characters)\n\n**Example:**\n```typescript\nparsePrivateKey('aa-2337...'); // '2337...'\nparsePrivateKey('0x2337...'); // '2337...'\nparsePrivateKey('2337...'); // '2337...'\n```\n\n## Common Patterns\n\n### Identity Storage\n\nStore only what you need:\n\n```typescript\n// For servers: Store the UUID as user identifier\nconst identity = generateIdentity();\nawait db.users.create({\n id: identity.agentauth_id,\n created: new Date()\n});\n\n// For clients: Store the private key securely\nconst identity = generateIdentity();\nawait secureStorage.set('agentauth_token', identity.agentauth_token);\n```\n\n### Authentication Flow\n\nBuild a simple authentication system:\n\n```typescript\n// Client side: Sign authentication request\nconst authPayload = {\n timestamp: new Date().toISOString()\n};\nconst signature = signPayload(authPayload, privateKey);\nconst address = deriveAddress(privateKey);\n\n// Send to server: { address, signature, payload: authPayload }\n\n// Server side: Verify and extract ID\nconst isValid = verifySignature(signature, authPayload, address);\nif (isValid) {\n const agentId = generateId(address);\n // Authenticated! Use agentId as user identifier\n}\n```\n\n### Key Format Handling\n\nThe library accepts multiple key formats for compatibility:\n\n```typescript\n// All these are equivalent\nconst key1 = 'aa-2337b9fa957a201db466a58065529dc40362e008d3f41655651b96b2abbcb602';\nconst key2 = '0x2337b9fa957a201db466a58065529dc40362e008d3f41655651b96b2abbcb602';\nconst key3 = '2337b9fa957a201db466a58065529dc40362e008d3f41655651b96b2abbcb602';\n\n// All will produce the same address\nderiveAddress(key1) === deriveAddress(key2) === deriveAddress(key3);\n```\n\n## Security Notes\n\n- **Private keys** (`agentauth_token`) should be kept secret and stored securely\n- **Deterministic generation** means same private key always produces same ID\n- **No random salts** in signatures β include timestamp in payload for replay protection\n- **Ethereum compatibility** allows integration with existing Ethereum development tools for testing and debugging\n- **Noble libraries** provide audited, constant-time implementations\n\n## TypeScript Support\n\nFull TypeScript support with exported types:\n\n```typescript\nimport type { Algorithm } from '@agentauth/core';\n\n// Currently only 'secp256k1' is supported\nconst algo: Algorithm = 'secp256k1';\n```\n\n## Testing\n\nRun the test suite:\n\n```bash\nnpm test\n```\n\n## Contributing\n\nAgentAuth ID is an early-stage open-source project maintained by the AgentAuth team. We welcome bug reports, feature suggestions, and early feedback via [GitHub Issues](https://github.com/agentauthco/agentauth/issues). You can also reach out at [developers@agentauth.co](mailto:developers@agentauth.co?subject=Contributing%20to%20AgentAuth) if you are interested in contributing.\n\n## License\n\nMIT License β see [LICENSE](https://github.com/agentauthco/agentauth/blob/main/LICENSE) for details.\n\n## Links\n\n- **Website** β [agentauth.co](https://agentauth.co)\n- **Documentation** β [docs.agentauth.co](https://docs.agentauth.co) \n- **GitHub** β [agentauthco/agentauth](https://github.com/agentauthco/agentauth)\n- **npm** β [@agentauth/core](https://www.npmjs.com/package/@agentauth/core)\n\n---\n\n**Built by [AgentAuth](https://agentauth.co)** β The Collaboration Layer for AI Agents.\n","readmeFilename":"README.md"}