inappwebview_script_guard #

Detect silently-failed JavaScript injection in flutter_inappwebview: canary-verified script loading at runtime, plus commit-time AST linting of the JavaScript you embed in Dart files.

Scope, honestly: this is a flutter_inappwebview package, not an "any WebView" abstraction. The verifier calls InAppWebViewController.evaluateJavascript directly. The commit-time tooling (invariants.dart + the executables + the example hooks) is WebView-agnostic — it lints Dart files — but the runtime canary is coupled to flutter_inappwebview by design.

The problem #

evaluateJavascript can swallow failures. A script with a parse error — or one that throws mid-execution — can resolve the Dart future normally, report nothing but Script error. @:0:0 on window.onerror (if anything), and leave your app believing the script loaded. The classic trigger is two adjacent Dart string literals ('foo ' 'bar') inside an embedded script: Dart concatenates them silently, V8 rejects the result, and every feature depending on that script degrades quietly — for days, if nothing distinguishes "script ran" from "script never parsed".

Three failure classes, three different corrective actions — and without instrumentation they are indistinguishable:

1. Script-side failure — parse error, mid-execution throw, page navigated away mid-run. Action: investigate the script — but the same missing verdict also arises when a navigation wiped the world after a healthy run, where the action is the opposite (re-inject once); see The missing verdict.
2. Bridge-side failure — evaluateJavascript itself threw or hung (navigation mid-eval, page disposal, bad ContentWorld). Action: investigate/report the bridge anomaly.
3. Stale script — the WebView is running a cached older version. Action: reload / invalidate cache.

This package makes the three distinguishable.

Quick start (runtime canary) #

import 'package:inappwebview_script_guard/inappwebview_script_guard.dart';

// 1. Wrap your literal JS in a JsScript. Keep the payload a raw
//    triple-quoted string — no interpolation, no concatenation.
final extractionScript = JsScript(
  name: 'extraction',
  source: r'''
JSON.stringify((function () {
  // ... your script ...
  return {ok: true};
})());
''',
);

// 2. Inject + verify in one call.
final (canary, bridgeRaw) =
    await injectAndVerifyCanary(controller, extractionScript);

// 3. Route on the verdict.
switch (canary) {
  case LoadedResult():
    final payload = jsonDecode(bridgeRaw as String);
  case MissingResult():
    // parse error / mid-run throw — or a navigation wiped the world;
    // rule out the wipe (re-inject once) before debugging the JS
  case InjectThrewResult(:final exception, :final stackTrace):
    // bridge-side failure: report exception + stackTrace
  case StaleResult():
    // cached older script: reload or invalidate cache
  case MalformedResult():
    // some other JS clobbered the flag: investigate the writer
}

How the canary works #

JsScript.withCanary wraps your source as:

;(function(){
  var __canary_result=(function(){return <SOURCE>
  })();
  window['__canaryLoaded_<name>']='<sha256-first-8>';
  return __canary_result;
})();

Three properties are load-bearing (each is locked by a test, and each was violated at some point by a wrap shape that "looked obviously correct"):

• The script's own return value still reaches the bridge. The inner IIFE returns your source's value; the outer IIFE captures it and returns the capture — not the canary assignment. Consumers that decode bridgeRaw keep working.
• The canary flag is written after the result assignment, in normal control flow — never in finally. If the bridge swallows a mid-script throw (the exact failure this package exists to detect), a finally-based flag would still fire and report loaded for a script that died. Flag set ⟹ source completed, regardless of bridge swallowing behavior.
• The flag value is a content hash, not true. A flag holding the SHA-256-first-8 of the source distinguishes "loaded the version I shipped" from "loaded something" — which is what turns cache staleness into a first-class verdict.

Verdicts #

CanaryResult is a sealed hierarchy: canary is InjectThrewResult narrows statically, so exception / stackTrace are non-nullable at the read site with no guards.

Configuration #

