@lifeaitools/clauth 0.4.1 → 0.5.0

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

@@ -1,148 +1,148 @@
-# 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
+```
+
+---
+
+## 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 |

package/README.md

@@ -1,125 +1,125 @@
-# @lifeaitools/clauth
-
-Hardware-bound credential vault for the LIFEAI stack. Your machine is the second factor. Keys live in Supabase Vault (AES-256). Nothing sensitive ever touches a config file.
-
----
-
-## Install
-
-```bash
-npm install -g @lifeaitools/clauth
-```
-
-Then provision your Supabase project:
-
-```bash
-clauth install
-```
-
-That's it. `clauth install` handles everything:
-- Creates all database tables
-- Deploys the `auth-vault` Edge Function
-- Generates HMAC salt + bootstrap token
-- Tests the connection end-to-end
-- Installs the Claude skill
-
-At the end it prints a **bootstrap token** — save it for the next step.
-
----
-
-## After Install — Register Your Machine
-
-```bash
-clauth setup
-```
-
-Prompts for: machine label, password, bootstrap token (from `clauth install`).
-
-Then verify:
-```bash
-clauth test      # → PASS
-clauth status    # → 12 services, all NO KEY
-```
-
----
-
-## What clauth install asks for
-
-Two things from Supabase:
-
-**1. Project ref** — the last segment of your Supabase project URL:
-`https://supabase.com/dashboard/project/` **`your-ref-here`**
-
-**2. Personal Access Token (PAT)**:
-`https://supabase.com/dashboard/account/tokens` → Generate new token
-
-> This is **not** your anon key or service_role key — it is your account-level token.
-
----
-
-## Writing Your First Key
-
-```bash
-clauth write key github     # prompts for value
-clauth enable github
-clauth get github
-```
-
----
-
-## Command Reference
-
-```
-clauth install              Provision Supabase + install Claude skill
-clauth setup                Register this machine with the vault
-clauth status               All services + state
-clauth test                 Verify connection
-
-clauth write key <service>  Store a credential
-clauth write pw             Change password
-clauth enable <svc|all>     Activate service
-clauth disable <svc|all>    Suspend service
-clauth get <service>        Retrieve a key
-
-clauth add service <n>      Register new service
-clauth remove service <n>   Remove service
-clauth revoke <svc|all>     Delete key (destructive)
-```
-
-## Built-in Services
-
-`github` `supabase-anon` `supabase-service` `supabase-db`
-`vercel` `namecheap` `neo4j` `anthropic`
-`r2` `r2-bucket` `cloudflare` `rocketreach`
-
----
-
-## How It Works
-
-```
-Machine fingerprint (BIOS UUID + OS install ID)
-  + Your clauth password
-  → HMAC-SHA256 token + 5-min timestamp window
-  → Supabase Edge Function validates
-  → Returns AES-256 encrypted key from Vault
-```
-
-Nothing stored locally. Password never persisted. Machine hash is one-way only.
-
----
-
-## Releasing a New Version (maintainers)
-
-```bash
-# 1. Bump version in package.json
-# 2. Commit and tag
-git tag v0.1.1
-git push --tags
-# GitHub Actions publishes automatically via Trusted Publishing
-```
-
----
-
-> Life before Profits. — LIFEAI / PRT
->
-> ☕ [Support this project](https://github.com/sponsors/DaveLadouceur)
+# @lifeaitools/clauth
+
+Hardware-bound credential vault for the LIFEAI stack. Your machine is the second factor. Keys live in Supabase Vault (AES-256). Nothing sensitive ever touches a config file.
+
+---
+
+## Install
+
+```bash
+npm install -g @lifeaitools/clauth
+```
+
+Then provision your Supabase project:
+
+```bash
+clauth install
+```
+
+That's it. `clauth install` handles everything:
+- Creates all database tables
+- Deploys the `auth-vault` Edge Function
+- Generates HMAC salt + bootstrap token
+- Tests the connection end-to-end
+- Installs the Claude skill
+
+At the end it prints a **bootstrap token** — save it for the next step.
+
+---
+
+## After Install — Register Your Machine
+
+```bash
+clauth setup
+```
+
+Prompts for: machine label, password, bootstrap token (from `clauth install`).
+
+Then verify:
+```bash
+clauth test      # → PASS
+clauth status    # → 12 services, all NO KEY
+```
+
+---
+
+## What clauth install asks for
+
+Two things from Supabase:
+
+**1. Project ref** — the last segment of your Supabase project URL:
+`https://supabase.com/dashboard/project/` **`your-ref-here`**
+
+**2. Personal Access Token (PAT)**:
+`https://supabase.com/dashboard/account/tokens` → Generate new token
+
+> This is **not** your anon key or service_role key — it is your account-level token.
+
+---
+
+## Writing Your First Key
+
+```bash
+clauth write key github     # prompts for value
+clauth enable github
+clauth get github
+```
+
+---
+
+## Command Reference
+
+```
+clauth install              Provision Supabase + install Claude skill
+clauth setup                Register this machine with the vault
+clauth status               All services + state
+clauth test                 Verify connection
+
+clauth write key <service>  Store a credential
+clauth write pw             Change password
+clauth enable <svc|all>     Activate service
+clauth disable <svc|all>    Suspend service
+clauth get <service>        Retrieve a key
+
+clauth add service <n>      Register new service
+clauth remove service <n>   Remove service
+clauth revoke <svc|all>     Delete key (destructive)
+```
+
+## Built-in Services
+
+`github` `supabase-anon` `supabase-service` `supabase-db`
+`vercel` `namecheap` `neo4j` `anthropic`
+`r2` `r2-bucket` `cloudflare` `rocketreach`
+
+---
+
+## How It Works
+
+```
+Machine fingerprint (BIOS UUID + OS install ID)
+  + Your clauth password
+  → HMAC-SHA256 token + 5-min timestamp window
+  → Supabase Edge Function validates
+  → Returns AES-256 encrypted key from Vault
+```
+
+Nothing stored locally. Password never persisted. Machine hash is one-way only.
+
+---
+
+## Releasing a New Version (maintainers)
+
+```bash
+# 1. Bump version in package.json
+# 2. Commit and tag
+git tag v0.1.1
+git push --tags
+# GitHub Actions publishes automatically via Trusted Publishing
+```
+
+---
+
+> Life before Profits. — LIFEAI / PRT
+>
+> ☕ [Support this project](https://github.com/sponsors/DaveLadouceur)