epistery 2.0.4 → 2.2.0

package/docs/RivetSignerConfigAuthority.md

@@ -0,0 +1,219 @@
+# Rivet Signer & Config Authority — Interface Spec
+
+Status: draft for review · 2026-06-23 · feeds RootzOracleTenancy · repo: `epistery-authority` (instance `epistery-authority-1`)
+
+This specifies the **interfaces** for turning `~/.epistery` local state into a shared
+configuration/key authority, so pool members become stateless and interchangeable.
+Interfaces first — no implementation here. It is the contract the authority, the
+`Config` rewrite, and the client/server signers all build against.
+
+## 0. The one idea
+
+A **rivet** is *an unextractable-but-usable signing identity*. The private key lives
+with a **custodian** that never hands it out; callers get **signatures**, not keys.
+
+This is already true client-side. `client/wallet.js` `RivetWallet` keeps the secp256k1
+key encrypted under a non-extractable WebCrypto AES key in IndexedDB and only ever
+decrypts it inside a function closure that signs and returns (`wallet.js:399-434`,
+`446-490`); `FidoWallet` wraps the key with a WebAuthn-PRF-derived key in the Secure
+Enclave (`wallet.js:1272-1316`). The key never escapes the custodian.
+
+The **server rivet** is the same object with a different custodian: the domain wallet's
+key lives in `epistery-authority-1` and is used via a signing RPC. Today that key is the
+plaintext mnemonic in `~/.epistery/<domain>/config.ini`, and **six call sites
+independently re-derive a wallet from it** — `Utils.ts:80`, `epistery.ts:109` & `:170`,
+host `DomainChain.mjs:78` & `index.mjs:239`, `relay/index.mjs:141`
+(plus `message-board` and `chat/` deploy scripts). That scatter is the parallel-channel
+we are collapsing into one owner.
+
+```
+            custodian (holds key, never releases)        rivet (used via signatures)
+client      WebCrypto/IndexedDB  |  FIDO Secure Enclave   RivetWallet | FidoWallet
+server      epistery-config-1 (HSM/TPM)                   RemoteSigner (domain wallet)
+```
+
+The custodian/rivet split is the shared abstraction. The authority is to the server
+rivet what the FIDO authenticator is to the client rivet.
+
+## 1. `Rivet` — the capability interface (shared)
+
+The narrow async contract every rivet satisfies, regardless of custodian. All methods
+are async because a remote/HSM/FIDO custodian cannot answer synchronously.
+
+```ts
+export interface Rivet {
+  readonly address: string;        // the rivet (signer) address — always present
+  readonly publicKey: string;      // uncompressed secp256k1, 0x04…
+  getAddress(): Promise<string>;
+  signMessage(message: string | Uint8Array): Promise<string>;
+  signTransaction(tx: UnsignedTransaction): Promise<string>;   // returns raw signed tx hex
+  // Optional ECDH peer crypto — implemented by custodians that can compute a
+  // shared secret without exposing the key (RivetWallet/FidoWallet do this today,
+  // wallet.js:495-530, 1321-1331). The authority MAY offer it as an RPC.
+  encryptForPeer?(peerPublicKey: string, plaintext: Uint8Array): Promise<EciesBlob>;
+  decryptFromPeer?(peerPublicKey: string, blob: EciesBlob): Promise<Uint8Array>;
+}
+```
+
+Notes:
+- This intentionally matches ethers v5 `Signer`'s `getAddress`/`signMessage`/
+  `signTransaction`. The **server realization of `Rivet` is an `ethers.Signer`**
+  (`RemoteSigner extends ethers.Signer`) because every server caller already consumes
+  a `Signer` (`Utils.InitServerWallet` returns `ethers.Wallet` today). So adopting
+  `Rivet` on the server is a no-op at the call sites — only the construction changes.
+- The **client `Wallet` hierarchy is adapted to `Rivet`**: drop the `ethers` argument
+  threaded through `sign(message, ethers)`/`signTransaction(tx, ethers)` (the browser
+  no-bundler quirk) by binding `ethers` at construction; expose `getAddress`. The
+  identity getters (`signerAddress`, `identityAddress`, `wallet.js:36-44`) stay — they
+  are an identity concern layered above signing, not part of `Rivet`.
+
+## 2. Two server rivets, layered
+
+| Rivet | Custodian | Unextractable | Purpose |
+|---|---|---|---|
+| **machine/device rivet** | the box's TPM (self-minted per instance, per the wiki) | yes (hardware) | authenticates *this host* to the authority |
+| **domain server rivet** | `epistery-authority-1` | Phase 2: yes | the on-chain identity the authority wields *on behalf of* authorized machines |
+
+A pool member never holds the domain key. It proves itself with its machine rivet, and
+borrows the domain rivet's signature from the authority. **N stateless machines share
+one on-chain domain identity without sharing its key** — the wiki's statelessness and
+its security story in one sentence.
+
+## 3. `Config` becomes async (breaking)
+
+Decided: all clients upgrade; no sync-snapshot shim. `Config` keeps its path-based shape
+(`src/utils/Config.ts`) but `load`/`save`/`setPath`/`read` become async fetch/push points;
+`.data` reflects the last `await`ed load.
+
+```ts
+export interface ConfigStore {
+  setPath(path: string): Promise<void>;   // was sync; now awaits a fetch in remote mode
+  getPath(): string;
+  load(): Promise<void>;
+  read(path: string): Promise<any>;       // read without moving current path
+  save(): Promise<void>;
+  readFile(name: string): Promise<Buffer>;
+  writeFile(name: string, data: string | Buffer): Promise<void>;
+  exists(): Promise<boolean>;
+  listPaths(): Promise<string[]>;
+  data: any;                               // snapshot from the last load()
+}
+```
+
+**Backend selection** happens in the `Config` constructor:
+- If local `~/.epistery/config.ini` has `[authority] url=…`, or `EPISTERY_CONFIG_URL`
+  is set → `RemoteConfig` (talks to `epistery-config-1`).
+- Else → `LocalConfig` (today's filesystem behavior, unchanged).
+
+The local file never disappears — in remote mode it shrinks to **bootstrap state**: the
+authority URL and this machine's credential (its machine-rivet handle). That is the
+"machine data" the wiki carves out and the only per-box state a pool member keeps.
+
+**Public/secret split in the data model.** Today `[wallet]` co-mingles public
+(`address`, `publicKey`) and secret (`mnemonic`, `privateKey`) — `types.ts:18-23`. The
+authority must serve the public fields freely and treat the secret as custodied:
+
+| Class | Examples | Phase 1 | Phase 2 |
+|---|---|---|---|
+| public config | provider, contract addresses, claim state, prefs | served R/W | served R/W |
+| signing key | wallet mnemonic / privateKey | released | **never released — authority signs** |
+| opaque secret blob | TLS cert+key, storj/S3, mongo password | released to authorized machines | released (governed safe; cannot be HSM'd) |
+
+**The authority is also a safe.** `readFile`/`writeFile` already persist arbitrary
+blobs (`Config.ts:151-163`), and `Config`'s `.ssl/<domain>` path is already in the path
+model — so the authority is two things at once: an **HSM** for signing keys (never
+released) and a **safe** for opaque blobs (governed release via `/file/*path/:name`).
+Anything that is a *bearer* secret — a key the host must itself present to a third party
+or to a TLS handshake — lives in the safe, because the authority can't wield it remotely
+the way it wields an Ethereum signing key.
+
+## 4. Authority HTTP API
+
+Auth is the **rivet key-exchange already in the codebase** (`Epistery.handleKeyExchange`,
+`epistery.ts:82-137`; wire shapes `KeyExchangeRequest`/`Response`, `types.ts:98-117`),
+pointed at the authority. One mechanism, not a bespoke machine-auth.
+
+```
+POST /auth/challenge   { machineAddress }                  -> { challenge }
+POST /auth/verify      { machineAddress, message, signature, publicKey }
+                       message = "Epistery Key Exchange - <machineAddress> - <challenge>"
+                                                            -> { token }            # session/bearer
+
+# Config data (token-gated; ACL decides which paths this machine may see)
+GET  /config/*path                                          -> { data }            # public fields only
+PUT  /config/*path     { data }                             -> { ok }
+GET  /config/*path/_paths                                   -> { paths: string[] }
+GET  /file/*path/:name                                      -> bytes
+PUT  /file/*path/:name                                       <- bytes
+
+# Server rivet — public info always; key material governed
+GET  /wallet/:domain                                        -> { address, publicKey }   # never the key
+POST /sign/message     { domain, message }                  -> { signature }            # Phase 2
+POST /sign/transaction { domain, tx }                       -> { signedTransaction }    # Phase 2
+GET  /secret/:domain/:name                                  -> { value }                # governed release (storj/mongo)
+```
+
+Governance ("like a CA"): the authority's ACL — keyed on the **machine rivet** — decides
+which domains a host may read and which signing ops it may request. That is the
+authority's reason to exist over a network share.
+
+## 5. `RemoteSigner` — server-side rivet realization (Phase 2)
+
+```ts
+class RemoteSigner extends ethers.Signer implements Rivet {
+  constructor(domain, authorityClient, provider) { super(); /* … */ }
+  async getAddress()              { return (await this.authority.wallet(this.domain)).address; }
+  async signMessage(message)      { return this.authority.signMessage(this.domain, message); }
+  async signTransaction(tx)       { return this.authority.signTransaction(this.domain, tx); }
+  connect(provider)               { return new RemoteSigner(this.domain, this.authority, provider); }
+  // sendTransaction is inherited: signTransaction (remote) then provider.broadcast (local) —
+  // so RPC/broadcast stay on the host; only the signature is remote.
+}
+```
+
+`Utils.InitServerWallet(domain)` is the **single owner** of "get a signer for this
+domain." It returns a `LocalWallet` (today / Phase 1) or a `RemoteSigner` (Phase 2)
+behind the same `ethers.Signer` type. The six scattered `fromMnemonic` sites all route
+through it — that consolidation is Phase 0 and is what makes Phase 2 a transport swap
+rather than a client rewrite.
+
+## 6. How each consumer adapts
+
+- **epistery-host** — `await` the new `Config`; reads domain config/claim state from the
+  authority; gets its domain signer from `Utils.InitServerWallet` (already does, via
+  `app.locals.epistery.signer`). `DomainChain.mjs:78` & `index.mjs:239` stop calling
+  `fromMnemonic` and ask `Utils`. TLS certs are a separate workstream (see §8).
+- **epistery-app** — minimal: `await` the root config reads (`relayUrl`, `helpOwner`);
+  manifest signing already goes through `epistery.signer`, so no signer change.
+- **relay** — **subordinate, not merged.** Keeps credit metering, broadcast, and on-chain
+  identity *reads*. Its pool wallet (`index.mjs:141`) becomes a domain rivet custodied by
+  the authority: drop `fromMnemonic`, fetch a signer from the authority. Relay then pools
+  too.
+- **cli** (`CliWallet.ts`) — `await` Config; `CliWallet.create/load` obtain signers via
+  the same path instead of `fromMnemonic`/`new Wallet(privateKey)` (`CliWallet.ts:153-156`).
+
+## 7. Invariants
+
+1. One owner for "get a signer": `Utils.InitServerWallet`. No other site derives a wallet
+   from key material.
+2. The custodian never emits a signing key in Phase 2. `GET /wallet/:domain` returns
+   address/publicKey only.
+3. The rivet key-exchange is the only host↔authority auth mechanism.
+4. `Rivet` is the shared capability; `ethers.Signer` is its server realization; the client
+   `Wallet` hierarchy is adapted to it. No second signing abstraction.
+
+## 8. Open gaps (call out, don't assume)
+
+- **TLS certs — not a blocker.** Certs persist as-is through the safe (`writeFile`/
+  `readFile` + `/file/.ssl/<domain>/…`), so the wiki's "certs live in the shared authority"
+  goal needs no special machinery: a pool member fetches its cert+key blob and self-
+  terminates TLS, NLB stays dumb L4. Certify/ACME (`@metric-im/administrate`) can keep
+  issuing and just write the result into the safe. A more elegant SSL flow (authority-
+  driven issuance/rotation) is possible later but is **not important now**.
+- **Nonce/ordering.** Once one domain rivet signs for N hosts, transaction nonce management
+  must centralize (at the authority or a per-domain sequencer) or concurrent hosts collide.
+- **Availability.** The authority becomes a hard dependency for any signing host. Needs a
+  bootstrap cache / degraded-mode policy decision.
+- **rootz-v6 alignment.** This mirrors the identity-owned Secret pattern; align at the
+  Solidity/interface level only, per standing guidance — no shared library yet.
+```

package/index.mjs

@@ -11,13 +11,12 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
 // Helper function to get or create domain configurations src/utils/Config.ts system
-function getDomainConfig(domain) {
-  let domainConfig = Utils.GetDomainInfo(domain);
-  if (!domainConfig?.wallet) {
-    Utils.InitServerWallet(domain);
-    domainConfig = Utils.GetDomainInfo(domain);
-  }
-  return domainConfig;
+async function getDomainConfig(domain) {
+  // InitServerWallet warms the per-domain wallet cache (and creates+persists a
+  // wallet on first touch). Awaiting it here keeps the synchronous `get signer()`
+  // getter able to read the cache via Utils.GetServerWalletFor.
+  await Utils.InitServerWallet(domain);
+  return await Utils.GetDomainInfo(domain);
 }
 
 class EpisteryAttach {
@@ -36,7 +35,7 @@ class EpisteryAttach {
 
   async setDomain(domain) {
     this.domainName = domain;
-    this.domain = getDomainConfig(domain);
+    this.domain = await getDomainConfig(domain);
   }
 
   /**
@@ -45,7 +44,9 @@ class EpisteryAttach {
    */
   get signer() {
     if (!this.domainName) return null;
-    return Utils.InitServerWallet(this.domainName) || null;
+    // Synchronous read of the cache warmed by setDomain()→getDomainConfig()→
+    // InitServerWallet. Keeps `.signer` a sync getter despite the async config.
+    return Utils.GetServerWalletFor(this.domainName) || null;
   }
 
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "epistery",
-  "version": "2.0.4",
+  "version": "2.2.0",
   "description": "Epistery brings blockchain capabilities to mundane web tasks like engagement metrics, authentication and commerce of all sorts.",
   "author": "Rootz Corp.",
   "license": "MIT",

package/routes/auth.mjs

@@ -25,7 +25,7 @@ export default function authRoutes(epistery) {
           .json({ status: "error", message: "Domain not found" });
       }
 
-      epistery.config.setPath(domain);
+      await epistery.config.setPath(domain);
 
       if (epistery.config.data && epistery.config.data.verified) {
         return res
@@ -97,7 +97,7 @@ export default function authRoutes(epistery) {
         });
       }
 
-      epistery.config.setPath(domain);
+      await epistery.config.setPath(domain);
 
       if (epistery.config.data && epistery.config.data.verified) {
         return res
@@ -125,7 +125,7 @@ export default function authRoutes(epistery) {
       epistery.config.data.challenge_requester_ip = req.ip;
       epistery.config.data.provider = providerConfig;
 
-      epistery.config.save();
+      await epistery.config.save();
       console.log(
         `Domain claim initiated: ${domain} by ${normalizedClientAddress}`,
       );
@@ -149,7 +149,7 @@ export default function authRoutes(epistery) {
           .json({ status: "error", message: "Domain not found" });
       }
 
-      epistery.config.setPath(domain);
+      await epistery.config.setPath(domain);
 
       if (!epistery.config.data.pending) {
         return res.status(400).json({
@@ -208,7 +208,7 @@ export default function authRoutes(epistery) {
       delete epistery.config.data.challenge_token;
       delete epistery.config.data.challenge_address;
       delete epistery.config.data.challenge_requester_ip;
-      epistery.config.save();
+      await epistery.config.save();
 
       res.json({ status: "success", message: "Domain claimed successfully" });
     } catch (error) {
@@ -229,7 +229,7 @@ export default function authRoutes(epistery) {
         return res.json({ isAdmin: false });
       }
 
-      epistery.config.setPath(domain);
+      await epistery.config.setPath(domain);
 
       if (
         !epistery.config.data ||

package/routes/domain.mjs

@@ -24,7 +24,7 @@ export default function domainRoutes(epistery) {
 
       // Check if domain already exists
       const config = Utils.GetConfig();
-      config.setPath(domain);
+      await config.setPath(domain);
 
       let domainConfig = config.data;
       if (!domainConfig.domain) domainConfig.domain = domain;
@@ -37,7 +37,7 @@ export default function domainRoutes(epistery) {
         };
 
       // Save domain config with custom provider (marked as pending)
-      config.save();
+      await config.save();
 
       res.json({
         status: "success",

package/routes/fido.mjs

@@ -64,8 +64,8 @@ export default function fidoRoutes(epistery) {
         return res.status(500).json({ error: "Domain not set" });
       }
 
-      epistery.config.setPath(`/${domain}/fido`);
-      epistery.config.writeFile(
+      await epistery.config.setPath(`/${domain}/fido`);
+      await epistery.config.writeFile(
         `${credentialId}.json`,
         JSON.stringify({
           credentialId,
@@ -97,11 +97,11 @@ export default function fidoRoutes(epistery) {
         return res.status(500).json({ error: "Domain not set" });
       }
 
-      epistery.config.setPath(`/${domain}/fido`);
+      await epistery.config.setPath(`/${domain}/fido`);
 
       let buf;
       try {
-        buf = epistery.config.readFile(`${credentialId}.json`);
+        buf = await epistery.config.readFile(`${credentialId}.json`);
       } catch (e) {
         return res.status(404).json({ error: "Blob not found" });
       }

package/src/chains/registry.ts

@@ -82,9 +82,9 @@ export function registeredChains(): ChainConfig[] {
  *
  * Chains without a config override are returned unchanged.
  */
-export function configuredChains(): ChainConfig[] {
+export async function configuredChains(): Promise<ChainConfig[]> {
   const config = new Config();
-  const rootData = config.read('/');
+  const rootData = await config.read('/');
   return registeredChains().map(chain => {
     const id = String(chain.chainId);
     const privateRpc = rootData?.default?.rpc?.[id]?.privateRpc
@@ -101,9 +101,9 @@ export function configuredChains(): ChainConfig[] {
  * Checks `[default] defaultChainId`, then `[default.provider] chainId`,
  * falling back to Polygon mainnet (137).
  */
-export function defaultChainId(): string {
+export async function defaultChainId(): Promise<string> {
   const config = new Config();
-  const rootData = config.read('/');
+  const rootData = await config.read('/');
   return String(
     rootData?.default?.defaultChainId
     || rootData?.default?.provider?.chainId

package/src/epistery.ts

@@ -43,7 +43,7 @@ export class Epistery {
     return clientWalletInfo;
   }
 
-  public static getStatus(client: ClientWalletInfo, server: DomainConfig): EpisteryStatus {
+  public static async getStatus(client: ClientWalletInfo, server: DomainConfig): Promise<EpisteryStatus> {
     // Build nativeCurrency object from flat fields with sensible defaults
     let nativeCurrency = undefined;
     if (server?.provider?.nativeCurrencySymbol) {
@@ -56,7 +56,7 @@ export class Epistery {
 
     // Read IPFS config from root config
     const config = Utils.GetConfig();
-    const rootConfig = config.read('/');
+    const rootConfig = await config.read('/');
     const ipfsConfig = rootConfig.ipfs;
 
     const status: EpisteryStatus = {
@@ -155,7 +155,7 @@ export class Epistery {
   ): Promise<any> {
     // RPC comes from ~/.epistery via Config (GetDomainInfo falls back to root
     // [provider]); never process.env — env is for deployment vars only.
-    const domainInfo = Utils.GetDomainInfo(domain);
+    const domainInfo = await Utils.GetDomainInfo(domain);
     const rpcUrl = domainInfo?.provider?.rpc;
     if (!rpcUrl) {
       throw new Error(`No provider RPC configured in ~/.epistery for domain "${domain}"`);
@@ -307,7 +307,7 @@ export class Epistery {
     // RPC from ~/.epistery root config via Config — not process.env. A signed
     // tx already encodes its chainId; we just need the network's RPC, which
     // single-domain apps declare once at root [provider].
-    const rootData = Utils.GetConfig().read('/');
+    const rootData = await Utils.GetConfig().read('/');
     const rpcUrl = rootData.provider?.rpc ?? rootData.default?.provider?.rpc;
     if (!rpcUrl) {
       throw new Error('No provider RPC configured in ~/.epistery (root [provider])');

package/src/utils/CliWallet.ts

@@ -67,32 +67,38 @@ export class CliWallet {
   /**
    * Get the default domain from config.ini [cli] section
    */
-  static getDefaultDomain(): string {
+  static async getDefaultDomain(): Promise<string> {
     const config = new Config();
+    await config.setPath('/');
     return (config.data as any).cli?.default_domain || 'localhost';
   }
 
   /**
-   * Set the default domain in config.ini [cli] section
+   * Set the default domain in config.ini [cli] section.
+   *
+   * Loads the root config first so the rest of it ([profile], [default.provider],
+   * …) is preserved on save. (Before the async migration, Config did not
+   * auto-load on construction, so this wrote {cli:…} over the whole root file.)
    */
-  static setDefaultDomain(domain: string): void {
+  static async setDefaultDomain(domain: string): Promise<void> {
     const config = new Config();
+    await config.setPath('/');
     if (!(config.data as any).cli) {
       (config.data as any).cli = {};
     }
     (config.data as any).cli.default_domain = domain;
-    config.save();
+    await config.save();
   }
 
   /**
    * Initialize a new domain with wallet
    * Creates ~/.epistery/{domain}/config.ini with new wallet
    */
-  static initialize(domain: string, provider?: { name: string, chainId: number, rpc: string }): CliWallet {
+  static async initialize(domain: string, provider?: { name: string, chainId: number, rpc: string }): Promise<CliWallet> {
     const config = new Config();
 
     // Check if domain already exists
-    config.setPath(domain);
+    await config.setPath(domain);
     if (config.data.wallet) {
       throw new Error(`Domain '${domain}' already initialized. Use load() to access it.`);
     }
@@ -101,7 +107,7 @@ export class CliWallet {
     const ethersWallet = ethers.Wallet.createRandom();
 
     // Get provider from root default, argument, or fallback default
-    config.setPath('/');
+    await config.setPath('/');
     const providerConfig = provider || config.data.default?.provider || {
       chainId: 420420422,
       name: 'polkadot-hub-testnet',
@@ -109,7 +115,7 @@ export class CliWallet {
     };
 
     // Create domain config
-    config.setPath(`/${domain}`);
+    await config.setPath(`/${domain}`);
     config.data = {
       domain: domain,
       wallet: {
@@ -120,7 +126,7 @@ export class CliWallet {
       },
       provider: providerConfig
     };
-    config.save();
+    await config.save();
 
     console.log(`Initialized domain: ${domain}`);
     console.log(`Address: ${ethersWallet.address}`);
@@ -133,12 +139,11 @@ export class CliWallet {
    * Load domain wallet from config
    * Throws if domain doesn't exist - use initialize() first
    */
-  static load(domain?: string): CliWallet {
+  static async load(domain?: string): Promise<CliWallet> {
     const config = new Config();
-    const domainName = domain || CliWallet.getDefaultDomain();
+    const domainName = domain || await CliWallet.getDefaultDomain();
 
-    config.setPath(`/${domainName}`);
-    config.load();
+    await config.setPath(`/${domainName}`);
 
     if (!config.data.wallet) {
       throw new Error(