Epic — Establish a lifecycle-safe, origin-bound signing review protocol

[knytcomics-ui]

Outcome

Replace the best-effort page-message/runtime-callback flow with a one-shot protocol binding every decision to the exact transaction, tab, frame, document, wallet adapter, and review window. Requests must survive MV3 worker suspension, reject replay or cross-window decisions, and settle within a defined deadline.

Audit evidence and problem

• src/intercept/mainWorldEntry.ts generates a page-visible ID, posts XDR through window.postMessage(..., '*'), and has no page-side timeout.
• src/intercept/bridgeEntry.ts trusts and forwards that page-provided ID; it does not generate the authoritative ID claimed by README.
• src/background/background.ts keeps resolver functions only in an in-memory Map; DEFAULT_TIMEOUT_MS is unused.
• Popup creation results are not retained. There is no chrome.windows.onRemoved handler, so closing a popup can hang the dApp request.
• DECISION_MADE resolves solely by request ID and ignores sender tab/frame/window. Duplicate IDs overwrite map entries.
• Transaction data and decision identity are placed in popup query parameters and treated as authoritative by src/popup/App.tsx.
• docs/threat-model.md records forgery, MV3 state loss, stale popup, request flooding, and missing sender binding as open threats.

Non-negotiable invariants

• A decision is bound to one transaction digest, tab, frame, document, adapter, and review window.
• Page-controlled identifiers are never authoritative capabilities.
• The first valid terminal transition wins; replay is a no-op.
• Unrelated or stale senders cannot resolve a request.
• Worker restart cannot release a cancelled request or lose a completed decision.
• Popup close, creation failure, bridge loss, and timeout settle deterministically.
• The released XDR is byte-for-byte identical to the reviewed XDR.
• Pending state, windows, timers, and tombstones are bounded and pruned.

Required scope

A. Versioned protocol

Define runtime-validated, versioned messages. Separate page correlation IDs from extension-generated request IDs and bind immutable transaction digests, network, adapter, tab/frame/document identity, timestamps, and state.

B. Durable state machine

Implement received → validating → assessing → awaiting_review → proceed | cancel | expired | failed. Persist recoverable metadata before opening UI and add a bridge resume/status handshake because callback functions cannot survive suspension.

C. Trusted review capability

Pass only an opaque capability in the review URL. Load display state from the worker, retain windowId, validate sender context, and reject copied, expired, mismatched, or consumed capabilities.

D. Failure and concurrency semantics

Install deadlines at page, bridge, assessment, and review layers. Handle popup/tab closure, navigation, worker restart, extension update, storage failure, duplicate messages, and popup creation failure. Add per-frame and global admission limits.

E. Compatibility

Define safe behavior for stale content scripts after extension updates and browsers lacking documentId. Compatibility fallbacks must be explicit and testable.

Deliverables

• Protocol/state-machine ADR and threat-model update.
• Runtime message schemas and transaction digest binding.
• Durable pending repository, replay tombstones, and resume handshake.
• Sender/window-bound popup state API.
• Timeout, close, restart, update, and admission-control handlers.
• Developer inspection/cleanup tooling and adversarial browser tests.

Acceptance criteria

• A page observing all window messages cannot forge a proceed decision.
• Decisions from the dApp tab, options page, unrelated tab, or wrong popup are rejected.
• Copying a review URL reveals no transaction and grants no authority.
• Fifty concurrent requests using one page ID cause no overwritten state.
• Replaying a valid proceed 100 times releases the wallet request once.
• Closing the popup settles as cancellation within two seconds.
• Popup creation failure settles and clears all state.
• Worker termination during review preserves context and permits one terminal decision.
• Worker termination after proceed cannot cause a second release.
• Originating-tab navigation or closure invalidates the request.
• A missing bridge/background cannot hang beyond the absolute deadline.
• Changing one XDR byte after review causes digest rejection.
• Incompatible old content scripts receive a typed failure, not silent bypass.
• Flooding 1,000 requests respects per-frame/global bounds and does not open 1,000 windows.

