@effect-agent/platform-cloudflare 0.1.0-beta.9 → 0.1.0-beta.90

package/src/protected-browser/inspect-frame.ts

@@ -0,0 +1,125 @@
+// This fixed program runs in an isolated world. Pages cannot replace its native DOM methods.
+// Handles retain actual nodes; a selector is never reconstructed from an opaque reference.
+export const maxAttributeLength = 2048;
+
+export const inspectFrame = `(() => {
+  const doc = document;
+  const forms = [];
+  const isChoice = el => el instanceof HTMLInputElement && ['radio','checkbox'].includes(el.type);
+  const presented = el => {
+    if (el.closest('[hidden],[aria-hidden="true"],[inert]') ||
+      ['hidden','collapse'].includes(getComputedStyle(el).visibility)) return false;
+    for (let parent = el; parent; parent = parent.parentElement) {
+      if (getComputedStyle(parent).opacity === '0') return false;
+    }
+    return true;
+  };
+  const hasLayout = el => presented(el) &&
+    [...el.getClientRects()].some(rect => rect.width > 0 && rect.height > 0);
+  const available = el => el.type !== 'hidden' && !el.closest('[hidden],[aria-hidden="true"],[inert]') &&
+    (hasLayout(el) || (isChoice(el) && [...(el.labels ?? [])].some(hasLayout)));
+  const elements = [...doc.querySelectorAll('input,textarea,select,button,a[href]')].filter(available).slice(0, 65);
+  const labelText = el => {
+    const label = el.labels?.[0]?.cloneNode(true);
+    label?.querySelectorAll('input,textarea,select,script,style,noscript').forEach(child => child.remove());
+    return label?.textContent ?? el.getAttribute('aria-label');
+  };
+  const describe = (el) => {
+    if (doc !== document || !el.isConnected || el.ownerDocument !== doc || !available(el)) return null;
+    const form = el.form ?? null;
+    let formIndex = forms.indexOf(form);
+    if (formIndex < 0) { formIndex = forms.length; forms.push(form); }
+    // Resolved href (including path/query/fragment and base-URL changes) is part of the fingerprint.
+    const action = el instanceof HTMLAnchorElement ? el.href : form ? (el.hasAttribute('formaction') ? el.formAction : form.action || doc.URL) : doc.URL;
+    const method = form ? (el.hasAttribute('formmethod') ? el.formMethod : form.method) : '';
+    const enctype = form?.enctype ?? '';
+    const name = el.name ?? '';
+    const completion = el.getAttribute('autocomplete') ?? '';
+    const inputType = el.type ?? '';
+    const choiceValue = isChoice(el) ? el.value : '';
+    // Reject before parsing, fingerprinting or CDP transfer. Truncation could hide a target change.
+    if ([action, method, enctype, name, completion, inputType, choiceValue].some(value => value.length > ${maxAttributeLength})) return null;
+    const type = inputType.toLowerCase();
+    const autocomplete = completion.trim().toLowerCase().split(/\\s+/).at(-1);
+    const cardRoles = { 'cc-name':'card-name', 'cc-number':'card-number', 'cc-exp':'card-expiry',
+      'cc-exp-month':'card-expiry-month', 'cc-exp-year':'card-expiry-year', 'cc-csc':'card-security-code' };
+    let role = 'unsupported';
+    const nativeField = el instanceof HTMLInputElement || el instanceof HTMLSelectElement || el instanceof HTMLTextAreaElement;
+    if (nativeField && !['submit','button'].includes(type) && !el.matches(':disabled') && !el.readOnly && !(el instanceof HTMLSelectElement && el.multiple)) {
+      if (isChoice(el)) role = type;
+      else if (type === 'password' || ['current-password','new-password','one-time-code'].includes(autocomplete)) {
+        if (type === 'password' && form) role = 'password';
+      } else if (['text','email','tel','number','month','search','url','date','time','week','datetime-local','textarea',''].includes(type) || el instanceof HTMLSelectElement) {
+        if (cardRoles[autocomplete]) { if (form) role = cardRoles[autocomplete]; }
+        else if (autocomplete === 'username' || autocomplete === 'email') { if (form) role = 'username'; }
+        else if (['text','email'].includes(type) && form && form.querySelector('input[type="password"]')) role = 'username';
+        else if (el instanceof HTMLSelectElement) { if (!el.multiple) role = 'select'; }
+        else role = 'text';
+      }
+    } else if (el instanceof HTMLButtonElement || (el instanceof HTMLInputElement && ['submit','button'].includes(type))) {
+      if (!el.matches(':disabled')) role = type === 'submit' && form ? 'submit' : type === 'button' ? 'button' : 'unsupported';
+    } else if (el instanceof HTMLAnchorElement) role = 'link';
+    const fingerprint = JSON.stringify([role, action, method, enctype, name, completion, type, choiceValue]);
+    return { role, formIndex, action, fingerprint, ...(isChoice(el) ? {checked: el.checked} : {}),
+      label: (labelText(el) ?? (nativeField ? '' : el.textContent) ?? '').slice(0,200) };
+  };
+  const expose = ({role, formIndex, action, label, checked}) =>
+    ({role, formIndex, action, label, ...(checked === undefined ? {} : {checked})});
+  const original = elements.map(describe);
+  const validate = (index) => {
+    const current = describe(elements[index]);
+    if (!current || !original[index] || current.fingerprint !== original[index].fingerprint ||
+      current.formIndex !== original[index].formIndex) return null;
+    return expose(current);
+  };
+  return {
+    doc, elements, original: original.map(current => current && expose(current)), validate,
+    text: () => {
+      if (doc !== document) return null;
+      if (!doc.body) return '';
+      const walker = doc.createTreeWalker(doc.body, NodeFilter.SHOW_TEXT);
+      const range = doc.createRange();
+      let text = '';
+      for (let node = walker.nextNode(); node && text.length < 65536; node = walker.nextNode()) {
+        const parent = node.parentElement;
+        if (!parent || parent.closest('input,textarea,select,script,style,noscript,iframe,object,embed')) continue;
+        if (!presented(parent)) continue;
+        range.selectNodeContents(node);
+        if (![...range.getClientRects()].some(rect => rect.width > 0 && rect.height > 0)) continue;
+        text += (node.textContent ?? '').replace(/\\s+/g, ' ') + ' ';
+      }
+      return text.slice(0,65536);
+    },
+    fill: (index, role, value) => {
+      const current = validate(index);
+      if (!current || current.role !== role) return false;
+      const el = elements[index];
+      if (role === 'select') {
+        const options = [...el.options].filter(option => !option.matches(':disabled'));
+        const values = options.filter(option => option.value === value);
+        const matches = values.length > 0 ? values : options.filter(option => option.textContent?.trim() === value);
+        if (matches.length !== 1) return 'unsupported';
+        value = matches[0].value;
+        if ([...el.options].filter(option => option.value === value).length !== 1) return 'unsupported';
+      }
+      let prototype = Object.getPrototypeOf(el);
+      let setter;
+      while (prototype && !setter) { setter = Object.getOwnPropertyDescriptor(prototype,'value')?.set; prototype = Object.getPrototypeOf(prototype); }
+      if (!setter) return false;
+      // Validate and mutate in one isolated-world task, without focusing first and running
+      // page handlers between validation and assignment. Native setters support controlled inputs.
+      setter.call(el, value);
+      if (el.value !== value) return 'unsupported';
+      el.dispatchEvent(new Event('input', {bubbles:true}));
+      el.dispatchEvent(new Event('change', {bubbles:true}));
+      return true;
+    },
+    click: (index) => {
+      const current = validate(index);
+      if (!current || !['button','submit','link','radio','checkbox'].includes(current.role)) return false;
+      if (current.role === 'submit' && elements[index].form && !elements[index].form.matches(':valid')) return 'needs-attention';
+      elements[index].click();
+      return true;
+    }
+  };
+})()`;

