@wtfalch/auth 0.22.0 → 0.24.0

package/dist/auth.d.ts

@@ -323,7 +323,7 @@ export interface Auth {
      * `maxAge` becomes OIDC `max_age`: the issuer re-authenticates anybody whose
      * last authentication is older than that many seconds.
      */
-    startUrl(next?: string | null, intent?: Intent, prompt?: Prompt, maxAge?: MaxAge): string;
+    startUrl(next?: string | null, intent?: Intent, prompt?: Prompt, maxAge?: MaxAge, loginHint?: string): string;
     /**
      * Whether `user` authenticated within `maxAge` seconds. A user with no
      * `authTime` is never fresh: the issuer only has to send the claim when the

package/dist/auth.js

@@ -6,7 +6,7 @@ import { clearQrTransaction, clearSession, clearTransaction, cookieFrom, openQrT
 import { namespaceSessions } from './namespace-session.js';
 import { AuthError, ORG_CLAIM, Oidc, isOAuthRefusal, scopeFor } from './oidc.js';
 import { pollDeviceToken, requestDeviceAuthorization } from './qr.js';
-import { safeNextPath } from './redirect.js';
+import { safeLoginHint, 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;
@@ -94,7 +94,7 @@ export function createAuth(input) {
             .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', prompt, maxAge) => {
+    const startUrl = (next, intent = 'login', prompt, maxAge, loginHint) => {
         const url = new URL(`${options().basePath}/start`, options().appUrl);
         const path = safeNextPath(next, '');
         if (path)
@@ -107,6 +107,9 @@ export function createAuth(input) {
             assertMaxAge(maxAge);
             url.searchParams.set('max_age', String(maxAge));
         }
+        const hint = safeLoginHint(loginHint);
+        if (hint)
+            url.searchParams.set('login_hint', hint);
         return url.href;
     };
     const fresh = (user, maxAge) => {
@@ -128,7 +131,8 @@ export function createAuth(input) {
         const silent = (await openSilent(options(), cookieFrom(request.headers.get('cookie'), silentCookieName(options())))) === 'try' &&
             !params.has('intent') &&
             !params.has('prompt') &&
-            !params.has('max_age');
+            !params.has('max_age') &&
+            !params.has('login_hint');
         const state = client.randomState();
         const nonce = client.randomNonce();
         const codeVerifier = client.randomPKCECodeVerifier();
@@ -136,6 +140,7 @@ export function createAuth(input) {
             create: params.get('intent') === 'register',
             prompt: silent ? 'none' : promptFrom(params.get('prompt')),
             maxAge: maxAgeFrom(params.get('max_age')),
+            loginHint: safeLoginHint(params.get('login_hint')),
         });
         const transaction = await sealTransaction(options(), {
             st: state,
@@ -503,7 +508,9 @@ export function createAuth(input) {
         return { location: new URL(next, options().appUrl).href, cookies: [cookie] };
     };
     const hostedUrl = (id) => {
-        const url = new URL('/login', options().namespace?.loginOrigin ?? options().issuer);
+        const url = options().namespace
+            ? new URL('/login', options().namespace?.loginOrigin)
+            : new URL('login', options().signInBase);
         url.searchParams.set('authRequest', id);
         return url.href;
     };

package/dist/browser.d.ts

@@ -160,7 +160,9 @@ export interface BrowserAuth {
     trySilentSignIn(returnTo?: string): Promise<boolean>;
     /** Leave for the issuer, expecting to be asked for credentials. Does not
      *  return. */
-    signIn(returnTo?: string): Promise<void>;
+    signIn(returnTo?: string, opts?: {
+        loginHint?: string;
+    }): Promise<void>;
     /** Finish the flow at the callback path. */
     completeSignIn(search?: string): Promise<SignInOutcome>;
     /**

package/dist/browser.js

@@ -1,4 +1,5 @@
 import { createNamespaceBrowserAuth } from './namespace-browser.js';
+import { safeLoginHint } from './redirect.js';
 const TOKEN = 'wtfalch.auth.token';
 const VERIFIER = 'wtfalch.auth.verifier';
 /** CSRF protection on the callback: checked before the code exchange, never persisted past it. */
@@ -137,7 +138,7 @@ export function createBrowserAuth(options) {
         error: 'This refresh was cancelled',
     });
     const open = options.open ?? ((url) => window.location.assign(url));
