@wtfalch/auth 0.2.1 → 0.3.1

package/README.md

@@ -3,8 +3,9 @@
 Sign in against [auth.wtfalch.dev](https://auth.wtfalch.dev) from a Next.js app.
 
 A thin OIDC client for one self-hosted ZITADEL instance, plus a client for the
-sign-in service that sits in front of it. Apps host their own sign-in pages: a
-browser never renders a page on the identity service.
+sign-in service that sits in front of it. Apps host their own password sign-in
+pages. Flows requiring MFA or another unsupported login policy continue at
+the identity service's hosted login.
 
 Built for the wtfalch estate, published because valet consumes it from a
 container and a `file:` path does not survive a Docker build.
@@ -39,6 +40,26 @@ middleware for the paths that need a session, and read the person with
 `createAuth` from `@wtfalch/auth` is the same thing without the framework, for
 a CLI or a worker that has no router to import.
 
+## MFA and hosted login
+
+The broker checks the organisation's login policy and enrolled authentication
+methods before completing password sign-in, signup, or password reset. MFA,
+disabled password authentication, and unknown authentication methods require
+the hosted login. Email links always continue there: ZITADEL email OTP is a
+second factor and cannot authenticate a session by itself.
+
+The Next.js adapter handles these redirects and preserves the OIDC
+transaction. With the framework-neutral API, a successful result carrying
+`hosted: true` means authentication is still pending: redirect to
+`redirectTo` (sign-in/signup) or `location` (reset), writing any returned
+cookies first. Do not pass a hosted URL to `complete`. The eventual OIDC
+callback completes authentication with the original PKCE, state, nonce, and
+destination.
+
+Auth-request lookup failures lead to the configured error page with
+`auth_error=request` or `auth_error=unavailable`. That page should show a
+retry link; it must not automatically restart authorization.
+
 ## Configuration
 
 | | |

package/dist/auth.d.ts

@@ -1,5 +1,5 @@
 import { type JWTPayload } from 'jose';
-import { type AuthRequest, type NewUser } from './broker.js';
+import { type AuthRequest, type NewUser, type PeoplePage } from './broker.js';
 import { type AuthOptions } from './config.js';
 import { type SetCookie } from './cookies.js';
 export interface User {
@@ -43,6 +43,7 @@ export type SignUpError = 'registration_closed' | 'email_taken' | 'username_take
 export type SignInResult = {
     ok: true;
     redirectTo: string;
+    hosted?: true;
 } | {
     ok: false;
     error: SignInError;
@@ -50,6 +51,7 @@ export type SignInResult = {
 export type SignUpResult = {
     ok: true;
     redirectTo: string;
+    hosted?: true;
 } | {
     ok: false;
     error: SignUpError;
@@ -64,6 +66,7 @@ export type SignedIn = {
     ok: true;
     location: string;
     cookies: SetCookie[];
+    hosted?: true;
 } | {
     ok: false;
     error: ResetError;
@@ -121,6 +124,33 @@ export interface Auth {
     }): Promise<ReadResult>;
     gate(request: Request, rules?: GateRules): Promise<Gate>;
     startUrl(next?: string | null, intent?: Intent): string;
+    /**
+     * Where to send somebody when a sign-in step failed for a reason they
+     * cannot fix by retrying it automatically: `onError` with `?auth_error=`,
+     * which is the same shape the callback's own failures use. Exposed because
+     * the Next adapter has to reach it from a server component, where a
+     * `Response` is no use.
+     */
+    errorUrl(reason: string): string;
+    /**
+     * The organisation's people, for an operator surface. The scope is this
+     * app's own organisation, decided by the service from the key rather than
+     * by an argument here, so there is no call that reads another one's.
+     */
+    people(options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<PeoplePage>;
+    /**
+     * Deactivate or reactivate somebody. Refused for a user outside this app's
+     * organisation. Deactivating stops them signing in and keeps the row, the
+     * memberships and the trail; there is no delete here, deliberately —
+     * erasure is an authorisation concern with its own audited path.
+     */
+    setPersonActive(userId: string, active: boolean): Promise<{
+        userId: string;
+        state: string;
+    }>;
     /** The auth request the issuer sent the browser here with. Refuses one for another application. */
     authRequest(id: string): Promise<AuthRequest>;
     signIn(input: {

package/dist/auth.js

@@ -180,6 +180,8 @@ export function createAuth(input) {
             return { kind: 'deny', cookies };
         return { kind: 'redirect', location: startUrl(`${url.pathname}${url.search}`), cookies };
     };
+    const people = (options) => broker().people(options);
+    const setPersonActive = (userId, active) => broker().setPersonActive(userId, active);
     const authRequest = (id) => broker().authRequest(id);
     /**
      * An OIDC flow this app starts and finishes itself, for a person arriving
@@ -207,6 +209,35 @@ export function createAuth(input) {
         const cookie = await sealSession(options(), { idt: tokens.idToken, rt: tokens.refreshToken });
         return { location: new URL(next, options().appUrl).href, cookies: [cookie] };
     };
+    const hostedUrl = (id) => {
+        const url = new URL('/login', options().issuer);
+        url.searchParams.set('authRequest', id);
+        return url.href;
+    };
+    const needsHostedLogin = (error) => error instanceof BrokerError && error.error === 'hosted_login_required';
+    // Email/reset flows started on the server must transfer their PKCE transaction
+    // to the browser before handing off to the issuer's full authentication UI.
+    const finishOrHandoff = async (action, flow, next) => {
+        try {
+            return await finish(await action(), flow, next);
+        }
+        catch (error) {
+            if (!needsHostedLogin(error))
+                throw error;
+            return {
+                location: hostedUrl(flow.id),
+                hosted: true,
+                cookies: [
+                    await sealTransaction(options(), {
+                        st: flow.state,
+                        nc: flow.nonce,
+                        cv: flow.verifier,
+                        nx: next,
+                    }),
+                ],
+            };
+        }
+    };
     const resendVerification = (email, next) => quietly(() => broker().sendVerification(email, safeNextPath(next, '')));
     const requestPasswordReset = (email, next) => quietly(() => broker().sendReset(email, safeNextPath(next, '')));
     const sendLink = (email, next) => quietly(() => broker().sendLink(email, safeNextPath(next, '')));
@@ -214,14 +245,8 @@ export function createAuth(input) {
     const resetPassword = async ({ userId, code, password, next, }) => {
         try {
             const flow = await serverFlow();
-            const callbackUrl = await broker().completeReset({
-                authRequestId: flow.id,
-                userId,
-                code,
-                password,
-            });
-            const { location, cookies } = await finish(callbackUrl, flow, safeNextPath(next, options().afterLogin));
-            return { ok: true, location, cookies };
+            const completed = await finishOrHandoff(() => broker().completeReset({ authRequestId: flow.id, userId, code, password }), flow, safeNextPath(next, options().afterLogin));
+            return { ok: true, ...completed };
         }
         catch (error) {
             if (error instanceof BrokerError && error.error === 'invalid_password') {
@@ -241,8 +266,7 @@ export function createAuth(input) {
             return failed('link', []);
         try {
             const flow = await serverFlow();
-            const callbackUrl = await broker().followLink({ authRequestId: flow.id, sessionId, code });
-            const { location, cookies } = await finish(callbackUrl, flow, safeNextPath(params.get('next'), options().afterLogin));
+            const { location, cookies } = await finishOrHandoff(() => broker().followLink({ authRequestId: flow.id, sessionId, code }), flow, safeNextPath(params.get('next'), options().afterLogin));
             return redirect(location, cookies);
         }
         catch {
@@ -254,6 +278,8 @@ export function createAuth(input) {
             return { ok: true, redirectTo: await broker().signIn({ authRequestId, email, password }) };
         }
         catch (error) {
+            if (needsHostedLogin(error))
+                return { ok: true, redirectTo: hostedUrl(authRequestId), hosted: true };
             return { ok: false, error: signInError(error) };
         }
     };
@@ -262,6 +288,8 @@ export function createAuth(input) {
             return { ok: true, redirectTo: await broker().signUp({ authRequestId, ...user }) };
         }
         catch (error) {
+            if (needsHostedLogin(error))
+                return { ok: true, redirectTo: hostedUrl(authRequestId), hosted: true };
             if (error instanceof BrokerError && error.error === 'email_taken') {
                 return { ok: false, error: 'email_taken', message: error.detail ?? error.error };
             }
@@ -289,6 +317,8 @@ export function createAuth(input) {
         url.searchParams.set('auth_error', reason);
         return { location: url.href, cookies };
     };
+    /** `failure`'s location on its own, for a caller that redirects rather than answering. */
+    const errorUrl = (reason) => failure(reason, []).location;
     const failed = (reason, cookies) => {
         const { location } = failure(reason, []);
         return redirect(location, cookies);
@@ -313,6 +343,9 @@ export function createAuth(input) {
         readCookie,
         gate,
         startUrl,
+        errorUrl,
+        people,
+        setPersonActive,
         authRequest,
         signIn,
         signUp,

package/dist/broker.d.ts

@@ -16,6 +16,21 @@ export interface NewUser {
      */
     username?: string;
 }
+/** One of the organisation's people, as the sign-in service reports them. */
+export interface Person {
+    readonly userId: string;
+    readonly username: string;
+    readonly displayName: string;
+    readonly email: string | null;
+    readonly emailVerified: boolean;
+    /** `active`, `inactive`, or `unknown` if the issuer said something newer. */
+    readonly state: string;
+}
+export interface PeoplePage {
+    /** Everyone in the organisation, not only this page. */
+    readonly total: number;
+    readonly people: readonly Person[];
+}
 export declare class BrokerError extends Error {
     readonly status: number;
     readonly error: string;
@@ -31,6 +46,14 @@ export declare class Broker {
     private readonly options;
     constructor(options: ResolvedOptions);
     private call;
+    people(options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<PeoplePage>;
+    setPersonActive(userId: string, active: boolean): Promise<{
+        userId: string;
+        state: string;
+    }>;
     authRequest(id: string): Promise<AuthRequest>;
     signIn(input: {
         authRequestId: string;

package/dist/broker.js

@@ -51,6 +51,17 @@ export class Broker {
         }
         return data;
     }
+    people(options = {}) {
+        const query = {};
+        if (options.limit !== undefined)
+            query.limit = options.limit;
+        if (options.offset !== undefined)
+            query.offset = options.offset;
+        return this.call('GET', '/people', query);
+    }
+    setPersonActive(userId, active) {
+        return this.call('POST', active ? '/people/reactivate' : '/people/deactivate', { userId });
+    }
     authRequest(id) {
         return this.call('GET', '/auth-request', { id });
     }

package/dist/next.d.ts

@@ -53,6 +53,10 @@ export interface NextAuth {
         userId: string;
         invited: boolean;
     }>;
+    /** The organisation's people, for an operator surface. Scoped to this app's organisation by the service. */
+    people: Auth['people'];
+    /** Deactivate or reactivate somebody in this app's organisation. */
+    setPersonActive: Auth['setPersonActive'];
     /** Sets the password from a reset link, signs the person in, and redirects. */
     resetPassword: (input: {
         userId: string;

package/dist/next.js

@@ -2,7 +2,19 @@ import { cookies } from 'next/headers';
 import { redirect } from 'next/navigation';
 import { NextResponse } from 'next/server';
 import { createAuth, } from './auth.js';
+import { BrokerError } from './broker.js';
 import { withCookies } from './cookies.js';
+/**
+ * Which of the two failures it was, in the vocabulary `auth_error` already
+ * uses. A refusal under 500 is about this request — the broker says unknown,
+ * expired, or not this application's — and retrying it will fail again. A
+ * 500, or no answer at all, is about the service, and retrying later may
+ * well work. The page says which, because "try again" is good advice for one
+ * and useless for the other.
+ */
+function authRequestReason(error) {
+    return error instanceof BrokerError && error.status < 500 ? 'request' : 'unavailable';
+}
 export function nextAuth(options) {
     const auth = createAuth(options);
     const proxy = async (request, rules) => {
@@ -39,16 +51,44 @@ export function nextAuth(options) {
             redirect(auth.startUrl(next));
         return user;
     };
+    /**
+     * The auth request the issuer sent the browser here with.
+     *
+     * **No id starts a flow; an id that will not resolve does not.** The
+     * distinction is the whole of this function, and getting it wrong is not a
+     * degraded page but an infinite one. Starting a flow because resolution
+     * failed sends the browser to the issuer, which sends it back here with a
+     * fresh id, which fails the same way — two requests to the issuer per lap,
+     * no error page, nothing in a log, forever. That is not hypothetical: a
+     * client id missing from the broker's registry produced exactly this on
+     * manage.wtfalch.dev, and the visible symptom was Cloudflare rate-limiting
+     * the operator, twenty minutes before anybody could see a 403 underneath
+     * it. The refusal was diagnosable from the first request and the loop hid
+     * it behind thousands.
+     *
+     * So a failure lands on `onError` with a reason, exactly as the callback's
+     * own failures do, and the person clicks to try again. A human click cannot
+     * loop. The reason distinguishes the two cases worth telling apart: the
+     * broker refused this request (unknown, expired, or belonging to another
+     * application) or the broker could not be reached at all.
+     *
+     * The cause goes to the server log either way. A library swallowing the one
+     * error that explains the page is what made this expensive.
+     */
     const authRequest = async (searchParams, opts = {}) => {
         const params = await searchParams;
         const id = typeof params.authRequest === 'string' ? params.authRequest : null;
-        if (id) {
-            try {
-                return await auth.authRequest(id);
-            }
-            catch { }
+        // Nobody has started a flow yet. This cannot loop: the issuer always
+        // sends the browser back carrying an id.
+        if (!id)
+            redirect(auth.startUrl(opts.next, opts.intent));
+        try {
+            return await auth.authRequest(id);
+        }
+        catch (error) {
+            console.error('@wtfalch/auth: could not resolve the auth request', error);
+            redirect(auth.errorUrl(authRequestReason(error)));
         }
-        redirect(auth.startUrl(opts.next, opts.intent));
     };
     // A server action cannot redirect into a route handler, so the callback runs here and the cookies are set on the action's response.
     const finish = async (callbackUrl) => {
@@ -78,19 +118,27 @@ export function nextAuth(options) {
             else
                 store.delete({ name: c.name, path: '/' });
         }
+        if (result.hosted)
+            redirect(result.location);
         const url = new URL(result.location);
         redirect(`${url.pathname}${url.search}`);
     };
     const signIn = async (input) => {
         const result = await auth.signIn(input);
-        if (result.ok)
+        if (result.ok) {
+            if (result.hosted)
+                redirect(result.redirectTo);
             return finish(result.redirectTo);
+        }
         return { error: result.error };
     };
     const signUp = async (input) => {
         const result = await auth.signUp(input);
-        if (result.ok)
+        if (result.ok) {
+            if (result.hosted)
+                redirect(result.redirectTo);
             return finish(result.redirectTo);
+        }
         return { error: result.error, message: result.message };
     };
     return {
@@ -106,6 +154,8 @@ export function nextAuth(options) {
         requestPasswordReset: auth.requestPasswordReset,
         sendLink: auth.sendLink,
         invite: auth.invite,
+        people: auth.people,
+        setPersonActive: auth.setPersonActive,
         resetPassword,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/auth",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Sign in against auth.wtfalch.dev from a Next.js app.",
   "repository": {
     "type": "git",
@@ -8,9 +8,7 @@
     "directory": "packages/auth"
   },
   "type": "module",
-  "files": [
-    "dist"
-  ],
+  "files": ["dist"],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -25,6 +23,12 @@
   "engines": {
     "node": ">=22.0.0"
   },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepack": "pnpm build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
   "dependencies": {
     "jose": "^6.2.10",
     "openid-client": "6.8.7"
@@ -40,16 +44,11 @@
   "devDependencies": {
     "@types/node": "^22",
     "@types/react": "^19",
+    "@wtfalch/auth-broker": "workspace:*",
     "next": "^16",
     "playwright-core": "^1.62.1",
     "react": "^19",
     "typescript": "^5.9.0",
-    "vitest": "^4.1.6",
-    "@wtfalch/auth-broker": "0.1.0"
-  },
-  "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run"
+    "vitest": "^4.1.6"
   }
-}
+}