@spfn/auth 0.3.0-beta.4 → 0.3.0-beta.6

package/dist/server.d.ts

@@ -1,5 +1,5 @@
-import { A as AuthInitOptions, l as OAuthProvider, j as VerificationPurpose, h as PermissionCategory, n as AuthContext } from './authenticate-Ctul07Sc.js';
-export { o as AuthProfileOutcome, p as AuthProfileVerifier, C as ChangePasswordParams, D as DeviceNameSchema, E as EmailSchema, I as IssueOneTimeTokenResult, q as KEY_FINGERPRINT_PREFIX_LENGTH, K as KeySummary, r as LoginParams, L as LoginResult, s as LogoutParams, N as NativeVerifyOptions, t as NormalizedIdentity, u as OAuthCallbackParams, v as OAuthCallbackResult, w as OAuthCodeExchangeOptions, x as OAuthNativeParams, d as OAuthNativeResult, y as OAuthStartParams, O as OAuthStartResult, z as OAuthTokens, B as PasswordSchema, F as PhoneSchema, G as PlatformSchema, H as RegisterParams, J as RegisterPublicKeyParams, a as RegisterResult, M as RevokeAllKeysParams, c as RevokeAllKeysResult, Q as RevokeKeyParams, T as RotateKeyParams, b as RotateKeyResult, W as SendVerificationCodeParams, S as SendVerificationCodeResult, X as TargetTypeSchema, Y as UnlinkNotification, Z as UnlinkNotifyRejection, _ as UnlinkNotifyRequest, $ as UnlinkNotifyResult, V as VERIFICATION_PURPOSES, i as VERIFICATION_TARGET_TYPES, a0 as VerificationPurposeSchema, k as VerificationTargetType, a1 as VerifyCodeParams, a2 as VerifyCodeResult, m as authRouter, a3 as authenticate, a4 as buildOAuthErrorUrl, a5 as changePasswordService, a6 as getEnabledOAuthProviders, a7 as getGoogleAccessToken, a8 as getOAuthProvider, a9 as getRegisteredProviders, aa as isOAuthProviderEnabled, ab as issueOneTimeTokenService, ac as listKeysService, ad as loginService, ae as logoutService, af as oauthCallbackService, ag as oauthNativeService, ah as oauthStartService, ai as oauthUnlinkNotifyService, aj as optionalAuth, ak as registerOAuthProvider, al as registerPublicKeyService, am as registerService, an as requireEnabledProvider, ao as resolveAuthenticatedUser, ap as revokeAllKeysService, aq as revokeKeyService, ar as rotateKeyService, as as runAuthProfile, at as selectAuthProfile, au as sendVerificationCodeService, av as verifyCodeService, aw as verifyOneTimeTokenService } from './authenticate-Ctul07Sc.js';
+import { A as AuthInitOptions, n as OAuthProvider, k as VerificationPurpose, i as PermissionCategory, o as AuthContext } from './authenticate-98lBIMxP.js';
+export { p as AuthProfileOutcome, q as AuthProfileVerifier, r as ChangePasswordParams, s as CompleteSignupParams, t as ConfirmSignupLinkParams, C as ConfirmSignupLinkResult, D as DeviceNameSchema, E as EmailSchema, I as IssueOneTimeTokenResult, u as KEY_FINGERPRINT_PREFIX_LENGTH, K as KeySummary, v as LoginParams, L as LoginResult, w as LogoutParams, N as NativeVerifyOptions, x as NormalizedIdentity, y as OAuthCallbackParams, z as OAuthCallbackResult, B as OAuthCodeExchangeOptions, F as OAuthNativeParams, e as OAuthNativeResult, G as OAuthStartParams, O as OAuthStartResult, H as OAuthTokens, J as PasswordSchema, M as PhoneSchema, Q as PlatformSchema, T as RegisterParams, W as RegisterPublicKeyParams, a as RegisterResult, X as RequestSignupLinkParams, b as RequestSignupLinkResult, Y as RevokeAllKeysParams, d as RevokeAllKeysResult, Z as RevokeKeyParams, _ as RotateKeyParams, c as RotateKeyResult, $ as SendVerificationCodeParams, S as SendVerificationCodeResult, a0 as TargetTypeSchema, a1 as UnlinkNotification, a2 as UnlinkNotifyRejection, a3 as UnlinkNotifyRequest, a4 as UnlinkNotifyResult, V as VERIFICATION_PURPOSES, j as VERIFICATION_TARGET_TYPES, a5 as VerificationPurposeSchema, l as VerificationTargetType, a6 as VerifyCodeParams, a7 as VerifyCodeResult, m as authRouter, a8 as authenticate, a9 as buildOAuthErrorUrl, aa as changePasswordService, ab as completeSignupService, ac as confirmSignupLinkService, ad as getEnabledOAuthProviders, ae as getGoogleAccessToken, af as getOAuthProvider, ag as getRegisteredProviders, ah as isOAuthProviderEnabled, ai as isSafeReturnPath, aj as issueOneTimeTokenService, ak as listKeysService, al as loginService, am as logoutService, an as oauthCallbackService, ao as oauthNativeService, ap as oauthStartService, aq as oauthUnlinkNotifyService, ar as optionalAuth, as as registerOAuthProvider, at as registerPublicKeyService, au as registerService, av as requestSignupLinkService, aw as requireEnabledProvider, ax as resolveAuthenticatedUser, ay as revokeAllKeysService, az as revokeKeyService, aA as rotateKeyService, aB as runAuthProfile, aC as selectAuthProfile, aD as sendVerificationCodeService, aE as verifyCodeService, aF as verifyOneTimeTokenService } from './authenticate-98lBIMxP.js';
 import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
 import { K as KeyAlgorithmType, d as InvitationStatus, j as SocialProvider, c as AccountDeletionRequestedBy, i as PurgeStrategy } from './types-DYyhze28.js';
 export { A as ACCOUNT_DELETION_REQUESTED_BY, a as ACCOUNT_DELETION_REQUEST_STATUSES, b as AccountDeletionRequestStatus, I as INVITATION_STATUSES, e as KEY_ALGORITHM, f as KEY_DEVICE_NAME_MAX_LENGTH, g as KEY_PLATFORM, h as KeyPlatformType, P as PURGE_STRATEGIES, S as SOCIAL_PROVIDERS, U as USER_STATUSES, k as UserStatus } from './types-DYyhze28.js';
