epistery 1.5.11 → 2.0.0

package/README.md

@@ -2,399 +2,365 @@
 
 _Epistemology is the study of knowledge. An Epistery, it follows, is a place to share the knowledge of knowledge._
 
-**Epistery** is blockchain-based middleware that provides websites and applications with decentralized authentication, data ownership verification, and trusted data exchange. It serves as a neutral foundation for web applications to identify users, verify data provenance, and conduct digital business without relying on centralized gatekeepers.
-
-## What Does Epistery Do?
-
-Epistery establishes a transactional wallet for both browser and server along with the session handshake. This provides:
-
-- **Decentralized Authentication**: Wallet-based user authentication using cryptographic signatures
-- **Data Wallets**: Blockchain smart contracts for data ownership, encryption, sharing, and transfer
-- **Whitelist Management**: On-chain access control for domains and users
-- **CLI Tools**: Command-line interface for authenticated API requests using bot mode
-- **Client Libraries**: Browser-based wallet and authentication tools
-- **Configuration Management**: Path-based filesystem-like API for secure configuration storage
-
->*NOTE:* The client wallet (signing key) is held in localStorage under strict domain rules unless the user presents
-> a selected wallet from a web3 plugin
-
-## Quick Start
-
-### Installation
-
-```bash
-npm install epistery
-```
-
-### Server Setup
-
-Initialize a domain to create its blockchain wallet:
-
-```bash
-npx epistery initialize mydomain.com
-```
-
-Integrate Epistery into your Express application:
+**Epistery is the identity foundation for web applications.** It gives a host one
+thing it can trust on every request — a cryptographically proven address — and
+binds that address to an on-chain IdentityContract when the user wants a durable
+multi-device identity. Everything else (data, ACLs, naming, content) is the host
+application's concern, not epistery's.
+
+> **Status — sealed contract, v1.2 (2026-05-27).** This README defines what
+> epistery is responsible for, what it is not, and its interface. Code is held to
+> this document. The `agent.sol` surface (data wallets, approvals, whitelist /
+> lists / roles, name registry, notabot) was **removed in v1.2**; see the wiki
+> archives ([[NotABot]], [[Whitelist]], [[DataWallets]], [[Approvals]],
+> [[ContractStandards]]) and git tag `epistery-pre-identity-refactor` for the
+> retired implementations. The dated **[Known divergences](#known-divergences-audit)**
+> section at the end lists where the current code still fails this contract.
+> If behavior and this document disagree, that is a bug in the code, not the doc.
+
+---
+
+## Responsibility (what epistery OWNS)
+
+Epistery is the **single owner** of:
+
+1. **Identity** — proving *who* a request is from. The proof is a wallet
+   signature, carried either by a short-lived signed session cookie (`_epistery`,
+   established via the `/connect` handshake) or a per-request `Bot` signature.
+   The result is a trusted **address** on `req.episteryClient`.
+2. **Identity binding** — relating a device key (rivet) to an **IdentityContract**,
+   verified on-chain (`isAuthorized`). When bound, epistery presents the *contract*
+   as the identity.
+3. **Key custody (client)** — generating and protecting the user's signing key in
+   the browser (non-extractable; see [Key custody](#identity--key-custody)).
+4. **Domain/server wallet & config** — the host's own wallet and the path-based
+   `~/.epistery` configuration.
+5. **FIDO blob storage** — server-side backup of WebAuthn-PRF-wrapped rivet keys
+   so they survive iOS ITP IndexedDB eviction.
+
+No consumer may bypass, re-derive, or duplicate any of these. In particular: a
+downstream service **never** trusts a client-supplied identity header and
+**never** re-implements identity resolution.
+
+---
+
+## What Epistery DOES
+
+- **Authenticates every request** to a trusted address (`req.episteryClient`),
+  via signed `_epistery` session cookie or `Bot` signature.
+- **Mints/loads wallets** for the browser (rivet / FIDO / web3) and server
+  (per-domain).
+- **Binds a device to an IdentityContract** and verifies that binding on-chain.
+- **Serves client libraries** at `/lib/*` (`witness.js`, `wallet.js`, `ethers.js`,
+  …) and contract artifacts at `/artifacts/*` for consumers.
+- **Persists FIDO blobs** (`/fido/blob`) — encrypted, PRF-wrapped rivet keys for
+  WebAuthn-backed identities.
+- **Exposes a CLI** for stateless bot-authenticated requests (`curl`), the
+  Streamable-HTTP MCP bridge (`mcp`), domain initialization, and basic info.
+
+## What Epistery does NOT do
+
+- **Does not store application data.** Apps own their storage; epistery records
+  identity, not your documents.
+- **Does not manage contracts.** It *binds keys to existing contracts* and
+  *verifies* the binding on-chain — it does not deploy, write to, or own
+  application contracts. Contract creation and on-chain ACL/state live in host
+  contracts (e.g. `IdentityContractV3.sol`, `DomainContract.sol`).
+- **Does not define application- or session-level ACLs.** Authorization is the
+  host's job, evaluated against the trusted address epistery provides.
+- **Does not run a name registry.** Per-domain naming is a relay service; epistery
+  carries no name → address mapping.
+- **Does not accept a client's claim of identity.** The only identity is the one
+  epistery itself proved (`req.episteryClient`). There is no "I am contract X"
+  header. Contract identity claims are verified on-chain at `/connect` and sealed
+  into the signed cookie.
+- **Does not let downstream code adjudicate auth.** Re-deriving identity or
+  re-checking signatures outside epistery is a contract violation.
+
+---
+
+## The trust contract: `req.episteryClient`
+
+The attach middleware sets exactly this on each request (or leaves it `undefined`):
+
+| Field             | Meaning |
+|-------------------|---------|
+| `signerAddress`   | **The signer.** The rivet whose signature was verified (cookie session or `Bot`). Always non-null. The only thing the client can assert by itself. |
+| `contractAddress` | **A verified contract claim.** When the client claimed an IdentityContract at `/connect`, this is that contract, verified on-chain via `isAuthorized(contractAddress, signerAddress)`. `null` when no claim. |
+| `identityAddress` | **The canonical identity.** Derived: `contractAddress || signerAddress`. This is what host ACLs evaluate against. Always non-null. |
+| `publicKey`       | The signer's public key. |
+| `authenticated`   | Whether the session/handshake completed. |
+| `authType`        | `"bot"` for `Bot`-signed requests; `"cookie"` for session-cookie. |
+
+The three roles are kept separate on purpose. `signerAddress` is a fact the
+client proves; `contractAddress` is a claim the server verifies; `identityAddress`
+is the server's derivation. The wire never asks the client to pick which role
+its address plays.
+
+**Rule for consumers:** authorize against `identityAddress`. The signer vs.
+contract distinction is available but rarely your concern.
 
 ```javascript
-import express from 'express';
-import https from 'https';
-import { Epistery } from 'epistery';
-
-const app = express();
-
-// Connect and attach epistery
-const epistery = await Epistery.connect();
-await epistery.setDomain('mydomain.com');
-await epistery.attach(app);
-
-// Optional: Add authentication callback
-const episteryWithAuth = await Epistery.connect({
-  authentication: async (clientInfo) => {
-    // clientInfo.address contains the wallet address
-    // Return user profile or null
-    return await getUserProfile(clientInfo.address);
-  },
-  onAuthenticated: async (clientInfo, req, res) => {
-    // Called after successful authentication
-    console.log('User authenticated:', clientInfo.address);
-  }
+app.get('/thing', (req, res) => {
+  const me = req.episteryClient;            // the ONLY source of identity
+  if (!me?.authenticated) return res.status(401).end();
+  // authorize against your host's contracts / policy using me.identityAddress
 });
-
-// Start your server
-const https_server = https.createServer(epistery.config.SNI, app);
-https_server.listen(443);
 ```
 
-This automatically mounts RFC 8615-compliant routes under `/.well-known/epistery/`:
-- `/.well-known/epistery` - Server wallet status (JSON)
-- `/.well-known/epistery/status` - Human-readable status page
-- `/.well-known/epistery/connect` - Client key exchange endpoint
-- `/.well-known/epistery/data/*` - Data wallet operations
-- `/.well-known/epistery/whitelist` - Access control endpoints
+### The wire (POST `/connect`)
 
-## Core Features
+The handshake body carries facts only:
 
-### 1. Authentication
+| Field             | Required | Meaning |
+|-------------------|----------|---------|
+| `signerAddress`   | yes      | The rivet. Must equal the address recovered from `signature` over `message`. |
+| `signerPublicKey` | yes      | The signer's public key. |
+| `contractAddress` | yes      | An IdentityContract claim, or `null`. When non-null, the server verifies it on-chain via `isAuthorized(contractAddress, signerAddress)`. |
+| `challenge`, `message`, `signature` | yes | Proof of signer (see [Identity & key custody](#identity--key-custody)). |
+| `walletSource`    | no       | `"rivet"` / `"fido"` / `"web3"` / etc. — informational. |
 
-Epistery provides cryptographic authentication using Ethereum wallets:
+There is no `clientAddress`, no `identityAddress` on the wire. Either of those
+would force the receiver to guess which role the address plays. The server
+derives `identityAddress` from the two facts and exposes it on
+`req.episteryClient`; the client never tells the server what its identity *is*.
 
-**Client-side:**
-```javascript
-// Load client library in your HTML
-<script src="/.well-known/epistery/lib/client.js"></script>
-<script>
-  const client = new EpisteryClient();
-  await client.connect();  // Automatic key exchange
-  console.log('Connected as:', client.address);
-</script>
-```
+---
 
-**Server-side:**
-```javascript
-// Access authenticated client in routes
-app.get('/profile', (req, res) => {
-  if (req.episteryClient?.authenticated) {
-    res.json({ address: req.episteryClient.address });
-  } else {
-    res.status(401).json({ error: 'Not authenticated' });
-  }
-});
-```
-
-### 2. Data Wallets
+## Identity & key custody
 
-Data wallets are blockchain smart contracts that provide ownership, encryption, sharing, and transfer capabilities for any data. They combine on-chain ownership records with off-chain storage:
+The browser signing key is created and protected by epistery. Custody depends on
+wallet type:
 
-```javascript
-// Client creates data wallet
-const dataWallet = await client.write({
-  title: 'My Document',
-  content: 'Document content...',
-  metadata: { tags: ['important'] }
-});
+| Wallet         | Key custody | Security property |
+|----------------|-------------|-------------------|
+| **RivetWallet** (default) | secp256k1 private key **encrypted at rest** by a **non-extractable** AES-GCM `CryptoKey` held in IndexedDB (WebCrypto). Only ciphertext + a key id are persisted. **Refuses to create the wallet if WebCrypto is unavailable** — no plaintext fallback. | The signing key cannot be exported — the core "unextractable device key" property. |
+| **FidoWallet** | Rivet key wrapped by a WebAuthn PRF secret (Secure Enclave); blob optionally backed up server-side via `/fido/blob` (survives iOS ITP eviction). | Key release gated by platform authenticator. |
+| **Web3Wallet** | External plugin (e.g. MetaMask) holds the key. | Custody is the plugin's. |
 
-// Read data wallet
-const data = await client.read();
+A device can hold **multiple independent rivets** (Browser/FIDO/Web3 are all
+rivets — different ways of presenting a device-locked signing key). This is how
+the system enforces one-key-one-identity without a hard cross-context check: the
+user mints another isolated rivet rather than pointing one key at two contracts.
 
-// Transfer ownership to another address
-await client.transferOwnership(newOwnerAddress);
-```
+Server/domain wallets live in `~/.epistery/<domain>/config.ini` (0600).
 
-**Data Wallet Features:**
-- **Blockchain Contracts**: Each data wallet is a smart contract on-chain
-- **Encryption**: Data can be encrypted before storage
-- **Sharing**: Grant read/write access to specific addresses
-- **Transferable**: Ownership can be transferred to other wallets
-- **IPFS Storage**: Content stored on IPFS by default, with hashes on-chain
-- **Provenance Tracking**: Full ownership and modification history on-chain
+### The `/connect` handshake & contract binding
 
-### 3. Whitelist Management
-
-Control who can access your domain using on-chain whitelists:
-
-```javascript
-// Check if address is whitelisted
-const isAllowed = await epistery.isWhitelisted('0x1234...');
-
-// Get full whitelist
-const whitelist = await epistery.getWhitelist();
-```
+1. The client `Witness` signs a challenge with its rivet and POSTs to `/connect`
+   with `signerAddress` (the rivet), `signerPublicKey`, and `contractAddress`
+   (the claim, or `null`).
+2. The server verifies the signature recovers to `signerAddress`. If
+   `contractAddress` is non-null, it calls `IdentityContract.isAuthorized(signerAddress)`
+   **on-chain** — the chain is truth.
+3. On success it issues the signed `_epistery` cookie, recording `signerAddress`
+   and (if verified) `contractAddress`. The auth middleware then exposes
+   `req.episteryClient.identityAddress = contractAddress || signerAddress`.
 
-Whitelist data is stored on the blockchain and managed through your domain's wallet.
+A rivet is bound to a contract client-side via `wallet.upgradeToContract(contract)`
+— afterward the wallet's derived `identityAddress` is the contract while
+`signerAddress` is still the rivet. A fresh key exchange follows; the witness
+short-circuits when (and only when) the cookie's `identityAddress` already
+matches the wallet's `identityAddress`. The rivet→contract relation in
+localStorage is not cryptographically sealed in the browser — but spoofing it
+is useless: the contract knows its authorized signers and can't be spoofed; the
+on-chain verification at `/connect` is the gate.
 
-### 4. CLI Tools
+---
 
-The Epistery CLI enables authenticated API requests from the command line using bot authentication (stateless, signs each request):
-
-```bash
-# Initialize a CLI wallet
-epistery initialize localhost
-epistery set-default localhost
-
-# Make authenticated GET request
-epistery curl https://api.example.com/data
-
-# PUT request with JSON data (note single quotes)
-epistery curl -X PUT -d '{"title":"Test","body":"Content"}' https://api.example.com/wiki/Test
-
-# Use specific wallet
-epistery curl -w production.example.com https://api.example.com/data
-
-# Verbose output for debugging
-epistery curl -v https://api.example.com/data
-```
+## HTTP interface
 
-Perfect for:
-- Testing authenticated endpoints
-- Building automation scripts
-- Creating bots and agents
-- CI/CD integration
+Mounted under `rootPath` (default `/.well-known/epistery`, RFC 8615):
 
-**CLI uses bot authentication** - each request is independently signed with the wallet's private key, no session management required.
+| Path | Methods | Purpose |
+|------|---------|---------|
+| `/` | GET | Server status JSON (`Witness.connect` probes this for chain/provider info). No HTML UI. |
+| `/lib/:module` | GET | Client libraries (`witness.js`, `wallet.js`, `client.js`, `ethers.js`, …) |
+| `/artifacts/:file` | GET | Contract ABIs/artifacts |
+| `/connect` | GET / POST | Session check / key-exchange handshake (sets `_epistery`; on-chain `isAuthorized` verify for contract claims) |
+| `/create` | GET | Wallet creation helper |
+| `/auth/account/claim`, `/auth/dns/claim`, `/auth/account/check-admin` | GET/POST | Domain claiming & admin checks |
+| `/identity/prepare-add-rivet` | POST | Unsigned tx for adding a rivet to an existing IdentityContract (client signs, then `/data/submit-signed`-style broadcast) |
+| `/domain/initialize` | POST | Initialize a domain wallet |
+| `/fido/blob`, `/fido/blob/:credentialId` | POST/GET | PRF-wrapped rivet key blob storage |
 
-See [CLI.md](CLI.md) for complete CLI documentation.
+---
 
-## Configuration
+## Server API
 
-Epistery uses a path-based configuration system stored in `~/.epistery/` with a filesystem-like API:
+```javascript
+import { Epistery, Config } from 'epistery';
 
+const epistery = await Epistery.connect({
+  authentication:  async (clientInfo) => { /* return profile or null */ },
+  onAuthenticated: async (clientInfo, req, res) => { /* post-auth hook */ },
+});
+await epistery.setDomain('mydomain.com');
+await epistery.attach(app);              // mounts middleware + routes under rootPath
 ```
-~/.epistery/
-├── config.ini                    # Root config (profile, IPFS, defaults)
-├── mydomain.com/
-│   └── config.ini                # Domain config (wallet, provider)
-└── .ssl/
-    └── mydomain.com/             # SSL certificates (optional)
-```
-
-### Root Config (`~/.epistery/config.ini`)
-
-```ini
-[profile]
-name=Your Name
-email=you@example.com
-
-[ipfs]
-url=https://rootz.digital/api/v0
-
-[cli]
-default_domain=localhost
-
-# Which chain the claim-page dropdown selects by default.
-[default]
-defaultChainId=137
-
-# Private RPC overrides, keyed by chainId. Only needed when the chain's
-# built-in public RPC isn't sufficient (rate-limited, needs an API key).
-# Everything else — name, public RPC, currency, fee policy — lives in
-# the chain classes (src/chains/) and doesn't need to be configured.
 
-[default.rpc.137]
-privateRpc=https://polygon-mainnet.infura.io/v3/YOUR_KEY
+The `clientInfo` passed to both hooks has the same shape as
+`req.episteryClient`: `{ signerAddress, contractAddress, identityAddress,
+publicKey }` (plus `authenticated` and `profile` after `authentication`
+resolves). Authorize against `identityAddress`.
 
-[default.rpc.1]
-privateRpc=https://mainnet.infura.io/v3/YOUR_KEY
-```
-
-Legacy single-provider format is also supported:
+`Epistery` (exported as `EpisteryAttach`): `connect`, `setDomain`, `attach`,
+`resolveClient(req)` (auth resolution for non-middleware contexts, e.g. WebSocket
+upgrades), `buildStatus`, `routes`.
 
-```ini
-[default.provider]
-chainId=137
-privateRpc=https://polygon-mainnet.infura.io/v3/YOUR_KEY
-```
+Also exported: `Config`, `chainFor`, `registerChain`, `configuredChains`,
+`defaultChainId`, `Chain`.
 
-### Domain Config (`~/.epistery/mydomain.com/config.ini`)
+The core `Epistery` static API (`src/epistery.ts`): `initialize`, `createWallet`,
+`getStatus`, `handleKeyExchange` (consumed by `/connect`),
+`prepareAddRivetToContract` (unsigned tx builder), `submitSignedTransaction`
+(generic broadcaster for client-signed transactions — this is the
+"server-requests-signature, interactive wallet (FIDO/MetaMask) signs, then submit"
+path).
 
-```ini
-[domain]
-domain=mydomain.com
+### Config
 
-[wallet]
-address=0x...
-mnemonic=word word word...
-publicKey=0x04...
-privateKey=0x...
+Path-based ini config under `~/.epistery` (`src/utils/Config.ts`):
 
-[provider]
-chainId=420420422
-name=polkadot-hub-testnet
-rpc=https://testnet-passet-hub-eth-rpc.polkadot.io
+```javascript
+import { Config } from 'epistery';
+const config = new Config();
+config.setPath('/');             // ~/.epistery/config.ini  (root)
+config.load();
+config.data.profile.email = 'user@example.com';
+config.save();
+config.setPath('/mydomain.com'); // ~/.epistery/mydomain.com/config.ini
 ```
 
-The Config class provides a path-based API that works like navigating a filesystem - set a path, load data, modify it, and save. This makes configuration management simple and predictable across all Epistery applications.
+Methods: `setPath`, `getPath`, `load`, `save` (+ `data`).
 
-## Advanced Usage
+---
 
-### Custom Authentication
+## Client API (`Witness`)
 
-Integrate with your existing user system:
+Served at `/.well-known/epistery/lib/witness.js`:
 
 ```javascript
-const epistery = await Epistery.connect({
-  authentication: async (clientInfo) => {
-    // clientInfo: { address, publicKey }
-
-    // Look up user in your database
-    const user = await db.users.findOne({
-      walletAddress: clientInfo.address
-    });
-
-    if (!user) return null;
-
-    // Return profile data
-    return {
-      id: user.id,
-      username: user.username,
-      permissions: user.permissions
-    };
-  },
-  onAuthenticated: async (clientInfo, req, res) => {
-    // Called after successful authentication
-    // clientInfo includes: address, publicKey, profile, authenticated
-
-    // Set up session, log authentication, etc.
-    req.session.userId = clientInfo.profile.id;
-  }
-});
+import Witness from '/.well-known/epistery/lib/witness.js';
+const witness = await Witness.connect({ rootPath: '/' }); // creates/loads wallet, runs key exchange
 ```
 
-### Configuration Management
+Public surface: `connect`, `performKeyExchange`, `getWallets`, `getStatus`,
+`addBrowserWallet` / `addFidoWallet` / `addWeb3Wallet`, `setDefaultWallet`,
+`removeWallet`, `updateWalletLabel`, `bindToEpisteryIdentity` (cross-host identity
+ferry). Wallet classes: `RivetWallet`, `FidoWallet`, `Web3Wallet`; binding via
+`wallet.upgradeToContract`.
 
-Use Epistery's Config class for secure, path-based configuration:
+Identity properties on every wallet — the canonical surface for client code
+deciding "who am I right now":
 
-```javascript
-import { Config } from 'epistery';
+| Property              | Meaning |
+|-----------------------|---------|
+| `wallet.signerAddress`   | The rivet — the address we sign with. |
+| `wallet.contractAddress` | The bound IdentityContract, or `null`. |
+| `wallet.identityAddress` | Derived: `contractAddress || signerAddress`. What host UI and ACLs should reference. |
 
-const config = new Config('epistery');
+---
 
-// Navigate filesystem-like paths
-config.setPath('/');
-config.load();
-config.data.profile.email = 'user@example.com';
-config.save();
+## CLI
 
-// Domain-specific config
-config.setPath('/mydomain.com');
-config.load();
-config.data.verified = true;
-config.save();
+Stateless bot authentication (each request independently signed):
 
-// Arbitrary paths
-config.setPath('/.ssl/mydomain.com');
-config.load();
-config.data.certData = '...';
-config.save();
+```bash
+epistery initialize localhost
+epistery set-default localhost
+epistery info localhost
+epistery curl https://api.example.com/data
+epistery curl -X PUT -d '{"title":"Test"}' https://api.example.com/wiki/Test
+epistery curl -b -w production.example.com https://api.example.com/data   # -b bot, -w wallet, -v verbose
+epistery mcp https://api.example.com    # stdio MCP bridge with bot-auth
 ```
 
-## Architecture
-
-Epistery follows a plugin architecture that integrates seamlessly with Express.js applications:
-
-- **Server Module** (`/src/epistery.ts`): Core wallet and data wallet operations
-- **Client Libraries** (`/client/*.js`): Browser-side authentication and data wallet tools
-- **CLI** (`/cli/epistery.mjs`): Command-line interface for authenticated requests
-- **Utils** (`/src/utils/`): Configuration, crypto operations, and Aqua protocol implementation
-- **Chains** (`/src/chains/`): Per-chain provider, fee policy, and gas estimation
-
-All endpoints follow RFC 8615 well-known URIs standard for service discovery.
-
-See [Architecture.md](Architecture.md) for detailed architecture documentation.
+Commands: `initialize`, `set-default`, `info`, `curl`, `mcp`, `help`. See
+[CLI.md](CLI.md).
 
-### Chain Support
+---
 
-Each EVM chain epistery talks to is represented by a `Chain` object that owns the JSON-RPC provider, fee policy, gas estimation strategy, and default public RPC. No configuration is needed to use a built-in chain — every detail is in the class itself.
+## Chains
 
-| Chain | ID | Fee Model | Default RPC |
-|-------|----|-----------|-------------|
-| Polygon Mainnet | 137 | EIP-1559, 25 gwei priority floor | polygon-rpc.com |
-| Polygon Amoy | 80002 | EIP-1559, 25 gwei priority floor | rpc-amoy.polygon.technology |
-| Ethereum Mainnet | 1 | Standard EIP-1559 | eth.llamarpc.com |
-| Sepolia Testnet | 11155111 | Standard EIP-1559 | eth-sepolia.public.blastapi.io |
-| Japan Open Chain | 81 | Legacy gasPrice, 30 gwei floor | rpc-2.japanopenchain.org |
+Each EVM chain is a `Chain` object owning its RPC, fee policy, and gas strategy.
+Only `chainId` is required; everything else comes from the class. Use
+`chainFor({ chainId })`; add a chain by extending `Chain` + `registerChain()`.
+See [src/chains/README.md](src/chains/README.md).
 
-Use `chainFor()` to get a chain instance. Only `chainId` is required — everything else comes from the chain class defaults:
+---
 
-```javascript
-import { chainFor, registeredChains } from 'epistery';
+## Versioning & local development
 
-// Minimal — chain class supplies name, RPC, currency, fee policy
-const chain = chainFor({ chainId: 137 });
+- Consumers depend on the **published** package: `npm install epistery@latest`.
+- Local cross-package work installs a **temporary relative path**
+  (`npm install ../../rootz/epistery`) for testing only.
+- Publishing to npm and any deployment is a deliberate, human-performed step. No
+  tooling or agent publishes, bumps versions, or deploys on its own.
 
-// Or with an override — privateRpc for server-side calls with an API key
-const chain = chainFor({ chainId: 137, privateRpc: 'https://polygon-mainnet.infura.io/v3/KEY' });
+---
 
-// Provider with explicit network info (no "could not detect network" errors)
-const wallet = ethers.Wallet.fromMnemonic(mnemonic).connect(chain.provider);
+## Known divergences (audit)
 
-// Per-chain fee data for transaction overrides
-const feeData = await chain.getFeeData();
-// → Polygon: { maxPriorityFeePerGas: 25 gwei, maxFeePerGas: 50 gwei }
-// → JOC:     { gasPrice: 30 gwei }
-// → Ethereum: { maxPriorityFeePerGas: <network>, maxFeePerGas: <network> }
+Where the code currently fails the contract above. Dated; remove as fixed.
 
-// Get the full built-in chain list (for UI dropdowns, etc.)
-const chains = registeredChains();
-```
+**Resolved in v1.2 (2026-05-27 identity-only refactor)**
 
-Adding a new chain is a single file — extend `Chain`, override the fee hooks that differ, and call `registerChain()`. No edits to existing code. See [src/chains/README.md](src/chains/README.md) for details.
+- **Plaintext private keys.** `BrowserWallet` (extractable-key legacy wallet) is
+  removed; `RivetWallet` WebCrypto fallback now **throws** rather than silently
+  storing a plaintext key. No code path persists a cleartext signing key.
+- **`agent.sol` surface.** Data wallets (`/data/*`), approvals (`/approval/*`),
+  whitelist (`/whitelist/*`), on-chain lists/roles (`/lists`, `/list`), name
+  registry (`resolveName`/`setAddressName`), `notabot`, contract creation
+  (`/identity/prepare-deploy`), `contracts/` directory — all removed. epistery
+  is now identity + storage/config + FIDO blob only.
+- **Client header trust path.** Removed at the server boundary in v1.2: the
+  middleware no longer reads `x-identity-contract`; identity is the verified
+  identity epistery itself proved.
 
-## Use Cases
+**Resolved in v1.2 follow-up (2026-05-28 naming cutover)**
 
-- **Decentralized Wikis**: User authentication and content ownership without central accounts
-- **API Authentication**: Replace API keys with wallet-based authentication
-- **Content Attribution**: Track content provenance and ownership on-chain
-- **Access Control**: Manage permissions through blockchain whitelists
-- **Bot/Agent Authentication**: Secure automation with wallet-based identity
+- **Ambiguous identity vocabulary; no in-session rivet→contract upgrade.** The
+  wire used `clientAddress` (alternately the signer or the identity), the
+  server reconstructed which-was-meant on the fly, and `Witness.performKeyExchange`
+  short-circuited by comparing the cookie's address to the signer — so a
+  device that already had a rivet cookie could never have its session re-issued
+  as contract-bound. Replaced with three distinct names everywhere: `signerAddress`
+  (fact, asserted), `contractAddress` (claim, server-verified on-chain), and the
+  derived `identityAddress` (= `contractAddress || signerAddress`, server-only).
+  The witness short-circuits when (and only when) the cookie's `identityAddress`
+  matches the wallet's `identityAddress`. The pre-cutover wire shape
+  (`clientAddress` / `clientPublicKey`) is removed without aliases — old
+  consumers fail at the handshake instead of silently degrading.
 
-## Security
+**Outstanding**
 
-- **Private Key Protection**: Domain configs stored with 0600 permissions (user-only access)
-- **Signature-Only Transmission**: Private keys never transmitted, only cryptographic signatures
-- **Wallet Isolation**: Each domain has its own isolated wallet
-- **Bot Authentication**: Stateless authentication with per-request signing and timestamp-based replay protection
-- **Encrypted Key Exchange**: Browser clients use ECDH for secure shared secret establishment
-- **On-Chain Verification**: Whitelist and ownership data stored immutably on blockchain
+1. **Downstream identity bypass (consumer: `epistery.app`).** Consumers have
+   asserted contract identity via a spoofable `x-identity-contract` header +
+   localStorage instead of consuming the verified `_epistery` cookie. Now
+   unblocked by the cutover above: the consumer's adopt path should call
+   `wallet.upgradeToContract(C)` + `Witness.performKeyExchange()` and read
+   identity from `req.episteryClient.identityAddress`.
 
-## Testing
+2. **Wallet-internal `address` field still flips on upgrade.** `RivetWallet.upgradeToContract`
+   still overwrites `wallet.address` with the contract address (the original
+   rivet survives as `wallet.rivetAddress`). The new `wallet.signerAddress` /
+   `wallet.identityAddress` getters cover the boundary, but every internal
+   caller of `wallet.address` reads an overloaded value. Phase 1b: rename the
+   persistence shape (with one-time IndexedDB migration so existing user
+   wallets keep working) and convert call sites.
 
-```bash
-# Setup test environment (generates wallets automatically)
-npm run test:setup
-
-# Run tests
-npm test
-```
+3. **`PrepareTransactionRequest`/`Response` types.** Reference removed
+   `agent.sol` operations (`write` / `transferOwnership` / `createApproval`
+   / etc.); imported but no longer consumed. Delete in the next dead-code sweep.
 
-The setup script creates `.test.env` with generated wallet credentials. For integration tests requiring a deployed contract, add `TEST_CONTRACT_ADDRESS` to `.test.env` after running `npm run deploy:agent`.
+---
 
 ## License
 
-MIT License - see [LICENSE](LICENSE) for details
+MIT — see [LICENSE](LICENSE).
 
 ## Links
 
-- **Homepage**: https://epistery.com
-- **Repository**: https://github.com/rootz-global/epistery
-- **Documentation**: See [CLI.md](CLI.md), [Architecture.md](Architecture.md), [SESSION.md](SESSION.md)
+- Repository: https://github.com/rootz-global/epistery
+- See [CLI.md](CLI.md), [Architecture.md](Architecture.md), [SESSION.md](SESSION.md)