@wtfalch/auth 0.31.0 → 0.33.0

package/dist/preview.js

@@ -0,0 +1,56 @@
+import { clearCookie, setCookie } from './cookies.js';
+import { isSameOrigin } from './redirect.js';
+import { NO_STORE } from './util.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;
+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) {
+    // 'allowed', or 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 { user } = await options.auth.read(request, { refresh: false });
+            if (user === null)
+                return 401;
+            return (await options.mayPreview(user)) ? 'allowed' : 403;
+        }
+        catch (error) {
+            console.error(`@wtfalch/auth: preview check failed (${error instanceof Error ? error.name : 'Error'})`);
+            return 403;
+        }
+    };
+    // Read per request: the auth instance resolves its options once, on first
+    // use, so nothing is read while this module is being imported.
+    const sameOrigin = (request) => isSameOrigin(request, options.auth.appOrigin);
+    return {
+        check: async (request) => {
+            const decision = await decide(request);
+            return reply(decision === 'allowed' ? 200 : decision);
+        },
+        set: async (request) => {
+            if (!sameOrigin(request))
+                return reply(403);
+            const decision = await decide(request);
+            if (decision !== 'allowed')
+                return reply(decision);
+            const cookie = setCookie(PREVIEW_COOKIE, '1', PREVIEW_MAX_AGE, options.auth.cookiesSecure);
+            return reply(204, { 'set-cookie': cookie.header });
+        },
+        clear: async (request) => {
+            if (!sameOrigin(request))
+                return reply(403);
+            const cookie = clearCookie(PREVIEW_COOKIE, options.auth.cookiesSecure);
+            return reply(204, { 'set-cookie': cookie.header });
+        },
+    };
+}

package/dist/redirect.d.ts

@@ -7,3 +7,12 @@ 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;
+/**
+ * Whether a state-changing request came from `origin` (the app's own, from
+ * `appUrl`, never from the request). A browser's `Origin` header must equal it
+ * exactly; with no `Origin`, `Sec-Fetch-Site: same-origin` is accepted. Both
+ * headers are set by the browser and cannot be forged by a page, but a non-browser
+ * client can send anything, so this is a CSRF defence, not authentication. A
+ * request with neither header is refused. Refuses silently: the caller answers.
+ */
+export declare function isSameOrigin(request: Request, origin: string): boolean;

package/dist/redirect.js

@@ -33,3 +33,17 @@ export function safeLoginHint(raw) {
         return undefined;
     return /^[^\s@\p{Cc}]+@[^\s@\p{Cc}]+\.[^\s@\p{Cc}]+$/u.test(raw) ? raw : undefined;
 }
+/**
+ * Whether a state-changing request came from `origin` (the app's own, from
+ * `appUrl`, never from the request). A browser's `Origin` header must equal it
+ * exactly; with no `Origin`, `Sec-Fetch-Site: same-origin` is accepted. Both
+ * headers are set by the browser and cannot be forged by a page, but a non-browser
+ * client can send anything, so this is a CSRF defence, not authentication. A
+ * request with neither header is refused. Refuses silently: the caller answers.
+ */
+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/dist/util.d.ts

@@ -1,6 +1,10 @@
 /** Helpers shared by the server and browser entry points. No Node-only imports: the browser bundle uses this file too. */
 /** ZITADEL's resource-owner (organisation) claim, on a JWT and on an introspection response alike. */
 export declare const ORG_CLAIM = "urn:zitadel:iam:user:resourceowner:id";
+/** Headers for a response no cache may keep. */
+export declare const NO_STORE: {
+    'Cache-Control': string;
+};
 /** How long an SDK request to the broker or issuer may take before it is abandoned. */
 export declare const FETCH_TIMEOUT_MS = 15000;
 /**

package/dist/util.js

@@ -1,6 +1,8 @@
 /** Helpers shared by the server and browser entry points. No Node-only imports: the browser bundle uses this file too. */
 /** ZITADEL's resource-owner (organisation) claim, on a JWT and on an introspection response alike. */
 export const ORG_CLAIM = 'urn:zitadel:iam:user:resourceowner:id';
