Security: production-guards batch — consolidates the six mechanical #279 fixes

[field123]

Batches the six remaining mechanical fixes from security PRD #279 into one branch/PR. Supersedes #281, #283, #284, #285, #286, #287 (closed pointing here). Design finalized 2026-08-04 — recorded in docs/adr/0001-single-origin-trust-list.md and the package CONTEXT.md ("Session & security" terms); detail in this issue's comments.

Design (resolved)

• Production signal: NODE_ENV === "production", no opt-out. Previews are held to production standards.
• Guard timing: guards throw at factory construction, skipped when NEXT_PHASE === "phase-production-build" so build-once/inject-env-at-runtime pipelines still build. Fallback if NEXT_PHASE proves unreliable: first-request throw.
• One origin list (ADR-0001): better-auth's trustedOrigins is the single origin trust list. The proxy derives its CORS allowlist from it; the allowedOrigins option is deleted (no alias). Wildcard entries honored with better-auth's pattern semantics (matcher implemented in-package). This dissolves MEDIUM-1's insecure default and structurally fixes the silent cart-id-persistence 403 from Studio origins.

Checklist

• HIGH-2 (was Security: production-secret guard in createEpAuth + example hard-fail (#279 HIGH-2) #281) — assertProductionSecret: in production, createEpAuth throws on a missing secret, a known example sentinel (list lives in the package), or <32 chars; checkout.sessionSecret keeps ≥16. Dev warns instead. Example app: remove both hardcoded fallbacks (lib/ep-auth.ts, lib/checkout-context.ts) — missing env fails loudly. No secret split (JWE + checkout AES continue sharing CHECKOUT_SESSION_SECRET).
• MED-1 (was Security: shared Origin-allowlist gate + production-required allowedOrigins on proxy (#279 MEDIUM-1) #283) — delete allowedOrigins + DEFAULT_ALLOWED_ORIGINS from proxy-routes.ts; derive CORS reflection from the auth instance's resolved trustedOrigins, with wildcard matching.
• MED-2 (was Security: apply Origin-allowlist gate to cart routes (#279 MEDIUM-2) #287) — origin gate on cart/server-routes.ts (shared helper, Go CrossOriginProtection semantics): GET/HEAD/OPTIONS always pass; unsafe methods pass on Sec-Fetch-Site: same-origin/none; cross-site requires an exact/wildcard trustedOrigins match; neither signal present → allow (non-browser); reject = 403 { error: "untrusted_origin" }.
• MED-3 (was Security: sanitize proxy dispatch_failed responses in production (#279 MEDIUM-3) #284) — production dispatch_failed → { error: "dispatch_failed", correlationId } (crypto.randomUUID()), full error to console.error; dev keeps message. No logger abstraction (observability: feat(plasmic-mcp): observability and logging for MCP server #243).
• LOW-1/2 (was Security: middleware cookie parsing + delete dead RSC cookie-write block (#279 LOW-1 + LOW-2) #286) — middleware: parseCookies instead of raw-header substring match; delete the dead RSC cookie-write block in the example catchall.
• LOW-3 (was Security: host allowlist on extractEpProviderConfig (#279 LOW-3) #285) — extractEpProviderConfig: hostAllowlist option (default *.elasticpath.com + localhost/127.0.0.1), threaded through createEpAuth/buildEpCtx for Self Managed Commerce. Rejection — and the existing regex-miss case — logs console.error naming the rejected host and the fixing option at the point of failure; never silently falls through to the bootstrap-placeholder chain.
• Tests: prod-secret throw + sentinel rejection; build-phase skip; proxy CORS derived from trustedOrigins incl. wildcard; origin-gate matrix (safe method / same-origin / cross-site trusted / cross-site untrusted / no signals); sanitized prod error body; cookie-parse gate; host-allowlist accept/reject.

Release

Breaking (allowedOrigins removed; prod guards throw). Lands first in the #384 → #282 → #288 sequence; publish once as 0.2.0 after #288 with one consolidated migration section. No deprecation aliases — no external consumers yet.

Out of scope

HIGH-3 #282 (separate breaking PR, re-scoped there) · #288 README security model (must document the gate + SameSite=Lax, no-CSRF-token composition) · secret splitting · logger abstraction.

[field123]

Scope revision from design review (recorded as ADR-0001 in the package):

• MEDIUM-1 (Security: shared Origin-allowlist gate + production-required allowedOrigins on proxy (#279 MEDIUM-1) #283) is redesigned, not guarded. The proxy's allowedOrigins option is removed outright (no deprecation alias); the proxy derives its CORS allowlist from the auth instance's resolved trustedOrigins — one origin trust list, wildcard patterns honored with better-auth's semantics. This deletes the insecure localhost default instead of throwing on it, and structurally fixes the known silent cart-id-persistence failure from Studio origins (proxy list ⊆ trustedOrigins by construction). Note: removing a published 0.1.0 option makes this batch a minor-bump breaking change — one changelog line.
• HIGH-2 sharpened: factory rejects missing/sentinel/short (<32) secrets when NODE_ENV === "production"; the two known example sentinel strings live in the package, not just the example; example loses its fallback entirely. checkout.sessionSecret keeps ≥16. No secret split in this batch.
• Guard timing: throws fire at factory construction, skipped during NEXT_PHASE === "phase-production-build" so build-once/inject-env-at-runtime pipelines still build; the guard fires at runtime boot. Fallback if NEXT_PHASE proves unreliable: first-request throw.

[field123]

Remaining design resolutions from the review (session complete):

• Origin gate (Security: apply Origin-allowlist gate to cart routes (#279 MEDIUM-2) #287 scope): Go CrossOriginProtection semantics, per OWASP/Django/Go/Phoenix consensus. Safe methods always pass; unsafe methods pass on Sec-Fetch-Site: same-origin/none; cross-site is admitted only on an exact trustedOrigins match (this is how Studio mutates); neither signal present → allow (non-browser client). Reject = 403 { error: "untrusted_origin" }. Layering is gate + SameSite=Lax, no CSRF tokens — Security: README security model + deployment hardening + epClientSecret audit (#279 LOW-4 + INFO-1) #288 must state that composition explicitly.
• Host allowlist (Security: host allowlist on extractEpProviderConfig (#279 LOW-3) #285 scope): default *.elasticpath.com + localhost/127.0.0.1 only; hostAllowlist option threaded through createEpAuth/buildEpCtx for Self Managed Commerce deployments. Rejection (and the existing regex-miss case) logs console.error naming the rejected host and the fixing option at the point of failure — no more silent fall-through to the bootstrap-placeholder 401-at-a-distance.
• Error sanitization (Security: sanitize proxy dispatch_failed responses in production (#279 MEDIUM-3) #284 scope): prod → { error: "dispatch_failed", correlationId } (crypto.randomUUID()), detail via console.error; dev keeps message. No logger abstraction here (observability is feat(plasmic-mcp): observability and logging for MCP server #243).
• Release: land Security: production-guards batch — consolidates the six mechanical #279 fixes #384 → Security: remove browser-readable EP token leak (#279 HIGH-3) #282 → Security: README security model + deployment hardening + epClientSecret audit (#279 LOW-4 + INFO-1) #288, publish once as 0.2.0 with one consolidated migration section. No deprecation aliases anywhere in the sequence — there are no external consumers yet, so clean removal now is cheaper than compat forever.

Design record: ADR-0001 (docs/adr/) + "Session & security" terms in the package CONTEXT.md.