@agenticprimitives/agent-naming 0.1.0-alpha.2

package/docs/migration.md

@@ -0,0 +1,93 @@
+# Agent Naming Migration Notes
+
+## Current Status
+
+`@agenticprimitives/agent-naming` is experimental. Public helpers, record
+schemas, ABIs, and call builders are present, but contract deployments and demo
+wiring may still change before a stable release.
+
+## Versioning Policy
+
+Before `1.0`, breaking changes may happen when:
+
+- the contract ABI changes
+- record predicates change
+- normalization rules change
+- the client write path changes
+- package-boundary rules move logic to another package
+
+Every breaking change should update:
+
+1. `README.md`
+2. `docs/api.md`
+3. `docs/security.md` when invariants change
+4. `capability.manifest.json`
+5. tests or examples that show the changed path
+
+## Canonical-Identifier-First Wiring
+
+New integrations should follow [spec 220](../../../specs/220-agent-identity-bootstrap.md):
+
+1. Deploy or resolve the Smart Agent (`agent-account`) — canonical `Address`.
+2. Register a forced-unique `.agent` name pointing at that address (this package).
+3. Enroll custodians (`custody` + `identity-auth` ceremonies).
+4. Optionally publish a profile (`agent-identity`).
+
+Display both in UI:
+
+```text
+Canonical Agent ID: eip155:84532:0x…
+Name:               alice.agent   (facet — may be alice2.agent if taken)
+```
+
+## From Ad Hoc Address Config To Names
+
+Old app wiring often carries raw addresses and endpoint URLs in local config:
+
+```ts
+const treasury = '0x...';
+const mcpEndpoint = 'https://...';
+```
+
+New wiring should resolve through names and records:
+
+```ts
+const treasury = await naming.resolveName('treasury.acme.agent');
+const records = await naming.getRecords('treasury.acme.agent');
+```
+
+Keep raw addresses as fallback diagnostics, not primary UI.
+
+## From Metadata-Only Profiles To Typed Records
+
+Use resolver records for small, frequently-read discovery fields:
+
+- `addr`
+- `displayName`
+- `agentKind`
+- `a2aEndpoint`
+- `mcpEndpoint`
+- `nativeId`
+
+Use `metadataUri` plus `metadataHash` for larger profile documents.
+
+## From Direct Writes To Encoded Calls
+
+When writes need custom submission, prefer call builders:
+
+```ts
+const call = buildRotateNameResolverCall({ registry, node, newResolver });
+```
+
+Then submit the call through the appropriate Smart Agent, relayer, or account
+policy path.
+
+## Future Migration Hooks
+
+Expected future migration areas:
+
+- IDN/punycode support beyond ASCII labels.
+- Generated API docs or manifest-doc synchronization.
+- Example typecheck enforcement.
+- Stable deployment address package.
+- Optional compatibility layer for external ENS resolvers.

package/docs/security.md

