feat(ens): @libid/ens, the ENS name of a handle

[SupremaLex]

A new package, @libid/ens: the ENS name of a libID handle, for applications that want to show users the name they can paste into a bio or a wallet.

import { ensName } from '@libid/ens'

ensName('x', '@Some_Handle')                              // 'some-handle.x.handles.link'
ensName('google', 'Alice.Smith@Gmail.com')                // 'alice.smith.google.handles.link'
ensName('google', 'alice@company.com')                    // 'alice._at.company.com.google.handles.link'
ensName('x', 'alice', { chain: 'base' })                  // 'alice.x.base.handles.link'
ensName('x', 'alice', { parent: 'testnet.handles.link' }) // 'alice.x.testnet.handles.link'
ensName('x', 'ab__cd')                                    // null

What it does

• Input. It normalizes the handle with the released rules from @libid/contracts. Those are the rules the gateway applies on every chain, so a name it builds is one the gateway reads back.
• Labels. It applies the label rules of the ENS integration spec (REQ-ENS-LABEL-01 to -04, docs(specs): specify the ENS integration #93):
  • GitHub: the handle unchanged.
  • X: every _ becomes -.
  • Gmail: the local part, split at dots.
  • Other Google domains: the local part, _at, then the domain.
• No name. A handle gets none when any label would fail ENSIP-15 or DNS:
  • -- at the third and fourth characters, including xn-- domains;
  • Gmail +, - or _;
  • an empty piece;
  • _at as a piece;
  • more than 63 bytes.
• Results. null means the handle has no name. Text that is not a handle on the platform throws HandleError, which is re-exported.
• Options.
  • chain narrows the name to one chain.
  • parent (default handles.link) targets a subname deployment such as testnet.handles.link.
  • Both are checked as labels. A chain label can't be a platform key.
  • A chain label must not name a subname that has its own deployment. That is documented, not enforced, because no single call can see which subnames do.
• Constants. Platform keys and handle rules come from @libid/contracts. @libid/contracts is pinned once, in the pnpm catalog that ceremony also uses.
• viem. It is a peer dependency, because @libid/contracts/identity loads viem. libID-contracts popup: mobile-WebKit flake in close-right-after-navigate (CI only) #86 adds a viem-free @libid/contracts/handle, which lets this package drop viem once released.

Checks

• 139 tests, 2 files:
  • each rule and refusal;
  • chain and parent validation, and null options;
  • vectors/names.json: names checked forward through ensName and back through a test-only inverse written from REQ-ENS-LABEL-05;
  • every handle in that file is already normalized;
  • every name is ENSIP-15 normal under viem's normalize.
• Gateway compatibility, once by hand: an early set of names parsed back correctly through the gateway's own parser (Name::query in usernames-indexer). The gateway does not read vectors/names.json yet.
• Repo checks:
  • typecheck, Biome, oxlint and build;
  • test:packages, which imports @libid/ens in the packed-package consumer;
  • the same consumer installed first without @libid/ens, to check that ledger, popup and ceremony load without viem. An injected viem import in ceremony makes this check fail.

Known gaps

• Names outside the transform's output. The gateway still answers some names this transform never produces, such as ab--cd.x, where wallets refuse first under ENSIP-15, and _at.gmail.com. docs(specs): specify the ENS integration #93 records this as a SHOULD.
• Spec link. The README links the spec at docs(specs): specify the ENS integration #93's head, 4d77835; it needs re-pinning if docs(specs): specify the ENS integration #93 changes.
• Publishing to npm is a separate maintainer step, as for the other packages.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Ar21wPcHzNprswTzLJd3MA