Developer Setup Bridge

What it is

When a developer sets up Omniscio on a fresh machine, the setup script often needs something only the app can reach: the signed-in developer's cloud session. A command-line script cannot read that session, so this bridge fills the gap — the app acts on the developer's behalf and hands back just the result.

The design is deliberate about trust: the developer's ID token is read in the main process, attached as a header on one outbound request, and never logged, never stored, and never handed back. The app does the privileged work itself and returns only what was produced.

Where to find it

This is a developer-facing surface, not something an everyday user opens. It is used during first-time developer onboarding, typically alongside the app's setup views. The two bridge actions are "seed my secrets vault with the dev sign-in credentials" and "mint me a cloud test key", each performed by the app on the signed-in developer's behalf.

How it behaves

The credentials action fetches the shared dev sign-in credential bundle — a set of secrets keyed by vault name, using the same names the repo's secret manifest already owns, so secrets:pull can seed the vault with no translation table. It carries no credential from the caller either way: the app reads the signed-in developer's ID token in the main process, attaches it to one outbound request, and returns only the bundle. The fetch is idempotent — call it as often as you like; the server's per-developer daily quota is the bound. An empty or malformed bundle is reported as unavailable rather than as a success with nothing to install.

The cloud-test-key action mints an amc_dtk_ product key for the signed-in developer. The mint itself is not idempotent: every call creates a new key, spends one of the account's ten active-key slots, and the plaintext comes back exactly once (only its hash is stored), so a lost response means that slot is gone. The route protects the common accident — a caller that sends X-Client-Request-Id has its first result replayed verbatim for the cache's lifetime instead of a second mint, which covers a dropped-connection re-send or a script re-run. Only a successful mint is remembered, the replayed plaintext is held in memory only and never written to disk, and a caller that sends no header still mints a fresh key.

Both actions require the machine's full-trust credential and a signed-in developer. If nobody is signed in, the request is unprocessable (a 422, not a 401 — the caller's own credential was fine; it is the app's state that is wrong). If the account is not on the developer list, or does not have the plan or free slot, it is forbidden; and if the supporting service cannot answer, it is unavailable.

For agents

• The bridge is exposed as CLI routes under src/main/services/cli/route-families/dev-setup.routes.ts (POST /dev-setup/credentials, POST /dev-setup/cloud-test-key), served by src/main/services/cli/cli-server-dev-setup-routes.ts.
• The client-side bridge is src/main/services/dev-setup/dev-setup-bridge.ts; its settings shape is src/shared/developer-setup-settings.ts.
• Both routes demand the global full-trust token only: a scoped agent token is refused (401).
• The cloud-test-key call runs against saas-api with signed-out 422, plan/ten-key-cap 403, and 503 when the service cannot answer. Its base URL comes from the one broker-origin resolver (resolveBrokerBaseUrl), which carries a built-in production default — no environment variable is needed. Only the http/loopback override paths are refused as misconfigured.
• The F189 replay cache is deliberately in-memory, never the persisted cli_pending_actions path: the replayed value contains the key plaintext, so it must not reach disk.

Related

• dev-pipeline.md — the development pipeline a developer sets up to work in.
• first-time-setup.md — the first-run experience this bridge supports.
• setup-assistant-card.md — the card that guides setup after onboarding.
• plugin-dev-mode.md — the related developer mode for building plugins.