@zudojs/auth 1.2.1 → 1.3.0

package/README.md

@@ -126,8 +126,22 @@ logout can revoke them. **The service therefore rejects a token without a
 Accepting them by default let a session-less refresh chain outlive
 `logoutAll()`.
 
+### Login identifiers
+
+`login()` normalizes the identifier before `findUser()` sees it: NFKC, trim,
+and lower-case when it is an email address (a username keeps its case). So
+`" Alice@Example.COM"` finds the account stored as `alice@example.com`, and
+case variants share one lockout budget. Store identifiers through the same
+exported `normalizeLoginIdentifier()` at registration. Pass
+`normalizeIdentifier: false` to receive the raw string, or your own function.
+
 ### Brute-force lockout
 
+A locked identifier gets `AccountLockedError` (`423`, `ERR_ACCOUNT_LOCKED`)
+with `retryAfterSeconds` set to the time left on the lockout and a
+`Retry-After` header in `error.headers`, which `@zudojs/http` copies onto the
+response. `AuthRateLimitError` (`429`) carries `Retry-After` the same way.
+
 A failure is reserved *before* the password is checked and cleared on
 success, so a parallel burst gets exactly `maxFailedAttempts` guesses before
 the lockout, not `maxAttemptsPerWindow`. Custom `LoginAttemptStore`s must make
@@ -143,6 +157,36 @@ unlocked failure streak after `failureTtlSeconds` of inactivity (default 900)
 and caps the tracked identifiers at `maxEntries` (default 100 000, oldest
 unlocked evicted first), so spraying identifiers cannot grow it without bound.
 
+### Sessions for OAuth and other sign-ins
+
+A user authenticated some other way — the OAuth callback of
+[`@zudojs/auth-oauth`](../auth-oauth), a passkey, a magic link — gets a
+session and tokens from `createSessionForUser()`, exactly as `login()` would
+issue them, without a password check:
+
+```typescript
+const auth = createAuthService({
+  /* … */
+  externalSessionMethods: ["oauth"], // off by default
+});
+
+// In the OAuth callback, after state/PKCE were verified and the provider
+// identity was mapped to one of your users:
+const { tokens, sessionId } = await auth.createSessionForUser(user.id, {
+  method: "oauth",
+  metadata: { provider: "github" }, // stored on the session
+  ip: req.socket.remoteAddress,
+});
+```
+
+It checks no credential — your code asserts the user is authenticated — so
+it throws `AuthConfigurationError` unless the `method` is listed in
+`externalSessionMethods`. It still loads the user with `findUserById()` and
+refuses an unknown user (`InvalidCredentialsError`) or a deactivated one
+(`AccountDeactivatedError`). **Never pass it a user id taken from the
+request.** The session records `metadata.authMethod`, and `logout()` /
+`logoutAll()` revoke it like any other.
+
 ### Refresh-token rotation
 
 With a `revocationStore` configured, `refresh()` claims the presented token's
