@spfn/auth 0.2.0-beta.74 → 0.2.0-beta.80

package/dist/server.d.ts

@@ -1,17 +1,18 @@
-import { j as AuthInitOptions, k as OAuthProvider, e as VerificationPurpose, i as PermissionCategory, l as AuthContext } from './authenticate-DXVtYh8X.js';
-export { C as ChangePasswordParams, a3 as EmailSchema, I as IssueOneTimeTokenResult, s as LoginParams, L as LoginResult, t as LogoutParams, aa as NativeVerifyOptions, a8 as NormalizedIdentity, Z as OAuthCallbackParams, _ as OAuthCallbackResult, a0 as OAuthNativeParams, c as OAuthNativeResult, Y as OAuthStartParams, O as OAuthStartResult, a9 as OAuthTokens, a5 as PasswordSchema, a4 as PhoneSchema, q as RegisterParams, E as RegisterPublicKeyParams, a as RegisterResult, G as RevokeKeyParams, F as RotateKeyParams, b as RotateKeyResult, w as SendVerificationCodeParams, S as SendVerificationCodeResult, a6 as TargetTypeSchema, g as VERIFICATION_PURPOSES, f as VERIFICATION_TARGET_TYPES, a7 as VerificationPurposeSchema, V as VerificationTargetType, x as VerifyCodeParams, y as VerifyCodeResult, m as authRouter, a1 as authenticate, N as buildOAuthErrorUrl, p as changePasswordService, W as getEnabledOAuthProviders, X as getGoogleAccessToken, ac as getOAuthProvider, ad as getRegisteredProviders, Q as isOAuthProviderEnabled, H as issueOneTimeTokenService, n as loginService, o as logoutService, M as oauthCallbackService, $ as oauthNativeService, K as oauthStartService, a2 as optionalAuth, ab as registerOAuthProvider, z as registerPublicKeyService, r as registerService, T as requireEnabledProvider, D as revokeKeyService, B as rotateKeyService, u as sendVerificationCodeService, v as verifyCodeService, J as verifyOneTimeTokenService } from './authenticate-DXVtYh8X.js';
+import { j as AuthInitOptions, k as OAuthProvider, e as VerificationPurpose, i as PermissionCategory, l as AuthContext } from './authenticate-ofdEmk6x.js';
+export { C as ChangePasswordParams, a3 as EmailSchema, I as IssueOneTimeTokenResult, s as LoginParams, L as LoginResult, t as LogoutParams, aa as NativeVerifyOptions, a8 as NormalizedIdentity, Z as OAuthCallbackParams, _ as OAuthCallbackResult, ab as OAuthCodeExchangeOptions, a0 as OAuthNativeParams, c as OAuthNativeResult, Y as OAuthStartParams, O as OAuthStartResult, a9 as OAuthTokens, a5 as PasswordSchema, a4 as PhoneSchema, q as RegisterParams, E as RegisterPublicKeyParams, a as RegisterResult, G as RevokeKeyParams, F as RotateKeyParams, b as RotateKeyResult, w as SendVerificationCodeParams, S as SendVerificationCodeResult, a6 as TargetTypeSchema, g as VERIFICATION_PURPOSES, f as VERIFICATION_TARGET_TYPES, a7 as VerificationPurposeSchema, V as VerificationTargetType, x as VerifyCodeParams, y as VerifyCodeResult, m as authRouter, a1 as authenticate, N as buildOAuthErrorUrl, p as changePasswordService, W as getEnabledOAuthProviders, X as getGoogleAccessToken, ad as getOAuthProvider, ae as getRegisteredProviders, Q as isOAuthProviderEnabled, H as issueOneTimeTokenService, n as loginService, o as logoutService, M as oauthCallbackService, $ as oauthNativeService, K as oauthStartService, a2 as optionalAuth, ac as registerOAuthProvider, z as registerPublicKeyService, r as registerService, T as requireEnabledProvider, D as revokeKeyService, B as rotateKeyService, u as sendVerificationCodeService, v as verifyCodeService, J as verifyOneTimeTokenService } from './authenticate-ofdEmk6x.js';
 import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
-import { K as KeyAlgorithmType, b as InvitationStatus, d as SocialProvider } from './types-BtksCI9X.js';
-export { I as INVITATION_STATUSES, a as KEY_ALGORITHM, S as SOCIAL_PROVIDERS, U as USER_STATUSES, c as UserStatus } from './types-BtksCI9X.js';
+import { K as KeyAlgorithmType, c as InvitationStatus, e as SocialProvider, g as AccountDeletionRequestedBy, h as PurgeStrategy } from './types-1BMx0OX1.js';
+export { b as ACCOUNT_DELETION_REQUESTED_BY, A as ACCOUNT_DELETION_REQUEST_STATUSES, f as AccountDeletionRequestStatus, I as INVITATION_STATUSES, a as KEY_ALGORITHM, P as PURGE_STRATEGIES, S as SOCIAL_PROVIDERS, U as USER_STATUSES, d as UserStatus } from './types-1BMx0OX1.js';
 import { UserProfile as UserProfile$1, ProfileInfo } from '@spfn/auth';
 import { BaseRepository } from '@spfn/core/db';
 import { Context } from 'hono';
 import * as _spfn_core_route from '@spfn/core/route';
 import { Algorithm } from 'jsonwebtoken';
-export { S as SessionData, g as getSessionInfo, s as sealSession, a as shouldRefreshSession, u as unsealSession } from './session-s_hiXmXC.js';
+export { S as SessionData, g as getSessionInfo, s as sealSession, a as shouldRefreshSession, u as unsealSession } from './session-CGxgH3C9.js';
 import { JWTPayload } from 'jose';
 import { SSETokenStore, SSETokenManager } from '@spfn/core/event/sse';
 import * as _spfn_core_logger from '@spfn/core/logger';
+import * as _spfn_core_job from '@spfn/core/job';
 import * as _spfn_core_event from '@spfn/core/event';
 import * as _sinclair_typebox from '@sinclair/typebox';
 import '@spfn/auth/server';
