feat/powerradar

Access-token cache backend unspecified — stampede risk on multi-device fleet

Concurrent Lambda cold-starts for a multi-device site will each call REFRESH_TOKEN_AUTH if cache is in-memory. Clarify in SG-1: in-memory is acceptable for small fleet; DDB if Cognito throttle is a concern. Also specify exp-buffer margin (not raw exp).

CSV→API transition: disjoint-tier invariant not addressed in SG-6 runbook

Existing powerradar CSV MetricSources have open coverage windows. SG-6 runbook must include: deactivate the CSV source before the API source goes live on the same stream, per the splice invariant (site-metrics-seam.md). Otherwise priority-splice outcome depends on source priority, potentially preferring CSV over live API data.

POWER unit (W vs kW) pending SG-1 probe — gating SG-3 translation

SG-3 should gate on SG-1 probe results. Use a real fixture from the live probe, not a synthetic one. The existing CSV worker scales kW×1000→W; confirm if API also returns kW.

ENERGY measurementType ambiguity: seam rule prohibits collecting ENERGY alongside POWER

Adding an ENERGY collection source alongside POWER on the same stream creates non-disjoint sources, violating the seam rule. Clarify in SG-2: ENERGY measurementType is probe-only documentation; do not register as a collectible manifest variable.

x-panpwr-roleversion: 12 hardcoded — no diagnostic logging for breakage

A portal release bumping this to 13 will silently fail. Log the roleversion sent in error diagnostics so a future 403 is diagnosable without re-probing.

169-day refresh token: no rotation runbook or revocation procedure documented

A stolen Cognito refresh token gives up to 169 days of portal-read access. Plan should include: (1) revocation runbook (cognito-idp:RevokeToken or password reset), (2) Secrets Manager rotation cadence ≤90 days or tied to a proactive re-login cycle, (3) anomaly alert for unexpected REFRESH_TOKEN_AUTH calls. Out-of-scope section says 'ship a runbook' — that runbook must cover revocation, not just initial login.

Cognito IDP egress not in IAM/VPC allowlist note

Lambda needs outbound HTTPS to cognito-idp.us-east-1.amazonaws.com. No IAM permission needed (public SPA client), but if NAT/security-group rules allowlist outbound HTTPS by host, add this endpoint alongside www.powerradar.energy. Note explicitly in SG-5 INFRA_DESIGN.md.

Using a SPA Cognito client server-side: ToS and stability risk

client_id 3kcr9l6iol4skjkao4768s1rtf is a public SPA client used server-side. Vendor can add adaptive auth, rotate the client, or block non-browser user-agents at any time. Document this risk in INFRA_DESIGN.md alongside the Export Jobs fallback.

Default AWS-managed KMS key for 169-day Secrets Manager credential

Hardening recommendation: use a CMK with key policy restricted to the Lambda's execution role ARN, providing defense-in-depth for this long-lived, high-access-scope credential.

Access token must never appear in CloudWatch logs

Add explicit constraint to SG-1 cognito-auth.ts design: never log AccessToken or RefreshToken values. Mirror the 'secret: true' credentialField convention.

Secret path should use canonical batu/{env}/metrics/powerradar-api/* prefix

infra/cdk/src/stacks/services/metrics/integrations/powerradar-api/iam.ts

scope.md proposes {env}/powerradar-api/oid={oid}. The v2 canonical pattern (victron, egauge, growatt IAM stacks) is batu/{env}/metrics/{integrationCode}/*. Fix in SG-5 iam.ts before seeding dev secrets.

shelly-fleet cited as two-access-path precedent but does not exist in the codebase

services/metrics/integrations/shelly-fleet/ does not exist. The live precedent is helioscope (helioscope-csv + helioscope-api manifests). Cite helioscope-api instead.

ENERGY variable note in SG-2 is misleading given the seam rule

Clarify in the manifest file comment: POWER→demand only; ENERGY is probe artifact, not a registered collection variable. Prevents a future implementer from adding an ENERGY MetricSource.

Engine-layer tests absent: cognito-auth.ts and eigw-client.ts have no planned coverage

SG-3 scopes tests to pure translation only. Auth engine is the highest-risk new code (new auth archetype). Minimum additions: (a) TTL gate tests for cognito-auth.ts, (b) error-classification tests for eigw-client.ts (401→UpstreamAuthFailed, 429→UpstreamRateLimited, 5xx→UpstreamUnavailable). Reference: huawei/auth-and-explore.test.ts, enphase/token-manager.test.ts.

Cognito REFRESH_TOKEN_AUTH failure path: NotAuthorizedException → wrong error tag

services/metrics/integrations/powerradar-api/src/engine/cognito-auth.ts

A revoked/expired refresh token returns NotAuthorizedException. Without a test, this could be mis-classified as UpstreamUnavailable → silent retry storms instead of alert. Add unit test for the error→_tag mapping.

Malformed/empty chart-data response not in SG-3 test scenarios

services/metrics/integrations/powerradar-api/src/translation/chart-to-batu.ts

§9 requires resilient skip for failing channels. Test: empty data array → zero MetricsPayload items, null point value → point dropped, unexpected JSON shape → error-as-value (not thrown). Reference: rows-to-batu.test.ts channel-not-found case.

Token cache TTL must subtract a safety buffer from exp (60–300s)

services/metrics/integrations/powerradar-api/src/engine/cognito-auth.ts

Using raw exp means a Lambda starting 2s before expiry passes the TTL gate but finds the token expired mid-request. Pattern: enphase EXPIRY_MARGIN_SEC=300. Specify exp−120s (minimum) in SG-1 cognito-auth.ts design.

In-process token cache lost on cold start — document the design decision

Module-level cache is acceptable for small fleets (SMA/Sol-Ark precedent). Document in INFRA_DESIGN.md: why in-memory chosen over DDB, and at what fleet size to switch. Prevents SG-7 re-litigating this.

@aws-sdk/client-cognito-identity-provider must be a runtime dep, not externalized

services/metrics/integrations/powerradar-api/package.json

Not pre-bundled in the Node.js 20 Lambda runtime. Must be in package.json dependencies and absent from CDK bundling externalModules. Missing → cold-start module-not-found crash. Note explicitly in SG-5.

SG-7 should add Cognito-refresh auth archetype to INTEGRATION_STANDARDS §8 checklist

services/metrics/integrations/INTEGRATION_STANDARDS.md

INTEGRATION_STANDARDS.md §8 only documents static-token and session/DDB-cache archetypes. Add headless Cognito REFRESH_TOKEN_AUTH as a third archetype. Prevents cargo-culting a DDB auth-cache stack for similar token-based integrations.