@wtfalch/auth 0.1.0

package/dist/broker.js

@@ -0,0 +1,102 @@
+export class BrokerError extends Error {
+    status;
+    error;
+    detail;
+    constructor(status, error, detail) {
+        super(detail ?? error);
+        this.status = status;
+        this.error = error;
+        this.detail = detail;
+        this.name = 'BrokerError';
+    }
+}
+/**
+ * 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 class Broker {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async call(method, path, body) {
+        if (!this.options.appKey) {
+            throw new Error('@wtfalch/auth: appKey is required to sign people in on the app');
+        }
+        const url = new URL(`${this.options.brokerUrl}${path}`);
+        if (method === 'GET')
+            for (const [k, v] of Object.entries(body))
+                url.searchParams.set(k, String(v));
+        const response = await this.options.fetch(url.href, {
+            method,
+            headers: {
+                authorization: `Bearer ${this.options.appKey}`,
+                'content-type': 'application/json',
+            },
+            body: method === 'GET'
+                ? undefined
+                : JSON.stringify({ ...body, origin: this.options.appUrl.origin }),
+        });
+        const text = await response.text();
+        let data = {};
+        try {
+            data = text ? JSON.parse(text) : {};
+        }
+        catch {
+            throw new BrokerError(response.status, 'unavailable', `non-JSON response from ${path}`);
+        }
+        if (!response.ok) {
+            throw new BrokerError(response.status, String(data.error ?? 'unavailable'), data.message);
+        }
+        return data;
+    }
+    authRequest(id) {
+        return this.call('GET', '/auth-request', { id });
+    }
+    async signIn(input) {
+        const { callbackUrl } = await this.call('POST', '/sign-in', input);
+        return callbackUrl;
+    }
+    async signUp(input) {
+        const { callbackUrl } = await this.call('POST', '/sign-up', {
+            ...input,
+        });
+        return callbackUrl;
+    }
+    async followLink(input) {
+        const { callbackUrl } = await this.call('POST', '/link/follow', input);
+        return callbackUrl;
+    }
+    async completeReset(input) {
+        const { callbackUrl } = await this.call('POST', '/reset/complete', input);
+        return callbackUrl;
+    }
+    invite(input) {
+        return this.call('POST', '/invite', input);
+    }
+    sendLink(email, next) {
+        return this.call('POST', '/link/send', { email, next });
+    }
+    sendReset(email, next) {
+        return this.call('POST', '/reset/send', { email, next });
+    }
+    sendVerification(email, next) {
+        return this.call('POST', '/verification/send', { email, next });
+    }
+    verifyEmail(userId, code) {
+        return this.call('POST', '/verify', { userId, code });
+    }
+    /** A public client revoking its own token: no key, no service. */
+    async revoke(refreshToken) {
+        await this.options.fetch(`${this.options.issuer}/oauth/v2/revoke`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({
+                token: refreshToken,
+                token_type_hint: 'refresh_token',
+                client_id: this.options.clientId,
+            }),
+        });
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,51 @@
+export interface AuthOptions {
+    /** This app's origin, e.g. https://portal.valet.wtfalch.dev. Every URL the SDK builds starts here, never from the request's Host. */
+    appUrl: string | undefined;
+    /** From scripts/provisioned.json. */
+    clientId: string | undefined;
+    /** From scripts/provisioned.json. Sent as a scope and checked on every token. */
+    organizationId: string | undefined;
+    /** 32 bytes, base64 or hex: `openssl rand -base64 32`. One per app. */
+    cookieSecret: string | undefined;
+    /** Default https://auth.wtfalch.dev. */
+    issuer?: string;
+    /** Where the routes are mounted. Default /auth. */
+    basePath?: string;
+    /** Default /. */
+    afterLogin?: string;
+    /** Default /. Must be a registered post-logout URI. */
+    afterLogout?: string;
+    /** Where a failed callback lands, with ?auth_error=<reason>. Default /. */
+    onError?: string;
+    /** Where a verified email link lands. Default /. */
+    afterVerify?: string;
+    /** This app's key for the sign-in service (APP_KEY_<name>). Needed for anything that checks a credential. */
+    appKey?: string;
+    /** The sign-in service. Defaults to the issuer's /api. */
+    brokerUrl?: string;
+    /** Cookie lifetime in seconds, sliding. Default 30 days, the issuer's idle expiry for a refresh token. */
+    sessionMaxAge?: number;
+    /** Refresh when the id token has fewer seconds left than this. Default 300. */
+    refreshWindow?: number;
+    fetch?: typeof fetch;
+}
+export interface ResolvedOptions {
+    appUrl: URL;
+    clientId: string;
+    organizationId: string;
+    cookieKey: Uint8Array;
+    issuer: string;
+    basePath: string;
+    afterLogin: string;
+    afterLogout: string;
+    onError: string;
+    afterVerify: string;
+    appKey: string | null;
+    brokerUrl: string;
+    sessionMaxAge: number;
+    refreshWindow: number;
+    secure: boolean;
+    fetch: typeof fetch;
+}
+export declare const ISSUER = "https://auth.wtfalch.dev";
+export declare function resolveOptions(options: AuthOptions): ResolvedOptions;

