@velmlabs/unstuck-core 0.1.4 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -2,7 +2,7 @@ import { C as CdpClient, P as PopupSource, L as LinkInfo, T as Transport } from
2
2
  export { V as ViewerConnection } from './takeover-Df0pBZ0z.js';
3
3
  import { TakeoverResult, Frame, ViewerInput, SessionStatus } from '@velmlabs/unstuck-protocol';
4
4
 
5
- type UnstuckEventType = 'created' | 'published' | 'link' | 'viewer_joined' | 'viewer_left' | 'viewer_rejected' | 'status' | 'finished';
5
+ type UnstuckEventType = 'created' | 'published' | 'link' | 'viewer_joined' | 'viewer_left' | 'viewer_rejected' | 'status' | 'finished' | 'navigation_blocked';
6
6
  /** Structured audit event. Never contains screenshots, typed text or secrets: only counts and states. */
7
7
  interface UnstuckEvent {
8
8
  ts: number;
@@ -38,6 +38,8 @@ interface TakeoverCallOptions {
38
38
  onLink?: LinkHandler;
39
39
  /** Ask the human for a 6-digit code delivered with the link. */
40
40
  requireCode?: boolean;
41
+ /** Sites besides the page's own the human may navigate to (e.g. an SSO or 3-D Secure provider). */
42
+ allowedSites?: string[];
41
43
  }
42
44
  interface Engine {
43
45
  /** Never rejects: every failure becomes a TakeoverResult. */
@@ -127,6 +129,11 @@ interface RelayTransportOptions {
127
129
  /** wss://host (or ws:// for local testing). */
128
130
  url: string;
129
131
  agentKey?: string;
132
+ /**
133
+ * A viewer served from its own origin (e.g. https://view.unstuck.sh/v/<version>): links open it instead of the
134
+ * relay's page and name the relay in ?r=, so whoever runs the relay can't change the code that holds the key.
135
+ */
136
+ viewerUrl?: string;
130
137
  WebSocketImpl?: typeof WebSocket;
131
138
  connectTimeoutMs?: number;
132
139
  }
@@ -135,5 +142,20 @@ declare function createRelayTransport(opts: RelayTransportOptions): Transport &
135
142
  onStatus(id: string, h: (s: 'up' | 'down') => void): void;
136
143
  };
137
144
 
138
- export { CdpClient, DEFAULT_TIMEOUT_S, InvalidTransitionError, LinkInfo, MemoryEventLog, PopupSource, RelayError, Transport, applyInput, createEngine, createLatestSender, createRelayTransport, importSecret, isTerminal, newSecret, newSessionId, nextStatus, probeCapabilities, signToken, startScreencast, startScreenshotPolling, verifyToken };
145
+ /**
146
+ * Keeps a takeover on its own site. The human holding the link may act on the page they were handed, not on whatever
147
+ * else the agent's browser is logged in to: the top frame can't navigate to another site (downloads from another
148
+ * site are navigations too, so they are stopped the same way).
149
+ * Frames inside the page stay unrestricted (CAPTCHA widgets are cross-site iframes).
150
+ *
151
+ * "Site" is the registrable domain from the public suffix list (private suffixes included, so github.io or
152
+ * myshopify.com tenants are separate sites). An agent whose flow crosses sites (SSO, 3-D Secure) lists the extra
153
+ * sites in `allowedSites`.
154
+ */
155
+ /** The site a host belongs to: its registrable domain, or the exact host for IPs, localhost and single labels. */
156
+ declare function siteOf(host: string): string;
157
+ /** True for a bare public suffix ("com", "co.uk", "github.io"): never a site an agent may allow wholesale. */
158
+ declare function isPublicSuffix(host: string): boolean;
159
+
160
+ export { CdpClient, DEFAULT_TIMEOUT_S, InvalidTransitionError, LinkInfo, MemoryEventLog, PopupSource, RelayError, Transport, applyInput, createEngine, createLatestSender, createRelayTransport, importSecret, isPublicSuffix, isTerminal, newSecret, newSessionId, nextStatus, probeCapabilities, signToken, siteOf, startScreencast, startScreenshotPolling, verifyToken };
139
161
  export type { Capabilities, Engine, EngineOptions, EventLog, FrameSink, LinkHandler, RelayErrorDetail, RelayTransportOptions, ScreencastOptions, SessionEvent, TakeoverCallOptions, TokenCheck, UnstuckEvent, UnstuckEventType };
package/dist/index.js CHANGED
@@ -304,9 +304,10 @@ async function evaluate(cdp, expression) {
304
304
  return void 0;
305
305
  }
306
306
  }
