@alvera-ai/platform-sdk 0.10.0-rc.9 → 0.11.0

package/.agent/account_management.md

@@ -0,0 +1,456 @@
+# Account management
+
+Every SDK call resolves against a **trust boundary** with three
+coordinates:
+
+```
+   who          User (human)  OR  ApiKey / PAT (agent)
+   where        Tenant   (+ optional Datalake)
+   what         Role assumed by this session
+```
+
+Account management is how those three coordinates are established
+and reasoned about. This page covers six SDK namespaces that work
+together:
+
+| Namespace          | Methods                                       |
+|--------------------|-----------------------------------------------|
+| `api.auth`         | `signUp`                                      |
+| `api.admin`        | `confirmUser` — **dev fixture only**          |
+| `api.sessions`     | `verify`                                      |
+| `api.tenants`      | `create`, `list`                              |
+| `api.invitations`  | `create`, `list`, `accept`                    |
+| `api.ping`         | unauthenticated health check (`GET /api/ping`) |
+| `createSession`    | mint a Bearer (top-level helper, not a namespace) |
+| `revokeSession`    | revoke the current Bearer (top-level helper, parallel to `createSession`) |
+
+Two top-level concerns sit above the surface:
+
+1. **Who is calling** — a human (Bearer) or an agent (API key / PAT)
+2. **What that caller can do** — gated by role + by credential type
+
+Both branches differ in lifecycle, capability, and whether they
+can be created programmatically. See §3 "Access control".
+
+## 1. Identity — humans
+
+Humans authenticate by exchanging email+password for a Bearer.
+The Bearer carries the trust-boundary coordinates and travels in
+the `Authorization: Bearer <token>` header on every subsequent
+request.
+
+### Three Bearer scopes
+
+`createSession` mints a Bearer at one of three scopes:
+
+```typescript
+import { createSession } from '@alvera-ai/platform-sdk'
+
+// root admin (no tenant) — for confirmUser, signUp on behalf of, etc.
+const root = await createSession({
+  baseUrl, email: rootEmail, password: rootPassword,
+})
+
+// tenantless — authenticated user who has not picked a tenant yet
+const tenantless = await createSession({
+  baseUrl, email, password,
+})
+// tenantless.tenant === null
+
+// tenant-scoped — the canonical Bearer for tenant operations
+const tenant = await createSession({
+  baseUrl, email, password, tenantSlug,
+})
+// tenant.tenant.slug === tenantSlug
+// tenant.role.name   === 'tenant_admin' | 'member' | ...
+```
+
+See `AGENTS.md` "Sessions come in three scopes" for when each is
+appropriate. Tenantless is a transient state used once: to create
+a tenant (creator path) or accept an invitation (invitee path).
+
+### Explicit teardown — `revokeSession`
+
+The inverse of `createSession`. Revokes the current Bearer on
+the server and short-circuits the local `api` instance — every
+subsequent request through the same instance returns 401:
+
+```typescript
+import { revokeSession } from '@alvera-ai/platform-sdk'
+
+await revokeSession()              // DELETE /api/v1/sessions
+// api.* calls now return 401
+```
+
+Use this for graceful sign-out flows in long-running consumers
+(CLIs, daemons). Letting the Bearer reach `expires_at` is fine
+for short-lived scripts, but explicit revocation removes the
+token server-side immediately and reduces the window of misuse
+if the token leaks.
+
+### Liveness check — `api.ping`
+
+A no-auth health probe used by load balancers, smoke tests, and
+SDK consumer setup checks. The response confirms the platform
+is reachable and reports the build version + database
+connectivity:
+
+```typescript
+const { data } = await api.ping()
+// data.status           === 'ok'
+// data.version          — platform build version
+// data.database_status  === 'connected' | 'disconnected'
+// data.timestamp        — ISO 8601
+```
+
+`api.ping` works on any api instance regardless of session
+state — useful as the first call in tests to detect a stale
+local server before authentication failures muddy the diagnostic.
+
+### Sign up
+
+```typescript
+const { data: user } = await rootApi.auth.signUp({
+  email: 'sarah@example.com',
+  password: '...',
+  first_name: 'Sarah',
+  last_name: 'Mitchell',
+})
+// user.id is a UUID; user.confirmed_at is null
+```
+
+A newly signed-up user CANNOT sign in until confirmed. The
+production confirmation path is **email-driven**: the platform
+sends a confirmation email; the user clicks a link; the platform
+records `confirmed_at`. **This email flow is not exposed in the
+SDK** — it's a browser+email round-trip outside the API surface.
+
+### `api.admin.confirmUser` is a dev fixture, not a production API
+
+```typescript
+// DEV / VITEST ONLY — do NOT call from production consumer code
+await rootApi.admin.confirmUser(userId)
+```
+
+`api.admin.confirmUser` bypasses the email-confirmation gate. It
+exists so integration tests can simulate a confirmed user without
+a real inbox round-trip. Production consumers MUST NOT use it:
+
+- It requires a root Bearer (impossible to obtain in customer
+  environments).
+- The email gate exists to prove a real person controls the
+  inbox — programmatically bypassing it defeats the human-gate
+  invariant (see §3).
+- Future platform releases may restrict it further or remove it
+  from the public surface entirely.
+
+The method ships in the typed client to support integration-test
+fixtures; treat it as a test-only helper, not a production API.
+
+### `api.sessions.verify` — "who am I, where, with what role"
+
+```typescript
+const { data: ctx } = await api.sessions.verify()
+// ctx.tenant?.slug — current tenant (null if tenantless)
+// ctx.role?.name   — role assumed in this session
+// ctx.user         — { id, first_name, last_name, ... }
+```
+
+Use cases:
+
+1. **Pre-flight check** before performing role-gated operations —
+   confirm the Bearer is tenant-scoped + has the expected role.
+2. **Bearer validity probe** — if the call throws, the Bearer is
+   expired or revoked; re-mint via `createSession`.
+3. **Cached-Bearer rehydration** — when persisting Bearers across
+   processes (integration tests, CLI sessions), verify before
+   reusing.
+
+For pattern (3), call `verify()` on the stored Bearer and only
+re-mint via `createSession` if the verify call fails.
+
+## 2. Tenant
+
+A **tenant** is the top-level data sovereignty boundary. Tenants
+own datalakes; datalakes own everything else. A user can belong
+to many tenants; a Bearer is scoped to exactly one.
+
+### Two paths to a tenant-scoped Bearer
+
+```
+  ┌─ creator path ─┐                ┌─ invitee path ─┐
+  │                                 │
+  api.auth.signUp                   api.auth.signUp
+  │                                 │
+  api.admin.confirmUser*            api.admin.confirmUser*   (* production: email link)
+  │                                 │
+  createSession (no tenantSlug)     createSession (no tenantSlug)
+  │                                 │
+  api.tenants.create                api.invitations.list → .accept
+  │                                 │
+  createSession ({ tenantSlug })    createSession ({ tenantSlug })
+  ▼                                 ▼
+        ┌──── tenant-scoped Bearer ────┐
+```
+
+Both paths converge on a tenant-scoped Bearer. The creator
+becomes `tenant_admin` of the new tenant; the invitee assumes the
+role specified in their invitation.
+
+### `api.tenants.create`
+
+```typescript
+const { data } = await tenantlessApi.tenants.create({
+  name: 'Acme Health',
+})
+// data.tenant.id, data.tenant.slug  — server-derived
+// data.session_token                — see "Gotchas" below
+```
+
+The slug is server-derived from `name` per the universal slug
+rules (see `type_naming.md` "Never pre-compute the slug
+client-side"). Use the returned slug for downstream calls.
+
+**Gotcha**: the response carries a `session_token` field, but this
+is an *incidental* token — do not treat it as a freshly minted
+tenant-scoped Bearer. The authoritative pattern is to call
+`createSession({ ..., tenantSlug })` after `tenants.create`. This
+gives a fresh Bearer with all role + tenant claims correctly
+populated.
+
+### `api.tenants.list`
+
+```typescript
+const { data: tenants } = await api.tenants.list()
+// tenants.data: TenantResponse[] — every tenant the current Bearer can see
+```
+
+A root Bearer sees every tenant; a tenant-scoped Bearer typically
+sees only its own. Use this for tenant pickers in apps where a
+user belongs to multiple tenants.
+
+## 3. Access control
+
+The platform separates **who you are** from **what you can do**.
+Identity (§1) proves the first; this section covers the second.
+
+### Roles — two vocabularies, one consumer
+
+The platform exposes two distinct role vocabularies on the wire,
+each rooted in a different schema. Knowing which surface
+demands which vocabulary is the difference between a clean
+invite and a 422.
+
+#### Vocabulary A: Invitation enum (3 values)
+
+What you SUBMIT when creating an invitation. The
+`InvitationRequest.role` field is a closed 3-value enum:
+
+| Invitation `role` | Result on accept                       |
+|-------------------|----------------------------------------|
+| `'member'`        | Standard tenant user                   |
+| `'researcher'`    | Tokenized-only access; blocked from regulated schema |
+| `'admin'`         | Full tenant management                 |
+
+```typescript
+const { data: invite } = await api.invitations.create(tenantSlug, {
+  email: 'emma@example.com',
+  role: 'admin',                  // NOT 'tenant_admin' — that's the role-name vocab
+})
+```
+
+Passing any value outside this 3-set returns a 422 on `/role`.
+
+#### Vocabulary B: Role-record names (what `session.role.name` carries)
+
+What you READ from a tenant-scoped Bearer's role record. The
+session carries a role-record name string that's distinct from
+the invitation enum:
+
+| `session.role.name`     | Scope                              | Source vocab |
+|-------------------------|------------------------------------|--------------|
+| `'tenant_admin'`        | Full tenant management             | invitation `'admin'`  |
+| `'member'`              | Standard tenant user               | invitation `'member'` |
+| `'tenant_api'`          | Programmatic tenant access (most API keys) | provisioned, not invited |
+| `'datalake_admin'`      | Full datalake management (requires `datalake_id` on session) | console-mediated |
+| `'researcher'`          | Tokenized-only datalake access     | invitation `'researcher'` |
+| `'datalake_api'`        | Programmatic datalake access       | provisioned, not invited |
+
+```typescript
+const session = await createSession({ baseUrl, email, password, tenantSlug })
+// session.role.name === 'tenant_admin'   if accepted from a role: 'admin' invitation
+// session.role.name === 'member'         if accepted from a role: 'member' invitation
+// session.role.name === 'researcher'     if accepted from a role: 'researcher' invitation
+```
+
+The asymmetry is deliberate but easy to trip over: the
+invitation enum value `'admin'` becomes the role-record name
+`'tenant_admin'`. The `'member'` and `'researcher'` values
+carry through unchanged.
+
+#### Why two vocabularies
+
+The Invitation/Membership schema (Vocabulary A) is the
+coarse-grained role assignment surfaced at invite time. The
+Role-record system (Vocabulary B) is the fine-grained policy
+entity that drives row-level access and permission checks at every
+request. They co-exist because the invitation captures the
+caller's intent ("admin-tier user"), while the role record
+captures the platform's enforcement vocabulary
+("tenant-scoped admin role").
+
+Datalake-scoped role records (`datalake_admin`, `researcher`
+when used at datalake scope, `datalake_api`) require the
+session to carry a `datalake_id` in addition to a `tenant_id`.
+Most SDK consumers stay at tenant scope; datalake-scoped
+sessions appear in console-mediated flows and are uncommon in
+SDK-consumer code.
+
+Reserved roles (`platform_admin`, `system`, `system_api`,
+`bot_*`) bypass tenant-based access isolation and are
+provisioned only by the platform itself — they never appear on
+consumer-minted sessions or invitations and are out of scope
+for SDK consumers.
+
+### Inviting humans into a tenant
+
+```typescript
+// As tenant_admin
+const { data: invite } = await api.invitations.create(tenantSlug, {
+  email: 'emma@example.com',
+  role: 'member',
+})
+
+// As the invitee (tenantless Bearer)
+const { data: invites } = await tenantlessApi.invitations.list()
+const mine = invites.data.find(i => i.tenant.slug === tenantSlug)
+const { data: membership } = await tenantlessApi.invitations.accept(mine.id)
+
+// Then mint a tenant-scoped Bearer
+const session = await createSession({ baseUrl, email, password, tenantSlug })
+// session.role.name === 'member'
+```
+
+The duplicate-invite envelope carries `detail` containing
+"already invited" — see `errors.md` for the canonical 422 shape.
+Treat it as a benign idempotency signal on retry.
+
+### Agent authentication — two-tier model
+
+Agents (programmatic callers) authenticate via two distinct
+credential types with very different capability profiles:
+
+| Credential type | Capability                | Created programmatically?    |
+|-----------------|---------------------------|------------------------------|
+| **API key**     | Write-only, very limited  | **Yes** — safe by scope      |
+| **PAT** (delegated) | Full per delegating human's role | **No** — human-gated     |
+
+The rule: **anything that gives an agent broad access is gated by
+a human**. Specifically:
+
+- **API keys** can be minted programmatically because their
+  capability is intrinsically narrow (write-only, scoped to
+  specific endpoints). A leaked API key can deposit data; it
+  cannot exfiltrate it.
+- **PATs** delegate a human's full role to an agent. Because the
+  resulting agent-Bearer has the same capability as the human,
+  PAT issuance MUST require human consent at mint time — the
+  human is the gate.
+- **User signup + confirmation** is human-gated (email flow) for
+  the same reason: a programmatically-created confirmed user
+  could mint Bearers without any human in the loop. The
+  email-link confirmation step proves a real person controls the
+  inbox.
+
+### What the SDK exposes for agent auth
+
+**Today the SDK exposes neither credential-lifecycle surface.**
+API key and PAT minting / listing / revocation happen via
+operator-mediated consoles, not via SDK methods. The absence
+of these lifecycle methods from the SDK is the contract.
+
+When the SDK does need to *authenticate as* an agent (uncommon in
+fixture code; common in production agent runtimes), the credential
+travels in the appropriate request header — see the credentials
+your operator provides for the exact header convention. A session
+Bearer minted via `createSession` is also accepted for any
+SDK-driven agent workflow.
+
+## 4. Lifecycle
+
+Bearers and credentials have distinct lifecycles. Summary:
+
+| Credential | Expires?                              | Revocation        |
+|------------|---------------------------------------|-------------------|
+| Bearer (session) | Yes — `expires_in` (default 24h, max 30d) | Server-side revoke |
+| API key    | No — until explicit revoke            | Operator console  |
+| PAT        | Configurable at issue time            | Operator console  |
+
+Bearer expiry surfaces as a 401 on the next call after expiry —
+re-mint via `createSession`. The SDK does NOT auto-refresh
+Bearers. For long-running agent processes, mint short-lived
+Bearers per logical unit of work rather than holding one for
+hours.
+
+## 5. Error envelopes
+
+All endpoints in this page emit the standard JSON:API envelope
+documented in `errors.md`. Common rejections:
+
+| `source.pointer` / shape                        | Cause                                        |
+|-------------------------------------------------|----------------------------------------------|
+| `/email` "has already been taken"               | `auth.signUp` with an existing email         |
+| `/password` "is too short"                      | password below minimum length                |
+| top-level 401 (no envelope)                     | Bearer missing, expired, or revoked          |
+| top-level 403 (no envelope)                     | role lacks permission for the action         |
+| `/email` "already invited"                      | duplicate `invitations.create`               |
+| `/tenant_slug` "not found"                      | tenant slug doesn't exist or invisible to Bearer |
+
+The `tenants.create` 422 is typically `/name` uniqueness — names
+must be unique platform-wide. Re-attempt with a different name or
+treat as "already exists" via `api.tenants.list` lookup.
+
+## 6. Gotchas
+
+1. **`api.admin.confirmUser` is dev-only.** Production user
+   confirmation happens via emailed link, outside the SDK. Treat
+   the SDK method as a test fixture; do not ship code that calls
+   it from a customer-facing path.
+
+2. **The `session_token` returned by `tenants.create` is
+   incidental.** Always re-mint a fresh tenant-scoped Bearer via
+   `createSession({ ..., tenantSlug })` after creating a tenant.
+   This guarantees clean role+tenant claims on the Bearer.
+
+3. **Tenantless Bearer is a transient state.** Only two
+   operations are useful with it: `tenants.create` (creator path)
+   and `invitations.list`/`.accept` (invitee path). For everything
+   else, mint a tenant-scoped Bearer first.
+
+4. **`api.sessions.verify` is the source of truth for current
+   scope.** Don't infer tenant or role from the Bearer string or
+   from the `tenants.create` response — call `verify` if you
+   need to know.
+
+5. **No SDK methods for API key or PAT lifecycle.** Credential
+   issuance is operator-console-mediated. If your agent process
+   needs an API key, the operator provisions it out-of-band; the
+   SDK consumes it but does not create it.
+
+6. **Bearers do not auto-refresh.** A long-running process holding
+   a Bearer for >24h will see 401s after expiry. Either mint
+   short-lived Bearers per logical unit of work, or wrap calls in
+   a re-mint-on-401 retry helper local to your code (the SDK does
+   not provide one).
+
+7. **Invitation acceptance is idempotent at the membership level
+   but not at the invitation level.** A second `accept(id)` call
+   on the same invitation will 422 (already accepted), but the
+   first acceptance's membership is unaffected. Treat retries via
+   the "already accepted" 422 the same as "already invited" — a
+   benign idempotency signal.
+
+8. **Multi-tenant Bearers don't exist.** A Bearer is scoped to
+   exactly one tenant at mint time. To act as multiple tenants
+   concurrently, mint one Bearer per tenant and use
+   `createIsolatedPlatformApi` (see `AGENTS.md`).