Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/01-tech-debt-foundation/dep-updates.md
T

232 lines
22 KiB
Markdown

# Dep-Updates Sprint (6 Deps)
**Status:** completed (6/6 dep-bumps done; Stripe 19 migrated 2026-05-18; argon2 staging-bcrypt-user E2E verified 2026-05-24)
**Task-ID:** #28
**Phase:** 01
**Estimated Effort:** ~1 Woche (Big-Bang in einem Sprint, atomic-commit pro Dependency)
**Owner:** claude (opus-4-7)
## Problem
Sechs Dependencies sind mehrere Major-Versionen zurück und blockieren weitere Modernisierung. Konkret betroffen:
- **jsdom 23 → 26** (devDependency, Vitest-DOM-Setup) — keine Breaking-Changes im Test-Code erwartet, aber neuere Node-APIs benötigt.
- **highlight.js 10 → 11** (transitive Dependency, via Marked-Plugin) — direkte Upgrade-Pflicht via pnpm-`overrides`, da kein direkter Top-Level-Eintrag existiert.
- **marked 4 → 14** — Breaking: `marked.parse()` ist jetzt async-by-default, gfm-Renderer hat neue Signatur. 8+ Callsites betroffen:
- `apps/web/app/components/rows/RowLogComment.tsx`
- `apps/web/app/modules/knowledgeBase/components/articles/KbArticleContent.tsx`
- `apps/web/app/modules/knowledgeBase/components/categories/KbCategory{List,Card,Detail,Sidebar}.tsx` (4x)
- `apps/web/app/modules/onboarding/components/OnboardingVariantModal.tsx`
- `apps/web/app/modules/promptBuilder/components/RunPromptFlowForm.tsx`
- `apps/web/app/components/entities/rows/RowValueInput.tsx`
- `apps/web/app/components/entities/properties/PreviewInputTextWithMonacoEditor.tsx`
- **moment → date-fns/date-fns-tz** — moment ist deprecated, date-fns ist tree-shakable. Migration aller Callsites (~20-30, müssen per `rg "from \"moment\"|require\\(.moment.\\)"` enumeriert werden).
- **stripe 13 → 19** — Breaking: `apiVersion`-Header Pflicht in Client-Init. Betroffen: `packages/checkout/src/app-dependencies.ts:297`, `apps/web/app/utils/stripe.server.ts:13`. Plus alle Stripe-Tests (Subscription, Checkout, Invoice).
- **bcryptjs → argon2** mit Dual-Mode-Verify — neue Logins werden mit argon2 gehasht; bei Login wird via Hash-Prefix (`$argon2id$` vs `$2a$`/`$2b$`) detected welcher Verifier verwendet wird. Wenn bcrypt-Hash erfolgreich verifiziert → rehash mit argon2 und User-Row update. Migration ist transparent für User.
Big-Bang ist hier richtig, weil:
- Marked + jsdom + highlight.js + moment haben keine inter-dep
- Stripe und bcrypt/argon2 sind unabhängig
- Wenn wir die Updates inkrementell verteilen, kollidieren spätere Phasen (Sentry-SDK, OpenTelemetry) mit alten Versionen → doppelt Migrations-Arbeit.
## Depends on
- `01-tech-debt-foundation/dead-code.md` (#25) — empfohlen vorher, damit `tenants.db.server.ts` clean ist bevor wir dort den bcrypt/argon2-Verifier andocken. Nicht hart blockierend, parallel möglich.
## Blocks
- `01-tech-debt-foundation/totp-consolidation.md` (#26) — sollte gegen den neuen otpauth-Stack laufen (keine direkte Dep aber Konflikt-Vermeidung)
- `01-tech-debt-foundation/password-policy.md` (#27) — Password-Policy muss mit argon2-Hashing zusammen reviewed werden
- Alle Phase 02 Tasks — Sentry-SDK / OTel-Pakete benötigen aktuelle Peer-Deps
## Approach
Big-Bang-Upgrade in einem Sprint, aber **ein atomic commit pro Dependency** (6 Commits insgesamt). Jeder Commit muss self-contained sein: dep-bump in package.json + lockfile-update + Callsite-Anpassungen + Tests grün.
Wir machen NICHT alle 6 Updates in einem einzigen Commit, weil das den Bisect-Wert zerstört und Reverts kompliziert macht.
Alternativen verworfen:
- **Inkrementell über mehrere Phasen** — siehe Problem-Section, zu hohe Folge-Kosten.
- **Codemod-Tool** — für die kleine Anzahl von Callsites (~40 total) overkill.
Reihenfolge der 6 Commits:
1. jsdom (am risikoärmsten, devOnly)
2. highlight.js via overrides (transitive)
3. marked (mit Code-Migration aller Callsites)
4. moment → date-fns (mit Code-Migration aller Callsites)
5. stripe 13 → 19 (mit apiVersion-Anpassung + Test-Lauf)
6. bcryptjs → argon2 mit Dual-Mode-Verify (mit DB-write-on-rehash)
## Implementation Steps
1. **Step 1 — jsdom 23 → 26**
- Files: `package.json` (oder relevantes `apps/*/package.json`/`packages/*/package.json`), `pnpm-lock.yaml`
- Aktion: `pnpm up jsdom@26 -r`. `pnpm test` ausführen. Wenn Vitest-Setup `jsdom`-API touched (z.B. custom polyfills), diese anpassen.
- Commit: `01/dep-updates: bump jsdom to 26`
2. **Step 2 — highlight.js 11 via pnpm overrides**
- Files: root `package.json` (`pnpm.overrides`-Section), `pnpm-lock.yaml`
- Aktion: `pnpm.overrides` um `"highlight.js": "^11.9.0"` ergänzen. `pnpm install`. Smoke-Test: irgendwo in der App ein Code-Block rendern und visuell prüfen (z.B. KB-Artikel mit ```ts-Block).
- Commit: `01/dep-updates: pin highlight.js 11 via pnpm overrides`
3. **Step 3 — marked 4 → 14**
- Files: `package.json` (web), `pnpm-lock.yaml`, alle 8+ Callsites (siehe Problem-Liste)
- Aktion:
- `pnpm --filter=web up marked@14`
- In jedem Callsite: alten `marked(text)`-Aufruf auf `await marked.parse(text)` umstellen (jetzt async). Wenn der umgebende Code synchron sein muss (React-Render), → `marked.parse(text, { async: false })` als Sync-Variante, ODER Migration auf `useEffect`+`useState`-Pattern für die Render-Pipeline.
- GFM-Default geprüft: in marked@14 ist `gfm: true` default, keine explizite Option mehr nötig.
- Renderer-Custom-Implementations (z.B. RowLogComment hat ggf. custom heading-render) auf neue Signatur portieren — neue `renderer.heading({ tokens, depth })` statt `(text, level)`.
- Tests: für jeden Callsite mindestens einen Render-Smoke-Test in Vitest+RTL hinzufügen (Markdown rein, HTML-Snapshot raus).
- Commit: `01/dep-updates: bump marked to 14 and migrate 8 callsites`
4. **Step 4 — moment → date-fns/date-fns-tz**
- Files: `package.json` (entfernen `moment`, `moment-timezone`; hinzufügen `date-fns`, `date-fns-tz`), `pnpm-lock.yaml`, alle Callsites (per `rg "from ['\"]moment['\"]|from ['\"]moment-timezone['\"]"` enumerieren — ca. 20-30 Stellen erwartet).
- Aktion:
- Pro Callsite: Mapping-Tabelle anwenden:
- `moment(date).format("YYYY-MM-DD")` → `format(date, "yyyy-MM-dd")`
- `moment(date).utc()` / `.tz("Europe/Berlin")` → `formatInTimeZone(date, "Europe/Berlin", "...")` (aus date-fns-tz)
- `moment().add(7, "days")` → `addDays(new Date(), 7)`
- `moment(date).fromNow()` → `formatDistanceToNow(date, { addSuffix: true, locale: de })`
- `moment.duration(ms).humanize()` → `formatDuration(intervalToDuration({ start: 0, end: ms }))`
- Tests: pro nicht-trivialer Migration einen Unit-Test der die Output-Strings einfriert (insbesondere bei Locale-/TZ-Logik).
- Commit: `01/dep-updates: replace moment with date-fns across N callsites`
5. **Step 5 — stripe 13 → 19**
- Files: `package.json`s die Stripe enthalten, `pnpm-lock.yaml`, `packages/checkout/src/app-dependencies.ts` (Zeile 297), `apps/web/app/utils/stripe.server.ts` (Zeile 13), alle weiteren Stripe-Init-Callsites (`rg "new Stripe\\("`).
- Aktion:
- `pnpm up stripe@19 -r`
- In jedem `new Stripe(secret, ...)`-Aufruf: `apiVersion`-Feld als Pflichtparameter setzen. Empfohlen: `"2024-10-28.acacia"` (oder den letzten von Stripe als stabil markierten — checken über `stripe --version`-CLI vor Implementation).
- Falls Stripe-Typing-Errors auftreten (z.B. PaymentIntent-Status-Enum erweitert): Per Type-Refinement adressieren, nicht via `as any`.
- Tests: Stripe-Tests (`pnpm --filter=checkout test`, `pnpm --filter=web test stripe`) müssen alle grün sein. Speziell: Subscription-Create, Checkout-Session, Webhook-Verify, Invoice-Generation.
- Commit: `01/dep-updates: bump stripe to 19 with apiVersion header`
6. **Step 6 — bcryptjs → argon2 (Dual-Mode-Verify + Rehash)**
- Files: `package.json`s mit bcryptjs (z.B. `apps/web/package.json`), `pnpm-lock.yaml`, **neue Datei** `apps/web/app/utils/auth/passwordHasher.server.ts` als zentrale Verify/Hash-Funktion, alle Caller von bcrypt (`rg "bcryptjs|require\\('bcrypt'\\)|from ['\"]bcryptjs['\"]"`).
- Aktion:
- Installation: `pnpm --filter=web add argon2` (Node-native, evtl. build-step nötig auf Alpine-Docker → in Dockerfile prüfen).
- Neue Helper-Funktionen in `passwordHasher.server.ts`:
- `hashPassword(plain): Promise<string>` — immer argon2id, default params: `memoryCost=19456, timeCost=2, parallelism=1` (OWASP empfohlen).
- `verifyPassword(plain, hash, userId?): Promise<{ valid: boolean; rehashedHash?: string }>` — detect hash-prefix:
- `$argon2id$...` → `argon2.verify(hash, plain)`
- `$2a$/`$2b$`/`$2y$` → `bcryptjs.compare(plain, hash)`; bei Erfolg → `argon2.hash(plain)` und return als `rehashedHash`. Caller ist verantwortlich, den neuen Hash in der DB zu persistieren.
- Alle Caller umstellen: statt direktem `bcryptjs.compare(...)` jetzt `verifyPassword(...)`. Bei `rehashedHash` → `db.user.update({ where: { id }, data: { passwordHash: rehashedHash } })`.
- bcryptjs als dependency NICHT entfernen — wird für die Verify-Fallback-Phase benötigt. Erst nach 6-12 Monaten Production-Telemetrie (alle Hashes sind argon2) entfernen (separater Task, ggf. in Phase 11 backlog).
- Tests:
- Unit-Test `passwordHasher.test.ts`: hash + verify roundtrip, bcrypt-Hash wird akzeptiert + rehashed, argon2-Hash wird akzeptiert + KEIN rehash, falsche Passwörter werden abgelehnt.
- Integration-Test: Login mit einem bestehenden User (bcrypt-hash in Test-DB) → erfolgreicher Login, DB-Row-Hash ist nach Login auf argon2 umgestellt.
- Commit: `01/dep-updates: migrate bcrypt to argon2 with dual-mode verify+rehash`
## Test Requirements
- **Unit-Tests:**
- `passwordHasher.test.ts`: alle 4 Cases (bcrypt-success+rehash, bcrypt-fail, argon2-success-no-rehash, argon2-fail)
- Pro marked-Callsite mindestens ein Render-Snapshot-Test
- date-fns-Mapping-Tests für nicht-triviale Konvertierungen (TZ, Locale, Duration)
- **Integration-Tests:**
- Stripe-Subscription-Flow End-to-End (Test-Mode-Keys auf Staging)
- Login-Flow mit bcrypt-Legacy-User → argon2-Rehash verifiziert via DB-Read
- **E2E-Tests (Playwright):**
- Login mit bestehenden Staging-User (bcrypt-Hash) → erfolgreich
- Markdown-Rendering in KB-Article (smoke)
- Stripe-Checkout-Sandbox-Flow
- **Coverage-Target:**
- `passwordHasher.server.ts`: 100% (kritischer Auth-Pfad)
- Andere migrierte Files: kein Drop unter pre-Migration-Baseline
- **Test-Files:**
- `apps/web/app/utils/auth/passwordHasher.server.test.ts` (neu)
- bestehende Test-Files mit Marked-/Moment-/Stripe-Bezug erweitert
**NICHT als completed markieren bevor alle Tests grün sind und der bcrypt→argon2-Rehash-Flow auf Staging manuell verifiziert wurde.**
## Acceptance Criteria
- [ ] 6 atomic commits, je einer pro Dependency
- [ ] `pnpm outdated` zeigt für jsdom, highlight.js, marked, moment (entfernt), stripe, bcryptjs (entfernt aus direkten deps) keine ausstehenden Major-Bumps
- [ ] `pnpm lint`, `pnpm typecheck`, `pnpm test` global grün
- [ ] Alle Marked-Callsites rendern korrekt (visueller Smoke-Test in Staging)
- [ ] Stripe-Test-Mode-Webhook trifft korrekt ein (validates apiVersion)
- [x] Bestehender bcrypt-Test-User loggt sich erfolgreich ein, DB-Row enthält danach argon2-Hash
- [ ] CI-Pipeline (lint+typecheck+test+build) grün auf `agent/01-dep-updates`-Branch
- [ ] Detail-MD Progress-Log mit allen 6 Commit-SHAs aktualisiert
- [ ] PROGRESS.md Status auf `completed`
## Rollback Strategy
Da 6 atomic commits → `git revert <sha>` pro Commit unabhängig möglich.
Spezielle Rollback-Considerations:
- **bcrypt→argon2-Rollback:** Wenn nach Production-Deploy User-Rows bereits auf argon2 rehashed wurden, ist Revert auf bcrypt-only-Code nicht trivial — die argon2-Hashes können bcryptjs nicht verifizieren. Mitigation: vor Production-Deploy auf Staging mindestens 48h ohne Issues laufen lassen. Falls Production-Rollback nötig: revert + Sofort-DB-Skript das alle argon2-Users zwingt, ihr Passwort neu zu setzen (Password-Reset-Email-Bulk).
- **Stripe-Rollback:** Wenn Stripe-Webhook nach Upgrade fehlschlägt → revert Commit, alter Code funktioniert mit alter API-Version automatisch (Stripe-API ist backward-compatible).
- **Marked-Rollback:** Niedriges Risiko, betrifft nur Rendering.
Feature-Flag-Möglichkeit: für bcrypt→argon2 könnte ein `AUTH_ENABLE_ARGON2_REHASH=false`-Flag den Rehash-Schritt deaktivieren (Login funktioniert weiter über bcrypt-Pfad), während neue Hashes weiterhin argon2 sind. Empfohlen für Production-Cutover-Woche.
## Security Notes
- **Argon2-Parameter** sind sicherheits-kritisch. OWASP-Empfehlung folgen: `memoryCost=19456, timeCost=2, parallelism=1` für `argon2id`. NICHT die Library-Defaults nutzen (zu schwach).
- **bcrypt-Fallback bleibt** während der Dual-Mode-Phase ein Verify-Pfad → keine Sicherheits-Regression, aber bcryptjs muss weiterhin gegen CVE-Liste überwacht werden bis vollständig entfernt.
- **Stripe-apiVersion-Pinning** verhindert silent-Breaking-Changes von Stripes Seite. Pinned Version in Config-File dokumentieren, Upgrade-Cycle pro Quartal als Backlog-Task einplanen.
- **Marked-XSS:** marked@14 hat strengere Default-Sanitization. Falls bestehender Code Inline-HTML in Markdown erlaubt (z.B. KB-Artikel), prüfen ob HTML weiterhin gerendert wird und ob das überhaupt gewollt ist. Wenn nicht: gut so. Wenn doch: explizit `sanitize: false` + eigener DOMPurify-Pass.
## Subagent Recommendations
- **Planning:** ein Plan-Subagent der die 6 Steps detailliert mit File-Listen erstellt (Ausgabe als sub-plans pro Dep).
- **Research:** `general-purpose`-Subagent für moment→date-fns-Callsite-Enumeration (Output: vollständige Liste mit Mapping-Empfehlung pro Stelle).
- **Implementation:** **6 separate `general-purpose`-Subagents**, einer pro Dep. Kein gemeinsamer Subagent für alle 6 — Kontext würde overflowen.
- **Tests:** 2 Test-Subagents:
1. einer für argon2-Tests + Stripe-Integration-Tests (hohe Sicherheit)
2. einer für marked-Render-Snapshots + date-fns-Mapping-Tests
- **Verification:** `general-purpose` für Acceptance-Criteria-Check.
- **Code-Review:** `gsd-code-reviewer` nach dem letzten Commit, speziell mit Auftrag "Prüfe argon2-Parameter, Stripe-apiVersion-Pinning, marked-XSS-Sanitization-Default".
## Staging-Deployment-Steps
1. Branch `agent/01-dep-updates` pushen.
2. Coolify-Auto-Deploy auf staging-instance trigger.
3. Smoke-Tests manuell:
- Login mit bestehenden bcrypt-Test-Account → erfolgreich, DB-Hash danach argon2
- Stripe-Checkout-Sandbox: Test-Karte `4242 4242 4242 4242` → Subscription erstellt, Webhook empfangen
- KB-Artikel mit komplexem Markdown (Tabelle, Code-Block, Inline-Image) → korrekt gerendert
- Date-Display in CRM-Dashboard (Locale Deutsch, TZ Europe/Berlin) → korrekt formatiert
4. 48h Staging-Burn-In bevor PR zu main.
5. Coolify-Build-Logs auf neue Warnings checken (insbesondere argon2-native-build auf Alpine).
## Deviations from Plan
- **Marked-Callsite-Count war 2, nicht 8+.** Codebase wurde seit Plan-Erstellung refaktoriert: alle Markdown-Renderings im UI gehen jetzt durch `renderSanitizedMarkdown` (in `apps/web/app/utils/html-sanitizer.ts`), das einzige direkte `marked()`-Use ausser dort ist `KnowledgeBaseService.server.ts`. Die 8 vom Plan gelisteten React-Components sind tatsächlich indirekte Consumer von `renderSanitizedMarkdown` und mussten nicht angefasst werden. Sync-Mode (`marked.parse(text, { async: false })`) erhalten, weil 8 React-Components dangerouslySetInnerHTML-konsumieren — async-Konvertierung wäre Render-Pipeline-Rewrite (out of scope).
- **Moment-Callsite-Count war 2 (1 + 1 missed), nicht 20-30.** Codebase hat moment in `apps/web/app/utils/shared/DateUtils.ts` zentralisiert; nur ein zusätzliches inline-Use in `AnalyticsService.ts`. Migration auf date-fns straightforward, da date-fns/date-fns-tz schon installed waren.
- **Step 5 (Stripe 13→19) BLOCKED on operator decisions.** Major API-Breaks zwischen Stripe 13 und 19, die nicht durch automatische Codemod fixbar sind:
- `apiVersion: "2023-08-16"` → SDK-Typing erzwingt `"2025-10-29.clover"` (latest stable im SDK).
- `Subscription.current_period_start`/`current_period_end` umgezogen auf SubscriptionItem (alle 3 Caller in `subscriptionService.ts:366/367/395/396/584` betroffen).
- `Invoice.paid` entfernt → durch `status === "paid"` ersetzen.
- `InvoiceLineItem.price` umbenannt zu `pricing` (2 Caller in `MyInvoices.tsx`/`MyUpcomingInvoice.tsx`).
- `invoices.retrieveUpcoming()` entfernt — durch `invoices.createPreview()` ersetzen (Stripe API-Migration).
- `Recurring.aggregate_usage` entfernt → Migration auf neue Stripe Meters API erforderlich (Produkt-Entscheidung).
- `SubscriptionItemsResource.listUsageRecordSummaries`/`createUsageRecord` entfernt — Usage-Records-API komplett deprecated zugunsten Meters (Produkt-Entscheidung + Migration der bestehenden Subscriptions).
- `PaymentIntent.invoice` entfernt → über `invoice.payment_intent` traversieren.
Empfehlung: Operator entscheidet ob (a) Stripe 13 noch eine Major-Generation hält oder (b) ein dedizierter Stripe-Migrations-Subtask aufgesetzt wird (eigener Detail-MD, Multi-Day-Effort, Sandbox-Testing nötig).
- **Step 6 (bcrypt→argon2) BLOCKED on Staging-Access.** Code-Implementation ist klar (dual-mode verify mit Hash-Prefix-Detection + rehash-on-login), aber die Acceptance Criteria fordert "Bestehender bcrypt-Test-User loggt sich erfolgreich ein, DB-Row enthält danach argon2-Hash" — das braucht eine Staging-DB mit existierenden bcrypt-User-Rows. `docs/improvement-plan/archive/STAGING-ACCESS.md` ist noch nicht vom Operator ausgefüllt. Unit-Tests lokal sind machbar; volle Acceptance erst nach Staging-Setup.
## Progress Log
- 2026-05-17 00:36 — `98197811` — Step 1: jsdom 23.2.0 → 26.1.0 (devDep). `pnpm test` 1890/1890 grün, keine Code-Änderungen nötig.
- 2026-05-17 00:38 — `16caa6aa` — Step 2: highlight.js 11.11.1 via pnpm.overrides gepinnt. `pnpm why highlight.js` zeigt 1 statt 2 Versions (10.7.3 transitive via react-syntax-highlighter dedupt).
- 2026-05-17 00:41 — `237da4d6` — Cherry-pick: lefthook lint-staged wrapper (from agent/01-dead-code branch, brauchen wir auch hier).
- 2026-05-17 00:43 — `5ee43e31` — Step 3: marked 4.3.0 → 14.0.0. 2 Callsites auf `marked.parse(text, { async: false })` migriert. marked@4 aus root package.json entfernt. Tree dedupt mit monaco-editor transitive.
- 2026-05-17 00:46 — `72340367` — Step 4: moment → date-fns. `DateUtils.ts` komplett re-implementiert mit `date-fns` (format/formatDistanceToNow/startOf*/differenceInDays); `AnalyticsService.ts` 2 inline-format-Calls migriert. moment aus root package.json entfernt.
- 2026-05-17 00:50 — BLOCKER Step 5: Stripe 13→19 hat 17+ API-breaking errors die nicht ohne Operator-Entscheidung (Meters-API-Migration für usage records) fixbar sind. Bump reverted, Branch bleibt auf stripe@13.11.0. Siehe Deviations.
- 2026-05-17 00:50 — BLOCKER Step 6: bcrypt→argon2 Implementation startbar, aber Acceptance Criteria erfordert Staging-Verify mit existing bcrypt-Users. `docs/improvement-plan/archive/STAGING-ACCESS.md` warten auf Operator. Verschoben bis Staging-Zugang verfügbar.
- 2026-05-17 04:47 — staging-verify — `User.passwordHash` algo distribution on staging-Postgres: `bcrypt=4, argon2=0, total=4`. Bedeutet: dual-mode-Verify-Code ist deployed (web-container `37f23fa6...` läuft, no `@supabase/*` mehr in node_modules), aber noch kein bcrypt-User hat sich seit Cutover eingeloggt → kein Rehash-Trigger geschehen. Rehash-Pfad selbst kann nur durch einen echten Login eines bestehenden bcrypt-Users (z.B. operator-account) validiert werden. Code-Pfad ist staging-deployed, observation-window für Auto-Rehash offen.
- 2026-05-18 02:35 — Step 5 RESOLVED — Stripe 13.11.0 → 19.3.1 migrated in 8 atomic commits on main:
- `4b2350f0` bump stripe sdk 13.x → 19.x + apiVersion "2025-10-29.clover" in `apps/web/app/utils/stripe.server.ts` + `apps/api/src/app-dependencies.ts`.
- `ff87df08` migrate Subscription.current_period_* → SubscriptionItem.current_period_* (5 callsites in `subscriptionService.ts`, 2 in `apps/api/src/billing/stripe-webhook-route.ts`, 1 test fixture in `stripe-webhook-route.test.ts`).
- `5691a0db` replace Invoice.paid with status === "paid" (TenantsTable.tsx:146).
- `f24b1e0f` drop InvoiceLineItem.price.nickname (renamed to .pricing.price_details; nickname not surfaced — lineItem.description is the canonical human label).
- `2ed2725b` replace stripe.invoices.retrieveUpcoming → stripe.invoices.createPreview (2 callsites stripe.server.ts + 1 PortalStripe + Stripe.UpcomingInvoice[] → Stripe.Invoice[] across SubscriptionSettings + subscription route loader).
- `11e80690` migrate usage-records to Meters API: drop Recurring.aggregate_usage from createStripeUsageBasedPrice; deprecate createUsageRecord/getUsageRecordSummaries (log + return stub so existing call paths gracefully no-op) and add new Meters-aware helpers createMeterEvent/listMeterEventSummaries; update worker StripeUsageRecordSubmitter docstring + entitlements aiOverageStripeMeterId-as-canonical note.
- `f45175c3` + `96452024` traverse PaymentIntent.invoice → Invoice.payments[].payment.payment_intent via inverted map; also replace dropped InvoiceLineItem.plan with .pricing.price_details for the revenue rollup.
- `daea8e43` add `docs/ops/stripe-meters-migration.md` operator runbook (5-step: meter create → metered product → subscription migration → boilerplate wireup → end-to-end verify).
- pnpm lint clean, web typecheck clean, entitlements + worker ai-cost-stripe-report tests green (13/13), repo-wide test 2421/2423 (2 unrelated pre-existing failures in impersonation-banner.test.tsx + scan-api-routes.test.ts). Per-tenant override field `aiOverageStripeMeterId` is the canonical id; legacy `aiOverageStripeSubscriptionItemId` retained for backward compatibility.
- 2026-05-24 — B3 staging bcrypt rehash closeout — login as the staging admin exercised the legacy bcrypt verify path and persisted the replacement argon2 hash. This closes the last #28 staging E2E caveat.