@wtfalch/auth 0.12.0 → 0.13.0

package/README.md

@@ -99,11 +99,11 @@ again. `forget()` sets the same mark, so a sign-out does not undo itself.
 `completeSignIn()` at the callback returns `signed-in`, `silent-refused` — the
 answer to a silent attempt, not a failure — or `error`.
 
-### Hub seams: a non-default opener, storage, refresh and scopes
+### Multi-session seams: a non-default opener, storage, refresh and scopes
 
 Four options on `BrowserAuthOptions` exist for a client that is not a
 plain same-origin web page — a phone driving a system browser, a desktop app,
-or a hub app juggling more than one issuer session. Every default matches the
+or an app juggling more than one issuer session. Every default matches the
 behaviour above exactly, so a caller that sets none of them sees no change.
 
 ```ts
@@ -124,7 +124,7 @@ const auth = createBrowserAuth({
   `{ get, set, drop }` shape — `get` synchronous, `set`/`drop` allowed to
   return a promise (see "Storage: `get` stays synchronous" below). Two
   `createBrowserAuth` instances given different stores never see each other's
-  values — one hub's session cannot leak into another's held in the same tab.
+  values — one app's session cannot leak into another's held in the same tab.
 - **`refresh()`**, a new method on the returned client, posts the
   `refresh_token` grant and stores the session it gets back — awaiting the
   store's write before it resolves, so an app that awaits `refresh()` knows

package/dist/auth.d.ts

@@ -1,6 +1,6 @@
 import { type JWTPayload } from 'jose';
 import { type AuthRequest, type NewUser, type PeoplePage } from './broker.js';
-import { type AuthOptions } from './config.js';
+import { type AccessTokenResult, type AuthOptions } from './config.js';
 import { type SetCookie } from './cookies.js';
 import type { SessionRecord } from './sessions.js';
 export interface User {
@@ -163,33 +163,6 @@ export interface QrPollResult {
     reason?: string;
     cookies: SetCookie[];
 }
-/**
- * Why `accessToken` refused: no session cookie, or one that will not open
- * (`no_session`); a session with no refresh token (`no_refresh_token`); or
- * the issuer refusing the refresh grant itself, including the same
- * organisation/id-token validation `readCookie`'s refresh path applies
- * (`refused`). A transient outage is not in this list -- `accessToken`
- * throws for that instead, see its own doc comment.
- */
-export type AccessTokenReason = 'no_session' | 'no_refresh_token' | 'refused';
-export type AccessTokenResult = {
-    ok: true;
-    /** The issuer's own bearer token. Never the id token, and never what was in the cookie. */
-    accessToken: string;
-    /** Epoch milliseconds. */
-    expiresAt: number;
-    /**
-     * The re-sealed session -- always exactly one cookie, even when the
-     * refresh token itself did not rotate, because the grant always
-     * returns a fresh id token too. Persist it, e.g. as a `Set-Cookie`,
-     * before the value passed in is used again: the refresh token in it
-     * is spent.
-     */
-    cookies: SetCookie[];
-} | {
-    ok: false;
-    reason: AccessTokenReason;
-};
 export interface Auth {
     readonly sessionCookieName: string;
     /** GET {basePath}/start?next=&intent= : begins the OIDC flow; the issuer sends the browser to {basePath}/login?authRequest= */
@@ -415,33 +388,33 @@ export interface Auth {
      */
     pollQrSignIn(request: Request): Promise<QrPollResult>;
     /**
-     * Trades a sealed session cookie's value (`readCookie`'s own `value`
-     * parameter, not a `Cookie` header) for a fresh issuer access token. The
-     * cookie never holds one -- `Tokens` keeps only an id token and a refresh
-     * token -- so this runs the refresh grant itself and reads `access_token`
-     * straight off that response, applying the same id-token and organisation
-     * checks `readCookie`'s own refresh path applies, through the same
-     * `Oidc.refresh`.
+     * Trades a sealed session's `value` (`readCookie`'s own `value` parameter,
+     * not a `Cookie` header -- in namespace mode, the handle) for a fresh
+     * issuer access token. Nothing here ever holds one -- `Tokens` keeps only
+     * an id token and a refresh token -- so this runs the refresh grant itself
+     * and reads `access_token` straight off that response, applying the same
+     * id-token and organisation checks `readCookie`'s own refresh path
+     * applies, through the same `Oidc.refresh`.
      *
      * The refresh token is SPENT on every call: the issuer rotates it on each
-     * grant. A caller must serialise calls for one session -- two in flight
-     * would race the same token -- and persist `cookies`, the re-sealed
-     * session this always returns on `ok: true` (a fresh id token comes back
-     * on every grant, even on the rare one that does not rotate the refresh
-     * token), before the session is read or `accessToken` is called again.
+     * grant. Cookie mode: a caller must serialise calls for one session -- two
+     * in flight would race the same token -- and persist `cookies`, the
+     * re-sealed session this always returns on `ok: true` (a fresh id token
+     * comes back on every grant, even on the rare one that does not rotate the
+     * refresh token), before the session is read or `accessToken` is called
+     * again. Namespace mode: `cookies` is always empty, and the call itself
+     * serialises under the record's own lease -- the same one a due `read`
+     * refreshes under -- so two calls, or a call racing a due read, spend the
+     * token in turn rather than together.
      *
      * `ok: false` is a definitive refusal -- no session, no refresh token in
      * it, or the issuer refusing the grant (`isOAuthRefusal`, or the same
      * organisation/id-token check `readCookie` applies). A transient issuer
      * outage (network error, 5xx, 429) throws instead of answering
      * `ok: false`: unlike `readCookie`, there is no still-valid access token
-     * to fall back to, because one was never kept.
-     *
-     * Not available in namespace mode: those sessions are a handle to a
-     * server-held record, refreshed under a lease (see `namespace-session.ts`)
-     * that serialises rotation across replicas. Spending the refresh token
-     * here would run outside that lease and could race, or duplicate, the
-     * rotation the lease exists to prevent. Throws when `namespace` is set.
+     * to fall back to, because one was never kept, in either mode.
+     * Namespace mode also throws while the binding is suspended, and when
+     * another holder keeps the record's lease past the wait.
      */
     accessToken(cookieValue: string): Promise<AccessTokenResult>;
 }

package/dist/auth.js

@@ -1,7 +1,7 @@
 import { errors } from 'jose';
 import * as client from 'openid-client';
 import { Broker, BrokerError } from './broker.js';
-import { resolveOptions } from './config.js';
+import { resolveOptions, } from './config.js';
 import { clearQrTransaction, clearSession, clearTransaction, cookieFrom, openQrTransaction, openRecord, openSession, openTransaction, qrTransactionCookieName, sealQrTransaction, sealSession, sealTransaction, sessionCookieName, transactionCookieName, } from './cookies.js';
 import { namespaceSessions } from './namespace-session.js';
 import { AuthError, ORG_CLAIM, Oidc, isOAuthRefusal, scopeFor } from './oidc.js';
@@ -19,6 +19,26 @@ export function createAuth(input) {
         }
         return resolved;
     };
+    const emit = (event) => {
+        try {
+            // The type says void, but nothing stops a caller from handing over an
+            // async function -- audit logging is usually a database write. An
+            // async throw never reaches this catch (calling an async function
+            // cannot throw synchronously, whatever is on its first line), so a
+            // thenable return is caught too, or a careless callback would produce
+            // an unhandled rejection instead of the logged-and-ignored failure
+            // promised above.
+            const result = options().onAuthEvent?.(event);
+            if (result && typeof result.then === 'function') {
+                Promise.resolve(result).catch((error) => {
+                    console.error('@wtfalch/auth: onAuthEvent threw', error);
+                });
+            }
+        }
+        catch (error) {
+            console.error('@wtfalch/auth: onAuthEvent threw', error);
+        }
+    };
     const boundUser = (claims) => {
         const namespace = options().namespace;
         return {
@@ -460,7 +480,11 @@ export function createAuth(input) {
     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 invite = async (input) => {
+        const result = await broker().invite({ ...input, next: safeNextPath(input.next, '') });
+        emit({ type: 'invite', email: input.email, userId: result.userId, invited: result.invited });
+        return result;
+    };
     const resetPassword = async ({ userId, code, password, next, }, requestHeaders) => {
         try {
             const flow = await serverFlow();
@@ -505,21 +529,29 @@ export function createAuth(input) {
     };
     const signIn = async ({ authRequestId, email, password, }) => {
         try {
-            return { ok: true, redirectTo: await broker().signIn({ authRequestId, email, password }) };
+            const redirectTo = await broker().signIn({ authRequestId, email, password });
+            emit({ type: 'signIn', email });
+            return { ok: true, redirectTo };
         }
         catch (error) {
-            if (needsHostedLogin(error))
+            if (needsHostedLogin(error)) {
+                emit({ type: 'signIn', email });
                 return { ok: true, redirectTo: hostedUrl(authRequestId), hosted: true };
+            }
             return { ok: false, error: signInError(error) };
         }
     };
     const signUp = async ({ authRequestId, ...user }) => {
         try {
-            return { ok: true, redirectTo: await broker().signUp({ authRequestId, ...user }) };
+            const redirectTo = await broker().signUp({ authRequestId, ...user });
+            emit({ type: 'signUp', email: user.email });
+            return { ok: true, redirectTo };
         }
         catch (error) {
-            if (needsHostedLogin(error))
+            if (needsHostedLogin(error)) {
+                emit({ type: 'signUp', email: user.email });
                 return { ok: true, redirectTo: hostedUrl(authRequestId), hosted: true };
+            }
             if (error instanceof BrokerError && error.error === 'email_taken') {
                 return { ok: false, error: 'email_taken', message: error.detail ?? error.error };
             }
@@ -707,9 +739,8 @@ export function createAuth(input) {
         return { status: 'signed_in', cookies: [cleared, session] };
     };
     const accessToken = async (cookieValue) => {
-        if (options().namespace) {
-            throw new Error('@wtfalch/auth: accessToken is not supported in namespace mode -- those sessions refresh under a server-side lease this would bypass');
-        }
+        if (options().namespace)
+            return sessions.accessToken(cookieValue);
         const session = await openSession(options(), cookieValue);
         if (!session)
             return { ok: false, reason: 'no_session' };

package/dist/browser.d.ts

@@ -85,7 +85,7 @@ export interface BrowserAuthOptions {
     /**
      * Holds the token, verifier, return path and silent-tried mark. Default
      * wraps `sessionStorage` and never throws. Two instances given different
-     * stores never see each other's values — inject one per hub.
+     * stores never see each other's values — inject one per app.
      */
     store?: BrowserAuthStore;
 }

package/dist/config.d.ts

@@ -1,5 +1,55 @@
+import type { SetCookie } from './cookies.js';
 import { type NamespaceSelection, resolveNamespaceContext } from './namespaces.js';
 import type { SessionStore } from './sessions.js';
+/**
+ * An auth lifecycle event, for audit logging. Each variant carries only
+ * what the call that fires it already has in hand -- `signIn`/`signUp`
+ * resolve to a redirect, not a decoded identity, so there is no `userId`
+ * to offer there; `invite` calls the broker's own endpoint, which returns
+ * one.
+ */
+export type AuthEvent = {
+    type: 'signIn';
+    email: string;
+} | {
+    type: 'signUp';
+    email: string;
+} | {
+    type: 'invite';
+    email: string;
+    userId: string;
+    invited: boolean;
+};
+/**
+ * Why `accessToken` refused: no session (no cookie in cookie mode, no live
+ * record behind the namespace handle in namespace mode), a session with no
+ * refresh token (`no_refresh_token`), or the issuer refusing the refresh
+ * grant itself, including the same organisation/id-token validation the
+ * ordinary refresh path applies (`refused`). A transient outage is not in
+ * this list -- `accessToken` throws for that instead, see its own doc
+ * comment.
+ */
+export type AccessTokenReason = 'no_session' | 'no_refresh_token' | 'refused';
+export type AccessTokenResult = {
+    ok: true;
+    /** The issuer's own bearer token. Never the id token, and never what was in the cookie. */
+    accessToken: string;
+    /** Epoch milliseconds. */
+    expiresAt: number;
+    /**
+     * Cookie mode: always exactly one, even when the refresh token itself
+     * did not rotate, because the grant always returns a fresh id token
+     * too. Persist it, e.g. as a `Set-Cookie`, before the value passed in
+     * is used again: the refresh token in it is spent.
+     *
+     * Namespace mode: always empty. The record updates itself under its
+     * own lease; there is nothing for the caller to persist.
+     */
+    cookies: SetCookie[];
+} | {
+    ok: false;
+    reason: AccessTokenReason;
+};
 export interface AuthOptions {
     /** Opt-in namespace mode. Resolve this from trusted workspace/host configuration. */
     namespace?: NamespaceSelection;
@@ -59,6 +109,13 @@ export interface AuthOptions {
      */
     freshness?: number;
     fetch?: typeof fetch;
+    /**
+     * Called after a sign-in, a sign-up, or an invite succeeds, so an app can
+     * add audit logging without threading it through every call site by hand.
+     * Never awaited; a throw from it is caught and logged rather than failing
+     * the call it rode in on.
+     */
+    onAuthEvent?: (event: AuthEvent) => void;
 }
 export interface ResolvedOptions {
     namespace: ReturnType<typeof resolveNamespaceContext> | null;
@@ -93,6 +150,7 @@ export interface ResolvedOptions {
     freshness: number;
     secure: boolean;
     fetch: typeof fetch;
+    onAuthEvent: ((event: AuthEvent) => void) | null;
 }
 export declare const ISSUER = "https://auth.wtfalch.dev";
 export declare function resolveOptions(options: AuthOptions): ResolvedOptions;

package/dist/config.js

@@ -59,6 +59,7 @@ export function resolveOptions(options) {
         freshness: seconds(options.freshness, 'freshness', 5 * 60),
         secure: appUrl.protocol === 'https:',
         fetch: options.fetch ?? globalThis.fetch,
+        onAuthEvent: options.onAuthEvent ?? null,
     };
 }
 function required(value, name) {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export { type AccessTokenReason, type AccessTokenResult, type Auth, type AuthRequest, type Gate, type GateRules, type Intent, type MaxAge, type NewUser, type PasskeyRegistrationResult, type PasskeyRegistrationStart, type PasskeySignInStart, type Prompt, 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 Auth, type AuthRequest, type Gate, type GateRules, type Intent, type MaxAge, type NewUser, type PasskeyRegistrationResult, type PasskeyRegistrationStart, type PasskeySignInStart, type Prompt, 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 AccessTokenReason, type AccessTokenResult, type AuthEvent, type AuthOptions, ISSUER, } from './config.js';
 export type { SetCookie } from './cookies.js';
 export type { SessionRecord, SessionStore, SessionUpdate } from './sessions.js';
 export { BrokerError } from './broker.js';

package/dist/index.js

@@ -1,5 +1,5 @@
 export { createAuth, } from './auth.js';
-export { ISSUER } from './config.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/namespace-session.d.ts

@@ -1,6 +1,6 @@
 import type { JWTPayload } from 'jose';
 import { type Broker } from './broker.js';
-import type { ResolvedOptions } from './config.js';
+import type { AccessTokenResult, ResolvedOptions } from './config.js';
 import { type SetCookie } from './cookies.js';
 import { type Oidc, type Tokens } from './oidc.js';
 import type { SessionRecord } from './sessions.js';
@@ -42,4 +42,5 @@ export declare function namespaceSessions(deps: {
     listSessions: (subject: string) => Promise<SessionRecord[]>;
     endSession: (key: string, subject: string) => Promise<boolean>;
     keyOf: (value: string | undefined) => Promise<string | null>;
+    accessToken: (value: string | undefined) => Promise<AccessTokenResult>;
 };

package/dist/namespace-session.js

@@ -266,6 +266,116 @@ export function namespaceSessions(deps) {
             tokens: { k: key, idt: fresh.idToken, rt: fresh.refreshToken },
         };
     };
+    /**
+     * A fresh access token for this namespace session, under the record's own
+     * lease -- so this can never race the rotation a due `read` triggers, and
+     * two calls for the same session serialise rather than spend the refresh
+     * token twice.
+     *
+     * Unlike `refresh`, this can never settle for "another request just
+     * refreshed it, that generation bump is good enough": the access token
+     * from that grant was never kept (`RecordPayload` holds only an id token
+     * and a refresh token, see `namespace-session.ts`'s own module comment),
+     * so the only way to answer is a grant this call runs itself. It waits
+     * out whoever holds the lease first, the same wait `refresh` does, but
+     * always performs its own grant once it takes the lease rather than
+     * reusing `refreshLeased`'s "give up and use what's there" shortcut.
+     */
+    const accessToken = async (value) => {
+        const key = await keyOf(value);
+        if (!key)
+            return { ok: false, reason: 'no_session' };
+        // A suspended binding mints nothing, the same gate `read` and every
+        // sign-in entry point apply. It throws rather than answering `ok: false`,
+        // as `startSignIn` does: a suspension is not a verdict on this session,
+        // and the fail-closed answer while the service is unreachable is not
+        // definitive either.
+        if (!(await bindingActive()))
+            throw new AuthError('unavailable', 'the namespace binding is not active');
+        let current = await load(key);
+        if (!current)
+            return { ok: false, reason: 'no_session' };
+        if (!current.tokens.rt)
+            return { ok: false, reason: 'no_refresh_token' };
+        for (let attempt = 0;; attempt++) {
+            const { record } = current;
+            const leased = record.leaseUntil !== null && record.leaseUntil > now();
+            if (!leased) {
+                const generation = record.generation + 1;
+                const acquired = await store().advance(key, record.generation, {
+                    payload: record.payload,
+                    expiresAt: record.expiresAt,
+                    leaseUntil: now() + LEASE_SECONDS,
+                });
+                if (acquired)
+                    return runGrant(key, current, generation);
+            }
+            // Still leased after the wait: someone else's grant is in flight, or a
+            // crashed holder's lease has not run out yet. Neither is a verdict on
+            // this session, so this throws like a transient issuer outage rather
+            // than answering `refused`, which a caller may treat as signed out.
+            if (attempt >= WAIT_STEPS)
+                throw new Error('@wtfalch/auth: accessToken timed out waiting for the session lease');
+            await sleep(WAIT_STEP_MS);
+            const latest = await load(key);
+            if (!latest)
+                return { ok: false, reason: 'no_session' };
+            if (!latest.tokens.rt)
+                return { ok: false, reason: 'no_refresh_token' };
+            current = latest;
+        }
+    };
+    /** The grant `accessToken` runs once it holds the lease itself. */
+    const runGrant = async (key, leased, generation) => {
+        const { record, tokens } = leased;
+        let fresh;
+        try {
+            fresh = await deps.oidc().refresh(tokens.rt);
+        }
+        catch (error) {
+            await store()
+                .advance(key, generation, {
+                payload: record.payload,
+                expiresAt: record.expiresAt,
+                leaseUntil: null,
+            })
+                .catch(() => { });
+            if (definitive(error)) {
+                // The lease means nobody else spent the token: the issuer has ended it.
+                await store().revoke(key, now());
+                return { ok: false, reason: 'refused' };
+            }
+            // A network error or a 5xx: no access token was ever minted, and
+            // unlike a plain session read there is no still-valid one to fall
+            // back to -- so this throws, exactly as the cookie-mode accessToken
+            // does for the same case.
+            throw error;
+        }
+        const committed = await store().advance(key, generation, {
+            payload: await seal(key, fresh),
+            expiresAt: now() + options().sessionMaxAge,
+            leaseUntil: null,
+        });
+        if (!committed) {
+            // Revoked while the grant was in flight, or the lease ran out and
+            // another request took over. The fresh tokens are kept nowhere, so
+            // the refresh token is not left live if it rotated.
+            if (fresh.refreshToken !== tokens.rt)
+                revokeToken(fresh.refreshToken);
+            return { ok: false, reason: 'refused' };
+        }
+        if (!fresh.accessToken || fresh.accessTokenExpiresAt === undefined) {
+            // The issuer answered the grant but sent no access token -- treat it
+            // the same as a refusal rather than handing back an unusable result.
+            return { ok: false, reason: 'refused' };
+        }
+        return {
+            ok: true,
+            accessToken: fresh.accessToken,
+            expiresAt: fresh.accessTokenExpiresAt,
+            cookies: [],
+        };
+    };
     /**
      * The person behind this cookie. Never sets a cookie: a dead or revoked
      * handle just reads as nobody until the next sign-in replaces it.
@@ -298,7 +408,17 @@ export function namespaceSessions(deps) {
             return { kind: 'none' };
         }
     };
-    return { bindingActive, create, end, read, revokeSubject, listSessions, endSession, keyOf };
+    return {
+        bindingActive,
+        create,
+        end,
+        read,
+        revokeSubject,
+        listSessions,
+        endSession,
+        keyOf,
+        accessToken,
+    };
 }
 /**
  * These apps sit behind a proxy, so the client never reaches this process

package/dist/next.d.ts

@@ -1,6 +1,6 @@
 import { type NextRequest, NextResponse } from 'next/server';
 import { type Auth, type AuthRequest, type ChangePasswordResult, type DeletePasskeyResult, type EmailChangeResult, type GateRules, type Intent, type MaxAge, type NewUser, type Passkey, type PasskeyRegistrationResult, type PasskeyRegistrationStart, type PasskeySignInStart, type Prompt, type QrPollStatus, type ResetError, type SignInError, type SignUpError, type User } from './auth.js';
-import type { AuthOptions } from './config.js';
+import type { AuthEvent, AuthOptions } from './config.js';
 import type { SessionRecord } from './sessions.js';
 type SearchParams = Record<string, string | string[] | undefined>;
 export interface QrSignIn {
@@ -157,4 +157,4 @@ export interface NextAuth {
     }>;
 }
 export declare function nextAuth(options: AuthOptions): NextAuth;
-export type { Auth, AuthOptions, AuthRequest, ChangePasswordResult, DeletePasskeyResult, EmailChangeResult, GateRules, Intent, MaxAge, NewUser, Passkey, PasskeyRegistrationResult, PasskeyRegistrationStart, PasskeySignInStart, Prompt, QrPollStatus, SessionRecord, User, };
+export type { Auth, AuthEvent, AuthOptions, AuthRequest, ChangePasswordResult, DeletePasskeyResult, EmailChangeResult, GateRules, Intent, MaxAge, NewUser, Passkey, PasskeyRegistrationResult, PasskeyRegistrationStart, PasskeySignInStart, Prompt, QrPollStatus, SessionRecord, User, };

package/dist/testing.d.ts

@@ -0,0 +1,31 @@
+import type { Auth, User } from './auth.js';
+export declare function setSessionUser(user: User | null): void;
+/** A User shaped like the SDK's, for `setSessionUser`. */
+export declare function testUser(id: string, overrides?: Partial<User>): User;
+export declare function getUser(): Promise<User | null>;
+export declare function requireUser(_next?: string): Promise<User>;
+export declare const handlers: () => never;
+export declare const proxy: () => never;
+export declare const authRequest: () => never;
+export declare const signIn: () => never;
+export declare const signUp: () => never;
+export declare const requestPasswordReset: () => never;
+export declare const resetPassword: () => never;
+export declare const sendLink: () => never;
+export declare const resendVerification: () => never;
+/**
+ * The core SDK instance, as far as a device sign-in module reaches into it.
+ *
+ * The real one talks to the issuer. This one records what was asked and
+ * answers with whatever a test set, so a device/link sign-in flow can be
+ * exercised against a real database without one. Only the members named
+ * here are stubbed; anything else read off `auth` is a mistake worth a loud
+ * one.
+ */
+export declare const sentLinks: {
+    email: string;
+    next?: string;
+}[];
+export declare function setFollowLinkResult(result: unknown): void;
+export declare function setCookieUser(user: User | null): void;
+export declare const auth: Auth;

package/dist/testing.js

@@ -0,0 +1,81 @@
+/**
+ * A stub for whatever `@/lib/auth` resolves to in an app's integration test
+ * tier. The real module reads a sealed cookie through `next/headers`, which
+ * does not load outside a Next.js build; this one answers with whatever
+ * `setSessionUser` last set, so a test can be "signed in" as one person,
+ * call the app's own authorization logic for real, then sign in as another.
+ * Nothing here talks to the issuer.
+ *
+ * Alias the app's auth module to `@wtfalch/auth/testing` for that tier (for
+ * example in a vitest config's `resolve.alias`), or re-export from it.
+ */
+let current = null;
+export function setSessionUser(user) {
+    current = user;
+}
+/** A User shaped like the SDK's, for `setSessionUser`. */
+export function testUser(id, overrides = {}) {
+    return {
+        id,
+        email: `${id}@example.test`,
+        emailVerified: true,
+        name: `Person ${id}`,
+        givenName: null,
+        familyName: null,
+        preferredUsername: null,
+        organizationId: 'org-test',
+        // Never fresh, which is what a stubbed session should be: the issuer only
+        // owes `auth_time` when the request asked for it, and nothing here asks.
+        authTime: null,
+        claims: {},
+        ...overrides,
+    };
+}
+export async function getUser() {
+    return current;
+}
+export async function requireUser(_next) {
+    if (!current)
+        throw new Error('requireUser: no session set; call setSessionUser first');
+    return current;
+}
+function unavailable(name) {
+    return () => {
+        throw new Error(`${name} is not available in the integration tier`);
+    };
+}
+export const handlers = unavailable('handlers');
+export const proxy = unavailable('proxy');
+export const authRequest = unavailable('authRequest');
+export const signIn = unavailable('signIn');
+export const signUp = unavailable('signUp');
+export const requestPasswordReset = unavailable('requestPasswordReset');
+export const resetPassword = unavailable('resetPassword');
+export const sendLink = unavailable('sendLink');
+export const resendVerification = unavailable('resendVerification');
+/**
+ * The core SDK instance, as far as a device sign-in module reaches into it.
+ *
+ * The real one talks to the issuer. This one records what was asked and
+ * answers with whatever a test set, so a device/link sign-in flow can be
+ * exercised against a real database without one. Only the members named
+ * here are stubbed; anything else read off `auth` is a mistake worth a loud
+ * one.
+ */
+export const sentLinks = [];
+let linkResult = { ok: false, error: 'invalid_code', message: 'no result set' };
+let cookieUser = null;
+export function setFollowLinkResult(result) {
+    linkResult = result;
+}
+export function setCookieUser(user) {
+    cookieUser = user;
+}
+export const auth = {
+    sessionCookieName: '__Host-wtfalch_auth',
+    sendLink: async (email, next) => {
+        sentLinks.push({ email, next });
+    },
+    followLink: async () => linkResult,
+    readCookie: async () => ({ user: cookieUser, cookies: [] }),
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/auth",
-  "version": "0.12.0",
+  "version": "0.13.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",
@@ -37,6 +37,10 @@
     "./sessions": {
       "types": "./dist/sessions.d.ts",
       "default": "./dist/sessions.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
     }
   },
   "sideEffects": false,