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