Required verification

Unit and property-based state-machine tests; actual Chrome sender integration tests; multi-tab/frame Playwright tests; forced worker termination; popup/navigation/update failure injection; adversarial same-page messaging; load tests; security review. A mocked happy-path resolver test is insufficient.

Out of scope

Oracle accuracy, expanded Stellar semantics, new wallets, and protection against a compromised browser/wallet.

Dependencies and sequencing

Foundational; land before the oracle, semantic review, protection-status, and retained-record contracts stabilize.

Complexity

Extreme

Impact

Critical — forged, lost, mismatched, or hanging decisions compromise a financial signing workflow.

Suggested labels

epic architecture security reliability browser-extension state-machine production

[LuisD-Dev]

Hi! I’d like to work on this issue.

I’ve reviewed the requirements, invariants, and acceptance criteria, and I understand that this is a foundational security and reliability change rather than a localized fix. The main areas I’d focus on are the versioned request protocol, durable state-machine persistence across MV3 worker suspension, sender/window-bound review capabilities, replay protection, deterministic timeout/closure handling, and concurrency/admission controls.

I would also make sure the implementation is covered by the required adversarial and browser-level tests, especially worker termination, stale/cross-window decisions, replay attempts, navigation, popup closure, and high-concurrency scenarios.

If this issue is available, I’d be happy to take it on. Could you please assign it to me?

[fytgian]

Hi! I'd like to request assignment to this issue. I'm a full-stack developer with a strong blockchain background, and I've spent considerable time working across Web3 ecosystems — building dApps, integrating wallets, writing smart contracts, and shipping polished user experiences on top of them. What excites me about this issue is that it sits right in the intersection of the work I enjoy most. I'll approach it carefully: study the existing patterns, mirror the project's style, write proper tests, and open a PR that reviewers can walk through easily. Kindly assign it to me and I'll get to work.

[james2177]

Understanding of the problem

The current flow treats page-supplied identifiers as authoritative and keeps decision state in ephemeral, unbound structures — an in-memory Map keyed only by request ID, popup results that are never retained, and a DECISION_MADE handler that resolves purely by ID with no sender/tab/frame/window binding. Combined with MV3 service worker suspension (which can wipe that Map mid-flow) and transaction data passed through popup query params, this creates concrete forgery, replay, and hang vectors that the existing docs/threat-model.md already flags as open.

The fix isn't a patch to the current message flow — it's replacing the trust model entirely: every decision needs to be cryptographically/structurally bound to one transaction digest, one tab/frame/document, one adapter, and one review window, with durable state that survives worker restarts and a state machine where only the first valid terminal transition can win.

Proposed approach

I'll work through this in the same order as the required scope (A→E), since B (durable state machine) depends on A (protocol schema) existing first, and C/D depend on B being in place.