307
+ var MAX_FIELDS = 30;
307
308
  async function scanFields(cdp) {
308
309
  const v = await evaluate(cdp, SCAN_SOURCE);
309
- return Array.isArray(v) ? v.filter(isField).map(({ x, y, w, h, kind }) => ({ x, y, w, h, kind })) : [];
310
+ return Array.isArray(v) ? v.filter(isField).slice(0, MAX_FIELDS).map(({ x, y, w, h, kind }) => ({ x, y, w, h, kind })) : [];
310
311
  }
311
312
  async function focusedField(cdp) {
312
313
  const v = await evaluate(cdp, FOCUS_SOURCE);
@@ -432,6 +433,103 @@ function createFieldFeed(deps) {
432
433
  };
433
434
  }
434
435
 
436
+ // src/session/page-lock.ts
437
+ import { getDomain, getPublicSuffix } from "tldts";
438
+ function siteOf(host) {
439
+ const h = host.toLowerCase().replace(/\.$/, "");
440
+ if (h.startsWith("[")) return h;
441
+ return getDomain(h, { allowPrivateDomains: true }) ?? h;
442
+ }
443
+ function isPublicSuffix(host) {
444
+ const h = host.toLowerCase().replace(/^\*\./, "").replace(/\.$/, "");
445
+ return !h.includes(".") || getPublicSuffix(h, { allowPrivateDomains: true }) === h;
446
+ }
447
+ function urlAllowed(url, sites) {
448
+ if (url === "about:blank" || url === "about:srcdoc") return true;
449
+ let u;
450
+ try {
451
+ u = new URL(url.startsWith("blob:") ? url.slice(5) : url);
452
+ } catch {
453
+ return false;
454
+ }
455
+ if (u.protocol !== "https:" && u.protocol !== "http:") return false;
456
+ const host = u.hostname.toLowerCase().replace(/\.$/, "");
457
+ return sites.some((s) => host === s || host.endsWith(`.${s}`));
458
+ }
459
+ async function lockPage(cdp, opts) {
460
+ let mainFrame = null;
461
+ let current = "about:blank";
462
+ try {
463
+ const tree = await cdp.send("Page.getFrameTree");
464
+ mainFrame = tree.frameTree.frame.id;
465
+ current = tree.frameTree.frame.url;
466
+ } catch {
467
+ }
468
+ const sites = [...(opts.allowedSites ?? []).map((s) => s.toLowerCase().replace(/^\*\./, "").replace(/\.$/, ""))];
469
+ try {
470
+ const own = new URL(current);
471
+ if (opts.ownSite !== false && (own.protocol === "https:" || own.protocol === "http:")) sites.push(siteOf(own.hostname));
472
+ } catch {
473
+ }
474
+ let lastAllowed = current;
475
+ const allowTop = (url) => urlAllowed(url, sites);
476
+ const blocked = (url) => opts.onBlocked?.(url);
477
+ const offPaused = cdp.on("Fetch.requestPaused", (e) => {
478
+ const top = mainFrame === null || e.frameId === void 0 || e.frameId === mainFrame;
479
+ if (top && !allowTop(e.request.url)) {
480
+ blocked(e.request.url);
481
+ void cdp.send("Fetch.failRequest", { requestId: e.requestId, errorReason: "Aborted" }).catch(() => {
482
+ });
483
+ } else void cdp.send("Fetch.continueRequest", { requestId: e.requestId }).catch(() => {
484
+ });
485
+ });
486
+ const offNavigated = cdp.on("Page.frameNavigated", (e) => {
487
+ if (e.frame.parentId) return;
488
+ mainFrame = e.frame.id;
489
+ if (allowTop(e.frame.url)) lastAllowed = e.frame.url;
490
+ else {
491
+ blocked(e.frame.url);
492
+ void cdp.send("Page.navigate", { url: lastAllowed }).catch(() => {
493
+ });
494
+ }
495
+ });
496
+ await cdp.send("Fetch.enable", { patterns: [{ urlPattern: "*", resourceType: "Document", requestStage: "Request" }] });
497
+ await cdp.send("Network.setBypassServiceWorker", { bypass: true }).catch(() => {
498
+ });
499
+ let stopped = false;
500
+ return {
501
+ sites,
502
+ onAllowedPage: urlAllowed(current, sites),
503
+ async stop() {
504
+ if (stopped) return;
505
+ stopped = true;
506
+ offPaused();
507
+ offNavigated();
508
+ await cdp.send("Fetch.disable").catch(() => {
509
+ });
510
+ await cdp.send("Network.setBypassServiceWorker", { bypass: false }).catch(() => {
511
+ });
512
+ }
513
+ };
514
+ }
515
+ var ALT2 = 1;
516
+ var META2 = 4;
517
+ var SHIFT2 = 8;
518
+ var HISTORY_KEYS = /* @__PURE__ */ new Set(["BrowserBack", "BrowserForward", "BrowserHome"]);
519
+ function safeInput(msg) {
520
+ if (msg.t === "mouse") {
521
+ if (msg.button === "middle" || msg.button === "right") return null;
522
+ return msg.modifiers === 0 ? msg : { ...msg, modifiers: 0 };
523
+ }
524
+ if (msg.t === "key") {
525
+ if (HISTORY_KEYS.has(msg.key) || msg.key === "ContextMenu" || msg.key === "F10" && msg.modifiers & SHIFT2) return null;
526
+ if ((msg.key === "Enter" || msg.key === " ") && msg.modifiers !== 0) return { ...msg, modifiers: 0 };
527
+ if (msg.modifiers === ALT2 && (msg.key === "ArrowLeft" || msg.key === "ArrowRight")) return null;
528
+ if (msg.modifiers === META2 && (msg.key === "[" || msg.key === "]")) return null;
529
+ }
530
+ return msg;
531
+ }
532
+
435
533
  // src/stream/latest.ts
