@becklyn/deployment-protection 0.2.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # `@becklyn/deployment-protection`
 
-Simple, shared deployment gate for Next.js apps on Vercel.
+Simple, shared deployment gate for Next.js apps and static Storybook deploys on Vercel.
 
 Use this instead of (or after disabling) Vercel platform Deployment Protection when you need:
 
@@ -9,7 +9,10 @@ Use this instead of (or after disabling) Vercel platform Deployment Protection w
 - always-on **automation bypass** via `x-vercel-protection-bypass` / `VERCEL_AUTOMATION_BYPASS_SECRET`
 - a kill switch (`DEPLOYMENT_PROTECTION_ENABLED`, on by default)
 
-Protection runs in Next.js **middleware** (Next ≤15) or **proxy** (Next 16+).
+Protection runs in:
+
+- Next.js **middleware** (Next ≤15) or **proxy** (Next 16+)
+- **Vercel Edge Middleware** for static Storybook (`@becklyn/deployment-protection/storybook`)
 
 > **Note:** Vercel Connect is unrelated (third-party API tokens). Platform Vercel Authentication cookies are not visible to your app once platform protection is off — team members use the **Sign in with Vercel** button instead.
 
@@ -21,7 +24,45 @@ npm i @becklyn/deployment-protection
 
 ## Quick setup
 
-### 1. Middleware / proxy
+### Storybook (static on Vercel)
+
+Built Storybook is static (`storybook-static`), so protection is **Vercel Edge Middleware** — not a Storybook addon.
+
+1. Install the package in the project that deploys Storybook.
+2. Add `middleware.ts` at the **Vercel project root** (same level Vercel uses for `vercel.json` / output):
+
+```ts
+import { withStorybookDeploymentProtection } from "@becklyn/deployment-protection/storybook";
+
+export default withStorybookDeploymentProtection();
+
+export const config = {
+    matcher: ["/((?!.*\\.(?:svg|png|jpg|jpeg|gif|webp|ico|css|js|map|txt|xml|woff2?|mjs)$).*)"],
+};
+```
+
+3. Set the same environment variables as for Next.js (below).
+4. Optional `vercel.json` for a Storybook-only project:
+
+```json
+{
+    "buildCommand": "npm run build-storybook",
+    "outputDirectory": "storybook-static",
+    "framework": null
+}
+```
+
+`withStorybookDeploymentProtection` does **not** require the `next` package. The matcher must stay a **string literal** in `middleware.ts` (same static-analysis rule as Next.js).
+
+Framework-agnostic alias (same implementation):
+
+```ts
+import { withEdgeDeploymentProtection } from "@becklyn/deployment-protection/edge";
+
+export default withEdgeDeploymentProtection();
+```
+
+### 1. Next.js middleware / proxy
 
 Next.js requires `config.matcher` to be a **string literal in the local middleware/proxy file**.
 It cannot be imported from a package (Next analyzes the matcher statically at build time).
