@wtfalch/auth 0.19.0 → 0.20.0

package/README.md

@@ -94,6 +94,15 @@ Auth-request lookup failures lead to the configured error page with
 `auth_error=request` or `auth_error=unavailable`. That page should show a
 retry link; it must not automatically restart authorization.
 
+When a sign-in fails after it started (reasons such as `state`, `unavailable`,
+`exchange`, `denied`, `organization`, `cookie`), the error URL is
+`<onError>?auth_error=<reason>&next=<path>`. `next` is the page the person came
+for, always a path starting with one `/`, URL-encoded as a single parameter, and
+present only when the sealed value is a safe same-origin path. An `onError` that
+already has a query string keeps it. `expired` and `request` carry no `next`:
+there is no transaction to read it from. Use it for the retry link
+(`/auth/start?next=<path>`); a page that ignores it behaves as before.
+
 ## In a browser app
 
 `@wtfalch/auth/browser` is the other half: a public PKCE client for an app that

package/dist/auth.d.ts

@@ -278,6 +278,7 @@ export interface Auth {
     }): Promise<{
         userId: string;
         invited: boolean;
+        personalEmailStored: boolean;
     }>;
     handle(request: Request): Promise<Response>;
     /**
@@ -331,6 +332,17 @@ export interface Auth {
         userId: string;
         state: string;
     }>;
+    /**
+     * An admin's reset for somebody in this app's own organisation whom
+     * `requestPasswordReset` cannot otherwise get back in -- returns a fresh
+     * one-time password the caller is trusted to deliver some other way,
+     * rather than mailing it. Refused for a user outside this app's
+     * organisation.
+     */
+    adminResetPassword(userId: string): Promise<{
+        userId: string;
+        password: string;
+    }>;
     /**
      * Namespace mode: end every session this person has in this service, on
      * every replica, at their next request. Deactivating someone does this too.

package/dist/auth.js

@@ -159,9 +159,9 @@ export function createAuth(input) {
             return failure('expired', options().namespace ? [] : [cleared]);
         const params = new URL(callbackUrl).searchParams;
         if (params.get('state') !== transaction.st)
-            return failure('state', options().namespace ? [] : [cleared]);
+            return failure('state', options().namespace ? [] : [cleared], transaction.nx);
         if (options().namespace && !(await sessions.bindingActive()))
-            return failure('unavailable', [cleared]);
+            return failure('unavailable', [cleared], transaction.nx);
         // A silent pass the issuer refused (login_required, interaction_required,
         // consent_required, or any other error) is not a failure: sign in the normal
         // way, once. `done` is already set, so `/start` will not go silent again.
@@ -181,7 +181,7 @@ export function createAuth(input) {
             session = await sessionCookie(tokens, requestHeaders);
         }
         catch (error) {
-            return failure(reasonOf(error), [cleared]);
+            return failure(reasonOf(error), [cleared], transaction.nx);
         }
         await replacePreviousSession(cookieHeader);
         return {
@@ -539,6 +539,20 @@ export function createAuth(input) {
         emit({ type: 'invite', email: input.email, userId: result.userId, invited: result.invited });
         return result;
     };
+    /**
+     * An admin's reset for somebody in this app's own organisation whom
+     * `requestPasswordReset` cannot otherwise get back in -- nobody at the
+     * mailbox a personal address or the login address itself would reach.
+     * Refused for a user outside this app's organisation, exactly as
+     * `setPersonActive` is. The password is a one-time one: the person must
+     * choose their own at next sign-in, same as an invite's. Audited with the
+     * target's id and never the password itself.
+     */
+    const adminResetPassword = async (userId) => {
+        const result = await broker().adminResetPassword(userId);
+        emit({ type: 'adminResetPassword', userId: result.userId });
+        return result;
+    };
     const resetPassword = async ({ userId, code, password, next, }, requestHeaders) => {
         try {
             const flow = await serverFlow();
@@ -891,9 +905,13 @@ export function createAuth(input) {
             cookies,
         };
     };
-    const failure = (reason, cookies) => {
+    /** `next`, when it is a safe same-origin path, rides on the error URL so the error page can offer a retry to it. */
+    const failure = (reason, cookies, next) => {
         const url = new URL(options().onError, options().appUrl);
         url.searchParams.set('auth_error', reason);
+        const retry = safeNextPath(next, '');
+        if (retry)
+            url.searchParams.set('next', retry);
         return { location: url.href, cookies };
     };
     /** `failure`'s location on its own, for a caller that redirects rather than answering. */
@@ -927,6 +945,7 @@ export function createAuth(input) {
         errorUrl,
         people,
         setPersonActive,
+        adminResetPassword,
         revokeSessions,
         sessions: listSessions,
         endSession,

package/dist/broker.d.ts

@@ -21,6 +21,12 @@ export interface NewUser {
      * `password_change_required`, then `setNewPassword`).
      */
     changeRequired?: boolean;
+    /**
+     * Where this person's reset links go instead of their own login address --
+     * for somebody who cannot yet open the mailbox that address names. See
+     * `Auth['adminResetPassword']` for the person this does not cover.
+     */
+    personalEmail?: string;
 }
 /** One of the organisation's people, as the sign-in service reports them. */
 export interface Person {
@@ -64,6 +70,11 @@ export declare class Broker {
         userId: string;
         state: string;
     }>;
+    /** An admin's reset for somebody requestPasswordReset cannot get back in: see `Auth['adminResetPassword']`. */
+    adminResetPassword(userId: string): Promise<{
+        userId: string;
+        password: string;
+    }>;
     authRequest(id: string): Promise<AuthRequest>;
     signIn(input: {
         authRequestId: string;
@@ -119,9 +130,11 @@ export declare class Broker {
         givenName: string;
         familyName: string;
         next: string;
+        personalEmail?: string;
     }): Promise<{
         userId: string;
         invited: boolean;
+        personalEmailStored: boolean;
     }>;
     sendLink(email: string, next: string): Promise<unknown>;
     sendReset(email: string, next: string): Promise<unknown>;

package/dist/broker.js

@@ -67,6 +67,10 @@ export class Broker {
     setPersonActive(userId, active) {
         return this.call('POST', active ? '/people/reactivate' : '/people/deactivate', { userId });
     }
+    /** An admin's reset for somebody requestPasswordReset cannot get back in: see `Auth['adminResetPassword']`. */
+    adminResetPassword(userId) {
+        return this.call('POST', '/people/reset-password', { userId });
+    }
     authRequest(id) {
         return this.call('GET', '/auth-request', { id });
     }

package/dist/config.d.ts

@@ -19,6 +19,11 @@ export type AuthEvent = {
     email: string;
     userId: string;
     invited: boolean;
+}
+/** Never the password: an audit record of who was reset, not a copy of the credential. */
+ | {
+    type: 'adminResetPassword';
+    userId: string;
 };
 /**
  * Why `accessToken` refused: no session (no cookie in cookie mode, no live

package/dist/next.d.ts

@@ -95,14 +95,18 @@ export interface NextAuth {
         givenName: string;
         familyName: string;
         next?: string;
+        personalEmail?: string;
     }) => Promise<{
         userId: string;
         invited: boolean;
+        personalEmailStored: boolean;
     }>;
     /** The organisation's people, for an operator surface. Scoped to this app's organisation by the service. */
     people: Auth['people'];
     /** Deactivate or reactivate somebody in this app's organisation. */
     setPersonActive: Auth['setPersonActive'];
+    /** An admin's reset for somebody in this app's organisation whom requestPasswordReset cannot otherwise get back in. */
+    adminResetPassword: Auth['adminResetPassword'];
     /** The devices page: the signed-in person's own live sessions, newest first. Namespace mode only. */
     sessions: () => Promise<SessionRecord[]>;
     /**

package/dist/next.js

@@ -272,6 +272,7 @@ export function nextAuth(options) {
         invite: auth.invite,
         people: auth.people,
         setPersonActive: auth.setPersonActive,
+        adminResetPassword: auth.adminResetPassword,
         sessions: sessionsList,
         endSession,
         resetPassword,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/auth",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Sign in against a self-hosted ZITADEL issuer: a server session for a Next.js app, and a browser client with silent single sign-on across subdomains.",
   "repository": {
     "type": "git",