Quick start
There are two entry points. The first requires no account and no server. The second creates a persistent workspace for connected reconciliation.
- Local audit: open /audit, load a Stripe subscription export and an entitlement export, then review the findings. The files stay in the browser tab.
- Workspace: create an account at /auth. If email confirmation is enabled, confirm the address before signing in.
- Workspace setup: open Settings, create a workspace, then connect a Stripe TEST key or create a Supabase integration.
- First reconciliation: open Monitoring and run reconciliation after both sources report a complete snapshot.
Fail-closed configuration
CSV audit
The browser audit accepts comma-, semicolon-, or tab-separated files. It maps common header variants automatically and lets you correct the mapping before reconciliation.
Stripe side
At minimum, provide a customer identifier and a subscription status. Optional fields improve the comparison: subscription ID, price or plan, current period end, cancel-at-period-end, and quantity.
Entitlement side
Provide a stable user or customer identifier and the access state. Optional fields include plan, entitlement expiry, and seat count.
Privacy
Parsing and reconciliation run in the tab. The audit does not upload the file content. Exporting the result creates a local CSV download. Closing or reloading the tab clears the parsed data.
CSV injection
Stripe connection
The connected source is a Stripe restricted key. The backend verifies read access to customers, subscriptions, invoices, products, and prices before storing the encrypted credential.
# Expected key shape
rk_test_...
# Required read permissions
customers: read
subscriptions: read
invoices: read
products: read
prices: read
# Not accepted in this build
sk_live_...
rk_live_...
sk_test_... (use a restricted key)The connection is deliberately test-only. The platform billing key check also rejects anything that does not begin with sk_test_.
Disconnect and rotate
Replacing a key overwrites the encrypted secret and records the change. Disconnecting a source stops future reads. Historical snapshots remain until a workspace owner erases them.
Supabase connector
The connector runs in the customer’s Supabase project. It exports a narrow entitlement shape and signs the exact request body. SubSync Guard stores the integration secret encrypted and verifies the signature with HMAC-SHA256.
Required headers
x-integration-id: <integration uuid>
x-timestamp: <13-digit unix milliseconds>
x-nonce: <cryptographically random, unique per request>
x-signature: <hex HMAC-SHA256>
signed material = timestamp + "." + nonce + "." + rawBodyPayload shape
{
"complete": true,
"snapshot_at": "2026-11-14T20:02:00.000Z",
"row_count": 842,
"rows": [
{
"user_id": "usr_01",
"stripe_customer_id": "cus_123",
"is_premium": true,
"plan": "pro",
"access_expires_at": null
}
]
}The receiver rejects missing signatures, timestamps outside the acceptance window, reused nonces, oversized bodies, and row counts that do not match the accepted rows. A nonce is inserted under a unique constraint in the same transaction as the snapshot write.
Rotation
Create the replacement secret, update the customer-side signer, verify a successful snapshot, then revoke the old secret. Do not rotate the platform encryption key casually; existing ciphertext depends on it.
The repository contains an example connector under examples/. It is a starting point, not a managed agent. The customer remains responsible for scheduling, monitoring, and securing their deployment.
Findings and policy
A finding is a durable record, not a transient notification. Each record includes a stable fingerprint, both source identifiers, billing and access states, snapshot times, the policy applied, a priority, a reason, a recommended next step, a status, and reviewer notes.
Priorities
- High: paid or entitled but blocked, or access that clearly outlives a terminated subscription.
- Review: ambiguous mapping, plan mismatch, stale snapshot, or a likely manual grant.
- Info: context that does not require action, such as a resolved historical case.
Statuses
- Open: detected in a complete run and awaiting review.
- Investigating: a reviewer is checking identity, policy, or the source record.
- Resolved: the underlying record was corrected in the system that owns it.
- Ignored: a documented exception with a reason and, ideally, an expiry.
The reconciliation engine is deterministic. It does not learn from previous reviews or silently suppress a category. Policy decisions are written into the comparison and versioned with the finding.
Alerts
Alerts are optional and route findings after reconciliation. Supported destinations are email, Slack incoming webhooks, and custom HTTPS webhooks whose hostname is approved by the deployment administrator.
# Backend secrets for email delivery
RESEND_API_KEY=re_...
EMAIL_FROM=SubSync Guard <alerts@your-domain.example>
# Administrator allowlist for custom webhooks
ALERT_WEBHOOK_ALLOWED_HOSTS=events.example.com,ops.example.netEach destination has a minimum priority and can be tested from the interface. A saved destination is not proof of delivery; the test send is. Slack destinations must use hooks.slack.com/services/ URLs.
Team and roles
Workspace roles are owner, admin, analyst, and viewer. Owners control billing settings and destructive actions. Admins manage connections, monitoring, alerts, findings, and invitations for analysts and viewers. Analysts review findings and run reconciliation. Viewers read.
Invitations
- An owner or admin invites an email address and chooses a role.
- The API creates a single-use token with a seven-day expiry and returns a copyable invitation link.
- The recipient signs in with the invited email address and opens
/invite/<token>. - The server verifies the authenticated email against the invitation before adding the member.
Invitation tokens are not exposed through the client table grant. The invitation link is a bearer credential; send it over a private channel and revoke it if it is exposed.
Data export and deletion
A workspace owner can export a JSON bundle containing findings, snapshot metadata, and sync runs. The export does not include encrypted connector secrets.
Deletion supports three scopes: findings only, snapshots only, or all audit data. Deletion is permanent. Workspace deletion requires typing the workspace name and removes the workspace and its dependent records.
Back up before erasing
Known limits
- Stripe live mode is disabled. Only TEST connections and a TEST platform key are accepted.
- There is no public API, API key program, SSO, or SCIM.
- No automatic remediation, access revocation, refund, or subscription change exists.
- Scheduled reconciliation depends on a configured cron secret and deployed function; the scheduling itself is an operator responsibility.
- Cross-tenant RLS behavior has not been verified against a live staging database in this release candidate. Treat the migration as code-reviewed, not production-certified.
- No SOC 2, ISO 27001, PCI DSS, or penetration-test report exists.
- No uptime SLA or support response SLA is offered.
- Commercial pricing and paid plans are not active.
Troubleshooting
“Configuration Required” instead of the app
The build is missing VITE_SUPABASE_URL or VITE_SUPABASE_PUBLISHABLE_KEY. Protected routes fail closed by design. Set both variables and rebuild; do not add a demo bypass.
“Please sign in again”
The workspace API could not obtain a valid access token. Sign out, sign in again, and confirm the Supabase project URL and publishable key belong to the same project as the Edge Functions.
Invitation fails
Confirm the signed-in email exactly matches the invited address, the token has not expired, the token has not already been accepted, and the production-hardening migration has been applied.
Stripe key rejected
Use a restricted test key beginning with rk_test_ and grant read access to all five required resources. A successful key prefix is not a permission check; the backend performs a real read against each resource.
Alert test fails
Email requires RESEND_API_KEY and EMAIL_FROM. Slack requires a valid incoming webhook. Custom webhooks require an allowlisted hostname. Check the function logs for the provider response, not the browser console.
CSV import fails
Export a fresh file with a header row and at least one data row. Remove duplicate or blank column names. Check that the delimiter is consistent.
Deployment procedure
Deployment is an operator procedure and is not proven by this documentation. The repository includes docs/DEPLOYMENT_WINDOWS.md, docs/ARCHITECTURE.md, and docs/SECURITY.md for the full sequence.
# Local verification
npm ci
npm run typecheck
npm test
npm run build
# Supabase migrations: apply the additive hardening migration deliberately.
# Do not replay the initial schema against a populated database.
# Do not run "supabase db push" without reviewing the diff.
# Edge Functions (names)
workspace-api
reconcile-workspace
stripe-sync
supabase-ingest
cron-sync
alerts-dispatch
stripe-billing-webhookRequired backend secrets include SUPABASE_URL, a server secret key, APP_BASE_URL, CREDENTIAL_ENCRYPTION_KEY, and SYNC_CRON_SECRET. Stripe, email, and alert variables are required only for the corresponding features. Never place a service-role key in a VITE_ variable.
Documentation last reviewed 2026-11-14