@resq-systems/security 1.0.0

package/README.md

@@ -0,0 +1,280 @@
+<!--
+  Copyright 2026 ResQ Systems, Inc.
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+-->
+
+# @resq-systems/security
+
+[![npm](https://img.shields.io/npm/v/%40resq-systems%2Fsecurity?style=flat-square)](https://www.npmjs.com/package/@resq-systems/security)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue?style=flat-square)](../../LICENSE.md)
+
+> Encryption, threat detection, input validation, PII sanitization, and Effect Schema validators.
+
+## Installation
+
+```bash
+bun add @resq-systems/security effect
+```
+
+Peer dependency: `effect`. Uses Node.js `crypto` module for encryption.
+
+## Quick Start
+
+```ts
+import { encryptData, decryptData, isSafeInput, escapeHtml, redactPII } from "@resq-systems/security";
+
+// Encrypt/decrypt
+const encrypted = await encryptData("sensitive", "my-secret-key");
+const decrypted = await decryptData(encrypted, "my-secret-key");
+
+// Validate input
+if (!isSafeInput(userInput)) {
+  return new Response("Invalid input", { status: 400 });
+}
+
+// Sanitize for display
+const safe = escapeHtml('<script>alert("xss")</script>');
+
+// Redact PII for logging
+const clean = redactPII("Email: john@example.com, SSN: 123-45-6789");
+// "Email: [EMAIL], SSN: [SSN]"
+```
+
+## API Reference
+
+### Encryption (`crypto.ts`)
+
+#### `encryptData(plaintext, encryptionKey): Promise<string>`
+
+Encrypts data using AES-256-GCM with scrypt key derivation.
+
+- **plaintext** (`string`) -- data to encrypt.
+- **encryptionKey** (`string`) -- encryption key/password.
+- Returns base64 string containing `salt:iv:authTag:ciphertext`.
+
+#### `decryptData(encryptedData, encryptionKey): Promise<string>`
+
+Decrypts data produced by `encryptData`.
+
+- **encryptedData** (`string`) -- base64-encoded encrypted data.
+- **encryptionKey** (`string`) -- same key used for encryption.
+- Returns the original plaintext string.
+
+#### `hashData(data): string`
+
+Hashes data using SHA-256. Non-reversible.
+
+- Returns hex-encoded hash string.
+
+#### `generateSecureToken(length?): string`
+
+Generates a cryptographically secure random token.
+
+- **length** (`number`, default `32`) -- byte length.
+- Returns hex string (2x the byte length).
+
+#### `maskPII(data): string`
+
+Masks a string, showing first 2 and last 2 characters (e.g. `"Al****ce"`). Returns `"****"` for strings <= 4 chars.
+
+#### `maskEmail(email): string`
+
+Masks email local part (e.g. `"j***n@example.com"`).
+
+#### `sanitizeForLogging(obj, sensitiveFields?): Partial<T>`
+
+Recursively redacts sensitive fields from an object for safe logging.
+
+- **sensitiveFields** (`string[]`, default: `["password", "passwordHash", "token", "secret", "twoFactorSecret", "apiKey"]`)
+- Email fields are automatically masked.
+
+```ts
+sanitizeForLogging({ password: "secret", email: "john@example.com", name: "John" });
+// { password: "[REDACTED]", email: "j***n@example.com", name: "John" }
+```
+
+### Threat Detection (`validators.ts`)
+
+#### `detectThreatPatterns(input, config?): ThreatDetectionResult`
+
+Runs all configured detectors on input.
+
+- Returns `{ isSafe: boolean, threats: ThreatFinding[] }`.
+
+| Config Option | Type | Default | Description |
+|---------------|------|---------|-------------|
+| `checkXSS` | `boolean` | `true` | Detect script injection, event handlers |
+| `checkSQLInjection` | `boolean` | `true` | Detect UNION, DROP, stacked queries |
+| `checkNoSQLInjection` | `boolean` | `true` | Detect MongoDB operators |
+| `checkCommandInjection` | `boolean` | `false` | Detect shell commands (can cause false positives) |
+| `checkPathTraversal` | `boolean` | `true` | Detect `../`, `%2e%2e`, null bytes |
+| `checkHomoglyphs` | `boolean` | `true` | Detect Unicode lookalike characters |
+
+#### `isSafeInput(input, config?): boolean`
+
+Quick check returning `true` if no threats are detected.
+
+#### Individual Detectors
+
+Each returns `ThreatFinding[]`:
+
+| Function | Detects |
+|----------|---------|
+| `containsXSSPatterns(input)` | Script tags, event handlers, `javascript:` URIs, `eval()` |
+| `containsSQLInjection(input)` | UNION SELECT, DROP TABLE, `1=1`, SLEEP, stacked queries |
+| `containsNoSQLInjection(input)` | MongoDB operators (`$gt`, `$where`, `$function`) |
+| `containsCommandInjection(input)` | Command substitution, piped shells |
+| `containsPathTraversal(input)` | Directory traversal, null bytes, sensitive paths |
+| `containsHomoglyphs(input)` | Cyrillic/Greek lookalike characters |
+
+#### `sanitizeForDisplay(input): string`
+
+Escapes HTML entities (`<`, `>`, `&`, `"`, `'`, `/`) for safe rendering.
+
+#### `normalizeUnicode(input): string`
+
+Normalizes to NFC form and replaces known homoglyphs with ASCII equivalents.
+
+#### `validateSafeText(input): boolean`
+
+Validates text is safe from all attack patterns. For use as a schema refinement.
+
+#### `validateSafeName(input): boolean`
+
+Validates a name field -- allows international characters but blocks injection patterns.
+
+#### `validateSafeEmail(input): boolean`
+
+Validates email format and checks for injection patterns.
+
+#### `getThreatErrorMessage(result): string`
+
+Returns a human-readable error message for a threat detection result.
+
+### Sanitization (`sanitize.ts`)
+
+#### `escapeHtml(text): string`
+
+Escapes `&`, `<`, `>`, `"`, `'` to HTML entities.
+
+```ts
+escapeHtml('<img onerror="alert(1)">'); // "&lt;img onerror=&quot;alert(1)&quot;&gt;"
+```
+
+#### `sanitizeUrl(url, allowedProtocols?): string`
+
+Validates and returns a safe URL; returns empty string if unsafe.
+
+- **allowedProtocols** (`string[]`, default: `["http:", "https:", "mailto:"]`).
+- Blocks `javascript:`, `data:` URIs.
+
+#### `sanitizeUrlEffect(url, allowedProtocols?): Exit<string, unknown>`
+
+Effect-based version returning an `Exit`.
+
+#### `validateUserInput(input, maxLength?, allowHtml?): string`
+
+Strips HTML tags, normalizes whitespace, removes dangerous patterns, and truncates.
+
+- **maxLength** (`number`, default `500`).
+- **allowHtml** (`boolean`, default `false`).
+
+#### `validateUserInputEffect(input, options?): Exit<string, unknown>`
+
+Effect-based version with full options.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `maxLength` | `number` | `500` | Max output length |
+| `allowHtml` | `boolean` | `false` | Preserve HTML tags |
+| `allowNewlines` | `boolean` | `false` | Preserve newlines |
+| `trimWhitespace` | `boolean` | `true` | Trim leading/trailing whitespace |
+
+#### `sanitizeJson<T>(jsonString): T | null`
+
+Safely parses JSON with prototype pollution protection. Removes `__proto__`, `constructor`, `prototype` keys.
+
+#### `parseJsonWithSchema<A>(jsonString, schema): Option<A>`
+
+Parses JSON with Effect Schema validation and prototype pollution protection. Returns `Option.some(value)` or `Option.none()`.
+
+```ts
+const UserSchema = Schema.Struct({ name: Schema.String, age: Schema.Number });
+const user = parseJsonWithSchema('{"name":"John","age":30}', UserSchema);
+// Option.some({ name: "John", age: 30 })
+```
+
+#### `stripAnsi(text): string`
+
+Removes ANSI escape codes from strings.
+
+#### `redactPII(text, options?): string`
+
+Replaces PII patterns with redaction markers.
+
+| Option | Type | Default | Marker |
+|--------|------|---------|--------|
+| `redactEmails` | `boolean` | `true` | `[EMAIL]` |
+| `redactPhones` | `boolean` | `true` | `[PHONE]` |
+| `redactSSN` | `boolean` | `true` | `[SSN]` |
+| `redactCreditCards` | `boolean` | `true` | `[CREDIT_CARD]` |
+| `redactIPs` | `boolean` | `true` | `[IP_ADDRESS]` |
+| `customPatterns` | `Array<{ pattern, replacement }>` | `[]` | custom |
+
+#### `safeStringify(obj, sensitiveKeys?, indent?): string`
+
+JSON.stringify with automatic redaction of sensitive keys.
+
+- **sensitiveKeys** (`string[]`, default: `["password", "token", "apiKey", "secret", "authorization", "cookie", "ssn", "creditCard"]`).
+
+### Validation Helpers
+
+| Function | Description |
+|----------|-------------|
+| `isValidEmail(email)` | Validates email format |
+| `isValidPhone(phone)` | Validates US phone format |
+| `isValidSSN(ssn)` | Validates US SSN format |
+| `isValidUrl(url)` | Validates safe URL |
+
+### Effect Schemas
+
+Exported for runtime validation: `SafeUrlSchema`, `EmailSchema`, `PhoneNumberSchema`, `SSNSchema`, `CreditCardSchema`, `IPv4Schema`, `SanitizedStringSchema`, `UrlProtocolSchema`, `PIIRedactionOptionsSchema`, `UserInputOptionsSchema`.
+
+### Types
+
+Exported types: `ThreatDetectionResult`, `ThreatFinding`, `ThreatType`, `ThreatDetectionConfig`, `PIIRedactionOptions`, `UserInputOptions`, `SafeUrl`, `Email`, `PhoneNumber`, `SSN`, `CreditCard`, `IPv4`, `UrlProtocol`.
+
+## Prerequisites
+
+- **Runtime**: Bun 1.1+ or Node.js 20+
+- **Peer Dependencies**: `effect` (v4.0.0-beta.93+)
+
+## Configuration
+
+- **Crypto Key**: Ensure `ENCRYPTION_KEY` is set for cryptographic modules (must be a valid hex string of proper bit length).
+
+## Testing
+
+```sh
+bun --filter @resq-systems/security test
+```
+
+## Troubleshooting
+
+- **Strict JSON parsing error**: Stricter `ts-reset` settings type `JSON.parse` as `unknown`. Use the provided `sanitizeJson` / `parseJsonWithSchema` wrapper helpers to cast to safe formats.
+
+
+## License
+
+Apache-2.0

package/lib/crypto.d.mts

@@ -0,0 +1,195 @@
+import { Brand, PositiveInt } from "@resq-systems/types";
+
+//#region src/crypto.d.ts
+/**
+ * Base64 AES-256-GCM payload produced by {@link encryptData} — the
+ * `salt | iv | authTag | ciphertext` envelope. Only {@link decryptData}
+ * should consume a value of this type; read one back from storage through
+ * {@link toCiphertext}.
+ */
+type Ciphertext = Brand<string, "Ciphertext">;
+/**
+ * A secret accepted by {@link encryptData}/{@link decryptData} as the
+ * scrypt password. Mint one at the boundary where the secret enters the
+ * process (typically from `process.env`) via {@link toEncryptionKey}.
+ */
+type EncryptionKey = Brand<string, "EncryptionKey">;
+/** Cryptographically random hex token minted by {@link generateSecureToken}. */
+type SecureToken = Brand<string, "SecureToken">;
+/** Lowercase 64-char SHA-256 hex digest produced by {@link hashData}. */
+type Sha256Hex = Brand<string, "Sha256Hex">;
+/** A PII string masked for safe logging by {@link maskPII}/{@link maskEmail}. */
+type Masked = Brand<string, "Masked">;
+/** Type guard: `true` when `value` is a usable {@link EncryptionKey}. */
+declare const isEncryptionKey: (value: string) => value is Brand<string, "EncryptionKey">;
+/** Assert `value` is a non-empty secret and brand it, throwing otherwise. */
+declare const toEncryptionKey: (value: string) => Brand<string, "EncryptionKey">;
+/** Return `value` branded as an {@link EncryptionKey}, or `null` when empty. */
+declare const coerceEncryptionKey: (value: string) => Brand<string, "EncryptionKey">;
+/** Brand `value` as an {@link EncryptionKey} without checking. */
+declare const unsafeEncryptionKey: (value: string) => Brand<string, "EncryptionKey">;
+/** Type guard: `true` when `value` is a well-formed {@link Ciphertext} envelope. */
+declare const isCiphertext: (value: string) => value is Brand<string, "Ciphertext">;
+/** Assert `value` is a well-formed envelope and brand it, throwing otherwise. */
+declare const toCiphertext: (value: string) => Brand<string, "Ciphertext">;
+/** Return `value` branded as a {@link Ciphertext}, or `null` when malformed. */
+declare const coerceCiphertext: (value: string) => Brand<string, "Ciphertext">;
+/** Brand `value` as a {@link Ciphertext} without checking. */
+declare const unsafeCiphertext: (value: string) => Brand<string, "Ciphertext">;
+/**
+ * Encrypt a UTF-8 string with AES-256-GCM authenticated encryption.
+ *
+ * Each call generates a fresh random salt and IV — the same plaintext
+ * encrypted twice with the same `encryptionKey` produces different
+ * ciphertexts, which is the property you want for at-rest encryption.
+ *
+ * Output layout (base64-encoded): `salt(32) | iv(16) | authTag(16) | ciphertext(*)`.
+ * The companion {@link decryptData} understands this layout.
+ *
+ * @param plaintext - UTF-8 string to encrypt.
+ * @param encryptionKey - Caller-supplied secret. Treated as a password
+ *   and stretched into a 256-bit AES key via scrypt; can be any length,
+ *   though a high-entropy secret (≥ 32 bytes) is strongly preferred.
+ *
+ * @returns A self-contained base64 string. Store or transmit verbatim;
+ *   the salt/IV are recovered on decryption.
+ *
+ * @throws From the underlying Node crypto primitives if `encryptionKey`
+ *   is empty or scrypt fails.
+ *
+ * @compliance NIST 800-53 SC-28 (Protection of Information at Rest),
+ *   SC-13 (Cryptographic Protection).
+ *
+ * @example
+ * ```ts
+ * const ct = await encryptData("user@example.com", process.env.PII_KEY!);
+ * await db.users.update(id, { email: ct });
+ * ```
+ */
+declare function encryptData(plaintext: string, encryptionKey: EncryptionKey): Promise<Ciphertext>;
+/**
+ * Reverse {@link encryptData}. Verifies the GCM authentication tag
+ * before returning plaintext — tampered ciphertexts throw.
+ *
+ * @param encryptedData - Base64 string produced by {@link encryptData}.
+ * @param encryptionKey - Same key/password used to encrypt. Wrong keys
+ *   throw an "Unsupported state or unable to authenticate data" error
+ *   from Node — the authenticated tag failure is indistinguishable from
+ *   tampering, by design.
+ *
+ * @returns The original UTF-8 plaintext.
+ *
+ * @throws Error if the tag does not verify (wrong key, modified
+ *   ciphertext, truncated payload). Catch this and treat it as a
+ *   security event, not a recoverable error.
+ *
+ * @example
+ * ```ts
+ * const plaintext = await decryptData(stored, process.env.PII_KEY!);
+ * ```
+ */
+declare function decryptData(encryptedData: Ciphertext, encryptionKey: EncryptionKey): Promise<string>;
+/**
+ * Compute a SHA-256 digest of a UTF-8 string and return it as lowercase
+ * hex.
+ *
+ * **Not for password storage.** SHA-256 is fast by design — use a
+ * deliberately slow KDF (`bcrypt`, `argon2`, or `scrypt`) for
+ * password-equivalent material. This helper is intended for
+ * non-reversible identifiers, content hashes, and idempotency keys.
+ *
+ * @param data - UTF-8 input.
+ * @returns 64-character lowercase hex digest.
+ *
+ * @example
+ * ```ts
+ * hashData("hello"); // → "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"
+ * ```
+ */
+declare function hashData(data: string): Sha256Hex;
+/**
+ * Generate a cryptographically random hex token suitable for session
+ * IDs, password-reset tokens, CSRF tokens, and similar single-use
+ * secrets.
+ *
+ * @param length - Number of random *bytes* to draw as a {@link PositiveInt}
+ *   (the returned hex string is twice as long). Default `32` ⇒ 64-char hex
+ *   / 256 bits of entropy. Construct non-default lengths with `toPositiveInt`
+ *   so zero-byte and negative lengths are unrepresentable.
+ * @returns A {@link SecureToken}: lowercase hex string of length `length * 2`.
+ *
+ * @example
+ * ```ts
+ * import { toPositiveInt } from "@resq-systems/types";
+ * generateSecureToken();                 // 64-char hex (256-bit entropy)
+ * generateSecureToken(toPositiveInt(16)); // 32-char hex (128-bit entropy)
+ * ```
+ */
+declare function generateSecureToken(length?: PositiveInt): SecureToken;
+/**
+ * Mask an arbitrary PII string for safe logging — keeps the first two
+ * and last two characters and replaces everything in between with
+ * asterisks. Strings of length ≤ 4 are fully masked as `"****"`.
+ *
+ * @param data - Raw PII string.
+ * @returns Masked representation safe for logs.
+ *
+ * @example
+ * ```ts
+ * maskPII("4242424242424242"); // → "42************42"
+ * maskPII("AB12");              // → "****"
+ * ```
+ */
+declare function maskPII(data: string): Masked;
+/**
+ * Mask an email address while preserving the domain — useful for
+ * deduplication and support workflows where the domain is non-PII but
+ * the local part identifies the user.
+ *
+ * @param email - Full email. Falls back to {@link maskPII} if the input
+ *   does not contain a valid `local@domain` shape.
+ * @returns Masked email; e.g. `"j*****e@example.com"`.
+ *
+ * @example
+ * ```ts
+ * maskEmail("jane@example.com"); // → "j**e@example.com"
+ * maskEmail("ab@example.com");   // → "**@example.com"
+ * maskEmail("not-an-email");     // → "no********il" (maskPII fallback)
+ * ```
+ */
+declare function maskEmail(email: string): Masked;
+/**
+ * Recursively shallow-copy an object, replacing any field whose key
+ * contains a sensitive substring (case-insensitive) with `[REDACTED]`,
+ * and masking string fields whose key contains `"email"` via
+ * {@link maskEmail}.
+ *
+ * Designed for log structures — preserves shape so log queries continue
+ * to work, but ensures secrets and identifiers don't leak. Use as a
+ * defensive layer **before** writing structured log lines.
+ *
+ * @param obj - Object to sanitize. Original is not mutated.
+ * @param sensitiveFields - Substring allow-list. Defaults to
+ *   `["password", "passwordHash", "token", "secret",
+ *   "twoFactorSecret", "apiKey"]`. Substrings match anywhere in the
+ *   key, e.g. `"token"` matches `"refreshToken"` and `"id_token"`.
+ *
+ * @returns A new object with sensitive fields redacted and emails
+ *   masked. Nested objects are recursed; arrays and primitives pass
+ *   through unchanged.
+ *
+ * @example
+ * ```ts
+ * sanitizeForLogging({
+ *   id: 1,
+ *   email: "u@x.com",
+ *   apiKey: "sk-...",
+ *   nested: { token: "..." },
+ * });
+ * // → { id: 1, email: "u@x.com" (masked), apiKey: "[REDACTED]", nested: { token: "[REDACTED]" } }
+ * ```
+ */
+declare function sanitizeForLogging(obj: Record<string, unknown>, sensitiveFields?: string[]): Record<string, unknown>;
+//#endregion
+export { Ciphertext, EncryptionKey, Masked, SecureToken, Sha256Hex, coerceCiphertext, coerceEncryptionKey, decryptData, encryptData, generateSecureToken, hashData, isCiphertext, isEncryptionKey, maskEmail, maskPII, sanitizeForLogging, toCiphertext, toEncryptionKey, unsafeCiphertext, unsafeEncryptionKey };
+//# sourceMappingURL=crypto.d.mts.map

package/lib/crypto.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.d.mts","names":[],"sources":["../src/crypto.ts"],"mappings":";;;;AA8FA;;;;;KAjCY,UAAA,GAAa,KAAA;;;;AAmCzB;;KA5BY,aAAA,GAAgB,KAAA;;KAGhB,WAAA,GAAc,KAAA;AA2B1B;AAAA,KAxBY,SAAA,GAAY,KAAA;;KAGZ,MAAA,GAAS,KAAA;;cAiBR,eAAA,GAAe,KAAA,aAAA,KAAA,IAAA,KAAA;;cAEf,eAAA,GAAe,KAAA,aAAA,KAAA;;cAEf,mBAAA,GAAmB,KAAA,aAAA,KAAA;AAgBhC;AAAA,cAda,mBAAA,GAAmB,KAAA,aAAA,KAAA;;cAcnB,YAAA,GAAY,KAAA,aAAA,KAAA,IAAA,KAAA;;cAEZ,YAAA,GAAY,KAAA,aAAA,KAAA;;cAEZ,gBAAA,GAAgB,KAAA,aAAA,KAAA;;cAEhB,gBAAA,GAAgB,KAAA,aAAA,KAAA;;;;;AAF7B;;;;;AAEA;;;;;AA8CA;;;;;;;;;;;;;;;AAqCA;iBArCsB,WAAA,CACrB,SAAA,UACA,aAAA,EAAe,aAAA,GACb,OAAA,CAAQ,UAAA;;;;;;;;;;;;;;AA0EX;;;;;AAsBA;;;iBA9DsB,WAAA,CACrB,aAAA,EAAe,UAAA,EACf,aAAA,EAAe,aAAA,GACb,OAAA;;;;;;AA6EH;;;;;AAyBA;;;;;AA2CA;;iBA5GgB,QAAA,CAAS,IAAA,WAAe,SAAA;;;;;;;;;;;;;;;;;;;iBAsBxB,mBAAA,CAAoB,MAAA,GAAQ,WAAA,GAAkC,WAAA;;;;;;;;;;;;;;;iBAkB9D,OAAA,CAAQ,IAAA,WAAe,MAAA;;;;;;;;;;;;;;;;;iBAyBvB,SAAA,CAAU,KAAA,WAAgB,MAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA2C1B,kBAAA,CACf,GAAA,EAAK,MAAA,mBACL,eAAA,cAQE,MAAA"}