\n\n| Protocol | \nDescription | \n
\n\nchapi | \nW3C Credential Handler API — navigator.credentials.get() | \n
\n\ndidcomm-v2 | \nDIDComm v2 Present Proof 3.0 | \n
\n\noid4vp | \nOpenID for Verifiable Presentations | \n
\n\nwaci-didcomm | \nWallet And Credential Interaction via DIDComm | \n
\n
\n\n## Ecosystem\n\nRelated repos in the Attestto ecosystem:\n\n| Package | Purpose | Repo |\n|---|---|---|\n| **@attestto/wallet-identity-resolver** | Given a wallet address, resolve all DIDs, credentials, SBTs attached to it | [GitHub](https://github.com/Attestto-com/wallet-identity-resolver) |\n| **@attestto/verify** | Web Components for wallet discovery, signing, and VP verification | [GitHub](https://github.com/Attestto-com/verify) |\n| **@attestto/vc-sdk** | Issue and verify W3C Verifiable Credentials | [GitHub](https://github.com/Attestto-com/vc-sdk) |\n| **did-sns-spec** | `did:sns` DID method spec — Solana domain to DID resolution | [GitHub](https://github.com/Attestto-com/did-sns-spec) |\n| **vLEI-Solana-Bridge** | Write and verify vLEI attestations from GLEIF on Solana | [GitHub](https://github.com/Attestto-com/vLEI-Solana-Bridge) |\n\n## Security\n\nSee [SECURITY.md](SECURITY.md) for:\n\n- **Wallet discovery spoofing** — discovery is untrusted metadata; trust is established via VP verification\n- **Trusted wallet allowlist** — restrict which wallet DIDs your app accepts\n- **Cross-origin considerations** — CORS for DID resolution and revocation checks\n- **API key exposure** — always use a backend proxy for resolver calls\n- **Trust chain** — the DID method spec defines where to resolve, not the VC\n\n## Trust model (for site developers)\n\nThis package implements a **bilateral trust model**. Each side declares what it accepts; neither side is asked to trust the other implicitly.\n\n### Site → wallet: declare which issuers you accept\n\nPass `trustedIssuers: string[]` on any `requestSignature` or `requestAuth` call:\n\n```ts\nawait requestAuth(wallet, {\n nonce, audience, origin,\n trustedIssuers: [\n 'did:sns:attestto.attestto.sol', // any identity issued by Attestto root\n 'did:web:your-tenant.example', // OR identities issued by your own tenant\n ],\n})\n```\n\nThe wallet uses this to filter and highlight matching identities in the consent popup. If the user has multiple identities, they default-see the one your site will actually accept — no \"user signs, server rejects, user retries\" loop.\n\n**Empty / omitted** → the wallet shows all the user's identities; you accept whatever they return (verify on the backend).\n\n### Wallet → site: per-origin consent and identity memory\n\nThese are wallet-side properties — your site doesn't configure them, but you should know they exist so you understand the UX:\n\n- **First-sight consent** — the first time your origin requests a sign-in or pushes an identity-sync payload, the wallet asks the user to approve your origin. Subsequent requests from the same origin proceed without re-prompting. This means a site that's never been visited cannot silently get an identity signature.\n- **Per-origin identity preference** — when the user picks an identity for your origin, the wallet remembers it. Next time you call `requestAuth`, the wallet default-selects the same identity. The user can override per-call.\n- **User-visible revocation** — the user can revoke your origin's trust (and forget the preference) from the wallet's Settings → Trusted Sites pane.\n\n### Backend verification responsibility\n\nThe adapter never trusts a `requestAuth` / `requestSignature` response on its own. Always verify on your backend:\n\n1. The returned `signature` is valid over `nonce + audience + origin` using the `publicKeyJwk` from the response.\n2. The `publicKeyJwk` matches a verification method published in the holder DID's DID Document (resolve via your resolver).\n3. If you set `trustedIssuers`: an issuer in your list actually attested the returned `did` (look for a corresponding VC chain, OR trust the wallet's filtering and skip — depending on your assurance level).\n\nThe `nonce` must be single-use and bound to the user's session. Replay protection is the verifier's job, not the wallet's.\n\n## Build with an LLM\n\nThis repo ships a [`llms.txt`](./llms.txt) context file — a machine-readable summary of the API, data structures, and integration patterns designed to be read by AI coding assistants.\n\n### Recommended setup\n\nUse the [`attestto-dev-mcp`](../attestto-dev-mcp) server to give your LLM active access to the ecosystem:\n\n```bash\ncd ../attestto-dev-mcp\nnpm install && npm run build\n```\n\nThen add it to your Claude / Cursor / Windsurf config and ask:\n\n> *\"Explore the Attestto ecosystem and scaffold me an on-chain identity resolver\"*\n\n### Which model?\n\nWe recommend **[Claude](https://claude.ai) Pro** (5× usage vs free) or higher. Long context and strong TypeScript reasoning handle this codebase well. The MCP server works with any LLM that supports tool use.\n\n> **Quick start:** Ask your LLM to read `llms.txt` in this repo, then describe what you want to build. It will find the right archetype, generate boilerplate, and walk you through the first run.\n\n## Roadmap\n\n### v0.3.0 — Protocol negotiation\n\nMulti-protocol wallets declare `protocols: ['oid4vp', 'chapi', 'didcomm-v2']`. The site needs a standard way to pick the best mutual protocol and act on it.\n\n```ts\nimport { pickWallet, negotiateProtocol } from '@attestto/id-wallet-adapter'\n\nconst wallet = await pickWallet()\nconst protocol = negotiateProtocol(wallet, ['oid4vp', 'chapi'])\n// Returns 'oid4vp' if wallet supports it, falls back to 'chapi', or null\n```\n\nInspired by [Aries RFC 0031 Discover Features](https://identity.foundation/aries-rfcs/latest/features/0031-discover-features/) — simplified for browser context.\n\n### v0.4.0 — Protocol execution\n\n`pickWallet()` returns a `ConnectedWallet` with protocol-specific request methods:\n\n```ts\nconst wallet = await pickWallet()\nconst vp = await wallet.request('oid4vp', { presentationDefinition })\n// or\nconst vp = await wallet.request('chapi', { query, challenge, domain })\n```\n\nOne return object, multiple wire protocols. The wallet adapter becomes the unified interface between the site and whatever protocol the wallet speaks.\n\n## See It In Action\n\n| Demo | What | Link |\n|------|------|------|\n| **Verify & Sign** | Live playground with the actual components — drop a PDF, sign it | [verify.attestto.com/docs](https://verify.attestto.com/docs) |\n| **@attestto/verify** | Web Components that use this adapter for wallet discovery + signing | [GitHub](https://github.com/attestto/verify) |\n| **DID Landscape Explorer** | Self-assessment wizard with wallet picker and CHAPI flow | [GitHub](https://github.com/chongkan/did-landscape-explorer) |\n\n**Debug logging:** Open the console on any page using this adapter and run `Attestto.debug = true` to see the full discovery and signing flow with numbered steps.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\n[Apache 2.0](./LICENSE) — see also [`NOTICE`](./NOTICE).\n\nThis package ships with Apache 2.0's explicit patent grant (§3): every contributor grants a perpetual, worldwide, royalty-free, irrevocable patent license for their contributions, plus the §3 retaliation clause that terminates that license for anyone who weaponizes patents against the project. We chose Apache 2.0 specifically because protocol-shaped infrastructure deserves a license that says something explicit about patents. MIT does not.\n","readmeFilename":"README.md"}