gemstone-nexus · Phase 6
DOC — Practitioner Vendor-Key Onboarding & Secure Storage
Metadata
| id | doc_id | title | category | source_path | summary | content_hash | indexed_at |
|---|---|---|---|---|---|---|---|
| 18 | DOC-WORKER-KEY-ONBOARDING | DOC — Practitioner Vendor-Key Onboarding & Secure Storage | reference | DevResources/docs/DOC-Worker-Key-Onboarding.md | Didymus live worker execution (Cursor, Claude, Gemini, optional Ollama) runs against **your** vendor accounts. This playbook explains how a practitioner connects each worker by providing an API key/token, how GemStone stores those keys securely, and how to rotate or remove them. It complements `DIDYMUS-PLAYBOOK.md` (operator/host provisioning) and `DIDYMUS-ARCH-01.md` (architecture). The permanent human-approval invariant is unchanged: connecting a key never lets a task run … | ae828a7c4d45371f3a1968ef9c79d1bc6e5693e5 | 2026-07-22 18:33:18 |
Content
# DOC — Practitioner Vendor-Key Onboarding & Secure Storage
*Guided onboarding for connecting Didymus AI workers with your own vendor keys*
**Initiative:** GemStone · **Version:** v2.0 (Rewrite) · **Status:** Implemented · **Date:** 2026-07-21
## 1. Purpose
Didymus live worker execution (Cursor, Claude, Gemini, optional Ollama) runs
against **your** vendor accounts. This playbook explains how a practitioner
connects each worker by providing an API key/token, how GemStone stores those
keys securely, and how to rotate or remove them. It complements
`DIDYMUS-PLAYBOOK.md` (operator/host provisioning) and `DIDYMUS-ARCH-01.md`
(architecture). The permanent human-approval invariant is unchanged: connecting
a key never lets a task run without explicit approval.
## 2. What you need per worker
| Worker | Credential | Where to generate |
| --- | --- | --- |
| **Cursor** | API key (Cloud Agents) | Cursor Dashboard → Integrations / API Keys |
| **Claude** | Anthropic API key (`sk-ant-...`) | Anthropic Console → API Keys |
| **Gemini** | Google AI / Gemini API key | Google AI Studio → API keys |
| **Ollama** (optional) | Endpoint URL (not a secret) | e.g. `http://gemstone-ollama:11434` |
You only need keys for the workers you intend to use. A worker with no key runs
in **simulated** mode (safe no-op result) so gates still pass.
## 3. Guided onboarding (in the app)
1. Sign in (see §6). You must be authenticated so the key is bound to your
practitioner + org.
2. Open **Settings → Connect AI Workers** (`/app/onboarding/workers`).
3. Each worker shows a card with a **Connected / Not connected** status and, when
connected, a masked hint (last 4 characters only).
4. Paste the key and select **Connect**. The value is sent once over TLS to
`POST /api/didymus/workers/{worker_id}/credential` and is **never returned**
by the API afterwards.
5. To replace a key, paste a new value and Connect again (overwrites). To remove
a key, select **Disconnect** (`DELETE /api/didymus/workers/{worker_id}/credential`).
Status endpoint (no secrets): `GET /api/didymus/workers/credentials` returns each
worker's `configured` flag, `source` (`vault` / `env` / null), and `last4`.
## 4. How keys are stored securely
- **Encrypted at rest.** Each key is sealed with **AES-256-GCM** before it touches
the database. Only ciphertext is stored in the `worker_credentials` table.
- **Master key from the secrets tier.** Encryption uses `WORKER_SECRETS_KEY`
(base64 of 32 bytes) loaded from AWS Secrets Manager (`DATARIGHT_DEV_SECRETS`)
via the standard bootstrap (`aws-secrets.md`). The key is **never** in the repo.
- **Fail closed.** If `WORKER_SECRETS_KEY` is absent, the vault refuses to store
or use any key (HTTP 503) rather than persisting plaintext.
- **Identity-bound.** The GCM associated data binds each ciphertext to your
`org_id`, `practitioner_id`, and `worker_id`; a blob cannot be reused under a
different identity.
- **Write-only + scoped.** The API never returns raw keys; rows are
org-isolated (RLS) and unique per `(practitioner, worker)`.
- **Never in transit to workers as data.** Keys are decrypted in-process only at
execution time and are never logged or placed in Didymus task payloads or MCP
arguments (`DIDYMUS-ARCH-01` §9). Vendor calls pass keys via request headers,
never query strings.
### Resolution order at execution
1. Your **per-practitioner** key from the encrypted vault.
2. Host **environment fallback** (`DIDYMUS_WORKER_*` / `GEMINI_API_KEY`) for
sovereign/backward-compat hosts.
3. Neither present → **simulated** execution.
## 5. Rotation & removal
1. Generate a new key at the vendor.
2. In the app, paste the new key and **Connect** (overwrites the stored value).
3. Revoke the old key at the vendor.
4. Confirm the worker still shows **Connected** with the new `last4`.
5. To offboard entirely, **Disconnect** the worker; the ciphertext row is deleted.
Host-level keys (env) rotate per `DIDYMUS-PLAYBOOK.md` §7.
## 6. Login prerequisite
Per-practitioner keys require an authenticated session. GemStone issues a local
JWT (email/password) whose claims (`org_id`, `practitioner_id`, `role`) scope all
interactions; this runs in parallel with the deferred Auth0 tenant and shares the
same claim shape. Set `AUTH_ENABLED=true` to enforce token-derived tenancy; see
`DOC-Auth0-Provisioning.md` for the eventual Auth0 swap-in.
## 7. Operator checklist
| Check | Pass criteria |
| --- | --- |
| Master key present | `WORKER_SECRETS_KEY` in `DATARIGHT_DEV_SECRETS`; `GET /api/didymus/workers/credentials` → `vault_available: true` |
| Store round-trip | Connect a test key → `configured: true`, correct `last4`; raw value never returned |
| Fail-closed | With `WORKER_SECRETS_KEY` unset, `POST .../credential` returns 503 |
| Live vs simulated | With a valid key, execute reports `mode: live`; without, `mode: simulated` |
| No leakage | Keys absent from logs, task payloads, and error messages |
## 8. Out of scope
- Storing keys in git, Capacitor bundled assets, or Didymus task JSON.
- Autonomous execution without human approval.
- Returning raw key values from any endpoint.
---
NEXTECH Business Technology Management LLC · nex-tech.biz · (941) 499-5505