Reference

Changelog — @bubblio/door

1.4.0 — 2026-11-17

Nothing to change in your code, and nothing new leaves your site.

  • Connected agents get their answer sooner. To act for a connected person, the desk needs that person's saved login. It used to ask Bubblio for it in the middle of every run. Bubblio now sends it along with the run request, so that extra trip is gone.
  • Why this is no less safe. It is the same encrypted data as before, and it still opens only with your site's own secret, which never leaves your site. Bubblio checks that the connection is still live right before it sends, so a person who disconnects stops the very next run. The desk uses the login it is sent only when the signed request is fresh (under 30 seconds old) and the login opens; in every other case it asks Bubblio, as before.
  • Sites on an older version keep working exactly as they did.

1.3.0 — 2026-11-16

Nothing to change in your code. One new thing leaves your site, so read this.

  • The desk tells agents what each action returns. When your site answers an AI agent with JSON, the desk now notes the answer's field names and types (id, name, price), never a value. From those, Bubblio adds one sentence to each learned action ("Returns a list; each item has: id, name, price.") and tells agents which lookup gives the value for an input ("product_id: one of the id values that get_products returns"). You do not write or maintain any of it.
  • What is and is not sent. Only names and types. A name is sent only where the desk is sure the key is a field and not data: a short plain word, in a list item or in an object whose values are of different kinds. An object that could be keyed by data (by user, id or address) gives up no names; neither does a name that sounds like a credential, or one the caller itself sent in its request. Nothing is noted for a request that carried a password or card, for an answer that was not a success, or for anything over 256 KB. Bubblio tells agents a name only after two separate senders were each given it. The answer your site sent goes to the agent untouched and is not held up.
  • New option recordAnswers (default true). Set it to false to send none of this.
  • One sender can no longer pass for several by typing a header. The desk counts "separate senders" by network address. It used to believe x-real-ip, cf-connecting-ip and similar headers wherever they appeared; off the platform that writes them, a sender can type them. A platform's header is now read only when the server's environment says it runs there (Vercel, Fly, Netlify, Cloudflare Workers). Everywhere else the desk uses the entry your nearest proxy wrote in X-Forwarded-For. If your site sits behind a proxy the desk cannot see, such as Cloudflare in front of your own server, name its header with the new option clientAddressHeader ('cf-connecting-ip'); without it the desk still works, it is only slower to propose.
  • Fixed: words that begin with "sk", "pk" or "rk" were taken for secret keys. A route such as /api/skates was recorded as /api/:id, and a value such as "skinny jeans" came back to the agent as [hidden]. Keys are now recognised by how they really start (sk_live_, sk-ant-, ghp_, xoxb- and so on).

1.2.2 — 2026-11-16

Nothing to change in your code.

  • Scripts that read pages as plain text can find the desk. For a script, the note was only a comment at the top of the page, which a tool that turns the page into text drops. It is now also the last paragraph of the page. Assistants still get it as the first paragraph; people in browsers and search or training crawlers still get nothing.

1.2.1 — 2026-11-16

Wording only; nothing to change in your code.

  • The guide agents read at /.well-known/bubblio now matches how the desk answers: a lookup answers in the quote call itself, anything that changes something is prepared and then run with confirm, and a call that needs the person's account answers with connect_url and agent_key.

1.2.0 — 2026-11-16