-    const authorize = async (prompt, returnTo) => {
+    const authorize = async (prompt, returnTo, loginHint) => {
         const generation = ++coordinator.generation;
         const proof = verifier();
         const state = verifier();
@@ -175,6 +176,9 @@ export function createBrowserAuth(options) {
         url.searchParams.set('nonce', nonce);
         if (prompt)
             url.searchParams.set('prompt', prompt);
+        const hint = safeLoginHint(loginHint);
+        if (hint)
+            url.searchParams.set('login_hint', hint);
         if (!current(generation))
             return false;
         await open(url.toString());
@@ -261,8 +265,8 @@ export function createBrowserAuth(options) {
                 return false;
             return authorize('none', returnTo);
         },
-        async signIn(returnTo = window.location.pathname) {
-            await authorize(undefined, returnTo);
+        async signIn(returnTo = window.location.pathname, opts) {
+            await authorize(undefined, returnTo, opts?.loginHint);
         },
         async completeSignIn(search = window.location.search) {
             const generation = coordinator.generation;

package/dist/config.d.ts

@@ -93,6 +93,15 @@ export interface AuthOptions {
     cookieSecret?: string | undefined;
     /** e.g. https://auth.example.com. Required -- there is no estate-wide default. */
     issuer: string | undefined;
+    /**
+     * Where the hosted login lives, when it is not at the issuer's origin: an
+     * app that proxies the login under its own address passes e.g.
+     * `https://agora.example.com/sign-in`, and the hosted login URL becomes
+     * `https://agora.example.com/sign-in/login`. https, or http for localhost
+     * only; no query, fragment or credentials. Default: the issuer's origin,
+     * which is what the SDK has always used.
+     */
+    signInBase?: string;
     /** Where the routes are mounted. Default /auth. */
     basePath?: string;
     /** Default /. */
@@ -147,6 +156,8 @@ export interface ResolvedOptions {
      */
     readonly cookieKey: Uint8Array;
     issuer: string;
+    /** Absolute, always ends with "/": `new URL('login', signInBase)` is the hosted login. */
+    signInBase: string;
     basePath: string;
     afterLogin: string;
     afterLogout: string;

package/dist/config.js

@@ -47,6 +47,7 @@ export function resolveOptions(options) {
             return cookieKey;
         },
         issuer,
+        signInBase: parseSignInBase(options.signInBase, issuer),
         basePath,
         afterLogin: options.afterLogin ?? '/',
         afterLogout: options.afterLogout ?? '/',
@@ -91,6 +92,25 @@ function parseAppUrl(raw) {
     }
     return url;
 }
+function parseSignInBase(raw, issuer) {
+    if (raw === undefined)
+        return `${new URL(issuer).origin}/`;
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error(`@wtfalch/auth: signInBase must be an absolute URL, got "${raw}"`);
+    }
+    const local = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && local)) {
+        throw new Error(`@wtfalch/auth: signInBase must be https (http only for localhost), got "${raw}"`);
+    }
+    if (raw.includes('?') || raw.includes('#') || url.username || url.password) {
+        throw new Error(`@wtfalch/auth: signInBase takes no query, fragment or credentials, got "${raw}"`);
+    }
+    return url.href.endsWith('/') ? url.href : `${url.href}/`;
+}
 function decodeKey(secret) {
     required(secret, 'cookieSecret');
     let bytes = new Uint8Array(0);

package/dist/index.d.ts

@@ -5,4 +5,4 @@ export type { SessionRecord, SessionStore, SessionUpdate } from './sessions.js';
 export type { PersonTokenConfig, PersonTokenVerifier } from './person-token.js';
 export { BrokerError } from './broker.js';
 export { AuthError, type AuthErrorReason, ORG_CLAIM } from './oidc.js';
-export { safeNextPath } from './redirect.js';
+export { safeLoginHint, safeNextPath } from './redirect.js';

package/dist/index.js

@@ -1,4 +1,4 @@
 export { STEP_UP_MAX_AGE, createAuth, } from './auth.js';
 export { BrokerError } from './broker.js';
 export { AuthError, ORG_CLAIM } from './oidc.js';
-export { safeNextPath } from './redirect.js';
+export { safeLoginHint, safeNextPath } from './redirect.js';

package/dist/names.d.ts

@@ -38,6 +38,14 @@ export interface NameRules {
     pattern: RegExp;
 }
 export declare const DEFAULT_RULES: NameRules;
+/**
+ * Lowercase letters with the digits read as letters and nothing else, runs
+ * collapsed. Every reading, since `1` may be an `i` or an `l`; the first is
+ * the one a list entry is stored under.
+ */
+export declare function flattenings(name: string): string[];
+/** Every entry checkName holds back: the system names, the people's and the reserved-usernames list, once each. */
+export declare function reservedNames(): readonly string[];
 /** The refusal as a sentence the person can act on. */
 export declare function explain(reason: Refusal, rules?: NameRules): string;
 export declare function checkName(name: string, rules?: NameRules): Verdict;

package/dist/names.js

@@ -35,7 +35,10 @@ strictWords.addPhrase((phrase) => {
         phrase.addWhitelistedTerm(term);
     return phrase;
 });
-const strict = new RegExpMatcher({ ...strictWords.build(), ...englishRecommendedTransformers });
+const strict = new RegExpMatcher({
+    ...strictWords.build(),
+    ...englishRecommendedTransformers,
+});
 /** Only the words that are slurs wherever they appear, read with everything between the letters skipped. */
 const looseWords = new DataSet();
 for (const entry of [
@@ -84,7 +87,7 @@ const LETTERS = {
  * collapsed. Every reading, since `1` may be an `i` or an `l`; the first is
  * the one a list entry is stored under.
  */
-function flattenings(name) {
+export function flattenings(name) {
     let forms = [''];
     for (const char of name.toLowerCase()) {
         const readings = /[a-z]/.test(char) ? [char] : (LETTERS[char] ?? []);
@@ -96,7 +99,12 @@ function flattenings(name) {
     }
     return [...new Set(forms.map((form) => form.replace(/(.)\1+/g, '$1')))];
 }
-const reserved = new Set([...reservedUsernames, ...SYSTEM, ...PEOPLE].map((entry) => flattenings(entry)[0]));
+const RESERVED = [...new Set([...reservedUsernames, ...SYSTEM, ...PEOPLE])];
+const reserved = new Set(RESERVED.map((entry) => flattenings(entry)[0]));
+/** Every entry checkName holds back: the system names, the people's and the reserved-usernames list, once each. */
+export function reservedNames() {
+    return RESERVED;
+}
 /** The name in the shapes a word might hide in. */
 function shapes(name) {
     const parts = name.split(/[^A-Za-z0-9æøåÆØÅ]+/).filter(Boolean);

package/dist/namespace-browser.js

@@ -1,6 +1,6 @@
 import { createRemoteJWKSet, jwtVerify } from 'jose';
 import { resolveNamespaceContext } from './namespaces.js';
-import { safeNextPath } from './redirect.js';
+import { safeLoginHint, safeNextPath } from './redirect.js';
 const OWNER = 'urn:zitadel:iam:user:resourceowner:id';
 const ttl = 10 * 60_000;
 const random = () => base64url(crypto.getRandomValues(new Uint8Array(32)));
@@ -75,7 +75,7 @@ export function createNamespaceBrowserAuth(options, selection) {
             : null;
     };
     const silentSignInAvailable = () => !accountChanged() && !currentSession() && !sessionStorage.getItem(triedKey);
-    const authorize = async (prompt, returnTo) => {
+    const authorize = async (prompt, returnTo, loginHint) => {
         const transaction = {
             context: binding.context,
             state: random(),
@@ -99,6 +99,7 @@ export function createNamespaceBrowserAuth(options, selection) {
             code_challenge: base64url(new Uint8Array(digest)),
             code_challenge_method: 'S256',
             ...(prompt ? { prompt } : {}),
+            ...(safeLoginHint(loginHint) ? { login_hint: safeLoginHint(loginHint) } : {}),
         }).toString();
         if (!ownsPending(transaction.state))
             throw new Error('Another sign-in replaced this attempt');
@@ -220,9 +221,9 @@ export function createNamespaceBrowserAuth(options, selection) {
             await authorize('none', returnTo);
             return true;
         },
-        async signIn(returnTo = window.location.pathname) {
+        async signIn(returnTo = window.location.pathname, opts) {
             sessionStorage.removeItem(triedKey);
-            await authorize(undefined, returnTo);
+            await authorize(undefined, returnTo, opts?.loginHint);
         },
         // Matches BrowserAuth.forget()'s Promise<void> signature; this path's
         // storage is always synchronous, so there is nothing to await.

package/dist/next.d.ts

@@ -49,6 +49,7 @@ export interface NextAuth {
         next?: string;
         intent?: Intent;
         prompt?: Prompt;
+        loginHint?: string;
     }) => Promise<AuthRequest>;
     /** For a server action: redirects into the app on success, returns the error otherwise. */
     signIn: (input: {

package/dist/next.js

@@ -123,7 +123,7 @@ export function nextAuth(options) {
         // Nobody has started a flow yet. This cannot loop: the issuer always
         // sends the browser back carrying an id.
         if (!id)
-            redirect(auth.startUrl(opts.next, opts.intent, opts.prompt));
+            redirect(auth.startUrl(opts.next, opts.intent, opts.prompt, undefined, opts.loginHint));
         try {
             return await auth.authRequest(id);
         }

package/dist/oidc.d.ts

@@ -42,10 +42,11 @@ export declare class Oidc {
     private config;
     private keys;
     get redirectUri(): URL;
-    authorizationUrl(state: string, nonce: string, codeVerifier: string, { create, prompt, maxAge, }?: {
+    authorizationUrl(state: string, nonce: string, codeVerifier: string, { create, prompt, maxAge, loginHint, }?: {
         create?: boolean;
         prompt?: 'select_account' | 'login' | 'none';
         maxAge?: number;
+        loginHint?: string;
     }): Promise<URL>;
     exchange(callbackParams: URLSearchParams, transaction: {
         state: string;

package/dist/oidc.js

@@ -81,10 +81,11 @@ export class Oidc {
     get redirectUri() {
         return new URL(`${this.options.basePath}/callback`, this.options.appUrl);
     }
-    async authorizationUrl(state, nonce, codeVerifier, { create = false, prompt, maxAge, } = {}) {
+    async authorizationUrl(state, nonce, codeVerifier, { create = false, prompt, maxAge, loginHint, } = {}) {
         return client.buildAuthorizationUrl(await this.config(), {
             ...(create ? { prompt: 'create' } : prompt ? { prompt } : {}),
             ...(maxAge === undefined ? {} : { max_age: String(maxAge) }),
+            ...(loginHint ? { login_hint: loginHint } : {}),
             redirect_uri: this.redirectUri.href,
             scope: scopeFor(this.options.organizationId, this.options.extraScopes),
             state,

package/dist/redirect.d.ts

@@ -1,2 +1,9 @@
 /** A path on this app, or the fallback. Refuses absolute, scheme-relative and backslash forms. */
 export declare function safeNextPath(next: string | null | undefined, fallback: string): string;
+/**
+ * An email address fit to send as the OIDC `login_hint`: at most 254
+ * characters, one `@`, a dotted domain, no whitespace or control characters.
+ * Anything else is `undefined` -- a bad hint is dropped, never a failure,
+ * because the person can still type their address at the issuer.
+ */
+export declare function safeLoginHint(raw: string | null | undefined): string | undefined;

package/dist/redirect.js

@@ -21,3 +21,14 @@ export function safeNextPath(next, fallback) {
     }
     return path;
 }
+/**
+ * An email address fit to send as the OIDC `login_hint`: at most 254
+ * characters, one `@`, a dotted domain, no whitespace or control characters.
+ * Anything else is `undefined` -- a bad hint is dropped, never a failure,
+ * because the person can still type their address at the issuer.
+ */
+export function safeLoginHint(raw) {
+    if (typeof raw !== 'string' || raw.length > 254)
+        return undefined;
+    return /^[^\s@\p{Cc}]+@[^\s@\p{Cc}]+\.[^\s@\p{Cc}]+$/u.test(raw) ? raw : undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/auth",
-  "version": "0.22.0",
+  "version": "0.24.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",