browxai 0.7.0

package/dist/session/permission.d.ts

@@ -0,0 +1,144 @@
+import type { BrowserContext, Page } from "playwright-core";
+export type PolicyMode = "allow" | "deny" | "raise" | "ask-human";
+/** Canonical name set for v1. Aligned with Playwright/Chromium permission names.
+ *  USB/Bluetooth/HID are deliberately NOT in v1 ('s `device-emulation`).
+ *  Re-exported in `permission_state` tool docs + tool-reference.md. */
+export declare const SUPPORTED_PERMISSIONS: readonly ["camera", "microphone", "geolocation", "notifications", "clipboard-read", "clipboard-write", "midi", "midi-sysex", "payment-handler", "background-sync", "accelerometer", "gyroscope", "magnetometer"];
+export type SupportedPermission = (typeof SUPPORTED_PERMISSIONS)[number];
+/** Public, runtime-mutable shape. Top-level `mode` is the default; the
+ *  per-permission override map wins when present. */
+export interface PermissionPolicy {
+    mode: PolicyMode;
+    perPermission?: Partial<Record<SupportedPermission, PolicyMode>>;
+}
+/** One captured permission request, exposed on `ActionResult.permissionRequests[]`. */
+export interface PermissionRecord {
+    permission: SupportedPermission;
+    /** origin of the page that made the request; undefined when not parseable. */
+    origin?: string;
+    /** What the server actually did. `"raised"` means the wrapper rejected
+     *  AND the policy was `raise`, so the action will be marked failed. */
+    handledAs: "allowed" | "denied" | "raised" | "asked-human";
+    /** epoch ms — used by the action-window slice. */
+    ts: number;
+}
+/** Hint emitted on `ActionResult.failure.hint` when `raise` mode fired.
+ *  Stable, agent-facing string — referenced in docs/tool-reference.md. */
+export declare const UNHANDLED_PERMISSION_HINT: string;
+/** BYOB warning surfaced when policy is set on `attached` sessions. CDP
+ *  `Browser.setPermission` mutates the human's Chrome and is not cleanly
+ *  revertable on detach — same posture class as the BYOB emulation warning. */
+export declare const BYOB_PERMISSION_WARNING: string;
+/** Mutable per-session state. The page-side check binding reads `current(name)`
+ *  on every request, so a `set_permission_policy` call takes effect on the
+ *  very next request without page reload. */
+export declare class PermissionPolicyState {
+    private policy;
+    /** Bounded record ring (shared `PolicyRecordBuffer` — the hard cap so a chatty
+     *  page can't grow this without bound; the per-action slice is the only
+     *  consumer, older records are noise). */
+    private readonly records;
+    /** Contexts we've already installed the init-script + binding on. Idempotent
+     *  install guard — BYOB reconnect / context rebuild MUST not double-wire. */
+    private wired;
+    constructor(initial?: PermissionPolicy, cap?: number);
+    /** Resolved policy snapshot. */
+    current(): PermissionPolicy;
+    /** Effective mode for a single permission — per-permission map wins, else
+     *  top-level. Unknown permissions fall through to top-level (we still want
+     *  a deterministic answer for whatever the page asked for). */
+    modeFor(name: string): PolicyMode;
+    set(next: PermissionPolicy): PermissionPolicy;
+    /** Append a request record. Caps the buffer at `cap`. */
+    record(rec: PermissionRecord): void;
+    /** Slice records with `ts >= since`. Used by the action-window. */
+    since(since: number): PermissionRecord[];
+    /** True if any record in `[since, now]` was handled in `raise` mode.
+     *  When true, the action-window flips the result to `ok:false`. */
+    raisedSince(since: number): boolean;
+    /** Has this context already been wired? Idempotent install guard. */
+    hasContext(c: BrowserContext): boolean;
+    /** Mark a context as wired. */
+    markContext(c: BrowserContext): void;
+}
+/** Parse the spec's compact string form for the top-level mode, or accept the
+ *  object form. Idempotent. */
+export declare function parsePermissionPolicyArg(v: string | PermissionPolicy | undefined): PermissionPolicy;
+/** Map a canonical permission name to the CDP `Browser.setPermission`
+ *  descriptor name. */
+export declare function cdpPermissionName(p: SupportedPermission): string;
+/** Compute the CDP setting (granted/denied) for a permission given the active
+ *  policy. `raise` / `deny` → "denied"; `allow` → "granted"; `ask-human` →
+ *  "prompt" (CDP returns to the page-script wrapper which then asks the human).
+ *
+ *  Kept as a pure function so registry.test.ts can assert the mapping without
+ *  launching Chromium. */
+export declare function cdpSettingFor(mode: PolicyMode): "granted" | "denied" | "prompt";
+/** Bridge callback type. The server-side binding wires this to await-human
+ *  (when the policy is `ask-human`); the page-side wrapper script consults it
+ *  before deciding whether to call through. Returns the decision the wrapper
+ *  should enact: `"allow"` calls through, `"deny"` throws NotAllowedError. */
+export type PermissionAskHandler = (permission: SupportedPermission, origin: string | undefined) => Promise<"allow" | "deny">;
+/** Init script that wraps the page-side permission APIs. Stringified so it can
+ *  be passed to `addInitScript` and `page.evaluate`. Keep browser-only JS — no
+ *  TS-only syntax. Re-injected on `framenavigated` (idempotent: guards on
+ *  `window.__browx_permission_installed`).
+ *
+ *  The wrappers consult `window.__browx_permission_check({permission, origin})`
+ *  (an exposeBinding callable from page context) — it returns `"allow" |
+ *  "deny"`. The server's binding implementation records the request + (for
+ *  `ask-human`) blocks on the bridge before answering. */
+export declare const PERMISSION_PAGE_SCRIPT = "(() => {\n  if (window.__browx_permission_installed) return;\n  window.__browx_permission_installed = true;\n  // Detect whether the exposeBinding is available. If not (BYOB multi-attach\n  // clobber, or the binding install failed), the wrappers fall back to\n  // call-through \u2014 the CDP setPermission baseline still enforces grant/deny.\n  function check(permission) {\n    try {\n      if (typeof window.__browx_permission_check === \"function\") {\n        return Promise.resolve(window.__browx_permission_check(JSON.stringify({\n          permission: permission, origin: location.origin,\n        })));\n      }\n    } catch (_) {}\n    return Promise.resolve(\"allow\");\n  }\n  function notAllowed(msg) {\n    var e = new Error(msg || \"permission denied by browxai permissionPolicy\");\n    try { e.name = \"NotAllowedError\"; } catch (_) {}\n    return e;\n  }\n\n  // --- navigator.mediaDevices.getUserMedia (camera + microphone) ---\n  try {\n    var md = navigator.mediaDevices;\n    if (md && typeof md.getUserMedia === \"function\") {\n      var origGUM = md.getUserMedia.bind(md);\n      md.getUserMedia = function (constraints) {\n        var wantsVideo = !!(constraints && constraints.video);\n        var wantsAudio = !!(constraints && constraints.audio);\n        var perm = wantsVideo ? \"camera\" : (wantsAudio ? \"microphone\" : \"camera\");\n        return check(perm).then(function (decision) {\n          if (decision === \"deny\") return Promise.reject(notAllowed(\"Permission denied\"));\n          return origGUM(constraints);\n        });\n      };\n    }\n  } catch (_) {}\n\n  // --- navigator.geolocation (getCurrentPosition + watchPosition) ---\n  // watchPosition is long-lived (the callback may fire many times) \u2014 we gate\n  // the *initial* permission check at watch-installation time, then if allowed\n  // pass through to the native API which itself manages the callback stream.\n  try {\n    var geo = navigator.geolocation;\n    if (geo && typeof geo.getCurrentPosition === \"function\") {\n      var origGet = geo.getCurrentPosition.bind(geo);\n      geo.getCurrentPosition = function (success, error, options) {\n        check(\"geolocation\").then(function (decision) {\n          if (decision === \"deny\") {\n            if (typeof error === \"function\") {\n              try { error({ code: 1, message: \"User denied geolocation\", PERMISSION_DENIED: 1, POSITION_UNAVAILABLE: 2, TIMEOUT: 3 }); } catch (_) {}\n            }\n            return;\n          }\n          try { origGet(success, error, options); } catch (e) {\n            if (typeof error === \"function\") { try { error(e); } catch (_) {} }\n          }\n        });\n      };\n    }\n    if (geo && typeof geo.watchPosition === \"function\") {\n      var origWatch = geo.watchPosition.bind(geo);\n      // Return a synthetic watch id when denied so callers calling\n      // clearWatch(id) still see a valid (no-op) integer. Native ids are\n      // small positive integers; we use negatives starting at -1 to avoid\n      // colliding with any in-flight native watch.\n      var synthCounter = 0;\n      geo.watchPosition = function (success, error, options) {\n        var pending = true;\n        var synthId = --synthCounter;\n        check(\"geolocation\").then(function (decision) {\n          pending = false;\n          if (decision === \"deny\") {\n            if (typeof error === \"function\") {\n              try { error({ code: 1, message: \"User denied geolocation\", PERMISSION_DENIED: 1, POSITION_UNAVAILABLE: 2, TIMEOUT: 3 }); } catch (_) {}\n            }\n            return;\n          }\n          // Allowed \u2014 install the native watch. We've already returned the\n          // synthetic id to the caller; the native id is held internally and\n          // proxied through clearWatch below.\n          try {\n            var nativeId = origWatch(success, error, options);\n            geo.__browx_watch_map = geo.__browx_watch_map || {};\n            geo.__browx_watch_map[synthId] = nativeId;\n          } catch (e) {\n            if (typeof error === \"function\") { try { error(e); } catch (_) {} }\n          }\n        });\n        return synthId;\n      };\n      var origClear = typeof geo.clearWatch === \"function\" ? geo.clearWatch.bind(geo) : null;\n      if (origClear) {\n        geo.clearWatch = function (id) {\n          var map = geo.__browx_watch_map || {};\n          if (id in map) {\n            try { origClear(map[id]); } catch (_) {}\n            delete map[id];\n            return;\n          }\n          try { origClear(id); } catch (_) {}\n        };\n      }\n    }\n  } catch (_) {}\n\n  // --- Notification.requestPermission ---\n  try {\n    if (typeof Notification !== \"undefined\" && typeof Notification.requestPermission === \"function\") {\n      var origReq = Notification.requestPermission.bind(Notification);\n      Notification.requestPermission = function (cb) {\n        return check(\"notifications\").then(function (decision) {\n          var result = decision === \"deny\" ? \"denied\" : \"granted\";\n          if (decision === \"deny\") {\n            try { Object.defineProperty(Notification, \"permission\", { get: function () { return \"denied\"; }, configurable: true }); } catch (_) {}\n            if (typeof cb === \"function\") { try { cb(result); } catch (_) {} }\n            return result;\n          }\n          // Allowed \u2014 delegate to native; the CDP setPermission baseline has\n          // already pre-granted, so the native call resolves immediately.\n          try {\n            var r = origReq(cb);\n            return r && typeof r.then === \"function\" ? r : Promise.resolve(result);\n          } catch (_) {\n            return result;\n          }\n        });\n      };\n    }\n  } catch (_) {}\n\n  // --- navigator.clipboard (read / write / readText / writeText) ---\n  try {\n    var clip = navigator.clipboard;\n    if (clip) {\n      var wrap = function (name, perm) {\n        var orig = typeof clip[name] === \"function\" ? clip[name].bind(clip) : null;\n        if (!orig) return;\n        clip[name] = function () {\n          var args = arguments;\n          return check(perm).then(function (decision) {\n            if (decision === \"deny\") return Promise.reject(notAllowed(\"Clipboard \" + name + \" denied\"));\n            return orig.apply(null, args);\n          });\n        };\n      };\n      wrap(\"read\", \"clipboard-read\");\n      wrap(\"readText\", \"clipboard-read\");\n      wrap(\"write\", \"clipboard-write\");\n      wrap(\"writeText\", \"clipboard-write\");\n    }\n  } catch (_) {}\n\n  // --- navigator.permissions.query \u2014 read-side. Force the wrapper's view of\n  // state through us so a query() honoured a \"raise\" policy returns \"denied\"\n  // (matching the wrapper rejection) and a \"ask-human\" returns \"prompt\" (the\n  // native query would otherwise see the CDP \"prompt\" setting and skip our\n  // recording). Falls back to native when the queried name isn't one we govern.\n  try {\n    var permsApi = navigator.permissions;\n    if (permsApi && typeof permsApi.query === \"function\") {\n      var origQuery = permsApi.query.bind(permsApi);\n      permsApi.query = function (desc) {\n        var name = desc && desc.name;\n        // pass through to native \u2014 we don't override the query result, just\n        // record that the page asked, so the next ActionResult shows it. The\n        // native value still reflects the CDP-set state (granted/denied/prompt).\n        if (typeof window.__browx_permission_observe === \"function\") {\n          try { window.__browx_permission_observe(JSON.stringify({ permission: name, origin: location.origin })); } catch (_) {}\n        }\n        return origQuery(desc);\n      };\n    }\n  } catch (_) {}\n})();";
+/** Server-side wire-up. Installs:
+ *   - `__browx_permission_check` exposeBinding: synchronous-from-page consult
+ *     that records the request, runs the ask-human handler if the policy is
+ *     `ask-human`, and returns the resolved decision (`"allow"` / `"deny"`).
+ *   - `__browx_permission_observe` exposeBinding: read-side notice that the
+ *     page called `navigator.permissions.query` (no decision returned).
+ *   - The page-side init script (see above), re-injected by Playwright on
+ *     every new document via `addInitScript`.
+ *
+ * Idempotent on the same context (the state's `WeakSet<BrowserContext>` guard).
+ * Errors during install are logged and swallowed — the CDP setPermission baseline
+ * still enforces grant/deny even when the in-page wrappers fail to wire.
+ */
+export declare function attachPermissionPolicy(context: BrowserContext, state: PermissionPolicyState, askHandler: PermissionAskHandler): Promise<void>;
+/** Apply the policy's baseline by computing the set of permissions that should
+ *  be GRANTED (mode `allow`) and routing them through Playwright's
+ *  `context.grantPermissions`. Permissions in `deny`/`raise`/`ask-human` are
+ *  NOT granted — the in-page wrapper rejects them at request time before the
+ *  native code runs.
+ *
+ *  Why not CDP `Browser.setPermission` directly: the underlying CDP method
+ *  takes a W3C PermissionDescriptor name (e.g. `geolocation`, `camera`) and
+ *  the descriptor schema varies by Chromium build. Playwright's
+ *  `grantPermissions` carries the canonical mapping (see Playwright's
+ *  `webPermissionToProtocol`) and falls back across Chromium versions —
+ *  delegating means we don't have to track the protocol versions ourselves.
+ *
+ *  Note: `clearPermissions` first then `grantPermissions` is the Playwright
+ *  idiom for "REPLACE the granted set" (the underlying CDP call is
+ *  `Browser.resetPermissions` + `Browser.grantPermissions`). Both are
+ *  context-wide on Chromium so the policy applies to every page.
+ *
+ *  Best-effort: errors are logged and don't throw — the in-page wrapper still
+ *  enforces grant/deny even if the baseline application fails. Re-applied on
+ *  `set_permission_policy` and re-attach paths. */
+export declare function applyCdpBaseline(context: BrowserContext, state: PermissionPolicyState): Promise<void>;
+/** Read-side via the page's native `navigator.permissions.query` (W3C
+ *  Permissions API). Returns `{ [name]: "granted"|"denied"|"prompt"|"unknown" }`.
+ *  Per-permission errors populate the entry with `"unknown"` so the caller
+ *  sees a deterministic shape.
+ *
+ *  Why the Permissions API and not CDP `Browser.getPermissionState`: the CDP
+ *  method's PermissionDescriptor schema varies across Chromium builds and
+ *  several of our supported names (e.g. `clipboard-write` → `clipboardSan…`)
+ *  don't map cleanly. The Permissions API takes the canonical web spec name
+ *  directly and is supported across versions. The state it reports reflects
+ *  whatever the CDP-level baseline set, so it's the right read-side mirror
+ *  for `applyCdpBaseline`.
+ *
+ *  Note: the in-page wrapper script is a no-op for query() (passes through);
+ *  it doesn't override the resulting state, so this read is the canonical
+ *  browser-reported state, not a wrapper-side guess. */
+export declare function readPermissionStates(context: BrowserContext, page: Page, names: SupportedPermission[], origin?: string): Promise<Record<string, "granted" | "denied" | "prompt" | "unknown">>;