Guard against browser-API regressions and slow fix propagation

[djscruggs]

Summary

Following #51 / #52 (navigator.credentials is non-configurable on WebKit, so
the Object.defineProperty() call added in 3.2.1 threw and loadOnce()
rejected on all iOS browsers and desktop Safari), two gaps remain that let the
regression both ship and linger in dependents:

1. No browser test exercised load(). CI runs lint only — there was no
   automated assertion that load() succeeds in any browser, so the WebKit
   breakage shipped undetected from 3.2.1 onward.
2. No signal pushed the fix downstream. Consumers pin ^4.0.x and would
   resolve the patched version on a fresh install, but lockfiles stayed pinned
   to the broken version and nothing prompted a bump + redeploy.

This issue proposes monitoring/guardrails across three layers. Decisions below
reflect maintainer feedback in the comments.

Layer 1 — Browser-API regression detection

1a. Cross-browser smoke test in CI (highest leverage).

• Add Playwright with chromium, firefox, and webkit projects.
• A test page loads the built bundle, calls loadOnce(), and asserts: it
  resolves without throwing; window.WebCredential is defined; and
  navigator.credentials.get / .store are functions (patched).
• The webkit project reproduces loadOnce() throws on iOS (WebKit) since 3.2.1: cannot redefine navigator.credentials #51 directly (red before Do not throw when navigator.credentials cannot be redefined #52, green after).
• Add a test script and a test CI job as a sibling of lint (no needs:,
  runs in parallel). This makes the regression class fail pre-publish.
• Decision: start with Playwright's bundled WebKit on Linux; revisit a real
  macOS/Safari runner only if needed.

1a-ext. Password-manager extension interference.

• Browser password-manager extensions (Dashlane, 1Password, etc.) have
  previously manipulated navigator.credentials and caused breakage. Track
  known-problematic extensions and exercise the smoke test with them installed,
  so extension-induced regressions are caught alongside browser ones.

1b. External browser-release feed (optional second layer).

• Watch WebKit/Chromium release notes and web-platform-tests deltas for
  Credential Management API / navigator.credentials changes, to flag upcoming
  behavior changes before they reach stable. Noisier; does not prove our code
  breaks (1a does).
• Decision: deferred — prove 1a first, then reassess.

Layer 2 — Downstream propagation

2a. Dependabot.

• Add .github/dependabot.yml (npm) so a new release auto-opens a
  lockfile-bump PR.
• Decision: scope to this repo only for now.

2b. Staleness check.

• A small script reporting, per consumer: pinned range, resolved (lockfile)
  version, and latest published — flagging anyone behind. Runnable on demand or
  on a schedule.
• Decision: scheduling/ownership deferred (follows from the 1b/2a answers).

Layer 3 — External consumers

• Publish release notes / advisory for the fix.
• npm deprecate the affected version range with a message pointing at the
  WebKit breakage, so installers see a warning.
• Decision: yes, do the npm deprecate.

Open questions

All resolved in the comments:

1. WebKit in CI → bundled WebKit on Linux to start.
2. Layer 1b → prove 1a first.
3. Dependabot rollout → this repo only.
4. Scheduling/ownership of 1b/2b → deferred.
5. npm deprecate → yes.

Next step

Implement 1a (cross-browser Playwright smoke test, bundled WebKit) — the
single change that would have caught #51 pre-publish — plus the 1a-ext
password-manager-extension coverage.

[davidlehn]

Beyond testing browsers, there are extensions (dashlane, 1password, etc) that have previously been manipulating navigator.credentials and causing issues. Might want to track ones with such issues, and add them into the test browsers too.

[dlongley]

+1 to this plan, answers to questions:

1. We can start with bundled webkit on linux and do more if necessary later.
2. Prove 1a first.
3. Any dependabot stuff should be just this repo for now.
4. Deferred because of other answers (IIUC).
5. IMO, yes, we should do npm deprecate.

Happy to hear other opinions.

[djscruggs]

Thanks both — I've folded the decisions into the issue body (bundled WebKit first, prove 1a before 1b, Dependabot this-repo-only, npm deprecate yes) and added extension coverage as 1a-ext.

One practical constraint on the extension idea worth flagging: Playwright can only load real browser extensions under Chromium (via a persistent context); WebKit and Firefox don't support loading extensions in Playwright. So we can't get "WebKit + 1Password/Dashlane installed" in CI directly.

Two ways to cover it:

• Simulate the behavior (browser-agnostic): after loadOnce(), have the test re-define / reassign navigator.credentials the way these extensions do, and assert CHAPI still works. This runs under all three projects (incl. webkit) and captures the actual failure mode without needing the real extension.
• Real extensions, Chromium-only: a separate Chromium-with-extension job for the handful of known-problematic ones.

I'd suggest the simulation approach as the default (it's what actually broke us — something else redefining the property) and add real-extension Chromium runs only if a specific extension does something the simulation can't reproduce. Will proceed on that basis unless anyone objects.

[djscruggs]

Implementation of Layer 1a has started in #56 (draft). Let's move test-suite discussion there — this issue stays as the home for the broader monitoring plan (Dependabot, npm deprecate, the external-release feed).

One finding from #56 worth flagging here since it touches the decisions above: Playwright's bundled WebKit (26.5) reports navigator.credentials as configurable: true, so it does not reproduce real Safari/iOS #51 on its own. The plain cross-browser smoke test would pass even with the 4.0.2 fix reverted. The PR works around this with a deterministic guard that forces the property non-configurable + non-writable (the shape that actually throws on Safari) — verified red without the fix, green with it, in all three engines.

So the "bundled WebKit first" decision still holds, but bundled WebKit alone isn't a faithful #51 reproduction — the forced-non-configurable test is the real guard. A real macOS/Safari runner would be the only way to catch it via the natural browser behavior, if we later decide that's worth the cost.

Details and the full checklist are in #56.