@brass-build/client 0.2.0 → 0.4.0

package/docs/app-manifest.md

@@ -8,9 +8,14 @@ a download button on the documents your app writes out.
 ## Where it goes
 
 Put `brass-app.json` in a `/.well-known/` directory at your bundle
-root, next to `index.html`. Some bundlers skip dot-directories when
-they copy static assets, so confirm the manifest is in your `dist/`
-directory after you build.
+root, next to `index.html`. In Vite, `public/.well-known/brass-app.json`
+builds to `dist/.well-known/brass-app.json`. Check it is there after you
+build: a bundler that skips dot-directories drops it silently.
+
+`brass publish` reads that same path out of the directory it publishes
+(`<dir>/.well-known/brass-app.json`), falling back to `brass-app.json` in
+the working directory, so it takes your `name` and `client_token` from the
+manifest you already ship.
 
 The platform re-reads the manifest after each deploy, so publishing
 your bundle is what registers it. If Brass hosts your bundle
@@ -32,7 +37,11 @@ no access, so you declare them yourself.
   "creates": "tracker",
   "exports": { "content_type": "text/csv", "file_extension": ".csv" },
   "icon": "/icon.svg",
-  "schema": { "...": "see schemas.md" }
+  "services": [{ "host": "api.anthropic.com", "headers": { "x-api-key": "{secret}" } }],
+  "schema": {
+    "family": "tracker",
+    "streams": { "default": { "type": "object", "required": ["rows"] } }
+  }
 }
 ```
 
@@ -59,6 +68,327 @@ Every field is optional, so ship only the ones your app uses.
   (`"icon": "/icon.svg"`, resolved against your origin), or give an
   absolute `https://` URL. An emoji (`"icon": "🏗️"`) also renders,
   though apps in one domain tend to land on the same few.
