@@ -15,0 +164,4 @@
+
+- **owner** — Created the org. Full access. Cannot be removed. One per org.
+- **admin** — Manage users, entitlements, and all data. Multiple per org.
+- **member** — Standard data access (read/write records, entities). No user or entitlement management.

@@ -15,0 +182,4 @@
+}
+```
+
+`method` is `"email"` or `"sms"`. If `"sms"`, `contact` is a phone number (E.164 format).

@@ -15,0 +147,4 @@
+}
+```
+
+**Refresh token** (long-lived, 30 days):

@@ -36,0 +45,4 @@
+- **Pros**: Simple, cheap, full control, great for SQLite (local disk I/O)
+- **Cons**: Manual scaling, single point of failure unless you add redundancy
+
+#### Option B: Container Platform (Fly.io, Railway, etc.)

@@ -36,0 +54,4 @@
+- **Pros**: Easier deploys, built-in health checks, can scale to multiple regions
+- **Cons**: Persistent volume adds complexity with SQLite, vendor lock-in, higher cost at scale
+
+#### Option C: Self-Hosted

@@ -36,0 +68,4 @@
+- `karriba.com` — Landing page (Cloudflare Workers, already deployed)
+- `demo.karriba.com` — Web demo (Cloudflare Workers, already deployed)
+- `api.karriba.com` — Backend API (Go server)
+- `admin.karriba.com` — Admin portal (spec #13)

@@ -44,0 +130,4 @@
+
+- [ ] Choose hosting option (A, B, or C)
+- [ ] Provision server / container / hardware
+- [ ] Set up reverse proxy with TLS (Caddy or platform-managed)

@@ -15,0 +267,4 @@
+
+#### `POST /v1/orgs`
+
+Create a new organization. The authenticated user becomes the sys-admin. Provisions a new tenant DB.

@@ -15,0 +384,4 @@
+
+#### `PATCH /v1/orgs/:orgId/users/:userId`
+
+Update a user's role. Sys-admin cannot be demoted. Only `sys-admin` can promote to `manager`.

@@ -15,0 +449,4 @@
+
+**Side effect:** Updated entitlements are synced to the tenant DB on next sync cycle (or immediately if the device is online).
+
+**Error codes:** `INVALID_MODULE`, `ENHANCEMENT_REQUIRES_STANDALONE`

@@ -15,0 +484,4 @@
+- `id` TEXT PRIMARY KEY (UUIDv7)
+- `email` TEXT (nullable, unique)
+- `phone` TEXT (nullable, unique)
+- `org_id` TEXT REFERENCES organizations(id)

@@ -15,0 +531,4 @@
+
+### Sys-Admin Role
+
+Separate from manager to prevent lockout. Every org has exactly one sys-admin (the creator). Sys-admin transfer can be added in the future, but is out of scope for now.

@@ -15,0 +472,4 @@
+
+### Tables
+
+**organizations**

@@ -15,0 +129,4 @@
+### OTP Flow
+
+1. Client sends email address
+2. Server generates a 6-digit OTP, stores it with expiry (5 minutes), sends via email

@@ -15,0 +20,4 @@
+
+- **Language**: Go
+- **Router**: `net/http` with `chi` (lightweight, stdlib-compatible)
+- **Database driver**: `github.com/mattn/go-sqlite3` (CGo) or `modernc.org/sqlite` (pure Go)

@@ -15,0 +163,4 @@
+
+The `jti` claim is the primary key of the corresponding `refresh_token` row. It guarantees uniqueness across tokens issued in the same second and gives the server an O(1) lookup path during rotation and reuse detection.
+
+Refresh tokens are stored in the Admin DB and can be revoked. Each time a refresh token is used to obtain a new access token, a **new refresh token** is also issued and the old one is revoked. This creates a sliding window — as long as the user is active within 90 days, their session continues indefinitely. If inactive for 90 days, the token expires and they must re-authenticate via OTP.

@@ -15,0 +748,4 @@
+
+### Threat: JWT signing-key compromise
+
+**Mitigation**: the access-token signing secret is loaded from environment configuration and rotated by deploying a new key. To support rotation without invalidating active sessions, the JWT carries a `kid` header and the server holds a small key set (current + previous). On rotation, the previous key remains valid for one access-token TTL (15 min) before being removed. Refresh tokens carry their `kid` too. This is a Phase 3 hardening task; the initial implementation can ship with a single static key and add rotation later.

@@ -15,0 +678,4 @@
+
+Orgs are archived (soft-deleted via `archived_at`) rather than permanently deleted. Archiving disables access but preserves all data and the tenant DB. This avoids destructive operations and allows data recovery. Hard delete may be added later with a grace period and explicit confirmation flow.
+
+**Enforcement**: the auth middleware treats members of an archived org as if they had no membership. Their access token still authenticates them, but `org_id` and `role` are not populated, so every org-scoped endpoint returns `403 FORBIDDEN`. Sys-admins continue to have full read access to archived orgs (e.g., to inspect or unarchive them). The `GET /v1/orgs/:orgId` response includes `archived_at` so clients can surface the disabled state to users.

@@ -15,0 +175,4 @@
+  - Creates organizations and assigns the initial manager
+  - Manages organization entitlement assignments
+  - Manages organization archival
+  - Has **no access** to organization data or users

@@ -44,0 +143,4 @@
+
+### Phase 2: Database Setup
+
+- [ ] Choose multi-tenant isolation model (Option 1 or 2)