@@ -0,0 +1,127 @@
+# Agent Naming Security
+
+This package is a **facet registry**, not the identity anchor. Treat names as
+user-facing labels; bind authority to Smart Agent addresses and contract checks
+([ADR-0010](../../../docs/architecture/decisions/0010-smart-agent-canonical-identifier.md)).
+
+## Read-Path Discipline (No Log Scans)
+
+Binding: [ADR-0012](../../../docs/architecture/decisions/0012-no-eth-getlogs-in-product-read-paths.md).
+
+Product reads must use `readContract` only:
+
+- `resolveName` and `getRecords` — compliant.
+- `reverseResolve` — on-chain round-trip uses `readContract`; returning the
+  dotted string currently uses **chunked `eth_getLogs`** in `_reconstructName`
+  (**transitional debt** — do not add more log walkers).
+
+Approved exits: store plaintext `label` on chain, or a naming indexer, or app
+cache after registration. Chunking log ranges does not make log scans an
+acceptable long-term pattern.
+
+## Deterministic Normalization
+
+Every name must normalize the same way on every runtime:
+
+1. NFC normalize.
+2. Trim whitespace.
+3. Lowercase.
+4. Validate labels.
+
+Two strings that normalize identically must produce the same `namehash`.
+
+Phase 1 uses ASCII-only labels to avoid Unicode spoofing and homoglyph attacks.
+Do not loosen this until the package has a full IDN/punycode policy and golden
+vectors.
+
+## Forward And Reverse Resolution
+
+Forward resolution answers:
+
+```text
+name -> address
+```
+
+Reverse resolution answers:
+
+```text
+address -> primary name
+```
+
+Reverse resolution is only trustworthy when it round-trips:
+
+```text
+reverseResolve(address) -> name
+resolveName(name) -> same address
+```
+
+This prevents a malicious account from claiming someone else's name as its
+primary name.
+
+## Unknown Predicates
+
+The record layer has asymmetric behavior:
+
+- Encode side is strict. Unknown fields are not representable through
+  `AgentNameRecords` and known fields are validated before encoding.
+- Decode side is forward-compatible. Unknown predicate ids are ignored.
+
+This prevents clients from accidentally writing unsupported records while still
+allowing older readers to survive newer resolver schemas.
+
+## Passkey Material
+
+Never store raw passkey credential IDs in naming records.
+
+The only passkey-related record is `passkeyCredentialDigest`, a `bytes32` hash
+of the credential ID. Use it for UI correlation only, not as an auth secret.
+
+## CAIP-10 Native ID
+
+`nativeId` must match CAIP-10 grammar on encode:
+
+```text
+namespace:reference:account
+```
+
+Phase 1 encode-side namespaces are allowlisted:
+
+- `eip155`
+- `hedera`
+- `solana`
+
+`eip155` account addresses are lowercased during encode. Decode remains more
+permissive so clients do not fail on future namespaces.
+
+## Endpoint Records
+
+`a2aEndpoint` and `mcpEndpoint` are discovery records. They tell clients where
+an agent service claims to be reachable.
+
+They do not prove endpoint control. If a product needs endpoint-control proof,
+compose with `@agenticprimitives/agent-profile` verification methods.
+
+## Naming Is Not Account Safety Policy
+
+This package can build calls that rotate name owners, resolvers, records, and
+subregistries. It does not decide who is allowed to submit those calls.
+
+Authorization lives in the owner Smart Agent and its account safety policy. The
+call builders return encoded calldata only; transaction submission and approval
+flows happen outside this package.
+
+## Subregistries
+
+Subregistries can make child-name issuance easier, but they change the authority
+model for a whole subtree.
+
+Before setting a subregistry, decide:
+
+- who can register children
+- whether registration requires a credential, invite, fee, or stake
+- whether names expire
+- how disputes and reserved names are handled
+- whether the subtree should ever become permissionless
+
+For organization/service namespaces, prefer permissioned or credential-gated
+subregistries unless anti-spam rules are already deployed.

package/docs/troubleshooting.md