@@ -70,33 +111,97 @@ export default withDeploymentProtection(async request => {
 | `DEPLOYMENT_PROTECTION_ENABLED`              | no                | `true`                    | Set `false` / `0` / `off` to disable                   |
 | `DEPLOYMENT_PROTECTION_USERNAME`             | for password auth | —                         | Shared username                                        |
 | `DEPLOYMENT_PROTECTION_PASSWORD`             | for password auth | —                         | Shared password                                        |
-| `DEPLOYMENT_PROTECTION_SECRET`               | recommended       | derived from user+pass    | HMAC secret for session cookies                        |
+| `DEPLOYMENT_PROTECTION_SECRET`               | recommended       | derived from user+pass    | HMAC secret for session cookies (+ handoff fallback)   |
+| `DEPLOYMENT_PROTECTION_AUTH_PROXY_URL`       | for proxy SSO     | —                         | Base URL of the central auth-proxy app                 |
+| `DEPLOYMENT_PROTECTION_HANDOFF_SECRET`       | no                | same as `…_SECRET`        | Shared secret between apps and the auth-proxy          |
 | `VERCEL_AUTOMATION_BYPASS_SECRET`            | no                | —                         | Same secret as Vercel Protection Bypass for Automation |
-| `DEPLOYMENT_PROTECTION_VERCEL_CLIENT_ID`     | for Vercel login  | —                         | Or `NEXT_PUBLIC_VERCEL_APP_CLIENT_ID`                  |
-| `DEPLOYMENT_PROTECTION_VERCEL_CLIENT_SECRET` | for Vercel login  | —                         | Or `VERCEL_APP_CLIENT_SECRET`                          |
+| `DEPLOYMENT_PROTECTION_VERCEL_CLIENT_ID`     | direct Vercel SSO | —                         | Or `NEXT_PUBLIC_VERCEL_APP_CLIENT_ID` (legacy)         |
+| `DEPLOYMENT_PROTECTION_VERCEL_CLIENT_SECRET` | direct Vercel SSO | —                         | Or `VERCEL_APP_CLIENT_SECRET` (legacy)                 |
 | `DEPLOYMENT_PROTECTION_FORM_TITLE`           | no                | `Authentication required` | Login heading                                          |
 | `DEPLOYMENT_PROTECTION_FORM_DESCRIPTION`     | no                | …                         | Login description                                      |
 
-At least one of password auth, Vercel OAuth, or a bypass secret must be configured while enabled. If nothing is configured, the gate stays inactive (fail-open) so local dev is not bricked.
+At least one of password auth, Vercel OAuth (proxy or direct), or a bypass secret must be configured while enabled. If nothing is configured, the gate stays inactive (fail-open) so local dev is not bricked.
+
+### 3. Sign in with Vercel via auth-proxy (recommended)
+
+Register **one** OAuth callback URL on a shared [Sign in with Vercel](https://vercel.com/docs/sign-in-with-vercel) app:
+
+```text
+https://<auth-proxy-host>/callback
+```
+
+Deploy the `deployment-protection-auth-proxy` app from this monorepo (or any tiny Next app that wires the handlers below) and set:
+
+**On the auth-proxy**
+
+| Variable                                             | Description                            |
+| ---------------------------------------------------- | -------------------------------------- |
+| `DEPLOYMENT_PROTECTION_VERCEL_CLIENT_ID`             | Vercel OAuth client id                 |
+| `DEPLOYMENT_PROTECTION_VERCEL_CLIENT_SECRET`         | Vercel OAuth client secret             |
+| `DEPLOYMENT_PROTECTION_SECRET` or `…_HANDOFF_SECRET` | Shared HMAC secret with protected apps |
+| `DEPLOYMENT_PROTECTION_ALLOWED_ORIGINS`              | Optional allowlist (see below)         |
+
+**On every protected app**
+
+| Variable                               | Description                            |
+| -------------------------------------- | -------------------------------------- |
+| `DEPLOYMENT_PROTECTION_AUTH_PROXY_URL` | e.g. `https://dp-auth.example.com`     |
+| `DEPLOYMENT_PROTECTION_SECRET`         | Session cookie secret                  |
+| `DEPLOYMENT_PROTECTION_HANDOFF_SECRET` | Same as proxy (defaults to `…_SECRET`) |
+
+No per-project / per-preview callback URLs.
+
+#### Flow
+
+1. App redirects to `{AUTH_PROXY_URL}/start` with a **signed** `return_origin` + `return_path`.
+2. Proxy runs Vercel OAuth against its fixed `/callback`.
+3. Proxy redirects to  
+   `{return_origin}/_becklyn/deployment-protection/vercel/callback?handoff=…&return_to=…`
+4. App verifies the short-lived handoff token (`aud` must match its origin), sets `__becklyn_dp_session`, continues.
+
+#### Allowlist (proxy)
+
+`DEPLOYMENT_PROTECTION_ALLOWED_ORIGINS` is a comma-separated list:
+
+- full origins: `https://app.example.com`
+- host suffixes: `.vercel.app`, `example.com`
+- `localhost` (http(s) localhost / 127.0.0.1)
+
+Empty allowlist → any origin that passes https (or local http) validation. Prefer an allowlist in production.
+
+#### Minimal proxy route handlers
+
+```ts
+// app/start/route.ts
+import { handleAuthProxyStart } from "@becklyn/deployment-protection";
+
+export const GET = (request: Request) => handleAuthProxyStart(request);
+
+// app/callback/route.ts
+import { handleAuthProxyCallback } from "@becklyn/deployment-protection";
+
+export const GET = (request: Request) => handleAuthProxyCallback(request);
+```
+
+### 4. Sign in with Vercel (legacy direct mode)
 
-### 3. Sign in with Vercel (optional)
+Still supported when `DEPLOYMENT_PROTECTION_AUTH_PROXY_URL` is unset:
 
-1. Create a [Sign in with Vercel](https://vercel.com/docs/sign-in-with-vercel) app in the Vercel dashboard.
-2. Generate a client secret.
-3. Add authorization callback URLs for each project host, pointing at:
+1. Create a Sign in with Vercel app.
+2. Add authorization callback URLs for **each** project host:
 
     ```text
     https://<your-host>/_becklyn/deployment-protection/vercel/callback
     http://localhost:3000/_becklyn/deployment-protection/vercel/callback
     ```
 
-    You can attach the path to preview + production domains of each project from the dashboard.
+3. Set client id/secret on the project(s).
 
-4. Set client id/secret env vars on the project(s). Prefer team-level shared env values.
+When both proxy URL and direct client credentials are set, **proxy mode wins** for the authorize step.
 
 Scopes used: `openid email profile`.
 
-### 4. Automation bypass
+### 5. Automation bypass
 
 Matches Vercel’s Protection Bypass for Automation:
 
@@ -116,7 +221,7 @@ When platform Deployment Protection is disabled, **this package** enforces the b
 ## Behaviour
 
 1. Disabled / misconfigured → pass through
-2. Internal Vercel OAuth routes → handled by the package
+2. Internal Vercel OAuth routes → handled by the package (proxy start or direct OAuth / handoff)
 3. Login form `POST` → validate username/password, set signed HttpOnly session cookie
 4. Valid bypass header/query/cookie → allow (optionally set cookies)
 5. Valid session cookie → allow
@@ -136,14 +241,20 @@ Redeploy. Middleware stays installed but is a no-op.
 
 ```ts
 import {
+    handleAuthProxyCallback,
+    handleAuthProxyStart,
     handleDeploymentProtection,
     resolveConfig,
     withDeploymentProtection,
+    withEdgeDeploymentProtection,
 } from "@becklyn/deployment-protection";
+import { withStorybookDeploymentProtection } from "@becklyn/deployment-protection/storybook";
 ```
 
-- `withDeploymentProtection(options?)` / `withDeploymentProtection(next, options?)` — middleware/proxy factory
+- `withDeploymentProtection(options?)` / `withDeploymentProtection(next, options?)` — Next.js middleware/proxy factory
+- `withStorybookDeploymentProtection(options?)` / `withEdgeDeploymentProtection(options?)` — Vercel Edge Middleware for Storybook / static deploys (no Next.js)
 - `handleDeploymentProtection(request, options?)` — framework-agnostic core (`null` = continue)
+- `handleAuthProxyStart` / `handleAuthProxyCallback` — central auth-proxy routes
 
 Recommended matcher (must be pasted as a string literal in your middleware/proxy file — see above):
 
@@ -155,6 +266,8 @@ Recommended matcher (must be pasted as a string literal in your middleware/proxy
 
 - This is a **shared-secret gate**, not per-user product auth.
 - Prefer a dedicated `DEPLOYMENT_PROTECTION_SECRET` in production.
+- Auth-proxy start requests are HMAC-signed; handoff tokens are short-lived and audience-bound.
+- Do not put the raw handoff secret in query strings — only signatures/tokens.
 - Turn off paid Vercel Password Protection / seat-heavy sharing once this is live; keep `VERCEL_AUTOMATION_BYPASS_SECRET` configured for tooling.
 - Middleware is a convenience edge check — do not treat it as the only control for highly sensitive data.
 

package/dist/cjs/auth-proxy.d.ts

@@ -0,0 +1,15 @@
+import type { DeploymentProtectionOptions } from "./types";
+/** Fixed OAuth callback path registered once on the Vercel OAuth app. */
+export declare const AUTH_PROXY_CALLBACK_PATH = "/callback";
+export declare const AUTH_PROXY_START_PATH = "/start";
+/**
+ * Auth-proxy entry: verify the signed start request from a protected app, then
+ * begin Sign in with Vercel against this proxy's fixed callback URL.
+ */
+export declare function handleAuthProxyStart(request: Request, options?: DeploymentProtectionOptions): Promise<Response>;
+/**
+ * Auth-proxy Vercel OAuth callback: exchange the code, mint a short-lived handoff
+ * token, and redirect back to the protected app callback.
+ */
+export declare function handleAuthProxyCallback(request: Request, options?: DeploymentProtectionOptions): Promise<Response>;
+//# sourceMappingURL=auth-proxy.d.ts.map

package/dist/cjs/auth-proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-proxy.d.ts","sourceRoot":"","sources":["../../src/auth-proxy.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,SAAS,CAAC;AAY3D,yEAAyE;AACzE,eAAO,MAAM,wBAAwB,cAAc,CAAC;AACpD,eAAO,MAAM,qBAAqB,WAAW,CAAC;AA0B9C;;;GAGG;AACH,wBAAsB,oBAAoB,CACtC,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,2BAAgC,GAC1C,OAAO,CAAC,QAAQ,CAAC,CAwCnB;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CACzC,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,2BAAgC,GAC1C,OAAO,CAAC,QAAQ,CAAC,CAqEnB"}

package/dist/cjs/auth-proxy.js

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AUTH_PROXY_START_PATH = exports.AUTH_PROXY_CALLBACK_PATH = void 0;
+exports.handleAuthProxyStart = handleAuthProxyStart;
+exports.handleAuthProxyCallback = handleAuthProxyCallback;
+const config_1 = require("./config");
+const constants_1 = require("./constants");
+const crypto_1 = require("./crypto");
+const handoff_1 = require("./handoff");
+const safe_return_to_1 = require("./safe-return-to");
+const vercel_oauth_1 = require("./vercel-oauth");
+/** Fixed OAuth callback path registered once on the Vercel OAuth app. */
+exports.AUTH_PROXY_CALLBACK_PATH = "/callback";
+exports.AUTH_PROXY_START_PATH = "/start";
+function isSecureRequest(request) {
+    return new URL(request.url).protocol === "https:";
+}
+function textResponse(message, status) {
+    return new Response(message, {
+        status,
+        headers: {
+            "Content-Type": "text/plain; charset=utf-8",
+            "Cache-Control": "no-store",
+        },
+    });
+}
+function cookieOptions(secure) {
+    return {
+        httpOnly: true,
+        sameSite: "lax",
+        secure,
+        path: "/",
+        maxAge: 10 * 60,
+    };
+}
+/**
+ * Auth-proxy entry: verify the signed start request from a protected app, then
+ * begin Sign in with Vercel against this proxy's fixed callback URL.
+ */
+async function handleAuthProxyStart(request, options = {}) {
+    const config = (0, config_1.resolveConfig)(options);
+    if (!(0, config_1.hasVercelDirectAuth)(config) || !config.handoffSecret) {
+        return textResponse("Auth proxy is not configured", 500);
+    }
+    const url = new URL(request.url);
+    const returnOrigin = (0, handoff_1.normalizeReturnOrigin)(url.searchParams.get("return_origin"));
+    const returnPath = (0, safe_return_to_1.safeReturnTo)(url.searchParams.get("return_path"));
+    const expRaw = url.searchParams.get("exp");
+    const nonce = url.searchParams.get("nonce");
+    const sig = url.searchParams.get("sig");
+    const exp = expRaw ? Number(expRaw) : NaN;
+    if (!returnOrigin || !nonce || !Number.isFinite(exp)) {
+        return textResponse("Invalid start request", 400);
+    }
+    if (!(0, handoff_1.isReturnOriginAllowed)(returnOrigin, config.allowedReturnOrigins)) {
+        return textResponse("Return origin is not allowed", 403);
+    }
+    const params = {
+        returnOrigin,
+        returnPath,
+        exp,
+        nonce,
+    };
+    if (!(await (0, handoff_1.verifyProxyStartSignature)(config.handoffSecret, params, sig))) {
+        return textResponse("Invalid or expired start signature", 403);
+    }
+    const response = await (0, vercel_oauth_1.buildVercelAuthorizeRedirect)(request, config, returnPath, {
+        callbackPath: exports.AUTH_PROXY_CALLBACK_PATH,
+    });
+    const secure = isSecureRequest(request);
+    (0, vercel_oauth_1.appendSetCookie)(response, constants_1.OAUTH_RETURN_ORIGIN_COOKIE, returnOrigin, cookieOptions(secure));
+    return response;
+}
+/**
+ * Auth-proxy Vercel OAuth callback: exchange the code, mint a short-lived handoff
+ * token, and redirect back to the protected app callback.
+ */
+async function handleAuthProxyCallback(request, options = {}) {
+    const config = (0, config_1.resolveConfig)(options);
+    if (!(0, config_1.hasVercelDirectAuth)(config) || !config.handoffSecret) {
+        return textResponse("Auth proxy is not configured", 500);
+    }
+    const url = new URL(request.url);
+    const code = url.searchParams.get("code");
+    const state = url.searchParams.get("state");
+    const secure = isSecureRequest(request);
+    const returnOrigin = (0, handoff_1.normalizeReturnOrigin)((0, vercel_oauth_1.readCookie)(request, constants_1.OAUTH_RETURN_ORIGIN_COOKIE));
+    const returnPath = (0, safe_return_to_1.safeReturnTo)((0, vercel_oauth_1.readCookie)(request, constants_1.OAUTH_RETURN_COOKIE));
+    const fail = (message, status = 401) => {
+        const response = textResponse(message, status);
+        (0, vercel_oauth_1.clearOAuthCookies)(response, secure);
+        return response;
+    };
+    if (!returnOrigin) {
+        return fail("Missing return origin", 400);
+    }
+    if (!(0, handoff_1.isReturnOriginAllowed)(returnOrigin, config.allowedReturnOrigins)) {
+        return fail("Return origin is not allowed", 403);
+    }
+    if (!code || !(await (0, vercel_oauth_1.assertOAuthState)(request, state))) {
+        return fail("Vercel sign-in failed (invalid state)");
+    }
+    try {
+        const codeVerifier = (0, vercel_oauth_1.readCookie)(request, constants_1.OAUTH_VERIFIER_COOKIE);
+        if (!codeVerifier) {
+            throw new Error("Missing PKCE verifier");
+        }
+        const tokenData = await (0, vercel_oauth_1.exchangeVercelCode)(request, config, code, codeVerifier, {
+            callbackPath: exports.AUTH_PROXY_CALLBACK_PATH,
+        });
+        const storedNonce = (0, vercel_oauth_1.readCookie)(request, constants_1.OAUTH_NONCE_COOKIE);
+        const tokenNonce = (0, vercel_oauth_1.decodeIdTokenNonce)(tokenData.id_token);
+        if (storedNonce && tokenNonce && !(await (0, crypto_1.timingSafeEqualString)(storedNonce, tokenNonce))) {
+            throw new Error("Nonce mismatch");
+        }
+        const user = await (0, vercel_oauth_1.fetchVercelUserInfo)(tokenData.access_token);
+        const subject = user.preferred_username || user.email || user.sub || "vercel-user";
+        const handoff = await (0, handoff_1.createHandoffToken)(config.handoffSecret, returnOrigin, subject);
+        const target = new URL(constants_1.VERCEL_CALLBACK_PATH, `${returnOrigin}/`);
+        target.searchParams.set("handoff", handoff);
+        target.searchParams.set("return_to", returnPath);
+        const response = new Response(null, {
+            status: 302,
+            headers: {
+                Location: target.toString(),
+                "Cache-Control": "no-store",
+            },
+        });
+        (0, vercel_oauth_1.clearOAuthCookies)(response, secure);
+        return response;
+    }
+    catch {
+        return fail("Vercel sign-in failed");
+    }
+}

package/dist/cjs/config.d.ts

@@ -4,6 +4,13 @@ import type { DeploymentProtectionConfig, DeploymentProtectionOptions } from "./
  */
 export declare function resolveConfig(options?: DeploymentProtectionOptions): DeploymentProtectionConfig;
 export declare function hasPasswordAuth(config: DeploymentProtectionConfig): boolean;
+/** Direct Vercel OAuth on the protected app (legacy / single-project setup). */
+export declare function hasVercelDirectAuth(config: DeploymentProtectionConfig): boolean;
+/**
+ * Central auth-proxy mode: apps only need the proxy URL + shared handoff secret.
+ * Vercel client credentials live solely on the proxy.
+ */
+export declare function hasVercelProxyAuth(config: DeploymentProtectionConfig): boolean;
 export declare function hasVercelAuth(config: DeploymentProtectionConfig): boolean;
 /**
  * Protection only runs when enabled and at least one auth method is configured.

package/dist/cjs/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,0BAA0B,EAAE,2BAA2B,EAAU,MAAM,SAAS,CAAC;AA0B/F;;GAEG;AACH,wBAAgB,aAAa,CACzB,OAAO,GAAE,2BAAgC,GAC1C,0BAA0B,CA6C5B;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,0BAA0B,GAAG,OAAO,CAE3E;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,0BAA0B,GAAG,OAAO,CAEzE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,0BAA0B,GAAG,OAAO,CAK9E"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,0BAA0B,EAAE,2BAA2B,EAAU,MAAM,SAAS,CAAC;AA0B/F;;GAEG;AACH,wBAAgB,aAAa,CACzB,OAAO,GAAE,2BAAgC,GAC1C,0BAA0B,CA0D5B;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,0BAA0B,GAAG,OAAO,CAE3E;AAED,gFAAgF;AAChF,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,0BAA0B,GAAG,OAAO,CAE/E;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,0BAA0B,GAAG,OAAO,CAE9E;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,0BAA0B,GAAG,OAAO,CAEzE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,0BAA0B,GAAG,OAAO,CAK9E"}

package/dist/cjs/config.js

@@ -2,8 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveConfig = resolveConfig;
 exports.hasPasswordAuth = hasPasswordAuth;
+exports.hasVercelDirectAuth = hasVercelDirectAuth;
+exports.hasVercelProxyAuth = hasVercelProxyAuth;
 exports.hasVercelAuth = hasVercelAuth;
 exports.isProtectionActive = isProtectionActive;
+const handoff_1 = require("./handoff");
 const FALSEY = new Set(["0", "false", "no", "off"]);
 function read(env, ...keys) {
     for (const key of keys) {
@@ -35,12 +38,17 @@ function resolveConfig(options = {}) {
     // Prefer an explicit secret; otherwise derive a stable key from credentials so
     // projects can stay zero-config beyond username/password.
     const secret = explicitSecret ?? (username && password ? `dp:${username}:${password}` : null);
+    const handoffSecret = read(env, "DEPLOYMENT_PROTECTION_HANDOFF_SECRET") ?? explicitSecret ?? secret;
+    const authProxyUrl = read(env, "DEPLOYMENT_PROTECTION_AUTH_PROXY_URL")?.replace(/\/$/, "") ?? null;
     return {
         enabled: isEnabled(env),
         username,
         password,
         secret,
+        handoffSecret,
         bypassSecret: read(env, "VERCEL_AUTOMATION_BYPASS_SECRET", "DEPLOYMENT_PROTECTION_BYPASS_SECRET"),
+        authProxyUrl,
+        allowedReturnOrigins: (0, handoff_1.parseAllowlist)(read(env, "DEPLOYMENT_PROTECTION_ALLOWED_ORIGINS", "DEPLOYMENT_PROTECTION_AUTH_PROXY_ALLOWED_ORIGINS")),
         vercelClientId: read(env, "DEPLOYMENT_PROTECTION_VERCEL_CLIENT_ID", "NEXT_PUBLIC_VERCEL_APP_CLIENT_ID", "VERCEL_APP_CLIENT_ID"),
         vercelClientSecret: read(env, "DEPLOYMENT_PROTECTION_VERCEL_CLIENT_SECRET", "VERCEL_APP_CLIENT_SECRET"),
         sessionTtlSeconds: options.sessionTtlSeconds ?? 60 * 60 * 24 * 14,
@@ -55,9 +63,20 @@ function resolveConfig(options = {}) {
 function hasPasswordAuth(config) {
     return Boolean(config.username && config.password && config.secret);
 }
-function hasVercelAuth(config) {
+/** Direct Vercel OAuth on the protected app (legacy / single-project setup). */
+function hasVercelDirectAuth(config) {
     return Boolean(config.vercelClientId && config.vercelClientSecret && config.secret);
 }
+/**
+ * Central auth-proxy mode: apps only need the proxy URL + shared handoff secret.
+ * Vercel client credentials live solely on the proxy.
+ */
+function hasVercelProxyAuth(config) {
+    return Boolean(config.authProxyUrl && config.handoffSecret && config.secret);
+}
+function hasVercelAuth(config) {
+    return hasVercelDirectAuth(config) || hasVercelProxyAuth(config);
+}
 /**
  * Protection only runs when enabled and at least one auth method is configured.
  * Misconfigured+enabled is treated as inactive (fail-open) so local/dev isn't bricked.

package/dist/cjs/constants.d.ts

@@ -4,6 +4,7 @@ export declare const OAUTH_STATE_COOKIE = "__becklyn_dp_oauth_state";
 export declare const OAUTH_NONCE_COOKIE = "__becklyn_dp_oauth_nonce";
 export declare const OAUTH_VERIFIER_COOKIE = "__becklyn_dp_oauth_verifier";
 export declare const OAUTH_RETURN_COOKIE = "__becklyn_dp_oauth_return";
+export declare const OAUTH_RETURN_ORIGIN_COOKIE = "__becklyn_dp_oauth_return_origin";
 export declare const INTERNAL_PATH_PREFIX = "/_becklyn/deployment-protection";
 export declare const VERCEL_AUTHORIZE_PATH = "/_becklyn/deployment-protection/vercel";
 export declare const VERCEL_CALLBACK_PATH = "/_becklyn/deployment-protection/vercel/callback";

package/dist/cjs/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,mBAAmB,yBAAyB,CAAC;AAC1D,eAAO,MAAM,kBAAkB,wBAAwB,CAAC;AACxD,eAAO,MAAM,kBAAkB,6BAA6B,CAAC;AAC7D,eAAO,MAAM,kBAAkB,6BAA6B,CAAC;AAC7D,eAAO,MAAM,qBAAqB,gCAAgC,CAAC;AACnE,eAAO,MAAM,mBAAmB,8BAA8B,CAAC;AAE/D,eAAO,MAAM,oBAAoB,oCAAoC,CAAC;AACtE,eAAO,MAAM,qBAAqB,2CAAmC,CAAC;AACtE,eAAO,MAAM,oBAAoB,oDAA4C,CAAC;AAE9E,eAAO,MAAM,aAAa,+BAA+B,CAAC;AAC1D,eAAO,MAAM,wBAAwB,+BAA+B,CAAC;AAErE,eAAO,MAAM,2BAA2B,QAAoB,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,mBAAmB,yBAAyB,CAAC;AAC1D,eAAO,MAAM,kBAAkB,wBAAwB,CAAC;AACxD,eAAO,MAAM,kBAAkB,6BAA6B,CAAC;AAC7D,eAAO,MAAM,kBAAkB,6BAA6B,CAAC;AAC7D,eAAO,MAAM,qBAAqB,gCAAgC,CAAC;AACnE,eAAO,MAAM,mBAAmB,8BAA8B,CAAC;AAC/D,eAAO,MAAM,0BAA0B,qCAAqC,CAAC;AAE7E,eAAO,MAAM,oBAAoB,oCAAoC,CAAC;AACtE,eAAO,MAAM,qBAAqB,2CAAmC,CAAC;AACtE,eAAO,MAAM,oBAAoB,oDAA4C,CAAC;AAE9E,eAAO,MAAM,aAAa,+BAA+B,CAAC;AAC1D,eAAO,MAAM,wBAAwB,+BAA+B,CAAC;AAErE,eAAO,MAAM,2BAA2B,QAAoB,CAAC"}

package/dist/cjs/constants.js

@@ -1,12 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_SESSION_TTL_SECONDS = exports.SET_BYPASS_COOKIE_HEADER = exports.BYPASS_HEADER = exports.VERCEL_CALLBACK_PATH = exports.VERCEL_AUTHORIZE_PATH = exports.INTERNAL_PATH_PREFIX = exports.OAUTH_RETURN_COOKIE = exports.OAUTH_VERIFIER_COOKIE = exports.OAUTH_NONCE_COOKIE = exports.OAUTH_STATE_COOKIE = exports.BYPASS_COOKIE_NAME = exports.SESSION_COOKIE_NAME = void 0;
+exports.DEFAULT_SESSION_TTL_SECONDS = exports.SET_BYPASS_COOKIE_HEADER = exports.BYPASS_HEADER = exports.VERCEL_CALLBACK_PATH = exports.VERCEL_AUTHORIZE_PATH = exports.INTERNAL_PATH_PREFIX = exports.OAUTH_RETURN_ORIGIN_COOKIE = exports.OAUTH_RETURN_COOKIE = exports.OAUTH_VERIFIER_COOKIE = exports.OAUTH_NONCE_COOKIE = exports.OAUTH_STATE_COOKIE = exports.BYPASS_COOKIE_NAME = exports.SESSION_COOKIE_NAME = void 0;
 exports.SESSION_COOKIE_NAME = "__becklyn_dp_session";
 exports.BYPASS_COOKIE_NAME = "__becklyn_dp_bypass";
 exports.OAUTH_STATE_COOKIE = "__becklyn_dp_oauth_state";
 exports.OAUTH_NONCE_COOKIE = "__becklyn_dp_oauth_nonce";
 exports.OAUTH_VERIFIER_COOKIE = "__becklyn_dp_oauth_verifier";
 exports.OAUTH_RETURN_COOKIE = "__becklyn_dp_oauth_return";
+exports.OAUTH_RETURN_ORIGIN_COOKIE = "__becklyn_dp_oauth_return_origin";
 exports.INTERNAL_PATH_PREFIX = "/_becklyn/deployment-protection";
 exports.VERCEL_AUTHORIZE_PATH = `${exports.INTERNAL_PATH_PREFIX}/vercel`;
 exports.VERCEL_CALLBACK_PATH = `${exports.INTERNAL_PATH_PREFIX}/vercel/callback`;

package/dist/cjs/edge.d.ts

@@ -0,0 +1,14 @@
+import type { DeploymentProtectionOptions } from "./types";
+/**
+ * Tell Vercel Edge Middleware to continue to the upstream / static asset.
+ * Same signal as `NextResponse.next()` without depending on the Next.js runtime.
+ */
+export declare function middlewarePassThrough(): Response;
+/**
+ * Framework-agnostic Vercel Edge Middleware factory (no Next.js runtime).
+ *
+ * Intended for static deployments such as Storybook `storybook-static` on Vercel.
+ * Reuses the same env vars and auth behaviour as {@link withDeploymentProtection}.
+ */
+export declare function withEdgeDeploymentProtection(options?: DeploymentProtectionOptions): (request: Request) => Promise<Response>;
+//# sourceMappingURL=edge.d.ts.map

package/dist/cjs/edge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge.d.ts","sourceRoot":"","sources":["../../src/edge.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,SAAS,CAAC;AAE3D;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,QAAQ,CAOhD;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,GAAE,2BAAgC,IACzB,SAAS,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC,CAShG"}

package/dist/cjs/edge.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.middlewarePassThrough = middlewarePassThrough;
+exports.withEdgeDeploymentProtection = withEdgeDeploymentProtection;
+const handler_1 = require("./handler");
+/**
+ * Tell Vercel Edge Middleware to continue to the upstream / static asset.
+ * Same signal as `NextResponse.next()` without depending on the Next.js runtime.
+ */
+function middlewarePassThrough() {
+    return new Response(null, {
+        status: 200,
+        headers: {
+            "x-middleware-next": "1",
+        },
+    });
+}
+/**
+ * Framework-agnostic Vercel Edge Middleware factory (no Next.js runtime).
+ *
+ * Intended for static deployments such as Storybook `storybook-static` on Vercel.
+ * Reuses the same env vars and auth behaviour as {@link withDeploymentProtection}.
+ */
+function withEdgeDeploymentProtection(options = {}) {
+    return async function deploymentProtectionEdgeMiddleware(request) {
+        const protectionResponse = await (0, handler_1.handleDeploymentProtection)(request, options);
+        if (protectionResponse) {
+            return protectionResponse;
+        }
+        return middlewarePassThrough();
+    };
+}

package/dist/cjs/handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../src/handler.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAA8B,2BAA2B,EAAE,MAAM,SAAS,CAAC;AA6OvF;;GAEG;AACH,wBAAsB,0BAA0B,CAC5C,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,2BAAgC,GAC1C,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAqD1B"}
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../src/handler.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAA8B,2BAA2B,EAAE,MAAM,SAAS,CAAC;AA4RvF;;GAEG;AACH,wBAAsB,0BAA0B,CAC5C,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,2BAAgC,GAC1C,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAqD1B"}

package/dist/cjs/handler.js

@@ -5,6 +5,7 @@ const bypass_1 = require("./bypass");
 const config_1 = require("./config");
 const constants_1 = require("./constants");
 const crypto_1 = require("./crypto");
+const handoff_1 = require("./handoff");
 const login_page_1 = require("./login-page");
 const password_1 = require("./password");
 const safe_return_to_1 = require("./safe-return-to");
@@ -117,6 +118,19 @@ async function handleVercelAuthorize(request, config) {
         return new Response("Sign in with Vercel is not configured", { status: 500 });
     }
     const returnTo = (0, safe_return_to_1.safeReturnTo)(new URL(request.url).searchParams.get("return_to"));
+    // Prefer central auth-proxy so apps never register per-host OAuth callbacks.
+    if ((0, config_1.hasVercelProxyAuth)(config) && config.authProxyUrl && config.handoffSecret) {
+        const startUrl = await (0, handoff_1.buildProxyStartUrl)({
+            authProxyUrl: config.authProxyUrl,
+            secret: config.handoffSecret,
+            returnOrigin: new URL(request.url).origin,
+            returnPath: returnTo,
+        });
+        return redirect(request, startUrl);
+    }
+    if (!(0, config_1.hasVercelDirectAuth)(config)) {
+        return new Response("Sign in with Vercel is not configured", { status: 500 });
+    }
     return (0, vercel_oauth_1.buildVercelAuthorizeRedirect)(request, config, returnTo);
 }
 async function handleVercelCallback(request, config) {
@@ -127,9 +141,32 @@ async function handleVercelCallback(request, config) {
         return new Response("Sign in with Vercel is not configured", { status: 500 });
     }
     const url = new URL(request.url);
+    const handoff = url.searchParams.get("handoff");
+    const secure = isSecureRequest(request);
+    // Auth-proxy handoff: short-lived signed token, no Vercel client secret on the app.
+    if (handoff) {
+        if (!config.handoffSecret) {
+            return new Response("Sign in with Vercel is not configured", { status: 500 });
+        }
+        const returnTo = (0, safe_return_to_1.safeReturnTo)(url.searchParams.get("return_to"));
+        const payload = await (0, handoff_1.verifyHandoffToken)(config.handoffSecret, handoff, url.origin);
+        if (!payload) {
+            return htmlResponse((0, login_page_1.renderLoginPage)(config, {
+                error: "Vercel sign-in failed (invalid handoff).",
+                returnTo,
+                showPassword: (0, config_1.hasPasswordAuth)(config),
+                showVercel: true,
+            }));
+        }
+        const response = redirect(request, returnTo);
+        return attachSession(response, config, "vercel", payload.subject, secure);
+    }
+    // Legacy direct OAuth callback on the protected app.
+    if (!(0, config_1.hasVercelDirectAuth)(config)) {
+        return new Response("Sign in with Vercel is not configured", { status: 500 });
+    }
     const code = url.searchParams.get("code");
     const state = url.searchParams.get("state");
-    const secure = isSecureRequest(request);
     const returnTo = (0, safe_return_to_1.safeReturnTo)((0, vercel_oauth_1.readCookie)(request, constants_1.OAUTH_RETURN_COOKIE));
     if (!code || !(await (0, vercel_oauth_1.assertOAuthState)(request, state))) {
         const response = htmlResponse((0, login_page_1.renderLoginPage)(config, {

package/dist/cjs/handoff.d.ts

@@ -0,0 +1,46 @@
+export declare const HANDOFF_TTL_SECONDS = 60;
+export declare const PROXY_START_TTL_SECONDS: number;
+export interface ProxyStartParams {
+    returnOrigin: string;
+    returnPath: string;
+    exp: number;
+    nonce: string;
+}
+export interface HandoffPayload {
+    exp: number;
+    aud: string;
+    subject: string;
+    method: "vercel";
+}
+/**
+ * Canonical payload for HMAC over the proxy start request.
+ * Field order is fixed so app and proxy produce the same signature.
+ */
+export declare function canonicalProxyStartPayload(params: ProxyStartParams): string;
+export declare function signProxyStart(secret: string, params: ProxyStartParams): Promise<string>;
+export declare function verifyProxyStartSignature(secret: string, params: ProxyStartParams, signature: string | null | undefined): Promise<boolean>;
+export declare function buildProxyStartUrl(options: {
+    authProxyUrl: string;
+    secret: string;
+    returnOrigin: string;
+    returnPath: string;
+    ttlSeconds?: number;
+}): Promise<string>;
+export declare function createHandoffToken(secret: string, audienceOrigin: string, subject: string, ttlSeconds?: number): Promise<string>;
+export declare function verifyHandoffToken(secret: string, token: string | null | undefined, expectedAudienceOrigin: string): Promise<HandoffPayload | null>;
+/**
+ * Validate a post-login return origin for the auth proxy.
+ * Only https (and http://localhost / 127.0.0.1) are accepted.
+ */
+export declare function normalizeReturnOrigin(value: string | null | undefined): string | null;
+/**
+ * Optional allowlist. Entries may be:
+ * - full origins (`https://app.example.com`)
+ * - hostname suffixes (`.vercel.app`, `example.com`)
+ * - `localhost` (any localhost / 127.0.0.1 http(s) origin)
+ *
+ * Empty allowlist → any origin that passes {@link normalizeReturnOrigin}.
+ */
+export declare function isReturnOriginAllowed(origin: string, allowlist: string[]): boolean;
+export declare function parseAllowlist(value: string | null | undefined): string[];
+//# sourceMappingURL=handoff.d.ts.map

package/dist/cjs/handoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff.d.ts","sourceRoot":"","sources":["../../src/handoff.ts"],"names":[],"mappings":"AASA,eAAO,MAAM,mBAAmB,KAAK,CAAC;AACtC,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAE9C,MAAM,WAAW,gBAAgB;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,QAAQ,CAAC;CACpB;AAeD;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAE3E;AAED,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAE9F;AAED,wBAAsB,yBAAyB,CAC3C,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,gBAAgB,EACxB,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACrC,OAAO,CAAC,OAAO,CAAC,CAWlB;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE;IAC9C,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAAC,MAAM,CAAC,CAgBlB;AAWD,wBAAsB,kBAAkB,CACpC,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,MAAM,EACf,UAAU,SAAsB,GACjC,OAAO,CAAC,MAAM,CAAC,CAUjB;AAED,wBAAsB,kBAAkB,CACpC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAChC,sBAAsB,EAAE,MAAM,GAC/B,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAwChC;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CA4BrF;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAgDlF;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,EAAE,CASzE"}