@@ -33,6 +34,40 @@ declare const users: drizzle_orm_pg_core.PgTableWithColumns<{
     name: "users";
     schema: string;
     columns: {
+        deletedAt: drizzle_orm_pg_core.PgColumn<{
+            name: "deleted_at";
+            tableName: "users";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        deletedBy: drizzle_orm_pg_core.PgColumn<{
+            name: "deleted_by";
+            tableName: "users";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
         createdAt: drizzle_orm_pg_core.PgColumn<{
             name: "created_at";
             tableName: "users";
@@ -208,14 +243,14 @@ declare const users: drizzle_orm_pg_core.PgTableWithColumns<{
             tableName: "users";
             dataType: "string";
             columnType: "PgText";
-            data: "active" | "inactive" | "suspended";
+            data: "active" | "inactive" | "suspended" | "pending_deletion" | "deleted";
             driverParam: string;
             notNull: true;
             hasDefault: true;
             isPrimaryKey: false;
             isAutoincrement: false;
             hasRuntimeDefault: false;
-            enumValues: ["active", "inactive", "suspended"] & [string, ...string[]];
+            enumValues: ["active", "inactive", "suspended", "pending_deletion", "deleted"] & [string, ...string[]];
             baseColumn: never;
             identity: undefined;
             generated: undefined;
@@ -287,6 +322,8 @@ type NewUser = typeof users.$inferInsert;
  * Get user by ID
  */
 declare function getUserByIdService(userId: number): Promise<{
+    deletedAt: Date | null;
+    deletedBy: string | null;
     createdAt: Date;
     updatedAt: Date;
     id: number;
@@ -297,7 +334,7 @@ declare function getUserByIdService(userId: number): Promise<{
     passwordHash: string | null;
     passwordChangeRequired: boolean;
     roleId: number;
-    status: "active" | "inactive" | "suspended";
+    status: "active" | "inactive" | "suspended" | "pending_deletion" | "deleted";
     emailVerifiedAt: Date | null;
     phoneVerifiedAt: Date | null;
     lastLoginAt: Date | null;
@@ -306,6 +343,8 @@ declare function getUserByIdService(userId: number): Promise<{
  * Get user by email
  */
 declare function getUserByEmailService(email: string): Promise<{
+    deletedAt: Date | null;
+    deletedBy: string | null;
     createdAt: Date;
     updatedAt: Date;
     id: number;
@@ -316,7 +355,7 @@ declare function getUserByEmailService(email: string): Promise<{
     passwordHash: string | null;
     passwordChangeRequired: boolean;
     roleId: number;
-    status: "active" | "inactive" | "suspended";
+    status: "active" | "inactive" | "suspended" | "pending_deletion" | "deleted";
     emailVerifiedAt: Date | null;
     phoneVerifiedAt: Date | null;
     lastLoginAt: Date | null;
@@ -325,6 +364,8 @@ declare function getUserByEmailService(email: string): Promise<{
  * Get user by phone
  */
 declare function getUserByPhoneService(phone: string): Promise<{
+    deletedAt: Date | null;
+    deletedBy: string | null;
     createdAt: Date;
     updatedAt: Date;
     id: number;
@@ -335,7 +376,7 @@ declare function getUserByPhoneService(phone: string): Promise<{
     passwordHash: string | null;
     passwordChangeRequired: boolean;
     roleId: number;
-    status: "active" | "inactive" | "suspended";
+    status: "active" | "inactive" | "suspended" | "pending_deletion" | "deleted";
     emailVerifiedAt: Date | null;
     phoneVerifiedAt: Date | null;
     lastLoginAt: Date | null;
@@ -363,6 +404,8 @@ declare function checkUsernameAvailableService(username: string): Promise<boolea
  * @throws UsernameAlreadyTakenError if username is already in use by another user
  */
 declare function updateUsernameService(userId: string | number | bigint, username: string | null): Promise<{
+    deletedAt: Date | null;
+    deletedBy: string | null;
     createdAt: Date;
     updatedAt: Date;
     id: number;
@@ -373,7 +416,7 @@ declare function updateUsernameService(userId: string | number | bigint, usernam
     passwordHash: string | null;
     passwordChangeRequired: boolean;
     roleId: number;
-    status: "active" | "inactive" | "suspended";
+    status: "active" | "inactive" | "suspended" | "pending_deletion" | "deleted";
     emailVerifiedAt: Date | null;
     phoneVerifiedAt: Date | null;
     lastLoginAt: Date | null;
@@ -1581,6 +1624,45 @@ interface VerifyIdTokenParams {
  */
 declare function verifyIdToken(params: VerifyIdTokenParams): Promise<JWTPayload>;
 
+/**
+ * @spfn/auth - Social Token At-Rest Encryption
+ *
+ * OAuth access/refresh tokens are encrypted with a backend-only rotating keyring.
+ * The active key is the first entry in SPFN_AUTH_TOKEN_ENCRYPTION_KEYS; remaining
+ * keys are decrypt-only grace keys. Ciphertext is bound to its provider account
+ * and token type with AES-GCM additional authenticated data (AAD).
+ *
+ * v2 format: enc:v2:<keyId>:<base64url(iv | authTag | ciphertext)>
+ * v1 format: enc:v1:<base64(iv | authTag | ciphertext)> (legacy session-secret key)
+ *
+ * Never include token or key material in logs or error messages.
+ */
+
+type OAuthTokenType = 'access' | 'refresh';
+interface OAuthTokenContext {
+    provider: SocialProvider;
+    providerUserId: string;
+    tokenType: OAuthTokenType;
+}
+interface DecryptedOAuthToken {
+    value: string;
+    /** True for plaintext, v1, or ciphertext encrypted with a non-active v2 key. */
+    needsRotation: boolean;
+}
+interface OAuthTokenCipher {
+    encrypt(value: string, context: OAuthTokenContext): Promise<string>;
+    decrypt(value: string, context: OAuthTokenContext): Promise<DecryptedOAuthToken>;
+}
+declare class EnvironmentKeyringTokenCipher implements OAuthTokenCipher {
+    encrypt(value: string, context: OAuthTokenContext): Promise<string>;
+    decrypt(value: string, context: OAuthTokenContext): Promise<DecryptedOAuthToken>;
+}
+/** Configure an external/KMS-backed cipher before the auth server starts. */
+declare function configureOAuthTokenCipher(cipher: OAuthTokenCipher): void;
+declare function encryptToken(value: string, context: OAuthTokenContext): Promise<string>;
+declare function decryptToken(value: string, context: OAuthTokenContext): Promise<DecryptedOAuthToken>;
+declare function isEncrypted(value: string): boolean;
+
 /**
  * Google OAuthProvider 구현
  *
@@ -1593,18 +1675,362 @@ declare function verifyIdToken(params: VerifyIdTokenParams): Promise<JWTPayload>
 declare const googleProvider: OAuthProvider;
 
 /**
- * Apple OAuthProvider 구현 (native id_token 검증 전용)
+ * Apple OAuthProvider 구현 (native id_token 검증 전용)
+ *
+ * Apple은 Android·웹에 네이티브 SDK를 제공하지 않으므로, web 흐름(Sign in with Apple JS,
+ * Android Custom Tab)도 결국 id_token을 클라이언트가 받아 서버로 보낸다. 서버는 그 id_token을
+ * Apple JWKS로 검증만 한다(authorization code 교환·client secret 없음).
+ *
+ * 따라서 web 메서드(getAuthUrl/exchangeCodeForTokens/getUserInfo)는 지원하지 않는다.
+ *
+ * 이 모듈을 import 하는 것만으로 apple provider가 registry에 자기 등록된다.
+ */
+
+declare const appleProvider: OAuthProvider;
+
+/**
+ * Kakao Login OAuthProvider (web authorization-code flow).
+ */
+
+declare const kakaoProvider: OAuthProvider;
+
+/**
+ * Naver Login OAuthProvider (web authorization-code flow).
+ */
+
+declare const naverProvider: OAuthProvider;
+
+/**
+ * @spfn/auth - Account Deletion Requests Entity
+ *
+ * Audit trail for account deletion/recovery. Rows are never deleted — even after
+ * a hard-delete purge — so "who requested/recovered/purged what, when" survives
+ * the user row itself (개인정보보호법 제21조 3항 분리 보존 원칙).
+ */
+declare const accountDeletionRequests: drizzle_orm_pg_core.PgTableWithColumns<{
+    name: "account_deletion_requests";
+    schema: string;
+    columns: {
+        createdAt: drizzle_orm_pg_core.PgColumn<{
+            name: "created_at";
+            tableName: "account_deletion_requests";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        updatedAt: drizzle_orm_pg_core.PgColumn<{
+            name: "updated_at";
+            tableName: "account_deletion_requests";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        id: drizzle_orm_pg_core.PgColumn<{
+            name: "id";
+            tableName: "account_deletion_requests";
+            dataType: "number";
+            columnType: "PgBigSerial53";
+            data: number;
+            driverParam: number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        userId: drizzle_orm_pg_core.PgColumn<{
+            name: `${string}_id`;
+            tableName: "account_deletion_requests";
+            dataType: "number";
+            columnType: "PgBigInt53";
+            data: number;
+            driverParam: string | number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        userPublicId: drizzle_orm_pg_core.PgColumn<{
+            name: "user_public_id";
+            tableName: "account_deletion_requests";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        requestedAt: drizzle_orm_pg_core.PgColumn<{
+            name: string;
+            tableName: "account_deletion_requests";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        purgeScheduledAt: drizzle_orm_pg_core.PgColumn<{
+            name: string;
+            tableName: "account_deletion_requests";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        status: drizzle_orm_pg_core.PgColumn<{
+            name: string;
+            tableName: "account_deletion_requests";
+            dataType: "string";
+            columnType: "PgText";
+            data: "pending" | "cancelled" | "completed";
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["pending", "cancelled", "completed"] & [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        requestedBy: drizzle_orm_pg_core.PgColumn<{
+            name: string;
+            tableName: "account_deletion_requests";
+            dataType: "string";
+            columnType: "PgText";
+            data: "admin" | "self";
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["self", "admin"] & [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        reason: drizzle_orm_pg_core.PgColumn<{
+            name: "reason";
+            tableName: "account_deletion_requests";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        cancelledAt: drizzle_orm_pg_core.PgColumn<{
+            name: string;
+            tableName: "account_deletion_requests";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        completedAt: drizzle_orm_pg_core.PgColumn<{
+            name: string;
+            tableName: "account_deletion_requests";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        purgeStrategy: drizzle_orm_pg_core.PgColumn<{
+            name: string;
+            tableName: "account_deletion_requests";
+            dataType: "string";
+            columnType: "PgText";
+            data: "anonymize" | "hard-delete";
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: ["anonymize", "hard-delete"] & [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
+type AccountDeletionRequest = typeof accountDeletionRequests.$inferSelect;
+type NewAccountDeletionRequest = typeof accountDeletionRequests.$inferInsert;
+
+/**
+ * @spfn/auth - Account Deletion Service
+ *
+ * Request / cancel (recovery) / purge for the account deletion lifecycle.
+ *
+ * Lifecycle:
+ *   active --request(reauth)--> pending_deletion --grace expires(cron)--> deleted (anonymize) | row removed (hard-delete)
+ *     ^                              |
+ *     +-------cancel(reauth)---------+          immediate = grace period of 0, same pipeline
+ */
+
+interface PendingDeletionInfo {
+    purgeScheduledAt: Date;
+}
+/**
+ * Look up the pending deletion request's `purgeScheduledAt` for a `pending_deletion`
+ * user, so login/OAuth/authenticate can surface it on `AccountPendingDeletionError`.
+ * Returns null if there is no pending row (shouldn't normally happen for a user in
+ * that status, but the caller falls back to an error without the date).
+ *
+ * Reads from the write primary, not a replica — this backs the same status gates
+ * that decide whether to grant a session, so a replica-lag window must not let a
+ * just-requested deletion go unnoticed.
+ */
+declare function getPendingDeletionInfo(userId: number): Promise<PendingDeletionInfo | null>;
+interface RequestAccountDeletionParams {
+    /** Who initiated this — 'self' requires re-auth via password/verificationToken; 'admin' does not. */
+    requestedBy: AccountDeletionRequestedBy;
+    password?: string;
+    verificationToken?: string;
+    reason?: string;
+    /** Skip the grace period and purge inline. Self-service requires `deletion.allowSelfImmediate`. */
+    immediate?: boolean;
+}
+interface RequestAccountDeletionResult {
+    requestId: number;
+    purgeScheduledAt: Date;
+}
+/**
+ * Request account deletion (self-service re-auth gate, or trusted admin/DSR call).
+ *
+ * Sets status -> 'pending_deletion', records the request, revokes every active
+ * session key, and (after commit) emits `auth.deletion.requested` and sends the
+ * request-received notice. With a zero grace period (explicit `immediate: true`,
+ * gated for self-service by `allowSelfImmediate`), purges inline instead of
+ * waiting for the cron sweep.
+ */
+declare function requestAccountDeletionService(userId: number, params: RequestAccountDeletionParams): Promise<RequestAccountDeletionResult>;
+interface CancelAccountDeletionParams {
+    email?: string;
+    phone?: string;
+    password?: string;
+    verificationToken?: string;
+}
+interface CancelAccountDeletionResult {
+    userId: string;
+}
+/**
+ * Cancel a pending deletion (recovery). All sessions were revoked at request
+ * time, so this is credential-based (no Bearer token) rather than auth-context-based.
  *
- * Apple은 Android·웹에 네이티브 SDK를 제공하지 않으므로, web 흐름(Sign in with Apple JS,
- * Android Custom Tab)도 결국 id_token을 클라이언트가 받아 서버로 보낸다. 서버는 그 id_token을
- * Apple JWKS로 검증만 한다(authorization code 교환·client secret 없음).
+ * Credential verification always runs before the caller learns whether the
+ * account exists / is pending deletion — otherwise this endpoint could be used
+ * to enumerate accounts or probe deletion status without a valid credential,
+ * the same posture `loginService` takes for missing accounts.
  *
- * 따라서 web 메서드(getAuthUrl/exchangeCodeForTokens/getUserInfo)는 지원하지 않는다.
+ * Claims the `account_deletion_requests` row (conditional `WHERE status =
+ * 'pending'`) before touching `users` — see the comment at that claim below for
+ * why the `users` row must not move until the claim succeeds.
+ */
+declare function cancelAccountDeletionService(params: CancelAccountDeletionParams): Promise<CancelAccountDeletionResult>;
+interface PurgeUserResult {
+    outcome: 'purged' | 'skipped' | 'not-found';
+}
+/**
+ * Purge a user's pending deletion request immediately, ignoring `purgeScheduledAt`.
+ * Admin/GDPR-response entry point — the route (if any) belongs to the app.
  *
- * 이 모듈을 import 하는 것만으로 apple provider가 registry에 자기 등록된다.
+ * @throws DeletionNotRequestedError if the user has no pending request
  */
-
-declare const appleProvider: OAuthProvider;
+declare function purgeUserService(userId: number): Promise<PurgeUserResult>;
+interface SweepDuePurgesResult {
+    processed: number;
+    purged: number;
+    skipped: number;
+}
+/**
+ * Sweep every request whose grace period has elapsed and purge it. Called by the
+ * `auth.deletion.purge` cron job. One user's failure (thrown error, not just an
+ * `onBeforePurge` skip) is logged and does not stop the rest of the sweep — it
+ * stays `pending` and is retried on the next tick.
+ */
+declare function sweepDuePurges(now?: Date): Promise<SweepDuePurgesResult>;
 
 /**
  * @spfn/auth - Database Schema Definition
@@ -2473,14 +2899,14 @@ declare const verificationCodes: drizzle_orm_pg_core.PgTableWithColumns<{
             tableName: "verification_codes";
             dataType: "string";
             columnType: "PgText";
-            data: "registration" | "login" | "password_reset" | "email_change" | "phone_change";
+            data: "registration" | "login" | "password_reset" | "email_change" | "phone_change" | "account_deletion";
             driverParam: string;
             notNull: true;
             hasDefault: false;
             isPrimaryKey: false;
             isAutoincrement: false;
             hasRuntimeDefault: false;
-            enumValues: ["registration", "login", "password_reset", "email_change", "phone_change"] & [string, ...string[]];
+            enumValues: ["registration", "login", "password_reset", "email_change", "phone_change", "account_deletion"] & [string, ...string[]];
             baseColumn: never;
             identity: undefined;
             generated: undefined;
@@ -3106,6 +3532,33 @@ declare class UsersRepository extends BaseRepository {
      * Read replica 사용
      */
     findById(id: number): 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;
+    }>;
+    /**
+     * ID로 사용자 조회 — Write primary에서 직접 읽는다.
+     *
+     * 복제 지연 창에서 status 전이(예: 삭제 요청으로 pending_deletion 전환)를 놓치면
+     * 안 되는 게이트(OAuth 세션 발급 등)가 사용한다. 일반 조회는 `findById`(replica)를
+     * 계속 사용할 것.
+     */
+    findByIdOnPrimary(id: number): Promise<{
+        deletedAt: Date | null;
+        deletedBy: string | null;
         createdAt: Date;
         updatedAt: Date;
         id: number;
@@ -3116,7 +3569,7 @@ declare class UsersRepository extends BaseRepository {
         passwordHash: string | null;
         passwordChangeRequired: boolean;
         roleId: number;
-        status: "active" | "inactive" | "suspended";
+        status: "active" | "inactive" | "suspended" | "pending_deletion" | "deleted";
         emailVerifiedAt: Date | null;
         phoneVerifiedAt: Date | null;
         lastLoginAt: Date | null;
@@ -3126,6 +3579,8 @@ declare class UsersRepository extends BaseRepository {
      * Read replica 사용
      */
     findByEmail(email: string): Promise<{
+        deletedAt: Date | null;
+        deletedBy: string | null;
         createdAt: Date;
         updatedAt: Date;
         id: number;
@@ -3136,7 +3591,7 @@ declare class UsersRepository extends BaseRepository {
         passwordHash: string | null;
         passwordChangeRequired: boolean;
         roleId: number;
-        status: "active" | "inactive" | "suspended";
+        status: "active" | "inactive" | "suspended" | "pending_deletion" | "deleted";
         emailVerifiedAt: Date | null;
         phoneVerifiedAt: Date | null;
         lastLoginAt: Date | null;
@@ -3146,6 +3601,8 @@ declare class UsersRepository extends BaseRepository {
      * Read replica 사용
      */
     findByPhone(phone: string): Promise<{
+        deletedAt: Date | null;
+        deletedBy: string | null;
         createdAt: Date;
         updatedAt: Date;
         id: number;
@@ -3156,7 +3613,7 @@ declare class UsersRepository extends BaseRepository {
         passwordHash: string | null;
         passwordChangeRequired: boolean;
         roleId: number;
-        status: "active" | "inactive" | "suspended";
+        status: "active" | "inactive" | "suspended" | "pending_deletion" | "deleted";
         emailVerifiedAt: Date | null;
         phoneVerifiedAt: Date | null;
         lastLoginAt: Date | null;
@@ -3166,6 +3623,8 @@ declare class UsersRepository extends BaseRepository {
      * Read replica 사용
      */
     findByUsername(username: string): Promise<{
+        deletedAt: Date | null;
+        deletedBy: string | null;
         createdAt: Date;
         updatedAt: Date;
         id: number;
@@ -3176,7 +3635,7 @@ declare class UsersRepository extends BaseRepository {
         passwordHash: string | null;
         passwordChangeRequired: boolean;
         roleId: number;
-        status: "active" | "inactive" | "suspended";
+        status: "active" | "inactive" | "suspended" | "pending_deletion" | "deleted";
         emailVerifiedAt: Date | null;
         phoneVerifiedAt: Date | null;
         lastLoginAt: Date | null;
@@ -3186,6 +3645,8 @@ declare class UsersRepository extends BaseRepository {
      * Read replica 사용
      */
     findByPublicId(publicId: string): Promise<{
+        deletedAt: Date | null;
+        deletedBy: string | null;
         createdAt: Date;
         updatedAt: Date;
         id: number;
@@ -3196,7 +3657,7 @@ declare class UsersRepository extends BaseRepository {
         passwordHash: string | null;
         passwordChangeRequired: boolean;
         roleId: number;
-        status: "active" | "inactive" | "suspended";
+        status: "active" | "inactive" | "suspended" | "pending_deletion" | "deleted";
         emailVerifiedAt: Date | null;
         phoneVerifiedAt: Date | null;
         lastLoginAt: Date | null;
@@ -3206,6 +3667,8 @@ declare class UsersRepository extends BaseRepository {
      * Read replica 사용
      */
     findByEmailOrPhone(email?: string, phone?: string): Promise<{
+        deletedAt: Date | null;
+        deletedBy: string | null;
         createdAt: Date;
         updatedAt: Date;
         id: number;
@@ -3216,7 +3679,7 @@ declare class UsersRepository extends BaseRepository {
         passwordHash: string | null;
         passwordChangeRequired: boolean;
         roleId: number;
-        status: "active" | "inactive" | "suspended";
+        status: "active" | "inactive" | "suspended" | "pending_deletion" | "deleted";
         emailVerifiedAt: Date | null;
         phoneVerifiedAt: Date | null;
         lastLoginAt: Date | null;
@@ -3229,6 +3692,8 @@ declare class UsersRepository extends BaseRepository {
      */
     findByIdWithRole(id: number): Promise<{
         user: {
+            deletedAt: Date | null;
+            deletedBy: string | null;
             createdAt: Date;
             updatedAt: Date;
             id: number;
@@ -3239,7 +3704,7 @@ declare class UsersRepository extends BaseRepository {
             passwordHash: string | null;
             passwordChangeRequired: boolean;
             roleId: number;
-            status: "active" | "inactive" | "suspended";
+            status: "active" | "inactive" | "suspended" | "pending_deletion" | "deleted";
             emailVerifiedAt: Date | null;
             phoneVerifiedAt: Date | null;
             lastLoginAt: Date | null;
@@ -3265,16 +3730,47 @@ declare class UsersRepository extends BaseRepository {
         roleId: number;
         createdAt: Date;
         updatedAt: Date;
-        status: "active" | "inactive" | "suspended";
+        status: "active" | "inactive" | "suspended" | "pending_deletion" | "deleted";
         emailVerifiedAt: Date | null;
         phoneVerifiedAt: Date | null;
         lastLoginAt: Date | null;
+        deletedAt: Date | null;
+        deletedBy: string | null;
     }>;
     /**
      * 사용자 정보 업데이트
      * Write primary 사용
      */
     updateById(id: number, data: Partial<NewUser>): 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;
+    }>;
+    /**
+     * 계정 삭제 취소(복구) — `WHERE status = 'pending_deletion'` 조건부 UPDATE.
+     *
+     * cancelAccountDeletionService가 account_deletion_requests claim(조건부
+     * markCancelled)에 성공한 **이후에만** 호출한다. 그 claim이 이미 purge와의
+     * 경합을 해결하므로 이 조건은 방어적 이중 안전장치 — 0 row 매치(= 이미
+     * status가 바뀐 상태) 시 null을 반환하며 예외를 던지지 않는다.
+     * Write primary 사용
+     */
+    reactivateFromPendingDeletion(id: number): Promise<{
+        deletedAt: Date | null;
+        deletedBy: string | null;
         createdAt: Date;
         updatedAt: Date;
         id: number;
@@ -3285,7 +3781,7 @@ declare class UsersRepository extends BaseRepository {
         passwordHash: string | null;
         passwordChangeRequired: boolean;
         roleId: number;
-        status: "active" | "inactive" | "suspended";
+        status: "active" | "inactive" | "suspended" | "pending_deletion" | "deleted";
         emailVerifiedAt: Date | null;
         phoneVerifiedAt: Date | null;
         lastLoginAt: Date | null;
@@ -3295,6 +3791,8 @@ declare class UsersRepository extends BaseRepository {
      * Write primary 사용
      */
     updatePassword(id: number, passwordHash: string, clearPasswordChangeRequired?: boolean): Promise<{
+        deletedAt: Date | null;
+        deletedBy: string | null;
         createdAt: Date;
         updatedAt: Date;
         id: number;
@@ -3305,7 +3803,7 @@ declare class UsersRepository extends BaseRepository {
         passwordHash: string | null;
         passwordChangeRequired: boolean;
         roleId: number;
-        status: "active" | "inactive" | "suspended";
+        status: "active" | "inactive" | "suspended" | "pending_deletion" | "deleted";
         emailVerifiedAt: Date | null;
         phoneVerifiedAt: Date | null;
         lastLoginAt: Date | null;
@@ -3315,6 +3813,8 @@ declare class UsersRepository extends BaseRepository {
      * Write primary 사용
      */
     updateLastLogin(id: number): Promise<{
+        deletedAt: Date | null;
+        deletedBy: string | null;
         createdAt: Date;
         updatedAt: Date;
         id: number;
@@ -3325,7 +3825,7 @@ declare class UsersRepository extends BaseRepository {
         passwordHash: string | null;
         passwordChangeRequired: boolean;
         roleId: number;
-        status: "active" | "inactive" | "suspended";
+        status: "active" | "inactive" | "suspended" | "pending_deletion" | "deleted";
         emailVerifiedAt: Date | null;
         phoneVerifiedAt: Date | null;
         lastLoginAt: Date | null;
@@ -3345,10 +3845,12 @@ declare class UsersRepository extends BaseRepository {
         roleId: number;
         createdAt: Date;
         updatedAt: Date;
-        status: "active" | "inactive" | "suspended";
+        status: "active" | "inactive" | "suspended" | "pending_deletion" | "deleted";
         emailVerifiedAt: Date | null;
         phoneVerifiedAt: Date | null;
         lastLoginAt: Date | null;
+        deletedAt: Date | null;
+        deletedBy: string | null;
     }>;
     /**
      * User의 Role과 Permissions 조회 (JOIN)
@@ -3553,6 +4055,14 @@ declare class KeysRepository extends BaseRepository {
         revokedAt: Date | null;
         revokedReason: string | null;
     }>;
+    /**
+     * 사용자의 모든 공개키 삭제 (계정 익명화 파기용)
+     *
+     * hard-delete는 FK cascade로 자동 처리되지만, anonymize 모드는 users row를
+     * 남기므로 자식 row를 직접 지워야 한다.
+     * Write primary 사용
+     */
+    deleteAllByUserId(userId: number): Promise<number>;
     /**
      * 마지막 사용 시간 업데이트
      * Write primary 사용
@@ -3630,7 +4140,7 @@ declare class VerificationCodesRepository extends BaseRepository {
         target: string;
         targetType: "email" | "phone";
         code: string;
-        purpose: "registration" | "login" | "password_reset" | "email_change" | "phone_change";
+        purpose: "registration" | "login" | "password_reset" | "email_change" | "phone_change" | "account_deletion";
         expiresAt: Date;
         usedAt: Date | null;
         attempts: number;
@@ -3646,7 +4156,7 @@ declare class VerificationCodesRepository extends BaseRepository {
         target: string;
         targetType: "email" | "phone";
         code: string;
-        purpose: "registration" | "login" | "password_reset" | "email_change" | "phone_change";
+        purpose: "registration" | "login" | "password_reset" | "email_change" | "phone_change" | "account_deletion";
         expiresAt: Date;
         usedAt: Date | null;
         attempts: number;
@@ -3658,7 +4168,7 @@ declare class VerificationCodesRepository extends BaseRepository {
     create(data: NewVerificationCode): Promise<{
         target: string;
         targetType: "email" | "phone";
-        purpose: "registration" | "login" | "password_reset" | "email_change" | "phone_change";
+        purpose: "registration" | "login" | "password_reset" | "email_change" | "phone_change" | "account_deletion";
         code: string;
         id: number;
         createdAt: Date;
@@ -3678,7 +4188,7 @@ declare class VerificationCodesRepository extends BaseRepository {
         target: string;
         targetType: "email" | "phone";
         code: string;
-        purpose: "registration" | "login" | "password_reset" | "email_change" | "phone_change";
+        purpose: "registration" | "login" | "password_reset" | "email_change" | "phone_change" | "account_deletion";
         expiresAt: Date;
         usedAt: Date | null;
         attempts: number;
@@ -3694,7 +4204,7 @@ declare class VerificationCodesRepository extends BaseRepository {
         target: string;
         targetType: "email" | "phone";
         code: string;
-        purpose: "registration" | "login" | "password_reset" | "email_change" | "phone_change";
+        purpose: "registration" | "login" | "password_reset" | "email_change" | "phone_change" | "account_deletion";
         expiresAt: Date;
         usedAt: Date | null;
         attempts: number;
@@ -3704,6 +4214,14 @@ declare class VerificationCodesRepository extends BaseRepository {
      * Write primary 사용
      */
     deleteExpired(): Promise<number>;
+    /**
+     * Target(email/phone)의 모든 인증 코드 삭제 (계정 파기용)
+     *
+     * verificationCodes는 userId FK가 없고 target 텍스트로만 연결되므로, 파기 시
+     * 원래 email/phone을 이 메서드로 직접 정리해야 한다.
+     * Write primary 사용
+     */
+    deleteByTarget(target: string): Promise<number>;
     /**
      * Target의 모든 이전 코드 무효화 (새 코드 발급 시)
      * Write primary 사용
@@ -4059,8 +4577,8 @@ declare class UserPermissionsRepository extends BaseRepository {
         createdAt: Date;
         updatedAt: Date;
         permissionId: number;
-        expiresAt: Date | null;
         reason: string | null;
+        expiresAt: Date | null;
         granted: boolean;
     }>;
     /**
@@ -4085,8 +4603,8 @@ declare class UserPermissionsRepository extends BaseRepository {
         createdAt: Date;
         updatedAt: Date;
         permissionId: number;
-        expiresAt: Date | null;
         reason: string | null;
+        expiresAt: Date | null;
         granted: boolean;
     }>;
     /**
@@ -4730,6 +5248,14 @@ declare class SocialAccountsRepository extends BaseRepository {
         refreshToken: string | null;
         tokenExpiresAt: Date | null;
     }>;
+    /**
+     * 사용자의 모든 소셜 계정 삭제 (계정 익명화 파기용)
+     *
+     * provider unique index(provider, providerUserId)를 해제해 같은 소셜 계정으로
+     * 재가입할 수 있게 한다.
+     * Write primary 사용
+     */
+    deleteAllByUserId(userId: number): Promise<number>;
 }
 declare const socialAccountsRepository: SocialAccountsRepository;
 
@@ -4752,6 +5278,168 @@ declare class AuthMetadataRepository extends BaseRepository {
 }
 declare const authMetadataRepository: AuthMetadataRepository;
 
+/**
+ * Account Deletion Requests Repository
+ *
+ * 계정 탈퇴 요청/복구/파기 감사 이력 관리를 위한 Repository
+ * BaseRepository를 상속받아 자동 트랜잭션 컨텍스트 지원 및 Read/Write 분리
+ *
+ * Row는 절대 삭제하지 않는다 — status 전이(pending -> cancelled|completed)로만 갱신.
+ */
+
+/**
+ * Account Deletion Requests Repository 클래스
+ */
+declare class AccountDeletionRequestsRepository extends BaseRepository {
+    /**
+     * ID로 요청 조회
+     * Read replica 사용
+     */
+    findById(id: number): Promise<{
+        createdAt: Date;
+        updatedAt: Date;
+        id: number;
+        userId: number | null;
+        userPublicId: string;
+        requestedAt: Date;
+        purgeScheduledAt: Date;
+        status: "pending" | "cancelled" | "completed";
+        requestedBy: "admin" | "self";
+        reason: string | null;
+        cancelledAt: Date | null;
+        completedAt: Date | null;
+        purgeStrategy: "anonymize" | "hard-delete" | null;
+    }>;
+    /**
+     * User ID로 pending 요청 조회 (유저당 최대 1건, partial unique index로 보장)
+     * Read replica 사용
+     */
+    findPendingByUserId(userId: number): Promise<{
+        createdAt: Date;
+        updatedAt: Date;
+        id: number;
+        userId: number | null;
+        userPublicId: string;
+        requestedAt: Date;
+        purgeScheduledAt: Date;
+        status: "pending" | "cancelled" | "completed";
+        requestedBy: "admin" | "self";
+        reason: string | null;
+        cancelledAt: Date | null;
+        completedAt: Date | null;
+        purgeStrategy: "anonymize" | "hard-delete" | null;
+    }>;
+    /**
+     * User ID로 pending 요청 조회 — Write primary에서 직접 읽는다.
+     *
+     * 로그인/OAuth/authenticate 게이트가 pending_deletion 유저의 purgeScheduledAt을
+     * 표시하는 데 쓴다. 이 경로들은 복제 지연이 있으면 방금 커밋된 상태 전이를 놓칠 수
+     * 있어(예: 삭제 요청 직후 OAuth 로그인 시도), replica가 아닌 primary에서 읽는다.
+     */
+    findPendingByUserIdOnPrimary(userId: number): Promise<{
+        createdAt: Date;
+        updatedAt: Date;
+        id: number;
+        userId: number | null;
+        userPublicId: string;
+        requestedAt: Date;
+        purgeScheduledAt: Date;
+        status: "pending" | "cancelled" | "completed";
+        requestedBy: "admin" | "self";
+        reason: string | null;
+        cancelledAt: Date | null;
+        completedAt: Date | null;
+        purgeStrategy: "anonymize" | "hard-delete" | null;
+    }>;
+    /**
+     * 파기 스윕 대상 조회 — status='pending' AND purgeScheduledAt <= now
+     * Read replica 사용
+     */
+    findDueForPurge(now: Date): Promise<{
+        createdAt: Date;
+        updatedAt: Date;
+        id: number;
+        userId: number | null;
+        userPublicId: string;
+        requestedAt: Date;
+        purgeScheduledAt: Date;
+        status: "pending" | "cancelled" | "completed";
+        requestedBy: "admin" | "self";
+        reason: string | null;
+        cancelledAt: Date | null;
+        completedAt: Date | null;
+        purgeStrategy: "anonymize" | "hard-delete" | null;
+    }[]>;
+    /**
+     * 요청 생성
+     * Write primary 사용
+     */
+    create(data: NewAccountDeletionRequest): Promise<{
+        userId: number | null;
+        id: number;
+        createdAt: Date;
+        updatedAt: Date;
+        status: "pending" | "cancelled" | "completed";
+        reason: string | null;
+        purgeScheduledAt: Date;
+        cancelledAt: Date | null;
+        userPublicId: string;
+        requestedAt: Date;
+        requestedBy: "admin" | "self";
+        completedAt: Date | null;
+        purgeStrategy: "anonymize" | "hard-delete" | null;
+    }>;
+    /**
+     * 요청 취소 (복구)
+     *
+     * `WHERE status = 'pending'` 조건부 UPDATE — 이미 completed(파기 완료)된 row를
+     * 뒤늦게 도착한 cancel이 덮어쓰지 않도록 한다. 0 row 매치(= 이미 completed거나
+     * cancelled) 시 null을 반환하니 호출자가 그 결과를 확인해야 한다.
+     * Write primary 사용
+     */
+    markCancelled(id: number): Promise<{
+        createdAt: Date;
+        updatedAt: Date;
+        id: number;
+        userId: number | null;
+        userPublicId: string;
+        requestedAt: Date;
+        purgeScheduledAt: Date;
+        status: "pending" | "cancelled" | "completed";
+        requestedBy: "admin" | "self";
+        reason: string | null;
+        cancelledAt: Date | null;
+        completedAt: Date | null;
+        purgeStrategy: "anonymize" | "hard-delete" | null;
+    }>;
+    /**
+     * 요청 완료 처리 (파기 실행 직전에 호출하는 "claim" — 파기 실행 후가 아니다)
+     *
+     * `WHERE status = 'pending'` 조건부 UPDATE. Postgres UPDATE는 매치되는 row에 락을
+     * 걸고 최신 커밋 상태로 WHERE를 재평가하므로, 이 호출 하나로 (1) 동시에 취소된
+     * row를 안전하게 걸러내고 (2) row-level 락으로 동시 파기 시도를 직렬화한다.
+     * 0 row 매치(= 이미 취소되었거나 다른 파기가 먼저 처리함) 시 null을 반환 — 호출자는
+     * destructive DML을 실행하기 **전에** 반드시 이 결과를 확인해야 한다.
+     * Write primary 사용
+     */
+    markCompleted(id: number, purgeStrategy: PurgeStrategy): Promise<{
+        createdAt: Date;
+        updatedAt: Date;
+        id: number;
+        userId: number | null;
+        userPublicId: string;
+        requestedAt: Date;
+        purgeScheduledAt: Date;
+        status: "pending" | "cancelled" | "completed";
+        requestedBy: "admin" | "self";
+        reason: string | null;
+        cancelledAt: Date | null;
+        completedAt: Date | null;
+        purgeStrategy: "anonymize" | "hard-delete" | null;
+    }>;
+}
+declare const accountDeletionRequestsRepository: AccountDeletionRequestsRepository;
+
 /**
  * @spfn/auth - Password Helpers
  *
@@ -4815,6 +5503,7 @@ declare function hashPassword(password: string): Promise<string>;
  * ```
  */
 declare function verifyPassword(password: string, hash: string): Promise<boolean>;
+declare function getDummyPasswordHash(): Promise<string>;
 /**
  * Validate password strength
  *
@@ -5202,10 +5891,12 @@ declare function getUser(c: Context | {
     roleId: number;
     createdAt: Date;
     updatedAt: Date;
-    status: "active" | "inactive" | "suspended";
+    status: "active" | "inactive" | "suspended" | "pending_deletion" | "deleted";
     emailVerifiedAt: Date | null;
     phoneVerifiedAt: Date | null;
     lastLoginAt: Date | null;
+    deletedAt: Date | null;
+    deletedBy: string | null;
 };
 /**
  * Get authenticated user ID from route context
@@ -5330,6 +6021,7 @@ declare function shouldRotateKey(createdAt: Date, rotationDays?: number): {
  *
  * Manages global auth configuration including session TTL
  */
+
 /**
  * Cookie names used by SPFN Auth
  *
@@ -5346,6 +6038,18 @@ declare const COOKIE_NAMES: {
     /** OAuth CSRF nonce — double-submit against the (encrypted) state.nonce at callback */
     readonly OAUTH_CSRF: string;
 };
+/**
+ * OAuth CSRF 쿠키를 PORT 접미사와 무관하게 전부 수집한다.
+ *
+ * 쿠키를 심는 쪽은 Next.js 프로세스, 읽는 쪽은 API 프로세스라 분리 배포에서는
+ * 두 프로세스의 PORT가 달라 COOKIE_NAMES.OAUTH_CSRF 정확 일치 조회가 빗나간다.
+ * nonce 자체가 랜덤값이고 암호화된 state의 nonce와 대조되므로, 접미사가 다른
+ * spfn_oauth_csrf* 후보를 모두 대조 대상으로 넘겨도 안전하다.
+ */
+declare function matchOAuthCsrfCookies(cookies: Record<string, string>): {
+    name: string;
+    value: string;
+}[];
 /**
  * Parse duration string to seconds
  *
@@ -5358,6 +6062,36 @@ declare const COOKIE_NAMES: {
  * parseDuration('3600')  // 3600
  */
 declare function parseDuration(duration: string | number): number;
+/**
+ * Registration channel passed to the beforeRegister hook
+ *
+ * - credentials: email/phone + password registration
+ * - oauth: new-user signup through a social provider (web or native flow)
+ * - invitation: invitation acceptance
+ */
+type RegisterChannel = 'credentials' | 'oauth' | 'invitation';
+/**
+ * Context passed to the beforeRegister hook
+ *
+ * Credentials (password, keys) are intentionally excluded — the hook is a
+ * policy gate, not a credential handler.
+ */
+interface BeforeRegisterContext {
+    channel: RegisterChannel;
+    /** Social provider — only set when channel is 'oauth' */
+    provider?: SocialProvider;
+    email?: string;
+    /**
+     * Whether the email is verified — only set when channel is 'oauth'.
+     * OAuth providers may report an unverified (spoofable) email; the created
+     * account stores it as null in that case, so email-based policies must
+     * check this flag. credentials/invitation emails are already verified.
+     */
+    emailVerified?: boolean;
+    phone?: string;
+    /** App-supplied registration metadata (register params / OAuth start params / invitation) */
+    metadata?: Record<string, unknown>;
+}
 /**
  * Auth configuration
  */
@@ -5372,6 +6106,35 @@ interface AuthConfig {
      * @default 7d (7 days)
      */
     sessionTtl?: string | number;
+    /**
+     * App-injected validator that runs before a new user row is created,
+     * on every registration channel (credentials, oauth, invitation).
+     *
+     * Throw to reject the registration — RegistrationRejectedError (403) is
+     * the recommended error; any HttpError subclass keeps its own status.
+     * Runs after built-in checks (verification token, duplicate account),
+     * so existing error precedence is unchanged. Not called for admin
+     * seeding (initializeAuth) or when linking a social account to an
+     * existing user.
+     *
+     * Runs inside the registration DB transaction on every channel — keep it
+     * fast. A slow call (e.g. an external policy API) holds a pooled DB
+     * connection open for its full duration on every signup.
+     *
+     * @example
+     * ```typescript
+     * configureAuth({
+     *     beforeRegister: async ({ channel, metadata }) =>
+     *     {
+     *         if (channel === 'credentials' && !isOldEnough(metadata?.birthDate))
+     *         {
+     *             throw new RegistrationRejectedError({ message: 'Age requirement not met' });
+     *         }
+     *     },
+     * });
+     * ```
+     */
+    beforeRegister?: (context: BeforeRegisterContext) => void | Promise<void>;
 }
 /**
  * Configure global auth settings
@@ -5390,6 +6153,14 @@ declare function configureAuth(config: AuthConfig): void;
  * Get current auth configuration
  */
 declare function getAuthConfig(): AuthConfig;
+/**
+ * Run the app-injected beforeRegister hook if configured — throws to reject.
+ *
+ * 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.
+ */
+declare function runBeforeRegister(context: BeforeRegisterContext): Promise<void>;
 /**
  * Get session TTL in seconds
  *
@@ -5442,6 +6213,66 @@ declare function initOneTimeTokenManager(config?: {
  */
 declare function getOneTimeTokenManager(): SSETokenManager;
 
+/**
+ * Account Deletion Configuration
+ *
+ * Singleton config for the account deletion/recovery lifecycle, mirroring the
+ * one-time-token manager pattern (`lib/one-time-token.ts`): a mutable module-level
+ * value, set once during `createAuthLifecycle()` and read at request/handler time.
+ *
+ * `purgeCron` is the one field this module does NOT make effective on its own —
+ * `job('auth.deletion.purge').cron(expression)` bakes the cron string in at
+ * *module-import* time, which always runs before `createAuthLifecycle()` executes
+ * (ESM evaluates imports before the importing module's own statements). So a
+ * statically-exported job router can never see a `purgeCron` set here. Apps that
+ * need a non-default cron must build the router themselves, after configuring
+ * deletion, with `createAuthDeletionJobRouter({ purgeCron })` — see
+ * `server/jobs/deletion-purge.ts` and the README.
+ */
+
+interface AccountDeletionPurgeUser {
+    id: number;
+    publicId: string;
+    email: string | null;
+    phone: string | null;
+}
+interface AuthDeletionConfig {
+    /** Days between a deletion request and the purge becoming eligible. 0 = immediate. */
+    gracePeriodDays: number;
+    /** How the purge job destroys the account once the grace period elapses. */
+    purgeStrategy: PurgeStrategy;
+    /** Whether a self-service caller may request `immediate: true` (skip the grace period). */
+    allowSelfImmediate: boolean;
+    /**
+     * Cron schedule for the purge sweep. NOT read automatically by the static
+     * `authJobRouter` export — see the module doc comment above.
+     */
+    purgeCron: string;
+    /** Whether to email users (when they have one) at request/recovery/purge time. */
+    sendNotifications: boolean;
+    /**
+     * Synchronous hook invoked immediately before a user is purged. Throw to skip
+     * that user for this sweep (they stay `pending`, retried on the next tick).
+     */
+    onBeforePurge?: (user: AccountDeletionPurgeUser) => Promise<void>;
+}
+declare const DEFAULT_DELETION_GRACE_PERIOD_DAYS = 30;
+declare const DEFAULT_DELETION_PURGE_STRATEGY: PurgeStrategy;
+declare const DEFAULT_DELETION_ALLOW_SELF_IMMEDIATE = false;
+declare const DEFAULT_DELETION_PURGE_CRON = "0 4 * * *";
+declare const DEFAULT_DELETION_SEND_NOTIFICATIONS = true;
+/**
+ * Set the resolved deletion config. Called synchronously from `createAuthLifecycle()`
+ * (not from `afterInfrastructure`) so it takes effect before any route/job handler
+ * that reads `getDeletionConfig()` can run.
+ */
+declare function configureDeletion(options?: Partial<AuthDeletionConfig>): void;
+/**
+ * Read the current deletion config. Safe to call any time — defaults apply even
+ * if `createAuthLifecycle()` was never given a `deletion` block.
+ */
+declare function getDeletionConfig(): AuthDeletionConfig;
+
 /**
  * @spfn/auth - Centralized Logger
  *
@@ -5581,9 +6412,131 @@ interface AuthLifecycleOptions extends AuthInitOptions {
          */
         store?: SSETokenStore;
     };
+    /**
+     * Account deletion/recovery lifecycle configuration
+     *
+     * Controls the grace-period request → recover → purge flow exposed by
+     * `POST /_auth/deletion/request` and `POST /_auth/deletion/cancel`.
+     * Registering the purge job itself is a separate step — see `authJobRouter`
+     * (`@spfn/auth/server`) and the README, since job registration happens after
+     * this lifecycle hook runs and can't be triggered from here.
+     *
+     * @example
+     * ```typescript
+     * createAuthLifecycle({
+     *     deletion: {
+     *         gracePeriodDays: 14,
+     *         purgeStrategy: 'anonymize',
+     *         allowSelfImmediate: false,
+     *         sendNotifications: true,
+     *         onBeforePurge: async (user) => {
+     *             await appDataCleanup(user.id); // throw to skip this user this sweep
+     *         },
+     *     },
+     * })
+     * ```
+     */
+    deletion?: {
+        /**
+         * Days between a deletion request and the purge becoming eligible.
+         * 0 = immediate (still goes through the same request/purge pipeline).
+         * @default 30
+         */
+        gracePeriodDays?: number;
+        /**
+         * How the purge job destroys the account once the grace period elapses.
+         * - 'anonymize': scrub PII, keep the row (status -> 'deleted') — recommended default
+         * - 'hard-delete': physically remove the `users` row (cascades to child rows)
+         * @default 'anonymize'
+         */
+        purgeStrategy?: PurgeStrategy;
+        /**
+         * Whether a self-service caller may pass `immediate: true` on
+         * `POST /_auth/deletion/request` to skip the grace period entirely.
+         * @default false
+         */
+        allowSelfImmediate?: boolean;
+        /**
+         * Cron schedule for the purge sweep. NOTE: this does not reach the static
+         * `authJobRouter` export automatically — job schedules are fixed at
+         * module-import time, before this lifecycle hook runs. For a non-default
+         * cron, build the router yourself after this call with
+         * `createAuthDeletionJobRouter({ purgeCron })` (see `@spfn/auth/server`).
+         * @default '0 4 * * *'
+         */
+        purgeCron?: string;
+        /**
+         * Whether to email users (when they have one on file) at request,
+         * recovery, and final-purge time.
+         * @default true
+         */
+        sendNotifications?: boolean;
+        /**
+         * Invoked immediately before a user is purged (both the immediate inline
+         * path and the cron sweep). Throw to skip that user for this run — they
+         * stay `pending` and are retried on the next sweep.
+         */
+        onBeforePurge?: (user: AccountDeletionPurgeUser) => Promise<void>;
+    };
 }
 declare function createAuthLifecycle(options?: AuthLifecycleOptions): AuthLifecycleConfig;
 
+/**
+ * @spfn/auth - Account Deletion Purge Job
+ *
+ * The package's first background job (`@spfn/core/job`). Sweeps
+ * `account_deletion_requests` for rows whose grace period elapsed and purges
+ * each one (see `sweepDuePurges` in `account-deletion.service.ts`).
+ *
+ * Registration is NOT automatic. `createAuthLifecycle()`'s `afterInfrastructure`
+ * hook runs *before* `initBoss`/`registerJobs` in `@spfn/core`'s server startup
+ * (`initializeInfrastructure()`), so the lifecycle has no opportunity to register
+ * jobs itself. Apps must register explicitly:
+ *
+ * ```typescript
+ * import { authJobRouter } from '@spfn/auth/server';
+ *
+ * export default defineServerConfig()
+ *     .lifecycle(createAuthLifecycle())
+ *     .jobs(authJobRouter)
+ *     .routes(appRouter)
+ *     .build();
+ * ```
+ *
+ * Cron schedule caveat: `job(...).cron(expression)` bakes the cron string in at
+ * *module-import* time, which always happens before `createAuthLifecycle()` runs
+ * in the app's own module (ESM evaluates imports before the importing module's
+ * statements). So the static `authJobRouter` export below always uses the default
+ * cron — `deletion.purgeCron` passed to `createAuthLifecycle()` cannot reach it.
+ * To use a custom cron, build the router yourself, after calling
+ * `createAuthLifecycle()`, with `createAuthDeletionJobRouter({ purgeCron })` and
+ * register that instead of the static export.
+ */
+/**
+ * Build the `auth.deletion.purge` job with a given cron schedule.
+ *
+ * @param cronExpression - Defaults to `deletion-config`'s default (daily at 04:00).
+ */
+declare function createAuthDeletionPurgeJob(cronExpression?: string): _spfn_core_job.JobDef<void, void>;
+/**
+ * Build a job router containing only the deletion purge job, with a given cron.
+ * Use this (after calling `createAuthLifecycle({ deletion: { purgeCron } })`) when
+ * you need a non-default schedule — see the module doc comment above for why the
+ * static `authJobRouter` export can't pick up `deletion.purgeCron` automatically.
+ */
+declare function createAuthDeletionJobRouter(options?: {
+    purgeCron?: string;
+}): _spfn_core_job.JobRouter<{
+    deletionPurge: _spfn_core_job.JobDef<void, void>;
+}>;
+/**
+ * Default job router — the default cron (`0 4 * * *`). Register with
+ * `.jobs(authJobRouter)` in `server.config.ts`.
+ */
+declare const authJobRouter: _spfn_core_job.JobRouter<{
+    deletionPurge: _spfn_core_job.JobDef<void, void>;
+}>;
+
 /**
  * @spfn/auth - Auth Events
  *
@@ -5695,6 +6648,48 @@ declare const invitationAcceptedEvent: _spfn_core_event.EventDef<{
     invitedBy: string;
     invitationId: string;
 }>;
+/**
+ * auth.deletion.requested - 계정 탈퇴 요청 이벤트
+ *
+ * 발행 시점:
+ * - requestAccountDeletionService() 성공 시 (self/admin 공통)
+ *
+ * @example
+ * ```typescript
+ * authDeletionRequestedEvent.subscribe(async (payload) => {
+ *     await analytics.trackChurnRisk(payload.userId);
+ * });
+ * ```
+ */
+declare const authDeletionRequestedEvent: _spfn_core_event.EventDef<{
+    userId: string;
+    purgeScheduledAt: string;
+    userPublicId: string;
+    requestedBy: "admin" | "self";
+}>;
+/**
+ * auth.deletion.cancelled - 계정 탈퇴 복구 이벤트
+ *
+ * 발행 시점:
+ * - cancelAccountDeletionService() 성공 시 (유예 기간 내 복구)
+ */
+declare const authDeletionCancelledEvent: _spfn_core_event.EventDef<{
+    userId: string;
+    userPublicId: string;
+}>;
+/**
+ * auth.deletion.completed - 계정 파기 완료 이벤트
+ *
+ * 발행 시점:
+ * - purge job(또는 즉시 파기 경로)이 유저를 파기한 직후
+ *
+ * PII를 담지 않는다 — userId(내부 순번)/email/phone 없이 userPublicId만 실어
+ * 파기 완료 이후에도 구독자가 식별 정보를 다시 축적하지 않도록 한다.
+ */
+declare const authDeletionCompletedEvent: _spfn_core_event.EventDef<{
+    userPublicId: string;
+    purgeStrategy: "anonymize" | "hard-delete";
+}>;
 /**
  * Auth event payload types
  */
@@ -5702,5 +6697,8 @@ type AuthLoginPayload = typeof authLoginEvent._payload;
 type AuthRegisterPayload = typeof authRegisterEvent._payload;
 type InvitationCreatedPayload = typeof invitationCreatedEvent._payload;
 type InvitationAcceptedPayload = typeof invitationAcceptedEvent._payload;
+type AuthDeletionRequestedPayload = typeof authDeletionRequestedEvent._payload;
+type AuthDeletionCancelledPayload = typeof authDeletionCancelledEvent._payload;
+type AuthDeletionCompletedPayload = typeof authDeletionCompletedEvent._payload;
 
-export { type AuthConfig, AuthContext, type AuthLifecycleConfig, type AuthLifecycleOptions, type AuthLoginPayload, type AuthMetadataEntity, AuthMetadataRepository, AuthProviderSchema, type AuthRegisterPayload, COOKIE_NAMES, type CreateOAuthStateParams, type GoogleTokenResponse, type GoogleUserInfo, type Invitation, type InvitationAcceptedPayload, type InvitationCreatedPayload, InvitationStatus, InvitationsRepository, KeyAlgorithmType, type KeyPair, KeysRepository, type NewAuthMetadataEntity, type NewInvitation, 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 Permission, type PermissionEntity, PermissionsRepository, type Role, type RoleEntity, type RoleGuardOptions, type RolePermission, RolePermissionsRepository, RolesRepository, type SessionPayload, SocialAccountsRepository, SocialProvider, type TokenPayload, type UpdateProfileParams, type User, type UserPermission, UserPermissionsRepository, type UserProfile, UserProfilesRepository, type UserPublicKey, type UserSocialAccount, UsersRepository, type VerificationCode, VerificationCodesRepository, VerificationPurpose, type VerifyIdTokenParams, acceptInvitation, addPermissionToRole, appleProvider, assertCanAssignRole, authLogger, authLoginEvent, authMetadata, authMetadataRepository, authRegisterEvent, authSchema, cancelInvitation, checkUsernameAvailableService, configureAuth, createAuthLifecycle, createInvitation, createOAuthState, createRole, decodeToken, deleteInvitation, deleteRole, exchangeCodeForTokens, expireOldInvitations, generateClientToken, generateKeyPair, generateKeyPairES256, generateKeyPairRS256, generateOAuthNonce, generateToken, getAllRoles, getAuth, getAuthConfig, getAuthSessionService, getGoogleAuthUrl, getGoogleOAuthConfig, getGoogleUserInfo, getInvitationByToken, getInvitationWithDetails, getKeyId, getKeySize, getLocale, getOneTimeTokenManager, getOptionalAuth, getRole, getRoleByName, getRolePermissions, getSessionTtl, getUser, getUserByEmailService, getUserByIdService, getUserByPhoneService, getUserId, getUserPermissions, getUserProfileService, getUserRole, googleProvider, hasAllPermissions, hasAnyPermission, hasAnyRole, hasPermission, hasRole, hashPassword, initOneTimeTokenManager, initializeAuth, invitationAcceptedEvent, invitationCreatedEvent, invitationsRepository, isGoogleOAuthEnabled, keysRepository, listInvitations, oneTimeTokenAuth, parseDuration, permissions, permissionsRepository, refreshAccessToken, removePermissionFromRole, requireAnyPermission, requirePermissions, requireRole, resendInvitation, roleGuard, rolePermissions, rolePermissionsRepository, roles, rolesRepository, setRolePermissions, shouldRotateKey, socialAccountsRepository, updateLastLoginService, updateLocaleService, updateRole, updateUserProfileService, updateUserService, updateUsernameService, userInvitations, userPermissions, userPermissionsRepository, userProfiles, userProfilesRepository, userPublicKeys, userSocialAccounts, users, usersRepository, validateInvitation, validatePasswordStrength, verificationCodes, verificationCodesRepository, verifyClientToken, verifyIdToken, verifyKeyFingerprint, verifyOAuthState, 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, EnvironmentKeyringTokenCipher, type GoogleTokenResponse, type GoogleUserInfo, type Invitation, type InvitationAcceptedPayload, type InvitationCreatedPayload, InvitationStatus, InvitationsRepository, KeyAlgorithmType, type KeyPair, KeysRepository, type NewAccountDeletionRequest, type NewAuthMetadataEntity, type NewInvitation, 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 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 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, generateClientToken, generateKeyPair, generateKeyPairES256, generateKeyPairRS256, generateOAuthNonce, generateToken, getAllRoles, getAuth, getAuthConfig, getAuthSessionService, getDeletionConfig, getDummyPasswordHash, getGoogleAuthUrl, getGoogleOAuthConfig, getGoogleUserInfo, getInvitationByToken, getInvitationWithDetails, getKeyId, getKeySize, getLocale, getOneTimeTokenManager, getOptionalAuth, getPendingDeletionInfo, getRole, getRoleByName, getRolePermissions, getSessionTtl, getUser, getUserByEmailService, getUserByIdService, getUserByPhoneService, getUserId, getUserPermissions, getUserProfileService, getUserRole, googleProvider, hasAllPermissions, hasAnyPermission, hasAnyRole, hasPermission, hasRole, hashPassword, initOneTimeTokenManager, initializeAuth, invitationAcceptedEvent, invitationCreatedEvent, invitationsRepository, isEncrypted, isGoogleOAuthEnabled, kakaoProvider, keysRepository, listInvitations, matchOAuthCsrfCookies, naverProvider, oneTimeTokenAuth, parseDuration, permissions, permissionsRepository, purgeUserService, refreshAccessToken, removePermissionFromRole, requestAccountDeletionService, requireAnyPermission, requirePermissions, requireRole, resendInvitation, roleGuard, rolePermissions, rolePermissionsRepository, roles, rolesRepository, runBeforeRegister, setRolePermissions, shouldRotateKey, 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, verifyPassword, verifyToken };