package/dist/config.js

@@ -0,0 +1,71 @@
+export const ISSUER = 'https://auth.wtfalch.dev';
+export function resolveOptions(options) {
+    const appUrl = parseAppUrl(options.appUrl);
+    required(options.clientId, 'clientId');
+    required(options.organizationId, 'organizationId');
+    const basePath = options.basePath ?? '/auth';
+    if (!basePath.startsWith('/') || basePath.endsWith('/')) {
+        throw new Error(`@wtfalch/auth: basePath must start with "/" and not end with one, got "${basePath}"`);
+    }
+    return {
+        appUrl,
+        clientId: options.clientId,
+        organizationId: options.organizationId,
+        cookieKey: decodeKey(options.cookieSecret),
+        issuer: (options.issuer ?? ISSUER).replace(/\/$/, ''),
+        basePath,
+        afterLogin: options.afterLogin ?? '/',
+        afterLogout: options.afterLogout ?? '/',
+        onError: options.onError ?? '/',
+        afterVerify: options.afterVerify ?? '/',
+        appKey: options.appKey || null,
+        brokerUrl: (options.brokerUrl ?? `${(options.issuer ?? ISSUER).replace(/\/$/, '')}/api`).replace(/\/$/, ''),
+        sessionMaxAge: seconds(options.sessionMaxAge, 'sessionMaxAge', 30 * 24 * 60 * 60),
+        refreshWindow: seconds(options.refreshWindow, 'refreshWindow', 5 * 60),
+        secure: appUrl.protocol === 'https:',
+        fetch: options.fetch ?? globalThis.fetch,
+    };
+}
+function required(value, name) {
+    if (!value)
+        throw new Error(`@wtfalch/auth: ${name} is required`);
+}
+function seconds(value, name, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new Error(`@wtfalch/auth: ${name} must be a positive number of seconds, got ${value}`);
+    }
+    return value;
+}
+function parseAppUrl(raw) {
+    required(raw, 'appUrl');
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error(`@wtfalch/auth: appUrl must be an absolute URL, got "${raw}"`);
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+        throw new Error(`@wtfalch/auth: appUrl must be http(s), got "${raw}"`);
+    }
+    if (url.pathname !== '/' || url.search || url.hash) {
+        throw new Error(`@wtfalch/auth: appUrl is an origin, not a page: "${raw}"`);
+    }
+    return url;
+}
+function decodeKey(secret) {
+    required(secret, 'cookieSecret');
+    let bytes = new Uint8Array(0);
+    try {
+        bytes = /^[0-9a-f]{64}$/i.test(secret)
+            ? Uint8Array.from(secret.match(/../g) ?? [], (pair) => Number.parseInt(pair, 16))
+            : Uint8Array.from(atob(secret.replace(/-/g, '+').replace(/_/g, '/')), (c) => c.charCodeAt(0));
+    }
+    catch { }
+    if (bytes.length !== 32) {
+        throw new Error(`@wtfalch/auth: cookieSecret must decode to 32 bytes (openssl rand -base64 32), got ${bytes.length}`);
+    }
+    return bytes;
+}

package/dist/cookies.d.ts

@@ -0,0 +1,45 @@
+import { type JWTPayload } from 'jose';
+import type { ResolvedOptions } from './config.js';
+export interface SessionPayload extends JWTPayload {
+    idt: string;
+    rt?: string;
+}
+export interface TransactionPayload extends JWTPayload {
+    st: string;
+    nc: string;
+    cv: string;
+    nx: string;
+}
+export interface CookieAttributes {
+    path: '/';
+    httpOnly: true;
+    sameSite: 'lax';
+    secure: boolean;
+    maxAge: number;
+}
+export interface LinkPayload extends JWTPayload {
+    sid: string;
+    stk: string;
+    ar: string;
+}
+export interface SetCookie {
+    name: string;
+    value: string;
+    header: string;
+    attributes: CookieAttributes;
+}
+export declare function sessionCookieName(options: ResolvedOptions): string;
+export declare function transactionCookieName(options: ResolvedOptions): string;
+export declare function sealSession(options: ResolvedOptions, payload: Omit<SessionPayload, keyof JWTPayload>): Promise<SetCookie>;
+export declare function openSession(options: ResolvedOptions, value: string | undefined): Promise<SessionPayload | null>;
+export declare function clearSession(options: ResolvedOptions): SetCookie;
+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 linkCookieName(options: ResolvedOptions): string;
+export declare function sealLink(options: ResolvedOptions, payload: Omit<LinkPayload, keyof JWTPayload>): Promise<SetCookie>;
+export declare function openLink(options: ResolvedOptions, value: string | undefined): Promise<LinkPayload | null>;
+export declare function clearLink(options: ResolvedOptions): SetCookie;
+export declare function cookieFrom(header: string | null, name: string): string | undefined;
+/** The Cookie header with these cookies replaced or removed, for a proxy to forward. */
+export declare function withCookies(header: string | null, updates: SetCookie[]): string;

