@lifeaitools/clauth 1.30.24 → 1.30.26

package/.clauth-skill/SKILL.md

@@ -1,14 +1,14 @@
----
-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).
-
----
-
+---
+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
@@ -52,119 +52,119 @@ clauth write key github -p "YourPassword"   # still prompts for the key value
 
 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`.
-
+
+**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
+
+---
+
+## 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
@@ -173,34 +173,34 @@ 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).
-
----
-
+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
@@ -216,6 +216,37 @@ 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
@@ -233,43 +264,43 @@ credential-discovery tools:
 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)
+
+### 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.
-
+
+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 |
+
+---
+
+## 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 |