{"_id":"@agentic-name-service/sdk","_rev":"2-a291333919adf3be69629cc28352beab","name":"@agentic-name-service/sdk","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@agentic-name-service/sdk","version":"0.1.0","keywords":["agentic-name-service","ans","mcp","agent-authentication","trilateral-handshake"],"license":"MIT","_id":"@agentic-name-service/sdk@0.1.0","maintainers":[{"name":"agentic_name_service","email":"agenticuns@gmail.com"}],"homepage":"https://github.com/UNS4Agentics/agenticnameservice#readme","bugs":{"url":"https://github.com/UNS4Agentics/agenticnameservice/issues"},"dist":{"shasum":"3c3d21b1480b0bab1b856c8bf6e8c6d545f176b3","tarball":"https://registry.npmjs.org/@agentic-name-service/sdk/-/sdk-0.1.0.tgz","fileCount":6,"integrity":"sha512-5ey41ZDVwiGGsZtF01WEKygTniDsiM48PjmVG7qKT1RlDNZo8B7tljddQiN9teGCbE6vfVyTABgpxgZrY/R8bg==","signatures":[{"sig":"MEUCICLi4Rohfy/aGCTmIE5l0pTniaDVycRimY2ADECgb65gAiEA+nVNxTyqFDz5ehASwCxn51H+3yfP6YHc5SS8yNGYdtk=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":31255},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"}}},"gitHead":"87d062079629f4c4e8a2e830871abfcc4f6ecb42","scripts":{"lint":"eslint src/","test":"vitest run","build":"tsc","typecheck":"tsc --noEmit","prepublishOnly":"pnpm build"},"_npmUser":{"name":"agentic_name_service","email":"agenticuns@gmail.com"},"repository":{"url":"git+https://github.com/UNS4Agentics/agenticnameservice.git","type":"git","directory":"packages/agent-sdk"},"_npmVersion":"10.8.2","description":"Official Agent SDK for the Agentic Name Service (ANS) — orchestrates MCP tool calls across Gateway and Guardian for trilateral authentication","directories":{},"_nodeVersion":"20.20.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.1.0","typescript":"^5.8.0"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.1.0_1775199745029_0.13516208046159117","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@agentic-name-service/sdk","version":"0.2.0","description":"Official Agent SDK for the Agentic Name Service (ANS) — orchestrates MCP tool calls across Gateway and Guardian for trilateral authentication","type":"module","main":"dist/index.js","types":"dist/index.d.ts","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"}}},"scripts":{"build":"tsc","test":"vitest run","lint":"eslint src/","typecheck":"tsc --noEmit","prepublishOnly":"pnpm build"},"keywords":["agentic-name-service","ans","mcp","agent-authentication","trilateral-handshake"],"license":"MIT","repository":{"type":"git","url":"git+https://github.com/UNS4Agentics/agenticnameservice.git","directory":"packages/agent-sdk"},"publishConfig":{"access":"public"},"devDependencies":{"typescript":"^5.8.0","vitest":"^3.1.0"},"_id":"@agentic-name-service/sdk@0.2.0","gitHead":"86b26ce06d08054ef1ad52d6047746d3dd397d68","bugs":{"url":"https://github.com/UNS4Agentics/agenticnameservice/issues"},"homepage":"https://github.com/UNS4Agentics/agenticnameservice#readme","_nodeVersion":"20.20.1","_npmVersion":"10.8.2","dist":{"integrity":"sha512-HX6tbBts4xFSlUVYzIEGU/8Oav8LwpQxrI1ZFCmecrEU5ZQKl1yzl8/duuS10nzxDy889SbAtDhzHmYzBKzC8Q==","shasum":"bebdf520d80159dfa9024196596974f675bf10e2","tarball":"https://registry.npmjs.org/@agentic-name-service/sdk/-/sdk-0.2.0.tgz","fileCount":6,"unpackedSize":31581,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIBMEZ3qt+EKX2do6BA/FVohS0gFo+xazV1waCiDPdUIKAiEA5i5Ue6syvEb4jpgrO38IRYLt4dy/iV1tpZJB5XOknpA="}]},"_npmUser":{"name":"agentic_name_service","email":"agenticuns@gmail.com"},"directories":{},"maintainers":[{"name":"agentic_name_service","email":"agenticuns@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.2.0_1775305288982_0.4699410828363475"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-03T07:02:24.924Z","modified":"2026-04-04T12:21:29.322Z","0.1.0":"2026-04-03T07:02:25.163Z","0.2.0":"2026-04-04T12:21:29.183Z"},"bugs":{"url":"https://github.com/UNS4Agentics/agenticnameservice/issues"},"license":"MIT","homepage":"https://github.com/UNS4Agentics/agenticnameservice#readme","keywords":["agentic-name-service","ans","mcp","agent-authentication","trilateral-handshake"],"repository":{"type":"git","url":"git+https://github.com/UNS4Agentics/agenticnameservice.git","directory":"packages/agent-sdk"},"description":"Official Agent SDK for the Agentic Name Service (ANS) — orchestrates MCP tool calls across Gateway and Guardian for trilateral authentication","maintainers":[{"name":"agentic_name_service","email":"agenticuns@gmail.com"}],"readme":"# Agentic Name Service Agent SDK\n\nTypeScript client for AI agents to authenticate via the ANS trilateral handshake protocol. Wraps 7 MCP tool calls into a single `authenticate()` function.\n\n## Install\n\n```bash\nnpm install @agentic-name-service/sdk\n```\n\n## Quick Start\n\n```typescript\nimport { AgentClient } from '@agentic-name-service/sdk';\n\nconst agent = new AgentClient({\n  gatewayUrl: 'https://gateway.agenticnameservice.ai',\n  guardianUrl: 'https://guardian.agenticnameservice.ai',\n});\n\n// Full trilateral handshake — one call\nconst result = await agent.authenticate('my-service', {\n  onOobRequired: (id, url) => console.log(`Approve at: ${url}`),\n});\n\nconsole.log(`Authenticated! Receipt: ${result.receipt_id}`);\n```\n\n## What MCP Native Means\n\nThe Agentic Name Service was designed MCP-first. Every Gateway and Guardian exposes MCP tools as its primary interface — REST endpoints exist for human operators and debugging, but agents operate via MCP.\n\nThe Agent SDK wraps **7 MCP tool calls** across two nodes into a single `authenticate()` function. Under the hood, it orchestrates:\n\n1. `get_service_manifest` (Gateway) — fetch service metadata\n2. `get_uns_challenge` (Gateway) — get signed cryptographic challenge\n3. `sign_token_request` (Guardian) — relay challenge, get Guardian signature\n4. `check_oob_status` (Guardian) — poll if human approval is needed\n5. `submit_signed_token` (Gateway) — complete handshake, get receipt\n\nHuman developers can use REST to test and debug. Agents operate via MCP — and this SDK handles the orchestration.\n\n### Orchestration Flow\n\n```\nAgent SDK                    Gateway (MCP)              Guardian (MCP)\n    |                            |                          |\n    |-- get_service_manifest -->|                          |\n    |<-- manifest + rules ------|                          |\n    |                            |                          |\n    |-- get_uns_challenge ----->|                          |\n    |<-- signed challenge ------|                          |\n    |                            |                          |\n    |-- sign_token_request -------------------------------->|\n    |<-- signed_token | pending_approval ------------------|\n    |                            |                          |\n    |   [if pending_approval]    |                          |\n    |-- check_oob_status (poll) --------------------------->|\n    |<-- approved ------------------------------------------|\n    |                            |                          |\n    |-- submit_signed_token --->|                          |\n    |<-- receipt ----------------|                          |\n```\n\n## API Reference\n\n### `new AgentClient(config: AgentConfig)`\n\nCreate a new agent client.\n\n```typescript\ninterface AgentConfig {\n  gatewayUrl: string;       // Gateway base URL\n  guardianUrl: string;      // Guardian base URL\n  pollInterval?: number;    // OOB polling interval in ms (default: 2000)\n  maxOobWait?: number;      // Max OOB wait in ms (default: 120000)\n}\n```\n\n### `agent.authenticate(serviceName, options?)`\n\nPerform the full 7-step trilateral handshake. Returns a receipt on success.\n\n```typescript\nconst result = await agent.authenticate('my-service', {\n  serviceAccountId: 'optional-existing-account-id',\n  requestContext: { action: 'transfer', amount: 100 },\n  onOobRequired: (oobRequestId, approvalUrl) => {\n    // Show the user where to approve\n  },\n});\n// result: { receipt_id: string, status: \"authorized\" }\n```\n\n### `agent.getManifest(serviceName)`\n\nFetch a service's manifest from the Gateway. Returns service metadata, attestation requirements, and supported OOB methods.\n\n### `agent.registerService(serviceName)`\n\nRegister a service with the Guardian. Fetches the manifest from the Gateway and creates a local service account on the Guardian. Required before first authentication.\n\n### `agent.getStatus()`\n\nCheck the Gateway's registration status and operational info.\n\n## Error Handling\n\nAll errors throw `AgentError` with a machine-readable `code`:\n\n```typescript\nimport { AgentError } from '@agentic-name-service/sdk';\n\ntry {\n  await agent.authenticate('my-service');\n} catch (err) {\n  if (err instanceof AgentError) {\n    console.error(err.code);    // e.g., \"ANS_SIGNATURE_INVALID\"\n    console.error(err.message); // Human-readable description\n  }\n}\n```\n\nCommon error codes:\n\n| Code | Meaning |\n|------|---------|\n| `ANS_SERVICE_NOT_FOUND` | Service not registered on Gateway |\n| `ANS_SIGNATURE_INVALID` | Cryptographic signature verification failed |\n| `ANS_USER_DECLINED` | User rejected the OOB approval |\n| `ANS_HANDSHAKE_TIMEOUT` | OOB approval timed out |\n| `ANS_NONCE_EXPIRED` | Challenge nonce expired (5 min TTL) |\n| `ANS_ATTESTATION_LEVEL_MISMATCH` | Provided attestation weaker than required |\n\n## Tutorial\n\nNew to the Agentic Name Service? Follow the step-by-step tutorial to go from zero to a working handshake receipt in under 30 minutes:\n\n**[Register Your First Service](../../docs/tutorial_register_your_first_service.md)**\n\nA runnable example project is also available at [`examples/first-handshake/`](../../examples/first-handshake/).\n\n## OOB Approval\n\nWhen a service requires attestation above `session_only`, the Guardian may need human approval (Out-of-Band). The SDK handles this automatically:\n\n1. `sign_token_request` returns `status: \"pending_approval\"`\n2. SDK calls your `onOobRequired` callback with the approval URL\n3. SDK polls `check_oob_status` every `pollInterval` ms\n4. When approved, SDK re-signs and submits the token\n5. If rejected or timed out, throws `AgentError`\n\n```typescript\nawait agent.authenticate('bank-service', {\n  onOobRequired: (id, url) => {\n    // Display to user: \"Please approve at {url}\"\n    // The Guardian dashboard shows the pending request\n  },\n});\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}