The desk, for the two people who meet it without reading any docs: an agent sent to the site's address, and the person asked to connect it. Additive; no code changes needed.

  • Agents find the desk from the site's own address. For AI assistants and scripts only (never browsers, search or training crawlers, or anything that draws the page), the desk adds one line to the pages they read, pointing to a guide at /.well-known/bubblio. It also answers /llms.txt, /.well-known/mcp and /mcp (a 307 to the desk's MCP address), each only when the site has none of its own. New option announce (default true).
  • "Sign in first", straight away. Someone who opens a connect link signed out is told so at once, with a button to the site's sign-in page (found from the home page's own link; new option signInPath overrides it). The page continues by itself when they come back.
  • A real signed-in check. A browser that has cookies is not a signed-in person. Before connecting, the desk opens one of the site's own read pages that turns strangers away, with the person's cookies, on the site only, and looks at the status. When it cannot tell, the connection goes ahead as before, and the person can always continue anyway.
  • The connect page lists what the agent can do in plain words (made by Bubblio's API), and no longer says an unnamed agent "typed this name itself".

1.1.0 — 2026-11-16

The desk: @bubblio/door/desk. A new entry point, withBubblioDesk(), installs as one line of middleware. It records what AI agents request (scrubbed inside the site), so Bubblio can propose actions for the owner to allow; serves the connect and disconnect pages on the site's own address; and replays approved requests as the connected user. Additive: nothing exported from @bubblio/door changes. See the README's first section.

Also in this release — connect-time consent enrollment (Bubblio API migration 0047). Additive — no breaking changes; with the new option left off, every request and response is byte-identical to 1.0.1.

Why: standing permission ("don't ask again for small actions") is only trustworthy if the human granted it, and Bubblio's approval pages can't prove that — their link travels through the agent. Your signed-in page can. From this release (and the matching API), a consent passkey may grant standing permission only if the human set it up through a link your key route received; a passkey made on an approval page approves requests one at a time.

  • New option consentEnrollment?: boolean on AgentKeyRouteConfig (createAgentKeyRoute). When true, every successful POST also answers enrollment: the plain mint returns { key, id, enrollment }, the phone-connect grant path returns { ok, connected, id, enrollment }. On the grant path the link is requested from the grant forward (not the mint), so Bubblio's enrollment page can continue straight to the waiting approval. Send the signed-in human to enrollment.url.
  • New option consentEnrollment?: boolean on MintAgentKeyOptions (mintAgentKey). Requests the link beside the key; sends consent_enrollment: true to POST /v1/agent-keys.
  • mintAgentKey's return type widens from Promise<{ key, id }> to Promise<{ key, id, enrollment?: ConsentEnrollment | null }>. enrollment is present only when consentEnrollment was set; without it the resolved object is exactly { key, id }, as before.
  • New exported type ConsentEnrollment — { url: string; expiresAt: string }. The URL (bubblio.dev/enroll#t=…) carries a single-use, ~30-minute ticket in its fragment: for the signed-in human's browser only — never log it or forward it to the agent.
  • Never fatal: enrollment: null means Bubblio could not mint a link this time (or the API predates 0047). The key or connection itself succeeded; a missing link is never treated as a grant-forward failure, so the just-minted key is not revoked over it.

1.0.1 — 2026-08-22

README-only patch — no code changes. The Guides links pointed at two docs routes that no longer exist (/docs/agent-door, /docs/nextjs); they now point at the real pages (/docs, /docs/quickstart). npm freezes a version's README at publish, which is why the fix needs a release.

1.0.0 — 2026-08-21

Renamed from @bubblio/server. Bubblio dropped its customer-service product — the real-time AI-avatar widget and the session SDK that bootstrapped it — entirely, so this package no longer carries it. Breaking:

  • Removed: createBubblioSession, BubblioSessionConfig, PlatformConfig, SelfHostedConfig, BubblioTool, BubblioToolConfig, BubblioSession, BubblioTransport, BubblioClientEvent, withUserContext, BubblioToolInput — the whole session-bootstrap surface (platform mode and self-hosted mode alike) and its config/return types. If you used any of these to run a Bubblio character widget, that product is gone; there is no successor in this package. The @runwayml/sdk dependency and the @runwayml/avatars-node-rpc optional peer leave with it — this package no longer touches Runway, or any avatar provider, at all.
  • @bubblio/door is agent-door-only from here on. Everything that made the door work is unchanged: defineDoorActions, createAgentKeyRoute, mintAgentKey / listAgentKeys / revokeAgentKey, createBubblioToolRoute, the payments lane (BubblioPaymentsClient / BubblioPaymentsConfig, completeBubblioCheckout, resumePaidQuote, pushDoorResult), and the shared verification/context primitives (verifyWebhookSignature, verifyBubblioWebhook, signUserContext / verifyUserContext / userContextFromRequest, deriveUserContextSecret, publicOrigin, BubblioApiError) all kept their exact contracts — a door integration needs only its import name updated, nothing else.
  • Migration: npm uninstall @bubblio/server && npm install @bubblio/door, then change from '@bubblio/server' to from '@bubblio/door' everywhere. If your callback route also imported one of the removed session symbols — some integrations shared one route between the widget and the door — that code has no replacement here; the customer-service product it served no longer exists.

Formerly published as @bubblio/server; its full release history (0.1 through 0.14) is preserved below, unedited — reconstructed from the release history (#52) and kept honest and current from 0.12.0 on. Versions below 0.9.0 predate this file; their story lives in the README's feature sections and the repository history.

0.14.0 — 2026-08-16

Member parity (#56): quote-time price resolution. Additive — no breaking changes.

  • priceFor on declared actions — an optional resolver (args, user, meta) => { covered: true, reason? } | { price: '$0.25' } | null answering Bubblio's quote-time question on keyed quotes of priced actions: what does THIS user pay? user is the agent key's minted identity, resolved exactly as handler calls resolve it; meta carries the pinned quote facts (tool, quoteId, listedPriceCents, currency, argsHash). covered: true pins $0 with price_source 'platform_covered' — the only path to a $0 quote, rendered honestly on the approval screen ("covered by your <label> account"). A member price parses through the same parser as the declared price and can only discount: Bubblio clamps anything above listed back to listed.
  • Fail-to-listed, never to free: no resolver on the action, a resolver throw, an unparseable price ('$0.00' included — free is only ever said as covered: true), a malformed request, an unknown tool — the route answers {} and the listed price stands. Bubblio's side of the same doctrine covers non-200s, the 4-second single-attempt timeout, and SDKs older than this release (they answer the wire as an unknown tool → listed).
  • The resolver travels on the handlers record (tools: { ...door.handlers } is unchanged), so member pricing needs zero new route config. priceFor without price is refused eagerly at defineDoorActions — price_for only fires for priced actions, so a resolver on an unpriced action is dead code, not a degraded mode.

0.13.0 — 2026-08-16

SDK papercuts from the stylica integration audit (#49). Additive — no breaking changes.

  • First-request door sync as a config line: sync: { door, callbackUrl, connectPath?, payments? } on createBubblioToolRoute wires the pattern every platform hand-rolled — build-safe (never at module scope; next build evaluates route modules), once per process, in-flight-deduped, retry-on-failure throttled to retrySeconds (default 60), never blocking a callback. door.sync() itself is unchanged for explicit control.
  • maxActiveKeysPerUser on createAgentKeyRoute (and mintAgentKey) — a per-user active-key quota enforced by Bubblio inside the mint path (it owns bl_agent_keys; a platform-side check-then-act can always lose the race, and stylica's did). Racing mints fail closed — a spurious at-cap 409 a retry resolves, never an overshoot — provided every mint for that user carries the cap: createAgentKeyRoute stamps it on every mint (grant path included), but an uncapped mint from another code path commits outside the enforcement and is never rolled back. At cap: calm 409 with code: 'key_cap_reached'; the phone-connect grant path mints through the same wall, so it is capped identically. BubblioApiError now carries the API's machine-readable code, and createAgentKeyRoute relays it to your UI.
  • API-key rotation no longer silently breaks managed-key identity: previousBubblioApiKeys on createBubblioToolRoute is the N/N-1 verify window — ctx tokens signed under the old key keep resolving their user while pre-rotation keys are live. Local and verification-only (the old key is never sent anywhere; it may already be revoked). verifyUserContext / userContextFromRequest now accept string | string[]. Full runbook in the README ("Rotating your Bubblio API key"). Deferred, by name: a server-assisted re-mint of stored ctx (PATCH /v1/agent-keys/:id { ctx }) — until it exists, a window shorter than the ctx lifetime means pre-rotation users re-mint through your route once the window closes.
  • Docs, corrected per the audit: the meta.idempotencyKey docs now say plainly that the hosted callback fires at most once per quote (no retry loop; duplicate confirms replay the receipt without reaching your endpoint) — handler-side replay caches are defense-in-depth for your own step-2 retries, not the primary double-execution defense; the primary double-spend vector is re-quoting, guarded platform-side by a per-identity unique claim. Teaching surfaces (README, docs site, examples/nextjs-door) now use the sync option instead of the hand-rolled syncOnce(), and door-only install docs no longer imply @bubblio/widget (the door never needs it).
  • OpenAPI spec for the door HTTP surface — docs/agent-door.openapi.yaml in the repo: discovery, per-door + hub MCP endpoints, the approvals API, agent keys + connect grant, the signed push endpoints, the actions sync, and the outbound callback contract as an OpenAPI webhook. Derived from the routes; when code and spec disagree, code wins.

Release order for this wave (load-bearing, not a nicety): publish @bubblio/server 0.13.0 and deploy the API before (or with) the dashboard deploy. The dashboard's docs teach sync: (silently ignored by an installed 0.12.0 in plain JS — no error anywhere), and /agents + llms.txt advertise GET /agent/feed.json, which 404s until the API is live. Publishing/deploying in that order closes the window where public teaching surfaces describe features nothing serves.

0.12.0 — 2026-08-15

The money lane: paid actions on your own Stripe. Additive — no breaking changes.

  • price on declared actions (price: '$0.40' or { amount_cents, currency }, usd-only for now). Synced as shape; every discovery surface (manifest, llms.txt, list_actions, about) shows it, and each quote pins it — the charged amount always derives from the pin, never from anything a caller sent.
  • Charge-wrap: payments: { stripeSecretKey } on createBubblioToolRoute charges on your own Stripe account, then runs your handler, and auto-refunds on throw. The quote id is the Stripe idempotency key (redelivered callbacks replay the PaymentIntent instead of charging twice); refunds run under quoteId + ':refund'. The payment token is transit-only — never stored, logged, echoed, or handed to your handler (meta.payment is the settled summary).
  • Payment rails profile: payments: { rails, stripePublishableKey } on door.sync declares payment_link and/or stripe_spt. Publishable key (pk_…) only — sk_/rk_ values are refused by name, before anything is stored.
  • completeBubblioCheckout(session, opts) — call from your Stripe checkout.session.completed webhook to settle a payment-link quote; non-Bubblio sessions are ignored (safe on a shared webhook), and a payment Bubblio refuses to settle is auto-refunded (quoteId + ':refund:' + sessionId). resumePaidQuote is the primitive underneath.
  • pushDoorResult now carries the payment summary with a late result, so an upgraded receipt still shows the charge. A connection that dies mid-charge retries once under the same idempotency key, then reports "outcome unknown" — never a false "nothing was charged".
  • Declaring a price against an API without migration 0036 refuses the whole sync (fail-closed: serving a paid action unpriced is a money bug, not a degraded mode) — the SDK throws BubblioApiError; the previously-synced registry keeps serving.

0.11.0 — 2026-08-15

Phone connect and approval hints. Additive — no breaking changes.

  • Phone connect: connectPath on door.sync declares your login page (path-only — it resolves against callbackUrl's origin and may never point off your site). createAgentKeyRoute becomes grant-aware: POST { grant: 'g_…' } mints the bak_ key and forwards it into Bubblio's connect grant, answering { ok, connected, id } — never the raw key. On a forward failure the just-minted key is revoked (best-effort) and the error is reported; no credential ends up owned by nobody. Requires API migrations 0033–0035 — against an older API, sync warns and the forward answers 404/409.
  • approvalSuggestion ('auto' | 'mandate' | 'always') on declared actions — a hint for the owner's per-action approval control, exactly like policySuggestion: stored on first sync, shown in the dashboard, never applied by a deploy.
  • Docs: the 'mandate' control's live evaluation (standing mandates under per-action caps and a daily budget) documented as shipped.

0.10.0 — 2026-08-15

Identity moves out of the URL; late results get a push channel.

  • body.ctx: on Agent Door managed-key confirms the user-context JWT now arrives inside the HMAC-signed callback body instead of only as ?ctx= on the URL (where access logs, proxies, error trackers, and Referer headers see a 90-day act-as-user credential). createBubblioToolRoute and userContextFromRequest (new third argument: the verified body) read the body first and fall back to the query param — both directions of version skew keep resolving user. A platform-side deprecation window keeps echoing ?ctx= for SDKs ≤0.9.1.
  • pushDoorResult: actions that outlive the ≤20s confirm window can deliver their late result to the quote (V2-signed, direction reversed), upgrading an unreachable receipt to ok instead of inviting a re-quote. createBubblioToolRoute pushes automatically when a handler finishes after the window.
  • Doctrine, written down: spend mandates never ride in ctx — the ctx token carries identity only. If a key path becomes spend-linked, mint its ctx with a short expiresInSeconds.
  • Callback bodies are extensible: fields arrive additively (agent in 0.8, ctx and callbackTimeoutSeconds here) — never validate them with a closed schema.

0.9.1 — 2026-08-13

Docs and package metadata only — no code changes.

  • README reframed for npm (chat-first, hosted API URLs, support via email).
  • repository field dropped (private repo), bugs → email.

0.9.0 — 2026-08-09

Security release: the legacy signature is refused by default.

  • verifyBubblioWebhook and createBubblioToolRoute require the replay-protected pair X-Bubblio-Signature-V2 + X-Bubblio-Timestamp; a request carrying only the body-only X-Bubblio-Signature is answered 401 (that signature never expires, so a captured callback could replay forever). Escape hatch while you fix a stale platform or a header-stripping proxy: allowLegacySignature: true — temporary by design.
  • onFailure callback on verification: missing_signature, legacy_signature_rejected, stale_timestamp, bad_signature, invalid_json — the 401 body names the reason, but the platform's log doesn't, so put it in your own.
  • meta.idempotencyKey on Agent Door confirms (the quote id) when the platform sends it — treat undefined as "no dedupe anchor available", not "first delivery".