@wtfalch/auth 0.1.0

package/dist/auth.d.ts

@@ -0,0 +1,136 @@
+import { type JWTPayload } from 'jose';
+import { type AuthRequest, type NewUser } from './broker.js';
+import { type AuthOptions } from './config.js';
+import { type SetCookie } from './cookies.js';
+export interface User {
+    id: string;
+    email: string | null;
+    emailVerified: boolean;
+    name: string | null;
+    givenName: string | null;
+    familyName: string | null;
+    preferredUsername: string | null;
+    organizationId: string;
+    claims: JWTPayload;
+}
+export interface ReadResult {
+    user: User | null;
+    /** What the response must set. Empty unless the session was refreshed or ended. */
+    cookies: SetCookie[];
+}
+export interface GateRules {
+    /** Paths that need no session. `/docs/*` covers `/docs` and everything under it. The SDK's own routes are always public. */
+    public?: string[] | ((pathname: string) => boolean);
+}
+export type Gate = {
+    kind: 'next';
+    user: User | null;
+    cookies: SetCookie[];
+} | {
+    kind: 'redirect';
+    location: string;
+    cookies: SetCookie[];
+}
+/** A fetch, prefetch or action without a session: 401, never a redirect into the sign-in route. */
+ | {
+    kind: 'deny';
+    cookies: SetCookie[];
+};
+export type Intent = 'login' | 'register';
+export type SignInError = 'invalid_credentials' | 'request' | 'unavailable';
+export type ResetError = 'invalid_code' | 'invalid_password' | 'unavailable';
+export type SignUpError = 'email_taken' | 'invalid' | 'request' | 'unavailable';
+export type SignInResult = {
+    ok: true;
+    redirectTo: string;
+} | {
+    ok: false;
+    error: SignInError;
+};
+export type SignUpResult = {
+    ok: true;
+    redirectTo: string;
+} | {
+    ok: false;
+    error: SignUpError;
+    message: string;
+};
+export interface Completed {
+    location: string;
+    cookies: SetCookie[];
+}
+/** A person signed in from a link rather than from a flow the browser started. */
+export type SignedIn = {
+    ok: true;
+    location: string;
+    cookies: SetCookie[];
+} | {
+    ok: false;
+    error: ResetError;
+    message: string;
+};
+export interface Auth {
+    readonly sessionCookieName: string;
+    /** GET {basePath}/start?next=&intent= : begins the OIDC flow; the issuer sends the browser to {basePath}/login?authRequest= */
+    start(request: Request): Promise<Response>;
+    /** GET {basePath}/callback */
+    callback(request: Request): Promise<Response>;
+    /** The callback as data, for a server action that finishes the sign-in itself and sets the cookies. */
+    complete(callbackUrl: string, cookieHeader: string | null): Promise<Completed>;
+    /** POST {basePath}/logout */
+    logout(request: Request): Promise<Response>;
+    /** GET {basePath}/verify?userId=&code= */
+    verify(request: Request): Promise<Response>;
+    /** GET {basePath}/link?sessionId=&code= : the sign-in link from an email, on any device. */
+    link(request: Request): Promise<Response>;
+    /** Emails a fresh verification link. Says nothing about whether the address exists. */
+    resendVerification(email: string, next?: string): Promise<void>;
+    /** Emails a password-reset link to {basePath}/reset?userId=&code=. Says nothing about whether the address exists. */
+    requestPasswordReset(email: string, next?: string): Promise<void>;
+    /** Sets the password from a reset link and signs the person in. */
+    resetPassword(input: {
+        userId: string;
+        code: string;
+        password: string;
+        next?: string;
+    }): Promise<SignedIn>;
+    /** Emails a sign-in link. Needs a verified address. Says nothing about whether the address exists. */
+    sendLink(email: string, next?: string): Promise<void>;
+    /**
+     * Brings a person into this app's organisation and mails them a link to
+     * choose a password. Unlike everything else here it says whether the
+     * address was already known, because the caller is an operator who asked
+     * for it rather than a stranger at a form.
+     */
+    invite(input: {
+        email: string;
+        givenName: string;
+        familyName: string;
+        next?: string;
+    }): Promise<{
+        userId: string;
+        invited: boolean;
+    }>;
+    handle(request: Request): Promise<Response>;
+    /** `refresh: false` for callers that cannot set cookies; they get a user only while the token is valid. */
+    read(request: Request, opts?: {
+        refresh?: boolean;
+    }): Promise<ReadResult>;
+    readCookie(value: string | undefined, opts?: {
+        refresh?: boolean;
+    }): Promise<ReadResult>;
+    gate(request: Request, rules?: GateRules): Promise<Gate>;
+    startUrl(next?: string | null, intent?: Intent): string;
+    /** The auth request the issuer sent the browser here with. Refuses one for another application. */
+    authRequest(id: string): Promise<AuthRequest>;
+    signIn(input: {
+        authRequestId: string;
+        email: string;
+        password: string;
+    }): Promise<SignInResult>;
+    signUp(input: {
+        authRequestId: string;
+    } & NewUser): Promise<SignUpResult>;
+}
+export declare function createAuth(input: AuthOptions): Auth;
+export type { AuthRequest, NewUser, SetCookie };

