epistery 1.0.0

package/Architecture.md

@@ -0,0 +1,84 @@
+# Plug in architecture
+
+This module is a plugin. It provides a host with data-wallet services exposed through
+host.tld/.well-known/epistery. Epistery will create wallets for both the client (browser)
+and the server if not otherwise provided. It provides the foundation methods for creating,
+validating and manipulating data-wallets.
+
+Server code is available through web calls. The
+client is implemented with a browser script available from client.js.
+
+## Structure
+This is a typescript project build on express.
+
+| path                   | description                                                                                                      |
+|------------------------|------------------------------------------------------------------------------------------------------------------|
+| /index.mjs             | Entry point harness                                                                                              |
+| /client                | Assets and scripts intended to be embedded in the browser page                                                   |
+| /client/client.js      | client-side counterpart to /epistery.ts.                                                                         |
+| /client/ethers.js      | Core blockchain tools                                                                                            |
+| /client/status.html    | The template page rendered by /.well-known/epistery/status. This is the only human readable content presented by /.epistery |
+| /client/witness.js     |                                                                                                                  |
+| /src                   | implementation                                                                                                   |
+| /src/controllers/      | Controllers provide discreet services usually behind a named route /.well-known/epistery/[controller]                       |
+| /src/utils             | Shared tools that assist the controllers                                                                         |
+| /src/utils/Aqua.ts     | Aqua protocol implementation that underlies the data wallet implementation                                       |
+| /src/utils/Config.ts   | Interface to the $HOME/.epistory/config.ini and dependent configuration data                                     |
+| /src/utils/types.ts    | Typescript common schema                                                                                         |
+| /src/utils/Utils.ts    | (Not sure. Seems like these methods should be attached to something with a named purpose                         |
+| /src/utils/index.ts    | Import root for reach all utilities                                                                              |
+| /src/epistery.ts       | Root class that is connected by the host                                                                         |
+| /test                  | A barebones host application to provide sample code and exercise the features                                    |
+| /default.ini           | template configuration for initialising a new installation                                                       |
+
+>NOTE: api.ts is left out. I propose that if we want a standalone generic implementation of the epistery plugin,
+> it should be implemented in a separate repo.
+
+## Data Wallets
+The core purpose of the epistery plugin is manage the creation and manipulation of data wallets. This manifests as api's
+invoked by the browser and partner sites
+
+All of the Data Wallet functionality is found in the in /src/controllers/DataWalletController, operating behind .well-known/epistery/data. Utils
+is used for common cryto functionaility and other tools
+
+## Signing Wallets
+
+## Config File
+System configuration is managed with ini files in $HOME/.epistery. The root defines config.ini which has system wide
+settings. The default settings are captured in default.ini. Each domain that has been initialized will have a folder
+with it's own config.ini file, as well as key files and other persistent settings.
+
+The root config file is structured into the following sections
+
+```ini
+[profile]
+  name=
+  email=
+[ipfs]
+ url=https://rootz.digital/api/v0
+[default.provider]
+// When a domain is initialized, it defaults to this provide info which is subsequencly saved with the domain config.ini
+ chainId=
+ name=
+ rpc=
+```
+
+A domain config file, like `$HOME/.epistery/mydomain.com/config.ini`, includes:
+
+```ini
+[provider]
+chainId=
+name=
+rpc=
+
+[wallet]
+address=
+mnemonic=
+publicKey=
+privateKey=
+
+[ssl]
+key=
+cert=
+modified=
+```

package/CLI.md

@@ -0,0 +1,291 @@
+# Epistery CLI
+
+Command-line interface for Epistery authentication and requests.
+
+## Quick Start
+
+```bash
+# Initialize a domain (creates wallet in ~/.epistery/{domain}/)
+epistery initialize localhost
+
+# Set as default
+epistery set-default localhost
+
+# Make authenticated requests (automatic key exchange on first use)
+epistery curl https://wiki.rootz.global/wiki/Home
+```
+
+## Commands
+
+### `epistery initialize <domain>`
+
+Initialize a domain with a new wallet. Creates `~/.epistery/{domain}/config.ini` with:
+- Wallet (address, keys, mnemonic)
+- Provider configuration (from `~/.epistery/config.ini` default)
+
+```bash
+epistery initialize localhost
+epistery initialize wiki.rootz.global
+```
+
+### `epistery curl [options] <url>`
+
+Make authenticated HTTP request. Automatically performs key exchange on first use.
+
+**Options:**
+- `-w, --wallet <domain>` - Use specific domain (overrides default)
+- `-X, --request <method>` - HTTP method (default: GET)
+- `-d, --data <data>` - Request body data
+- `-H, --header <header>` - Additional headers
+- `-b, --bot` - Use bot auth header (default: session cookie)
+- `-v, --verbose` - Show detailed output
+
+**Examples:**
+```bash
+# GET request (uses default domain)
+epistery curl https://wiki.rootz.global/wiki/Home
+
+# Use specific domain
+epistery curl -w localhost https://localhost:4080/session/context
+
+# POST request
+epistery curl -X POST -d '{"title":"Test","body":"# Test"}' https://wiki.rootz.global/wiki/Test
+
+# Bot mode (no session, sign per request)
+epistery curl --bot https://wiki.rootz.global/session/context
+```
+
+### `epistery info [domain]`
+
+Show domain information (wallet address, provider, session status).
+
+```bash
+epistery info                # Show default domain
+epistery info localhost      # Show specific domain
+```
+
+### `epistery set-default <domain>`
+
+Set default domain for CLI operations.
+
+```bash
+epistery set-default localhost
+```
+
+## Architecture
+
+### Domain-Based Configuration
+
+Epistery CLI uses the same domain configuration system as the server:
+
+```
+~/.epistery/
+├── config.ini                    # Root config with [cli] section
+│   └── [cli]
+│       └── default_domain=localhost
+├── localhost/
+│   ├── config.ini                # Domain config with wallet & provider
+│   └── session.json              # Session cookie (auto-created)
+└── wiki.rootz.global/
+    ├── config.ini
+    └── session.json
+```
+
+### Authentication Modes
+
+**Session Cookie (Default):**
+- Performs key exchange once, saves session cookie
+- Subsequent requests use cookie
+- Best for multiple requests to same server
+
+**Bot Auth Header (`--bot`):**
+- Signs each request individually
+- No session management
+- Best for distributed systems or one-off requests
+
+### Automatic Key Exchange
+
+The `curl` command automatically performs key exchange when needed:
+
+1. Check for existing session in `~/.epistery/{domain}/session.json`
+2. If no session, perform key exchange with server
+3. Save session cookie for future requests
+4. Make the actual HTTP request
+
+No manual "connect" step required!
+
+## Usage Patterns
+
+### Local Development
+
+```bash
+# Initialize for local development
+epistery initialize localhost
+epistery set-default localhost
+
+# Make requests
+epistery curl https://localhost:4080/wiki/index
+epistery curl -X PUT -d '{"title":"Test","body":"# Test"}' https://localhost:4080/wiki/Test
+```
+
+### Multiple Domains
+
+```bash
+# Initialize multiple domains
+epistery initialize localhost
+epistery initialize wiki.rootz.global
+epistery initialize staging.example.com
+
+# Switch between them
+epistery curl -w localhost https://localhost:4080/...
+epistery curl -w wiki.rootz.global https://wiki.rootz.global/...
+epistery curl -w staging.example.com https://staging.example.com/...
+
+# Or set default and omit -w
+epistery set-default wiki.rootz.global
+epistery curl https://wiki.rootz.global/...
+```
+
+### Bot/Agent Applications
+
+```javascript
+import { CliWallet } from 'epistery';
+
+// Load domain wallet
+const wallet = CliWallet.load('localhost');  // or CliWallet.load() for default
+
+// Create bot auth header
+const authHeader = await wallet.createBotAuthHeader();
+
+// Make request
+const response = await fetch('https://localhost:4080/wiki/Home', {
+  headers: { 'Authorization': authHeader }
+});
+```
+
+## Configuration Files
+
+### Root Config (`~/.epistery/config.ini`)
+
+```ini
+[profile]
+name=
+email=
+
+[ipfs]
+url=https://rootz.digital/api/v0
+
+[default.provider]
+chainId=420420422,
+name=polkadot-hub-testnet
+rpc=https://testnet-passet-hub-eth-rpc.polkadot.io
+
+[cli]
+default_domain=localhost
+```
+
+### Domain Config (`~/.epistery/{domain}/config.ini`)
+
+```ini
+[domain]
+domain=localhost
+
+[wallet]
+address=0x...
+mnemonic=word word word...
+publicKey=0x04...
+privateKey=0x...
+
+[provider]
+chainId=420420422,
+name=polkadot-hub-testnet
+rpc=https://testnet-passet-hub-eth-rpc.polkadot.io
+```
+
+### Session File (`~/.epistery/{domain}/session.json`)
+
+Auto-created by `epistery curl`:
+
+```json
+{
+  "domain": "https://wiki.rootz.global",
+  "cookie": "session_token_here",
+  "authenticated": true,
+  "timestamp": "2025-01-10T12:00:00.000Z"
+}
+```
+
+## Security
+
+- Domain configs stored with 0600 permissions (user only)
+- Private keys never transmitted (only signatures)
+- Each domain has its own isolated wallet
+- Session cookies saved securely per domain
+
+## Design Philosophy
+
+The Epistery CLI uses a unified command structure with subcommands:
+- ✅ Uses existing Epistery domain config system
+- ✅ Consistent with server-side architecture
+- ✅ Automatic key exchange (no manual connect step)
+- ✅ Default domain support (less typing)
+- ✅ Simpler mental model (domain = wallet)
+
+## Examples
+
+### Initialize and Use
+
+```bash
+# Setup
+epistery initialize localhost
+epistery set-default localhost
+
+# Use
+epistery curl https://wiki.rootz.global/wiki/Home
+epistery curl https://wiki.rootz.global/wiki/index
+```
+
+### Multiple Domains
+
+```bash
+# Setup each environment
+epistery initialize dev.example.com
+epistery initialize staging.example.com
+epistery initialize prod.example.com
+
+# Use different environments
+epistery curl -w dev.example.com https://dev.example.com/api/status
+epistery curl -w staging.example.com https://staging.example.com/api/status
+epistery curl -w prod.example.com https://prod.example.com/api/status
+```
+
+### Bot Mode
+
+```bash
+# Bot mode doesn't need session, signs each request
+epistery curl --bot https://wiki.rootz.global/session/context
+epistery curl --bot -X POST -d '{"title":"Log","body":"# Entry"}' https://wiki.rootz.global/wiki/Log
+```
+
+## Troubleshooting
+
+**"Domain not found or has no wallet"**
+- Run `epistery initialize <domain>` first
+
+**"Key exchange failed"**
+- Check server is running and accessible
+- Verify URL is correct
+- Use `-v` flag for detailed output
+
+**"Failed to obtain session cookie"**
+- Server may not be setting cookies
+- Try `--bot` mode instead
+- Check server configuration
+
+## Integration
+
+The CLI is designed to work with:
+- **Rhonda** - Wiki with Epistery authentication
+- **Any Epistery-enabled app** - Just initialize and curl!
+
+Server-side apps should implement bot authentication handler (see Rhonda's account-server for example).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 rootz-global
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MONGODB_GOTCHA.md

@@ -0,0 +1,69 @@
+# MongoDB Object _id Field Order Sensitivity
+
+## The Problem
+
+MongoDB treats object `_id` fields as **order-sensitive**. This means:
+
+```javascript
+{_id: {a: "root", d: "Home"}}  // Different from...
+{_id: {d: "Home", a: "root"}}  // ...this!
+```
+
+These are considered **two different documents** even though they have the same fields and values.
+
+## The Impact
+
+When doing a PUT/upsert on the wiki, if you get the field order wrong in the `_id`, you will:
+- ✅ NOT update the existing document
+- ❌ CREATE a duplicate document with a different `_id` field order
+- The original document remains unchanged and continues to be displayed
+- Your new document becomes an orphan
+
+## The Solution
+
+**Always preserve the exact field order when constructing `_id` objects:**
+
+```javascript
+// Correct for wiki doclets:
+{_id: {d: "PageName", a: "accountName"}}
+
+// WRONG - will create duplicate:
+{_id: {a: "accountName", d: "PageName"}}
+```
+
+## How to Avoid This
+
+1. **Read first, update second**: Always GET the existing document first to see the exact `_id` structure
+2. **Preserve field order**: When constructing updates, maintain the exact field order from the original
+3. **Use string _id when possible**: Avoid compound object `_id` fields in new collections
+
+## Cleaning Up Duplicates
+
+If you accidentally create a duplicate:
+
+```javascript
+// Find duplicates
+db.wiki.find({"_id.d": "PageName"})
+
+// Delete the wrong one (check field order!)
+db.wiki.deleteOne({_id: {a: "root", d: "PageName"}})
+```
+
+## Why This Design?
+
+This is an arcane MongoDB behavior that's a source of time-wasting bugs. String `_id` fields would be much safer.
+
+## TODO: Fix in wiki-mixin
+
+**Action item**: Normalize the `_id` field order in `@metric-im/wiki-mixin` API so clients never have to worry about this.
+
+The wiki API should:
+1. Always construct `_id` as `{d: docName, a: accountName}` regardless of input order
+2. Normalize any incoming `_id` objects to this canonical order before MongoDB operations
+3. Document the canonical order in API docs
+
+This would prevent this issue for all wiki hosts and clients.
+
+---
+
+*Documented 2025-10-14 after accidentally creating a duplicate Home page*

package/README.md

@@ -0,0 +1,50 @@
+# Epistery
+
+_Epistemology is the study of knowledge. An Epistery, it follows, is a place share the knowledge of knowledge._
+
+This project is open source middleware that provides websites and browsers a shared neutral space to identify and
+verify the origin of data and conduct digital business. It inserts the blockchain as a witness and clerk for the mundane
+business of clicking, tipping, stamping and cloaking, currently run by commercial web gatekeepers.
+
+Epistery provides the primitive tools for creating and rendering data-wallets.
+
+* /.well-known/epistery - json data presenting the signing identity/wallet of the site
+* /.well-known/epistery/status - human version of the above, plus overview of the site's activity and interactive features like comments, ratings.
+* /.well-known/epistery/data/* - data-wallet module api for mint, manipulate, render and delete
+* /.well-known/acme - Ephemeral ACME url for authorizing ssl cert assignment.
+
+## Usage
+
+```bash
+npm install epistery
+```
+
+Initialize your domain:
+```bash
+npx epistery initialize mydomain.com
+```
+
+In your Express application:
+```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);
+
+// Start your server
+const https_server = https.createServer(epistery.config.SNI, app);
+https_server.listen(443);
+```
+
+## Data Wallets
+
+A data wallet is data with chain. The data wallet attaches to the source object with a hash and is used to track
+the provenance, manipulation and usage of the data, per instruction by the owner. The epistery enables IPFS as a
+default storage option for uploaded objects, but there is no requirement to load the data itself on chain, just
+its accounting.

package/SESSION.md

@@ -0,0 +1,98 @@
+1# Epistery CLI Session Log
+## Date: 2025-10-14
+
+### Context
+Building epistery CLI for authenticated requests to wiki.rootz.global. Hours of work building authentication system. Machine has crashed multiple times, losing session context.
+
+### Current State
+- **CLI Location**: `./cli/epistery.mjs`
+- **Identity**: localhost wallet at `~/.epistery/localhost/config.ini`
+- **Address**: `0x8df97495e72461786E263CaECcAf21315E98e9aF`
+- **Default Domain**: Set to `localhost`
+- **Authorization**: This address is authorized on wiki.rootz.global server
+- **Recent Change**: Bot mode now defaults to `true` (was `false`) in cli/epistery.mjs line 127
+
+### Goal
+Post documentation to https://wiki.rootz.global/wiki/Home explaining how other developers can:
+1. Set up epistery CLI
+2. Configure authentication
+3. Post to the wiki from their dev environment using Claude
+
+### Current Issue
+- ✅ Read works: `epistery curl https://wiki.rootz.global/wiki/Home`
+- ❌ Write getting unauthorized (was working before crash)
+
+### Commands That Work
+```bash
+epistery set-default localhost
+epistery curl https://wiki.rootz.global/wiki/Home
+```
+
+### Debugging Progress
+
+**Bot Mode (Authorization header):**
+- ✅ Signature generation works
+- ❌ Server returns 401 Unauthorized
+- Format: `Authorization: Bot <base64 JSON with address, signature, message>`
+
+**Session Mode (Key Exchange):**
+- ✅ Key exchange completes successfully
+- ✅ Server responds: 0x06E2174095fB7cb1251EEf4D229772A59a0C8761
+- ❌ Returns `authenticated: false`
+- ❌ No session cookie set by server
+- This means the server doesn't recognize/trust the client address (9aF)
+
+### Solution Found
+
+The bot authentication in Rhonda's account-server (lines 825-909) expects:
+1. User exists in database ✅
+2. ACL exists for account access ✅
+3. Signature verification ✅
+
+The user needs to be marked as a system account. Update MongoDB:
+```
+db.user.updateOne(
+  {_id: '0x8df97495e72461786E263CaECcAf21315E98e9aF'},
+  {$set: {'options.systemAccount': true}}
+)
+```
+
+### Next Steps
+1. Update user record to mark as system account
+2. Test bot authentication with CLI
+3. Write and post developer documentation to wiki
+
+### Resolution
+
+**Fixed in `/home/msprague/workspace/rootz/rhonda/modules/account-server/index.mjs:866`**
+
+Changed from:
+```javascript
+const userAccount = await this.userCollection.findOne({
+  address: address.toLowerCase()
+});
+```
+
+To:
+```javascript
+const userAccount = await this.userCollection.findOne({
+  address: new RegExp(`^${address}$`, 'i')
+});
+```
+
+This makes address lookup case-insensitive, handling addresses stored with mixed case in the database.
+
+### Success
+
+✅ Bot authentication working
+✅ Test page created at `/wiki/ClaudeTest`
+✅ Documentation updated on wiki Home page
+✅ Other developers can now follow the instructions to set up their own agents
+
+### Key Learnings
+
+1. **Case sensitivity**: Ethereum addresses are case-insensitive but often stored with mixed case (checksummed). Always use case-insensitive comparison in MongoDB queries.
+
+2. **Bot authentication flow**: The Epistery CLI signs each request with the wallet's private key. The server verifies the signature, looks up the user by address, checks ACL permissions, and allows/denies the request.
+
+3. **Session persistence**: Creating SESSION.md files for important development sessions helps recover from machine crashes and provides documentation of debugging processes.