@@ -0,0 +1,116 @@
+# Agent Naming Troubleshooting
+
+## `InvalidNameError`
+
+The name failed normalization.
+
+Common causes:
+
+- empty string
+- leading or trailing dot
+- consecutive dots
+- label starts or ends with `-`
+- non-ASCII character
+- label longer than 63 characters
+
+Use `isValidAgentName(name)` for UI validation and `normalizeAgentName(name)`
+when you want the canonical value or a detailed thrown error.
+
+## `resolveName(name)` Returns `null`
+
+Possible causes:
+
+- the name is not registered
+- the name has no resolver
+- the resolver has no `addr` record
+- the configured registry/universal resolver addresses point to the wrong chain
+
+Check `chainId`, `registry`, `universalResolver`, and the normalized name.
+
+## `reverseResolve(address)` Returns `null`
+
+Possible causes:
+
+- the address has no primary name
+- the primary name node cannot be reconstructed from registry events
+- round-trip verification failed
+
+Round-trip failure means the primary name points somewhere else or no longer
+resolves to the given address.
+
+## Empty Records From `getRecords(name)`
+
+An empty object means no known records were read. Common causes:
+
+- no resolver is set
+- records have not been written
+- the resolver is on a different chain
+- records exist only under newer predicates this SDK does not know yet
+
+Unknown predicates are ignored on decode by design.
+
+## Unknown Predicate Dropped On Decode
+
+This is expected. Decode is forward-compatible and silently ignores unknown
+predicate ids.
+
+If the record should be first-class, add it to:
+
+1. `src/types.ts`
+2. `src/records.ts`
+3. `test/records.test.ts`
+4. `docs/api.md`
+5. `capability.manifest.json`
+
+## Unknown Or Invalid Record Rejected On Encode
+
+Encode is strict. Known fields validate their expected shape:
+
+- addresses must be 20-byte hex strings
+- `bytes32` values must be 32-byte hex strings
+- `agentKind` must be `person`, `org`, or `service` (a treasury is a `service`
+  agent; the `treasury` distinction lives on the profile, not the agent kind)
+- `nativeId` must match CAIP-10 grammar and use an allowed namespace
+
+## Native ID Validation Failed
+
+Expected shape:
+
+```text
+eip155:84532:0x0000000000000000000000000000000000000003
+```
+
+`nativeId` must match the `addr` record for the same Smart Agent on EVM chains.
+If you need a new CAIP-10 namespace, add it deliberately to
+`CAIP10_NAMESPACE_ALLOWLIST` and include a test vector.
+
+## Resolver Unset
+
+`setAgentRecords` requires the name to have a resolver. Install a resolver
+through registry owner flow before writing records.
+
+## Subregistry Unset
+
+If a parent has no subregistry, child registration falls back to parent-owner
+authorization. If a product expects permissionless or credential-gated child
+registration, confirm `setSubregistry` has been applied to the parent node.
+
+## Transaction Write Fails
+
+The client write methods submit raw encoded calls through the supplied
+`walletClient`. The caller must be authorized by the contracts.
+
+If writes need to pass through a Smart Agent, relayer, or scheduled approval
+flow, use the pure call builders in `@agenticprimitives/agent-naming/custody`
+and submit them through that external flow.
+
+## Confused Name With Identity
+
+Symptom: CREATE2 address changes when the user picks a different `.agent` label,
+or APIs accept only a name string with no `Address`.
+
+Fix:
+
+- Deploy / resolve the Smart Agent first (`agent-account`).
+- Register the name as a facet pointing at that address.
+- Never derive CREATE2 salt from the chosen `.agent` name ([spec 220](../../../specs/220-agent-identity-bootstrap.md)).

package/examples/basic.ts

@@ -0,0 +1,31 @@
+import {
+  AgentNamingClient,
+  labelhash,
+  namehash,
+  normalizeAgentName,
+} from '@agenticprimitives/agent-naming';
+
+const normalized = normalizeAgentName('  Treasury.Acme.Agent  ');
+const labelNode = labelhash('treasury');
+const nameNode = namehash(normalized);
+
+console.log({ normalized, labelNode, nameNode });
+
+const naming = new AgentNamingClient({
+  rpcUrl: 'https://base-sepolia.example/rpc',
+  chainId: 84532,
+  registry: '0x0000000000000000000000000000000000000001',
+  universalResolver: '0x0000000000000000000000000000000000000002',
+});
+
+async function main() {
+  const address = await naming.resolveName('treasury.acme.agent');
+  const records = await naming.getRecords('treasury.acme.agent');
+
+  if (address) {
+    const primaryName = await naming.reverseResolve(address);
+    console.log({ address, primaryName, records });
+  }
+}
+
+void main();

package/examples/custody-rotation.ts

@@ -0,0 +1,44 @@
+import { namehash } from '@agenticprimitives/agent-naming';
+import {
+  buildRecordCalls,
+  buildRotateNameOwnerCall,
+  buildRotateNameResolverCall,
+  buildSetPrimaryNameCall,
+} from '@agenticprimitives/agent-naming/custody';
+
+const registry = '0x0000000000000000000000000000000000000001';
+const resolver = '0x0000000000000000000000000000000000000002';
+const newOwner = '0x0000000000000000000000000000000000000003';
+const node = namehash('treasury.acme.agent');
+
+// These are pure encoded calls. Submit them through your own transaction path:
+// a Smart Agent execute call, a relayer, or an account-safety approval flow.
+const rotateOwner = buildRotateNameOwnerCall({
+  registry,
+  node,
+  newOwner,
+});
+
+const rotateResolver = buildRotateNameResolverCall({
+  registry,
+  node,
+  newResolver: resolver,
+});
+
+const setPrimaryName = buildSetPrimaryNameCall({
+  registry,
+  node,
+});
+
+const recordCalls = buildRecordCalls({
+  resolver,
+  node,
+  records: {
+    addr: newOwner,
+    agentKind: 'service', // treasury is a service subtype (profile), not an agent kind
+    displayName: 'Acme Treasury',
+    nativeId: `eip155:84532:${newOwner}`,
+  },
+});
+
+console.log([rotateOwner, rotateResolver, setPrimaryName, ...recordCalls]);