package/dist/auth.js

@@ -0,0 +1,403 @@
+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 { AuthError, ORG_CLAIM, Oidc } from './oidc.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.
+    let resolved = null;
+    const options = () => {
+        resolved ??= resolveOptions(input);
+        return resolved;
+    };
+    let oidcInstance = null;
+    const oidc = () => {
+        oidcInstance ??= new Oidc(options());
+        return oidcInstance;
+    };
+    let brokerInstance = null;
+    const broker = () => {
+        brokerInstance ??= new Broker(options());
+        return brokerInstance;
+    };
+    const startUrl = (next, intent = 'login') => {
+        const url = new URL(`${options().basePath}/start`, options().appUrl);
+        const path = safeNextPath(next, '');
+        if (path)
+            url.searchParams.set('next', path);
+        if (intent === 'register')
+            url.searchParams.set('intent', 'register');
+        return url.href;
+    };
+    const start = async (request) => {
+        if (!isNavigation(request))
+            return new Response('Unauthorized', { status: 401 });
+        const params = new URL(request.url).searchParams;
+        const next = safeNextPath(params.get('next'), options().afterLogin);
+        const state = client.randomState();
+        const nonce = client.randomNonce();
+        const codeVerifier = client.randomPKCECodeVerifier();
+        const target = await oidc().authorizationUrl(state, nonce, codeVerifier, {
+            create: params.get('intent') === 'register',
+        });
+        const transaction = await sealTransaction(options(), {
+            st: state,
+            nc: nonce,
+            cv: codeVerifier,
+            nx: next,
+        });
+        return redirect(target.href, [transaction]);
+    };
+    const complete = async (callbackUrl, cookieHeader) => {
+        const cleared = clearTransaction(options());
+        const transaction = await openTransaction(options(), cookieFrom(cookieHeader, transactionCookieName(options())));
+        if (!transaction)
+            return failure('expired', [cleared]);
+        const params = new URL(callbackUrl).searchParams;
+        if (params.get('state') !== transaction.st)
+            return failure('state', [cleared]);
+        let session;
+        try {
+            const tokens = await oidc().exchange(params, {
+                state: transaction.st,
+                nonce: transaction.nc,
+                codeVerifier: transaction.cv,
+            });
+            session = await sealSession(options(), { idt: tokens.idToken, rt: tokens.refreshToken });
+        }
+        catch (error) {
+            return failure(reasonOf(error), [cleared]);
+        }
+        return {
+            location: new URL(transaction.nx, options().appUrl).href,
+            cookies: [cleared, session],
+        };
+    };
+    const callback = async (request) => {
+        const { location, cookies } = await complete(request.url, request.headers.get('cookie'));
+        return redirect(location, cookies);
+    };
+    const logout = async (request) => {
+        if (!isSameOrigin(request, options().appUrl.origin)) {
+            return new Response('Forbidden', { status: 403 });
+        }
+        const session = await openSession(options(), cookieFrom(request.headers.get('cookie'), sessionCookieName(options())));
+        if (session?.rt)
+            await broker()
+                .revoke(session.rt)
+                .catch(() => { });
+        return redirect(new URL(options().afterLogout, options().appUrl).href, [clearSession(options())], 303);
+    };
+    const verify = async (request) => {
+        const params = new URL(request.url).searchParams;
+        const userId = params.get('userId');
+        const code = params.get('code');
+        const url = new URL(safeNextPath(params.get('next'), options().afterVerify), options().appUrl);
+        if (!userId || !code)
+            return failed('verify', []);
+        try {
+            await broker().verifyEmail(userId, code);
+        }
+        catch {
+            return failed('verify', []);
+        }
+        // The id token in the cookie still says unverified; the claim is what the
+        // app reads, so it is refreshed here rather than at the next expiry.
+        const cookies = [];
+        const session = await openSession(options(), cookieFrom(request.headers.get('cookie'), sessionCookieName(options())));
+        if (session?.rt) {
+            try {
+                const tokens = await oidc().refresh(session.rt);
+                cookies.push(await sealSession(options(), { idt: tokens.idToken, rt: tokens.refreshToken }));
+            }
+            catch { }
+        }
+        url.searchParams.set('verified', '1');
+        return redirect(url.href, cookies);
+    };
+    const handle = async (request) => {
+        const { pathname } = new URL(request.url);
+        const route = pathname.startsWith(`${options().basePath}/`)
+            ? pathname.slice(options().basePath.length + 1)
+            : null;
+        if (route === 'start' && request.method === 'GET')
+            return start(request);
+        if (route === 'callback' && request.method === 'GET')
+            return callback(request);
+        if (route === 'verify' && request.method === 'GET')
+            return verify(request);
+        if (route === 'link' && request.method === 'GET')
+            return link(request);
+        if (route === 'logout' && request.method === 'POST')
+            return logout(request);
+        return new Response('Not found', { status: 404 });
+    };
+    const readCookie = async (value, { refresh = true } = {}) => {
+        const session = await openSession(options(), value);
+        if (!session)
+            return { user: null, cookies: [] };
+        const now = Math.floor(Date.now() / 1000);
+        const exp = expiryOf(session.idt);
+        const valid = exp !== null && exp > now - 60;
+        const due = exp === null || exp - options().refreshWindow <= now;
+        if (due && refresh && session.rt) {
+            try {
+                const tokens = await oidc().refresh(session.rt);
+                const cookie = await sealSession(options(), {
+                    idt: tokens.idToken,
+                    rt: tokens.refreshToken,
+                });
+                return { user: userFrom(tokens.claims), cookies: [cookie] };
+            }
+            catch (error) {
+                // A failed refresh never clears the cookie: a valid token carries on, and a dead one is replaced by the next sign-in.
+                if (error instanceof AuthError)
+                    return { user: null, cookies: [clearSession(options())] };
+                if (!valid)
+                    return { user: null, cookies: [] };
+            }
+        }
+        try {
+            const claims = await oidc().verify(session.idt);
+            return { user: userFrom(claims), cookies: [] };
+        }
+        catch (error) {
+            return { user: null, cookies: refresh && rejected(error) ? [clearSession(options())] : [] };
+        }
+    };
+    const read = (request, opts) => readCookie(cookieFrom(request.headers.get('cookie'), sessionCookieName(options())), opts);
+    const gate = async (request, rules = {}) => {
+        const url = new URL(request.url);
+        const isPublic = url.pathname === options().basePath ||
+            url.pathname.startsWith(`${options().basePath}/`) ||
+            matches(rules.public, url.pathname);
+        const { user, cookies } = await read(request);
+        if (user || isPublic)
+            return { kind: 'next', user, cookies };
+        if (!isNavigation(request))
+            return { kind: 'deny', cookies };
+        return { kind: 'redirect', location: startUrl(`${url.pathname}${url.search}`), cookies };
+    };
+    const authRequest = (id) => broker().authRequest(id);
+    /**
+     * An OIDC flow this app starts and finishes itself, for a person arriving
+     * from an email rather than from a browser the app sent to the issuer.
+     */
+    const serverFlow = async () => {
+        const state = client.randomState();
+        const nonce = client.randomNonce();
+        const verifier = client.randomPKCECodeVerifier();
+        const target = await oidc().authorizationUrl(state, nonce, verifier);
+        const response = await options().fetch(target.href, { redirect: 'manual' });
+        const location = response.headers.get('location');
+        const id = location && new URL(location, options().issuer).searchParams.get('authRequest');
+        if (!id)
+            throw new AuthError('request', 'the issuer did not start an auth request');
+        return { id, state, nonce, verifier };
+    };
+    /** Exchanges a callback the service issued, and seals the cookie. */
+    const finish = async (callbackUrl, flow, next) => {
+        const tokens = await oidc().exchange(new URL(callbackUrl).searchParams, {
+            state: flow.state,
+            nonce: flow.nonce,
+            codeVerifier: flow.verifier,
+        });
+        const cookie = await sealSession(options(), { idt: tokens.idToken, rt: tokens.refreshToken });
+        return { location: new URL(next, options().appUrl).href, cookies: [cookie] };
+    };
+    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, '')));
+    const invite = (input) => broker().invite({ ...input, next: safeNextPath(input.next, '') });
+    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 };
+        }
+        catch (error) {
+            if (error instanceof BrokerError && error.error === 'invalid_password') {
+                return { ok: false, error: 'invalid_password', message: error.detail ?? error.error };
+            }
+            if (error instanceof BrokerError && error.status < 500) {
+                return { ok: false, error: 'invalid_code', message: error.detail ?? error.error };
+            }
+            return { ok: false, error: 'unavailable', message: 'the sign-in service did not answer' };
+        }
+    };
+    const link = async (request) => {
+        const params = new URL(request.url).searchParams;
+        const sessionId = params.get('sessionId');
+        const code = params.get('code');
+        if (!sessionId || !code)
+            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));
+            return redirect(location, cookies);
+        }
+        catch {
+            return failed('link', []);
+        }
+    };
+    const signIn = async ({ authRequestId, email, password, }) => {
+        try {
+            return { ok: true, redirectTo: await broker().signIn({ authRequestId, email, password }) };
+        }
+        catch (error) {
+            return { ok: false, error: signInError(error) };
+        }
+    };
+    const signUp = async ({ authRequestId, ...user }) => {
+        try {
+            return { ok: true, redirectTo: await broker().signUp({ authRequestId, ...user }) };
+        }
+        catch (error) {
+            if (error instanceof BrokerError && error.error === 'email_taken') {
+                return { ok: false, error: 'email_taken', message: error.detail ?? error.error };
+            }
+            if (error instanceof BrokerError && error.error === 'request') {
+                return { ok: false, error: 'request', message: error.detail ?? error.error };
+            }
+            if (error instanceof BrokerError && error.status < 500) {
+                return { ok: false, error: 'invalid', message: error.detail ?? error.error };
+            }
+            return { ok: false, error: 'unavailable', message: 'the sign-in service did not answer' };
+        }
+    };
+    const failure = (reason, cookies) => {
+        const url = new URL(options().onError, options().appUrl);
+        url.searchParams.set('auth_error', reason);
+        return { location: url.href, cookies };
+    };
+    const failed = (reason, cookies) => {
+        const { location } = failure(reason, []);
+        return redirect(location, cookies);
+    };
+    return {
+        get sessionCookieName() {
+            return sessionCookieName(options());
+        },
+        start,
+        callback,
+        complete,
+        logout,
+        verify,
+        link,
+        resendVerification,
+        requestPasswordReset,
+        resetPassword,
+        sendLink,
+        invite,
+        handle,
+        read,
+        readCookie,
+        gate,
+        startUrl,
+        authRequest,
+        signIn,
+        signUp,
+    };
+}
+function redirect(location, cookies, status = 302) {
+    const headers = new Headers({ Location: location });
+    for (const cookie of cookies)
+        headers.append('Set-Cookie', cookie.header);
+    return new Response(null, { status, headers });
+}
+function matches(rule, pathname) {
+    if (!rule)
+        return false;
+    if (typeof rule === 'function')
+        return rule(pathname);
+    return rule.some((entry) => {
+        if (entry.endsWith('/*')) {
+            const prefix = entry.slice(0, -2) || '/';
+            return pathname === prefix || pathname.startsWith(prefix === '/' ? '/' : `${prefix}/`);
+        }
+        return pathname === entry;
+    });
+}
+function expiryOf(idToken) {
+    try {
+        const [, payload] = idToken.split('.');
+        const json = JSON.parse(atob(payload.replace(/-/g, '+').replace(/_/g, '/')));
+        return typeof json.exp === 'number' ? json.exp : null;
+    }
+    catch {
+        return null;
+    }
+}
+function userFrom(claims) {
+    const str = (key) => typeof claims[key] === 'string' ? claims[key] : null;
+    return {
+        id: String(claims.sub),
+        email: str('email'),
+        emailVerified: claims.email_verified === true,
+        name: str('name'),
+        givenName: str('given_name'),
+        familyName: str('family_name'),
+        preferredUsername: str('preferred_username'),
+        organizationId: String(claims[ORG_CLAIM]),
+        claims,
+    };
+}
+// The token itself is bad, as opposed to the keys being unreachable or rotating.
+function rejected(error) {
+    return (error instanceof AuthError ||
+        error instanceof errors.JWTExpired ||
+        error instanceof errors.JWTClaimValidationFailed ||
+        error instanceof errors.JWSSignatureVerificationFailed ||
+        error instanceof errors.JWSInvalid ||
+        error instanceof errors.JWTInvalid ||
+        error instanceof errors.JOSEAlgNotAllowed);
+}
+function isNavigation(request) {
+    const mode = request.headers.get('sec-fetch-mode');
+    if (mode && mode !== 'navigate')
+        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 {
+        await act();
+    }
+    catch (error) {
+        if (error instanceof BrokerError && error.status < 500)
+            return;
+        throw error;
+    }
+}
+function signInError(error) {
+    if (error instanceof BrokerError && error.error === 'request')
+        return 'request';
+    // A key the service will not take is the app's problem, not the visitor's.
+    if (error instanceof BrokerError && error.error === 'unauthorized')
+        return 'unavailable';
+    if (error instanceof BrokerError && error.status < 500)
+        return 'invalid_credentials';
+    return 'unavailable';
+}
+function reasonOf(error) {
+    if (error instanceof AuthError)
+        return error.reason;
+    if (error instanceof client.AuthorizationResponseError)
+        return 'denied';
+    return 'exchange';
+}

