@topolo/cli 0.13.13 → 0.13.16

package/README.md

@@ -74,27 +74,50 @@ OAuth errors, and never extends the original device-code expiry.
 ### Contexts
 
 A user can act in their personal space or any organization they belong to. Each
-context has its own credential; the CLI (and the MCP) run in the active one.
+context has its own credential. Name the one to act as with `--context <key>` or
+`TOPOLO_CONTEXT`; without a pin the CLI (and the MCP) use the stored context only
+while it is the only one signed in for the environment.
 These credentials are independent from the shared web preference: switching a
 CLI/MCP context never moves the browser session, and a web switch never changes
 an already-issued CLI/MCP token or its refresh chain.
 
 ```bash
-topolo context ls                          # personal + your orgs, and which is active
-topolo context use <organization|personal> # switch (validated + a fresh token minted server-side)
+topolo context ls                          # personal + your orgs, and which is the stored default
+topolo context use <organization|personal> # set the stored default (validated + a fresh token minted server-side)
+topolo --context org:org_acme whoami       # pin one command to one context
 ```
 
+**No implicit default context.** Once several contexts are signed in for an
+environment, every account command without `--context`/`TOPOLO_CONTEXT` refuses
+with "the context is no longer safe to assume", exactly like the
+multi-environment `--env` guard. `topolo context use` stays available for anyone
+who wants a stored default, but nothing relies on it implicitly.
+
+`topolo auth login` stores the approved sign-in under its own context key and
+never moves the stored default (`--use` opts in; the environment's first sign-in
+becomes the default). It prints which user and organization were approved. To
+re-authorise one context, name it:
+
+```bash
+topolo --env production --context org:org_acme auth login
+```
+
+If the browser approves a different user or organization, the CLI warns that
+`org:org_acme` was not renewed and exits 1.
+
 ### Wire into agent hosts
 
 ```bash
-topolo setup             # detects installed local hosts and registers the exact bundled MCP
+topolo setup             # registers the exact bundled MCP, pinned to the only signed-in context
 topolo setup --all       # configure every supported local host
 topolo doctor            # verifies auth, handshake, tool discovery, and identity
 ```
 
 The MCP reads the same credential `topolo auth login` writes — no API key to paste.