@@ -431,6 +431,42 @@ declare function updateUsernameService(userId: string | number | bigint, usernam
  */
 declare function initializeAuth(options?: AuthInitOptions): Promise<void>;
 
+/**
+ * @spfn/auth - Stored email normalization
+ *
+ * Brings existing rows into the canonical form the repository now writes and
+ * reads. Without it, normalizing the code alone would lock out every account
+ * whose address was stored with any capitalization: the lookup folds the typed
+ * address to lower case, the stored one stays mixed, and they stop matching.
+ *
+ * Runs once at startup and records that it ran, so a healthy install pays one
+ * small metadata read per boot rather than a scan of the users table.
+ *
+ * The work itself stays in the database — one query to find the addresses two
+ * rows would share, one statement to fold the rest. Nothing proportional to the
+ * table is carried through the application, which is what keeps a legacy
+ * install's first boot from turning into a row-at-a-time migration.
+ */
+interface EmailNormalizationResult {
+    /** Rows rewritten to canonical form. */
+    normalized: number;
+    /** User id groups that share an address once folded, left untouched. */
+    conflicts: number[][];
+}
+/**
+ * Rewrite stored addresses to canonical form, skipping anything that would
+ * collide.
+ *
+ * A collision means two accounts differ only by capitalization. Which of them is
+ * the real one, and what happens to the other's data, is not a question this can
+ * answer — so every row in the group is left exactly as it is and all of their
+ * ids are reported. The alternative, merging or deleting one, destroys an
+ * account on a guess.
+ *
+ * @returns what was rewritten and what was left for an operator
+ */
+declare function normalizeStoredEmails(): Promise<EmailNormalizationResult>;
+
 /**
  * @spfn/auth - Permission Service
  *
@@ -3057,6 +3093,209 @@ declare const verificationCodes: drizzle_orm_pg_core.PgTableWithColumns<{
 type VerificationCode = typeof verificationCodes.$inferSelect;
 type NewVerificationCode = typeof verificationCodes.$inferInsert;
 
+/**
+ * @spfn/auth - Signup Link Tokens Entity
+ *
+ * Backs the verified-email signup flow: a one-time confirmation link is emailed,
+ * opening it mints a short-lived setup session, and setting a password on that
+ * session creates the account.
+ *
+ * A separate table from `verification_codes` on purpose. That table stores its
+ * six-digit code in plaintext, which is acceptable for a short-lived numeric code
+ * bounded by an attempt counter, but a link token is a bearer credential sitting
+ * in someone's mailbox and must only ever be stored as a hash. Sharing one table
+ * would make "plaintext or hash" a per-row property that nothing enforces.
+ */
+declare const signupLinkTokens: drizzle_orm_pg_core.PgTableWithColumns<{
+    name: "signup_link_tokens";
+    schema: string;
+    columns: {
+        createdAt: drizzle_orm_pg_core.PgBuildColumn<"signup_link_tokens", drizzle_orm_pg_core.SetNotNull<drizzle_orm_pg_core.SetHasDefault<drizzle_orm_pg_core.PgTimestampBuilder>>, {
+            name: string;
+            tableName: "signup_link_tokens";
+            dataType: "object date";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+        updatedAt: drizzle_orm_pg_core.PgBuildColumn<"signup_link_tokens", drizzle_orm_pg_core.SetHasDefault<drizzle_orm_pg_core.SetNotNull<drizzle_orm_pg_core.SetHasDefault<drizzle_orm_pg_core.PgTimestampBuilder>>>, {
+            name: string;
+            tableName: "signup_link_tokens";
+            dataType: "object date";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+        id: drizzle_orm_pg_core.PgBuildColumn<"signup_link_tokens", drizzle_orm_pg_core.SetIsPrimaryKey<drizzle_orm_pg_core.PgBigSerial53Builder>, {
+            name: string;
+            tableName: "signup_link_tokens";
+            dataType: "number int53";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+        email: drizzle_orm_pg_core.PgBuildColumn<"signup_link_tokens", drizzle_orm_pg_core.SetNotNull<drizzle_orm_pg_core.PgTextBuilder<[string, ...string[]]>>, {
+            name: string;
+            tableName: "signup_link_tokens";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+        tokenHash: drizzle_orm_pg_core.PgBuildColumn<"signup_link_tokens", drizzle_orm_pg_core.SetNotNull<drizzle_orm_pg_core.PgTextBuilder<[string, ...string[]]>>, {
+            name: string;
+            tableName: "signup_link_tokens";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+        returnPath: drizzle_orm_pg_core.PgBuildColumn<"signup_link_tokens", drizzle_orm_pg_core.PgTextBuilder<[string, ...string[]]>, {
+            name: string;
+            tableName: "signup_link_tokens";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+        expiresAt: drizzle_orm_pg_core.PgBuildColumn<"signup_link_tokens", drizzle_orm_pg_core.SetNotNull<drizzle_orm_pg_core.PgTimestampBuilder>, {
+            name: string;
+            tableName: "signup_link_tokens";
+            dataType: "object date";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+        consumedAt: drizzle_orm_pg_core.PgBuildColumn<"signup_link_tokens", drizzle_orm_pg_core.PgTimestampBuilder, {
+            name: string;
+            tableName: "signup_link_tokens";
+            dataType: "object date";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+        supersededAt: drizzle_orm_pg_core.PgBuildColumn<"signup_link_tokens", drizzle_orm_pg_core.PgTimestampBuilder, {
+            name: string;
+            tableName: "signup_link_tokens";
+            dataType: "object date";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+        setupSecretHash: drizzle_orm_pg_core.PgBuildColumn<"signup_link_tokens", drizzle_orm_pg_core.PgTextBuilder<[string, ...string[]]>, {
+            name: string;
+            tableName: "signup_link_tokens";
+            dataType: "string";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+        setupExpiresAt: drizzle_orm_pg_core.PgBuildColumn<"signup_link_tokens", drizzle_orm_pg_core.PgTimestampBuilder, {
+            name: string;
+            tableName: "signup_link_tokens";
+            dataType: "object date";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+        completedAt: drizzle_orm_pg_core.PgBuildColumn<"signup_link_tokens", drizzle_orm_pg_core.PgTimestampBuilder, {
+            name: string;
+            tableName: "signup_link_tokens";
+            dataType: "object date";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            identity: undefined;
+            generated: undefined;
+        }>;
+    };
+    dialect: "pg";
+}>;
+type SignupLinkToken = typeof signupLinkTokens.$inferSelect;
+type NewSignupLinkToken = typeof signupLinkTokens.$inferInsert;
+
 /**
  * @spfn/auth - Permissions Entity
  *
@@ -3629,6 +3868,38 @@ declare class UsersRepository extends BaseRepository {
         phoneVerifiedAt: Date | null;
         lastLoginAt: Date | null;
     }>;
+    /**
+     * 이메일로 사용자 조회 — 저장된 형태와 무관하게 찾는다.
+     *
+     * `findByEmail` asks whether a row holds this exact address; this asks
+     * whether any row *is* this address, whatever form it was written in. The
+     * difference matters to a caller that answers "no" by creating an account:
+     * a lookup that misses a row stored in another form would make a second
+     * account for a person who already has one, and the unique constraint
+     * cannot object because the two stored strings differ.
+     *
+     * Folding in the predicate means no index on `email` applies, so this is for
+     * the few addresses a caller decides about — admin seeding — not for a
+     * request path. Write primary: the answer decides whether to insert.
+     */
+    findByEmailInAnyStoredForm(email: string): Promise<{
+        deletedAt: Date | null;
+        deletedBy: string | null;
+        createdAt: Date;
+        updatedAt: Date;
+        id: number;
+        publicId: string;
+        email: string | null;
+        phone: string | null;
+        username: string | null;
+        passwordHash: string | null;
+        passwordChangeRequired: boolean;
+        roleId: number;
+        status: "active" | "inactive" | "suspended" | "pending_deletion" | "deleted";
+        emailVerifiedAt: Date | null;
+        phoneVerifiedAt: Date | null;
+        lastLoginAt: Date | null;
+    }>;
     /**
      * 전화번호로 사용자 조회
      * Read replica 사용
@@ -3770,6 +4041,51 @@ declare class UsersRepository extends BaseRepository {
         deletedAt: Date | null;
         deletedBy: string | null;
     }>;
+    /**
+     * User ids grouped by an address two or more rows share once folded.
+     *
+     * The whole comparison happens in the database and only the colliding groups
+     * come back, so the size of the answer is the size of the problem rather
+     * than the size of the table. `users.email` is unique, so a group of more
+     * than one can only be rows that differ by capitalization or padding —
+     * exactly the ones a rewrite cannot decide between.
+     *
+     * Every member id is returned, including a row already holding the
+     * canonical form, because the operator has to compare the accounts against
+     * each other to settle which is real.
+     *
+     * Write primary: the caller is about to rewrite rows and a replica could
+     * still be showing the pre-fix state.
+     */
+    findEmailConflictGroups(): Promise<number[][]>;
+    /**
+     * Fold every stored address to canonical form, leaving the given ids alone.
+     *
+     * One statement rather than a row at a time: the rewrite is the same
+     * expression the detection uses, so the database can do it in place. A
+     * legacy install with a large users table therefore pays one update instead
+     * of a round trip per row on the boot path, and no list of addresses is ever
+     * carried through the application.
+     *
+     * The excluded ids travel as a single array parameter, so the count of
+     * conflicts cannot run into the protocol's limit on bind parameters.
+     *
+     * One statement also means all or nothing. `users.email` is unique, so if an
+     * instance still running the old code registers a canonical address in the
+     * moment between the conflict query and this update, the update aborts and
+     * nothing is folded on this boot. The next boot sees that pair as a conflict
+     * and folds everything else, so the repair is deferred rather than lost.
+     *
+     * `lower(btrim(...))` is the SQL spelling of `normalizeEmail`. The two agree
+     * on every address this package's validation accepts (ASCII, no interior
+     * whitespace); an address outside that set — reachable only by an app
+     * writing to the repository directly — may fold differently in a database
+     * whose collation lower-cases non-ASCII letters.
+     *
+     * @param excludedIds - Rows to leave untouched, normally the conflict groups
+     * @returns How many rows were rewritten
+     */
+    normalizeEmailsExcept(excludedIds: number[]): Promise<number>;
     /**
      * 사용자 정보 업데이트
      * Write primary 사용
@@ -4428,6 +4744,75 @@ declare class VerificationCodesRepository extends BaseRepository {
 }
 declare const verificationCodesRepository: VerificationCodesRepository;
 
+/**
+ * Signup Link Tokens Repository
+ *
+ * Data access for the verified-email signup flow. Extends BaseRepository for
+ * transaction-context detection and read/write splitting.
+ *
+ * The two claim methods (`claimLink`, `claimSetupSession`) update conditionally
+ * and return the row only if THIS call was the one that moved it. Two concurrent
+ * confirms — or two concurrent password submits — therefore produce one winner
+ * and one refusal, rather than both proceeding on a row they each read as
+ * unclaimed. Read-then-write would lose that race.
+ */
+
+declare class SignupLinkTokensRepository extends BaseRepository {
+    /**
+     * Create a signup link row.
+     * Write primary.
+     */
+    create(data: NewSignupLinkToken): Promise<SignupLinkToken>;
+    /**
+     * Find a row by the hash of an emailed token, in any state.
+     *
+     * Deliberately unfiltered: the caller decides why a link is refused, and a
+     * row filtered out here would be indistinguishable from an unknown token in
+     * the logs.
+     *
+     * Read replica.
+     */
+    findByTokenHash(tokenHash: string): Promise<SignupLinkToken | null>;
+    /**
+     * Find a row by the hash of a setup session secret, in any state.
+     * Read replica.
+     */
+    findBySetupSecretHash(setupSecretHash: string): Promise<SignupLinkToken | null>;
+    /**
+     * Consume a link and open a setup session on it, but only if it is still
+     * unconsumed and not superseded.
+     *
+     * @returns the updated row, or null if another request claimed it first
+     */
+    claimLink(id: number, setupSecretHash: string, setupExpiresAt: Date): Promise<SignupLinkToken | null>;
+    /**
+     * Mark a setup session as completed, but only if it has not completed
+     * already.
+     *
+     * @returns the updated row, or null if another request completed it first
+     */
+    claimSetupSession(id: number): Promise<SignupLinkToken | null>;
+    /**
+     * Supersede every live link for an address, so requesting a new one
+     * invalidates the previous one and any setup session opened from it.
+     *
+     * Write primary.
+     *
+     * @returns number of rows superseded
+     */
+    supersedeLiveForEmail(email: string): Promise<number>;
+    /**
+     * Delete every signup link row for an address (account destruction).
+     *
+     * Rows key on the email text and carry no user FK, so destruction has to
+     * clean them up by address the way verification codes are cleaned up.
+     *
+     * Write primary.
+     */
+    deleteByEmail(email: string): Promise<number>;
+}
+declare const signupLinkTokensRepository: SignupLinkTokensRepository;
+
 /**
  * Roles Repository
  *
@@ -5145,12 +5530,12 @@ declare class InvitationsRepository extends BaseRepository {
     create(data: NewInvitation): Promise<{
         email: string;
         metadata: Record<string, any> | null;
+        token: string;
         id: number;
         roleId: number;
         createdAt: Date;
         updatedAt: Date;
         status: "pending" | "accepted" | "expired" | "cancelled";
-        token: string;
         invitedBy: number;
         expiresAt: Date;
         acceptedAt: Date | null;
@@ -5179,12 +5564,12 @@ declare class InvitationsRepository extends BaseRepository {
     deleteById(id: number): Promise<{
         email: string;
         metadata: Record<string, any> | null;
+        token: string;
         id: number;
         roleId: number;
         createdAt: Date;
         updatedAt: Date;
         status: "pending" | "accepted" | "expired" | "cancelled";
-        token: string;
         invitedBy: number;
         expiresAt: Date;
         acceptedAt: Date | null;
@@ -5581,10 +5966,10 @@ declare class AccountDeletionRequestsRepository extends BaseRepository {
         reason: string | null;
         purgeScheduledAt: Date;
         cancelledAt: Date | null;
+        completedAt: Date | null;
         userPublicId: string;
         requestedAt: Date;
         requestedBy: "admin" | "self";
-        completedAt: Date | null;
         purgeStrategy: "anonymize" | "hard-delete" | null;
     }>;
     /**
@@ -5669,6 +6054,43 @@ declare class OpsTokensRepository extends BaseRepository {
 }
 declare const opsTokensRepository: OpsTokensRepository;
 
+/**
+ * @spfn/auth - Email address normalization
+ *
+ * One canonical form for an address, applied on the way in AND on the way out,
+ * so `Foo@Example.com` and `foo@example.com` are the same account everywhere.
+ *
+ * Both sides have to agree or normalization makes things worse rather than
+ * better: normalizing only the lookup means an address stored in mixed case can
+ * no longer be found, and normalizing only the write means an old row stays
+ * unreachable. `UsersRepository` therefore applies this to every read and every
+ * write of `users.email`, which is what keeps a call site from forgetting.
+ */
+/**
+ * Trim and lower-case an address.
+ *
+ * Nothing else. Two normalizations that look tempting are deliberately absent:
+ * stripping dots and cutting at `+` are Gmail delivery rules, not internet ones,
+ * and applying them would merge addresses that other providers treat as
+ * genuinely different people.
+ *
+ * The local part is technically case-sensitive per RFC 5321, but no mail
+ * provider in practice treats it that way, while users routinely retype their
+ * address with different capitalization. Matching the practice avoids duplicate
+ * accounts; honouring the RFC creates them.
+ *
+ * @param email - Address as supplied
+ * @returns The canonical form used for storage and lookup
+ */
+declare function normalizeEmail(email: string): string;
+/**
+ * Normalize when there is an address, pass null/undefined through untouched.
+ *
+ * Accounts registered by phone have no email, and `null` is meaningfully
+ * different from `''` in that column.
+ */
+declare function normalizeOptionalEmail<T extends string | null | undefined>(email: T): T;
+
 /**
  * @spfn/auth - Password Helpers
  *
@@ -6227,6 +6649,8 @@ declare const COOKIE_NAMES: {
     readonly OAUTH_PENDING: string;
     /** OAuth CSRF nonce — double-submit against the (encrypted) state.nonce at callback */
     readonly OAUTH_CSRF: string;
+    /** Password-setup session for verified-email signup — temporary, single-purpose */
+    readonly SIGNUP_SETUP: string;
 };
 /**
  * OAuth CSRF 쿠키를 PORT 접미사와 무관하게 전부 수집한다.
@@ -6270,6 +6694,12 @@ interface BeforeRegisterContext {
     channel: RegisterChannel;
     /** Social provider — only set when channel is 'oauth' */
     provider?: SocialProvider;
+    /**
+     * Canonical form of the address — trimmed and lower-cased, the same form
+     * the account is stored under. A policy keyed on the address (a denylist, a
+     * domain allowlist) therefore matches whatever capitalization the person
+     * typed, instead of being walked past by `Blocked@Example.com`.
+     */
     email?: string;
     /**
      * Whether the email is verified — only set when channel is 'oauth'.
@@ -6349,6 +6779,11 @@ declare function getAuthConfig(): AuthConfig;
  * Single entry point for every registration channel so a new channel cannot
  * forget the configured-check. Callers invoke this right before creating the
  * user row.
+ *
+ * The address is folded here rather than at each call site, for the same reason
+ * the check itself lives here: three channels supply it, and a policy that sees
+ * a different spelling depending on which one the person came through is a
+ * policy that can be walked past.
  */
 declare function runBeforeRegister(context: BeforeRegisterContext): Promise<void>;
 /**
@@ -6808,8 +7243,8 @@ declare const invitationCreatedEvent: _spfn_core_event.EventDef<{
         [x: string]: unknown;
     } | undefined;
     email: string;
-    roleId: number;
     token: string;
+    roleId: number;
     invitedBy: string;
     expiresAt: string;
     invitationId: string;
@@ -6915,4 +7350,4 @@ type AuthDeletionCancelledPayload = typeof authDeletionCancelledEvent._payload;
 type AuthDeletionCompletedPayload = typeof authDeletionCompletedEvent._payload;
 type OAuthUnlinkedPayload = typeof oauthUnlinkedEvent._payload;
 
-export { type AccountDeletionPurgeUser, type AccountDeletionRequest, AccountDeletionRequestedBy, AccountDeletionRequestsRepository, type AuthConfig, AuthContext, type AuthDeletionCancelledPayload, type AuthDeletionCompletedPayload, type AuthDeletionConfig, type AuthDeletionRequestedPayload, type AuthLifecycleConfig, type AuthLifecycleOptions, type AuthLoginPayload, type AuthMetadataEntity, AuthMetadataRepository, AuthProviderSchema, type AuthRegisterPayload, type BeforeRegisterContext, COOKIE_NAMES, type CancelAccountDeletionParams, type CancelAccountDeletionResult, type CreateOAuthStateParams, DEFAULT_DELETION_ALLOW_SELF_IMMEDIATE, DEFAULT_DELETION_GRACE_PERIOD_DAYS, DEFAULT_DELETION_PURGE_CRON, DEFAULT_DELETION_PURGE_STRATEGY, DEFAULT_DELETION_SEND_NOTIFICATIONS, type DecryptedOAuthToken, EnvironmentKeyringTokenCipher, type GoogleTokenResponse, type GoogleUserInfo, type Invitation, type InvitationAcceptedPayload, type InvitationCreatedPayload, InvitationStatus, InvitationsRepository, type IssuedOpsToken, KeyAlgorithmType, KeysRepository, type NewAccountDeletionRequest, type NewAuthMetadataEntity, type NewInvitation, type NewOpsToken, type NewPermission, type NewPermissionEntity, type NewRole, type NewRoleEntity, type NewRolePermission, type NewUser, type NewUserPermission, type NewUserProfile, type NewUserPublicKey, type NewUserSocialAccount, type NewVerificationCode, OAuthProvider, type OAuthState, type OAuthTokenCipher, type OAuthTokenContext, type OAuthTokenType, type OAuthUnlinkedPayload, type OpsToken, OpsTokensRepository, type PendingDeletionInfo, type Permission, type PermissionEntity, PermissionsRepository, PurgeStrategy, type PurgeUserResult, type RegisterChannel, type RequestAccountDeletionParams, type RequestAccountDeletionResult, type Role, type RoleEntity, type RoleGuardOptions, type RolePermission, RolePermissionsRepository, RolesRepository, type SessionPayload, SocialAccountsRepository, SocialProvider, type SweepDuePurgesResult, type TokenPayload, type UpdateProfileParams, type User, type UserPermission, UserPermissionsRepository, type UserProfile, UserProfilesRepository, type UserPublicKey, type UserSocialAccount, UsersRepository, type VerificationCode, VerificationCodesRepository, VerificationPurpose, type VerifiedOpsToken, type VerifyIdTokenParams, acceptInvitation, accountDeletionRequests, accountDeletionRequestsRepository, addPermissionToRole, appleProvider, assertCanAssignRole, authDeletionCancelledEvent, authDeletionCompletedEvent, authDeletionRequestedEvent, authJobRouter, authLogger, authLoginEvent, authMetadata, authMetadataRepository, authRegisterEvent, authSchema, cancelAccountDeletionService, cancelInvitation, checkUsernameAvailableService, configureAuth, configureDeletion, configureOAuthTokenCipher, createAuthDeletionJobRouter, createAuthDeletionPurgeJob, createAuthLifecycle, createInvitation, createOAuthState, createRole, decodeToken, decryptToken, deleteInvitation, deleteRole, encryptToken, exchangeCodeForTokens, expireOldInvitations, generateOAuthNonce, generateToken, getAllRoles, getAuth, getAuthConfig, getAuthSessionService, getDeletionConfig, getDummyPasswordHash, getGoogleAuthUrl, getGoogleOAuthConfig, getGoogleUserInfo, getInvitationByToken, getInvitationWithDetails, getKeyId, getLocale, getOneTimeTokenManager, getOpsToken, getOptionalAuth, getPendingDeletionInfo, getRole, getRoleByName, getRolePermissions, getSessionTtl, getUser, getUserByEmailService, getUserByIdService, getUserByPhoneService, getUserId, getUserPermissions, getUserProfileService, getUserRole, githubProvider, googleProvider, hasAllPermissions, hasAnyPermission, hasAnyRole, hasPermission, hasRole, hashPassword, initOneTimeTokenManager, initializeAuth, invitationAcceptedEvent, invitationCreatedEvent, invitationsRepository, isEncrypted, isGoogleOAuthEnabled, issueOpsTokenService, kakaoProvider, keysRepository, listInvitations, listOpsTokensService, matchOAuthCsrfCookies, naverProvider, oauthUnlinkedEvent, oneTimeTokenAuth, opsTokenAuth, opsTokens, opsTokensRepository, parseDuration, permissions, permissionsRepository, purgeUserService, refreshAccessToken, removePermissionFromRole, requestAccountDeletionService, requireAnyPermission, requireOpsScope, requirePermissions, requireRole, resendInvitation, revokeOpsTokenService, roleGuard, rolePermissions, rolePermissionsRepository, roles, rolesRepository, runBeforeRegister, setRolePermissions, socialAccountsRepository, sweepDuePurges, updateLastLoginService, updateLocaleService, updateRole, updateUserProfileService, updateUserService, updateUsernameService, userInvitations, userPermissions, userPermissionsRepository, userProfiles, userProfilesRepository, userPublicKeys, userSocialAccounts, users, usersRepository, validateInvitation, validatePasswordStrength, verificationCodes, verificationCodesRepository, verifyClientToken, verifyIdToken, verifyKeyFingerprint, verifyOAuthState, verifyOpsTokenService, verifyPassword, verifyToken };
+export { type AccountDeletionPurgeUser, type AccountDeletionRequest, AccountDeletionRequestedBy, AccountDeletionRequestsRepository, type AuthConfig, AuthContext, type AuthDeletionCancelledPayload, type AuthDeletionCompletedPayload, type AuthDeletionConfig, type AuthDeletionRequestedPayload, type AuthLifecycleConfig, type AuthLifecycleOptions, type AuthLoginPayload, type AuthMetadataEntity, AuthMetadataRepository, AuthProviderSchema, type AuthRegisterPayload, type BeforeRegisterContext, COOKIE_NAMES, type CancelAccountDeletionParams, type CancelAccountDeletionResult, type CreateOAuthStateParams, DEFAULT_DELETION_ALLOW_SELF_IMMEDIATE, DEFAULT_DELETION_GRACE_PERIOD_DAYS, DEFAULT_DELETION_PURGE_CRON, DEFAULT_DELETION_PURGE_STRATEGY, DEFAULT_DELETION_SEND_NOTIFICATIONS, type DecryptedOAuthToken, type EmailNormalizationResult, EnvironmentKeyringTokenCipher, type GoogleTokenResponse, type GoogleUserInfo, type Invitation, type InvitationAcceptedPayload, type InvitationCreatedPayload, InvitationStatus, InvitationsRepository, type IssuedOpsToken, KeyAlgorithmType, KeysRepository, type NewAccountDeletionRequest, type NewAuthMetadataEntity, type NewInvitation, type NewOpsToken, type NewPermission, type NewPermissionEntity, type NewRole, type NewRoleEntity, type NewRolePermission, type NewSignupLinkToken, type NewUser, type NewUserPermission, type NewUserProfile, type NewUserPublicKey, type NewUserSocialAccount, type NewVerificationCode, OAuthProvider, type OAuthState, type OAuthTokenCipher, type OAuthTokenContext, type OAuthTokenType, type OAuthUnlinkedPayload, type OpsToken, OpsTokensRepository, type PendingDeletionInfo, type Permission, type PermissionEntity, PermissionsRepository, PurgeStrategy, type PurgeUserResult, type RegisterChannel, type RequestAccountDeletionParams, type RequestAccountDeletionResult, type Role, type RoleEntity, type RoleGuardOptions, type RolePermission, RolePermissionsRepository, RolesRepository, type SessionPayload, type SignupLinkToken, SignupLinkTokensRepository, SocialAccountsRepository, SocialProvider, type SweepDuePurgesResult, type TokenPayload, type UpdateProfileParams, type User, type UserPermission, UserPermissionsRepository, type UserProfile, UserProfilesRepository, type UserPublicKey, type UserSocialAccount, UsersRepository, type VerificationCode, VerificationCodesRepository, VerificationPurpose, type VerifiedOpsToken, type VerifyIdTokenParams, acceptInvitation, accountDeletionRequests, accountDeletionRequestsRepository, addPermissionToRole, appleProvider, assertCanAssignRole, authDeletionCancelledEvent, authDeletionCompletedEvent, authDeletionRequestedEvent, authJobRouter, authLogger, authLoginEvent, authMetadata, authMetadataRepository, authRegisterEvent, authSchema, cancelAccountDeletionService, cancelInvitation, checkUsernameAvailableService, configureAuth, configureDeletion, configureOAuthTokenCipher, createAuthDeletionJobRouter, createAuthDeletionPurgeJob, createAuthLifecycle, createInvitation, createOAuthState, createRole, decodeToken, decryptToken, deleteInvitation, deleteRole, encryptToken, exchangeCodeForTokens, expireOldInvitations, generateOAuthNonce, generateToken, getAllRoles, getAuth, getAuthConfig, getAuthSessionService, getDeletionConfig, getDummyPasswordHash, getGoogleAuthUrl, getGoogleOAuthConfig, getGoogleUserInfo, getInvitationByToken, getInvitationWithDetails, getKeyId, getLocale, getOneTimeTokenManager, getOpsToken, getOptionalAuth, getPendingDeletionInfo, getRole, getRoleByName, getRolePermissions, getSessionTtl, getUser, getUserByEmailService, getUserByIdService, getUserByPhoneService, getUserId, getUserPermissions, getUserProfileService, getUserRole, githubProvider, googleProvider, hasAllPermissions, hasAnyPermission, hasAnyRole, hasPermission, hasRole, hashPassword, initOneTimeTokenManager, initializeAuth, invitationAcceptedEvent, invitationCreatedEvent, invitationsRepository, isEncrypted, isGoogleOAuthEnabled, issueOpsTokenService, kakaoProvider, keysRepository, listInvitations, listOpsTokensService, matchOAuthCsrfCookies, naverProvider, normalizeEmail, normalizeOptionalEmail, normalizeStoredEmails, oauthUnlinkedEvent, oneTimeTokenAuth, opsTokenAuth, opsTokens, opsTokensRepository, parseDuration, permissions, permissionsRepository, purgeUserService, refreshAccessToken, removePermissionFromRole, requestAccountDeletionService, requireAnyPermission, requireOpsScope, requirePermissions, requireRole, resendInvitation, revokeOpsTokenService, roleGuard, rolePermissions, rolePermissionsRepository, roles, rolesRepository, runBeforeRegister, setRolePermissions, signupLinkTokens, signupLinkTokensRepository, socialAccountsRepository, sweepDuePurges, updateLastLoginService, updateLocaleService, updateRole, updateUserProfileService, updateUserService, updateUsernameService, userInvitations, userPermissions, userPermissionsRepository, userProfiles, userProfilesRepository, userPublicKeys, userSocialAccounts, users, usersRepository, validateInvitation, validatePasswordStrength, verificationCodes, verificationCodesRepository, verifyClientToken, verifyIdToken, verifyKeyFingerprint, verifyOAuthState, verifyOpsTokenService, verifyPassword, verifyToken };