@wtfalch/auth 0.7.0 → 0.8.0

package/README.md

@@ -139,11 +139,24 @@ app URL, and refreshes itself when the id token is close to expiring.
 `ORG_CLAIM` is enforced on every token: a token from another organisation is
 refused even when the issuer and the signature are good.
 
+## Passkeys and QR sign-in
+
+Passkeys live on each app's own domain: the relying-party ID is the app's
+origin, so one made on one app never signs in on another. `@wtfalch/auth/passkey`
+is the browser half of the WebAuthn ceremony; `startPasskeyRegistration`,
+`finishPasskeyRegistration`, `startPasskeySignIn` and `finishPasskeySignIn` are
+the server half.
+
+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`.
+
 ## Documentation
 
 `docs/adopting.md` in [wtfalch/auth](https://github.com/wtfalch/auth) covers a
-full adoption: the files to add, the email flows, invitations, refresh, and the
-checks to run against a real issuer.
+full adoption: the files to add, the email flows, invitations, refresh,
+passkeys, signing in a new device from a QR code, and the checks to run
+against a real issuer.
 
 ## Licence
 

package/dist/auth.d.ts

@@ -65,6 +65,26 @@ export type SignUpResult = {
     error: SignUpError;
     message: string;
 };
+export interface PasskeyRegistrationStart {
+    passkeyId: string;
+    /** ZITADEL's `publicKeyCredentialCreationOptions`, opaque here -- `@wtfalch/auth/passkey`'s `createPasskey` knows its shape. */
+    options: unknown;
+}
+export type PasskeyRegistrationResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: 'invalid';
+};
+export type PasskeySignInStart = {
+    ok: true;
+    sessionId: string;
+    /** ZITADEL's `publicKeyCredentialRequestOptions`, opaque here -- `@wtfalch/auth/passkey`'s `getPasskey` knows its shape. */
+    options: unknown;
+} | {
+    ok: false;
+    error: SignInError;
+};
 export interface Completed {
     location: string;
     cookies: SetCookie[];
@@ -80,6 +100,27 @@ export type SignedIn = {
     error: ResetError;
     message: string;
 };
+export interface QrSignInStart {
+    /** The verification URL, complete with the user code -- what the QR code encodes. */
+    url: string;
+    /** The same code, for a person to type in by hand instead of scanning. */
+    userCode: string;
+    expiresIn: number;
+    /** Seconds between polls; the issuer's own pace. */
+    interval: number;
+    cookies: SetCookie[];
+}
+export type QrPollStatus = 'pending' | 'slow_down' | 'expired' | 'denied'
+/** Namespace mode: the binding stopped being active between approval and this poll. */
+ | 'unavailable'
+/** The issuer's token response or the id token it carried was rejected -- `reason` is the same vocabulary `auth_error` uses. */
+ | 'failed' | 'signed_in';
+export interface QrPollResult {
+    status: QrPollStatus;
+    /** Set only when `status` is `'failed'`. */
+    reason?: string;
+    cookies: SetCookie[];
+}
 export interface Auth {
     readonly sessionCookieName: string;
     /** GET {basePath}/start?next=&intent= : begins the OIDC flow; the issuer sends the browser to {basePath}/login?authRequest= */
@@ -199,6 +240,48 @@ export interface Auth {
     signUp(input: {
         authRequestId: string;
     } & NewUser): Promise<SignUpResult>;
+    /**
+     * Starts registering a passkey on this app's own domain, for whoever is
+     * signed in on `request` -- never for a stranger. Throws `AuthError` when
+     * nobody is: `account_changed`/`unavailable` exactly as `read` reports
+     * them, `unauthenticated` otherwise.
+     */
+    startPasskeyRegistration(request: Request): Promise<PasskeyRegistrationStart>;
+    /** The second half of `startPasskeyRegistration`. Same signed-in requirement. */
+    finishPasskeyRegistration(request: Request, input: {
+        passkeyId: string;
+        credential: unknown;
+        name: string;
+    }): Promise<PasskeyRegistrationResult>;
+    /** The passkey half of `signIn`: a challenge to answer with `@wtfalch/auth/passkey`'s `getPasskey`. */
+    startPasskeySignIn(input: {
+        authRequestId: string;
+        email: string;
+    }): Promise<PasskeySignInStart>;
+    /** The second half of a passkey sign-in -- otherwise exactly `signIn`: same redirect and hosted-login handling, same error mapping. */
+    finishPasskeySignIn(input: {
+        authRequestId: string;
+        sessionId: string;
+        credential: unknown;
+    }): Promise<SignInResult>;
+    /**
+     * Starts a QR sign-in: the OAuth device authorization grant, on this app's
+     * own web client. `url` is what the QR code encodes (and `userCode` what a
+     * person types instead); a phone already signed in approves it, and
+     * `pollQrSignIn` is how this device finds out. In namespace mode, throws
+     * `AuthError('unavailable', ...)` when the binding is not active -- unlike
+     * `start`, which answers a 503 `Response` for the same case rather than
+     * throwing.
+     */
+    startQrSignIn(): Promise<QrSignInStart>;
+    /**
+     * Polls the transaction `startQrSignIn` began; `request` carries its
+     * cookie. Never throws for an outcome of the poll itself -- a suspended
+     * binding or a rejected token response answers `'unavailable'`/`'failed'`
+     * with the transaction cookie cleared, the same way `complete` answers a
+     * failed callback rather than throwing.
+     */
+    pollQrSignIn(request: Request): Promise<QrPollResult>;
 }
 export declare function createAuth(input: AuthOptions): Auth;
 export type { AuthRequest, NewUser, SetCookie };

package/dist/auth.js

@@ -2,9 +2,10 @@ import { errors } from 'jose';
 import * as client from 'openid-client';
 import { Broker, BrokerError } from './broker.js';
 import { resolveOptions } from './config.js';
-import { clearSession, clearTransaction, cookieFrom, openSession, openTransaction, sealSession, sealTransaction, sessionCookieName, transactionCookieName, } from './cookies.js';
+import { clearQrTransaction, clearSession, clearTransaction, cookieFrom, openQrTransaction, openSession, openTransaction, qrTransactionCookieName, sealQrTransaction, sealSession, sealTransaction, sessionCookieName, transactionCookieName, } from './cookies.js';
 import { namespaceSessions } from './namespace-session.js';
-import { AuthError, ORG_CLAIM, Oidc } from './oidc.js';
+import { AuthError, ORG_CLAIM, Oidc, scopeFor } from './oidc.js';
+import { pollDeviceToken, requestDeviceAuthorization } from './qr.js';
 import { safeNextPath } from './redirect.js';
 export function createAuth(input) {
     // Resolved on first use so `next build`, which imports every route module, needs none of the values set.
@@ -59,6 +60,19 @@ export function createAuth(input) {
     const sessionCookie = (tokens) => options().namespace
         ? sessions.create(tokens)
         : sealSession(options(), { idt: tokens.idToken, rt: tokens.refreshToken });
+    /**
+     * Signing in again replaces this binding's previous session outright: in
+     * namespace mode, ends whatever session record `cookieHeader` already
+     * named. Shared by `complete` and `pollQrSignIn`, the two places a fresh
+     * session is created for a browser that may already hold one.
+     */
+    const replacePreviousSession = async (cookieHeader) => {
+        if (!options().namespace)
+            return;
+        await sessions
+            .end(cookieFrom(cookieHeader, sessionCookieName(options())))
+            .catch((error) => console.error('@wtfalch/auth: could not end the replaced session', error));
+    };
     const unavailable = () => new Response('Sign-in is unavailable for this workspace', { status: 503 });
     const startUrl = (next, intent = 'login') => {
         const url = new URL(`${options().basePath}/start`, options().appUrl);
@@ -114,11 +128,7 @@ export function createAuth(input) {
         catch (error) {
             return failure(reasonOf(error), [cleared]);
         }
-        // Signing in again replaces this binding's previous session outright.
-        if (options().namespace)
-            await sessions
-                .end(cookieFrom(cookieHeader, sessionCookieName(options())))
-                .catch((error) => console.error('@wtfalch/auth: could not end the replaced session', error));
+        await replacePreviousSession(cookieHeader);
         return {
             location: new URL(transaction.nx, options().appUrl).href,
             cookies: [cleared, session],
@@ -256,6 +266,22 @@ export function createAuth(input) {
             return { kind: 'deny', cookies };
         return { kind: 'redirect', location: startUrl(`${url.pathname}${url.search}`), cookies };
     };
+    /**
+     * The person signed in on `request`, for the passkey routes -- never a
+     * stranger. Adapts `requireUser`'s reasons for a caller that throws rather
+     * than redirects: `account_changed`/`unavailable` are read's own, and
+     * plain absence becomes `unauthenticated`, which read has no reason for.
+     */
+    const currentUser = async (request) => {
+        const { user, accountChanged, unavailable } = await read(request, { refresh: false });
+        if (accountChanged)
+            throw new AuthError('account_changed', 'Choose an account to continue');
+        if (unavailable)
+            throw new AuthError('unavailable', 'Sign-in is unavailable for this workspace');
+        if (!user)
+            throw new AuthError('unauthenticated', 'sign in to use a passkey');
+        return user;
+    };
     const people = (options) => broker().people(options);
     const setPersonActive = async (userId, active) => {
         const result = await broker().setPersonActive(userId, active);
@@ -417,6 +443,114 @@ export function createAuth(input) {
             return { ok: false, error: 'unavailable', message: 'the sign-in service did not answer' };
         }
     };
+    const startPasskeyRegistration = async (request) => {
+        const user = await currentUser(request);
+        return broker().startPasskeyRegistration(user.id);
+    };
+    const finishPasskeyRegistration = async (request, input) => {
+        const user = await currentUser(request);
+        // Built from named fields, never spread: `input` crosses a trust
+        // boundary (a Next.js Server Action does not enforce its TS parameter
+        // types on the wire), and a spread after `userId: user.id` would let a
+        // caller-supplied `userId` key overwrite the session's own identity.
+        const passkeyId = input?.passkeyId;
+        const name = typeof input?.name === 'string' ? input.name.trim() : '';
+        const credential = input?.credential;
+        if (typeof passkeyId !== 'string' ||
+            passkeyId.length === 0 ||
+            name.length === 0 ||
+            name.length > 64 ||
+            !credential ||
+            typeof credential !== 'object' ||
+            Array.isArray(credential)) {
+            return { ok: false, error: 'invalid' };
+        }
+        try {
+            await broker().finishPasskeyRegistration({ userId: user.id, passkeyId, credential, name });
+            return { ok: true };
+        }
+        catch (error) {
+            if (error instanceof BrokerError && error.status < 500)
+                return { ok: false, error: 'invalid' };
+            throw error;
+        }
+    };
+    const startPasskeySignIn = async ({ authRequestId, email, }) => {
+        try {
+            const { sessionId, options } = await broker().startPasskeySignIn({ authRequestId, email });
+            return { ok: true, sessionId, options };
+        }
+        catch (error) {
+            return { ok: false, error: signInError(error) };
+        }
+    };
+    const finishPasskeySignIn = async ({ authRequestId, sessionId, credential, }) => {
+        try {
+            return {
+                ok: true,
+                redirectTo: await broker().finishPasskeySignIn({ authRequestId, sessionId, credential }),
+            };
+        }
+        catch (error) {
+            if (needsHostedLogin(error))
+                return { ok: true, redirectTo: hostedUrl(authRequestId), hosted: true };
+            return { ok: false, error: signInError(error) };
+        }
+    };
+    const startQrSignIn = async () => {
+        if (options().namespace && !(await sessions.bindingActive()))
+            throw new AuthError('unavailable', 'the namespace binding is not active');
+        const device = await requestDeviceAuthorization(options(), scopeFor(options().organizationId));
+        const cookie = await sealQrTransaction(options(), { dc: device.deviceCode, iv: device.interval }, device.expiresIn);
+        return {
+            url: device.verificationUriComplete,
+            userCode: device.userCode,
+            expiresIn: device.expiresIn,
+            interval: device.interval,
+            cookies: [cookie],
+        };
+    };
+    const pollQrSignIn = async (request) => {
+        const cleared = clearQrTransaction(options());
+        const transaction = await openQrTransaction(options(), cookieFrom(request.headers.get('cookie'), qrTransactionCookieName(options())));
+        // Missing, tampered, another binding's, or its own `exp` (the issuer's
+        // `expires_in`, sealed in by `startQrSignIn`) already past: all the same
+        // refusal a stranger's cookie gets everywhere else in this file.
+        if (!transaction)
+            return { status: 'expired', cookies: [cleared] };
+        // An outcome of the poll itself -- a rejected token response, or an id
+        // token that fails validation (wrong organisation, bad signature) --
+        // answers rather than throws, exactly as `complete` answers a failed
+        // exchange with `failure(reasonOf(error), ...)` instead of throwing it.
+        let outcome;
+        try {
+            outcome = await pollDeviceToken(options(), oidc(), transaction.dc);
+        }
+        catch (error) {
+            return { status: 'failed', reason: reasonOf(error), cookies: [cleared] };
+        }
+        if (outcome.status === 'pending')
+            return { status: 'pending', cookies: [] };
+        if (outcome.status === 'slow_down')
+            return { status: 'slow_down', cookies: [] };
+        if (outcome.status === 'expired')
+            return { status: 'expired', cookies: [cleared] };
+        if (outcome.status === 'denied')
+            return { status: 'denied', cookies: [cleared] };
+        // The binding can go suspended between approval and this poll landing;
+        // that is this outcome, not a programmer error, so it answers too.
+        if (options().namespace && !(await sessions.bindingActive()))
+            return { status: 'unavailable', cookies: [cleared] };
+        let session;
+        try {
+            session = await sessionCookie(outcome.tokens);
+        }
+        catch (error) {
+            return { status: 'failed', reason: reasonOf(error), cookies: [cleared] };
+        }
+        await replacePreviousSession(request.headers.get('cookie'));
+        return { status: 'signed_in', cookies: [cleared, session] };
+    };
     const failure = (reason, cookies) => {
         const url = new URL(options().onError, options().appUrl);
         url.searchParams.set('auth_error', reason);
@@ -456,6 +590,12 @@ export function createAuth(input) {
         authRequest,
         signIn,
         signUp,
+        startPasskeyRegistration,
+        finishPasskeyRegistration,
+        startPasskeySignIn,
+        finishPasskeySignIn,
+        startQrSignIn,
+        pollQrSignIn,
     };
 }
 function redirect(location, cookies, status = 302) {

package/dist/broker.d.ts

@@ -63,6 +63,30 @@ export declare class Broker {
     signUp(input: {
         authRequestId: string;
     } & NewUser): Promise<string>;
+    /** A passkey for somebody already signed in on the app's own domain. */
+    startPasskeyRegistration(userId: string): Promise<{
+        passkeyId: string;
+        options: unknown;
+    }>;
+    finishPasskeyRegistration(input: {
+        userId: string;
+        passkeyId: string;
+        credential: unknown;
+        name: string;
+    }): Promise<void>;
+    /** The passkey half of `signIn`: a challenge to answer, not yet a session. */
+    startPasskeySignIn(input: {
+        authRequestId: string;
+        email: string;
+    }): Promise<{
+        sessionId: string;
+        options: unknown;
+    }>;
+    finishPasskeySignIn(input: {
+        authRequestId: string;
+        sessionId: string;
+        credential: unknown;
+    }): Promise<string>;
     followLink(input: {
         authRequestId: string;
         sessionId: string;

package/dist/broker.js

@@ -76,6 +76,21 @@ export class Broker {
         });
         return callbackUrl;
     }
+    /** A passkey for somebody already signed in on the app's own domain. */
+    startPasskeyRegistration(userId) {
+        return this.call('POST', '/passkey/register/start', { userId });
+    }
+    async finishPasskeyRegistration(input) {
+        await this.call('POST', '/passkey/register/finish', input);
+    }
+    /** The passkey half of `signIn`: a challenge to answer, not yet a session. */
+    startPasskeySignIn(input) {
+        return this.call('POST', '/passkey/start', input);
+    }
+    async finishPasskeySignIn(input) {
+        const { callbackUrl } = await this.call('POST', '/passkey/finish', input);
+        return callbackUrl;
+    }
     async followLink(input) {
         const { callbackUrl } = await this.call('POST', '/link/follow', input);
         return callbackUrl;

package/dist/cookies.d.ts

@@ -28,6 +28,11 @@ export interface LinkPayload extends JWTPayload {
     stk: string;
     ar: string;
 }
+/** The QR device-grant transaction: the device_code, never handed to the caller, and the interval the issuer asked us to poll at. Its own `exp` -- set to the issuer's `expires_in` -- is what makes an unsealed-past-expiry cookie fail open with the others below. */
+export interface QrTransactionPayload extends JWTPayload {
+    dc: string;
+    iv: number;
+}
 export interface SetCookie {
     name: string;
     value: string;
@@ -52,6 +57,15 @@ export declare function digest(value: string): Promise<string>;
 export declare function sealTransaction(options: ResolvedOptions, payload: Omit<TransactionPayload, keyof JWTPayload>): Promise<SetCookie>;
 export declare function openTransaction(options: ResolvedOptions, value: string | undefined): Promise<TransactionPayload | null>;
 export declare function clearTransaction(options: ResolvedOptions): SetCookie;
+export declare function qrTransactionCookieName(options: ResolvedOptions): string;
+/**
+ * `ttl` is the issuer's own `expires_in` for the device code, not a fixed
+ * constant like the other transactions: the cookie must not outlive what it
+ * points at.
+ */
+export declare function sealQrTransaction(options: ResolvedOptions, payload: Omit<QrTransactionPayload, keyof JWTPayload>, ttl: number): Promise<SetCookie>;
+export declare function openQrTransaction(options: ResolvedOptions, value: string | undefined): Promise<QrTransactionPayload | null>;
+export declare function clearQrTransaction(options: ResolvedOptions): SetCookie;
 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>;

package/dist/cookies.js

@@ -3,6 +3,7 @@ import { AuthError } from './oidc.js';
 const SESSION = 'wtfalch_auth';
 const TRANSACTION = 'wtfalch_auth_tx';
 const LINK = 'wtfalch_auth_link';
+const QR = 'wtfalch_auth_qr';
 const TRANSACTION_TTL = 10 * 60;
 /**
  * A namespace session handle lives as long as a browser will keep a cookie.
@@ -80,6 +81,27 @@ export async function openTransaction(options, value) {
 export function clearTransaction(options) {
     return setCookie(transactionCookieName(options), '', 0, options.secure);
 }
+export function qrTransactionCookieName(options) {
+    return options.secure ? `__Host-${QR}` : QR;
+}
+/**
+ * `ttl` is the issuer's own `expires_in` for the device code, not a fixed
+ * constant like the other transactions: the cookie must not outlive what it
+ * points at.
+ */
+export async function sealQrTransaction(options, payload, ttl) {
+    const value = await seal(options, 'qr', payload, ttl);
+    return setCookie(qrTransactionCookieName(options), value, ttl, options.secure);
+}
+export async function openQrTransaction(options, value) {
+    const payload = await open(options, 'qr', value);
+    return payload && typeof payload.dc === 'string' && typeof payload.iv === 'number'
+        ? payload
+        : null;
+}
+export function clearQrTransaction(options) {
+    return setCookie(qrTransactionCookieName(options), '', 0, options.secure);
+}
 export function linkCookieName(options) {
     return options.secure ? `__Host-${LINK}` : LINK;
 }

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { type Auth, type AuthRequest, type Gate, type GateRules, type Intent, type NewUser, type ReadResult, type ResetError, type SignInError, type SignInResult, type SignUpError, type SignUpResult, type SignedIn, type User, createAuth, } from './auth.js';
+export { type Auth, type AuthRequest, type Gate, type GateRules, type Intent, type NewUser, type PasskeyRegistrationResult, type PasskeyRegistrationStart, type PasskeySignInStart, type QrPollResult, type QrPollStatus, type QrSignInStart, type ReadResult, type ResetError, type SignInError, type SignInResult, type SignUpError, type SignUpResult, type SignedIn, type User, createAuth, } from './auth.js';
 export { type AuthOptions, ISSUER } from './config.js';
 export type { SetCookie } from './cookies.js';
 export type { SessionRecord, SessionStore, SessionUpdate } from './sessions.js';

package/dist/namespaces.d.ts

@@ -20,6 +20,19 @@ export interface NamespaceService {
     postLogoutRedirectUris: string[];
     credentialRef: string;
     registration: boolean;
+    /**
+     * A sign-in link may finish a sign-in on its own, making the inbox proof
+     * enough. The broker's `App.emailLink` holds the reasoning. Omitted means
+     * off.
+     */
+    emailLink?: true;
+    /**
+     * A new device can be signed in by a QR code that an already signed-in
+     * person approves, via the issuer's OAuth device authorization grant on
+     * this binding's own OIDC client. Anyone can start one, so the approving
+     * page must show what is being approved. Omitted means off.
+     */
+    qrSignIn?: true;
 }
 /**
  * Installed software a person signs in to by approving on another device: a
@@ -108,6 +121,19 @@ export declare function resolveNamespaceBinding(registry: NamespaceRegistry, inp
     postLogoutRedirectUris: string[];
     credentialRef: string;
     registration: boolean;
+    /**
+     * A sign-in link may finish a sign-in on its own, making the inbox proof
+     * enough. The broker's `App.emailLink` holds the reasoning. Omitted means
+     * off.
+     */
+    emailLink?: true;
+    /**
+     * A new device can be signed in by a QR code that an already signed-in
+     * person approves, via the issuer's OAuth device authorization grant on
+     * this binding's own OIDC client. Anyone can start one, so the approving
+     * page must show what is being approved. Omitted means off.
+     */
+    qrSignIn?: true;
     appId: string;
     clientId: string;
     issuer: string;
@@ -143,6 +169,19 @@ export declare function resolveNamespaceContext(selection: NamespaceSelection, o
     postLogoutRedirectUris: string[];
     credentialRef: string;
     registration: boolean;
+    /**
+     * A sign-in link may finish a sign-in on its own, making the inbox proof
+     * enough. The broker's `App.emailLink` holds the reasoning. Omitted means
+     * off.
+     */
+    emailLink?: true;
+    /**
+     * A new device can be signed in by a QR code that an already signed-in
+     * person approves, via the issuer's OAuth device authorization grant on
+     * this binding's own OIDC client. Anyone can start one, so the approving
+     * page must show what is being approved. Omitted means off.
+     */
+    qrSignIn?: true;
     appId: string;
     clientId: string;
     issuer: string;

package/dist/namespaces.js

@@ -86,7 +86,14 @@ function credential(value) {
         invalid('credentialRef');
     return credentialRef;
 }
-const WEB_FIELDS = ['appOrigin', 'redirectUris', 'postLogoutRedirectUris', 'registration'];
+const WEB_FIELDS = [
+    'appOrigin',
+    'redirectUris',
+    'postLogoutRedirectUris',
+    'registration',
+    'emailLink',
+    'qrSignIn',
+];
 function service(value) {
     const s = object(value, 'service');
     const kind = s.kind === undefined ? 'web' : oneOf(s.kind, ['web', 'native', 'api'], 'kind');
@@ -111,6 +118,10 @@ function service(value) {
     const credentialRef = credential(s.credentialRef);
     if (s.registration !== undefined && typeof s.registration !== 'boolean')
         invalid('registration');
+    if (s.emailLink !== undefined && typeof s.emailLink !== 'boolean')
+        invalid('emailLink');
+    if (s.qrSignIn !== undefined && typeof s.qrSignIn !== 'boolean')
+        invalid('qrSignIn');
     return {
         ...identity,
         appOrigin,
@@ -118,6 +129,8 @@ function service(value) {
         postLogoutRedirectUris: uris(s.postLogoutRedirectUris, appOrigin, 'postLogoutRedirectUris'),
         credentialRef,
         registration: s.registration === true,
+        ...(s.emailLink === true ? { emailLink: true } : {}),
+        ...(s.qrSignIn === true ? { qrSignIn: true } : {}),
     };
 }
 function parse(raw, resolved) {

package/dist/next.d.ts

@@ -1,7 +1,13 @@
 import { type NextRequest, NextResponse } from 'next/server';
-import { type Auth, type AuthRequest, type GateRules, type Intent, type NewUser, type ResetError, type SignInError, type SignUpError, type User } from './auth.js';
+import { type Auth, type AuthRequest, type GateRules, type Intent, type NewUser, type PasskeyRegistrationResult, type PasskeyRegistrationStart, type PasskeySignInStart, type QrPollStatus, type ResetError, type SignInError, type SignUpError, type User } from './auth.js';
 import type { AuthOptions } from './config.js';
 type SearchParams = Record<string, string | string[] | undefined>;
+export interface QrSignIn {
+    url: string;
+    userCode: string;
+    expiresIn: number;
+    interval: number;
+}
 export interface NextAuth {
     auth: Auth;
     /** `export const { GET, POST } = handlers` from app/auth/[...auth]/route.ts. */
@@ -67,6 +73,47 @@ export interface NextAuth {
         error: ResetError;
         message: string;
     }>;
+    /**
+     * Registers a passkey on this app's own domain for the person signed in
+     * here. Throws `AuthError('unauthenticated', ...)` for nobody, exactly as
+     * `requireUser` throws `account_changed`/`unavailable` for those.
+     */
+    startPasskeyRegistration: () => Promise<PasskeyRegistrationStart>;
+    /** The second half of `startPasskeyRegistration`. Same signed-in requirement. */
+    finishPasskeyRegistration: (input: {
+        passkeyId: string;
+        credential: unknown;
+        name: string;
+    }) => Promise<PasskeyRegistrationResult>;
+    /** The passkey half of `signIn`: a challenge to answer with `@wtfalch/auth/passkey`'s `getPasskey`. */
+    startPasskeySignIn: (input: {
+        authRequestId: string;
+        email: string;
+    }) => Promise<PasskeySignInStart>;
+    /** For a server action: redirects into the app on success, returns the error otherwise -- the passkey half of `signIn`. */
+    finishPasskeySignIn: (input: {
+        authRequestId: string;
+        sessionId: string;
+        credential: unknown;
+    }) => Promise<{
+        error: SignInError;
+    }>;
+    /**
+     * Starts a QR sign-in from a server action or route handler, setting the
+     * transaction cookie. In namespace mode, throws `AuthError('unavailable', ...)`
+     * when the binding is not active -- unlike `proxy`/`gate`, which answer a
+     * 503 for the same case rather than throwing.
+     */
+    startQrSignIn: () => Promise<QrSignIn>;
+    /**
+     * Polls the transaction `startQrSignIn` began, reading and setting cookies
+     * through `next/headers`. Never throws for an outcome of the poll itself --
+     * see `Auth['pollQrSignIn']`. `reason` is set only when `status` is `'failed'`.
+     */
+    pollQrSignIn: () => Promise<{
+        status: QrPollStatus;
+        reason?: string;
+    }>;
 }
 export declare function nextAuth(options: AuthOptions): NextAuth;
-export type { Auth, AuthOptions, AuthRequest, GateRules, Intent, NewUser, User };
+export type { Auth, AuthOptions, AuthRequest, GateRules, Intent, NewUser, PasskeyRegistrationResult, PasskeyRegistrationStart, PasskeySignInStart, QrPollStatus, User, };

package/dist/next.js

@@ -119,6 +119,29 @@ export function nextAuth(options) {
         const url = new URL(location);
         redirect(`${url.pathname}${url.search}`);
     };
+    // The passkey routes take a `Request`; a server action has none of its
+    // own, only what `cookies()` already exposes for this request. Only the
+    // cookie header matters to `read`, so a synthetic request carrying just
+    // that is exactly as good as the real one.
+    const requestFromCookies = async () => {
+        const store = await cookies();
+        const header = store
+            .getAll()
+            .map((c) => `${c.name}=${c.value}`)
+            .join('; ');
+        return new Request('http://localhost/', header ? { headers: { cookie: header } } : undefined);
+    };
+    const startPasskeyRegistration = async () => auth.startPasskeyRegistration(await requestFromCookies());
+    const finishPasskeyRegistration = async (input) => auth.finishPasskeyRegistration(await requestFromCookies(), input);
+    const finishPasskeySignIn = async (input) => {
+        const result = await auth.finishPasskeySignIn(input);
+        if (result.ok) {
+            if (result.hosted)
+                redirect(result.redirectTo);
+            return finish(result.redirectTo);
+        }
+        return { error: result.error };
+    };
     const resetPassword = async (input) => {
         const result = await auth.resetPassword(input);
         if (!result.ok)
@@ -153,6 +176,28 @@ export function nextAuth(options) {
         }
         return { error: result.error, message: result.message };
     };
+    const startQrSignIn = async () => {
+        const { cookies: set, ...start } = await auth.startQrSignIn();
+        const store = await cookies();
+        for (const c of set) {
+            if (c.value)
+                store.set(c.name, c.value, c.attributes);
+            else
+                store.delete({ name: c.name, path: '/' });
+        }
+        return start;
+    };
+    const pollQrSignIn = async () => {
+        const { status, reason, cookies: set } = await auth.pollQrSignIn(await requestFromCookies());
+        const store = await cookies();
+        for (const c of set) {
+            if (c.value)
+                store.set(c.name, c.value, c.attributes);
+            else
+                store.delete({ name: c.name, path: '/' });
+        }
+        return reason ? { status, reason } : { status };
+    };
     return {
         auth,
         handlers: { GET: auth.handle, POST: auth.handle },
@@ -169,5 +214,11 @@ export function nextAuth(options) {
         people: auth.people,
         setPersonActive: auth.setPersonActive,
         resetPassword,
+        startPasskeyRegistration,
+        finishPasskeyRegistration,
+        startPasskeySignIn: auth.startPasskeySignIn,
+        finishPasskeySignIn,
+        startQrSignIn,
+        pollQrSignIn,
     };
 }

package/dist/oidc.d.ts

@@ -1,6 +1,8 @@
 import * as jose from 'jose';
 import type { ResolvedOptions } from './config.js';
 export declare const ORG_CLAIM = "urn:zitadel:iam:user:resourceowner:id";
+/** The scopes every flow asks for: the code-exchange authorization request and the QR device grant alike. */
+export declare function scopeFor(organizationId: string): string;
 export interface Tokens {
     idToken: string;
     refreshToken?: string;
@@ -28,7 +30,9 @@ export declare class Oidc {
     verify(idToken: string): Promise<jose.JWTPayload>;
     private assertOrganization;
 }
-export type AuthErrorReason = 'expired' | 'state' | 'denied' | 'exchange' | 'organization' | 'cookie' | 'request' | 'account_changed' | 'unavailable';
+export type AuthErrorReason = 'expired' | 'state' | 'denied' | 'exchange' | 'organization' | 'cookie' | 'request' | 'account_changed' | 'unavailable'
+/** No session at all -- distinct from `account_changed`/`unavailable`, which `requireUser` already covers by redirecting instead. */
+ | 'unauthenticated';
 export declare class AuthError extends Error {
     readonly reason: AuthErrorReason;
     constructor(reason: AuthErrorReason, message: string);

package/dist/oidc.js

@@ -1,6 +1,17 @@
 import * as jose from 'jose';
 import * as client from 'openid-client';
 export const ORG_CLAIM = 'urn:zitadel:iam:user:resourceowner:id';
+/** The scopes every flow asks for: the code-exchange authorization request and the QR device grant alike. */
+export function scopeFor(organizationId) {
+    return [
+        'openid',
+        'email',
+        'profile',
+        'offline_access',
+        `urn:zitadel:iam:org:id:${organizationId}`,
+        'urn:zitadel:iam:user:resourceowner',
+    ].join(' ');
+}
 export class Oidc {
     options;
     configuration = null;
@@ -46,14 +57,7 @@ export class Oidc {
         return client.buildAuthorizationUrl(await this.config(), {
             ...(create ? { prompt: 'create' } : {}),
             redirect_uri: this.redirectUri.href,
-            scope: [
-                'openid',
-                'email',
-                'profile',
-                'offline_access',
-                `urn:zitadel:iam:org:id:${this.options.organizationId}`,
-                'urn:zitadel:iam:user:resourceowner',
-            ].join(' '),
+            scope: scopeFor(this.options.organizationId),
             state,
             nonce,
             code_challenge: await client.calculatePKCECodeChallenge(codeVerifier),

package/dist/passkey-browser.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The WebAuthn ceremony, for an app's own sign-in page: `createPasskey`
+ * answers `auth.startPasskeyRegistration`'s options, `getPasskey` answers
+ * `auth.startPasskeySignIn`'s. Both take the options JSON exactly as the
+ * broker hands it back -- ZITADEL's own `publicKeyCredentialCreationOptions`
+ * / `publicKeyCredentialRequestOptions`, base64url strings where the
+ * WebAuthn spec wants `ArrayBuffer`s and a `publicKey` wrapper around the
+ * rest -- and return a plain JSON-serialisable credential ready for
+ * `auth.finishPasskeyRegistration` / `auth.finishPasskeySignIn`.
+ *
+ * This is a browser file: no server import, nothing that would drag OIDC or
+ * cookie code into the client bundle. The base64url<->`ArrayBuffer`
+ * conversion and the credential's field names are copied from the vendored
+ * login app's own client components (`register-passkey.tsx`,
+ * `login-passkey.tsx`, `helpers/base64.ts`) -- ZITADEL is the judge of what
+ * it accepts, not the WebAuthn spec's own `toJSON`, and that app is what
+ * ZITADEL already accepts. Not a byte-for-byte port, though: a `null`
+ * `userHandle` (a non-discoverable credential need not carry one) is sent as
+ * `''` here (see `getPasskey` below), the same answer the login app's own
+ * `new Uint8Array(...)` pre-wrap already produces for the same input --
+ * `new Uint8Array(null)` is a zero-length view, not a throw -- but is not
+ * the byte a naive re-encoding of a `null` would produce.
+ */
+/** A record whose own shape nobody but the issuer needs to know; only the few fields below get touched. */
+type Loose = Record<string, unknown>;
+/** ZITADEL's `publicKeyCredentialCreationOptions`, wrapped in `publicKey` as the WebAuthn `CredentialCreationOptions` dictionary is. */
+export interface PasskeyCreationOptions {
+    publicKey: Loose & {
+        challenge: unknown;
+        user: Loose & {
+            id: unknown;
+        };
+        excludeCredentials?: Array<Loose & {
+            id: unknown;
+        }>;
+    };
+}
+/** ZITADEL's `publicKeyCredentialRequestOptions`, wrapped in `publicKey` as `CredentialRequestOptions` is. */
+export interface PasskeyRequestOptions {
+    publicKey: Loose & {
+        challenge: unknown;
+        allowCredentials?: Array<Loose & {
+            id: unknown;
+        }>;
+    };
+}
+/** What `verifyPasskeyRegistration` (ZITADEL, via the broker's `/passkey/register/finish`) accepts as `publicKeyCredential`. */
+export interface PasskeyCreationCredential {
+    id: string;
+    rawId: string;
+    type: string;
+    response: {
+        attestationObject: string;
+        clientDataJSON: string;
+    };
+}
+/** What `checkPasskey` (ZITADEL, via the broker's `/passkey/finish`) accepts as `credentialAssertionData`. */
+export interface PasskeyAssertionCredential {
+    id: string;
+    rawId: string;
+    type: string;
+    response: {
+        authenticatorData: string;
+        clientDataJSON: string;
+        signature: string;
+        userHandle: string;
+    };
+}
+/**
+ * Registers a passkey: decodes `options` (from `auth.startPasskeyRegistration`)
+ * into the `CredentialCreationOptions` the browser wants, calls
+ * `navigator.credentials.create`, and re-encodes the result for
+ * `auth.finishPasskeyRegistration`.
+ */
+export declare function createPasskey(options: PasskeyCreationOptions): Promise<PasskeyCreationCredential>;
+/**
+ * Signs in with a passkey: decodes `options` (from `auth.startPasskeySignIn`)
+ * into the `CredentialRequestOptions` the browser wants, calls
+ * `navigator.credentials.get`, and re-encodes the result for
+ * `auth.finishPasskeySignIn`.
+ */
+export declare function getPasskey(options: PasskeyRequestOptions): Promise<PasskeyAssertionCredential>;
+export {};

package/dist/passkey-browser.js

@@ -0,0 +1,150 @@
+/**
+ * The WebAuthn ceremony, for an app's own sign-in page: `createPasskey`
+ * answers `auth.startPasskeyRegistration`'s options, `getPasskey` answers
+ * `auth.startPasskeySignIn`'s. Both take the options JSON exactly as the
+ * broker hands it back -- ZITADEL's own `publicKeyCredentialCreationOptions`
+ * / `publicKeyCredentialRequestOptions`, base64url strings where the
+ * WebAuthn spec wants `ArrayBuffer`s and a `publicKey` wrapper around the
+ * rest -- and return a plain JSON-serialisable credential ready for
+ * `auth.finishPasskeyRegistration` / `auth.finishPasskeySignIn`.
+ *
+ * This is a browser file: no server import, nothing that would drag OIDC or
+ * cookie code into the client bundle. The base64url<->`ArrayBuffer`
+ * conversion and the credential's field names are copied from the vendored
+ * login app's own client components (`register-passkey.tsx`,
+ * `login-passkey.tsx`, `helpers/base64.ts`) -- ZITADEL is the judge of what
+ * it accepts, not the WebAuthn spec's own `toJSON`, and that app is what
+ * ZITADEL already accepts. Not a byte-for-byte port, though: a `null`
+ * `userHandle` (a non-discoverable credential need not carry one) is sent as
+ * `''` here (see `getPasskey` below), the same answer the login app's own
+ * `new Uint8Array(...)` pre-wrap already produces for the same input --
+ * `new Uint8Array(null)` is a zero-length view, not a throw -- but is not
+ * the byte a naive re-encoding of a `null` would produce.
+ */
+/** Base64url string, or an already-decoded `Array`/`Uint8Array`/`ArrayBuffer`, to `ArrayBuffer`. Mirrors the login app's `coerceToArrayBuffer`. */
+function coerceToArrayBuffer(value, name) {
+    let thing = value;
+    if (typeof thing === 'string') {
+        const base64 = thing.replace(/-/g, '+').replace(/_/g, '/');
+        const binary = atob(base64);
+        const bytes = new Uint8Array(binary.length);
+        for (let i = 0; i < binary.length; i++)
+            bytes[i] = binary.charCodeAt(i);
+        thing = bytes;
+    }
+    if (Array.isArray(thing))
+        thing = new Uint8Array(thing);
+    if (thing instanceof Uint8Array)
+        thing = thing.buffer;
+    if (!(thing instanceof ArrayBuffer)) {
+        throw new TypeError(`@wtfalch/auth: could not coerce '${name}' to ArrayBuffer`);
+    }
+    return thing;
+}
+/** `ArrayBuffer`/`Uint8Array`/`Array` to a base64url string. Mirrors the login app's `coerceToBase64Url`. */
+function coerceToBase64Url(value, name) {
+    let thing = value;
+    if (Array.isArray(thing))
+        thing = Uint8Array.from(thing);
+    if (thing instanceof ArrayBuffer)
+        thing = new Uint8Array(thing);
+    if (thing instanceof Uint8Array) {
+        let str = '';
+        for (let i = 0; i < thing.byteLength; i++)
+            str += String.fromCharCode(thing[i]);
+        thing = btoa(str);
+    }
+    if (typeof thing !== 'string') {
+        throw new Error(`@wtfalch/auth: could not coerce '${name}' to string`);
+    }
+    return thing.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+/**
+ * Registers a passkey: decodes `options` (from `auth.startPasskeyRegistration`)
+ * into the `CredentialCreationOptions` the browser wants, calls
+ * `navigator.credentials.create`, and re-encodes the result for
+ * `auth.finishPasskeyRegistration`.
+ */
+export async function createPasskey(options) {
+    const source = options?.publicKey;
+    if (!source) {
+        throw new Error("@wtfalch/auth: passkey creation options have no 'publicKey'");
+    }
+    const publicKey = {
+        ...source,
+        challenge: coerceToArrayBuffer(source.challenge, 'challenge'),
+        user: { ...source.user, id: coerceToArrayBuffer(source.user.id, 'user.id') },
+        ...(Array.isArray(source.excludeCredentials)
+            ? {
+                excludeCredentials: source.excludeCredentials.map((cred) => ({
+                    ...cred,
+                    id: coerceToArrayBuffer(cred.id, 'excludeCredentials.id'),
+                })),
+            }
+            : {}),
+    };
+    const credential = (await navigator.credentials.create({
+        publicKey,
+    }));
+    if (!credential)
+        throw new Error('@wtfalch/auth: the browser returned no credential');
+    const response = credential.response;
+    return {
+        id: credential.id,
+        rawId: coerceToBase64Url(credential.rawId, 'rawId'),
+        type: credential.type,
+        response: {
+            attestationObject: coerceToBase64Url(response.attestationObject, 'attestationObject'),
+            clientDataJSON: coerceToBase64Url(response.clientDataJSON, 'clientDataJSON'),
+        },
+    };
+}
+/**
+ * Signs in with a passkey: decodes `options` (from `auth.startPasskeySignIn`)
+ * into the `CredentialRequestOptions` the browser wants, calls
+ * `navigator.credentials.get`, and re-encodes the result for
+ * `auth.finishPasskeySignIn`.
+ */
+export async function getPasskey(options) {
+    const source = options?.publicKey;
+    if (!source) {
+        throw new Error("@wtfalch/auth: passkey request options have no 'publicKey'");
+    }
+    const publicKey = {
+        ...source,
+        challenge: coerceToArrayBuffer(source.challenge, 'challenge'),
+        ...(Array.isArray(source.allowCredentials)
+            ? {
+                allowCredentials: source.allowCredentials.map((cred) => ({
+                    ...cred,
+                    id: coerceToArrayBuffer(cred.id, 'allowCredentials.id'),
+                })),
+            }
+            : {}),
+    };
+    const credential = (await navigator.credentials.get({
+        publicKey,
+    }));
+    if (!credential)
+        throw new Error('@wtfalch/auth: the browser returned no credential');
+    const response = credential.response;
+    // `new Uint8Array(x)` first, exactly as the login app does: a `null`
+    // `userHandle` (a non-discoverable credential need not carry one) becomes
+    // a zero-length view rather than a value `coerceToBase64Url` would refuse.
+    const authenticatorData = new Uint8Array(response.authenticatorData);
+    const clientDataJSON = new Uint8Array(response.clientDataJSON);
+    const rawId = new Uint8Array(credential.rawId);
+    const signature = new Uint8Array(response.signature);
+    const userHandle = new Uint8Array(response.userHandle ?? new ArrayBuffer(0));
+    return {
+        id: credential.id,
+        rawId: coerceToBase64Url(rawId, 'rawId'),
+        type: credential.type,
+        response: {
+            authenticatorData: coerceToBase64Url(authenticatorData, 'authenticatorData'),
+            clientDataJSON: coerceToBase64Url(clientDataJSON, 'clientDataJSON'),
+            signature: coerceToBase64Url(signature, 'signature'),
+            userHandle: coerceToBase64Url(userHandle, 'userHandle'),
+        },
+    };
+}

package/dist/qr.d.ts

@@ -0,0 +1,23 @@
+import type { ResolvedOptions } from './config.js';
+import { type Oidc, type Tokens } from './oidc.js';
+export interface DeviceAuthorization {
+    deviceCode: string;
+    userCode: string;
+    verificationUriComplete: string;
+    expiresIn: number;
+    interval: number;
+}
+export declare function requestDeviceAuthorization(options: ResolvedOptions, scope: string): Promise<DeviceAuthorization>;
+export type DevicePoll = {
+    status: 'pending';
+} | {
+    status: 'slow_down';
+} | {
+    status: 'expired';
+} | {
+    status: 'denied';
+} | {
+    status: 'signed_in';
+    tokens: Tokens;
+};
+export declare function pollDeviceToken(options: ResolvedOptions, oidc: Oidc, deviceCode: string): Promise<DevicePoll>;

package/dist/qr.js

@@ -0,0 +1,75 @@
+import { AuthError } from './oidc.js';
+/**
+ * The OAuth device authorization grant (RFC 8628), for signing in a new
+ * device from a QR code a phone that is already signed in approves. Raw
+ * `fetch` against the issuer's own endpoints -- the same convention
+ * `browser.ts` and `namespace-browser.ts` use for their token calls -- rather
+ * than `openid-client`'s device-grant helpers, which poll synchronously and
+ * do not fit a request served once per browser poll.
+ */
+const DEVICE_GRANT_TYPE = 'urn:ietf:params:oauth:grant-type:device_code';
+export async function requestDeviceAuthorization(options, scope) {
+    const response = await options.fetch(`${options.issuer}/oauth/v2/device_authorization`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({ client_id: options.clientId, scope }),
+    });
+    if (!response.ok) {
+        throw new AuthError('request', `the issuer refused the device authorization request (${response.status})`);
+    }
+    const body = (await response.json().catch(() => null));
+    const deviceCode = str(body?.device_code);
+    const userCode = str(body?.user_code);
+    const verificationUriComplete = str(body?.verification_uri_complete);
+    const expiresIn = num(body?.expires_in);
+    if (!deviceCode || !userCode || !verificationUriComplete || expiresIn === null) {
+        throw new AuthError('request', 'the issuer returned an incomplete device authorization');
+    }
+    return {
+        deviceCode,
+        userCode,
+        verificationUriComplete,
+        expiresIn,
+        interval: num(body?.interval) ?? 5,
+    };
+}
+export async function pollDeviceToken(options, oidc, deviceCode) {
+    const response = await options.fetch(`${options.issuer}/oauth/v2/token`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({
+            grant_type: DEVICE_GRANT_TYPE,
+            device_code: deviceCode,
+            client_id: options.clientId,
+        }),
+    });
+    const body = (await response.json().catch(() => null));
+    if (!response.ok) {
+        const error = str(body?.error);
+        if (error === 'authorization_pending')
+            return { status: 'pending' };
+        if (error === 'slow_down')
+            return { status: 'slow_down' };
+        if (error === 'expired_token')
+            return { status: 'expired' };
+        if (error === 'access_denied')
+            return { status: 'denied' };
+        throw new AuthError('exchange', str(body?.error_description) ?? error ?? 'device token request failed');
+    }
+    const idToken = str(body?.id_token);
+    if (!idToken)
+        throw new AuthError('exchange', 'the issuer returned no id token');
+    // Signature, issuer, audience, expiry and the organisation claim -- exactly
+    // the code-exchange path's checks, minus the nonce a device grant has none of.
+    const claims = await oidc.verify(idToken);
+    return {
+        status: 'signed_in',
+        tokens: { idToken, refreshToken: str(body?.refresh_token) ?? undefined, claims },
+    };
+}
+function str(value) {
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+function num(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/auth",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Sign in against auth.wtfalch.dev: a server session for a Next.js app, and a browser client with silent single sign-on across subdomains.",
   "repository": {
     "type": "git",
@@ -22,6 +22,10 @@
       "types": "./dist/browser.d.ts",
       "default": "./dist/browser.js"
     },
+    "./passkey": {
+      "types": "./dist/passkey-browser.d.ts",
+      "default": "./dist/passkey-browser.js"
+    },
     "./namespaces": {
       "types": "./dist/namespaces.d.ts",
       "default": "./dist/namespaces.js"