package/dist/cookies.js

@@ -0,0 +1,131 @@
+import { EncryptJWT, jwtDecrypt } from 'jose';
+import { AuthError } from './oidc.js';
+const SESSION = 'wtfalch_auth';
+const TRANSACTION = 'wtfalch_auth_tx';
+const LINK = 'wtfalch_auth_link';
+const TRANSACTION_TTL = 10 * 60;
+export function sessionCookieName(options) {
+    return options.secure ? `__Host-${SESSION}` : SESSION;
+}
+export function transactionCookieName(options) {
+    return options.secure ? `__Host-${TRANSACTION}` : TRANSACTION;
+}
+export async function sealSession(options, payload) {
+    const value = await seal(options, 'session', payload, options.sessionMaxAge);
+    const cookie = setCookie(sessionCookieName(options), value, options.sessionMaxAge, options.secure);
+    if (cookie.header.length > 4096) {
+        throw new AuthError('cookie', `the session cookie is ${cookie.header.length} bytes; browsers drop over 4096`);
+    }
+    return cookie;
+}
+export async function openSession(options, value) {
+    const payload = await open(options, 'session', value);
+    return payload && typeof payload.idt === 'string' ? payload : null;
+}
+export function clearSession(options) {
+    return setCookie(sessionCookieName(options), '', 0, options.secure);
+}
+export async function sealTransaction(options, payload) {
+    const value = await seal(options, 'transaction', payload, TRANSACTION_TTL);
+    return setCookie(transactionCookieName(options), value, TRANSACTION_TTL, options.secure);
+}
+export async function openTransaction(options, value) {
+    const payload = await open(options, 'transaction', value);
+    return payload &&
+        typeof payload.st === 'string' &&
+        typeof payload.nc === 'string' &&
+        typeof payload.cv === 'string' &&
+        typeof payload.nx === 'string'
+        ? payload
+        : null;
+}
+export function clearTransaction(options) {
+    return setCookie(transactionCookieName(options), '', 0, options.secure);
+}
+export function linkCookieName(options) {
+    return options.secure ? `__Host-${LINK}` : LINK;
+}
+export async function sealLink(options, payload) {
+    const value = await seal(options, 'link', payload, TRANSACTION_TTL);
+    return setCookie(linkCookieName(options), value, TRANSACTION_TTL, options.secure);
+}
+export async function openLink(options, value) {
+    const payload = await open(options, 'link', value);
+    return payload &&
+        typeof payload.sid === 'string' &&
+        typeof payload.stk === 'string' &&
+        typeof payload.ar === 'string'
+        ? payload
+        : null;
+}
+export function clearLink(options) {
+    return setCookie(linkCookieName(options), '', 0, options.secure);
+}
+async function seal(options, kind, payload, ttl) {
+    return new EncryptJWT(payload)
+        .setProtectedHeader({ alg: 'dir', enc: 'A256GCM' })
+        .setIssuer(options.appUrl.origin)
+        .setAudience(kind)
+        .setIssuedAt()
+        .setExpirationTime(Math.floor(Date.now() / 1000) + ttl)
+        .encrypt(options.cookieKey);
+}
+async function open(options, kind, value) {
+    if (!value)
+        return null;
+    try {
+        const { payload } = await jwtDecrypt(value, options.cookieKey, {
+            issuer: options.appUrl.origin,
+            audience: kind,
+            contentEncryptionAlgorithms: ['A256GCM'],
+            keyManagementAlgorithms: ['dir'],
+        });
+        return payload;
+    }
+    catch {
+        return null;
+    }
+}
+function setCookie(name, value, maxAge, secure) {
+    const parts = [`${name}=${value}`, 'Path=/', 'HttpOnly', 'SameSite=Lax'];
+    if (maxAge > 0) {
+        parts.push(`Max-Age=${maxAge}`);
+    }
+    else {
+        parts.push('Max-Age=0', 'Expires=Thu, 01 Jan 1970 00:00:00 GMT');
+    }
+    if (secure)
+        parts.push('Secure');
+    return {
+        name,
+        value,
+        header: parts.join('; '),
+        attributes: { path: '/', httpOnly: true, sameSite: 'lax', secure, maxAge },
+    };
+}
+export function cookieFrom(header, name) {
+    for (const part of (header ?? '').split(';')) {
+        const eq = part.indexOf('=');
+        if (eq !== -1 && part.slice(0, eq).trim() === name) {
+            const value = part.slice(eq + 1).trim();
+            return value.length > 0 ? value : undefined;
+        }
+    }
+    return undefined;
+}
+/** The Cookie header with these cookies replaced or removed, for a proxy to forward. */
+export function withCookies(header, updates) {
+    const names = new Set(updates.map((u) => u.name));
+    const kept = (header ?? '')
+        .split(';')
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0)
+        .filter((part) => {
+        const eq = part.indexOf('=');
+        return eq === -1 || !names.has(part.slice(0, eq).trim());
+    });
+    for (const u of updates)
+        if (u.value)
+            kept.push(`${u.name}=${u.value}`);
+    return kept.join('; ');
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+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 AuthOptions, ISSUER } from './config.js';
+export type { SetCookie } from './cookies.js';
+export { BrokerError } from './broker.js';
+export { AuthError, type AuthErrorReason, ORG_CLAIM } from './oidc.js';
+export { safeNextPath } from './redirect.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { createAuth, } from './auth.js';
+export { ISSUER } from './config.js';
+export { BrokerError } from './broker.js';
+export { AuthError, ORG_CLAIM } from './oidc.js';
+export { safeNextPath } from './redirect.js';