package/src/protected-browser/native.ts

@@ -0,0 +1,445 @@
+/// <reference types="@cloudflare/workers-types" />
+import type { Browser, Frame, JSHandle, Page } from "@cloudflare/puppeteer";
+import { Clock, Context, Crypto, Effect, Redacted, Schema, type Scope } from "effect";
+import { type InteractiveBrowserPolicy } from "effect-agent/interactive-browser";
+import {
+  CredentialOrigin,
+  CredentialTarget,
+  ProtectedBrowserControl,
+} from "effect-agent/protected-browser";
+
+import { inspectFrame, maxAttributeLength } from "./inspect-frame.ts";
+import {
+  ProtectedBrowserDispatch,
+  ProtectedTransportError,
+  ProtectedDiscovery,
+  ProtectedPageContext,
+  type ProtectedBrowserTransport,
+} from "./policy.ts";
+
+// The pinned SDK implements this method but strips its internal declaration from lib/types.d.ts.
+// Keep the declaration narrow and refuse runtimes without it. No main-world fallback is safe.
+declare module "@cloudflare/puppeteer" {
+  interface Frame {
+    isolatedRealm(): { evaluateHandle(source: string): Promise<JSHandle<unknown>> };
+  }
+}
+
+const Description = Schema.Struct({
+  role: ProtectedBrowserControl.fields.role,
+  formIndex: Schema.Natural,
+  action: Schema.String.check(Schema.isMaxLength(maxAttributeLength)),
+  label: Schema.String.check(Schema.isMaxLength(200)),
+  checked: Schema.optionalKey(Schema.Boolean),
+});
+
+const Descriptions = Schema.Array(Schema.NullOr(Description)).check(Schema.isMaxLength(65));
+
+interface FrameState {
+  readonly frame: Frame;
+  readonly handle: JSHandle<unknown>;
+  readonly ref: string;
+  readonly document: string;
+  readonly forms: Map<number, string>;
+}
+interface ControlState {
+  readonly frame: FrameState;
+  readonly index: number;
+  readonly control: ProtectedBrowserControl;
+  readonly expires: number;
+}
+
+/** One host-private acquired session. The SDK handles and exact-session cleanup have one owner. */
+export class ProtectedNativeSession extends Context.Service<
+  ProtectedNativeSession,
+  {
+    readonly browser: Browser;
+    readonly page: Page;
+    readonly close: Effect.Effect<"confirmed" | "unconfirmed">;
+    /** Host-owned attachment release may detach a committed suspended session. */
+    readonly release?: Effect.Effect<void>;
+  }
+>()("@effect-agent/platform-cloudflare/ProtectedNativeSession") {}
+
+const transportError = (reason: ProtectedTransportError["reason"]) =>
+  new ProtectedTransportError({ reason });
+
+const decode = <A>(schema: Schema.Codec<A>, value: unknown) =>
+  Schema.decodeUnknownEffect(schema)(value).pipe(Effect.mapError(() => transportError("provider")));
+
+// Attach rejection handling inside the SDK callback before workerd can report foreign diagnostics.
+const remote = <A>(run: (signal: AbortSignal) => Promise<A>) =>
+  Effect.tryPromise({
+    try: async (signal) => {
+      try {
+        return { ok: true as const, value: await run(signal) };
+      } catch {
+        return { ok: false as const };
+      }
+    },
+    catch: () => transportError("provider"),
+  }).pipe(
+    Effect.flatMap((result) =>
+      result.ok ? Effect.succeed(result.value) : Effect.fail(transportError("provider")),
+    ),
+  );
+
+/** Host-private scoped transport. Session capabilities are requirements; policy is per-pass data. */
+export const makeProtectedNativeTransport = Effect.fn("ProtectedNativeTransport.make")(function* (
+  policy: InteractiveBrowserPolicy,
+): Effect.fn.Return<
+  ProtectedBrowserTransport,
+  never,
+  ProtectedNativeSession | Crypto.Crypto | Scope.Scope
+> {
+  const session = yield* ProtectedNativeSession;
+  const { browser, page } = session;
+  const crypto = yield* Crypto.Crypto;
+  const clock = yield* Clock.Clock;
+  const uuid = crypto.randomUUIDv4.pipe(Effect.mapError(() => transportError("provider")));
+  let closed = false;
+  let violation = false;
+  let documentRef: string | undefined;
+  let observationOrigins: ReadonlySet<string> | undefined;
+  const frames = new Map<Frame, FrameState>();
+  const controls = new Map<string, ControlState>();
+
+  const origin = (value: string) =>
+    Effect.try({
+      try: () => {
+        const url = new URL(value);
+
+        if (url.username || url.password) throw transportError("stale-reference");
+        if (!Schema.is(CredentialOrigin)(url.origin)) throw transportError("unsupported");
+        if (policy.network._tag === "ExactHosts" && !policy.network.allowedHosts.includes(url.host))
+          throw transportError("stale-reference");
+
+        return url.origin;
+      },
+      catch: (cause) =>
+        Schema.is(ProtectedTransportError)(cause) ? cause : transportError("provider"),
+    });
+
+  const check = Effect.suspend(() =>
+    closed || violation || !browser.isConnected()
+      ? Effect.fail(transportError("stale-reference"))
+      : Effect.void,
+  );
+
+  const clear = () => {
+    controls.clear();
+    // Browser event callbacks only invalidate. The next Effect operation allocates the new identity.
+    documentRef = undefined;
+  };
+
+  const onNavigated = () => {
+    clear();
+  };
+
+  const onTarget = (target: { type(): string }) => {
+    if (target.type() !== "page") return;
+    // No popup or additional page may inherit an observation channel.
+    violation = true;
+    clear();
+  };
+
+  const invalidate = () => {
+    closed = true;
+    clear();
+  };
+
+  const observationFrames = Effect.gen(function* () {
+    const list = page.frames();
+
+    if (list.length > 32) return yield* transportError("unsupported");
+
+    // Opaque/blank child documents have no observation channel or credential targets.
+    // The main document and every retained HTTPS child still require strict origin validation.
+    return yield* Effect.filter(list, (frame) =>
+      frame === page.mainFrame()
+        ? Effect.succeed(true)
+        : Effect.try({
+            try: () => frame.url() !== "" && new URL(frame.url()).protocol === "https:",
+            catch: () => transportError("provider"),
+          }),
+    );
+  });
+
+  const context = Effect.gen(function* () {
+    yield* check;
+    const list = yield* observationFrames;
+    const topOrigin = yield* origin(page.url());
+    const frameOrigins = [...new Set(yield* Effect.forEach(list, (frame) => origin(frame.url())))];
+
+    if (frameOrigins.length > 16) return yield* transportError("unsupported");
+
+    if (documentRef === undefined) documentRef = yield* uuid;
+
+    return yield* decode(ProtectedPageContext, { document: documentRef, topOrigin, frameOrigins });
+  });
+
+  const isCurrent = Effect.fn("ProtectedNativeTransport.isCurrent")(function* (state: FrameState) {
+    if (state.frame.detached) return false;
+
+    return yield* remote(() =>
+      state.handle.evaluate((held) => {
+        if (typeof held !== "object" || held === null) return false;
+
+        return Reflect.get(held, "doc") === Reflect.get(globalThis, "document");
+      }),
+    );
+  });
+
+  const get = Effect.fn("ProtectedNativeTransport.get")(function* (ref: string) {
+    yield* check;
+    const state = controls.get(ref);
+
+    if (
+      !state ||
+      (observationOrigins !== undefined &&
+        !observationOrigins.has(state.control.target.frameOrigin)) ||
+      state.expires <= (yield* clock.currentTimeMillis) ||
+      !(yield* isCurrent(state.frame))
+    )
+      return yield* transportError("stale-reference");
+
+    const current = yield* remote(() =>
+      state.frame.handle.evaluate((held, index) => {
+        if (typeof held !== "object" || held === null) return null;
+
+        return Reflect.apply(Reflect.get(held, "validate"), held, [index]);
+      }, state.index),
+    );
+
+    const description = yield* decode(Schema.NullOr(Description), current);
+
+    if (description === null) return yield* transportError("stale-reference");
+    const ctx = yield* context;
+
+    if (
+      ctx.topOrigin !== state.control.target.topOrigin ||
+      (yield* origin(state.frame.frame.url())) !== state.control.target.frameOrigin ||
+      (yield* origin(description.action)) !== state.control.target.recipientOrigin ||
+      description.role !== state.control.role
+    )
+      return yield* transportError("stale-reference");
+
+    return state;
+  });
+
+  const close = yield* Effect.cached(
+    Effect.gen(function* () {
+      invalidate();
+
+      return yield* session.close;
+    }).pipe(
+      Effect.ensuring(
+        Effect.sync(() => {
+          page.off("framenavigated", onNavigated);
+          page.off("framedetached", onNavigated);
+          browser.off("targetcreated", onTarget);
+          // Handles die with the exact session. Do not block remote termination on local disposal.
+          frames.clear();
+        }),
+      ),
+    ),
+  );
+
+  yield* Effect.acquireRelease(
+    Effect.sync(() => {
+      page.on("framenavigated", onNavigated);
+      page.on("framedetached", onNavigated);
+      browser.on("targetcreated", onTarget);
+    }),
+    () =>
+      session.release === undefined
+        ? close
+        : session.release.pipe(
+            Effect.ensuring(
+              Effect.sync(() => {
+                invalidate();
+                page.off("framenavigated", onNavigated);
+                page.off("framedetached", onNavigated);
+                browser.off("targetcreated", onTarget);
+                frames.clear();
+              }),
+            ),
+          ),
+  );
+
+  return {
+    restrictObservation: Effect.fn("ProtectedNativeTransport.restrictObservation")(
+      function* (origins) {
+        yield* check;
+        observationOrigins =
+          origins === undefined
+            ? undefined
+            : new Set(yield* decode(Schema.Array(CredentialOrigin), origins));
+        // A later grant expansion must not revive previously excluded references.
+        for (const [ref, state] of controls)
+          if (
+            observationOrigins !== undefined &&
+            !observationOrigins.has(state.control.target.frameOrigin)
+          )
+            controls.delete(ref);
+      },
+    ),
+    context,
+    invalidate,
+    resetReferences: clear,
+    close,
+    navigate: Effect.fn("ProtectedNativeTransport.navigate")(function* (url) {
+      yield* check;
+      yield* origin(url);
+      clear();
+      yield* remote(() => page.goto(url, { waitUntil: "load" }));
+      yield* context;
+    }),
+    target: (ref) => get(ref).pipe(Effect.map((state) => state.control)),
+    discover: Effect.gen(function* () {
+      const before = yield* context;
+
+      controls.clear();
+      for (const state of frames.values()) yield* remote(() => state.handle.dispose());
+      frames.clear();
+      const discovered: Array<ProtectedBrowserControl> = [];
+      let text = "";
+      let truncated = false;
+      const frameOrigins = new Set<string>();
+
+      for (const frame of yield* observationFrames) {
+        const frameOrigin = yield* origin(frame.url());
+
+        if (observationOrigins !== undefined && !observationOrigins.has(frameOrigin)) continue;
+        frameOrigins.add(frameOrigin);
+        if (typeof frame.isolatedRealm !== "function") return yield* transportError("unsupported");
+        const handle = yield* remote(() => frame.isolatedRealm().evaluateHandle(inspectFrame));
+
+        const state: FrameState = {
+          frame,
+          handle,
+          ref: yield* uuid,
+          document: yield* uuid,
+          forms: new Map(),
+        };
+
+        frames.set(frame, state);
+
+        const raw = yield* remote(() =>
+          handle.evaluate((held) => {
+            if (typeof held !== "object" || held === null) return null;
+
+            return Reflect.get(held, "original");
+          }),
+        );
+
+        const descriptions = yield* decode(Descriptions, raw);
+
+        for (let index = 0; index < descriptions.length; index++) {
+          const desc = descriptions[index];
+
+          if (!desc) continue;
+          if (discovered.length === 64) {
+            truncated = true;
+            break;
+          }
+          let form = state.forms.get(desc.formIndex);
+
+          if (form === undefined) {
+            form = yield* uuid;
+            state.forms.set(desc.formIndex, form);
+          }
+          // Unsupported destinations/controls are not offered as credential targets.
+          const recipient = yield* origin(desc.action).pipe(Effect.result);
+
+          if (recipient._tag === "Failure") continue;
+
+          const control = ProtectedBrowserControl.make({
+            ref: yield* uuid,
+            role: desc.role,
+            label: desc.label,
+            ...(desc.checked === undefined ? {} : { checked: desc.checked }),
+            ...(desc.role === "link" ? { url: desc.action } : {}),
+            target: CredentialTarget.make({
+              topOrigin: before.topOrigin,
+              frameOrigin: yield* origin(frame.url()),
+              recipientOrigin: recipient.success,
+              document: state.document,
+              frame: state.ref,
+              form,
+            }),
+          });
+
+          controls.set(control.ref, {
+            frame: state,
+            index,
+            control,
+            expires: (yield* clock.currentTimeMillis) + 60_000,
+          });
+          discovered.push(control);
+        }
+
+        const rawText = yield* remote(() =>
+          handle.evaluate((held) => {
+            if (typeof held !== "object" || held === null) return null;
+
+            return Reflect.apply(Reflect.get(held, "text"), held, []);
+          }),
+        );
+
+        text += yield* decode(Schema.String.check(Schema.isMaxLength(65536)), rawText);
+        if (text.length > 65536) {
+          text = text.slice(0, 65536);
+          truncated = true;
+        }
+      }
+      if ((yield* context).document !== before.document)
+        return yield* transportError("stale-reference");
+
+      return yield* decode(ProtectedDiscovery, {
+        ...before,
+        frameOrigins: [...frameOrigins],
+        text,
+        controls: discovered,
+        truncated,
+      });
+    }),
+    fill: Effect.fn("ProtectedNativeTransport.fill")(function* (ref, role, value) {
+      const dispatch = yield* ProtectedBrowserDispatch;
+      const state = yield* get(ref);
+
+      // CDP dispatch may mutate before its reply is lost, so uncertainty starts here.
+      yield* dispatch.mark;
+
+      const filled = yield* remote(() =>
+        state.frame.handle.evaluate(
+          (held, index, expectedRole, secret) => {
+            if (typeof held !== "object" || held === null) return false;
+
+            return Reflect.apply(Reflect.get(held, "fill"), held, [index, expectedRole, secret]);
+          },
+          state.index,
+          role,
+          Redacted.value(value),
+        ),
+      );
+
+      if (filled === "unsupported") return yield* transportError("unsupported");
+      if (filled !== true) return yield* transportError("stale-reference");
+    }),
+    click: Effect.fn("ProtectedNativeTransport.click")(function* (ref) {
+      const state = yield* get(ref);
+
+      const clicked = yield* remote(() =>
+        state.frame.handle.evaluate((held, index) => {
+          if (typeof held !== "object" || held === null) return false;
+
+          return Reflect.apply(Reflect.get(held, "click"), held, [index]);
+        }, state.index),
+      );
+
+      if (clicked === "needs-attention") return yield* transportError("needs-attention");
+      if (clicked !== true) return yield* transportError("stale-reference");
+    }),
+  };
+}, Effect.withTracerEnabled(false));