-For concurrent agents pinned to different organizations, use an exact context
-key returned by `topolo context ls --json`:
+Every registration setup writes pins `TOPOLO_ENV` and `TOPOLO_CONTEXT`. Without
+`--context`, setup pins the only signed-in context, and refuses when there are
+none or several. For each additional organization, use an exact context key
+returned by `topolo context ls --json`:
 
 ```bash
 topolo setup --name topolo-acme --context org:org_acme --env production
@@ -114,11 +137,96 @@ The local installer does not edit JetBrains AI Assistant settings or web-only
 connectors because those are managed through their own UI or remote connector
 configuration. Use the generated native MCP entry as the import source there.
 
+### Shared local MCP hub (opt-in)
+
+Every stdio registration starts its own Node process in every agent thread, so
+N threads x M pinned identities means N x M MCP processes. The shared hub runs
+**one** loopback process that serves every identity at
+`http://127.0.0.1:<port>/mcp/<name>`; Claude Code and Codex connect to it by URL.
+Plain `topolo setup` keeps the stdio path; `--shared` is opt-in.
+
+```bash
+topolo --env production setup --shared --name topolo-acme --context org:org_acme
+topolo --env staging    setup --shared --name topolo-acme-stg --context org:org_acme
+topolo setup --shared --import-stdio   # move every existing stdio topolo/topolo-* entry onto the hub
+topolo doctor --shared                 # hub, token, unit, registrations, then MCP whoami per identity
+topolo mcp serve [--port 7337]         # what the keep-alive unit runs; foreground for debugging
+```
+
+`setup --shared`:
+
+1. Adds the identity (`{name, env, context}`, exactly what a stdio entry pins
+   with `TOPOLO_ENV` + `TOPOLO_CONTEXT`; both are always pinned, and without
+   `--context` the only signed-in context is pinned) to `mcp-hub.json` next to
+   the credential store (`~/.config/topolo/mcp-hub.json`, or the directory of
+   `TOPOLO_CONFIG_PATH`). `--import-stdio` converts existing stdio entries and
+   skips ones the hub cannot serve (entries with no `TOPOLO_CONTEXT` pin,
+   private `TOPOLO_CONFIG_PATH` profiles, agent installations, invalid or
+   conflicting definitions). Add a skipped unpinned entry back with
+   `--name <name> --context <context>`.
+2. Creates `mcp-hub.token` (256-bit, mode 0600) once and reuses it.
+3. Registers **every** hub identity with Claude Code and Codex at user scope,
+   replacing same-name stdio entries. `--project` is refused so the token can
+   never land in a repository file. Other hosts stay on stdio.
+4. Installs a keep-alive unit running the exact Node binary and CLI entry that
+   ran setup (`--no-service` to skip): `~/Library/LaunchAgents/io.topolo.mcp-hub.plist`
+   (launchd, `KeepAlive`, logs to `~/Library/Logs/topolo-mcp-hub.log`) or
+   `~/.config/systemd/user/topolo-mcp-hub.service` (`Restart=always`). Only
+   `TOPOLO_CONFIG_PATH`/`XDG_CONFIG_HOME` are passed through; PATH and secrets
+   are not. With `--agent-home` the unit is written there but not loaded.
+
+Exact entries written (token shown as `<token>`):
+
+```jsonc
+// ~/.claude.json (written 0600)
+"mcpServers": {
+  "topolo-acme": {
+    "type": "http",
+    "url": "http://127.0.0.1:7337/mcp/topolo-acme",
+    "headers": { "Authorization": "Bearer <token>", "X-Topolo-Agent": "claude-code" }
+  }
+}
+```
+
+```toml
+# ~/.codex/config.toml (written 0600)
+[mcp_servers.topolo-acme]
+url = "http://127.0.0.1:7337/mcp/topolo-acme"
+http_headers = { "Authorization" = "Bearer <token>", "X-Topolo-Agent" = "codex" }
+```
+
+Codex streamable-HTTP servers accept `url`, `bearer_token_env_var`,
+`http_headers` and `env_http_headers`; an inline `bearer_token` is rejected.
+`http_headers` is used so the hub works when Codex is launched from a GUI with
+no shell environment. To keep the token out of `config.toml`, replace the
+`Authorization` header with `bearer_token_env_var = "TOPOLO_MCP_HUB_TOKEN"` and
+export that variable (contents of `mcp-hub.token`) into Codex's environment.
+
+Hub behaviour and security:
+
+- Binds `127.0.0.1` only; there is no host option.
+- Refuses any request whose `Host` is not `127.0.0.1`, `localhost` or `[::1]`
+  on the hub port, or that carries a non-loopback `Origin` (DNS rebinding and
+  browser cross-origin calls), before checking the bearer token
+  (constant-time). Only then is `/mcp/<name>` routed; `GET /health` lists
+  identity names.
+- Each identity has its own handler (`@topolo/mcp/local`) that resolves and
+  refreshes its credential from the local store exactly as a pinned stdio MCP
+  does. Process-wide `TOPOLO_API_KEY`/`TOPOLO_ACCESS_TOKEN`/`TOPOLO_CONTEXT`,
+  request headers and other identities are never consulted; the hub token is
+  stripped before the request reaches an identity.
+- Stateless Streamable HTTP (no session ids), so restarts never strand a client.
+- `mcp-hub.json` is re-read when it changes; adding an identity needs no restart.
+- Logs carry method, path, status and duration only.
+- Rotating the token: delete `mcp-hub.token`, rerun `topolo setup --shared`,
+  then restart the agents.
+
 ## Cross-org isolation
 
 The CLI **never accepts an `orgId` argument**. Every command is scoped to the
-active context embedded in the credential (personal or a specific org); to act
-in a different organization you switch context with `topolo context use`, which
+context embedded in the credential (personal or a specific org); to act
+in a different organization you pin that context's own stored credential
+(`--context`), or create one with `topolo context use`, which
 mints a new context-scoped credential — you can never target another org by
 passing an id. The context remains bound through refresh rotation and is not
 re-hydrated from the user's current web selection. This is enforced in two places:
@@ -224,6 +332,77 @@ Both resource flags are required together. This supports concurrent agent
 operations across many app-local workspaces without changing the CLI/MCP org
 context or the user's web switcher.
 
