@fluojs/passport 1.0.0-beta.1

package/dist/status.js

@@ -0,0 +1,173 @@
+/** Snapshot payload describing passport readiness, health, ownership, and diagnostic details. */
+
+/** Input contract for deriving passport platform health and readiness diagnostics. */
+
+function hasRegisteredStrategies(input) {
+  return input.registeredStrategies.length > 0;
+}
+function hasDefaultStrategyMismatch(input) {
+  if (!input.defaultStrategy) {
+    return false;
+  }
+  return !input.registeredStrategies.includes(input.defaultStrategy);
+}
+function isCookiePresetReady(input) {
+  if (!input.cookiePresetEnabled) {
+    return true;
+  }
+  return input.cookiePresetReady ?? true;
+}
+function isRefreshTokenStoreReady(input) {
+  if (!input.refreshTokenEnabled) {
+    return true;
+  }
+  return input.refreshTokenStoreReady ?? true;
+}
+function collectReadinessReasons(input) {
+  const reasons = [];
+  if (!hasRegisteredStrategies(input)) {
+    reasons.push('No auth strategies are registered.');
+  }
+  if (hasDefaultStrategyMismatch(input)) {
+    reasons.push(`Default strategy "${input.defaultStrategy}" is not registered.`);
+  }
+  if (!isCookiePresetReady(input)) {
+    reasons.push('Cookie auth preset is enabled but not ready.');
+  }
+  if (!isRefreshTokenStoreReady(input)) {
+    reasons.push(input.refreshTokenStoreReason ?? 'Refresh token backing store is unavailable.');
+  }
+  return reasons;
+}
+function createReadiness(input) {
+  const critical = input.readinessCritical ?? false;
+  const reasons = collectReadinessReasons(input);
+  if (reasons.length === 0) {
+    return {
+      critical,
+      status: 'ready'
+    };
+  }
+  return {
+    critical,
+    reason: reasons.join(' '),
+    status: critical ? 'not-ready' : 'degraded'
+  };
+}
+function createHealth(input) {
+  const reasons = collectReadinessReasons(input);
+  if (reasons.length === 0) {
+    return {
+      status: 'healthy'
+    };
+  }
+  return {
+    reason: reasons.join(' '),
+    status: 'degraded'
+  };
+}
+
+/**
+ * Creates a platform snapshot for passport strategy wiring and preset readiness.
+ *
+ * @param input Passport readiness inputs such as registered strategies, default strategy, and preset readiness flags.
+ * @returns A platform snapshot containing passport health, readiness, ownership, and structured details.
+ */
+export function createPassportPlatformStatusSnapshot(input) {
+  const componentId = input.componentId ?? 'passport.default';
+  const degraded = collectReadinessReasons(input).length > 0;
+  return {
+    details: {
+      policyBoundary: {
+        applicationOwned: ['login credential validation', 'session persistence and consent policy', 'account upsert or merge ownership'],
+        frameworkOwned: ['strategy execution and guard contract', 'cookie auth preset primitives', 'refresh token strategy bridge and lifecycle contract']
+      },
+      presets: {
+        cookieAuth: {
+          enabled: input.cookiePresetEnabled ?? false,
+          ready: isCookiePresetReady(input)
+        },
+        refreshToken: {
+          backingStore: {
+            dependencyId: input.refreshTokenDependencyId,
+            reason: input.refreshTokenStoreReason,
+            ready: isRefreshTokenStoreReady(input)
+          },
+          enabled: input.refreshTokenEnabled ?? false
+        }
+      },
+      strategyRegistry: {
+        defaultStrategy: input.defaultStrategy,
+        hasStrategies: hasRegisteredStrategies(input),
+        registeredStrategies: input.registeredStrategies
+      },
+      telemetry: {
+        labels: {
+          component_id: componentId,
+          component_kind: 'passport',
+          operation: 'auth-strategy-dispatch',
+          result: degraded ? 'degraded' : 'ready'
+        },
+        namespace: 'passport'
+      }
+    },
+    health: createHealth(input),
+    ownership: {
+      externallyManaged: true,
+      ownsResources: false
+    },
+    readiness: createReadiness(input)
+  };
+}
+
+/**
+ * Creates platform diagnostic issues for passport registry and preset readiness problems.
+ *
+ * @param input Passport readiness inputs such as registered strategies, default strategy, and preset readiness flags.
+ * @returns Diagnostic issues describing empty registries, strategy mismatches, and preset dependency failures.
+ */
+export function createPassportPlatformDiagnosticIssues(input) {
+  const componentId = input.componentId ?? 'passport.default';
+  const critical = input.readinessCritical ?? false;
+  const severity = critical ? 'error' : 'warning';
+  const issues = [];
+  if (!hasRegisteredStrategies(input)) {
+    issues.push({
+      code: 'AUTH_PASSPORT_STRATEGY_REGISTRY_EMPTY',
+      componentId,
+      fixHint: 'Register at least one auth strategy via PassportModule.forRoot(..., strategies).',
+      message: 'Passport strategy registry has no registered auth strategies.',
+      severity
+    });
+  }
+  if (hasDefaultStrategyMismatch(input)) {
+    issues.push({
+      code: 'AUTH_PASSPORT_DEFAULT_STRATEGY_NOT_REGISTERED',
+      componentId,
+      fixHint: 'Register the default strategy token or change defaultStrategy to a registered strategy name.',
+      message: `Passport default strategy "${input.defaultStrategy}" is not present in the strategy registry.`,
+      severity
+    });
+  }
+  if (!isCookiePresetReady(input)) {
+    issues.push({
+      code: 'AUTH_PASSPORT_COOKIE_PRESET_NOT_READY',
+      componentId,
+      fixHint: 'Ensure cookie auth preset providers are registered and cookie options are configured for this environment.',
+      message: 'Cookie auth preset is enabled but cannot accept authentication traffic safely.',
+      severity
+    });
+  }
+  if (!isRefreshTokenStoreReady(input)) {
+    issues.push({
+      code: 'AUTH_PASSPORT_REFRESH_TOKEN_BACKING_STORE_NOT_READY',
+      componentId,
+      cause: input.refreshTokenStoreReason,
+      dependsOn: input.refreshTokenDependencyId ? [input.refreshTokenDependencyId] : undefined,
+      fixHint: 'Restore refresh token backing store readiness, or disable refresh-token strategy for this environment.',
+      message: 'Refresh token strategy is enabled, but its backing dependency is not ready.',
+      severity
+    });
+  }
+  return issues;
+}

