@bffless/skills 1.7.0 → 1.8.1

package/.claude-plugin/marketplace.json

@@ -5,7 +5,7 @@
   },
   "metadata": {
     "description": "BFFless platform skills",
-    "version": "1.7.0"
+    "version": "1.8.1"
   },
   "plugins": [
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bffless/skills",
-  "version": "1.7.0",
+  "version": "1.8.1",
   "description": "BFFless platform skills — usable with Claude Code or any agent via the `skills` CLI",
   "keywords": [
     "skills",

package/plugins/bffless/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "bffless",
-  "version": "1.7.0",
+  "version": "1.8.1",
   "description": "BFFless platform skills for Claude Code — deployments, pipelines, proxy rules, chat, traffic splitting, and more",
   "author": {
     "name": "BFFless"

package/plugins/bffless/skills/authentication/SKILL.md

@@ -52,11 +52,23 @@ All auth endpoints are available at `/_bffless/auth/*` on any domain served by B
 
 | Endpoint                    | Method | Purpose                                                  |
 | --------------------------- | ------ | -------------------------------------------------------- |
-| `/_bffless/auth/session`    | GET    | Check current session (returns user info or 401)         |
+| `/_bffless/auth/session`    | GET    | Check current session — see response shape below         |
 | `/_bffless/auth/refresh`    | POST   | Refresh an expired access token using the refresh cookie |
 | `/_bffless/auth/callback`   | GET    | Exchange a domain relay token for auth cookies           |
 | `/_bffless/auth/logout`     | POST   | Clear auth cookies                                       |
 
+### Session Endpoint Response Shape
+
+`GET /_bffless/auth/session` has **three** possible outcomes — make sure your client distinguishes all three:
+
+| Outcome | Status | Body | Meaning |
+| ------- | ------ | ---- | ------- |
+| Logged in | `200` | `{ "authenticated": true, "user": { id, email, role } }` | Use the user object |
+| **Guest** | **`200`** | **`{ "authenticated": false, "user": null }`** | **Not logged in — do NOT trust `res.ok` alone** |
+| Expired | `401` | `"try refresh token"` | Call `/_bffless/auth/refresh`, then retry session |
+
+**Common bug**: writing `if (res.ok) return res.json()` and treating guests as authenticated. The body's `authenticated` field is the source of truth, not the HTTP status.
+
 ### Session Check Priority
 
 The `/_bffless/auth/session` endpoint checks auth in this order:
@@ -73,36 +85,42 @@ If the access token is expired, it returns `401` with `"try refresh token"` to s
 Use a shared promise pattern to avoid duplicate session checks across components:
 
 ```typescript
-async function checkSession() {
+type Session =
+  | { authenticated: true; user: { id: string; email?: string; role?: string } }
+  | { authenticated: false };
+
+async function checkSession(): Promise<Session> {
   // Reuse shared session promise so multiple components don't duplicate requests
   if (!(window as any).__bfflessSession) {
-    (window as any).__bfflessSession = (async () => {
-      const res = await fetch('/_bffless/auth/session', { credentials: 'include' });
-      if (res.ok) return res.json();
+    (window as any).__bfflessSession = (async (): Promise<Session> => {
+      const get = () => fetch('/_bffless/auth/session', { credentials: 'include' });
 
+      let res = await get();
       if (res.status === 401) {
-        // Token expired — try refreshing
+        // Token expired — try refreshing, then retry the session check
         const refreshRes = await fetch('/_bffless/auth/refresh', {
           method: 'POST',
           credentials: 'include',
         });
-        if (refreshRes.ok) {
-          // Retry session check with new token
-          const retryRes = await fetch('/_bffless/auth/session', { credentials: 'include' });
-          if (retryRes.ok) return retryRes.json();
-        }
+        if (refreshRes.ok) res = await get();
       }
-      return null;
-    })().catch(() => null);
+
+      if (!res.ok) return { authenticated: false };
+
+      // IMPORTANT: a 200 can still be a guest — the body decides.
+      const body = await res.json();
+      if (body?.authenticated === false || body?.user == null) {
+        return { authenticated: false };
+      }
+      return { authenticated: true, user: body.user ?? body };
+    })().catch(() => ({ authenticated: false }) as Session);
   }
 
   return (window as any).__bfflessSession;
 }
-
-// Returns: { authenticated: true, user: { id, email, role } } or null
 ```
 
-The flow is: session check → if 401, refresh token → retry session check. This handles the common case where the access token has expired but the refresh token is still valid.
+The flow is: session check → if 401, refresh and retry → inspect `body.authenticated`. Do NOT treat any 200 as authenticated; the guest response is also a 200 (see the response shape table above).
 
 ### Redirecting to Login
 
@@ -110,7 +128,11 @@ When unauthenticated, redirect the user to the admin login with relay params. Us
 
 ```typescript
 function getLoginUrl(adminLoginUrl: string, redirectPath: string): string {
-  const targetDomain = window.location.hostname;
+  // Use `host`, NOT `hostname` — host includes the port (e.g. `localhost:5173`).
+  // Using `hostname` strips the port, and the backend builds a callback URL
+  // like `https://localhost/_bffless/auth/callback?...` (no port, wrong scheme)
+  // which is unreachable in local dev.
+  const targetDomain = window.location.host;
   const params = new URLSearchParams({
     customDomainRelay: 'true',
     targetDomain,
@@ -131,10 +153,36 @@ if (!session) {
 
 ### Logout
 
+Logout is symmetric to login: the admin domain owns the SuperTokens session, so you have to bounce through it to actually revoke. Calling `/_bffless/auth/logout` on its own is **not enough** on workspace subdomains — see the dedicated troubleshooting entry below.
+
 ```typescript
-await fetch('/_bffless/auth/logout', { method: 'POST', credentials: 'include' });
+async function logout(adminLogoutUrl: string) {
+  // 1. Clear the bffless_access / bffless_refresh cookies that live on this
+  //    domain. No-op on workspace subdomains (those cookies are never set
+  //    there), but required for custom domains.
+  try {
+    await fetch('/_bffless/auth/logout', {
+      method: 'POST',
+      credentials: 'include',
+    });
+  } catch {
+    // ignore — the admin bounce below is the source of truth
+  }
+
+  // 2. Bounce through the admin logout page so SuperTokens revokes the
+  //    session and clears `sAccessToken` on the parent domain. The admin
+  //    page validates `redirect` (same base-domain only) and sends the
+  //    user back.
+  const redirect = window.location.origin + window.location.pathname;
+  window.location.href = `${adminLogoutUrl}?redirect=${encodeURIComponent(redirect)}`;
+}
+
+// Example:
+// logout('https://admin.console.bffless.app/logout');
 ```
 
+Mirrors the login flow — same admin URL pattern, just `/logout` instead of `/login`. If you derive both URLs from a single env var, do it explicitly rather than munging the login URL with regex, so the intent is obvious to the next reader.
+
 ### Updating UI Based on Auth State (Header example)
 
 ```typescript
@@ -151,6 +199,87 @@ window.__bfflessSession.then((data) => {
 });
 ```
 
+## Local Development
+
+There is no auth backend running on `localhost`, so `/_bffless/auth/*` 404s out of the box. There are two patterns for working around this:
+
+### 1. Proxy `/_bffless` to a deployed workspace (real auth)
+
+Best when you want to exercise the real cookie/relay flow. Configure your dev server to proxy `/_bffless` (and usually `/api`) to a real BFFless deployment:
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  server: {
+    proxy: {
+      '/api': { target: 'https://yourworkspace.bffless.app', changeOrigin: true },
+      '/_bffless': { target: 'https://yourworkspace.bffless.app', changeOrigin: true },
+    },
+  },
+});
+```
+
+Caveats:
+- Login redirects you to the admin domain. The `targetDomain` you send must be a registered domain in that workspace — `localhost:5173` will get rejected with "Domain not registered" unless an admin adds it (or you point at a workspace that does). Most teams add their dev host to a sandbox workspace's domain mappings for this purpose.
+- The session endpoint will return the **guest** shape (`200 { authenticated: false, user: null }`) until you complete the login + callback round trip, which is why the body-inspection pattern above is required.
+
+### 2. Mock `/_bffless/auth/*` with MSW (no backend)
+
+Best when you want to iterate on auth-gated UI without leaving localhost. [MSW](https://mswjs.io) intercepts at the service-worker layer so the production `fetch` calls stay untouched:
+
+```ts
+// src/mocks/handlers.ts
+import { http, HttpResponse, passthrough } from 'msw';
+
+const STORAGE_KEY = 'bffless:mockAuth';
+
+function readMock() {
+  try { return JSON.parse(localStorage.getItem(STORAGE_KEY) ?? '{}'); }
+  catch { return {}; }
+}
+
+export const handlers = [
+  http.get('/_bffless/auth/session', () => {
+    const m = readMock();
+    if (!m.enabled) return passthrough();
+    if (!m.authenticated) {
+      return HttpResponse.json({ authenticated: false, user: null });
+    }
+    return HttpResponse.json({ authenticated: true, user: m.user });
+  }),
+  http.post('/_bffless/auth/refresh', () => {
+    const m = readMock();
+    if (!m.enabled) return passthrough();
+    return new HttpResponse(null, { status: m.authenticated ? 200 : 401 });
+  }),
+  http.post('/_bffless/auth/logout', () => {
+    const m = readMock();
+    if (!m.enabled) return passthrough();
+    localStorage.setItem(STORAGE_KEY, JSON.stringify({ ...m, authenticated: false }));
+    return new HttpResponse(null, { status: 204 });
+  }),
+];
+```
+
+Then boot the worker only in dev, before render:
+
+```ts
+// src/main.tsx
+async function enableMocks() {
+  if (!import.meta.env.DEV) return;
+  const { setupWorker } = await import('msw/browser');
+  const { handlers } = await import('./mocks/handlers');
+  await setupWorker(...handlers).start({ onUnhandledRequest: 'bypass' });
+}
+enableMocks().then(() => { /* createRoot(...).render(...) */ });
+```
+
+Add a small dev-only panel (rendered when `import.meta.env.DEV`) that writes `{ enabled, authenticated, user }` to localStorage and dispatches a `CustomEvent` so your session hook can refetch. With this setup you can toggle authed/guest and swap user attributes live without restarting the dev server.
+
+Caveats:
+- Returning `passthrough()` when `enabled === false` lets you fall back to a proxied real backend (pattern #1) on demand.
+- MSW requires `public/mockServiceWorker.js`; generate it once with `npx msw init public/ --save`.
+
 ## Auth Flow Diagram
 
 ```
@@ -202,3 +331,13 @@ Custom Domain Flow:
 
 - If the workspace has a promoted domain (e.g., `console.bffless.app`), use `admin.console.bffless.app`, NOT `admin.console.workspace.bffless.app`
 - The workspace subdomain format still works but the promoted domain is cleaner
+
+**Logout returns 200 "Logged out successfully" but the next session check still returns `authenticated: true`?**
+
+This is the most-reported logout footgun. It means you called `/_bffless/auth/logout` alone:
+
+- `/_bffless/auth/logout` only clears the **custom-domain JWT cookies** (`bffless_access`, `bffless_refresh`).
+- The session endpoint falls back to the **SuperTokens session** (`sAccessToken`) when no `bffless_access` cookie is present. That cookie lives on the parent domain (`.bffless.app` / `.yourdomain.com`) and was set by the admin login — it is not cleared by `/_bffless/auth/logout`.
+- On workspace subdomains the `bffless_access` cookie was never set in the first place, so `/_bffless/auth/logout` is effectively a no-op and the SuperTokens fallback re-authenticates the user immediately.
+
+Fix: after the `/_bffless/auth/logout` call, navigate to `admin.<workspace>/logout?redirect=<current-page>`. The admin page calls SuperTokens `signOut()`, which revokes the session and clears the shared cookie, then redirects back. See the [Logout](#logout) section for the full pattern.

package/plugins/bffless/skills/upload-artifact/SKILL.md

@@ -102,11 +102,13 @@ You can upload multiple artifacts in the same workflow:
 | `branch` | no | auto | Branch name |
 | `is-public` | no | `'true'` | Public visibility |
 | `alias` | no | -- | Deployment alias (e.g., `production`) |
-| `base-path` | no | `/<path>` | Path prefix in zip |
+| `base-path` | no | `/<path>` | URL prefix the alias serves under. See [Base path and URL shape](#base-path-and-url-shape). |
 | `committed-at` | no | auto | ISO 8601 commit timestamp |
 | `description` | no | -- | Human-readable description |
-| `proxy-rule-set-name` | no | -- | Proxy rule set name |
-| `proxy-rule-set-id` | no | -- | Proxy rule set ID |
+| `proxy-rule-set-name` | no | -- | Single proxy rule set name (legacy — prefer `proxy-rule-set-names`) |
+| `proxy-rule-set-id` | no | -- | Single proxy rule set ID (legacy — prefer `proxy-rule-set-ids`) |
+| `proxy-rule-set-names` | no | -- | Comma-separated proxy rule set names. Appended idempotently — re-deploying with the same names is a no-op. See [Attaching multiple proxy rule sets](#attaching-multiple-proxy-rule-sets). |
+| `proxy-rule-set-ids` | no | -- | Comma-separated proxy rule set IDs. Same append-and-dedupe semantics as `proxy-rule-set-names`. |
 | `tags` | no | -- | Comma-separated tags |
 | `summary` | no | `'true'` | Write GitHub Step Summary |
 | `summary-title` | no | `'Deployment Summary'` | Summary heading |
@@ -147,7 +149,60 @@ The action automatically detects:
 - **Commit SHA**: PR head SHA or push SHA
 - **Branch**: PR head ref or push ref
 - **Committed At**: via `git log` (requires `fetch-depth: 0`)
-- **Base Path**: derived from `path` input as `/<path>`
+- **Base Path**: derived from `path` input as `/<path>` — chosen so files appear at the auto-alias root. See [Base path and URL shape](#base-path-and-url-shape) for what this means and when to override.
+
+## Base path and URL shape
+
+`base-path` controls the URL prefix the deployment's alias serves files under. It does **not** rewrite the zip — the action always zips the contents of `path` with the source folder name preserved (e.g. `path: coverage` produces a zip containing `coverage/index.html`). At serve time, the alias's `basePath` is prepended to the incoming request URL before the lookup against stored asset keys.
+
+Combined with the default `base-path: /<path>`, this produces a useful sleight of hand: the prefix on the URL cancels the folder name on the stored path, so files appear at the **auto-alias root**.
+
+Example: `path: coverage`, default `base-path`
+
+| Request URL | `basePath` prepended | Resolves to stored | Result |
+|---|---|---|---|
+| `/index.html` | `coverage/index.html` | `coverage/index.html` | ✅ served |
+| `/coverage/index.html` | `coverage/coverage/index.html` | — | ❌ 404 |
+
+If you'd rather the source folder be **visible** in the URL (e.g. `/coverage/index.html`), set `base-path: /` so the alias's prefix is empty:
+
+| Request URL | `basePath` prepended | Resolves to stored | Result |
+|---|---|---|---|
+| `/coverage/index.html` | `coverage/index.html` | `coverage/index.html` | ✅ served |
+| `/index.html` | `index.html` | — | ❌ 404 |
+
+Rule of thumb:
+
+- **Want files at auto-alias root** (`<auto-alias>/file.png`) → leave `base-path` unset (default).
+- **Want folder visible in URL** (`<auto-alias>/srcfolder/file.png`) → set `base-path: /`.
+- **Want a different sub-path** → set `base-path: /custom-prefix`. The serving lookup will prepend `custom-prefix/` to incoming requests, so this only works if the zip contents are under a folder of the same name (i.e. `path: custom-prefix`).
+
+### Pitfalls
+
+- **Do not use `base-path: ./`** — the backend normalization only strips leading/trailing slashes, so `./` becomes the literal segment `.` and gets prepended to every lookup, breaking all requests. Use `/` instead.
+- Empty / whitespace values are also unsafe; pass exactly `/` to mean "no prefix."
+
+## Attaching multiple proxy rule sets
+
+Use `proxy-rule-set-names` (or `proxy-rule-set-ids`) when the deployment's auto-preview alias needs to chain more than one proxy rule set — for example a Stripe webhook rule set followed by an AI proxy rule set:
+
+```yaml
+- uses: bffless/upload-artifact@v1
+  with:
+    path: dist
+    api-url: ${{ vars.ASSET_HOST_URL }}
+    api-key: ${{ secrets.ASSET_HOST_KEY }}
+    proxy-rule-set-names: stripe-webhook,ai-proxy
+```
+
+Semantics:
+
+- **Append + idempotent.** Each name/id is appended to whatever the alias already has. Re-running the workflow with the same list is a no-op — no duplicate join rows, no rule reordering.
+- **Order preserved on first attach.** The list order is the priority order in the rule merge — earlier entries win when two rule sets match the same request.
+- **Names resolve per-project.** Unknown names fail the deploy with a `400`; existing IDs that don't belong to the project are silently ignored at the rule-merge layer.
+- **Singular still works.** `proxy-rule-set-name` / `proxy-rule-set-id` remain supported as a back-compat shim. If both singular and plural are provided, the plural list wins and the singular value is ignored.
+
+If you need full replacement (drop all existing rule sets and set exactly this list), do not use the action — use the `update_alias` API with the `proxyRuleSetIds` array instead. The action's deploy path is intentionally append-only so that rule sets added through other channels (admin UI, scripts) are never silently dropped by a workflow run.
 
 ## PR Comments
 
@@ -183,9 +238,15 @@ permissions:
   pull-requests: write # Required for comments
 ```
 
+### Files 404 at the auto-alias root
+
+If `https://<auto-alias>/<file>` returns 404 but `https://<auto-alias>/<srcfolder>/<file>` works (or vice versa), `base-path` is the wrong shape. See [Base path and URL shape](#base-path-and-url-shape).
+
+Common cause: setting `base-path: ./` instead of `base-path: /`. The backend doesn't normalize `./`, so it gets prepended literally and breaks every lookup.
+
 ### Custom base path
 
-If your app expects to be served from a subdirectory:
+If your app expects to be served from a subdirectory (and the zip contents live under that directory):
 
 ```yaml
 - uses: bffless/upload-artifact@v1
@@ -193,3 +254,5 @@ If your app expects to be served from a subdirectory:
     path: build
     base-path: /docs/build # Served at /docs/build/*
 ```
+
+See [Base path and URL shape](#base-path-and-url-shape) for the full mental model.