+- **`services`** names the third-party APIs your app calls. Brass proxies
+  each call, using either your credentials or the user's. See
+  [Services](#services-for-calling-third-party-apis) below.
 - **`schema`** declares the record shape your app works with, whether
-  you invented it or adopted an existing one. See
+  you designed it or adopted an existing one. See
   [`schemas.md`](./schemas.md).
+
+## Services, for calling third-party APIs
+
+`services` names the third-party APIs that your app calls. Each service
+declaration includes a host name and an authentication method. Brass then
+proxies each call, using either your credentials or the user's, so no secret
+is exposed in the client.
+
+```json
+{
+  "services": [
+    { "host": "api.anthropic.com", "headers": { "x-api-key": "{secret}" } },
+    { "host": "api.example.com", "headers": { "authorization": "Bearer {secret}" } }
+  ]
+}
+```
+
+[`services.md`](./services.md) covers the calling side: what each refusal code
+means, how to prompt for a missing credential, which host to pass for a
+service split across addresses, and how to provide setup instructions for
+the people who supply your credentials.
+
+### Specifying a host
+
+`host` is the host name your app passes to `Brass.callService`. It must be a
+public https host: no scheme, no port, no path.
+
+Use a wildcard where a service is split across subdomains (`*.example.com`).
+Your app can then call any address under that suffix.
+
+Set `credentialPerHost` to give each address its own credential. Without it,
+one credential covers every address under the wildcard. With it, the user
+enters a separate credential for each address, which is what a vendor that
+hosts a separate address per account requires.
+
+```json
+{
+  "services": [
+    { "host": "*.example.com", "headers": { "authorization": "Bearer {secret}" } },
+    {
+      "host": "*.myshopify.com",
+      "credentialPerHost": true,
+      "headers": { "x-shopify-access-token": "{secret}" }
+    }
+  ]
+}
+```
+
+`credentialPerHost` is required for a suffix that anyone can register a name
+under. One credential covering `*.herokuapp.com` or `*.pages.dev` could be
+used at an address a stranger created, so Brass rejects that declaration and
+reports it on your next publish. The same rule limits a shared wildcard:
+`*.amazonaws.com` can call `sts.amazonaws.com` and
+`lambda.us-west-2.amazonaws.com`, but not `any-bucket.s3.amazonaws.com`,
+because that name belongs to whoever created the bucket.
+
+### Credential fields
+
+A field is one value the person connecting a credential is asked for. Each one
+is a box on the form they fill in.
+
+Some authentication methods declare their own fields, and each method below
+lists the ones it declares. Declare any others in `fields`:
+
+| Property | |
+| --- | --- |
+| `name` | Required. Identifies the field. |
+| `secret` | `true` by default. Brass encrypts the value and shows only its last few characters afterwards. `false` stores it in the clear and shows it in full. |
+| `label` | What the form calls the field. Use the vendor's own word for it, since that is what the person is reading from. Defaults to the name. |
+| `readable` | `false` by default. `true` returns the value to your app with the service, for a value your app has to include in the request. Such a field is not secret, so `secret` defaults to `false` for it and declaring both is refused. See [Values the app reads](./services.md#values-the-app-reads). |
+
+```json
+{
+  "services": [
+    {
+      "host": "api.example.com",
+      "headers": { "x-app": "{app_id}", "x-region": "{region}", "x-key": "{key}" },
+      "fields": [
+        { "name": "app_id", "secret": false, "label": "Application ID" },
+        { "name": "region", "secret": false, "label": "Region" }
+      ]
+    }
+  ]
+}
+```
+
+An entry naming a field the method already declared changes that field's
+properties instead of adding a new one, which is how you relabel one. A field
+the method declares secret stays secret.
+
+### Choosing an authentication method
+
+A credential sent in a plain header needs no `auth` block. Every other method
+is an `auth` block naming its `type`.
+
+#### `headers`, for a credential sent in a header
+
+Each header value is a template, and Brass substitutes a field into each
+placeholder you write. The fields are the names in those placeholders; this
+method declares none of its own.
+
+```json
+{
+  "services": [
+    {
+      "host": "production.plaid.com",
+      "headers": {
+        "plaid-client-id": "{client_id}",
+        "plaid-secret": "{secret}"
+      },
+      "fields": [{ "name": "client_id", "secret": false, "label": "Client ID" }]
+    }
+  ]
+}
+```
+
+#### `basic`, for HTTP basic auth
+
+Brass sends `authorization: Basic base64(username:password)`.
+
+The fields are `username` and `password`.
+
+```json
+{ "host": "api.twilio.com", "auth": { "type": "basic" } }
+```
+
+Some services take a fixed word as the user half rather than an account name,
+such as `api` for Mailgun. Set it as `username` on the `auth` block and the
+person is asked for the password alone.
+
+```json
+{ "host": "api.mailgun.net", "auth": { "type": "basic", "username": "api" } }
+```
+
+#### `query`, for a credential sent as a query parameter
+
+Brass appends these parameters to the query your app wrote, substituting a
+field into each placeholder you write. The fields are the names in those
+placeholders; this method declares none of its own.
+
+```json
+{
+  "host": "maps.example.com",
+  "auth": { "type": "query", "params": { "key": "{secret}" } }
+}
+```
+
+#### `aws_sigv4`, for a signed AWS request
+
+Brass signs the request, so the secret never leaves Brass.
+
+The fields are `access_key_id` and `secret_access_key`.
+
+```json
+{ "host": "*.amazonaws.com", "auth": { "type": "aws_sigv4" } }
+```
+
+AWS puts the region and the service in most of its host names, and Brass signs
+for whichever the address names. Set `region` and `service` for addresses that
+name neither, such as a bucket or an account id before the service name. Brass
+uses them only where the host name does not say, so one credential still
+covers a whole suffix.
+
+#### `oauth2_client_credentials`, for a token from your client credentials
+
+You register a client with the vendor. Brass posts the client id and secret to
+the token endpoint, receives a short-lived token, and sends that token with
+each call. Set `clientAuth` to `body` or `basic` to say where the id and
+secret go; vendors differ, and many accept only one.
+
+The fields are `client_id` and `client_secret`.
+
+```json
+{
+  "host": "api.xero.com",
+  "auth": {
+    "type": "oauth2_client_credentials",
+    "tokenHost": "identity.xero.com",
+    "tokenPath": "/connect/token",
+    "clientAuth": "basic",
+    "scope": "accounting.transactions"
+  }
+}
+```
+
+#### `jwt_bearer`, for a token from a signed assertion
+
+Brass signs a short-lived assertion with a private key, so the key never
+leaves Brass. Set `audience` to the string the vendor requires in the
+assertion. Vendors are strict about this value, so declare it rather than
+letting Brass build one.
+
+The fields are `issuer` and `private_key`.
+
+```json
+{
+  "host": "oauth2.googleapis.com",
+  "auth": {
+    "type": "jwt_bearer",
+    "tokenPath": "/token",
+    "audience": "https://oauth2.googleapis.com/token",
+    "algorithm": "RS256"
+  }
+}
+```
+
+Both token methods take two more fields:
+
+- `tokenPath` names the path on the credential's own host. Set `tokenUrl`
+  instead to name the whole address. `tokenHost` defaults to the credential's
+  own host.
+  Set it to post the exchange to a different host. Brass allows this for a
+  credential you supply, and rejects it for one the user supplies, unless the
+  user chose the method. Otherwise your manifest would decide where their
+  secret is sent.
+- `tokenBody` sets how the exchange is posted: `form` (the default) or `json`.
+  Set `json` when your vendor's token endpoint takes a JSON body.
+
+#### `oauth2_authorization_code`, for a per-user approval at the vendor
+
+Each user approves at the vendor, and Brass stores the result for that user
+alone. Your app then reaches only what that user can reach. Use this at a host
+whose permissions differ per user, where one shared account would reach
+everything.
+
+The fields are `client_id` and `client_secret`, which are your registered
+OAuth client rather than anything the approving user enters.
+
+```json
+{
+  "host": "api.example.com",
+  "auth": {
+    "type": "oauth2_authorization_code",
+    "authorizationUrl": "https://app.example.com/oauth/authorize",
+    "tokenUrl": "https://api.example.com/oauth/token",
+    "clientAuth": "basic"
+  }
+}
+```
+
+- `clientAuth` sets where your client id and secret go on the exchange: `body`
+  or `basic`.
+- `authorizeParams` adds parameters the vendor requires on the approval
+  request. Many vendors issue no refresh token without one, and the connection
+  then stops working when the first token expires. Google requires
+  `{"access_type": "offline", "prompt": "consent"}`. Read your vendor's
+  documentation on refresh tokens before you ship this.
+- `pkce` defaults to `true`. Set `false` for a vendor that rejects the
+  challenge.
+
+You supply an OAuth client registered with the vendor, entering its id and
+secret like any other credential. Register
+`https://brass.build/services/oauth/callback` as the redirect URL. That one
+address serves every service, and there is nothing to configure in Brass.
+
+Calls return `409` with `credential_required` until the user approves.
+[`services.md`](./services.md) covers prompting them.
+
+#### An OpenAPI security scheme
+
+`auth` also accepts an OpenAPI `securityScheme`, so you can paste what your
+vendor's spec already says. Brass reads it as the equivalent method above:
+`apiKey` and `http` `bearer` take a single `secret` field, sent in the place
+the spec names; `http` `basic` reads as `basic`; and the `clientCredentials`
+and `authorizationCode` flows read as their OAuth methods, with those methods'
+fields.
+
+```json
+{ "host": "api.example.com", "auth": { "type": "apiKey", "in": "header", "name": "X-API-Key" } }
+```
+
+The `authorizationCode` flow is the same grant as `oauth2_authorization_code`
+above. A spec carries no `clientAuth`, `authorizeParams` or `pkce`, so set
+those alongside `flows`:
+
+```json
+{
+  "host": "api.example.com",
+  "auth": {
+    "type": "oauth2",
+    "flows": {
+      "authorizationCode": {
+        "authorizationUrl": "https://app.example.com/oauth/authorize",
+        "tokenUrl": "https://api.example.com/oauth/token",
+        "scopes": { "contacts.read": "Read contacts" }
+      }
+    }
+  }
+}
+```
+
+#### More than one method at one host
+
+Set `auth` to an array where a host accepts more than one kind of credential.
+A user with an API key can then use it at a host you declared for approval:
+
+```json
+{
+  "host": "api.example.com",
+  "auth": [
+    { "type": "oauth2", "flows": { "authorizationCode": { "...": "..." } } },
+    { "type": "apiKey", "in": "header", "name": "X-API-Key" }
+  ]
+}
+```
+
+Brass uses your first entry by default. The user can choose another when they
+enter their credential, and Brass then asks for whatever that method needs.
+
+Set `authorOnly` on an entry to keep it out of the user's choices. Use it for
+a credential only you can obtain, such as a vendor's internal-integration
+secret, which authenticates as your account rather than theirs.
+
+A host often accepts several kinds of credential. A vendor that issues both
+personal tokens and OAuth clients takes either, and they are different
+credentials at one address. Declare the method your app is built around. A
+user who pastes an OAuth client pair where you declared a bearer token is
+asked for the client id as well, and your app keeps calling one host.

package/docs/custom-chrome.md

@@ -48,8 +48,10 @@ Each piece renders one cluster wired to `Brass.session` and returns
 - `Brass.mountPresenceRoster` renders the who's-here roster of
   coloured initials. It is the receiver half only: still publish your
   own presence state (see the README's "Presence").
-- `Brass.mountDriveSync` renders the drive-sync badge. It renders
-  nothing on a non-drive doc, so it is safe to mount in any header.
+- `Brass.mountDriveSync` renders the drive-sync badge: the sync state
+  and publish of a document linked to a drive, and the offer to publish
+  one its project's drive has not received yet. It carries the actions
+  the open document has, so it is safe in any header.
 - `Brass.mountAccountMenu` renders the account avatar menu (email, an
   Open Brass dashboard link, and sign out).
 
@@ -128,6 +130,9 @@ hook for keyboard shortcuts).
 Reading the list and calling `run()` wires all of it. You render and
 invoke, and the SDK owns the behavior:
 
+- **`new`** creates a document and binds it, asking the platform where
+  to put it (`Brass.session.create()` under the hood).
+- **`open`** opens the hosted picker and binds what the user chooses.
 - **`history`** drives version preview end to end. During a preview
   `doc.readOnly` is `true`, so gate your own edit controls on it;
   returning to live is the chrome's job (the `mountVersionPreview`

package/docs/presence.md

@@ -67,9 +67,21 @@ interface PresenceState {
   // The entity ids the user has selected. Use to highlight remote
   // selections so collaborators see what each other is working on.
   selection?: string[];
+  // Where the user's caret sits in a text container. `key` names the
+  // container (`doc.text(key)`), and both offsets count UTF-16 code
+  // units into its value: `anchor` where the selection began, `head`
+  // where it is now, equal for a plain caret. Use it to draw remote
+  // carets in prose, the way `selection` highlights picked entities.
+  textCaret?: { key: string; anchor: number; head: number };
 }
 ```
 
+A caret belongs in `state` rather than in `ext` for the same reason a
+selection does: a document of prose is often open in more than one app,
+and a reader wants to see where the other person is working whichever
+app they are each in. Publish it on every selection change, which the
+10 Hz debounce already paces.
+
 App-specific state (the current tool, a chat bubble, a typing
 indicator) goes under `ext` instead so it stays namespaced and out of
 the cross-app conventions. The `ext` block is otherwise free-form:

package/docs/services.md

@@ -0,0 +1,265 @@
+# Calling an outside service
+
+The README's [Calling an outside service](../README.md#calling-an-outside-service)
+covers how to make a call. This page covers what each refusal code means,
+how to read values only the user knows, and which host to pass for a service
+split across several addresses. [`app-manifest.md`](./app-manifest.md) covers
+declaring a host and its authentication method.
+
+## What comes back
+
+`callService` returns the service's response unchanged, within these limits:
+
+- Text only, up to 5 MB, within 25 seconds.
+- No streaming. A streaming endpoint's events all arrive together at the end.
+- For binary data, call an endpoint that returns a URL or base64.
+- Brass does not follow redirects. A `3xx` is returned as
+  `response_redirected`, with the service's `location` in the body.
+
+`options.method` defaults to `'POST'`.
+
+## Refusal codes
+
+When Brass refuses a call rather than sending it, the response body has a
+`code`:
+
+```js
+const res = await Brass.callService(host, path);
+if (!res.ok) {
+  const { code } = await res.json();
+  if (code === 'credential_required') await Brass.connectService(host);
+}
+```
+
+Each code always comes with the same HTTP status, so branching on the code
+is enough. Two answers carry no code, and both mean the hop to the service
+itself did not complete: a `502` where Brass could not reach the service, and
+a `504` where the service did not answer in time. Other `502`s do carry a
+code, so read the body before treating one as unreachable.
+
+**Somebody using your app can supply what is missing.** Call
+`Brass.connectService(host)`. The dialog asks whoever opened it for whatever
+the host needs, and tells anyone who cannot answer who to ask.
+
+| `code`                | What it means                                                                                             |
+| --------------------- | --------------------------------------------------------------------------------------------------------- |
+| `credential_required` | No credential is connected for this host, or the one connected is not approved for your app, no longer covers what your app sends, or carries no value under a name your app reads back. One code, because the dialog is the answer to all of them. The body's sentence says which, for a person to read. |
+
+**Your own key is what is missing.** These are yours to settle on your app's
+settings page, so there is nothing to raise on the page: report the feature as
+unavailable.
+
+| `code`                       | What it means                                                                                             |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `app_credential_not_set`     | You have not entered a key for this service yet. This is the refusal you get by default, until you enter one or hand the service over for whoever runs your app to connect. |
+| `app_credential_incomplete`  | Your own key carries no value under a name your manifest asks for.                                         |
+
+**A stored credential is there and does not work.**
+
+| `code`                       | What it means                                                                                             |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `credential_rejected`        | The service rejected the stored credential.                                                                |
+| `credential_scheme_unusable` | The host's credential is not usable as configured.                                                         |
+| `credential_exchange_failed` | Brass could not reach the service for a token, or got back something that was not one.                     |
+| `credential_unreadable`      | Brass cannot read the credential stored here. Enter it again.                                              |
+
+**The call itself is not allowed.** Fix these in your app.
+
+| `code`                    | What it means                                                                                             |
+| ------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `service_not_declared`    | Your manifest does not declare that host, or your latest publish has not registered it.                    |
+| `path_invalid`            | The path names its own host, escapes the service with `..`, or cannot be decoded.                           |
+| `service_headers_invalid` | A header in `options.headers` is one HTTP itself controls (`content-length`, `host`, `connection` and the like), or its name or value cannot go on a header line. |
+| `host_not_public`         | The host does not resolve to a public IP address.                                                           |
+
+**The call is allowed but cannot go through right now.** Some of these clear
+on their own.
+
+| `code`               | What it means                                                                          |
+| -------------------- | -------------------------------------------------------------------------------------- |
+| `cap_exceeded`       | A cap has been reached. Try again later.                                               |
+| `rate_limited`       | Over Brass's own rate limit. Slow down.                                                |
+| `calls_paused`       | Whoever owns the account being spent set its cap to zero. Waiting will not clear it.   |
+| `vault_unavailable`  | Brass could not read the stored key just now. Nothing is wrong with it; make the same call again. |
+
+**Brass could not return the response.**
+
+| `code`               | What it means                                                       |
+| -------------------- | --------------------------------------------------------------------- |
+| `response_too_large` | The service returned more than 5 MB.                                  |
+| `response_not_text`  | The service returned bytes rather than text. Call an endpoint that returns a URL or base64. |
+| `response_unreadable`| Brass could not read the service's response.                          |
+| `response_redirected`| The service answered with a redirect. The body carries its `location`. |
+| `service_timeout`    | The service did not answer in time.                                   |
+| `service_unreachable`| Brass could not reach the service.                                    |
+
+**The app is not the one that may call.** These are about your app's standing
+rather than the credential.
+
+| `code`               | What it means                                                       |
+| -------------------- | --------------------------------------------------------------------- |
+| `app_not_installed`  | The organization has not installed your app. `requestMissingCredentials: true` raises the install dialog; otherwise the call returns `403`. |
+| `no_acting_app`      | The caller is not acting as an app. |
+
+A call made before the app has an organization returns `409 destination_required`.
+
+## Asking for a missing credential
+
+`Brass.listServices()` returns each declared host, with `ready: true` where
+Brass has a credential for it. It shows no dialog, so you can call it while
+the page loads. It returns `null` while the app is acting nowhere: nobody is
+signed in, the app has no organization, or it is running in one that has not
+installed it.
+
+Each entry also carries `connectable`, which says whether the dialog has
+anything for the person on the page to do at that host. Together the two are
+the whole branch:
+
+```js
+const services = await Brass.listServices();
+const ai = services?.find((s) => s.host === 'api.anthropic.com');
+if (ai?.ready) showSummariseButton();
+else if (ai?.connectable) showConnectCard();
+else showUnavailableCard();
+```
+
+`Brass.connectService(host)` opens the dialog and resolves true once that
+host works. Whoever can supply the credential does it there; anyone else is
+told who to ask. Put it on a button, so the user is asked when they reach for
+the feature:
+
+```js
+if (await Brass.connectService('api.anthropic.com')) showSummariseButton();
+```
+
+Passing `requestMissingCredentials: true` to `callService` opens the same
+dialog from the call, which then goes through once the user answers. It covers
+every refusal the person using your app can answer: `credential_required`, plus
+`credential_rejected` and `credential_scheme_unusable` when the account that
+failed is one they own.
+
+A host still waiting for the key you enter as its author
+(`app_credential_not_set`, `app_credential_incomplete`) is yours to settle on
+the app's own settings page, so the call returns that refusal for you to
+handle:
+
+```js
+const res = await Brass.callService(host, path, { requestMissingCredentials: true });
+```
+
+## Who supplies the credential
+
+You choose on your app's settings page whether a host runs on a key of yours
+or on an account whoever runs your app connects, and they can change that
+under you. A host you have just declared starts on a key of yours, so
+`connectable` is false there until you change it. Either way your call is the
+same one: you name a host, and Brass attaches whichever credential is in
+force.
+
+Your app reads `connectable` rather than the supplier, because that is the
+split it can act on. Where it is true, the person using your app can
+settle it, so a Connect button leads somewhere; where it is false, the host is
+waiting on you, so there is nothing to raise. Leave the wording about who to
+ask to the dialog, which knows both the supplier and who is reading, where
+your app is told neither.
+
+## Values the app reads
+
+Your app sometimes has to include a value in the request it sends, such as
+an account id. Mark that field `readable` in the manifest and Brass returns
+it to your app with the service.
+
+Brass collects the value when somebody connects an account, and offers your app
+only the accounts carrying it, so it is there whenever a call reaches your code.
+
+The field's name is the key your app reads the value back under.
+
+```json
+{
+  "services": [
+    {
+      "host": "api.cloudflare.com",
+      "headers": { "authorization": "Bearer {token}" },
+      "fields": [{ "name": "account_id", "readable": true, "label": "Account ID" }]
+    }
+  ]
+}
+```
+
+```js
+const services = await Brass.listServices();
+const cf = services?.find((s) => s.host === 'api.cloudflare.com');
+const account = cf?.values?.account_id;
+if (cf?.ready && account) {
+  const res = await Brass.callService(
+    'api.cloudflare.com',
+    `client/v4/accounts/${account}/tokens/verify`,
+    { method: 'GET' },
+  );
+}
+```
+
+`values` is present on a `ready` service.
+
+## Providing credential setup instructions
+
+Brass shows your setup instructions on the form that collects a credential,
+and you are strongly encouraged to provide them. Without them the form shows
+your field labels alone, and the person filling it in has to work out what
+to create at the vendor and where.
+
+Declare a `setup` beside the host:
+
+```json
+{
+  "services": [
+    {
+      "host": "api.example.com",
+      "headers": { "authorization": "Bearer {secret}" },
+      "setup": {
+        "credentialName": "API key",
+        "consoleUrl": "https://example.com/settings/keys",
+        "docsUrl": "https://example.com/docs/api",
+        "steps": [
+          "Open Settings, then API keys.",
+          "Create a key with read and write access.",
+          "Copy the key before closing the dialog."
+        ]
+      }
+    }
+  ]
+}
+```
+
+- **`credentialName`** is what the vendor calls the credential, so it
+  matches what they see there.
+- **`consoleUrl`** is the page where they create it. Link to that page
+  rather than the vendor's home page.
+- **`docsUrl`** is where the vendor documents this method.
+- **`steps`** are step-by-step instructions for creating the credential.
+  Up to six, shown in order.
+
+## A service split across addresses
+
+A wildcard host (`*.myshopify.com`) covers every address under it;
+[`app-manifest.md`](./app-manifest.md) covers declaring one. Which `host` you
+pass to `callService` depends on `credentialPerHost`.
+
+Without it, one credential covers every address under the suffix, and
+`listServices` returns a single entry under the declared name. Match on the
+wildcard, not on the address you are about to call.
+
+With it, each secret is entered against a specific address, and
+`listServices` returns one entry per connected address, each with
+`declared_as: '*.myshopify.com'`. Pass the `host` from one of those entries.
+An address you build from a shop name points at a shop nobody has connected.
+Before any address is connected there is one entry for the wildcard itself,
+and `Brass.connectService` takes that `host`:
+
+```js
+const shops = ((await Brass.listServices()) ?? []).filter(
+  (s) => s.declared_as === '*.myshopify.com',
+);
+const connected = shops.filter((s) => s.ready);
+if (connected.length === 0) await Brass.connectService('*.myshopify.com');
+```