@agenticprimitives/agent-naming 0.1.0-alpha.2

package/AUDIT.md

@@ -0,0 +1,86 @@
+# @agenticprimitives/agent-naming — package audit
+
+**Status:** Phase 1 (SDK skeleton + spec + pure helpers).
+**Last refreshed:** 2026-05-23.
+**Owner:** [security-auditor](../../docs/agents/security-auditor.md) +
+[technical-architect-auditor](../../docs/agents/technical-architect-auditor.md).
+**System audit cross-ref:** see
+[`docs/architecture/product-readiness-audit.md`](../../docs/architecture/product-readiness-audit.md)
+and the [evidence checklist](../../docs/audits/evidence-checklist.md).
+
+This audit is Phase-1 scope only. Findings against contract behavior,
+on-chain authority paths, and demo integration land in Phase 3+.
+
+## Charter (what's audit-relevant in this package)
+
+- Pure helpers (`normalizeAgentName`, `labelhash`, `namehash`): MUST
+  be deterministic + match the reference ENS algorithm + reject
+  malformed input.
+- Record schema (`AgentNameRecords` + `records` subpath): MUST
+  refuse unknown keys on encode (fail-loud write) AND drop unknown
+  keys on decode (fail-closed read).
+- `AgentNamingClient` (Phase 1 skeleton): MUST throw clearly when
+  invoked before contract wiring, so a Phase-1 consumer can't
+  silently get a no-op call.
+- Vocabulary firewall against `delegation`, `account-custody`, `mcp-runtime`,
+  `tool-policy`, `key-custody`, `audit`, and MCP transport.
+
+## Findings (Phase 1)
+
+| ID | Severity | Finding | Evidence | Status |
+| --- | --- | --- | --- | --- |
+| **AN-1** | P2 | Lowercase normalization uses `String.prototype.toLowerCase`, which has Turkish-locale-specific edge cases for `İ → i` mapping. Phase 1 labels are ASCII-only so the practical risk is zero, but the locale-sensitivity is worth either documenting OR replacing with a locale-explicit map. | `src/normalize.ts:21` | open — Phase 1 acceptable (ASCII-only labels in `LABEL_RE`). Revisit when Phase 2 expands to Punycode/IDN. |
+| **AN-2** | P2 | The package depends on `@agenticprimitives/agent-account` for ERC-1271 verification, but the Phase 1 client doesn't yet exercise it (writes throw). The dependency is declared early to lock the boundary; verify in Phase 2 that the import remains narrow (`AgentAccountClient` only, no transitive widening). | `package.json` peerDependencies; `capability.manifest.json:imports` | open — track in Phase 2 review. |
+| **AN-3** | P3 | Multi-root TLD support exists in the contract design (per smart-agent port) but the package surface restricts to `.agent`. A future TLD addition (e.g. `.org-agent`) requires both the contract `initializeRoot` AND a surface change here. Make sure the surface change is intentional + spec'd, not snuck in. | `src/constants.ts:8` | open — design-time control; no current risk. |
+
+## Phase-1 security invariants (verified by tests)
+
+- ✅ `normalize` rejects empty / leading-hyphen / trailing-hyphen /
+  non-ASCII / oversize labels. Throws `InvalidNameError`. Covered in
+  `test/normalize.test.ts`.
+- ✅ `normalize` is idempotent: `normalize(normalize(x)) === normalize(x)`.
+- ✅ `namehash('')` = `ZERO_NODE` (`0x00…00`) per the ENS sentinel
+  convention.
+- ✅ `namehash` matches the ENS reference algorithm under an
+  in-band independent reimplementation (`test/namehash.test.ts`
+  golden-vector table).
+- ✅ `namehash` rejects malformed input by delegating to `normalize`.
+- ✅ `decodeRecords` silently drops unknown predicate keys
+  (fail-closed read).
+- ✅ `encodeRecordValue` rejects unknown predicate keys (fail-loud
+  write).
+- ✅ `decodeRecords` drops invalid `agent-kind` values that don't
+  match the closed enum.
+- ✅ `AgentNamingClient` throws `NS Phase 2 — wire to …` from every
+  read method (so silent no-op calls are impossible in Phase 1).
+- ✅ `AgentNamingClient` throws `NS Phase 4 — wire to …` from every
+  write method.
+
+## Audit events this package emits (Phase 2+)
+
+| Action | When | Severity in audit context |
+| --- | --- | --- |
+| `agent-naming.resolve.{accept,reject}` | demo-mcp uses name in audit context | telemetry |
+| `agent-naming.register` | on subname registration | forensic-critical |
+| `agent-naming.records.update` | on resolver-record writes | forensic-critical |
+| `agent-naming.primary-name.update` | on reverse-record writes | forensic-critical |
+| `agent-naming.subregistry.update` | on subregistry-delegation changes | forensic-critical |
+
+These are spec-declared in `specs/215-agent-naming.md` § 9. The
+client doesn't yet take an `auditSink`; Phase 2 will add the optional
+`opts.auditSink` and emit through it.
+
+## Out-of-scope (won't audit here)
+
+- Contract source — lives in `packages/contracts/src/naming/` (Phase 3).
+- On-chain authority paths (subregistry delegation, owner rotation
+  via custody) — Phase 3 contract Forge tests + Phase 4 client
+  integration tests.
+- Demo wiring — Phase 5; per-demo audit lives in the demo's
+  integration evidence rows, not in this package.
+
+## Change log
+
+| Date | Wave | What changed |
+| --- | --- | --- |
+| 2026-05-23 | NS Phase 1 | Initial audit. AN-1/2/3 open; security invariants verified by unit tests. |

