@fluojs/passport 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fluo contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,179 @@
+# @fluojs/passport
+
+<p><a href="./README.md"><kbd>English</kbd></a> <strong><kbd>한국어</kbd></strong></p>
+
+fluo를 위한 인증 실행 계층으로, 어떤 `AuthStrategy`든 공통 `AuthGuard`를 통해 요청 컨텍스트(`requestContext.principal`)에 연결합니다.
+
+## 목차
+
+- [설치](#설치)
+- [사용 시점](#사용-시점)
+- [빠른 시작](#빠른-시작)
+- [일반적인 패턴](#일반적인-패턴)
+- [공개 API 개요](#공개-api-개요)
+- [관련 패키지](#관련-패키지)
+- [예제 소스](#예제-소스)
+
+## 설치
+
+```bash
+npm install @fluojs/passport
+```
+
+## 사용 시점
+
+- 애플리케이션에 인증 및 권한 부여(RBAC/Scopes) 기능을 추가해야 할 때.
+- 하나의 애플리케이션에서 여러 인증 방식(JWT, 쿠키, API 키 등)을 혼합하여 사용할 때.
+- 기존 Passport.js 전략들을 fluo의 DI 및 비동기 환경에서 재사용하고 싶을 때.
+- 리프레시 토큰 로테이션이나 계정 연결 정책을 구현할 때.
+
+## 빠른 시작
+
+### 1. 모듈 등록
+
+사용할 전략을 정의하고 `PassportModule.forRoot(...)`를 통해 등록합니다.
+
+```typescript
+import { Module } from '@fluojs/core';
+import { PassportModule } from '@fluojs/passport';
+import { MyJwtStrategy } from './jwt.strategy';
+
+@Module({
+  imports: [
+    PassportModule.forRoot(
+      { defaultStrategy: 'jwt' },
+      [{ name: 'jwt', token: MyJwtStrategy }]
+    ),
+  ],
+  providers: [MyJwtStrategy],
+})
+export class AuthModule {}
+```
+
+전략 등록은 `PassportModule.forRoot(...)`로 구성합니다.
+
+### 2. 라우트 보호
+
+`@UseAuth()`와 `@RequireScopes()`를 사용하여 인증을 강제합니다.
+
+```typescript
+import { Controller, Get, type RequestContext } from '@fluojs/http';
+import { UseAuth, RequireScopes } from '@fluojs/passport';
+
+@Controller('/profile')
+export class ProfileController {
+  @Get('/')
+  @UseAuth('jwt')
+  @RequireScopes('profile:read')
+  async getProfile(input: never, ctx: RequestContext) {
+    return { user: ctx.principal };
+  }
+}
+```
+
+## 일반적인 패턴
+
+### Passport.js 브릿지 (Bridge)
+
+표준 Passport.js 전략(예: `passport-google-oauth20`)을 fluo의 DI와 비동기 수명 주기에 맞춰 쉽게 변환하여 사용할 수 있습니다.
+
+```typescript
+const googleBridge = createPassportJsStrategyBridge('google', GoogleStrategy, {
+  mapPrincipal: ({ user }) => ({ subject: user.id, claims: user }),
+});
+```
+
+### 쿠키 인증 프리셋
+
+HTTP 쿠키에서 인증 정보를 읽는 애플리케이션이라면 `CookieAuthModule.forRoot(...)`를 사용합니다.
+
+```typescript
+import { Module } from '@fluojs/core';
+import {
+  CookieAuthModule,
+  CookieAuthStrategy,
+  COOKIE_AUTH_STRATEGY_NAME,
+  PassportModule,
+} from '@fluojs/passport';
+
+@Module({
+  imports: [
+    CookieAuthModule.forRoot(),
+    PassportModule.forRoot(
+      { defaultStrategy: COOKIE_AUTH_STRATEGY_NAME },
+      [{ name: COOKIE_AUTH_STRATEGY_NAME, token: CookieAuthStrategy }],
+    ),
+  ],
+})
+export class AuthModule {}
+```
+
+애플리케이션 모듈에서 cookie-auth 지원이 필요하면 `CookieAuthModule.forRoot(...)`를 `PassportModule.forRoot(...)`와 함께 import 하세요.
+
+### 리프레시 토큰 수명 주기
+
+패키지에서 제공하는 `RefreshTokenStrategy`와 `RefreshTokenService`를 사용하여 안전한 토큰 로테이션 및 폐기 기능을 구현할 수 있습니다.
+
+```typescript
+import { Module } from '@fluojs/core';
+import { Controller, Post, type RequestContext } from '@fluojs/http';
+import {
+  PassportModule,
+  REFRESH_TOKEN_STRATEGY_NAME,
+  RefreshTokenModule,
+  RefreshTokenStrategy,
+  UseAuth,
+} from '@fluojs/passport';
+
+@Module({
+  imports: [
+    RefreshTokenModule.forRoot(MyRefreshTokenService),
+    PassportModule.forRoot(
+      { defaultStrategy: REFRESH_TOKEN_STRATEGY_NAME },
+      [{ name: REFRESH_TOKEN_STRATEGY_NAME, token: RefreshTokenStrategy }],
+    ),
+  ],
+  providers: [MyRefreshTokenService],
+})
+export class AuthModule {}
+
+@Controller('/auth')
+export class AuthController {
+  @Post('/refresh')
+  @UseAuth('refresh-token')
+  async refresh(input: never, ctx: RequestContext) {
+    return ctx.principal; // 새 토큰 쌍이 포함된 principal 반환
+  }
+}
+```
+
+`RefreshTokenModule.forRoot(...)`를 `PassportModule.forRoot(...)`와 함께 import 하여 refresh-token 전략과 공유 `REFRESH_TOKEN_SERVICE` alias를 같은 모듈 wiring에서 사용하세요.
+
+## 공개 API 개요
+
+### 데코레이터
+- `@UseAuth(strategyName)`: `AuthGuard`를 부착하고 사용할 전략을 설정합니다.
+- `@RequireScopes(...scopes)`: 특정 권한(스코프) 요구 사항을 강제합니다.
+
+### 주요 클래스
+- `PassportModule`: passport 전략 wiring을 위한 모듈 진입점입니다.
+- `AuthGuard`: 전략 체인을 실행하는 HTTP 가드입니다.
+- `CookieAuthModule`: 내장 cookie-auth 프리셋의 모듈 진입점입니다.
+- `CookieManager`: HttpOnly 인증 쿠키 관리를 위한 유틸리티입니다.
+- `RefreshTokenModule`: 내장 refresh-token 프리셋의 모듈 진입점입니다.
+- `JwtRefreshTokenAdapter`: `@fluojs/jwt`의 리프레시 로직을 패스포트 인터페이스로 연결합니다.
+
+### 인터페이스
+- `AuthStrategy`: 커스텀 인증 로직 구현을 위한 계약입니다.
+- `AccountLinkPolicy`: 계정 연결 결정 로직을 위한 확장 지점입니다.
+
+## 관련 패키지
+
+- `@fluojs/jwt`: JWT 기반 전략을 위한 하위 토큰 코어 패키지입니다.
+- `@fluojs/http`: 라우팅 및 가드 인프라를 제공하는 기본 패키지입니다.
+
+## 예제 소스
+
+- `packages/passport/src/guard.test.ts`: 가드 실행 및 권한 강제 패턴 예제.
+- `packages/passport/src/adapters/passport-js.ts`: Passport.js 브릿지 구현체.
+- `examples/auth-jwt-passport/src/auth/bearer.strategy.ts`: 표준 JWT 전략 구현 예제.

package/README.md

@@ -0,0 +1,179 @@
+# @fluojs/passport
+
+<p><strong><kbd>English</kbd></strong> <a href="./README.ko.md"><kbd>한국어</kbd></a></p>
+
+Strategy-agnostic auth execution layer for fluo. It routes any `AuthStrategy` through a generic `AuthGuard` into the request context, populating `requestContext.principal`.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [When to use](#when-to-use)
+- [Quick Start](#quick-start)
+- [Common Patterns](#common-patterns)
+- [Public API](#public-api)
+- [Related Packages](#related-packages)
+- [Example Sources](#example-sources)
+
+## Installation
+
+```bash
+npm install @fluojs/passport
+```
+
+## When to Use
+
+- When you need to protect routes with authentication and authorization (RBAC/Scopes).
+- When using multiple auth strategies (e.g., JWT, Cookies, API Keys) in the same application.
+- When you need a bridge to existing Passport.js strategies.
+- When implementing refresh token rotation or account-linking policies.
+
+## Quick Start
+
+### 1. Register Modules
+
+Define your strategies and register them using `PassportModule.forRoot(...)`.
+
+```typescript
+import { Module } from '@fluojs/core';
+import { PassportModule } from '@fluojs/passport';
+import { MyJwtStrategy } from './jwt.strategy';
+
+@Module({
+  imports: [
+    PassportModule.forRoot(
+      { defaultStrategy: 'jwt' },
+      [{ name: 'jwt', token: MyJwtStrategy }]
+    ),
+  ],
+  providers: [MyJwtStrategy],
+})
+export class AuthModule {}
+```
+
+Register strategies through `PassportModule.forRoot(...)`.
+
+### 2. Protect Routes
+
+Use `@UseAuth()` and `@RequireScopes()` to enforce authentication.
+
+```typescript
+import { Controller, Get, type RequestContext } from '@fluojs/http';
+import { UseAuth, RequireScopes } from '@fluojs/passport';
+
+@Controller('/profile')
+export class ProfileController {
+  @Get('/')
+  @UseAuth('jwt')
+  @RequireScopes('profile:read')
+  async getProfile(input: never, ctx: RequestContext) {
+    return { user: ctx.principal };
+  }
+}
+```
+
+## Common Patterns
+
+### Passport.js Bridge
+
+Easily adapt any standard Passport.js strategy (like `passport-google-oauth20`) to work with fluo's DI and async lifecycle.
+
+```typescript
+const googleBridge = createPassportJsStrategyBridge('google', GoogleStrategy, {
+  mapPrincipal: ({ user }) => ({ subject: user.id, claims: user }),
+});
+```
+
+### Cookie Auth Preset
+
+Use `CookieAuthModule.forRoot(...)` when your app authenticates requests from HTTP cookies.
+
+```typescript
+import { Module } from '@fluojs/core';
+import {
+  CookieAuthModule,
+  CookieAuthStrategy,
+  COOKIE_AUTH_STRATEGY_NAME,
+  PassportModule,
+} from '@fluojs/passport';
+
+@Module({
+  imports: [
+    CookieAuthModule.forRoot(),
+    PassportModule.forRoot(
+      { defaultStrategy: COOKIE_AUTH_STRATEGY_NAME },
+      [{ name: COOKIE_AUTH_STRATEGY_NAME, token: CookieAuthStrategy }],
+    ),
+  ],
+})
+export class AuthModule {}
+```
+
+Import `CookieAuthModule.forRoot(...)` alongside `PassportModule.forRoot(...)` when you want cookie-auth support in an application module.
+
+### Refresh Token Lifecycle
+
+The package provides a built-in `RefreshTokenStrategy` and `RefreshTokenService` to handle secure token rotation and revocation.
+
+```typescript
+import { Module } from '@fluojs/core';
+import { Controller, Post, type RequestContext } from '@fluojs/http';
+import {
+  PassportModule,
+  REFRESH_TOKEN_STRATEGY_NAME,
+  RefreshTokenModule,
+  RefreshTokenStrategy,
+  UseAuth,
+} from '@fluojs/passport';
+
+@Module({
+  imports: [
+    RefreshTokenModule.forRoot(MyRefreshTokenService),
+    PassportModule.forRoot(
+      { defaultStrategy: REFRESH_TOKEN_STRATEGY_NAME },
+      [{ name: REFRESH_TOKEN_STRATEGY_NAME, token: RefreshTokenStrategy }],
+    ),
+  ],
+  providers: [MyRefreshTokenService],
+})
+export class AuthModule {}
+
+@Controller('/auth')
+export class AuthController {
+  @Post('/refresh')
+  @UseAuth('refresh-token')
+  async refresh(input: never, ctx: RequestContext) {
+    return ctx.principal; // Contains new token pair
+  }
+}
+```
+
+Import `RefreshTokenModule.forRoot(...)` alongside `PassportModule.forRoot(...)` so the refresh-token strategy and shared `REFRESH_TOKEN_SERVICE` alias are available in the same module wiring.
+
+## Public API Overview
+
+### Decorators
+- `@UseAuth(strategyName)`: Attaches `AuthGuard` and sets the active strategy.
+- `@RequireScopes(...scopes)`: Enforces specific scope requirements.
+
+### Core Classes
+- `PassportModule`: Module entry point for passport strategy wiring.
+- `AuthGuard`: The HTTP guard that executes the strategy chain.
+- `CookieAuthModule`: Module entry point for the built-in cookie-auth preset.
+- `CookieManager`: Utility for managing HttpOnly auth cookies.
+- `RefreshTokenModule`: Module entry point for the built-in refresh-token preset.
+- `JwtRefreshTokenAdapter`: Bridges `@fluojs/jwt` refresh logic to the passport interface.
+
+### Interfaces
+- `AuthStrategy`: The contract for implementing custom authentication logic.
+- `AccountLinkPolicy`: Extension point for identity-linking decisions.
+
+## Related Packages
+
+- `@fluojs/jwt`: The underlying token core for JWT-based strategies.
+- `@fluojs/http`: Provides the routing and guard infrastructure.
+
+## Example Sources
+
+- `packages/passport/src/guard.test.ts`: Guard execution and scope enforcement patterns.
+- `packages/passport/src/adapters/passport-js.ts`: Implementation of the Passport.js bridge.
+- `examples/auth-jwt-passport/src/auth/bearer.strategy.ts`: JWT strategy implementation.

package/dist/account/account-linking.d.ts

@@ -0,0 +1,91 @@
+import { FluoError, type MaybePromise } from '@fluojs/core';
+/** DI token for registering an account-linking policy implementation. */
+export declare const ACCOUNT_LINKING_POLICY: unique symbol;
+/** Identity payload from an external authentication provider. */
+export interface AccountIdentity {
+    provider: string;
+    providerSubject: string;
+    email?: string;
+    emailVerified?: boolean;
+    claims?: Record<string, unknown>;
+}
+/** Candidate account that may be linked to an external identity. */
+export interface AccountLinkCandidate {
+    accountId: string;
+    reason: 'existing-link' | 'email-match' | 'username-match' | string;
+}
+/** Explicit user confirmation payload for a requested linking target. */
+export interface AccountLinkAttempt {
+    targetAccountId: string;
+    confirmedByUser: boolean;
+}
+/** Input passed to account-link policy evaluation. */
+export interface AccountLinkContext {
+    identity: AccountIdentity;
+    candidates: AccountLinkCandidate[];
+    linkAttempt?: AccountLinkAttempt;
+}
+/** Normalized decision contract returned by an `AccountLinkPolicy`. */
+export type AccountLinkPolicyDecision = {
+    action: 'link';
+    accountId: string;
+    reason: string;
+} | {
+    action: 'create-account';
+    reason: string;
+} | {
+    action: 'reject';
+    reason: string;
+    code?: string;
+} | {
+    action: 'conflict';
+    reason: string;
+    candidateAccountIds: string[];
+};
+/** Policy contract for account-linking decisions. */
+export interface AccountLinkPolicy {
+    evaluate(context: AccountLinkContext): MaybePromise<AccountLinkPolicyDecision>;
+}
+/** Optional runtime behavior when no policy is configured. */
+export interface AccountLinkingOptions {
+    fallback?: 'create-account' | 'skip';
+}
+/** Final framework-level resolution for account-linking flow. */
+export type AccountLinkingResolution = {
+    status: 'linked';
+    accountId: string;
+    reason: string;
+} | {
+    status: 'create-account';
+    reason: string;
+} | {
+    status: 'skipped';
+    reason: string;
+};
+/** Error raised when linking requires user confirmation among candidates. */
+export declare class AccountLinkConflictError extends FluoError {
+    readonly candidateAccountIds: string[];
+    constructor(candidateAccountIds: string[], message?: string);
+}
+/** Error raised when an account-linking attempt is rejected by policy. */
+export declare class AccountLinkRejectedError extends FluoError {
+    constructor(message?: string, code?: string);
+}
+/**
+ * Conservative baseline policy that never auto-links ambiguous candidates.
+ *
+ * @returns An `AccountLinkPolicy` implementation that requires explicit user confirmation for non-explicit matches.
+ */
+export declare function createConservativeAccountLinkPolicy(): AccountLinkPolicy;
+/**
+ * Resolves account-linking flow using the provided policy and fallback rules.
+ *
+ * @param context Identity, candidate accounts, and optional explicit link-attempt confirmation input.
+ * @param policy Optional account-link policy implementation. When omitted, `options.fallback` controls behavior.
+ * @param options Runtime fallback behavior used only when `policy` is not configured.
+ * @returns A normalized framework decision: `linked`, `create-account`, or `skipped`.
+ * @throws {AccountLinkRejectedError} When policy returns `action: 'reject'`.
+ * @throws {AccountLinkConflictError} When policy returns `action: 'conflict'` and explicit confirmation is required.
+ */
+export declare function resolveAccountLinking(context: AccountLinkContext, policy?: AccountLinkPolicy, options?: AccountLinkingOptions): Promise<AccountLinkingResolution>;
+//# sourceMappingURL=account-linking.d.ts.map

package/dist/account/account-linking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"account-linking.d.ts","sourceRoot":"","sources":["../../src/account/account-linking.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5D,yEAAyE;AACzE,eAAO,MAAM,sBAAsB,eAAqD,CAAC;AAEzF,iEAAiE;AACjE,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,oEAAoE;AACpE,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,eAAe,GAAG,aAAa,GAAG,gBAAgB,GAAG,MAAM,CAAC;CACrE;AAED,yEAAyE;AACzE,MAAM,WAAW,kBAAkB;IACjC,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,sDAAsD;AACtD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,eAAe,CAAC;IAC1B,UAAU,EAAE,oBAAoB,EAAE,CAAC;IACnC,WAAW,CAAC,EAAE,kBAAkB,CAAC;CAClC;AAED,uEAAuE;AACvE,MAAM,MAAM,yBAAyB,GACjC;IACE,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB,GACD;IACE,MAAM,EAAE,gBAAgB,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;CAChB,GACD;IACE,MAAM,EAAE,QAAQ,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GACD;IACE,MAAM,EAAE,UAAU,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,mBAAmB,EAAE,MAAM,EAAE,CAAC;CAC/B,CAAC;AAEN,qDAAqD;AACrD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,GAAG,YAAY,CAAC,yBAAyB,CAAC,CAAC;CAChF;AAED,8DAA8D;AAC9D,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,gBAAgB,GAAG,MAAM,CAAC;CACtC;AAED,iEAAiE;AACjE,MAAM,MAAM,wBAAwB,GAChC;IACE,MAAM,EAAE,QAAQ,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB,GACD;IACE,MAAM,EAAE,gBAAgB,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;CAChB,GACD;IACE,MAAM,EAAE,SAAS,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEN,6EAA6E;AAC7E,qBAAa,wBAAyB,SAAQ,SAAS;IACrD,QAAQ,CAAC,mBAAmB,EAAE,MAAM,EAAE,CAAC;gBAGrC,mBAAmB,EAAE,MAAM,EAAE,EAC7B,OAAO,SAAoE;CAW9E;AAED,0EAA0E;AAC1E,qBAAa,wBAAyB,SAAQ,SAAS;gBACzC,OAAO,SAA0C,EAAE,IAAI,SAA0B;CAG9F;AAED;;;;GAIG;AACH,wBAAgB,mCAAmC,IAAI,iBAAiB,CAsDvE;AAKD;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,kBAAkB,EAC3B,MAAM,CAAC,EAAE,iBAAiB,EAC1B,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,wBAAwB,CAAC,CA0CnC"}

package/dist/account/account-linking.js

@@ -0,0 +1,145 @@
+import { FluoError } from '@fluojs/core';
+
+/** DI token for registering an account-linking policy implementation. */
+export const ACCOUNT_LINKING_POLICY = Symbol.for('fluo.passport.account-linking-policy');
+
+/** Identity payload from an external authentication provider. */
+
+/** Candidate account that may be linked to an external identity. */
+
+/** Explicit user confirmation payload for a requested linking target. */
+
+/** Input passed to account-link policy evaluation. */
+
+/** Normalized decision contract returned by an `AccountLinkPolicy`. */
+
+/** Policy contract for account-linking decisions. */
+
+/** Optional runtime behavior when no policy is configured. */
+
+/** Final framework-level resolution for account-linking flow. */
+
+/** Error raised when linking requires user confirmation among candidates. */
+export class AccountLinkConflictError extends FluoError {
+  candidateAccountIds;
+  constructor(candidateAccountIds, message = 'Multiple account candidates require explicit link confirmation.') {
+    super(message, {
+      code: 'ACCOUNT_LINK_CONFLICT',
+      meta: {
+        candidateAccountIds: [...candidateAccountIds]
+      }
+    });
+    this.candidateAccountIds = [...candidateAccountIds];
+  }
+}
+
+/** Error raised when an account-linking attempt is rejected by policy. */
+export class AccountLinkRejectedError extends FluoError {
+  constructor(message = 'Account-linking attempt was rejected.', code = 'ACCOUNT_LINK_REJECTED') {
+    super(message, {
+      code
+    });
+  }
+}
+
+/**
+ * Conservative baseline policy that never auto-links ambiguous candidates.
+ *
+ * @returns An `AccountLinkPolicy` implementation that requires explicit user confirmation for non-explicit matches.
+ */
+export function createConservativeAccountLinkPolicy() {
+  return {
+    evaluate(context) {
+      const existingLink = context.candidates.find(candidate => candidate.reason === 'existing-link');
+      if (existingLink) {
+        return {
+          action: 'link',
+          accountId: existingLink.accountId,
+          reason: 'Existing identity link found.'
+        };
+      }
+      const linkAttempt = context.linkAttempt;
+      if (linkAttempt) {
+        if (!linkAttempt.confirmedByUser) {
+          return {
+            action: 'reject',
+            code: 'ACCOUNT_LINK_CONFIRMATION_REQUIRED',
+            reason: 'Explicit link confirmation is required before linking identities.'
+          };
+        }
+        if (context.candidates.some(candidate => candidate.accountId === linkAttempt.targetAccountId)) {
+          return {
+            action: 'link',
+            accountId: linkAttempt.targetAccountId,
+            reason: 'Identity linked after explicit user confirmation.'
+          };
+        }
+        return {
+          action: 'reject',
+          code: 'ACCOUNT_LINK_TARGET_NOT_FOUND',
+          reason: 'Requested account for linking is not a valid candidate.'
+        };
+      }
+      if (context.candidates.length === 0) {
+        return {
+          action: 'create-account',
+          reason: 'No matching account candidate found for this external identity.'
+        };
+      }
+      return {
+        action: 'conflict',
+        candidateAccountIds: context.candidates.map(candidate => candidate.accountId),
+        reason: context.candidates.length === 1 ? 'A single account candidate matched. Explicit confirmation is required before linking.' : 'Multiple account candidates matched. Explicit confirmation is required before linking.'
+      };
+    }
+  };
+}
+const DEFAULT_SKIP_REASON = 'No account-linking policy was configured. The framework leaves identity linking to the application.';
+
+/**
+ * Resolves account-linking flow using the provided policy and fallback rules.
+ *
+ * @param context Identity, candidate accounts, and optional explicit link-attempt confirmation input.
+ * @param policy Optional account-link policy implementation. When omitted, `options.fallback` controls behavior.
+ * @param options Runtime fallback behavior used only when `policy` is not configured.
+ * @returns A normalized framework decision: `linked`, `create-account`, or `skipped`.
+ * @throws {AccountLinkRejectedError} When policy returns `action: 'reject'`.
+ * @throws {AccountLinkConflictError} When policy returns `action: 'conflict'` and explicit confirmation is required.
+ */
+export async function resolveAccountLinking(context, policy, options = {}) {
+  if (!policy) {
+    if (options.fallback === 'create-account') {
+      return {
+        reason: 'No policy configured. Falling back to account creation.',
+        status: 'create-account'
+      };
+    }
+    return {
+      reason: DEFAULT_SKIP_REASON,
+      status: 'skipped'
+    };
+  }
+  const decision = await policy.evaluate(context);
+  switch (decision.action) {
+    case 'link':
+      return {
+        accountId: decision.accountId,
+        reason: decision.reason,
+        status: 'linked'
+      };
+    case 'create-account':
+      return {
+        reason: decision.reason,
+        status: 'create-account'
+      };
+    case 'reject':
+      throw new AccountLinkRejectedError(decision.reason, decision.code);
+    case 'conflict':
+      throw new AccountLinkConflictError(decision.candidateAccountIds, decision.reason);
+    default:
+      {
+        const exhaustiveCheck = decision;
+        return exhaustiveCheck;
+      }
+  }
+}