+/** Headers for a response no cache may keep. */
+export const NO_STORE = { 'Cache-Control': 'no-store' };
 /** How long an SDK request to the broker or issuer may take before it is abandoned. */
 export const FETCH_TIMEOUT_MS = 15_000;
 /**

package/dist/workspaces.d.ts

@@ -0,0 +1,79 @@
+import type { User } from './auth.js';
+/**
+ * Client for the broker's customer-workspace routes (ADR 0004). The app keeps
+ * the person's session and tells the broker who is acting; the key never
+ * leaves this module except in the `Authorization` header.
+ */
+export interface WorkspacesEnv {
+    WORKSPACES_URL?: string;
+    WORKSPACES_API_KEY?: string;
+    AUTH_ORGANIZATION_ID?: string;
+    [name: string]: string | undefined;
+}
+export interface Workspace {
+    id: string;
+    name: string;
+    slug: string;
+}
+export interface WorkspaceMembership {
+    id: string;
+    name: string;
+    role: string;
+}
+export interface WorkspaceMember {
+    sub: string;
+    email: string;
+    name: string | null;
+    role: string;
+}
+export interface WorkspaceInvitation {
+    id: string;
+    email: string;
+    role: string;
+    createdAt: string;
+    expiresAt: string;
+}
+export type WorkspacesIdentity = Pick<User, 'id' | 'email' | 'emailVerified'>;
+export declare const WORKSPACES_TIMEOUT_MS = 10000;
+export declare class WorkspacesError extends Error {
+    readonly status: number;
+    /** The broker's `error` code, or `unavailable` when it did not answer in the expected shape. */
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+export interface Workspaces {
+    create(input: {
+        name: string;
+        owner: WorkspacesIdentity;
+    }): Promise<Workspace>;
+    listFor(user: Pick<User, 'id'>): Promise<WorkspaceMembership[]>;
+    invite(workspaceId: string, input: {
+        email: string;
+        role: string;
+        actor: Pick<User, 'id'>;
+    }): Promise<{
+        id: string;
+    }>;
+    accept(token: string, user: WorkspacesIdentity): Promise<{
+        workspaceId: string;
+        role: string;
+    }>;
+    setRole(workspaceId: string, memberSub: string, input: {
+        role: string;
+        actor: Pick<User, 'id'>;
+    }): Promise<void>;
+    remove(workspaceId: string, memberSub: string, actor: Pick<User, 'id'>): Promise<void>;
+    /** The person's role in the workspace, or null when they are not a member. */
+    access(workspaceId: string, user: Pick<User, 'id'>): Promise<string | null>;
+    /** Who is in the workspace. Any member may ask. */
+    members(workspaceId: string, actor: Pick<User, 'id'>): Promise<WorkspaceMember[]>;
+    /** Invitations not yet accepted or revoked. Owner only. */
+    invitations(workspaceId: string, actor: Pick<User, 'id'>): Promise<WorkspaceInvitation[]>;
+    /** Owner only. The emailed link stops working. */
+    revokeInvitation(workspaceId: string, invitationId: string, actor: Pick<User, 'id'>): Promise<void>;
+    /** Owner only. */
+    rename(workspaceId: string, name: string, actor: Pick<User, 'id'>): Promise<void>;
+    /** Owner only. The workspace leaves every list and later calls fail with status 410. */
+    archive(workspaceId: string, actor: Pick<User, 'id'>): Promise<void>;
+}
+export declare function workspaces(env?: WorkspacesEnv): Workspaces;

package/dist/workspaces.js

@@ -0,0 +1,137 @@
+export const WORKSPACES_TIMEOUT_MS = 10_000;
+export class WorkspacesError extends Error {
+    status;
+    /** The broker's `error` code, or `unavailable` when it did not answer in the expected shape. */
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.name = 'WorkspacesError';
+        this.status = status;
+        this.code = code;
+    }
+}
+function need(env, name) {
+    const value = env[name]?.trim();
+    if (!value)
+        throw new Error(`@wtfalch/auth/workspaces: ${name} is not set.`);
+    return value;
+}
+function requireEmail(user) {
+    if (!user.email) {
+        throw new WorkspacesError(0, 'invalid', 'The signed-in person has no email address.');
+    }
+    return user.email;
+}
+export function workspaces(env = process.env) {
+    const base = need(env, 'WORKSPACES_URL').replace(/\/+$/, '');
+    const key = need(env, 'WORKSPACES_API_KEY');
+    const organizationId = need(env, 'AUTH_ORGANIZATION_ID');
+    const root = `${base}/apps/${encodeURIComponent(organizationId)}/v1`;
+    async function call(method, path, options = {}) {
+        const url = new URL(root + path);
+        for (const [name, value] of Object.entries(options.query ?? {})) {
+            url.searchParams.set(name, value);
+        }
+        const headers = {
+            authorization: `Bearer ${key}`,
+            accept: 'application/json',
+        };
+        if (options.body !== undefined)
+            headers['content-type'] = 'application/json';
+        let response;
+        try {
+            response = await fetch(url, {
+                method,
+                headers,
+                body: options.body === undefined ? undefined : JSON.stringify(options.body),
+                signal: AbortSignal.timeout(WORKSPACES_TIMEOUT_MS),
+            });
+        }
+        catch (error) {
+            const timedOut = error instanceof Error && error.name === 'TimeoutError';
+            throw new WorkspacesError(0, 'unavailable', timedOut
+                ? `The workspaces service did not answer within ${WORKSPACES_TIMEOUT_MS / 1000} seconds.`
+                : 'The workspaces service could not be reached.');
+        }
+        let payload;
+        try {
+            payload = await response.json();
+        }
+        catch {
+            payload = undefined;
+        }
+        if (!response.ok) {
+            const fields = (payload ?? {});
+            throw new WorkspacesError(response.status, typeof fields.error === 'string' ? fields.error : 'unavailable', typeof fields.message === 'string'
+                ? fields.message.split(key).join('[redacted]')
+                : `The workspaces service answered ${response.status}.`);
+        }
+        return payload;
+    }
+    const segment = encodeURIComponent;
+    return {
+        async create({ name, owner }) {
+            const body = { name, ownerSub: owner.id, ownerEmail: requireEmail(owner) };
+            return (await call('POST', '/workspaces', { body }));
+        },
+        async listFor(user) {
+            return (await call('GET', '/workspaces', {
+                query: { sub: user.id },
+            }));
+        },
+        async invite(workspaceId, { email, role, actor }) {
+            const body = { email, role, actorSub: actor.id };
+            return (await call('POST', `/workspaces/${segment(workspaceId)}/invitations`, {
+                body,
+            }));
+        },
+        async accept(token, user) {
+            const body = {
+                token,
+                sub: user.id,
+                email: requireEmail(user),
+                emailVerified: user.emailVerified,
+            };
+            return (await call('POST', '/invitations/accept', { body }));
+        },
+        async setRole(workspaceId, memberSub, { role, actor }) {
+            await call('PUT', `/workspaces/${segment(workspaceId)}/members/${segment(memberSub)}`, {
+                body: { role, actorSub: actor.id },
+            });
+        },
+        async remove(workspaceId, memberSub, actor) {
+            await call('DELETE', `/workspaces/${segment(workspaceId)}/members/${segment(memberSub)}`, {
+                query: { actorSub: actor.id },
+            });
+        },
+        async access(workspaceId, user) {
+            const answer = (await call('GET', `/workspaces/${segment(workspaceId)}/access`, {
+                query: { sub: user.id },
+            }));
+            return answer.role;
+        },
+        async members(workspaceId, actor) {
+            return (await call('GET', `/workspaces/${segment(workspaceId)}/members`, {
+                query: { actorSub: actor.id },
+            }));
+        },
+        async invitations(workspaceId, actor) {
+            return (await call('GET', `/workspaces/${segment(workspaceId)}/invitations`, {
+                query: { actorSub: actor.id },
+            }));
+        },
+        async revokeInvitation(workspaceId, invitationId, actor) {
+            await call('DELETE', `/workspaces/${segment(workspaceId)}/invitations/${segment(invitationId)}`, { query: { actorSub: actor.id } });
+        },
+        async rename(workspaceId, name, actor) {
+            await call('PATCH', `/workspaces/${segment(workspaceId)}`, {
+                body: { name, actorSub: actor.id },
+            });
+        },
+        async archive(workspaceId, actor) {
+            await call('POST', `/workspaces/${segment(workspaceId)}/archive`, {
+                body: { actorSub: actor.id },
+            });
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/auth",
-  "version": "0.31.0",
+  "version": "0.33.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",
@@ -65,6 +65,10 @@
     "./desktop": {
       "types": "./dist/desktop.d.ts",
       "default": "./dist/desktop.js"
+    },
+    "./workspaces": {
+      "types": "./dist/workspaces.d.ts",
+      "default": "./dist/workspaces.js"
     }
   },
   "sideEffects": false,
@@ -103,10 +107,12 @@
     "@cloudflare/vitest-pool-workers": "0.23.0",
     "@electric-sql/pglite": "^0.5.8",
     "@types/node": "^22",
+    "@types/pg": "^8.23.1",
     "@types/qrcode": "^1.5.6",
     "@types/react": "^19",
     "@wtfalch/auth-broker": "workspace:*",
-    "next": "^16.4.0",
+    "next": "^16.4.2",
+    "pg": "8.16.3",
     "playwright-core": "^1.62.1",
     "react": "^19",
     "typescript": "^5.9.0",