package/CLAUDE.md

@@ -0,0 +1,180 @@
+# @agenticprimitives/agent-naming — Claude guide
+
+## Naming facet, not identity
+Names are a **facet registration** pointing AT the canonical Smart Agent ([ADR-0010](../../docs/architecture/decisions/0010-smart-agent-canonical-identifier.md)). Forced-unique labels: [spec 220 § 5](../../specs/220-agent-identity-bootstrap.md). `addr` + `nativeId` MUST reference the same SA.
+
+## What this package owns
+
+- The `.agent` TLD constant (`AGENT_TLD`).
+- Name normalization (`normalizeAgentName`) — NFC + lowercase + label
+  validation. Rejects empty / hyphen-prefixed / non-ASCII labels in v0.
+- `labelhash` + `namehash` — ENS-compatible keccak256 hashes for
+  identifier nodes.
+- Record schemas (`AgentNameRecords`) and predicate constants
+  (subpath `/records`).
+- `AgentNamingClient` — read API (resolve / reverse-resolve / get
+  records) + write API skeleton (Phase 1 writes throw `NS Phase 2`).
+- Pure encoded call builders for name-owner rotation that compose
+  into custody-policy ceremonies (subpath `/custody`).
+
+## What this package does NOT own
+
+- Smart-account internals → [`agent-account`](../agent-account)
+  (we consume `AgentAccountClient` for ERC-1271 verification +
+  counterfactual address derivation).
+- Custody policy, scheduling, quorum → [`custody`](../account-custody).
+  We expose call builders only — never import.
+- Delegation / caveat / mint → [`delegation`](../delegation).
+- Passkey ceremonies → [`connect-auth`](../connect-auth).
+- MCP / A2A transport → demo apps + future `a2a-runtime`.
+- Contract source — that lives in `packages/contracts/src/naming/`
+  (Phase 3+); this package ships ABIs + client only.
+
+## Vocabulary
+
+**Owns:** `AgentName`, `Label`, `Node` (namehash), `NameRecord`,
+`AgentNamingClient`, `Subregistry`, `Resolver`, `PrimaryName`,
+`AGENT_TLD`.
+**Disambiguation:**
+
+- **"resolver"** here = on-chain ENS-v2 resolver. Distinct from
+  any other package.
+- **"registry"** here = `AgentNameRegistry` contract. Distinct from
+  the factory deploy-registry in `agent-account`.
+- **"primary name"** = reverse-record on a Smart Agent address.
+  Distinct from `connect-auth.sessionId` and `delegation.SessionRow`.
+  **Does not use:** `Delegation`, `Caveat`, `Steward`, `Custodian`,
+  `Trustee`, `KMS`, `RiskTier`, `JtiStore`, MCP / A2A transport.
+  See `capability.manifest.json:forbiddenTerms`.
+
+## Read these first (in order)
+
+1. `capability.manifest.json` — boundary.
+2. `src/index.ts` — public API.
+3. `../../specs/215-agent-naming.md` — the spec.
+4. `src/namehash.ts` + `src/normalize.ts` — the pure substrate.
+5. `src/client.ts` — the client skeleton.
+
+## Stable public exports
+
+**Constants + helpers:** `AGENT_TLD`, `normalizeAgentName`,
+`labelhash`, `namehash`.
+**Types:** `AgentNameRecords`, `RegisterSubnameInput`,
+`SetPrimaryNameInput`, `SetAgentRecordsInput`,
+`SetSubregistryInput`.
+**Client:** `AgentNamingClient`.
+**Errors:** `InvalidNameError`, `NameNotFoundError`,
+`UnauthorizedNameOwnerError`.
+**Subpaths:**
+
+- `/records` — predicate constants + encoders/decoders.
+- `/custody` — pure encoded call builders for custody-gated name
+  rotation (no `@agenticprimitives/account-custody` import).
+
+## Allowed imports
+
+`@agenticprimitives/types`, `@agenticprimitives/connect-auth`
+(`Signer` type only), `@agenticprimitives/agent-account`
+(`AgentAccountClient`), `viem`, `@noble/hashes` (transitive via viem).
+
+## Forbidden imports
+
+- `apps/*`
+- `@agenticprimitives/delegation`, `mcp-runtime`, `tool-policy`,
+  `key-custody`, `audit`, `account-custody`
+- `@modelcontextprotocol/sdk`
+
+## Drift triggers — STOP and route
+
+- "Add `getLogs` / `queryFilter` / `watchContractEvent` for a product read" —
+  **STOP.** [ADR-0012](../../docs/architecture/decisions/0012-no-eth-getlogs-in-product-read-paths.md):
+  use `readContract`, on-chain stored fields, or an indexer. There is NO log
+  walker left here — `reverseResolve` is a single `reverseResolveString` call.
+- "Add a `try fast path / catch → slower different path` fallback" — **STOP.**
+  [ADR-0013](../../docs/architecture/decisions/0013-no-silent-fallbacks.md): one
+  mechanism per read. Empty/null is the answer; don't escalate to a log walk or
+  second contract.
+- "Add a delegation-token mint or verify path" — **STOP.** Belongs
+  in [`delegation`](../delegation).
+- "Add a CustodyAction to gate name rotation" — **STOP.** Belongs
+  in [`custody`](../account-custody). Compose via `agent-naming/custody`
+  call builders here without importing.
+- "Add a passkey ceremony" — **STOP.** Belongs in [`connect-auth`](../connect-auth).
+- "Reach for an MCP transport" — **STOP.** Out of scope.
+- "Auto-resolve name via a system-wide hook in the worker" — **STOP.**
+  Demo-app integration only; the package itself is transport-agnostic.
+
+## Decision Tree
+
+- Adding a new record field? Start in `src/types.ts` and
+  `src/records.ts`; update tests and `docs/api.md`.
+- Adding resolver reads? Start in `src/client.ts`.
+- Adding name rotation calls? Start in `src/custody.ts`; do not import
+  `@agenticprimitives/account-custody`.
+- Adding passkey behavior? Stop. Route to `connect-auth`.
+- Adding delegation or caveat behavior? Stop. Route to `delegation`.
+- Adding MCP/A2A transport? Stop. Route to app/runtime packages.
+
+## Before you write code
+
+- [ ] Is the change in the resolver-records / namehash / normalize /
+      client surface?
+- [ ] Did I avoid importing from `delegation`, `account-custody`,
+      `mcp-runtime`, `tool-policy`, `key-custody`, `audit`?
+- [ ] Did I keep `normalize` deterministic (NFC + lowercase + label
+      validation)?
+- [ ] Did I write golden-vector tests for any namehash / labelhash
+      change?
+- [ ] Did I update `specs/215-agent-naming.md` if the public API or
+      records schema changed?
+
+## Security invariants (DO NOT BREAK)
+
+- **Name normalization is deterministic.** Two strings that normalize
+  identically MUST produce identical namehashes.
+- **No raw passkey material in records.** Only `credentialIdDigest`
+  (a hash) is ever stored in `passkey-credential-digest`.
+- **Reverse resolution requires round-trip.** `reverseResolve(agent)`
+  returns a name only when `resolveName(name) === agent`.
+- **Fail-closed on unknown predicates.** Unknown record keys decode
+  to `undefined`; encoders refuse unknown keys.
+- **Write methods require the name owner.** Verified via the owner
+  Smart Agent's ERC-1271 `isValidSignature` (Phase 2+).
+
+## Validate the package
+
+```bash
+pnpm --filter @agenticprimitives/agent-naming typecheck
+pnpm --filter @agenticprimitives/agent-naming test
+pnpm check:forbidden-terms
+```
+
+## Common task routing
+
+- New record predicate → `src/records.ts` (encoder/decoder + constant)
+  - update `AgentNameRecords` type in `src/types.ts` + add a test.
+- New client method → `src/client.ts` (Phase 1 stub with
+  `throw new Error('NS Phase 2')`; wire in Phase 2).
+- New custody-rotation call builder → `src/custody.ts` (subpath
+  `/custody`; pure encoded call — no `@agenticprimitives/account-custody`
+  import).
+
+## Capabilities this package participates in
+
+- **Agent identity + service discovery** — the naming graph IS the
+  on-chain authority for "which Smart Agent answers to which
+  human-readable name." Demos use it to resolve service endpoints
+  (`a2a-endpoint`, `mcp-endpoint`) without hardcoded URLs.
+- **Audit / forensics trail** — emits (via consumer-supplied
+  `AuditSink`): `agent-naming.{resolve,register,records.update,
+primary-name.update,subregistry.update}`.
+- Index of cross-cutting capabilities:
+  [`docs/architecture/cross-cutting-capabilities.md`](../../docs/architecture/cross-cutting-capabilities.md).
+
+## Documentation map
+
+[`README.md`](README.md) · [`docs/concepts.md`](docs/concepts.md) · [`docs/api.md`](docs/api.md) · [`docs/security.md`](docs/security.md) · [`docs/troubleshooting.md`](docs/troubleshooting.md) · [`docs/migration.md`](docs/migration.md)
+
+## Generated files (ignore)
+
+`dist/`, `node_modules/`, `coverage/`, `*.tsbuildinfo`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agentic Trust Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,158 @@
+# @agenticprimitives/agent-naming
+
+Human-readable `.agent` **naming facets** for Smart Agents.
+
+The canonical identifier is the Smart Agent address
+(`@agenticprimitives/agent-account`). This package registers names and records
+that point **at** that address — it does not create or own identity.
+
+> **Layer:** Discover — a naming **facet** (not canonical identity — that is `agent-account`).
+> **Canonical key:** the Smart Agent address the name resolves to.
+
+Use this package to resolve names like `alice.agent`, `acme.agent`, and
+`treasury.acme.agent` to Smart Agent addresses, read typed service-discovery
+records, and build encoded calls for name-management transactions.
+
+## Use This When
+
+- You need forward resolution: `alice.agent -> 0x...`.
+- You need reverse resolution from a Smart Agent address to its primary name.
+- You need typed records such as `displayName`, `a2aEndpoint`, `mcpEndpoint`,
+  `nativeId`, or `metadataUri`.
+- You need pure call builders for name registration, resolver updates, primary
+  name updates, or owner rotation.
+
+## Do Not Use This For
+
+- Passkey ceremonies or auth flows. Use `@agenticprimitives/connect-auth`.
+- Smart-account deployment or UserOps. Use `@agenticprimitives/agent-account`.
+- Account safety policy and approval scheduling. Use `@agenticprimitives/account-custody`.
+- Permission-token minting or attenuation. Use `@agenticprimitives/delegation`.
+- MCP/A2A transport wiring. Use demo apps or runtime packages.
+
+## Install
+
+This package is workspace-internal and not yet published.
+
+```bash
+pnpm add @agenticprimitives/agent-naming
+```
+
+## 60-Second Quickstart
+
+```ts
+import {
+  AgentNamingClient,
+  labelhash,
+  namehash,
+  normalizeAgentName,
+} from '@agenticprimitives/agent-naming';
+
+normalizeAgentName('  ALICE.AGENT  '); // "alice.agent"
+labelhash('alice'); // 0x...
+namehash('treasury.acme.agent'); // 0x...
+
+const naming = new AgentNamingClient({
+  rpcUrl: 'https://base-sepolia.example/rpc',
+  chainId: 84532,
+  registry: '0x0000000000000000000000000000000000000001',
+  universalResolver: '0x0000000000000000000000000000000000000002',
+});
+
+const address = await naming.resolveName('alice.agent');
+const primaryName = await naming.reverseResolve('0x0000000000000000000000000000000000000003');
+const records = await naming.getRecords('treasury.acme.agent');
+```
+
+## Main Concepts
+
+- **Canonical SA**: the ERC-4337 address every name must reference (`addr`,
+  `nativeId`). Owned by `agent-account`, not this package.
+- **AgentName**: a normalized dotted name under `.agent` (a facet label).
+- **Label**: one segment of a name, such as `treasury`.
+- **Node**: ENS-compatible `namehash(name)`.
+- **Registry**: owns name records: owner, resolver, parent, subregistry.
+- **Resolver**: stores typed records for a node.
+- **Primary name**: reverse record for a Smart Agent address.
+- **Records**: typed data such as endpoints, display name, CAIP-10 `nativeId`,
+  and public-safe passkey credential digest.
+
+See [`docs/concepts.md`](docs/concepts.md).
+
+## Common Recipes
+
+```ts
+import {
+  decodeRecords,
+  encodeRecords,
+  PREDICATE_ID,
+} from '@agenticprimitives/agent-naming/records';
+
+const encoded = encodeRecords({
+  addr: '0x0000000000000000000000000000000000000003',
+  agentKind: 'service', // a treasury is a service agent; 'treasury' is a profile subtype
+  displayName: 'Acme Treasury',
+  nativeId: 'eip155:84532:0x0000000000000000000000000000000000000003',
+});
+
+const decoded = decodeRecords({
+  strings: { [PREDICATE_ID.displayName]: 'Acme Treasury' },
+  addresses: { [PREDICATE_ID.addr]: '0x0000000000000000000000000000000000000003' },
+  bytes32s: {},
+});
+```
+
+More examples:
+
+- [`examples/basic.ts`](examples/basic.ts)
+- [`examples/records.ts`](examples/records.ts)
+- [`examples/custody-rotation.ts`](examples/custody-rotation.ts)
+
+## Runtime Support
+
+Pure helpers and record encoders work in browser, Node, and Workers. The client
+uses `viem` public and wallet clients and requires an RPC URL for chain reads or
+transaction submission.
+
+## Subpath Exports
+
+- `@agenticprimitives/agent-naming` — public helpers, client, ABIs, and types.
+- `@agenticprimitives/agent-naming/records` — predicate ids and typed
+  record encode/decode helpers.
+- `@agenticprimitives/agent-naming/custody` — pure encoded call builders for
+  name-management transactions.
+
+## Security Invariants
+
+- Product reads use `readContract`; no `eth_getLogs` in hot paths
+  ([ADR-0012](../../docs/architecture/decisions/0012-no-eth-getlogs-in-product-read-paths.md)).
+  `reverseResolve` string reconstruction is transitional log debt — do not copy.
+- Name normalization is deterministic.
+- Reverse resolution must round-trip before it is trusted.
+- Unknown predicates are ignored on decode and rejected by typed encoders.
+- Raw passkey credential IDs are never stored.
+- Endpoint records are discovery hints, not proof of endpoint control.
+
+See [`docs/security.md`](docs/security.md) and [`AUDIT.md`](AUDIT.md).
+
+## Documentation Map
+
+- [`docs/concepts.md`](docs/concepts.md) — naming model and vocabulary.
+- [`docs/api.md`](docs/api.md) — human-readable public API guide.
+- [`docs/security.md`](docs/security.md) — security posture and invariants.
+- [`docs/troubleshooting.md`](docs/troubleshooting.md) — common errors.
+- [`docs/migration.md`](docs/migration.md) — version and migration notes.
+- [`CLAUDE.md`](CLAUDE.md) — agent routing and drift prevention.
+- [`spec.md`](spec.md) — canonical spec pointer.
+
+## Validation
+
+```bash
+pnpm check:agent-naming
+pnpm check:public-exports
+pnpm check:forbidden-terms
+```
+
+## License
+
+UNLICENSED.