@powerhousedao/academy 5.1.0-dev.14 → 5.1.0-dev.17

package/docs/academy/04-APIReferences/00-PowerhouseCLI.md

@@ -16,11 +16,7 @@ pnpm install -g ph-cmd
 
 :::
 
-<!-- AUTO-GENERATED-CLI-COMMANDS-START -->\n<!-- This content is automatically generated. Do not edit directly. -->\n
-
-### ph-cmd Commands
-
-- [Checkout](#checkout)
+<!-- AUTO-GENERATED-CLI-COMMANDS-START -->\n<!-- This content is automatically generated. Do not edit directly. -->\n### ph-cmd Commands\n\n- [Checkout](#checkout)
 - [Init](#init)
 - [Setup Globals](#setup-globals)
 - [Update](#update)
@@ -247,7 +243,8 @@ Examples:
 
 ---
 
-*This document was automatically generated from the help text in the codebase.*\n\n### ph-cli Commands\n\n- [Connect Build](#connect-build)
+*This document was automatically generated from the help text in the codebase.*\n\n### ph-cli Commands\n\n- [Access Token](#access-token)
+- [Connect Build](#connect-build)
 - [Connect Preview](#connect-preview)
 - [Connect Studio](#connect-studio)
 - [Dev](#dev)
@@ -255,6 +252,7 @@ Examples:
 - [Inspect](#inspect)
 - [Install](#install)
 - [List](#list)
+- [Login](#login)
 - [Reactor](#reactor)
 - [Service](#service)
 - [Switchboard](#switchboard)
@@ -262,6 +260,76 @@ Examples:
 - [Version](#version)
 - [Vetra](#vetra)
 
+## Access Token
+
+```
+Command Overview:
+  The access-token command generates a bearer token for API authentication. This token
+  can be used to authenticate requests to Powerhouse APIs like reactor-api (Switchboard).
+
+  This command:
+  1. Uses your CLI's cryptographic identity (DID) to sign a verifiable credential
+  2. Creates a JWT bearer token with configurable expiration
+  3. Outputs the token to stdout (info to stderr) for easy piping
+
+Prerequisites:
+  You must have a cryptographic identity. Run 'ph login' first to:
+  - Generate a keypair (stored in .keypair.json)
+  - Optionally link your Ethereum address (stored in .auth.json)
+
+Options:
+  --expiry <duration>     Set the token expiration time. Supports multiple formats:
+                          - Days: "7d" (default), "30d", "1d"
+                          - Hours: "24h", "12h", "1h"
+                          - Seconds: "3600", "3600s", "86400s"
+                          Default is 7 days.
+
+  --audience <url>        Optional. Set the intended audience (aud claim) for the token.
+                          This can be used to restrict the token to specific services.
+
+Token Details:
+  The generated token is a JWT (JSON Web Token) containing:
+  - Issuer (iss): Your CLI's DID (did:key:...)
+  - Subject (sub): Your CLI's DID
+  - Credential Subject: Chain ID, network ID, and address (if authenticated)
+  - Expiration (exp): Based on --expiry option
+  - Audience (aud): If --audience is specified
+
+Output:
+  - Token information (DID, address, expiry) is printed to stderr
+  - The token itself is printed to stdout for easy piping/copying
+
+  This allows you to use the command in scripts:
+    TOKEN=$(ph access-token)
+    curl -H "Authorization: Bearer $TOKEN" http://localhost:4001/graphql
+
+Examples:
+  $ ph access-token                          # Generate token valid for 7 days
+  $ ph access-token --expiry 30d             # Generate token valid for 30 days
+  $ ph access-token --expiry 24h             # Generate token valid for 24 hours
+  $ ph access-token --expiry 3600            # Generate token valid for 1 hour (3600 seconds)
+  $ ph access-token --audience http://localhost:4001  # Set audience claim
+  $ ph access-token | pbcopy                 # Copy token to clipboard (macOS)
+  $ ph access-token | xclip -selection c     # Copy token to clipboard (Linux)
+
+Usage with APIs:
+  # Generate token and use with curl
+  TOKEN=$(ph access-token --expiry 1d)
+  curl -X POST http://localhost:4001/graphql \\
+    -H "Content-Type: application/json" \\
+    -H "Authorization: Bearer $TOKEN" \\
+    -d '{"query": "{ drives { id name } }"}'
+
+  # Export as environment variable
+  export PH_ACCESS_TOKEN=$(ph access-token)
+
+Notes:
+  - Tokens are self-signed using your CLI's private key
+  - No network request is made; tokens are generated locally
+  - The recipient API must trust your CLI's DID to accept the token
+  - For reactor-api, ensure AUTH_ENABLED=true to require authentication
+```
+
 ## Connect Build
 
 ```
@@ -604,6 +672,76 @@ Notes:
   - Each package is displayed by its package name
 ```
 
+## Login
+
+```
+Command Overview:
+  The login command authenticates you with Renown using your Ethereum wallet. This enables
+  the CLI to act on behalf of your Ethereum identity for authenticated operations.
+
+  This command:
+  1. Generates or loads a cryptographic identity (DID) for the CLI
+  2. Opens your browser to the Renown authentication page
+  3. You authorize the CLI's DID to act on behalf of your Ethereum address
+  4. Stores the credentials locally in ~/.ph/auth.json
+
+Options:
+  --renown-url <url>    Specify a custom Renown server URL. Defaults to
+                        https://www.renown.id
+
+  --timeout <seconds>   Set the authentication timeout in seconds. The command will
+                        wait this long for you to complete authentication in the browser.
+                        Defaults to 300 seconds (5 minutes).
+
+  --logout              Sign out and clear your stored credentials. Use this when you
+                        want to switch accounts or revoke local authentication.
+
+  --status              Show your current authentication status without logging in.
+                        Displays your CLI DID, ETH address, and when you authenticated.
+
+  --show-did            Show only the CLI's DID and exit. Useful for scripts.
+
+Authentication Flow:
+  1. Run 'ph login' - the CLI generates/loads its cryptographic identity (DID)
+  2. A browser window opens to Renown with the CLI's DID
+  3. Connect your Ethereum wallet (MetaMask, etc.)
+  4. Authorize the CLI's DID to act on behalf of your ETH address
+  5. Return to your terminal - authentication is complete!
+
+Credentials Storage:
+  All identity files are stored per-project in the current working directory:
+
+  .keypair.json   The CLI's cryptographic keypair (ECDSA P-256)
+  .auth.json      Your authentication credentials including:
+                  - Your Ethereum address (the account you authorized)
+                  - Your User DID (did:pkh:eip155:chainId:address)
+                  - CLI DID (did:key:... - the CLI's cryptographic identity)
+                  - Credential ID for session validation
+
+  This allows each project to have its own identity and credentials.
+  For CI/CD, provide the keypair via PH_RENOWN_PRIVATE_KEY env variable.
+
+Environment Variables:
+  PH_RENOWN_PRIVATE_KEY   JSON-encoded JWK keypair for the CLI's identity.
+                          If set, the CLI will use this instead of generating
+                          or loading from file. Useful for CI/CD environments.
+
+Examples:
+  $ ph login                              # Authenticate with default settings
+  $ ph login --status                     # Check authentication status and CLI DID
+  $ ph login --show-did                   # Print only the CLI's DID
+  $ ph login --logout                     # Sign out and clear credentials
+  $ ph login --timeout 600                # Wait up to 10 minutes for authentication
+  $ ph login --renown-url http://localhost:3000   # Use local Renown server
+
+Notes:
+  - You only need to authenticate once; credentials persist until you log out
+  - The CLI's DID remains stable unless you delete .keypair.json from your project
+  - If already authenticated, the command will show your current status
+  - The browser must remain open until authentication completes
+  - Your wallet signature authorizes the CLI's DID to act on your behalf
+```
+
 ## Reactor
 
 ```
@@ -701,29 +839,42 @@ Command Overview:
   2. Loads document models and processors
   3. Provides an API for document operations
   4. Enables real-time document processing
+  5. Can authenticate with remote services using your identity from 'ph login'
 
 Options:
   --port <PORT>           Port to host the API. Default is 4001.
-                        
-  --config-file <path>    Path to the powerhouse.config.js file. Default is 
+
+  --config-file <path>    Path to the powerhouse.config.js file. Default is
                         './powerhouse.config.json'. This configures the switchboard behavior.
-                        
+
   --dev                   Enable development mode to load local packages from the current directory.
                         This allows the switchboard to discover and load document models, processors,
                         and subgraphs from your local development environment.
-                        
+
   --db-path <DB_PATH>     Path to the database for storing document data.
-                        
+
   --https-key-file <path> Path to the SSL key file if using HTTPS for secure connections.
-                        
+
   --https-cert-file <path> Path to the SSL certificate file if using HTTPS.
-                        
+
   --packages <pkg...>     List of packages to be loaded. If defined, packages specified
                         in the config file are ignored.
-                        
-  --base-path <path>      Base path for the API endpoints. Sets the BASE_PATH environment 
+
+  --base-path <path>      Base path for the API endpoints. Sets the BASE_PATH environment
                         variable used by the server to prefix all routes.
 
+Identity Options:
+  --use-identity          Enable identity using the keypair from 'ph login'. This allows the
+                        switchboard to authenticate with remote drives and services using
+                        your authorized Ethereum identity.
+
+  --keypair-path <path>   Path to a custom keypair file. Overrides the default .keypair.json
+                        in the current directory.
+
+  --require-identity      Require an existing keypair; fail if not found. Use this when you
+                        want to ensure the switchboard runs with a valid identity. If no
+                        keypair exists, run 'ph login' first to create one.
+
 Examples:
   $ ph switchboard                           # Start switchboard with default settings
   $ ph switchboard --port 5000               # Use custom port 5000
@@ -731,6 +882,8 @@ Examples:
   $ ph switchboard --config-file custom.json # Use custom configuration file
   $ ph switchboard --packages pkg1 pkg2      # Load specific packages
   $ ph switchboard --base-path /switchboard  # Set API base path to /switchboard
+  $ ph switchboard --use-identity            # Start with identity from ph login
+  $ ph switchboard --require-identity        # Require identity, fail if not logged in
 ```
 
 ## Uninstall

package/docs/academy/04-APIReferences/01-ReactHooks.md

@@ -1,3 +1,10 @@
+---
+toc_max_heading_level: 2
+
+
+---
+
+
 # React Hooks
 
 On this page we're providing an overview of the available hooks you can make use of as a builder.

package/docs/academy/04-APIReferences/04-RelationalDatabase.md

@@ -1,3 +1,9 @@
+---
+toc_max_heading_level: 2
+
+
+---
+
 # Relational Database
 
 This page covers the relational database tools available in Powerhouse applications, providing type-safe database operations with real-time updates through PGlite integration.

package/docs/academy/04-APIReferences/renown-sdk/03-CLIIdentity.md

@@ -0,0 +1,321 @@
+# CLI Identity & Authentication
+
+This guide covers how to authenticate the Powerhouse CLI with your Ethereum identity and use that identity in the Switchboard for authenticated operations with remote services.
+
+## Overview
+
+The Powerhouse CLI uses **Renown** for identity management. When you run `ph login`, the CLI:
+
+1. Generates a cryptographic keypair (ECDSA P-256) stored locally
+2. Creates a DID (Decentralized Identifier) in `did:key:...` format
+3. Opens your browser to authorize this DID to act on behalf of your Ethereum address
+4. Stores the authorization credentials for future use
+
+This enables the CLI and Switchboard to authenticate with remote drives and services using your Ethereum identity.
+
+## Quick Start
+
+```bash
+# 1. Login with your Ethereum wallet
+ph login
+
+# 2. Start switchboard with your identity
+ph switchboard --use-identity
+```
+
+## The Login Command
+
+### Basic Usage
+
+```bash
+# Authenticate with Renown
+ph login
+
+# Check your authentication status
+ph login --status
+
+# Show only your CLI's DID (useful for scripts)
+ph login --show-did
+
+# Logout and clear credentials
+ph login --logout
+```
+
+### How It Works
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│                          ph login                                     │
+├──────────────────────────────────────────────────────────────────────┤
+│                                                                       │
+│  1. CLI generates/loads keypair (.keypair.json)                      │
+│     └─► Creates DID: did:key:zDnae...                                │
+│                                                                       │
+│  2. Opens browser to Renown portal                                   │
+│     └─► URL includes CLI's DID                                       │
+│                                                                       │
+│  3. User connects wallet & signs authorization                       │
+│     └─► "I authorize did:key:zDnae... to act on my behalf"          │
+│                                                                       │
+│  4. Renown issues credential                                         │
+│     └─► Links CLI DID to user's ETH address                         │
+│                                                                       │
+│  5. CLI stores credentials (.auth.json in project dir)               │
+│     └─► Ready to authenticate with remote services                   │
+│                                                                       │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+### Output Example
+
+```
+$ ph login
+Initializing cryptographic identity...
+CLI DID: did:key:zDnaej4f3d83mmCodYjZyHzUKDSt2dGVKjzD8dd22AS83GtMo
+
+Opening browser for authentication...
+Session ID: a1b2c3d4...
+
+Waiting for authentication in browser
+(timeout in 300 seconds)
+
+Please connect your wallet and authorize this CLI to act on your behalf.
+
+Waiting.................
+
+Successfully authenticated!
+  ETH Address: 0x1234...abcd
+  User DID: did:pkh:eip155:1:0x1234...abcd
+  CLI DID: did:key:zDnaej4f3d83mmCodYjZyHzUKDSt2dGVKjzD8dd22AS83GtMo
+
+The CLI can now act on behalf of your Ethereum identity.
+```
+
+## Storage Locations
+
+All identity files are stored **per-project** in the current working directory:
+
+```
+your-project/
+├── .keypair.json          # CLI's cryptographic keypair (did:key identity)
+├── .auth.json             # Authentication credentials (ETH address, User DID, etc.)
+├── powerhouse.config.json
+└── ...
+```
+
+This means each project can have its own identity and credentials, which is useful for:
+- Different projects requiring different identities
+- Team members using the same machine
+- Separating development and production identities
+- Isolating credentials between projects
+
+### Environment Variable
+
+For CI/CD environments, provide the keypair via environment variable:
+
+```bash
+# Export keypair as JSON
+export PH_RENOWN_PRIVATE_KEY='{"publicKey":{"kty":"EC",...},"privateKey":{"kty":"EC",...}}'
+
+# Now ph login --show-did will use this keypair
+ph login --show-did
+```
+
+## Using Identity in Switchboard
+
+### Starting with Identity
+
+```bash
+# Enable identity using keypair from ph login
+ph switchboard --use-identity
+
+# Output includes identity DID:
+#    ➜  Switchboard: http://localhost:4001
+#    ➜  Identity: did:key:zDnaej4f3d83mmCodYjZyHzUKDSt2dGVKjzD8dd22AS83GtMo
+```
+
+### Identity Options
+
+| Option | Description |
+|--------|-------------|
+| `--use-identity` | Enable identity using `.keypair.json` |
+| `--keypair-path <path>` | Use a custom keypair file |
+| `--require-identity` | Fail if no keypair exists |
+
+### Requiring Identity
+
+Use `--require-identity` when the switchboard must have a valid identity:
+
+```bash
+# Fails if no keypair exists (user must run ph login first)
+ph switchboard --require-identity
+
+# Error if not logged in:
+# Error: Identity required but failed to initialize. Run "ph login" first.
+```
+
+### Custom Keypair Path
+
+```bash
+# Use a specific keypair file
+ph switchboard --use-identity --keypair-path /path/to/my-keypair.json
+```
+
+## How the Switchboard Uses Identity
+
+When the Switchboard starts with identity enabled, it can:
+
+1. **Authenticate with Remote Drives**: Generate bearer tokens for API requests
+2. **Sign Operations**: Cryptographically sign document operations
+3. **Identify Itself**: Present its DID to remote services
+
+### Getting Bearer Tokens
+
+The Switchboard can generate bearer tokens for authenticated API calls:
+
+```typescript
+import { getBearerToken, getConnectDid } from "@powerhousedao/switchboard";
+
+// Get the switchboard's DID
+const did = await getConnectDid();
+console.log("Switchboard DID:", did);
+
+// Get a bearer token for a remote drive
+const token = await getBearerToken("https://remote.drive.example.com");
+console.log("Bearer Token:", token);
+
+// Use in API requests
+const response = await fetch("https://remote.drive.example.com/api/documents", {
+  headers: {
+    Authorization: `Bearer ${token}`,
+  },
+});
+```
+
+## Security Considerations
+
+### Identity Files Protection
+
+The `.keypair.json` and `.auth.json` files contain sensitive data. Protect them:
+
+```bash
+# Add to .gitignore
+echo ".keypair.json" >> .gitignore
+echo ".auth.json" >> .gitignore
+
+# Set restrictive permissions (Unix)
+chmod 600 .keypair.json .auth.json
+```
+
+### CI/CD Best Practices
+
+For automated environments:
+
+1. **Use environment variables** instead of files
+2. **Store secrets securely** (GitHub Secrets, AWS Secrets Manager, etc.)
+3. **Rotate keys** periodically
+4. **Limit scope** - use separate identities for different environments
+
+```yaml
+# GitHub Actions example
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup identity
+        env:
+          PH_RENOWN_PRIVATE_KEY: ${{ secrets.PH_KEYPAIR }}
+        run: |
+          ph switchboard --use-identity &
+```
+
+### Authorization Scope
+
+When you authorize the CLI's DID:
+- It can act on behalf of your Ethereum address
+- It can authenticate with services that trust Renown
+- It **cannot** sign Ethereum transactions or access your wallet
+
+## Troubleshooting
+
+### "No existing keypair found"
+
+```bash
+$ ph switchboard --require-identity
+Error: Identity required but failed to initialize. Run "ph login" first.
+```
+
+**Solution**: Run `ph login` to create a keypair:
+
+```bash
+ph login
+# Then retry
+ph switchboard --require-identity
+```
+
+### "Authentication timed out"
+
+The browser authentication didn't complete in time.
+
+**Solutions**:
+- Increase timeout: `ph login --timeout 600`
+- Check browser opened correctly
+- Ensure you completed the wallet connection
+
+### Different DID than expected
+
+Each project directory has its own `.keypair.json`.
+
+**Check current DID**:
+```bash
+ph login --show-did
+```
+
+**Use specific keypair**:
+```bash
+ph switchboard --use-identity --keypair-path ~/.shared-keypair.json
+```
+
+## API Reference
+
+### Login Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `--renown-url` | string | `https://renown.powerhouse.io` | Renown server URL |
+| `--timeout` | number | `300` | Auth timeout (seconds) |
+| `--logout` | boolean | `false` | Clear credentials |
+| `--status` | boolean | `false` | Show auth status |
+| `--show-did` | boolean | `false` | Print DID only |
+
+### Switchboard Identity Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `--use-identity` | boolean | `false` | Enable identity |
+| `--keypair-path` | string | `.keypair.json` | Keypair file path |
+| `--require-identity` | boolean | `false` | Fail without keypair |
+
+### Exported Functions (Switchboard)
+
+```typescript
+// Get the ConnectCrypto instance
+function getConnectCrypto(): IConnectCrypto | null;
+
+// Get the switchboard's DID
+async function getConnectDid(): Promise<string | null>;
+
+// Get a bearer token for a remote URL
+async function getBearerToken(
+  driveUrl: string,
+  address?: string,
+  refresh?: boolean
+): Promise<string | null>;
+```
+
+## Related Documentation
+
+- [Renown SDK Overview](./00-Overview.md) - Introduction to Renown
+- [Authentication Guide](./01-Authentication.md) - Web app authentication
+- [API Reference](./02-APIReference.md) - Full SDK reference

package/docs/academy/05-Architecture/00-PowerhouseArchitecture.md

@@ -1,20 +1,55 @@
 # Powerhouse Architecture
 
-**Vetra is part of the Powerhouse Ecosystem** and acts as the builder platform and builder tooling for scalable network organizations. 
+**Vetra is part of the Powerhouse Ecosystem** and acts as the builder platform for creating an independent, open-source and decentralized back-end for any SaaS, ERP, CMS or CRM needs.
 
-The Powerhouse ecosystem makes use of 4 core host applications that together form a modular, scalable operating system for decentralized organizations. 
-Each application serves a distinct role, yet they are interdependent, working as a unified system to streamline operations, enhance collaboration, and drive automation.
+## Local First. Built to Scale.
 
-These five applications are:
+Vetra helps you build any type of web application on a **Reactive Document Architecture**. Define workflows once, deploy them globally, and co-own the software you create. The architecture is built on a minimal but powerful tech-stack: **GraphQL**, **TypeScript**, and **React**.
 
-1. **Connect** – The contributor's public or private workspace.
-2. **Switchboard** – The data infrastructure and API engine.
-3. **Fusion** – The public-facing collaboration hub.
-4. **Renown** – The decentralized reputation and identity system.
+### Reactive Document Architecture
+
+The Powerhouse framework is built around structured document models and declarative design:
+
+- **Reactive**: Real-time, responsive, and message-driven with an elastic scalable architecture.
+- **Document-Centric**: Documents as local-first, self-contained data structures and nodes in a decentralized network.
+- **Git-like UX**: State-of-the-art editing with history branching, merging, and commenting.
+- **Stateful**: Documents with well-defined operations as state transitions become mini-APIs.
+- **Scalable**: CQRS and EDA-inspired architecture with read models for data aggregation.
+
+## Target Audiences
+
+Vetra supports a variety of organizations with a headless open-source back-end:
+
+- Decentralized Autonomous Organizations (DAOs)
+- Scalable Network Organizations (an evolution of DAOs within the Powerhouse framework)
+- NGOs and Governmental Organizations
+- Cooperatives and distributed teams
+
+## Host Applications
+
+The Powerhouse ecosystem makes use of 4 core host applications that together form a modular, scalable operating system for any organization or business. Each application serves a distinct role, yet they are interdependent—working as a unified system to streamline operations, enhance collaboration, and drive automation.
+
+1. **Connect** – A collaboration hub and private workspace for independent contributors.
+2. **Switchboard** – The data infrastructure and API engine for managing remote instances.
+3. **Fusion** – An SDK for visualizing collected data and public-facing collaboration.
+4. **Renown** – A decentralized reputation and identity system.
+
+## How It All Connects: Reactors
+
+The host applications sync their documents with one another through **Reactors**. A reactor is a node within any Powerhouse network responsible for storing documents, resolving conflicts, and verifying document event histories.
+
+Reactors can be configured for:
+- **Local Storage** – For offline or on-device access.
+- **Cloud Storage** – For centralized, scalable data management.
+- **Decentralized Storage** – Such as Ceramic or IPFS for distributed storage.
+
+The documents within the network react to one another through the **DocSync** protocol—which sends updates from one reactor to another, ensuring all data stays synchronized across the system.
 
 ![Powerhouse Host Apps Interaction](./images/PowerhouseArchitecture.png)
 
-With the help of these host applications Powerhouse is launching 2 platforms that form an example of the infrastructure that can be build with the Powerhouse techstack.
+## Powerhouse Platforms
+
+With the help of these host applications, Powerhouse is launching 2 platforms that demonstrate the infrastructure that can be built with the Powerhouse tech-stack:
 
-- [Vetra Builder Platform](https://vetra.io/): Sovereign infrastructure for scalable network organizations that is local first, built to scale. 
-- [Achra Decentralized Operations Platform](https://achra.com/): Where open organizations can procure and purchase services. 
+- [**Vetra Builder Platform**](https://vetra.io/): Sovereign infrastructure for scalable network organizations—local first, built to scale.
+- [**Achra Decentralized Operations Platform**](https://achra.com/): Where open organizations can procure and purchase services.