@furystack/security 7.0.9 → 8.0.1

package/src/security-policy-manager.ts

@@ -1,51 +1,100 @@
-import { Injectable, Injected } from '@furystack/inject'
+import { defineService, type Token } from '@furystack/inject'
 import type { PasswordCredential, PasswordResetToken } from './models/index.js'
 import { SecurityPolicy } from './security-policy.js'
 
-@Injectable({ lifetime: 'singleton' })
-export class SecurityPolicyManager {
+/**
+ * Result of a successful password complexity check — no rule reported a
+ * failure.
+ */
+export type PasswordComplexityMatch = { match: true }
+
+/**
+ * Result of a failed password complexity check along with the individual
+ * rule failures for user-facing reporting.
+ */
+export type PasswordComplexityMismatch = {
+  match: false
+  errors: Array<{ message: string; rule: string }>
+}
+
+/**
+ * Runtime checker for the active {@link SecurityPolicy}. Applies complexity
+ * rules to candidate passwords and determines whether stored credentials
+ * and reset tokens have expired.
+ */
+export interface SecurityPolicyManager {
+  /** The active {@link SecurityPolicy} snapshot captured at resolve time. */
+  readonly policy: SecurityPolicy
   /**
-   * @param password The Plain password string
-   * @returns whether the password matches the complexity rules
+   * Evaluates every complexity rule against `password` and aggregates the
+   * result. `match: true` means the password is acceptable.
    */
-  public async matchPasswordComplexityRules(password: string) {
-    const result = await Promise.all(this.policy.passwordComplexityRules.map((rule) => rule.check(password)))
-    const failed = result.filter((r) => r.success === false)
-    if (failed.length) {
-      return {
-        match: false as const,
-        errors: failed.map((f) => f.success === false && { message: f.message, rule: f.rule }) as Array<{
-          message: string
-          rule: string
-        }>,
-      }
-    }
+  matchPasswordComplexityRules(password: string): Promise<PasswordComplexityMatch | PasswordComplexityMismatch>
+  /**
+   * Returns `true` when `credential.creationDate` plus
+   * `policy.passwordExpirationDays` is in the past. Always `false` when the
+   * policy sets `passwordExpirationDays` to `0`.
+   */
+  hasPasswordExpired(credential: PasswordCredential): boolean
+  /**
+   * Returns `true` when `token.createdAt` plus
+   * `policy.resetTokenExpirationSeconds` is in the past. Always `false`
+   * when the policy sets `resetTokenExpirationSeconds` to `0`.
+   */
+  hasTokenExpired(token: PasswordResetToken): boolean
+}
 
-    return {
-      match: true as const,
-    }
-  }
+const addDays = (base: Date, days: number): Date => {
+  const result = new Date(base)
+  result.setDate(result.getDate() + days)
+  return result
+}
 
-  public hasPasswordExpired(credential: PasswordCredential) {
-    if (!this.policy.passwordExpirationDays) {
-      return false
-    }
-    const credentialExpiration = new Date(credential.creationDate)
-    credentialExpiration.setDate(credentialExpiration.getDate() + this.policy.passwordExpirationDays)
-    const now = new Date()
-    return now > credentialExpiration
-  }
+const addSeconds = (base: Date, seconds: number): Date => {
+  const result = new Date(base)
+  result.setSeconds(result.getSeconds() + seconds)
+  return result
+}
 
-  public hasTokenExpired(token: PasswordResetToken) {
-    if (!this.policy.resetTokenExpirationSeconds) {
-      return false
+/**
+ * DI token for the singleton {@link SecurityPolicyManager}. Resolves the
+ * current {@link SecurityPolicy} once and closes over it for the lifetime
+ * of the owning injector.
+ */
+export const SecurityPolicyManager: Token<SecurityPolicyManager, 'singleton'> = defineService({
+  name: 'furystack/security/SecurityPolicyManager',
+  lifetime: 'singleton',
+  factory: ({ inject }): SecurityPolicyManager => {
+    const policy = inject(SecurityPolicy)
+    return {
+      policy,
+      matchPasswordComplexityRules: async (password) => {
+        const outcomes = await Promise.all(policy.passwordComplexityRules.map((rule) => rule.check(password)))
+        const failed = outcomes.filter((outcome) => outcome.success === false)
+        if (failed.length === 0) {
+          return { match: true }
+        }
+        return {
+          match: false,
+          errors: failed.map((outcome) =>
+            outcome.success === false ? { message: outcome.message, rule: outcome.rule } : { message: '', rule: '' },
+          ),
+        }
+      },
+      hasPasswordExpired: (credential) => {
+        if (!policy.passwordExpirationDays) {
+          return false
+        }
+        const expiration = addDays(new Date(credential.creationDate), policy.passwordExpirationDays)
+        return new Date() > expiration
+      },
+      hasTokenExpired: (token) => {
+        if (!policy.resetTokenExpirationSeconds) {
+          return false
+        }
+        const expiration = addSeconds(new Date(token.createdAt), policy.resetTokenExpirationSeconds)
+        return new Date() > expiration
+      },
     }
-    const tokenExpiration = new Date(token.createdAt)
-    tokenExpiration.setSeconds(tokenExpiration.getSeconds() + this.policy.resetTokenExpirationSeconds)
-    const now = new Date()
-    return now > tokenExpiration
-  }
-
-  @Injected(SecurityPolicy)
-  declare public readonly policy: SecurityPolicy
-}
+  },
+})

package/src/security-policy.ts

@@ -1,33 +1,65 @@
-import type { Constructable } from '@furystack/inject'
-import { Injectable } from '@furystack/inject'
+import { defineService, type Token } from '@furystack/inject'
 import { CryptoPasswordHasher } from './crypto-password-hasher.js'
 import type { PasswordComplexityRule } from './models/password-complexity-rule.js'
 import type { PasswordHasher } from './password-hasher.js'
 
-@Injectable({ lifetime: 'singleton' })
-export class SecurityPolicy {
+/**
+ * Application-wide policy that governs password hashing, complexity rules,
+ * expiration and second-factor requirements.
+ *
+ * The default policy shipped by `@furystack/security` uses
+ * {@link CryptoPasswordHasher}, enforces no complexity rules, disables
+ * password and reset-token expiration by default and does not require
+ * second factor authentication. Override via {@link usePasswordPolicy}.
+ */
+export type SecurityPolicy = {
   /**
-   * A Hasher instance for password hash generation
+   * Token resolving to the {@link PasswordHasher} used for generating and
+   * verifying password credentials.
    */
-  hasher: Constructable<PasswordHasher> = CryptoPasswordHasher
-
+  hasher: Token<PasswordHasher, 'singleton'>
   /**
-   * Array of password complexity rules to apply
+   * Ordered list of password complexity rules applied to every new or
+   * changed password.
    */
-  passwordComplexityRules: PasswordComplexityRule[] = []
-
+  passwordComplexityRules: PasswordComplexityRule[]
   /**
-   * The password expiration in days
+   * Number of days after which a stored password credential is considered
+   * expired. `0` disables expiration entirely.
    */
-  passwordExpirationDays = 0
-
+  passwordExpirationDays: number
   /**
-   * Defines if the login needs a second factor authentication
+   * Second-factor authentication policy. `'always'` forces a second factor
+   * on every login; `'never'` disables it. Trusted-device-aware policies
+   * are not yet implemented.
    */
-  requireSecondFactor: 'never' | 'always' = 'never' // TODO - Challenge based on trusted devices
-
+  requireSecondFactor: 'never' | 'always'
   /**
-   * The Password Reset Token expiration in seconds
+   * Lifetime of a password reset token in seconds.
    */
-  resetTokenExpirationSeconds = 15
+  resetTokenExpirationSeconds: number
 }
+
+/**
+ * Returns a fresh copy of the default {@link SecurityPolicy}. Useful as a
+ * starting point for `Object.assign`-style overrides or spec fixtures.
+ */
+export const defaultSecurityPolicy = (): SecurityPolicy => ({
+  hasher: CryptoPasswordHasher,
+  passwordComplexityRules: [],
+  passwordExpirationDays: 0,
+  requireSecondFactor: 'never',
+  resetTokenExpirationSeconds: 15,
+})
+
+/**
+ * DI token that resolves the current {@link SecurityPolicy}. Rebind this
+ * token via {@link usePasswordPolicy} (preferred) or directly through
+ * {@link Injector.bind} to customise the policy per-application or
+ * per-scope.
+ */
+export const SecurityPolicy: Token<SecurityPolicy, 'singleton'> = defineService({
+  name: 'furystack/security/SecurityPolicy',
+  lifetime: 'singleton',
+  factory: () => defaultSecurityPolicy(),
+})