first commit

docs/security-stack/security/security-codes/src/utils/luhn.md

@@ -0,0 +1,69 @@
+# luhn
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Implements the Luhn algorithm for credit-card number validation. The Luhn
+check is a widely-used checksum formula that can quickly determine whether a
+sequence of digits is plausibly a valid credit-card number, and is used here
+to reduce false-positive detections in the `credit-card` pattern module.
+
+## Features
+
+- Strips non-digit characters before validating, accepting space- or
+  dash-separated card number formats.
+- O(n) implementation with no allocations beyond the cleaned digit string.
+- Returns `false` immediately for inputs shorter than 2 digits.
+
+## Usage: Basic Example
+
+```ts
+import { luhnCheck } from '@suaveplan/security-codes/utils/luhn';
+
+luhnCheck('4532015112830366'); // true  — valid Visa test number
+luhnCheck('1234567890123456'); // false — fails Luhn
+```
+
+## Usage: Advanced Example
+
+```ts
+import { luhnCheck } from '@suaveplan/security-codes/utils/luhn';
+
+// Space-separated card numbers are handled transparently
+luhnCheck('4532 0151 1283 0366'); // true
+
+// Short or empty strings are safely rejected
+luhnCheck('');  // false
+luhnCheck('4'); // false
+```
+
+## API Reference
+
+### `luhnCheck(digits: string): boolean`
+
+| Parameter | Type | Description |
+|---|---|---|
+| `digits` | `string` | Raw digit string; non-digit chars are stripped before validation |
+
+Returns `true` when `digits` passes the Luhn checksum and contains at least
+two digit characters, `false` otherwise. Does not throw.
+
+## Implementation Notes
+
+The algorithm doubles every second digit from the right (starting at index
+`length - 2`). When doubling produces a value greater than 9, 9 is subtracted.
+All digits are summed; a total divisible by 10 indicates a valid number.
+
+This implementation intentionally avoids any dependency on built-in crypto or
+external libraries so that it can be used in both Node.js and browser
+environments without a polyfill.
+
+The Luhn check is used by the `credit-card` pattern module as a secondary gate
+after the initial regex match. A 16-digit string matching the card-number
+pattern but failing the Luhn check is discarded rather than reported, which
+significantly reduces false positives in documents containing order IDs,
+tracking numbers, or other long numeric strings. Note that Luhn validation
+confirms mathematical plausibility only — it does not verify that the card
+number has ever been issued or is currently active.