@lifeaitools/clauth 1.30.24 → 1.30.26

package/.clauth-skill/references/operator-guide.md

@@ -1,148 +1,175 @@
-# clauth Operator Guide
-
-For teams deploying their own clauth instance from scratch.
-
----
-
-## What "Operator" Means
-
-When you clone the clauth repo and run `clauth setup`, you're connecting to an existing vault. If you want to run your **own** vault (different Supabase project, your own team), you're the operator. This guide covers that.
-
----
-
-## Step 1 — Supabase Project
-
-You need a Supabase project. Create one at supabase.com if you don't have one.
-
-Collect:
-- Project URL: `https://<ref>.supabase.co`
-- Anon key (public JWT)
-- Service role key (admin JWT)
-
----
-
-## Step 2 — Run Migrations
-
-In Supabase SQL Editor (or via CLI), run both migration files in order:
-
-1. `supabase/migrations/001_clauth_schema.sql`
-2. `supabase/migrations/002_vault_helpers.sql`
-
-Or via Supabase CLI:
-```bash
-supabase db push
-```
-
-This creates:
-- `clauth_services` — service registry (12 services seeded)
-- `clauth_machines` — machine fingerprint registry
-- `clauth_audit` — all operations logged
-- Vault helper RPCs (upsert/decrypt/delete/list)
-
----
-
-## Step 3 — Deploy Edge Function
-
-```bash
-supabase functions deploy auth-vault --project-ref <your-ref>
-```
-
-Or deploy from the Supabase dashboard by uploading `supabase/functions/auth-vault/index.ts`.
-
-The function automatically reads `CLAUTH_HMAC_SALT` and `CLAUTH_ADMIN_BOOTSTRAP_TOKEN` from Supabase Vault (or env vars if set).
-
----
-
-## Step 4 — Generate and Store Secrets
-
-Run this to generate a salt and bootstrap token:
-```bash
-node -e "const c=require('crypto'); console.log('SALT:', c.randomBytes(32).toString('hex')); console.log('BOOTSTRAP:', c.randomBytes(16).toString('hex'));"
-```
-
-Store them in Supabase Vault via SQL Editor:
-```sql
-select vault.create_secret('<your-salt>', 'CLAUTH_HMAC_SALT', 'clauth HMAC salt');
-select vault.create_secret('<your-bootstrap>', 'CLAUTH_ADMIN_BOOTSTRAP_TOKEN', 'clauth bootstrap token');
-```
-
-Or via Supabase Dashboard → Vault → New Secret.
-
----
-
-## Step 5 — Distribute to Team
-
-Give team members:
-1. Your Supabase project URL
-2. Your Supabase anon key (public — safe to share)
-3. The bootstrap token (treat as a shared secret — regenerate after everyone registers)
-
-Each person runs:
-```bash
-git clone https://github.com/LIFEAI/clauth
-cd clauth && .\install.ps1   # or bash install.sh
-clauth setup
-```
-
----
-
-## Adding Team Members After Initial Setup
-
-Once the bootstrap token has been used by the first person, you can either:
-- Keep the same token for additional machines (it's reusable)
-- Rotate it after everyone is registered:
-
-```sql
--- Generate new one
-select vault.create_secret('new-token-here', 'CLAUTH_ADMIN_BOOTSTRAP_TOKEN', 'rotated');
--- This overwrites the old one
-```
-
----
-
-## Viewing the Audit Log
-
-```sql
-select machine_hash, service_name, action, result, detail, created_at
-from clauth_audit
-order by created_at desc
-limit 50;
-```
-
----
-
-## Disabling a Machine
-
-If a machine is lost or stolen:
-```sql
-update clauth_machines set enabled = false where label = 'Dave-Desktop-Win11';
-```
-
-That machine's HMAC tokens will be rejected immediately.
-
----
-
-## Rotating the HMAC Salt
-
-If the salt is compromised, rotate it:
-```sql
--- Find the existing secret ID
-select id, name from vault.secrets where name = 'CLAUTH_HMAC_SALT';
-
--- Update it
-select vault.update_secret('<id>', 'new-salt-here');
-```
-
-**Warning:** After rotating the salt, ALL existing machines will fail HMAC validation. Every machine needs to re-run `clauth setup` with the new bootstrap token.
-
----
-
-## Project Identifiers (LIFEAI canonical)
-
-| Item | Value |
-|------|-------|
-| Supabase project | `uvojezuorjgqzmhhgluu` |
-| Supabase URL | `https://uvojezuorjgqzmhhgluu.supabase.co` |
-| Edge Function | `auth-vault` (deployed, ACTIVE) |
-| GitHub org | LIFEAI |
-| Repo | https://github.com/LIFEAI/clauth |
+# clauth Operator Guide
+
+For teams deploying their own clauth instance from scratch.
+
+---
+
+## What "Operator" Means
+
+When you clone the clauth repo and run `clauth setup`, you're connecting to an existing vault. If you want to run your **own** vault (different Supabase project, your own team), you're the operator. This guide covers that.
+
+---
+
+## Step 1 — Supabase Project
+
+You need a Supabase project. Create one at supabase.com if you don't have one.
+
+Collect:
+- Project URL: `https://<ref>.supabase.co`
+- Anon key (public JWT)
+- Service role key (admin JWT)
+
+---
+
+## Step 2 — Run Migrations
+
+In Supabase SQL Editor (or via CLI), run both migration files in order:
+
+1. `supabase/migrations/001_clauth_schema.sql`
+2. `supabase/migrations/002_vault_helpers.sql`
+
+Or via Supabase CLI:
+```bash
+supabase db push
+```
+
+This creates:
+- `clauth_services` — service registry (12 services seeded)
+- `clauth_machines` — machine fingerprint registry
+- `clauth_audit` — all operations logged
+- Vault helper RPCs (upsert/decrypt/delete/list)
+
+---
+
+## Step 3 — Deploy Edge Function
+
+```bash
+supabase functions deploy auth-vault --project-ref <your-ref>
+```
+
+Or deploy from the Supabase dashboard by uploading `supabase/functions/auth-vault/index.ts`.
+
+The function automatically reads `CLAUTH_HMAC_SALT` and `CLAUTH_ADMIN_BOOTSTRAP_TOKEN` from Supabase Vault (or env vars if set).
+
+---
+
+## Step 4 — Generate and Store Secrets
+
+Run this to generate a salt and bootstrap token:
+```bash
+node -e "const c=require('crypto'); console.log('SALT:', c.randomBytes(32).toString('hex')); console.log('BOOTSTRAP:', c.randomBytes(16).toString('hex'));"
+```
+
+Store them in Supabase Vault via SQL Editor:
+```sql
+select vault.create_secret('<your-salt>', 'CLAUTH_HMAC_SALT', 'clauth HMAC salt');
+select vault.create_secret('<your-bootstrap>', 'CLAUTH_ADMIN_BOOTSTRAP_TOKEN', 'clauth bootstrap token');
+```
+
+Or via Supabase Dashboard → Vault → New Secret.
+
+---
+
+## Step 5 — Distribute to Team
+
+Give team members:
+1. Your Supabase project URL
+2. Your Supabase anon key (public — safe to share)
+3. The bootstrap token (treat as a shared secret — regenerate after everyone registers)
+
+Each person runs:
+```bash
+git clone https://github.com/LIFEAI/clauth
+cd clauth && .\install.ps1   # or bash install.sh
+clauth setup
+```
+
+---
+
+## Adding Team Members After Initial Setup
+
+Once the bootstrap token has been used by the first person, you can either:
+- Keep the same token for additional machines (it's reusable)
+- Rotate it after everyone is registered:
+
+```sql
+-- Generate new one
+select vault.create_secret('new-token-here', 'CLAUTH_ADMIN_BOOTSTRAP_TOKEN', 'rotated');
+-- This overwrites the old one
+```
+
+---
+
+## Managed PM2 Operations (LIFEAI development hosts)
+
+Use the clauth operations controller for approved PM2 lifecycle and deployment
+actions. Its policy JSON is the server-side allowlist; it must define only the
+applications and operations this host is permitted to expose. Do not grant
+host-wide PM2 actions unless there is an explicit operational requirement.
+
+Validate before changing the process manager, then install:
+
+```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 installer owns only the `clauth-deployment` process. It checks the local
+health endpoint and verifies that the catalog remains bearer-gated. Keep the
+controller bearer in clauth, not in a shell history, policy file, or PM2
+environment dump. Use `clauth ops catalog` and scoped operations commands rather
+than invoking PM2 directly.
+
+---
+
+## Viewing the Audit Log
+
+```sql
+select machine_hash, service_name, action, result, detail, created_at
+from clauth_audit
+order by created_at desc
+limit 50;
+```
+
+---
+
+## Disabling a Machine
+
+If a machine is lost or stolen:
+```sql
+update clauth_machines set enabled = false where label = 'Dave-Desktop-Win11';
+```
+
+That machine's HMAC tokens will be rejected immediately.
+
+---
+
+## Rotating the HMAC Salt
+
+If the salt is compromised, rotate it:
+```sql
+-- Find the existing secret ID
+select id, name from vault.secrets where name = 'CLAUTH_HMAC_SALT';
+
+-- Update it
+select vault.update_secret('<id>', 'new-salt-here');
+```
+
+**Warning:** After rotating the salt, ALL existing machines will fail HMAC validation. Every machine needs to re-run `clauth setup` with the new bootstrap token.
+
+---
+
+## Project Identifiers (LIFEAI canonical)
+
+| Item | Value |
+|------|-------|
+| Supabase project | `uvojezuorjgqzmhhgluu` |
+| Supabase URL | `https://uvojezuorjgqzmhhgluu.supabase.co` |
+| Edge Function | `auth-vault` (deployed, ACTIVE) |
+| GitHub org | LIFEAI |
+| Repo | https://github.com/LIFEAI/clauth |