• canaryPrefix (JsScript, default '__canaryLoaded') — the window property prefix. The full flag is '<prefix>_<name>', exposed as script.canaryFlagName — the single source of truth both the wrap and the read-back derive from.
• evalTimeout (verifyCanary / injectAndVerifyCanary, default 10 s) — bounds every evaluateJavascript await. A hung bridge call (mid-navigation stall; iOS's async-only eval) routes to injectThrew with a TimeoutException instead of hanging your capture pipeline. Note injectAndVerifyCanary performs two awaits (inject + read-back), so its worst case is 2× this value.
• contentWorld — threads to both the inject and the read-back, so isolated-world injections read the flag from the world it was written in. (A shape that threads it only to inject verifies as spuriously missing.)

Async scripts #

If your source returns a Promise, the canary fires when the synchronous prologue completes — it does not wait for the Promise to settle. loaded means "the script started and returned a Promise," not "the async work succeeded." Check both the verdict and the awaited result. This is deliberate: awaiting would couple the canary to user-page network state.

The missing verdict: two causes, opposite responses #

missing means the flag never appeared. That has two cause classes, and the corrective actions point in opposite directions:

1. Script-side failure — a parse error mid-execution, or the body threw before the canary tail ran. Re-injecting reproduces the failure. Investigate the JS (window.onerror, a log line at the top of the script to disambiguate "never started" from "started but threw").
2. Navigation wipe — the page navigated between the script running and your read-back: a redirect, or a WebView restoring its session and committing the real document after an early onLoadStop already fired. The script ran and the flag was written (the two are one synchronous eval — "flag set ⟹ source completed" still holds), but into a document that was then replaced, so the read-back queries a fresh JS world that never had it. (A navigation landing mid-run kills the script before the flag write — cause 1's shape — but the corrective action below is the same either way.) This is easy to hit with the standard inject-at-onLoadStop pattern, and on pages where no second onLoadStop follows (session restore, some SPAs), a one-shot inject stays dead until something re-injects.

For cause 2, "investigate the JS" is a dead end — the fix is to re-inject once when the page has settled. A bounded recovery shape:

var pageGeneration = 0; // bump on every page load AND on teardown

Future<void> injectWithRecovery(
    InAppWebViewController controller, JsScript script,
    {ContentWorld? contentWorld}) async {
  final gen = ++pageGeneration;
  final (verdict, _) = await injectAndVerifyCanary(controller, script,
      contentWorld: contentWorld);
  if (verdict is! MissingResult) return; // any non-missing verdict: never retry
  unawaited(Future<void>.delayed(const Duration(seconds: 5)).then((_) async {
    if (pageGeneration != gen) return; // a later load re-injected anyway
    if (scriptSignalsObserved) return; // it was alive all along
    final (retry, _) = await injectAndVerifyCanary(controller, script,
        contentWorld: contentWorld);
    if (pageGeneration != gen) return;
    debugPrint(retry.isHealthy
        ? 'script re-inject recovered (canary ok)'
        : 'script re-inject still unhealthy: $retry');
    // ONE attempt only — a second miss is a genuine script-side
    // failure (or a hostile page); log it and stop.
  }));
}

The guards matter as much as the retry:

• Generation / session counter — bump it on every navigation and on teardown. Future.delayed has no cancel handle, so without the teardown bump a pending retry fires into a disposed controller.
• scriptSignalsObserved — whatever your script emits (JS-handler messages, samples). If signals are flowing, the first inject actually survived and the missing verdict was a read-back race — re-evaluating a live script would double its listeners and timers.
• Retry missing only. stale means a script IS running (an older version — re-evaluating doubles listeners; invalidate the cache instead), and injectThrew is bridge-side (a re-eval doesn't fix the bridge).
• Thread your contentWorld through both calls (as above). A retry that omits it runs — and verifies — in the default world, reporting a verdict about a world your isolated-world script never touched.
• Bound it to one attempt. Unbounded retries against a page that genuinely blocks your script spin forever.

Two layers of defense #

Parse errors are guarded twice — once before they ship, once at runtime:

Commit time (static): parse validation — lives in package:inappwebview_script_guard/invariants.dart, the bundled executables, and the example hook scripts.

• checkSource / dart run inappwebview_script_guard:check_js_invariants — AST-only invariant checker (sub-second, no Node). Rejects the Dart-level constructs that silently corrupt embedded JS before they ever reach a device.
• dart run inappwebview_script_guard:extract_js + node --check — extracts every raw triple-quoted literal and parse-checks it with real V8, so anything the AST rules can't prove is caught by an actual JS parser.

Runtime: the canary — catches what static checks structurally can't see: mid-execution throws, runtime DOM-shape mismatches, stale-cache shipping. It is also the backstop for parse failures that somehow get past commit time: an unparseable script never reaches the canary write, so it reads back as missing.

Design note — why nothing sits between them. An in-between layer is conceivable: wrap every payload in eval("…") at runtime so parse errors propagate as catchable exceptions. This package deliberately doesn't do that — it would add an eval indirection to every script, and it detects nothing the two layers above don't already cover (commit-time node --check catches the parse error before it ships; the runtime canary reports it as missing if it ships anyway).

The four rejected constructs (commit time) #

Keep raw JS payloads in a dedicated scripts directory and point the checker at it (--root <dir> — nothing about the directory name is hard-coded). Files there are restricted to literal JS in raw triple-quoted strings. The AST checker rejects:

Composed JS (templating, conditionals) belongs in a separate composers directory outside the checked root, with unit tests on the composed output.

Per-file skip directive #

A file awaiting migration can opt out with a top-of-file directive (first 10 lines):

// CHECK_JS_INVARIANTS_SKIP_FILE: <reason> #<issue>

Both fields are required — a malformed directive fails the check rather than silently exempting the file, and skipped files are printed loudly so review sees them. #<issue> refers to your own tracker.

Git-hook wiring (example scripts, not package API) #

The example/hooks/ directory ships three copy-in scripts:

• pre-commit — runs the AST invariants on staged scripts-root files (sub-second).
• check_js.sh — the full sweep: AST invariants + node --check, then writes a proof-of-work JSON keyed to the SHA-256 of the entire scripts root at HEAD (CRLF-normalized, so Windows and Linux hash identically).
• pre-push — verifies the proof matches the pushed tree's bytes. Honest-system enforcement: it doesn't re-validate, it confirms validation happened against exactly what ships.

Setup:

flutter pub add inappwebview_script_guard          # the hooks run the package's
                                             # executables via `dart run`
cp example/hooks/pre-commit example/hooks/pre-push .githooks/
cp example/hooks/check_js.sh tool/
chmod +x .githooks/pre-commit .githooks/pre-push tool/check_js.sh
git config core.hooksPath .githooks
export JS_SCRIPTS_ROOT=lib/webview_scripts   # or edit the scripts
echo .js-check-state/ >> .gitignore          # proof files are local state
tool/check_js.sh                             # first run: 0 violations

(chmod +x matters: git silently ignores a non-executable hook — no error, the hook just never runs.)

These are examples on purpose: hook policy (bypass variables, proof location, which gates chain together) is repo policy, not package API. Edit them freely.

Testing your integration #

The package's own suite pins the wrap format, the verdict routing, the timeout, and the AST rules — you don't need to re-test those. What's worth testing in your repo:

• a parse test per JS-bearing file (extract + node --check in CI or hooks, as above);
• your routing of each verdict to the right corrective action.

For fakes, implement InAppWebViewController with noSuchMethod throwing and override only evaluateJavascript — see this package's test/canary_verifier_test.dart for the pattern.

When something fails #

• Pre-commit fails with "adjacent string literals": the silent-concatenation shape. Restructure, or move the composition to a composers directory.
• Pre-push fails with "proof stale" / "no proof": the scripts root changed since the last check_js.sh run (or it never ran). Re-run it.
• Canary missing at runtime: commit-time checks passed but the flag never appeared. First rule out a navigation wipe (redirect / session restore between inject and flag write) — re-inject once when the page settles; see The missing verdict. If it recurs, it's script-side: a runtime throw (check window.onerror); a log line at the top of the script disambiguates "never started" from "started but threw".
• Canary stale at runtime: the WebView is running a cached copy. Force a reload or invalidate the cache.
• Canary malformed: something else wrote to your flag — don't reload; find the writer (or change canaryPrefix).

License #

MIT.