@fluid-app/droplet-bridge 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,120 @@
-# Temporary Holding Version
+# @fluid-app/droplet-bridge
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Canonical browser client for embedded droplets.
+
+```ts
+import { createFluidBridge } from "@fluid-app/droplet-bridge";
+
+const bridge = createFluidBridge({ clientId, hostOrigin });
+const context = await bridge.getContext();
+const token = await bridge.getSessionToken();
+await fetch("/api/embedded-action", { method: "POST" });
+// Use disableFetchPatch: true to opt out of ambient fetch.
+await bridge.fetch("/api/embedded-action", { method: "POST" });
+// Component teardown, or explicit shutdown:
+bridge.destroy();
+```
+
+`hostOrigin` is the exact HTTP(S) host-shell origin supplied by the shell. The client
+accepts only that origin and `window.parent`. It installs its listener before sending
+UUID-v7 `bridge.ready`, retries at most eight times with bounded backoff until context
+arrives, and rejects an incomplete handshake after ten seconds by default. Protocol or
+SDK mismatches fail closed with typed errors. Only one client may own a document at a
+time; destroy it before creating another. A real navigation's `pagehide`
+(`persisted: false`) and `unload` destroy it automatically. A `pagehide` into the
+back/forward cache (`persisted: true`) leaves the bridge intact — the document is
+frozen, not gone — and `pageshow` on restore resumes an unresolved handshake; an
+already-resolved one keeps working unchanged.
+
+`getContext()` resolves the immutable, unsigned Rails context delivered at handshake;
+it never fetches context on demand. `getSessionToken()` requests a fresh identity-only
+token over `session_token.refresh_request` every time, coalescing concurrent callers
+onto one in-flight request. The SDK schedules its own refresh from the token's
+lifetime relative to receipt, never from comparing `exp` against this client's clock —
+an admin's local clock can run well ahead of the host's, and a short-lived token must
+not be rejected, or refreshed every second, because of it. Decoding is for delivery
+and scheduling only: the droplet backend verifies signatures, identity and expiry per
+the
+[verification contract](../../../apps/rails/docs/droplet-session-token-verification-contract.md).
+The SDK uses in-memory delivery binding against app/store/actor/entry/sid and ignores
+replies for unknown or previous-document request IDs.
+
+Explicit and ambient fetch authenticate only exact origins in the server-delivered
+`fetch.allowedOrigins`. There is no iframe `appOrigins` option. Fluid API origins are
+excluded first, even if accidentally listed. Ambient fetch also passes a request
+through untouched — never waiting on the handshake — whenever the handshake has
+failed, or is still pending and the request targets an origin other than the current
+document's own. Explicit disallowed requests reject; ambient disallowed requests pass
+through with their original input/options — including a reference to the ambient
+wrapper captured before `destroy()`, for every cross-origin call made through it
+afterward; a same-origin call through that same reference keeps failing closed.
+Allowed requests preserve Request bodies,
+headers and credentials, replace Authorization with the fresh session token, and send
+the viewer's active language as `Accept-Language` from `store.locale`. Missing locale
+fails closed. Relative request URLs resolve against the document's current location,
+read at call time, so an in-document route change is honored. Explicit bridge fetch
+refuses redirects with `redirect: "error"` — browsers strip the Authorization header
+across a cross-origin redirect, so forwarding it would be silently insecure — and
+converts HTTP 401/403 into a typed error. Ambient fetch keeps the caller's own redirect
+mode and returns 401/403 as an ordinary Response, since same-origin app code expects to
+read its own response status. Network failures return typed errors without response
+bodies or raw exception text on both paths. `destroy()` restores the prior fetch,
+cancels timers and rejects dangling requests.
+
+## First request and later documents
+
+The URL `session_token` is **first-request server bootstrap only**. The SDK strips it
+immediately with `history.replaceState` and never uses it as a browser credential.
+The droplet response must set `Referrer-Policy: no-referrer` before subresources load;
+the host iframe’s referrer policy does not protect those subresources. Do not log full
+bootstrap URLs or persist bridge tokens in localStorage, sessionStorage, cookies or
+window.name.
+
+A full-document navigation inside the iframe keeps the droplet’s current route. Its
+server must treat any URL token as absent after bootstrap, use its own short HttpOnly
+app session established from verified first-load identity, or render a bridge-first
+recovery page. That recovery page initializes this SDK and sends a fresh bridge token
+to its own backend for verification. A stale URL token must not hard-fail recovery.
+Every new document initializes the SDK again and obtains fresh context/tokens over
+postMessage. The host must **not rewrite the frozen iframe src** to inject another
+bootstrap token, because it would reset the droplet’s route. An app session cookie
+stores the app’s own bounded session, never the Fluid bridge token.
+
+## Canonical host
+
+`createCanonicalBridgeHost` uses the shared versioned protocol. The authenticated shell
+supplies the registered app origin and fixed mount: client, store, actor, installation,
+entry and sid. Create sid before the first URL mint and reuse it for the same mount.
+Store/actor/installation/entry/resource changes destroy the host and iframe and create
+a new mount; document navigation within the same mount preserves src and sid.
+
+Every valid `bridge.ready` gets current permission-gated server context and a fresh
+mint, including after the first document. A retry of the same in-flight readiness ID
+coalesces; a new document ID proceeds even while older work is pending. Readiness and
+refresh each have their own bounded pending pool, so a storm of refreshes can never
+cost a new document's `bridge.ready` a `host_unavailable`. The client ignores old
+correlations, binds refreshes to its delivered sid, and coalesces concurrent
+`getSessionToken()` callers onto a single in-flight refresh request. Both host
+adapters must honor AbortSignal and perform uncached authorized requests. Refresh
+rechecks context and SDK compatibility before minting. Refresh also refuses to mint,
+leaving the document's existing context and token in place, if an origin ever
+delivered on this mount has since been removed from the live authorized context —
+the removal is compared against the union of every origin set delivered by any
+`bridge.ready` on this mount, never against a value a prior refresh already
+advanced, so an earlier removal cannot hide behind a later addition. That baseline
+is monotonic for the whole mount, not reset by a later `bridge.ready`: the host
+cannot reliably tell a new document's readiness from a duplicate or retried one
+from the same document (an SDK retry race, or a bfcache `pageshow` resend), so a
+duplicate ready is never allowed to erase a prior removal. An origin removed
+mid-session therefore stops refreshing tokens for the rest of that mount's life,
+even for a document that attaches after the removal; reload the admin page to
+remount the iframe and pick up the new context. Adding an origin mid-session
+refreshes normally. Neither adapter trusts iframe identity or origin declarations.
+`createFluidBridgeHost` remains
+the legacy pull host used by the portal until its separately specified member tier and
+cutover land.
+
+Session tokens are identity assertions, never Fluid API credentials. Backend API
+access uses the existing OAuth client_credentials flow with a store resource and
+installation-scoped permission enforcement. Navigation and shell UI actions are
+outside this client’s token/context scope.