@@ -163,8 +207,11 @@ const decision = await auth.checkAccess({
 });
 ```
 
-When a `permissions` engine is configured the decision comes from it. When it
-is not, `checkAccess()` **throws** `AuthConfigurationError` rather than
+When a `permissions` engine is configured the decision comes from it, with
+`resourceOwnerId` passed as the resource `{ ownerId }`. An ownership policy
+that should grant on its own must say `effect: "grant"` — since
+`@zudojs/permissions` 1.4 an allowing policy only constrains what the roles
+grant. When it is not, `checkAccess()` **throws** `AuthConfigurationError` rather than
 guessing. Setting `allowInsecureFallbackGuard: true` opts into a built-in
 fallback that grants a resource owner *every* permission and grants the
 `fallbackAdminRole` (default `"admin"`) everything; its allowed results carry
@@ -210,7 +257,9 @@ with OWASP's N=2^14, r=8, p=5 row. Hashes written by earlier versions of this
 package (`scrypt$N$r$p$…`, including the p=1 default and the param-less legacy
 format) still verify, and `needsRehash()` returns `true` for every hash that is
 not a current-parameter `@zudojs/crypto` scrypt hash, so they upgrade on the
-next login. `hashPassword("")` throws `AuthError` (`INVALID_INPUT`).
+next login. A hash made by `@zudojs/crypto`'s own `hashPassword()` with its
+defaults (same N, r, p; 16-byte salt, 32-byte key) is current too, and
+`needsRehash()` returns `false` for it. `hashPassword("")` throws `AuthError` (`INVALID_INPUT`).
 
 - `createAuthService()` validates its configuration up front: bad or
   identical secrets, a non-positive or `NaN` `sessionTtlSeconds` /
@@ -244,23 +293,25 @@ throw.
 
 Every error carries an accurate HTTP status and is safe to expose:
 
-| Error | Status | Category |
-| --- | --- | --- |
-| `AuthError` | 401 | authentication |
-| `InvalidCredentialsError` | 401 | authentication |
-| `TokenExpiredError` | 401 | authentication |
-| `TokenInvalidError` | 401 | authentication |
-| `SessionExpiredError` | 401 | authentication |
-| `TokenRevokedError` | 403 | authorization |
-| `AccountDeactivatedError` | 403 | authorization |
-| `AccessDeniedError` | 403 | authorization |
-| `AccountLockedError` | 423 | rate_limit |
-| `AuthRateLimitError` | 429 | rate_limit |
-| `AuthConfigurationError` | 500 | configuration (not exposed) |
-
-`AccountLockedError` and `AuthRateLimitError` carry
-`metadata.retryAfterSeconds` for a `Retry-After` header; `AccessDeniedError`
-carries `metadata.requiredPermission`.
+| Error | Status | Code | Category |
+| --- | --- | --- | --- |
+| `AuthError` | 401 | `ERR_AUTHENTICATION` | authentication |
+| `InvalidCredentialsError` | 401 | `ERR_INVALID_CREDENTIALS` | authentication |
+| `TokenExpiredError` | 401 | `ERR_TOKEN_EXPIRED` | authentication |
+| `TokenInvalidError` | 401 | `ERR_TOKEN_INVALID` | authentication |
+| `TokenRevokedError` | 401 | `ERR_TOKEN_REVOKED` | authentication |
+| `SessionExpiredError` | 401 | `ERR_SESSION_EXPIRED` | authentication |
+| `AccountDeactivatedError` | 403 | `ERR_ACCOUNT_DEACTIVATED` | authorization |
+| `AccessDeniedError` | 403 | `ERR_ACCESS_DENIED` | authorization |
+| `AccountLockedError` | 423 | `ERR_ACCOUNT_LOCKED` | rate_limit |
+| `AuthRateLimitError` | 429 | `ERR_RATE_LIMITED` | rate_limit |
+| `AuthConfigurationError` | 500 | `ERR_CONFIGURATION_INVALID` | configuration (not exposed) |
+
+`AccountLockedError` and `AuthRateLimitError` carry `retryAfterSeconds` (also
+in `metadata`) and a `Retry-After` header in `headers`; `AccessDeniedError`
+carries `metadata.requiredPermission`. Before 1.3, `TokenRevokedError` was
+`403 ERR_FORBIDDEN`, and the lockout and deactivation errors shared
+`ERR_FORBIDDEN` too, so a client could not tell them apart.
 
 `login()` throws the same `InvalidCredentialsError` for an unknown user and a
 wrong password, and performs equivalent scrypt work on both paths, so the
@@ -273,7 +324,8 @@ after the password has been proven correct.
   [`@zudojs/auth-oauth`](../auth-oauth), which implements the
   authorization-code flow with PKCE, mandatory `state`, and provider presets
   for Google, GitHub, Microsoft, Apple and Discord. Nothing OAuth-related is
-  exported from this package any more.
+  exported from this package any more; once the callback has identified the
+  user, `createSessionForUser()` issues the session.
 - **No password-reset flow.** `generateRandomToken()` gives you a random
   token; storage, expiry, single-use enforcement and constant-time comparison
   are yours to build.

package/dist/authErrors/authError.base.d.ts

@@ -45,22 +45,16 @@ export declare class TokenInvalidError extends AuthError {
     constructor(message?: string, options?: AuthErrorOptions);
 }
 /**
- * Token has been revoked.
+ * Token has been revoked (logout, or a refresh token replayed after
+ * rotation).
+ *
+ * `401` with `ERR_TOKEN_REVOKED`: the credential is no longer valid, so the
+ * client must authenticate again. It was `403 ERR_FORBIDDEN`, which told a
+ * client that re-authenticating would not help.
  */
 export declare class TokenRevokedError extends AuthError {
     constructor(message?: string, options?: AuthErrorOptions);
 }
-/**
- * User account is locked (too many failed attempts).
- *
- * `423 Locked`; `metadata.retryAfterSeconds` is intended for a `Retry-After`
- * response header.
- */
-export declare class AccountLockedError extends AuthError {
-    constructor(message?: string, options?: AuthErrorOptions & {
-        readonly retryAfterSeconds?: number;
-    });
-}
 /**
  * User account is deactivated.
  */
@@ -81,12 +75,4 @@ export declare class AccessDeniedError extends AuthError {
 export declare class SessionExpiredError extends AuthError {
     constructor(message?: string, options?: AuthErrorOptions);
 }
-/**
- * Rate limit exceeded for an auth endpoint.
- */
-export declare class AuthRateLimitError extends AuthError {
-    constructor(message?: string, options?: AuthErrorOptions & {
-        readonly retryAfterSeconds?: number;
-    });
-}
 //# sourceMappingURL=authError.base.d.ts.map

package/dist/authErrors/authError.base.js

@@ -73,46 +73,29 @@ export class TokenInvalidError extends AuthError {
     }
 }
 /**
- * Token has been revoked.
+ * Token has been revoked (logout, or a refresh token replayed after
+ * rotation).
+ *
+ * `401` with `ERR_TOKEN_REVOKED`: the credential is no longer valid, so the
+ * client must authenticate again. It was `403 ERR_FORBIDDEN`, which told a
+ * client that re-authenticating would not help.
  */
 export class TokenRevokedError extends AuthError {
     constructor(message = "Token has been revoked", options) {
         super(message, {
-            code: ErrorCode.FORBIDDEN,
-            category: ErrorCategory.AUTHORIZATION,
-            statusCode: 403,
+            code: ErrorCode.TOKEN_REVOKED,
+            statusCode: 401,
             ...options,
         });
     }
 }
-/**
- * User account is locked (too many failed attempts).
- *
- * `423 Locked`; `metadata.retryAfterSeconds` is intended for a `Retry-After`
- * response header.
- */
-export class AccountLockedError extends AuthError {
-    constructor(message = "Account is locked due to too many failed attempts", options) {
-        const { retryAfterSeconds, metadata, ...rest } = options ?? {};
-        super(message, {
-            code: ErrorCode.FORBIDDEN,
-            category: ErrorCategory.RATE_LIMIT,
-            statusCode: 423,
-            ...rest,
-            metadata: {
-                retryAfterSeconds: retryAfterSeconds ?? 900,
-                ...metadata,
-            },
-        });
-    }
-}
 /**
  * User account is deactivated.
  */
 export class AccountDeactivatedError extends AuthError {
     constructor(message = "User account is deactivated", options) {
         super(message, {
-            code: ErrorCode.FORBIDDEN,
+            code: ErrorCode.ACCOUNT_DEACTIVATED,
             category: ErrorCategory.AUTHORIZATION,
             statusCode: 403,
             ...options,
@@ -149,22 +132,4 @@ export class SessionExpiredError extends AuthError {
         });
     }
 }
-/**
- * Rate limit exceeded for an auth endpoint.
- */
-export class AuthRateLimitError extends AuthError {
-    constructor(message = "Too many authentication attempts", options) {
-        const { retryAfterSeconds, metadata, ...rest } = options ?? {};
-        super(message, {
-            code: ErrorCode.RATE_LIMITED,
-            category: ErrorCategory.RATE_LIMIT,
-            statusCode: 429,
-            ...rest,
-            metadata: {
-                retryAfterSeconds: retryAfterSeconds ?? 60,
-                ...metadata,
-            },
-        });
-    }
-}
 //# sourceMappingURL=authError.base.js.map

package/dist/authErrors/authError.throttle.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Throttling errors: lockout and rate limit.
+ *
+ * Both carry `retryAfterSeconds` and a `Retry-After` header in `headers`.
+ * `@zudojs/http` copies an error's `headers` onto the response it answers
+ * the error with, so a client told `423 Locked` or `429 Too Many Requests`
+ * also learns when to try again; the lockout used to go out without one.
+ *
+ * @module authErrors/authError.throttle
+ */
+import { AuthError, type AuthErrorOptions } from "@zudojs/errors";
+/** Options shared by the throttling errors. */
+export type ThrottleErrorOptions = AuthErrorOptions & {
+    /** Seconds until the client may retry. Rounded up; at least 1. */
+    readonly retryAfterSeconds?: number;
+};
+/**
+ * User account is locked (too many failed attempts).
+ *
+ * `423 Locked`, code `ERR_ACCOUNT_LOCKED`. `retryAfterSeconds` is the time
+ * left on the lockout, and `headers` carries it as `Retry-After`.
+ */
+export declare class AccountLockedError extends AuthError {
+    /** Seconds until the lockout lapses. */
+    readonly retryAfterSeconds: number;
+    /** Response headers for this error: `Retry-After`. */
+    readonly headers: Readonly<Record<string, string>>;
+    constructor(message?: string, options?: ThrottleErrorOptions);
+}
+/**
+ * Rate limit exceeded for an auth endpoint.
+ *
+ * `429 Too Many Requests`; `headers` carries `Retry-After`.
+ */
+export declare class AuthRateLimitError extends AuthError {
+    /** Seconds until the window resets. */
+    readonly retryAfterSeconds: number;
+    /** Response headers for this error: `Retry-After`. */
+    readonly headers: Readonly<Record<string, string>>;
+    constructor(message?: string, options?: ThrottleErrorOptions);
+}
+//# sourceMappingURL=authError.throttle.d.ts.map

package/dist/authErrors/authError.throttle.js

@@ -0,0 +1,69 @@
+/**
+ * Throttling errors: lockout and rate limit.
+ *
+ * Both carry `retryAfterSeconds` and a `Retry-After` header in `headers`.
+ * `@zudojs/http` copies an error's `headers` onto the response it answers
+ * the error with, so a client told `423 Locked` or `429 Too Many Requests`
+ * also learns when to try again; the lockout used to go out without one.
+ *
+ * @module authErrors/authError.throttle
+ */
+import { AuthError, ErrorCategory, ErrorCode, } from "@zudojs/errors";
+function toRetryAfter(value, fallback) {
+    if (value === undefined || !Number.isFinite(value))
+        return fallback;
+    return Math.max(1, Math.ceil(value));
+}
+function retryAfterHeaders(seconds) {
+    return Object.freeze({ "retry-after": String(seconds) });
+}
+/**
+ * User account is locked (too many failed attempts).
+ *
+ * `423 Locked`, code `ERR_ACCOUNT_LOCKED`. `retryAfterSeconds` is the time
+ * left on the lockout, and `headers` carries it as `Retry-After`.
+ */
+export class AccountLockedError extends AuthError {
+    /** Seconds until the lockout lapses. */
+    retryAfterSeconds;
+    /** Response headers for this error: `Retry-After`. */
+    headers;
+    constructor(message = "Account is locked due to too many failed attempts", options) {
+        const { retryAfterSeconds, metadata, ...rest } = options ?? {};
+        const seconds = toRetryAfter(retryAfterSeconds, 900);
+        super(message, {
+            code: ErrorCode.ACCOUNT_LOCKED,
+            category: ErrorCategory.RATE_LIMIT,
+            statusCode: 423,
+            ...rest,
+            metadata: { retryAfterSeconds: seconds, ...metadata },
+        });
+        this.retryAfterSeconds = seconds;
+        this.headers = retryAfterHeaders(seconds);
+    }
+}
+/**
+ * Rate limit exceeded for an auth endpoint.
+ *
+ * `429 Too Many Requests`; `headers` carries `Retry-After`.
+ */
+export class AuthRateLimitError extends AuthError {
+    /** Seconds until the window resets. */
+    retryAfterSeconds;
+    /** Response headers for this error: `Retry-After`. */
+    headers;
+    constructor(message = "Too many authentication attempts", options) {
+        const { retryAfterSeconds, metadata, ...rest } = options ?? {};
+        const seconds = toRetryAfter(retryAfterSeconds, 60);
+        super(message, {
+            code: ErrorCode.RATE_LIMITED,
+            category: ErrorCategory.RATE_LIMIT,
+            statusCode: 429,
+            ...rest,
+            metadata: { retryAfterSeconds: seconds, ...metadata },
+        });
+        this.retryAfterSeconds = seconds;
+        this.headers = retryAfterHeaders(seconds);
+    }
+}
+//# sourceMappingURL=authError.throttle.js.map

package/dist/authErrors/index.d.ts

@@ -3,5 +3,6 @@
  *
  * @module authErrors
  */
-export { AuthError, type AuthErrorOptions, AuthConfigurationError, InvalidCredentialsError, TokenExpiredError, TokenInvalidError, TokenRevokedError, AccountLockedError, AccountDeactivatedError, AccessDeniedError, SessionExpiredError, AuthRateLimitError, } from "./authError.base.js";
+export { AuthError, type AuthErrorOptions, AuthConfigurationError, InvalidCredentialsError, TokenExpiredError, TokenInvalidError, TokenRevokedError, AccountDeactivatedError, AccessDeniedError, SessionExpiredError, } from "./authError.base.js";
+export { AccountLockedError, AuthRateLimitError, type ThrottleErrorOptions, } from "./authError.throttle.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/authErrors/index.js

@@ -3,5 +3,6 @@
  *
  * @module authErrors
  */
-export { AuthError, AuthConfigurationError, InvalidCredentialsError, TokenExpiredError, TokenInvalidError, TokenRevokedError, AccountLockedError, AccountDeactivatedError, AccessDeniedError, SessionExpiredError, AuthRateLimitError, } from "./authError.base.js";
+export { AuthError, AuthConfigurationError, InvalidCredentialsError, TokenExpiredError, TokenInvalidError, TokenRevokedError, AccountDeactivatedError, AccessDeniedError, SessionExpiredError, } from "./authError.base.js";
+export { AccountLockedError, AuthRateLimitError, } from "./authError.throttle.js";
 //# sourceMappingURL=index.js.map

package/dist/authPassword/authPassword.rehash.d.ts

@@ -5,8 +5,10 @@
  */
 /**
  * Check if a password hash needs rehashing: every hash that is not a
- * `@zudojs/crypto` scrypt hash with the current parameters (N, r, p, salt
- * and key length). All legacy `scrypt$…` hashes return `true`.
+ * `@zudojs/crypto` scrypt hash with the current parameters. Current means
+ * N, r and p equal to this package's policy, with the salt and key lengths
+ * either this package writes (32/64 bytes) or `@zudojs/crypto` writes by
+ * default (16/32 bytes). All legacy `scrypt$…` hashes return `true`.
  *
  * @param hashedPassword - The stored hash
  * @returns Whether the hash should be regenerated

package/dist/authPassword/authPassword.rehash.js

@@ -3,12 +3,28 @@
  *
  * @module authPassword/authPassword.rehash
  */
-import { CryptoAlgorithm, decodePasswordHash } from "@zudojs/crypto";
+import { CryptoAlgorithm, decodePasswordHash, getDefaultPasswordHashOptions, } from "@zudojs/crypto";
 import { KEY_LENGTH, SALT_LENGTH, SCRYPT_N, SCRYPT_P, SCRYPT_R, } from "./authPassword.policy.js";
+/**
+ * Salt and key lengths a current hash may have: the ones this package's
+ * `hashPassword()` writes, and the ones `@zudojs/crypto`'s `hashPassword()`
+ * writes with its own defaults. Both use the same scrypt N, r and p, and
+ * both are current — flagging a crypto-default hash made every login
+ * rewrite it for nothing.
+ */
+function currentLengths() {
+    const crypto = getDefaultPasswordHashOptions();
+    return [
+        [SALT_LENGTH, KEY_LENGTH],
+        [crypto.saltBytes, crypto.keyBytes],
+    ];
+}
 /**
  * Check if a password hash needs rehashing: every hash that is not a
- * `@zudojs/crypto` scrypt hash with the current parameters (N, r, p, salt
- * and key length). All legacy `scrypt$…` hashes return `true`.
+ * `@zudojs/crypto` scrypt hash with the current parameters. Current means
+ * N, r and p equal to this package's policy, with the salt and key lengths
+ * either this package writes (32/64 bytes) or `@zudojs/crypto` writes by
+ * default (16/32 bytes). All legacy `scrypt$…` hashes return `true`.
  *
  * @param hashedPassword - The stored hash
  * @returns Whether the hash should be regenerated
@@ -20,11 +36,12 @@ export function needsRehash(hashedPassword) {
         const decoded = decodePasswordHash(hashedPassword);
         if (decoded.algorithm !== CryptoAlgorithm.SCRYPT)
             return true;
-        return (decoded.salt.byteLength !== SALT_LENGTH ||
-            decoded.hash.byteLength !== KEY_LENGTH ||
-            decoded.cost !== SCRYPT_N ||
+        if (decoded.cost !== SCRYPT_N ||
             decoded.blockSize !== SCRYPT_R ||
-            decoded.parallelization !== SCRYPT_P);
+            decoded.parallelization !== SCRYPT_P) {
+            return true;
+        }
+        return !currentLengths().some(([salt, key]) => decoded.salt.byteLength === salt && decoded.hash.byteLength === key);
     }
     catch {
         return true;

package/dist/authProvider/authProvider.core.d.ts

@@ -7,6 +7,7 @@ import type { AuthUser, UserCredentials, UserId } from "../authTypes/authUser.ty
 import type { TokenPair, TokenPayload, TokenConfig, TokenRevocationStore } from "../authTypes/authToken.type.js";
 import type { SessionStore, SessionId } from "../authTypes/authSession.type.js";
 import type { LoginThrottleConfig } from "../authTypes/authAttempt.type.js";
+import { type ExternalSessionOptions } from "./authProvider.external.js";
 import type { GuardContext, GuardResult } from "../authTypes/authRbac.type.js";
 import type { PermissionEngine } from "@zudojs/permissions";
 export { throttleKey } from "./authProvider.throttle.js";
@@ -82,6 +83,23 @@ export interface AuthServiceConfig {
      * and verify them through this service.
      */
     readonly allowSessionlessTokens?: boolean;
+    /**
+     * Methods `createSessionForUser()` may start a session for, e.g.
+     * `["oauth"]`. Default: none, so `createSessionForUser()` throws.
+     *
+     * That method checks no credential — your code asserts the user is
+     * already authenticated — so it is off until you name the flows that
+     * verify authentication themselves (an OAuth callback that validated
+     * `state` and exchanged the code).
+     */
+    readonly externalSessionMethods?: readonly string[];
+    /**
+     * How `login()` normalizes the submitted identifier before `findUser()`
+     * sees it. Default: {@link normalizeLoginIdentifier} (NFKC, trim, and
+     * lower-case for an email). Pass `false` to hand `findUser()` the raw
+     * string, or your own function to match how you store identifiers.
+     */
+    readonly normalizeIdentifier?: false | ((identifier: string) => string);
 }
 /**
  * Auth service interface.
@@ -101,6 +119,18 @@ export interface AuthService {
     refresh(refreshToken: string): Promise<TokenPair>;
     logout(sessionId: SessionId, refreshToken?: string): Promise<void>;
     logoutAll(userId: UserId): Promise<void>;
+    /**
+     * Start a session for a user your code has already authenticated some
+     * other way — OAuth (`@zudojs/auth-oauth`), a passkey, a magic link — and
+     * return tokens exactly as `login()` does, without a password check.
+     *
+     * Only for methods listed in `externalSessionMethods`; otherwise it throws
+     * `AuthConfigurationError`. The user is loaded with `findUserById()`, and
+     * an unknown user (`InvalidCredentialsError`) or a deactivated one
+     * (`AccountDeactivatedError`) is refused. Never pass it a user id taken
+     * from the request.
+     */
+    createSessionForUser(userId: UserId, options: ExternalSessionOptions): Promise<LoginResult>;
     checkAccess(context: GuardContext): Promise<GuardResult>;
     hashPassword(password: string): Promise<string>;
     verifyPasswordHash(password: string, hash: string): Promise<boolean>;

package/dist/authProvider/authProvider.core.js

@@ -4,6 +4,8 @@
  * @module authProvider/authProvider
  */
 import { createLoginThrottleGate } from "./authProvider.throttle.js";
+import { createExternalSessionStarter, } from "./authProvider.external.js";
+import { normalizeLoginIdentifier } from "../authUtils/authUtils.identifier.js";
 import { hashPassword, verifyPassword, } from "../authPassword/authPassword.core.js";
 import { createTokenPair, verifyAccessToken, verifyRefreshToken, } from "../authToken/authToken.core.js";
 import { assertTokenSecrets } from "../authToken/authToken.signing.js";
@@ -22,7 +24,7 @@ export { throttleKey } from "./authProvider.throttle.js";
  * Create an auth service.
  */
 export function createAuthService(config) {
-    const { token: tokenConfig, sessionStore, findUser, findUserById, verifyPassword: verifyPwd, sessionTtlSeconds, absoluteSessionTtlSeconds, permissions, revocationStore, loginThrottle, allowInsecureFallbackGuard, fallbackAdminRole, allowSessionlessTokens, } = config;
+    const { token: tokenConfig, sessionStore, findUser, findUserById, verifyPassword: verifyPwd, sessionTtlSeconds, absoluteSessionTtlSeconds, permissions, revocationStore, loginThrottle, allowInsecureFallbackGuard, fallbackAdminRole, allowSessionlessTokens, externalSessionMethods, normalizeIdentifier, } = config;
     // Fail at construction, not at the first login: a bad secret or a NaN
     // lifetime (`Number(process.env.X)` with X unset) otherwise surfaced as
     // a runtime error on the request path — or, for the session TTL, not at
@@ -31,6 +33,17 @@ export function createAuthService(config) {
     assertPositiveSeconds(sessionTtlSeconds, "sessionTtlSeconds");
     assertPositiveSeconds(absoluteSessionTtlSeconds, "absoluteSessionTtlSeconds");
     const throttle = createLoginThrottleGate(loginThrottle);
+    const normalize = normalizeIdentifier === false
+        ? (identifier) => identifier
+        : (normalizeIdentifier ?? normalizeLoginIdentifier);
+    const createSessionForUser = createExternalSessionStarter({
+        methods: externalSessionMethods,
+        findUserById,
+        sessionStore,
+        tokenConfig,
+        sessionTtlSeconds,
+        absoluteSessionTtlSeconds,
+    });
     /**
      * Reject the token unless the session it was issued against is still
      * alive; refresh the session's idle timer when it is.
@@ -72,9 +85,12 @@ export function createAuthService(config) {
          * deactivated account are indistinguishable to the caller: the same
          * `InvalidCredentialsError` is thrown, and the unknown-user path performs
          * the same scrypt work as the known-user path.
+         *
+         * The identifier is normalized first (see `normalizeIdentifier`), so
+         * `findUser()` and the lockout counters see one spelling of it.
          */
         async login(credentials, context) {
-            const identifier = credentials.identifier;
+            const identifier = normalize(credentials.identifier);
             const slot = await throttle.begin(identifier);
             const user = await findUser(identifier);
             let authenticated = false;
@@ -197,6 +213,7 @@ export function createAuthService(config) {
         async logoutAll(userId) {
             await sessionStore.destroyAllForUser(userId);
         },
+        createSessionForUser,
         /**
          * Check if a user has a specific permission.
          * Delegates to the @zudojs/permissions engine when configured.

package/dist/authProvider/authProvider.external.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Sessions for users authenticated outside `login()` — OAuth, passkeys,
+ * magic links.
+ *
+ * @module authProvider/authProvider.external
+ */
+import type { AuthUser, UserId } from "../authTypes/authUser.type.js";
+import type { TokenConfig, TokenPair } from "../authTypes/authToken.type.js";
+import type { SessionId, SessionStore } from "../authTypes/authSession.type.js";
+/** Options for `AuthService.createSessionForUser()`. */
+export interface ExternalSessionOptions {
+    /**
+     * How your code authenticated the user — `"oauth"`, `"passkey"`,
+     * `"magic-link"`. It must be listed in the service's
+     * `externalSessionMethods`, and is recorded on the session as
+     * `metadata.authMethod`.
+     */
+    readonly method: string;
+    /** Client user-agent string, recorded on the session. */
+    readonly userAgent?: string;
+    /** Client IP address, recorded on the session. */
+    readonly ip?: string;
+    /** Extra session metadata, e.g. `{ provider: "github" }`. */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** What `createSessionForUser()` returns: the same shape as `login()`. */
+export interface ExternalSessionResult {
+    readonly user: AuthUser;
+    readonly tokens: TokenPair;
+    readonly sessionId: SessionId;
+}
+/** The parts of the service configuration the starter needs. */
+export interface ExternalSessionDependencies {
+    readonly methods: readonly string[] | undefined;
+    readonly findUserById: (userId: UserId) => Promise<AuthUser | null>;
+    readonly sessionStore: SessionStore;
+    readonly tokenConfig: TokenConfig;
+    readonly sessionTtlSeconds: number;
+    readonly absoluteSessionTtlSeconds: number | undefined;
+}
+/**
+ * Build `createSessionForUser()`.
+ *
+ * It performs no credential check: the caller asserts the user is already
+ * authenticated. It is therefore off unless the service lists the method in
+ * `externalSessionMethods` — a route that forwards a client-supplied user id
+ * cannot reach it by default — and it still refuses unknown and deactivated
+ * users.
+ */
+export declare function createExternalSessionStarter(deps: ExternalSessionDependencies): (userId: UserId, options: ExternalSessionOptions) => Promise<ExternalSessionResult>;
+//# sourceMappingURL=authProvider.external.d.ts.map

package/dist/authProvider/authProvider.external.js

@@ -0,0 +1,50 @@
+/**
+ * Sessions for users authenticated outside `login()` — OAuth, passkeys,
+ * magic links.
+ *
+ * @module authProvider/authProvider.external
+ */
+import { createTokenPair } from "../authToken/authToken.core.js";
+import { AccountDeactivatedError, AuthConfigurationError, InvalidCredentialsError, } from "../authErrors/authError.base.js";
+/**
+ * Build `createSessionForUser()`.
+ *
+ * It performs no credential check: the caller asserts the user is already
+ * authenticated. It is therefore off unless the service lists the method in
+ * `externalSessionMethods` — a route that forwards a client-supplied user id
+ * cannot reach it by default — and it still refuses unknown and deactivated
+ * users.
+ */
+export function createExternalSessionStarter(deps) {
+    const allowed = new Set(deps.methods ?? []);
+    return async (userId, options) => {
+        const method = options?.method;
+        if (typeof method !== "string" || !allowed.has(method)) {
+            throw new AuthConfigurationError(`createSessionForUser(): method "${String(method)}" is not enabled. ` +
+                "List it in `externalSessionMethods` once your code verifies that " +
+                "authentication itself (e.g. the OAuth callback).");
+        }
+        if (typeof userId !== "string" || userId.length === 0) {
+            throw new InvalidCredentialsError();
+        }
+        const user = await deps.findUserById(userId);
+        if (!user)
+            throw new InvalidCredentialsError();
+        if (!user.active)
+            throw new AccountDeactivatedError();
+        const session = await deps.sessionStore.create({
+            userId: user.id,
+            userAgent: options.userAgent,
+            ip: options.ip,
+            ttlSeconds: deps.sessionTtlSeconds,
+            absoluteTtlSeconds: deps.absoluteSessionTtlSeconds,
+            metadata: { ...options.metadata, authMethod: method },
+        });
+        const tokens = createTokenPair(user.id, deps.tokenConfig, {
+            roles: user.roles,
+            sessionId: session.id,
+        });
+        return { user, tokens, sessionId: session.id };
+    };
+}
+//# sourceMappingURL=authProvider.external.js.map

package/dist/authProvider/authProvider.throttle.js

@@ -4,7 +4,7 @@
  *
  * @module authProvider/authProvider.throttle
  */
-import { AccountLockedError, AuthRateLimitError, } from "../authErrors/authError.base.js";
+import { AccountLockedError, AuthRateLimitError, } from "../authErrors/authError.throttle.js";
 const DEFAULT_MAX_FAILED_ATTEMPTS = 5;
 const DEFAULT_LOCKOUT_SECONDS = 900;
 const DEFAULT_MAX_ATTEMPTS_PER_WINDOW = 20;

package/dist/authProvider/index.d.ts

@@ -5,4 +5,5 @@
  */
 export { createAuthService, type AuthService, type AuthServiceConfig, type LoginResult, type UserLookup, type UserByIdLookup, type PasswordVerifier, } from "./authProvider.core.js";
 export { createMemoryLoginAttemptStore } from "./authAttempt.memory.js";
+export { type ExternalSessionOptions, type ExternalSessionResult, } from "./authProvider.external.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/authProvider/index.js

@@ -5,4 +5,5 @@
  */
 export { createAuthService, } from "./authProvider.core.js";
 export { createMemoryLoginAttemptStore } from "./authAttempt.memory.js";
+export {} from "./authProvider.external.js";
 //# sourceMappingURL=index.js.map

package/dist/authUtils/authUtils.identifier.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Login identifier normalization.
+ *
+ * @module authUtils/authUtils.identifier
+ */
+/**
+ * Normalize a login identifier the way `login()` does before looking the
+ * user up: Unicode-compatibility fold (NFKC) and trim, then lower-case the
+ * whole identifier when it is an email address. A username keeps its case.
+ *
+ * Store identifiers through this same function at registration, so
+ * `" Alice@Example.com"` at sign-in finds the account registered as
+ * `alice@example.com`. The lockout counters are keyed case-insensitively
+ * independently of this, so case variants never get their own attempt
+ * budget either way.
+ *
+ * @param identifier - The identifier as submitted.
+ * @returns The normalized identifier.
+ */
+export declare function normalizeLoginIdentifier(identifier: string): string;
+//# sourceMappingURL=authUtils.identifier.d.ts.map

package/dist/authUtils/authUtils.identifier.js

@@ -0,0 +1,25 @@
+/**
+ * Login identifier normalization.
+ *
+ * @module authUtils/authUtils.identifier
+ */
+import { isEmail } from "@zudojs/types";
+/**
+ * Normalize a login identifier the way `login()` does before looking the
+ * user up: Unicode-compatibility fold (NFKC) and trim, then lower-case the
+ * whole identifier when it is an email address. A username keeps its case.
+ *
+ * Store identifiers through this same function at registration, so
+ * `" Alice@Example.com"` at sign-in finds the account registered as
+ * `alice@example.com`. The lockout counters are keyed case-insensitively
+ * independently of this, so case variants never get their own attempt
+ * budget either way.
+ *
+ * @param identifier - The identifier as submitted.
+ * @returns The normalized identifier.
+ */
+export function normalizeLoginIdentifier(identifier) {
+    const trimmed = String(identifier).normalize("NFKC").trim();
+    return isEmail(trimmed) ? trimmed.toLowerCase() : trimmed;
+}
+//# sourceMappingURL=authUtils.identifier.js.map

package/dist/authUtils/index.d.ts

@@ -1,7 +1,9 @@
 /**
- * Auth utility helpers: token parsing, cookie parsing, CSRF.
+ * Auth utility helpers: token parsing, cookie parsing, CSRF, login
+ * identifier normalization.
  *
  * @module authUtils
  */
 export { parseBearerToken, parseCookies, isTokenExpired, extractUserId, generateCsrfToken, } from "./authUtils.helper.js";
+export { normalizeLoginIdentifier } from "./authUtils.identifier.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/authUtils/index.js

@@ -1,7 +1,9 @@
 /**
- * Auth utility helpers: token parsing, cookie parsing, CSRF.
+ * Auth utility helpers: token parsing, cookie parsing, CSRF, login
+ * identifier normalization.
  *
  * @module authUtils
  */
 export { parseBearerToken, parseCookies, isTokenExpired, extractUserId, generateCsrfToken, } from "./authUtils.helper.js";
+export { normalizeLoginIdentifier } from "./authUtils.identifier.js";
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/auth",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Authentication and authorization services for the Zudojs framework — JWT, sessions, RBAC, and password management.",
   "license": "MIT",
   "author": {
@@ -25,17 +25,18 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/constants": "1.1.1",
-    "@zudojs/crypto": "1.3.0",
-    "@zudojs/errors": "1.2.0",
-    "@zudojs/permissions": "1.3.0"
+    "@zudojs/constants": "1.1.2",
+    "@zudojs/crypto": "1.3.1",
+    "@zudojs/errors": "1.3.0",
+    "@zudojs/permissions": "1.4.0",
+    "@zudojs/types": "1.2.0"
   },
   "engines": {
     "node": ">=24.0.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.1"
   },
   "publishConfig": {
     "access": "public"
@@ -48,7 +49,7 @@
     "sessions",
     "rbac"
   ],
-  "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "homepage": "https://zudojs.oyinlola.site/docs/packages-auth",
   "bugs": {
     "url": "https://github.com/oyinlola-tech/zudo/issues"
   },