+### `topolo credentials write-custody`
+
+Local CLI and stdio MCP replace credentials in action results with opaque
+`topolo-secret:<uuid>` references held in the OS protected store (macOS
+Keychain, Linux Secret Service, Windows DPAPI). Both use the same store service
+and the same binding (environment, verified principal, organization and API key
+identity), so a reference returned by a stdio MCP call can be used by the CLI
+pinned to the same identity and environment. References expire after 30 minutes.
+
+When a service such as the release controller needs a scoped API key in a
+custody file, write it straight from the reference so no person or agent sees
+the plaintext:
+
+```bash
+export TOPOLO_CONTEXT=org:<organizationId>
+created=$(topolo --env production actions call app_topolo_auth.api_keys.create \
+  --data '{"appId":"<appId>","name":"<label>","scopes":["<scope>"],"expiresInDays":90}' \
+  --confirm --detail --json)   # data.key.secret is a topolo-secret reference
+topolo --env production credentials write-custody "$(jq -r .data.key.secret <<<"$created")" \
+  --api-key-id "$(jq -r .data.key.id <<<"$created")" --app <appId> \
+  --out /absolute/custody/dir/production --confirm --json
+```
+
+The command:
+
+1. Requires `--confirm`, an absolute `--out`, `--app` and `--api-key-id`.
+   Keep one key per environment in its own subdirectory (for example
+   `.../catalog-publication-credentials/<environment>/`). When the last path
+   component is an environment name it must equal the credential's environment
+   (`custody_environment_mismatch` otherwise), and `custody.json.environment`
+   is always the environment the credential, protected store and Auth calls
+   are bound to.
+2. Creates `--out` (and any missing parents) with mode 0700, or accepts an existing 0700 directory owned
+   by the current user. Every path component must be a real directory (no
+   symbolic links); parents must be owned by root or the current user and must
+   not be group- or world-writable (root-owned sticky directories such as
+   `/tmp` are allowed).
+3. Refuses to overwrite `api-key.json` or `custody.json` without `--replace`,
+   and refuses symbolic-link or non-regular destinations even with it.
+4. Reads the key's metadata from Auth `app_topolo_auth.api_keys.list` with the
+   pinned credential and requires the same organization, the `--app`
+   application, status `active` and an unexpired key.
+5. Resolves the reference through the SDK protected store with its binding
+   checks, then verifies the key against Auth introspection: it must be that
+   API key id, application, organization and scope set.
+6. Writes, each 0600 through a temporary file and rename in the same directory:
+   - `api-key.json`: `{"schemaVersion":1,"apiKey":"<secret>"}`
+   - `custody.json`: `{schemaVersion, appId, scopes, organizationId, environment,
+     apiKeyId, expiresAt, keyDigest, createdAt}`. `expiresAt` and `createdAt`
+     are Auth's values unchanged (epoch seconds, `expiresAt` null for no
+     expiry); `keyDigest` is `sha256:<hex>` of the secret.
+7. Deletes the local protected reference, like `actions release-secret`. This
+   does **not** revoke the upstream key; use `app_topolo_auth.api_keys.revoke`.
+
+Output (JSON or text) carries only paths, metadata and the digest. Refusals use
+stable `error.code` values: `custody_confirmation_required`,
+`custody_invalid_input`, `custody_path_not_absolute`, `custody_environment_mismatch`, `custody_platform_unsupported`,
+`custody_path_symlink`, `custody_path_not_directory`, `custody_path_not_regular`,
+`custody_parent_insecure`, `custody_dir_insecure`, `custody_file_exists`,
+`custody_organization_required`, `custody_metadata_unavailable`,
+`custody_key_not_found`, `custody_app_mismatch`, `custody_organization_mismatch`,
+`custody_key_inactive`, `custody_key_expired`, `custody_secret_unsupported_type`,
+`custody_key_verification_failed`, `custody_key_mismatch`,
+`custody_metadata_mismatch`, `custody_reference_release_failed` and
+`custody_error_withheld`, plus the protected store's `invalid_action_secret_reference`,
+`action_secret_unavailable` (unknown, or bound to another principal,
+organization, API key or environment), `action_secret_expired`,
+`action_secret_invalid` and `action_secret_identity_required`. A refusal before
+step 6 writes no custody file and keeps the reference (step 2 may already have
+created the empty 0700 directory).
+
 ### `topolo workspaces`
 
 Discovers canonical workspaces and the caller-specific creation policy for a

package/agent-packs/templates/career/skills/topolo/SKILL.md

@@ -270,6 +270,13 @@ Local deletion does not revoke the upstream credential; use its published
 revocation action separately when required. Other SDK/remote hosts keep
 redaction unless they explicitly provide a protected store.
 
+The only supported way to put a referenced API key on disk is an
+operator-approved custody file:
+`topolo credentials write-custody <reference> --out <absolute-dir> --app <appId> --api-key-id <id> --confirm --json`
+verifies the key against Auth, writes 0600 `api-key.json` and `custody.json`
+(metadata and a SHA-256 digest only) into a 0700 directory, prints no secret,
+and deletes the local reference without revoking the upstream key.
+
 ## Generic public API escape hatch
 
 Only when public docs provide a complete contract:

package/agent-packs/templates/clients/skills/topolo/SKILL.md

@@ -270,6 +270,13 @@ Local deletion does not revoke the upstream credential; use its published
 revocation action separately when required. Other SDK/remote hosts keep
 redaction unless they explicitly provide a protected store.
 
+The only supported way to put a referenced API key on disk is an
+operator-approved custody file:
+`topolo credentials write-custody <reference> --out <absolute-dir> --app <appId> --api-key-id <id> --confirm --json`
+verifies the key against Auth, writes 0600 `api-key.json` and `custody.json`
+(metadata and a SHA-256 digest only) into a 0700 directory, prints no secret,
+and deletes the local reference without revoking the upstream key.
+
 ## Generic public API escape hatch
 
 Only when public docs provide a complete contract:

package/agent-packs/templates/creative/skills/topolo/SKILL.md

@@ -270,6 +270,13 @@ Local deletion does not revoke the upstream credential; use its published
 revocation action separately when required. Other SDK/remote hosts keep
 redaction unless they explicitly provide a protected store.
 
+The only supported way to put a referenced API key on disk is an
+operator-approved custody file:
+`topolo credentials write-custody <reference> --out <absolute-dir> --app <appId> --api-key-id <id> --confirm --json`
+verifies the key against Auth, writes 0600 `api-key.json` and `custody.json`
+(metadata and a SHA-256 digest only) into a 0700 directory, prints no secret,
+and deletes the local reference without revoking the upstream key.
+
 ## Generic public API escape hatch
 
 Only when public docs provide a complete contract:

package/agent-packs/templates/founder/skills/topolo/SKILL.md

@@ -270,6 +270,13 @@ Local deletion does not revoke the upstream credential; use its published
 revocation action separately when required. Other SDK/remote hosts keep
 redaction unless they explicitly provide a protected store.
 
+The only supported way to put a referenced API key on disk is an
+operator-approved custody file:
+`topolo credentials write-custody <reference> --out <absolute-dir> --app <appId> --api-key-id <id> --confirm --json`
+verifies the key against Auth, writes 0600 `api-key.json` and `custody.json`
+(metadata and a SHA-256 digest only) into a 0700 directory, prints no secret,
+and deletes the local reference without revoking the upstream key.
+
 ## Generic public API escape hatch
 
 Only when public docs provide a complete contract:

package/agent-packs/templates/learning/skills/topolo/SKILL.md

@@ -270,6 +270,13 @@ Local deletion does not revoke the upstream credential; use its published
 revocation action separately when required. Other SDK/remote hosts keep
 redaction unless they explicitly provide a protected store.
 
+The only supported way to put a referenced API key on disk is an
+operator-approved custody file:
+`topolo credentials write-custody <reference> --out <absolute-dir> --app <appId> --api-key-id <id> --confirm --json`
+verifies the key against Auth, writes 0600 `api-key.json` and `custody.json`
+(metadata and a SHA-256 digest only) into a 0700 directory, prints no secret,
+and deletes the local reference without revoking the upstream key.
+
 ## Generic public API escape hatch
 
 Only when public docs provide a complete contract:

package/agent-packs/templates/personal/skills/topolo/SKILL.md

@@ -270,6 +270,13 @@ Local deletion does not revoke the upstream credential; use its published
 revocation action separately when required. Other SDK/remote hosts keep
 redaction unless they explicitly provide a protected store.
 
+The only supported way to put a referenced API key on disk is an
+operator-approved custody file:
+`topolo credentials write-custody <reference> --out <absolute-dir> --app <appId> --api-key-id <id> --confirm --json`
+verifies the key against Auth, writes 0600 `api-key.json` and `custody.json`
+(metadata and a SHA-256 digest only) into a 0700 directory, prints no secret,
+and deletes the local reference without revoking the upstream key.
+
 ## Generic public API escape hatch
 
 Only when public docs provide a complete contract:

package/agent-packs/templates/research/skills/topolo/SKILL.md

@@ -270,6 +270,13 @@ Local deletion does not revoke the upstream credential; use its published
 revocation action separately when required. Other SDK/remote hosts keep
 redaction unless they explicitly provide a protected store.
 
+The only supported way to put a referenced API key on disk is an
+operator-approved custody file:
+`topolo credentials write-custody <reference> --out <absolute-dir> --app <appId> --api-key-id <id> --confirm --json`
+verifies the key against Auth, writes 0600 `api-key.json` and `custody.json`
+(metadata and a SHA-256 digest only) into a 0700 directory, prints no secret,
+and deletes the local reference without revoking the upstream key.
+
 ## Generic public API escape hatch
 
 Only when public docs provide a complete contract:

package/agent-packs/templates/ventures/skills/topolo/SKILL.md

@@ -270,6 +270,13 @@ Local deletion does not revoke the upstream credential; use its published
 revocation action separately when required. Other SDK/remote hosts keep
 redaction unless they explicitly provide a protected store.
 
+The only supported way to put a referenced API key on disk is an
+operator-approved custody file:
+`topolo credentials write-custody <reference> --out <absolute-dir> --app <appId> --api-key-id <id> --confirm --json`
+verifies the key against Auth, writes 0600 `api-key.json` and `custody.json`
+(metadata and a SHA-256 digest only) into a 0700 directory, prints no secret,
+and deletes the local reference without revoking the upstream key.
+
 ## Generic public API escape hatch
 
 Only when public docs provide a complete contract: