@simplelayer/graniteer-core 0.2.0 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (124) hide show
  1. package/index.js +2 -2
  2. package/package.json +1 -1
  3. package/src/agreementCheckout.ts +250 -250
  4. package/src/agreementPortalEmail.ts +128 -128
  5. package/src/billingPortalLinkEmail.ts +117 -117
  6. package/src/bookingAgreementEmail.ts +149 -149
  7. package/src/bookingEffects.ts +388 -388
  8. package/src/busClient.ts +268 -268
  9. package/src/busSignature.ts +71 -71
  10. package/src/checkoutCoupon.test.ts +675 -675
  11. package/src/checkoutCoupon.ts +455 -455
  12. package/src/commonsDeposit.ts +298 -298
  13. package/src/commonsDepositWebhook.ts +237 -237
  14. package/src/dayPassConfirmation.ts +230 -230
  15. package/src/dunningEmails.test.ts +263 -263
  16. package/src/dunningEmails.ts +203 -203
  17. package/src/email-templates/brand.ts +93 -93
  18. package/src/email-templates/magic-link.tsx +59 -59
  19. package/src/email-templates/recovery.tsx +59 -59
  20. package/src/email-templates/signup.tsx +67 -67
  21. package/src/functions/admin-cancel-membership.ts +311 -311
  22. package/src/functions/admin-change-membership-plan.ts +312 -312
  23. package/src/functions/admin-charge-guest-print.ts +229 -229
  24. package/src/functions/admin-correct-booking.ts +333 -333
  25. package/src/functions/admin-create-booking.ts +460 -460
  26. package/src/functions/admin-create-commons-event.ts +244 -244
  27. package/src/functions/admin-debug-boldsign-doc.ts +93 -93
  28. package/src/functions/admin-door-write.ts +272 -272
  29. package/src/functions/admin-issue-day-pass.ts +231 -231
  30. package/src/functions/admin-mark-booking-paid.ts +203 -203
  31. package/src/functions/admin-mint-billing-portal-link.ts +168 -168
  32. package/src/functions/admin-mint-portal-link.ts +62 -62
  33. package/src/functions/admin-photo-upload.ts +128 -128
  34. package/src/functions/admin-remove-team-member.ts +150 -150
  35. package/src/functions/admin-request-trial.ts +366 -366
  36. package/src/functions/admin-resend-commons-deposit-link.ts +323 -323
  37. package/src/functions/admin-reset-mfa.ts +138 -138
  38. package/src/functions/admin-retry-invoice-payment.ts +333 -333
  39. package/src/functions/admin-reverse-coupon-redemption.ts +98 -98
  40. package/src/functions/admin-revoke-agreement.ts +467 -467
  41. package/src/functions/admin-send-commons-agreement.ts +214 -214
  42. package/src/functions/admin-set-credit-amount.ts +123 -123
  43. package/src/functions/admin-skip-commons-contract.ts +165 -165
  44. package/src/functions/admin-undo-membership-cancel.ts +144 -144
  45. package/src/functions/admin-wall-photo-write.ts +141 -141
  46. package/src/functions/auth-email-hook.ts +259 -259
  47. package/src/functions/boldsign-sender-identity.ts +114 -114
  48. package/src/functions/booking-availability.ts +419 -419
  49. package/src/functions/booking-member-preview.ts +136 -136
  50. package/src/functions/booking-status.ts +149 -149
  51. package/src/functions/create-booking.ts +648 -648
  52. package/src/functions/create-day-pass-checkout.ts +218 -218
  53. package/src/functions/create-portal-session.ts +142 -142
  54. package/src/functions/create-subscription-checkout.test.ts +222 -222
  55. package/src/functions/create-subscription-checkout.ts +440 -440
  56. package/src/functions/day-pass-status.ts +89 -89
  57. package/src/functions/diag-webpush-test.ts +45 -45
  58. package/src/functions/event-access-admin.ts +277 -277
  59. package/src/functions/event-access-store.ts +334 -309
  60. package/src/functions/ezeep-print-webhook.ts +213 -213
  61. package/src/functions/ezeep-usage-reconcile.ts +299 -299
  62. package/src/functions/fetch-avatar-original.ts +457 -457
  63. package/src/functions/get-provider-sign-link.ts +155 -155
  64. package/src/functions/get-signing-link.ts +211 -211
  65. package/src/functions/guest-print-setup-confirm.ts +128 -128
  66. package/src/functions/guest-print-submit.ts +149 -149
  67. package/src/functions/luma-webhook.ts +165 -165
  68. package/src/functions/mcp.ts +67 -67
  69. package/src/functions/member-door-action.test.ts +1248 -1248
  70. package/src/functions/member-door-action.ts +863 -863
  71. package/src/functions/member-unifi-mapping.test.ts +516 -516
  72. package/src/functions/member-unifi-mapping.ts +206 -206
  73. package/src/functions/membership-door-sync.ts +956 -956
  74. package/src/functions/migration-collision-alert.copy.ts +232 -232
  75. package/src/functions/migration-collision-alert.test.ts +349 -349
  76. package/src/functions/migration-collision-alert.ts +232 -232
  77. package/src/functions/office-assignment-end.ts +146 -146
  78. package/src/functions/portal-booking-access.ts +217 -95
  79. package/src/functions/portal-list-invoices.ts +99 -99
  80. package/src/functions/portal-request-login.ts +219 -192
  81. package/src/functions/portal-resend-invite.ts +248 -248
  82. package/src/functions/portal-submit-event.ts +168 -168
  83. package/src/functions/print-billing-recover.ts +97 -97
  84. package/src/functions/print-billing-run.ts +183 -183
  85. package/src/functions/public-facts.ts +168 -168
  86. package/src/functions/push-send.ts +348 -348
  87. package/src/functions/push-test.ts +234 -234
  88. package/src/functions/request-portal-link.ts +211 -211
  89. package/src/functions/review-ratings.ts +113 -113
  90. package/src/functions/space-availability-range.acceptance.test.ts +161 -161
  91. package/src/functions/space-availability-range.ts +142 -142
  92. package/src/functions/stripe-db-reconcile.ts +319 -319
  93. package/src/functions/stripe-webhook.moved-regression.test.ts +78 -78
  94. package/src/functions/stripe-webhook.ts +2595 -2595
  95. package/src/functions/sync-gcal-blackouts.ts +298 -298
  96. package/src/functions/timetable-event-register.ts +162 -162
  97. package/src/functions/timetable-event-status.ts +90 -90
  98. package/src/functions/timetable-spaces.ts +219 -219
  99. package/src/functions/touch-pass-reconciler.ts +689 -689
  100. package/src/functions/touch-pass-signup.ts +478 -478
  101. package/src/functions/upload-booking-display-image.ts +179 -179
  102. package/src/functions/virtual-onboarding-purge.ts +134 -134
  103. package/src/functions/virtual-onboarding-submit.ts +315 -315
  104. package/src/functions/voice-booking.ts +453 -453
  105. package/src/functions/voice-day-pass.ts +346 -346
  106. package/src/functions/voice-inquiry.test.ts +301 -301
  107. package/src/functions/voice-inquiry.ts +198 -198
  108. package/src/functions/voice-membership-signup.ts +355 -355
  109. package/src/functions/voice-tour-availability.ts +204 -204
  110. package/src/functions/voice-tour-booking.ts +429 -429
  111. package/src/ghlEventInquiry.ts +143 -143
  112. package/src/mailArrivalEmail.ts +121 -121
  113. package/src/manageToken.ts +363 -363
  114. package/src/membershipBusClient.ts +537 -537
  115. package/src/membershipWelcome.ts +683 -683
  116. package/src/migrationCheckout.ts +366 -366
  117. package/src/paymentLinkEmail.ts +123 -123
  118. package/src/signedUnpaidReminderEmail.test.ts +246 -246
  119. package/src/signedUnpaidReminderEmail.ts +132 -132
  120. package/src/stripeCoworkingPortal.ts +91 -91
  121. package/src/supabaseTestFakes.ts +131 -131
  122. package/src/supportTicketEmail.ts +119 -119
  123. package/src/unifiAccessPolicies.ts +228 -228
  124. package/src/unifiGroups.ts +129 -129
