@guuey/agent-client 0.1.0 → 0.2.1

package/src/web-adapters.ts

@@ -12,7 +12,7 @@ import type {
   InvokeTransport,
   ThreadIdStore,
 } from "./types";
-import { fetchThreadHistory } from "./history";
+import { fetchThreadHistory, HistoryUnauthorizedError } from "./history";
 
 /**
  * Thrown when the pod returns a non-2xx status on `/agent/invoke` (before any
@@ -61,16 +61,66 @@ export function webGenerateId(): string {
 }
 
 /**
- * Web SSE transport. When `accessToken` is present the pod identifies the
- * caller by their verified Cognito access token (the same identity the
- * history read plane uses, so persisted threads round-trip on reload).
- * Otherwise it falls back to `credentials: "include"`, which round-trips the
- * HttpOnly `guuey_guest` cookie the pod mints for anonymous browser callers.
+ * Header carrying a caller-owned anonymous guest secret. A LOCAL MIRROR of the
+ * two server-side constants — the pod's `GUEST_HEADER_NAME`
+ * (`backend/services/nocode-runtime/src/identity.ts`) and the read plane's
+ * `GUEST_HEADER` (`backend/amplify/functions/publicApi/identity.ts`) — because
+ * this is a published npm package and cannot take a `@guuey-private` dep (same
+ * arrangement as `@guuey/host`'s mirrored fs-contract constants). The string is
+ * a wire contract: both planes already advertise it in
+ * `Access-Control-Allow-Headers`, so changing it is a breaking protocol change,
+ * not a rename.
+ */
+const GUEST_HEADER = "x-guuey-guest";
+
+/**
+ * A well-formed guest secret: exactly 32 bytes as 64 LOWERCASE hex chars —
+ * the shape `crypto.getRandomValues` + hex-encoding mints.
+ *
+ * Deliberately stricter than the server's `/^[a-f0-9]{64}$/i` (pod
+ * `identity.ts`, publicApi `identity.ts`): both sides lowercase before
+ * hashing, so an uppercase secret would in fact be accepted, but the only
+ * supported mint path emits lowercase and a non-canonical value means the
+ * caller's storage is not what this adapter expects. Anything that fails is
+ * IGNORED — the request falls through to cookie mode rather than sending a
+ * secret the two identity planes might key differently.
+ */
+const GUEST_SECRET_RE = /^[0-9a-f]{64}$/;
+
+/**
+ * Narrow a caller-supplied guest secret to a value that is safe to put on the
+ * wire, or `null`. The single gate for the header: every write of
+ * {@link GUEST_HEADER} in this module goes through it, so a malformed secret
+ * can never reach a request. The value is never logged (here or anywhere on
+ * this path) — it IS the anonymous identity, so a leak is an impersonation.
+ */
+function sendableGuestSecret(secret: string | null | undefined): string | null {
+  return typeof secret === "string" && GUEST_SECRET_RE.test(secret) ? secret : null;
+}
+
+/**
+ * Web SSE transport. Exactly ONE identity carrier per request, in order:
+ *
+ *  1. `accessToken` → `Authorization: Bearer` — the pod identifies the caller
+ *     by their verified access token (the same identity the history read
+ *     plane uses, so persisted threads round-trip on reload).
+ *  2. a well-formed `guestSecret` → `x-guuey-guest` — the caller owns and
+ *     persists its own anonymous secret. The path for hosts with no usable
+ *     cookie jar: React-Native, and the embedded widget, whose third-party
+ *     iframe cannot rely on the pod's cookie surviving browser partitioning.
+ *     The pod never mints a cookie for a header client.
+ *  3. neither → `credentials: "include"`, which round-trips the HttpOnly
+ *     `guuey_guest` cookie the pod mints for anonymous browser callers.
+ *
+ * Never two at once: a bearer wins over a guest secret, and a request that
+ * carries either header does NOT also send cookie credentials.
+ *
  * Reads the body via `ReadableStream.getReader()` (browser).
  */
 export async function* fetchStreamTransport(
   req: InvokeRequest,
   accessToken?: string | null,
+  guestSecret?: string | null,
 ): AsyncGenerator<string> {
   const headers: Record<string, string> = {
     "Content-Type": "application/json",
@@ -82,8 +132,11 @@ export async function* fetchStreamTransport(
     headers,
     body: JSON.stringify(req.body),
   };
+  const guest = sendableGuestSecret(guestSecret);
   if (accessToken) {
     headers.Authorization = `Bearer ${accessToken}`;
+  } else if (guest) {
+    headers[GUEST_HEADER] = guest;
   } else {
     init.credentials = "include";
   }
@@ -124,28 +177,81 @@ export interface CreateWebAdaptersOptions {
    * Resolve the caller's Cognito access token (fresh), or `null` when signed
    * out. When a token is present the chat transport AND the history read
    * authenticate as that user, so a reload restores the transcript. Without
-   * a token the transport falls back to the guest cookie and history is
-   * skipped — the read plane can't identify a cookie-only browser caller
-   * (it reads the `x-guuey-guest` header or a Bearer, not the HttpOnly
-   * guest cookie), so there is no identity to replay.
+   * a token, identity falls to {@link getGuestSecret} (if supplied) and then
+   * to the guest cookie.
+   *
+   * Called with `{ forceRefresh: true }` exactly once: when the history read
+   * gets a 401 on a token this resolver already returned (a token cached
+   * before the mount-time history read fired can be stale by the time it
+   * runs — the same window the send path's own 401-retry closes). A resolver
+   * that caches (Amplify's `fetchAuthSession` does, and so does the widget's
+   * `createHostTokenProvider`) MUST bypass that cache for a forced call and
+   * obtain a genuinely fresh token — returning the SAME stale value would
+   * make the retry indistinguishable from not retrying at all. A resolver
+   * with nothing fresher to offer returns `null`, and the read surfaces the
+   * ORIGINAL 401 rather than replaying the value that just failed.
+   */
+  getAccessToken?: (opts?: { forceRefresh?: boolean }) => Promise<string | null>;
+  /**
+   * Resolve the caller's own persisted anonymous guest secret (64 lowercase
+   * hex chars), or `null` when there is none. Supply this on hosts whose
+   * cookie jar can't carry the pod's HttpOnly `guuey_guest` — notably the
+   * embedded widget, a third-party iframe whose cookies browsers partition
+   * or block outright.
+   *
+   * With a secret, BOTH the chat transport and the history read send
+   * `x-guuey-guest`, so an anonymous transcript replays on reload the same
+   * way a signed-in one does — the read plane identifies a guest by that
+   * header (it cannot see the HttpOnly cookie, which is why a cookie-only
+   * caller still gets no history).
+   *
+   * Called once per request, so a rotated secret takes effect immediately.
+   * A value that isn't 64 lowercase hex is ignored (never sent) and the
+   * request falls through to cookie mode.
+   *
+   * **Supply at most ONE identity resolver per mode.** Anonymous hosts pass
+   * this one; identified hosts pass {@link getAccessToken} and surface a token
+   * failure rather than continuing. Passing BOTH is a hazard, not a fallback
+   * chain: `getAccessToken` resolving `null` is indistinguishable here from
+   * "signed out on purpose", so a merely *expired or unavailable* token
+   * silently downgrades the caller to the anonymous identity. The request then
+   * SUCCEEDS — the pod accepts anonymous invokes unconditionally — but the
+   * turns land in a different thread (the pod forks on an owner mismatch
+   * rather than appending), unreachable from the identified session, which
+   * gets its own transcript back minus those turns on the next good load. A
+   * 401-then-re-request-token retry loop is exactly this window.
+   *
+   * MUST be synchronous and MUST NOT throw: a throw propagates and fails the
+   * invoke. This is a real hazard for the widget, not a formality —
+   * `localStorage` access raises `SecurityError` in a third-party iframe with
+   * storage blocked (Safari's default for embedded content), which is normal
+   * operation here. A host reading storage owns that handling and MUST return
+   * `null` on a blocked read, the way {@link localStorageThreadStore} does for
+   * the threadId; `null` degrades to cookie mode, whereas a throw takes the
+   * chat down. Deliberately NOT caught at this seam: catching a host-supplied
+   * callback would also swallow ordinary host bugs into a silent anonymous
+   * downgrade — the same failure this docblock warns about above.
    */
-  getAccessToken?: () => Promise<string | null>;
+  getGuestSecret?: () => string | null;
 }
 
 /**
  * Build the web host-adapter bundle for {@link useAgentInvoke}. Pass an
- * access-token resolver (and the read-plane base) to authenticate the chat
- * transport and enable transcript restore on reload; omit them for an
- * anonymous, history-less bundle.
+ * access-token resolver and/or a guest-secret resolver (plus the read-plane
+ * base) to give the chat transport an identity the read plane can also see,
+ * which is what enables transcript restore on reload; omit both for a
+ * cookie-only, history-less bundle.
  */
 export function createWebAdapters(
   opts: CreateWebAdaptersOptions = {},
 ): AgentInvokeAdapters {
-  const { apiBaseUrl, getAccessToken } = opts;
+  const { apiBaseUrl, getAccessToken, getGuestSecret } = opts;
 
   const transport: InvokeTransport = async function* (req) {
     const token = getAccessToken ? await getAccessToken() : null;
-    yield* fetchStreamTransport(req, token);
+    // Both candidates go to the transport; it owns the precedence (and the
+    // never-two-carriers rule) so there is exactly one place that decides.
+    yield* fetchStreamTransport(req, token, getGuestSecret ? getGuestSecret() : null);
   };
 
   const adapters: AgentInvokeAdapters = {
@@ -154,18 +260,57 @@ export function createWebAdapters(
     transport,
   };
 
-  if (apiBaseUrl && getAccessToken) {
+  // History needs an identity the READ plane can resolve: a Bearer or the
+  // `x-guuey-guest` header. Either resolver can supply one, so either one
+  // installs the adapter; a cookie-only caller is unidentifiable there and
+  // gets no adapter at all.
+  if (apiBaseUrl && (getAccessToken || getGuestSecret)) {
     adapters.history = {
       load: async (threadId) => {
-        const token = await getAccessToken();
+        // Same precedence, and the same one-carrier rule, as the transport:
+        // a bearer wins over the guest header, and the two never combine.
+        if (getAccessToken) {
+          const token = await getAccessToken();
+          if (token) {
+            try {
+              return await fetchThreadHistory({
+                baseUrl: apiBaseUrl,
+                threadId,
+                includeCards: true,
+                requestInit: { headers: { Authorization: `Bearer ${token}` } },
+              });
+            } catch (err) {
+              if (!(err instanceof HistoryUnauthorizedError)) throw err;
+              // The one retry the send path already gets on a 401
+              // (`withIdentifiedToken`): this read runs from a mount effect,
+              // before the send path has asked anyone for anything, so a
+              // token cached earlier can be the exact stale value that just
+              // failed. `forceRefresh` is the signal that asks past whatever
+              // cache the resolver keeps instead of returning that same dead
+              // value.
+              const fresh = await getAccessToken({ forceRefresh: true });
+              if (!fresh) throw err; // nothing fresher to retry with — the ORIGINAL 401 is the honest cause
+              return fetchThreadHistory({
+                baseUrl: apiBaseUrl,
+                threadId,
+                includeCards: true,
+                requestInit: { headers: { Authorization: `Bearer ${fresh}` } },
+              });
+            }
+          }
+        }
+        const guest = sendableGuestSecret(getGuestSecret?.());
+        if (guest) {
+          return fetchThreadHistory({
+            baseUrl: apiBaseUrl,
+            threadId,
+            includeCards: true,
+            requestInit: { headers: { [GUEST_HEADER]: guest } },
+          });
+        }
         // No readable identity → leave the chat empty (skip) rather than
         // `gone`, which would clear the persisted threadId.
-        if (!token) return { messages: [] };
-        return fetchThreadHistory({
-          baseUrl: apiBaseUrl,
-          threadId,
-          requestInit: { headers: { Authorization: `Bearer ${token}` } },
-        });
+        return { messages: [] };
       },
     };
   }