Add Stripe Checkout harness and provider planning

[mickmister]

Summary

This PR turns FullCircle toward an agent-friendly external-service harness by adding a first Stripe Checkout provider slice, signed Stripe webhook delivery helpers, dogfood coverage with a SQLite-backed sample app, and planning docs for Stripe and Soundspace.

What changed

• Added a Stripe provider harness in packages/harness/src/providers/stripe.ts with support for:
  • creating deterministic Checkout Session fixtures
  • retrieving Checkout Session fixtures
  • returning Checkout Session line-item fixtures
  • delivering signed Stripe webhook events and ordered webhook sequences
• Hardened the core harness request path matching so mocks can match requests with query strings, such as Stripe expand[] parameters.
• Added request body parsing for form-encoded and JSON requests in the FullCircle harness server.
• Fixed passthrough bookkeeping so passthrough registrations are tracked separately from mocks.
• Added Stripe provider tests for Checkout Session matching, retrieval, line items, webhook signatures, invalid/missing signature modes, and webhook ordering.
• Added a dogfood acceptance test that exercises a miniature billing app end-to-end:
  • user starts on a Free plan
  • app creates a Stripe Checkout Session through FullCircle
  • FullCircle sends a signed checkout.session.completed webhook
  • app updates a SQLite database
  • test verifies UI state and inserted-row diffs
• Added documentation:
  • Stripe Checkout subscription flow spec for API calls, webhook events, fixture requirements, and implementation checklist
  • Soundspace provider case study covering external service inventory, fixture plans, app seams, and resource/DB injection strategy
  • branch review with concerns and recommended follow-up work
• Updated the test script to run Jest serially before the example app tests, avoiding fixed-port races.

Why

FullCircle is intended to bridge e2e tests and imported provider clients in application servers, so tests can control third-party communications without relying on sandbox keys or ad hoc mocks below the SDK boundary.

The first productization slice focuses on Stripe Checkout subscriptions because it exercises the key capabilities FullCircle needs for real apps:

• matching SDK-originated HTTP requests at the provider boundary
• returning deterministic provider fixtures
• simulating provider-to-app webhook callbacks with valid signatures
• verifying application-visible behavior and database side effects

The Soundspace research and case-study docs capture the broader target: agents should be able to identify third-party dependencies, put them behind FullCircle sessions/providers, inject resource usage, and use database snapshots/diffs while writing e2e tests.

Important implementation details

• Stripe request matching currently supports selected Checkout Session form fields and metadata. The branch review documents follow-up work to expand this for Soundspace's embedded Checkout contract (client_secret, ui_mode, return_url, customer, multiple line items, trials, and promotion codes).
• Webhook delivery signs payloads with Stripe-compatible HMAC-SHA256 Stripe-Signature headers and supports valid, invalid, and missing signature modes for positive and negative tests.
• The dogfood acceptance test intentionally uses SQLite to validate the desired database snapshot/diff direction, while the Soundspace plan notes that Postgres/Supabase adapters will be needed for real Soundspace dogfooding.
• await using is used in tests for reliable harness cleanup and assertion execution; the review recommends adding callback-style helper APIs for older JS/TS projects and agent-generated tests.

Validation

• npm test
• npm run build

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	supertest@​6.3.4
	@​types/​better-sqlite3@​7.6.13
	@​types/​node-fetch@​2.6.9 ⏵ 2.6.13	+1
	@​types/​jest@​29.5.8 ⏵ 29.5.14
	@​types/​node@​20.19.43
	ts-node@​10.9.2
	tsup@​8.0.1 ⏵ 8.5.1	+1	+1	+1
	better-sqlite3@​12.11.1
	typescript@​5.9.3
	ts-jest@​29.4.11

View full report

[socket-security]

Warning

Review the following alerts detected in dependencies.

According to your organization's Security Policy, it is recommended to resolve "Warn" alerts. Learn more about Socket for GitHub.

Action	Severity	Alert  (click "▶" to expand/collapse)
Warn		Obfuscated code: npm @noble/hashes is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: pnpm-lock.yaml → npm/supertest@6.3.4 → npm/@noble/hashes@1.8.0 ℹ Read more on: This package | This alert | What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/@noble/hashes@1.8.0. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		Obfuscated code: npm @noble/hashes is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: pnpm-lock.yaml → npm/supertest@6.3.4 → npm/@noble/hashes@1.8.0 ℹ Read more on: This package | This alert | What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/@noble/hashes@1.8.0. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		Obfuscated code: npm better-sqlite3 is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: package.json → npm/better-sqlite3@12.11.1 ℹ Read more on: This package | This alert | What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/better-sqlite3@12.11.1. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		Obfuscated code: npm yargs is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: pnpm-lock.yaml → npm/jest@29.7.0 → npm/yargs@17.7.3 ℹ Read more on: This package | This alert | What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/yargs@17.7.3. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.

View full report