@startup-api/cloudflare 0.2.0 → 0.3.0

package/README.md

@@ -160,7 +160,34 @@ Configure an ordered list of rules (first match wins) mapping a path pattern to
 - **`authenticated`** — any logged-in user.
 - **`entitlement`** — a provider condition: Patreon `active_patron`, a specific `benefit` (perk) ID, or a `tier` ID.
 
-Patterns are exact (`/special`), prefix (`/app/*`), or `/` (homepage only). Each rule's `on_unauthorized` is `login` (redirect to sign in), `forbidden` (403), or `upgrade` (redirect to `upgrade_url`, e.g. a Patreon join page). When no policy is configured at all, every path is treated as `public` (backward compatible).
+Patterns are exact (`/special`), prefix (`/app/*`), or `/` (homepage only). Each rule's `on_unauthorized` is `login` (redirect to sign in), `forbidden` (403), `upgrade` (redirect to `upgrade_url`, e.g. a Patreon join page), or `gate` (serve an explainer page **in place**, with no redirect — see below). When no policy is configured at all, every path is treated as `public` (backward compatible).
+
+#### Serving a gate page in place (`on_unauthorized: 'gate'`)
+
+Instead of redirecting, a denied request can serve an explainer page **at the requested URL** (no redirect, status `200` by default). The page shown depends on login state, so anonymous and logged-in-but-unentitled visitors can see different copy:
+
+- **`anonymous`** (required) — shown to visitors who are **not** logged in (e.g. a "become a patron + log in" page).
+- **`unentitled`** (optional) — shown to logged-in visitors who fail the requirement (e.g. a "pledge/upgrade" page). Falls back to `anonymous` when omitted.
+- **`status`** (optional) — HTTP status for the served page; defaults to `200` to preserve typical explainer-page UX (set `403` if you prefer).
+
+Each variant is a `PageSource` whose body comes from **either** the `ASSETS` binding **or** a path proxied from `ORIGIN_URL` — exactly one of:
+
+- **`{ asset: '/early-access' }`** — a local file from `ASSETS` (resolved like other assets, `/early-access` → `early-access.html`).
+- **`{ origin: '/early-access' }`** — a path proxied from `ORIGIN_URL`. The path must be reachable directly on the origin (the raw site, not behind this worker).
+
+The gate config is set per rule via `gate`, or on the policy default via `default_gate`. The served gate page is produced inside the deny path, so it is not re-subjected to the access policy and no power-strip is injected — the page is expected to carry its own login CTA. Because nothing redirects, there is no loop risk.
+
+```ts
+const accessPolicy = {
+  default: { mode: 'entitlement', provider: 'patreon', condition: { type: 'benefit', benefit_id: '<BENEFIT_ID>' } },
+  default_on_unauthorized: 'gate',
+  default_gate: {
+    anonymous: { origin: '/early-access' }, // or { asset: '/early-access' }
+    unentitled: { origin: '/pledge-needed' }, // or { asset: '/pledge-needed' }
+    // status: 403, // optional; defaults to 200
+  },
+};
+```
 
 Admin users (those listed in `ADMIN_IDS`) bypass every `authenticated`/`entitlement` requirement and can reach any gated path. Their identity is still resolved and the usual identity/entitlement headers are forwarded to the origin — only the gate itself is skipped. (`bypass` paths remain a raw pass-through for everyone, with no identity resolution.)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startup-api/cloudflare",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "Apache-2.0",
   "publishConfig": {
     "access": "public"

package/src/createStartupAPI.ts

@@ -24,7 +24,7 @@ import { handleSSR } from './handlers/ssr';
 import type { StartupAPIEnv } from './StartupAPIEnv';
 import { StartupAPIConfigSchema } from './schemas/config';
 import type { StartupAPIConfig, ProviderOptions, ResolvedFreshness } from './schemas/config';
-import type { AccessPolicyConfig } from './schemas/policy';
+import type { AccessPolicyConfig, PageSource } from './schemas/policy';
 import { AccessPolicy, evaluateAccess } from './policy/accessPolicy';
 import type { PolicyDecision } from './policy/accessPolicy';
 import { loadEntitlements, entitlementHeaders } from './entitlements/service';
@@ -67,11 +67,46 @@ function resolveAccessPolicy(configPolicy: AccessPolicyConfig | undefined): Acce
   return configPolicy ?? { default: { mode: 'public' } };
 }
 
