@lifeaitools/clauth 1.30.23 → 1.30.25

package/.clauth-skill/SKILL.md

@@ -1,275 +1,306 @@
----
-name: clauth
-description: Install, configure, and operate clauth — the LIFEAI hardware-bound credential vault. Triggers on "install clauth", "set up my keys", "clauth install", "store my credentials", "set up the vault", or any mention of clauth or managing LIFEAI service credentials. When triggered for install, check GitHub MCP first, clone LIFEAI/clauth, and run the installer. Also handles ongoing clauth commands: status, get, write, enable, disable, add service, revoke.
----
-
-# clauth — LIFEAI Credential Vault
-
-Hardware-bound credential vault for the LIFEAI stack. Your machine is the second factor. Keys live in Supabase Vault (AES-256).
-
----
-
-## How Claude Interfaces with clauth
-
-> **CRITICAL:** Agents should use the local daemon for credential discovery and
-> exact secret retrieval. Do not ask the user for the vault password just to get
-> a key, do not use interactive prompts, and do not walk every service.
-
-### Method 1 — Local daemon (preferred for agents)
-
-Discover services without reading secrets:
-
-```bash
-curl -s http://127.0.0.1:52437/ping
-curl -s http://127.0.0.1:52437/knowledge
-curl -s http://127.0.0.1:52437/list-services
-```
-
-Retrieve exactly one credential only when the next command needs it:
-
-```bash
-curl -s http://127.0.0.1:52437/v/<service>
-```
-
-`/knowledge` is safe to cache for a session: it returns service metadata and
-`has_key`, but no raw secrets and no Vault secret names. `/status` uses the same
-short metadata cache and can be forced with `?refresh=1`.
-
-### Method 2 — CLI with `--pw` flag (admin/setup only)
-
-All clauth commands accept `-p` / `--pw <password>` to skip the interactive
-password prompt. Use this for local admin/setup tasks, not routine agent secret
-retrieval:
-
-```bash
-clauth status -p "YourPassword"
-clauth test -p "YourPassword"
-clauth enable github -p "YourPassword"
-clauth write key github -p "YourPassword"   # still prompts for the key value
-```
-
-### Method 3 — Direct API calls (implementation/debugging only)
-
-Call the auth-vault Edge Function directly only when debugging clauth internals.
-Normal agents should not bypass the daemon metadata cache.
-
-**Base URL:** `https://<project-ref>.supabase.co/functions/v1/auth-vault`
-**Auth header:** `Authorization: Bearer <supabase-anon-key>`
-**Method:** POST (all routes)
-**Content-Type:** `application/json`
-
-#### HMAC Token Derivation (must match server)
-
-```js
-import { createHmac, createHash, execSync } from "crypto";
-
-// 1. Get machine hash (same as fingerprint.js)
-// Windows:
-const uuid = execSync("wmic csproduct get uuid /format:value", { encoding: "utf8" })
-  .match(/UUID=([A-F0-9-]+)/i)?.[1]?.trim();
-const machineGuid = execSync(
-  "reg query HKLM\\SOFTWARE\\Microsoft\\Cryptography /v MachineGuid",
-  { encoding: "utf8" }
-).match(/MachineGuid\s+REG_SZ\s+([a-f0-9-]+)/i)?.[1]?.trim();
-const machineHash = createHash("sha256").update(`${uuid}:${machineGuid}`).digest("hex");
-
-// 2. Derive HMAC token
-const windowMs = 5 * 60 * 1000;
-const window = Math.floor(Date.now() / windowMs);
-const message = `${machineHash}:${window}`;
-const token = createHmac("sha256", password).update(message).digest("hex");
-const timestamp = window * windowMs;
-```
-
-#### API Routes
-
-| Route | Body fields | Returns |
-|-------|-------------|---------|
-| `POST /status` | `machine_hash, token, timestamp, password` | `{ services: [...] }` |
-| `POST /test` | `machine_hash, token, timestamp, password` | `{ ok: true }` |
-| `POST /retrieve` | `+ service` | `{ value: "..." }` |
-| `POST /write` | `+ service, value` | `{ ok: true }` |
-| `POST /enable` | `+ service, enabled: bool` | `{ ok: true }` |
-| `POST /add` | `+ name, label, key_type, description` | `{ ok: true }` |
-| `POST /remove` | `+ service, confirm: true` | `{ ok: true }` |
-| `POST /revoke` | `+ service, confirm: true` | `{ ok: true }` |
-| `POST /register-machine` | `machine_hash, hmac_seed_hash, label, admin_token` | `{ ok: true }` |
-
-All auth routes require: `machine_hash`, `token`, `timestamp`, `password`.
-
-### Password Handling
-
-- Do not ask the user for their clauth password for routine credential lookup
-- Use the unlocked local daemon whenever possible
-- Never log or echo the password
-- If the daemon is locked, ask the user to unlock `http://127.0.0.1:52437`
-
----
-
-## When someone says "install clauth"
-
-### Step 1 — Install from npm
-
-```bash
-npm install -g @lifeaitools/clauth
-```
-
-If already installed, update:
-```bash
-npm update -g @lifeaitools/clauth
-```
-
-### Step 2 — Run the installer
-
-Use CLI flags to avoid interactive prompts:
-
-```bash
-clauth install --ref <supabase-project-ref> --pat <personal-access-token>
-```
-
-**Project ref** — last part of the Supabase project URL:
-`https://supabase.com/dashboard/project/` **`uvojezuorjgqzmhhgluu`**
-
-**Personal Access Token (PAT):**
-`https://supabase.com/dashboard/account/tokens` → Generate new token
-*(NOT the anon key or service_role — this is your account-level token)*
-
-The installer provisions everything and prints a **bootstrap token** — save it.
-
-### Step 3 — Setup this machine
-
-```bash
-clauth setup --admin-token <bootstrap-token> -p <password>
-```
-
-Then verify:
-```bash
-clauth test -p <password>
-clauth status -p <password>
-```
-
-### Step 4 — Write your first key
-
-```bash
-clauth write key github -p <password>     # prompts for value
-clauth enable github -p <password>
-clauth get github -p <password>
-```
-
-See `references/keys-guide.md` for where to find every credential.
-
----
-
-## Command reference
-
-```
-clauth install [--ref R] [--pat P]     First-time: provision Supabase + install skill
-clauth setup [--admin-token T] [-p P]  Register this machine
-clauth status [-p P]                   All services + state
-clauth test [-p P]                     Verify HMAC connection
-clauth list [-p P]                     Service names
-clauth search <query> [-p P]           Search names and metadata
-clauth search <query> --addresses [-p P]
-                                      Also search redacted address hints (may read multiple secrets)
-
-clauth write key <service> [-p P]      Store a credential
-clauth write pw [-p P]                 Change password
-clauth enable <svc|all> [-p P]         Activate service
-clauth disable <svc|all> [-p P]        Suspend service
-clauth get <service> [-p P]            Retrieve a key
-
-clauth add service <n> [-p P]          Register new service
-clauth remove service <n> [-p P]       Remove service
-clauth revoke <svc|all> [-p P]         Delete key (destructive)
-
-clauth scrub                           Scrub active transcript (most recent .jsonl)
-clauth scrub <file>                    Scrub a specific file
-clauth scrub all                       Scrub all transcripts in ~/.claude/projects/
-clauth scrub all --force               Rescrub everything (ignore markers)
-
-clauth uninstall --ref R --pat P       Full teardown (DB, Edge Fn, secrets, skill, config)
-clauth uninstall --ref R --pat P --yes Skip confirmation
-```
-
-## Services
-
-`github` `supabase-anon` `supabase-service` `supabase-db`
-`vercel` `namecheap` `neo4j` `anthropic`
-`r2` `r2-bucket` `cloudflare` `rocketreach`
-
-Service type `fileserver` — mount configuration for fs tools (UI-only config).
-
----
-
-## Daemon Metadata Cache
-
-When discovering service names, do not retrieve secrets. Use the daemon metadata
-cache:
-
-```bash
-curl -s http://127.0.0.1:52437/knowledge
-curl -s http://127.0.0.1:52437/list-services
-```
-
-`/knowledge` is agent-safe: it returns service metadata and `has_key`, but no
-raw secrets and no Vault secret names. Fetch `GET /v/<service>` only for the one
-exact credential needed by the next command. Never walk every service and never
-bulk-fetch all secrets.
-
-## MCP Server (v1.16.9+)
-
-clauth runs as an MCP server with five namespaced paths and safe
-credential-discovery tools:
-
-| Path | Namespace | Tools |
-|------|-----------|-------|
-| `/clauth` | `clauth_*` + runtime helpers | 23 default live tools, including `clauth_knowledge` |
-| `/gws` | `gws_*` | 6 Google Workspace tools |
-| `/fs` | `fs_*` | 20 filesystem and git-safe file tools |
-| `/chitchat` | `chitchat_*` | 7 collaboration relay tools |
-| `/codevelop` | `codevelop_*` | 7 peer development tools |
-| `/mcp` | all | 63 tools combined |
-
-The default live `/clauth` surface includes credential tools plus
-`call_agent`, `monkey_dispatch`, `handoff_start`, `terminal_*`, and `channel_*`.
-Admin write tools are gated by write-mode.
-
-### claude.ai Connector URLs (noauth mode)
-- `https://clauth.regendevcorp.com/clauth` — credential tools
-- `https://clauth.regendevcorp.com/gws` — Google Workspace
-- `https://clauth.regendevcorp.com/chitchat` — collaboration relay tools
-- `https://clauth.regendevcorp.com/codevelop` — peer development tools
-- `https://fs.regendevcorp.com/fs` — filesystem tools
-
-Noauth mode: fresh domains that return 404 on OAuth endpoints. claude.ai connects directly (Anthropic OAuth proxy bug workaround).
-
-Use `clauth_knowledge` or `clauth_status` for discovery. Use `clauth_get` only
-for one exact secret. `clauth_search` is metadata-only by default; pass
-`addresses: true` only when redacted address hints are intentionally needed.
-`clauth_inject` is guarded against accidental bulk vault sweeps.
-
-### FS Tools
-`fs_read` `fs_write` `fs_stat` `fs_append` `fs_write_chunk` `fs_ingest_url`
-`fs_import_git_files` `fs_list` `fs_grep` `fs_glob` `fs_delete` `fs_mkdir`
-`fs_edit` `fs_move` `fs_copy` `fs_mounts` `fs_repo_status` `fs_use_branch`
-`fs_commit` `fs_diff`
-
-Path-jail security: all paths resolved against mount root. Permission flags (r/w/d) per mount. Uses `@vscode/ripgrep` for grep, `fast-glob` for glob.
-
-### Testing
-```bash
-node test-tools.mjs    # MCP tool execution smoke tests
-```
-
----
-
-## Troubleshooting
-
-| Error | Fix |
-|-------|-----|
-| `machine_not_found` | Run `clauth setup` |
-| `timestamp_expired` | Sync system clock |
-| `invalid_token` | Wrong password |
-| `service_disabled` | `clauth enable <service> -p <password>` |
-| `no_key_stored` | `clauth write key <service> -p <password>` |
-| ANSI garbage output | You piped stdin — use `-p` flag instead |
+---
+name: clauth
+description: Install, configure, and operate clauth — the LIFEAI hardware-bound credential vault. Triggers on "install clauth", "set up my keys", "clauth install", "store my credentials", "set up the vault", or any mention of clauth or managing LIFEAI service credentials. When triggered for install, check GitHub MCP first, clone LIFEAI/clauth, and run the installer. Also handles ongoing clauth commands: status, get, write, enable, disable, add service, revoke.
+---
+
+# clauth — LIFEAI Credential Vault
+
+Hardware-bound credential vault for the LIFEAI stack. Your machine is the second factor. Keys live in Supabase Vault (AES-256).
+
+---
+
+## How Claude Interfaces with clauth
+
+> **CRITICAL:** Agents should use the local daemon for credential discovery and
+> exact secret retrieval. Do not ask the user for the vault password just to get
+> a key, do not use interactive prompts, and do not walk every service.
+
+### Method 1 — Local daemon (preferred for agents)
+
+Discover services without reading secrets:
+
+```bash
+curl -s http://127.0.0.1:52437/ping
+curl -s http://127.0.0.1:52437/knowledge
+curl -s http://127.0.0.1:52437/list-services
+```
+
+Retrieve exactly one credential only when the next command needs it:
+
+```bash
+curl -s http://127.0.0.1:52437/v/<service>
+```
+
+`/knowledge` is safe to cache for a session: it returns service metadata and
+`has_key`, but no raw secrets and no Vault secret names. `/status` uses the same
+short metadata cache and can be forced with `?refresh=1`.
+
+### Method 2 — CLI with `--pw` flag (admin/setup only)
+
+All clauth commands accept `-p` / `--pw <password>` to skip the interactive
+password prompt. Use this for local admin/setup tasks, not routine agent secret
+retrieval:
+
+```bash
+clauth status -p "YourPassword"
+clauth test -p "YourPassword"
+clauth enable github -p "YourPassword"
+clauth write key github -p "YourPassword"   # still prompts for the key value
+```
+
+### Method 3 — Direct API calls (implementation/debugging only)
+
+Call the auth-vault Edge Function directly only when debugging clauth internals.
+Normal agents should not bypass the daemon metadata cache.
+
+**Base URL:** `https://<project-ref>.supabase.co/functions/v1/auth-vault`
+**Auth header:** `Authorization: Bearer <supabase-anon-key>`
+**Method:** POST (all routes)
+**Content-Type:** `application/json`
+
+#### HMAC Token Derivation (must match server)
+
+```js
+import { createHmac, createHash, execSync } from "crypto";
+
+// 1. Get machine hash (same as fingerprint.js)
+// Windows:
+const uuid = execSync("wmic csproduct get uuid /format:value", { encoding: "utf8" })
+  .match(/UUID=([A-F0-9-]+)/i)?.[1]?.trim();
+const machineGuid = execSync(
+  "reg query HKLM\\SOFTWARE\\Microsoft\\Cryptography /v MachineGuid",
+  { encoding: "utf8" }
+).match(/MachineGuid\s+REG_SZ\s+([a-f0-9-]+)/i)?.[1]?.trim();
+const machineHash = createHash("sha256").update(`${uuid}:${machineGuid}`).digest("hex");
+
+// 2. Derive HMAC token
+const windowMs = 5 * 60 * 1000;
+const window = Math.floor(Date.now() / windowMs);
+const message = `${machineHash}:${window}`;
+const token = createHmac("sha256", password).update(message).digest("hex");
+const timestamp = window * windowMs;
+```
+
+#### API Routes
+
+| Route | Body fields | Returns |
+|-------|-------------|---------|
+| `POST /status` | `machine_hash, token, timestamp, password` | `{ services: [...] }` |
+| `POST /test` | `machine_hash, token, timestamp, password` | `{ ok: true }` |
+| `POST /retrieve` | `+ service` | `{ value: "..." }` |
+| `POST /write` | `+ service, value` | `{ ok: true }` |
+| `POST /enable` | `+ service, enabled: bool` | `{ ok: true }` |
+| `POST /add` | `+ name, label, key_type, description` | `{ ok: true }` |
+| `POST /remove` | `+ service, confirm: true` | `{ ok: true }` |
+| `POST /revoke` | `+ service, confirm: true` | `{ ok: true }` |
+| `POST /register-machine` | `machine_hash, hmac_seed_hash, label, admin_token` | `{ ok: true }` |
+
+All auth routes require: `machine_hash`, `token`, `timestamp`, `password`.
+
+### Password Handling
+
+- Do not ask the user for their clauth password for routine credential lookup
+- Use the unlocked local daemon whenever possible
+- Never log or echo the password
+- If the daemon is locked, ask the user to unlock `http://127.0.0.1:52437`
+
+---
+
+## When someone says "install clauth"
+
+### Step 1 — Install from npm
+
+```bash
+npm install -g @lifeaitools/clauth
+```
+
+If already installed, update:
+```bash
+npm update -g @lifeaitools/clauth
+```
+
+### Step 2 — Run the installer
+
+Use CLI flags to avoid interactive prompts:
+
+```bash
+clauth install --ref <supabase-project-ref> --pat <personal-access-token>
+```
+
+**Project ref** — last part of the Supabase project URL:
+`https://supabase.com/dashboard/project/` **`uvojezuorjgqzmhhgluu`**
+
+**Personal Access Token (PAT):**
+`https://supabase.com/dashboard/account/tokens` → Generate new token
+*(NOT the anon key or service_role — this is your account-level token)*
+
+The installer provisions everything and prints a **bootstrap token** — save it.
+
+### Step 3 — Setup this machine
+
+```bash
+clauth setup --admin-token <bootstrap-token> -p <password>
+```
+
+Then verify:
+```bash
+clauth test -p <password>
+clauth status -p <password>
+```
+
+### Step 4 — Write your first key
+
+```bash
+clauth write key github -p <password>     # prompts for value
+clauth enable github -p <password>
+clauth get github -p <password>
+```
+
+See `references/keys-guide.md` for where to find every credential.
+
+---
+
+## Command reference
+
+```
+clauth install [--ref R] [--pat P]     First-time: provision Supabase + install skill
+clauth setup [--admin-token T] [-p P]  Register this machine
+clauth status [-p P]                   All services + state
+clauth test [-p P]                     Verify HMAC connection
+clauth list [-p P]                     Service names
+clauth search <query> [-p P]           Search names and metadata
+clauth search <query> --addresses [-p P]
+                                      Also search redacted address hints (may read multiple secrets)
+
+clauth write key <service> [-p P]      Store a credential
+clauth write pw [-p P]                 Change password
+clauth enable <svc|all> [-p P]         Activate service
+clauth disable <svc|all> [-p P]        Suspend service
+clauth get <service> [-p P]            Retrieve a key
+
+clauth add service <n> [-p P]          Register new service
+clauth remove service <n> [-p P]       Remove service
+clauth revoke <svc|all> [-p P]         Delete key (destructive)
+
+clauth scrub                           Scrub active transcript (most recent .jsonl)
+clauth scrub <file>                    Scrub a specific file
+clauth scrub all                       Scrub all transcripts in ~/.claude/projects/
+clauth scrub all --force               Rescrub everything (ignore markers)
+
+clauth uninstall --ref R --pat P       Full teardown (DB, Edge Fn, secrets, skill, config)
+clauth uninstall --ref R --pat P --yes Skip confirmation
+```
+
+## Services
+
+`github` `supabase-anon` `supabase-service` `supabase-db`
+`vercel` `namecheap` `neo4j` `anthropic`
+`r2` `r2-bucket` `cloudflare` `rocketreach`
+
+Service type `fileserver` — mount configuration for fs tools (UI-only config).
+
+---
+
+## Daemon Metadata Cache
+
+When discovering service names, do not retrieve secrets. Use the daemon metadata
+cache:
+
+```bash
+curl -s http://127.0.0.1:52437/knowledge
+curl -s http://127.0.0.1:52437/list-services
+```
+
+`/knowledge` is agent-safe: it returns service metadata and `has_key`, but no
+raw secrets and no Vault secret names. Fetch `GET /v/<service>` only for the one
+exact credential needed by the next command. Never walk every service and never
+bulk-fetch all secrets.
+
+## Managed PM2 Operations Control Plane
+
+For LIFEAI development hosts, manage an approved PM2 application through the
+bearer-authenticated clauth operations control plane. Do **not** invoke PM2
+directly from an agent, dashboard, or deployment script. The policy file is the
+allowlist: it names permitted applications, operations, deployment definitions,
+and whether host-wide actions are available.
+
+Install or validate the local controller with its explicit policy file:
+
+```bash
+# Linux
+clauth ops install --config /etc/clauth/ops-control-plane.json --dry-run
+clauth ops install --config /etc/clauth/ops-control-plane.json
+
+# Windows PowerShell
+clauth ops install --config C:\ProgramData\clauth\ops-control-plane.json --dry-run
+clauth ops install --config C:\ProgramData\clauth\ops-control-plane.json
+```
+
+The live install replaces only the installer-owned `clauth-deployment` PM2
+process, verifies its loopback `/health` response, and checks that an unauthenticated
+catalog request is rejected. It retrieves its bearer only from the local clauth
+service; never paste, print, or place that bearer in a policy file.
+
+Use `clauth ops catalog` or the corresponding scoped MCP operations tools for
+approved process inspection and lifecycle actions. Before a production promotion,
+retain the job receipt and verify the selected application's health route. A
+passing install proves controller setup; it does not by itself prove an arbitrary
+application deployment.
+
+## MCP Server (v1.16.9+)
+
+clauth runs as an MCP server with five namespaced paths and safe
+credential-discovery tools:
+
+| Path | Namespace | Tools |
+|------|-----------|-------|
+| `/clauth` | `clauth_*` + runtime helpers | 23 default live tools, including `clauth_knowledge` |
+| `/gws` | `gws_*` | 6 Google Workspace tools |
+| `/fs` | `fs_*` | 20 filesystem and git-safe file tools |
+| `/chitchat` | `chitchat_*` | 7 collaboration relay tools |
+| `/codevelop` | `codevelop_*` | 7 peer development tools |
+| `/mcp` | all | 63 tools combined |
+
+The default live `/clauth` surface includes credential tools plus
+`call_agent`, `monkey_dispatch`, `handoff_start`, `terminal_*`, and `channel_*`.
+Admin write tools are gated by write-mode.
+
+### claude.ai Connector URLs (noauth mode)
+- `https://clauth.regendevcorp.com/clauth` — credential tools
+- `https://clauth.regendevcorp.com/gws` — Google Workspace
+- `https://clauth.regendevcorp.com/chitchat` — collaboration relay tools
+- `https://clauth.regendevcorp.com/codevelop` — peer development tools
+- `https://fs.regendevcorp.com/fs` — filesystem tools
+
+Noauth mode: fresh domains that return 404 on OAuth endpoints. claude.ai connects directly (Anthropic OAuth proxy bug workaround).
+
+Use `clauth_knowledge` or `clauth_status` for discovery. Use `clauth_get` only
+for one exact secret. `clauth_search` is metadata-only by default; pass
+`addresses: true` only when redacted address hints are intentionally needed.
+`clauth_inject` is guarded against accidental bulk vault sweeps.
+
+### FS Tools
+`fs_read` `fs_write` `fs_stat` `fs_append` `fs_write_chunk` `fs_ingest_url`
+`fs_import_git_files` `fs_list` `fs_grep` `fs_glob` `fs_delete` `fs_mkdir`
+`fs_edit` `fs_move` `fs_copy` `fs_mounts` `fs_repo_status` `fs_use_branch`
+`fs_commit` `fs_diff`
+
+Path-jail security: all paths resolved against mount root. Permission flags (r/w/d) per mount. Uses `@vscode/ripgrep` for grep, `fast-glob` for glob.
+
+### Testing
+```bash
+node test-tools.mjs    # MCP tool execution smoke tests
+```
+
+---
+
+## Troubleshooting
+
+| Error | Fix |
+|-------|-----|
+| `machine_not_found` | Run `clauth setup` |
+| `timestamp_expired` | Sync system clock |
+| `invalid_token` | Wrong password |
+| `service_disabled` | `clauth enable <service> -p <password>` |
+| `no_key_stored` | `clauth write key <service> -p <password>` |
+| ANSI garbage output | You piped stdin — use `-p` flag instead |