@ultimat3/auth 27.3.0 → 27.5.0

package/CLAUDE.md

@@ -33,6 +33,7 @@ Tier 2. Produces the `Actor`; produces nothing else. Authorization is `@ultimat3
   `password.test.ts` proves an unreadable hash burns the KDF. A TTL takes `min: 1`.
 - Every credential failure throws `loginFailed()` — one code, one cause, one fix. Adding a
   parameter to it re-opens account enumeration.
+- **`login()` takes an email or a handle** (`login-identity.ts`, `defineAuth({ handles })`).
 - **A stored hash Bun cannot read is the generic failure, and it burns the same KDF.**
   `verifyAgainst` (`password.ts`) answers `null` for `Bun.password.verify`'s throw (unsupported
   algorithm, malformed PHC) and `''`, joining the no-user branch; nothing is logged. An

package/README.md

@@ -18,6 +18,10 @@ export const auth = defineAuth({
 
 const { actor, token, cookie } = await login(auth, { email, password, ip });
 
+// Or by handle, for an app whose users are `@ada`: `defineAuth({ handles })` names the lookup from
+// a normalised handle to the auth user's id, and `register(auth, { id, ... })` links the two rows.
+const byHandle = await login(auth, { handle: 'ada', password, ip });
+
 // "Log in with GitHub" is a link to /auth/oauth/github. These two routes are what serves it.
 const { start, callback } = oauthLogin(auth);
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/auth",
-  "version": "27.3.0",
+  "version": "27.5.0",
   "description": "Sessions, passwords, OAuth, MFA and api keys — resolved to one Actor",
   "license": "MIT",
   "type": "module",
@@ -32,8 +32,8 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "27.3.0",
-    "@ultimat3/db": "27.3.0",
-    "@ultimat3/schema": "27.3.0"
+    "@ultimat3/core": "27.5.0",
+    "@ultimat3/db": "27.5.0",
+    "@ultimat3/schema": "27.5.0"
   }
 }

package/src/auth.ts

@@ -10,6 +10,7 @@ import { normaliseEmail } from './email';
 import { mfaRequiredUnenforceable, sessionUnknown } from './errors';
 import { installedAuthLimiter } from './limiter-install';
 import { openLoginAttempt } from './login-attempt';
+import { type HandleDirectory, loginIdentity } from './login-identity';
 import { memoryTotpReplayGuard, type TotpReplayGuard } from './mfa';
 import { mfaChallengeRequired } from './mfa-challenge';
 import type { OAuthProviderId } from './oauth';
@@ -25,7 +26,6 @@ import { assertPasswordPolicy, assertRateLimitPolicy, assertSessionPolicy } from
 import {
   type AuthLimiter,
   type AuthRateLimitPolicy,
-  accountKey,
   assertAuthLimiterPolicy,
   DEFAULT_AUTH_RATE_LIMIT,
   loginFailed,
@@ -162,6 +162,13 @@ export interface AuthConfigInput {
   readonly providers?: readonly OAuthProviderId[] | undefined;
   /** Defaults to `'verified-email'` — both halves proven. See `OAuthLinkPolicy`. */
   readonly link?: OAuthLinkPolicy | undefined;
+  /**
+   * How `login(auth, { handle })` finds its user: the app's lookup from a normalised handle to the
+   * auth user's id. Absent means logins are by email only, and a handle login is refused
+   * (`X_CONFIG_INVALID`). For an app that keeps handles in a table of its own, linked to `x_users`
+   * by id — `register(auth, { id })` creates the auth user under the app's id.
+   */
+  readonly handles?: HandleDirectory | undefined;
 }
 
 export interface Auth {
@@ -178,6 +185,7 @@ export interface Auth {
   readonly totpReplay: TotpReplayGuard;
   readonly providers: readonly OAuthProviderId[];
   readonly link: OAuthLinkPolicy;
+  readonly handles?: HandleDirectory | undefined;
 }
 
 export function defineAuth(config: AuthConfigInput): Auth {
@@ -245,10 +253,16 @@ export function defineAuth(config: AuthConfigInput): Auth {
     // to be.
     providers: config.providers ?? [],
     link: config.link ?? 'verified-email',
+    ...(config.handles === undefined ? {} : { handles: config.handles }),
   });
 }
 
 export interface RegisterInput {
+  /**
+   * The user's id, when the app already chose one — its own `users` row's, so the two link by id.
+   * Omit it and one is minted.
+   */
+  readonly id?: string | undefined;
   readonly email: string;
   readonly password: string;
   readonly orgId?: string | null | undefined;
@@ -259,7 +273,7 @@ export interface RegisterInput {
 export async function register(auth: Auth, input: RegisterInput): Promise<AuthUser> {
   checkPasswordStrength(input.password, { policy: auth.password });
   return await auth.adapter.createUser({
-    id: uuidV7(auth.clock),
+    id: input.id ?? uuidV7(auth.clock),
     email: normaliseEmail(input.email),
     passwordHash: await hashPassword(input.password, auth.password.params),
     orgId: input.orgId ?? null,
@@ -268,13 +282,22 @@ export async function register(auth: Auth, input: RegisterInput): Promise<AuthUs
   });
 }
 
-export interface LoginInput {
-  readonly email: string;
+interface LoginCredentials {
   readonly password: string;
   readonly ip?: string | null | undefined;
   readonly userAgent?: string | null | undefined;
 }
 
+/**
+ * By email, or by handle when `defineAuth({ handles })` names the lookup — one or the other, and
+ * every failure of either is the same `loginFailed()`.
+ */
+export type LoginInput = LoginCredentials &
+  (
+    | { readonly email: string; readonly handle?: undefined }
+    | { readonly handle: string; readonly email?: undefined }
+  );
+
 export interface LoginResult {
   readonly actor: PolicyActor;
   readonly session: AuthSession;
@@ -294,12 +317,13 @@ export interface LoginResult {
  */
 export async function login(auth: Auth, input: LoginInput): Promise<LoginResult> {
   const ip = input.ip ?? null;
-  const attempt = await openLoginAttempt(auth, accountKey(input.email), ip);
+  const identity = loginIdentity(auth, input);
+  const attempt = await openLoginAttempt(auth, identity.key, ip);
 
   let user: AuthUser | null;
   let verification: Awaited<ReturnType<typeof verifyPassword>>;
   try {
-    user = await auth.adapter.findUserByEmail(normaliseEmail(input.email));
+    user = await identity.find();
     // The tenant bucket can only be joined once the address resolves to an org, which is still
     // before the KDF runs — the expensive half of this function — and it caps a spray that
     // per-IP and per-account buckets both let through.

package/src/errors.ts

@@ -254,6 +254,18 @@ export const mfaRequiredUnenforceable = (): AuthError =>
     fix: 'drop required from defineAuth({ mfa }) and gate it in your own sign-in handler, which is where the enrolment route lives: if (user.mfaSecret === null) send them to enrolTotp(auth, { account: user.email }) instead of createSession(auth.sessions, ...)',
   });
 
+/**
+ * `login(auth, { handle })` on an app whose `defineAuth` named no `handles` lookup. Refused before
+ * any bucket is reserved or any hash run: this is a wiring fault, never a failed guess.
+ */
+export const handlesUndeclared = (): AuthError =>
+  new AuthError({
+    code: 'X_CONFIG_INVALID',
+    cause:
+      'login() was handed a handle, and defineAuth declared no handles lookup to resolve one to a user',
+    fix: 'defineAuth({ adapter, handles: async (handle) => (await db.users.where({ handle }).one())?.id ?? null })',
+  });
+
 /**
  * A policy NUMBER that is not one, refused where `defineAuth` still names the key.
  *

package/src/index.ts

@@ -123,6 +123,8 @@ export type { AuthLimiterFactory } from './limiter-install';
 // `installedAuthLimiter` is deliberately absent: `defineAuth` is the one reader, and a second
 // caller building limiters out of band would be a second answer to where failures are counted.
 export { configureAuthLimiters, purgeAuthLimits, resetAuthLimiters } from './limiter-install';
+export type { HandleDirectory } from './login-identity';
+export { normaliseHandle } from './login-identity';
 export { type MemoryAuthAdapter, memoryAuthAdapter } from './memory-adapter';
 export type {
   EnrolTotpInput,

package/src/login-identity.ts

@@ -0,0 +1,42 @@
+// Single responsibility: which account a login names — an email, or a handle an app resolves
+// through `defineAuth({ handles })` — as the bucket key its failures count against and the lookup
+// that finds the user. Both spellings normalise before either is used, so a bucket keyed one way
+// and a row found another cannot hand a sprayer a fresh budget per spelling.
+
+import type { AuthUser } from './adapter';
+import type { Auth, LoginInput } from './auth';
+import { normaliseEmail } from './email';
+import { handlesUndeclared } from './errors';
+import { accountKey } from './rate-limit';
+
+/** An app's lookup from a normalised handle to the auth user's id, or `null` for nobody. */
+export type HandleDirectory = (handle: string) => Promise<string | null>;
+
+/**
+ * Trim, then lowercase: a handle differing only in case or surrounding space is one account. The
+ * app's lookup receives this form, so its table must store handles the same way.
+ */
+export const normaliseHandle = (handle: string): string => handle.trim().toLowerCase();
+
+export interface LoginIdentity {
+  /** The ACCOUNT bucket — prefixed apart from an email's, so the two namespaces never meet. */
+  readonly key: string;
+  readonly find: () => Promise<AuthUser | null>;
+}
+
+export function loginIdentity(auth: Auth, input: LoginInput): LoginIdentity {
+  if (input.handle === undefined) {
+    const email = normaliseEmail(input.email);
+    return { key: accountKey(email), find: () => auth.adapter.findUserByEmail(email) };
+  }
+  const handles = auth.handles;
+  if (handles === undefined) throw handlesUndeclared();
+  const handle = normaliseHandle(input.handle);
+  return {
+    key: `account-handle:${handle}`,
+    async find() {
+      const id = await handles(handle);
+      return id === null ? null : await auth.adapter.findUserById(id);
+    },
+  };
+}