Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

Sign agents controller releases, and stop handing agents long-lived service credentials

Petr Bauch26a2c0f119ba
diff --git a/.github/workflows/agent-controller-release.yml b/.github/workflows/agent-controller-release.yml
index 7e2b68a53..23ab88f9d 100644
--- a/.github/workflows/agent-controller-release.yml
+++ b/.github/workflows/agent-controller-release.yml
@@ -3,10 +3,16 @@ name: switch-agent-controller release
# Builds the installable agents controller (console/packages/agent-controller)
# and publishes it as a GitHub release: the npm package
# `switch-agent-controller-<version>.tgz`, installed with
-# `npm install --global <its URL>`, and the `install.sh` that finds and installs
+# `npm install --global --ignore-scripts`, and the `install.sh` that finds, verifies and installs
# the newest one. `switch-agent-controller update` and `install.sh` read these
# releases, so nothing needs an npm registry or token.
#
+# A release is signed: `switch-agent-controller-<version>.tgz.sig` is the
+# Ed25519 signature of the version and the package's SHA-256
+# (scripts/sign-release.mjs), made with the CONTROLLER_RELEASE_SIGNING_KEY
+# secret, and controllers and `install.sh` install nothing that does not verify
+# against the keys built into them. A release run without the secret fails.
+#
# Trigger by pushing a tag like `switch-agent-controller-v0.2.0`; the package
# is built with the tag's version. `workflow_dispatch` builds and tests it
# without releasing, for verification. See RELEASING.md.
@@ -82,10 +88,17 @@ jobs:
VERSION: ${{ steps.version.outputs.version }}
run: |
prefix="$(mktemp -d)"
- npm install --global --prefix "$prefix" "packages/agent-controller/dist-package/switch-agent-controller-$VERSION.tgz"
+ npm install --global --ignore-scripts --prefix "$prefix" "packages/agent-controller/dist-package/switch-agent-controller-$VERSION.tgz"
test "$("$prefix/bin/switch-agent-controller" --version)" = "$VERSION"
"$prefix/bin/switch-agent-controller" --help > /dev/null
+ - name: Sign the package
+ if: steps.version.outputs.release == 'true'
+ env:
+ CONTROLLER_RELEASE_SIGNING_KEY: ${{ secrets.CONTROLLER_RELEASE_SIGNING_KEY }}
+ VERSION: ${{ steps.version.outputs.version }}
+ run: node packages/agent-controller/scripts/sign-release.mjs "packages/agent-controller/dist-package/switch-agent-controller-$VERSION.tgz" "$VERSION"
+
- name: Release
if: steps.version.outputs.release == 'true'
env:
@@ -95,9 +108,10 @@ jobs:
run: |
gh release create "$TAG" \
"packages/agent-controller/dist-package/switch-agent-controller-$VERSION.tgz" \
+ "packages/agent-controller/dist-package/switch-agent-controller-$VERSION.tgz.sig" \
packages/agent-controller/install.sh \
--title "switch-agent-controller $VERSION" \
--notes "The Switch agents controller $VERSION, for running managed agents on your own Linux or macOS machines.
- Install (Node 22.13 or later): \`npm install --global https://github.com/$GITHUB_REPOSITORY/releases/download/$TAG/switch-agent-controller-$VERSION.tgz\`, or run \`install.sh\`. Then enroll with a code from the Machines page and run \`switch-agent-controller install-service\`. An installed controller updates with \`switch-agent-controller update\`." \
+ Install (Node 22.13 or later) with \`install.sh\`, which checks the package's signature (\`switch-agent-controller-$VERSION.tgz.sig\`) before installing it. Then enroll with a code from the Machines page and run \`switch-agent-controller install-service\`. An installed controller updates with \`switch-agent-controller update\`." \
--latest=false
diff --git a/.github/workflows/switch-release.yml b/.github/workflows/switch-release.yml
index 31fef177d..24402a896 100644
--- a/.github/workflows/switch-release.yml
+++ b/.github/workflows/switch-release.yml
@@ -46,7 +46,10 @@ name: switch release
# release (a prerelease for an RC or a dev build; switch-dev-cleanup.yml prunes
# only the dev ones), and pins
# that package into the switch chart's switchCore.controllerRelease, so Core
-# tells controllers to run the controller of the Switch they talk to.
+# tells controllers to run the controller of the Switch they talk to. The
+# package is published with its signature (`.tgz.sig`, made with the
+# CONTROLLER_RELEASE_SIGNING_KEY secret), which controllers verify before they
+# install it; a publishing run without the secret fails.
#
# Artifacts go to GHCR by default, and the packages are public alongside the
# repo. REGISTRY / IMAGE_NAMESPACE are the only things to change to retarget
@@ -381,7 +384,7 @@ jobs:
VERSION: ${{ steps.version.outputs.version }}
run: |
prefix="$(mktemp -d)"
- npm install --global --prefix "$prefix" "packages/agent-controller/dist-package/switch-agent-controller-$VERSION.tgz"
+ npm install --global --ignore-scripts --prefix "$prefix" "packages/agent-controller/dist-package/switch-agent-controller-$VERSION.tgz"
test "$("$prefix/bin/switch-agent-controller" --version)" = "$VERSION"
"$prefix/bin/switch-agent-controller" --help > /dev/null
@@ -393,6 +396,15 @@ jobs:
sha256="$(sha256sum "packages/agent-controller/dist-package/switch-agent-controller-$VERSION.tgz" | cut -d' ' -f1)"
echo "sha256=$sha256" | tee -a "$GITHUB_OUTPUT"
+ - name: Sign the package
+ # Controllers install only a release signed with a key built into them
+ # (src/release-keys.ts); see "Release signing" in RELEASING.md.
+ if: needs.prep.outputs.push == 'true'
+ env:
+ CONTROLLER_RELEASE_SIGNING_KEY: ${{ secrets.CONTROLLER_RELEASE_SIGNING_KEY }}
+ VERSION: ${{ steps.version.outputs.version }}
+ run: node packages/agent-controller/scripts/sign-release.mjs "packages/agent-controller/dist-package/switch-agent-controller-$VERSION.tgz" "$VERSION"
+
- name: Release
# The tag is created from this commit by the release itself. A tag
# pushed with the workflow token starts no workflow, so
@@ -417,11 +429,18 @@ jobs:
echo "::error::$TAG is already released with a different package (sha256 $published, this build $SHA256). Delete that release and its tag, then re-run."
exit 1
fi
- echo "$TAG is already released with this package."
+ # Its signature must be there too, or no controller installs it.
+ if ! gh release view "$TAG" --repo "$GITHUB_REPOSITORY" --json assets --jq '.assets[].name' |
+ grep -Fqx "switch-agent-controller-$VERSION.tgz.sig"; then
+ gh release upload "$TAG" "$package.sig" --repo "$GITHUB_REPOSITORY"
+ echo "$TAG is already released with this package; uploaded its signature."
+ exit 0
+ fi
+ echo "$TAG is already released with this package and its signature."
exit 0
fi
if [ "$CHANNEL" = rc ]; then
- gh release create "$TAG" "$package" \
+ gh release create "$TAG" "$package" "$package.sig" \
--repo "$GITHUB_REPOSITORY" \
--target "$GITHUB_SHA" \
--title "switch-agent-controller $VERSION (release candidate)" \
@@ -433,7 +452,7 @@ jobs:
exit 0
fi
if [ "$CHANNEL" = dev ]; then
- gh release create "$TAG" "$package" \
+ gh release create "$TAG" "$package" "$package.sig" \
--repo "$GITHUB_REPOSITORY" \
--target "$GITHUB_SHA" \
--title "switch-agent-controller $VERSION (dev build of main)" \
@@ -444,7 +463,7 @@ jobs:
--latest=false
exit 0
fi
- gh release create "$TAG" "$package" packages/agent-controller/install.sh \
+ gh release create "$TAG" "$package" "$package.sig" packages/agent-controller/install.sh \
--repo "$GITHUB_REPOSITORY" \
--target "$GITHUB_SHA" \
--title "switch-agent-controller $VERSION" \
@@ -452,7 +471,7 @@ jobs:
SHA-256: \`$SHA256\`
- Install (Node 22.13 or later): \`npm install --global https://github.com/$GITHUB_REPOSITORY/releases/download/$TAG/switch-agent-controller-$VERSION.tgz\`, or run \`install.sh\`. Then enroll with a code from the Machines page and run \`switch-agent-controller install-service\`. A controller connected to Switch $VERSION updates to this release on its own once it is idle." \
+ Install (Node 22.13 or later) with \`install.sh\`, which checks the package's signature (\`switch-agent-controller-$VERSION.tgz.sig\`) before installing it. Then enroll with a code from the Machines page and run \`switch-agent-controller install-service\`. A controller connected to Switch $VERSION updates to this release on its own once it is idle." \
--latest=false
chart:
diff --git a/CHANGELOG.md b/CHANGELOG.md
index fff9e0b67..a10996bc0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -44,6 +44,29 @@ version of their own to them without also giving them a release of their own.
### [Unreleased]
+#### Security
+- **Agents are no longer handed a key that never expires.** Datadog connects
+ with an API key and an application key that do not expire and that only
+ Datadog can revoke, and an agent granted Datadog was handed both. Switch now
+ refuses: Datadog can no longer be connected or granted, and an agent with an
+ existing Datadog grant is told why when it asks. A Datadog connection made
+ before can still be disconnected; revoke the keys in Datadog if they were
+ ever granted to an agent.
+- **Service connections start off in a new workspace.** A workspace created
+ from now on has every service connection switched off until a workspace
+ admin switches each on under Connectors. Workspaces that already had members
+ keep every service on by default, as before, along with every switch an
+ admin already set.
+- **A Google Workspace token is never handed out with more than an hour
+ left,** and one Google issues for longer is refused.
+- **Withdrawing access says what it could not take back.** Removing a grant,
+ disconnecting, or switching a service off for the workspace cannot revoke an
+ Atlassian or Google Workspace token already given to an agent, since that
+ token is the owner's own. The change now marks those tokens withdrawn and
+ its warning names the service and the time until which they may keep
+ working: up to an hour for Google Workspace, and up to eight hours for
+ Atlassian, whose tokens cannot be asked for shorter.
+
#### Fixed
- **The template guide agents read now covers a room's `roles:`,
`references:` and `docs:`.** All three already worked in a room resource
diff --git a/RELEASING.md b/RELEASING.md
index 967e9af0e..000215a05 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -287,7 +287,9 @@ git push origin switch-agent-controller-v0.2.0
to Switch and compares it with newer releases.
- **What it publishes:** a GitHub Release holding
`switch-agent-controller-<version>.tgz` (one npm package with the CLI and the
- shared-host bundle, no dependencies) and `install.sh`. It is never marked Latest,
+ shared-host bundle, no dependencies), its signature
+ `switch-agent-controller-<version>.tgz.sig` (see [Release signing](#release-signing))
+ and `install.sh`. It is never marked Latest,
so Switch Console's stable updater never sees it.
- **How installs find it:** `install.sh` and `switch-agent-controller update` list the
repository's releases and take the highest non-draft, non-prerelease controller tag
@@ -297,7 +299,58 @@ git push origin switch-agent-controller-v0.2.0
- **Not gated:** the workflow needs no approval. It tests the controller, packs it,
installs the package and runs it once before releasing.
-`workflow_dispatch` runs everything except the release, for verification.
+`workflow_dispatch` runs everything except signing and the release, for
+verification, and needs no secret.
+
+### Release signing
+
+Controllers install only a release signed with a key built into them, so neither
+a compromised Switch server nor its chart values can make them run a package the
+release workflows did not publish. Both `agent-controller-release.yml` and the
+`controller` job of `switch-release.yml` sign each package they publish (stable,
+RC and dev builds alike) with `scripts/sign-release.mjs`, which writes
+`<package>.tgz.sig`: the Ed25519 signature, base64, of
+`switch-agent-controller-release-v1\n<version>\n<sha256>\n`. The private key is
+the `CONTROLLER_RELEASE_SIGNING_KEY` GitHub Actions secret (PKCS#8 PEM). A
+publishing run without it fails, and so does one whose key's public half is not in
+`console/packages/agent-controller/src/release-keys.ts`. A re-run of a release
+that is already published with the same package uploads the signature if the
+release lacks it.
+
+The controller (`run`, `update`) and `install.sh` check the signature against the
+trusted keys in `src/release-keys.ts` (`install.sh` carries a copy between its
+`TRUSTED RELEASE KEYS` markers; `release-keys.test.ts` fails when they differ).
+With no trusted key, they install nothing.
+
+**Generating the first key.** On a machine you trust:
+
+```bash
+cd console/packages/agent-controller
+node scripts/generate-release-signing-key.mjs release-<yyyy>-<mm>
+```
+
+It prints three things: the entry for `TRUSTED_RELEASE_KEYS` in
+`src/release-keys.ts`, the same key as a line for `install.sh`, and the private
+key. Paste the first two and merge them; store the private key as the repository
+secret `CONTROLLER_RELEASE_SIGNING_KEY` (Settings → Secrets and variables →
+Actions, or `gh secret set CONTROLLER_RELEASE_SIGNING_KEY < key.pem` from a file
+you then delete), and keep no other copy outside a password manager or vault.
+No release can be published while the list is empty: `sign-release.mjs` refuses
+a key that is not in it. Controllers from before release signing check only the
+SHA-256 Switch names, so they update to the first signed release as before and
+verify signatures from then on.
+
+**Rotating.** Generate a new key with a new id, add it to both lists beside the
+old one, and release: controllers on that release trust both. Once they have
+moved to it (the owner's controller list shows `release.current`), replace the
+secret with the new private key, and in a later release remove the old public
+key. A controller that skipped the release trusting both cannot verify releases
+signed only with the new key; reinstall it by hand.
+
+**If the private key leaks.** Remove its public key from both lists, add a new
+one, replace the secret, and release. Controllers still on releases that trust
+the leaked key keep trusting it until they update, so treat them as exposed until
+they run the new release.
### The controller a Switch release names
@@ -317,8 +370,9 @@ The chart from that release names the package in `switchCore.controllerRelease`
`CONTROLLER_RELEASE_VERSION`, `_URL` and `_SHA256` and hands every controller in
its status answer (except Switch Console's own, which updates with Console). A
controller running another version downloads the package,
-refuses it unless its SHA-256 matches, and installs it and restarts once none of
-its agents has a session running. The owner's controller list
+refuses it unless its SHA-256 matches and its signature (`<url>.sig`) verifies
+against a key built into the controller, and installs it and restarts once none
+of its agents has a session running. The owner's controller list
(`GET /gateway/management/controllers`, `release.current`) shows which are not yet
on it.
@@ -326,6 +380,8 @@ on it.
version, its `.../switch-agent-controller-v<old>/switch-agent-controller-<old>.tgz`
URL, and the SHA-256 in its release notes) and upgrade the chart. Setting none of
them stops telling controllers anything; they keep the version they have.
+ The previous release must carry a signature a controller trusts: one published
+ before release signing, or signed only with a key since removed, is refused.
- **Versions now follow Switch.** Controllers released this way carry the Switch
version, which is well above the controller's own earlier `0.1.x` line. A
controller release tagged by hand still works, but take its version from the
diff --git a/console/apps/switch-console-desktop/src/renderer/features/connectors/connector-copy.ts b/console/apps/switch-console-desktop/src/renderer/features/connectors/connector-copy.ts
index 47c03a124..b7e1d3121 100644
--- a/console/apps/switch-console-desktop/src/renderer/features/connectors/connector-copy.ts
+++ b/console/apps/switch-console-desktop/src/renderer/features/connectors/connector-copy.ts
@@ -61,12 +61,12 @@ export function switchOffConfirmation(
};
}
-/** Who last changed a workspace switch, and when; a switch nobody touched is on by default. */
+/** Who last changed a workspace switch, and when; a switch nobody touched takes the workspace's default. */
export function workspaceSwitchNote(
service: Pick<WorkspaceService, 'enabled' | 'updated_by_name' | 'updated_at'>,
formatTime: (iso: string) => string
): string {
- if (service.updated_at === null) return 'On by default.';
+ if (service.updated_at === null) return service.enabled ? 'On by default.' : 'Off by default.';
const state = service.enabled ? 'on' : 'off';
const who = service.updated_by_name ?? 'a deleted account';
return `Switched ${state} by ${who}, ${formatTime(service.updated_at)}.`;
diff --git a/console/apps/switch-console-desktop/src/renderer/features/connectors/connectors-catalog.ts b/console/apps/switch-console-desktop/src/renderer/features/connectors/connectors-catalog.ts
index 57298090f..3174ff944 100644
--- a/console/apps/switch-console-desktop/src/renderer/features/connectors/connectors-catalog.ts
+++ b/console/apps/switch-console-desktop/src/renderer/features/connectors/connectors-catalog.ts
@@ -93,15 +93,19 @@ export function workspaceOffNotice(
* repositories, or replace a connected key. None while the workspace has the
* service off, whose notice says what to do instead, nor where the server
* says nothing can be connected until its app is set up, or ever on this
- * server. Another reason the server gives does not take it away: a service
- * can often be connected where it cannot be granted, and the button is
- * disabled where it cannot.
+ * server, nor for a key Switch never hands to agents. Another reason the
+ * server gives does not take it away: a service can often be connected where
+ * it cannot be granted, and the button is disabled where it cannot.
*/
export function profileConnectAction(
entry: ConnectionCatalogEntry
): 'connect' | 'reconnect' | 'replace' | null {
if (entry.status === 'coming_soon' || entry.workspace_enabled === false) return null;
- if (entry.unavailable_code === 'app_not_set_up' || entry.unavailable_code === 'needs_https')
+ if (
+ entry.unavailable_code === 'app_not_set_up' ||
+ entry.unavailable_code === 'needs_https' ||
+ entry.unavailable_code === 'key_never_expires'
+ )
return null;
if (entry.status === 'not_connected') return 'connect';
if (entry.status === 'needs_reauthorization' || entry.status === 'error') return 'reconnect';
diff --git a/console/apps/switch-console-desktop/src/renderer/tests/connectors.test.ts b/console/apps/switch-console-desktop/src/renderer/tests/connectors.test.ts
index 7343e2c82..5d481663f 100644
--- a/console/apps/switch-console-desktop/src/renderer/tests/connectors.test.ts
+++ b/console/apps/switch-console-desktop/src/renderer/tests/connectors.test.ts
@@ -262,6 +262,16 @@ describe('what each person is told about a connector that cannot be used', () =>
)
).toBe('connect');
});
+
+ it('offers no way to connect or replace a key Switch never hands to agents', () => {
+ const key = entry({
+ auth_type: 'api_key',
+ unavailable_reason: 'Datadog keys do not expire.',
+ unavailable_code: 'key_never_expires',
+ });
+ expect(profileConnectAction(key)).toBeNull();
+ expect(profileConnectAction({ ...key, status: 'connected' })).toBeNull();
+ });
});
describe('the Yours and Discover tabs', () => {
@@ -722,6 +732,9 @@ describe('an admin switching a service off', () => {
expect(
workspaceSwitchNote({ enabled: true, updated_by_name: null, updated_at: null }, at)
).toBe('On by default.');
+ expect(
+ workspaceSwitchNote({ enabled: false, updated_by_name: null, updated_at: null }, at)
+ ).toBe('Off by default.');
expect(
workspaceSwitchNote({ enabled: false, updated_by_name: 'Ada', updated_at: 'T' }, at)
).toBe('Switched off by Ada, at T.');
diff --git a/console/apps/switch-console-desktop/src/shared/core/switch-servers/connection-catalog.ts b/console/apps/switch-console-desktop/src/shared/core/switch-servers/connection-catalog.ts
index 78c4974e4..f140a0e9a 100644
--- a/console/apps/switch-console-desktop/src/shared/core/switch-servers/connection-catalog.ts
+++ b/console/apps/switch-console-desktop/src/shared/core/switch-servers/connection-catalog.ts
@@ -29,6 +29,8 @@ export type ServiceKeyForm = z.infer<typeof serviceKeyFormSchema>;
* Connector apps, and isn't yet.
* - `not_set_up`: nothing on this server connects it.
* - `not_fully_set_up`: it can be connected but not granted to agents.
+ * - `key_never_expires`: it connects with a key that never expires, which
+ * Switch does not hand to agents, so there is nothing to connect it for.
*/
export const UNAVAILABLE_CODES = [
'coming_soon',
@@ -37,6 +39,7 @@ export const UNAVAILABLE_CODES = [
'app_not_set_up',
'not_set_up',
'not_fully_set_up',
+ 'key_never_expires',
] as const;
export type UnavailableCode = (typeof UNAVAILABLE_CODES)[number];
diff --git a/console/packages/agent-controller/README.md b/console/packages/agent-controller/README.md
index 789f5cf25..cf5365512 100644
--- a/console/packages/agent-controller/README.md
+++ b/console/packages/agent-controller/README.md
@@ -62,8 +62,12 @@ cannot write there (Node from the system's packages installs into `/usr`), it
installs into `~/.local` instead, without changing npm's settings, and says so
if `~/.local/bin` is not on the PATH; the service runs the controller by its
full path either way. `switch-agent-controller update` installs into the same
-prefix the running controller came from. The package can also be installed
-directly: `npm install --global <the release's .tgz URL>`.
+prefix the running controller came from. `install.sh`, `update` and the
+controller's own updates install only a release signed with a key built into
+them (see [Release signing](#release-signing)), with `npm install
+--ignore-scripts`. The package can also be installed directly, `npm install
+--global --ignore-scripts <the release's .tgz URL>`, but that checks no signature:
+check it yourself first, as `install.sh` does.
From a checkout, build the workspace packages
(`pnpm install && pnpm -r --filter './packages/**' run build` from `console/`) and
@@ -211,7 +215,7 @@ with systemd and polkit, each agent can instead run as a Linux user of its own,
which sees only its own directory. Set it up once, as root, after enrolling:
```bash
-sudo npm install --global <the release's .tgz URL> # Node and the controller system-wide
+sudo npm install --global --ignore-scripts <the release's .tgz, its signature checked> # Node and the controller system-wide
switch-agent-controller enroll --server https://switch.example.com --code <code>
sudo switch-agent-controller install-service --separate-users [--env-file /etc/switch/agents.env]
```
@@ -359,10 +363,16 @@ than the one running (newer or older: Switch can roll back), the controller:
of those onto it as soon as none of its sessions is mid-turn: each records
the shared-host bundle it runs in its `health.json`). An agent host too old to report busy sessions holds it back
while it has any session, as `sessions_running` counts them;
-2. downloads the package into `<data dir>/updates/` (at most 200 MB) and checks
- its SHA-256 against the one Switch gave, the only one trusted; a package that
- differs is deleted;
-3. installs it from that file, never from the URL, checks that the installed CLI
+2. downloads the package over https (an `http` URL is refused) into
+ `<data dir>/updates/` (at most 200 MB), checks its SHA-256 against the one
+ Switch gave, then fetches `<url>.sig` and checks the release signature for that
+ version and SHA-256 against the keys built into the controller (see
+ [Release signing](#release-signing)); a package that fails either check, or has
+ no signature, is deleted and the attempt reported as failed. The server alone
+ cannot make a controller install a package: only one the release workflows
+ signed;
+3. installs it from that file, never from the URL, with `npm install
+ --ignore-scripts` (no install script runs), checks that the installed CLI
says `--version` is that version, checks again that no turn started
meanwhile, and switches to it;
4. exits with code `7`, and its service starts it again on the new release.
@@ -377,6 +387,15 @@ SSH host (run with `--updated-by-console`) update when Console replaces their
bundle. Each reports `controller.updated_by: "console"` in its status (`"self"`
otherwise), and Switch names it no release.
+**Turning it off.** `SWITCH_CONTROLLER_SELF_UPDATE=off`, in the controller's
+environment or in the `--env-file` it runs with (the one `install-service
+--env-file` set up), or `run --no-self-update`, keeps the controller on the
+release it has. When Switch names another, the controller installs nothing and
+reports `update: {"target", "state": "failed", "problem"}` saying self-update is
+off, as it does for any controller that cannot update itself. `on` (or unset) is
+the default; any other value stops `run` with a configuration error. `update`
+still installs by hand.
+
Where it installs depends on how the controller was installed:
- **As a service, of your user or with `--separate-users`:** into its releases
@@ -391,7 +410,7 @@ Where it installs depends on how the controller was installed:
was. A service of your user installed before releases directories updates in
place, as below, until `install-service` is run again.
- **A plain npm install, not run as a service:** with `npm install --global
- --prefix <prefix>`, over the prefix the running controller came from, as `update`
+ --ignore-scripts --prefix <prefix>`, over the prefix the running controller came from, as `update`
does. A controller run from a checkout does not update itself, and reports why,
as does one on Windows. Under systemd (which sets `INVOCATION_ID`) or launchd
(`--launchd`) it exits `7` to be restarted; run any other way, it installs,
@@ -404,6 +423,27 @@ install into a releases directory, which only its controller installs into. Run
the npm install, it installs there and points the service's `current` back at it when
that is newer than what `current` names.
+### Release signing
+
+Every published controller release carries, beside
+`switch-agent-controller-<version>.tgz`, `switch-agent-controller-<version>.tgz.sig`:
+an Ed25519 signature, base64 on one line, of the message
+
+```
+switch-agent-controller-release-v1
+<version>
+<the package's SHA-256, lowercase hex>
+```
+
+(each line ending in a newline, the last one included). It binds the version as
+well as the bytes, so a signed package cannot be passed off as another version.
+The trusted public keys are built into the controller (`src/release-keys.ts`, with
+a copy in `install.sh` that a test keeps equal); a signature verifies when any of
+them verifies it, which is how keys are rotated (see "Release signing" in
+`RELEASING.md`). The controller (`run` and `update`) and `install.sh` refuse a
+release with no signature, a signature that does not verify, or a non-https URL,
+and install nothing at all while the list of trusted keys is empty.
+
### Checking a machine
`doctor` checks what a machine needs to run agents and says what to do where it
diff --git a/console/packages/agent-controller/install.sh b/console/packages/agent-controller/install.sh
index 854573bec..258f15b0b 100755
--- a/console/packages/agent-controller/install.sh
+++ b/console/packages/agent-controller/install.sh
@@ -14,6 +14,9 @@
# --no-service Enroll, but do not install the service.
# --version <x.y.z> Install this release rather than the newest.
#
+# It installs only a release signed with one of the release signing keys
+# below, and runs no npm install scripts.
+#
# It installs where npm installs global packages. When this user cannot write
# there (Node from the system's packages installs into /usr), it installs into
# ~/.local instead, without changing npm's settings.
@@ -29,6 +32,48 @@ fail() {
exit 1
}
+# The release signing keys this installer trusts, one "<id> <base64 SPKI>" per
+# line: a copy of src/release-keys.ts, which release-keys.test.ts keeps equal.
+# BEGIN TRUSTED RELEASE KEYS
+TRUSTED_RELEASE_KEYS='
+release-2026-10 MCowBQYDK2VwAyEAaRFfp1Yd/b91KkZs8Vj/OQSdsZS2ifd+rZu24pKTMpU=
+'
+# END TRUSTED RELEASE KEYS
+
+# Verifies <package> against <signature file> for <version>: the Ed25519
+# signature over "switch-agent-controller-release-v1\n<version>\n<sha256>\n"
+# by one of TRUSTED_RELEASE_KEYS. Prints the id of the key that verifies it.
+# BEGIN VERIFY RELEASE
+VERIFY_RELEASE_JS='
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const [file, signatureFile, version] = process.argv.slice(1);
+const refuse = (why) => {
+ process.stderr.write(why + "\n");
+ process.exit(1);
+};
+const sha256 = crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+const text = fs.readFileSync(signatureFile, "utf8").trim();
+const signature = /^[A-Za-z0-9+/]+={0,2}$/.test(text) ? Buffer.from(text, "base64") : null;
+if (!signature || signature.length !== 64) refuse("The release signature is not a base64 Ed25519 signature.");
+const message = Buffer.from(`switch-agent-controller-release-v1\n${version}\n${sha256}\n`, "utf8");
+const ids = [];
+for (const line of (process.env.TRUSTED_RELEASE_KEYS || "").split("\n")) {
+ const [id, key] = line.trim().split(/\s+/);
+ if (!id) continue;
+ ids.push(id);
+ const publicKey = crypto.createPublicKey({ key: Buffer.from(key || "", "base64"), format: "der", type: "spki" });
+ if (publicKey.asymmetricKeyType !== "ed25519") refuse(`Trusted release key ${id} is not an Ed25519 key.`);
+ if (crypto.verify(null, message, publicKey, signature)) {
+ process.stdout.write(id);
+ process.exit(0);
+ }
+}
+if (ids.length === 0) refuse("This installer trusts no release signing key.");
+refuse(`The release signature does not verify switch-agent-controller ${version} with SHA-256 ${sha256} against any trusted release key (${ids.join(", ")}).`);
+'
+# END VERIFY RELEASE
+
SERVER=""
CODE=""
NAME=""
@@ -60,6 +105,8 @@ command -v node >/dev/null 2>&1 || fail "Node 22.13 or later is needed (https://
command -v npm >/dev/null 2>&1 || fail "npm is needed; it comes with Node."
node -e 'const [a, b] = process.versions.node.split(".").map(Number); process.exit(a > 22 || (a === 22 && b >= 13) ? 0 : 1)' ||
fail "Node $(node --version) is too old; the controller needs 22.13 or later."
+[ -n "$(printf '%s' "$TRUSTED_RELEASE_KEYS" | tr -d '[:space:]')" ] ||
+ fail "This installer trusts no release signing key yet, so it installs no release: it could not tell a signed release from any other package."
if [ -n "$VERSION" ]; then
case "$VERSION" in
@@ -69,7 +116,7 @@ if [ -n "$VERSION" ]; then
else
# The repository also releases Switch and Switch Console: take the highest
# controller release that carries its package, leaving out drafts and prereleases.
- URL="$(curl -fsSL -H 'Accept: application/vnd.github+json' "https://api.github.com/repos/$REPO/releases?per_page=100" |
+ FOUND="$(curl -fsSL -H 'Accept: application/vnd.github+json' "https://api.github.com/repos/$REPO/releases?per_page=100" |
TAG_PREFIX="$TAG_PREFIX" node -e '
let input = "";
process.stdin.on("data", (chunk) => (input += chunk));
@@ -86,11 +133,28 @@ else
const order = (x, y) => x[0] - y[0] || x[1] - y[1] || x[2] - y[2];
if (!best || order(parts, best.parts) > 0) best = { parts, url: asset.browser_download_url };
}
- if (best) process.stdout.write(best.url);
+ if (best) process.stdout.write(`${best.parts.join(".")} ${best.url}`);
});
')" || fail "Could not list the releases of $REPO."
- [ -n "$URL" ] || fail "$REPO has no switch-agent-controller release yet."
+ [ -n "$FOUND" ] || fail "$REPO has no switch-agent-controller release yet."
+ VERSION="${FOUND%% *}"
+ URL="${FOUND#* }"
fi
+case "$URL" in
+ https://*) ;;
+ *) fail "The release package must be downloaded over https, not from $URL." ;;
+esac
+
+WORK="$(mktemp -d)"
+trap 'rm -rf "$WORK"' EXIT
+PACKAGE="$WORK/switch-agent-controller-$VERSION.tgz"
+echo "Downloading $URL"
+curl -fsSL -o "$PACKAGE" "$URL" || fail "Could not download $URL."
+curl -fsSL -o "$PACKAGE.sig" "$URL.sig" ||
+ fail "Could not download $URL.sig: the release has no signature, and only signed releases are installed."
+KEY_ID="$(TRUSTED_RELEASE_KEYS="$TRUSTED_RELEASE_KEYS" node -e "$VERIFY_RELEASE_JS" "$PACKAGE" "$PACKAGE.sig" "$VERSION")" ||
+ fail "$URL is not a release signed with a trusted key; nothing was installed."
+echo "The package is signed with trusted release key $KEY_ID."
PREFIX="$(npm config get prefix)"
if [ ! -w "$PREFIX" ] && [ ! -w "$PREFIX/lib/node_modules" ]; then
@@ -99,8 +163,8 @@ if [ ! -w "$PREFIX" ] && [ ! -w "$PREFIX/lib/node_modules" ]; then
mkdir -p "$PREFIX"
fi
-echo "Installing $URL"
-npm install --global --prefix "$PREFIX" "$URL"
+echo "Installing switch-agent-controller $VERSION"
+npm install --global --ignore-scripts --prefix "$PREFIX" "$PACKAGE"
BIN="$PREFIX/bin/switch-agent-controller"
[ -x "$BIN" ] || fail "npm did not install $BIN."
case ":$PATH:" in
diff --git a/console/packages/agent-controller/scripts/generate-release-signing-key.mjs b/console/packages/agent-controller/scripts/generate-release-signing-key.mjs
new file mode 100644
index 000000000..138d1f27f
--- /dev/null
+++ b/console/packages/agent-controller/scripts/generate-release-signing-key.mjs
@@ -0,0 +1,39 @@
+import { generateKeyPairSync } from 'node:crypto';
+
+/**
+ * Generates a controller release signing key pair (Ed25519):
+ *
+ * node scripts/generate-release-signing-key.mjs <key id>
+ *
+ * Prints, on stdout, the entry to add to TRUSTED_RELEASE_KEYS in
+ * src/release-keys.ts, the matching line for install.sh's TRUSTED RELEASE KEYS
+ * block, and the private key as PKCS#8 PEM, which goes into the
+ * CONTROLLER_RELEASE_SIGNING_KEY GitHub Actions secret and nowhere else. Run
+ * it on a machine you trust and do not keep the private key in a file. See
+ * "Release signing" in RELEASING.md.
+ */
+const id = process.argv[2];
+if (!id || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(id)) {
+ process.stderr.write(
+ 'usage: node scripts/generate-release-signing-key.mjs <key id>\n' +
+ 'The id names the key in the trusted list, e.g. release-2026-10: letters, digits, ".", "_" and "-".\n'
+ );
+ process.exit(2);
+}
+const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+const spki = publicKey.export({ type: 'spki', format: 'der' }).toString('base64');
+const pem = privateKey.export({ type: 'pkcs8', format: 'pem' });
+
+process.stdout.write(
+ [
+ '# 1. Add to TRUSTED_RELEASE_KEYS in src/release-keys.ts:',
+ ` { id: '${id}', publicKey: '${spki}' },`,
+ '',
+ "# 2. Add between install.sh's BEGIN/END TRUSTED RELEASE KEYS lines, inside the quotes:",
+ `${id} ${spki}`,
+ '',
+ '# 3. Store as the CONTROLLER_RELEASE_SIGNING_KEY GitHub Actions secret (then discard):',
+ pem.trimEnd(),
+ '',
+ ].join('\n')
+);
diff --git a/console/packages/agent-controller/scripts/sign-release.mjs b/console/packages/agent-controller/scripts/sign-release.mjs
new file mode 100644
index 000000000..76ba97701
--- /dev/null
+++ b/console/packages/agent-controller/scripts/sign-release.mjs
@@ -0,0 +1,57 @@
+import { createHash, createPrivateKey, createPublicKey, sign, verify } from 'node:crypto';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Signs a packaged controller release:
+ *
+ * CONTROLLER_RELEASE_SIGNING_KEY=<PKCS#8 PEM> node scripts/sign-release.mjs <package .tgz> <version>
+ *
+ * Writes `<package>.sig`: the Ed25519 signature, base64 on one line, of
+ *
+ * switch-agent-controller-release-v1\n<version>\n<sha256 of the package>\n
+ *
+ * which the controller (src/release-signing.ts) and install.sh check before
+ * they install a release. Fails when the key is missing, is not Ed25519, or
+ * its public key is not in src/release-keys.ts: a release no controller trusts
+ * is not worth publishing.
+ */
+const [file, version] = process.argv.slice(2);
+if (!file || !version) {
+ process.stderr.write('usage: node scripts/sign-release.mjs <package .tgz> <version>\n');
+ process.exit(2);
+}
+if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z]+(?:\.[0-9A-Za-z]+)*)?$/.test(version))
+ throw new Error(`The version must be x.y.z or x.y.z-<prerelease>, not '${version}'.`);
+const pem = process.env.CONTROLLER_RELEASE_SIGNING_KEY;
+if (!pem?.trim())
+ throw new Error(
+ 'CONTROLLER_RELEASE_SIGNING_KEY is not set: a published controller release must be signed. See "Release signing" in RELEASING.md.'
+ );
+const privateKey = createPrivateKey(pem);
+if (privateKey.asymmetricKeyType !== 'ed25519')
+ throw new Error('CONTROLLER_RELEASE_SIGNING_KEY must be an Ed25519 private key (PKCS#8 PEM).');
+const spki = createPublicKey(privateKey).export({ type: 'spki', format: 'der' }).toString('base64');
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..');
+const trusted = [
+ ...readFileSync(join(root, 'src', 'release-keys.ts'), 'utf8').matchAll(
+ /\{\s*id:\s*'([^']+)',\s*publicKey:\s*'([^']+)'\s*\}/g
+ ),
+].map((match) => ({ id: match[1], publicKey: match[2] }));
+const key = trusted.find((candidate) => candidate.publicKey === spki);
+if (!key)
+ throw new Error(
+ `The signing key's public key (${spki}) is not in src/release-keys.ts, so no controller would install this release. Add it there (and to install.sh) first.`
+ );
+
+const sha256 = createHash('sha256').update(readFileSync(file)).digest('hex');
+const message = Buffer.from(`switch-agent-controller-release-v1\n${version}\n${sha256}\n`, 'utf8');
+const signature = sign(null, message, privateKey);
+if (!verify(null, message, createPublicKey(privateKey), signature))
+ throw new Error('The signature just made does not verify.');
+writeFileSync(`${file}.sig`, `${signature.toString('base64')}\n`);
+process.stdout.write(
+ `Signed switch-agent-controller ${version} (SHA-256 ${sha256}) with release key ${key.id}: ${file}.sig\n`
+);
diff --git a/console/packages/agent-controller/src/main.ts b/console/packages/agent-controller/src/main.ts
index 745fa1685..e774d6956 100644
--- a/console/packages/agent-controller/src/main.ts
+++ b/console/packages/agent-controller/src/main.ts
@@ -50,6 +50,8 @@ import { dataLayout, ensureDataDir, resolveDataDir, serverWorkspacesDir } from '
import { ProviderRechecks } from './provider-rechecks';
import { readProviderSeed, writeProviderSeed } from './provider-seed';
import { definitionProblem } from './reconcile';
+import { TRUSTED_RELEASE_KEYS } from './release-keys';
+import { assertTrustedKeys, verifyDownloadedRelease } from './release-signing';
import { isManagedRelease, readCurrent, throughCurrent } from './releases';
import { emptyObservation, InProcessRuntime, observeOnDisk, probeProvider } from './runtime';
import { AgentRuntimes } from './runtimes';
@@ -74,7 +76,9 @@ import {
type ReleaseInstaller,
ReleasesDirInstaller,
runInstallCommand,
+ SELF_UPDATE_OFF,
SelfUpdater,
+ selfUpdateTurnedOff,
unavailableInstaller,
} from './self-update';
import {
@@ -127,7 +131,7 @@ Commands:
run [--data-dir <dir>] [--shared-host-bundle <path>]
[--controller-id <id> --server <agent-bridge-url> [--name <name>]]
[--credential-stdin] [--agent-runtime default|separate-user]
- [--releases-dir <dir> | --updated-by-console]
+ [--releases-dir <dir> | --updated-by-console] [--no-self-update]
Run the agents assigned to this machine and report their status.
--agent-runtime separate-user runs every agent as a Linux user of its
own, as set up by install-service --separate-users.
@@ -139,7 +143,10 @@ Commands:
the releases Switch names, beside the ones before.
--updated-by-console, which Switch Console passes to a controller it
runs on an SSH host, says Console updates it: it follows no release
- Switch names, and tells Switch so. --provider-seed <file> takes the
+ Switch names, and tells Switch so. --no-self-update (or
+ SWITCH_CONTROLLER_SELF_UPDATE=off in the environment or the env file)
+ turns following the release Switch names off on this machine; it
+ reports why when Switch names another. --provider-seed <file> takes the
provider checks precheck wrote, so the first report carries them.
precheck --out <file> --probe-dir <dir> [--shared-host-bundle <path>]
Check every provider's installation and sign-in as run would, with no
@@ -185,7 +192,8 @@ Commands:
--check only says whether there is one.
When Switch names a release for this controller, run installs it once no
-session runs and exits 7 for its service to start it again on it.
+session runs and exits 7 for its service to start it again on it. run and
+update install only a release signed with a key built into this controller.
run, install-service and doctor --env-file read NAME=value lines (as for
systemd's EnvironmentFile) into the agents' environment: provider API keys, or
@@ -467,6 +475,7 @@ async function runCommand(args: string[]): Promise<number> {
'agent-runtime': { type: 'string' },
'releases-dir': { type: 'string' },
'updated-by-console': { type: 'boolean' },
+ 'no-self-update': { type: 'boolean' },
'provider-seed': { type: 'string' },
},
strict: true,
@@ -486,6 +495,7 @@ async function runCommand(args: string[]): Promise<number> {
// Before anything reads the environment: the agents inherit it.
const fromFile = values['env-file'] ? await readEnvFile(resolve(values['env-file'])) : {};
Object.assign(process.env, fromFile);
+ const selfUpdateOff = selfUpdateTurnedOff(values['no-self-update'] === true, process.env);
const controllerId = values['controller-id'];
if ((controllerId === undefined) !== (values.server === undefined))
throw new UsageError('--controller-id and --server adopt an identity together; pass both.');
@@ -568,16 +578,19 @@ async function runCommand(args: string[]): Promise<number> {
updatedBy === 'self'
? new SelfUpdater({
version: VERSION,
- installer: await installerFor(
- separateUsers,
- releasesDir,
- updateNpm(dataDir),
- process.platform
- ),
+ installer: selfUpdateOff
+ ? unavailableInstaller(SELF_UPDATE_OFF)
+ : await installerFor(
+ separateUsers,
+ releasesDir,
+ updateNpm(dataDir),
+ process.platform
+ ),
download: (release, signal) =>
downloadVerified({
fetch,
release,
+ keys: TRUSTED_RELEASE_KEYS,
dir: updatesDir(dataDir),
maxBytes: MAX_PACKAGE_BYTES,
signal,
@@ -1111,15 +1124,26 @@ async function updateCommand(args: string[]): Promise<number> {
throw new ConfigurationError(
`This controller runs from ${prefix}, a releases directory install-service set up: it installs the release Switch names itself, once no session is mid-turn. To install another by hand, install it with npm and run install-service again.`
);
+ assertTrustedKeys(TRUSTED_RELEASE_KEYS);
const dataDir = resolveDataDir(values['data-dir']);
process.stdout.write(`Installing ${latest.version} from ${latest.packageUrl}\n`);
- const { file } = await downloadPackage({
+ const { file, sha256 } = await downloadPackage({
fetch,
url: latest.packageUrl,
dir: updatesDir(dataDir),
maxBytes: MAX_PACKAGE_BYTES,
signal: null,
});
+ const keyId = await verifyDownloadedRelease({
+ fetch,
+ file,
+ url: latest.packageUrl,
+ version: latest.version,
+ sha256,
+ keys: TRUSTED_RELEASE_KEYS,
+ signal: null,
+ });
+ process.stdout.write(`The package is signed with trusted release key ${keyId}.\n`);
try {
await npmInstall(updateNpm(dataDir), prefix, file, null);
} catch (error) {
diff --git a/console/packages/agent-controller/src/release-keys.test.ts b/console/packages/agent-controller/src/release-keys.test.ts
new file mode 100644
index 000000000..0c70fca7e
--- /dev/null
+++ b/console/packages/agent-controller/src/release-keys.test.ts
@@ -0,0 +1,148 @@
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { TRUSTED_RELEASE_KEYS } from './release-keys';
+import { publicKeyOf } from './release-signing';
+import { signRelease, testSigningKey } from './testing/release-signing';
+
+const installSh = readFileSync(
+ join(dirname(fileURLToPath(import.meta.url)), '..', 'install.sh'),
+ 'utf8'
+);
+
+/** The text between `# BEGIN <name>` and `# END <name>` in install.sh, inside its single quotes. */
+function installShBlock(name: string): string {
+ const match = new RegExp(`# BEGIN ${name}\\n[A-Z_]+='([^']*)'\\n# END ${name}\\n`).exec(
+ installSh
+ );
+ if (!match) throw new Error(`install.sh has no ${name} block.`);
+ return match[1]!;
+}
+
+describe('TRUSTED_RELEASE_KEYS', () => {
+ it('lists Ed25519 public keys under ids of their own', () => {
+ for (const key of TRUSTED_RELEASE_KEYS) expect(() => publicKeyOf(key)).not.toThrow();
+ const ids = TRUSTED_RELEASE_KEYS.map((key) => key.id);
+ expect(new Set(ids).size).toBe(ids.length);
+ for (const id of ids) expect(id).toMatch(/^[A-Za-z0-9][A-Za-z0-9._-]*$/);
+ });
+
+ it('is the list install.sh carries', () => {
+ const lines = installShBlock('TRUSTED RELEASE KEYS')
+ .split('\n')
+ .map((line) => line.trim())
+ .filter(Boolean)
+ .map((line) => {
+ const [id, publicKey, ...rest] = line.split(/\s+/);
+ expect(rest).toEqual([]);
+ return { id, publicKey };
+ });
+ expect(lines).toEqual(TRUSTED_RELEASE_KEYS.map(({ id, publicKey }) => ({ id, publicKey })));
+ });
+});
+
+describe("install.sh's signature check", () => {
+ let dir: string;
+ beforeEach(() => {
+ dir = mkdtempSync(join(tmpdir(), 'install-sh-verify-'));
+ });
+ afterEach(() => {
+ rmSync(dir, { recursive: true, force: true });
+ });
+
+ const script = installShBlock('VERIFY RELEASE');
+ const key = testSigningKey('release-test');
+ const other = testSigningKey('release-other');
+
+ /** Runs the check as install.sh does; its stdout, or the error it fails with. */
+ function check(signature: string, keys: string, version = '0.31.0') {
+ const file = join(dir, 'package.tgz');
+ writeFileSync(file, 'a package');
+ writeFileSync(`${file}.sig`, signature);
+ try {
+ return {
+ ok: true,
+ out: execFileSync(process.execPath, ['-e', script, file, `${file}.sig`, version], {
+ env: { TRUSTED_RELEASE_KEYS: keys },
+ encoding: 'utf8',
+ stdio: ['ignore', 'pipe', 'pipe'],
+ }),
+ };
+ } catch (error) {
+ return { ok: false, out: String((error as { stderr?: string }).stderr) };
+ }
+ }
+
+ const sha = createHash('sha256').update('a package').digest('hex');
+ const line = (k: typeof key) => `${k.trusted.id} ${k.trusted.publicKey}`;
+
+ it('accepts a release signed with a listed key, and names the key', () => {
+ expect(check(signRelease(key, '0.31.0', sha), `\n${line(other)}\n${line(key)}\n`)).toEqual({
+ ok: true,
+ out: 'release-test',
+ });
+ });
+
+ it('refuses a wrong key, a tampered package, another version, garbage, and no keys', () => {
+ expect(check(signRelease(other, '0.31.0', sha), line(key))).toMatchObject({
+ ok: false,
+ out: expect.stringMatching(/does not verify/),
+ });
+ expect(check(signRelease(key, '0.31.0', 'c'.repeat(64)), line(key)).ok).toBe(false);
+ expect(check(signRelease(key, '0.30.0', sha), line(key)).ok).toBe(false);
+ expect(check('nonsense', line(key))).toMatchObject({
+ ok: false,
+ out: expect.stringMatching(/not a base64 Ed25519 signature/),
+ });
+ expect(check(signRelease(key, '0.31.0', sha), '\n')).toMatchObject({
+ ok: false,
+ out: expect.stringMatching(/trusts no release signing key/),
+ });
+ });
+});
+
+describe('scripts/sign-release.mjs', () => {
+ const signScript = join(
+ dirname(fileURLToPath(import.meta.url)),
+ '..',
+ 'scripts',
+ 'sign-release.mjs'
+ );
+ let dir: string;
+ beforeEach(() => {
+ dir = mkdtempSync(join(tmpdir(), 'sign-release-'));
+ });
+ afterEach(() => {
+ rmSync(dir, { recursive: true, force: true });
+ });
+
+ function sign(env: Record<string, string>) {
+ const file = join(dir, 'switch-agent-controller-0.31.0.tgz');
+ writeFileSync(file, 'a package');
+ try {
+ execFileSync(process.execPath, [signScript, file, '0.31.0'], {
+ env,
+ encoding: 'utf8',
+ stdio: ['ignore', 'pipe', 'pipe'],
+ });
+ return '';
+ } catch (error) {
+ return String((error as { stderr?: string }).stderr);
+ }
+ }
+
+ it('fails loud with no signing key', () => {
+ expect(sign({})).toMatch(/CONTROLLER_RELEASE_SIGNING_KEY is not set/);
+ });
+
+ it('refuses a key whose public half no controller trusts', () => {
+ const key = testSigningKey('untrusted');
+ const pem = key.privateKey.export({ type: 'pkcs8', format: 'pem' }).toString();
+ const said = sign({ CONTROLLER_RELEASE_SIGNING_KEY: pem });
+ expect(said).toMatch(/is not in src\/release-keys.ts/);
+ });
+});
diff --git a/console/packages/agent-controller/src/release-keys.ts b/console/packages/agent-controller/src/release-keys.ts
new file mode 100644
index 000000000..8b90ca8fd
--- /dev/null
+++ b/console/packages/agent-controller/src/release-keys.ts
@@ -0,0 +1,26 @@
+/**
+ * The Ed25519 public keys a controller release must be signed with before
+ * this controller installs it, by `run` (the release Switch names) or by
+ * `update`. Built into the controller, so whoever runs the Switch server it
+ * talks to cannot name a package of their own: they can only name one the
+ * release workflows signed.
+ *
+ * Each key is `{ id, publicKey }`, `publicKey` being the key's SubjectPublicKeyInfo
+ * (DER) in base64, as `scripts/generate-release-signing-key.mjs` prints it. A
+ * release verifies when any key here verifies it, so rotating adds the new key,
+ * ships a release with both, switches the signing secret, and only then removes
+ * the old one. See "Release signing" in RELEASING.md.
+ *
+ * `install.sh` carries a copy of this list (between its TRUSTED RELEASE KEYS
+ * markers); `release-keys.test.ts` fails when the two differ.
+ *
+ * With no key here, the controller installs no release at all, and says so.
+ */
+export type TrustedReleaseKey = { id: string; publicKey: string };
+
+export const TRUSTED_RELEASE_KEYS: readonly TrustedReleaseKey[] = [
+ {
+ id: 'release-2026-10',
+ publicKey: 'MCowBQYDK2VwAyEAaRFfp1Yd/b91KkZs8Vj/OQSdsZS2ifd+rZu24pKTMpU=',
+ },
+];
diff --git a/console/packages/agent-controller/src/release-signing.test.ts b/console/packages/agent-controller/src/release-signing.test.ts
new file mode 100644
index 000000000..f7d645370
--- /dev/null
+++ b/console/packages/agent-controller/src/release-signing.test.ts
@@ -0,0 +1,132 @@
+import { createHash, generateKeyPairSync } from 'node:crypto';
+import { mkdtempSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import {
+ fetchSignature,
+ NO_TRUSTED_KEYS,
+ signatureUrl,
+ signedMessage,
+ verifyDownloadedRelease,
+ verifyReleaseSignature,
+} from './release-signing';
+import { signRelease, testSigningKey } from './testing/release-signing';
+
+const SHA = createHash('sha256').update('a package').digest('hex');
+const current = testSigningKey('release-current');
+const next = testSigningKey('release-next');
+const stranger = testSigningKey('someone-else');
+
+describe('signedMessage', () => {
+ it('names the scheme, the version and the SHA-256 in lower case, one per line', () => {
+ expect(signedMessage('0.31.0', SHA.toUpperCase())).toBe(
+ `switch-agent-controller-release-v1\n0.31.0\n${SHA}\n`
+ );
+ });
+});
+
+describe('signatureUrl', () => {
+ it('is the package path with .sig, the query kept', () => {
+ expect(signatureUrl('https://example.invalid/r/switch-agent-controller-0.31.0.tgz')).toBe(
+ 'https://example.invalid/r/switch-agent-controller-0.31.0.tgz.sig'
+ );
+ expect(signatureUrl('https://example.invalid/p.tgz?token=x')).toBe(
+ 'https://example.invalid/p.tgz.sig?token=x'
+ );
+ });
+});
+
+describe('verifyReleaseSignature', () => {
+ const verifying = (signature: string, keys = [current.trusted], version = '0.31.0') =>
+ verifyReleaseSignature({ version, sha256: SHA, signature, keys });
+
+ it('names the trusted key that verifies a signature', () => {
+ expect(verifying(signRelease(current, '0.31.0', SHA))).toBe('release-current');
+ });
+
+ it('accepts any trusted key, so keys can be rotated', () => {
+ const both = [current.trusted, next.trusted];
+ expect(verifying(signRelease(next, '0.31.0', SHA), both)).toBe('release-next');
+ expect(verifying(signRelease(current, '0.31.0', SHA), both)).toBe('release-current');
+ });
+
+ it('refuses a signature by a key it does not trust', () => {
+ expect(() => verifying(signRelease(stranger, '0.31.0', SHA))).toThrow(
+ /does not verify switch-agent-controller 0.31.0 .* \(release-current\)/
+ );
+ });
+
+ it('refuses a signature made for another SHA-256 or another version', () => {
+ expect(() => verifying(signRelease(current, '0.31.0', 'b'.repeat(64)))).toThrow(
+ /does not verify/
+ );
+ expect(() => verifying(signRelease(current, '0.30.0', SHA))).toThrow(/does not verify/);
+ expect(() =>
+ verifying(signRelease(current, '0.31.0', SHA), [current.trusted], '0.32.0')
+ ).toThrow(/does not verify/);
+ });
+
+ it('refuses what is not a signature', () => {
+ for (const signature of ['', 'not base64!', Buffer.alloc(63).toString('base64')])
+ expect(() => verifying(signature)).toThrow(/not a base64 Ed25519 signature/);
+ });
+
+ it('refuses everything with no trusted key', () => {
+ expect(() => verifying(signRelease(current, '0.31.0', SHA), [])).toThrow(NO_TRUSTED_KEYS);
+ });
+
+ it('refuses a trusted key that is not Ed25519', () => {
+ const { publicKey } = generateKeyPairSync('ec', { namedCurve: 'P-256' });
+ const ec = {
+ id: 'ec',
+ publicKey: publicKey.export({ type: 'spki', format: 'der' }).toString('base64'),
+ };
+ expect(() => verifying(signRelease(current, '0.31.0', SHA), [ec])).toThrow(/not an Ed25519/);
+ });
+});
+
+describe('fetching and verifying a downloaded release', () => {
+ let dir: string;
+ beforeEach(() => {
+ dir = mkdtempSync(join(tmpdir(), 'release-signing-'));
+ });
+ afterEach(() => {
+ rmSync(dir, { recursive: true, force: true });
+ });
+
+ const url = 'https://example.invalid/switch-agent-controller-0.31.0.tgz';
+ const answering = (status: number, body: string) =>
+ (async (requested: string | URL | Request) => {
+ expect(String(requested)).toBe(`${url}.sig`);
+ return new Response(body, { status });
+ }) as typeof fetch;
+
+ it('fails loud when the release has no signature', async () => {
+ await expect(fetchSignature(answering(404, 'no'), url, null)).rejects.toThrow(
+ /has no signature: fetching .*\.sig answered 404/
+ );
+ });
+
+ it('keeps a package whose signature verifies, and deletes one whose does not', async () => {
+ const file = join(dir, 'package.tgz');
+ writeFileSync(file, 'a package');
+ const common = { file, url, version: '0.31.0', sha256: SHA, signal: null };
+ expect(
+ await verifyDownloadedRelease({
+ ...common,
+ fetch: answering(200, signRelease(current, '0.31.0', SHA)),
+ keys: [current.trusted],
+ })
+ ).toBe('release-current');
+ expect(readdirSync(dir)).toEqual(['package.tgz']);
+ await expect(
+ verifyDownloadedRelease({
+ ...common,
+ fetch: answering(200, signRelease(stranger, '0.31.0', SHA)),
+ keys: [current.trusted],
+ })
+ ).rejects.toThrow(/does not verify.*was deleted/);
+ expect(readdirSync(dir)).toEqual([]);
+ });
+});
diff --git a/console/packages/agent-controller/src/release-signing.ts b/console/packages/agent-controller/src/release-signing.ts
new file mode 100644
index 000000000..221a430cc
--- /dev/null
+++ b/console/packages/agent-controller/src/release-signing.ts
@@ -0,0 +1,117 @@
+import { createPublicKey, type KeyObject, verify } from 'node:crypto';
+import { rm } from 'node:fs/promises';
+import type { Fetch } from './api';
+import type { TrustedReleaseKey } from './release-keys';
+
+/**
+ * Release signatures. The release workflows sign, with Ed25519, the message
+ *
+ * switch-agent-controller-release-v1\n<version>\n<sha256>\n
+ *
+ * (`<sha256>` the package's digest in lowercase hex), and publish the
+ * signature, base64 on one line, beside the package as `<package>.sig`. The
+ * message binds the version as well as the bytes, so a signed package cannot be
+ * offered as another version than the one it was released as.
+ */
+export const SIGNED_MESSAGE_PREFIX = 'switch-agent-controller-release-v1';
+
+/** The largest signature file read: a signature is 88 base64 characters. */
+const MAX_SIGNATURE_BYTES = 1024;
+const SIGNATURE_TIMEOUT_MS = 60 * 1000;
+
+export const NO_TRUSTED_KEYS =
+ 'This controller build trusts no release signing key (src/release-keys.ts is empty), so it installs no release: it could not tell a release the workflows signed from any other package. Install a release that carries a signing key by hand.';
+
+/** What a release signature signs, for `version` and the package's SHA-256. */
+export function signedMessage(version: string, sha256: string): string {
+ return `${SIGNED_MESSAGE_PREFIX}\n${version}\n${sha256.toLowerCase()}\n`;
+}
+
+/** Where the signature of the package at `packageUrl` is: `<path>.sig`, the query kept. */
+export function signatureUrl(packageUrl: string): string {
+ const url = new URL(packageUrl);
+ url.pathname = `${url.pathname}.sig`;
+ return url.toString();
+}
+
+/** Throws when `keys` is empty: nothing could be verified. */
+export function assertTrustedKeys(keys: readonly TrustedReleaseKey[]): void {
+ if (keys.length === 0) throw new Error(NO_TRUSTED_KEYS);
+}
+
+/** A trusted key as a key object; throws when it is not an Ed25519 public key. */
+export function publicKeyOf(key: TrustedReleaseKey): KeyObject {
+ const object = createPublicKey({
+ key: Buffer.from(key.publicKey, 'base64'),
+ format: 'der',
+ type: 'spki',
+ });
+ if (object.asymmetricKeyType !== 'ed25519')
+ throw new Error(`Trusted release key ${key.id} is not an Ed25519 key.`);
+ return object;
+}
+
+/**
+ * Checks `signature` (the `.sig` file's text) over `version` and `sha256`
+ * against `keys`; the id of the key that verifies it. Throws when none does.
+ */
+export function verifyReleaseSignature(input: {
+ version: string;
+ sha256: string;
+ signature: string;
+ keys: readonly TrustedReleaseKey[];
+}): string {
+ assertTrustedKeys(input.keys);
+ const text = input.signature.trim();
+ const bytes = /^[A-Za-z0-9+/]+={0,2}$/.test(text) ? Buffer.from(text, 'base64') : null;
+ if (!bytes || bytes.length !== 64)
+ throw new Error('The release signature is not a base64 Ed25519 signature.');
+ const message = Buffer.from(signedMessage(input.version, input.sha256), 'utf8');
+ for (const key of input.keys) if (verify(null, message, publicKeyOf(key), bytes)) return key.id;
+ throw new Error(
+ `The release signature does not verify switch-agent-controller ${input.version} with SHA-256 ${input.sha256} against any trusted release key (${input.keys.map((key) => key.id).join(', ')}).`
+ );
+}
+
+/** Fetches the signature published beside the package at `packageUrl`. */
+export async function fetchSignature(
+ fetch: Fetch,
+ packageUrl: string,
+ signal: AbortSignal | null
+): Promise<string> {
+ const url = signatureUrl(packageUrl);
+ const signals = [AbortSignal.timeout(SIGNATURE_TIMEOUT_MS), ...(signal ? [signal] : [])];
+ const response = await fetch(url, { signal: AbortSignal.any(signals) });
+ if (!response.ok)
+ throw new Error(
+ `The release has no signature: fetching ${url} answered ${response.status}. A controller installs only signed releases.`
+ );
+ const body = new Uint8Array(await response.arrayBuffer());
+ if (body.byteLength > MAX_SIGNATURE_BYTES)
+ throw new Error(`${url} is ${body.byteLength} bytes, too large for a release signature.`);
+ return new TextDecoder().decode(body);
+}
+
+/**
+ * Fetches the signature of the package downloaded to `file` from `url` and
+ * verifies it for `version` and the package's `sha256`; a package whose
+ * signature is missing or does not verify is deleted.
+ */
+export async function verifyDownloadedRelease(input: {
+ fetch: Fetch;
+ file: string;
+ url: string;
+ version: string;
+ sha256: string;
+ keys: readonly TrustedReleaseKey[];
+ signal: AbortSignal | null;
+}): Promise<string> {
+ try {
+ const signature = await fetchSignature(input.fetch, input.url, input.signal);
+ return verifyReleaseSignature({ ...input, signature });
+ } catch (error) {
+ await rm(input.file, { force: true });
+ const said = error instanceof Error ? error.message : String(error);
+ throw new Error(`${said} The package from ${input.url} was deleted.`, { cause: error });
+ }
+}
diff --git a/console/packages/agent-controller/src/self-update.test.ts b/console/packages/agent-controller/src/self-update.test.ts
index f66932f78..6defead29 100644
--- a/console/packages/agent-controller/src/self-update.test.ts
+++ b/console/packages/agent-controller/src/self-update.test.ts
@@ -14,10 +14,13 @@ import {
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { ConfigurationError } from './errors';
import { silentLogger } from './log';
+import { NO_TRUSTED_KEYS } from './release-signing';
import { packageDir } from './releases';
import {
type ControllerReleaseTarget,
+ downloadPackage,
downloadVerified,
type InstallRunner,
type NpmSetup,
@@ -26,11 +29,14 @@ import {
type ReleaseInstaller,
ReleasesDirInstaller,
RETRY_AFTER_MS,
+ SELF_UPDATE_OFF,
SelfUpdater,
+ selfUpdateTurnedOff,
type UpdateAttempt,
type UpdateHost,
unavailableInstaller,
} from './self-update';
+import { signRelease, testSigningKey } from './testing/release-signing';
let dir: string;
@@ -83,6 +89,7 @@ describe('readControllerRelease', () => {
'latest',
{ version: '0.31', url: 'https://example.invalid/a.tgz', sha256: SHA },
{ version: '0.31.0', url: 'ftp://example.invalid/a.tgz', sha256: SHA },
+ { version: '0.31.0', url: 'http://example.invalid/a.tgz', sha256: SHA },
{ version: '0.31.0', url: 'https://example.invalid/a.tgz', sha256: 'abc' },
{ version: '../../etc', url: 'https://example.invalid/a.tgz', sha256: SHA },
{ version: '0.31.0-dev..1', url: 'https://example.invalid/a.tgz', sha256: SHA },
@@ -95,13 +102,44 @@ describe('readControllerRelease', () => {
});
});
-function serving(body: Buffer, headers: Record<string, string> = {}): typeof fetch {
- return (async () => new Response(new Uint8Array(body), { status: 200, headers })) as typeof fetch;
+const KEY = testSigningKey('release-test');
+const KEYS = [KEY.trusted];
+
+/**
+ * Serves `body` at the package URL and, at `<url>.sig`, `signature` (by
+ * default the release signature of `body` as `release` names it); 404 for it
+ * when `signature` is null. Records the URLs fetched.
+ */
+function serving(
+ body: Buffer | (() => Response),
+ options: { headers?: Record<string, string>; signature?: string | null; version?: string } = {}
+) {
+ const fetched: string[] = [];
+ const version = options.version ?? '0.31.0';
+ const fetchImpl = (async (requested: string | URL | Request) => {
+ const url = String(requested);
+ fetched.push(url);
+ if (url.endsWith('.sig')) {
+ const signature =
+ options.signature === undefined
+ ? Buffer.isBuffer(body)
+ ? signRelease(KEY, version, createHash('sha256').update(body).digest('hex'))
+ : null
+ : options.signature;
+ return signature === null
+ ? new Response('not found', { status: 404 })
+ : new Response(signature, { status: 200 });
+ }
+ return Buffer.isBuffer(body)
+ ? new Response(new Uint8Array(body), { status: 200, headers: options.headers ?? {} })
+ : body();
+ }) as typeof fetch;
+ return { fetch: fetchImpl, fetched };
}
/** A body sent in chunks, with no Content-Length to go by. */
-function streaming(chunks: Buffer[]): typeof fetch {
- return (async () =>
+function streaming(chunks: Buffer[]): () => Response {
+ return () =>
new Response(
new ReadableStream({
start(controller) {
@@ -110,7 +148,7 @@ function streaming(chunks: Buffer[]): typeof fetch {
},
}),
{ status: 200 }
- )) as typeof fetch;
+ );
}
function releaseOf(body: Buffer, version = '0.31.0'): ControllerReleaseTarget {
@@ -122,67 +160,137 @@ function releaseOf(body: Buffer, version = '0.31.0'): ControllerReleaseTarget {
}
describe('downloadVerified', () => {
- it('keeps a package whose SHA-256 is the one Switch named', async () => {
- const body = Buffer.from('a package');
- const file = await downloadVerified({
- fetch: serving(body),
- release: releaseOf(body),
+ const download = (
+ served: ReturnType<typeof serving>,
+ release: ControllerReleaseTarget,
+ keys = KEYS
+ ) =>
+ downloadVerified({
+ fetch: served.fetch,
+ release,
+ keys,
dir: join(dir, 'updates'),
maxBytes: 1024,
signal: null,
});
+
+ it('keeps a package whose SHA-256 is the one Switch named and whose signature verifies', async () => {
+ const body = Buffer.from('a package');
+ const served = serving(body);
+ const file = await download(served, releaseOf(body));
expect(readFileSync(file)).toEqual(body);
expect(dirname(file)).toBe(join(dir, 'updates'));
+ expect(served.fetched).toEqual([
+ 'https://example.invalid/switch-agent-controller-0.31.0.tgz',
+ 'https://example.invalid/switch-agent-controller-0.31.0.tgz.sig',
+ ]);
});
it('deletes a package whose SHA-256 differs', async () => {
const body = Buffer.from('a package');
await expect(
- downloadVerified({
- fetch: serving(Buffer.from('another package')),
- release: releaseOf(body),
- dir: join(dir, 'updates'),
- maxBytes: 1024,
- signal: null,
- })
+ download(serving(Buffer.from('another package')), releaseOf(body))
).rejects.toThrow(/not the [0-9a-f]{64} Switch named/);
expect(readdirSync(join(dir, 'updates'))).toEqual([]);
});
+ it('deletes a package with no signature', async () => {
+ const body = Buffer.from('a package');
+ await expect(download(serving(body, { signature: null }), releaseOf(body))).rejects.toThrow(
+ /has no signature.*404.*was deleted/
+ );
+ expect(readdirSync(join(dir, 'updates'))).toEqual([]);
+ });
+
+ it('deletes a package signed by a key this controller does not trust', async () => {
+ const body = Buffer.from('a package');
+ const sha256 = createHash('sha256').update(body).digest('hex');
+ const signature = signRelease(testSigningKey('someone-else'), '0.31.0', sha256);
+ await expect(download(serving(body, { signature }), releaseOf(body))).rejects.toThrow(
+ /does not verify.*\(release-test\).*was deleted/
+ );
+ expect(readdirSync(join(dir, 'updates'))).toEqual([]);
+ });
+
+ it('deletes a package whose signature is for another version', async () => {
+ const body = Buffer.from('a package');
+ // Switch names a signed 0.30.0 package as 0.31.0, and gives its true SHA-256.
+ await expect(
+ download(serving(body, { version: '0.30.0' }), releaseOf(body, '0.31.0'))
+ ).rejects.toThrow(/does not verify switch-agent-controller 0.31.0/);
+ expect(readdirSync(join(dir, 'updates'))).toEqual([]);
+ });
+
+ it('deletes a package when Switch and the signature agree on a SHA-256 the bytes do not have', async () => {
+ const body = Buffer.from('a package');
+ const tampered = Buffer.from('a package, tampered');
+ await expect(
+ download(
+ serving(tampered, { signature: signRelease(KEY, '0.31.0', releaseOf(body).sha256) }),
+ releaseOf(body)
+ )
+ ).rejects.toThrow(/not the [0-9a-f]{64} Switch named/);
+ expect(readdirSync(join(dir, 'updates'))).toEqual([]);
+ });
+
+ it('downloads nothing while it trusts no signing key', async () => {
+ const body = Buffer.from('a package');
+ const served = serving(body);
+ await expect(download(served, releaseOf(body), [])).rejects.toThrow(NO_TRUSTED_KEYS);
+ expect(served.fetched).toEqual([]);
+ });
+
it('refuses a package larger than the cap, declared or sent', async () => {
const body = Buffer.alloc(2048, 1);
await expect(
- downloadVerified({
- fetch: serving(body, { 'content-length': '2048' }),
- release: releaseOf(body),
- dir: join(dir, 'updates'),
- maxBytes: 1024,
- signal: null,
- })
+ download(serving(body, { headers: { 'content-length': '2048' } }), releaseOf(body))
).rejects.toThrow(/2048 bytes, more than the 1024/);
await expect(
- downloadVerified({
- fetch: streaming([body.subarray(0, 1000), body.subarray(1000)]),
- release: releaseOf(body),
- dir: join(dir, 'updates'),
- maxBytes: 1024,
- signal: null,
- })
+ download(serving(streaming([body.subarray(0, 1000), body.subarray(1000)])), releaseOf(body))
).rejects.toThrow(/more than the 1024 bytes/);
expect(readdirSync(join(dir, 'updates'))).toEqual([]);
});
it('fails loud when the server refuses', async () => {
- const refusing = (async () => new Response('gone', { status: 404 })) as typeof fetch;
await expect(
- downloadVerified({
- fetch: refusing,
- release: releaseOf(Buffer.from('x')),
+ download(
+ serving(() => new Response('gone', { status: 404 })),
+ releaseOf(Buffer.from('x'))
+ )
+ ).rejects.toThrow(/404/);
+ });
+});
+
+describe('downloadPackage', () => {
+ it('refuses a URL that is not https, fetching nothing', async () => {
+ const served = serving(Buffer.from('a package'));
+ await expect(
+ downloadPackage({
+ fetch: served.fetch,
+ url: 'http://example.invalid/switch-agent-controller-0.31.0.tgz',
dir: join(dir, 'updates'),
maxBytes: 1024,
signal: null,
})
- ).rejects.toThrow(/404/);
+ ).rejects.toThrow(/over https only/);
+ expect(served.fetched).toEqual([]);
+ });
+});
+
+describe('selfUpdateTurnedOff', () => {
+ it('is off by the flag or SWITCH_CONTROLLER_SELF_UPDATE=off, on otherwise', () => {
+ expect(selfUpdateTurnedOff(false, {})).toBe(false);
+ expect(selfUpdateTurnedOff(false, { SWITCH_CONTROLLER_SELF_UPDATE: 'on' })).toBe(false);
+ expect(selfUpdateTurnedOff(false, { SWITCH_CONTROLLER_SELF_UPDATE: '' })).toBe(false);
+ expect(selfUpdateTurnedOff(false, { SWITCH_CONTROLLER_SELF_UPDATE: 'off' })).toBe(true);
+ expect(selfUpdateTurnedOff(false, { SWITCH_CONTROLLER_SELF_UPDATE: ' OFF ' })).toBe(true);
+ expect(selfUpdateTurnedOff(true, {})).toBe(true);
+ });
+
+ it('fails loud on a value it does not know', () => {
+ expect(() => selfUpdateTurnedOff(false, { SWITCH_CONTROLLER_SELF_UPDATE: 'no' })).toThrow(
+ ConfigurationError
+ );
});
});
@@ -266,6 +374,7 @@ describe.skipIf(process.platform === 'win32')('ReleasesDirInstaller', () => {
'npm',
'install',
'--global',
+ '--ignore-scripts',
'--prefix',
join(releases, '0.31.0.partial'),
join(dir, 'package-0.31.0.tgz'),
@@ -331,7 +440,14 @@ describe('PrefixInstaller', () => {
expect(npm.calls).toEqual([]);
await installer.activate('0.31.0', packageFile('0.31.0'));
expect(npm.calls.map((call) => call.slice(1))).toEqual([
- ['install', '--global', '--prefix', prefix, join(dir, 'package-0.31.0.tgz')],
+ [
+ 'install',
+ '--global',
+ '--ignore-scripts',
+ '--prefix',
+ prefix,
+ join(dir, 'package-0.31.0.tgz'),
+ ],
[cli, '--version'],
]);
});
@@ -509,6 +625,40 @@ describe('SelfUpdater', () => {
});
});
+ it('with self-update turned off, installs nothing and says so', async () => {
+ const { self, downloads } = updater({ installer: unavailableInstaller(SELF_UPDATE_OFF) });
+ const idle = host();
+ await self.offer(named, idle.lent);
+ expect(downloads).toEqual([]);
+ expect(idle.restarts()).toBe(0);
+ expect(self.status()).toEqual({
+ target: '0.31.0',
+ state: 'failed',
+ problem: expect.stringMatching(
+ /Self-update is turned off .*SWITCH_CONTROLLER_SELF_UPDATE=off/
+ ),
+ });
+ });
+
+ it('reports a release whose signature does not verify as failed, and does not install it', async () => {
+ const { installer, calls } = recordingInstaller();
+ const { self } = updater({
+ installer,
+ download: async () => {
+ throw new Error('The release signature does not verify switch-agent-controller 0.31.0.');
+ },
+ });
+ const idle = host();
+ await self.offer(named, idle.lent);
+ expect(calls).toEqual([]);
+ expect(idle.restarts()).toBe(0);
+ expect(self.status()).toEqual({
+ target: '0.31.0',
+ state: 'failed',
+ problem: 'The release signature does not verify switch-agent-controller 0.31.0.',
+ });
+ });
+
it('outside a service, installs and says a restart is needed rather than exiting', async () => {
const { installer, calls } = recordingInstaller();
const { self } = updater({ installer, supervised: false });
diff --git a/console/packages/agent-controller/src/self-update.ts b/console/packages/agent-controller/src/self-update.ts
index 7829a6d74..d366a2079 100644
--- a/console/packages/agent-controller/src/self-update.ts
+++ b/console/packages/agent-controller/src/self-update.ts
@@ -5,14 +5,19 @@ import { mkdir, open, rename, rm, stat } from 'node:fs/promises';
import { delimiter, dirname, join } from 'node:path';
import { z } from 'zod';
import type { Fetch } from './api';
+import { ConfigurationError } from './errors';
import { errorMessage, type Logger } from './log';
+import type { TrustedReleaseKey } from './release-keys';
+import { assertTrustedKeys, verifyDownloadedRelease } from './release-signing';
import { pointCurrent, prefixBin, pruneReleases, readCurrent } from './releases';
import { RELEASE_VERSION } from './update';
/**
* Updating this controller to the release Switch names in its status
- * responses (`controller_release`): fetched, checked against the SHA-256
- * Switch gave, installed, then switched to by exiting with `EXIT_RESTARTING`
+ * responses (`controller_release`): fetched over https, checked against the
+ * SHA-256 Switch gave and against the release signature, which only a key built
+ * into this controller (`release-keys.ts`) can make, installed with no install
+ * scripts run, then switched to by exiting with `EXIT_RESTARTING`
* for the service to start it again. Only while no session is in the middle
* of a turn: idle sessions are restarted with it and resume their
* conversations.
@@ -26,12 +31,32 @@ const DOWNLOAD_TIMEOUT_MS = 10 * 60 * 1000;
const INSTALL_TIMEOUT_MS = 10 * 60 * 1000;
const MAX_PROBLEM = 500;
+/** Turns following the release Switch names off on this machine: `off`, or `on` (the default). */
+export const SELF_UPDATE_ENV = 'SWITCH_CONTROLLER_SELF_UPDATE';
+
+/**
+ * Whether self-update is turned off, by `--no-self-update` or
+ * `SWITCH_CONTROLLER_SELF_UPDATE=off` (from the environment or the env file);
+ * any other value of it than `on` or `off` is a configuration error.
+ */
+export function selfUpdateTurnedOff(flag: boolean, env: NodeJS.ProcessEnv): boolean {
+ const value = env[SELF_UPDATE_ENV]?.trim().toLowerCase();
+ if (value !== undefined && value !== '' && value !== 'on' && value !== 'off')
+ throw new ConfigurationError(
+ `${SELF_UPDATE_ENV} must be on or off, not '${env[SELF_UPDATE_ENV]}'.`
+ );
+ return flag || value === 'off';
+}
+
+/** What a controller with self-update turned off reports when Switch names another release. */
+export const SELF_UPDATE_OFF = `Self-update is turned off on this machine (${SELF_UPDATE_ENV}=off or --no-self-update); install releases by hand (switch-agent-controller update), or turn it back on.`;
+
/** The release Switch names for this controller. */
export type ControllerReleaseTarget = { version: string; url: string; sha256: string };
const controllerReleaseSchema = z.object({
version: z.string().regex(RELEASE_VERSION, 'must be x.y.z or x.y.z-<prerelease>'),
- url: z.url({ protocol: /^https?$/ }),
+ url: z.url({ protocol: /^https$/ }),
sha256: z
.string()
.regex(/^[0-9a-fA-F]{64}$/, 'must be 64 hex digits')
@@ -66,6 +91,8 @@ export async function downloadPackage(input: {
maxBytes: number;
signal: AbortSignal | null;
}): Promise<{ file: string; sha256: string }> {
+ if (new URL(input.url).protocol !== 'https:')
+ throw new Error(`A controller package is downloaded over https only, not from ${input.url}.`);
await mkdir(input.dir, { recursive: true, mode: 0o700 });
const signals = [
AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
@@ -105,16 +132,20 @@ export async function downloadPackage(input: {
}
/**
- * Fetches the release into `dir` and checks it against the SHA-256 Switch
- * gave, the only one trusted: a file that differs is deleted.
+ * Fetches the release into `dir`, checks it against the SHA-256 Switch gave,
+ * then checks the signature published beside it (`<url>.sig`) against `keys`
+ * for that version and SHA-256: a file that fails either is deleted. With no
+ * trusted key, nothing is downloaded.
*/
export async function downloadVerified(input: {
fetch: Fetch;
release: ControllerReleaseTarget;
+ keys: readonly TrustedReleaseKey[];
dir: string;
maxBytes: number;
signal: AbortSignal | null;
}): Promise<string> {
+ assertTrustedKeys(input.keys);
const { file, sha256 } = await downloadPackage({ ...input, url: input.release.url });
if (sha256 !== input.release.sha256) {
await rm(file, { force: true });
@@ -122,6 +153,15 @@ export async function downloadVerified(input: {
`The package at ${input.release.url} has SHA-256 ${sha256}, not the ${input.release.sha256} Switch named; it was deleted.`
);
}
+ await verifyDownloadedRelease({
+ fetch: input.fetch,
+ file,
+ url: input.release.url,
+ version: input.release.version,
+ sha256,
+ keys: input.keys,
+ signal: input.signal,
+ });
return file;
}
@@ -181,8 +221,9 @@ function npmCommand(setup: NpmSetup): { file: string; env: NodeJS.ProcessEnv } {
}
/**
- * `npm install --global --prefix <prefix> <file>`: the package from the local
- * file, never a URL. With no prefix, into npm's own global one.
+ * `npm install --global --ignore-scripts --prefix <prefix> <file>`: the
+ * package from the local file, never a URL, with no lifecycle script run. With
+ * no prefix, into npm's own global one.
*/
export async function npmInstall(
setup: NpmSetup,
@@ -193,7 +234,7 @@ export async function npmInstall(
const npm = npmCommand(setup);
await setup.run(
npm.file,
- ['install', '--global', ...(prefix ? ['--prefix', prefix] : []), file],
+ ['install', '--global', '--ignore-scripts', ...(prefix ? ['--prefix', prefix] : []), file],
{
env: npm.env,
signal,
diff --git a/console/packages/agent-controller/src/testing/release-signing.ts b/console/packages/agent-controller/src/testing/release-signing.ts
new file mode 100644
index 000000000..971bcfdc2
--- /dev/null
+++ b/console/packages/agent-controller/src/testing/release-signing.ts
@@ -0,0 +1,22 @@
+import { generateKeyPairSync, type KeyObject, sign } from 'node:crypto';
+import type { TrustedReleaseKey } from '../release-keys';
+import { signedMessage } from '../release-signing';
+
+/** A release signing key made for a test, and the trusted-list entry for it. */
+export type TestSigningKey = { trusted: TrustedReleaseKey; privateKey: KeyObject };
+
+export function testSigningKey(id: string): TestSigningKey {
+ const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+ return {
+ trusted: {
+ id,
+ publicKey: publicKey.export({ type: 'spki', format: 'der' }).toString('base64'),
+ },
+ privateKey,
+ };
+}
+
+/** The `.sig` file a release workflow would publish for `version` and `sha256`. */
+export function signRelease(key: TestSigningKey, version: string, sha256: string): string {
+ return `${sign(null, Buffer.from(signedMessage(version, sha256)), key.privateKey).toString('base64')}\n`;
+}
diff --git a/core/switch_core/bridges/agent/operations/my_context.py b/core/switch_core/bridges/agent/operations/my_context.py
index 8de9cc008..d676d4589 100644
--- a/core/switch_core/bridges/agent/operations/my_context.py
+++ b/core/switch_core/bridges/agent/operations/my_context.py
@@ -92,8 +92,9 @@ async def get_my_context() -> dict[str, Any]:
set up; `unavailable_code` says why not, one of "switched_off" (its
operator turned it off), "needs_https" (it can't work on this
server), "app_not_set_up" (its operator can set it up under Admin →
- Connector apps in Switch Console), "not_set_up" or
- "not_fully_set_up";
+ Connector apps in Switch Console), "not_set_up",
+ "not_fully_set_up" or "key_never_expires" (it connects with a key
+ that never expires, which Switch does not hand to agents);
`connection` is your owner's: "not_connected", "active",
"needs_reauthorization" or "error". `agents_using` names your owner's
agents granted it. Empty when this server has service connections off.
diff --git a/core/switch_core/connections/adapters/api_key.py b/core/switch_core/connections/adapters/api_key.py
index 39b9696f2..8204ed3e9 100644
--- a/core/switch_core/connections/adapters/api_key.py
+++ b/core/switch_core/connections/adapters/api_key.py
@@ -9,8 +9,10 @@ headers, a CLI run's environment) and redacts every secret one.
A key is the owner's own and does not expire, so nothing is refreshed and
nothing can be revoked: disconnecting forgets it, and only the vendor can
-revoke it. Each issue hands it out for an hour, so the grant is checked again
-at least hourly, as for any pass-through token.
+revoke it. For the same reason it is never handed to an agent: whatever ran
+beside the agent could keep it for good, and neither a removed grant nor a
+disconnect would end it. The catalog says so (`token.max_lifetime: null`),
+and the broker refuses before it gets here.
"""
from __future__ import annotations
@@ -19,7 +21,6 @@ import hashlib
import json
import re
from dataclasses import dataclass
-from datetime import UTC, datetime, timedelta
from typing import Any
import httpx
@@ -44,8 +45,6 @@ from switch_core.connections.loader import (
# single header value or argument; longer than this is not a key.
FIELD_VALUE_RE = re.compile(r"^[\x21-\x7e]{1,1024}$")
MAX_IDENTITY_BYTES = 256 * 1024
-# How long one issue hands the key out: the grant is checked again by then.
-USE_WINDOW = timedelta(hours=1)
class InvalidKeyError(ServiceAdapterError):
@@ -82,7 +81,7 @@ def _path_value(document: Any, path: str) -> Any:
class ApiKeyAdapter:
- can_issue = True
+ can_issue = False
def __init__(self, definition: ConnectionDefinition, http: httpx.AsyncClient):
sign_in = definition.auth.api_key
@@ -216,12 +215,8 @@ class ApiKeyAdapter:
return {}
async def issue(self, access: AccessToken, request: IssueRequest) -> IssuedToken:
- await self.check_grant(access.token, request)
- return IssuedToken(
- token=access.token,
- expires_at=datetime.now(UTC) + USE_WINDOW,
- resources={},
- revocable=False,
+ raise ServiceAdapterError(
+ f"A {self._name} key does not expire, so it is never handed to an agent."
)
async def revoke_issued(self, token: str) -> None:
diff --git a/core/switch_core/connections/broker.py b/core/switch_core/connections/broker.py
index 61365a4e2..9bd68475c 100644
--- a/core/switch_core/connections/broker.py
+++ b/core/switch_core/connections/broker.py
@@ -130,6 +130,10 @@ REVOCATION_BUDGET_SECONDS = 10.0
REVOCATION_CLAIM = timedelta(seconds=90)
VENDOR_CALL_SECONDS = 8
ACCESS_WARNING = "Some access already given out may remain for up to 1 hour."
+UNREVOCABLE_UNKNOWN = (
+ "Some access already given to agents cannot be taken back and may keep "
+ "working until it expires."
+)
SWITCHED_OFF = "Switched off on this server."
# Why a connection needs reconnecting: the operator replaced the app it
# signed in through.
@@ -151,6 +155,9 @@ UnavailableCode = Literal[
"not_set_up",
# It can be connected but not granted: its app is missing a part.
"not_fully_set_up",
+ # Its credential (a pasted key) never expires, so it is never handed to
+ # an agent, and there is nothing to connect it for.
+ "key_never_expires",
]
@@ -248,6 +255,19 @@ def _passes_through(entry: Connection) -> bool:
return token is not None and token.kind == "pass_through"
+def _issued_to_agents(entry: Connection) -> bool:
+ """Whether `entry`'s credential expires, so it may be handed to an agent."""
+ token = entry.definition.token
+ return token is not None and token.issued_to_agents
+
+
+def _never_expires(name: str) -> str:
+ return (
+ f"{name} keys do not expire and only {name} can revoke them, so Switch "
+ "does not hand them to agents."
+ )
+
+
def _level_reach(entry: Connection, access: AccessLevel) -> dict[str, Any] | None:
"""What the catalog says `access` reaches, or None where it has no such
level. A key reaches whatever its vendor let it, at either level."""
@@ -444,10 +464,11 @@ class ServiceBroker:
)
async def workspace_disabled(self, session: AsyncSession) -> set[str]:
- """The services a workspace admin switched off; none with the gate off."""
+ """The services off in this workspace, by an admin's switch or the
+ workspace's default; none with the gate off."""
if not self._workspace_gate:
return set()
- return await self._workspace_services.disabled_services(session)
+ return await self._workspace_services.disabled_services(session, self._catalog)
def _adapter(self, service: str) -> ServiceAdapter:
"""The adapter that issues for `service`, or the refusal saying why not."""
@@ -501,6 +522,8 @@ class ServiceBroker:
self._require_switched_on(service)
await self.require_workspace_enabled(session, service)
name = entry.definition.name
+ if not _issued_to_agents(entry):
+ raise ServiceError(403, FORBIDDEN, _never_expires(name), retryable=False)
tenant_id = require_tenant_id()
agent = await session.scalar(
select(Agent)
@@ -694,6 +717,23 @@ class ServiceBroker:
raise ServiceError(403, FORBIDDEN, str(error), retryable=False) from None
definition = self._entry(service).definition
policy = self._token_policy(service)
+ if policy.max_lifetime is None:
+ raise ServiceError(
+ 403, FORBIDDEN, _never_expires(definition.name), retryable=False
+ )
+ max_lifetime = timedelta(seconds=policy.max_lifetime)
+ if policy.kind == "pass_through" and (
+ issued.token != access.token or issued.expires_at != access.expires_at
+ ):
+ # The lifetime checked below must be the vendor's own: the agent
+ # holds the owner's token for as long as the vendor honours it.
+ raise ServiceError(
+ 500,
+ INTERNAL,
+ f"{definition.name} handed out a token other than the owner's, or "
+ "with another expiry, so it was not handed out.",
+ retryable=False,
+ )
if policy.kind == "pass_through" and issued.revocable:
# The owner's own token: revoking it would end their connection,
# so it is never kept to revoke, nor taken back here.
@@ -709,7 +749,7 @@ class ServiceBroker:
if not (
now + TOKEN_LEEWAY
< issued.expires_at
- <= now + timedelta(seconds=policy.max_lifetime) + TOKEN_LEEWAY
+ <= now + max_lifetime + TOKEN_LEEWAY
):
raise ServiceError(
500,
@@ -1100,12 +1140,13 @@ class ServiceBroker:
return grants
def connectable(self, service: str) -> bool:
- """Whether a person can connect `service` here: it has an adapter and
- is not switched off."""
+ """Whether a person can connect `service` here: it has an adapter, is
+ not switched off, and what it connects could be handed to an agent."""
entry = self._catalog.get(service)
return (
entry is not None
and entry.definition.enabled
+ and _issued_to_agents(entry)
and service in self._adapters
and service not in self._disabled
)
@@ -1153,6 +1194,8 @@ class ServiceBroker:
reason = self._disabled.get(service)
if reason is not None:
return Unavailable("switched_off", reason)
+ if not _issued_to_agents(entry):
+ return Unavailable("key_never_expires", _never_expires(name))
adapter = self._adapters.get(service)
if adapter is None:
kind = app_kind(entry.definition)
@@ -1442,10 +1485,9 @@ class ServiceBroker:
await session.commit()
if not narrowed:
return grant, None
- pending = await self.revoke_pending(
+ return grant, await self.revoke_withdrawn(
session, (ServiceTokenIssuance.grant_id == grant_id,)
)
- return grant, ACCESS_WARNING if pending else None
async def connect(
self,
@@ -1470,8 +1512,11 @@ class ServiceBroker:
sign-in, and the old sign-in itself when it is not the new one.
Commits `session`; returns a warning naming what could not be revoked.
"""
- name = self._entry(service).definition.name
+ entry = self._entry(service)
+ name = entry.definition.name
self._require_switched_on(service)
+ if not _issued_to_agents(entry):
+ raise ServiceError(403, FORBIDDEN, _never_expires(name), retryable=False)
try:
await self.require_workspace_enabled(session, service)
except ServiceError as refusal:
@@ -1544,8 +1589,9 @@ class ServiceBroker:
f"{name} could not revoke the old sign-in. Revoke it in your "
f"{name} settings."
)
- if await self.revoke_pending(session, issued_on_it):
- warnings.append(ACCESS_WARNING)
+ withdrawn = await self.revoke_withdrawn(session, issued_on_it)
+ if withdrawn is not None:
+ warnings.append(withdrawn)
return " ".join(warnings) or None
async def _revoke_unkept(
@@ -1584,7 +1630,8 @@ class ServiceBroker:
and the secret a connection keeps. Connect it with `connect`, at
`KEY_CONSENT`: a key reaches whatever its vendor let it, so the
connection's level is the highest a grant can take."""
- definition = self._entry(service).definition
+ entry = self._entry(service)
+ definition = entry.definition
self._require_switched_on(service)
if definition.adapter != "api_key":
raise ServiceError(
@@ -1593,6 +1640,10 @@ class ServiceBroker:
f"{definition.name} is not connected with a key.",
retryable=False,
)
+ if not _issued_to_agents(entry):
+ raise ServiceError(
+ 403, FORBIDDEN, _never_expires(definition.name), retryable=False
+ )
adapter = self._adapters.get(service)
if not isinstance(adapter, ApiKeyAdapter):
raise ServiceError(
@@ -1696,10 +1747,9 @@ class ServiceBroker:
details={"service": service},
)
await session.commit()
- pending = await self.revoke_pending(
+ return await self.revoke_withdrawn(
session, (ServiceTokenIssuance.grant_id == grant_id,)
)
- return ACCESS_WARNING if pending else None
async def disconnect(
self, session: AsyncSession, user_id: str, service: str
@@ -1804,14 +1854,59 @@ class ServiceBroker:
f"{name} could not revoke the sign-in. Revoke it in your "
f"{name} settings."
)
- if removed and await self.revoke_pending(
- session, (ServiceTokenIssuance.owner_id == user_id,)
- ):
- warnings.append(ACCESS_WARNING)
+ if removed:
+ withdrawn = await self.revoke_withdrawn(
+ session, (ServiceTokenIssuance.owner_id == user_id,)
+ )
+ if withdrawn is not None:
+ warnings.append(withdrawn)
return " ".join(warnings) or None
# ── Revocation and retention ─────────────────────────────────────────────
+ async def revoke_withdrawn(
+ self, session: AsyncSession, conditions: tuple[Any, ...]
+ ) -> str | None:
+ """After an access change has committed: revoke what it withdrew, and
+ say what could not be taken back.
+
+ A token its vendor can revoke that is still pending is retried by the
+ periodic tick, and lives an hour at most. One no vendor can revoke
+ alone (the owner's own, passed through) stays valid until it expires;
+ the warning names the service and when.
+ """
+ pending = await self.revoke_pending(session, conditions)
+ warnings = [ACCESS_WARNING] if pending else []
+ unrevocable = sorted(
+ slug for slug, entry in self._catalog.items() if _passes_through(entry)
+ )
+ try:
+ async with tenant_session(
+ self._session_factory, require_tenant_id()
+ ) as own:
+ withdrawn = await self._store.withdrawn_until(
+ own, unrevocable, conditions
+ )
+ await own.commit()
+ except Exception as error:
+ logger.error(
+ "Could not read which withdrawn service tokens are still valid: "
+ "error_type=%s",
+ type(error).__name__,
+ )
+ warnings.append(UNREVOCABLE_UNKNOWN)
+ return " ".join(warnings)
+ if withdrawn:
+ names = " and ".join(
+ self._catalog[slug].definition.name for slug in sorted(withdrawn)
+ )
+ until = max(withdrawn.values()).astimezone(UTC)
+ warnings.append(
+ f"{names} access already given to agents cannot be taken back "
+ f"and may keep working until {until:%Y-%m-%d %H:%M} UTC."
+ )
+ return " ".join(warnings) or None
+
async def revoke_pending(
self, session: AsyncSession, conditions: tuple[Any, ...]
) -> bool:
diff --git a/core/switch_core/connections/catalog/atlassian/connection.yaml b/core/switch_core/connections/catalog/atlassian/connection.yaml
index 8201eeacd..eed7c10a0 100644
--- a/core/switch_core/connections/catalog/atlassian/connection.yaml
+++ b/core/switch_core/connections/catalog/atlassian/connection.yaml
@@ -22,7 +22,9 @@ auth:
url: https://api.atlassian.com/me
account_id: account_id
label: email
-# Atlassian's MCP access tokens live 8 hours; agents still ask again hourly.
+# Atlassian's MCP access tokens live 8 hours, and Atlassian offers no way to
+# ask for a shorter one or to revoke one alone, so an agent's copy may outlive
+# its grant by up to that long. Agents still ask again hourly.
token: { kind: pass_through, max_lifetime: 28800 }
mcp:
servers:
diff --git a/core/switch_core/connections/catalog/datadog/connection.yaml b/core/switch_core/connections/catalog/datadog/connection.yaml
index 8effdc146..573b0a3c4 100644
--- a/core/switch_core/connections/catalog/datadog/connection.yaml
+++ b/core/switch_core/connections/catalog/datadog/connection.yaml
@@ -35,9 +35,9 @@ auth:
url: "https://api.{site}/api/v1/validate"
headers: { DD-API-KEY: "{api_key}" }
help_url: https://docs.datadoghq.com/account_management/api-app-keys/
-# A key does not expire; each issue hands it out for an hour, so the grant is
-# checked again at least hourly.
-token: { kind: pass_through, max_lifetime: 3600 }
+# A key does not expire, and only Datadog can revoke it, so it is never handed
+# to an agent: whatever runs beside the agent could keep it for good.
+token: { kind: pass_through, max_lifetime: null }
mcp:
servers:
# Datadog's remote MCP server takes the keys in headers named with
diff --git a/core/switch_core/connections/catalog/google-workspace/connection.yaml b/core/switch_core/connections/catalog/google-workspace/connection.yaml
index 636d4c379..9b860b895 100644
--- a/core/switch_core/connections/catalog/google-workspace/connection.yaml
+++ b/core/switch_core/connections/catalog/google-workspace/connection.yaml
@@ -28,9 +28,9 @@ auth:
url: https://openidconnect.googleapis.com/v1/userinfo
account_id: sub
label: email
-# Google's access tokens lived 3,599 s when measured; its documentation's
-# sample shows 3,920. Agents still ask again hourly.
-token: { kind: pass_through, max_lifetime: 3920 }
+# Google's access tokens lived 3,599 s when measured, so one handed out never
+# has more than an hour left; a longer one is refused rather than handed out.
+token: { kind: pass_through, max_lifetime: 3600 }
cli:
name: google-workspace
binary: gws
diff --git a/core/switch_core/connections/loader.py b/core/switch_core/connections/loader.py
index 4fdd411d2..37c625dfb 100644
--- a/core/switch_core/connections/loader.py
+++ b/core/switch_core/connections/loader.py
@@ -300,17 +300,26 @@ class TokenPolicy(BaseModel):
`minted`: made for the one issue and narrowed to the grant (GitHub's
installation tokens). `pass_through`: the owner's own access token, shared
by every agent they grant, which can be neither narrowed nor revoked per
- agent. `max_lifetime`, in seconds, is the longest the vendor's token may
- live; a longer one is refused.
+ agent. `max_lifetime`, in seconds, is the longest the credential handed
+ out may stay valid at the vendor; one valid for longer is refused. It is
+ null for a credential that never expires (a pasted key): Switch could
+ neither take such a credential back nor wait for it to lapse, so it is
+ never handed to an agent.
"""
model_config = ConfigDict(extra="forbid", frozen=True, strict=True)
kind: Literal["minted", "pass_through"]
- max_lifetime: int = Field(ge=300, le=7 * 24 * 3600)
+ max_lifetime: Annotated[int, Field(ge=300, le=7 * 24 * 3600)] | None
+
+ @property
+ def issued_to_agents(self) -> bool:
+ return self.max_lifetime is not None
@model_validator(mode="after")
def _minted_within_the_hour(self) -> "TokenPolicy":
- if self.kind == "minted" and self.max_lifetime > MINTED_MAX_LIFETIME:
+ if self.kind == "minted" and (
+ self.max_lifetime is None or self.max_lifetime > MINTED_MAX_LIFETIME
+ ):
raise ValueError(
f"a minted token lives at most {MINTED_MAX_LIFETIME} seconds"
)
@@ -574,11 +583,11 @@ class ConnectionDefinition(BaseModel):
if self.enabled and (self.auth.api_key is None or not (self.mcp or self.cli)):
raise ValueError("an api_key entry needs auth.api_key, and mcp or cli")
if self.token is not None and (
- self.token.kind != "pass_through" or self.token.max_lifetime > 3600
+ self.token.kind != "pass_through" or self.token.max_lifetime is not None
):
raise ValueError(
- "an api_key entry passes the key through, handed out for at most "
- "an hour at a time"
+ "a key does not expire, so it is never handed to an agent: "
+ "token is { kind: pass_through, max_lifetime: null }"
)
if self.access is not None:
raise ValueError("a key reaches whatever its vendor let it: no access")
@@ -661,6 +670,8 @@ class ConnectionDefinition(BaseModel):
raise ValueError("an oauth sign-in is refreshed: rotating or reusable")
if self.token is not None and self.token.kind != "pass_through":
raise ValueError("the oauth adapter passes the owner's token through")
+ if self.token is not None and self.token.max_lifetime is None:
+ raise ValueError("an OAuth access token expires: name its max_lifetime")
if self.tools is not None and self.tools.mode != "pass_through":
raise ValueError("an oauth entry's tools pass through until classified")
if self.access is not None and any(
diff --git a/core/switch_core/db/models.py b/core/switch_core/db/models.py
index b5ee6af5c..e8291b679 100644
--- a/core/switch_core/db/models.py
+++ b/core/switch_core/db/models.py
@@ -96,6 +96,13 @@ class Tenant(Base):
created_at: Mapped[str] = mapped_column(
DateTime(timezone=True), server_default=func.now(), nullable=False
)
+ # Whether a catalog service no workspace admin has switched on or off
+ # (`WorkspaceServiceSetting`) is on. Off for every workspace made since
+ # services started off; on for those that already had members then, so
+ # what they were using kept working.
+ services_on_by_default: Mapped[bool] = mapped_column(
+ Boolean, server_default="false", nullable=False
+ )
class TenantMember(Base):
@@ -4126,7 +4133,9 @@ class ServerAuditEvent(Base):
class WorkspaceServiceSetting(TenantScoped, Base):
"""A workspace admin switched a catalog service on or off for the workspace.
- No row means on: a row is written only when an admin touches the switch,
+ No row means the workspace's default (`Tenant.services_on_by_default`),
+ off for a workspace made since services started off: a row is written
+ only when an admin touches the switch,
so `updated_by` always names a person. `service` is a catalog slug, checked
in code as `ServiceConnection.service` is. Off, nobody in the workspace can
connect, grant or be issued a token for it, and its grants drop out of
@@ -4226,6 +4235,10 @@ class ServiceTokenIssuance(TenantScoped, Base):
token has expired or been revoked. `token_sha256` stays, so a leaked token
can be traced to the agent it was issued to. Records are pruned after
`service_token_retention_days`.
+
+ `revoke_requested` on a token held without its ciphertext from the start
+ (the owner's own, passed through) means its access was withdrawn while it
+ was live: nothing can revoke it, and it stays valid until `expires_at`.
"""
__tablename__ = "service_token_issuances"
@@ -4244,6 +4257,14 @@ class ServiceTokenIssuance(TenantScoped, Base):
"expires_at",
postgresql_where=text("encrypted_token IS NOT NULL"),
),
+ # The tokens that cannot be revoked, for marking the ones still live
+ # when their access is withdrawn.
+ Index(
+ "ix_service_token_issuances_unrevocable",
+ "tenant_id",
+ "expires_at",
+ postgresql_where=text("encrypted_token IS NULL"),
+ ),
)
id: Mapped[str] = mapped_column(Text, nullable=False, default=_uuid)
diff --git a/core/switch_core/db/stores/service_connection_store.py b/core/switch_core/db/stores/service_connection_store.py
index e364cc0ab..a3982fae3 100644
--- a/core/switch_core/db/stores/service_connection_store.py
+++ b/core/switch_core/db/stores/service_connection_store.py
@@ -325,16 +325,56 @@ class ServiceConnectionStore:
session.add(issuance)
async def queue_revocation(self, session: AsyncSession, *conditions: Any) -> None:
- """Ask for every live token matching `conditions` to be revoked."""
+ """Ask for every live token matching `conditions` to be revoked.
+
+ A live token no vendor can revoke alone (the owner's own, passed
+ through, recorded without its ciphertext) is marked the same way: it
+ stays valid until it expires, and the record says its access was
+ withdrawn before then.
+ """
+ tenant_id = require_tenant_id()
await session.execute(
update(ServiceTokenIssuance)
.where(
- ServiceTokenIssuance.tenant_id == require_tenant_id(),
+ ServiceTokenIssuance.tenant_id == tenant_id,
ServiceTokenIssuance.encrypted_token.is_not(None),
*conditions,
)
.values(revoke_requested=True)
)
+ await session.execute(
+ update(ServiceTokenIssuance)
+ .where(
+ ServiceTokenIssuance.tenant_id == tenant_id,
+ ServiceTokenIssuance.encrypted_token.is_(None),
+ ServiceTokenIssuance.revoke_requested.is_(False),
+ ServiceTokenIssuance.expires_at > func.now(),
+ *conditions,
+ )
+ .values(revoke_requested=True)
+ )
+
+ async def withdrawn_until(
+ self, session: AsyncSession, services: list[str], conditions: tuple[Any, ...]
+ ) -> dict[str, datetime]:
+ """For each of `services`, whose tokens no vendor can revoke alone, when
+ the last token matching `conditions` that was withdrawn but is still
+ valid expires. A service with none is left out."""
+ rows = await session.execute(
+ select(
+ ServiceTokenIssuance.service, func.max(ServiceTokenIssuance.expires_at)
+ )
+ .where(
+ ServiceTokenIssuance.tenant_id == require_tenant_id(),
+ ServiceTokenIssuance.service.in_(services),
+ ServiceTokenIssuance.encrypted_token.is_(None),
+ ServiceTokenIssuance.revoke_requested.is_(True),
+ ServiceTokenIssuance.expires_at > func.now(),
+ *conditions,
+ )
+ .group_by(ServiceTokenIssuance.service)
+ )
+ return {service: until for service, until in rows.tuples()}
async def queue_orphaned(self, session: AsyncSession) -> None:
"""Queue every live token whose grant, or owner's membership, is gone,
diff --git a/core/switch_core/db/stores/workspace_service_store.py b/core/switch_core/db/stores/workspace_service_store.py
index af0666cc8..50a72169a 100644
--- a/core/switch_core/db/stores/workspace_service_store.py
+++ b/core/switch_core/db/stores/workspace_service_store.py
@@ -1,27 +1,43 @@
-"""Which catalog services a workspace admin switched off for the workspace.
+"""Which catalog services a workspace admin switched on or off for the workspace.
-No row means on. Every query runs in the bound tenant.
+No row means the workspace's default, `Tenant.services_on_by_default`: off
+for a workspace made since services started off. Every query runs in the
+bound tenant.
"""
from __future__ import annotations
+from collections.abc import Iterable
+
from sqlalchemy import func, select
from sqlalchemy.dialects.postgresql import insert
from sqlalchemy.ext.asyncio import AsyncSession
-from switch_core.db.models import WorkspaceServiceSetting, require_tenant_id
+from switch_core.db.models import Tenant, WorkspaceServiceSetting, require_tenant_id
class WorkspaceServiceStore:
- async def disabled_services(self, session: AsyncSession) -> set[str]:
- return set(
- await session.scalars(
- select(WorkspaceServiceSetting.service).where(
- WorkspaceServiceSetting.tenant_id == require_tenant_id(),
- WorkspaceServiceSetting.enabled.is_(False),
- )
- )
+ async def on_by_default(self, session: AsyncSession) -> bool:
+ """Whether a service no admin has switched is on in the workspace."""
+ tenant_id = require_tenant_id()
+ on = await session.scalar(
+ select(Tenant.services_on_by_default).where(Tenant.id == tenant_id)
)
+ if on is None:
+ raise LookupError(f"No workspace {tenant_id!r}.")
+ return on
+
+ async def disabled_services(
+ self, session: AsyncSession, services: Iterable[str]
+ ) -> set[str]:
+ """Those of `services` that are off in the workspace."""
+ default = await self.on_by_default(session)
+ settings = await self.list_settings(session)
+ return {
+ service
+ for service in services
+ if not (settings[service].enabled if service in settings else default)
+ }
async def is_enabled(self, session: AsyncSession, service: str) -> bool:
enabled = await session.scalar(
@@ -30,7 +46,9 @@ class WorkspaceServiceStore:
WorkspaceServiceSetting.service == service,
)
)
- return enabled is not False
+ if enabled is None:
+ return await self.on_by_default(session)
+ return enabled
async def list_settings(
self, session: AsyncSession
diff --git a/core/switch_core/gateway/workspace_services.py b/core/switch_core/gateway/workspace_services.py
index 82c7bad7e..bf2f89f1f 100644
--- a/core/switch_core/gateway/workspace_services.py
+++ b/core/switch_core/gateway/workspace_services.py
@@ -1,11 +1,15 @@
"""A workspace admin's switch for each catalog service, for the whole workspace.
-On by default: a service with no setting is usable. Switched off, nobody in the
+Off by default: a service no admin has switched takes the workspace's default
+(`Tenant.services_on_by_default`), off for every workspace made since services
+started off and on for those that had members by then. Off, nobody in the
workspace can connect it, grant it or be issued a token for it, and it drops
out of the grants every agent's session reads, so the session's host restarts
it without the service within about half a minute. Grants are kept, so
switching it back on returns them. A token already handed out may be used
-until that restart; one the vendor can revoke (GitHub's) is revoked here.
+until that restart; one the vendor can revoke (GitHub's) is revoked here, and
+one no vendor can revoke alone is marked withdrawn and stays valid until it
+expires, which the answer's warning says.
"""
from __future__ import annotations
@@ -18,11 +22,7 @@ from pydantic import BaseModel, ConfigDict
from sqlalchemy import func, select
from sqlalchemy.ext.asyncio import AsyncSession
-from switch_core.connections.broker import (
- ACCESS_WARNING,
- ServiceBroker,
- get_service_broker,
-)
+from switch_core.connections.broker import ServiceBroker, get_service_broker
from switch_core.connections.loader import CATALOG
from switch_core.db.audit import AuditAction, record_audit_event
from switch_core.db.models import (
@@ -57,6 +57,7 @@ async def list_workspace_services(
"""Every catalog service that can be connected, whether the workspace has
it on, and who it reaches: what an admin weighs before switching it off."""
settings = await STORE.list_settings(session)
+ on_by_default = await STORE.on_by_default(session)
names = {
user.id: user.name
for user in await session.scalars(
@@ -78,7 +79,7 @@ async def list_workspace_services(
{
"slug": definition.slug,
"name": definition.name,
- "enabled": setting is None or setting.enabled,
+ "enabled": on_by_default if setting is None else setting.enabled,
"updated_by_name": (
None if setting is None else names.get(setting.updated_by)
),
@@ -107,7 +108,8 @@ async def set_workspace_service(
Off queues every live token this workspace was issued for it, in the same
transaction, and revokes them before answering; `warning` says when some
- could not be revoked yet, which the periodic tick keeps trying.
+ could not be revoked yet, which the periodic tick keeps trying, and until
+ when those no vendor can revoke alone stay valid.
"""
entry = CATALOG.get(service)
if entry is None or not entry.definition.enabled:
@@ -130,9 +132,7 @@ async def set_workspace_service(
details={"service": service},
)
await session.commit()
- pending = not body.enabled and await broker.revoke_pending(session, issued_for_it)
- return {
- "slug": service,
- "enabled": body.enabled,
- "warning": ACCESS_WARNING if pending else None,
- }
+ warning = (
+ None if body.enabled else await broker.revoke_withdrawn(session, issued_for_it)
+ )
+ return {"slug": service, "enabled": body.enabled, "warning": warning}
diff --git a/core/switch_core/migrations/versions/f68b679599ab_workspace_services_off_by_default.py b/core/switch_core/migrations/versions/f68b679599ab_workspace_services_off_by_default.py
new file mode 100644
index 000000000..daf133834
--- /dev/null
+++ b/core/switch_core/migrations/versions/f68b679599ab_workspace_services_off_by_default.py
@@ -0,0 +1,71 @@
+"""workspace services off by default, and an index for withdrawn tokens
+
+`tenants.services_on_by_default` says whether a catalog service no workspace
+admin has switched on or off (`workspace_service_settings`) is on in the
+workspace. A workspace made from now on starts with every service off, the
+column's default, until an admin switches each on.
+
+A workspace that already has members keeps every service on by default, as
+it had: this revision sets the column for them, so nothing they connected or
+granted stops working on upgrade, and every switch an admin already set is
+kept as it is. A workspace with no members yet, as the one the first
+migration makes on a fresh install, could not have used a service, so it
+starts off like a new one.
+
+`ix_service_token_issuances_unrevocable` serves marking the tokens no vendor
+can revoke alone (`encrypted_token IS NULL`) that are still live when their
+access is withdrawn, by `expires_at`.
+
+Expand only: a release from before this revision never reads the column,
+reads every service with no row as on, as it always did, and never uses the
+index.
+
+Revision ID: f68b679599ab
+Revises: c7715ebb95c9
+Create Date: 2026-10-23 08:25:37.727969
+
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "f68b679599ab"
+down_revision: str | None = "c7715ebb95c9"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+expand_only: bool = True
+
+_INDEX = "ix_service_token_issuances_unrevocable"
+
+
+def upgrade() -> None:
+ op.add_column(
+ "tenants",
+ sa.Column(
+ "services_on_by_default",
+ sa.Boolean(),
+ server_default="false",
+ nullable=False,
+ ),
+ )
+ op.execute(
+ """
+ UPDATE tenants SET services_on_by_default = true
+ WHERE EXISTS (
+ SELECT 1 FROM tenant_members WHERE tenant_members.tenant_id = tenants.id
+ )
+ """
+ )
+ op.create_index(
+ _INDEX,
+ "service_token_issuances",
+ ["tenant_id", "expires_at"],
+ postgresql_where=sa.text("encrypted_token IS NULL"),
+ )
+
+
+def downgrade() -> None:
+ op.drop_index(_INDEX, table_name="service_token_issuances")
+ op.drop_column("tenants", "services_on_by_default")
diff --git a/core/tests/switch_core/connections/adapters/test_api_key.py b/core/tests/switch_core/connections/adapters/test_api_key.py
index e17b8854c..53df982db 100644
--- a/core/tests/switch_core/connections/adapters/test_api_key.py
+++ b/core/tests/switch_core/connections/adapters/test_api_key.py
@@ -3,11 +3,17 @@
from __future__ import annotations
import json
+from datetime import UTC, datetime, timedelta
import httpx
import pytest
-from switch_core.connections.adapters import ConnectionNotRevocable
+from switch_core.connections.adapters import (
+ AccessToken,
+ ConnectionNotRevocable,
+ IssueRequest,
+ ServiceAdapterError,
+)
from switch_core.connections.adapters.api_key import (
ApiKeyAdapter,
InvalidKeyError,
@@ -46,7 +52,7 @@ ENTRY = {
},
},
},
- "token": {"kind": "pass_through", "max_lifetime": 3600},
+ "token": {"kind": "pass_through", "max_lifetime": None},
"mcp": {
"servers": [
{
@@ -119,3 +125,15 @@ async def test_disconnecting_says_only_the_vendor_can_revoke_a_key() -> None:
adapter = _adapter(lambda request: httpx.Response(200))
with pytest.raises(ConnectionNotRevocable, match="Revoke it in Example"):
await adapter.revoke_connection(adapter.secret(FIELDS))
+
+
+async def test_a_key_is_never_issued_to_an_agent() -> None:
+ adapter = _adapter(lambda request: httpx.Response(200))
+ assert adapter.can_issue is False
+ key = adapter.secret(FIELDS).access_token
+ assert key is not None
+ with pytest.raises(ServiceAdapterError, match="never handed to an agent"):
+ await adapter.issue(
+ AccessToken(key, datetime.now(UTC) + timedelta(hours=1)),
+ IssueRequest(service="example", access="write", reach={}, resources={}),
+ )
diff --git a/core/tests/switch_core/connections/service_harness.py b/core/tests/switch_core/connections/service_harness.py
index bcbb2c017..9b3b80dba 100644
--- a/core/tests/switch_core/connections/service_harness.py
+++ b/core/tests/switch_core/connections/service_harness.py
@@ -19,12 +19,21 @@ from datetime import timedelta
from typing import Any
import httpx
+from sqlalchemy import update
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from switch_core.bridges.agent.api.service_routes import router as service_router
from switch_core.connections.broker import ServiceBroker
from switch_core.connections.loader import CATALOG
-from switch_core.db.models import Agent, ApiKey, Client, ServiceGrant, User
+from switch_core.db.models import (
+ TENANT_ZERO_ID,
+ Agent,
+ ApiKey,
+ Client,
+ ServiceGrant,
+ Tenant,
+ User,
+)
from switch_core.db.session_scope import tenant_session
from switch_core.db.stores.service_connection_store import ServiceConnectionStore
from switch_core.db.stores.workspace_service_store import WorkspaceServiceStore
@@ -77,6 +86,20 @@ def build_service_harness(
return harness, broker
+async def services_on_by_default(
+ session_factory: async_sessionmaker[AsyncSession],
+) -> None:
+ """Make the workspace one that had members before services started off,
+ where a service no admin has switched is on."""
+ async with session_factory() as session:
+ await session.execute(
+ update(Tenant)
+ .where(Tenant.id == TENANT_ZERO_ID)
+ .values(services_on_by_default=True)
+ )
+ await session.commit()
+
+
async def agent_with_key(
session_factory: async_sessionmaker[AsyncSession],
owner: User,
diff --git a/core/tests/switch_core/connections/test_broker.py b/core/tests/switch_core/connections/test_broker.py
index 3cc266bca..13addbe3b 100644
--- a/core/tests/switch_core/connections/test_broker.py
+++ b/core/tests/switch_core/connections/test_broker.py
@@ -23,7 +23,9 @@ from sqlalchemy import delete, event, select, update
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from switch_core.connections.adapters import (
+ AccessToken,
ConnectionSecret,
+ IssuedToken,
ReauthorizationRequiredError,
ServiceAdapterError,
)
@@ -44,6 +46,7 @@ from switch_core.db.models import (
ServiceConnection,
ServiceGrant,
ServiceTokenIssuance,
+ Tenant,
TenantMember,
User,
)
@@ -1090,6 +1093,31 @@ class TestPassThrough:
assert "does not expire within an hour" in refused.message
assert pt.vendor.revoked == []
+ async def test_refuses_the_owners_token_handed_out_with_a_shorter_expiry(
+ self, session_factory, tmp_path, monkeypatch
+ ) -> None:
+ """The lifetime checked is the vendor's: an adapter cannot pass a
+ long-lived owner's token off as one that lapses within the cap."""
+ pt = await _pass_through(session_factory, tmp_path / "c", expires_in=8 * 3600)
+ issue = pt.vendor.issue
+
+ async def claims_an_hour(access: AccessToken, request) -> IssuedToken:
+ issued = await issue(access, request)
+ return IssuedToken(
+ token=issued.token,
+ expires_at=datetime.now(UTC) + timedelta(minutes=50),
+ resources={},
+ revocable=False,
+ )
+
+ monkeypatch.setattr(pt.vendor, "issue", claims_an_hour)
+ refused = await _refused(
+ pt.broker, session_factory, pt.world.agent.id, service="example"
+ )
+ assert (refused.status_code, refused.code) == (500, "internal")
+ assert "with another expiry" in refused.message
+ assert await _issuances(session_factory) == []
+
async def test_a_longer_lived_token_is_used_for_an_hour_at_most(
self, session_factory, tmp_path
) -> None:
@@ -1182,10 +1210,61 @@ class TestPassThrough:
grant = await STORE.get_grant(session, pt.world.agent.id, "example")
assert grant is not None
warning = await pt.broker.revoke_grant(session, grant, pt.world.owner.id)
- assert warning is None
await maintain_once(session_factory, pt.broker, prune=False)
assert pt.vendor.revoked == []
assert pt.vendor.connections_revoked == []
+ # Nothing could take it back, so the record says it was withdrawn and
+ # the warning says until when it may keep working.
+ async with session_factory() as session:
+ [record] = await session.scalars(select(ServiceTokenIssuance))
+ assert (record.revoke_requested, record.encrypted_token) == (True, None)
+ assert warning == (
+ "Example access already given to agents cannot be taken back and may "
+ f"keep working until {record.expires_at.astimezone(UTC):%Y-%m-%d %H:%M} UTC."
+ )
+
+ async def test_withdrawing_access_marks_only_the_live_pass_through_tokens(
+ self, session_factory, tmp_path
+ ) -> None:
+ pt = await _pass_through(session_factory, tmp_path / "c", expires_in=50 * 60)
+ await _issue(pt.broker, session_factory, pt.world.agent.id, service="example")
+ async with session_factory() as session:
+ [live] = await session.scalars(select(ServiceTokenIssuance))
+ expired = ServiceTokenIssuance(
+ tenant_id=TENANT_ZERO_ID,
+ grant_id=live.grant_id,
+ agent_id=live.agent_id,
+ owner_id=live.owner_id,
+ service="example",
+ principal="agent_key",
+ controller_id=None,
+ permissions={},
+ resources={},
+ expires_at=datetime.now(UTC) - timedelta(minutes=5),
+ token_sha256="0" * 64,
+ encrypted_token=None,
+ revoke_requested=False,
+ attempts=0,
+ )
+ session.add(expired)
+ await session.commit()
+ live_id, expired_id = live.id, expired.id
+
+ async with session_factory() as session:
+ await pt.broker.queue_revocation(
+ session, ServiceTokenIssuance.agent_id == pt.world.agent.id
+ )
+ await session.commit()
+ warning = await pt.broker.revoke_withdrawn(
+ session, (ServiceTokenIssuance.agent_id == pt.world.agent.id,)
+ )
+ async with session_factory() as session:
+ marked = {
+ row.id: row.revoke_requested
+ for row in await session.scalars(select(ServiceTokenIssuance))
+ }
+ assert marked == {live_id: True, expired_id: False}
+ assert warning is not None and warning.startswith("Example access already")
def _workspace_refusal(name: str) -> str:
@@ -1273,6 +1352,17 @@ async def _gated(
return Gated(broker, github, example, world)
+async def _on_by_default(session_factory: async_sessionmaker[AsyncSession]) -> None:
+ """Make the workspace one that had members before services started off."""
+ async with session_factory() as session:
+ await session.execute(
+ update(Tenant)
+ .where(Tenant.id == TENANT_ZERO_ID)
+ .values(services_on_by_default=True)
+ )
+ await session.commit()
+
+
async def _switch(
session_factory: async_sessionmaker[AsyncSession],
service: str,
@@ -1363,7 +1453,6 @@ ENTRY_POINTS = {
"issue": (_issue_github, "github", "GitHub"),
"set_grant": (_set_grant_github, "github", "GitHub"),
"connect_github": (_connect_github, "github", "GitHub"),
- "connect_key": (_connect_key, "datadog", "Datadog"),
"relink_oauth": (_relink_oauth, "example", "Example"),
}
@@ -1371,19 +1460,38 @@ ENTRY_POINTS = {
class TestWorkspaceSwitch:
@pytest.mark.parametrize("entry_point", sorted(ENTRY_POINTS))
@pytest.mark.parametrize(
- ("gate", "row"),
- [(False, False), (True, True), (True, None)],
- ids=["gate_off_row_off", "gate_on_enabled", "gate_on_no_row"],
+ ("gate", "row", "on_by_default"),
+ [(False, False, False), (True, True, False), (True, None, True)],
+ ids=["gate_off_row_off", "gate_on_enabled", "gate_on_no_row_on_by_default"],
)
async def test_allowed(
- self, session_factory, tmp_path, entry_point, gate, row
+ self, session_factory, tmp_path, entry_point, gate, row, on_by_default
) -> None:
call, service, _ = ENTRY_POINTS[entry_point]
g = await _gated(session_factory, tmp_path / "c", gate=gate)
+ if on_by_default:
+ await _on_by_default(session_factory)
if row is not None:
await _switch(session_factory, service, row, g.world.owner.id)
await call(g, session_factory)
+ @pytest.mark.parametrize("entry_point", sorted(ENTRY_POINTS))
+ async def test_a_new_workspace_has_every_service_off_until_an_admin_switches_it_on(
+ self, session_factory, tmp_path, entry_point
+ ) -> None:
+ call, service, name = ENTRY_POINTS[entry_point]
+ g = await _gated(session_factory, tmp_path / "c", gate=True)
+ async with session_factory() as session:
+ assert await g.broker.workspace_disabled(session) == set(g.broker._catalog)
+
+ with pytest.raises(ServiceError) as caught:
+ await call(g, session_factory)
+ assert (caught.value.status_code, caught.value.code) == (403, "forbidden")
+ assert caught.value.message == _workspace_refusal(name)
+
+ await _switch(session_factory, service, True, g.world.owner.id)
+ await call(g, session_factory)
+
@pytest.mark.parametrize("entry_point", sorted(ENTRY_POINTS))
async def test_switched_off_in_the_workspace_is_refused_naming_who_and_where(
self, session_factory, tmp_path, entry_point
@@ -1443,14 +1551,19 @@ class TestWorkspaceSwitch:
"gho_access_new"
]
- async def test_a_key_refused_by_the_workspace_is_not_stored(
- self, session_factory, tmp_path
+ @pytest.mark.parametrize("enabled", [True, False])
+ async def test_a_key_that_never_expires_is_not_stored(
+ self, session_factory, tmp_path, enabled
) -> None:
g = await _gated(session_factory, tmp_path / "c", gate=True)
- await _switch(session_factory, "datadog", False, g.world.owner.id)
+ await _switch(session_factory, "datadog", enabled, g.world.owner.id)
with pytest.raises(ServiceError) as caught:
await _connect_key(g, session_factory)
- assert caught.value.message == _workspace_refusal("Datadog")
+ assert (caught.value.status_code, caught.value.code) == (403, "forbidden")
+ assert caught.value.message == (
+ "Datadog keys do not expire and only Datadog can revoke them, so "
+ "Switch does not hand them to agents."
+ )
assert "datadog" not in {
service for service, _, _ in await _all_connections(session_factory)
}
@@ -1476,6 +1589,7 @@ class TestWorkspaceSwitch:
self, session_factory, tmp_path
) -> None:
g = await _gated(session_factory, tmp_path / "c", gate=True)
+ await _on_by_default(session_factory)
async def listed() -> list[str]:
async with session_factory() as session:
diff --git a/core/tests/switch_core/connections/test_loader.py b/core/tests/switch_core/connections/test_loader.py
index 61baf0241..5a8b032fa 100644
--- a/core/tests/switch_core/connections/test_loader.py
+++ b/core/tests/switch_core/connections/test_loader.py
@@ -69,9 +69,10 @@ def test_the_shipped_google_entry_signs_in_and_runs_gws_as_the_spike_found_it_mu
"email",
)
assert definition.token is not None
+ # Google's tokens live under an hour; one handed out never has more left.
assert (definition.token.kind, definition.token.max_lifetime) == (
"pass_through",
- 3920,
+ 3600,
)
access = definition.access
assert access is not None and access.write is not None
@@ -357,8 +358,9 @@ def test_rejects_a_skill_that_talks_about_credentials(catalog_copy, phrase):
load_catalog(catalog_copy)
-def test_rejects_a_minted_token_that_outlives_the_hour(catalog_copy):
- _rewrite_github(catalog_copy, "max_lifetime: 3600", "max_lifetime: 7200")
[email protected]("lifetime", ["7200", "null"])
+def test_rejects_a_minted_token_that_outlives_the_hour(catalog_copy, lifetime):
+ _rewrite_github(catalog_copy, "max_lifetime: 3600", f"max_lifetime: {lifetime}")
with pytest.raises(CatalogError, match="(?s)github is invalid.*at most 3600"):
load_catalog(catalog_copy)
@@ -541,6 +543,7 @@ def test_loads_a_static_client_with_its_endpoints(catalog_copy):
),
("refresh: rotating", "refresh: none", "rotating or reusable"),
("max_lifetime: 3600", "max_lifetime: 60", "max_lifetime"),
+ ("max_lifetime: 3600", "max_lifetime: null", "name its max_lifetime"),
("account_id: account.id", "account_id: account/id", "account_id"),
(
" redirect: [loopback, core]\n",
@@ -840,7 +843,7 @@ auth:
headers: { X-Key: "{api_key}" }
account_id: account.id
label: account.email
-token: { kind: pass_through, max_lifetime: 3600 }
+token: { kind: pass_through, max_lifetime: null }
mcp:
servers:
- name: example
@@ -869,7 +872,10 @@ def test_the_shipped_datadog_entry_puts_both_keys_in_its_mcp_headers():
"DD_APPLICATION_KEY": "{application_key}",
}
assert sign_in.identity.headers == {"DD-API-KEY": "{api_key}"}
- assert definition.token is not None and definition.token.max_lifetime == 3600
+ # A key never expires, so it is never handed to an agent.
+ assert definition.token is not None
+ assert definition.token.max_lifetime is None
+ assert definition.token.issued_to_agents is False
def test_loads_an_api_key_entry(catalog_copy):
@@ -937,9 +943,9 @@ def test_loads_an_api_key_entry_whose_tool_is_a_cli(catalog_copy):
),
(" refresh: none\n", " refresh: rotating\n", "refresh is none"),
(
+ "token: { kind: pass_through, max_lifetime: null }",
"token: { kind: pass_through, max_lifetime: 3600 }",
- "token: { kind: pass_through, max_lifetime: 7200 }",
- "at most an hour",
+ "never handed to an agent",
),
(
"tools: { mode: pass_through }",
diff --git a/core/tests/switch_core/connections/test_registry.py b/core/tests/switch_core/connections/test_registry.py
index 55ebfc537..71949c6a6 100644
--- a/core/tests/switch_core/connections/test_registry.py
+++ b/core/tests/switch_core/connections/test_registry.py
@@ -226,15 +226,34 @@ def test_a_service_with_no_app_to_set_up_is_just_not_set_up(
tmp_path: Path, session_factory
) -> None:
broker = _broker(_catalog(tmp_path, STATIC), session_factory, {}, None)
+ atlassian = broker.unavailable("atlassian")
+ assert atlassian is not None
+ assert (atlassian.code, atlassian.reason) == (
+ "not_set_up",
+ "Atlassian is not set up on this server.",
+ )
+ assert broker.server_setup_needed("atlassian") is False
+ asana = broker.unavailable("asana")
+ assert asana is not None and asana.code == "coming_soon"
+
+
+def test_a_key_that_never_expires_is_neither_connected_nor_granted(
+ tmp_path: Path, session_factory
+) -> None:
+ catalog = _catalog(tmp_path, STATIC)
+ adapters = build_adapters(
+ catalog, github_app=None, oauth_clients={}, http=HTTP, registration=REG
+ )
+ broker = _broker(catalog, session_factory, adapters, None)
datadog = broker.unavailable("datadog")
assert datadog is not None
assert (datadog.code, datadog.reason) == (
- "not_set_up",
- "Datadog is not set up on this server.",
+ "key_never_expires",
+ "Datadog keys do not expire and only Datadog can revoke them, so Switch "
+ "does not hand them to agents.",
)
+ assert broker.connectable("datadog") is False
assert broker.server_setup_needed("datadog") is False
- asana = broker.unavailable("asana")
- assert asana is not None and asana.code == "coming_soon"
def test_a_replaced_adapter_is_used_at_once(tmp_path: Path, session_factory) -> None:
diff --git a/core/tests/switch_core/db/test_workspace_service_store.py b/core/tests/switch_core/db/test_workspace_service_store.py
index b60c704da..9595f5a36 100644
--- a/core/tests/switch_core/db/test_workspace_service_store.py
+++ b/core/tests/switch_core/db/test_workspace_service_store.py
@@ -1,6 +1,7 @@
"""A workspace admin's switch per service, against Postgres.
-No row means on. The isolation test writes through the restricted role the
+No row means the workspace's default, off for a workspace made since services
+started off. The isolation test writes through the restricted role the
server connects as, so a missing policy fails it rather than being bypassed
by the superuser's exemption.
"""
@@ -10,15 +11,16 @@ from __future__ import annotations
import uuid
import pytest
-from sqlalchemy import select, text
+from sqlalchemy import select, text, update
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
-from switch_core.db.models import Tenant, User, WorkspaceServiceSetting
+from switch_core.db.models import TENANT_ZERO_ID, Tenant, User, WorkspaceServiceSetting
from switch_core.db.session_scope import tenant_session
from switch_core.db.stores.workspace_service_store import WorkspaceServiceStore
from tests.conftest import RLSHarness
STORE = WorkspaceServiceStore()
+SERVICES = ["atlassian", "datadog", "github"]
async def _user(session_factory: async_sessionmaker[AsyncSession], name: str) -> str:
@@ -33,26 +35,69 @@ async def _user(session_factory: async_sessionmaker[AsyncSession], name: str) ->
return user.id
+async def _on_by_default(session_factory: async_sessionmaker[AsyncSession]) -> None:
+ async with session_factory() as session:
+ await session.execute(
+ update(Tenant)
+ .where(Tenant.id == TENANT_ZERO_ID)
+ .values(services_on_by_default=True)
+ )
+ await session.commit()
+
+
class TestSwitch:
- async def test_with_no_row_every_service_is_on(self, session_factory) -> None:
+ async def test_a_new_workspace_with_no_row_has_every_service_off(
+ self, session_factory
+ ) -> None:
async with session_factory() as session:
- assert await STORE.is_enabled(session, "datadog") is True
- assert await STORE.disabled_services(session) == set()
+ assert await STORE.on_by_default(session) is False
+ assert await STORE.is_enabled(session, "datadog") is False
+ assert await STORE.disabled_services(session, SERVICES) == set(SERVICES)
assert await STORE.list_settings(session) == {}
- async def test_off_then_on_round_trips(self, session_factory) -> None:
+ async def test_a_workspace_on_by_default_with_no_row_has_every_service_on(
+ self, session_factory
+ ) -> None:
+ await _on_by_default(session_factory)
+ async with session_factory() as session:
+ assert await STORE.is_enabled(session, "datadog") is True
+ assert await STORE.disabled_services(session, SERVICES) == set()
+
+ async def test_on_then_off_round_trips_in_a_new_workspace(
+ self, session_factory
+ ) -> None:
+ admin = await _user(session_factory, "admin")
+ async with session_factory() as session:
+ await STORE.set_enabled(session, "datadog", True, admin)
+ await session.commit()
+ assert await STORE.is_enabled(session, "datadog") is True
+ assert await STORE.is_enabled(session, "atlassian") is False
+ assert await STORE.disabled_services(session, SERVICES) == {
+ "atlassian",
+ "github",
+ }
+
+ await STORE.set_enabled(session, "datadog", False, admin)
+ await session.commit()
+ assert await STORE.is_enabled(session, "datadog") is False
+ assert await STORE.disabled_services(session, SERVICES) == set(SERVICES)
+
+ async def test_off_then_on_round_trips_in_a_workspace_on_by_default(
+ self, session_factory
+ ) -> None:
+ await _on_by_default(session_factory)
admin = await _user(session_factory, "admin")
async with session_factory() as session:
await STORE.set_enabled(session, "datadog", False, admin)
await session.commit()
assert await STORE.is_enabled(session, "datadog") is False
assert await STORE.is_enabled(session, "atlassian") is True
- assert await STORE.disabled_services(session) == {"datadog"}
+ assert await STORE.disabled_services(session, SERVICES) == {"datadog"}
await STORE.set_enabled(session, "datadog", True, admin)
await session.commit()
assert await STORE.is_enabled(session, "datadog") is True
- assert await STORE.disabled_services(session) == set()
+ assert await STORE.disabled_services(session, SERVICES) == set()
async def test_the_same_switch_twice_is_one_row_naming_the_last_admin(
self, session_factory
@@ -81,7 +126,14 @@ class TestIsolation:
theirs = f"tenant-{uuid.uuid4().hex[:8]}"
async with rls_harness.owner() as session:
for tenant_id in (mine, theirs):
- session.add(Tenant(id=tenant_id, slug=tenant_id, name=tenant_id))
+ session.add(
+ Tenant(
+ id=tenant_id,
+ slug=tenant_id,
+ name=tenant_id,
+ services_on_by_default=True,
+ )
+ )
await session.commit()
admin = await _user(rls_harness.owner, "admin")
@@ -96,7 +148,7 @@ class TestIsolation:
)
assert raw.all() == []
assert await STORE.is_enabled(session, "datadog") is True
- assert await STORE.disabled_services(session) == set()
+ assert await STORE.disabled_services(session, SERVICES) == set()
async with tenant_session(rls_harness.restricted, mine) as session:
- assert await STORE.disabled_services(session) == {"datadog"}
+ assert await STORE.disabled_services(session, SERVICES) == {"datadog"}
diff --git a/core/tests/switch_core/gateway/test_github_connections.py b/core/tests/switch_core/gateway/test_github_connections.py
index 14c24f309..8094a201a 100644
--- a/core/tests/switch_core/gateway/test_github_connections.py
+++ b/core/tests/switch_core/gateway/test_github_connections.py
@@ -639,6 +639,7 @@ async def test_with_the_flag_off_the_workspace_switch_is_ignored(github_app):
@pytest.mark.parametrize("github_app", [True], indirect=True)
async def test_switched_off_mid_flow_the_sign_in_is_revoked_and_not_kept(github_app):
client, github, identity, factory = github_app
+ await _switch_github(factory, identity["user"].id, True)
flow_id = await authorize(client)
await relay(client, flow_id)
await _switch_github(factory, identity["user"].id, False)
diff --git a/core/tests/switch_core/gateway/test_service_connections.py b/core/tests/switch_core/gateway/test_service_connections.py
index d459f0554..7db418543 100644
--- a/core/tests/switch_core/gateway/test_service_connections.py
+++ b/core/tests/switch_core/gateway/test_service_connections.py
@@ -42,6 +42,7 @@ from tests.switch_core.connections.service_harness import (
build_service_harness,
connect,
grant_directly,
+ services_on_by_default,
)
from tests.switch_core.gateway.test_tenant_api_routes import (
TENANT_A,
@@ -506,6 +507,7 @@ class TestWorkspaceSwitch:
async def test_the_list_says_which_services_the_workspace_has_on(
self, gated: Harness
) -> None:
+ await services_on_by_default(gated.session_factory)
owner = await add_member(gated.session_factory, "ada")
await connect(gated.session_factory, owner.id, consent="read")
await _switch_off(gated, "datadog", owner.id)
@@ -519,6 +521,24 @@ class TestWorkspaceSwitch:
assert entries["github"]["consent"] == "read"
assert entries["atlassian"]["consent"] is None
+ async def test_a_new_workspace_reads_every_service_off_until_one_is_switched_on(
+ self, gated: Harness
+ ) -> None:
+ owner = await add_member(gated.session_factory, "ada")
+ assert all(
+ entry["workspace_enabled"] is False
+ for entry in (await _listed(gated, owner)).values()
+ )
+ async with gated.session_factory() as session:
+ await WorkspaceServiceStore().set_enabled(session, "github", True, owner.id)
+ await session.commit()
+
+ entries = await _listed(gated, owner)
+
+ assert {
+ slug for slug, entry in entries.items() if entry["workspace_enabled"]
+ } == {"github"}
+
async def test_with_the_gate_off_every_service_reads_as_on(
self, harness: Harness
) -> None:
diff --git a/core/tests/switch_core/gateway/test_service_flows.py b/core/tests/switch_core/gateway/test_service_flows.py
index ee71f5419..808efa008 100644
--- a/core/tests/switch_core/gateway/test_service_flows.py
+++ b/core/tests/switch_core/gateway/test_service_flows.py
@@ -681,6 +681,7 @@ class TestWorkspaceSwitch:
workspace_gate=True,
)
ada = await add_member(session_factory, "ada")
+ await _switch(session_factory, True, ada)
async with world.harness.client() as client:
console = Console(client, ada)
code = await _loopback_code(world, console)
@@ -703,6 +704,7 @@ class TestWorkspaceSwitch:
) -> None:
world = _world(session_factory, tmp_path / "catalog", workspace_gate=True)
ada = await add_member(session_factory, "ada")
+ await _switch(session_factory, True, ada)
async with world.harness.client() as client:
console = Console(client, ada)
code = await _loopback_code(world, console)
diff --git a/core/tests/switch_core/gateway/test_service_keys.py b/core/tests/switch_core/gateway/test_service_keys.py
index f6612f2bd..b7a74a432 100644
--- a/core/tests/switch_core/gateway/test_service_keys.py
+++ b/core/tests/switch_core/gateway/test_service_keys.py
@@ -1,15 +1,16 @@
-"""Connecting a service with a pasted key, and using it, against Postgres.
+"""A service connected with a pasted key, against Postgres.
-Datadog, the shipped entry, is the service: its API key is checked with the
-vendor (a stand-in transport here) before anything is stored, the connection
-keeps the fields as the token a session host is handed, and a grant hands that
-token out like any pass-through one.
+Datadog, the shipped entry, is the service. Its keys do not expire and only
+Datadog can revoke them, so Switch never hands one to an agent: a key is
+neither checked nor stored, nothing can be granted, and a connection and grant
+made before that rule are refused at issue time rather than dropped. The
+connection can still be disconnected.
"""
from __future__ import annotations
import json
-from datetime import UTC, datetime, timedelta
+import time
import httpx
import pytest
@@ -19,11 +20,12 @@ from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
from switch_core.connections.adapters.api_key import ApiKeyAdapter
from switch_core.connections.broker import ServiceBroker
from switch_core.connections.loader import CATALOG
-from switch_core.db.models import ServiceConnection
+from switch_core.db.models import ServiceConnection, ServiceTokenIssuance
from switch_core.db.stores.workspace_service_store import WorkspaceServiceStore
from tests.conftest import TEST_KEYRING
from tests.switch_core.connections.fake_vendor import FakeVendor
from tests.switch_core.connections.service_harness import (
+ STORE,
agent_with_key,
build_service_harness,
)
@@ -39,6 +41,10 @@ KEYS = {
"application_key": "app-key-xxxxxxxx",
"site": "datadoghq.eu",
}
+NEVER_EXPIRES = (
+ "Datadog keys do not expire and only Datadog can revoke them, so Switch "
+ "does not hand them to agents."
+)
class DatadogStandIn:
@@ -90,8 +96,54 @@ async def _connections(harness: Harness) -> list[ServiceConnection]:
return list(await session.scalars(select(ServiceConnection)))
+async def _connected_before(
+ session_factory: async_sessionmaker[AsyncSession],
+ owner_id: str,
+ agent_id: str,
+) -> None:
+ """A Datadog connection and grant as a server before the rule left them."""
+ token = json.dumps(
+ {
+ "secret": {
+ "api_key": KEYS["api_key"],
+ "application_key": KEYS["application_key"],
+ },
+ "public": {"site": KEYS["site"]},
+ },
+ separators=(",", ":"),
+ sort_keys=True,
+ )
+ async with session_factory() as session:
+ await STORE.save_connection(
+ session,
+ user_id=owner_id,
+ service="datadog",
+ consent="write",
+ granted_scopes=[],
+ account_id="dd-key",
+ external_identity="Datadog key · datadoghq.eu",
+ encrypted_secret=TEST_KEYRING.encrypt(
+ json.dumps({"access_token": token, "expires_at": time.time()})
+ ),
+ oauth_client_id=None,
+ )
+ await STORE.save_grant(
+ session,
+ agent_id=agent_id,
+ owner_id=owner_id,
+ service="datadog",
+ access="write",
+ tool_mode="deny",
+ tools=[],
+ resources={},
+ account_id="dd-key",
+ created_by=owner_id,
+ )
+ await session.commit()
+
+
class TestConnect:
- async def test_the_list_offers_the_key_form(self, service) -> None:
+ async def test_the_list_says_why_it_cannot_be_connected(self, service) -> None:
harness, _ = service
owner = await add_member(harness.session_factory, "ada")
async with harness.client() as client:
@@ -99,100 +151,38 @@ class TestConnect:
"/gateway/service-connections", cookies=cookies_for(owner)
)
entry = next(e for e in listed.json()["connections"] if e["slug"] == "datadog")
- assert entry["connectable"] is True
+ assert entry["connectable"] is False
assert entry["auth_type"] == "api_key"
- form = entry["key"]
- assert [(f["name"], f["secret"]) for f in form["fields"]] == [
- ("api_key", True),
- ("application_key", True),
- ("site", False),
- ]
- assert "datadoghq.eu" in form["fields"][2]["choices"]
- assert form["help_url"].startswith("https://docs.datadoghq.com/")
- github = next(e for e in listed.json()["connections"] if e["slug"] == "github")
- assert github["key"] is None
-
- async def test_a_key_the_vendor_accepts_is_stored_and_never_sent_back(
- self, service, datadog: DatadogStandIn
- ) -> None:
- harness, _ = service
- owner = await add_member(harness.session_factory, "ada")
-
- response = await _connect(harness, owner, KEYS)
-
- assert response.status_code == 200, response.text
- assert response.json()["external_identity"] == "Datadog key · datadoghq.eu"
- assert KEYS["api_key"] not in response.text
- [request] = datadog.requests
- assert str(request.url) == "https://api.datadoghq.eu/api/v1/validate"
- assert request.headers["DD-API-KEY"] == KEYS["api_key"]
- [connection] = await _connections(harness)
- assert (connection.service, connection.consent, connection.status) == (
- "datadog",
- "write",
- "active",
+ assert (entry["unavailable_code"], entry["unavailable_reason"]) == (
+ "key_never_expires",
+ NEVER_EXPIRES,
)
- assert KEYS["api_key"] not in connection.encrypted_secret
- stored = json.loads(TEST_KEYRING.decrypt(connection.encrypted_secret))
- assert json.loads(stored["access_token"]) == {
- "secret": {
- "api_key": KEYS["api_key"],
- "application_key": KEYS["application_key"],
- },
- "public": {"site": "datadoghq.eu"},
- }
+ assert entry["token_lifetime"] is None
- async def test_a_refused_key_is_not_stored(
+ async def test_a_key_is_neither_checked_nor_stored(
self, service, datadog: DatadogStandIn
) -> None:
harness, _ = service
owner = await add_member(harness.session_factory, "ada")
- response = await _connect(harness, owner, {**KEYS, "api_key": "WRONG-KEY"})
-
- assert response.status_code == 422, response.text
- assert "refused the key" in response.json()["detail"]
- assert await _connections(harness) == []
-
- @pytest.mark.parametrize(
- ("fields", "message"),
- [
- ({**KEYS, "site": "evil.example"}, "must be one of"),
- ({**KEYS, "api_key": "has a space"}, "without spaces"),
- ({k: v for k, v in KEYS.items() if k != "application_key"}, "required"),
- ({**KEYS, "extra": "x"}, "takes no field named extra"),
- ],
- ids=["site-not-offered", "space", "missing", "unknown"],
- )
- async def test_malformed_fields_are_refused_before_the_vendor_is_asked(
- self, service, datadog: DatadogStandIn, fields, message
- ) -> None:
- harness, _ = service
- owner = await add_member(harness.session_factory, "ada")
-
- response = await _connect(harness, owner, fields)
+ response = await _connect(harness, owner, KEYS)
- assert response.status_code == 422, response.text
- assert message in response.json()["detail"]
+ assert response.status_code == 403, response.text
+ assert response.json() == {
+ "detail": NEVER_EXPIRES,
+ "code": "forbidden",
+ "retryable": False,
+ }
assert datadog.requests == []
+ assert await _connections(harness) == []
- async def test_a_key_someone_else_linked_is_refused(self, service) -> None:
- harness, _ = service
- ada = await add_member(harness.session_factory, "ada")
- grace = await add_member(harness.session_factory, "grace")
- assert (await _connect(harness, ada, KEYS)).status_code == 200
-
- response = await _connect(harness, grace, KEYS)
-
- assert response.status_code == 409, response.text
- assert response.json()["code"] == "account_linked_elsewhere"
-
- async def test_disconnecting_says_the_key_still_works_at_the_vendor(
+ async def test_a_key_connected_before_can_still_be_disconnected(
self, service
) -> None:
harness, _ = service
owner = await add_member(harness.session_factory, "ada")
- await _connect(harness, owner, KEYS)
+ agent_id, _ = await agent_with_key(harness.session_factory, owner, "sre")
+ await _connected_before(harness.session_factory, owner.id, agent_id)
async with harness.client() as client:
response = await client.delete(
@@ -205,21 +195,14 @@ class TestConnect:
class TestUse:
- async def test_a_granted_agent_is_handed_the_fields_for_an_hour(
+ async def test_a_grant_made_before_is_refused_at_issue_and_kept(
self, service
) -> None:
harness, _ = service
owner = await add_member(harness.session_factory, "ada")
agent_id, key = await agent_with_key(harness.session_factory, owner, "sre")
- await _connect(harness, owner, KEYS)
+ await _connected_before(harness.session_factory, owner.id, agent_id)
async with harness.client() as client:
- granted = await client.put(
- f"/gateway/agents/{agent_id}/service-grants/datadog",
- json={"resources": {}},
- cookies=cookies_for(owner),
- )
- assert granted.status_code == 200, granted.text
- assert granted.json()["grant"]["access"] == "write"
grants = await client.get(
f"/agents/{agent_id}/service-grants", headers=bearer(key)
)
@@ -227,22 +210,34 @@ class TestUse:
f"/agents/{agent_id}/service-tokens/datadog", headers=bearer(key)
)
- assert token.status_code == 200, token.text
- body = token.json()
- assert json.loads(body["token"])["secret"]["api_key"] == KEYS["api_key"]
- expires_at = datetime.fromisoformat(body["expires_at"])
- assert expires_at <= datetime.now(UTC) + timedelta(hours=1, minutes=1)
- [grant] = grants.json()["grants"]
- assert grant["mcp_servers"] == [
- {
- "name": "datadog",
- "url": "https://mcp.{site}/api/unstable/mcp-server/mcp",
- "headers": {
- "DD_API_KEY": "{api_key}",
- "DD_APPLICATION_KEY": "{application_key}",
- },
- }
- ]
+ # Listed, so the session asks and is told why, rather than losing it
+ # without a word.
+ assert [grant["service"] for grant in grants.json()["grants"]] == ["datadog"]
+ assert token.status_code == 403, token.text
+ assert token.json()["error"] == {
+ "code": "forbidden",
+ "message": NEVER_EXPIRES,
+ "retryable": False,
+ }
+ assert KEYS["api_key"] not in token.text
+ async with harness.session_factory() as session:
+ assert list(await session.scalars(select(ServiceTokenIssuance))) == []
+
+ async def test_a_new_grant_is_refused(self, service) -> None:
+ harness, _ = service
+ owner = await add_member(harness.session_factory, "ada")
+ agent_id, _ = await agent_with_key(harness.session_factory, owner, "sre")
+ other_id, _ = await agent_with_key(harness.session_factory, owner, "ops")
+ await _connected_before(harness.session_factory, owner.id, other_id)
+ async with harness.client() as client:
+ granted = await client.put(
+ f"/gateway/agents/{agent_id}/service-grants/datadog",
+ json={"resources": {}},
+ cookies=cookies_for(owner),
+ )
+
+ assert granted.status_code == 422, granted.text
+ assert granted.json()["detail"] == NEVER_EXPIRES
class TestWorkspaceSwitch:
diff --git a/core/tests/switch_core/gateway/test_workspace_services.py b/core/tests/switch_core/gateway/test_workspace_services.py
index 4b421fc8a..5bcaba2bc 100644
--- a/core/tests/switch_core/gateway/test_workspace_services.py
+++ b/core/tests/switch_core/gateway/test_workspace_services.py
@@ -35,6 +35,7 @@ from tests.switch_core.connections.service_harness import (
build_service_harness,
connect,
grant_directly,
+ services_on_by_default,
)
from tests.switch_core.gateway.test_tenant_api_routes import TENANT_A, _make_tenant
from tests.switch_core.management.harness import Harness, add_member, cookies_for
@@ -232,16 +233,19 @@ class TestRequests:
class TestResults:
- async def test_untouched_services_read_on_with_nobody_named(
- self, harness: Harness
+ @pytest.mark.parametrize("on_by_default", [False, True])
+ async def test_untouched_services_take_the_workspaces_default_with_nobody_named(
+ self, harness: Harness, on_by_default: bool
) -> None:
+ if on_by_default:
+ await services_on_by_default(harness.session_factory)
admin = await _person(harness.session_factory, "admin", member_role="admin")
services = _by_slug(await _get(harness, admin))
assert set(services) == {"atlassian", "datadog", "github", "google-workspace"}
assert services["datadog"] == {
"slug": "datadog",
"name": "Datadog",
- "enabled": True,
+ "enabled": on_by_default,
"updated_by_name": None,
"updated_at": None,
"connected_members": 0,
diff --git a/core/tests/switch_core/management/test_my_context.py b/core/tests/switch_core/management/test_my_context.py
index d531668a5..307f9161a 100644
--- a/core/tests/switch_core/management/test_my_context.py
+++ b/core/tests/switch_core/management/test_my_context.py
@@ -387,7 +387,8 @@ class TestGivingAgentsServices:
datadog = next(
entry for entry in context["services"] if entry["slug"] == "datadog"
)
- assert datadog["unavailable_code"] == "not_set_up"
+ assert datadog["unavailable_code"] == "key_never_expires"
+ assert datadog["available"] is False
taken = await _op(
client,
diff --git a/core/tests/switch_core/test_migration_workspace_services_off_by_default.py b/core/tests/switch_core/test_migration_workspace_services_off_by_default.py
new file mode 100644
index 000000000..b6aa92600
--- /dev/null
+++ b/core/tests/switch_core/test_migration_workspace_services_off_by_default.py
@@ -0,0 +1,76 @@
+"""`f68b679599ab` keeps services on for the workspaces that had members.
+
+`test_migration_parity.py` replays the chain into an empty database, so it
+cannot see what the revision does to an existing deployment's tenants. This
+seeds one workspace with a member and one without, stops the chain one
+revision short, runs it, and reads the column it adds.
+"""
+
+from __future__ import annotations
+
+from sqlalchemy import text
+
+from tests.switch_core.test_migration_operator_owns_tenant_zero import (
+ _drop_fixture,
+ _fixture_engine,
+ _upgrade_to,
+)
+
+_PRE_MIGRATION_REVISION = "c7715ebb95c9"
+_MIGRATION_UNDER_TEST = "f68b679599ab"
+_TENANT_ZERO_ID = "00000000-0000-0000-0000-000000000000"
+
+
+async def test_a_workspace_with_members_stays_on_and_one_without_starts_off(
+ postgres_url: str,
+) -> None:
+ engine = await _fixture_engine(postgres_url)
+ try:
+ async with engine.begin() as connection:
+ await connection.run_sync(_upgrade_to(_PRE_MIGRATION_REVISION))
+
+ async with engine.begin() as connection:
+ await connection.execute(
+ text(
+ """
+ INSERT INTO users (id, name, email, role, password_hash, metadata)
+ VALUES ('ada', 'Ada', '[email protected]', 'user', 'bcrypt-hash',
+ NULL)
+ """
+ )
+ )
+ await connection.execute(
+ text(
+ f"""
+ INSERT INTO tenant_members (tenant_id, user_id, role)
+ VALUES ('{_TENANT_ZERO_ID}', 'ada', 'owner')
+ """
+ )
+ )
+ await connection.execute(
+ text(
+ "INSERT INTO tenants (id, slug, name) "
+ "VALUES ('empty', 'empty', 'Empty')"
+ )
+ )
+
+ async with engine.begin() as connection:
+ await connection.run_sync(_upgrade_to(_MIGRATION_UNDER_TEST))
+
+ async with engine.begin() as connection:
+ await connection.execute(
+ text(
+ "INSERT INTO tenants (id, slug, name) VALUES ('new', 'new', 'New')"
+ )
+ )
+
+ async with engine.connect() as connection:
+ rows = await connection.execute(
+ text("SELECT id, services_on_by_default FROM tenants")
+ )
+ on = {row.id: row.services_on_by_default for row in rows}
+ finally:
+ await engine.dispose()
+ await _drop_fixture(postgres_url)
+
+ assert on == {_TENANT_ZERO_ID: True, "empty": False, "new": False}
diff --git a/deploy/hosted/machine/README.md b/deploy/hosted/machine/README.md
index 451f182d2..1a387c559 100644
--- a/deploy/hosted/machine/README.md
+++ b/deploy/hosted/machine/README.md
@@ -166,6 +166,12 @@ instance of the image must give the files on it the same owners.
`agent-users` (16 by default) is how many agents each controller on a machine
can run at once.
+`install.sh` installs the package it is given with `npm install --ignore-scripts`
+and checks no signature: give it a package from a controller release whose
+signature you checked (the controller's `install.sh` shows how), since the image
+runs what it bakes. The controllers then update only to releases signed with a
+key built into that package.
+
## Running it
- Core needs the `hosted_agents` and `agent_management` feature flags as
diff --git a/deploy/hosted/machine/install.sh b/deploy/hosted/machine/install.sh
index 81ca9d385..9e7061e04 100644
--- a/deploy/hosted/machine/install.sh
+++ b/deploy/hosted/machine/install.sh
@@ -89,7 +89,7 @@ while [ "$slot" -le "$agent_users" ]; do
done
install -d -o root -g root -m 0755 /opt/switch/controller /usr/local/libexec /etc/switch-hosted /data
-npm install --global --prefix /opt/switch/controller "$controller_package"
+npm install --global --ignore-scripts --prefix /opt/switch/controller "$controller_package"
cli=/opt/switch/controller/bin/switch-agent-controller
"$cli" --version >/dev/null
diff --git a/docs/design/service-connections-v2.md b/docs/design/service-connections-v2.md
index 7d6b6a6f1..3270095fb 100644
--- a/docs/design/service-connections-v2.md
+++ b/docs/design/service-connections-v2.md
@@ -127,7 +127,12 @@ A removed grant stops a running session within a minute: the agent host reads
the grants again at most every 30 seconds while it holds a token, drops one
whose grant has moved on or gone, and the next ask is refused. While Core
cannot be reached that check cannot run, and `use_until` bounds it to the
-hour. A token already handed out stays valid at the vendor until it expires.
+hour. A token already handed out stays valid at the vendor until it expires:
+for a pass-through service nothing can revoke the owner's token alone (for
+Google, revoking it would end the owner's whole sign-in), so its issuance
+record is marked withdrawn and the change's `warning` says until when it may
+keep working, up to the entry's `max_lifetime` (an hour for Google, eight
+hours for Atlassian, whose tokens cannot be asked for shorter).
## Connecting
@@ -278,8 +283,11 @@ disconnecting still works. A slug outside the catalog stops the server.
A workspace admin switches each catalog service on or off for the workspace
(`GET` and `PUT /gateway/workspace/services[/{service}]`, admins and owners,
-and the operator in a workspace they belong to). A service with no setting is
-on, so an upgraded server behaves as before; a row is written only when an
+and the operator in a workspace they belong to). A service with no setting
+takes the workspace's default, `tenants.services_on_by_default`: off for every
+workspace made since services started off, so a new workspace has none until
+an admin switches each on, and on for the workspaces that already had members
+then, so nothing they used stopped working. A row is written only when an
admin touches the switch, and each change is audited
(`workspace_service.enabled` / `.disabled`). The switch applies only with the
`service_connections` flag on; with it off, GitHub works as it always has.
@@ -296,7 +304,8 @@ service out, so a running session loses the service within half a minute, as
it does a removed grant: its host restarts it without the service. A token
already handed out may be used until that restart, except GitHub's, which the
switch queues and revokes before it answers (`warning` when some could not be
-yet; the five-minute tick keeps trying). On again, the grants come back with
+yet; the five-minute tick keeps trying). A pass-through token is marked
+withdrawn, and the `warning` says until when it may keep working. On again, the grants come back with
no re-grant.
The service list (`GET /gateway/service-connections`) carries
@@ -318,6 +327,11 @@ what each person can do about it (`UnavailableCode` in
- `not_set_up`: nothing on this server connects it, and no app would.
- `not_fully_set_up`: it can be connected but not granted: its app lacks a
part (a GitHub App configured with no signing key).
+- `key_never_expires`: it connects with a key that never expires
+ (`token.max_lifetime: null`), which Switch never hands to an agent, so it
+ can be neither connected nor granted. One already connected can still be
+ disconnected, and an existing grant is refused at issue time (403
+ `forbidden`).
`get_my_context`'s `services` carry the same code.
@@ -346,7 +360,7 @@ auth:
account_id: user.id # optional: without it, the key's SHA-256
label: user.email # optional: without it, the name and choices
help_url: https://docs.example.com/keys
-token: { kind: pass_through, max_lifetime: 3600 } # handed out an hour at a time
+token: { kind: pass_through, max_lifetime: null } # never handed to an agent
mcp:
servers:
- name: example
@@ -358,7 +372,15 @@ tools: { mode: pass_through }
The loader refuses a template naming an unknown field, a URL naming a secret
one, a server without headers, an entry naming `access` (a key reaches
-whatever its vendor let it), and a token handed out for longer than an hour.
+whatever its vendor let it), and a `max_lifetime` other than null.
+
+**A key is never handed to an agent.** It does not expire and only its vendor
+can revoke it, so whatever ran beside the agent could keep it for good, past a
+removed grant or a disconnect. The broker refuses to issue one (403
+`forbidden`), the services list marks it `key_never_expires`, and it can be
+neither connected nor granted; one already connected can be disconnected.
+What follows describes the connection as it was built, which stays in place
+for a later server-side use of the key.
- **Connecting.** Switch Console shows the entry's fields (the services list
carries them as `key`) and sends them to
@@ -368,10 +390,9 @@ whatever its vendor let it), and a token handed out for longer than an hour.
the vendor accepts them; a refusal names the fields to check. One account
is linked to one person in a workspace, as for a sign-in. Re-pasting
replaces the key in place, keeping the grants.
-- **The token.** The connection's secret is the token a session host is
- handed: compact JSON, `{"public": {...}, "secret": {...}}`. Each issue
- hands it out for an hour, so the grant checks run at least hourly, and the
- host's grant check reaches running sessions within half a minute.
+- **The token.** The connection's secret is compact JSON,
+ `{"public": {...}, "secret": {...}}`, the shape a session host would render
+ into its templates.
- **Sessions.** The host renders each MCP server's `url` and `headers`, or the
tool's `env`, from the token, and redacts every secret field on its own as
well as the whole token. The key never reaches the coding tool.
@@ -482,8 +503,9 @@ Built from a spike against a test Workspace with an Internal app:
browser signed in to another Google account (a personal one, or another
organization's) does not pick it unasked. `prompt` takes several values,
space-separated, as OAuth writes them.
-- **Tokens.** Access tokens lived 3,599 s; `max_lifetime` is 3,920, Google's
- documented sample. Agents still ask again hourly.
+- **Tokens.** Access tokens lived 3,599 s, so `max_lifetime` is 3,600: a
+ token handed out never has more than an hour left, and one Google issued
+ for longer is refused rather than handed out.
- **The account** is OpenID's `sub`, labelled by `email`, from userinfo.
- **Scopes as Google names them.** Google answers with full scope URLs
(`email` comes back as `.../auth/userinfo.email`), and the level is read by