@furystack/security 7.0.9 → 8.0.1

package/esm/security-policy.js

@@ -1,35 +1,25 @@
-var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-};
-import { Injectable } from '@furystack/inject';
+import { defineService } from '@furystack/inject';
 import { CryptoPasswordHasher } from './crypto-password-hasher.js';
-let SecurityPolicy = class SecurityPolicy {
-    /**
-     * A Hasher instance for password hash generation
-     */
-    hasher = CryptoPasswordHasher;
-    /**
-     * Array of password complexity rules to apply
-     */
-    passwordComplexityRules = [];
-    /**
-     * The password expiration in days
-     */
-    passwordExpirationDays = 0;
-    /**
-     * Defines if the login needs a second factor authentication
-     */
-    requireSecondFactor = 'never'; // TODO - Challenge based on trusted devices
-    /**
-     * The Password Reset Token expiration in seconds
-     */
-    resetTokenExpirationSeconds = 15;
-};
-SecurityPolicy = __decorate([
-    Injectable({ lifetime: 'singleton' })
-], SecurityPolicy);
-export { SecurityPolicy };
+/**
+ * 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 = () => ({
+    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 = defineService({
+    name: 'furystack/security/SecurityPolicy',
+    lifetime: 'singleton',
+    factory: () => defaultSecurityPolicy(),
+});
 //# sourceMappingURL=security-policy.js.map

package/esm/security-policy.js.map

@@ -1 +1 @@
-{"version":3,"file":"security-policy.js","sourceRoot":"","sources":["../src/security-policy.ts"],"names":[],"mappings":";;;;;;AACA,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAC9C,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAA;AAK3D,IAAM,cAAc,GAApB,MAAM,cAAc;IACzB;;OAEG;IACH,MAAM,GAAkC,oBAAoB,CAAA;IAE5D;;OAEG;IACH,uBAAuB,GAA6B,EAAE,CAAA;IAEtD;;OAEG;IACH,sBAAsB,GAAG,CAAC,CAAA;IAE1B;;OAEG;IACH,mBAAmB,GAAuB,OAAO,CAAA,CAAC,4CAA4C;IAE9F;;OAEG;IACH,2BAA2B,GAAG,EAAE,CAAA;CACjC,CAAA;AAzBY,cAAc;IAD1B,UAAU,CAAC,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;GACzB,cAAc,CAyB1B"}
+{"version":3,"file":"security-policy.js","sourceRoot":"","sources":["../src/security-policy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAc,MAAM,mBAAmB,CAAA;AAC7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAA;AAyClE;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,GAAmB,EAAE,CAAC,CAAC;IAC1D,MAAM,EAAE,oBAAoB;IAC5B,uBAAuB,EAAE,EAAE;IAC3B,sBAAsB,EAAE,CAAC;IACzB,mBAAmB,EAAE,OAAO;IAC5B,2BAA2B,EAAE,EAAE;CAChC,CAAC,CAAA;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAuC,aAAa,CAAC;IAC9E,IAAI,EAAE,mCAAmC;IACzC,QAAQ,EAAE,WAAW;IACrB,OAAO,EAAE,GAAG,EAAE,CAAC,qBAAqB,EAAE;CACvC,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@furystack/security",
-  "version": "7.0.9",
+  "version": "8.0.1",
   "description": "Security, password management and authorization related stuff for FuryStack",
   "type": "module",
   "scripts": {
@@ -37,16 +37,16 @@
     "url": "https://github.com/furystack/furystack/issues"
   },
   "dependencies": {
-    "@furystack/core": "^16.0.4",
-    "@furystack/inject": "^12.0.36",
-    "@furystack/repository": "^10.1.11"
+    "@furystack/core": "^17.1.0",
+    "@furystack/inject": "^13.0.1",
+    "@furystack/repository": "^11.0.1"
   },
   "homepage": "https://github.com/furystack/furystack",
   "devDependencies": {
-    "@furystack/utils": "^8.2.5",
-    "@types/node": "^25.6.0",
+    "@furystack/utils": "^9.0.1",
+    "@types/node": "^25.9.1",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.4"
+    "vitest": "^4.1.7"
   },
   "engines": {
     "node": ">=22.0.0"

package/src/crypto-password-hasher.ts

@@ -1,44 +1,51 @@
-import { Injectable } from '@furystack/inject'
+import { defineService, type Token } from '@furystack/inject'
+import { pbkdf2, randomBytes } from 'crypto'
+import type { PasswordCheckResult } from './models/index.js'
 import type { PasswordHasher } from './password-hasher.js'
-import { randomBytes, pbkdf2 } from 'crypto'
-import type { PasswordCheckResult, PasswordCredential } from './models/index.js'
 
-@Injectable({ lifetime: 'singleton' })
-export class CryptoPasswordHasher implements PasswordHasher {
-  private readonly iterations = 1000
-  private readonly keylen = 64
+const ITERATIONS = 1000
+const KEY_LENGTH = 64
+const SALT_BYTES = 16
 
-  public async verifyCredential(
-    password: string,
-    { passwordHash, salt }: PasswordCredential,
-  ): Promise<PasswordCheckResult> {
-    const newHash = await new Promise((resolve, reject) =>
-      pbkdf2(password, salt, this.iterations, this.keylen, 'sha512', (err, key) =>
-        err ? reject(err) : resolve(key.toString('hex')),
-      ),
-    )
-    if (newHash === passwordHash) {
+const deriveHash = (password: string, salt: string): Promise<string> =>
+  new Promise<string>((resolve, reject) => {
+    pbkdf2(password, salt, ITERATIONS, KEY_LENGTH, 'sha512', (err, key) => {
+      if (err) {
+        reject(err)
+        return
+      }
+      resolve(key.toString('hex'))
+    })
+  })
+
+/**
+ * Default PBKDF2-based {@link PasswordHasher} implementation. Uses SHA-512
+ * with 1000 iterations and a 64-byte derived key length.
+ *
+ * Swap this token in {@link SecurityPolicy.hasher} to replace the hashing
+ * algorithm — for example with a stronger Argon2 implementation or a
+ * delegated hashing service.
+ */
+export const CryptoPasswordHasher: Token<PasswordHasher, 'singleton'> = defineService({
+  name: 'furystack/security/CryptoPasswordHasher',
+  lifetime: 'singleton',
+  factory: (): PasswordHasher => ({
+    verifyCredential: async (password, { passwordHash, salt }): Promise<PasswordCheckResult> => {
+      const candidate = await deriveHash(password, salt)
+      if (candidate === passwordHash) {
+        return { isValid: true }
+      }
+      return { isValid: false, reason: 'badUsernameOrPassword' }
+    },
+    createCredential: async (userName, password) => {
+      const salt = randomBytes(SALT_BYTES).toString('hex')
+      const passwordHash = await deriveHash(password, salt)
       return {
-        isValid: true,
+        userName,
+        salt,
+        passwordHash,
+        creationDate: new Date().toISOString(),
       }
-    }
-    return {
-      isValid: false,
-      reason: 'badUsernameOrPassword',
-    }
-  }
-  public async createCredential(userName: string, password: string) {
-    const salt = randomBytes(16).toString('hex')
-    const passwordHash = await new Promise<string>((resolve, reject) =>
-      pbkdf2(password, salt, this.iterations, this.keylen, 'sha512', (err, key) =>
-        err ? reject(err) : resolve(key.toString('hex')),
-      ),
-    )
-    return {
-      userName,
-      salt,
-      passwordHash,
-      creationDate: new Date().toISOString(),
-    }
-  }
-}
+    },
+  }),
+})