package/dist/types.d.ts

@@ -0,0 +1,36 @@
+import type { MaybePromise, Token } from '@fluojs/core';
+import type { Guard, GuardContext, Principal } from '@fluojs/http';
+/** Route-level authentication requirement metadata. */
+export interface AuthRequirement {
+    /** Named strategy to resolve from the strategy registry. */
+    strategy?: string;
+    /** Required scopes that must be present on the resolved principal. */
+    scopes?: string[];
+}
+/** Authentication result variant used when a strategy fully handled the response. */
+export interface AuthHandledResult {
+    handled: true;
+    principal?: Principal;
+}
+/** Return type of an `AuthStrategy.authenticate(...)` call. */
+export type AuthStrategyResult = Principal | AuthHandledResult;
+/** Strategy contract implemented by authentication adapters. */
+export interface AuthStrategy {
+    authenticate(context: GuardContext): MaybePromise<AuthStrategyResult>;
+}
+/** Registration entry used by `PassportModule.forRoot(...)`. */
+export interface AuthStrategyRegistration {
+    name: string;
+    token: Token<AuthStrategy>;
+}
+/** Immutable strategy lookup map keyed by strategy name. */
+export type AuthStrategyRegistry = Readonly<Record<string, Token<AuthStrategy>>>;
+/** Module-level options for passport strategy wiring. */
+export interface PassportModuleOptions {
+    defaultStrategy?: string;
+}
+/** Contract for the public `AuthGuard` behavior. */
+export interface AuthGuardContract extends Guard {
+    canActivate(context: GuardContext): Promise<true>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEnE,uDAAuD;AACvD,MAAM,WAAW,eAAe;IAC9B,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,qFAAqF;AACrF,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,IAAI,CAAC;IACd,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED,+DAA+D;AAC/D,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,iBAAiB,CAAC;AAE/D,gEAAgE;AAChE,MAAM,WAAW,YAAY;IAC3B,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,YAAY,CAAC,kBAAkB,CAAC,CAAC;CACvE;AAED,gEAAgE;AAChE,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC;CAC5B;AAED,4DAA4D;AAC5D,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;AAEjF,yDAAyD;AACzD,MAAM,WAAW,qBAAqB;IACpC,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,oDAAoD;AACpD,MAAM,WAAW,iBAAkB,SAAQ,KAAK;IAC9C,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@fluojs/passport",
+  "description": "Strategy-agnostic authentication guard wiring and strategy registry for Fluo.",
+  "keywords": [
+    "fluo",
+    "passport",
+    "authentication",
+    "auth",
+    "guard",
+    "strategy"
+  ],
+  "version": "1.0.0-beta.1",
+  "private": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fluojs/fluo.git",
+    "directory": "packages/passport"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@fluojs/core": "^1.0.0-beta.1",
+    "@fluojs/di": "^1.0.0-beta.1",
+    "@fluojs/http": "^1.0.0-beta.1",
+    "@fluojs/jwt": "^1.0.0-beta.1",
+    "@fluojs/runtime": "^1.0.0-beta.1"
+  },
+  "devDependencies": {
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "prebuild": "node ../../tooling/scripts/clean-dist.mjs",
+    "build": "pnpm exec babel src --extensions .ts --ignore 'src/**/*.test.ts' --out-dir dist --config-file ../../tooling/babel/babel.config.cjs && pnpm exec tsc -p tsconfig.build.json",
+    "typecheck": "pnpm exec tsc -p tsconfig.json --noEmit",
+    "test": "pnpm exec vitest run -c vitest.config.ts",
+    "test:watch": "pnpm exec vitest -c vitest.config.ts"
+  }
+}