@blamejs/blamejs-shop 0.4.23 → 0.4.24

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.4.x
 
+- v0.4.24 (2026-06-06) — **Order timelines, in-console new-order alerts, partial refunds, a customer idea board, storefront sidebar widgets, and Stripe wallet checkout — alongside refund-accounting, inventory-race, and access-control hardening.** This release adds operator and storefront surfaces that compose primitives already in the tree, and closes a set of value-conservation, concurrency, and access-control gaps in the same areas. Operators get a single order-story timeline, an in-console inbox that flags new paid orders with an unread badge, a browser partial-refund control, and curated storefront sidebar widgets. Shoppers get a receipt download on their orders, a suggestion board, and Stripe wallet buttons (Apple Pay, Google Pay, Link) at checkout. The fixes make partial refunds return gift-card and loyalty value in exact proportion, make inventory and quote state transitions race-proof under concurrency, gate the privacy export/erasure routes behind the operator role matrix, and harden the audit log, gift-card ledger, session revocation, and magic-link throttling. Upgrade applies six new D1 migrations and adds one optional environment variable for Apple Pay. **Added:** *Order timeline on the admin order screen* — /admin/orders/:id now shows one chronological feed of the whole order story — state changes, payments and refunds, shipments and carrier tracking events, customer-service notes, returns, and shipping labels — instead of separate panels. Each source is optional; an unwired source simply drops out of the feed. Wire orderTimeline into admin.mount to enable it. · *New-order inbox with an unread badge* — When an order is paid, an entry lands in a new in-console inbox at /admin/inbox and the admin navigation shows an unread count, so a sale is visible on the next page load without polling. Mark a message read once actioned, or archive it. The inbox is addressed to a role broadcast, so a single shared-credential console still sees the badge. Wire operatorInbox into admin.mount to enable it. · *Partial refunds from the browser* — The order screen gains a Refunds panel: enter an amount and the framework charges it back through the payment provider, validates it server-side, and caps it at the order's remaining balance — an over-refund is refused before any money moves. The provider call is keyed so a double-click cannot refund twice. A refund that clears the balance moves the order to refunded; a smaller refund leaves it on its current track and records the slice. · *Customer receipt download* — A customer can download a receipt for their own order from the order page. The document streams in chunks rather than buffering, and the route is gated to the order's owner (and guest-order token holders, matching the existing order-page guard). · *Customer suggestion board* — Shoppers can submit and vote on product and feature ideas at /suggestions (linked from the footer). Operators triage from a new admin console: respond, move ideas along a status flow, merge duplicates, flag spam, or archive. Submissions are rate-limited and bot-guarded, the submitter's email is hashed before storage, and all free text is escaped on both the public board and the admin screen. · *Operator-curated storefront sidebar widgets* — Operators can place an ordered set of sidebar content blocks (newsletter signup, trust badges, social proof, size chart, countdown, featured collection, and more) per page across product, cart, search, and collection pages. The content is operator-authored and global, so it renders identically from the edge cache and the container. Manage widgets and per-page placement from the new Sidebar widgets admin screen. · *Stripe wallet checkout (Apple Pay, Google Pay, Link)* — The pay page now offers the Stripe Express Checkout Element, surfacing the wallet buttons a shopper's browser supports against the existing PaymentIntent. It degrades to the card form when no wallet is available or when payments are unconfigured. Apple Pay additionally needs the domain-association file served (see Migration) and each web domain registered with Stripe. · *Email-change guidance on the profile screen* — The profile screen now explains that a sign-in email cannot be changed in place: addresses are stored as a hash by design, so changing one means re-registering. The copy states what is and is not possible and why, rather than leaving the field unexplained. **Fixed:** *Partial refunds return gift-card and loyalty value in proportion* — A partial refund previously re-minted the entire gift-card spend and clawed back 100% of earned loyalty points the moment the order reached the refunded state, and restored nothing on a smaller slice — so a buyer could keep goods plus the full re-minted gift-card balance. Refunds now re-mint gift-card spend, claw earned loyalty, and restore redeemed loyalty points in exact proportion to the amount refunded, and a partial-then-final refund sequence converges on exactly the amount returned. · *Redeemed loyalty points are restored on refund* — Loyalty points spent as a checkout tender were never returned when the order was refunded, even though gift-card spend was — an inconsistency that cost the customer. Redeemed points are now restored on refund, in proportion to the refunded amount. · *Referral rewards reverse on refund or cancel* — A referral's qualifying first order being refunded or cancelled now rolls back the both-rewarded completion and decrements the referrer's leaderboard count, closing a buy-then-refund reward-farming path. The reversal is claimed once so a re-delivered refund webhook cannot double-reverse. · *Inventory and quote state transitions are race-proof* — Stock-transfer reconcile, inventory receive and reverse, write-off reversal, allocation commit, cycle-count finalize, and quote accept and convert all read state and then mutated it without an atomic guard, so two concurrent calls could both proceed — double-crediting a destination shelf, double-restocking, or minting two orders from one quote. Each transition now claims its state atomically and proceeds only if it won the claim. The stock-transfer and inventory-receipt lifecycles are additionally validated against a declared state machine. **Security:** *Privacy export and erasure now enforce the operator role matrix* — The data-subject export (full customer PII) and erasure routes did not pass through the role check every other mutating admin route uses, so a read-only viewer could export a customer's data and run an irreversible erasure. Both are now gated by the role matrix, and the mutating admin routes were swept to confirm each maps to a required permission. · *Operator audit log no longer self-reports tampering under concurrency* — Two operator actions recorded at the same instant could each read the same chain head and append rows sharing one previous-hash, forking the tamper-evident chain so verification reported a break where no tampering occurred. Audit appends are now serialized per chain, so the hash chain stays linear under concurrent writes. · *Gift-card ledger is now tamper-evident* — The gift-card balance ledger carried no cryptographic linkage, so a direct database edit that inflated a balance or dropped a debit passed balance reads undetected. Each ledger row now carries a per-card hash chain (the same construction the operator audit log uses), and a verification pass surfaces any insert, rewrite, reorder, or deletion. · *Erasure, passkey-revoke, and sign-out terminate live sessions* — The sealed sign-in cookie is self-validating for up to 14 days, so an erased or anonymized account stayed usable until the cookie expired. A per-customer session boundary now lets erasure, passkey revocation, and explicit sign-out invalidate every cookie minted before the boundary. A customer with no boundary is unaffected, so upgrading does not sign anyone out. · *Marketing email honors the suppression list everywhere* — Wishlist price-drop and back-in-stock alerts did not consult the marketing suppression list, and a newsletter one-click unsubscribe recorded the opt-out without adding the address to suppressions — so a hard-bounced, complained, or unsubscribed address could still be mailed by another flow. Both paths now consult and feed the suppression list, matching the transactional and campaign paths. · *Per-recipient throttle on magic-link sign-in* — Magic-link minting was throttled per source address only, so a distributed source could email-bomb one victim's inbox. A per-recipient limit now caps how often a link can be sent to a single address, alongside the existing per-source limit. · *Strict validation of inbound webhook idempotency keys* — The inbound webhook idempotency key was validated against a broad printable-ASCII pattern that accepted path-traversal shapes. It now uses the framework's strict idempotency-key guard, which refuses slash, backslash, and dot-dot sequences. The strict profile permits a space (harmless in the parameterized lookup) while refusing the traversal shapes. **Migration:** *Six new D1 migrations* — 0220 adds the gift-card ledger hash-chain columns; 0221, 0223, 0224, and 0225 add proportional-reversal tracking to gift-card redemptions, loyalty transactions, the loyalty earn log, and referral invitations; 0222 adds the per-customer session-revocation boundary table. All apply cleanly over existing rows (new columns default to nothing-reversed-yet; the revocation table is empty, which is the default-allow state). Run pending migrations and sync theme assets as usual. · *Optional APPLE_PAY_DOMAIN_ASSOCIATION environment variable* — To show the Apple Pay wallet button, set APPLE_PAY_DOMAIN_ASSOCIATION to the file contents Stripe provides (Stripe owns Apple merchant validation, so no Apple Developer account is needed) and register each web domain with Stripe. The shop serves the value verbatim at /.well-known/apple-developer-merchantid-domain-association on both the edge and container. Unset, the path returns 404 and the Apple Pay button stays hidden; card, Google Pay, Link, and PayPal are unaffected.
+
 - v0.4.23 (2026-06-06) — **A stolen sign-in cookie stops working on another device, payment-provider outages fail fast and recover, replayed payment webhooks are refused, and the staff audit log is rewrite-evident.** A security-hardening release. The signed-in session cookie now carries a device fingerprint — a cookie lifted from one browser softly signs out instead of working anywhere for two weeks. Payment-provider calls run behind a circuit breaker, so a provider brown-out fails fast into the existing payment-unavailable page and recovers automatically instead of hanging every checkout. A captured payment-webhook payload can no longer be replayed inside the signature tolerance window. And the staff-activity audit log is anchored with post-quantum checkpoint signatures, with a verification endpoint that detects any rewrite of its history. **Security:** *The sign-in cookie is pinned to the device that signed in* — The signed-in session cookie was tamper-proof but portable — exfiltrated once, it worked from any device until expiry. Signing in now embeds a fingerprint of the signing-in browser inside the sealed cookie, and every authenticated request re-checks it in constant time. A mismatch signs the visitor out gently to the sign-in page rather than failing the request mid-page; network changes don't trip it (the fingerprint deliberately excludes the IP address), and sessions issued before this release continue to work until they expire naturally. · *Payment-provider calls are circuit-broken and retried where safe* — A payment-provider brown-out previously failed every checkout serially, each waiting out the full network timeout. Provider calls now run behind a circuit breaker: repeated failures trip it, subsequent checkouts fail fast into the existing payment-unavailable page, and the circuit closes again when the provider recovers. Idempotent calls — reads and writes carrying an idempotency key — retry through brief blips; non-idempotent calls never retry. The TLS configuration for provider connections is unchanged. · *Replayed payment webhooks are refused* — A captured, validly-signed payment-webhook payload could be replayed within the signature timestamp tolerance and re-drive order transitions. Each event is now recorded on first receipt and a replay of the same event answers as an already-processed no-op — enforced with a single atomic write, so two concurrent deliveries of the same event also collapse to one. Replay records expire with the signature tolerance window. · *The staff audit log detects history rewrites* — Staff-activity audit rows were hash-linked, which catches tampering with a single row but not a consistent rewrite of the whole chain. The chain is now anchored with periodic checkpoint signatures (ML-DSA, the same signing the framework audit chain uses), and `/admin/operators/audit/verify` reports both link integrity and checkpoint verification — a rewritten history fails the check. Stores that disable destructive operations behind a second approver were also evaluated: with one active operator the gate would deadlock the store, so gift-card voids, refunds, and operator disables remain single-approver — role-gated, bounded, reversible, and audited — with the stance and its revisit condition documented in the module.
 
 - v0.4.22 (2026-06-06) — **Privacy export covers every table, erasure revokes the login, one-click unsubscribe actually works, and bounces feed the suppression list.** A privacy and email-integrity release. The data-subject export now includes reviews, consent history, wishlist, surveys, and recently-viewed data — with a manifest that makes any absent section visible. Erasing a customer also deletes their passkeys and social-login links and revokes live sessions, so a deleted account can no longer sign in. The one-click unsubscribe that mail clients invoke from their native button now works (it pointed at a route that didn't exist), a new intake endpoint feeds provider bounce and complaint webhooks into the marketing suppression list, support-ticket edge cases are fixed, and the CSV exports share one complete injection-neutralizer. **Added:** *Bounce and complaint webhook intake* — A new `POST /api/webhooks/mail-bounce` endpoint accepts bounce and complaint webhooks from Postmark, SES, or Resend (selectable per request). Spam complaints and permanently-dead addresses land on the marketing suppression list — transactional mail still flows — and campaign metrics gain the bounce events they were built to read. The endpoint is armed only when `MAIL_BOUNCE_SECRET` is set and the provider presents it in the `x-mail-bounce-secret` header; unconfigured, it answers 503 and accepts nothing. **Fixed:** *The data-subject export includes every table that holds the customer* — The export bundle silently omitted reviews, consent history, wishlist items, survey responses, and recently-viewed data. All five are now included, and the bundle carries a completeness manifest listing every section as exported, empty, or absent — an omission is visible rather than silent. · *Erasure revokes the customer's ability to sign in* — Deleting a customer scrubbed their profile but left passkeys, Google/Apple login links, and live sessions intact — the "deleted" account could sign right back in. Erasure now deletes the passkeys and social-login links, revokes live portal sessions, and tombstones the email lookup hash irreversibly, while the anonymized record survives for order-history integrity. · *One-click unsubscribe works from the mail client's native button* — The unsubscribe headers stamped on every campaign pointed at a route that didn't exist, and the unsubscribe endpoint read its token from the form body — which a mail client's native one-click POST never carries. The header now points at the real endpoint and the token rides the URL, so the RFC 8058 one-click flow a mail client fires actually unsubscribes. The browser confirmation page is unchanged. · *Support tickets: reopen on customer reply, atomic tags, honest first-response time* — A customer reply to a resolved ticket silently disappeared from every operator queue — it now reopens the ticket with a fresh activity timestamp. Concurrent tag edits no longer overwrite each other (tag changes are single-statement updates). And an internal-only operator note no longer counts as the first response — only a reply the customer can actually see stamps the first-response time. · *CSV exports share one complete injection neutralizer* — The order-export and segment-members CSV exports each carried their own formula-injection defense, and both missed the tab, carriage-return, newline, and pipe vectors. Both now compose the framework's CSV cell guard, which covers the full vector set — including signed numerics, which the previous neutralizers deliberately exempted.

package/README.md

@@ -167,6 +167,11 @@ node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('b
 #   STRIPE_API_KEY (sk_test_… or sk_live_…)
 #   STRIPE_WEBHOOK_SECRET (whsec_…)
 #   STRIPE_PUBLISHABLE_KEY (pk_test_… or pk_live_…)
+# Apple Pay (optional — only to show the Apple Pay wallet button):
+#   APPLE_PAY_DOMAIN_ASSOCIATION (paste the file's contents from your
+#   Stripe dashboard; served verbatim at the apple-developer-merchantid
+#   well-known path so Apple can verify the domain). A plaintext public
+#   file — `npx wrangler secret put` works, or set it as a plain var.
 
 # 3. Apply database migrations
 npx wrangler d1 migrations apply blamejs-shop --remote
@@ -198,7 +203,7 @@ variables. A signed-in operator can see the live on/off status of each at
 |-------------|-----------------|----------|-------|
 | **Admin console** | The bearer-token JSON API + the `/admin` browser console (sign-in, setup wizard, dashboard). | `ADMIN_API_KEY` (≥ 16 chars — use 32 random bytes) | Sign in at `/admin` by pasting the key. Without it the admin surface doesn't mount. |
 | **Card checkout (Stripe)** | Checkout + the Payment Element on the pay page; refunds; subscription billing. | `STRIPE_API_KEY` (`sk_…`), `STRIPE_WEBHOOK_SECRET` (`whsec_…`), `STRIPE_PUBLISHABLE_KEY` (`pk_…`) | Point your Stripe webhook at `/api/webhooks/stripe`. Without these the shop stays browsable but checkout doesn't mount. |
-| **Apple Pay & Google Pay** | One-tap wallet buttons (Express Checkout Element) on the pay page. | Stripe (above) **+** register each web domain: `POST /admin/payment-method-domains {"domain_name":"shop.example.com"}` | Stripe performs Apple merchant validation and hosts the association file — **no Apple Developer account needed**. Apex, `www`, and each subdomain register separately; a live-mode registration also covers sandbox. |
+| **Apple Pay & Google Pay** | One-tap wallet buttons (Express Checkout Element) on the pay page. | Stripe (above) **+** register each web domain: `POST /admin/payment-method-domains {"domain_name":"shop.example.com"}`; for Apple Pay also set `APPLE_PAY_DOMAIN_ASSOCIATION` to the file Stripe provides | Google Pay needs no extra step. For **Apple Pay**, the button renders only after Apple verifies the domain by fetching `/.well-known/apple-developer-merchantid-domain-association` — download that file's contents from your Stripe dashboard and paste them verbatim into `APPLE_PAY_DOMAIN_ASSOCIATION`; the shop serves them unchanged at that path. **No Apple Developer account needed** (Stripe owns merchant validation). Until the value is set the route 404s and the Apple Pay button stays hidden; every other method is unaffected. Apex, `www`, and each subdomain register (and serve the file) separately; a live-mode domain registration also covers sandbox. |
 | **Sign in with Google** | A *Continue with Google* button on `/account/login` (OIDC). | `GOOGLE_OAUTH_CLIENT_ID`, `GOOGLE_OAUTH_CLIENT_SECRET`, `SHOP_ORIGIN` (e.g. `https://shop.example.com`) | Create a Google Cloud **OAuth 2.0 Web** client; add `<SHOP_ORIGIN>/account/auth/google/callback` as an Authorized redirect URI; consent-screen scopes `openid email profile`. The button appears only when all three are set. |
 | **Sign in with Apple** | A *Continue with Apple* button on `/account/login` (OIDC). | `APPLE_TEAM_ID`, `APPLE_KEY_ID`, `APPLE_CLIENT_ID` (your **Services ID**), `APPLE_PRIVATE_KEY` (the `.p8` key contents), `SHOP_ORIGIN` | Needs an **Apple Developer Program** membership. Create a Services ID, enable Sign in with Apple, add `<SHOP_ORIGIN>/account/auth/apple/callback` as a Return URL, and create a Sign-in-with-Apple key (`.p8`). The shop mints Apple's ES256 client secret from the key at boot (re-minted each deploy, inside Apple's 6-month window). The button appears only when all five are set. |
 | **PayPal checkout** | A native PayPal button on `/checkout` (PayPal Orders v2 — create / approve / capture), distinct from PayPal-through-Stripe. | `PAYPAL_CLIENT_ID`, `PAYPAL_SECRET` (a PayPal REST app), `PAYPAL_WEBHOOK_ID`, `PAYPAL_ENV` (`sandbox`\|`live`); Stripe checkout must also be live | The shop exchanges the OAuth2 token and creates / captures orders server-side; the button drives `/checkout/paypal/create` + `/checkout/paypal/capture`. Point a PayPal webhook at `/api/webhooks/paypal` (verified through PayPal's API). Allow `www.paypal.com` in your CSP `script-src` / `frame-src` (as you would `js.stripe.com`). |

package/SECURITY.md

@@ -165,6 +165,19 @@ node -e "
   `hmac-sha256-stripe`) inside `lib/payment.js` before any FSM
   transition runs. An unsigned or out-of-window delivery never
   touches origin resources.
+- **Apple Pay domain-association file.** Apple verifies the domain
+  before it will render the Apple Pay wallet button, and it verifies by
+  fetching `/.well-known/apple-developer-merchantid-domain-association`.
+  The shop serves that path verbatim from `APPLE_PAY_DOMAIN_ASSOCIATION`
+  (the file's contents, supplied by Stripe) — a static, unauthenticated,
+  state-free public file with no transform applied. Apple's verification
+  crawler may omit `Accept-Language`, so the path is on the bot guard's
+  skip list (the same machine-caller exemption the `/_/` ticks use)
+  rather than being 403'd as automated traffic; this exposes nothing
+  beyond the public association bytes. When the value is unset the route
+  returns 404 and the button stays hidden — no other payment method is
+  affected. Set the value identically on the Worker and the container;
+  apex, `www`, and each subdomain serve their own file.
 - **Worker → Container trust boundary.** The Worker treats the
   container as untrusted-for-D1: it never proxies arbitrary headers
   into D1, only the explicit `sql` + `params` from the bridge body.