key-bindings
/key-bindings
Wyjaśnia, jak poświadczenia operacji callApi wiążą się z kluczami po zatwierdzeniu i jak diagnozować odmowę powiązania.
- Autor
- cardstack ↗
- Repozytorium
- boxel ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 13.11.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 1
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 3
Brak sygnałów. Repozytorium zmienione 13.11.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Wyjaśnia, jak poświadczenia operacji callApi wiążą się z kluczami po zatwierdzeniu i jak diagnozować odmowę powiązania.
Wyzwalacze z opisu
Oryginalny opis (EN)
How a `callApi` operation's credential slots are filled from bindings — a key owner's approval of one operation in one realm, naming the key (or share) for each slot — and how to diagnose a binding refusal. Covers the `key_bindings`, `key_binding_approvals` and `key_binding_notices` tables, the `/_key-bindings` routes and who may call them, how approving creates or reuses a grant, the fingerprint and exactly which parts of a declaration it covers, `needs-reapproval` and its one notice, per-instance bindings, automations versus interactive invocation (`Realm.handleAutomation`, `automationAdmiss
Jak działa
- What a binding is keyed by
- Approving
- The fingerprint
- Filling a slot at call time
- Automations and interactive invocation
- Anonymous use
- Readiness
- Published realms
- What else changes bindings
- Diagnosing a refusal
Podgląd SKILL.md
---
name: key-bindings
description: How a `callApi` operation's credential slots are filled from bindings — a key owner's approval of one operation in one realm, naming the key (or share) for each slot — and how to diagnose a binding refusal. Covers the `key_bindings`, `key_binding_approvals` and `key_binding_notices` tables, the `/_key-bindings` routes and who may call them, how approving creates or reuses a grant, the fingerprint and exactly which parts of a declaration it covers, `needs-reapproval` and its one notice, per-instance bindings, automations versus interactive invocation (`Realm.handleAutomation`, `automationAdmission`), anonymous use by people who aren't signed in (the realm's policy and the shared key's own setting), what removing a grant, deleting a key, suspending a share and swapping a key into a share do to bindings, and each refusal (`binding-not-approved`, `share-suspended`, `binding-needs-reapproval`, `interactive-use-not-approved`, `anonymous-use-not-approved`). Use when a `callApi` is refused with one of those codes, when reading or querying the binding tables as an operator, or when changing `lib/key-bindings.ts`, `lib/key-binding-revocation.ts`, `handlers/handle-key-bindings.ts`, the slot filling in `card-operations/call-api.ts`, or anything that removes grants, keys or shares.
---
# Key bindings
A **binding** is a key owner's approval for one `callApi` operation, in one
realm, to send a chosen key in one of its credential slots. Card code never
names a key; the binding does. At call time nothing is searched: each slot's
binding is looked up by its identity, and a slot with none is not sent.
| What | Where |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |
| Approving, filling, fingerprints, swap, admission | `packages/realm-server/lib/key-bindings.ts` |
| Revoking (shared by revoke, grant removal, key delete) | `packages/realm-server/lib/key-binding-revocation.ts` |
| Routes | `packages/realm-server/handlers/handle-key-bindings.ts` |
| Where the executor asks for the slots | `packages/runtime-common/card-operations/call-api.ts` (`callApiOperation`, `CallApiSender.fill`) |
| The sender that fills them | `packages/realm-server/lib/outbound/call-api-sender.ts` (`createCallApiSender`) |
| Automation entry | `Realm.handleAutomation` in `packages/runtime-common/realm.ts` |
| Tables, trigger | the `add-key-bindings` migration in `packages/postgres/migrations/` |
| Grants | the `user-keys` skill, _Grants_ |
## What a binding is keyed by
One row of `key_bindings` per slot:
- `realm_url` — the realm it was approved in. Approving in one realm says
nothing about another.
- `definition_url`, `export_name`, `operation_name` — the operation, as the
**type it is invoked through** resolves it: the type a type target names, or
the one an instance adopts from (`resolvedTypeOf` in `dispatch.ts`). An
operation inherited from a parent class is bound per subclass. The module is
resolved against the realm with its executable extension trimmed, at
approval (`bindingType`) and at call time alike, so `…/inbox` and
`…/inbox.gts` name one type.
- `instance_url` — the card, for an operation declared `perInstance: true`
(one webhook per channel card), as invocations address it once the realm
canonicalizes the target (`canonicalInstance`: the realm root is its index
card; a `.json`, trailing slash, query or fragment names the card); null
otherwise. Invoking a per-instance
operation on the type, or on a card it wasn't approved for, is
`binding-not-approved`.
- `slot` — the token as written: `userKey`, `apiKey`, or `apiKey:<name>`.
- Exactly one of `key_id` (a `userKey` slot: the approver's own key) and
`share_id` (an `apiKey` slot: a share in the realm).
- `approved_by` — the key's owner. For a `userKey` slot it is also the **only
caller** the binding serves, so uniqueness includes it: each caller approves
their own key. An `apiKey` slot has one binding per realm (per instance),
serving every caller; approving another share for it replaces the first.
- `grant_id` — the grant the credential is sent under.
- `interactive` — whether the owner also allowed interactive use (a card
opened in the browser, the AI assistant, the CLI) as well as automations.
Each approval sets it for every slot it writes, so approving again without
it returns a binding to automations only. A swap keeps it.
- `anonymous` — always false. A binding is never approved for use by people
who aren't signed in: that follows the realm's policy and the key its share
holds (see _Anonymous use_ below), and approving it here is refused 403.
- `fingerprint`, `approval_id`, `state` (`active`, `needs-reapproval`,
`suspended`).
## Approving
`POST /_key-bindings` with a **secure-origin session** (the secure window's
own, or the CLI's), from the secure origin's `Origin` or none — the same rule
as creating a grant (`secureClientOf`). The app page's session is refused
403 from any origin: card code can reach that session, and a card that could
approve bindings could spend the user's key.
```json
{
"data": {
"type": "key-binding-approval",
"attributes": {
"realm": "https://app.boxel.ai/someone/inbox/",
"operations": [
{
"codeRef": { "module": "https://…/inbox", "name": "Inbox" },
"operation": "listPRs",
"expectedDestination": "https://api.github.com/",
"slots": {
"userKey": { "keyId": "<uuid>", "expectedFingerprint": "<hex>" }
}
}
]
}
}
}
```
Before approving, the approval screen reads what it shows from
`GET /_key-bindings/preview?realm=&module=&name=&operation=` (any session
that can read the realm): the destination, whether the operation is approved
per instance, and for each slot the request snapshot and its fingerprint. The
approval names those back.
A per-instance operation adds `"instance": "<card id>"`; a share slot is
`{ "shareId": "<uuid>", "expectedFingerprint": … }`, and only the owner of the
share's key approves it, while the share is active. A realm, card or module
may be named in prefix form; answers name them in RRI form. One request is one
confirmation: every row it writes shares a `batch_id`, and its
`"interactive": true` applies to every slot it approves. A share approved
for interactive use for the first time (no binding of it is `interactive`
yet) is spent by every reader of its realm, so that approval names its daily
budget, `"dailyBudgets": {"<share id>": <calls>}`, which is set on the share
in the same transaction (see the `key-limits` skill). Without one it is
refused 400. A later interactive approval may name one; a budget is refused
for a share the approval doesn't fill, or without `interactive`.
`"anonymous": true` is refused 403: anonymous use of a binding is not offered. For each operation, in order:
1. The operation is read from the realm's definition cache (the caller must
be able to read the realm and the module's realm, as for a grant). Its
destination must equal `expectedDestination`, and each slot's request must
hash to its `expectedFingerprint` — what the user was shown — or nothing
is approved (409). So an edit between showing and approving, such as the
key moved from a header into the body at the same destination, is never
approved unseen.
2. A grant of the key (the share's key, for a share) covering that destination
is reused, or one is created (`createOrReuseGrantIn`).
3. The binding is written or moved to this approval, `active`, and an
`approved` / `re-approved` row is appended to `key_binding_approvals`.
The window builds what it approves from `POST /_key-bindings/batch`
(`lib/key-binding-batch.ts`, a secure-origin session only: the window's own or
the CLI's), whose
`attributes.target` names a card or a card type in its realm as the window's
context does, with `review` for review-changes, and `interactive` to also
answer slots approved for automations only (status `automations-only`), which
the window shows only once the user allows interactive use. Within the batch's slot cap, the slots that need approving come first and
automations-only ones take what room is left, so they never hold one back;
`remainingAutomationsOnly` counts those left out. It answers every `callApi`
operation on that card definition, in that realm, that needs the caller's
approval: a slot the caller approves (their own key for `userKey`, a share of
theirs in the realm for `apiKey`; a share slot someone else approved is
theirs) with no binding, a binding whose grant is gone, or one whose
fingerprint no longer matches (`changed`, carrying the last approval's
snapshot for a field-by-field diff). Approved, unchanged slots are left out,
and so is an operation with nothing left; a per-instance operation is in the
batch only when the target is a card. Operations come grouped by normalized
destination, with the caller's keys a slot can take and their shares in the
realm, each with the batch's destinations its grants already cover
(`covers`). `fillers[use][slot]` names, for `interactive` and `automations`
use, the keys and shares that can fill each slot token
(`keyOfferedForSlot` in `lib/slot-fill.ts`): of a kind the slot takes
(its declared `keyKind`, or `slotKeyKinds`) in every operation that sends
it, with a credential good at every destination it is sent to. An OAuth
connection's tokens, or an OAuth client's own, are good only at the API
hosts its client names (`apiHostsOfKeySql` in `lib/oauth.ts`); any other
key is good wherever it is sent, as is a client that names no hosts, and a
connection whose client is gone is good nowhere. For `automations`, an
operation approved for automations only doesn't count. Asked with
`operations: [<name>, …]`, only those operations count, and the batch still
holds every operation. An OAuth client people only sign in through is never
offered, as a key or as a share (`sendableKeySql`), and a share of one
doesn't count as the caller's share for readiness either. The approve page
offers a slot only its `fillers`; only a declared kind is enforced when
approving. A share
also says whether any binding of it is `interactive` yet, its
`dailyBudget` in force, and whether the key it holds allows people who aren't
signed in to use it (`anonymous`, with its `anonymousDailyCap` and `anonymousMonthlyCap`, read from
`user_keys`); each
slot's `approved` says whether its last approval was `interactive`. Each
operation's `openToAnonymous` says whether the realm's policy opens it to
people who aren't signed in through a shared key, for the card's type or one
it descends from (`Realm.sharedKeyOperationsOpenToAnonymous`; see
_Anonymous use_).
A batch
never spans card definitions or realms: approving one card's batch says
nothing about another card calling the same host, which gets its own batch
and reuses the grant.
The answer carries each binding with `meta.request` (the snapshot below) and
`meta.grant` (with `created`). `GET /_key-bindings` lists the caller's own
(narrowed by `?realm=&module=&name=&operation=&instance=`, each resolved
from prefix form or a URL as a binding is keyed),
each with `operationLabel` and `cardName`: what the key page names it by, as
the approve page does. They are read per type as a batch reads its definition
(`bindingNames` in `lib/key-binding-batch.ts`), under the same read checks; a
type the caller can't read, or whose realm fails to mount, is named by its
export name and its operation's name split into words;
`DELETE /_key-bindings/:id` revokes one (secure session again) and leaves its
grant.
**From the terminal** (`packages/boxel-cli/src/commands/keys/approve.ts`):
- `boxel keys approve <key or share label> --operation <module>#<Class>[.<op>]
--realm <url> [--slot] [--instance] [--interactive [--anonymous]] [--yes]`
asks for the batch with the CLI's secure session, keeps the operations
named (all of the class without `.<op>`) and the slots the key or share
fills where the batch's `fillers` for the use it approves for offer it,
refusing a key or share they don't offer for a slot its type fills, prints each request (label, method, path, where the key goes, body)
and the hosts the key goes to for the first time, and asks y/N once
(`--yes` without a terminal). An approval whose every slot a grant already
covers (the batch's `covers`) is posted from the terminal (`via` `cli`).
One that needs a new grant is confirmed in the secure window: the CLI
opens `approve#module=…&name=…&realm=…&operation=…&key=…&operations=…`
with `cli_port`/`cli_state` naming a single-use loopback listener, the
window approves under its own session (`via` `window`) and posts only
`window_outcome=done`, or `window_outcome=cancelled` when the user cancels
or closes the window first (the CLI then ends at once with "Not
approved"), and either way the CLI reads the bindings back
(`GET /_key-bindings` with `realm`, `module`, `name` and `instance`, which
the server resolves from prefix form or a URL). The CLI never creates a
grant on its own. The window approves every slot of an operation, so a
`--slot` approval that needs a new grant is refused in the terminal.
`--operation <…>.<op>` asks the batch with `operations: [<op>]`, so
`fillers` weigh only where that operation sends.
`--interactive` also asks the batch for automations-only slots, prints what
interactive use allows, and approves interactively. For the operations the
policy opens to visitors (`openToAnonymous`) it prints the same lines the
approve window shows: "Anyone on the internet who opens this card,
including people who aren't signed in, can make … with <share>[, up to N
calls a day all together]." where the share's key allows it, and otherwise
that they're asked to sign in. A share's first
interactive approval made in the terminal needs `--daily-budget <calls>`;
in the window, the page starts on interactive use (`#interactive=1`) and
asks for the budget itself. Re-approving a slot last approved `interactive`
without `--interactive` is refused in the terminal rather than returning
it to automations only. `--anonymous` is refused 403: whether people who
aren't signed in may use a key is its owner's setting for the key
(`boxel keys anonymous`; see the `user-keys` skill), and where they can is
the realm's policy's to say.
- `boxel keys revoke` (same shape) lists the user's matching bindings with
the same filters and deletes them.
- `boxel keys pending` lists bindings that won't send as approved:
`needs-reapproval`, or a fingerprint that differs from the preview's now
(`GET /_key-bindings/preview`, ordinary session), so an edit no call has
found yet is listed too, and one whose operation can't be read.
- `boxel keys ungrant <key> --destination <url>` lists the bindings sent
under that grant, confirms, and removes it.
- `boxel keys swap` reads the share's `operations[].destination` from the
realm's share listing; when none of the key's grants (a rejected one
included, which the swap reuses) covers one, the swap is made in the
window's `swap-key` page the same way, and otherwise in the terminal.
## The fingerprint
`fingerprintOf(bindingSnapshot(request, slot))`: SHA-256, as hex, over a
fixed-order JSON array of what reaches the vendor —
| Field | From the lowered `OperationCallApi` |
| ----------------------------------------- | ---------------------------------------------------------------------- |
| `destination` | `destination` |
| `method` | `method` |
| `pathTemplate` | `url` with its `{name}` segments, `path` (what fills each) and `query` |
| `headersTemplate` | `headers` |
| `placement`, `placementName`, `transform` | the slot's: `header` + `authorization`, `body` + `auth.token`, `basic` |
| `bodyTemplate` | the JSON body, or the GraphQL document and variables |
Templates keep their typed references as lowering's markers and are encoded
with members sorted, so how a declaration is written doesn't change the hash.
**Not** covered: the `label`, the `output` mapping, `params`, `input`. Headers
are covered as well as the body, because a header such as
`X-HTTP-Method-Override` changes what a request does.
Every call recomputes it from what the definition cache holds now and compares
it with the binding's. A mismatch moves the binding to `needs-reapproval` and
records **one** `key_binding_notices` row for its owner (only on the move, so
repeated calls don't notify again), and the call is refused. The binding stays
refused even if the declaration is edited back: only approving again (which
appends `re-approved`, moves the fingerprint and returns it to `active`)
serves it. The check runs when a binding is read — at a call, or at a
automation's admission — so an edit nobody calls through yet is not yet flagged.
## Filling a slot at call time
`callApiOperation` asks `sender.fill(lookup)` for every slot before it builds
the request. `fillSlots` checks, per slot, in this order:
| Check | Refusal | Status |
| ------------------------------------------------------------------------------------ | ------------------------------ | ------ |
| A binding with this identity (and caller, for `userKey`) | `binding-not-approved` | 409 |
| Its share, if any, is `active` | `share-suspended` | 409 |
| `state` isn't `needs-reapproval` and the fingerprint matches | `binding-needs-reapproval` | 409 |
| Interactive invocation needs `interactive` | `interactive-use-not-approved` | 403 |
| A caller who isn't signed in needs the share's key to allow anonymous use | `anonymous-use-not-approved` | 401 |
| A grant is set, opens, and belongs to the binding's key (or the share's current key) | `binding-not-approved` | 409 |
| The grant isn't `rejected`, unless this call claims its probe | `credential-rejected` | 424 |
| Its service-account key isn't `rejected`, unless this call claims the key's probe | `credential-rejected` | 424 |
The value is the grant's copy (`openGrantForSending`), never the key's master
copy — or, for a key that mints its access tokens (an OAuth connection, a
`client_credentials` client, a Google service account), the access token
minted now, once the grant's marker has opened; a key that can't mint one is
refused `credential-rejected` (424) with `meta.reason` (see the
`oauth-connections` skill, and the `user-keys` skill's Google service
accounts) — with `|basic` applied (the raw value is registered with the scrubber
too). Back in the executor, after building, the request — every slot still a
token — must be under the **grant's stored destination**
(`destinationCovers`), not the declaration's, or it is refused
`guard-refused` with `meta.reason: 'destination'`. Only then is it sent.
## Automations and interactive invocation
Every request that reaches `_operations` off the network is **interactive**:
it carries a user session (a browser card, the AI assistant, the CLI). A
**automation** invocation exists only in-process: the realm server hands an
`_operations` request carrying the payer's session to `realm.handleAutomation`,
which records that request object and runs it through the ordinary
authorization; the `callApi` arm then runs with `callApiMode: 'automation'`.
Any active binding serves an automation. Only one approved `interactive` serves
an interactive call, which also counts against the key's or share's limits
(`chargeInteractiveCall`; see the `key-limits` skill).
The approve page says what interactive use exposes before it is allowed.
Card code runs with the user's session, so any card the user opens, from any
realm, can invoke an operation another card's realm approved and read the
response: for a personal key, as its owner; for a share, as any reader of
the realm. The automation pattern (an automation calls the vendor and writes what
cards need into the realm) keeps private responses out of that reach.
Sandboxing card code per realm origin is what would close it.
Before a run starts, `automationAdmission(dbAdapter, {core, realmURL, codeRef,
operation, instance?, payer})` answers the refusal the call would get (or
nothing), without opening any key, so a missing or changed approval stops the
run up front. It checks each slot with `checkSlots`, the check every call and
readiness make. So a slot is refused `credential-rejected` when its OAuth
connection or `client_credentials` client can't mint a token, with `reason`
`rejected` or `needs-admin` (see the `oauth-connections` skill). A rejected
grant or service-account key admits the run only while its probe is due.
## Anonymous use
People who aren't signed in can use a shared key, for a public card such as a
weather widget, where two decisions meet. Whether they may use a key is its
owner's decision about the key itself (`user_keys.anonymous`, with optional
`anonymous_daily_cap` and `anonymous_monthly_cap`; see the `user-keys` skill). Whether they can use it in
a realm is that realm's policy's to say. A binding never carries either.
Three things must all hold before such a caller's `callApi` sends anything:
1. **The realm's policy admits them to the operation**: a grant whose `where`
names `"anonymous"`. Policy compilation opens a `callApi` to them only when
it sends no key or only shared ones (`{{apiKey}}`); a keyless one is then
limited by the grant's own rate limit and blocklist alone. A grant on one with a
`{{userKey}}` slot is kept for signed-in callers and recorded as
`anonymous-grant-user-key` (a warning). The grant's own blocklist and rate
limit apply as for any anonymous grant (the `realm-auth` skill).
2. **Every slot is filled by an `interactive` share binding whose share's key
allows anonymous use** (`checkSlot` reads the key's `anonymous` as
`share_key_anonymous`), or the call is refused `anonymous-use-not-approved`
(401: signing in is what serves them). A `{{userKey}}` slot never fills
for them: `callApiOperation` refuses it `actor-required` before any
binding is read.
3. **There is room in the limits for them** (see the `key-limits` skill): a
bucket per client address at the share's per-person rate; their part of
the share's daily budget (`KEY_ANONYMOUS_SHARE_PERCENT`, default 50), so
signed-in readers keep the rest; and, where the key's owner set them, the
key's daily and monthly anonymous caps, each counted once across every
realm the key is shared into, and once per call even when the call goes
through two shares of the key. Their calls spend the share's daily and monthly budgets too.
The realm passes the caller's address (the anonymous limiter's `rateLimitKey`,
an IPv6 caller's /64) as `callApiAnonymous` on the invocation; the lookup's
`caller` is then `"anonymous"` and `anonymous.address` says where from. A
caller the realm couldn't place has no address and is refused
`actor-required`. Whether visitors may use a share follows the key it holds:
swapping a key into a share in a realm whose policy opens shared-key calls to
visitors is refused 400 for a key that doesn't allow anonymous use (see the
`key-shares` skill). A sign-in app or a connection never serves visitors and
takes no anonymous setting (see the `user-keys` skill).
The gate judges every behavior but a create against a stored card, so a
visitor invokes a `callApi` on a card instance, never on its type. In a realm
anyone may read, a visitor's capability check judges their write lane through
the policy's grants that open it (`ANONYMOUS_WRITE_CHECK`), and a `callApi`
grant counts there (`CompiledAnonymousGrant.sendsOutside`) since it travels
as a write. A visitor who may read the realm and is refused a `callApi` that
sends the caller's own key is told readiness `needs-sign-in`.
Whether a realm's policy opens such a call at all is
`opensSharedKeysToAnonymous` (`lib/anonymous-key-use.ts`): some compiled
grant has `anonymous.sendsSharedKey`, which compilation sets only for a
`callApi` with a shared-key slot whose every slot takes a shared key (a grant
on a keyless `callApi` doesn't count). The secure window's context carries it
as `realm.opensToAnonymous`, and sharing follows it: where the policy opens
such calls, sharing a key there means visitors will use it, so a key that
doesn't allow anonymous use isn't shared there until its owner allows it for
the key (see the `key-shares` skill). Per
operation, the approval batch's `openToAnonymous` says the same
(`Realm.sharedKeyOperationsOpenToAnonymous`), and the approve page notes, for
each ticked operation the policy opens, whether the chosen share's key lets
visitors use it or they will be asked to sign in. A key shared into a realm
whose policy later opens calls to visitors serves them if the key allows
anonymous use, and otherwise they are asked to sign in.
```sql
-- The shares that serve people who aren't signed in, and their keys' caps.
SELECT s.id, s.label, s.realm_url, s.daily_budget, k.anonymous_daily_cap, k.anonymous_monthly_cap
FROM key_shares s JOIN user_keys k ON k.id = s.key_id
WHERE k.anonymous
AND EXISTS (SELECT 1 FROM key_bindings b WHERE b.share_id = s.id AND b.interactive);
```
To stop anonymous use of a share at once, a realm writer suspends the share,
or the policy's anonymous grant is removed. The key's owner can also turn
anonymous use off for the key (`boxel keys anonymous <name> off`, or the
key's page in the secure window), which stops it in every realm the key is
shared into.
## Readiness
`@context.keyReadiness(operation, target)` asks, through a `_capabilities`
pair carrying `readiness: true`, what filling the slots would answer for this
caller invoking from a card. `lib/key-readiness.ts` (`keyReadiness`, the
sender's `readiness`) reads the same rows as `checkedBindings`, in the same
order, and maps each way a slot falls short to an answer: no binding →
`needs-connect`, or `needs-approval` where one of the caller's grants already
covers the destination; a changed fingerprint → `needs-reapproval`; not
`interactive` → `needs-approval`; a share slot short in any way → `needs-admin`
to anyone but the share key's owner, except that a share slot with no binding
is `needs-approval` to a caller with an active share of their own in the realm
(the shares the approve page offers them for it); a grant the vendor rejected, with no
probe due → `credential-rejected` (to everyone, since the call says the
same); nobody signed in → `needs-sign-in`, unless every slot is a share's
and the realm admitted them from an address, when a share whose key doesn't allow
anonymous use answers `needs-sign-in` and one that does is asked about the
anonymous limits (`rate-limited`, `over-budget`). It
opens no key and writes nothing: a changed fingerprint is reported, not moved
to `needs-reapproval`, and no notice is recorded. **A check added to
`checkedBindings` or `fillSlots` belongs in `key-readiness.ts` too**, or
readiness will say `ready` for a call that is refused.
## Published realms
A published realm has no bindings of its own. Its calls are filled from the
bindings of the realm it was published from: `key_bindings.realm_url`,
`definition_url` and `instance_url` hold the source's URLs, and the published
realm's sender rebases its lookup onto them (`publishedFrom` in
`lib/outbound/call-api-sender.ts`; see the `key-shares` skill). Its fill passes
`publishedRealmURL`, which changes three things:
- A fingerprint that doesn't match refuses the call `binding-needs-reapproval`
without moving the binding: the published copy runs the source's code as of
its last publish, and an older copy mustn't undo an approval the source still
uses. Republishing fixes it; nothing on the published realm can.
- A refusal names the published realm, never the source.
- A refused fill is recorded under the published realm.
To diagnose a refusal on a published site, query the bindings by the
source's URL (`realm_registry.source_url` of the published row).
## What else changes bindings
- **Removing a grant** (`DELETE /_user-key-grants/:id`) revokes every binding
that uses it, in every realm, each with a `revoked` row; the answer's
`meta.revokedBindings` lists them.
- **Deleting a key** revokes its `userKey` bindings (`via` null, since the
realm server did it). A share's bindings stay: the share is suspended
`key-deleted`, its grants go with the key (`grant_id` becomes null), and a
swap restores them.
- **A share suspended** for any reason suspends its bindings, and resuming it
returns them to `active`: `key_bindings_follow_share`, a trigger on
`key_shares.state`. A `needs-reapproval` binding stays so either way.
- **Swapping a key into a share** (`POST /_key-shares/:id/swap`) moves each
of its bindings to a grant of the new key for the destination it was last
approved for, with the swapper as `approved_by` and a `re-approved` row. The
fingerprint is unchanged. A swap into a share with bindings needs a
secure-origin session (it creates grants); one with none needs only its
ticket. `meta.reapprovedBindings` lists the moved bindings.
- **Unsharing**, or deleting the realm, deletes the bindings with no
`revoked` row; a deleted realm's `userKey` bindings are deleted too, so a
realm later made at the same URL starts with none approved.
## Diagnosing a refusal
All four codes arrive in the operations refusal format with `meta.slot` (or
`meta.slots` for `binding-not-approved`). The detail names the slot and
whose key fills it, since the AI assistant sees only the message.
```sql
-- The binding a call looked for (userKey: add AND approved_by = '<caller>').
SELECT id, slot, key_id, share_id, grant_id, approved_by, state, fingerprint, updated_at
FROM key_bindings
WHERE realm_url = '<realm>/' AND definition_url = '<module>' AND export_name = '<Class>'
AND operation_name = '<op>';
-- Its history: what was approved, by whom, how, and when.
SELECT at, action, actor, via, batch_id, destination, method, placement, placement_name, fingerprint
FROM key_binding_approvals WHERE binding_id = '<id>' ORDER BY at;
-- Whether its owner was told it needs re-approval.
SELECT created_at, owner FROM key_binding_notices WHERE binding_id = '<id>';
```
- **`binding-not-approved`** with no row: never approved here, approved for
another type (a subclass), another instance, or (for `userKey`) by another
user; or revoked — look for a `revoked` row by operation name in
`key_binding_approvals`. With a row: its grant doesn't open, or belongs to
another key than the binding's (see the `user-keys` skill on hand-written
grant rows); the realm server logs which on `realm:key-bindings`. A fault
opening the grant other than those (the database, the keyring) is an error,
not this refusal.
- **`binding-needs-reapproval`**: diff the last approval row's snapshot
against the declaration now; the owner approves again.
- **`share-suspended`**: the share's `suspension_reason` (see the
`key-shares` skill). For `key-deleted`, the binding's `grant_id` is null
too, since its grants went with the key: a direct writer swaps a key in,
which grants it the binding's destination again.
- **`anonymous-use-not-approved`**: a caller who isn't signed in reached a
binding whose share's key doesn't allow anonymous use (`user_keys.anonymous`
false), or a personal key's binding. Whether a key allows it is its owner's
setting (`boxel keys anonymous <name> on`, or the key's page in the secure
window). Readiness answers `needs-sign-in`.
- **`interactive-use-not-approved`**: the binding is approved for automations
only (`interactive` false). Its owner approves it again allowing
interactive use; readiness answers `needs-approval`, whose button opens the
approve page.
The binding tables hold no secret, and all three are excluded from the SQLite
schema dump. `readonly_role` (dashboards and read-only database access, such
as `claude_readonly_user` in staging and production) can read `key_bindings`,
so which operations a realm has bound, to which key or share, can be checked
while triaging. `key_binding_approvals` and `key_binding_notices` are withheld
from it, like the keys tables; query those as the application role.
## Tests
- `packages/realm-server/tests/key-bindings-test.ts` — end to end against the
stub vendor: approve then call as an automation, grant reuse and a second
grant at another host, realm and caller scoping, automations-only refusal, the
app session refused, re-approval on edits (and not on label or `output`
edits), approving refused when the request shown has changed, share
approval only by its key's owner and only while active, grant removal, key
deletion, share suspension and swap, per-instance bindings, keyless
operations untouched, the fingerprint pinned to a fixed value, and the
listing's names with and without read on the card. It indexes a card using `perInstance`, so it needs a
host dist built from your tree (see the `call-api` skill).
- `packages/realm-server/tests/interactive-bindings-test.ts` — interactive
use end to end with the PR Inbox: a personal key approved interactively
loads pull requests in a browser call, counted against the key's limits; a
automations-only binding refuses it; approving again without it; anonymous
refused; the batch's `automations-only` slots; a share's first interactive
approval and its daily budget; a swap keeping `interactive`.
- `packages/realm-server/tests/anonymous-key-use-test.ts` — anonymous use
through a policy in another realm: the policy opening only a share-only
`callApi` (and warning about a `userKey` one), sharing into such a realm
refused for a key that doesn't allow anonymous use, a
visitor served through a share whose key allows it and refused by one whose
key doesn't, the per-address rate, the key's daily and monthly anonymous caps exhausting
without touching signed-in readers, a swapped-in key deciding for the share,
a personal key refusing them `actor-required`, and readiness for each.
- `packages/realm-server/tests/key-binding-batch-test.ts` — the batch: six
operations approved as one with one grant, an unticked one left
unapproved, an edited one alone in the review batch with its approved
snapshot, a second card reusing the grant in a batch of its own, removing
the grant returning them, share slots only in their key owner's batch, and
the listings the key page's Use with a card reads.
- `packages/realm-server/tests/card-operations-dispatch-test.ts` — the
executor's use of `fill` and the grant-destination check, with a fake
sender.
- `packages/host/tests/unit/operation-lowering-test.ts` — lowering
`perInstance`.
## Related skills
- **`call-api`** — the declaration, lowering and the rest of dispatch.
- **`user-keys`** — keys and grants.
- **`key-shares`** — shares, their states and the swap.
- **`secure-session`** — the secure-origin session approving needs.
Wersje
W bazie nie ma innych skilli o nazwie key-bindings.
Migawka bazy z 13.11.2026 · wersja paczki d0464a11ef15 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 87call-api
Wyjaśnia, jak operacja callApi na karcie wysyła żądania do zewnętrznych usług i obsługuje poświadczenia. - 87outbound-guard
Diagnozuje strażnika ruchu wychodzącego serwera realm, który blokuje połączenia bez HTTPS i adresy prywatne przy wysyłce danych logowania.