# CAuth

Central authentication, user accounts, usage accounting, and billing for the Adeno platform.

CAuth is the shared trust fabric for Adeno. Every service — Keryx, Kairos, Eunomia, APS, Arachne, and more — delegates login, account management, and billing to CAuth instead of implementing its own identity system.

- **Host:** `https://adeno.ltd/cauth` (also mounted on product domains as needed)
- **Token model:** JWT transtokens signed with `CAUTH_SECRET_KEY` (HS256)

## Token model

| Token | Lifetime | Purpose |
|---|---|---|
| `transtoken` | ~15 minutes | Short-lived per-request auth across services |
| `anontoken` | ~2 days | Anonymous/trial flows |

Transtokens are JWTs with claims `sub`, `iat`, `exp`, `type`, and `jti`. Services validate them with the shared `CAUTH_SECRET_KEY` using HS256.

```http
Authorization: Bearer <transtoken>
```

User-facing services obtain a transtoken via login or registration; internal services can also use shared secrets for backend-to-backend calls.

## Security features

- Password hashing with PBKDF2-HMAC-SHA256
- Fernet encryption for server-side sensitive fields
- Itemized pricing support for downstream service usage

## Core endpoints

All endpoints are JSON in / JSON out. Errors return an HTTP status code plus a body with an `error` key.

### Authentication & accounts

| Method | Path | Description |
|--------|------|-------------|
| POST | `/cauth/auth` | Login; returns a fresh transtoken |
| POST | `/cauth/register` | Register a new account |
| POST | `/cauth/verify-code` | Submit an email verification code |
| POST | `/cauth/resend-code` | Resend a verification code |
| GET | `/cauth/chkverify` | Check verification status |
| GET | `/cauth/me` | Current user profile from a bearer token |
| GET | `/cauth/userinfo` | User info lookup |
| DELETE | `/cauth/account` | Delete the account (GDPR) |
| GET | `/cauth/account/data` | Export account data (GDPR) |
| GET/PUT | `/cauth/account/preferences` | Read/update preferences |

Example:

```bash
curl -X POST https://adeno.ltd/cauth/auth \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "..."}'
```

A successful response contains a token to attach to subsequent service calls:

```json
{ "token": "<transtoken>", "uid": 123 }
```

### Usage & credits

| Method | Path | Description |
|--------|------|-------------|
| POST | `/cauth/account/usage/authorize` | Authorize an operation before it runs |
| POST | `/cauth/account/usage/record` | Record itemized usage against a user |
| GET | `/cauth/account/usage` | Usage summary |
| GET | `/cauth/account/usage/itemized` | Itemized usage detail |
| GET | `/cauth/account/credits` | Current credit balance |
| POST | `/cauth/account/billing/purchase-bundle` | Buy a prepaid credit bundle |

CAuth can authorize operations before they run; usage is priced per service-specific unit and billed through prepaid bundles or subscriptions.

### Billing & subscriptions

| Method | Path | Description |
|--------|------|-------------|
| GET | `/cauth/pricing` | Public unit pricing |
| GET | `/cauth/bundles` | Available credit bundles |
| GET | `/cauth/subscriptions` | Subscription plans |
| GET | `/cauth/account/billing` | Billing overview |
| POST | `/cauth/account/billing/portal` | Stripe customer portal session |
| GET | `/cauth/account/subscription` | Current subscription state |
| POST | `/cauth/account/billing/mobile-subscription` | Google Play subscription verification |
| POST | `/cauth/webhooks/stripe` | Stripe webhook receiver |

### API keys & services

| Method | Path | Description |
|--------|------|-------------|
| GET/POST/DELETE | `/cauth/account/apikeys` | Manage personal API keys |
| POST | `/cauth/services/request` | Request access for a new service |
| POST | `/cauth/service/verify` | Verify a service token server-to-server |
| GET/POST | `/cauth/admin/service-tokens` | Admin: issue/list service tokens |
| DELETE | `/cauth/admin/service-tokens/<id>` | Admin: revoke a service token |

The `/cauth/service/verify` endpoint is how downstream Adeno services validate tokens presented by clients without holding user context themselves.

### Enterprise

| Method | Path | Description |
|--------|------|-------------|
| GET/POST | `/cauth/enterprise/workspace` | Workspace configuration |
| GET | `/cauth/enterprise/members` | List workspace members |
| POST | `/cauth/enterprise/members/invite` | Invite a member |
| GET | `/cauth/enterprise/audit-log` | Audit log stream |
| GET/POST | `/cauth/enterprise/channels` | Notification channels (Jira/GitHub/Slack integrations) |

### Health

| Method | Path | Description |
|--------|------|-------------|
| GET | `/health` | Liveness probe |
| GET | `/cauth/health` | Service health + version info |

## Email relay

Downstream services can send transactional email through CAuth's relay rather than holding SMTP credentials:

| Method | Path | Description |
|--------|------|-------------|
| POST | `/cauth/email/relay` | Send email on behalf of an authenticated service |
| GET | `/cauth/admin/email/log` | Admin: delivery log |
| GET/POST/DELETE | `/cauth/admin/email/addresses` | Admin: allowlist management |

## Integrating a service with CAuth

1. Register your service (`POST /cauth/services/request`) or seed it as an internal client.
2. Accept CAuth tokens from users: validate the JWT with `CAUTH_SECRET_KEY` (HS256), checking `exp`, `type`, and audience.
3. For backend validation of client-presented tokens, call `POST /cauth/service/verify`.
4. Before metered operations, call `POST /cauth/account/usage/authorize`; after completion call `POST /cauth/account/usage/record` with itemized units.
5. Propagate base URLs via environment variables (e.g., `CAUTH_URL`) pointing at the same external FQDN used by browsers.