package/dist/next.d.ts

@@ -0,0 +1,68 @@
+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 { AuthOptions } from './config.js';
+type SearchParams = Record<string, string | string[] | undefined>;
+export interface NextAuth {
+    auth: Auth;
+    /** `export const { GET, POST } = handlers` from app/auth/[...auth]/route.ts. */
+    handlers: {
+        GET: (request: Request) => Promise<Response>;
+        POST: (request: Request) => Promise<Response>;
+    };
+    /** The gate and the refresh, for src/proxy.ts. */
+    proxy: (request: NextRequest, rules?: GateRules) => Promise<NextResponse>;
+    /** Reads the cookie, never writes it. Fresh only where the proxy ran. */
+    getUser: () => Promise<User | null>;
+    /** The user, or a redirect to sign in with `next` to come back to. */
+    requireUser: (next?: string) => Promise<User>;
+    /**
+     * For the app's login and register pages: the auth request the issuer sent
+     * the browser with, or a redirect that starts one. Pass the page's searchParams.
+     */
+    authRequest: (searchParams: SearchParams | Promise<SearchParams>, opts?: {
+        next?: string;
+        intent?: Intent;
+    }) => Promise<AuthRequest>;
+    /** For a server action: redirects into the app on success, returns the error otherwise. */
+    signIn: (input: {
+        authRequestId: string;
+        email: string;
+        password: string;
+    }) => Promise<{
+        error: SignInError;
+    }>;
+    signUp: (input: {
+        authRequestId: string;
+    } & NewUser) => Promise<{
+        error: SignUpError;
+        message: string;
+    }>;
+    /** Emails a fresh verification link. Never says whether the address exists. */
+    resendVerification: (email: string, next?: string) => Promise<void>;
+    /** Emails a password-reset link. Never says whether the address exists. */
+    requestPasswordReset: (email: string, next?: string) => Promise<void>;
+    /** Emails a sign-in link. Never says whether the address exists. */
+    sendLink: (email: string, next?: string) => Promise<void>;
+    /** Brings a person into this app's organisation and mails them a way in. */
+    invite: (input: {
+        email: string;
+        givenName: string;
+        familyName: string;
+        next?: string;
+    }) => Promise<{
+        userId: string;
+        invited: boolean;
+    }>;
+    /** Sets the password from a reset link, signs the person in, and redirects. */
+    resetPassword: (input: {
+        userId: string;
+        code: string;
+        password: string;
+        next?: string;
+    }) => Promise<{
+        error: ResetError;
+        message: string;
+    }>;
+}
+export declare function nextAuth(options: AuthOptions): NextAuth;
+export type { Auth, AuthOptions, AuthRequest, GateRules, Intent, NewUser, User };

package/dist/next.js

