Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

feat: census-test the isolated-handle ambient-globals rule (PIN-070)

Luigi Agostibaa22c09ed0e
diff --git a/internal/bridge/ambient_globals_test.go b/internal/bridge/ambient_globals_test.go
new file mode 100644
index 00000000..44fb18dd
--- /dev/null
+++ b/internal/bridge/ambient_globals_test.go
@@ -0,0 +1,365 @@
+package bridge
+
+import (
+ "io/fs"
+ "os"
+ "path/filepath"
+ "regexp"
+ "strings"
+ "testing"
+)
+
+// An isolated-world node handle lives in the TOP frame's isolated context, so
+// inside a Runtime.callFunctionOn declaration the ambient window/document are the
+// top frame's, not the node's. A frame-offset walk started from the ambient window
+// terminates on its first iteration and yields frame-local coordinates; a hit test
+// there runs against the wrong document. Both fail silently.
+//
+// This census is the enforcement half of that rule. Its sibling,
+// TestIsolatedWorldBoundaryCensus, covers WHICH element is acted on; this one
+// covers what the declaration is allowed to read once it has one.
+//
+// PRESENCE, NOT ABSENCE. It does not try to prove a bare window/document is
+// shadowed — that is an absence heuristic over JS inside Go string literals and
+// fails open on any wording it did not anticipate, which is exactly the shape of
+// the near miss it exists to catch (`const view = window;` landing under a comment
+// asserting the opposite). Instead: if a declaration mentions an ambient global at
+// all, it must carry a node-derived shadow line verbatim. A hand-rolled variant
+// fails closed.
+//
+// GRANULARITY: per file, not per call site. Correlating a declaration with whether
+// its handle came from IsolatedNodeObjectID is not reliably textual, so a file that
+// obtains isolated handles puts every callFunctionOn declaration in it in scope.
+//
+// FALSE POSITIVES point one way, and that way is safe: a main-world declaration
+// sitting in such a file is asked to shadow too. Shadowing is correct in either
+// world — it costs one line and changes no behaviour. The census never excuses a
+// declaration that should shadow; it can only ask one that need not to.
+//
+// THE CANONICAL LINES STAY INLINE, four copies of one line, deliberately. Hoisting
+// them into a shared const would blind this census, because what it matches is text
+// inside the literal it scans. Four copies held identical by a test that fails on
+// drift beats one const the guard cannot see. If declaration assembly ever becomes
+// first-class, revisit both together.
+
+// isolatedHandleTokens put a file in scope: it either produces an isolated-world
+// handle or obtains one. Naming the producers rather than a directory is what
+// keeps the census module-wide — pinchtab spreads CDP work over internal/bridge,
+// internal/bridge/cdpops and internal/cdptk.
+var isolatedHandleTokens = []string{"IsolatedNodeObjectID", "FrameExecutionContextID"}
+
+// shadowForm is one accepted way to derive a global from the node. requires is
+// extra text that must also be present for the form to be node-derived at all:
+// the root spelling is only sound because the declaration binds root to this.
+type shadowForm struct {
+ line string
+ requires string
+}
+
+// ambientShadows is the rule as data: mention the global, carry one of its forms.
+// Entries are compliance, not exemption — every one derives the global from the
+// node the handle points at.
+var ambientShadows = map[string][]shadowForm{
+ "window": {
+ {line: "const view = (this.ownerDocument && this.ownerDocument.defaultView) || window;"},
+ },
+ "document": {
+ {line: "const doc = this.ownerDocument || document;"},
+ {line: "const document = root.ownerDocument || root;", requires: "const root = this;"},
+ },
+}
+
+// ambientGlobalsExceptions is empty, and the first entry ever added has to be
+// argued on the harm it accepts, not on how reasonable the wording sounds. It is
+// checked in both directions like the resolution census: a listed file that no
+// longer violates the rule fails here too, so an exception cannot outlive its
+// reason.
+var ambientGlobalsExceptions = map[string]string{}
+
+// canonicalViewLine is the preamble as it stands in the tree. Counting its
+// occurrences module-wide against the occurrences the scan actually reached is
+// what closes the parser's blind spot: a declaration assembled in a shape this
+// census cannot recognise stops being scanned, and that divergence fails.
+const canonicalViewLine = "const view = (this.ownerDocument && this.ownerDocument.defaultView) || window;"
+
+type jsLiteral struct {
+ text string
+ startLine int
+}
+
+// plusChain matches the Go source between two raw literals that are concatenated,
+// including any named fragments in the chain: `head` + jsNormalizeHelper + `tail`
+// is one declaration, and the xpath arm of the selector resolver lives in the tail.
+// Missing this shape is not a cosmetic gap — the fragment that actually reads a
+// global is routinely not the fragment that opens the function.
+var plusChain = regexp.MustCompile(`^\s*\+\s*(?:[A-Za-z_][A-Za-z0-9_.]*\s*\+\s*)*$`)
+
+var identLiteral = regexp.MustCompile("(?s)([A-Za-z_][A-Za-z0-9_]*)\\s*(?::?=)\\s*`([^`]*)`")
+
+// goRawLiterals returns every backtick literal in a Go source file, splicing
+// +-concatenated ones — named fragments included, resolved to their own literal —
+// into the single string the browser is actually handed.
+func goRawLiterals(src string) []jsLiteral {
+ fragments := map[string]string{}
+ for _, m := range identLiteral.FindAllStringSubmatch(src, -1) {
+ fragments[m[1]] = m[2]
+ }
+
+ var literals []jsLiteral
+ prevEnd := 0
+ line := 1
+ for i := 0; i < len(src); i++ {
+ if src[i] == '\n' {
+ line++
+ continue
+ }
+ if src[i] != '`' {
+ continue
+ }
+ end := strings.IndexByte(src[i+1:], '`')
+ if end < 0 {
+ break
+ }
+ body := src[i+1 : i+1+end]
+ startLine := line
+ line += strings.Count(body, "\n")
+
+ between := src[prevEnd:i]
+ if last := len(literals) - 1; last >= 0 && plusChain.MatchString(between) {
+ for _, name := range identsInChain(between) {
+ literals[last].text += fragments[name]
+ }
+ literals[last].text += body
+ } else {
+ literals = append(literals, jsLiteral{text: body, startLine: startLine})
+ }
+ prevEnd = i + end + 2
+ i = prevEnd - 1
+ }
+ return literals
+}
+
+var identToken = regexp.MustCompile(`[A-Za-z_][A-Za-z0-9_.]*`)
+
+func identsInChain(chain string) []string {
+ return identToken.FindAllString(chain, -1)
+}
+
+// declarations returns the literals that are Runtime.callFunctionOn function
+// declarations: a bare function expression. An IIFE (`(function(`) is a
+// Runtime.evaluate payload — no node handle, so the rule does not apply and the
+// census never sees it. Excluded by scope beats excluded by exception.
+func callFunctionDeclarations(literals []jsLiteral) []jsLiteral {
+ var decls []jsLiteral
+ for _, lit := range literals {
+ head := strings.TrimLeft(lit.text, " \t\n")
+ if strings.HasPrefix(head, "function(") || strings.HasPrefix(head, "function (") {
+ decls = append(decls, lit)
+ }
+ }
+ return decls
+}
+
+// ambientMention reports the offset of the first mention of name that is not a field
+// access or part of a longer identifier, so ownerDocument and el.document never
+// count as ambient reads.
+func ambientMention(text, name string) int {
+ for from := 0; ; {
+ idx := strings.Index(text[from:], name)
+ if idx < 0 {
+ return -1
+ }
+ at := from + idx
+ from = at + len(name)
+ // A dot BEFORE the name is a field access (el.ownerDocument); a dot AFTER it
+ // is the ambient read itself (document.evaluate), which is the whole point.
+ // Treating both the same way is how a detector reports mentions it never
+ // actually looks for.
+ if at > 0 && (text[at-1] == '.' || isIdentByte(text[at-1])) {
+ continue
+ }
+ if from < len(text) && isIdentByte(text[from]) {
+ continue
+ }
+ return at
+ }
+}
+
+func isIdentByte(b byte) bool {
+ return b == '_' || b == '$' ||
+ (b >= 'a' && b <= 'z') || (b >= 'A' && b <= 'Z') || (b >= '0' && b <= '9')
+}
+
+// jsCode blanks whole-line JS comments, keeping the line structure. It matters in
+// both directions: prose mentioning window is not an ambient read, and a
+// commented-out preamble must not satisfy the rule — that commenting-out is the
+// exact near miss this census exists to catch. Only full-line comments are
+// blanked, never a trailing one, because eating code would make the census fail
+// open, and a trailing comment can only ever cost a harmless extra shadow.
+func jsCode(text string) string {
+ lines := strings.Split(text, "\n")
+ for i, line := range lines {
+ trimmed := strings.TrimSpace(line)
+ for _, prefix := range []string{"//", "/*", "*/", "*"} {
+ if strings.HasPrefix(trimmed, prefix) {
+ lines[i] = strings.Repeat(" ", len(line))
+ break
+ }
+ }
+ }
+ return strings.Join(lines, "\n")
+}
+
+func lineAtOffset(text string, offset int) string {
+ start := strings.LastIndexByte(text[:offset], '\n') + 1
+ end := strings.IndexByte(text[start:], '\n')
+ if end < 0 {
+ return strings.TrimSpace(text[start:])
+ }
+ return strings.TrimSpace(text[start : start+end])
+}
+
+// sourceLine locates the offending JS line back in the Go file. A declaration
+// spliced from concatenated fragments does not lay out like the source it came
+// from, so counting newlines inside the merged text reports a line the reader
+// cannot find; the line's own text can be.
+func sourceLine(src, offending string, fallback int) int {
+ if offending == "" {
+ return fallback
+ }
+ at := strings.Index(src, offending)
+ if at < 0 {
+ return fallback
+ }
+ return strings.Count(src[:at], "\n") + 1
+}
+
+func hasShadow(text string, forms []shadowForm) bool {
+ for _, form := range forms {
+ if !strings.Contains(text, form.line) {
+ continue
+ }
+ if form.requires != "" && !strings.Contains(text, form.requires) {
+ continue
+ }
+ return true
+ }
+ return false
+}
+
+func TestIsolatedHandleDeclarationsShadowAmbientGlobals(t *testing.T) {
+ root, err := filepath.Abs("../..")
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ scopedFiles := 0
+ checkedDecls := 0
+ exercised := map[string]int{}
+ violations := map[string]bool{}
+ canonicalInScope := 0
+ canonicalInModule := 0
+
+ walkErr := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
+ if err != nil {
+ return err
+ }
+ if d.IsDir() || !strings.HasSuffix(path, ".go") || strings.HasSuffix(path, "_test.go") {
+ return nil
+ }
+ rel, relErr := filepath.Rel(root, path)
+ if relErr != nil {
+ return relErr
+ }
+ name := filepath.ToSlash(rel)
+ raw, err := os.ReadFile(path)
+ if err != nil {
+ return err
+ }
+ src := string(raw)
+ canonicalInModule += strings.Count(jsCode(src), canonicalViewLine)
+
+ inScope := false
+ for _, token := range isolatedHandleTokens {
+ if strings.Contains(src, token) {
+ inScope = true
+ break
+ }
+ }
+ if !inScope {
+ return nil
+ }
+ scopedFiles++
+
+ for _, decl := range callFunctionDeclarations(goRawLiterals(src)) {
+ checkedDecls++
+ body := jsCode(decl.text)
+ canonicalInScope += strings.Count(body, canonicalViewLine)
+ for ambient, forms := range ambientShadows {
+ at := ambientMention(body, ambient)
+ if at < 0 {
+ continue
+ }
+ exercised[ambient]++
+ if hasShadow(body, forms) {
+ continue
+ }
+ violations[name] = true
+ offending := lineAtOffset(body, at)
+ line := sourceLine(src, offending, decl.startLine)
+ if why, excused := ambientGlobalsExceptions[name]; excused {
+ t.Logf("%s:%d reads ambient %s under a recorded exception (%s)", name, line, ambient, why)
+ continue
+ }
+ t.Errorf("%s:%d reads the ambient %s inside a callFunctionOn declaration without deriving it from the node:\n %s\n"+
+ "An isolated handle runs in the TOP frame's world, so the ambient %s is not the node's — frame offsets vanish and hit tests run on the wrong document.\n"+
+ "Add one of:\n %s",
+ name, line, ambient, offending, ambient,
+ strings.Join(formLines(forms), "\n "))
+ }
+ }
+ return nil
+ })
+ if walkErr != nil {
+ t.Fatal(walkErr)
+ }
+
+ t.Logf("census scope: %d files obtain isolated handles, %d callFunctionOn declarations scanned, ambient mentions %v, canonical preamble %d/%d in scope",
+ scopedFiles, checkedDecls, exercised, canonicalInScope, canonicalInModule)
+ if scopedFiles == 0 {
+ t.Error("no file in the module obtains an isolated node handle — the census is checking nothing")
+ }
+ if checkedDecls == 0 {
+ t.Error("no callFunctionOn declaration found in the files that obtain isolated handles — the census is checking nothing")
+ }
+ // Per ambient global, not in total: one of them falling to zero mentions is how
+ // a whole half of the rule stops being scanned while the census stays green.
+ for ambient := range ambientShadows {
+ if exercised[ambient] == 0 {
+ t.Errorf("no declaration mentions the ambient %s any more; drop it from ambientShadows so the recorded rule stays true", ambient)
+ }
+ }
+ // The parser recognises a declaration by its shape. If the preamble turns up in
+ // the module somewhere the scan never reached, that shape is a blind spot.
+ if canonicalInScope != canonicalInModule {
+ t.Errorf("the canonical preamble appears %d times in the module but only %d were inside a declaration this census recognises; a declaration is assembled in a shape the scan cannot see",
+ canonicalInModule, canonicalInScope)
+ }
+ for name, why := range ambientGlobalsExceptions {
+ if !violations[name] {
+ t.Errorf("%s no longer reads an ambient global unshadowed (%s); remove it from ambientGlobalsExceptions so the recorded exceptions stay true", name, why)
+ }
+ }
+}
+
+func formLines(forms []shadowForm) []string {
+ lines := make([]string, 0, len(forms))
+ for _, form := range forms {
+ if form.requires != "" {
+ lines = append(lines, form.line+" (only with "+form.requires+")")
+ continue
+ }
+ lines = append(lines, form.line)
+ }
+ return lines
+}