@effect-agent/platform-cloudflare 0.1.0-beta.87 → 0.1.0-beta.89

package/src/protected-browser/policy.ts

@@ -25,6 +25,7 @@ import {
   LoginCredential,
   ProtectedBrowser,
   ProtectedBrowserClick,
+  ProtectedBrowserCheckpoint,
   ProtectedBrowserError,
   ProtectedBrowserFill,
   ProtectedBrowserNavigate,
@@ -69,6 +70,10 @@ export interface ProtectedBrowserTransport {
   ) => Effect.Effect<void, ProtectedTransportError, ProtectedBrowserDispatch>;
   /** Invalidates local references synchronously before bounded exact-session cleanup. */
   readonly invalidate: () => void;
+  /** Forget all discovered controls on a controller transition. */
+  readonly resetReferences: () => void;
+  /** Host attachment release, available only for transferable provider sessions. */
+  readonly detach?: Effect.Effect<void, ProtectedBrowserError>;
   readonly close: Effect.Effect<typeof ProtectedCleanup.Type>;
 }
 
@@ -137,581 +142,680 @@ const secretFor = (material: BrowserCredentialMaterial, role: typeof CredentialF
   }
 };
 
-/**
- * Fresh private passes only. Account administrators and Browser Rendering token holders are
- * trusted operators. No viewer, handoff, raw JavaScript, screenshot or plaintext credential API exists.
- * Hosts explicitly authorize post-exposure observations for recipients they trust not to echo.
- */
-export const browserRunProtectedLayer = () =>
-  Layer.effect(ProtectedBrowser)(
-    Effect.gen(function* () {
-      const transport = yield* BrowserRunProtectedTransport;
-      const crypto = yield* Crypto.Crypto;
+/** Shared protected policy implementation for ephemeral and host-owned passes. */
+export const makeProtectedBrowserPolicy = Effect.fn("ProtectedBrowser.open")(function* (
+  input: InteractiveBrowserPolicy,
+  checkpoint?: ProtectedBrowserCheckpoint,
+) {
+  const initialError = (reason: ProtectedBrowserError["reason"]) =>
+    new ProtectedBrowserError({
+      reason,
+      dispatch: "not-dispatched",
+      milestone: "none",
+      observation: "closed",
+      cleanup: "not-requested",
+    });
+
+  const decodedPolicy = yield* Schema.decodeEffect(InteractiveBrowserPolicy)(input).pipe(
+    Effect.mapError(() => initialError("denied")),
+  );
 
-      const open = Effect.fn("ProtectedBrowser.open")(function* (
-        input: InteractiveBrowserPolicy,
-      ): Effect.fn.Return<
-        ProtectedBrowserHandle,
-        ProtectedBrowserError,
-        Scope.Scope | BrowserCredentialAccess
-      > {
-        const initialError = (reason: ProtectedBrowserError["reason"]) =>
-          new ProtectedBrowserError({
-            reason,
-            dispatch: "not-dispatched",
-            milestone: "none",
-            observation: "closed",
-            cleanup: "not-requested",
-          });
+  if (decodedPolicy.network._tag === "PublicWeb") return yield* initialError("unsupported");
 
-        const decodedPolicy = yield* Schema.decodeEffect(InteractiveBrowserPolicy)(input).pipe(
-          Effect.mapError(() => initialError("denied")),
-        );
+  const policy = InteractiveBrowserPolicy.make({
+    ...decodedPolicy,
+    network:
+      decodedPolicy.network._tag === "ExactHosts"
+        ? { _tag: "ExactHosts", allowedHosts: [...decodedPolicy.network.allowedHosts] }
+        : { _tag: "Unrestricted" },
+  });
 
-        if (decodedPolicy.network._tag === "PublicWeb") return yield* initialError("unsupported");
-
-        const policy = InteractiveBrowserPolicy.make({
-          ...decodedPolicy,
-          network:
-            decodedPolicy.network._tag === "ExactHosts"
-              ? { _tag: "ExactHosts", allowedHosts: [...decodedPolicy.network.allowedHosts] }
-              : { _tag: "Unrestricted" },
-        });
-
-        // Capture the host access service for THIS execution, not the application singleton.
-        const access = yield* BrowserCredentialAccess;
-        const started = yield* Clock.currentTimeMillis;
-        const driver = yield* transport.open(policy);
-        const lock = yield* Semaphore.make(1);
-        let observation: typeof ProtectedObservationState.Type = "before-exposure";
-        let cleanup: typeof ProtectedCleanup.Type = "not-requested";
-        let actions = 0;
-        let dispatch: ProtectedBrowserError["dispatch"] = "not-dispatched";
-        let milestone: ProtectedBrowserError["milestone"] = "none";
-        const exposures: Array<CredentialTarget> = [];
-
-        const offers = new Map<
-          string,
-          {
-            caller: Redacted.Redacted<string>;
-            key: Redacted.Redacted<string>;
-            target: CredentialTarget;
-            targetRef: string;
-            kind: typeof CredentialKind.Type;
-            expires: number;
-          }
-        >();
-
-        const fail = (reason: ProtectedBrowserError["reason"]) =>
-          new ProtectedBrowserError({ reason, dispatch, milestone, observation, cleanup });
-
-        const close = yield* Effect.cached(
-          Effect.uninterruptible(
-            Effect.gen(function* () {
-              observation = "closed";
-              offers.clear();
-              driver.invalidate();
-              cleanup = yield* driver.close.pipe(
-                Effect.interruptible,
-                Effect.timeoutOrElse({
-                  duration: "10 seconds",
-                  orElse: () => Effect.succeed("unconfirmed" as const),
-                }),
-                Effect.catchCause(() => Effect.succeed("unconfirmed" as const)),
-              );
+  // Capture the host access service for THIS execution, not the application singleton.
+  const access = yield* BrowserCredentialAccess;
 
-              return cleanup;
-            }),
-          ),
+  const restored =
+    checkpoint === undefined
+      ? undefined
+      : yield* Schema.decodeEffect(ProtectedBrowserCheckpoint)(checkpoint).pipe(
+          Effect.mapError(() => initialError("denied")),
         );
 
-        yield* Effect.addFinalizer(() =>
-          close.pipe(
-            Effect.flatMap((result) =>
-              result === "unconfirmed"
-                ? Effect.logWarning("Protected browser exact-session closure unconfirmed")
-                : Effect.void,
-            ),
-          ),
+  const now = yield* Clock.currentTimeMillis;
+
+  if (
+    restored !== undefined &&
+    (restored.startedAt > now ||
+      restored.actions > policy.maxActions ||
+      now - restored.startedAt >= policy.maxElapsedMillis)
+  )
+    return yield* initialError("timeout");
+  const started = restored?.startedAt ?? now;
+  const driver = yield* (yield* BrowserRunProtectedTransport).open(policy);
+  const crypto = yield* Crypto.Crypto;
+  let suspended = restored !== undefined;
+  let detached = false;
+  let needsObservation = restored !== undefined;
+  let humanExposure = restored?.humanExposure ?? false;
+  let humanOrigins = [...(restored?.humanOrigins ?? [])];
+  const lock = yield* Semaphore.make(1);
+  let observation: typeof ProtectedObservationState.Type = "before-exposure";
+  let cleanup: typeof ProtectedCleanup.Type = "not-requested";
+  let actions = restored?.actions ?? 0;
+  let dispatch: ProtectedBrowserError["dispatch"] = restored?.dispatch ?? "not-dispatched";
+  let milestone: ProtectedBrowserError["milestone"] = restored?.milestone ?? "none";
+  const exposures: Array<CredentialTarget> = [...(restored?.exposures ?? [])];
+
+  const offers = new Map<
+    string,
+    {
+      caller: Redacted.Redacted<string>;
+      key: Redacted.Redacted<string>;
+      target: CredentialTarget;
+      targetRef: string;
+      kind: typeof CredentialKind.Type;
+      expires: number;
+    }
+  >();
+
+  const fail = (reason: ProtectedBrowserError["reason"]) =>
+    new ProtectedBrowserError({ reason, dispatch, milestone, observation, cleanup });
+
+  const close = yield* Effect.cached(
+    Effect.uninterruptible(
+      Effect.gen(function* () {
+        observation = "closed";
+        offers.clear();
+        driver.invalidate();
+        cleanup = yield* driver.close.pipe(
+          Effect.interruptible,
+          Effect.timeoutOrElse({
+            duration: "10 seconds",
+            orElse: () => Effect.succeed("unconfirmed" as const),
+          }),
+          Effect.catchCause(() => Effect.succeed("unconfirmed" as const)),
         );
 
-        const remote = <A, R>(effect: Effect.Effect<A, ProtectedTransportError, R>) =>
-          effect.pipe(Effect.mapError((error) => fail(error.reason)));
-
-        const decode = <A>(schema: Schema.Codec<A>, value: unknown) =>
-          Schema.decodeUnknownEffect(schema)(value).pipe(Effect.mapError(() => fail("provider")));
+        return cleanup;
+      }),
+    ),
+  );
 
-        const caller = access.caller.pipe(Effect.mapError((error) => fail(error.reason)));
-        const pageContext = remote(driver.context);
+  yield* Effect.addFinalizer(() =>
+    detached
+      ? Effect.void
+      : close.pipe(
+          Effect.flatMap((result) =>
+            result === "unconfirmed"
+              ? Effect.logWarning("Protected browser exact-session closure unconfirmed")
+              : Effect.void,
+          ),
+        ),
+  );
 
-        const permitObservation = Effect.gen(function* () {
-          const context = yield* pageContext;
-          let origins: ReadonlyArray<typeof CredentialOrigin.Type> | undefined;
+  const remote = <A, R>(effect: Effect.Effect<A, ProtectedTransportError, R>) =>
+    effect.pipe(Effect.mapError((error) => fail(error.reason)));
+
+  const decode = <A>(schema: Schema.Codec<A>, value: unknown) =>
+    Schema.decodeUnknownEffect(schema)(value).pipe(Effect.mapError(() => fail("provider")));
+
+  const caller = access.caller.pipe(Effect.mapError((error) => fail(error.reason)));
+  const pageContext = remote(driver.context);
+
+  const permitObservation = Effect.gen(function* () {
+    const context = yield* pageContext;
+    let origins: ReadonlyArray<typeof CredentialOrigin.Type> | undefined;
+
+    if (exposures.length > 0 || humanExposure) {
+      observation = "protected";
+      const principal = yield* caller;
+
+      const rawDecision = yield* access
+        .observation({
+          ...context,
+          caller: principal,
+          exposures: [...exposures],
+          humanExposure,
+          humanOrigins,
+        })
+        .pipe(Effect.mapError((error) => fail(error.reason)));
+
+      if (Redacted.value(yield* caller) !== Redacted.value(principal)) return yield* fail("denied");
+
+      const decision = yield* Schema.decodeEffect(CredentialObservationDecision)(rawDecision).pipe(
+        Effect.mapError(() => fail("observation-blocked")),
+      );
+
+      if (decision === "deny") return yield* fail("observation-blocked");
+      if (typeof decision !== "string") {
+        origins = [...decision.origins];
+        if (!origins.includes(context.topOrigin)) return yield* fail("observation-blocked");
+      }
+      observation = "approved-after-exposure";
+    }
+    yield* remote(driver.restrictObservation(origins));
+
+    return {
+      ...context,
+      frameOrigins: context.frameOrigins.filter(
+        (origin) => origins === undefined || origins.includes(origin),
+      ),
+    };
+  });
+
+  const target = (ref: string) => remote(driver.target(ref));
+
+  const authorizeAction = Effect.fn("ProtectedBrowser.authorizeAction")(function* (
+    action: ProtectedBrowserAction,
+  ) {
+    if (access.authorizeAction === undefined) {
+      if (action._tag === "Submit") return yield* fail("unsupported");
+
+      return;
+    }
+    const principal = yield* caller;
+
+    yield* access
+      .authorizeAction({ caller: principal, action, exposures: [...exposures] })
+      .pipe(Effect.mapError((error) => fail(error.reason)));
+    if (Redacted.value(yield* caller) !== Redacted.value(principal)) return yield* fail("denied");
+    if (action._tag !== "Navigate") {
+      const current = yield* target(action.ref);
+
+      if (
+        !sameTarget(current.target, action.target) ||
+        current.role !== (action._tag === "Submit" ? "submit" : action.role) ||
+        (action._tag === "Click" && action.role === "link" && current.url !== action.url)
+      )
+        return yield* fail("stale-reference");
+    }
+  }, Effect.withTracerEnabled(false));
+
+  const bounded = <A>(result: A) => {
+    const bytes = new TextEncoder().encode(JSON.stringify(result)).byteLength;
+
+    return bytes <= policy.maxReturnedBytes ? Effect.succeed(result) : Effect.fail(fail("limit"));
+  };
+
+  const run = <A>(effect: Effect.Effect<A, ProtectedBrowserError>, observing = false) =>
+    lock
+      .withPermitsIfAvailable(1)(
+        Effect.gen(function* () {
+          if (suspended || detached) return yield* fail("busy");
+          if (needsObservation && !observing) return yield* fail("stale-reference");
+          dispatch = "not-dispatched";
+          milestone = "none";
+          if (observation === "closed") return yield* fail("closed");
+          if (++actions > policy.maxActions) return yield* fail("limit");
+
+          const remaining = policy.maxElapsedMillis - ((yield* Clock.currentTimeMillis) - started);
+
+          if (remaining <= 0) {
+            yield* close;
+
+            return yield* fail("timeout");
+          }
 
-          if (exposures.length > 0) {
-            observation = "protected";
-            const principal = yield* caller;
+          return yield* effect.pipe(
+            Effect.timeoutOrElse({
+              duration: remaining,
+              orElse: () => Effect.fail(fail("timeout")),
+            }),
+            Effect.catchCause((cause) =>
+              Effect.gen(function* () {
+                // No foreign exception or defect is retained. Interrupted operations still finalize.
+                const error = cause.reasons.find(
+                  (reason) =>
+                    reason._tag === "Fail" && Schema.is(ProtectedBrowserError)(reason.error),
+                );
 
-            const rawDecision = yield* access
-              .observation({ ...context, caller: principal, exposures: [...exposures] })
-              .pipe(Effect.mapError((error) => fail(error.reason)));
+                const reason =
+                  error?._tag === "Fail" && Schema.is(ProtectedBrowserError)(error.error)
+                    ? error.error.reason
+                    : "provider";
 
-            if (Redacted.value(yield* caller) !== Redacted.value(principal))
-              return yield* fail("denied");
+                const interrupt = cause.reasons.some((reason) => reason._tag === "Interrupt");
 
-            const decision = yield* Schema.decodeEffect(CredentialObservationDecision)(
-              rawDecision,
-            ).pipe(Effect.mapError(() => fail("observation-blocked")));
+                if (
+                  dispatch !== "not-dispatched" ||
+                  interrupt ||
+                  reason === "provider" ||
+                  reason === "timeout"
+                )
+                  yield* close;
+                if (interrupt) return yield* Effect.interrupt;
 
-            if (decision === "deny") return yield* fail("observation-blocked");
-            if (typeof decision !== "string") {
-              origins = [...decision.origins];
-              if (!origins.includes(context.topOrigin)) return yield* fail("observation-blocked");
-            }
-            observation = "approved-after-exposure";
+                return yield* fail(
+                  dispatch === "possibly-dispatched" && reason === "provider"
+                    ? "outcome-unknown"
+                    : reason,
+                );
+              }),
+            ),
+            Effect.onInterrupt(() => close),
+            Effect.withTracerEnabled(false),
+          );
+        }),
+      )
+      .pipe(
+        Effect.flatMap(
+          Effect.fromOption(
+            () =>
+              new ProtectedBrowserError({
+                reason: "busy",
+                dispatch: "not-dispatched",
+                milestone: "none",
+                observation,
+                cleanup,
+              }),
+          ),
+        ),
+      );
+
+  const handle: ProtectedBrowserHandle = {
+    close: Effect.suspend(() => (detached ? Effect.succeed("not-requested" as const) : close)),
+    navigate: (request) =>
+      run(
+        Effect.gen(function* () {
+          const decoded = yield* Schema.decodeEffect(ProtectedBrowserNavigate)(request).pipe(
+            Effect.mapError(() => fail("denied")),
+          );
+
+          let url: URL;
+
+          try {
+            url = new URL(decoded.url);
+          } catch {
+            return yield* fail("denied");
           }
-          yield* remote(driver.restrictObservation(origins));
+          if (
+            url.protocol !== "https:" ||
+            url.username ||
+            url.password ||
+            (policy.network._tag === "ExactHosts" &&
+              !policy.network.allowedHosts.includes(url.host))
+          )
+            return yield* fail("denied");
+          if (exposures.length > 0 || humanExposure) yield* permitObservation;
+          yield* authorizeAction({ _tag: "Navigate", url: decoded.url });
+          offers.clear();
+          dispatch = "possibly-dispatched";
+          yield* remote(driver.navigate(decoded.url));
+          dispatch = "dispatched";
+          yield* permitObservation;
+        }),
+      ),
+    observe: run(
+      Effect.gen(function* () {
+        const before = yield* permitObservation;
+        const result = yield* remote(driver.discover);
+        const after = yield* permitObservation;
+
+        if (
+          before.document !== after.document ||
+          result.document !== after.document ||
+          result.topOrigin !== after.topOrigin
+        )
+          return yield* fail("stale-reference");
+        if (result.frameOrigins.some((origin) => !after.frameOrigins.includes(origin)))
+          return yield* fail("observation-blocked");
+
+        const observation = yield* bounded(
+          ProtectedBrowserObservation.make({
+            ...result,
+            observation:
+              exposures.length > 0 || humanExposure ? "approved-after-exposure" : "before-exposure",
+          }),
+        );
 
-          return {
-            ...context,
-            frameOrigins: context.frameOrigins.filter(
-              (origin) => origins === undefined || origins.includes(origin),
-            ),
-          };
-        });
+        needsObservation = false;
+
+        return observation;
+      }),
+      true,
+    ),
+    click: (request) =>
+      run(
+        Effect.gen(function* () {
+          const decoded = yield* Schema.decodeEffect(ProtectedBrowserClick)(request).pipe(
+            Effect.mapError(() => fail("denied")),
+          );
+
+          yield* permitObservation;
+          const control = yield* target(decoded.ref);
+
+          if (
+            control.role !== "link" &&
+            control.role !== "button" &&
+            control.role !== "radio" &&
+            control.role !== "checkbox" &&
+            control.role !== "submit"
+          )
+            return yield* fail("unsupported");
+          let action: ProtectedBrowserAction;
+
+          if (control.role === "link") {
+            if (control.url === undefined) return yield* fail("unsupported");
+            action = {
+              _tag: "Click",
+              ref: decoded.ref,
+              target: control.target,
+              role: "link",
+              url: control.url,
+            };
+          } else if (control.role === "submit") {
+            action = { _tag: "Submit", ref: decoded.ref, target: control.target };
+          } else {
+            action = {
+              _tag: "Click",
+              ref: decoded.ref,
+              target: control.target,
+              role: control.role,
+            };
+          }
+          yield* authorizeAction(action);
+          dispatch = "possibly-dispatched";
+          yield* remote(driver.click(decoded.ref)).pipe(
+            Effect.catch((error) => {
+              if (error.reason === "needs-attention") dispatch = "not-dispatched";
 
-        const target = (ref: string) => remote(driver.target(ref));
+              return Effect.fail(error);
+            }),
+          );
+          dispatch = "dispatched";
+          if (control.role === "submit") milestone = "submission-dispatched";
+          yield* permitObservation;
+        }),
+      ),
+    fill: (request) =>
+      run(
+        Effect.gen(function* () {
+          const decoded = yield* Schema.decodeEffect(ProtectedBrowserFill)(request).pipe(
+            Effect.mapError(() => fail("denied")),
+          );
+
+          yield* permitObservation;
+          const control = yield* target(decoded.ref);
+
+          if (control.role !== "text" && control.role !== "select")
+            return yield* fail("unsupported");
+          yield* authorizeAction({
+            _tag: "Fill",
+            ref: decoded.ref,
+            target: control.target,
+            role: control.role,
+          });
+          yield* remote(driver.fill(decoded.ref, control.role, Redacted.make(decoded.value))).pipe(
+            Effect.provideService(ProtectedBrowserDispatch, {
+              mark: Effect.sync(() => {
+                dispatch = "possibly-dispatched";
+              }),
+            }),
+          );
+          dispatch = "dispatched";
+          milestone = "filled";
+          yield* permitObservation;
+        }),
+      ),
+    listCredentialOffers: (request) =>
+      run(
+        Effect.gen(function* () {
+          const decoded = yield* Schema.decodeEffect(ListCredentialOffers)(request).pipe(
+            Effect.mapError(() => fail("denied")),
+          );
+
+          yield* permitObservation;
+          const control = yield* target(decoded.target);
+
+          if (kindFor(control.role) !== decoded.kind) return yield* fail("unsupported");
+          const principal = yield* caller;
 
-        const authorizeAction = Effect.fn("ProtectedBrowser.authorizeAction")(function* (
-          action: ProtectedBrowserAction,
-        ) {
-          if (access.authorizeAction === undefined) {
-            if (action._tag === "Submit") return yield* fail("unsupported");
+          const candidates = yield* access
+            .list({ caller: principal, kind: decoded.kind, target: control.target })
+            .pipe(Effect.mapError((error) => fail(error.reason)));
 
-            return;
+          const now = yield* Clock.currentTimeMillis;
+
+          for (const [ref, offer] of offers) if (offer.expires <= now) offers.delete(ref);
+          if (candidates.length > 16 || offers.size + candidates.length > 64)
+            return yield* fail("limit");
+          if (!sameTarget(control.target, (yield* target(decoded.target)).target))
+            return yield* fail("stale-reference");
+          const expires = now + 60_000;
+          const result: Array<CredentialOffer> = [];
+          const pending: typeof offers = new Map();
+
+          for (const candidate of candidates) {
+            const metadata = yield* decode(CredentialOfferMetadata, candidate.metadata);
+
+            const ref = yield* crypto.randomUUIDv4.pipe(Effect.mapError(() => fail("provider")));
+
+            pending.set(ref, {
+              caller: principal,
+              key: candidate.key,
+              target: control.target,
+              targetRef: decoded.target,
+              kind: decoded.kind,
+              expires,
+            });
+            result.push(CredentialOffer.make({ ref, kind: decoded.kind, metadata }));
           }
+          yield* bounded(result);
+          for (const [ref, offer] of pending) offers.set(ref, offer);
+
+          return result;
+        }),
+      ),
+    useCredential: (request) =>
+      run(
+        Effect.gen(function* () {
+          const decoded = yield* Schema.decodeEffect(UseCredential)(request).pipe(
+            Effect.mapError(() => fail("denied")),
+          );
+
+          const offer = offers.get(decoded.offer);
+
+          if (offer === undefined || offer.expires <= (yield* Clock.currentTimeMillis))
+            return yield* fail("stale-reference");
           const principal = yield* caller;
 
-          yield* access
-            .authorizeAction({ caller: principal, action, exposures: [...exposures] })
-            .pipe(Effect.mapError((error) => fail(error.reason)));
-          if (Redacted.value(yield* caller) !== Redacted.value(principal))
+          if (Redacted.value(principal) !== Redacted.value(offer.caller))
+            return yield* fail("denied");
+          if (
+            new Set(decoded.fields.map((field) => field.ref)).size !== decoded.fields.length ||
+            new Set(decoded.fields.map((field) => field.role)).size !== decoded.fields.length
+          )
             return yield* fail("denied");
-          if (action._tag !== "Navigate") {
-            const current = yield* target(action.ref);
-
-            if (
-              !sameTarget(current.target, action.target) ||
-              current.role !== (action._tag === "Submit" ? "submit" : action.role) ||
-              (action._tag === "Click" && action.role === "link" && current.url !== action.url)
-            )
-              return yield* fail("stale-reference");
-          }
-        }, Effect.withTracerEnabled(false));
-
-        const bounded = <A>(result: A) => {
-          const bytes = new TextEncoder().encode(JSON.stringify(result)).byteLength;
-
-          return bytes <= policy.maxReturnedBytes
-            ? Effect.succeed(result)
-            : Effect.fail(fail("limit"));
-        };
-
-        const run = <A>(effect: Effect.Effect<A, ProtectedBrowserError>) =>
-          lock
-            .withPermitsIfAvailable(1)(
-              Effect.gen(function* () {
-                dispatch = "not-dispatched";
-                milestone = "none";
-                if (observation === "closed") return yield* fail("closed");
-                if (++actions > policy.maxActions) return yield* fail("limit");
-
-                const remaining =
-                  policy.maxElapsedMillis - ((yield* Clock.currentTimeMillis) - started);
-
-                if (remaining <= 0) {
-                  yield* close;
-
-                  return yield* fail("timeout");
-                }
-
-                return yield* effect.pipe(
-                  Effect.timeoutOrElse({
-                    duration: remaining,
-                    orElse: () => Effect.fail(fail("timeout")),
-                  }),
-                  Effect.catchCause((cause) =>
-                    Effect.gen(function* () {
-                      // No foreign exception or defect is retained. Interrupted operations still finalize.
-                      const error = cause.reasons.find(
-                        (reason) =>
-                          reason._tag === "Fail" && Schema.is(ProtectedBrowserError)(reason.error),
-                      );
-
-                      const reason =
-                        error?._tag === "Fail" && Schema.is(ProtectedBrowserError)(error.error)
-                          ? error.error.reason
-                          : "provider";
-
-                      const interrupt = cause.reasons.some((reason) => reason._tag === "Interrupt");
-
-                      if (
-                        dispatch !== "not-dispatched" ||
-                        interrupt ||
-                        reason === "provider" ||
-                        reason === "timeout"
-                      )
-                        yield* close;
-                      if (interrupt) return yield* Effect.interrupt;
-
-                      return yield* fail(
-                        dispatch === "possibly-dispatched" && reason === "provider"
-                          ? "outcome-unknown"
-                          : reason,
-                      );
-                    }),
-                  ),
-                  Effect.onInterrupt(() => close),
-                  Effect.withTracerEnabled(false),
-                );
-              }),
-            )
-            .pipe(
-              Effect.flatMap(
-                Effect.fromOption(
-                  () =>
-                    new ProtectedBrowserError({
-                      reason: "busy",
-                      dispatch: "not-dispatched",
-                      milestone: "none",
-                      observation,
-                      cleanup,
-                    }),
-                ),
-              ),
-            );
-
-        return {
-          close,
-          navigate: (request) =>
-            run(
-              Effect.gen(function* () {
-                const decoded = yield* Schema.decodeEffect(ProtectedBrowserNavigate)(request).pipe(
-                  Effect.mapError(() => fail("denied")),
-                );
-
-                let url: URL;
 
-                try {
-                  url = new URL(decoded.url);
-                } catch {
-                  return yield* fail("denied");
-                }
-                if (
-                  url.protocol !== "https:" ||
-                  url.username ||
-                  url.password ||
-                  (policy.network._tag === "ExactHosts" &&
-                    !policy.network.allowedHosts.includes(url.host))
-                )
-                  return yield* fail("denied");
-                if (exposures.length > 0) yield* permitObservation;
-                yield* authorizeAction({ _tag: "Navigate", url: decoded.url });
-                offers.clear();
-                dispatch = "possibly-dispatched";
-                yield* remote(driver.navigate(decoded.url));
-                dispatch = "dispatched";
-                yield* permitObservation;
-              }),
-            ),
-          observe: run(
-            Effect.gen(function* () {
-              const before = yield* permitObservation;
-              const result = yield* remote(driver.discover);
-              const after = yield* permitObservation;
+          const validate = Effect.gen(function* () {
+            if (!sameTarget(offer.target, (yield* target(offer.targetRef)).target))
+              return yield* fail("stale-reference");
+            for (const field of decoded.fields) {
+              const current = yield* target(field.ref);
 
               if (
-                before.document !== after.document ||
-                result.document !== after.document ||
-                result.topOrigin !== after.topOrigin
+                field.role !== current.role ||
+                kindFor(field.role) !== offer.kind ||
+                !sameTarget(offer.target, current.target)
               )
-                return yield* fail("stale-reference");
-              if (result.frameOrigins.some((origin) => !after.frameOrigins.includes(origin)))
-                return yield* fail("observation-blocked");
-
-              return yield* bounded(
-                ProtectedBrowserObservation.make({
-                  ...result,
-                  observation: exposures.length > 0 ? "approved-after-exposure" : "before-exposure",
-                }),
-              );
-            }),
-          ),
-          click: (request) =>
-            run(
-              Effect.gen(function* () {
-                const decoded = yield* Schema.decodeEffect(ProtectedBrowserClick)(request).pipe(
-                  Effect.mapError(() => fail("denied")),
-                );
+                return yield* fail("denied");
+            }
+            if (decoded.submit !== undefined) {
+              const submit = yield* target(decoded.submit);
 
-                yield* permitObservation;
-                const control = yield* target(decoded.ref);
+              if (submit.role !== "submit" || !sameTarget(offer.target, submit.target))
+                return yield* fail("denied");
+            }
+          });
 
-                if (
-                  control.role !== "link" &&
-                  control.role !== "button" &&
-                  control.role !== "radio" &&
-                  control.role !== "checkbox" &&
-                  control.role !== "submit"
-                )
-                  return yield* fail("unsupported");
-                let action: ProtectedBrowserAction;
-
-                if (control.role === "link") {
-                  if (control.url === undefined) return yield* fail("unsupported");
-                  action = {
-                    _tag: "Click",
-                    ref: decoded.ref,
-                    target: control.target,
-                    role: "link",
-                    url: control.url,
-                  };
-                } else if (control.role === "submit") {
-                  action = { _tag: "Submit", ref: decoded.ref, target: control.target };
-                } else {
-                  action = {
-                    _tag: "Click",
-                    ref: decoded.ref,
-                    target: control.target,
-                    role: control.role,
-                  };
-                }
-                yield* authorizeAction(action);
-                dispatch = "possibly-dispatched";
-                yield* remote(driver.click(decoded.ref)).pipe(
-                  Effect.catch((error) => {
-                    if (error.reason === "needs-attention") dispatch = "not-dispatched";
+          yield* validate;
 
-                    return Effect.fail(error);
-                  }),
-                );
-                dispatch = "dispatched";
-                if (control.role === "submit") milestone = "submission-dispatched";
-                yield* permitObservation;
-              }),
-            ),
-          fill: (request) =>
-            run(
-              Effect.gen(function* () {
-                const decoded = yield* Schema.decodeEffect(ProtectedBrowserFill)(request).pipe(
-                  Effect.mapError(() => fail("denied")),
-                );
+          const authorization: CredentialUseAuthorization = {
+            caller: principal,
+            key: offer.key,
+            kind: offer.kind,
+            target: offer.target,
+            roles: decoded.fields.map((field) => field.role),
+            submit: decoded.submit !== undefined,
+          };
 
-                yield* permitObservation;
-                const control = yield* target(decoded.ref);
-
-                if (control.role !== "text" && control.role !== "select")
-                  return yield* fail("unsupported");
-                yield* authorizeAction({
-                  _tag: "Fill",
-                  ref: decoded.ref,
-                  target: control.target,
-                  role: control.role,
-                });
-                yield* remote(
-                  driver.fill(decoded.ref, control.role, Redacted.make(decoded.value)),
-                ).pipe(
-                  Effect.provideService(ProtectedBrowserDispatch, {
-                    mark: Effect.sync(() => {
-                      dispatch = "possibly-dispatched";
-                    }),
-                  }),
-                );
-                dispatch = "dispatched";
-                milestone = "filled";
-                yield* permitObservation;
-              }),
-            ),
-          listCredentialOffers: (request) =>
-            run(
-              Effect.gen(function* () {
-                const decoded = yield* Schema.decodeEffect(ListCredentialOffers)(request).pipe(
-                  Effect.mapError(() => fail("denied")),
-                );
+          const authorize = Effect.gen(function* () {
+            if (Redacted.value(yield* caller) !== Redacted.value(principal))
+              return yield* fail("denied");
+            yield* access
+              .authorize(authorization)
+              .pipe(Effect.mapError((error) => fail(error.reason)));
+            if (Redacted.value(yield* caller) !== Redacted.value(principal))
+              return yield* fail("denied");
+          });
 
-                yield* permitObservation;
-                const control = yield* target(decoded.target);
-
-                if (kindFor(control.role) !== decoded.kind) return yield* fail("unsupported");
-                const principal = yield* caller;
-
-                const candidates = yield* access
-                  .list({ caller: principal, kind: decoded.kind, target: control.target })
-                  .pipe(Effect.mapError((error) => fail(error.reason)));
-
-                const now = yield* Clock.currentTimeMillis;
-
-                for (const [ref, offer] of offers) if (offer.expires <= now) offers.delete(ref);
-                if (candidates.length > 16 || offers.size + candidates.length > 64)
-                  return yield* fail("limit");
-                if (!sameTarget(control.target, (yield* target(decoded.target)).target))
-                  return yield* fail("stale-reference");
-                const expires = now + 60_000;
-                const result: Array<CredentialOffer> = [];
-                const pending: typeof offers = new Map();
-
-                for (const candidate of candidates) {
-                  const metadata = yield* decode(CredentialOfferMetadata, candidate.metadata);
-
-                  const ref = yield* crypto.randomUUIDv4.pipe(
-                    Effect.mapError(() => fail("provider")),
-                  );
-
-                  pending.set(ref, {
-                    caller: principal,
-                    key: candidate.key,
-                    target: control.target,
-                    targetRef: decoded.target,
-                    kind: decoded.kind,
-                    expires,
-                  });
-                  result.push(CredentialOffer.make({ ref, kind: decoded.kind, metadata }));
-                }
-                yield* bounded(result);
-                for (const [ref, offer] of pending) offers.set(ref, offer);
-
-                return result;
-              }),
-            ),
-          useCredential: (request) =>
-            run(
-              Effect.gen(function* () {
-                const decoded = yield* Schema.decodeEffect(UseCredential)(request).pipe(
-                  Effect.mapError(() => fail("denied")),
-                );
+          yield* authorize;
+          yield* validate;
 
-                const offer = offers.get(decoded.offer);
+          const raw = yield* access
+            .resolve(authorization)
+            .pipe(Effect.mapError((error) => fail(error.reason)));
 
-                if (offer === undefined || offer.expires <= (yield* Clock.currentTimeMillis))
-                  return yield* fail("stale-reference");
-                const principal = yield* caller;
+          const material = yield* Schema.decodeEffect(
+            offer.kind === "login" ? LoginCredential : CardCredential,
+          )(raw).pipe(Effect.mapError(() => fail("resolver")));
 
-                if (Redacted.value(principal) !== Redacted.value(offer.caller))
-                  return yield* fail("denied");
-                if (
-                  new Set(decoded.fields.map((field) => field.ref)).size !==
-                    decoded.fields.length ||
-                  new Set(decoded.fields.map((field) => field.role)).size !== decoded.fields.length
-                )
-                  return yield* fail("denied");
-
-                const validate = Effect.gen(function* () {
-                  if (!sameTarget(offer.target, (yield* target(offer.targetRef)).target))
-                    return yield* fail("stale-reference");
-                  for (const field of decoded.fields) {
-                    const current = yield* target(field.ref);
-
-                    if (
-                      field.role !== current.role ||
-                      kindFor(field.role) !== offer.kind ||
-                      !sameTarget(offer.target, current.target)
-                    )
-                      return yield* fail("denied");
-                  }
-                  if (decoded.submit !== undefined) {
-                    const submit = yield* target(decoded.submit);
-
-                    if (submit.role !== "submit" || !sameTarget(offer.target, submit.target))
-                      return yield* fail("denied");
-                  }
-                });
-
-                yield* validate;
-
-                const authorization: CredentialUseAuthorization = {
-                  caller: principal,
-                  key: offer.key,
-                  kind: offer.kind,
-                  target: offer.target,
-                  roles: decoded.fields.map((field) => field.role),
-                  submit: decoded.submit !== undefined,
-                };
-
-                const authorize = Effect.gen(function* () {
-                  if (Redacted.value(yield* caller) !== Redacted.value(principal))
-                    return yield* fail("denied");
-                  yield* access
-                    .authorize(authorization)
-                    .pipe(Effect.mapError((error) => fail(error.reason)));
-                  if (Redacted.value(yield* caller) !== Redacted.value(principal))
-                    return yield* fail("denied");
-                });
-
-                yield* authorize;
-                yield* validate;
-
-                const raw = yield* access
-                  .resolve(authorization)
-                  .pipe(Effect.mapError((error) => fail(error.reason)));
-
-                const material = yield* Schema.decodeEffect(
-                  offer.kind === "login" ? LoginCredential : CardCredential,
-                )(raw).pipe(Effect.mapError(() => fail("resolver")));
-
-                for (const field of decoded.fields)
-                  if (secretFor(material, field.role) === undefined)
-                    return yield* fail("missing-credential");
-                offers.delete(decoded.offer);
-                for (const field of decoded.fields) {
-                  yield* validate;
-                  yield* authorize;
-                  const value = secretFor(material, field.role);
-
-                  if (value === undefined) return yield* fail("missing-credential");
-                  observation = "protected";
-                  yield* remote(driver.fill(field.ref, field.role, value)).pipe(
-                    Effect.provideService(ProtectedBrowserDispatch, {
-                      mark: Effect.sync(() => {
-                        dispatch = "possibly-dispatched";
-                        if (!exposures.some((target) => sameTarget(target, offer.target)))
-                          exposures.push(offer.target);
-                      }),
-                    }),
-                  );
-                  dispatch = "dispatched";
-                  milestone = "partial-fill";
-                }
-                milestone = "filled";
-                if (decoded.submit !== undefined) {
-                  yield* validate;
-                  yield* authorize;
-                  const ref = decoded.submit;
+          for (const field of decoded.fields)
+            if (secretFor(material, field.role) === undefined)
+              return yield* fail("missing-credential");
+          offers.delete(decoded.offer);
+          for (const field of decoded.fields) {
+            yield* validate;
+            yield* authorize;
+            const value = secretFor(material, field.role);
 
+            if (value === undefined) return yield* fail("missing-credential");
+            observation = "protected";
+            yield* remote(driver.fill(field.ref, field.role, value)).pipe(
+              Effect.provideService(ProtectedBrowserDispatch, {
+                mark: Effect.sync(() => {
                   dispatch = "possibly-dispatched";
-                  yield* remote(driver.click(ref)).pipe(
-                    Effect.catch((error) => {
-                      if (error.reason === "needs-attention") dispatch = "dispatched";
-
-                      return Effect.fail(error);
-                    }),
-                  );
-                  dispatch = "dispatched";
-                  milestone = "submission-dispatched";
-                }
-                yield* permitObservation;
-
-                return CredentialUseResult.make({
-                  dispatch,
-                  milestone,
-                  observation,
-                  cleanup,
-                  authentication: "unverified",
-                });
+                  if (!exposures.some((target) => sameTarget(target, offer.target)))
+                    exposures.push(offer.target);
+                }),
               }),
-            ),
-        };
-      }, Effect.withTracerEnabled(false));
+            );
+            dispatch = "dispatched";
+            milestone = "partial-fill";
+          }
+          milestone = "filled";
+          if (decoded.submit !== undefined) {
+            yield* validate;
+            yield* authorize;
+            const ref = decoded.submit;
+
+            dispatch = "possibly-dispatched";
+            yield* remote(driver.click(ref)).pipe(
+              Effect.catch((error) => {
+                if (error.reason === "needs-attention") dispatch = "dispatched";
+
+                return Effect.fail(error);
+              }),
+            );
+            dispatch = "dispatched";
+            milestone = "submission-dispatched";
+          }
+          yield* permitObservation;
+
+          return CredentialUseResult.make({
+            dispatch,
+            milestone,
+            observation,
+            cleanup,
+            authentication: "unverified",
+          });
+        }),
+      ),
+  };
+
+  const locked = <A>(effect: Effect.Effect<A, ProtectedBrowserError>) =>
+    lock
+      .withPermitsIfAvailable(1)(effect)
+      .pipe(Effect.flatMap(Effect.fromOption(() => fail("busy"))));
+
+  return {
+    handle,
+    suspend: (human = false) =>
+      locked(
+        Effect.gen(function* () {
+          if (detached || observation === "closed") return yield* fail("closed");
+          if (dispatch === "possibly-dispatched") return yield* fail("outcome-unknown");
+          if ((yield* Clock.currentTimeMillis) - started >= policy.maxElapsedMillis)
+            return yield* fail("timeout");
+          suspended = true;
+          if (human) {
+            const context = yield* pageContext;
+
+            const origins = yield* Schema.decodeEffect(
+              ProtectedBrowserCheckpoint.fields.humanOrigins,
+            )([...new Set([...humanOrigins, context.topOrigin, ...context.frameOrigins])]).pipe(
+              Effect.catch(() => fail("needs-attention")),
+            );
+
+            humanExposure = true;
+            humanOrigins = [...origins];
+            observation = "protected";
+          }
+          driver.resetReferences();
+          offers.clear();
+
+          return ProtectedBrowserCheckpoint.make({
+            policy,
+            startedAt: started,
+            actions,
+            exposures: [...exposures],
+            humanExposure,
+            humanOrigins,
+            dispatch,
+            milestone,
+          });
+        }),
+      ),
+    returnControl: locked(
+      Effect.gen(function* () {
+        if (detached || observation === "closed") return yield* fail("closed");
+        if (!suspended) return yield* fail("denied");
+        yield* permitObservation;
+        offers.clear();
+        driver.resetReferences();
+        needsObservation = true;
+        suspended = false;
+      }),
+    ),
+    detach: locked(
+      Effect.gen(function* () {
+        if (!suspended || observation === "closed") return yield* fail("denied");
+        if (driver.detach === undefined) return yield* fail("unsupported");
+        yield* driver.detach.pipe(
+          Effect.onError(() => close),
+          Effect.onInterrupt(() => close),
+        );
+        detached = true;
+        offers.clear();
+        driver.invalidate();
+      }),
+    ),
+  };
+}, Effect.withTracerEnabled(false));
+
+/** Fresh private passes; scoped release confirms exact-session termination. */
+export const browserRunProtectedLayer = () =>
+  Layer.effect(ProtectedBrowser)(
+    Effect.gen(function* () {
+      const transport = yield* BrowserRunProtectedTransport;
+      const crypto = yield* Crypto.Crypto;
 
-      return { open };
+      return {
+        open: (policy: InteractiveBrowserPolicy) =>
+          makeProtectedBrowserPolicy(policy).pipe(
+            Effect.map((session) => session.handle),
+            Effect.provideService(BrowserRunProtectedTransport, transport),
+            Effect.provideService(Crypto.Crypto, crypto),
+          ),
+      };
     }),
   );