# 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 |
