Skip to content

Add a runtime self-test and warning banner for interception-registration-order failures #8

Description

@knytcomics-ui

Summary

README explicitly documents that interception is 'registration-order dependent' (README.md:130-133) -- if Chrome loads Freighter's content script before mainWorldEntry.ts, Gryd Lock silently does nothing and the user gets zero protection with zero indication anything is wrong.

Current Behavior / Relevant Code

  • src/intercept/mainWorldEntry.ts:52-92 has no fallback or detection for a missed registration race.
  • manifest.json:12-18 declares run_at: 'document_start' but that's a necessary, not sufficient, condition per the README's own caveat.

Why This Matters

Silent failure is the worst failure mode for a security tool -- a user who believes they're protected and isn't is worse off than one who knows they aren't. This is called out as a known tradeoff in the docs but has no runtime mitigation.

Proposed Solution

  • Add a lightweight self-check: on load, mainWorldEntry.ts records a timestamp/flag; a companion check flags degraded protection when the race is suspected.
  • Surface a non-intrusive badge/warning (e.g. toolbar badge text) when the self-test indicates interception may not be active.
  • Document the detection mechanism's limits honestly (a race condition can't be perfectly detected after the fact).

Acceptance Criteria

  • A detectable-degradation signal exists and is surfaced to the user via the toolbar badge or popup.
  • Behavior documented in README alongside the existing race-condition note.

Definition of Done

  • npm run lint, npm run typecheck, npm test, and npm run build all pass locally and in CI
  • New or changed behavior is covered by unit tests (and integration/E2E tests where the change touches interception, background messaging, or the popup)
  • Any user-facing or architectural change is reflected in README.md
  • No regressions to the existing test suite or existing tier/interception behavior

How to Claim This Issue (Application Process)

  1. Comment first. Post a short implementation plan on this issue — your proposed approach, the files you expect to touch, and any open questions — before writing code. This prevents duplicate effort and lets a maintainer flag concerns early, which matters especially for an issue at this complexity level.
  2. Wait for assignment. A maintainer will review your plan and assign the issue to you, typically within 48 hours. Please do not open a draft PR before you're assigned.
  3. Stay active. If there's no visible activity (commits or comments) for 10 days after assignment, the issue may be unassigned and reopened to other contributors.
  4. Submit a scoped PR. Reference this issue (Closes #<issue-number>), keep the diff scoped to the acceptance criteria above, and ensure all CI gates pass before requesting review.
  5. Engage with review. Respond to review feedback within a reasonable timeframe; PRs with no response after 7 days may be closed pending resubmission when you're ready to pick it back up.

Category: Security & Interception Robustness
Estimated effort: M (medium, ~3-5 days)
Difficulty: Advanced — this issue assumes familiarity with the codebase's MV3 service-worker architecture, the Freighter interception protocol, and/or the Stellar SDK.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions