# Admin & operator onboarding

For onboarding admins and operators deploying TrustFortress / Cubie. Public-safe
overview; the exact repo runbooks (`docs/DEPLOYMENT.md`, `docs/ONBOARDING.md`,
`docs/GO_LIVE_READINESS.md`, `docs/CLOUDFLARE_FIRST_DEPLOY.md`) carry the full detail.

## 1. Choose a deployment mode

| Mode | What runs | Target | Notes |
|---|---|---|---|
| **Local / On-Prem** | `tf-server` (Axum) | any x86-64 Linux/Windows | air-gap capable; SQLite backend |
| **Data Center** | `tf-server` + eBPF XDP + AMX | Linux 5.15+ | line-rate admission at top-of-rack |
| **Kubernetes** | `tf-server` + PostgreSQL + SPIFFE + OpenFGA + Redis | cluster | production identity + authz mesh |
| **Cloud (edge)** | `tf-edge` (Wasm) | Cloudflare Workers | D1 + Workers + R2; custom domain |

The core admission logic is identical across modes; only the surrounding backends differ.

## 2. Identity and tenancy

- **Cloud:** Cloudflare Access — the Worker reads the authenticated-user email header
  (`Cf-Access-Authenticated-User-Email`); the **tenant derives from the email domain**.
- **On-Prem / Hybrid:** Keycloak or OpenBao over OIDC; local identity-key generation.
  Hybrid uses CF Access for remote users and a local OIDC provider for direct users, sharing
  an `X-TF-Verified` proxy header.
- **Model:** email is the natural key (hashed); a customer key links SSO + password auth;
  agent tokens are **one-time-use** and bound to intent + tenant, so replay is rejected and
  revocation busts the permission cache fleet-wide.

## 3. First Cloudflare deploy (edge mode)

1. **Tooling:** Node LTS, Rust (pinned by `rust-toolchain.toml`), `wrangler`.
2. **D1:** create the databases (edge DB + audit ledger), copy the IDs into `wrangler.jsonc`, apply migrations.
3. **Dispatch namespace:** create the tenant dispatch namespace (Workers for Platforms).
4. **CF Access:** create an application + policy; note the AUD tag for the authenticated MCP tier.
5. **Secrets:** set the API token (Workers Scripts / KV / D1 / R2 edit, Workers AI read); never commit secrets.
6. **Deploy:** push to `main` (the deploy workflow runs) or `npx wrangler deploy`.

Full step list: `docs/CLOUDFLARE_FIRST_DEPLOY.md`.

## 4. Turn on the AI features (resource library)

These are **opt-in and safe to deploy before provisioning** (they stay inert until configured):

- **AI Gateway** (response caching + analytics + fallback for `/api/ask`): create a gateway
  in the dashboard, set `AI_GATEWAY_ID` in `wrangler.jsonc`, redeploy. See [../AI_GATEWAY.md](../AI_GATEWAY.md).
- **AI Search** (semantic recall over the R2 library): `wrangler ai-search create
  trustfortress-library --type r2 --source trustfortress-resource-library`, add the
  `[[ai_search]]` binding (`AI_SEARCH`), redeploy. Confirm an index job runs. See [../AI_SEARCH.md](../AI_SEARCH.md).
- **Generation model:** `/api/ask` uses `@cf/google/gemma-4-26b-a4b-it` via Workers AI
  (routed through AI Gateway when configured).

## 5. Publishing artifacts to the resource library

Follow `docs/resource-library/AGENT_RUNBOOK.md`:
- Reuse the existing bucket `trustfortress-resource-library` — **never create a new bucket**.
- Use `/objects/<encoded-key>` links; prefix as `<repo>/<family>/<yyyy-mm-dd>/<file>`.
- **Secret-scan and hash every object**; split Wrangler uploads over 300 MiB.
- Verify with `/api/list` + object `HEAD` before marking a locator "live" in Git.
- After upload, refresh the D1 catalog (cron every 6h, or the protected `/api/reindex`).

## 6. Go-live checklist (abridged)

From `docs/GO_LIVE_READINESS.md` — the operator owns these:
- Local/On-Prem path verified (build, test, dashboard, stats, evidence, metrics).
- Cloudflare path verified (Worker build, public MCP smoke, browser command center, authenticated E2E).
- Release tag, D1 IDs, dispatch namespace, CF Access policy, Worker URLs set.
- Optional: AI Gateway id, MCP upstream, backend dispatch.
- Smoke tests green, then deploy.

## 7. Compliance posture (for regulated deployments)

- **EU AI Act:** classification is Annex III (biometric/PUF device identity → high-risk);
  the conformity route is Annex VII (third-party notified body). Plan 6–12 weeks lead time in
  parallel with development. The `cubie-eu-*` crates emit Annex IV technical documentation.
- **CRA:** classified Annex IV (critical — TEE + hardware-rooted attestation); requires a
  third-party conformity assessment and a CycloneDX SBOM.
- **Incident reporting:** critical-vuln acknowledgement 24h / patch 7 days; AI Act serious-
  incident reporting within 15 days; CRA/ENISA active-exploitation reporting within 24h.
- **Component vs. standalone:** if `cubie-eu` ships as a *component*, the system integrator
  carries the conformity obligation (with a component certificate); as *standalone*, the
  vendor does. Clarify this per deployment.

See the compliance docs (`docs/conformity-route.md`, `docs/cra-classification.md`,
`docs/gpai-assessment.md`) and <https://lib.trustfortress.ai/claims/eu-ai-act>.