@redeemid/emdash 0.0.24 → 0.0.25

package/docs/shop.md

@@ -0,0 +1,65 @@
+# Shop and preferences
+
+## Shop
+
+Products, collections, search and the cart come from the Storefront API. Shopify works out prices, discounts, taxes and stock, and runs checkout. EmDash has no Shopify plugin underneath, so these components are the storefront.
+
+```astro
+<!-- layout, once -->
+<Cart drawer />
+<CartDrawer />
+<RedeemIDClient />
+<!-- /shop/ (rendered on demand for filters and pages) -->
+<Collection handle="shop" productHref="/shop/{handle}/" showTitle browse quickAdd />
+<!-- /shop/[handle]/ -->
+<Product handle={Astro.params.handle} heading="h1"><p>No such product.</p></Product>
+<Recommendations handle={Astro.params.handle} productHref="/shop/{handle}/" />
+<!-- /search/ -->
+<ProductSearch productHref="/shop/{handle}/" />
+<!-- /cart/ -->
+<CartView productHref="/shop/{handle}/" />
+<!-- anywhere -->
+<Contribution handle="support" amounts={[5, 10, 25]} />
+```
+
+- `<Product>`: images (with thumbnails), title, price and sale price, description (`html` for Shopify's formatted one), a picker per option (Size, Color…), one-time or subscription when the product has selling plans, quantity, Add to cart and Buy now. On a product's own page (`heading="h1"`) it prints Product structured data.
+- `<Collection>`: up to 50 products as cards linking to `productHref`. `browse` adds Shopify's filters (set up in the Search & Discovery app), sort orders and pages, read from the page URL. `quickAdd` adds Add to cart on cards that need no choice.
+- `<ProductSearch>`: a search box with Shopify's matches, filters, sorting and pages. `boxOnly` gives just the box, for a header, sending searches to `action`.
+- `<Recommendations>`: Shopify's "You may also like" (`intent="related"`) or "Pair it with" (`intent="complementary"`) for a product.
+- `<CartView>`: each line with a quantity to change (0 removes it) and Remove, a discount code field, the totals and Checkout.
+- `<CartDrawer>`: the same cart in a modal dialog that slides in. With `<RedeemIDClient />` on the page, Add to cart opens it in place and `<Cart drawer />` opens it instead of going to checkout.
+- `<Contribution>`: pay what you want. Price a product at 1.00, and the amount the reader picks becomes the quantity.
+- `<Cart>`: the item count, linking to checkout, or to `href` (a cart page), or opening the drawer with `drawer`.
+
+Everything works without JavaScript: the forms post to `/_emdash/api/auth/redeemid/cart-edit`, which reads every product, variant, option and selling plan from Shopify again and only changes the visitor's own cart. `<RedeemIDClient />` adds the drawer, option pickers that follow the choice, and search suggestions. A new cart carries the `_redeemid_page` attribute (the page the first item was added on), which shows on the order in Shopify admin. Editors get the same with the Product, Collection, Product search and Contribution blocks.
+
+**Signed-in checkout.** When a signed-in member checks out, RedeemID puts their store sign-in (the Customer Account API access token, kept only in the server-side session, encrypted with a key kept in the site's database, and renewed when it's about to expire) on the cart, so Shopify's checkout opens signed in and the order lands on their customer record, where your Flow or apps tag it. If that can't be done, they check out as a guest with their email filled in. Set `checkout: { signIn: false }` to always use a guest checkout; then the tokens aren't kept at all.
+
+**Local prices.** Set `market: { country: "visitor" }` to show each visitor prices in their own market (from Cloudflare's `CF-IPCountry`), or a fixed `country` and `language`. Markets are set up in Shopify.
+
+**Shoppers' agents.** Shopify runs a Storefront MCP server for every store at `https://<store domain>/api/mcp`, for AI agents that browse, build a cart and check out. Point shopping agents there; RedeemID's own tools are for staff.
+
+## Preferences
+
+```ts
+preferences: [
+	{ key: "preferences.topics" },                  // members can change it
+	{ key: "preferences.level", access: "view" },   // members only see it
+],
+```
+
+Define each field in Shopify (**Settings → Custom data → Customers**); the definition sets its name, type and limits. List the ones members get, in the order to show them. Reading and saving use the Admin API app (`REDEEMID_SHOPIFY_ADMIN_APP_CLIENT_ID` with `read_customers` and `write_customers`), always on the signed-in member's own customer. Fields in the `membership` namespace are never offered, and preferences never open content.
+
+`<Preferences>` (or its block) is a form that works without JavaScript. Visitors see its `signed-out` slot.
+
+| Shopify type | Value |
+| --- | --- |
+| Single line text | A string; with choices, one of them |
+| Multi-line text | A string |
+| List of single line text | A list of strings; with choices, each one of them |
+| True or false | `true` or `false` |
+| Integer | A whole number |
+| Decimal | A number, as a string |
+| Date | `YYYY-MM-DD` |
+
+Every value is checked against the definition first. One refusal saves nothing, and an empty value clears the field. Scripts can `GET` `/_emdash/api/auth/redeemid/preferences` for `{ fields }`, or `POST` JSON `{ values: { "namespace.key": value } }`. A refused save answers `400` with `fields` mapping each key to `unknown_field`, `read_only`, `invalid_type`, `invalid_choice`, `invalid_length` or `invalid_range`. Saves are limited to 10 a minute per member (`429`). From your own code, `readPreferences(config, customerId)` and `savePreferences(config, customerId, values)` in `@redeemid/emdash/preferences` do the same (no rate limit there; `config` comes from `siteConfig()`).

package/docs/shopify-flow.md

@@ -16,7 +16,7 @@ The examples use a product called "Membership" and the tag `member`. Use your ow
 
 Use **Order paid** rather than Order created, so an unpaid order (for example, a payment that's still pending) doesn't open anything. Also add `order.customer` exists to the condition. A checkout always has an email, but a draft order may not have a customer.
 
-If the plan is meant to show as a gift, also add an **Update customer metafield** action that sets `membership.gift_until` (type date). See [membership dates](../README.md#membership-dates).
+If the plan is meant to show as a gift, also add an **Update customer metafield** action that sets `membership.gift_until` (type date). See [membership dates](staff.md#membership-dates).
 
 ## 2. A refund removes it
 

package/docs/shopify-setup.md

@@ -33,13 +33,13 @@ Give the app the `read_customers` and `write_customers` Admin API scopes, plus `
 
 Without the client ID, subscribe them to that URL yourself. If the app already sends webhooks to another site, add this URL as extra subscriptions.
 
-The client ID and those scopes also run the staff tools (member resync and tag edits written to Shopify), member preferences, and the reads that keep tags in order (see the README). RedeemID uses the client credentials grant, which works when the app and the store are in the same Shopify organization. For the **Also request erasure in Shopify** button on a member's page, add the optional `write_customer_data_erasure` scope.
+The client ID and those scopes also run the staff tools (member resync and tag edits written to Shopify), member preferences, and the reads that keep tags in order (see [staff tools](staff.md#staff-tools)). RedeemID uses the client credentials grant, which works when the app and the store are in the same Shopify organization. For the **Also request erasure in Shopify** button on a member's page, add the optional `write_customer_data_erasure` scope.
 
-Shopify's compliance topics (`customers/data_request`, `customers/redact`, `shop/redact`) can't be registered by the button: they reach only apps that declare them in the app's configuration, under `[webhooks.privacy_compliance]`. Point all three at the same webhook URL. RedeemID logs each one on the Privacy page and acts on it (see the README's privacy requests).
+Shopify's compliance topics (`customers/data_request`, `customers/redact`, `shop/redact`) can't be registered by the button: they reach only apps that declare them in the app's configuration, under `[webhooks.privacy_compliance]`. Point all three at the same webhook URL. RedeemID logs each one on the Privacy page and acts on it (see [privacy requests](staff.md#privacy-requests)).
 
 ## 3. The site
 
-Add the package and config as in the [README](../README.md#quick-start), with `shop` set to the store's domain. A custom customer-account domain works as well as `*.myshopify.com`.
+Add the package and config as in [getting started](getting-started.md#3-configure), with `shop` set to the store's domain. A custom customer-account domain works as well as `*.myshopify.com`.
 
 Set the secrets. On Cloudflare Workers:
 
@@ -65,4 +65,4 @@ On Workers, also add a Cron Trigger to the site's Worker, as EmDash's deployment
 3. Click **Sign in**, sign in with that customer's email, and you come back to the post, unlocked.
 4. Add or remove the tag in Shopify; the post opens or locks again once the webhook arrives.
 
-If sign-in sends you back with `?redeemid_notice=…`, the code says why: `not_configured` means the client ID or `shop` is missing, and `sign_in_unavailable` means store discovery failed, usually a wrong `shop`. The README lists [every notice](../README.md#notices).
+If sign-in sends you back with `?redeemid_notice=…`, the code says why: `not_configured` means the client ID or `shop` is missing, and `sign_in_unavailable` means store discovery failed, usually a wrong `shop`. The reference lists [every notice](reference.md#notices).

package/docs/staff.md

@@ -0,0 +1,81 @@
+# Staff tools, webhooks and privacy
+
+## Staff tools
+
+With `REDEEMID_SHOPIFY_ADMIN_APP_CLIENT_ID` set, RedeemID gets an Admin API token for the webhook app with the client credentials grant. The app must be in the same Shopify organization as the store, as Dev Dashboard apps are, and needs `read_customers` and `write_customers`. Then, under **Plugins → RedeemID**:
+
+- **Member detail.** Levels, tags and features; resync from Shopify; add and remove tags. Tag edits are made in Shopify and read back. Nothing is granted on the site.
+- **Site user.** Signing in links a customer to the site user with the same verified email. When the emails differ, staff link the customer to an existing Subscriber by that user's email on the member's page (never a staff account, never a user linked to another customer), or unlink them. This part needs no Admin API app.
+- **Bulk resync.** Reads the 25 members synced longest ago, few enough for the Workers free limit of 50 database queries a request. Press it again for the next 25. It never runs on its own.
+- **Webhook subscriptions.** Webhooks → Setup lists the store's subscriptions to this site and registers any that are missing. A topic Shopify refuses, such as `customers/merge` without `read_customer_merge`, is named with the reason and doesn't stop the others. `customers/redact` stays in the app's own settings.
+- **Access test.** A collection, an entry, terms and a reader's tags in; the verdict out.
+
+Resync updates email, name, tags, email marketing consent and the membership dates. Enabled or disabled status comes only from the enable and disable webhooks. With the app set up, two more things read the customer from the Admin API as it is now: every sign-in (and Refresh membership), and every `customer.tags_added` or `customer.tags_removed` webhook. Those topics carry only the change and can arrive out of order, so reading the current tags keeps the mirror right. Without the app, or when the read fails, the webhook's change is applied as sent.
+
+### Membership dates
+
+A subscription app or Shopify Flow can keep these customer metafields, as dates (`YYYY-MM-DD`):
+
+| Metafield | Shown |
+| --- | --- |
+| `membership.member_since` | As the start date on the member card, in place of when the tag arrived |
+| `membership.renews_on` | "Renews on ..." |
+| `membership.ends_on` | "Ends on ...", for a pass that doesn't renew |
+| `membership.gift_until` | "Gift membership until ...", while it's in the future |
+
+RedeemID reads them with the Admin API (resync, sign-in, tag webhooks), so they need the Admin API app. They're for display only: access still comes from tags alone, and nothing on the site ends access on these dates. Time-boxed access is a Flow that waits and removes the tag (see [Shopify Flow recipes](shopify-flow.md)).
+
+## Webhooks, app events and reports
+
+Members gain and lose access only when Shopify sends tag changes, so RedeemID shows what arrived and warns when deliveries stop.
+
+- **Webhooks → Received.** Each delivery's topic, what became of it (processed, skipped, older than what's stored, not used) and the customer ID, with counts of deliveries turned away (bad signature) and failed (storage errors; Shopify sends those again).
+- **Webhooks → Health.** Once a day RedeemID registers again any subscription Shopify dropped (with the Admin API app), and warns when no webhook has come in for a number of days (3 by default, 0 turns it off), or when deliveries were turned away or failed in the last day. **Check now** runs it at once. Warnings show on the page and the dashboard widget. If you enter an address on the Health tab and the site has an EmDash email provider, they also go by email: once when problems start or change, then once a week while they last.
+- **Webhooks → Setup.** The endpoint, whether signatures can be checked, and the subscriptions.
+- **App events.** What RedeemID did and what came of it: webhooks received, turned away and failed, sign-ins and refusals (by reason), Admin API calls (by operation, with timings), resyncs, tag edits, webhook registrations, settings saves, outbound events that failed, metered reads and the health checks. Filter by event or show problems only. Entries hold ids, labels and outcomes, never bodies, tokens or emails. Failed outbound events also keep the event body (ids and levels, never an email or a name) so they can be sent again.
+- **Reports.** Members on each level, who joined and left in the last 30 days and by week for 12 weeks (from each member's tag dates), sign-ins and metered reads.
+
+App events and delivery records are kept 30 days. The daily check runs from EmDash's scheduler: on Node it runs by itself; on Cloudflare Workers, add a Cron Trigger to the site's Worker as EmDash's deployment guide describes. The plugin asks for `email:send` only to send these warnings.
+
+## AI agents and the command line
+
+Staff questions as data, for AI agents and scripts. Every one needs an administrator, reads what the site has synced, and never grants access, edits a rule or returns a secret.
+
+| MCP tool | Command | What it answers |
+| --- | --- | --- |
+| `explain_access` | `access <collection>` | Can this reader read this entry, and why. Give the entry by `id` or `terms`, and the reader by `tags`, `customerId` or `signedIn: false`. |
+| `list_levels` | `levels` | Every level, its tag groups, the levels it includes, wall text and join link |
+| `get_rules` | `rules` | How rules combine, every rule, the meter, teasers, features and file rules |
+| `get_member` | `member <id or email>` | One member: status, tags, levels with start dates, past levels, features, last sync |
+| `site_health` | `health` | Each setting (set or not, never a value), the last webhook, open privacy requests, ignored text replacements |
+| `level_changes` | `changes --since <date>` | Who joined or left a level since a date |
+| `find_products` | `products <words>` | Search the Shopify catalog: handles, titles, prices, stock |
+| `get_product` | `product <handle>` | One product: options, variants, prices, selling plans |
+| `get_collection` | `collection <handle>` | One collection: its products and the filters Shopify offers |
+
+With `agents: { actions: true }`, three actions are offered too: `resync_member` (`resync <customer id>`), `resync_batch` (`resync-batch`, 25 members) and `edit_member_tags` (`tags <customer id> --add a,b --remove c`, marked destructive for agents).
+
+**Agents** use EmDash's MCP server at `/_emdash/api/mcp` with an API token that has the `mcp:tools` or `mcp:tools:redeemid` scope. The tools stay off until an administrator turns them on for RedeemID under **Plugins**, and a release that changes the list needs approving again. Names carry the prefix, such as `redeemid__explain_access`.
+
+**The command line** signs in the way EmDash's CLI does: `--token`, `EMDASH_TOKEN`, or the token `emdash login` saved. The site comes from `--url` or `EMDASH_URL`. Output is JSON.
+
+```sh
+npx -p @redeemid/emdash redeemid-emdash access posts --id my-story --tags gold-member --url https://example.com
+npx -p @redeemid/emdash redeemid-emdash member jane@example.com
+```
+
+Each command POSTs JSON to a staff-only route under `/_emdash/api/plugins/redeemid/`, named after its tool with hyphens (`explain_access` is `explain-access`). Scripts can call those routes directly.
+
+## Privacy requests
+
+What RedeemID keeps about a member: the synced record (Shopify customer ID, email, name, tags and when each started, account status, first sign-in, last sync, whether the email was verified, email and SMS marketing consent, and the membership dates) and their meter. Preference answers stay on the Shopify customer, and webhook deliveries keep only a topic and a time. Erasing on the site never erases Shopify data; it can only ask Shopify to.
+
+| Started by | What happens |
+| --- | --- |
+| A member, with `<YourData>` | **Download my data** returns their record and meter as JSON. **Delete my data** needs a ticked box, erases both, and signs them out. |
+| Staff, on a member's page | **Export data**, **Erase site data**, and **Also request erasure in Shopify** (orders included, after Shopify's wait; **Cancel the Shopify erasure** withdraws it). The Shopify request needs the `write_customer_data_erasure` scope. |
+| Shopify `customers/data_request` | An open request on the **Privacy** page. Press **Export and mark done**, then send the export to the store owner. |
+| Shopify `customers/redact` | The member's record and meter are erased. |
+| Shopify `shop/redact` | Every member record and meter is erased, a hundred at a time, so even a large shop fits in one request on the Workers Free plan. |
+
+The Privacy page shows each request's source and Shopify customer ID, never an email or a name. The daily check deletes finished requests after a year; open ones stay until staff mark them done. An erase sends the `member.erased` event so a CRM can delete its copy too. The site's own user account stays; delete it under Users if the person asks. The JSON route is `/_emdash/api/auth/redeemid/privacy`: `GET` downloads, `POST` with `confirm=yes` erases, only for the signed-in member and only from the site's own origin.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@redeemid/emdash",
-	"version": "0.0.24",
+	"version": "0.0.25",
 	"description": "Shopify customer accounts, member levels and paywalls for EmDash sites. Shopify runs commerce; EmDash runs content.",
 	"type": "module",
 	"license": "MIT",
@@ -14,6 +14,7 @@
 		".": "./src/index.ts",
 		"./access": "./src/access.ts",
 		"./search": "./src/search-guard.ts",
+		"./cache": "./src/route-cache.ts",
 		"./guard.ts": "./src/guard.ts",
 		"./rate-limit-cloudflare.ts": "./src/rate-limit-cloudflare.ts",
 		"./templates.ts": "./src/templates.ts",

package/src/api-version.ts

@@ -3,4 +3,4 @@
  * when something is added, the major part when something stable changes or
  * goes. Separate from the package version.
  */
-export const API_VERSION = "1.3.0";
+export const API_VERSION = "1.4.0";

package/src/components/Content.astro

@@ -36,7 +36,8 @@
  */
 import { PortableText } from "emdash/ui";
 
-import { canRead, entryRequirement, readEntry, viewer, type Terms, type Verdict } from "../access.js";
+import { canRead, entryRequirement, entryRuleFor, readEntry, viewer, type Terms, type Verdict } from "../access.js";
+import { noRouteCache } from "../route-cache.js";
 import { holdsItem, sections, soldItem, splitAtPaywall, teaser } from "../blocks-names.js";
 import { siteConfig } from "../site-config.js";
 import { text } from "../text.js";
@@ -101,6 +102,11 @@ const schema =
 				hasPart: { "@type": "WebPageElement", isAccessibleForFree: false, cssSelector: ".redeemid-locked" },
 			}).replace(/</g, "\\u003c")
 		: null;
+// A body that reads differently for members, or is free only until a date,
+// never goes into the route cache, whatever the page's hint or the site's
+// route rules say.
+const freeUntil = entryRuleFor(config, collection, id)?.openUntil;
+if (lockedEntry || item || (freeUntil && Date.now() < Date.parse(freeUntil))) noRouteCache(Astro);
 const metered = verdict.reason === "metered" ? (verdict as Verdict) : null;
 const week = metered?.meter?.period === "week";
 const left = metered?.meterLeft ?? 0;

package/src/components/Gate.astro

@@ -11,6 +11,7 @@
  * Pass `levels` to lock a part of a page to specific levels instead.
  */
 import { canRead, type Terms } from "../access.js";
+import { noRouteCache } from "../route-cache.js";
 import LockedPanel from "./LockedPanel.astro";
 
 interface Props {
@@ -23,6 +24,8 @@ interface Props {
 
 const { collection = "", terms, levels, id } = Astro.props;
 const verdict = await canRead(Astro, { collection, terms, id }, levels ? { levels } : undefined);
+// What shows depends on the reader: never in the route cache.
+if (verdict.reason !== "open") noRouteCache(Astro);
 ---
 
 {verdict.allowed ? (

package/src/components/MemberCard.astro

@@ -12,6 +12,7 @@
  * membership reads it from the store again.
  */
 import { accountUrl, badgeColor, membership, meterUsage, refreshUrl, signInUrl, signOutUrl, viewer } from "../access.js";
+import { noRouteCache } from "../route-cache.js";
 import { featuresFor } from "../features.js";
 import { siteConfig } from "../site-config.js";
 import { text, textParts } from "../text.js";
@@ -24,6 +25,8 @@ interface Props {
 const config = await siteConfig(Astro.locals);
 const { title = text(config, "Your membership") } = Astro.props;
 const v = await viewer(Astro);
+// One member's own details: never in the route cache.
+noRouteCache(Astro);
 const here = Astro.url.pathname + Astro.url.search;
 const m = v.member;
 const disabled = m?.status === "disabled";

package/src/components/Plan.astro

@@ -16,6 +16,7 @@
  * - join: anyone else.
  */
 import { closure, directLevels, membership, topLevels, viewer } from "../access.js";
+import { noRouteCache } from "../route-cache.js";
 import { siteConfig } from "../site-config.js";
 import { money, plan as loadPlan, storeContext, type Plan } from "../storefront.js";
 import { text } from "../text.js";
@@ -51,6 +52,8 @@ if (config) {
 const price = money(p?.price);
 const here = Astro.url.pathname + Astro.url.search;
 const v = levels.length > 0 ? await viewer(Astro) : null;
+// Held, upgrade, renew or join depends on the reader: never in the route cache.
+if (levels.length > 0) noRouteCache(Astro);
 const live = v?.member && v.member.status !== "disabled" ? v.member : null;
 const direct = live ? directLevels(live.tags, all) : [];
 const top = topLevels(v?.levels ?? [], all);

package/src/components/Preferences.astro

@@ -9,6 +9,7 @@
  *   <Preferences title="Your preferences" />
  */
 import { viewer } from "../access.js";
+import { noRouteCache } from "../route-cache.js";
 import { preferencesConfigured, readPreferences, type PreferenceField } from "../preferences.js";
 import { siteConfig } from "../site-config.js";
 import { text } from "../text.js";
@@ -23,6 +24,8 @@ interface Props {
 const config = await siteConfig(Astro.locals);
 const { title = text(config, "Your preferences"), heading = "h2", label = text(config, "Save preferences") } = Astro.props;
 const v = await viewer(Astro);
+// One member's own details: never in the route cache.
+noRouteCache(Astro);
 const m = v.member;
 let fields: PreferenceField[] = [];
 let failed = false;

package/src/components/YourData.astro

@@ -8,6 +8,7 @@
  *   <YourData />
  */
 import { viewer } from "../access.js";
+import { noRouteCache } from "../route-cache.js";
 import { siteConfig } from "../site-config.js";
 import { text } from "../text.js";
 
@@ -19,6 +20,8 @@ interface Props {
 const config = await siteConfig(Astro.locals);
 const { title = text(config, "Your data"), heading = "h2" } = Astro.props;
 const v = await viewer(Astro);
+// One member's own details: never in the route cache.
+noRouteCache(Astro);
 const route = "/_emdash/api/auth/redeemid/privacy";
 const here = Astro.url.pathname;
 const H = heading;

package/src/contract.ts

@@ -24,6 +24,7 @@ export const MODULES = {
 	"@redeemid/emdash/events": ["signBody"],
 	"@redeemid/emdash/text": ["STRINGS", "text", "textParts"],
 	"@redeemid/emdash/search": ["readableResults"],
+	"@redeemid/emdash/cache": ["cacheEntry", "cachePage", "noRouteCache", "CACHE_TAG"],
 } as const;
 
 /** Public JSON routes under /_emdash/api/auth/redeemid/. */

package/src/guard.ts

@@ -17,6 +17,12 @@
  * text included) could be stored and served to anyone. A later
  * `Astro.cache.set(hint)` turns caching back on, and the route cache reads its
  * options only after the page has rendered, so the opt-out runs after `next()`.
+ * Pages that called noRouteCache() or cacheEntry() for a gated entry get the
+ * same opt-out, for every visitor.
+ *
+ * A request that saves access settings (the Access page, an entry's Access
+ * panel) purges the pages cacheEntry() and cachePage() let in, by their
+ * `redeemid` tag, so they follow the new rules.
  */
 
 import { defineMiddleware } from "astro:middleware";
@@ -24,7 +30,9 @@ import { defineMiddleware } from "astro:middleware";
 import { signInUrl } from "./access.js";
 import { readCart } from "./cart.js";
 import { keysFromUrl, pathAccess, refusal } from "./files.js";
+import { keptOut, purgeRouteCache } from "./route-cache.js";
 import { guardSearch, SEARCH_PATH, SUGGEST_PATH } from "./search-guard.js";
+import { accessWrites } from "./settings.js";
 import { AFTER_LOGOUT_COOKIE, readAfterLogout } from "./routes/shared.js";
 import { shareConfig, siteConfig } from "./site-config.js";
 
@@ -86,7 +94,17 @@ export function keepPrivate(context: { cache?: { set(options: false): void } },
 	}
 }
 
+type Next = Parameters<Parameters<typeof defineMiddleware>[0]>[1];
+type Context = Parameters<Parameters<typeof defineMiddleware>[0]>[0];
+
 export const onRequest = defineMiddleware(async (context, next) => {
+	const writes = accessWrites();
+	const res = await guard(context, next);
+	if (accessWrites() !== writes) await purgeRouteCache(context.cache);
+	return res;
+});
+
+async function guard(context: Context, next: Next): Promise<Response> {
 	const { locals, url } = context;
 	const user = (locals as { user?: { role?: number } | null }).user;
 	const config = await siteConfig(locals);
@@ -125,7 +143,10 @@ export const onRequest = defineMiddleware(async (context, next) => {
 
 	if (!url.pathname.startsWith("/_emdash")) {
 		const own = Boolean(user) || Boolean(await readCart(context.session as never).catch(() => null));
-		return own ? keepPrivate(context, await next()) : next();
+		if (own) return keepPrivate(context, await next());
+		const res = await next();
+		if (keptOut(locals)) context.cache?.set(false);
+		return res;
 	}
 
 	// Site search answers visitors and members only with what they may read.
@@ -149,4 +170,4 @@ export const onRequest = defineMiddleware(async (context, next) => {
 		status: 403,
 		headers: { "content-type": "application/json", "cache-control": "private, no-store" },
 	});
-});
+}

package/src/plugin.ts

@@ -39,7 +39,7 @@ import { AdminError, adminConfigured } from "./admin-api.js";
 import { cancelShopifyErasure, closeRequest, eraseMember, exportMember, exportRequest, requestShopifyErasure } from "./privacy.js";
 import { accessTest, bulkResync, BULK_BATCH, exportBlocks, memberDetail, privacyPage, registerWebhooks, resyncOne, staffLink, staffUnlink, tagEdit } from "./staff.js";
 import { textProblems } from "./text.js";
-import { gatedFindings, templateFindings } from "./template-scan.js";
+import { cacheFindings, gatedFindings, templateFindings } from "./template-scan.js";
 import { setupFacts, setupPage, WEBHOOK } from "./setup.js";
 import { record } from "./log.js";
 import { resend } from "./events.js";
@@ -867,7 +867,23 @@ function templateBlocks(config: RedeemIDConfig): unknown[] {
 	const found = templateFindings();
 	if (!found) return [{ type: "banner", variant: "alert", title: "Templates weren't checked", description: "Add redeemidGuard() to the integrations in astro.config.mjs. It gates pages and keeps members out of EmDash's own APIs, and checks the templates." }];
 	const risky = gatedFindings(found, config);
-	if (!risky.length) return [{ type: "context", text: "Templates: none renders a gated collection's body with EmDash's PortableText. Bodies go through RedeemID's Content." }];
+	const caching = cacheFindings(found, config);
+	const cacheRows = caching.length
+		? [
+				{ type: "banner", variant: "alert", title: "A template caches gated pages itself", description: "These templates call Astro.cache.set() on pages of a gated collection. With the route cache on, one reader's copy then reaches everyone, and pages keep old rules after an Access save. Use cacheEntry(Astro, collection, entry, cacheHint) on entry pages and cachePage(Astro, cacheHint) on lists, from @redeemid/emdash/cache." },
+				{
+					type: "table",
+					page_action_id: "template_cache_findings",
+					columns: [
+						{ key: "file", label: "Template" },
+						{ key: "lines", label: "Line" },
+						{ key: "collections", label: "Gated collection" },
+					],
+					rows: caching.map((f) => ({ file: f.file, lines: (f.cache ?? []).join(", "), collections: f.gated.join(", ") })),
+				},
+			]
+		: [];
+	if (!risky.length) return [{ type: "context", text: "Templates: none renders a gated collection's body with EmDash's PortableText. Bodies go through RedeemID's Content." }, ...cacheRows];
 	const sure = risky.filter((f) => f.gated.length);
 	return [
 		sure.length
@@ -883,6 +899,7 @@ function templateBlocks(config: RedeemIDConfig): unknown[] {
 			],
 			rows: risky.map((f) => ({ file: f.file, lines: f.lines.join(", "), collections: f.gated.join(", ") || "Not found in the file" })),
 		},
+		...cacheRows,
 	];
 }
 

package/src/route-cache.ts

@@ -0,0 +1,134 @@
+/**
+ * Astro's route cache, made safe for gated content.
+ *
+ * The route cache keys pages by URL and serves a stored page without running
+ * any code, middleware included. So a page cached for one reader reaches the
+ * next one whoever they are: a visitor's copy (wall included) reaches a
+ * member, and a page cached while its entry was free keeps showing all of it
+ * after a rule locks it. Use these in page frontmatter instead of calling
+ * `Astro.cache.set()` yourself:
+ *
+ *   const { entry: post, cacheHint } = await getEmDashEntry("posts", slug);
+ *   await cacheEntry(Astro, "posts", post, cacheHint);
+ *
+ *   const { entries, cacheHint } = await getEmDashCollection("posts");
+ *   cachePage(Astro, cacheHint);
+ *
+ * cacheEntry caches the page only when it reads the same for everyone: no
+ * rule covers the entry, no open window is running out, and the body has no
+ * Members only part, single sale, Plan or Preferences block. Otherwise the
+ * page stays out of the route cache, even when a layout sets a hint later:
+ * redeemidGuard() opts it out again after the page renders.
+ *
+ * RedeemID's member-aware components (Content for a locked body, Gate, Plan,
+ * MemberCard, Preferences, YourData) call noRouteCache() themselves as a
+ * safety net, for pages that set hints by hand or sites with route rules.
+ *
+ * Both tag the page `redeemid`. Saving on the Access page or an entry's
+ * Access panel purges that tag, so cached pages follow the new rules.
+ *
+ * The cache still serves its copy to signed-in members (no code runs on a
+ * hit), so keep member-aware chrome on cached pages, such as the header's
+ * Account link, in the browser (window.redeemid) or out of cached pages.
+ */
+
+import { entryRequirement, entryRuleFor, type AstroLike, type Terms } from "./access.js";
+import { ITEM_BLOCK, MEMBERS_BLOCK, PLAN_BLOCK, PREFERENCES_BLOCK } from "./blocks-names.js";
+import { siteConfig } from "./site-config.js";
+
+/** The cache tag RedeemID puts on pages it lets into the route cache. */
+export const CACHE_TAG = "redeemid";
+
+/** Blocks whose output depends on who reads them. */
+export const MEMBER_BLOCKS: readonly string[] = [MEMBERS_BLOCK, ITEM_BLOCK, PLAN_BLOCK, PREFERENCES_BLOCK];
+
+type Hint = { tags?: string[]; maxAge?: number; swr?: number; lastModified?: Date; etag?: string };
+interface RouteCache {
+	enabled?: boolean;
+	set(options: Hint | false): void;
+}
+type CacheAstro = AstroLike & { cache?: RouteCache };
+
+const KEEP_OUT = Symbol.for("redeemid:keep-out-of-route-cache");
+
+/** Did page code ask to keep this request out of the route cache? (Read by redeemidGuard.) */
+export function keptOut(locals: unknown): boolean {
+	return Boolean(locals && typeof locals === "object" && (locals as Record<symbol, unknown>)[KEEP_OUT]);
+}
+
+/**
+ * Keep this page out of the route cache, whatever sets a hint later. Its
+ * Cache-Control stays as it was: a visitor's copy is the same for every
+ * visitor, and redeemidGuard() already makes signed-in pages private.
+ */
+export function noRouteCache(astro: CacheAstro): void {
+	if (astro.locals && typeof astro.locals === "object") (astro.locals as Record<symbol, unknown>)[KEEP_OUT] = true;
+	astro.cache?.set(false);
+}
+
+/** Cache a page that shows no gated body (a list, a page RedeemID doesn't touch), tagged so Access saves purge it. */
+export function cachePage(astro: CacheAstro, hint?: Hint | null): void {
+	if (keptOut(astro.locals) || !astro.cache?.enabled) return;
+	astro.cache.set({ ...(hint ?? {}), tags: [...(hint?.tags ?? []), CACHE_TAG] });
+}
+
+/** Does a body hold a block that reads differently for members? Looks at every field of the entry's data. */
+export function hasMemberBlocks(data: Record<string, unknown> | null | undefined): boolean {
+	for (const v of Object.values(data ?? {})) {
+		if (Array.isArray(v) && v.some((b) => MEMBER_BLOCKS.includes((b as { _type?: string })?._type ?? ""))) return true;
+	}
+	return false;
+}
+
+/**
+ * May this entry's page be stored and served to everyone? Only when it reads
+ * the same for every visitor, now and until the cache could expire.
+ */
+export async function cacheable(
+	astro: AstroLike,
+	collection: string,
+	entry: { id?: string; data?: Record<string, unknown> | null } | null | undefined,
+): Promise<boolean> {
+	if (!entry) return false;
+	const config = await siteConfig(astro.locals);
+	if (!config) return !hasMemberBlocks(entry.data);
+	if (config.unavailable) return false;
+	const terms = entry.data?.terms as Terms | undefined;
+	if ((await entryRequirement(config, collection, terms, entry.id)) !== null) return false;
+	// Free until a date: a stored copy would outlive the window.
+	const own = entryRuleFor(config, collection, entry.id);
+	if (own?.openUntil && Date.now() < Date.parse(own.openUntil)) return false;
+	return !hasMemberBlocks(entry.data);
+}
+
+/**
+ * Cache an entry's page with its hint when it reads the same for everyone;
+ * otherwise keep it out of the route cache. Returns whether it was cached.
+ */
+export async function cacheEntry(
+	astro: CacheAstro,
+	collection: string,
+	entry: { id?: string; data?: Record<string, unknown> | null } | null | undefined,
+	hint?: Hint | null,
+): Promise<boolean> {
+	if (keptOut(astro.locals)) return false;
+	if (!(await cacheable(astro, collection, entry))) {
+		noRouteCache(astro);
+		return false;
+	}
+	if (!astro.cache?.enabled) return false;
+	cachePage(astro, hint);
+	return true;
+}
+
+// ------------------------------------------------------------------ purging
+
+/** Purge RedeemID's cached pages. Never throws: the save it follows already happened. */
+export async function purgeRouteCache(cache: { enabled?: boolean; invalidate?(o: { tags: string[] }): Promise<unknown> } | undefined): Promise<void> {
+	if (!cache?.enabled || !cache.invalidate) return;
+	try {
+		await cache.invalidate({ tags: [CACHE_TAG] });
+	} catch (e) {
+		console.error("[redeemid] couldn't purge the route cache:", (e as Error).message);
+	}
+}

package/src/settings.ts

@@ -159,9 +159,18 @@ export function forgetAccess(): void {
 	held()[HELD] = undefined;
 }
 
+const WRITES = Symbol.for("redeemid:access-writes");
+
+/** How many times this server has saved access settings. redeemidGuard() purges the route cache when a request moves it. */
+export function accessWrites(): number {
+	return (globalThis as unknown as Record<symbol, number | undefined>)[WRITES] ?? 0;
+}
+
 /** Record that the settings changed, so every server reads them again. */
 export async function touchAccess(store: StorageCollection<AccessRecord>): Promise<void> {
 	forgetAccess();
+	const g = globalThis as unknown as Record<symbol, number | undefined>;
+	g[WRITES] = (g[WRITES] ?? 0) + 1;
 	await store.put(STAMP_ID, { kind: "stamp", version: crypto.randomUUID() });
 }