package/examples/records.ts

@@ -0,0 +1,41 @@
+import {
+  AGENT_KIND_ID,
+  PREDICATE_ID,
+  decodeRecords,
+  encodeRecords,
+} from '@agenticprimitives/agent-naming/records';
+
+const agentAddress = '0x0000000000000000000000000000000000000003';
+
+const encoded = encodeRecords({
+  addr: agentAddress,
+  // A treasury is a SERVICE agent (agentKind='service'); 'treasury' is a profile
+  // subtype (ProfileType/serviceType), not an agent kind (specs 210/217/225 §6).
+  agentKind: 'service',
+  displayName: 'Acme Treasury',
+  a2aEndpoint: 'https://a2a.acme.example',
+  mcpEndpoint: 'https://mcp.acme.example',
+  metadataUri: 'https://metadata.acme.example/treasury.json',
+  metadataHash: '0x1111111111111111111111111111111111111111111111111111111111111111',
+  passkeyCredentialDigest: '0x2222222222222222222222222222222222222222222222222222222222222222',
+  custodyPolicy: '0x0000000000000000000000000000000000000004',
+  nativeId: `eip155:84532:${agentAddress}`,
+});
+
+console.log(encoded);
+
+const decoded = decodeRecords({
+  strings: {
+    [PREDICATE_ID.displayName]: 'Acme Treasury',
+    [PREDICATE_ID.a2aEndpoint]: 'https://a2a.acme.example',
+    [PREDICATE_ID.nativeId]: `eip155:84532:${agentAddress}`,
+  },
+  addresses: {
+    [PREDICATE_ID.addr]: agentAddress,
+  },
+  bytes32s: {
+    [PREDICATE_ID.agentKind]: AGENT_KIND_ID.service,
+  },
+});
+
+console.log(decoded);

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@agenticprimitives/agent-naming",
+  "version": "0.1.0-alpha.2",
+  "description": "Agent Naming Service SDK: ENS-v2-style hierarchical naming for Smart Agents (.agent TLD). Owns name normalization, namehash/labelhash, records schemas, and the AgentNamingClient (resolve / reverse / registry). Speaks naming-domain vocabulary only \u2014 no delegation / caveat / custody concepts.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agentictrustlabs/agenticprimitives.git",
+    "directory": "packages/agent-naming"
+  },
+  "homepage": "https://github.com/agentictrustlabs/agenticprimitives/tree/master/packages/agent-naming",
+  "bugs": {
+    "url": "https://github.com/agentictrustlabs/agenticprimitives/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./records": {
+      "types": "./dist/records.d.ts",
+      "import": "./dist/records.js"
+    },
+    "./custody": {
+      "types": "./dist/custody.d.ts",
+      "import": "./dist/custody.js"
+    }
+  },
+  "files": [
+    "LICENSE",
+    "dist",
+    "docs",
+    "examples",
+    "spec.md",
+    "README.md",
+    "AUDIT.md",
+    "CLAUDE.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:unit": "vitest run test/normalize.test.ts test/namehash.test.ts test/records.test.ts",
+    "test:integration": "vitest run test/integration.test.ts",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@agenticprimitives/agent-account": "workspace:*",
+    "@agenticprimitives/connect-auth": "workspace:*",
+    "@agenticprimitives/types": "workspace:*",
+    "viem": "^2.50.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.0",
+    "vitest": "^2.1.0"
+  },
+  "keywords": [
+    "agent",
+    "naming",
+    "ens",
+    "smart-agent",
+    "agentic"
+  ]
+}

package/spec.md

@@ -0,0 +1,14 @@
+# @agenticprimitives/agent-naming — spec
+
+The full design lives in [`../../specs/215-agent-naming.md`](../../specs/215-agent-naming.md).
+
+Architecture decisions:
+
+- [ADR-0006](../../docs/architecture/decisions/0006-agent-naming-as-resolution-layer.md)
+  — naming as resolution layer via NameContext injection (no
+  back-edges from downstream packages).
+- [ADR-0008](../../docs/architecture/decisions/0008-caip10-nativeid-record-predicate.md)
+  — `native-id` predicate carries CAIP-10 (HCS-14 interop) without
+  UAID derivation.
+
+Do not edit a divergent copy here — edit the canonical spec.