@@ -0,0 +1,111 @@
+import { cookies } from 'next/headers';
+import { redirect } from 'next/navigation';
+import { NextResponse } from 'next/server';
+import { createAuth, } from './auth.js';
+import { withCookies } from './cookies.js';
+export function nextAuth(options) {
+    const auth = createAuth(options);
+    const proxy = async (request, rules) => {
+        const gate = await auth.gate(request, rules);
+        let response;
+        if (gate.kind === 'redirect') {
+            response = NextResponse.redirect(gate.location, 303);
+        }
+        else if (gate.kind === 'deny') {
+            response = new NextResponse('Unauthorized', { status: 401 });
+        }
+        else if (gate.cookies.length > 0) {
+            const headers = new Headers(request.headers);
+            headers.set('cookie', withCookies(request.headers.get('cookie'), gate.cookies));
+            response = NextResponse.next({ request: { headers } });
+        }
+        else {
+            response = NextResponse.next();
+        }
+        for (const cookie of gate.cookies)
+            response.headers.append('Set-Cookie', cookie.header);
+        return response;
+    };
+    const getUser = async () => {
+        const store = await cookies();
+        const { user } = await auth.readCookie(store.get(auth.sessionCookieName)?.value, {
+            refresh: false,
+        });
+        return user;
+    };
+    const requireUser = async (next) => {
+        const user = await getUser();
+        if (!user)
+            redirect(auth.startUrl(next));
+        return user;
+    };
+    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 { }
+        }
+        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) => {
+        const store = await cookies();
+        const header = store
+            .getAll()
+            .map((c) => `${c.name}=${c.value}`)
+            .join('; ');
+        const { location, cookies: set } = await auth.complete(callbackUrl, header);
+        for (const c of set) {
+            if (c.value)
+                store.set(c.name, c.value, c.attributes);
+            else
+                store.delete({ name: c.name, path: '/' });
+        }
+        const url = new URL(location);
+        redirect(`${url.pathname}${url.search}`);
+    };
+    const resetPassword = async (input) => {
+        const result = await auth.resetPassword(input);
+        if (!result.ok)
+            return { error: result.error, message: result.message };
+        const store = await cookies();
+        for (const c of result.cookies) {
+            if (c.value)
+                store.set(c.name, c.value, c.attributes);
+            else
+                store.delete({ name: c.name, path: '/' });
+        }
+        const url = new URL(result.location);
+        redirect(`${url.pathname}${url.search}`);
+    };
+    const signIn = async (input) => {
+        const result = await auth.signIn(input);
+        if (result.ok)
+            return finish(result.redirectTo);
+        return { error: result.error };
+    };
+    const signUp = async (input) => {
+        const result = await auth.signUp(input);
+        if (result.ok)
+            return finish(result.redirectTo);
+        return { error: result.error, message: result.message };
+    };
+    return {
+        auth,
+        handlers: { GET: auth.handle, POST: auth.handle },
+        proxy,
+        getUser,
+        requireUser,
+        authRequest,
+        signIn,
+        signUp,
+        resendVerification: auth.resendVerification,
+        requestPasswordReset: auth.requestPasswordReset,
+        sendLink: auth.sendLink,
+        invite: auth.invite,
+        resetPassword,
+    };
+}

package/dist/oidc.d.ts

@@ -0,0 +1,35 @@
+import * as jose from 'jose';
+import type { ResolvedOptions } from './config.js';
+export declare const ORG_CLAIM = "urn:zitadel:iam:user:resourceowner:id";
+export interface Tokens {
+    idToken: string;
+    refreshToken?: string;
+    claims: jose.JWTPayload;
+}
+export declare class Oidc {
+    private readonly options;
+    private configuration;
+    private jwks;
+    private refreshing;
+    constructor(options: ResolvedOptions);
+    private config;
+    private keys;
+    get redirectUri(): URL;
+    authorizationUrl(state: string, nonce: string, codeVerifier: string, { create }?: {
+        create?: boolean;
+    }): Promise<URL>;
+    exchange(callbackParams: URLSearchParams, transaction: {
+        state: string;
+        nonce: string;
+        codeVerifier: string;
+    }): Promise<Tokens>;
+    refresh(refreshToken: string): Promise<Tokens>;
+    private tokensFrom;
+    verify(idToken: string): Promise<jose.JWTPayload>;
+    private assertOrganization;
+}
+export type AuthErrorReason = 'expired' | 'state' | 'denied' | 'exchange' | 'organization' | 'cookie' | 'request';
+export declare class AuthError extends Error {
+    readonly reason: AuthErrorReason;
+    constructor(reason: AuthErrorReason, message: string);
+}