@dp-pcs/ogp 0.2.0

package/docs/quickstart.md

@@ -0,0 +1,241 @@
+# OGP Quick Start Guide
+
+Get started with OGP federation in 5 minutes.
+
+## Prerequisites
+
+- Node.js >= 18
+- OpenClaw running locally or remotely
+- OpenClaw API token
+
+## Step 1: Install
+
+```bash
+npm install -g @dp-pcs/ogp
+```
+
+## Step 2: Configure
+
+Run the interactive setup:
+
+```bash
+ogp setup
+```
+
+Answer the prompts:
+
+```
+Daemon port [18790]: <enter>
+OpenClaw URL [http://localhost:18789]: <enter>
+OpenClaw API token: your-token-here
+Gateway URL (your public URL): https://temporary-url.com
+Display name: Alice
+Email: alice@example.com
+State directory [~/.ogp]: <enter>
+```
+
+Don't worry about the gateway URL yet — we'll get a real one in the next step.
+
+## Step 3: Start Daemon
+
+```bash
+ogp start
+```
+
+You should see:
+
+```
+[OGP] Daemon listening on port 18790
+[OGP] Public key: 302a300506032b6570032100...
+```
+
+## Step 4: Expose to Internet
+
+In a new terminal:
+
+```bash
+ogp expose
+```
+
+This starts a cloudflared tunnel and shows your public URL:
+
+```
+https://abc-def-123.trycloudflare.com
+```
+
+**Important:** Copy this URL!
+
+## Step 5: Update Gateway URL
+
+1. Stop the daemon (Ctrl+C in the daemon terminal)
+2. Edit `~/.ogp/config.json`
+3. Update `"gatewayUrl"` to your tunnel URL
+4. Restart: `ogp start`
+
+## Step 6: Verify Setup
+
+Test your public endpoint:
+
+```bash
+curl https://abc-def-123.trycloudflare.com/.well-known/ogp
+```
+
+You should see:
+
+```json
+{
+  "version": "0.1.0",
+  "displayName": "Alice",
+  "email": "alice@example.com",
+  "gatewayUrl": "https://abc-def-123.trycloudflare.com",
+  "publicKey": "302a300506032b6570032100...",
+  "endpoints": {
+    "request": "https://abc-def-123.trycloudflare.com/federation/request",
+    "approve": "https://abc-def-123.trycloudflare.com/federation/approve",
+    "reply": "https://abc-def-123.trycloudflare.com/federation/reply/:nonce"
+  }
+}
+```
+
+✓ Your OGP daemon is now publicly accessible!
+
+## Step 7: Federate with a Peer
+
+Ask a friend to share their OGP gateway URL, then:
+
+```bash
+ogp federation request https://peer.example.com peer-bob
+```
+
+You'll see:
+
+```
+✓ Federation request sent
+  Status: pending
+  Message: Federation request received and pending approval
+```
+
+Wait for Bob to approve your request:
+
+```bash
+# Bob runs this on their end:
+ogp federation approve peer-alice
+```
+
+Check your approved peers:
+
+```bash
+ogp federation list --status approved
+```
+
+## Step 8: Send Your First Message
+
+```bash
+ogp federation send peer-bob message '{"text":"Hello from OGP!"}'
+```
+
+Bob's OpenClaw agent will receive:
+
+```
+[OGP] Message from Alice: Hello from OGP!
+```
+
+## Next Steps
+
+### Send Different Message Types
+
+```bash
+# Task request
+ogp federation send peer-bob task-request '{
+  "taskType": "analysis",
+  "description": "Analyze server logs from last hour"
+}'
+
+# Status update
+ogp federation send peer-bob status-update '{
+  "status": "online",
+  "message": "Ready to collaborate"
+}'
+```
+
+### Manage Incoming Requests
+
+When someone sends you a federation request:
+
+```bash
+# List pending
+ogp federation list --status pending
+
+# Approve
+ogp federation approve peer-charlie
+
+# Or reject
+ogp federation reject peer-charlie
+```
+
+### Keep Tunnel Running
+
+For production use, set up a permanent tunnel:
+
+**Option 1: Named cloudflared tunnel**
+
+```bash
+cloudflared tunnel login
+cloudflared tunnel create ogp-daemon
+# Edit config.yml with your tunnel settings
+cloudflared tunnel run ogp-daemon
+```
+
+**Option 2: Run as system service**
+
+See [ogp-expose skill](../skills/ogp-expose/SKILL.md) for systemd/launchd setup.
+
+## Troubleshooting
+
+### "No configuration found"
+
+Run `ogp setup` first.
+
+### "Failed to notify OpenClaw"
+
+- Verify OpenClaw URL is correct
+- Check API token is valid
+- Ensure OpenClaw is running
+
+### "Peer not approved"
+
+The peer must approve your federation request first. Contact them or check their status.
+
+### Tunnel URL not accessible
+
+- Check firewall settings
+- Verify daemon is running
+- Try accessing locally first: `curl http://localhost:18790/.well-known/ogp`
+
+## Common Commands Cheat Sheet
+
+```bash
+# Setup
+ogp setup
+ogp start
+ogp expose
+
+# Status
+ogp status
+ogp federation list
+
+# Federation
+ogp federation request <url> <peer-id>
+ogp federation approve <peer-id>
+ogp federation send <peer-id> <intent> '<json>'
+
+# Stop
+ogp stop
+```
+
+## What's Next?
+
+- Read [Federation Flow](./federation-flow.md) for detailed message flow
+- Check [Skills](../skills/) for Claude Code integration
+- Explore custom intents in `~/.ogp/intents.json`
+- Set up automatic peer discovery

package/docs/scopes.md

@@ -0,0 +1,198 @@
+# OGP Scope Negotiation (v0.2.0)
+
+OGP v0.2.0 introduces a three-layer scope model for per-peer access control, inspired by BGP route filtering.
+
+## The Three-Layer Model
+
+```
+Layer 1: Gateway Capabilities  → What I CAN support (advertised globally)
+Layer 2: Peer Negotiation      → What I WILL grant YOU (per-peer, during approval)
+Layer 3: Runtime Enforcement   → Is THIS request within YOUR granted scope (doorman)
+```
+
+### Layer 1: Gateway Capabilities
+
+Your gateway advertises its capabilities in the federation card at `/.well-known/ogp`:
+
+```json
+{
+  "version": "0.2.0",
+  "displayName": "David's Gateway",
+  "capabilities": {
+    "intents": ["message", "task-request", "status-update", "agent-comms"],
+    "features": ["scope-negotiation", "reply-callback"]
+  }
+}
+```
+
+This tells other gateways what you **can** support, not what you **will** grant.
+
+### Layer 2: Peer Negotiation
+
+When you approve a federation request, you decide what to grant **this specific peer**:
+
+```bash
+# Grant Stan only agent-comms with specific topics
+ogp federation approve stan \
+  --intents agent-comms \
+  --topics memory-management,task-delegation \
+  --rate 10/60
+
+# Grant Alice full access to message and task-request
+ogp federation approve alice \
+  --intents message,task-request,status-update \
+  --rate 100/3600
+```
+
+Scope grants are stored with the peer record and sent to the remote gateway during approval.
+
+### Layer 3: Runtime Enforcement (Doorman)
+
+The doorman validates every incoming request:
+
+1. **Peer verification** - Is the sender approved?
+2. **Scope check** - Is this intent in their granted scopes?
+3. **Topic check** - For agent-comms, is this topic allowed?
+4. **Rate limit** - Is the peer within their request quota?
+
+Requests that fail any check receive appropriate error codes:
+- `403 Forbidden` - Scope or topic not allowed
+- `429 Too Many Requests` - Rate limit exceeded (includes `Retry-After`)
+
+## Scope Grant Structure
+
+```typescript
+interface ScopeGrant {
+  intent: string;                    // e.g., "agent-comms"
+  enabled: boolean;                  // Can disable without removing
+  rateLimit?: {
+    requests: number;                // Max requests allowed
+    windowSeconds: number;           // Time window
+  };
+  topics?: string[];                 // For agent-comms only
+  expiresAt?: string;                // Optional expiration (ISO timestamp)
+}
+
+interface ScopeBundle {
+  version: "0.2.0";
+  grantedAt: string;                 // When this grant was created
+  scopes: ScopeGrant[];
+}
+```
+
+## CLI Commands
+
+### View Scopes
+
+```bash
+ogp federation scopes <peer-id>
+```
+
+Shows both:
+- **Granted to peer**: What they can request from you
+- **Received from peer**: What you can request from them
+
+### Approve with Scopes
+
+```bash
+ogp federation approve <peer-id> \
+  --intents <comma-separated-list> \
+  --rate <requests>/<seconds> \
+  --topics <comma-separated-list>
+```
+
+### Update Grants
+
+```bash
+ogp federation grant <peer-id> \
+  --intents <comma-separated-list> \
+  --rate <requests>/<seconds> \
+  --topics <comma-separated-list>
+```
+
+## Rate Limiting
+
+Rate limits are enforced per-peer, per-intent using a sliding window algorithm:
+
+```bash
+# 10 requests per minute for agent-comms
+ogp federation approve stan --intents agent-comms --rate 10/60
+
+# 100 requests per hour for all intents
+ogp federation approve stan --intents message,task-request --rate 100/3600
+```
+
+When a peer exceeds their rate limit:
+- Response: `429 Too Many Requests`
+- Header: `Retry-After: <seconds>`
+- Message: Rate limit exceeded for intent 'agent-comms'
+
+## Topic Restrictions (agent-comms)
+
+Topics provide fine-grained control over agent communication categories:
+
+```bash
+# Allow only memory-related topics
+ogp federation approve stan --intents agent-comms --topics memory-management,context-persistence
+
+# Peer can send:
+ogp federation agent me memory-management "Question"  # ✓
+
+# Peer cannot send:
+ogp federation agent me billing "Question"  # ✗ 403 Topic not allowed
+```
+
+Topics support prefix matching:
+- Allowing `memory` matches `memory`, `memory/contexts`, `memory/persistence`
+- Use specific topics for tighter control
+
+## Backward Compatibility
+
+OGP v0.2.0 is fully backward compatible with v0.1 peers:
+
+| Scenario | Behavior |
+|----------|----------|
+| v0.2 approves v0.1 peer | No scopes sent, default rate limits apply |
+| v0.1 peer sends message | Allowed with default limit (100/hour) |
+| v0.2 sends to v0.1 peer | Works normally, no scope enforcement on their end |
+
+Protocol version is detected automatically from:
+1. `protocolVersion` field in approval
+2. Presence of `scopeGrants` field
+3. Federation card version
+
+## Security Considerations
+
+- **Principle of least privilege**: Grant only what's needed
+- **Review grants periodically**: Use `ogp federation scopes` to audit
+- **Monitor rate limits**: Watch for peers hitting limits frequently
+- **Use topic restrictions**: Especially for agent-comms
+- **Set expiration**: For temporary access, use `expiresAt` in code
+
+## Examples
+
+### Minimal Access
+
+```bash
+# Grant only ping intent
+ogp federation approve stan --intents message --rate 10/3600
+```
+
+### Full Agent Access
+
+```bash
+# Grant full agent-comms with generous limits
+ogp federation approve alice \
+  --intents agent-comms \
+  --rate 1000/3600
+```
+
+### Scoped Agent Access
+
+```bash
+# Grant agent-comms for specific project
+ogp federation approve bob \
+  --intents agent-comms \
+  --topics project-alpha,planning \
+  --rate 50/3600
+```

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@dp-pcs/ogp",
+  "version": "0.2.0",
+  "description": "Open Gateway Protocol (OGP) - Peer-to-peer federation daemon for OpenClaw AI gateways with cryptographic signatures",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "ogp": "./dist/cli.js",
+    "ogp-install-skills": "./scripts/install-skills.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ogp",
+    "openclaw",
+    "federation",
+    "ai-gateway",
+    "protocol",
+    "peer-to-peer",
+    "ed25519",
+    "cryptographic-signatures"
+  ],
+  "author": "David Proctor",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dp-pcs/ogp.git"
+  },
+  "homepage": "https://github.com/dp-pcs/ogp#readme",
+  "bugs": {
+    "url": "https://github.com/dp-pcs/ogp/issues"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "scripts",
+    "docs",
+    "README.md",
+    "package.json"
+  ],
+  "dependencies": {
+    "commander": "^12.0.0",
+    "express": "^4.18.2"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.11.0",
+    "typescript": "^5.3.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/scripts/install-skills.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import { existsSync, mkdirSync, cpSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const skillsSrc = join(__dirname, '..', 'skills');
+const skillsDest = join(homedir(), '.openclaw', 'skills');
+
+const skills = ['ogp', 'ogp-expose'];
+
+try {
+  if (!existsSync(skillsDest)) {
+    mkdirSync(skillsDest, { recursive: true });
+  }
+
+  for (const skill of skills) {
+    const src = join(skillsSrc, skill);
+    const dest = join(skillsDest, skill);
+    if (existsSync(src)) {
+      cpSync(src, dest, { recursive: true });
+      console.log(`✓ Installed skill: ${skill} → ${dest}`);
+    }
+  }
+
+  console.log('\nOGP skills installed. Restart your OpenClaw gateway to load them.');
+} catch (err) {
+  console.warn('Note: Could not auto-install OpenClaw skills:', err.message);
+  console.warn('Manual install: cp -r $(npm root -g)/ogp/skills/ogp ~/.openclaw/skills/');
+}