-/** Build a deny response (login redirect / 403 / upgrade redirect) for an unmet access requirement. */
+/**
+ * Serve a gate page body in place (no redirect), sourced from either the ASSETS binding (a local file)
+ * or a path proxied from ORIGIN_URL. The configured status is re-stamped onto the response so e.g. a
+ * 200 asset can be served as a 403 gate.
+ */
+async function serveGatePage(
+  source: PageSource,
+  status: number,
+  request: Request,
+  env: StartupAPIEnv,
+  reqUrl: URL,
+): Promise<Response> {
+  let res: Response;
+  if ('asset' in source) {
+    // Serve a local file from ASSETS, mirroring the existing user-asset path.
+    const assetReq = new Request(new URL(source.asset, reqUrl).toString(), { method: 'GET' });
+    assetReq.headers.set('x-skip-worker', 'true');
+    res = await env.ASSETS.fetch(assetReq);
+  } else {
+    // Proxy a path from ORIGIN_URL (swap host, set Host), like the main origin proxy.
+    const target = new URL(source.origin, new URL(env.ORIGIN_URL));
+    const proxied = new Request(target.toString(), request);
+    proxied.headers.set('Host', target.host);
+    res = await originFetch(proxied);
+  }
+  // Re-stamp the status (e.g. a 200 asset can be served as the configured gate status).
+  return new Response(res.body, { status, headers: res.headers });
+}
+
+/** Build a deny response (login redirect / 403 / upgrade redirect / in-place gate page) for an unmet access requirement. */
 function denyResponse(
   decision: Extract<PolicyDecision, { allow: false }>,
-  ctx: { usersPath: string; returnUrl: string; activeProviders: string[] },
-): Response {
+  ctx: { usersPath: string; returnUrl: string; activeProviders: string[]; authenticated: boolean; request: Request; env: StartupAPIEnv; url: URL },
+): Response | Promise<Response> {
+  if (decision.action === 'gate' && decision.gate) {
+    // Serve an explainer page in place: anonymous variant for logged-out visitors, unentitled variant
+    // (falling back to anonymous) for logged-in visitors who fail the requirement. No redirect.
+    const source = ctx.authenticated ? (decision.gate.unentitled ?? decision.gate.anonymous) : decision.gate.anonymous;
+    return serveGatePage(source, decision.gate.status ?? 200, ctx.request, ctx.env, ctx.url);
+  }
   if (decision.action === 'forbidden') {
     return new Response('Forbidden', { status: 403 });
   }
@@ -298,7 +333,15 @@ export function createStartupAPI(config: StartupAPIConfig = {}) {
       // Enforce the requirement. Admins bypass the gate (identity/headers above still apply).
       const decision = evaluateAccess(rule, { authenticated, entitlements, isAdmin: userIsAdmin });
       if (!decision.allow) {
-        return denyResponse(decision, { usersPath, returnUrl, activeProviders: getActiveProviders(env) });
+        return denyResponse(decision, {
+          usersPath,
+          returnUrl,
+          activeProviders: getActiveProviders(env),
+          authenticated,
+          request,
+          env,
+          url,
+        });
       }
 
       const response = await originFetch(newRequest);

package/src/policy/accessPolicy.ts

@@ -1,5 +1,5 @@
 import { AccessPolicySchema } from '../schemas/policy';
-import type { AccessPolicyConfig, AccessPolicyResolved, AccessRule, Requirement, UnauthorizedAction } from '../schemas/policy';
+import type { AccessPolicyConfig, AccessPolicyResolved, AccessRule, Gate, Requirement, UnauthorizedAction } from '../schemas/policy';
 import type { Entitlements } from '../entitlements/types';
 import { providerEntitlementCheckers, providerSupportsEntitlements } from './entitlementCheckers';
 
@@ -20,10 +20,10 @@ export function matchPattern(pattern: string, path: string): boolean {
 
 export type PolicyDecision =
   | { allow: true }
-  | { allow: false; reason: 'unauthenticated' | 'not_entitled'; action: UnauthorizedAction; upgrade_url?: string };
+  | { allow: false; reason: 'unauthenticated' | 'not_entitled'; action: UnauthorizedAction; upgrade_url?: string; gate?: Gate };
 
 function deny(reason: 'unauthenticated' | 'not_entitled', rule: AccessRule): PolicyDecision {
-  return { allow: false, reason, action: rule.on_unauthorized, upgrade_url: rule.upgrade_url };
+  return { allow: false, reason, action: rule.on_unauthorized, upgrade_url: rule.upgrade_url, gate: rule.gate };
 }
 
 /**
@@ -101,6 +101,7 @@ export class AccessPolicy {
       requirement: cfg.default ?? { mode: 'authenticated' },
       on_unauthorized: cfg.default_on_unauthorized,
       upgrade_url: cfg.default_upgrade_url,
+      gate: cfg.default_gate,
     };
   }
 }

package/src/schemas/policy.ts

@@ -34,7 +34,27 @@ export const RequirementSchema = z.discriminatedUnion('mode', [
   }),
 ]);
 
-export const UnauthorizedActionSchema = z.enum(['login', 'forbidden', 'upgrade']);
+/** Where a gate page body comes from. Exactly one of asset/origin. */
+export const PageSourceSchema = z.union([
+  // Served from the ASSETS binding; path is resolved like other assets (`/foo` -> foo.html).
+  z.object({ asset: z.string() }),
+  // Proxied from this path on ORIGIN_URL.
+  z.object({ origin: z.string() }),
+]);
+export type PageSource = z.infer<typeof PageSourceSchema>;
+
+/** Page(s) served in place when a requirement is not met (on_unauthorized: 'gate'). */
+export const GateSchema = z.object({
+  /** Shown to visitors who are NOT logged in. Required. */
+  anonymous: PageSourceSchema,
+  /** Shown to logged-in visitors who fail the requirement. Falls back to `anonymous` if omitted. */
+  unentitled: PageSourceSchema.optional(),
+  /** HTTP status for the served page. Default 200 (preserves typical explainer-page UX). */
+  status: z.number().int().optional(),
+});
+export type Gate = z.infer<typeof GateSchema>;
+
+export const UnauthorizedActionSchema = z.enum(['login', 'forbidden', 'upgrade', 'gate']);
 
 export const RuleSchema = z.object({
   /** Path pattern: exact (`/special`), prefix (`/special/*`), or `/` for the homepage only. */
@@ -44,6 +64,8 @@ export const RuleSchema = z.object({
   on_unauthorized: UnauthorizedActionSchema.default('login'),
   /** Redirect target for the 'upgrade' action (e.g. a Patreon join page). */
   upgrade_url: z.string().optional(),
+  /** Page(s) served in place for the 'gate' action. */
+  gate: GateSchema.optional(),
 });
 
 export const AccessPolicySchema = z.object({
@@ -52,6 +74,8 @@ export const AccessPolicySchema = z.object({
   default: RequirementSchema.optional(),
   default_on_unauthorized: UnauthorizedActionSchema.default('login'),
   default_upgrade_url: z.string().optional(),
+  /** Page(s) served in place for the 'gate' action on paths that match no rule. */
+  default_gate: GateSchema.optional(),
 });
 
 export type EntitlementCondition = z.infer<typeof EntitlementConditionSchema>;