@startup-api/cloudflare 0.1.0 → 0.3.0

package/README.md

@@ -132,6 +132,21 @@ const api = createStartupAPI({
 3. **Proxying:** All other requests are proxied to the configured `ORIGIN_URL`
 4. **Injection:** For `text/html` responses, the worker injects a `<script>` tag and a `<power-strip>` custom element before serving the content to the user
 
+### Customizing the power strip
+
+By default the worker injects its own `<power-strip>` pinned to the top-right corner of the page. If that overlaps your own menu or you simply want it somewhere else, **place a `<power-strip>` element in your own HTML**. When the worker sees one, it injects only `power-strip.js` (which defines the custom element) and leaves your element exactly where you put it — so you control placement and styling:
+
+```html
+<nav>
+  <!-- ...your links... -->
+  <power-strip></power-strip>
+</nav>
+```
+
+- **`providers` is optional.** If you omit it, the worker fills in the active providers for you (e.g. `providers="google,twitch,patreon"`). Set it yourself to override which login buttons appear.
+- **Prefer an explicit closing tag.** `<power-strip></power-strip>` and `<power-strip/>` are both detected, but per the HTML spec `<power-strip/>` is *not* truly self-closing — the browser treats it as an open tag and nests the following content inside it. Use a closing tag (or place the element last in its container) to avoid surprises.
+- **Script-only opt-out.** Use `<power-strip hidden>` to load `power-strip.js` (and its JS API) without rendering a visible strip.
+
 ## Access policy & provider entitlements
 
 StartupAPI can gate access to paths and forward the visitor's login/entitlement status to your origin so it can render gated UI. This is **provider-agnostic infrastructure**; only Patreon currently implements perk-level (benefit/tier) checks — Google and Twitch participate at the login levels only.
@@ -145,7 +160,36 @@ 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.)
 
 The policy is passed to the factory as `accessPolicy` (see below). Example:
 

package/package.json

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

package/public/users/power-strip.js

@@ -252,7 +252,14 @@ class PowerStrip extends HTMLElement {
           display: block;
           font-family: system-ui, -apple-system, sans-serif;
         }
-        
+
+        /* Honor the native [hidden] attribute so authors can load the script
+           without rendering a visible strip (<power-strip hidden>). The :host
+           rule above would otherwise override the UA [hidden] { display: none }. */
+        :host([hidden]) {
+          display: none !important;
+        }
+
         @keyframes fadeIn {
           from { opacity: 0; }
           to { opacity: 1; }

package/src/PowerStrip.ts

@@ -2,18 +2,42 @@ export async function injectPowerStrip(response: Response, usersPath: string, pr
   const contentType = response.headers.get('Content-Type');
 
   if (contentType && contentType.includes('text/html')) {
-    // Inject a script tag and a custom element into the proxied HTML pages.
-    // The script is loaded from the USERS_PATH, which is intercepted by this worker.
+    const providersAttr = providers.join(',');
+
+    // Track whether the page author placed their own <power-strip> element.
+    // If they did, we respect their placement/styling and only load the script.
+    let hasUserPowerStrip = false;
+
     return new HTMLRewriter()
+      .on('power-strip', {
+        element(element) {
+          hasUserPowerStrip = true;
+
+          // Fill in the active providers for the author so their element works
+          // out of the box, unless they explicitly chose their own list.
+          if (!element.hasAttribute('providers')) {
+            element.setAttribute('providers', providersAttr);
+          }
+        },
+      })
       .on('body', {
         element(element) {
-          element.prepend(
-            `<script src="${usersPath}power-strip.js" async></script>` +
-              `<power-strip providers="${providers.join(',')}" style="position: absolute; top: 0; right: 0; z-index: 9999; padding: 0.1rem; border-radius: 0 0 0 0.3rem;">` +
-              '<svg viewBox="0 0 24 24" style="width: 1rem; height: 1rem;"><path d="M7 2v11h3v9l7-12h-4l4-8z"/></svg>' +
-              '</power-strip>',
-            { html: true },
-          );
+          // The script is always needed to define the <power-strip> custom element.
+          // It is loaded from the USERS_PATH, which is intercepted by this worker.
+          element.prepend(`<script src="${usersPath}power-strip.js" async></script>`, { html: true });
+
+          // Defer the component decision until the end of <body>, by which point
+          // the streaming parser has seen any author-supplied <power-strip>.
+          element.onEndTag((end) => {
+            if (!hasUserPowerStrip) {
+              end.before(
+                `<power-strip providers="${providersAttr}" style="position: absolute; top: 0; right: 0; z-index: 9999; padding: 0.1rem; border-radius: 0 0 0 0.3rem;">` +
+                  '<svg viewBox="0 0 24 24" style="width: 1rem; height: 1rem;"><path d="M7 2v11h3v9l7-12h-4l4-8z"/></svg>' +
+                  '</power-strip>',
+                { html: true },
+              );
+            }
+          });
         },
       })
       .transform(response);

package/src/createStartupAPI.ts

@@ -7,7 +7,7 @@ import { CredentialDO } from './storage/CredentialDO';
 import { CookieManager } from './CookieManager';
 import { initPlans } from './billing/plansConfig';
 import { Plan } from './billing/Plan';
-import { getActiveProviders, parseCookies, getUserFromSession } from './handlers/utils';
+import { getActiveProviders, parseCookies, getUserFromSession, isAdmin } from './handlers/utils';
 import { handleAdmin } from './handlers/admin';
 import {
   handleMe,
@@ -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 });
   }
@@ -259,6 +294,7 @@ export function createStartupAPI(config: StartupAPIConfig = {}) {
 
       const user = await getUserFromSession(request, env, cookieManager);
       const authenticated = !!user;
+      const userIsAdmin = user ? isAdmin(user, env) : false;
       let entitlements: Entitlements | null = null;
       let loginProvider: string | undefined;
 
@@ -294,10 +330,18 @@ export function createStartupAPI(config: StartupAPIConfig = {}) {
         newRequest.headers.set(key, value);
       }
 
-      // Enforce the requirement.
-      const decision = evaluateAccess(rule, { authenticated, entitlements });
+      // 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,18 +20,25 @@ 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 };
 }
 
 /**
  * Decide whether a request satisfies a resolved rule, given the auth state and resolved entitlements.
  * `bypass`/`public` always allow; `authenticated` needs a logged-in user; `entitlement` dispatches the
  * condition through the provider checker registry.
+ *
+ * Admin users (`ctx.isAdmin`) bypass every requirement: identity has already been resolved and headers
+ * forwarded by the time we get here, but the gate itself is skipped so admins can reach any gated path.
  */
-export function evaluateAccess(rule: AccessRule, ctx: { authenticated: boolean; entitlements: Entitlements | null }): PolicyDecision {
+export function evaluateAccess(
+  rule: AccessRule,
+  ctx: { authenticated: boolean; entitlements: Entitlements | null; isAdmin?: boolean },
+): PolicyDecision {
+  if (ctx.isAdmin) return { allow: true };
   const req = rule.requirement;
   switch (req.mode) {
     case 'bypass':
@@ -94,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>;