QuickBooks Online connection foundation #161

Summary

Build the complete QuickBooks Online (QBO) connection foundation so the app can securely connect to Deep Dive Brewing's QuickBooks Online company and later sync Stripe/tour/ad-hoc transactions into QBO (follow-up to the payments work in #155/#156).

Scope

• Intuit OAuth 2.0 authorization-code flow (connect, callback, disconnect/revoke, reconnect) with strong single-use, short-lived, admin-bound state
• Sandbox vs production environment separation (explicit QBO_ENVIRONMENT, distinct Intuit credentials, fail-closed)
• Secure token lifecycle: AES-GCM-encrypted token storage in a server-only Firestore collection, rotating refresh-token handling, race-safe refresh
• Company/realm connection state with CompanyInfo verification
• Admin integration surface at /admin/integrations/quickbooks (connect/test/disconnect, health badge, environment badge)
• Narrow server-only QBO API client boundary with provider error normalization
• Webhook receiver at POST /api/webhooks/quickbooks with intuit-signature HMAC-SHA256 verification and durable dedupe
• Read-only discovery APIs (CompanyInfo, Account, Item, Customer, PaymentMethod) for future transaction mapping
• Accounting-mapping configuration model (no hard-coded QBO IDs)
• Forward-compatible sync state model + enqueue contract for the future Stripe→QBO export
• Firestore security rules (deny-all for credential/webhook/mapping/sync collections) + tests
• Operational setup documentation (Intuit Developer Portal, Vercel env scopes, webhook config)

Explicitly out of scope

• Final Stripe-payment→QBO accounting mapping (SalesReceipt vs Invoice+Payment vs summarized journal/deposit) — decided in a follow-up once the accounting policy is chosen and feat(admin): Stripe payment tool for tours and ad-hoc charges (#155) #156 is merged. No bookkeeping transactions are created by this work.

Security notes

• All Intuit credentials are server-only; tokens are encrypted at rest and never serialized to clients.
• Admin routes reuse requireAdminActor; the OAuth callback trusts only the validated one-time state.
• New Firestore collections are deny-all to clients; all access flows through admin API routes.