feat(connections): a client names the scopes it may ask, and a way takes the one covering its scope

auto-runtime.schema.json

@@ -400,16 +400,25 @@
                 "type": "string",
                 "enum": ["client_secret_basic", "client_secret_post", "private_key_jwt", "none"],
                 "description": "How the client authenticates at the token endpoint where the metadata of the authorization server leaves the choice; chosen from the client and the metadata when left out"
+              },
+              "scopes": {
+                "type": "array",
+                "items": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "minItems": 1,
+                "description": "The scopes the client may ask at its issuers, each as a provider's way writes it: a way takes the first client at its issuer that names every scope the way asks. Named for each client where several clients serve one issuer, and left out for a client that may ask any"
               }
             },
             "required": ["issuers", "client_id"],
             "additionalProperties": false
           },
-          "description": "The clients whoever runs the runtime registered at authorization servers, each with the issuers it is registered at, its client_id, and its client_secret, or its private_key with its algorithm, as a reference, or neither for a public client"
+          "description": "The clients whoever runs the runtime registered at authorization servers, each with the issuers it is registered at, its client_id, and its client_secret, or its private_key with its algorithm, as a reference, or neither for a public client, and the scopes it may ask, which each client names where several serve one issuer"
         },
         "auto_clients": {
           "type": "boolean",
-          "description": "Whether a provider whose way takes a registered client takes Auto's client too, through Auto's consent service, where none is registered at its issuer; true in local mode and false otherwise when left out. AUTO_CLIENTS wins over it"
+          "description": "Whether a provider whose way takes a registered client takes Auto's client too, through Auto's consent service, where no client registered at its issuer covers the scope the way asks; true in local mode and false otherwise when left out. AUTO_CLIENTS wins over it"
         },
         "providers": {
           "type": "array",

docs/self-host/configuration.md

@@ -112,7 +112,7 @@ Every setting is an environment variable. The tables below group them by area.
 | `ALLOWED_ORIGINS`     | none                                    | Comma-separated origins a browser page may call the API from, besides the Studio host's and, where the runtime serves Studio, its own; `allowed_origins` in the file. See [Calling from a browser](security.md#calling-from-a-browser)                                                                                                                                                                                                                                                                                                                                                                            |
 | `STUDIO_ORIGIN`       | `https://studio.on.auto`                | The Studio host: an `https` address, or an `http` address on `localhost`, `127.0.0.1` or `[::1]`, with no path. A page there may call the API, and the runtime fetches Studio from it when it serves Studio; `studio_origin` in the file. See [Studio served by the runtime](security.md#studio-served-by-the-runtime)                                                                                                                                                                                                                                                                                            |
 | `SERVE_STUDIO`        | `true` in local mode, `false` otherwise | `true` or `false`: whether the runtime serves Studio itself at `/studio/` on its own address, fetched from `STUDIO_ORIGIN` and kept beside a SQLite ledger file. It works in local mode alone for now, and the server warns at start where it is on elsewhere; `serve_studio` in the file. See [Studio served by the runtime](security.md#studio-served-by-the-runtime)                                                                                                                                                                                                                                           |
-| `AUTO_CLIENTS`        | `true` in local mode, `false` otherwise | `true` or `false`: whether a provider whose way takes a registered client takes Auto's client too, through Auto's consent service, where `registered_clients` lists none at its issuer; it wins over `auto_clients` of the `connections` section. The tokens of such a consent pass through Auto at the consent and at every renewal. See [Consent through Auto](connections.md#consent-through-auto)                                                                                                                                                                                                             |
+| `AUTO_CLIENTS`        | `true` in local mode, `false` otherwise | `true` or `false`: whether a provider whose way takes a registered client takes Auto's client too, through Auto's consent service, where `registered_clients` lists none at its issuer that covers the scope its way asks; it wins over `auto_clients` of the `connections` section. The tokens of such a consent pass through Auto at the consent and at every renewal. See [Consent through Auto](connections.md#consent-through-auto)                                                                                                                                                                          |
 | `CONSENT_SERVICE_URL` | `https://consent.on.auto`               | Auto's consent service, an `https` URL with no path, query or fragment, or an `http` URL on `localhost`, `127.0.0.1` or `[::1]` for a test. The runtime reaches it whatever `allowed_hosts` says, as it reaches the Auto identity service                                                                                                                                                                                                                                                                                                                                                                         |
 
 ### Storage
@@ -528,15 +528,17 @@ connections:
 | -------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `people_may_add`     | `true`                                  | `false` refuses every new connection, and the runtime uses none already added, though `list_connections` still lists them as they are                                                                                                                                                                                                                                                                                                                                                                                           |
 | `allowed_hosts`      | every host                              | The hosts a connection may reach, each a host or `*.` and a host for every host under it; the host of an `mcp` connection's `url`, of an `openapi` connection's `document` and `base_url`, of the `issuer` of client credentials, and of the issuer and the endpoints of a provider's way of consent. Left out, a connection may reach every host, addresses inside your network such as `localhost` or `10.0.0.5` among them                                                                                                   |
-| `registered_clients` | none                                    | The clients you registered at authorization servers, each with its `issuers`, its `client_id`, and its `client_secret`, or its `private_key` with its `algorithm`, as a reference, or neither for a public client, as [Register your clients](connections.md#register-your-clients) sets out                                                                                                                                                                                                                                    |
-| `auto_clients`       | `true` in local mode, `false` otherwise | Whether a provider whose way takes a registered client takes Auto's client too, through Auto's consent service, where `registered_clients` lists none at its issuer; `AUTO_CLIENTS` wins over it. See [Consent through Auto](connections.md#consent-through-auto)                                                                                                                                                                                                                                                               |
+| `registered_clients` | none                                    | The clients you registered at authorization servers, each with its `issuers`, its `client_id`, and its `client_secret`, or its `private_key` with its `algorithm`, as a reference, or neither for a public client, and its `scopes`, the scopes it may ask, which each client names where several serve one issuer, as [Register your clients](connections.md#register-your-clients) sets out                                                                                                                                   |
+| `auto_clients`       | `true` in local mode, `false` otherwise | Whether a provider whose way takes a registered client takes Auto's client too, through Auto's consent service, where `registered_clients` lists none at its issuer that covers the scope its way asks; `AUTO_CLIENTS` wins over it. See [Consent through Auto](connections.md#consent-through-auto)                                                                                                                                                                                                                            |
 | `credential_kinds`   | every kind                              | The kinds of credential a connection may take: `none`, `reference`, `secret`, `client_credentials` and `authorization`                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `variables`          | none                                    | The environment variables a `reference` credential may name, such as `CRM_API_KEY`. None of them may be a variable the runtime reads for itself: any variable this page lists, such as `SECRETS_KEY`, `API_KEYS`, `PUBLIC_URL` or a provider's key; a credential the cloud libraries read, such as `AWS_SECRET_ACCESS_KEY`, `AZURE_CLIENT_SECRET`, `AZURE_CLIENT_CERTIFICATE_PASSWORD` or `AZURE_PASSWORD`; a gateway's `api_key_env`; or a variable that a reference of this file, of `TOOL_SERVERS` or of `CONNECTIONS` names |
 | `providers`          | none                                    | Providers of your own beside those the runtime ships, each an entry of a provider, which a person connects by its name and an entry of `tool_servers` may name; one named as a shipped provider takes its place. See [Add providers of your own](connections.md#add-providers-of-your-own)                                                                                                                                                                                                                                      |
 
 `add_connection` refuses with `403` a connection one of these rules does not take, with the sentence of the rule, and with `409` a connection named as an entry of `tool_servers`. A key the section does not know, a pattern that is not a host, a kind there is not, a variable the runtime reads for itself and an entry of `providers` the runtime cannot take stop the server at start, naming the line.
 
-A registered client's `client_secret` and `private_key` are the only keys of a client that hold a reference, and the only ones the server substitutes from the environment, at start, whether the section comes from this file or from `CONNECTIONS`; a provider under `providers` holds one in a header or a query value alone, for a value of your own registration at the vendor, which the server substitutes when it sends that provider's server a request. A reference anywhere else in the section, in a host, a variable, an issuer, a `client_id` or an `algorithm`, stops the server at start; in a key that takes only some values, such as `credential_kinds` or `people_may_add`, it is refused as a value the key does not take. The section keeps the references of `registered_clients` and of `providers` as `tool_servers` keeps its own, so no secret of a client and no value of a provider is written into `CONNECTIONS`. The variables those references name are among the variables the runtime reads for itself, so `variables` may not list them.
+A registered client's `client_secret` and `private_key` are the only keys of a client that hold a reference, and the only ones the server substitutes from the environment, at start, whether the section comes from this file or from `CONNECTIONS`; a provider under `providers` holds one in a header or a query value alone, for a value of your own registration at the vendor, which the server substitutes when it sends that provider's server a request. A reference anywhere else in the section, in a host, a variable, an issuer, a `client_id`, an `algorithm` or a scope, stops the server at start; in a key that takes only some values, such as `credential_kinds` or `people_may_add`, it is refused as a value the key does not take. The section keeps the references of `registered_clients` and of `providers` as `tool_servers` keeps its own, so no secret of a client and no value of a provider is written into `CONNECTIONS`. The variables those references name are among the variables the runtime reads for itself, so `variables` may not list them.
+
+A registered client may name `scopes`, the scopes it may ask at its issuers, each written as a provider's way writes it. A way takes the first client at its issuer whose `scopes` cover the scope the way asks: every scope of the way's `scope`, split on spaces, is one the client names, compared exactly as written. A client that names no `scopes` covers every way, so a client alone at its issuers needs none. Where several clients serve one issuer, each names its `scopes`, and a way none of them covers is one you set up first, as a way whose issuer no client names is.
 
 The server stops at start, naming the line or the place and never a value, at a registered client:
 
@@ -545,7 +547,8 @@ The server stops at start, naming the line or the place and never a value, at a
 - with an empty `client_id` or `algorithm`;
 - without an issuer;
 - with an issuer that is neither an https URL nor an http URL on a loopback address;
-- with an issuer that an earlier client names too, the same but for a trailing slash;
+- without `scopes`, at an issuer another client names too, the same but for a trailing slash, since a client that names none would serve every way there that no client before it covers, and a client after it never;
+- with `scopes` that lists no scope, or lists an empty one;
 - with both a `client_secret` and a `private_key`, since a client authenticates with one;
 - with a `private_key` and no `algorithm`, or an `algorithm` and no `private_key`;
 - with a `token_endpoint_auth_method` its kind does not authenticate with: `client_secret_basic` or `client_secret_post` for a client with a secret, `private_key_jwt` for one with a key, and `none` for a public client.