package/dist/broker.d.ts

@@ -0,0 +1,63 @@
+import type { ResolvedOptions } from './config.js';
+export interface AuthRequest {
+    id: string;
+    intent: 'login' | 'register';
+    loginHint: string | null;
+}
+export interface NewUser {
+    email: string;
+    password: string;
+    givenName: string;
+    familyName: string;
+}
+export declare class BrokerError extends Error {
+    readonly status: number;
+    readonly error: string;
+    readonly detail?: string | undefined;
+    constructor(status: number, error: string, detail?: string | undefined);
+}
+/**
+ * The privileged half, over HTTP. The app holds a key that reaches its own
+ * organisation through these calls only; the token that can sign anyone in
+ * anywhere stays in the service.
+ */
+export declare class Broker {
+    private readonly options;
+    constructor(options: ResolvedOptions);
+    private call;
+    authRequest(id: string): Promise<AuthRequest>;
+    signIn(input: {
+        authRequestId: string;
+        email: string;
+        password: string;
+    }): Promise<string>;
+    signUp(input: {
+        authRequestId: string;
+    } & NewUser): Promise<string>;
+    followLink(input: {
+        authRequestId: string;
+        sessionId: string;
+        code: string;
+    }): Promise<string>;
+    completeReset(input: {
+        authRequestId: string;
+        userId: string;
+        code: string;
+        password: string;
+    }): Promise<string>;
+    invite(input: {
+        email: string;
+        givenName: string;
+        familyName: string;
+        next: string;
+    }): Promise<{
+        userId: string;
+        invited: boolean;
+    }>;
+    sendLink(email: string, next: string): Promise<unknown>;
+    sendReset(email: string, next: string): Promise<unknown>;
+    sendVerification(email: string, next: string): Promise<unknown>;
+    verifyEmail(userId: string, code: string): Promise<unknown>;
+    /** A public client revoking its own token: no key, no service. */
+    revoke(refreshToken: string): Promise<void>;
+}