package/src/errors/password-complexity-error.ts

@@ -1,8 +1,11 @@
+import type { PasswordComplexityRule } from '../models/password-complexity-rule.js'
+
+/**
+ * Thrown by password-setting flows when the candidate password fails one or
+ * more configured {@link PasswordComplexityRule}s. `result` carries the
+ * per-rule failures so callers can render targeted user feedback.
+ */
 export class PasswordComplexityError extends Error {
-  /**
-   * @param result A detailed error result array
-   * @param message The Error message
-   */
   constructor(
     public readonly result: Array<{ message: string; rule: string }>,
     message?: string,

package/src/errors/unauthenticated-error.ts

@@ -1,4 +1,6 @@
 /**
- * Error that can be thrown if an authentication is required but not provided
+ * Thrown when credential verification fails: bad username/password, expired
+ * password, or expired/invalid reset token. REST handlers should map this
+ * to a 401 response.
  */
 export class UnauthenticatedError extends Error {}

package/src/helpers.ts

@@ -1,22 +1,34 @@
 import type { Injector } from '@furystack/inject'
-import { SecurityPolicy } from './security-policy.js'
+import { PasswordAuthenticator } from './password-authenticator.js'
+import { SecurityPolicyManager } from './security-policy-manager.js'
+import { defaultSecurityPolicy, SecurityPolicy } from './security-policy.js'
 
 /**
- * Sets up the @furystack/security with the provided settings.
+ * Rebinds the {@link SecurityPolicy} on the given injector with the default
+ * policy merged with `overrides`.
  *
- * **Prerequisite:** DataSets for `PasswordCredential` and `PasswordResetToken` must be registered
- * via `getRepository(injector).createDataSet()` before `PasswordAuthenticator` is instantiated,
- * as it resolves these DataSets through `@Injected`.
+ * Apply this at application setup before resolving any service that reads
+ * the policy — {@link PasswordAuthenticator}, {@link SecurityPolicyManager}
+ * or direct `injector.get(SecurityPolicy)` callers. Because those services
+ * capture the policy at resolve time, calling `usePasswordPolicy` after
+ * they have been resolved has no effect unless you also invalidate them.
  *
- * @param injector The Injector instance
- * @param policy The security policy to use
+ * **Prerequisite:** bind persistent implementations of
+ * `PasswordCredentialStore` and `PasswordResetTokenStore` before resolving
+ * {@link PasswordAuthenticator}. Their default factories throw on purpose
+ * so password data is never silently kept in-memory.
+ *
+ * @example
+ * ```ts
+ * usePasswordPolicy(injector, {
+ *   passwordExpirationDays: 90,
+ *   passwordComplexityRules: [createMinLengthComplexityRule(8)],
+ * })
+ * ```
  */
-export const usePasswordPolicy = (injector: Injector, policy?: Partial<SecurityPolicy>) => {
-  const plainPolicy = new SecurityPolicy()
-
-  if (policy) {
-    Object.assign(plainPolicy, policy)
-  }
-
-  injector.setExplicitInstance(plainPolicy, SecurityPolicy)
+export const usePasswordPolicy = (injector: Injector, overrides?: Partial<SecurityPolicy>): void => {
+  injector.bind(SecurityPolicy, () => ({ ...defaultSecurityPolicy(), ...overrides }))
+  injector.invalidate(SecurityPolicy)
+  injector.invalidate(SecurityPolicyManager)
+  injector.invalidate(PasswordAuthenticator)
 }

package/src/index.ts

@@ -1,9 +1,10 @@
 export * from './crypto-password-hasher.js'
 export * from './errors/index.js'
+export * from './helpers.js'
 export * from './models/index.js'
 export * from './password-authenticator.js'
 export * from './password-complexity-rules/index.js'
+export * from './password-credential-store.js'
 export * from './password-hasher.js'
 export * from './security-policy-manager.js'
-
-export * from './helpers.js'
+export * from './security-policy.js'

package/src/models/password-credential.ts

@@ -1,23 +1,13 @@
+import type { PasswordHasher } from '../password-hasher.js'
+
 /**
- * Entry that stores credential info for password login
+ * Persisted password credential. `passwordHash` and `salt` are produced by
+ * the configured {@link PasswordHasher}; `creationDate` (ISO 8601 string)
+ * is the source of truth for password-expiration policies.
  */
 export class PasswordCredential {
-  /**
-   * The unique name of the user
-   */
   declare userName: string
-  /**
-   * The hashed password value
-   */
   declare passwordHash: string
-
-  /**
-   * Salt value for password hashing // TODO
-   */
   declare salt: string
-
-  /**
-   * The Creation date in ISO String format
-   */
   declare creationDate: string
 }

package/src/models/password-reset-token.ts

@@ -1,14 +1,10 @@
+/**
+ * Single-use password reset token. `token` is the URL-safe identifier
+ * shared with the user (e.g. via email). `createdAt` (ISO 8601) is the
+ * expiration anchor honoured by `SecurityPolicyManager.hasTokenExpired`.
+ */
 export class PasswordResetToken {
-  /**
-   * The related user name
-   */
   declare userName: string
-  /**
-   * The Token value - should be some kind of generated UUID that can be included e.g. in URLs
-   */
   declare token: string
-  /**
-   * The creation date in an ISO datetime format
-   */
   declare createdAt: string
 }