From cfb6eb894efc1947c3d663bc6e178dd1fba3edd2 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 20 Nov 2026 13:16:34 +0000 Subject: [PATCH 1/4] docs: clarify credential binding destination approval Credential guidance implied that mechanism presence alone grants approval and that custom secrets always replace header placeholders. Require approved destinations for each mechanism and explain authentication header stripping on denied kit routes. --- .../ai/sandboxes/configuration/credentials.md | 25 +++++++++++++------ 1 file changed, 18 insertions(+), 7 deletions(-) diff --git a/content/manuals/ai/sandboxes/configuration/credentials.md b/content/manuals/ai/sandboxes/configuration/credentials.md index 3ab366955e1..d971bb87da2 100644 --- a/content/manuals/ai/sandboxes/configuration/credentials.md +++ b/content/manuals/ai/sandboxes/configuration/credentials.md @@ -468,6 +468,11 @@ configured hosts and the placeholder appears in an HTTP request header, the proxy replaces it with the real value. Replacement applies only to HTTP request headers, not request bodies. The agent never sees the real secret. +On a kit route where credential bindings approve no usable service credential, +the proxy strips recognized authentication headers, such as `Authorization` +and `x-api-key`, even if they contain a custom secret. Other headers aren't +subject to this restriction. See [Credential bindings](#credential-bindings). + ### List custom secrets To find stored custom secrets by host, use `--host`: @@ -608,9 +613,10 @@ bindings: domains: [api.github.com, github.com] ``` -A binding is only an approval record: the presence of `apiKey` or `oauth` -authorizes that mechanism. Declining a credential writes no entry at all. -The real credential isn't stored in this file. +A binding is only an approval record: each mechanism must list approved +domains to authorize its use. A binding with no domains for either mechanism +is treated as missing. Declining a credential writes no entry at all. The real +credential isn't stored in this file. ### First-run approval @@ -622,7 +628,8 @@ to `credentials.yaml`. In non-interactive contexts (CI or `--detach`), there's no one to answer the prompt. In `sbx`, the sandbox starts with the credential withheld when no -binding exists. For a required credential, `sbx` prints a warning rather than +binding exists or the binding lists no domains for either mechanism. For a +required credential, `sbx` prints a warning rather than failing sandbox creation. This is a limitation of `sbx` enforcement: kit authors shouldn't rely on a required credential being available merely because the sandbox started. @@ -630,9 +637,13 @@ sandbox started. Pre-create the binding by running the kit interactively once or by writing `credentials.yaml` directly before running unattended. -The bindings file gates whether a third-party kit can use a service -credential. The kit's credential injection rules and network permissions still -constrain which requests can carry the credential. +For kit-declared routes handled by the local proxy, API keys are sent only to +destinations approved under `apiKey.domains`. OAuth tokens and keys obtained +through OAuth require approval under `oauth.domains`. Approval for one +mechanism doesn't authorize the other. Built-in routes and aliases managed by +the daemon retain service-level authorization. The kit's credential injection +rules and network permissions still constrain which requests can carry the +credential. ### Kits that require a binding From 3d8d1739e052feb33df3bdde9baf902eae305e70 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 20 Nov 2026 13:26:48 +0000 Subject: [PATCH 2/4] docs: explain credential approvals from the reader perspective The credential guide described routing internals instead of explaining what readers need to approve. Put separate API key and OAuth domain approvals next to the binding example and explain how denied requests affect custom secrets. --- .../ai/sandboxes/configuration/credentials.md | 38 +++++++++---------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/content/manuals/ai/sandboxes/configuration/credentials.md b/content/manuals/ai/sandboxes/configuration/credentials.md index d971bb87da2..fd35607d678 100644 --- a/content/manuals/ai/sandboxes/configuration/credentials.md +++ b/content/manuals/ai/sandboxes/configuration/credentials.md @@ -468,10 +468,11 @@ configured hosts and the placeholder appears in an HTTP request header, the proxy replaces it with the real value. Replacement applies only to HTTP request headers, not request bodies. The agent never sees the real secret. -On a kit route where credential bindings approve no usable service credential, -the proxy strips recognized authentication headers, such as `Authorization` -and `x-api-key`, even if they contain a custom secret. Other headers aren't -subject to this restriction. See [Credential bindings](#credential-bindings). +Custom secrets don't override [credential bindings](#credential-bindings) +for third-party kits. If a kit tries to authenticate to a domain without the +required approval, the proxy removes authentication headers such as +`Authorization` and `x-api-key`, including any custom secrets in them. +Custom secrets in other headers aren't affected by this restriction. ### List custom secrets @@ -599,9 +600,14 @@ mechanisms: and the proxy handles token refresh and routing. OAuth domains include the token endpoint host and any resource hosts declared by the kit. -Each mechanism takes a `domains` list that records the domains you approved. +For each credential type you approve, list its domains under `apiKey.domains` +or `oauth.domains`. Approving a domain for an API key doesn't approve sending +OAuth tokens there, or vice versa. Keys obtained through OAuth use the +`oauth.domains` approval too. + `sbx` asks for approval when a kit requests domains that the existing binding -doesn't cover. +doesn't cover. If a third-party kit adds a domain, it needs your approval +before sending your stored credentials there. ```yaml bindings: @@ -613,10 +619,9 @@ bindings: domains: [api.github.com, github.com] ``` -A binding is only an approval record: each mechanism must list approved -domains to authorize its use. A binding with no domains for either mechanism -is treated as missing. Declining a credential writes no entry at all. The real -credential isn't stored in this file. +A binding with no domains under either `apiKey` or `oauth` is treated as +missing. Declining a credential writes no entry at all. The binding records +your approval; the real credential isn't stored in this file. ### First-run approval @@ -629,21 +634,16 @@ to `credentials.yaml`. In non-interactive contexts (CI or `--detach`), there's no one to answer the prompt. In `sbx`, the sandbox starts with the credential withheld when no binding exists or the binding lists no domains for either mechanism. For a -required credential, `sbx` prints a warning rather than -failing sandbox creation. This is a limitation of `sbx` enforcement: kit authors +required credential, `sbx` prints a warning rather than failing sandbox creation. +This is a limitation of `sbx` enforcement: kit authors shouldn't rely on a required credential being available merely because the sandbox started. Pre-create the binding by running the kit interactively once or by writing `credentials.yaml` directly before running unattended. -For kit-declared routes handled by the local proxy, API keys are sent only to -destinations approved under `apiKey.domains`. OAuth tokens and keys obtained -through OAuth require approval under `oauth.domains`. Approval for one -mechanism doesn't authorize the other. Built-in routes and aliases managed by -the daemon retain service-level authorization. The kit's credential injection -rules and network permissions still constrain which requests can carry the -credential. +The kit's credential injection rules and network permissions still constrain +which requests can carry the credential. ### Kits that require a binding From 68c4b6d63846cbf8d8bb4811b0c739582bc537a3 Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 20 Nov 2026 13:39:59 +0000 Subject: [PATCH 3/4] docs: clarify credential domain approvals for kits The credential guide repeated kit scope and mixed approval concepts. Explain the domain lists beside the example and state what happens to custom secrets in blocked authentication headers. --- .../ai/sandboxes/configuration/credentials.md | 63 +++++++------------ 1 file changed, 23 insertions(+), 40 deletions(-) diff --git a/content/manuals/ai/sandboxes/configuration/credentials.md b/content/manuals/ai/sandboxes/configuration/credentials.md index fd35607d678..be31b945756 100644 --- a/content/manuals/ai/sandboxes/configuration/credentials.md +++ b/content/manuals/ai/sandboxes/configuration/credentials.md @@ -468,11 +468,10 @@ configured hosts and the placeholder appears in an HTTP request header, the proxy replaces it with the real value. Replacement applies only to HTTP request headers, not request bodies. The agent never sees the real secret. -Custom secrets don't override [credential bindings](#credential-bindings) -for third-party kits. If a kit tries to authenticate to a domain without the -required approval, the proxy removes authentication headers such as -`Authorization` and `x-api-key`, including any custom secrets in them. -Custom secrets in other headers aren't affected by this restriction. +If credential approval blocks authentication on a kit-declared route, the proxy +removes authentication headers such as `Authorization` and `x-api-key`. This +also removes custom secrets placed in those headers. Custom secrets in other +headers aren't affected. See [Credential bindings](#credential-bindings). ### List custom secrets @@ -578,36 +577,22 @@ to `npm.pkg.github.com`, and the proxy replaces it with the token retrieved by ## Credential bindings -A credential bindings file records which credential mechanisms and domains -you've approved for each service. It lives at +Kits shipped with `sbx` don't need separate credential approval. Other kits ask +you to approve the credentials they request and the domains that can receive +them. `sbx` saves these approvals in `credentials.yaml` at `~/.config/sbx/credentials.yaml`, or `%APPDATA%\sbx\credentials.yaml` on -Windows. - -Third-party kits require an approved binding for each credential they use, -regardless of schema version. `sbx` creates one interactively the first time you -run such a kit (see [First-run approval](#first-run-approval)); you can also -write entries by hand. Credentials requested only by the built-in kits shipped -with `sbx` don't need a binding. +Windows. You can also write entries by hand. Each entry under `bindings` is keyed by a -[service identifier](#built-in-services) and approves one or both credential -mechanisms: - -- `apiKey` — approves injecting the service's stored API key. The value comes - from the [secret store](#stored-secrets) (`sbx secret set `); the - binding records approval, it doesn't hold or locate the value. -- `oauth` — approves the OAuth flow for the service. You sign in on the host, - and the proxy handles token refresh and routing. OAuth domains include the - token endpoint host and any resource hosts declared by the kit. +[service identifier](#built-in-services). Each service lists its approved +domains separately for API keys and OAuth: -For each credential type you approve, list its domains under `apiKey.domains` -or `oauth.domains`. Approving a domain for an API key doesn't approve sending -OAuth tokens there, or vice versa. Keys obtained through OAuth use the -`oauth.domains` approval too. +- `apiKey.domains` controls where the proxy can send the stored API key. +- `oauth.domains` controls where the proxy can send OAuth tokens, including API + keys obtained through OAuth. -`sbx` asks for approval when a kit requests domains that the existing binding -doesn't cover. If a third-party kit adds a domain, it needs your approval -before sending your stored credentials there. +Approval under one list doesn't grant approval under the other. If a kit +requests additional domains, `sbx` asks you to approve them. ```yaml bindings: @@ -619,14 +604,14 @@ bindings: domains: [api.github.com, github.com] ``` -A binding with no domains under either `apiKey` or `oauth` is treated as -missing. Declining a credential writes no entry at all. The binding records -your approval; the real credential isn't stored in this file. +The file stores your approvals, not your secrets. An entry with both domain +lists empty grants no access and is treated as missing. Declining a credential +writes no entry at all. ### First-run approval -When a third-party kit needs a credential that has no binding, `sbx` walks you -through approving one. For an API key, you can use a value already in the secret +When a kit needs a credential that has no binding, `sbx` walks you through +approving one. For an API key, you can use a value already in the secret store or enter one at the prompt. For OAuth, you approve the sign-in flow. In both cases, you approve the domains declared by the kit. `sbx` writes the entry to `credentials.yaml`. @@ -647,11 +632,9 @@ which requests can carry the credential. ### Kits that require a binding -Third-party kits require your approval to use credentials, regardless of -schema version. The built-in kits shipped with `sbx` can use credentials they -request without a binding. If a third-party v2 kit extends a built-in agent, -you must approve its use of the inherited credentials. You must also approve -a third-party kit that requests the same service itself. +Approval is required regardless of schema version. If a v2 kit extends a +built-in agent, you must approve its use of the inherited credentials. You must +also approve a kit that requests the same service itself. ## Registry credentials From 9146ff089b4dfa02f5dfb9aa9a65f3ca43c9b2ae Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Fri, 20 Nov 2026 14:53:55 +0000 Subject: [PATCH 4/4] docs: Remove version qualifier from kit credential approval Credential approval applies regardless of kit schema version. Refer to kits without a v2 qualifier in the inherited-credential guidance. --- content/manuals/ai/sandboxes/configuration/credentials.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/manuals/ai/sandboxes/configuration/credentials.md b/content/manuals/ai/sandboxes/configuration/credentials.md index be31b945756..a44241e9d6d 100644 --- a/content/manuals/ai/sandboxes/configuration/credentials.md +++ b/content/manuals/ai/sandboxes/configuration/credentials.md @@ -632,7 +632,7 @@ which requests can carry the credential. ### Kits that require a binding -Approval is required regardless of schema version. If a v2 kit extends a +Approval is required regardless of schema version. If a kit extends a built-in agent, you must approve its use of the inherited credentials. You must also approve a kit that requests the same service itself.