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

package/README.md

@@ -1,7 +1,7 @@
 # @spfn/auth — Authentication, OAuth, and RBAC for SPFN
 
 Asymmetric client-signed JWT auth (ES256/RS256), OTP verification, OAuth 2.0 (pluggable
-provider registry, Google built-in), session cookies for Next.js, and runtime RBAC.
+provider registry; Google, Kakao, and Naver built in), session cookies for Next.js, and runtime RBAC.
 Routes are exposed under the `/_auth/*` namespace and reached through a type-safe `authApi`
 client. Requires `@spfn/core`; Next.js is an optional peer (`^15 || ^16`).
 
@@ -111,6 +111,7 @@ real secret values out of band, never commit them.
 | `DATABASE_URL` | both | yes | Postgres connection |
 | `SPFN_AUTH_VERIFICATION_TOKEN_SECRET` | `.env.server` | yes | OTP / verification token signing |
 | `SPFN_AUTH_SESSION_SECRET` | `.env.local` | yes | ≥32 chars, AES-256 session cookie encryption (validated: entropy/unique-char checks) |
+| `SPFN_AUTH_TOKEN_ENCRYPTION_KEYS` | `.env.server` | web OAuth | OAuth token keyring: comma-separated `<keyId>:<base64-32-byte-key>` entries; first key is active |
 | `SPFN_API_URL` | `.env.local` | — | default `http://localhost:8790` |
 | `SPFN_AUTH_SESSION_TTL` | both | — | default `7d` (e.g. `7d`, `12h`, `45m`) |
 | `SPFN_AUTH_JWT_SECRET` / `SPFN_AUTH_JWT_EXPIRES_IN` | `.env.server` | — | legacy server-signed JWT mode only |
@@ -119,7 +120,11 @@ real secret values out of band, never commit them.
 | `SPFN_AUTH_ADMIN_*` | `.env.server` | — | admin seeding (see below) |
 | `SPFN_AUTH_GOOGLE_CLIENT_ID` / `_CLIENT_SECRET` | `.env.server` | — | enables Google OAuth when both set |
 | `SPFN_AUTH_GOOGLE_SCOPES` | `.env.server` | — | comma-separated; default `email,profile` |
-| `SPFN_AUTH_GOOGLE_REDIRECT_URI` | `.env.server` | — | default `{NEXT_PUBLIC_SPFN_API_URL\|\|SPFN_API_URL}/_auth/oauth/google/callback` |
+| `SPFN_AUTH_GOOGLE_REDIRECT_URI` | `.env.server` | — | default `{NEXT_PUBLIC_SPFN_APP_URL\|\|SPFN_APP_URL}/_auth/oauth/google/callback` — see [OAuth callback origin](#oauth-callback-origin-web-app-host--rewrite) |
+| `SPFN_AUTH_KAKAO_CLIENT_ID` / `_CLIENT_SECRET` | `.env.server` | — | REST API key enables Kakao Login; secret is included when configured |
+| `SPFN_AUTH_KAKAO_SCOPES` / `_REDIRECT_URI` | `.env.server` | — | default scope `account_email`; callback `/_auth/oauth/kakao/callback` |
+| `SPFN_AUTH_NAVER_CLIENT_ID` / `_CLIENT_SECRET` | `.env.server` | — | both values enable Naver Login |
+| `SPFN_AUTH_NAVER_REDIRECT_URI` | `.env.server` | — | default `{NEXT_PUBLIC_SPFN_APP_URL\|\|SPFN_APP_URL}/_auth/oauth/naver/callback` |
 | `SPFN_AUTH_GOOGLE_NATIVE_CLIENT_IDS` | `.env.server` | — | comma-separated client IDs accepted as native id_token audience (iOS/Android/web); enables Google native sign-in |
 | `SPFN_AUTH_APPLE_CLIENT_IDS` | `.env.server` | — | comma-separated Apple client IDs (bundle ID / Services ID); enables Apple native sign-in |
 | `SPFN_AUTH_OAUTH_SUCCESS_URL` | `.env.server` | — | default `/auth/callback` |
@@ -159,6 +164,8 @@ routes use `.skip(['auth'])`; the rest require `Authorization: Bearer <client-si
 | `checkUsername` / `updateUsername` / `updateLocale` | — | mixed | username availability/update, locale |
 | `getUserProfile` / `updateUserProfile` | — | yes | profile read/update |
 | `createInvitation` / `acceptInvitation` / `listInvitations` / `cancelInvitation` / `resendInvitation` / `deleteInvitation` / `getInvitation` | — | mixed | invitation flow |
+| `requestAccountDeletion` | POST `/_auth/deletion/request` | yes | request account deletion (re-auth gated) — see [Account Deletion & Recovery](#account-deletion--recovery) |
+| `cancelAccountDeletion` | POST `/_auth/deletion/cancel` | public | cancel a pending deletion (credential-based recovery) |
 | `listRoles` / `createAdminRole` / `updateAdminRole` / `deleteAdminRole` / `updateUserRole` | — | superadmin | admin RBAC management |
 | OAuth routes | — | — | see OAuth section |
 
@@ -206,10 +213,11 @@ Context helpers from `@spfn/auth/server`: `getAuth`, `getOptionalAuth`, `getUser
 
 ## OAuth
 
-OAuth uses a **pluggable provider registry** — not hardcoded branches. The built-in `google`
-provider self-registers on module load. External packages add providers at runtime with
-`registerOAuthProvider()`. Google OAuth turns on automatically once both
-`SPFN_AUTH_GOOGLE_CLIENT_ID` and `SPFN_AUTH_GOOGLE_CLIENT_SECRET` are set.
+OAuth uses a **pluggable provider registry** — not hardcoded branches. The built-in `google`,
+`kakao`, and `naver` web providers self-register on module load; `apple` provides native
+`id_token` sign-in. External packages add providers at runtime with `registerOAuthProvider()`.
+Google requires its client ID and secret, Kakao requires its REST API key (and sends its optional
+client secret when configured), and Naver requires its client ID and secret.
 
 Client flow: call `authApi.getGoogleOAuthUrl.call({ body: { returnUrl } })`, redirect the browser
 to the returned `authUrl`, and render `OAuthCallback` on your success page. The Next.js interceptor
@@ -222,16 +230,83 @@ export { OAuthCallback as default } from '@spfn/auth/nextjs/client';
 
 ```typescript
 import { authApi } from '@spfn/auth';
-const { authUrl } = await authApi.getGoogleOAuthUrl.call({ body: { returnUrl: '/dashboard' } });
+const { authUrl } = await authApi.getGoogleOAuthUrl.call({
+    body: {
+        returnUrl: '/dashboard',
+        metadata: { birthDate: '2000-01-01', termsAgreed: true },
+    },
+});
+window.location.href = authUrl;
+```
+
+Kakao and Naver use the provider-generic URL route:
+
+```typescript
+const { authUrl } = await authApi.getProviderOAuthUrl.call({
+    params: { provider: 'kakao' }, // or 'naver'
+    body: {
+        returnUrl: '/dashboard',
+        metadata: { birthDate: '2000-01-01', termsAgreed: true },
+    },
+});
 window.location.href = authUrl;
 ```
 
+Both convenience URL APIs seal `metadata` into the encrypted OAuth state. On a new social
+signup, the callback passes it to `beforeRegister` and `authRegisterEvent`; existing-account
+logins do not run the registration hook.
+
 Built-in OAuth routes: `POST /_auth/oauth/google/url`, `GET /_auth/oauth/google` (redirect),
 `GET /_auth/oauth/google/callback`, `POST /_auth/oauth/finalize`, `GET /_auth/oauth/providers`,
 plus the provider-generic `POST /_auth/oauth/start`. `getGoogleAccessToken(userId)` returns a
 valid Google access token (auto-refreshing via stored refresh token when near expiry; throws if
 no Google account is linked or no refresh token is available).
 
+Kakao's `is_email_valid` and `is_email_verified` claims are both required before its email can
+link an existing SPFN account. Naver provides an email address but no verified-email claim, so
+Naver login never links an existing account by email; new Naver users can verify and add their
+email through the application's normal onboarding flow. Until then, the OAuth account is identified
+by its provider and provider user ID, so its user row may have both email and phone unset.
+
+### OAuth callback origin (web app host + rewrite)
+
+The callback's CSRF check is a double-submit: the Next.js interceptor sets an `oauth_csrf`
+cookie on the **web app host**, and the callback compares it against the nonce sealed in the
+state. Host-only cookies never reach a different host, so **the provider callback must return
+to the web app origin** — redirect URIs default to
+`{NEXT_PUBLIC_SPFN_APP_URL || SPFN_APP_URL}/_auth/oauth/<provider>/callback`.
+
+The app forwards `/_auth/*` to the API with a standard rewrite (**required** — without it the
+callback 404s on the web host, including in local dev):
+
+```javascript
+// next.config.js
+const nextConfig = {
+    async rewrites()
+    {
+        return [
+            {
+                source: '/_auth/:path*',
+                destination: `${process.env.SPFN_API_URL}/_auth/:path*`,
+            },
+        ];
+    },
+};
+```
+
+Register each **web app host** callback URL in its provider console, for example
+`https://app.example.com/_auth/oauth/kakao/callback` and
+`https://app.example.com/_auth/oauth/naver/callback`.
+
+The cookie name also carries a `_${PORT}` suffix from the process that set it (the Next.js
+process), which differs from the API process in a split deployment — the callback therefore
+matches every `spfn_oauth_csrf*` cookie candidate against the state nonce, so no PORT
+coordination is needed.
+
+One caveat: the direct `POST /_auth/oauth/start` flow (no Next.js interceptor) sets its CSRF
+cookie on the **API host**. If you use that flow in a split deployment, set
+the corresponding provider redirect URI explicitly to the API host callback instead.
+
 ### Native social sign-in (mobile / web id_token)
 
 For native apps — and for Apple on Android/web, which has no native SDK — the client obtains an
@@ -273,13 +348,40 @@ import {
 registerOAuthProvider(myProvider);   // same id re-registers (override)
 ```
 
+### OAuth token encryption and key rotation
+
+Web OAuth access and refresh tokens are encrypted at rest with AES-256-GCM. Token encryption is
+separate from session-cookie encryption: `SPFN_AUTH_TOKEN_ENCRYPTION_KEYS` is backend-only and
+must never be exposed to the Next.js process. Generate a key with `openssl rand -base64 32` and
+assign it a non-secret key ID:
+
+```dotenv
+SPFN_AUTH_TOKEN_ENCRYPTION_KEYS=v2:<base64-32-byte-key>
+```
+
+For zero-downtime rotation, prepend the new key and retain old keys for decryption:
+
+```dotenv
+SPFN_AUTH_TOKEN_ENCRYPTION_KEYS=v3:<new-key>,v2:<old-key>
+```
+
+New writes use the first key. Reads using an older key, the legacy session-secret-derived `enc:v1`
+format, or historical plaintext are automatically re-encrypted with the active key. Keep every old
+key available until all rows have been read or explicitly migrated; removing a referenced key makes
+those tokens undecryptable. Ciphertext is bound to `provider`, `providerUserId`, and token type
+(`access` or `refresh`) with authenticated data, preventing ciphertext from being moved to another
+account or field.
+
+Deployments that need a KMS or per-account envelope encryption can call
+`configureOAuthTokenCipher()` from `@spfn/auth/server` before the server starts. The custom cipher
+receives the same account/token context and owns its key rotation policy.
+
 **Integration contract for custom providers:**
 
-- The package only ships google's callback route. A custom provider must expose its **own**
-  callback route that calls `oauthCallbackService({ provider, code, state })`.
-- **Wrap that callback route in `Transactional()`** (`import { Transactional } from '@spfn/core/db'`).
-  `oauthCallbackService` creates/links a user and stores the social account in sequence — without
-  a transaction, a mid-flow failure leaves an orphan user. The built-in google callback uses it.
+- The built-in provider-generic callback route handles any registered provider. A custom callback is
+  only needed when the provider does not follow the standard `code` / `state` response contract.
+- If a custom callback calls `oauthCallbackService()` directly, wrap the route in `Transactional()`
+  (`import { Transactional } from '@spfn/core/db'`).
 - The provider `id` must be in `SOCIAL_PROVIDERS` (`enumText`, plain text — adding a value needs **no**
   DB migration).
 - `auth.login` / `auth.register` events now carry any `SOCIAL_PROVIDERS` value in `provider` —
@@ -354,7 +456,48 @@ authRegisterEvent.subscribe(async ({ userId, email, provider, metadata }) =>
 ```
 
 Payload types: `AuthLoginPayload`, `AuthRegisterPayload`, `InvitationCreatedPayload`,
-`InvitationAcceptedPayload`. These events also bind to `@spfn/core/job` jobs via `.on(event)`.
+`InvitationAcceptedPayload`, `AuthDeletionRequestedPayload`, `AuthDeletionCancelledPayload`,
+`AuthDeletionCompletedPayload`. These events also bind to `@spfn/core/job` jobs via `.on(event)`.
+
+## Registration gate (`beforeRegister`)
+
+Events fire *after* the user exists — they cannot reject a registration. For server-enforced
+signup policy (age gate, invite-only domains, block lists) inject a validator with
+`configureAuth`; it runs **before the user row is created** on every registration channel:
+`credentials` (email/phone register), `oauth` (new-user social signup, web + native), and
+`invitation` (acceptance). Throwing rejects the registration; `RegistrationRejectedError` (403)
+is the recommended error. The hook receives the same `metadata` the app supplied to
+`register` / OAuth start / the invitation — never credentials.
+
+```typescript
+import { configureAuth, RegistrationRejectedError } from '@spfn/auth/server';
+
+configureAuth({
+    beforeRegister: async ({ channel, provider, email, phone, metadata }) =>
+    {
+        if (!isOldEnough(metadata?.birthDate))
+        {
+            throw new RegistrationRejectedError({ message: 'Age requirement not met' });
+        }
+    },
+});
+```
+
+Notes:
+- Runs after built-in checks (verification token, duplicate account) — existing error
+  precedence is unchanged, and the hook cannot be probed without a valid verification token.
+- Not called when an OAuth login links a social account to an existing user, nor for admin
+  seeding in `initializeAuth()`.
+- OAuth signups have no client-typed fields unless you pass `metadata` at OAuth start — decide
+  per channel (reject, or allow and collect during onboarding).
+- On the `oauth` channel `email` is the provider-reported address and may be **unverified**
+  (the created account then stores `email` as `null`). The context carries
+  `emailVerified` — an email-based allow/block policy must check it before trusting `email`.
+- The hook 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 per signup.
+- On the **web** OAuth flow a rejection surfaces as the standard OAuth error redirect
+  (302 to the app's OAuth error URL, message only) — not a 403 JSON response. The native
+  OAuth flow, credentials, and invitation channels return the error status (403) directly.
 
 ## One-Time Token
 
@@ -362,6 +505,107 @@ For short-lived authenticated handshakes (e.g. SSE) where a `Bearer` header is a
 with `authApi.issueOneTimeToken`, protect the consuming route with the `oneTimeTokenAuth`
 middleware. Call `initOneTimeTokenManager({ ttl, store })` during setup for a custom TTL/store.
 
+## Account Deletion & Recovery
+
+Grace-period deletion with in-window recovery, an admin/GDPR-response entry point for immediate
+purge, and a pluggable app-data cleanup hook. Not covered by this feature: re-signup email
+blind-index/hashing (a purged account's email becomes reusable immediately — see the project's
+PII protection track for blind-index re-signup prevention), backup beyond-use handling, DSR
+intake/response workflows, and webhook fan-out — those are app/ops concerns.
+
+```
+active ──request (re-auth)──> pending_deletion ──grace period elapses (cron)──> deleted (anonymize) | row removed (hard-delete)
+  ^                                  │
+  └───────────cancel (re-auth)───────┘        immediate = grace period of 0, same pipeline
+```
+
+- **Request** — `POST /_auth/deletion/request` (authenticated). Step-up re-auth: password
+  holders confirm with `password`; OAuth-only/passwordless accounts confirm with a
+  `verificationToken` from `/_auth/codes` + `/_auth/codes/verify` (`purpose: 'account_deletion'`).
+  On success: status → `pending_deletion`, every active session key is revoked, a
+  `account_deletion_requests` audit row is created, `auth.deletion.requested` fires, and (if
+  the user has an email and `sendNotifications` is on) a notice is sent with the scheduled purge
+  date.
+- **Login is blocked while pending** — password login, OAuth login, and the `authenticate`
+  middleware all reject a `pending_deletion` account with `AccountPendingDeletionError` (403,
+  `details.purgeScheduledAt`) instead of the generic `AccountDisabledError`, so the client can
+  show a recovery prompt.
+- **Cancel (recovery)** — `POST /_auth/deletion/cancel` (public — sessions were revoked at
+  request time, so there's no Bearer token to authenticate with). Credential-based: email/phone
+  plus `password` or a fresh `verificationToken`. On success, status → `active`; the user still
+  needs to log in separately afterward.
+- **Purge job** — sweeps `account_deletion_requests` for rows past their grace period and
+  destroys the account. Register it explicitly (see below); it is **not** wired up by
+  `createAuthLifecycle()` automatically.
+- **Admin / GDPR-response entry points** — `requestAccountDeletionService(userId, { requestedBy: 'admin', immediate })`
+  and `purgeUserService(userId)` are exported for app-side admin routes / DSR handling; the app
+  owns the route and its authorization.
+
+```typescript
+import { defineServerConfig } from '@spfn/core/server';
+import { createAuthLifecycle, authJobRouter } from '@spfn/auth/server';
+
+export default defineServerConfig()
+    .lifecycle(createAuthLifecycle({
+        deletion: {
+            gracePeriodDays: 30,               // default; 0 = immediate
+            purgeStrategy: 'anonymize',        // default; or 'hard-delete'
+            allowSelfImmediate: false,         // default; self-service immediate: true
+            sendNotifications: true,           // default
+            onBeforePurge: async (user) =>
+            {
+                // throw to skip this user for the current sweep (retried next run)
+                await appDataCleanup(user.id);
+            },
+        },
+    }))
+    .jobs(authJobRouter)   // registers the daily (04:00 UTC) purge sweep
+    .routes(appRouter)
+    .build();
+```
+
+**Purge strategies:**
+
+- `anonymize` (default) — scrubs PII, keeps the row: `email` → `deleted-{publicId}@deleted.invalid`,
+  `phone`/`username`/`passwordHash` → `null`, `status` → `'deleted'`, `deletedAt`/`deletedBy` set
+  (`softDelete()` on `users`). Social accounts and public keys are deleted (frees the provider
+  link and revokes access), the profile's PII columns are cleared, and any leftover verification
+  codes for the original email/phone are removed. The freed email/phone can be re-registered
+  immediately.
+- `hard-delete` — physically removes the `users` row; child rows (`user_profiles`,
+  `user_public_keys`, `user_social_accounts`, `user_permissions`) cascade-delete via their FK.
+  The `account_deletion_requests` audit row survives either strategy — its `userId` FK is
+  `set null` (not cascade), by design, so "who requested/purged what, when" outlives the user row.
+
+The final "your account has been deleted" notice is sent **after** the purge transaction commits
+(never before, and never on a purge that aborted or rolled back — see below), using the address
+captured before the destructive step ran. This holds for `hard-delete` too: the row is already
+gone by send time, but the address was captured beforehand, so the notice still goes out.
+
+**Concurrency.** The purge job re-verifies the user is still `pending_deletion` on the write
+primary immediately before any destructive DML, inside the same transaction as the DML itself —
+closing the window between a stale read (the sweep's own batch, or replica lag) and a concurrent
+`cancel`. The `account_deletion_requests` claim (`markCompleted`) is a conditional `UPDATE ...
+WHERE status = 'pending'`; if a concurrent cancel already moved the row off `pending`, the claim
+matches zero rows and the purge aborts with no destructive DML and no overwritten audit row.
+
+**Cron schedule caveat.** `deletion.purgeCron` (default `0 4 * * *`) is stored for reference, but
+the static `authJobRouter` export above always runs on the *default* cron — `job(...).cron(...)`
+is fixed at module-import time, which happens before `createAuthLifecycle()` runs in your
+`server.config.ts`. For a non-default schedule, build the router yourself, after the
+`createAuthLifecycle()` call, and register that instead:
+
+```typescript
+import { createAuthDeletionJobRouter } from '@spfn/auth/server';
+
+// ... after .lifecycle(createAuthLifecycle({ deletion: { purgeCron: '0 3 * * *' } }))
+.jobs(createAuthDeletionJobRouter({ purgeCron: '0 3 * * *' }))
+```
+
+Register **only one** of `authJobRouter` / `createAuthDeletionJobRouter(...)` — both build a job
+named `auth.deletion.purge`, so registering both (e.g. the static export *and* a custom-cron
+router) double-registers the same job name against pg-boss instead of overriding it.
+
 ## Pitfalls & anti-patterns
 
 - **Wrong entry point.** `@spfn/auth/server` and `@spfn/auth/nextjs/*` are server-only (Node /
@@ -373,8 +617,9 @@ middleware. Call `initOneTimeTokenManager({ ttl, store })` during setup for a cu
   `authErrorRegistry` in `src/errors/index.ts`) and pass it to your `createApi({ errorRegistry })`,
   or the client receives a generic error instead of the typed one.
 - **Two env files, by audience.** `SPFN_AUTH_SESSION_SECRET` lives in `.env.local` (Next.js needs
-  it for cookie crypto); `SPFN_AUTH_VERIFICATION_TOKEN_SECRET` lives in `.env.server`. Splitting
-  them wrong yields "missing secret" failures only at runtime.
+  it for cookie crypto); `SPFN_AUTH_VERIFICATION_TOKEN_SECRET` and
+  `SPFN_AUTH_TOKEN_ENCRYPTION_KEYS` live in `.env.server`. Token encryption keys are backend-only;
+  putting them in `.env.local` unnecessarily gives the Next.js process token-decryption authority.
 - **`SPFN_AUTH_SESSION_SECRET` is validated.** Minimum 32 chars plus entropy/unique-char checks —
   a short or low-entropy value fails startup, not just a warning.
 - **Forgetting the interceptor import.** Without `import '@spfn/auth/nextjs/api'` in the RPC proxy
@@ -391,6 +636,13 @@ middleware. Call `initOneTimeTokenManager({ ttl, store })` during setup for a cu
   every `switch(provider)` over login/register events must handle the new value.
 - **Email/SMS is not here.** It moved to `@spfn/notification` (`import { sendEmail, sendSMS } from
   '@spfn/notification/server'`). Wire verification-code / invitation emails through its events.
+- **`authJobRouter` isn't registered for you.** `createAuthLifecycle()`'s `afterInfrastructure`
+  hook runs *before* `@spfn/core` initializes pg-boss and registers jobs, so the lifecycle has no
+  opportunity to auto-register the account-deletion purge job. Call `.jobs(authJobRouter)`
+  yourself — see [Account Deletion & Recovery](#account-deletion--recovery).
+- **`USER_STATUSES` gained `pending_deletion` / `deleted`.** Any code with a `switch(user.status)`
+  or an exhaustive status union must handle both — `enumText` is plain `text` with no DB `CHECK`,
+  so nothing enforces this at the database layer.
 
 ## Complete example
 

package/dist/{authenticate-DXVtYh8X.d.ts → authenticate-ofdEmk6x.d.ts}

@@ -1,5 +1,5 @@
 import * as _spfn_core_route from '@spfn/core/route';
-import { K as KeyAlgorithmType, d as SocialProvider } from './types-BtksCI9X.js';
+import { K as KeyAlgorithmType, e as SocialProvider } from './types-1BMx0OX1.js';
 import * as _sinclair_typebox from '@sinclair/typebox';
 import { Static } from '@sinclair/typebox';
 import { User } from '@spfn/auth/server';
@@ -158,9 +158,9 @@ declare const PasswordSchema: _sinclair_typebox.TString;
 declare const TargetTypeSchema: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"email">, _sinclair_typebox.TLiteral<"phone">]>;
 type VerificationTargetType = Static<typeof TargetTypeSchema>;
 declare const VERIFICATION_TARGET_TYPES: readonly ["email", "phone"];
-declare const VerificationPurposeSchema: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"registration">, _sinclair_typebox.TLiteral<"login">, _sinclair_typebox.TLiteral<"password_reset">, _sinclair_typebox.TLiteral<"email_change">, _sinclair_typebox.TLiteral<"phone_change">]>;
+declare const VerificationPurposeSchema: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"registration">, _sinclair_typebox.TLiteral<"login">, _sinclair_typebox.TLiteral<"password_reset">, _sinclair_typebox.TLiteral<"email_change">, _sinclair_typebox.TLiteral<"phone_change">, _sinclair_typebox.TLiteral<"account_deletion">]>;
 type VerificationPurpose = Static<typeof VerificationPurposeSchema>;
-declare const VERIFICATION_PURPOSES: readonly ["registration", "login", "password_reset", "email_change", "phone_change"];
+declare const VERIFICATION_PURPOSES: readonly ["registration", "login", "password_reset", "email_change", "phone_change", "account_deletion"];
 
 /**
  * @spfn/auth - Verification Service
@@ -392,6 +392,10 @@ interface NativeVerifyOptions {
     /** 클라이언트가 생성한 raw nonce. provider별 규약(raw 또는 SHA-256 해시)으로 대조된다. */
     nonce: string;
 }
+interface OAuthCodeExchangeOptions {
+    /** Provider가 callback에 돌려준 원본 state. 일부 provider는 token 교환에도 요구한다. */
+    state: string;
+}
 /**
  * OAuth provider 구현 인터페이스
  *
@@ -413,7 +417,7 @@ interface OAuthProvider {
     /**
      * authorization code를 토큰으로 교환
      */
-    exchangeCodeForTokens(code: string): Promise<OAuthTokens>;
+    exchangeCodeForTokens(code: string, options: OAuthCodeExchangeOptions): Promise<OAuthTokens>;
     /**
      * access token으로 사용자 정보를 조회하고 공통 형태로 정규화
      */
@@ -477,12 +481,15 @@ interface OAuthCallbackParams {
     code: string;
     state: string;
     /**
-     * Value of the oauth_csrf cookie from the callback request. Must equal the
-     * nonce bound into the (encrypted) state — otherwise the flow wasn't initiated
-     * by this browser (login CSRF). Pass `undefined` when the cookie is absent;
-     * verification then fails closed.
+     * Value(s) of the oauth_csrf cookie from the callback request. One of them
+     * must equal the nonce bound into the (encrypted) state — otherwise the flow
+     * wasn't initiated by this browser (login CSRF). An array arises because the
+     * cookie name carries the PORT suffix of the process that set it (the Next.js
+     * web process), which differs from the API process in a split deployment, so
+     * the callback collects every spfn_oauth_csrf* candidate. Pass `undefined` or
+     * an empty array when absent; verification then fails closed.
      */
-    expectedNonce: string | undefined;
+    expectedNonce: string | string[] | undefined;
 }
 interface OAuthCallbackResult {
     redirectUrl: string;
@@ -586,6 +593,7 @@ declare function oauthNativeService(params: OAuthNativeParams): Promise<OAuthNat
  * - OAuth: /_auth/oauth/google, /_auth/oauth/google/callback, etc.
  * - Invitations: /_auth/invitations/*
  * - Users: /_auth/users/*
+ * - Deletion: /_auth/deletion/request, /_auth/deletion/cancel
  * - Admin: /_auth/admin/* (superadmin only)
  */
 declare const mainAuthRouter: _spfn_core_route.Router<{
@@ -593,7 +601,7 @@ declare const mainAuthRouter: _spfn_core_route.Router<{
         body: _sinclair_typebox.TObject<{
             target: _sinclair_typebox.TString;
             targetType: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"email">, _sinclair_typebox.TLiteral<"phone">]>;
-            purpose: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"registration">, _sinclair_typebox.TLiteral<"login">, _sinclair_typebox.TLiteral<"password_reset">, _sinclair_typebox.TLiteral<"email_change">, _sinclair_typebox.TLiteral<"phone_change">]>;
+            purpose: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"registration">, _sinclair_typebox.TLiteral<"login">, _sinclair_typebox.TLiteral<"password_reset">, _sinclair_typebox.TLiteral<"email_change">, _sinclair_typebox.TLiteral<"phone_change">, _sinclair_typebox.TLiteral<"account_deletion">]>;
         }>;
     }, {}, SendVerificationCodeResult>;
     verifyCode: _spfn_core_route.RouteDef<{
@@ -601,7 +609,7 @@ declare const mainAuthRouter: _spfn_core_route.Router<{
             target: _sinclair_typebox.TString;
             targetType: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"email">, _sinclair_typebox.TLiteral<"phone">]>;
             code: _sinclair_typebox.TString;
-            purpose: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"registration">, _sinclair_typebox.TLiteral<"login">, _sinclair_typebox.TLiteral<"password_reset">, _sinclair_typebox.TLiteral<"email_change">, _sinclair_typebox.TLiteral<"phone_change">]>;
+            purpose: _sinclair_typebox.TUnion<[_sinclair_typebox.TLiteral<"registration">, _sinclair_typebox.TLiteral<"login">, _sinclair_typebox.TLiteral<"password_reset">, _sinclair_typebox.TLiteral<"email_change">, _sinclair_typebox.TLiteral<"phone_change">, _sinclair_typebox.TLiteral<"account_deletion">]>;
         }>;
     }, {}, {
         valid: boolean;
@@ -674,6 +682,24 @@ declare const mainAuthRouter: _spfn_core_route.Router<{
         hasPassword: boolean;
     }>;
     issueOneTimeToken: _spfn_core_route.RouteDef<{}, {}, IssueOneTimeTokenResult>;
+    requestAccountDeletion: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            password: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            verificationToken: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            reason: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            immediate: _sinclair_typebox.TOptional<_sinclair_typebox.TBoolean>;
+        }>;
+    }, {}, {
+        purgeScheduledAt: string;
+    }>;
+    cancelAccountDeletion: _spfn_core_route.RouteDef<{
+        body: _sinclair_typebox.TObject<{
+            email: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            phone: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            password: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            verificationToken: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+        }>;
+    }, {}, void>;
     oauthGoogleStart: _spfn_core_route.RouteDef<{
         query: _sinclair_typebox.TObject<{
             state: _sinclair_typebox.TString;
@@ -704,6 +730,7 @@ declare const mainAuthRouter: _spfn_core_route.Router<{
     getGoogleOAuthUrl: _spfn_core_route.RouteDef<{
         body: _sinclair_typebox.TObject<{
             returnUrl: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            metadata: _sinclair_typebox.TOptional<_sinclair_typebox.TRecord<_sinclair_typebox.TString, _sinclair_typebox.TUnknown>>;
             state: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
         }>;
     }, {}, {
@@ -746,6 +773,7 @@ declare const mainAuthRouter: _spfn_core_route.Router<{
         }>;
         body: _sinclair_typebox.TObject<{
             returnUrl: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
+            metadata: _sinclair_typebox.TOptional<_sinclair_typebox.TRecord<_sinclair_typebox.TString, _sinclair_typebox.TUnknown>>;
             state: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
         }>;
     }, {}, {
@@ -900,6 +928,8 @@ declare const mainAuthRouter: _spfn_core_route.Router<{
             username: _sinclair_typebox.TUnion<[_sinclair_typebox.TString, _sinclair_typebox.TNull]>;
         }>;
     }, {}, {
+        deletedAt: Date | null;
+        deletedBy: string | null;
         createdAt: Date;
         updatedAt: Date;
         id: number;
@@ -910,7 +940,7 @@ declare const mainAuthRouter: _spfn_core_route.Router<{
         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;
@@ -1076,4 +1106,4 @@ declare const authenticate: _spfn_core_route.NamedMiddleware<"auth">;
  */
 declare const optionalAuth: _spfn_core_route.NamedMiddleware<"optionalAuth">;
 
-export { oauthNativeService as $, type AuthSession as A, rotateKeyService as B, type ChangePasswordParams as C, revokeKeyService as D, type RegisterPublicKeyParams as E, type RotateKeyParams as F, type RevokeKeyParams as G, issueOneTimeTokenService as H, type IssueOneTimeTokenResult as I, verifyOneTimeTokenService as J, oauthStartService as K, type LoginResult as L, oauthCallbackService as M, buildOAuthErrorUrl as N, type OAuthStartResult as O, type PermissionConfig as P, isOAuthProviderEnabled as Q, type RoleConfig as R, type SendVerificationCodeResult as S, requireEnabledProvider as T, type UserProfile as U, type VerificationTargetType as V, getEnabledOAuthProviders as W, getGoogleAccessToken as X, type OAuthStartParams as Y, type OAuthCallbackParams as Z, type OAuthCallbackResult as _, type RegisterResult as a, type OAuthNativeParams as a0, authenticate as a1, optionalAuth as a2, EmailSchema as a3, PhoneSchema as a4, PasswordSchema as a5, TargetTypeSchema as a6, VerificationPurposeSchema as a7, type NormalizedIdentity as a8, type OAuthTokens as a9, type NativeVerifyOptions as aa, registerOAuthProvider as ab, getOAuthProvider as ac, getRegisteredProviders as ad, type RotateKeyResult as b, type OAuthNativeResult as c, type ProfileInfo as d, type VerificationPurpose as e, VERIFICATION_TARGET_TYPES as f, VERIFICATION_PURPOSES as g, PERMISSION_CATEGORIES as h, type PermissionCategory as i, type AuthInitOptions as j, type OAuthProvider as k, type AuthContext as l, mainAuthRouter as m, loginService as n, logoutService as o, changePasswordService as p, type RegisterParams as q, registerService as r, type LoginParams as s, type LogoutParams as t, sendVerificationCodeService as u, verifyCodeService as v, type SendVerificationCodeParams as w, type VerifyCodeParams as x, type VerifyCodeResult as y, registerPublicKeyService as z };
+export { oauthNativeService as $, type AuthSession as A, rotateKeyService as B, type ChangePasswordParams as C, revokeKeyService as D, type RegisterPublicKeyParams as E, type RotateKeyParams as F, type RevokeKeyParams as G, issueOneTimeTokenService as H, type IssueOneTimeTokenResult as I, verifyOneTimeTokenService as J, oauthStartService as K, type LoginResult as L, oauthCallbackService as M, buildOAuthErrorUrl as N, type OAuthStartResult as O, type PermissionConfig as P, isOAuthProviderEnabled as Q, type RoleConfig as R, type SendVerificationCodeResult as S, requireEnabledProvider as T, type UserProfile as U, type VerificationTargetType as V, getEnabledOAuthProviders as W, getGoogleAccessToken as X, type OAuthStartParams as Y, type OAuthCallbackParams as Z, type OAuthCallbackResult as _, type RegisterResult as a, type OAuthNativeParams as a0, authenticate as a1, optionalAuth as a2, EmailSchema as a3, PhoneSchema as a4, PasswordSchema as a5, TargetTypeSchema as a6, VerificationPurposeSchema as a7, type NormalizedIdentity as a8, type OAuthTokens as a9, type NativeVerifyOptions as aa, type OAuthCodeExchangeOptions as ab, registerOAuthProvider as ac, getOAuthProvider as ad, getRegisteredProviders as ae, type RotateKeyResult as b, type OAuthNativeResult as c, type ProfileInfo as d, type VerificationPurpose as e, VERIFICATION_TARGET_TYPES as f, VERIFICATION_PURPOSES as g, PERMISSION_CATEGORIES as h, type PermissionCategory as i, type AuthInitOptions as j, type OAuthProvider as k, type AuthContext as l, mainAuthRouter as m, loginService as n, logoutService as o, changePasswordService as p, type RegisterParams as q, registerService as r, type LoginParams as s, type LogoutParams as t, sendVerificationCodeService as u, verifyCodeService as v, type SendVerificationCodeParams as w, type VerifyCodeParams as x, type VerifyCodeResult as y, registerPublicKeyService as z };