feat/energy-api

needs attentionviewing older commit

3fd1d03 · incrementalPR #207reviewed 2026-07-05 04:36 UTC0H · 3M · 5L · 3I

The branch

Purpose

Port the legacy electricity-data-api (billing + savings + metrics + webhooks + PDFs from batu-monorepo Pulumi/DDB/Athena) into the platform monorepo, following a 10-phase roadmap.

Goal

Deliver the functional core of the port end-to-end — metrics adapter → tariff/TOU reference data → CFE bill calculators → calculated-bill persistence → PDF — plus pure cores of run-orchestration, webhook, savings, and public-API phases.

Sub-goals

Phase 0: Port spec + decisions D1–D5
Phase 1: Tinybird → SiteMetrics adapter (derived-at-read, KK validated to 1e-6)
Phase 2: tariff_rate_values storage + CFE TOU classifier
Phase 3: CFE bill calculators + computed bill source
Phase 4 Inc1: Run orchestration (pure planner + runScheduledBillingShell)
Phase 5 Inc1: Webhooks (bill.finalized event + WebhookDeliveryFCIS)
Phase 6 Inc1: Savings (SavingsFCIS)
Phase 7 Inc1: Public API energy-summary + savings handlers
Phase 8: PDF generation (bill-pdf)

The changes (whole branch)

What: Incremental: (1) Remove /i from WEBHOOK_PUBLIC_ID_PATTERN — case-sensitive regex prevents format-vs-not-found oracle on the public DELETE endpoint. (2) Add SSRF deferral comment to webhook-endpoint.decisions.ts and webhook-delivery.decisions.ts per BAT-236. (3) Add tou_band 0-vs-absent test to bill-calculator suite.
Why: Hygiene sweep after the previous review flagged the /i oracle; SSRF deferral comments suppress repeated security-review noise on a known, intentionally-deferred gap; test closes a coverage gap in the tou_band demand branch.
Areas: apps/platform+16526−4387packages/database+8699−8domains/cross-domain+8435−13domains/utility+6640−28docs/development+5512−0packages/ui+3529−0domains/metrics+1180−14packages/api+1142−33domains/core+133−62
Blast: 488 files, +112k/−4.7k across platform/database/cross-domain/utility/metrics; this incremental: 4 files +37/−1

public-api webhooks SSRF-deferred-BAT-236

➖CI· No CI data available➖CodeRabbit· No .coderabbit.yaml in repo✅correctness✅security· 2 medium notes (pre-existing, documented)✅conventions· 1 medium: comment scope inaccuracy✅tests· 1 medium: missing regex regression test✅improvement· Minor test structure issues

Findings · 11

security4

medium

IPv6 private ranges bypass PRIVATE_V4 regex in validateWebhookUrl

domains/utility/src/webhook-delivery/webhook-delivery.decisions.ts:48

https://[::ffff:169.254.169.254] evades the regex. Pre-existing, documented in BAT-236. The comment now claims 'string-level blocking' — this is accurate for IPv4 but incomplete for IPv6.

low

Registration-time decideCreate has no IP-range check

domains/core/src/webhook-endpoint/webhook-endpoint.decisions.ts:86

Customers can register https://169.254.169.254/… today. No live SSRF impact (dispatcher not wired), but the registration-delivery gap is undocumented in this comment.

low

Deferral has no code-level enforcement — dispatcher could ship without IP guard

domains/utility/src/webhook-delivery/webhook-delivery.decisions.ts:56

Consider a TODO/guard in the future delivery shell so the dependency is explicit in code rather than prose.

info

/i flag removal is a correct security hardening

apps/platform/src/api/handlers/public-v1/webhooks.handler.ts:42

Old /i let lowercase IDs leak format-vs-not-found distinction via Postgres case-sensitivity. Fix is correct.

conventions5

medium

SSRF comment in webhook-endpoint.decisions.ts overstates what is deferred

domains/core/src/webhook-endpoint/webhook-endpoint.decisions.ts:86

Says 'Blocking loopback / RFC-1918 here … is deferred' but validateWebhookUrl already does string-level blocking. What's actually deferred is DNS-rebinding / resolve-and-check-IP only. Fix: trim the comment to reference the delivery-side guard and scope the deferral accurately.

low

SSRF deferral comment is too long for a pure-function annotation

domains/core/src/webhook-endpoint/webhook-endpoint.decisions.ts:86

7-line narrative in a decisions file. Trim to 2 lines: the fact and the ticket reference.

low

Test combines 0-vs-absent into one it() block (inconsistent with suite style)

domains/utility/src/bill-calculator/__tests__/bill-calculator.decisions.test.ts:123

Existing suite splits these into separate it() cases. Two blocks would give clearer failure attribution.

info

WEBHOOK_PUBLIC_ID_PATTERN comment is well-placed and justified

apps/platform/src/api/handlers/public-v1/webhooks.handler.ts:40

Explains a non-obvious invariant. Correct per project comment rules.

info

webhook-delivery.decisions.ts SSRF comment is correctly scoped

domains/utility/src/webhook-delivery/webhook-delivery.decisions.ts:56

Accurately describes what validateWebhookUrl does (string-level) vs what is deferred (DNS-rebinding). Well-placed in the JSDoc.

tests1

medium

No unit test pins the /i flag removal on WEBHOOK_PUBLIC_ID_PATTERN

apps/platform/src/api/handlers/public-v1/webhooks.handler.ts:42

A future contributor reintroducing /i would not be caught by CI. A test in public-v1-validation.test.ts asserting lowercase IDs are rejected would prevent silent regression.

improvement1

low

denom = 31 * 24 * 0.57 re-declared in four test bodies

domains/utility/src/bill-calculator/__tests__/bill-calculator.decisions.test.ts:124

Extract once at describe scope or name it JAN_Q_DENOM to avoid silent drift.

History · 8 commits

d6b4a35needs attentionincremental4H · 4M · 5L2026-07-05 20:29
678cb93safeincremental0H · 0M · 1L2026-07-05 17:40
d219403needs attentionincremental1H · 3M · 4L2026-07-05 05:37
5ecd80cneeds attentionincremental1H · 2M · 1L2026-07-05 04:59
3fd1d03needs attentionincremental0H · 3M · 5L2026-07-05 04:36current
1446f7eneeds attentionincremental2H · 4M · 7L2026-07-05 04:08
ca73a1bneeds attentionfull4H · 10M · 14L2026-07-05 02:46
c24738eneeds attentionincremental3H · 10M · 9L2026-07-04 05:12