@@ -1,478 +1,478 @@
1
- // supabase/functions/touch-pass-signup/index.ts
2
- //
3
- // Member-initiated signup for the Touch Pass add-on (Apple/Google Wallet tap
4
- // credential, $5/mo, Commons front + Midtown doors only). Implements
5
- // touch-pass-addon-plan-v1.md v7 §2 steps 1, 2, 4, 5 exactly.
6
- //
7
- // STANDING REQUIREMENT (Kyle): this add-on is opt-in ONLY. This function is the
8
- // ONLY code path anywhere that may set touch_pass_addon_status = 'pending'.
9
- // membership_enforce.py / membership_revoke.py on ftw-middleware are forbidden
10
- // from calling unifi.assign_touch_pass -- see the plan's "why this is riskier
11
- // than it looks" section. Nothing about this function's existence changes that;
12
- // it is itself gated behind TOUCH_PASS_ENABLED + an allowlist below, matching
13
- // the staged-rollout discipline (flag off -> dry run -> one real subject ->
14
- // leave on) used elsewhere in this codebase (see member-door-action/index.ts).
15
- //
16
- // Money-path logic (steps 1/2/4/5) was dry-run-tested against a pure-mock
17
- // harness first (touch-pass-dryrun/, 16/16 passing, vacuity-proofed) using
18
- // abstract Stripe/Supabase client interfaces. This file is the real
19
- // implementation against real Deno/Stripe/Supabase-js -- the differences from
20
- // the mock (documented inline below) are the parts that could NOT be dry-run
21
- // tested without a live Stripe call, and are flagged for extra scrutiny in
22
- // review:
23
- // - supabase-js does NOT throw on a Postgres constraint violation from
24
- // .update()/.insert() -- it returns { data, error } with error.code set.
25
- // The mock's claimPendingRow assumed a thrown exception (matching a raw
26
- // pg client); this real version checks the returned error object instead.
27
- // - stripe.invoiceItems.create requires `currency` alongside `amount` --
28
- // omitted in the design doc's pseudocode and the mock; added here.
29
- // - There is no combined "finalizeAndPay" call in the real Stripe Node/Deno
30
- // SDK -- finalizeInvoice(id) and pay(id) are two separate calls. The SCA
31
- // branch is detected primarily by the documented Stripe error `code`
32
- // (`invoice_payment_intent_requires_action`), with the less-certain
33
- // `err.payment_intent?.status === 'requires_action'` shape kept only as a
34
- // secondary/fallback clause, not the primary discriminator (round 6 fix:
35
- // the `code` field is Stripe's own documented contract for this error;
36
- // `payment_intent` presence on a thrown error is comparatively
37
- // under-verified). Neither clause has been exercised against a real live
38
- // Stripe SCA-required card in this session (Technique 1's pure-mock dry
39
- // run cannot do that) -- flag this specific branch for extra scrutiny in
40
- // review and treat it as the single least-verified piece of this file.
41
-
42
- import { createClient } from 'npm:@supabase/supabase-js@2';
43
- import Stripe from 'npm:stripe@17.5.0';
44
- import { z } from 'npm:zod@3.23.8';
45
- import { clientIp, checkRateLimit } from 'npm:@simplelayer/graniteer-core/rateLimit';
46
- import { resolvePortalSession } from 'npm:@simplelayer/graniteer-core/portalSession';
47
- import { logOps } from 'npm:@simplelayer/graniteer-core/ops';
48
-
49
- const corsHeaders = {
50
- 'Access-Control-Allow-Origin': '*',
51
- 'Access-Control-Allow-Headers': 'authorization, x-client-info, apikey, content-type',
52
- 'Access-Control-Allow-Methods': 'POST, OPTIONS',
53
- };
54
-
55
- function json(status: number, body: unknown) {
56
- return new Response(JSON.stringify(body), {
57
- status, headers: { ...corsHeaders, 'Content-Type': 'application/json' },
58
- });
59
- }
60
-
61
- // ---------------------------------------------------------------------------
62
- // Constant, defined once in this module (§2 step 8 / B1 guard). Never a price
63
- // string looked up dynamically -- the whole point of the B1 assertion (see
64
- // the standalone deploy-time check, touch-pass-b1-assert.ts) is that this
65
- // literal can be grepped and diffed against membership_plans.
66
- // ---------------------------------------------------------------------------
67
- const TOUCH_PASS_PRICE_ID = Deno.env.get('TOUCH_PASS_STRIPE_PRICE_ID') ?? '';
68
- const TOUCH_PASS_AMOUNT_CENTS = 500; // $5.00 flat -- see plan v7 §2 step 4
69
-
70
- const Body = z.object({
71
- membership_id: z.string().uuid(),
72
- });
73
-
74
- interface MembershipRow {
75
- id: string;
76
- email: string;
77
- auth_user_id: string | null;
78
- touch_pass_addon_status: string | null;
79
- touch_pass_pending_at: string | null;
80
- touch_pass_stripe_item_id: string | null;
81
- stripe_customer_id: string | null;
82
- stripe_subscription_id: string | null;
83
- }
84
-
85
- export async function handle(req: Request): Promise<Response> {
86
- if (req.method === 'OPTIONS') return new Response('ok', { headers: corsHeaders });
87
- if (req.method !== 'POST') return json(405, { ok: false, error: 'method_not_allowed' });
88
-
89
- const SUPABASE_URL = Deno.env.get('SUPABASE_URL') ?? '';
90
- const SERVICE_ROLE_KEY = Deno.env.get('SUPABASE_SERVICE_ROLE_KEY') ?? '';
91
- const stripeKey = Deno.env.get('STRIPE_SECRET_KEY') ?? '';
92
- if (!SUPABASE_URL || !SERVICE_ROLE_KEY || !stripeKey) {
93
- return json(503, { ok: false, error: 'not_configured' });
94
- }
95
-
96
- const admin = createClient(SUPABASE_URL, SERVICE_ROLE_KEY, {
97
- auth: { persistSession: false, autoRefreshToken: false },
98
- });
99
- // S-12: this pinned API version is LOAD-BEARING, not a routine pin --
100
- // `Invoice.payment_intent` (read in chargeActivationFee's SCA branch, and
101
- // in touch-pass-reconciler-index.ts's sweep) does not exist on Invoice in
102
- // current/later Stripe API versions at all (Stripe moved 3DS confirmation
103
- // off Invoice.payment_intent in later versions). Bumping this version
104
- // string without re-verifying that field's presence would silently break
105
- // SCA detection everywhere it's read in this codebase.
106
- const stripe = new Stripe(stripeKey, { apiVersion: '2024-11-20.acacia' as Stripe.LatestApiVersion });
107
-
108
- // ---- Staged-rollout gate (NEW vs. the design doc -- added to match this
109
- // codebase's own established rollout discipline: flag off -> dry run ->
110
- // one real subject -> leave on. member-door-action/index.ts is the pattern
111
- // this mirrors. Flag this addition explicitly in review: it is a safety
112
- // property added during implementation, not present in the reviewed plan
113
- // text, and should be checked for correctness on its own merits.) --------
114
- const enabledRaw = (Deno.env.get('TOUCH_PASS_ENABLED') ?? '').trim().toLowerCase();
115
- const enabled = ['1', 'true', 't', 'yes', 'y', 'on'].includes(enabledRaw);
116
- if (!enabled) return json(503, { ok: false, error: 'not_configured' });
117
- if (!TOUCH_PASS_PRICE_ID) return json(503, { ok: false, error: 'not_configured' });
118
-
119
- const allowlist = new Set(
120
- (Deno.env.get('TOUCH_PASS_ALLOWLIST') ?? '').split(/[\s,;]+/).map((s) => s.trim()).filter(Boolean),
121
- );
122
-
123
- // ---- Identity: from Supabase's own verified session, never the body ----
124
- const session = await resolvePortalSession(req, admin);
125
- if (!session) return json(401, { ok: false, error: 'unauthorized' });
126
-
127
- if (!allowlist.has(session.id)) {
128
- return json(503, { ok: false, error: 'not_configured' });
129
- }
130
-
131
- // ---- Body ----------------------------------------------------------------
132
- const raw = await req.json().catch(() => ({}));
133
- const parsed = Body.safeParse(raw);
134
- if (!parsed.success) return json(400, { ok: false, error: 'invalid_payload' });
135
- const { membership_id } = parsed.data;
136
-
137
- // ---- Rate limit, keyed on the verified sub (never email) ----------------
138
- const buckets = await Promise.all([
139
- checkRateLimit(admin, 'touch-pass-signup-ip', clientIp(req), 30, 300),
140
- checkRateLimit(admin, 'touch-pass-signup', session.id, 5, 300),
141
- ]);
142
- if (buckets.some((ok) => !ok)) return json(429, { ok: false, error: 'rate_limited' });
143
-
144
- // ===========================================================================
145
- // §2 step 1 -- claim-lock the row, keyed on gc-io's own RLS resolution order.
146
- // ===========================================================================
147
- // Uses the touch_pass_claim_pending() SQL function (SECURITY DEFINER,
148
- // EXECUTE revoked from anon/authenticated, granted only to service_role --
149
- // confirmed via has_function_privilege before this shipped) rather than a
150
- // PostgREST .or() filter string built from session.email: interpolating a
151
- // JWT-derived email into a hand-built filter expression is a real, if
152
- // narrow, injection surface (RFC 5321 technically allows a comma or
153
- // parenthesis inside a quoted-string local part), and a parameterized SQL
154
- // function closes it outright instead of relying on escaping discipline.
155
- async function claimPending(id: string): Promise<
156
- { ok: true } | { ok: false; reason: 'no_match' | 'unique_violation' }
157
- > {
158
- const { data, error } = await admin.rpc('touch_pass_claim_pending', {
159
- p_membership_id: id,
160
- p_auth_user_id: session!.id,
161
- p_email: session!.email,
162
- });
163
- if (error) throw error; // genuine DB/RPC failure -> outer catch, 500
164
- const row = Array.isArray(data) ? data[0] : data;
165
- if (row?.unique_violation) return { ok: false, reason: 'unique_violation' };
166
- if (row?.claimed) return { ok: true };
167
- return { ok: false, reason: 'no_match' };
168
- }
169
-
170
- // ===========================================================================
171
- // §2 step 2 -- resolve a stale cross-subscription blocking row via a LIVE
172
- // Stripe read, CAS-guarded DB write BEFORE the Stripe cancellation, 404
173
- // folded into "resolvable". Guard (found by the dry run, see plan v7
174
- // changelog): a blocking row with NO Stripe item yet is a live in-flight
175
- // claim, never resolved here.
176
- // ===========================================================================
177
- async function findBlockingRow(): Promise<MembershipRow | null> {
178
- const { data, error } = await admin.rpc('touch_pass_find_blocking_row', {
179
- p_exclude_id: membership_id,
180
- p_auth_user_id: session!.id,
181
- p_email: session!.email,
182
- });
183
- if (error) throw error;
184
- const rows = (data as MembershipRow[] | null) ?? [];
185
- return rows[0] ?? null;
186
- }
187
-
188
- async function resolveStaleBlockingRow(
189
- blocking: MembershipRow,
190
- ): Promise<{ ok: true } | { ok: false; reason: 'still_active' | 'cas_lost_race' }> {
191
- // Dry-run-found guard: nothing to check on Stripe if this row never got a
192
- // SubscriptionItem -- that's a live in-flight claim, not staleness.
193
- if (!blocking.touch_pass_stripe_item_id) return { ok: false, reason: 'still_active' };
194
-
195
- let resolvable = false;
196
- try {
197
- const item = await stripe.subscriptionItems.retrieve(blocking.touch_pass_stripe_item_id);
198
- // stripe-node types SubscriptionItem.subscription as `string` (expanded
199
- // form only appears when `expand` is requested, which it never is here).
200
- const subId = typeof item.subscription === 'string' ? item.subscription : undefined;
201
- if (!subId) {
202
- resolvable = true; // no parent to check -- treat like gone
203
- } else {
204
- try {
205
- const sub = await stripe.subscriptions.retrieve(subId);
206
- resolvable = sub.status === 'canceled';
207
- } catch (e) {
208
- if ((e as { statusCode?: number }).statusCode === 404) resolvable = true;
209
- else throw e;
210
- }
211
- }
212
- } catch (e) {
213
- if ((e as { statusCode?: number }).statusCode === 404) {
214
- resolvable = true; // 404 on the item itself folds into "resolvable"
215
- } else {
216
- throw e;
217
- }
218
- }
219
-
220
- if (!resolvable) return { ok: false, reason: 'still_active' };
221
-
222
- // CAS BEFORE cancel (round 5's ordering fix) -- exact-status-match WHERE
223
- // clause is the optimistic lock against §4's reconciler touching the same
224
- // row concurrently.
225
- const { data: casRows, error: casErr } = await admin
226
- .from('memberships')
227
- .update({ touch_pass_addon_status: 'canceled', touch_pass_canceled_at: new Date().toISOString() })
228
- .eq('id', blocking.id)
229
- .eq('touch_pass_addon_status', blocking.touch_pass_addon_status)
230
- .select('id');
231
- if (casErr) throw casErr;
232
- if (!casRows || casRows.length === 0) return { ok: false, reason: 'cas_lost_race' };
233
-
234
- // Only now touch Stripe. If this fails, the DB row already reads
235
- // 'canceled' -- the reconciler's Job C (forward-reconciliation pass,
236
- // touch-pass-reconciler-index.ts) finishes the Stripe-side cancel on its
237
- // next pass. Never the reverse (live row, Stripe item already gone).
238
- try {
239
- await stripe.subscriptionItems.del(blocking.touch_pass_stripe_item_id, { proration_behavior: 'none' });
240
- } catch (e) {
241
- if ((e as { statusCode?: number }).statusCode !== 404) {
242
- await logOps(admin, 'touch_pass_stale_resolution_cancel_failed', {
243
- membership_id: blocking.id, stripe_item_id: blocking.touch_pass_stripe_item_id,
244
- message: String(e).slice(0, 300),
245
- }, { severity: 'warning' });
246
- }
247
- }
248
- return { ok: true };
249
- }
250
-
251
- // ===========================================================================
252
- // §2 step 4 -- one-off $5 charge: invoice-first + InvoiceItem.invoice,
253
- // sidestepping pending_invoice_items_behavior entirely. Explicit branch on
254
- // the pay() outcome.
255
- // ===========================================================================
256
- async function chargeActivationFee(
257
- row: MembershipRow,
258
- ): Promise<
259
- | { outcome: 'paid'; stripeItemId: string; invoiceId: string; hostedInvoiceUrl?: string | null }
260
- | { outcome: 'requires_action'; stripeItemId: string; invoiceId: string; hostedInvoiceUrl?: string | null }
261
- | { outcome: 'declined'; stripeItemId: string; invoiceId: string; hostedInvoiceUrl?: string | null }
262
- > {
263
- // S-2: idempotency keys on every Stripe-mutating call in this function.
264
- // Keyed on membership_id AND touch_pass_pending_at (the timestamp step 1's
265
- // claim just set) rather than membership_id alone -- a key must be unique
266
- // PER PENDING EPISODE, not per membership, or a later signup attempt on
267
- // the same row (after a prior cancel) would replay Stripe's cached
268
- // response from the FIRST attempt (Stripe caches an idempotency key's
269
- // response for 24h) instead of creating fresh resources.
270
- const idemBase = `touch_pass:${row.id}:${row.touch_pass_pending_at ?? 'unknown'}`;
271
-
272
- const item = await stripe.subscriptionItems.create({
273
- subscription: row.stripe_subscription_id!,
274
- price: TOUCH_PASS_PRICE_ID,
275
- proration_behavior: 'none',
276
- // S-3: metadata on the SubscriptionItem itself (in addition to the
277
- // Invoice's own metadata set below) so any Stripe-side view of just the
278
- // item -- e.g. Job B's orphan scan -- can identify it without a DB join.
279
- metadata: { membership_id: row.id, feature: 'touch_pass' },
280
- }, { idempotencyKey: `${idemBase}:item` });
281
-
282
- let invoice = await stripe.invoices.create({
283
- customer: row.stripe_customer_id!,
284
- auto_advance: false,
285
- // touch_pass_stripe_item_id is stamped on the INVOICE's own metadata too
286
- // (not just the InvoiceItem's below) so the stripe-webhook diff's
287
- // invoice.payment_failed branch can cancel the right SubscriptionItem
288
- // by reading event.data.object.metadata directly, with no extra DB
289
- // round-trip and no dependency on memberships.touch_pass_stripe_item_id
290
- // having been written yet (step 5 below writes it, but a payment_failed
291
- // event racing ahead of that write must still be able to cancel).
292
- metadata: { membership_id: row.id, feature: 'touch_pass', touch_pass_stripe_item_id: item.id },
293
- }, { idempotencyKey: `${idemBase}:invoice` });
294
-
295
- // `currency` is required alongside `amount` -- absent from the design
296
- // doc's pseudocode and the mock; added here (see file header).
297
- await stripe.invoiceItems.create({
298
- customer: row.stripe_customer_id!,
299
- invoice: invoice.id,
300
- amount: TOUCH_PASS_AMOUNT_CENTS,
301
- currency: 'usd',
302
- metadata: { membership_id: row.id, touch_pass_stripe_item_id: item.id },
303
- }, { idempotencyKey: `${idemBase}:invoiceitem` });
304
-
305
- // Capture finalizeInvoice's return value (not just await it) -- it's the
306
- // finalized invoice with hosted_invoice_url populated, needed below for
307
- // S-6's requires_action/declined responses.
308
- invoice = await stripe.invoices.finalizeInvoice(invoice.id, undefined, { idempotencyKey: `${idemBase}:finalize` });
309
-
310
- try {
311
- const paid = await stripe.invoices.pay(invoice.id, undefined, { idempotencyKey: `${idemBase}:pay` });
312
- return { outcome: 'paid', stripeItemId: item.id, invoiceId: invoice.id, hostedInvoiceUrl: paid.hosted_invoice_url };
313
- } catch (e) {
314
- // Least-verified branch in this file -- see file header. Round 6 fix
315
- // (BL-3): check the documented Stripe error `code` FIRST -- Stripe's own
316
- // documented contract for this condition -- with the payment_intent
317
- // status check kept only as a secondary/fallback clause, not the
318
- // primary discriminator. Confirm this shape against a real Stripe test
319
- // card during review/staging before trusting it in prod.
320
- const stripeErr = e as { type?: string; code?: string; payment_intent?: { status?: string } };
321
- if (stripeErr?.code === 'invoice_payment_intent_requires_action'
322
- || stripeErr?.payment_intent?.status === 'requires_action') {
323
- // S-6 (partial): surface hosted_invoice_url so the client can send
324
- // the member to complete 3DS. `invoice` here is the pre-pay() object
325
- // (finalizeInvoice's return value, not re-fetched) -- its
326
- // hosted_invoice_url is populated once finalized, before pay() is
327
- // ever called, so this is available even though pay() threw.
328
- return { outcome: 'requires_action', stripeItemId: item.id, invoiceId: invoice.id, hostedInvoiceUrl: invoice.hosted_invoice_url };
329
- }
330
- if (stripeErr?.type === 'StripeCardError') {
331
- return { outcome: 'declined', stripeItemId: item.id, invoiceId: invoice.id, hostedInvoiceUrl: invoice.hosted_invoice_url };
332
- }
333
- throw e; // anything else (network, Stripe 5xx) -> outer catch, 500, no silent miscategorization
334
- }
335
- }
336
-
337
- // ===========================================================================
338
- // Orchestration
339
- // ===========================================================================
340
- try {
341
- let step1 = await claimPending(membership_id);
342
-
343
- if (!step1.ok) {
344
- // Both failure modes (plain no-match, and a caught unique-violation) fall
345
- // through to the SAME blocking-row lookup + resolution attempt -- fixed
346
- // during the dry run, see plan v7 changelog. Only resolution actually
347
- // failing results in a refusal.
348
- const blocking = await findBlockingRow();
349
- if (!blocking) {
350
- return json(409, { ok: false, error: 'not_found_or_not_eligible' });
351
- }
352
- const step2 = await resolveStaleBlockingRow(blocking);
353
- if (!step2.ok) {
354
- return json(409, {
355
- ok: false,
356
- error: step2.reason === 'still_active' ? 'already_has_touch_pass' : 'try_again',
357
- });
358
- }
359
- step1 = await claimPending(membership_id);
360
- if (!step1.ok) {
361
- return json(409, { ok: false, error: 'try_again' });
362
- }
363
- }
364
-
365
- const { data: row, error: rowErr } = await admin
366
- .from('memberships')
367
- .select('id,email,auth_user_id,touch_pass_addon_status,touch_pass_pending_at,touch_pass_stripe_item_id,stripe_customer_id,stripe_subscription_id,unifi_access_user_id')
368
- .eq('id', membership_id)
369
- .maybeSingle();
370
- if (rowErr) throw rowErr;
371
- if (!row) throw new Error('membership row vanished after successful claim');
372
- const membership = row as unknown as MembershipRow & { unifi_access_user_id: string | null };
373
-
374
- if (!membership.stripe_customer_id || !membership.stripe_subscription_id) {
375
- await admin.from('memberships').update({ touch_pass_addon_status: 'canceled' })
376
- .eq('id', membership_id).eq('touch_pass_addon_status', 'pending');
377
- return json(409, { ok: false, error: 'no_active_subscription' });
378
- }
379
-
380
- // Identity-not-verified: no auth_user_id AND no unifi_access_user_id means
381
- // this member's building profile isn't linked yet -- surface it as a
382
- // staff-visible warning (deduped once per membership via ops_events'
383
- // dedupe_key, not a separate task-queue table -- membership_admin_actions
384
- // is a billing/plan-change audit log with no open/resolved concept and no
385
- // fit for this; ops_events + logOps's dedupeKey is this codebase's actual
386
- // mechanism for "alert staff once"), then refuse the charge.
387
- if (!membership.auth_user_id && !membership.unifi_access_user_id) {
388
- await admin.from('memberships').update({ touch_pass_addon_status: 'canceled' })
389
- .eq('id', membership_id).eq('touch_pass_addon_status', 'pending');
390
- await logOps(admin, 'touch_pass_identity_not_verified', {
391
- membership_id,
392
- }, { severity: 'warning', dedupeKey: `touch_pass_identity_not_verified:${membership_id}` });
393
- return json(409, { ok: false, error: 'identity_not_verified' });
394
- }
395
-
396
- const charge = await chargeActivationFee(membership);
397
-
398
- // BL-9: CAS-guard this write -- exact-status-match plus "not already
399
- // written" -- rather than an unconditional update with no row-count
400
- // check. An unconditional update can silently no-op (0 rows) if the row
401
- // moved underfoot (e.g. the reconciler's Job A canceled it for timing out
402
- // while this Stripe round-trip was in flight) and the code would sail on
403
- // as if the ids were safely recorded when they were not.
404
- const { data: writtenRows, error: writeErr } = await admin
405
- .from('memberships')
406
- .update({ touch_pass_stripe_item_id: charge.stripeItemId, touch_pass_activation_invoice_id: charge.invoiceId })
407
- .eq('id', membership_id)
408
- .eq('touch_pass_addon_status', 'pending')
409
- .is('touch_pass_stripe_item_id', null)
410
- .select('id');
411
- if (writeErr) {
412
- // Unreachable in the ordinary case (both ids are freshly minted by
413
- // Stripe) -- a unique-constraint hit here means a retry/replay bug
414
- // cross-wired two members' rows. Fatal, alert a human, never overwrite.
415
- await logOps(admin, 'touch_pass_activation_id_write_failed', {
416
- membership_id, stripe_item_id: charge.stripeItemId, invoice_id: charge.invoiceId,
417
- message: writeErr.message,
418
- }, { severity: 'error' });
419
- return json(500, { ok: false, error: 'write_failed' });
420
- }
421
- if (!writtenRows || writtenRows.length === 0) {
422
- await logOps(admin, 'touch_pass_activation_id_write_no_match', {
423
- membership_id, stripe_item_id: charge.stripeItemId, invoice_id: charge.invoiceId,
424
- }, { severity: 'error' });
425
- return json(500, { ok: false, error: 'write_failed' });
426
- }
427
-
428
- if (charge.outcome === 'paid') {
429
- // System of record is the invoice.paid webhook (see the stripe-webhook
430
- // diff) -- this response just reflects the synchronous pay() result.
431
- return json(200, { ok: true, status: 'activating' });
432
- }
433
- if (charge.outcome === 'requires_action') {
434
- // S-6 (partial): give the client the hosted_invoice_url so the member
435
- // can be sent to complete 3DS. (The other half of S-6 -- the hard-bound
436
- // SCA escalation having no terminal disposition, i.e. what eventually
437
- // happens to a row stuck past SCA_HARD_BOUND_MS in the reconciler --
438
- // is deliberately deferred; see final report.)
439
- return json(200, { ok: true, status: 'requires_action', hosted_invoice_url: charge.hostedInvoiceUrl ?? null });
440
- }
441
- // BL-5: a synchronous decline must also cancel the Stripe item -- the
442
- // charge already created a live SubscriptionItem (see chargeActivationFee)
443
- // and the earlier version of this branch only flipped the DB row,
444
- // leaving a canceled-in-our-eyes row with a still-live Stripe item that
445
- // nothing else was guaranteed to clean up promptly. `del` failures are
446
- // non-fatal (a 404 is fine; anything else is logged, not thrown -- the
447
- // reconciler's Job C forward-reconciliation pass retries it, which is
448
- // why this UPDATE also stamps touch_pass_canceled_at -- NEW-1: Job C's
449
- // own retry filter requires that column to be non-null, and this branch
450
- // was previously leaving it NULL, making the row invisible to Job C).
451
- if (charge.outcome === 'declined') {
452
- try {
453
- await stripe.subscriptionItems.del(charge.stripeItemId, { proration_behavior: 'none' });
454
- } catch (e) {
455
- if ((e as { statusCode?: number }).statusCode !== 404) {
456
- await logOps(admin, 'touch_pass_decline_cancel_failed', {
457
- membership_id, stripe_item_id: charge.stripeItemId, message: String(e).slice(0, 300),
458
- }, { severity: 'error' });
459
- }
460
- }
461
- await admin.from('memberships').update({
462
- touch_pass_addon_status: 'canceled',
463
- touch_pass_canceled_at: new Date().toISOString(),
464
- })
465
- .eq('id', membership_id).eq('touch_pass_addon_status', 'pending');
466
- return json(200, { ok: false, status: 'declined' }); // S-14: ok:false on a failed charge
467
- }
468
- // Unreachable: chargeActivationFee's return type is exhaustively
469
- // 'paid' | 'requires_action' | 'declined', and 'paid' returned above.
470
- throw new Error(`unreachable charge outcome: ${(charge as { outcome: string }).outcome}`);
471
- } catch (e) {
472
- console.error('[touch-pass-signup] error', e);
473
- await logOps(admin, 'touch_pass_signup_error', {
474
- membership_id, actor_uid: session.id, message: e instanceof Error ? e.message : String(e),
475
- }, { severity: 'error' });
476
- return json(500, { ok: false, error: 'signup_failed' });
477
- }
478
- }
1
+ // supabase/functions/touch-pass-signup/index.ts
2
+ //
3
+ // Member-initiated signup for the Touch Pass add-on (Apple/Google Wallet tap
4
+ // credential, $5/mo, Commons front + Midtown doors only). Implements
5
+ // touch-pass-addon-plan-v1.md v7 §2 steps 1, 2, 4, 5 exactly.
6
+ //
7
+ // STANDING REQUIREMENT (Kyle): this add-on is opt-in ONLY. This function is the
8
+ // ONLY code path anywhere that may set touch_pass_addon_status = 'pending'.
9
+ // membership_enforce.py / membership_revoke.py on ftw-middleware are forbidden
10
+ // from calling unifi.assign_touch_pass -- see the plan's "why this is riskier
11
+ // than it looks" section. Nothing about this function's existence changes that;
12
+ // it is itself gated behind TOUCH_PASS_ENABLED + an allowlist below, matching
13
+ // the staged-rollout discipline (flag off -> dry run -> one real subject ->
14
+ // leave on) used elsewhere in this codebase (see member-door-action/index.ts).
15
+ //
16
+ // Money-path logic (steps 1/2/4/5) was dry-run-tested against a pure-mock
17
+ // harness first (touch-pass-dryrun/, 16/16 passing, vacuity-proofed) using
18
+ // abstract Stripe/Supabase client interfaces. This file is the real
19
+ // implementation against real Deno/Stripe/Supabase-js -- the differences from
20
+ // the mock (documented inline below) are the parts that could NOT be dry-run
21
+ // tested without a live Stripe call, and are flagged for extra scrutiny in
22
+ // review:
23
+ // - supabase-js does NOT throw on a Postgres constraint violation from
24
+ // .update()/.insert() -- it returns { data, error } with error.code set.
25
+ // The mock's claimPendingRow assumed a thrown exception (matching a raw
26
+ // pg client); this real version checks the returned error object instead.
27
+ // - stripe.invoiceItems.create requires `currency` alongside `amount` --
28
+ // omitted in the design doc's pseudocode and the mock; added here.
29
+ // - There is no combined "finalizeAndPay" call in the real Stripe Node/Deno
30
+ // SDK -- finalizeInvoice(id) and pay(id) are two separate calls. The SCA
31
+ // branch is detected primarily by the documented Stripe error `code`
32
+ // (`invoice_payment_intent_requires_action`), with the less-certain
33
+ // `err.payment_intent?.status === 'requires_action'` shape kept only as a
34
+ // secondary/fallback clause, not the primary discriminator (round 6 fix:
35
+ // the `code` field is Stripe's own documented contract for this error;
36
+ // `payment_intent` presence on a thrown error is comparatively
37
+ // under-verified). Neither clause has been exercised against a real live
38
+ // Stripe SCA-required card in this session (Technique 1's pure-mock dry
39
+ // run cannot do that) -- flag this specific branch for extra scrutiny in
40
+ // review and treat it as the single least-verified piece of this file.
41
+
42
+ import { createClient } from 'npm:@supabase/supabase-js@2';
43
+ import Stripe from 'npm:stripe@17.5.0';
44
+ import { z } from 'npm:zod@3.23.8';
45
+ import { clientIp, checkRateLimit } from 'npm:@simplelayer/graniteer-core/rateLimit';
46
+ import { resolvePortalSession } from 'npm:@simplelayer/graniteer-core/portalSession';
47
+ import { logOps } from 'npm:@simplelayer/graniteer-core/ops';
48
+
49
+ const corsHeaders = {
50
+ 'Access-Control-Allow-Origin': '*',
51
+ 'Access-Control-Allow-Headers': 'authorization, x-client-info, apikey, content-type',
52
+ 'Access-Control-Allow-Methods': 'POST, OPTIONS',
53
+ };
54
+
55
+ function json(status: number, body: unknown) {
56
+ return new Response(JSON.stringify(body), {
57
+ status, headers: { ...corsHeaders, 'Content-Type': 'application/json' },
58
+ });
59
+ }
60
+
61
+ // ---------------------------------------------------------------------------
62
+ // Constant, defined once in this module (§2 step 8 / B1 guard). Never a price
63
+ // string looked up dynamically -- the whole point of the B1 assertion (see
64
+ // the standalone deploy-time check, touch-pass-b1-assert.ts) is that this
65
+ // literal can be grepped and diffed against membership_plans.
66
+ // ---------------------------------------------------------------------------
67
+ const TOUCH_PASS_PRICE_ID = Deno.env.get('TOUCH_PASS_STRIPE_PRICE_ID') ?? '';
68
+ const TOUCH_PASS_AMOUNT_CENTS = 500; // $5.00 flat -- see plan v7 §2 step 4
69
+
70
+ const Body = z.object({
71
+ membership_id: z.string().uuid(),
72
+ });
73
+
74
+ interface MembershipRow {
75
+ id: string;
76
+ email: string;
77
+ auth_user_id: string | null;
78
+ touch_pass_addon_status: string | null;
79
+ touch_pass_pending_at: string | null;
80
+ touch_pass_stripe_item_id: string | null;
81
+ stripe_customer_id: string | null;
82
+ stripe_subscription_id: string | null;
83
+ }
84
+
85
+ export async function handle(req: Request): Promise<Response> {
86
+ if (req.method === 'OPTIONS') return new Response('ok', { headers: corsHeaders });
87
+ if (req.method !== 'POST') return json(405, { ok: false, error: 'method_not_allowed' });
88
+
89
+ const SUPABASE_URL = Deno.env.get('SUPABASE_URL') ?? '';
90
+ const SERVICE_ROLE_KEY = Deno.env.get('SUPABASE_SERVICE_ROLE_KEY') ?? '';
91
+ const stripeKey = Deno.env.get('STRIPE_SECRET_KEY') ?? '';
92
+ if (!SUPABASE_URL || !SERVICE_ROLE_KEY || !stripeKey) {
93
+ return json(503, { ok: false, error: 'not_configured' });
94
+ }
95
+
96
+ const admin = createClient(SUPABASE_URL, SERVICE_ROLE_KEY, {
97
+ auth: { persistSession: false, autoRefreshToken: false },
98
+ });
99
+ // S-12: this pinned API version is LOAD-BEARING, not a routine pin --
100
+ // `Invoice.payment_intent` (read in chargeActivationFee's SCA branch, and
101
+ // in touch-pass-reconciler-index.ts's sweep) does not exist on Invoice in
102
+ // current/later Stripe API versions at all (Stripe moved 3DS confirmation
103
+ // off Invoice.payment_intent in later versions). Bumping this version
104
+ // string without re-verifying that field's presence would silently break
105
+ // SCA detection everywhere it's read in this codebase.
106
+ const stripe = new Stripe(stripeKey, { apiVersion: '2024-11-20.acacia' as Stripe.LatestApiVersion });
107
+
108
+ // ---- Staged-rollout gate (NEW vs. the design doc -- added to match this
109
+ // codebase's own established rollout discipline: flag off -> dry run ->
110
+ // one real subject -> leave on. member-door-action/index.ts is the pattern
111
+ // this mirrors. Flag this addition explicitly in review: it is a safety
112
+ // property added during implementation, not present in the reviewed plan
113
+ // text, and should be checked for correctness on its own merits.) --------
114
+ const enabledRaw = (Deno.env.get('TOUCH_PASS_ENABLED') ?? '').trim().toLowerCase();
115
+ const enabled = ['1', 'true', 't', 'yes', 'y', 'on'].includes(enabledRaw);
116
+ if (!enabled) return json(503, { ok: false, error: 'not_configured' });
117
+ if (!TOUCH_PASS_PRICE_ID) return json(503, { ok: false, error: 'not_configured' });
118
+
119
+ const allowlist = new Set(
120
+ (Deno.env.get('TOUCH_PASS_ALLOWLIST') ?? '').split(/[\s,;]+/).map((s) => s.trim()).filter(Boolean),
121
+ );
122
+
123
+ // ---- Identity: from Supabase's own verified session, never the body ----
124
+ const session = await resolvePortalSession(req, admin);
125
+ if (!session) return json(401, { ok: false, error: 'unauthorized' });
126
+
127
+ if (!allowlist.has(session.id)) {
128
+ return json(503, { ok: false, error: 'not_configured' });
129
+ }
130
+
131
+ // ---- Body ----------------------------------------------------------------
132
+ const raw = await req.json().catch(() => ({}));
133
+ const parsed = Body.safeParse(raw);
134
+ if (!parsed.success) return json(400, { ok: false, error: 'invalid_payload' });
135
+ const { membership_id } = parsed.data;
136
+
137
+ // ---- Rate limit, keyed on the verified sub (never email) ----------------
138
+ const buckets = await Promise.all([
139
+ checkRateLimit(admin, 'touch-pass-signup-ip', clientIp(req), 30, 300),
140
+ checkRateLimit(admin, 'touch-pass-signup', session.id, 5, 300),
141
+ ]);
142
+ if (buckets.some((ok) => !ok)) return json(429, { ok: false, error: 'rate_limited' });
143
+
144
+ // ===========================================================================
145
+ // §2 step 1 -- claim-lock the row, keyed on gc-io's own RLS resolution order.
146
+ // ===========================================================================
147
+ // Uses the touch_pass_claim_pending() SQL function (SECURITY DEFINER,
148
+ // EXECUTE revoked from anon/authenticated, granted only to service_role --
149
+ // confirmed via has_function_privilege before this shipped) rather than a
150
+ // PostgREST .or() filter string built from session.email: interpolating a
151
+ // JWT-derived email into a hand-built filter expression is a real, if
152
+ // narrow, injection surface (RFC 5321 technically allows a comma or
153
+ // parenthesis inside a quoted-string local part), and a parameterized SQL
154
+ // function closes it outright instead of relying on escaping discipline.
155
+ async function claimPending(id: string): Promise<
156
+ { ok: true } | { ok: false; reason: 'no_match' | 'unique_violation' }
157
+ > {
158
+ const { data, error } = await admin.rpc('touch_pass_claim_pending', {
159
+ p_membership_id: id,
160
+ p_auth_user_id: session!.id,
161
+ p_email: session!.email,
162
+ });
163
+ if (error) throw error; // genuine DB/RPC failure -> outer catch, 500
164
+ const row = Array.isArray(data) ? data[0] : data;
165
+ if (row?.unique_violation) return { ok: false, reason: 'unique_violation' };
166
+ if (row?.claimed) return { ok: true };
167
+ return { ok: false, reason: 'no_match' };
168
+ }
169
+
170
+ // ===========================================================================
171
+ // §2 step 2 -- resolve a stale cross-subscription blocking row via a LIVE
172
+ // Stripe read, CAS-guarded DB write BEFORE the Stripe cancellation, 404
173
+ // folded into "resolvable". Guard (found by the dry run, see plan v7
174
+ // changelog): a blocking row with NO Stripe item yet is a live in-flight
175
+ // claim, never resolved here.
176
+ // ===========================================================================
177
+ async function findBlockingRow(): Promise<MembershipRow | null> {
178
+ const { data, error } = await admin.rpc('touch_pass_find_blocking_row', {
179
+ p_exclude_id: membership_id,
180
+ p_auth_user_id: session!.id,
181
+ p_email: session!.email,
182
+ });
183
+ if (error) throw error;
184
+ const rows = (data as MembershipRow[] | null) ?? [];
185
+ return rows[0] ?? null;
186
+ }
187
+
188
+ async function resolveStaleBlockingRow(
189
+ blocking: MembershipRow,
190
+ ): Promise<{ ok: true } | { ok: false; reason: 'still_active' | 'cas_lost_race' }> {
191
+ // Dry-run-found guard: nothing to check on Stripe if this row never got a
192
+ // SubscriptionItem -- that's a live in-flight claim, not staleness.
193
+ if (!blocking.touch_pass_stripe_item_id) return { ok: false, reason: 'still_active' };
194
+
195
+ let resolvable = false;
196
+ try {
197
+ const item = await stripe.subscriptionItems.retrieve(blocking.touch_pass_stripe_item_id);
198
+ // stripe-node types SubscriptionItem.subscription as `string` (expanded
199
+ // form only appears when `expand` is requested, which it never is here).
200
+ const subId = typeof item.subscription === 'string' ? item.subscription : undefined;
201
+ if (!subId) {
202
+ resolvable = true; // no parent to check -- treat like gone
203
+ } else {
204
+ try {
205
+ const sub = await stripe.subscriptions.retrieve(subId);
206
+ resolvable = sub.status === 'canceled';
207
+ } catch (e) {
208
+ if ((e as { statusCode?: number }).statusCode === 404) resolvable = true;
209
+ else throw e;
210
+ }
211
+ }
212
+ } catch (e) {
213
+ if ((e as { statusCode?: number }).statusCode === 404) {
214
+ resolvable = true; // 404 on the item itself folds into "resolvable"
215
+ } else {
216
+ throw e;
217
+ }
218
+ }
219
+
220
+ if (!resolvable) return { ok: false, reason: 'still_active' };
221
+
222
+ // CAS BEFORE cancel (round 5's ordering fix) -- exact-status-match WHERE
223
+ // clause is the optimistic lock against §4's reconciler touching the same
224
+ // row concurrently.
225
+ const { data: casRows, error: casErr } = await admin
226
+ .from('memberships')
227
+ .update({ touch_pass_addon_status: 'canceled', touch_pass_canceled_at: new Date().toISOString() })
228
+ .eq('id', blocking.id)
229
+ .eq('touch_pass_addon_status', blocking.touch_pass_addon_status)
230
+ .select('id');
231
+ if (casErr) throw casErr;
232
+ if (!casRows || casRows.length === 0) return { ok: false, reason: 'cas_lost_race' };
233
+
234
+ // Only now touch Stripe. If this fails, the DB row already reads
235
+ // 'canceled' -- the reconciler's Job C (forward-reconciliation pass,
236
+ // touch-pass-reconciler-index.ts) finishes the Stripe-side cancel on its
237
+ // next pass. Never the reverse (live row, Stripe item already gone).
238
+ try {
239
+ await stripe.subscriptionItems.del(blocking.touch_pass_stripe_item_id, { proration_behavior: 'none' });
240
+ } catch (e) {
241
+ if ((e as { statusCode?: number }).statusCode !== 404) {
242
+ await logOps(admin, 'touch_pass_stale_resolution_cancel_failed', {
243
+ membership_id: blocking.id, stripe_item_id: blocking.touch_pass_stripe_item_id,
244
+ message: String(e).slice(0, 300),
245
+ }, { severity: 'warning' });
246
+ }
247
+ }
248
+ return { ok: true };
249
+ }
250
+
251
+ // ===========================================================================
252
+ // §2 step 4 -- one-off $5 charge: invoice-first + InvoiceItem.invoice,
253
+ // sidestepping pending_invoice_items_behavior entirely. Explicit branch on
254
+ // the pay() outcome.
255
+ // ===========================================================================
256
+ async function chargeActivationFee(
257
+ row: MembershipRow,
258
+ ): Promise<
259
+ | { outcome: 'paid'; stripeItemId: string; invoiceId: string; hostedInvoiceUrl?: string | null }
260
+ | { outcome: 'requires_action'; stripeItemId: string; invoiceId: string; hostedInvoiceUrl?: string | null }
261
+ | { outcome: 'declined'; stripeItemId: string; invoiceId: string; hostedInvoiceUrl?: string | null }
262
+ > {
263
+ // S-2: idempotency keys on every Stripe-mutating call in this function.
264
+ // Keyed on membership_id AND touch_pass_pending_at (the timestamp step 1's
265
+ // claim just set) rather than membership_id alone -- a key must be unique
266
+ // PER PENDING EPISODE, not per membership, or a later signup attempt on
267
+ // the same row (after a prior cancel) would replay Stripe's cached
268
+ // response from the FIRST attempt (Stripe caches an idempotency key's
269
+ // response for 24h) instead of creating fresh resources.
270
+ const idemBase = `touch_pass:${row.id}:${row.touch_pass_pending_at ?? 'unknown'}`;
271
+
272
+ const item = await stripe.subscriptionItems.create({
273
+ subscription: row.stripe_subscription_id!,
274
+ price: TOUCH_PASS_PRICE_ID,
275
+ proration_behavior: 'none',
276
+ // S-3: metadata on the SubscriptionItem itself (in addition to the
277
+ // Invoice's own metadata set below) so any Stripe-side view of just the
278
+ // item -- e.g. Job B's orphan scan -- can identify it without a DB join.
279
+ metadata: { membership_id: row.id, feature: 'touch_pass' },
280
+ }, { idempotencyKey: `${idemBase}:item` });
281
+
282
+ let invoice = await stripe.invoices.create({
283
+ customer: row.stripe_customer_id!,
284
+ auto_advance: false,
285
+ // touch_pass_stripe_item_id is stamped on the INVOICE's own metadata too
286
+ // (not just the InvoiceItem's below) so the stripe-webhook diff's
287
+ // invoice.payment_failed branch can cancel the right SubscriptionItem
288
+ // by reading event.data.object.metadata directly, with no extra DB
289
+ // round-trip and no dependency on memberships.touch_pass_stripe_item_id
290
+ // having been written yet (step 5 below writes it, but a payment_failed
291
+ // event racing ahead of that write must still be able to cancel).
292
+ metadata: { membership_id: row.id, feature: 'touch_pass', touch_pass_stripe_item_id: item.id },
293
+ }, { idempotencyKey: `${idemBase}:invoice` });
294
+
295
+ // `currency` is required alongside `amount` -- absent from the design
296
+ // doc's pseudocode and the mock; added here (see file header).
297
+ await stripe.invoiceItems.create({
298
+ customer: row.stripe_customer_id!,
299
+ invoice: invoice.id,
300
+ amount: TOUCH_PASS_AMOUNT_CENTS,
301
+ currency: 'usd',
302
+ metadata: { membership_id: row.id, touch_pass_stripe_item_id: item.id },
303
+ }, { idempotencyKey: `${idemBase}:invoiceitem` });
304
+
305
+ // Capture finalizeInvoice's return value (not just await it) -- it's the
306
+ // finalized invoice with hosted_invoice_url populated, needed below for
307
+ // S-6's requires_action/declined responses.
308
+ invoice = await stripe.invoices.finalizeInvoice(invoice.id, undefined, { idempotencyKey: `${idemBase}:finalize` });
309
+
310
+ try {
311
+ const paid = await stripe.invoices.pay(invoice.id, undefined, { idempotencyKey: `${idemBase}:pay` });
312
+ return { outcome: 'paid', stripeItemId: item.id, invoiceId: invoice.id, hostedInvoiceUrl: paid.hosted_invoice_url };
313
+ } catch (e) {
314
+ // Least-verified branch in this file -- see file header. Round 6 fix
315
+ // (BL-3): check the documented Stripe error `code` FIRST -- Stripe's own
316
+ // documented contract for this condition -- with the payment_intent
317
+ // status check kept only as a secondary/fallback clause, not the
318
+ // primary discriminator. Confirm this shape against a real Stripe test
319
+ // card during review/staging before trusting it in prod.
320
+ const stripeErr = e as { type?: string; code?: string; payment_intent?: { status?: string } };
321
+ if (stripeErr?.code === 'invoice_payment_intent_requires_action'
322
+ || stripeErr?.payment_intent?.status === 'requires_action') {
323
+ // S-6 (partial): surface hosted_invoice_url so the client can send
324
+ // the member to complete 3DS. `invoice` here is the pre-pay() object
325
+ // (finalizeInvoice's return value, not re-fetched) -- its
326
+ // hosted_invoice_url is populated once finalized, before pay() is
327
+ // ever called, so this is available even though pay() threw.
328
+ return { outcome: 'requires_action', stripeItemId: item.id, invoiceId: invoice.id, hostedInvoiceUrl: invoice.hosted_invoice_url };
329
+ }
330
+ if (stripeErr?.type === 'StripeCardError') {
331
+ return { outcome: 'declined', stripeItemId: item.id, invoiceId: invoice.id, hostedInvoiceUrl: invoice.hosted_invoice_url };
332
+ }
333
+ throw e; // anything else (network, Stripe 5xx) -> outer catch, 500, no silent miscategorization
334
+ }
335
+ }
336
+
337
+ // ===========================================================================
338
+ // Orchestration
339
+ // ===========================================================================
340
+ try {
341
+ let step1 = await claimPending(membership_id);
342
+
343
+ if (!step1.ok) {
344
+ // Both failure modes (plain no-match, and a caught unique-violation) fall
345
+ // through to the SAME blocking-row lookup + resolution attempt -- fixed
346
+ // during the dry run, see plan v7 changelog. Only resolution actually
347
+ // failing results in a refusal.
348
+ const blocking = await findBlockingRow();
349
+ if (!blocking) {
350
+ return json(409, { ok: false, error: 'not_found_or_not_eligible' });
351
+ }
352
+ const step2 = await resolveStaleBlockingRow(blocking);
353
+ if (!step2.ok) {
354
+ return json(409, {
355
+ ok: false,
356
+ error: step2.reason === 'still_active' ? 'already_has_touch_pass' : 'try_again',
357
+ });
358
+ }
359
+ step1 = await claimPending(membership_id);
360
+ if (!step1.ok) {
361
+ return json(409, { ok: false, error: 'try_again' });
362
+ }
363
+ }
364
+
365
+ const { data: row, error: rowErr } = await admin
366
+ .from('memberships')
367
+ .select('id,email,auth_user_id,touch_pass_addon_status,touch_pass_pending_at,touch_pass_stripe_item_id,stripe_customer_id,stripe_subscription_id,unifi_access_user_id')
368
+ .eq('id', membership_id)
369
+ .maybeSingle();
370
+ if (rowErr) throw rowErr;
371
+ if (!row) throw new Error('membership row vanished after successful claim');
372
+ const membership = row as unknown as MembershipRow & { unifi_access_user_id: string | null };
373
+
374
+ if (!membership.stripe_customer_id || !membership.stripe_subscription_id) {
375
+ await admin.from('memberships').update({ touch_pass_addon_status: 'canceled' })
376
+ .eq('id', membership_id).eq('touch_pass_addon_status', 'pending');
377
+ return json(409, { ok: false, error: 'no_active_subscription' });
378
+ }
379
+
380
+ // Identity-not-verified: no auth_user_id AND no unifi_access_user_id means
381
+ // this member's building profile isn't linked yet -- surface it as a
382
+ // staff-visible warning (deduped once per membership via ops_events'
383
+ // dedupe_key, not a separate task-queue table -- membership_admin_actions
384
+ // is a billing/plan-change audit log with no open/resolved concept and no
385
+ // fit for this; ops_events + logOps's dedupeKey is this codebase's actual
386
+ // mechanism for "alert staff once"), then refuse the charge.
387
+ if (!membership.auth_user_id && !membership.unifi_access_user_id) {
388
+ await admin.from('memberships').update({ touch_pass_addon_status: 'canceled' })
389
+ .eq('id', membership_id).eq('touch_pass_addon_status', 'pending');
390
+ await logOps(admin, 'touch_pass_identity_not_verified', {
391
+ membership_id,
392
+ }, { severity: 'warning', dedupeKey: `touch_pass_identity_not_verified:${membership_id}` });
393
+ return json(409, { ok: false, error: 'identity_not_verified' });
394
+ }
395
+
396
+ const charge = await chargeActivationFee(membership);
397
+
398
+ // BL-9: CAS-guard this write -- exact-status-match plus "not already
399
+ // written" -- rather than an unconditional update with no row-count
400
+ // check. An unconditional update can silently no-op (0 rows) if the row
401
+ // moved underfoot (e.g. the reconciler's Job A canceled it for timing out
402
+ // while this Stripe round-trip was in flight) and the code would sail on
403
+ // as if the ids were safely recorded when they were not.
404
+ const { data: writtenRows, error: writeErr } = await admin
405
+ .from('memberships')
406
+ .update({ touch_pass_stripe_item_id: charge.stripeItemId, touch_pass_activation_invoice_id: charge.invoiceId })
407
+ .eq('id', membership_id)
408
+ .eq('touch_pass_addon_status', 'pending')
409
+ .is('touch_pass_stripe_item_id', null)
410
+ .select('id');
411
+ if (writeErr) {
412
+ // Unreachable in the ordinary case (both ids are freshly minted by
413
+ // Stripe) -- a unique-constraint hit here means a retry/replay bug
414
+ // cross-wired two members' rows. Fatal, alert a human, never overwrite.
415
+ await logOps(admin, 'touch_pass_activation_id_write_failed', {
416
+ membership_id, stripe_item_id: charge.stripeItemId, invoice_id: charge.invoiceId,
417
+ message: writeErr.message,
418
+ }, { severity: 'error' });
419
+ return json(500, { ok: false, error: 'write_failed' });
420
+ }
421
+ if (!writtenRows || writtenRows.length === 0) {
422
+ await logOps(admin, 'touch_pass_activation_id_write_no_match', {
423
+ membership_id, stripe_item_id: charge.stripeItemId, invoice_id: charge.invoiceId,
424
+ }, { severity: 'error' });
425
+ return json(500, { ok: false, error: 'write_failed' });
426
+ }
427
+
428
+ if (charge.outcome === 'paid') {
429
+ // System of record is the invoice.paid webhook (see the stripe-webhook
430
+ // diff) -- this response just reflects the synchronous pay() result.
431
+ return json(200, { ok: true, status: 'activating' });
432
+ }
433
+ if (charge.outcome === 'requires_action') {
434
+ // S-6 (partial): give the client the hosted_invoice_url so the member
435
+ // can be sent to complete 3DS. (The other half of S-6 -- the hard-bound
436
+ // SCA escalation having no terminal disposition, i.e. what eventually
437
+ // happens to a row stuck past SCA_HARD_BOUND_MS in the reconciler --
438
+ // is deliberately deferred; see final report.)
439
+ return json(200, { ok: true, status: 'requires_action', hosted_invoice_url: charge.hostedInvoiceUrl ?? null });
440
+ }
441
+ // BL-5: a synchronous decline must also cancel the Stripe item -- the
442
+ // charge already created a live SubscriptionItem (see chargeActivationFee)
443
+ // and the earlier version of this branch only flipped the DB row,
444
+ // leaving a canceled-in-our-eyes row with a still-live Stripe item that
445
+ // nothing else was guaranteed to clean up promptly. `del` failures are
446
+ // non-fatal (a 404 is fine; anything else is logged, not thrown -- the
447
+ // reconciler's Job C forward-reconciliation pass retries it, which is
448
+ // why this UPDATE also stamps touch_pass_canceled_at -- NEW-1: Job C's
449
+ // own retry filter requires that column to be non-null, and this branch
450
+ // was previously leaving it NULL, making the row invisible to Job C).
451
+ if (charge.outcome === 'declined') {
452
+ try {
453
+ await stripe.subscriptionItems.del(charge.stripeItemId, { proration_behavior: 'none' });
454
+ } catch (e) {
455
+ if ((e as { statusCode?: number }).statusCode !== 404) {
456
+ await logOps(admin, 'touch_pass_decline_cancel_failed', {
457
+ membership_id, stripe_item_id: charge.stripeItemId, message: String(e).slice(0, 300),
458
+ }, { severity: 'error' });
459
+ }
460
+ }
461
+ await admin.from('memberships').update({
462
+ touch_pass_addon_status: 'canceled',
463
+ touch_pass_canceled_at: new Date().toISOString(),
464
+ })
465
+ .eq('id', membership_id).eq('touch_pass_addon_status', 'pending');
466
+ return json(200, { ok: false, status: 'declined' }); // S-14: ok:false on a failed charge
467
+ }
468
+ // Unreachable: chargeActivationFee's return type is exhaustively
469
+ // 'paid' | 'requires_action' | 'declined', and 'paid' returned above.
470
+ throw new Error(`unreachable charge outcome: ${(charge as { outcome: string }).outcome}`);
471
+ } catch (e) {
472
+ console.error('[touch-pass-signup] error', e);
473
+ await logOps(admin, 'touch_pass_signup_error', {
474
+ membership_id, actor_uid: session.id, message: e instanceof Error ? e.message : String(e),
475
+ }, { severity: 'error' });
476
+ return json(500, { ok: false, error: 'signup_failed' });
477
+ }
478
+ }