@shtora/auth 0.1.0 → 0.1.1

package/README.md

@@ -1,15 +1,27 @@
 # @shtora/auth
 
+[Repository](https://github.com/orgShtora-1/auth) · [Issues](https://github.com/orgShtora-1/auth/issues)
+
 Framework-neutral authentication handlers and session management for Next.js and Cloudflare Workers. The core uses standard `Request`/`Response` APIs and Web Crypto; optional entry points add Cloudflare D1, OIDC, and WebAuthn support.
 
 Your application owns its user records, credential verification, password hashing, email delivery, and persistent stores. The package does not hash, encrypt, or persist passwords and includes no ORM.
 
 ## Install
 
+Install the published package from npm:
+
+```sh
+bun add @shtora/auth@latest
+```
+
+To install a beta release:
+
 ```sh
-bun add @shtora/auth
+bun add @shtora/auth@beta
 ```
 
+The `beta` tag must point to a published beta version. It is not currently available.
+
 Install optional protocol dependencies only when you use those entry points:
 
 ```sh
@@ -93,7 +105,7 @@ function getAuth(env: Env) {
     credentials,
     sessions: createD1SessionStore(env.DB),
     rateLimiter: createD1RateLimiter(env.DB, {
-      email: { limit: 5, windowSeconds: 60 },
+      identifier: { limit: 5, windowSeconds: 60 },
       ip: { limit: 100, windowSeconds: 60 },
     }),
     resolveClientIp: (request) => request.headers.get("cf-connecting-ip"),
@@ -112,7 +124,7 @@ export default {
 };
 ```
 
-Apply the SQL files in `migrations/` to the D1 database before handling requests. D1 cleanup is bounded; schedule it often enough for your session and rate-limit volume. Workers Free and Paid use the same package code, subject to each plan's D1, storage, and CPU quotas. Local Worker tests do not measure production quotas.
+The npm package omits SQL files; see the [Cloudflare D1 adapter](#cloudflare-d1-adapter) section for the pinned migration source and application instructions. D1 cleanup is bounded; schedule it often enough for your session and rate-limit volume. Workers Free and Paid use the same package code, subject to each plan's D1, storage, and CPU quotas.
 
 ## Routes
 
@@ -133,12 +145,44 @@ The default base path is `/api/auth`; set `basePath` to change it.
 | `POST` | `/api/auth/password-reset/confirm` | Optional; revokes sessions, then delegates the password update to the application. |
 
 State-changing POST and DELETE requests require a same-origin `Origin` header by default. Read-only session GET requests allow a missing `Origin`. Keep this check enabled for browser cookie authentication unless equivalent CSRF protection is in place.
+## Registration and login identifiers
+
+Email-only behavior is the default. `identity.registration` accepts `"email"`, `"username"`, `"both"`, or `"either"`; `"either"` requires exactly one identifier. `identity.login` accepts `"email"`, `"username"`, or `"either"`, also requiring exactly one login identifier. Compatible pairs are email/email, username/username, either/either, and both with any login mode; other pairs fail during `createAuth`.
+
+```ts
+createAuth({
+  users,
+  credentials,
+  sessions,
+  identity: { registration: "either", login: "either" },
+  passwordPolicy: {
+    minLength: 12,
+    maxLength: 128,
+    requireUppercase: true,
+    requireLowercase: true,
+    requireSpecial: true,
+  },
+});
+```
+
+Registration accepts `{ email, password }`, `{ username, password }`, both identifiers with `registration: "both"`, or exactly one identifier with `"either"`. Login accepts the configured identifier field and a password; `"either"` rejects requests containing both. Unknown JSON keys are ignored, but supplying a disabled email/username field is invalid. Password is always required.
+
+Usernames are 3–32 ASCII letters, digits, `.`, `_`, or `-`; they are canonicalized to lowercase without trimming. The application’s `UserStore.findByIdentifier` must use the same canonical form, and `create` must enforce email/username uniqueness atomically with database constraints. Email input is lowercased; whitespace is rejected. Username syntax excludes `@`, so valid email and username values cannot collide across namespaces. Lookup and rate limiting carry an explicit `"email"`/`"username"` discriminator.
+
+`AuthUser` contains an opaque `id` and optional `email`/`username`. The package returns only `id` and present email/username fields; it never spreads adapter fields into a public response. OIDC and WebAuthn continue to map identities through the application’s opaque user ID.
+
+`UserStore` results must contain exactly the configured identity shape before a session is created: email mode requires only email, username mode only username, both requires both, and either requires exactly one. Missing or invalid canonical identifiers fail closed and are reported through `onError`; no partial identity response is issued.
+
+The default password policy is min 1 and max 4096 Unicode code points, with uppercase/lowercase/special requirements disabled. Policy checks run during registration and password-reset confirmation, not login. Passwords are neither trimmed nor normalized. “Special” means a Unicode code point that is not a letter, number, or whitespace. The 4096-code-point hard cap is independent of the request-body byte limit. Invalid shape or policy returns the generic `400 { "error": "invalid_request" }`.
+
+Email verification requires registration mode `"email"` or `"both"` and rejects incompatible configurations at `createAuth`. Password-reset request remains email-address-only; username-only accounts and `"either"` accounts created without an email cannot request an email reset. `emailPolicy` denies email-less users, including session creation through OIDC. No additional migration is needed for this identity-mode change: D1 rate-limit table keys store only digests, with identifier kind included in the hashed key.
+
 
 ## Email verification and password reset
 
 These flows are opt-in. Configure the matching options with an `AuthActionTokenStore` and a delivery callback. The store persists only a SHA-256 token hash, atomically replaces an earlier token for the same user and purpose, consumes the current unexpired token once, and implements bounded expiration cleanup. The callback receives the raw bearer token: enqueue it promptly and never log it. Submit tokens to the POST confirmation routes rather than consuming them in GET requests, which link scanners may follow.
 
-Email verification also requires `isVerified` and `markVerified`. When enabled, unverified users cannot log in or use existing sessions. Password reset delegates password hashing and persistence to `setPassword`; sessions are revoked before that callback runs. If password persistence fails, the user remains signed out but the old password may still work. The application remains responsible for password policy and hash configuration.
+Email verification also requires `isVerified` and `markVerified`. When enabled, unverified users cannot log in or use existing sessions. The configured package `passwordPolicy` applies to registration and password-reset confirmation. Reset sessions are revoked before `setPassword` delegates hashing and persistence to the application; if persistence fails, the user remains signed out but the old password may still work. The application owns hashing, persistence, and any policy checks for password flows outside these package handlers.
 
 Known and unknown addresses receive the same request response, though delivery timing can differ. Use asynchronous delivery and configure rate limiting for public auth endpoints.
 
@@ -163,25 +207,29 @@ The application also owns persistent storage for action tokens, OIDC transaction
 
 ### OIDC
 
-Import `createOidc` from `@shtora/auth/oidc`. It uses state, nonce, and PKCE, checks the fixed callback URL, and consumes a matching unexpired transaction once. The application owns `OidcTransactionStore`, issuer/client configuration, identity-to-user mapping, and session creation. Use an HTTPS issuer and pre-registered callback URL; schedule the returned `cleanupExpired()` method.
+Import `createOidc` and its types from `@shtora/auth/oidc`. Required options are `issuer` (HTTPS issuer URL), `clientId`, an absolute HTTPS `callbackUrl` registered with the provider, a fixed same-origin `successPath`, a persistent `transactions` store, `resolveUser`, `auth`, a trusted `resolveClientIp`, and a `rateLimiter`. `auth` is the `createAuth` result; `resolveUser` maps the verified `{ issuer, subject }` to an application user or `null`.
+
+The returned handler accepts GET `/start` and GET `/callback` paths. Mount it at the callback URL's origin and route both paths to it; register the exact callback URL with the identity provider. It uses state, nonce, PKCE, and one-use transaction consumption. Schedule its `cleanupExpired()` method.
 
 ### WebAuthn and passkeys
 
-Import `createWebAuthn` from `@shtora/auth/webauthn`. Registration requires an authenticated user flow and a stable, non-PII application user ID of at most 64 UTF-8 bytes. Configure the exact expected origin and RP ID, persistent one-use challenge storage, unique credential IDs, compare-and-set counter updates, trusted client-IP resolution, and a request rate limiter. Schedule the returned `cleanupExpired()` method.
+Import `createWebAuthn` and its types from `@shtora/auth/webauthn`. Required options are the exact `expectedOrigin` (HTTPS, or localhost HTTP for development), matching `rpID`, `rpName`, persistent one-use `challenges` and `credentials` stores, `resolveRegistrationUser`, `auth`, a trusted `resolveClientIp`, and a `rateLimiter`. `auth` is the `createAuth` result. Registration requires an authenticated application user with a stable, non-PII ID of at most 64 UTF-8 bytes.
 
-## Cloudflare D1 adapter
+Forward POST `/webauthn/registration/options`, `/webauthn/registration/verify`, `/webauthn/authentication/options`, and `/webauthn/authentication/verify` to the returned handler. It verifies the configured origin and RP ID, requires user verification, and uses one-use challenges. Credential IDs must be unique and counter updates atomic compare-and-set operations. Schedule the returned `cleanupExpired()` method.
 
-`@shtora/auth/cloudflare` exports D1 session, action-token, and fixed-window rate-limit adapters. The core entry point does not import Cloudflare code. Rate-limit keys are hashed before storage; the counters remain scoped to one D1 database and consume D1 write capacity. Cloudflare's Workers Rate Limit binding is location-local and approximate, not a globally strict limiter.
+## Public entry points
 
-Run all SQL migrations in order. `cleanupD1AuthState` removes bounded batches of expired sessions, action tokens, and rate-limit records; set `rateLimitMaxWindowSeconds` to at least the longest configured rate-limit window. See the [D1 Worker API](https://developers.cloudflare.com/d1/worker-api/d1-database/) and [Workers Rate Limit binding](https://developers.cloudflare.com/workers/runtime-apis/bindings/rate-limit/).
+- `@shtora/auth`: `createAuth` and the core types for users, credentials, sessions, rate limiting, policies, and optional email verification/password reset.
+- `@shtora/auth/cloudflare`: `D1Database`, D1 session/action-token stores, core and request rate limiters, and D1 auth-state cleanup.
+- `@shtora/auth/oidc`: `createOidc` and OIDC configuration, transaction-store, and handler types.
+- `@shtora/auth/webauthn`: `createWebAuthn` and WebAuthn challenge-store, credential-store, options, and user types.
 
-## Development
+Install `openid-client` for `@shtora/auth/oidc` and `@simplewebauthn/server` for `@shtora/auth/webauthn`; these optional peer dependencies are not needed by the core entry point.
+
+## Cloudflare D1 adapter
+
+`@shtora/auth/cloudflare` exports `createD1SessionStore`, `createD1ActionTokenStore`, `createD1RateLimiter`, `createD1RequestRateLimiter`, and `cleanupD1AuthState`. `createD1RateLimiter` implements the core auth limiter for registration, login, email verification, and password reset; `createD1RequestRateLimiter` implements the separate request limiter required by OIDC and WebAuthn using `{ limit, windowSeconds }`. Both use hashed keys in the same `shtora_rate_limits` table.
+
+The npm package omits SQL files; apply migrations in filename order from the [pinned repository source](https://github.com/orgShtora-1/auth/tree/694089c260cdcc229b78b20a6b3a90f92eb38fd6/migrations), using `wrangler d1 execute <database-name> --remote --file <migration.sql>`. If schemas diverge in a later release, use the repository commit matching your installed package version. `cleanupD1AuthState` deletes bounded batches of expired sessions, action tokens, and rate-limit records; set `rateLimitMaxWindowSeconds` to at least the longest configured rate-limit window. D1 counters share one database and consume D1 write capacity. Cloudflare's Workers Rate Limit binding is location-local and approximate, not a globally strict limiter. See the [D1 Worker API](https://developers.cloudflare.com/d1/worker-api/d1-database/) and [Workers Rate Limit binding](https://developers.cloudflare.com/workers/runtime-apis/bindings/rate-limit/).
 
-```sh
-bun install
-bun run typecheck
-bun test
-bun run build
-```
 
-Changes to auth behavior should include tests for the affected boundary or state transition. Keep package documentation in English, update this README when public contracts change, and avoid adding generated output to commits. See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution workflow.

package/dist/auth.js

@@ -1,6 +1,6 @@
 import { clearedSessionCookie, readSessionToken, sessionCookie } from "./cookies.js";
 import { createSessionToken, hashSessionToken } from "./crypto.js";
-import { parseActionTokenRequest, parseCredentials, parseEmailRequest, parsePasswordReset, readJson, RequestError } from "./request.js";
+import { parseActionTokenRequest, parseEmailRequest, parseLoginCredentials, parsePasswordReset, parseRegistrationCredentials, readJson, RequestError } from "./request.js";
 const defaultBasePath = "/api/auth";
 const defaultCookieName = "__Host-shtora.session";
 const defaultSessionTtl = 60 * 60 * 24 * 7;
@@ -9,12 +9,42 @@ const defaultMaxRequestBytes = 8192;
 const defaultVerificationTokenTtl = 60 * 60;
 const defaultResetTokenTtl = 15 * 60;
 const maxActionTokenTtl = 60 * 60 * 24;
+const defaultPasswordPolicy = { minLength: 1, maxLength: 4096 };
+const hardMaxPasswordLength = 4096;
 export function createAuth(options) {
     const basePath = options.basePath ?? defaultBasePath;
     const cookieName = options.cookieName ?? defaultCookieName;
     const sessionTtlSeconds = options.sessionTtlSeconds ?? defaultSessionTtl;
     const maxRequestBytes = options.maxRequestBytes ?? defaultMaxRequestBytes;
     const requireOrigin = options.requireOrigin ?? true;
+    const registrationMode = options.identity?.registration ?? "email";
+    const loginMode = options.identity?.login ?? "email";
+    const passwordPolicy = { ...defaultPasswordPolicy, ...options.passwordPolicy };
+    if (!["email", "username", "both", "either"].includes(registrationMode) ||
+        !["email", "username", "either"].includes(loginMode)) {
+        throw new TypeError("identity modes are invalid");
+    }
+    if ((registrationMode === "email" && loginMode !== "email") ||
+        (registrationMode === "username" && loginMode !== "username") ||
+        (registrationMode === "either" && loginMode !== "either")) {
+        throw new TypeError("identity login mode is incompatible with registration mode");
+    }
+    if (!Number.isInteger(passwordPolicy.minLength) || passwordPolicy.minLength < 1 ||
+        !Number.isInteger(passwordPolicy.maxLength) || passwordPolicy.maxLength > hardMaxPasswordLength ||
+        passwordPolicy.maxLength < passwordPolicy.minLength) {
+        throw new RangeError("passwordPolicy lengths must be integers between 1 and 4096 with minLength <= maxLength");
+    }
+    for (const flag of [
+        options.passwordPolicy?.requireUppercase,
+        options.passwordPolicy?.requireLowercase,
+        options.passwordPolicy?.requireSpecial,
+    ]) {
+        if (flag !== undefined && typeof flag !== "boolean")
+            throw new TypeError("passwordPolicy requirements must be booleans");
+    }
+    if (options.emailVerification && registrationMode !== "email" && registrationMode !== "both") {
+        throw new TypeError("emailVerification requires registration mode 'email' or 'both'");
+    }
     if (!basePath.startsWith("/") || basePath.endsWith("/") || basePath.includes("?")) {
         throw new TypeError("basePath must start with '/' and must not end with '/'");
     }
@@ -35,6 +65,26 @@ export function createAuth(options) {
             throw new RangeError("tokenTtlSeconds must be between 1 and 86400");
         }
     }
+    function passwordAllowed(password) {
+        let length = 0;
+        for (const _character of password)
+            length += 1;
+        return length >= passwordPolicy.minLength &&
+            length <= passwordPolicy.maxLength &&
+            (!options.passwordPolicy?.requireUppercase || /\p{Lu}/u.test(password)) &&
+            (!options.passwordPolicy?.requireLowercase || /\p{Ll}/u.test(password)) &&
+            (!options.passwordPolicy?.requireSpecial || /[^\p{L}\p{N}\p{White_Space}]/u.test(password));
+    }
+    function requirePasswordPolicy(password) {
+        if (!passwordAllowed(password))
+            throw new RequestError(400, "invalid_request");
+    }
+    function requireEmail(user) {
+        if (typeof user.email !== "string" || user.email.length === 0) {
+            throw new TypeError("UserStore returned a user without an email");
+        }
+        return user.email;
+    }
     async function isAllowed(policy, value, request) {
         return policy ? policy.allow({ value, request }) : true;
     }
@@ -101,11 +151,30 @@ export function createAuth(options) {
             return false;
         }
     }
-    function publicUser(user) {
-        if (typeof user.id !== "string" || user.id.length === 0 || typeof user.email !== "string") {
-            throw new TypeError("UserStore returned an invalid user");
+    function assertUserIdentity(user) {
+        const validEmail = user.email === undefined ||
+            (typeof user.email === "string" && user.email.length <= 254 && user.email.includes("@") &&
+                !/\s/.test(user.email) && user.email === user.email.toLowerCase());
+        const validUsername = user.username === undefined ||
+            (typeof user.username === "string" && /^[a-z0-9._-]{3,32}$/.test(user.username));
+        const hasEmail = user.email !== undefined;
+        const hasUsername = user.username !== undefined;
+        const modeSatisfied = (registrationMode === "email" && hasEmail && !hasUsername) ||
+            (registrationMode === "username" && hasUsername && !hasEmail) ||
+            (registrationMode === "both" && hasEmail && hasUsername) ||
+            (registrationMode === "either" && hasEmail !== hasUsername);
+        if (typeof user.id !== "string" || user.id.length === 0 || !validEmail || !validUsername || !modeSatisfied) {
+            throw new TypeError("UserStore returned an invalid user identity");
         }
-        return { id: user.id, email: user.email };
+    }
+    function publicUser(user) {
+        return {
+            id: user.id,
+            ...(["email", "both"].includes(registrationMode) && user.email !== undefined ? { email: user.email } : {}),
+            ...(["username", "both"].includes(registrationMode) && user.username !== undefined ? { username: user.username } : {}),
+            ...(registrationMode === "either" && user.email !== undefined ? { email: user.email } : {}),
+            ...(registrationMode === "either" && user.username !== undefined ? { username: user.username } : {}),
+        };
     }
     async function getSession(request) {
         try {
@@ -125,9 +194,10 @@ export function createAuth(options) {
                 await options.sessions.deleteByTokenHash(tokenHash);
                 return null;
             }
+            assertUserIdentity(user);
             if (options.emailVerification && !options.emailVerification.isVerified(user))
                 return null;
-            if (!(await isAllowed(options.emailPolicy, user.email, request)))
+            if (options.emailPolicy && (!user.email || !(await isAllowed(options.emailPolicy, user.email, request))))
                 return null;
             if (options.ipPolicy) {
                 const ip = await clientIp(request);
@@ -142,7 +212,7 @@ export function createAuth(options) {
             throw error;
         }
     }
-    async function rateLimit(action, email, request) {
+    async function rateLimit(action, identifier, request) {
         if (!options.rateLimiter)
             return null;
         const ip = await clientIp(request);
@@ -151,7 +221,7 @@ export function createAuth(options) {
                 return response({ error: "invalid_credentials" }, 401);
             return response({ status: "accepted" }, 202);
         }
-        const result = await options.rateLimiter.check({ action, email, ip });
+        const result = await options.rateLimiter.check({ action, identifier, ip });
         if (result.allowed)
             return null;
         const seconds = Number.isInteger(result.retryAfterSeconds) && result.retryAfterSeconds > 0
@@ -171,7 +241,7 @@ export function createAuth(options) {
         }
     }
     async function passPolicies(email, request) {
-        if (!(await isAllowed(options.emailPolicy, email, request)))
+        if (options.emailPolicy && (!email || !(await isAllowed(options.emailPolicy, email, request))))
             return false;
         if (!options.ipPolicy)
             return true;
@@ -179,18 +249,23 @@ export function createAuth(options) {
         return ip !== null && isAllowed(options.ipPolicy, ip, request);
     }
     async function register(request) {
-        const credentials = parseCredentials(await readJson(request, maxRequestBytes));
-        const limited = await rateLimit("register", credentials.email, request);
+        const credentials = parseRegistrationCredentials(await readJson(request, maxRequestBytes), registrationMode);
+        requirePasswordPolicy(credentials.password);
+        const identifier = credentials.email !== undefined
+            ? { type: "email", value: credentials.email }
+            : { type: "username", value: credentials.username };
+        const limited = await rateLimit("register", identifier, request);
         if (limited)
             return limited;
         if (!(await passPolicies(credentials.email, request)))
             return response({ status: "accepted" }, 202);
-        const created = await options.users.create({ email: credentials.email, password: credentials.password });
+        const created = await options.users.create(credentials);
         if (created.created) {
             if (!created.user)
                 throw new TypeError("UserStore must return the created user");
+            assertUserIdentity(created.user);
             if (options.emailVerification) {
-                await issueActionToken("email-verification", created.user.id, created.user.email, options.emailVerification.tokens, options.emailVerification, defaultVerificationTokenTtl, "email-verification.send");
+                await issueActionToken("email-verification", created.user.id, requireEmail(created.user), options.emailVerification.tokens, options.emailVerification, defaultVerificationTokenTtl, "email-verification.send");
             }
         }
         return response({ status: "accepted" }, 202);
@@ -200,14 +275,14 @@ export function createAuth(options) {
         if (!flow)
             return response({ error: "not_found" }, 404);
         const email = parseEmailRequest(await readJson(request, maxRequestBytes));
-        const limited = await rateLimit("email-verification", email, request);
+        const limited = await rateLimit("email-verification", { type: "email", value: email }, request);
         if (limited)
             return limited;
         if (!(await passPolicies(email, request)))
             return response({ status: "accepted" }, 202);
         const user = await options.users.findByEmail(email);
         if (user && !flow.isVerified(user)) {
-            await issueActionToken("email-verification", user.id, user.email, flow.tokens, flow, defaultVerificationTokenTtl, "email-verification.send");
+            await issueActionToken("email-verification", user.id, requireEmail(user), flow.tokens, flow, defaultVerificationTokenTtl, "email-verification.send");
         }
         return response({ status: "accepted" }, 202);
     }
@@ -234,14 +309,14 @@ export function createAuth(options) {
         if (!flow)
             return response({ error: "not_found" }, 404);
         const email = parseEmailRequest(await readJson(request, maxRequestBytes));
-        const limited = await rateLimit("password-reset", email, request);
+        const limited = await rateLimit("password-reset", { type: "email", value: email }, request);
         if (limited)
             return limited;
         if (!(await passPolicies(email, request)))
             return response({ status: "accepted" }, 202);
         const user = await options.users.findByEmail(email);
         if (user) {
-            await issueActionToken("password-reset", user.id, user.email, flow.tokens, flow, defaultResetTokenTtl, "password-reset.send");
+            await issueActionToken("password-reset", user.id, requireEmail(user), flow.tokens, flow, defaultResetTokenTtl, "password-reset.send");
         }
         return response({ status: "accepted" }, 202);
     }
@@ -250,6 +325,7 @@ export function createAuth(options) {
         if (!flow)
             return response({ error: "not_found" }, 404);
         const { token, password } = parsePasswordReset(await readJson(request, maxRequestBytes));
+        requirePasswordPolicy(password);
         const consumed = await flow.tokens.consume({
             purpose: "password-reset",
             tokenHash: await hashSessionToken(token),
@@ -265,6 +341,7 @@ export function createAuth(options) {
         return new Response(null, { status: 204, headers: { "Cache-Control": "no-store" } });
     }
     async function createSessionForUser(user) {
+        assertUserIdentity(user);
         const token = createSessionToken();
         const tokenHash = await hashSessionToken(token);
         const now = Date.now();
@@ -285,8 +362,10 @@ export function createAuth(options) {
             if (!hostIsAllowed(request))
                 return response({ error: "invalid_host" }, 403);
             const user = await options.users.findById(userId);
-            if (!user ||
-                (options.emailVerification && !options.emailVerification.isVerified(user)) ||
+            if (!user)
+                return response({ error: "unauthenticated" }, 401);
+            assertUserIdentity(user);
+            if ((options.emailVerification && !options.emailVerification.isVerified(user)) ||
                 !(await passPolicies(user.email, request))) {
                 return response({ error: "unauthenticated" }, 401);
             }
@@ -299,15 +378,17 @@ export function createAuth(options) {
         }
     }
     async function login(request) {
-        const { email, password } = parseCredentials(await readJson(request, maxRequestBytes));
-        const limited = await rateLimit("login", email, request);
+        const { identifier, password } = parseLoginCredentials(await readJson(request, maxRequestBytes), loginMode);
+        const limited = await rateLimit("login", identifier, request);
         if (limited)
             return limited;
-        if (!(await passPolicies(email, request)))
-            return response({ error: "invalid_credentials" }, 401);
-        const user = await options.users.findByEmail(email);
-        const verified = await options.credentials.verify({ email, password, user });
-        if (!user || !verified || (options.emailVerification && !options.emailVerification.isVerified(user))) {
+        const user = await options.users.findByIdentifier(identifier);
+        const verified = await options.credentials.verify({ identifier, password, user });
+        if (user)
+            assertUserIdentity(user);
+        const policyAllowed = await passPolicies(identifier.type === "email" ? identifier.value : user?.email, request);
+        if (!user || !verified || !policyAllowed ||
+            (options.emailVerification && !options.emailVerification.isVerified(user))) {
             return response({ error: "invalid_credentials" }, 401);
         }
         return createSessionForUser(user);

package/dist/cloudflare.d.ts

@@ -26,7 +26,7 @@ export interface D1RateLimitWindow {
     windowSeconds: number;
 }
 export interface D1RateLimiterOptions {
-    email: D1RateLimitWindow;
+    identifier: D1RateLimitWindow;
     ip: D1RateLimitWindow;
     /** Epoch milliseconds; injectable to make window boundaries deterministic in tests. */
     now?: () => number;

package/dist/cloudflare.js

@@ -57,13 +57,13 @@ function toStoredSession(row) {
     };
 }
 export function createD1RateLimiter(db, options) {
-    validateWindow("email", options.email);
+    validateWindow("identifier", options.identifier);
     validateWindow("ip", options.ip);
     const now = options.now ?? Date.now;
     return {
-        async check({ action, email, ip }) {
+        async check({ action, identifier, ip }) {
             const dimensions = [
-                { name: "email", raw: email, config: options.email },
+                { name: `identifier:${identifier.type}`, raw: identifier.value, config: options.identifier },
                 { name: "ip", raw: ip, config: options.ip },
             ];
             const digests = await Promise.all(dimensions.map(({ name, raw }) => hashKey(`${action}\0${name}\0${raw}`)));

package/dist/index.d.ts

@@ -1,2 +1,2 @@
 export { createAuth } from "./auth.js";
-export type { AccessPolicy, AuthActionTokenDelivery, AuthActionTokenPurpose, AuthActionTokenStore, AuthApi, AuthenticatedUser, AuthOptions, AuthRateLimiter, AuthRequestRateLimitAction, AuthRequestRateLimiter, AuthUser, CredentialVerifier, EmailVerificationOptions, ExpiredRecordStore, PasswordResetOptions, SessionStore, StoredSession, UserStore, } from "./types.js";
+export type { AccessPolicy, AuthActionTokenDelivery, AuthActionTokenPurpose, AuthActionTokenStore, AuthApi, AuthenticatedUser, AuthOptions, AuthRateLimiter, AuthRequestRateLimitAction, AuthIdentifier, AuthUser, CredentialVerifier, EmailVerificationOptions, LoginIdentityMode, PasswordPolicy, RegistrationIdentityMode, ExpiredRecordStore, PasswordResetOptions, SessionStore, StoredSession, UserStore, } from "./types.js";

package/dist/request.d.ts

@@ -8,8 +8,16 @@ export declare function parseEmailRequest(value: unknown): string;
 export declare function parseActionTokenRequest(value: unknown): string;
 export declare function parseEmail(value: unknown): string;
 export declare function parseActionToken(value: unknown): string;
-export declare function parseCredentials(value: unknown): {
-    email: string;
+export declare function parseRegistrationCredentials(value: unknown, mode: "email" | "username" | "both" | "either"): {
+    email?: string;
+    username?: string;
+    password: string;
+};
+export declare function parseLoginCredentials(value: unknown, mode: "email" | "username" | "either"): {
+    identifier: {
+        type: "email" | "username";
+        value: string;
+    };
     password: string;
 };
 export declare function parsePasswordReset(value: unknown): {

package/dist/request.js

@@ -77,17 +77,56 @@ export function parseActionToken(value) {
     }
     return value;
 }
-export function parseCredentials(value) {
-    const { email, password } = objectFields(value);
-    if (typeof password !== "string" || password.length === 0 || password.length > 4096) {
+function parsePassword(value) {
+    if (typeof value !== "string" || value.length === 0)
         throw new RequestError(400, "invalid_request");
+    let codePoints = 0;
+    for (const _character of value) {
+        codePoints += 1;
+        if (codePoints > 4096)
+            throw new RequestError(400, "invalid_request");
     }
-    return { email: parseEmail(email), password };
+    return value;
 }
-export function parsePasswordReset(value) {
-    const { token, password } = objectFields(value);
-    if (typeof password !== "string" || password.length === 0 || password.length > 4096) {
+function parseUsername(value) {
+    if (typeof value !== "string" || !/^[A-Za-z0-9._-]{3,32}$/.test(value)) {
+        throw new RequestError(400, "invalid_request");
+    }
+    return value.toLowerCase();
+}
+export function parseRegistrationCredentials(value, mode) {
+    const fields = objectFields(value);
+    const password = parsePassword(fields.password);
+    const hasEmail = fields.email !== undefined;
+    const hasUsername = fields.username !== undefined;
+    if ((mode === "email" && (hasUsername || !hasEmail)) ||
+        (mode === "username" && (hasEmail || !hasUsername)) ||
+        (mode === "both" && (!hasEmail || !hasUsername)) ||
+        (mode === "either" && hasEmail === hasUsername)) {
         throw new RequestError(400, "invalid_request");
     }
-    return { token: parseActionToken(token), password };
+    const email = hasEmail ? parseEmail(fields.email) : undefined;
+    const username = hasUsername ? parseUsername(fields.username) : undefined;
+    return { ...(email === undefined ? {} : { email }), ...(username === undefined ? {} : { username }), password };
+}
+export function parseLoginCredentials(value, mode) {
+    const fields = objectFields(value);
+    const password = parsePassword(fields.password);
+    const hasEmail = fields.email !== undefined;
+    const hasUsername = fields.username !== undefined;
+    if ((mode === "email" && (hasUsername || !hasEmail)) ||
+        (mode === "username" && (hasEmail || !hasUsername)) ||
+        (mode === "either" && hasEmail === hasUsername)) {
+        throw new RequestError(400, "invalid_request");
+    }
+    return {
+        identifier: hasEmail
+            ? { type: "email", value: parseEmail(fields.email) }
+            : { type: "username", value: parseUsername(fields.username) },
+        password,
+    };
+}
+export function parsePasswordReset(value) {
+    const { token, password } = objectFields(value);
+    return { token: parseActionToken(token), password: parsePassword(password) };
 }

package/dist/types.d.ts

@@ -1,13 +1,32 @@
 export interface AuthUser {
     readonly id: string;
-    readonly email: string;
+    readonly email?: string;
+    readonly username?: string;
+}
+export type AuthIdentifier = {
+    readonly type: "email";
+    readonly value: string;
+} | {
+    readonly type: "username";
+    readonly value: string;
+};
+export type RegistrationIdentityMode = "email" | "username" | "both" | "either";
+export type LoginIdentityMode = "email" | "username" | "either";
+export interface PasswordPolicy {
+    minLength?: number;
+    maxLength?: number;
+    requireUppercase?: boolean;
+    requireLowercase?: boolean;
+    requireSpecial?: boolean;
 }
 export interface UserStore<User extends AuthUser = AuthUser> {
+    findByIdentifier(identifier: AuthIdentifier): Promise<User | null>;
     findByEmail(email: string): Promise<User | null>;
     findById(id: string): Promise<User | null>;
-    /** Enforce normalized-email uniqueness atomically; hash the password before persistence. */
+    /** Enforce canonical email/username uniqueness atomically; hash the password before persistence. */
     create(input: {
-        email: string;
+        email?: string;
+        username?: string;
         password: string;
     }): Promise<{
         created: true;
@@ -18,7 +37,7 @@ export interface UserStore<User extends AuthUser = AuthUser> {
 }
 export interface CredentialVerifier<User extends AuthUser = AuthUser> {
     verify(input: {
-        email: string;
+        identifier: AuthIdentifier;
         password: string;
         user: User | null;
     }): Promise<boolean>;
@@ -75,6 +94,11 @@ export interface AuthOptions<User extends AuthUser = AuthUser> {
     users: UserStore<User>;
     credentials: CredentialVerifier<User>;
     sessions: SessionStore;
+    identity?: {
+        registration?: RegistrationIdentityMode;
+        login?: LoginIdentityMode;
+    };
+    passwordPolicy?: PasswordPolicy;
     emailPolicy?: AccessPolicy;
     resolveClientIp?: (request: Request) => string | null | Promise<string | null>;
     ipPolicy?: AccessPolicy;
@@ -110,7 +134,7 @@ export interface SessionStore extends ExpiredRecordStore {
 export interface AuthRateLimiter {
     check(input: {
         action: "register" | "login" | "email-verification" | "password-reset";
-        email: string;
+        identifier: AuthIdentifier;
         ip: string;
     }): Promise<{
         allowed: boolean;
@@ -135,7 +159,8 @@ export interface AccessPolicy {
 }
 export interface AuthenticatedUser {
     readonly id: string;
-    readonly email: string;
+    readonly email?: string;
+    readonly username?: string;
 }
 export interface AuthApi {
     handle(request: Request): Promise<Response>;

package/package.json

@@ -20,7 +20,7 @@
     "email-verification",
     "password-reset"
   ],
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "exports": {
     ".": {
@@ -63,7 +63,9 @@
       "optional": true
     }
   },
-  "files": ["dist", "migrations"],
+  "files": [
+    "dist"
+  ],
   "sideEffects": false,
   "scripts": {
     "build": "tsc -p tsconfig.build.json",

package/migrations/0001_shtora_auth.sql

@@ -1,39 +0,0 @@
-CREATE TABLE IF NOT EXISTS shtora_sessions (
-  id TEXT PRIMARY KEY NOT NULL,
-  token_hash TEXT NOT NULL UNIQUE,
-  user_id TEXT NOT NULL,
-  created_at_ms INTEGER NOT NULL,
-  expires_at_ms INTEGER NOT NULL
-);
-
-CREATE INDEX IF NOT EXISTS shtora_sessions_user_created
-  ON shtora_sessions (user_id, created_at_ms, id);
-
-CREATE TABLE IF NOT EXISTS shtora_rate_limits (
-  key_hash TEXT PRIMARY KEY NOT NULL,
-  window_start_ms INTEGER NOT NULL,
-  count INTEGER NOT NULL CHECK (count > 0)
-);
-
-CREATE TABLE IF NOT EXISTS shtora_action_tokens (
-  purpose TEXT NOT NULL,
-  user_id TEXT NOT NULL,
-  token_hash TEXT NOT NULL,
-  expires_at_ms INTEGER NOT NULL,
-  PRIMARY KEY (purpose, token_hash)
-);
-
-CREATE INDEX IF NOT EXISTS shtora_action_tokens_expiry
-  ON shtora_action_tokens (expires_at_ms);
-CREATE INDEX IF NOT EXISTS shtora_action_tokens_user_purpose
-  ON shtora_action_tokens (purpose, user_id);
-
--- Preferred cleanup path: schedule cleanupD1AuthState(db, { rateLimitMaxWindowSeconds }).
--- It uses bounded batches for expired sessions/action tokens and completed rate-limit windows.
--- Manual equivalent for rate counters:
--- DELETE FROM shtora_rate_limits WHERE window_start_ms < :now_ms - :max_window_ms;
--- Set :max_window_ms to the longest configured rate-limit window in milliseconds.
--- Manual equivalent for action tokens and sessions:
--- DELETE FROM shtora_action_tokens WHERE expires_at_ms <= :now_ms;
--- DELETE FROM shtora_sessions WHERE expires_at_ms <= :now_ms;
--- Apply 0002_session_expiry_index.sql and 0003_rate_limit_expiry_index.sql for cleanup indexes.

package/migrations/0002_session_expiry_index.sql

@@ -1,2 +0,0 @@
-CREATE INDEX IF NOT EXISTS shtora_sessions_expiry
-  ON shtora_sessions (expires_at_ms);

package/migrations/0003_rate_limit_expiry_index.sql

@@ -1,2 +0,0 @@
-CREATE INDEX IF NOT EXISTS shtora_rate_limits_window_start
-  ON shtora_rate_limits (window_start_ms);