feat/energy-api

tariff-jobs: new admin-required comment claims `withPublicApiAuth` gate but handler uses `withAuth`

apps/platform/src/api/handlers/tariff-jobs.handler.ts

The new comment reads 'The scrape is a service-role write gated by withPublicApiAuth — matches the cfe-jobs posture (BAT-247)' but the handler imports and calls `withAuth` (Supabase session JWT), not `withPublicApiAuth` (machine actor key). These are materially different: `withAuth` accepts any active session with no role gate; `withPublicApiAuth` accepts Batu machine-actor JWTs. The factual error misrepresents the security posture in an audit-trail comment and misleads future reviewers. Fix: either correct the comment to reference `withAuth`, or if machine actors should be able to trigger tariff scrapes (BAT-247 intent), swap the middleware.

API key scopes declared but silently dropped — per-key access restrictions are never enforced

apps/platform/src/api/handlers/public-v1/energy-summary.handler.ts

API keys carry a `scopes` array; `validateBatuPublicApiAuth` verifies the claim but then maps to `AuthContext` which has no `scopes` field — they are dropped. No handler checks scopes. A narrowly-scoped key (`['bills:read']`) has identical reach to a wildcard key. Pre-existing issue surfaced by the admin-required audit pass; should be resolved before Niko host cutover.

Post-gate shells receive raw `params.sitePublicId` rather than the gate-confirmed `site.sitePublicId`

apps/platform/src/api/handlers/public-v1/energy-summary.handler.ts

`resolveSiteTariffContext` and `resolveSiteEnergyMetricsShell` are called with the raw path param `params.sitePublicId`, not the gate-confirmed value returned by `findSiteInOrg`. Currently safe (the gate already 404s for cross-org sites), but if a future refactor reorders or conditionalizes the gate these calls would silently expose cross-org data. Passing `site.publicId` instead costs nothing and makes the defense explicit.

Multi-org human JWTs silently collapse to memberships[0] in public-v1 handlers

apps/platform/src/api/handlers/public-v1/savings.handler.ts

All public-v1 handlers resolve the caller's org as `memberships[0]?.orgId`. A human user belonging to multiple orgs always uses their first-claim org; requests for sites in a second org return 404 with no indication why. Pre-existing; document the single-org machine-actor design intent explicitly or reject multi-membership tokens at `withPublicApiAuth`.

admin-required comment in tariff-jobs incorrectly names auth middleware

apps/platform/src/api/handlers/tariff-jobs.handler.ts:58

The admin-required comment pattern is the audit trail for service-role DB reads. Naming the wrong middleware (`withPublicApiAuth` vs actual `withAuth`) in this canonical justification comment undermines the audit-trail purpose — a reviewer cannot trust the comment accurately describes the security boundary. The correctness lens also flagged this: the comment has a factual error.

admin-required comment tags `dispatchTariffJobPipeline` as a 'DB read' — it is an SFN dispatch

apps/platform/src/api/handlers/tariff-jobs.handler.ts:80

`dispatchTariffJobPipeline` is an AWS Step Functions `StartExecution` call (with a best-effort ARN write), not a DB read of the tariff job. The admin-required pattern is for service-role DB reads that bypass RLS; tagging an SFN dispatch with it adds noise and misrepresents what bypass is happening at that point.

No tracking issue for restoring sites e2e coverage when the feature ships

e2e/platform/sites.spec.ts

The commit removes the spec as 'premature WIP UI'. No corresponding Linear issue or TODO comment marks that coverage needs to be restored when the sidebar link is enabled. Consider filing a tracking issue or a `// TODO(sites-launch)` comment in the e2e directory.

E2E spec deletions are safe — both files tested a disabled/pre-launch UI route

e2e/platform/sites.spec.ts

Sites sidebar link is `disabled (coming-soon)`; the spec navigated directly to the route. No shipped user-reachable behavior is uncovered by the deletion. SitesPage has zero remaining imports after removal.

Identical org-gate comment duplicated 4× in savings.handler.ts

apps/platform/src/api/handlers/public-v1/savings.handler.ts

The same 2-line admin-required org-gate justification appears verbatim before every `findSiteInOrg` call across all four handlers. The file-level module JSDoc already documents the public-v1 auth posture. A single module-level comment plus a one-line reference at each call site would reduce drift risk.

3 no-console lint warnings remain after ESLint devDeps fix

services/utility/tariffs/cfe

ESLint now runs (exit 0) but leaves 3 `no-console` warnings: `console.log` in `src/db.ts` lines ~48 and ~61, `console.info` in `src/browser-clearance.ts`. The fix commit was the natural moment to resolve these — they're not errors, but structured logging (stderr/warn) is the convention for Lambda handlers.

Deleted e2e page objects had reusable patterns worth documenting before they're lost

e2e/pages/SitesPage.ts

The deleted files demonstrated: (1) `domcontentloaded` + explicit readiness assertion (not `networkidle` — PostHog keeps pages non-idle); (2) `gotoFromList()` seed-independent navigation helper; (3) `escapeRegExp` multi-value text-match for status pills. A brief note in `e2e/CLAUDE.md` or a fixture would prevent reinventing these patterns.