Phase 1 — Protocol & schema (Scope A)
Define versioned, runtime-validated message schemas (I'd use a schema validator like zod or a hand-rolled runtime guard, whichever the existing codebase leans toward) for every message crossing the page → bridge → background → popup boundary.
Separate page correlation IDs (untrusted, page-controlled, used only for UX matching) from extension-generated request IDs (authoritative, generated in the background worker, never derived from anything page-controlled).
Bind each request ID at creation time to: transaction digest (hash of the XDR itself, not a reference to it), network, wallet adapter identity, tab ID, frame ID, documentId (with a fallback path for browsers lacking it, per Scope E), and a creation timestamp.
Phase 2 — Durable state machine (Scope B)
Implement the received → validating → assessing → awaiting_review → {proceed | cancel | expired | failed} machine as its own module, independent of message-passing code, so it can be property-tested in isolation.
Persist recoverable metadata (state, bindings, digest, deadlines) to chrome.storage.session (or equivalent durable-but-ephemeral store) before opening the popup — not after — so a worker suspension between "decided to open popup" and "popup opened" can't lose the request.
Add a bridge resume/status handshake: on worker wake, the bridge re-announces itself and the background worker replies with current state for any pending request tied to that tab/frame, rather than assuming in-memory continuity.
Phase 3 — Trusted review capability (Scope C)
Replace query-param transaction data with an opaque, single-use capability token in the review URL. The popup calls back into the worker to fetch actual display state — it never trusts what's in its own URL.
Validate on every capability use: sender context matches the bound tab/frame/window, the capability hasn't been consumed, hasn't expired, and matches the windowId that was recorded when the popup was created.
Reject (not silently ignore) copied URLs, replayed capabilities, and mismatched senders — each with a distinct typed failure so this is testable.
Phase 4 — Failure & concurrency semantics (Scope D)
Install deadlines at each layer (page-post, bridge-relay, assessment, review) so a missing bridge/background can't hang past an absolute ceiling.
Add chrome.windows.onRemoved and chrome.tabs.onRemoved/onUpdated (navigation) handlers that settle the request as cancellation deterministically — within the 2-second bound in the acceptance criteria.
Add per-frame and global admission limits (bounded pending-request count) so a flood of requests can't open unbounded windows or exhaust memory — with tombstones for completed/cancelled requests so replay is a guaranteed no-op, pruned on a cadence so they don't grow unbounded either.
Phase 5 — Compatibility (Scope E)
Define explicit, typed failure behavior for stale content scripts talking to an updated background script (version mismatch in the schema itself makes this straightforward — reject unknown/unversioned messages rather than best-effort parsing them).
Add a fallback identity scheme for browsers lacking documentId, and mark it explicitly as a fallback (not silently equivalent) so tests can target it directly.
Deliverables I'll produce
ADR documenting the protocol/state-machine design + updated docs/threat-model.md reflecting which threats are now closed and why.
Runtime-validated message schemas + transaction digest binding logic.
Durable pending-request repository, replay tombstone store, and bridge resume/status handshake.
Sender- and window-bound popup state API (capability issuance/validation).
Timeout, popup-close, worker-restart, extension-update, and admission-control handlers.
A small developer inspection/cleanup CLI or debug panel for pending state (for maintainer confidence, and for debugging the adversarial tests below).
Adversarial browser test suite: forced worker termination mid-flow, multi-tab/frame Playwright scenarios, popup creation failure injection, replay flooding, and navigation/close races — explicitly not just a mocked happy-path resolver test.
How I'll verify against the acceptance criteria

I'll treat the acceptance-criteria checklist as literal test cases rather than a description to satisfy loosely:

Forgery attempts (page observing all window.postMessage traffic) get a dedicated adversarial test that tries to construct a proceed message from observed traffic alone.
Cross-tab/cross-window decision rejection, capability-copy tests, and the 50-concurrent-same-page-ID test get property-based / fuzzed test generation rather than a handful of hardcoded cases, since the state machine's core guarantee (first valid terminal transition wins, replay is a no-op) is exactly the kind of invariant that benefits from randomized interleavings.
Worker-termination tests will use Chrome's actual service worker suspension (via chrome.runtime test harness / forced eviction), not a simulated stand-in, since that's the gap the issue explicitly calls out as under-tested currently.
I'll benchmark the flood-admission-control path (1,000 concurrent requests) and report actual window-open counts and memory bounds, not just "it didn't crash."
Notes on scope discipline

I'll keep this PR (or PR series, given the size) strictly to what's listed under "Required scope" — oracle accuracy, expanded Stellar semantics, new wallet support, and compromised-browser protection are explicitly out of scope per the issue, and I won't fold in unrelated refactors. Given the "Extreme" complexity label, I'd expect to split this into a few sequenced PRs (protocol/schema first, state machine second, popup capability + failure handling third, compatibility + adversarial test suite last) rather than one large diff, so each can be reviewed against its own slice of the acceptance criteria — happy to adjust that sequencing if the maintainer prefers a different split.

[grantfox-oss]

🦊 GrantFox — @james2177 has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #124)
2. Your PR will be reviewed by the Gryd-lock maintainers

Good luck! Track your progress on GrantFox.