@startup-api/cloudflare 0.1.0 → 0.2.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.
@@ -147,6 +162,8 @@ Configure an ordered list of rules (first match wins) mapping a path pattern to
 
 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).
 
+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:
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startup-api/cloudflare",
-  "version": "0.1.0",
+  "version": "0.2.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,
@@ -259,6 +259,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,8 +295,8 @@ 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) });
       }

package/src/policy/accessPolicy.ts

@@ -30,8 +30,15 @@ function deny(reason: 'unauthenticated' | 'not_entitled', rule: AccessRule): Pol
  * 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':