@topolo/cli 0.13.12 → 0.13.15

package/README.md

@@ -114,6 +114,88 @@ 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`; omit `--context` only for the default
+   `topolo` identity that follows the active context) 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 (private `TOPOLO_CONFIG_PATH` profiles,
+   agent installations, invalid or conflicting definitions).
+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
@@ -224,6 +306,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
@@ -453,7 +606,7 @@ silently become version 2 CLI plans.
 
 `topolo agent-packs --store /owned/AgentPacks runtime-adoption plan --manifest /review/adoption.json` produces a nonwriting configuration plan. Review its physical targets and digest, then use `runtime-adoption apply --manifest /review/adoption.json --plan-digest <sha256> --confirm` for one configuration-only attempt.
 
-The closed owner manifest binds the actual consumer set and effective local Topolo transport origins, physical file preimages, shared aliases, private profile metadata, immutable CLI 0.13.11/MCP 0.14.26/SDK 0.23.21 targets and the separately pinned successor Python adapter. It must include every server in each physical config as either a targeted transport or an explicitly untouched server. Empty or incomplete manifests refuse. The command never installs skills, rebinds a home, changes existing instructions/permissions, starts a consumer or probes Auth.
+The closed owner manifest binds the actual consumer set and effective local Topolo transport origins, physical file preimages, shared aliases, private profile metadata, one of the two reviewed immutable consumer tuples (CLI 0.13.11/MCP 0.14.26/SDK 0.23.21 or CLI 0.13.12/MCP 0.14.27/SDK 0.23.22) and the separately pinned successor Python adapter. Consumer tuple versions are independent of the driver package version; mixed tuples and other versions refuse. It must include every server in each physical config as either a targeted transport or an explicitly untouched server. Empty or incomplete manifests refuse. The command never installs skills, rebinds a home, changes existing instructions/permissions, starts a consumer or probes Auth.
 
 A successful apply means configuration is prepared. It does not mean existing processes reloaded it, the private account is healthy, permissions were granted or either native harness completed a task. Starting or refreshing consumers is a separate owner-authorized step and can contact private Auth and renew the selected private profile. Public credential-store repair is not a blanket prerequisite for independent private profiles. See [the manifest and effect boundaries](agent-packs/README.md#private-runtime-adoption).
 

package/agent-packs/README.md

@@ -710,7 +710,7 @@ The manifest is a local owner-reviewed configuration scope, not native provenanc
 - `ownerGeneration: {path, sha256}`: the owner's current bounded nonsecret effective-transport/generation record, inside that library. The owner must establish its native currency separately.
 - `consumers`: the complete unique existing native IDs in scope. Target rows must account for every ID; no new native IDs are created.
 - `profile: {path, publicPath, metadata, environment, contextKey, principalId}`: absolute private and public credential-file references, explicit organization context, and metadata only. Files must be physically distinct; the private profile must be owned, single-link, regular and mode 0600. Neither profile's contents are read or hashed. A renewal that changes private file metadata invalidates the descriptor and requires owner reconciliation.
-- `runtime: {node, cli, mcp, cohort, pythonSource, adapterFiles, osEnvironment}`. Each executable/entry and each `cohort` value is `{path, sha256}`. Cohort keys `cli`, `mcp`, `sdk` pin their package JSON; required target versions are 0.13.11, 0.14.26 and 0.23.21. CLI and MCP entries must be their pinned package's `dist/index.js`. `pythonSource` is the physical successor source directory; `adapterFiles` pins its `topolo_agent_pack/{cli,live,topolo}.py`. Verify the complete installed cohort independently before admitting its pins. `osEnvironment` permits only HOME/PATH and optional USER/LOGNAME/LANG/LC_ALL/TMPDIR, with no credential, service-origin, Node or installation overrides.
+- `runtime: {node, cli, mcp, cohort, pythonSource, adapterFiles, osEnvironment}`. Each executable/entry and each `cohort` value is `{path, sha256}`. Cohort keys `cli`, `mcp`, `sdk` pin their package JSON; the exact reviewed consumer tuples are CLI 0.13.11/MCP 0.14.26/SDK 0.23.21 and CLI 0.13.12/MCP 0.14.27/SDK 0.23.22. Each tuple is coupled: mixed or unreviewed versions refuse, and both CLI and MCP must depend on that tuple's exact SDK version. The consumer tuple is independent of the driver package version. CLI and MCP entries must be their pinned package's `dist/index.js`. `pythonSource` is the physical successor source directory; `adapterFiles` pins its `topolo_agent_pack/{cli,live,topolo}.py`. Verify the complete installed cohort independently before admitting its pins. `osEnvironment` permits only HOME/PATH and optional USER/LOGNAME/LANG/LC_ALL/TMPDIR, with no credential, service-origin, Node or installation overrides.
 - `targets`: one row per unique physical configuration file, with `{path, before, aliases, format, rootKey, consumers, transports, untouchedServers}`. Supported formats are JSON `mcpServers` and simple TOML `mcp_servers` tables. Each transport is `{name, origin, consumers}` and must already exist as a local command; URL, inherited `env_vars`, installation-mode, ambiguous names or unsupported TOML layouts refuse. `origin` is the exact physical file. The complete physical server map must equal the targeted names plus `untouchedServers`. The owner must independently bind all effective native layers; a zero-table query or a guessed server name is insufficient.
 - `launcher: {path, before}`: exactly the owned generated `launchers/topolo-agent-pack-backend`; its interpreter, owner and mode are preserved.
 - `preserve`: nonsecret `{path, sha256}` references to existing roster, model/effort, permission, charter/context, routing and lifecycle records. Include every protected fixed and dynamic record in the approved scope. These may not overlap destinations. No transcript or credential contents belong in a manifest.

package/agent-packs/src/topolo_agent_pack/live.py

@@ -2086,12 +2086,19 @@ def adoption_runtime(runtime,profile):
     adoption_read_guard(profile,adoption_runtime_paths(runtime))
     for key in ['node','cli','mcp']:adoption_pin(runtime[key],profile)
     adoption_keys(runtime['cohort'],['cli','mcp','sdk'])
-    for key,name,version in [('cli','@topolo/cli','0.13.11'),('mcp','@topolo/mcp','0.14.26'),('sdk','@topolo/sdk','0.23.21')]:
+    packages={}
+    for key,name in [('cli','@topolo/cli'),('mcp','@topolo/mcp'),('sdk','@topolo/sdk')]:
         package=json.loads(adoption_pin(runtime['cohort'][key],profile))
-        adoption_require(package.get('name')==name and package.get('version')==version,'immutable target cohort differs')
-        if key!='sdk':
-            adoption_require(runtime[key]['path']==str(pathlib.Path(runtime['cohort'][key]['path']).parent/'dist/index.js') and
-                             package.get('dependencies',{}).get('@topolo/sdk')=='0.23.21','entry/dependency cohort differs')
+        adoption_require(package.get('name')==name,'immutable target cohort differs')
+        packages[key]=package
+    versions=tuple(packages[key].get('version') for key in ['cli','mcp','sdk'])
+    # Reviewed consumer tuples are independent of this adapter driver's version.
+    # Membership is coupled: independently allowed versions would admit mixtures.
+    adoption_require(versions in (('0.13.11','0.14.26','0.23.21'),('0.13.12','0.14.27','0.23.22')),
+                     'immutable target cohort differs')
+    for key in ['cli','mcp']:
+        adoption_require(runtime[key]['path']==str(pathlib.Path(runtime['cohort'][key]['path']).parent/'dist/index.js') and
+                         packages[key].get('dependencies',{}).get('@topolo/sdk')==versions[2],'entry/dependency cohort differs')
     source=pathlib.Path(runtime['pythonSource'])
     adoption_require(source.is_absolute() and source==source.resolve(),'physical adapter source required')
     adoption_require(isinstance(runtime['adapterFiles'],list) and len(runtime['adapterFiles'])==3 and

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: