@aiconnect/confidant 1.0.0

package/README.md

@@ -0,0 +1,570 @@
+# Confidant
+
+**The missing link between AI assistants and humans for secure secret sharing.**
+
+When your AI assistant needs a password, API key, or any sensitive credential, where does it go? Through chat history. Logged. Stored. Exposed.
+
+Confidant solves this. It creates a secure, time-limited channel where humans can submit secrets directly to AI assistants — without the secret ever touching chat logs.
+
+## The Problem
+
+AI assistants like [Clawdbot](https://github.com/clawdbot/clawdbot), Claude Code, and others are becoming trusted collaborators. They need credentials to help you:
+
+- Deploy to your servers
+- Access your APIs  
+- Configure your services
+- Manage your accounts
+
+But every time you paste a password in chat, it's logged somewhere. Chat history, model training data, audit logs. That's not secure.
+
+## The Solution
+
+Confidant provides a **pull-based secret handoff**:
+
+1. **AI requests a secret** → Creates a secure request with a unique URL
+2. **Human receives the URL** → Opens it in their browser
+3. **Human submits the secret** → Direct browser-to-server, bypassing chat
+4. **AI retrieves the secret** → Auto-polls until the secret arrives
+5. **Secret self-destructs** → Deleted immediately after retrieval
+
+The secret never passes through chat. It's a direct handshake between human and AI.
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install -g confidant
+# or
+npx confidant
+```
+
+### Start the Server
+
+```bash
+confidant serve
+# Server running on http://localhost:3000
+```
+
+### Request a Secret (AI side)
+
+```bash
+confidant request
+# 🔗 Share this URL: http://localhost:3000/r/abc123...
+# ⏳ Waiting for secret...
+# ✅ Secret received!
+```
+
+### Multiple URL Options
+
+When you create a request, Confidant automatically detects and displays multiple URL options for different deployment scenarios:
+
+#### Localhost URL (Always Available)
+Use when both CLI and user are on the same machine:
+```bash
+confidant request
+# Access URLs:
+# 
+# Localhost (primary):
+#   Use when both CLI and user are on the same machine
+#   http://localhost:3000/request/abc123
+```
+
+#### Local Network IP URL (Auto-Detected)
+Automatically displayed when a private IP is detected on the same network:
+```bash
+confidant request
+# Access URLs:
+#
+# Local Network IP:
+#   Use for cross-device access on the same network
+#   http://192.168.1.100:3000/request/abc123
+```
+
+Use cases:
+- **Mac Mini + iPhone**: CLI on Mac Mini, user on iPhone
+- **Docker + Host**: CLI in Docker container, user on host machine
+- **VM + External**: CLI in VM, user on host network
+
+#### Tunneling Services (For External Access)
+For containers, VMs, or when external access is needed, use tunneling services:
+
+**ngrok** (Quick Setup)
+```bash
+# Install ngrok
+brew install ngrok  # or download from ngrok.com
+
+# Expose server
+ngrok http 3000
+# Forwarding: https://abc123.ngrok.io -> http://localhost:3000
+```
+
+**Tailscale** (Mesh VPN)
+```bash
+# Install Tailscale
+# Follow instructions at https://tailscale.com
+
+# Get your Tailscale IP
+tailscale ip -4
+# Use this IP with Confidant
+```
+
+**Cloudflare Tunnel** (Zero Trust)
+```bash
+# Install cloudflared
+# Follow instructions at https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/
+
+# Start tunnel
+cloudflared tunnel --url http://localhost:3000
+```
+
+**localtunnel** (Simple, No Signup)
+```bash
+# Install localtunnel
+npm install -g localtunnel
+
+# Expose server
+lt --port 3000
+# Your URL is: https://abc123.loca.lt
+```
+
+Choose the tunneling service that best fits your needs and security requirements.
+
+### Expose with ngrok (for remote access)
+
+For AI assistants running on remote servers, use [ngrok](https://ngrok.com) to expose your Confidant instance:
+
+```bash
+# Install ngrok
+brew install ngrok  # or download from ngrok.com
+
+# Expose the server
+ngrok http 3000
+# Forwarding: https://abc123.ngrok.io -> http://localhost:3000
+```
+
+Then configure the CLI to use the public URL:
+
+```bash
+export CONFIDANT_API_URL=https://abc123.ngrok.io
+confidant request
+# 🔗 Share this URL: https://abc123.ngrok.io/r/xyz789...
+```
+
+Now anyone can submit secrets to your AI assistant from anywhere.
+
+## How It Works
+
+```
+┌─────────────┐     1. Request      ┌─────────────┐
+│             │ ─────────────────▶  │             │
+│     AI      │                     │  Confidant  │
+│  Assistant  │  ◀─────────────────  │   Server    │
+│             │     4. Secret       │             │
+└─────────────┘                     └─────────────┘
+                                          ▲
+                                          │ 3. Submit
+                                          │    (HTTPS)
+                                    ┌─────────────┐
+        2. URL via chat             │             │
+    ─────────────────────────────▶  │    Human    │
+                                    │   Browser   │
+                                    └─────────────┘
+```
+
+The secret travels from browser → server → AI. Chat only carries the URL.
+
+## Use Cases
+
+### For AI Assistants (Clawdbot, etc.)
+
+When your AI needs credentials:
+
+```bash
+# AI runs this
+confidant request --quiet
+# Outputs just the URL to share with the human
+```
+
+The AI shares the URL in chat, waits for submission, then uses the secret.
+
+### For DevOps / CI/CD
+
+Share deployment secrets without hardcoding:
+
+```bash
+# Create a one-time secret
+confidant create --secret "$DEPLOY_KEY" --max-access-count 1
+# Share the ID with your pipeline
+```
+
+### For Team Collaboration
+
+Share credentials securely with teammates:
+
+```bash
+# Create a secret that expires in 5 minutes
+confidant create --secret "temp-password" --ttl 300000
+```
+
+## CLI Reference
+
+### `confidant serve`
+Start the Confidant server.
+
+### `confidant request`
+Create a secret request and wait for submission.
+
+Options:
+- `--expires-in <seconds>` - Request expiration (default: 86400)
+- `--poll-interval <seconds>` - Polling interval (default: 2)
+- `--label <text>` - Optional label to describe what secret is being requested (max 200 characters)
+- `--quiet` - Minimal output (just URLs and secret)
+- `--json` - JSON output format (includes all URL fields)
+- `--verbose` - Show detailed information including network detection
+
+**Multi-URL Display**: When creating a request, Confidant automatically detects your local network IP and displays multiple URL options:
+
+- **Localhost URL** (Always shown): For accessing from the same device (e.g., `http://localhost:3000/r/abc123`)
+- **Local Network IP URL** (Auto-detected): For sharing with other devices on your local network (e.g., `http://192.168.1.100:3000/r/abc123`)
+- **Tunneling Suggestions** (Always shown): For containers/VMs or external access (ngrok, Tailscale, Cloudflare Tunnel, localtunnel)
+
+This makes it easy to share secrets across devices without needing external services like ngrok.
+
+### `confidant create`
+Create a secret directly.
+
+Options:
+- `--secret <value>` - The secret to store
+- `--ttl <ms>` - Time-to-live in milliseconds
+- `--max-access-count <n>` - Maximum access count
+
+### `confidant get <id>`
+Retrieve a secret by ID.
+
+### `confidant delete <id>`
+Delete a secret.
+
+### `confidant status <id>`
+Check secret status.
+
+## API Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/requests` | Create a secret request |
+| GET | `/requests/:hash` | Secret submission form (HTML) |
+| POST | `/requests/:hash` | Submit a secret |
+| GET | `/requests/:id/poll` | Poll for secret availability |
+| POST | `/secrets` | Create a secret directly |
+| GET | `/secrets/:id` | Retrieve a secret |
+| DELETE | `/secrets/:id` | Delete a secret |
+| GET | `/health` | Health check |
+
+## Deployment Options
+
+### Local Development
+```bash
+npm run dev
+```
+
+### Docker
+```bash
+docker build -t confidant .
+docker run -p 3000:3000 confidant
+```
+
+### ngrok (Quick Public Access)
+```bash
+ngrok http 3000
+```
+
+### Production
+For production, deploy behind a reverse proxy (nginx, Caddy) with proper TLS.
+
+## Security Notes
+
+- **No persistence by default**: Secrets live in memory only
+- **Auto-expiration**: Secrets self-destruct after TTL or access limit
+- **No chat logging**: Secrets bypass chat history entirely
+- **HTTPS required**: Always use TLS in production (ngrok provides this automatically)
+
+## Troubleshooting
+
+### URL Access Issues
+
+**Localhost URL not working?**
+- Ensure Confidant server is running: `confidant serve`
+- Check if port 3000 is available: `lsof -i :3000` (macOS/Linux) or `netstat -ano | findstr :3000` (Windows)
+- Verify server is listening on correct port
+
+**Local Network IP URL not accessible?**
+- Verify both devices are on the same network
+- Check firewall settings on the machine running Confidant
+- Ensure the detected IP is correct (use `--verbose` flag to see detection results)
+- Try pinging the IP from the other device: `ping 192.168.x.x`
+
+**No local IP detected?**
+- This is normal in some environments (cloud VMs, certain network configurations)
+- Use localhost URL if CLI and user are on same machine
+- Use tunneling services for external access
+
+**Tunneling service not working?**
+- Ensure tunnel is running and forwarding to correct port (3000)
+- Check tunnel service status page for connection issues
+- Verify tunnel URL matches the one displayed by Confidant
+- Some tunnels may require authentication - check service documentation
+
+**Cross-device scenarios not working?**
+- Mac Mini + iPhone: Ensure both are on same Wi-Fi network
+- Docker + Host: Use `--network host` flag or port mapping
+- VM + Host: Configure VM network to use bridged or host-only adapter
+
+### Verbose Mode
+
+Use `--verbose` flag to see detailed information:
+```bash
+confidant request --verbose
+# Shows network interface detection results
+# Shows API response details
+# Shows timing information
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | 3000 | Server port |
+| `CONFIDANT_API_URL` | http://localhost:3000 | API URL for CLI |
+
+## Tech Stack
+
+- **Runtime**: Node.js 18+
+- **Language**: TypeScript
+- **Framework**: Hono
+- **Validation**: Zod
+
+## Modular Registry System
+
+Confidant includes a modular registry system that enables dynamic registration and management of components. This provides extensibility and allows for plugin-like architecture.
+
+### Overview
+
+The registry system provides:
+- **Type-safe module registration** using TypeScript generics
+- **Lifecycle hooks** (`init`, `destroy`) for module initialization and cleanup
+- **Multiple registry types** for different component categories
+- **Singleton instances** for consistent access across the application
+
+### Module Types
+
+#### Storage Modules
+
+Storage modules handle data persistence and retrieval:
+
+```typescript
+import { StorageModule, storageRegistry } from './registry.js';
+
+const myStorage: StorageModule = {
+  name: 'my-storage',
+  
+  async init() {
+    console.log('Initializing storage...');
+  },
+  
+  async get(key: string) {
+    // Retrieve value by key
+    return value;
+  },
+  
+  async set(key: string, value: any, ttl?: number) {
+    // Store value with optional TTL
+  },
+  
+  async delete(key: string) {
+    // Delete value by key
+  }
+};
+
+// Register the module
+await storageRegistry.register('my-storage', myStorage);
+
+// Retrieve and use the module
+const storage = storageRegistry.get('my-storage');
+await storage?.set('key', 'value');
+```
+
+#### Validator Modules
+
+Validator modules handle data validation:
+
+```typescript
+import { ValidatorModule, validatorRegistry } from './registry.js';
+
+const myValidator: ValidatorModule = {
+  name: 'my-validator',
+  
+  private errors: string[] = [],
+  
+  async init() {
+    console.log('Initializing validator...');
+  },
+  
+  validate(data: any): boolean {
+    this.errors = [];
+    // Validation logic
+    if (!data) {
+      this.errors.push('Data is required');
+      return false;
+    }
+    return true;
+  },
+  
+  getErrors(): string[] {
+    return [...this.errors];
+  }
+};
+
+await validatorRegistry.register('my-validator', myValidator);
+```
+
+#### Transformer Modules
+
+Transformer modules handle data transformation:
+
+```typescript
+import { TransformerModule, transformerRegistry } from './registry.js';
+
+const myTransformer: TransformerModule = {
+  name: 'my-transformer',
+  
+  async init() {
+    console.log('Initializing transformer...');
+  },
+  
+  transform(data: any): any {
+    // Transform data
+    if (typeof data === 'string') {
+      return data.toUpperCase();
+    }
+    return data;
+  }
+};
+
+await transformerRegistry.register('my-transformer', myTransformer);
+```
+
+### Lifecycle Hooks
+
+Modules can implement optional lifecycle hooks:
+
+```typescript
+const moduleWithLifecycle = {
+  name: 'lifecycle-module',
+  
+  // Called when module is registered
+  async init() {
+    console.log('Module initializing...');
+    // Setup resources, connections, etc.
+  },
+  
+  // Called when module is unregistered
+  async destroy() {
+    console.log('Module cleaning up...');
+    // Release resources, close connections, etc.
+  }
+};
+```
+
+### Registry API
+
+#### `register(name: string, module: T): Promise<void>`
+
+Register a module with the given name.
+
+```typescript
+await storageRegistry.register('redis', redisStorageModule);
+```
+
+#### `unregister(name: string): Promise<void>`
+
+Unregister a module by name.
+
+```typescript
+await storageRegistry.unregister('redis');
+```
+
+#### `get(name: string): T | undefined`
+
+Retrieve a registered module by name.
+
+```typescript
+const storage = storageRegistry.get('redis');
+if (storage) {
+  await storage.get('key');
+}
+```
+
+#### `has(name: string): boolean`
+
+Check if a module is registered.
+
+```typescript
+if (storageRegistry.has('redis')) {
+  console.log('Redis storage is available');
+}
+```
+
+#### `list(): string[]`
+
+Get list of all registered module names.
+
+```typescript
+const modules = storageRegistry.list();
+console.log('Available modules:', modules);
+```
+
+#### `clear(): Promise<void>`
+
+Clear all registered modules.
+
+```typescript
+await storageRegistry.clear();
+```
+
+### Error Handling
+
+The registry throws errors for invalid operations:
+
+```typescript
+try {
+  await storageRegistry.register('redis', redisModule);
+  await storageRegistry.register('redis', redisModule); // Error: duplicate
+} catch (error) {
+  console.error('Registration failed:', error.message);
+}
+
+try {
+  await storageRegistry.unregister('non-existent'); // Error: not found
+} catch (error) {
+  console.error('Unregistration failed:', error.message);
+}
+```
+
+### Example Modules
+
+Confidant includes example modules:
+
+- **MemoryStorageModule**: In-memory storage with TTL support
+- **BasicValidatorModule**: Simple validation for non-empty data
+- **UppercaseTransformerModule**: Transforms strings to uppercase
+
+These are automatically registered on application startup.
+
+## License
+
+ISC
+
+---
+
+**Confidant**: Because your AI assistant shouldn't have to ask for passwords in public.

package/dist/api-client.d.ts

@@ -0,0 +1,58 @@
+export interface SecretCreateResponse {
+    id: string;
+    expiresAt: string;
+    maxAccessCount: number;
+}
+export interface SecretGetResponse {
+    secret: string;
+}
+export interface SecretStatusResponse {
+    id: string;
+    expiresAt: string;
+    accessCount: number;
+    maxAccessCount: number;
+}
+export interface ErrorResponse {
+    error: string;
+}
+export interface CreateSecretRequestResponse {
+    id: string;
+    hash: string;
+    url: string;
+    expiresAt: string;
+    status: string;
+    label?: string;
+}
+export interface PollSecretRequestResponse {
+    id: string;
+    status: string;
+    secret: string | null;
+    label?: string;
+}
+export declare class ApiClient {
+    private baseUrl;
+    constructor(baseUrl: string);
+    get apiUrl(): string;
+    private validateUrl;
+    private request;
+    createSecret(secret: string, ttl?: number, maxAccessCount?: number): Promise<SecretCreateResponse>;
+    getSecret(id: string): Promise<SecretGetResponse>;
+    deleteSecret(id: string): Promise<{
+        message: string;
+    }>;
+    getSecretStatus(id: string): Promise<SecretStatusResponse>;
+    /**
+     * Create a new secret request
+     * @param expiresIn Time to live in seconds (default: 86400)
+     * @param label Optional label to describe what secret is being requested
+     * @returns Secret request details
+     */
+    createSecretRequest(expiresIn?: number, label?: string): Promise<CreateSecretRequestResponse>;
+    /**
+     * Poll for secret availability and retrieve if available
+     * @param id The request ID
+     * @returns Poll result with status and optional secret
+     */
+    pollSecretRequest(id: string): Promise<PollSecretRequestResponse>;
+}
+//# sourceMappingURL=api-client.d.ts.map

package/dist/api-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../src/api-client.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,2BAA2B;IAC1C,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,yBAAyB;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,SAAS;IACpB,OAAO,CAAC,OAAO,CAAS;gBAEZ,OAAO,EAAE,MAAM;IAK3B,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,OAAO,CAAC,WAAW;YAQL,OAAO;IA8Bf,YAAY,CAChB,MAAM,EAAE,MAAM,EACd,GAAG,CAAC,EAAE,MAAM,EACZ,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,oBAAoB,CAAC;IAmB1B,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAIjD,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAMtD,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAMhE;;;;;OAKG;IACG,mBAAmB,CACvB,SAAS,GAAE,MAAc,EACzB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,2BAA2B,CAAC;IAgBvC;;;;OAIG;IACG,iBAAiB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,yBAAyB,CAAC;CAGxE"}