436
534
  function createLatestSender(conn, opts = {}) {
437
535
  const mark = opts.highWaterMark ?? 512 * 1024;
@@ -504,7 +602,7 @@ function sealConnection(conn, key, sessionId) {
504
602
  }).catch(() => {
505
603
  }).finally(() => void (pendingBytes -= plain.length));
506
604
  };
507
- queue(enc2.encode(JSON.stringify({ t: "challenge", n: nonce })), true);
605
+ queue(enc2.encode(JSON.stringify({ t: "challenge", n: nonce, v: 2 })), true);
508
606
  const kill = () => {
509
607
  dead = true;
510
608
  conn.close(1008, "undecryptable");
@@ -524,7 +622,7 @@ function sealConnection(conn, key, sessionId) {
524
622
  if (dead) return;
525
623
  const m = await openMsg(key, sessionId, "v2e", nonce, bytes);
526
624
  if (dead) return;
527
- if (!m || m.seq <= lastIn) return kill();
625
+ if (!m || m.seq !== lastIn + 1) return kill();
528
626
  lastIn = m.seq;
529
627
  h(isJsonPlaintext(m.plain) ? dec2.decode(m.plain) : m.plain);
530
628
  }).catch(() => {
@@ -590,6 +688,15 @@ function runTakeover(deps, cdp, opts) {
590
688
  let wrongCodes = 0;
591
689
  let lastFrame = null;
592
690
  let caps = { screencast: true, insertText: true, input: true };
691
+ let pageSites = [];
692
+ const onBlocked = (url2) => {
693
+ let host = "";
694
+ try {
695
+ host = new URL(url2).hostname;
696
+ } catch {
697
+ }
698
+ emit("navigation_blocked", { host });
699
+ };
593
700
  const targets = [];
594
701
  const active = () => targets[targets.length - 1] ?? { cdp, caps, off: () => {
595
702
  } };
@@ -628,7 +735,7 @@ function runTakeover(deps, cdp, opts) {
628
735
  await Promise.race([stop(), new Promise((r) => timer = setTimeout(r, STOP_TIMEOUT_MS))]);
629
736
  clearTimeout(timer);
630
737
  }
631
- function finish(final, detail) {
738
+ function finish(final, detail, logged) {
632
739
  if (isTerminal(status)) return;
633
740
  status = nextStatus(status, FINAL_EVENT[final]);
634
741
  clearTimeout(expiryTimer);
@@ -639,6 +746,7 @@ function runTakeover(deps, cdp, opts) {
639
746
  offPopups();
640
747
  fieldFeed.stop();
641
748
  for (const t of targets) t.off();
749
+ const locks = targets.map((t) => t.lock);
642
750
  const viewer = holder;
643
751
  holder = null;
644
752
  if (viewer) {
@@ -648,15 +756,18 @@ function runTakeover(deps, cdp, opts) {
648
756
  const durationS = Math.round(now() - startedAt) / 1e3;
649
757
  void (async () => {
650
758
  await stopStream();
759
+ let unlockTimer;
760
+ await Promise.race([Promise.all(locks.map((l) => l?.stop())), new Promise((r) => unlockTimer = setTimeout(r, STOP_TIMEOUT_MS))]);
761
+ clearTimeout(unlockTimer);
651
762
  if (published) await transport.unpublish(sessionId).catch(() => {
652
763
  });
653
- emit("finished", { status: final, durationS, inputCount, ...detail ? { detail } : {} });
764
+ emit("finished", { status: final, durationS, inputCount, ...logged ?? (detail ? { detail } : {}) });
654
765
  const fallbacks = [!caps.screencast && "screenshots", !caps.insertText && "per-key typing"].filter(Boolean).join(", ");
655
766
  const shown = detail ?? (fallbacks ? `fallback: ${fallbacks}` : void 0);
656
767
  resolveResult({ status: final, sessionId, url, durationS, ...shown ? { detail: shown } : {} });
657
768
  })();
658
769
  }
659
- async function attachViewer(conn) {
770
+ async function attachViewer(conn, vn) {
660
771
  const previous = holder;
661
772
  holder = conn;
662
773
  leftAt = null;
@@ -666,7 +777,7 @@ function runTakeover(deps, cdp, opts) {
666
777
  resumeKey = newSessionId();
667
778
  if (status === "waiting") go("viewer_joined");
668
779
  emit("viewer_joined");
669
- sendJson(conn, { t: "ready", reason: opts.reason, site: opts.site ?? "", expiresAt, resumeKey });
780
+ sendJson(conn, { t: "ready", reason: opts.reason, site: opts.site ?? "", expiresAt, resumeKey, ...vn ? { vn } : {} });
670
781
  sender = createLatestSender(conn);
671
782
  if (lastFrame) sender.push(lastFrame);
672
783
  fieldFeed.onTargetChanged();
@@ -716,7 +827,17 @@ function runTakeover(deps, cdp, opts) {
716
827
  });
717
828
  const popupCaps = await probeCapabilities(popup);
718
829
  if (gone || !popupCaps.input || isTerminal(status)) return void off();
719
- entry = { cdp: popup, caps: popupCaps, off };
830
+ const lock = await lockPage(popup, { allowedSites: pageSites, ownSite: false, onBlocked }).catch(() => null);
831
+ if (lock && !lock.onAllowedPage) {
832
+ onBlocked(await popup.send("Page.getFrameTree").then((t) => t.frameTree.frame.url, () => ""));
833
+ void popup.send("Page.close").catch(() => {
834
+ });
835
+ }
836
+ if (!lock || !lock.onAllowedPage || gone || isTerminal(status)) {
837
+ void lock?.stop();
838
+ return void off();
839
+ }
840
+ entry = { cdp: popup, caps: popupCaps, off, lock };
720
841
  targets.push(entry);
721
842
  await switchStream();
722
843
  }
@@ -726,6 +847,7 @@ function runTakeover(deps, cdp, opts) {
726
847
  const wasActive = i === targets.length - 1;
727
848
  targets.splice(i, 1);
728
849
  entry.off();
850
+ void entry.lock?.stop();
729
851
  if (wasActive) void switchStream();
730
852
  }
731
853
  function detachViewer(conn) {
@@ -752,7 +874,7 @@ function runTakeover(deps, cdp, opts) {
752
874
  startLeftTimer();
753
875
  }
754
876
  }
755
- async function onHello(conn, token, offeredResumeKey, offeredCode) {
877
+ async function onHello(conn, token, offeredResumeKey, offeredCode, vn) {
756
878
  const check = await verifyToken(key, token, now());
757
879
  if (isTerminal(status)) {
758
880
  reject(conn, "session_closed");
@@ -787,7 +909,7 @@ function runTakeover(deps, cdp, opts) {
787
909
  return false;
788
910
  }
789
911
  redeemed = true;
790
- await attachViewer(conn);
912
+ await attachViewer(conn, vn);
791
913
  return true;
792
914
  }
793
915
  function handleInput(conn, raw) {
@@ -798,20 +920,25 @@ function runTakeover(deps, cdp, opts) {
798
920
  return sendJson(conn, { t: "pong" });
799
921
  case "done":
800
922
  return finish("resolved");
801
- case "cant_solve":
802
- return finish("cancelled", msg.reason || "cant_solve");
803
- default:
923
+ case "cant_solve": {
924
+ const reason = cleanReason(msg.reason ?? "");
925
+ return finish("cancelled", reason || "cant_solve", reason ? { detail: "cant_solve", reasonLength: reason.length } : void 0);
926
+ }
927
+ default: {
928
+ const safe = safeInput(msg);
929
+ if (!safe) return;
804
930
  inputCount++;
805
931
  inputChain = inputChain.then(async () => {
806
932
  const target = active();
807
933
  try {
808
- const msgs = msg.t === "key" ? translateShortcut(msg, await browserPlatformIsMac(target.cdp)) : [msg];
934
+ const msgs = safe.t === "key" ? translateShortcut(safe, await browserPlatformIsMac(target.cdp)) : [safe];
809
935
  for (const m of msgs) await applyInput(target.cdp, m, target.caps);
810
936
  } catch (e) {
811
937
  return onTargetError(target, e);
812
938
  }
813
- fieldFeed.onInput(msg);
939
+ fieldFeed.onInput(safe);
814
940
  });
941
+ }
815
942
  }
816
943
  }
817
944
  function onConnection(conn) {
@@ -837,7 +964,7 @@ function runTakeover(deps, cdp, opts) {
837
964
  greeting = true;
838
965
  clearTimeout(helloTimer);
839
966
  helloTimers.delete(helloTimer);
840
- void onHello(conn, msg.token, msg.resumeKey, msg.code).then((ok) => {
967
+ void onHello(conn, msg.token, msg.resumeKey, msg.code, msg.vn).then((ok) => {
841
968
  greeted = ok;
842
969
  greeting = false;
843
970
  for (const next of waiting.splice(0)) dispatch(next);
@@ -854,8 +981,15 @@ function runTakeover(deps, cdp, opts) {
854
981
  emit("created", { screencast: caps.screencast, insertText: caps.insertText, input: caps.input });
855
982
  if (isTerminal(status)) return;
856
983
  if (!caps.input) return finish("failed", "browser does not support input");
857
- targets.push({ cdp, caps, off: () => {
858
- } });
984
+ try {
985
+ const lock = await lockPage(cdp, { allowedSites: opts.allowedSites ?? [], onBlocked });
986
+ if (isTerminal(status)) return void lock.stop();
987
+ pageSites = lock.sites;
988
+ targets.push({ cdp, caps, off: () => {
989
+ }, lock });
990
+ } catch {
991
+ return finish("failed", "page_lock_unavailable");
992
+ }
859
993
  if (opts.popups) offPopups = opts.popups.onPopup((popup) => void addPopup(popup));
860
994
  try {
861
995
  const rawE2e = newE2eKey();
@@ -894,6 +1028,9 @@ function sameCode(a, b) {
894
1028
  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
895
1029
  return diff === 0;
896
1030
  }
1031
+ function cleanReason(text) {
1032
+ return text.replace(/[\p{Cc}\p{Cf}\u2028\u2029]/gu, " ").replace(/\s+/g, " ").trim().slice(0, 200);
1033
+ }
897
1034
 
898
1035
  // src/engine.ts
899
1036
  var DEFAULT_TIMEOUT_S = 600;
@@ -914,7 +1051,8 @@ function createEngine(opts) {
914
1051
  site: call.site,
915
1052
  onLink: call.onLink ?? opts.onLink,
916
1053
  popups: call.popups,
917
- requireCode: call.requireCode ?? opts.requireCode
1054
+ requireCode: call.requireCode ?? opts.requireCode,
1055
+ ...call.allowedSites ? { allowedSites: call.allowedSites } : {}
918
1056
  });
919
1057
  running.add(session);
920
1058
  try {
@@ -1117,6 +1255,7 @@ function createRelayTransport(opts) {
1117
1255
  sessions.delete(id);
1118
1256
  throw e;
1119
1257
  }
1258
+ if (opts.viewerUrl) return { baseUrl: `${opts.viewerUrl.replace(/\/+$/, "")}/s/${id}?r=${encodeURIComponent(relay)}` };
1120
1259
  return { baseUrl: `${httpBase}/s/${id}` };
1121
1260
  },
1122
1261
  onConnection(id, h) {
@@ -1143,12 +1282,14 @@ export {
1143
1282
  createLatestSender,
1144
1283
  createRelayTransport,
1145
1284
  importSecret,
1285
+ isPublicSuffix,
1146
1286
  isTerminal,
1147
1287
  newSecret,
1148
1288
  newSessionId,
1149
1289
  nextStatus,
1150
1290
  probeCapabilities,
1151
1291
  signToken,
1292
+ siteOf,
1152
1293
  startScreencast,
1153
1294
  startScreenshotPolling,
1154
1295
  verifyToken
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@velmlabs/unstuck-core",
3
- "version": "0.1.4",
3
+ "version": "0.1.6",
4
4
  "description": "The Unstuck takeover engine core: screencast, input, sessions and transports, usable in Node or Cloudflare Workers.",
5
5
  "keywords": [
6
6
  "ai",
@@ -46,7 +46,8 @@
46
46
  "node": ">=20"
47
47
  },
48
48
  "dependencies": {
49
- "@velmlabs/unstuck-protocol": "0.1.4"
49
+ "tldts": "^7.5.2",
50
+ "@velmlabs/unstuck-protocol": "0.1.6"
50
51
  },
51
52
  "publishConfig": {
52
53
  "access": "public"