Supercheck integrations and extensions

Recorder architecture

The recorder is an Apache-2.0 browser extension built from Playwright CRX and vendored Playwright source. Supercheck-specific app integration lets users record browser interactions and save generated Playwright tests.

sequenceDiagram
  participant App as Supercheck app
  participant Page as Trusted page API
  participant CS as Content script
  participant BG as Extension worker
  App->>Page: validated connection/recording request
  Page->>CS: exact-origin window message
  CS->>BG: validated extension message
  BG-->>CS: state or generated recording
  CS-->>Page: sender-bound response
  Page-->>App: validated result

Source and build map

Security contract

• The page bridge/content script accepts only event.source === window, parsed allowed origins, expected protocol/hostname, and schema-valid messages.
• Allow exactly the configured instance origin (localhost only when it is the configured instance URL) plus the pinned cloud origins; never arbitrary HTTP/HTTPS pages, wildcard subdomains, or a blanket localhost allowance.
• Use window.location.origin or another verified exact origin as postMessage target; never * for privileged data.
• Bind return/callback URLs to the verified sender origin and restrict navigated/recorded target protocols.
• Inject the page API only on trusted Supercheck pages. Do not add broad externally_connectable access.
• Keep extension permissions/host permissions minimal and validate all background/content/page boundaries independently.
• Retry only idempotent API methods and preserve authentication/error behavior without exposing tokens.

Licensing and release

• Preserve recorder/LICENSE, recorder/NOTICE, recorder/playwright/LICENSE, recorder/playwright/NOTICE, and upstream file headers.
• Do not relicense Playwright-derived recorder files as AGPL. App, worker (including Private Agent mode), and docs remain AGPL-3.0-only. CLI releases from 0.3.1 are Apache-2.0.
• The vendored source must be enough for a clean reproducible build without another private checkout.
• Build lint, vendored bundles, generated types, CRX library, recorder/TodoMVC examples, and test extension.
• Unit security runs on PRs; the recorder browser suite runs weekly (Mondays 04:30 UTC) and on-demand as a release gate. Local browser fixture limitations must be disclosed; CI/Linux and manual installed-extension acceptance remain release gates.
• Chrome and Edge store descriptions/assets/certification are separate. Edge submission copy must not describe the product as a Chrome extension.
• Store publishing requires manual account/2FA/reviewer gates and uses canonical listing IDs/URLs from current public docs.

Polar billing

flowchart LR
  ORG[Organization] --> CUSTOMER[Organization-scoped customer]
  CUSTOMER --> SUB[Subscription lifecycle]
  CHECKOUT[Checkout] --> SUB
  WEBHOOK[Verified webhook] --> LEDGER[Idempotent local state]
  USAGE[Durable usage event] --> PROVIDER[Polar meter/event]
  SUB --> ENT[Server-side entitlements]

• Polar customer identity is organization-scoped, using the current organization external identity. Never collapse multiple organizations under a user-scoped customer.
• Checkout and customer portal requests authenticate the user, resolve the organization, authorize billing management (normally organization owner), and use configured product/price references.
• Webhooks verify signatures, deduplicate by provider event identity, tolerate retries/reordering, and update local state transactionally/idempotently.
• Subscription status, plan, period, cancellation, and entitlement behavior come from durable server state synchronized from verified provider events.
• Entitlements and limits are enforced server-side. UI labels/buttons are not authorization.
• Usage is durably recorded server-side before or atomically with provider delivery and retried safely without duplicate billing.
• Use whole-cent currency arithmetic and explicit units. Never rely on floating-point money or silently mix credits/events/cents.
• Polling stops on success, terminal failure, cancellation/navigation, and timeout.
• Never automatically mutate live products/prices, attach overage prices, migrate customers, or make paid actions without explicit authorization and invoice/recovery analysis.
• Provider product IDs, prices, tax settings, limits, and UI are drift-prone; verify them in the provider environment.

Billing acceptance

• Test organization isolation, shared-user/multiple-org customer identity, checkout, webhook replay/reordering, upgrade/downgrade, cancellation, expiry, recovery, portal, invoice, usage retries, and entitlement transitions.
• Automated/local tests do not replace sandbox/live provider acceptance and invoice inspection.

Customer support chat and third parties

• Load support scripts only when configured; no consent-gate mechanism exists today.
• Keep tokens and identity-verification secrets server-side. Do not send tenant secrets, auth tokens, sensitive route data, or private incident content to chat by default.
• Polar is the only signature-verified inbound provider today; support-chat webhooks are not implemented. Apply signature verification, payload validation, rate limiting, and idempotency to any new callback.
• Provider plan, branding, pricing, privacy, and hosting claims change; verify current terms before product decisions.

Verify

• Test every trust boundary and cross-tenant denial.
• Test provider retries, malformed/signed-invalid callbacks, cancellation, cleanup, and redaction.
• Separate source/unit evidence from browser store, provider account, invoice, and production acceptance.