@thurinlabs/identity-kit 0.7.5 → 1.0.0

package/README.md

@@ -1,12 +1,12 @@
 # @thurinlabs/identity-kit
 
-The shared library for Thurin identity — the single source of truth for looking up and **verifying** on-chain identity claims, PGP key proofs, social proofs, and EFP social graph data. It powers both the [Scry](https://thurin.id) explorer and the embeddable `ScryCard`, so a "verified" result means the same thing everywhere.
+The shared library for Thurin identity — the single source of truth for looking up and **verifying** on-chain identity claims, PGP key proofs, social proofs, and EFP social graph data. It powers both the [thurin.id](https://thurin.id) explorer and the embeddable `ThurinCard`, so a "verified" result means the same thing everywhere.
 
 Three layers — use whichever fits:
 
 - **Core** — framework-agnostic functions (verify proofs, parse PGP keys, fetch EFP/claims). No React required.
 - **Hooks** — thin React wrappers around the core.
-- **ScryCard** — a drop-in identity card UI built on the hooks.
+- **ThurinCard** — a drop-in identity card UI built on the hooks.
 
 A [Thurin Labs](https://thurin.id) project.
 
@@ -21,25 +21,25 @@ Peer dependencies: `react`, `react-dom`, `wagmi`, `viem`, `@tanstack/react-query
 ## Quick Start
 
 ```tsx
-import { IdentityKitProvider, ScryCard } from '@thurinlabs/identity-kit'
+import { IdentityKitProvider, ThurinCard } from '@thurinlabs/identity-kit'
 import '@thurinlabs/identity-kit/styles'
 
 function App() {
   return (
     <IdentityKitProvider>
-      <ScryCard ens="vitalik.eth" theme="thurin" />
+      <ThurinCard ens="vitalik.eth" theme="thurin" />
     </IdentityKitProvider>
   )
 }
 ```
 
-## ScryCard
+## ThurinCard
 
 A self-contained identity card that fetches and displays all available identity data.
 
 ```tsx
-<ScryCard ens="vitalik.eth" theme="thurin" />
-<ScryCard address="0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" theme="dark" />
+<ThurinCard ens="vitalik.eth" theme="thurin" />
+<ThurinCard address="0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" theme="dark" />
 ```
 
 **Props:**
@@ -50,7 +50,7 @@ A self-contained identity card that fetches and displays all available identity
 | `address` | `string` | — | ETH address to look up |
 | `theme` | `'thurin' \| 'dark' \| 'light'` | `'thurin'` | Visual theme |
 
-**Displays:** ENS avatar, name, address, Signet seal count, verified proof count, EFP follower count, proof provider badges, and a link to the full [Scry](https://thurin.id) profile.
+**Displays:** ENS avatar, name, address, on-chain attestation count, verified proof count, EFP follower count, proof provider badges, and a link to the full [thurin.id](https://thurin.id) profile.
 
 ## Provider
 
@@ -59,48 +59,51 @@ Wrap your app (or just the part using identity-kit) in `IdentityKitProvider`. If
 ```tsx
 // Zero config — uses public RPC, no Farcaster verification
 <IdentityKitProvider>
-  <ScryCard ens="vitalik.eth" />
+  <ThurinCard ens="vitalik.eth" />
 </IdentityKitProvider>
 
 // With options
 <IdentityKitProvider
   rpcUrl="https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY"
   neynarApiKey="YOUR_NEYNAR_KEY"
-  scryBaseUrl="https://thurin.id"
+  baseUrl="https://thurin.id"
 >
-  <ScryCard ens="vitalik.eth" />
+  <ThurinCard ens="vitalik.eth" />
 </IdentityKitProvider>
 ```
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `rpcUrl` | `string` | publicnode | Ethereum RPC endpoint |
+| `rpcUrl` | `string` | publicnode | Ethereum RPC endpoint. Any RPC works — v2 needs only `eth_call` |
 | `neynarApiKey` | `string` | — | Neynar API key for Farcaster proof verification |
-| `scryBaseUrl` | `string` | `https://thurin.id` | Base URL for "View on Scry" links |
+| `baseUrl` | `string` | `https://thurin.id` | Base URL for "View on Thurin" links |
+| `network` | `'mainnet' \| 'sepolia' \| 'local'` | `'mainnet'` | Which chain to read the PGPRegistry on (`local` = a running anvil) |
+| `registryAddress` | `string` | v2 address | Override the registry contract address |
 
 ## Hooks
 
-For custom UI, use the hooks directly instead of `ScryCard`.
+For custom UI, use the hooks directly instead of `ThurinCard`.
 
-### useScryIdentity
+### useThurinIdentity
 
-Combined identity data — ENS, Signet claims, PGP proofs, and EFP social graph.
+Combined identity data — ENS, on-chain attestations, PGP proofs, and EFP social graph.
 
 ```tsx
-const identity = useScryIdentity('vitalik.eth')
+const identity = useThurinIdentity('vitalik.eth')
 // or
-const identity = useScryIdentity('0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045')
+const identity = useThurinIdentity('0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045')
 ```
 
-Returns: `ScryIdentity` with `address`, `ensName`, `ensAvatar`, `claims`, `totalClaims`, `activeClaims`, `currentFingerprint`, `pgpKeyInfo`, `proofs`, `efp`, `isLoading`, `error`.
+Returns: `ThurinIdentity` with `address`, `ensName`, `ensAvatar`, `claims`, `totalClaims`, `activeClaims`, `currentFingerprint`, `pgpKeyInfo`, `proofs`, `efp`, `isLoading`, `error`.
 
-### useSignetClaims
+### useAttestations
 
-On-chain attestation data from the PGPRegistry contract.
+On-chain attestation data from the PGPRegistry v2 contract — the owner's history plus the stored signature and key for each claim, read with plain contract calls (no event logs), each verified off-chain.
 
 ```tsx
 const { claims, totalClaims, activeClaims, currentFingerprint, isLoading } =
-  useSignetClaims('0xd8dA...')
+  useAttestations('0xd8dA...')
+// claims[].{ index, fingerprint, createdAt, revoked, revokedAt, messageVersion, pgpSignature, pgpPublicKey, verification }
 ```
 
 ### useEFPGraph
@@ -114,16 +117,18 @@ const { efp, isLoading } = useEFPGraph('0xd8dA...')
 
 ### usePGPProofs
 
-PGP key info and verified social proofs from keyserver.
+PGP key info and verified social proofs, read from the key stored in the identity's on-chain attestation. No keyserver is consulted.
 
 ```tsx
-const { keyInfo, proofs, isLoading } = usePGPProofs('03E53D807CE38C...')
+const { keyInfo, proofs, isLoading } = usePGPProofs(fingerprint, attestation.pgpPublicKey)
 // proofs[].provider, proofs[].status, proofs[].displayUrl
 ```
 
+`useThurinIdentity` wires this up for you from the current attestation.
+
 ## Core utilities (no React)
 
-The verification and data logic is exported as plain functions — no React, no provider. This is the layer the Scry explorer and the hooks both build on; use it directly when you need the validated data behind your own UI.
+The verification and data logic is exported as plain functions — no React, no provider. This is the layer the thurin.id explorer and the hooks both build on; use it directly when you need the validated data behind your own UI.
 
 ### Proofs
 
@@ -142,7 +147,7 @@ const result = await verifyProof(proof, fingerprint, neynarApiKey /* only needed
 ### PGP
 
 ```ts
-import { parsePgpKey, verifyAttestation, fetchKeyByFingerprint, fetchKeyByKeyId } from '@thurinlabs/identity-kit'
+import { parsePgpKey, verifyAttestation, stripEmailUserIDs, hasEmailUserID } from '@thurinlabs/identity-kit'
 
 const keyInfo = await parsePgpKey(armoredKey)
 // → { fingerprint, userIDs, algorithm, created, expires, notations, subkeys } | null
@@ -150,9 +155,17 @@ const keyInfo = await parsePgpKey(armoredKey)
 const verification = await verifyAttestation({ pgpPublicKey, pgpSignature, fingerprint, ethAddress })
 // → { verified: boolean, reason?: string }
 
-const armored = await fetchKeyByFingerprint(fingerprint) // from keys.openpgp.org
+// Prepare a key for publishing: drop every user ID that contains an email address.
+const stripped = await stripEmailUserIDs(armoredKey)
+// → { armored, kept: ['thurin'], removed: ['Alice <alice@example.com>'] } | null (null = nothing would remain)
+
+await hasEmailUserID(armoredKey) // → true if any user ID contains an @
 ```
 
+**Published identity.** An attestation stores the armored key on-chain, permanently and publicly. Since 0.9.0 the intended shape is a key whose only user ID is a non-email one (any name — `thurin` is the suggestion), carrying the `proof@thurin.id` notations. `stripEmailUserIDs` produces that from a normal export; the stripped key still verifies (`verifyAttestation` needs at least one self-certified user ID, so a key with none is rejected) and keeps the notations on the user ID it retains. Proofs are then read from the on-chain key, never from a keyserver.
+
+`fetchKeyByFingerprint` / `fetchKeyByKeyId` (keys.openpgp.org) remain exported for key-ID → fingerprint resolution, but note that keyserver serves unverified-email keys as bare packets and drops non-email user IDs, so it cannot supply a published identity.
+
 ### EFP & claims
 
 ```ts
@@ -162,19 +175,52 @@ const graph = await fetchEFPGraph(address)
 // → { followers, following, top8: string[], hasEfp } | null
 ```
 
-### Contract constants
+### Contract
+
+```ts
+import { REGISTRY_ADDRESS, REGISTRY_ABI, NETWORKS, getRegistry } from '@thurinlabs/identity-kit'
+
+getRegistry('sepolia') // → { chainId: 11155111, address, deployBlock, explorerUrl, defaultRpcUrl }
+```
+
+`REGISTRY_ABI` is the complete v2 ABI (reads and writes), so apps that publish claims use the same one. The v2 registry is deployed with CREATE2 and has the same address on every network.
+
+### Fingerprints and key IDs
+
+The v2 registry takes raw fingerprint bytes and indexes by their hash and by long key ID:
 
 ```ts
-import { REGISTRY_ADDRESS, REGISTRY_ABI, CONTRACT_DEPLOY_BLOCK } from '@thurinlabs/identity-kit'
+import { fingerprintToBytes, bytesToFingerprint, fingerprintHash, keyIdOf, keyIdToBytes } from '@thurinlabs/identity-kit'
+
+fingerprintToBytes('6E00 5391 … 7FE7')  // → '0x6e0053911942a889426c1866e34d9266098f7fe7' (attest / reattest arg)
+bytesToFingerprint('0x6e00…7fe7')       // → '6e0053911942a889426c1866e34d9266098f7fe7'
+fingerprintHash(fp)                      // → keccak256 of the raw bytes (addressesFor arg)
+keyIdOf(fp)                              // → '0xe34d9266098f7fe7' (fingerprintsForKeyId arg; v4 = last 8 bytes, v6 = first 8, per RFC 9580)
 ```
 
-Note `REGISTRY_ABI` here is read-only (events + `attestationCount` + `getAttestation`). Apps that write claims (the Signet flow) need their own ABI with the `attest`/`revoke` functions.
+### Authorized writes (EIP-712)
+
+Every write has a `…For` twin that anyone can submit with the owner's signature — for cold wallets, a CLI, or a sponsor. The helpers build exactly the typed data the contract verifies:
+
+```ts
+import { attestTypedData, authorizationDigest } from '@thurinlabs/identity-kit'
+import { signTypedData } from '@wagmi/core'
+
+const nonce = await readContract({ ..., functionName: 'nonces', args: [owner] })
+const typedData = attestTypedData(chainId, registryAddress, {
+  owner, fingerprint, pgpSignature, pgpPublicKey, nonce, deadline: BigInt(Math.floor(Date.now() / 1000) + 3600),
+})
+const signature = await signTypedData(config, typedData)
+// anyone: attestFor(owner, fingerprintBytes, sigBytes, keyBytes, deadline, signature)
+```
+
+Also `reattestTypedData`, `updateKeyTypedData`, `revokeTypedData`, `setRecordTypedData`, and `recordKind(name)` for the `bytes32 kind` of a record.
 
 ## Themes
 
-Three built-in themes: `thurin`, `dark`, `light`. All styles are scoped under `[data-scry-theme]` with `scry-` prefixed class names to avoid conflicts with your app's styles.
+Three built-in themes: `thurin`, `dark`, `light`. All styles are scoped under `[data-thurin-theme]` with `thurin-` prefixed class names to avoid conflicts with your app's styles.
 
-Import styles when using `ScryCard`:
+Import styles when using `ThurinCard`:
 
 ```tsx
 import '@thurinlabs/identity-kit/styles'
@@ -188,22 +234,25 @@ For static sites, Jekyll blogs, WordPress, or any HTML page — use the standalo
 
 ```html
 <div
-  data-scry-card="bendoubleu.eth"
+  data-thurin-card="bendoubleu.eth"
   data-theme="thurin"
   data-rpc-url="https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY"
 ></div>
 
-<script src="https://cdn.jsdelivr.net/npm/@thurinlabs/identity-kit/dist/embed.global.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@thurinlabs/identity-kit@0/dist/embed.global.js"></script>
 ```
 
 | Attribute | Description |
 |-----------|-------------|
-| `data-scry-card` | ENS name or ETH address to look up (required) |
-| `data-theme` | `thurin`, `dark`, or `light` (default: `thurin`) |
-| `data-rpc-url` | An Ethereum RPC that supports `eth_getLogs` — required to verify on-chain claims. The card reads the chain directly, so use your own node or any provider. (Public fallback RPCs throttle `getLogs`.) |
+| `data-thurin-card` | ENS name or ETH address to look up (required) |
+| `data-theme` | `thurin`, `dark`, or `light` (default: `thurin`). Change it after render and the card follows, so a page with a theme switch can keep the card in step. |
+| `data-rpc-url` | Optional. Any Ethereum RPC; the card reads the v2 registry with plain calls, so the keyless public default works. |
 | `data-neynar-key` | Optional. A Neynar API key, only to verify Farcaster proofs. Without it, Farcaster shows as unverified. |
+| `data-base-url` | Optional. Where the card's "View on Thurin" link points (default `https://thurin.id`). A page served from ENS can pass its own name so the link stays on ENS. |
+| `data-network` | Optional. `sepolia` or `local` instead of mainnet. |
+| `data-registry-address` | Optional. Override the registry contract address. |
 
-The card talks directly to Ethereum, keys.openpgp.org, and each proof platform — no intermediary. Cards render automatically on page load and for dynamically added elements.
+The card talks directly to Ethereum and each proof platform — no intermediary, no keyserver. Cards render automatically on page load and for dynamically added elements.
 
 ## Supported Proof Providers
 
@@ -215,6 +264,47 @@ The card talks directly to Ethereum, keys.openpgp.org, and each proof platform
 | Codeberg | Repository description |
 | Mastodon | Profile metadata |
 
+## Migrating from 0.9.x
+
+1.0.0 reads the **PGPRegistry v2** contract. The v1 registry is no longer read.
+
+| 0.9.x | 1.0.0 |
+|-------|-------|
+| `REGISTRY_ABI` (v1, reads only) | v2 ABI, reads + writes |
+| `CONTRACT_DEPLOY_BLOCK` | removed (no log scans) |
+| `Attestation.txHash` | removed; `revokedAt` and `messageVersion` added |
+| `rpcUrl` needed `eth_getLogs` | any RPC |
+| — | `local` network, `registryAddress` prop / `data-registry-address` |
+| — | fingerprint helpers, EIP-712 authorization helpers |
+
+## Migrating from 0.8.x
+
+0.9.0 moves proofs to the on-chain key and adds key-preparation helpers.
+
+| 0.8.x | 0.9.0 |
+|-------|-------|
+| `usePGPProofs(fingerprint)` — fetched the key from keys.openpgp.org | `usePGPProofs(fingerprint, armoredKey)` — parses the supplied (on-chain) key |
+| — | `stripEmailUserIDs(armoredKey)`, `hasEmailUserID(armoredKey)` |
+| mainnet only | `network` prop / `data-network` attribute; `NETWORKS`, `getRegistry()` |
+
+`useThurinIdentity`, `ThurinCard`, and the embed need no changes; they pass the attestation's key through automatically.
+
+## Migrating from 0.7.x
+
+0.8.0 collapses the Scry / Signet sub-brands into Thurin. Renames only — no behaviour changed, and existing on-chain attestations verify exactly as before.
+
+| 0.7.x | 0.8.0 |
+|-------|-------|
+| `ScryCard` / `ScryCardProps` | `ThurinCard` / `ThurinCardProps` |
+| `useScryIdentity` | `useThurinIdentity` |
+| `useSignetClaims` | `useAttestations` |
+| `ScryIdentity` (type) | `ThurinIdentity` |
+| `SignetClaim` (type) | `Attestation` |
+| `scryBaseUrl` (provider prop) | `baseUrl` |
+| `data-scry-card` (embed) | `data-thurin-card` |
+| `[data-scry-theme]`, `.scry-*`, `--scry-*` | `[data-thurin-theme]`, `.thurin-*`, `--thurin-*` |
+| `ScryEmbed` (IIFE global) | `ThurinEmbed` |
+
 ## Development
 
 ```bash
@@ -225,8 +315,8 @@ npm test
 
 ## Links
 
-- [Scry](https://thurin.id) — Identity explorer
-- [Signet](https://thurin.id/signet) — Create identity claims
+- [Thurin](https://thurin.id) — Identity explorer
+- [Attest](https://thurin.id/attest) — Create identity claims
 - [Documentation](https://docs.thurin.id)
 - [GitHub](https://github.com/thurinlabs/identity-kit)
 - [Codeberg](https://codeberg.org/thurinlabs/identity-kit)