@wtfalch/auth 0.31.0 → 0.32.0

package/README.md

@@ -433,6 +433,25 @@ A phone that is already signed in can also approve a new device from a QR
 code, the issuer's OAuth device grant opted into per namespace binding with
 `qrSignIn: true`, through `startQrSignIn` and `pollQrSignIn`.
 
+## Preview routes
+
+For apps on live/idle releases. The balancer sends a request with the `bg_preview=1` cookie to the idle slot, after asking the live slot whether the person may see it.
+
+```ts
+import { createPreviewRoutes } from '@wtfalch/auth';
+
+export const preview = createPreviewRoutes({
+  readSession: async (request) => (await auth.read(request, { refresh: false })).user,
+  mayPreview: (session) => canPreview(session), // `releases:preview` in the app's production authz
+  appOrigin: 'https://app.example.test', // required: the app's own origin, the one `appUrl` names
+});
+// GET    /api/foundry/preview-check -> preview.check  (200, 401 no session, 403 otherwise)
+// POST   /api/foundry/preview       -> preview.set    (204 and the cookie, same-origin only)
+// DELETE /api/foundry/preview       -> preview.clear  (204, same-origin only, no permission needed)
+```
+
+Answers carry no body and `cache-control: no-store`. A reader or permission check that throws answers 403 and logs one fixed line with the error name only. `appOrigin` is required and is never read from the request. `PREVIEW_COOKIE`, `PREVIEW_CHECK_PATH` and `PREVIEW_PATH` are exported too.
+
 ## Documentation
 
 `docs/adopting.md` in [wtfalch/auth](https://github.com/wtfalch/auth) covers a

package/dist/auth.js

@@ -5,7 +5,7 @@ import { clearQrTransaction, clearSession, clearTransaction, cookieFrom, openQrT
 import { namespaceSessions } from './namespace-session.js';
 import { AuthError, ORG_CLAIM, Oidc, isOAuthRefusal, rejected, scopeFor, } from './oidc.js';
 import { pollDeviceToken, requestDeviceAuthorization } from './qr.js';
-import { safeLoginHint, safeNextPath } from './redirect.js';
+import { isSameOrigin, safeLoginHint, safeNextPath } from './redirect.js';
 import { expiryOf, issuedAtOf, recheckSeconds, timeoutSignal } from './util.js';
 export function createAuth(input) {
     // Resolved on first use so `next build`, which imports every route module, needs none of the values set.
@@ -1210,12 +1210,6 @@ function isNavigation(request) {
         return false;
     return !request.headers.has('rsc') && !request.headers.has('next-action');
 }
-function isSameOrigin(request, origin) {
-    const from = request.headers.get('origin');
-    if (from)
-        return from === origin;
-    return request.headers.get('sec-fetch-site') === 'same-origin';
-}
 // Never says whether the address exists, so neither can the app.
 async function quietly(act) {
     try {

package/dist/cookies.d.ts

@@ -78,6 +78,7 @@ export declare function linkCookieName(options: ResolvedOptions): string;
 export declare function sealLink(options: ResolvedOptions, payload: Omit<LinkPayload, keyof JWTPayload>): Promise<SetCookie>;
 export declare function openLink(options: ResolvedOptions, value: string | undefined): Promise<LinkPayload | null>;
 export declare function clearLink(options: ResolvedOptions): SetCookie;
+export declare function setCookie(name: string, value: string, maxAge: number, secure: boolean): SetCookie;
 export declare function cookieFrom(header: string | null, name: string): string | undefined;
 /** The Cookie header with these cookies replaced or removed, for a proxy to forward. */
 export declare function withCookies(header: string | null, updates: SetCookie[]): string;

package/dist/cookies.js

@@ -186,7 +186,7 @@ async function open(options, kind, value) {
         return null;
     }
 }
-function setCookie(name, value, maxAge, secure) {
+export function setCookie(name, value, maxAge, secure) {
     const parts = [`${name}=${value}`, 'Path=/', 'HttpOnly', 'SameSite=Lax'];
     if (maxAge > 0) {
         parts.push(`Max-Age=${maxAge}`);

package/dist/index.d.ts

@@ -7,3 +7,4 @@ export type { PersonIdentity, PersonTokenConfig, PersonTokenOutcome, PersonToken
 export { BrokerError, type PeoplePage, type Person } from './broker.js';
 export { AuthError, type AuthErrorReason, ORG_CLAIM } from './oidc.js';
 export { safeLoginHint, safeNextPath } from './redirect.js';
+export { PREVIEW_CHECK_PATH, PREVIEW_COOKIE, PREVIEW_PATH, type PreviewRoutes, type PreviewRoutesOptions, createPreviewRoutes, } from './preview.js';

package/dist/index.js

@@ -3,3 +3,4 @@ export { DesktopHandoffError, } from './desktop.js';
 export { BrokerError } from './broker.js';
 export { AuthError, ORG_CLAIM } from './oidc.js';
 export { safeLoginHint, safeNextPath } from './redirect.js';
+export { PREVIEW_CHECK_PATH, PREVIEW_COOKIE, PREVIEW_PATH, createPreviewRoutes, } from './preview.js';

package/dist/preview.d.ts

@@ -0,0 +1,24 @@
+/** The cookie that selects the idle slot at the balancer. */
+export declare const PREVIEW_COOKIE = "bg_preview";
+/** Where the balancer's forwardAuth asks whether the request may see the idle slot. */
+export declare const PREVIEW_CHECK_PATH = "/api/foundry/preview-check";
+/** Where the app sets (POST) and clears (DELETE) the preview cookie. */
+export declare const PREVIEW_PATH = "/api/foundry/preview";
+export interface PreviewRoutesOptions<S> {
+    /** The app's own session reader (for example `auth.read`). Null means signed out. */
+    readSession: (request: Request) => Promise<S | null>;
+    /** Whether this session holds `releases:preview` in the app's production authz. */
+    mayPreview: (session: S) => Promise<boolean>;
+    /** The app's own origin, the one `appUrl` names. Required: the trusted origin never comes from the request. */
+    appOrigin: string;
+}
+export interface PreviewRoutes {
+    /** GET `PREVIEW_CHECK_PATH`: 200 allowed, 401 no session, 403 otherwise. */
+    check: (request: Request) => Promise<Response>;
+    /** POST `PREVIEW_PATH`: same-origin, same check, then sets the cookie (204). */
+    set: (request: Request) => Promise<Response>;
+    /** DELETE `PREVIEW_PATH`: same-origin, clears the cookie (204). */
+    clear: (request: Request) => Promise<Response>;
+}
+/** Route handlers for the idle preview: the check the balancer calls, and the cookie the person sets and clears. */
+export declare function createPreviewRoutes<S>(options: PreviewRoutesOptions<S>): PreviewRoutes;

package/dist/preview.js

@@ -0,0 +1,60 @@
+import { setCookie } from './cookies.js';
+import { isSameOrigin } from './redirect.js';
+/** The cookie that selects the idle slot at the balancer. */
+export const PREVIEW_COOKIE = 'bg_preview';
+/** Where the balancer's forwardAuth asks whether the request may see the idle slot. */
+export const PREVIEW_CHECK_PATH = '/api/foundry/preview-check';
+/** Where the app sets (POST) and clears (DELETE) the preview cookie. */
+export const PREVIEW_PATH = '/api/foundry/preview';
+/** Eight hours. */
+const PREVIEW_MAX_AGE = 28_800;
+const NO_STORE = { 'cache-control': 'no-store' };
+function reply(status, extra = {}) {
+    return new Response(null, { status, headers: { ...NO_STORE, ...extra } });
+}
+/** Route handlers for the idle preview: the check the balancer calls, and the cookie the person sets and clears. */
+export function createPreviewRoutes(options) {
+    // 200 when allowed; otherwise the refusing status. A thrown reader or
+    // permission check is a refusal, logged by error name only so no session
+    // data or message reaches the log.
+    const decide = async (request) => {
+        try {
+            const session = await options.readSession(request);
+            if (session === null)
+                return 401;
+            return (await options.mayPreview(session)) ? 200 : 403;
+        }
+        catch (error) {
+            console.error(`@wtfalch/auth: preview check failed (${error instanceof Error ? error.name : 'Error'})`);
+            return 403;
+        }
+    };
+    // Normalised once so a malformed value throws at setup, and case or a
+    // trailing slash cannot change `secure` or the same-origin compare.
+    const appOrigin = new URL(options.appOrigin).origin;
+    const secure = appOrigin.startsWith('https:');
+    const sameOrigin = (request) => {
+        if (isSameOrigin(request, appOrigin))
+            return true;
+        console.error('@wtfalch/auth: preview request refused (cross-origin)');
+        return false;
+    };
+    return {
+        check: async (request) => reply(await decide(request)),
+        set: async (request) => {
+            if (!sameOrigin(request))
+                return reply(403);
+            const status = await decide(request);
+            if (status !== 200)
+                return reply(status);
+            const cookie = setCookie(PREVIEW_COOKIE, '1', PREVIEW_MAX_AGE, secure);
+            return reply(204, { 'set-cookie': cookie.header });
+        },
+        clear: async (request) => {
+            if (!sameOrigin(request))
+                return reply(403);
+            const cookie = setCookie(PREVIEW_COOKIE, '', 0, secure);
+            return reply(204, { 'set-cookie': cookie.header });
+        },
+    };
+}

package/dist/redirect.d.ts

@@ -7,3 +7,4 @@ export declare function safeNextPath(next: string | null | undefined, fallback:
  * because the person can still type their address at the issuer.
  */
 export declare function safeLoginHint(raw: string | null | undefined): string | undefined;
+export declare function isSameOrigin(request: Request, origin: string): boolean;

package/dist/redirect.js

@@ -33,3 +33,9 @@ export function safeLoginHint(raw) {
         return undefined;
     return /^[^\s@\p{Cc}]+@[^\s@\p{Cc}]+\.[^\s@\p{Cc}]+$/u.test(raw) ? raw : undefined;
 }
+export function isSameOrigin(request, origin) {
+    const from = request.headers.get('origin');
+    if (from)
+        return from === origin;
+    return request.headers.get('sec-fetch-site') === 'same-origin';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/auth",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "Sign in against a self-hosted ZITADEL issuer: a server session for a Next.js app, and a browser client with silent single sign-on across subdomains.",
   "repository": {
     "type": "git",