typesecure 0.1.0 → 0.2.2

package/README.md

@@ -1,18 +1,29 @@
 # typesecure
 
-A focused TypeScript cryptography package that provides secure encryption and hashing utilities with strong typing and runtime validation using Zod.
+`typesecure` is a **classification-first security core** for TypeScript projects.
+
+Instead of starting with crypto primitives, it starts with what actually causes most security incidents in web apps: **data leaving the boundary it should never cross** (logs, analytics, error trackers, headers, client bundles, etc).
+
+You “type” your data as `public | pii | secret | token | credential`, and `typesecure` helps you **enforce** safe handling using TypeScript + runtime checks.
 
 ## Features
 
-- 🔐 **Strong Typing**: Built with TypeScript for complete type safety.
-- ✅ **Runtime Validation**: Uses Zod to validate inputs and ensure security.
-- 🔍 **Advanced Encryption**: AES encryption with multiple modes (CBC, CTR, GCM, ECB).
-- 🛡️ **Authenticated Encryption**: GCM mode for authenticated encryption with additional data (AAD).
-- 🔏 **Cryptographic Hashing**: SHA-256, SHA-512, SHA-3, and more.
-- 📝 **HMAC Signatures**: Create and verify message authentication codes.
-- ⏱️ **Timing-Safe Comparison**: Prevent timing attacks with constant-time string comparison.
-- 🚦 **Security Level Assessment**: Analyze and report the security level of encryption configurations.
-- 🔑 **Password Hashing**: PBKDF2 for secure password hashing with salt and configurable iterations.
+- **Classification types**: `PublicString`, `PIIString`, `SecretString`, `TokenString`, `CredentialString`.
+- **Runtime validation**: Zod-backed constructors (`secretText()`, `piiText()`, ...).
+- **Redaction**: `redact()` and `safeJsonStringify()` prevent secret/PII leakage.
+- **Policy enforcement**: `defaultPolicy()`, `assertAllowed()`, `audit()` help block unsafe crossings.
+
+## Good for / Use when
+
+- **You need to stop leaks early**: preventing secrets/PII from ending up in logs, analytics, error trackers, or client bundles.
+- **You want safe defaults**: making insecure behavior harder than secure behavior.
+- **You want guardrails at the boundary**: before logging, emitting telemetry, making network calls, or writing to storage.
+
+## Not a fit / Don’t use when
+
+- **You need a full security platform** (hosted policy registry, enterprise controls). `typesecure` is a library.
+- **You need production-grade crypto primitives**. Use well-reviewed, purpose-built libraries and treat crypto carefully.
+- **You only want compile-time types with zero runtime behavior**. `typesecure` deliberately includes runtime checks/redaction.
 
 ## Installation
 
@@ -29,113 +40,94 @@ pnpm add typesecure
 
 ## Usage
 
-### Encryption with Security Assessment
+### Classification-first data handling
 
 ```typescript
-import { encrypt, decrypt, generateKey, getSecurityLevel, SecurityLevel } from 'typesecure';
-
-// Generate a secure key
-const key = generateKey();
-
-// Encrypt data with GCM (authenticated encryption)
-const encrypted = encrypt('Sensitive information', key, {
-  mode: 'aes-gcm',
-  aad: 'Additional authenticated data' // Optional
-});
-
-// Decrypt data
-const decrypted = decrypt(encrypted, key, {
-  mode: 'aes-gcm',
-  aad: 'Additional authenticated data' // Must match encryption
-});
-
-// Assess security level of encryption options
-const securityLevel = getSecurityLevel({ mode: 'aes-cbc', padding: 'Pkcs7' });
-if (securityLevel === SecurityLevel.HIGH) {
-  console.log('Using high security encryption configuration');
-}
+import {
+  piiText,
+  secretText,
+  token,
+  publicText,
+  redact,
+  safeJsonStringify,
+  defaultPolicy,
+  assertAllowed,
+  policyLog,
+} from "typesecure";
+
+const userEmail = piiText("user@example.com");
+const sessionToken = token("abc.def.ghi");
+const dbPassword = secretText(process.env.DB_PASSWORD ?? "");
+
+// Redact before logging / serialization
+console.log(redact({ userEmail, sessionToken, dbPassword }));
+console.log(
+  safeJsonStringify({ userEmail, sessionToken, dbPassword }, undefined, 2),
+);
+
+// Enforce policy before a boundary crossing
+const policy = defaultPolicy();
+assertAllowed(policy, "network", { sessionToken }); // allowed
+// assertAllowed(policy, 'log', { dbPassword }); // throws
+
+// Safe logging helper with enforcement
+policyLog(policy, console, "info", publicText("login_ok"), { userEmail });
 ```
 
-### Secure Password Storage
+### Express / Next.js examples
 
 ```typescript
-import { hashPassword, verifyPassword } from 'typesecure';
-
-// Hash a password with PBKDF2
-const { hash, salt, params } = hashPassword('userPassword123', {
-  algorithm: 'pbkdf2',
-  iterations: 10000,
-  saltLength: 32,
-  keyLength: 64
-});
-
-// Store hash, salt, and params in your database
-
-// Later, verify the password
-const isValid = verifyPassword('userPassword123', hash, salt, params);
-```
-
-### Timing-Safe Comparison and Random Bytes Generation
-
-```typescript
-import { timingSafeEqual, generateRandomBytes } from 'typesecure';
-
-// Compare strings in constant time to prevent timing attacks
-const isEqual = timingSafeEqual(userProvidedToken, storedToken);
-
-// Generate cryptographically secure random bytes
-const randomBytes = generateRandomBytes(32, 'hex');
-```
-
-### Hashing and HMAC
-
-```typescript
-import { hash, verifyHash, hmac } from 'typesecure';
-
-// Create a hash
-const hashedValue = hash('data to hash', {
-  algorithm: 'sha256',
-  encoding: 'hex'
-});
-
-// Verify a hash
-const isMatch = verifyHash('data to hash', hashedValue, {
-  algorithm: 'sha256',
-  encoding: 'hex'
-});
-
-// Create an HMAC
-const signature = hmac('message', 'secret key', {
-  algorithm: 'sha256',
-  encoding: 'base64'
+// Express middleware example
+import {
+  safeLoggerAdapter,
+  defaultPolicy,
+  assertAllowed,
+  token,
+} from "typesecure";
+
+const log = safeLoggerAdapter(console);
+const policy = defaultPolicy();
+
+app.use((req, _res, next) => {
+  const auth = req.headers.authorization?.replace(/^Bearer\s+/i, "");
+  if (auth) {
+    const t = token(auth);
+    assertAllowed(policy, "network", { t });
+    log.info({ route: req.path, auth: t }); // will be redacted
+  }
+  next();
 });
 ```
 
 ## API Reference
 
-### Encryption
+### Classification
 
-- `encrypt(text: string, key: string, options?: Partial<EncryptionOptions>): string`
-- `decrypt(encryptedText: string, key: string, options?: Partial<EncryptionOptions>): string`
-- `generateKey(length?: number): string`
-- `getSecurityLevel(options: EncryptionOptions): SecurityLevel`
+- `publicText(value: string): PublicString`
+- `piiText(value: string): PIIString`
+- `secretText(value: string): SecretString`
+- `token(value: string): TokenString`
+- `credential(value: string): CredentialString`
+- `reveal(value): string` (intentionally explicit)
 
-### Secure Password Storage
+### Redaction
 
-- `hashPassword(password: string, options?: Partial<PasswordHashOptions>): { hash: string; salt: string; params: PasswordHashOptions }`
-- `verifyPassword(password: string, hash: string, salt: string, options?: Partial<PasswordHashOptions>): boolean`
-- `timingSafeEqual(a: string, b: string, options?: Partial<TimingSafeOptions>): boolean`
-- `generateRandomBytes(length?: number, encoding?: 'hex' | 'base64'): string`
+- `redact(value): value` (deep traversal)
+- `safeJsonStringify(value): string`
+- `safeLoggerAdapter(consoleLike)`
 
-### Hashing
+### Policy
 
-- `hash(input: string, options?: Partial<HashOptions>): string`
-- `verifyHash(input: string, hashedValue: string, options?: Partial<HashOptions>): boolean`
-- `hmac(input: string, key: string, options?: Partial<HashOptions>): string`
+- `defaultPolicy(): Policy`
+- `assertAllowed(policy, action, data): void`
+- `audit(policy, action, data): AuditEvent`
+- `policyLog(policy, logger, level, ...args): void`
 
 ## Security Considerations
 
-This package implements best practices for cryptographic operations, but remember that cryptography is complex. For production applications with high security requirements, consider:
+Security is as much about **preventing leaks** as it is about cryptographic correctness. `typesecure` focuses on preventing accidental secret/PII exposure across common boundaries.
+
+If you need cryptography for production-grade requirements, prefer well-reviewed primitives and consult a security professional. For production applications with high security requirements, consider:
 
 1. Consulting a security professional
 2. Using specialized security libraries
@@ -162,4 +154,4 @@ MIT © [Arvid Berndtsson](https://github.com/arvid-berndtsson)
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request. 
+Contributions are welcome! Please feel free to submit a Pull Request.

package/dist/index.d.mts

@@ -1,237 +1,116 @@
 import { z } from 'zod';
 
-declare const PasswordStrengthSchema: z.ZodObject<{
-    score: z.ZodNumber;
-    feedback: z.ZodObject<{
-        warning: z.ZodOptional<z.ZodString>;
-        suggestions: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    }, "strip", z.ZodTypeAny, {
-        warning?: string | undefined;
-        suggestions?: string[] | undefined;
-    }, {
-        warning?: string | undefined;
-        suggestions?: string[] | undefined;
-    }>;
-    isStrong: z.ZodBoolean;
-}, "strip", z.ZodTypeAny, {
-    score: number;
-    feedback: {
-        warning?: string | undefined;
-        suggestions?: string[] | undefined;
-    };
-    isStrong: boolean;
-}, {
-    score: number;
-    feedback: {
-        warning?: string | undefined;
-        suggestions?: string[] | undefined;
-    };
-    isStrong: boolean;
+type DataClassification = "public" | "pii" | "secret" | "token" | "credential";
+declare const TYPESECURE_SYMBOL: unique symbol;
+type Classified<K extends DataClassification, T> = Readonly<{
+    kind: K;
+    value: T;
+    [TYPESECURE_SYMBOL]: true;
 }>;
-type PasswordStrength = z.infer<typeof PasswordStrengthSchema>;
-declare const HashOptionsSchema: z.ZodObject<{
-    algorithm: z.ZodDefault<z.ZodEnum<["md5", "sha1", "sha256", "sha512", "sha3"]>>;
-    encoding: z.ZodDefault<z.ZodEnum<["hex", "base64"]>>;
-}, "strip", z.ZodTypeAny, {
-    algorithm: "md5" | "sha1" | "sha256" | "sha512" | "sha3";
-    encoding: "hex" | "base64";
-}, {
-    algorithm?: "md5" | "sha1" | "sha256" | "sha512" | "sha3" | undefined;
-    encoding?: "hex" | "base64" | undefined;
-}>;
-type HashOptions = z.infer<typeof HashOptionsSchema>;
-declare const PasswordHashOptionsSchema: z.ZodObject<{
-    algorithm: z.ZodDefault<z.ZodEnum<["pbkdf2", "argon2", "bcrypt"]>>;
-    iterations: z.ZodDefault<z.ZodNumber>;
-    saltLength: z.ZodDefault<z.ZodNumber>;
-    keyLength: z.ZodDefault<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    algorithm: "pbkdf2" | "argon2" | "bcrypt";
-    iterations: number;
-    saltLength: number;
-    keyLength: number;
-}, {
-    algorithm?: "pbkdf2" | "argon2" | "bcrypt" | undefined;
-    iterations?: number | undefined;
-    saltLength?: number | undefined;
-    keyLength?: number | undefined;
-}>;
-type PasswordHashOptions = z.infer<typeof PasswordHashOptionsSchema>;
-declare const TimingSafeOptionsSchema: z.ZodObject<{
-    encoding: z.ZodDefault<z.ZodEnum<["utf8", "hex", "base64"]>>;
-}, "strip", z.ZodTypeAny, {
-    encoding: "hex" | "base64" | "utf8";
-}, {
-    encoding?: "hex" | "base64" | "utf8" | undefined;
-}>;
-type TimingSafeOptions = z.infer<typeof TimingSafeOptionsSchema>;
-declare const EncryptionOptionsSchema: z.ZodObject<{
-    mode: z.ZodDefault<z.ZodEnum<["aes-cbc", "aes-ctr", "aes-ecb", "aes-gcm"]>>;
-    padding: z.ZodDefault<z.ZodEnum<["Pkcs7", "NoPadding", "ZeroPadding"]>>;
-    iv: z.ZodOptional<z.ZodString>;
-    authTag: z.ZodOptional<z.ZodString>;
-    aad: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    mode: "aes-cbc" | "aes-ctr" | "aes-ecb" | "aes-gcm";
-    padding: "Pkcs7" | "NoPadding" | "ZeroPadding";
-    iv?: string | undefined;
-    authTag?: string | undefined;
-    aad?: string | undefined;
-}, {
-    mode?: "aes-cbc" | "aes-ctr" | "aes-ecb" | "aes-gcm" | undefined;
-    padding?: "Pkcs7" | "NoPadding" | "ZeroPadding" | undefined;
-    iv?: string | undefined;
-    authTag?: string | undefined;
-    aad?: string | undefined;
-}>;
-type EncryptionOptions = z.infer<typeof EncryptionOptionsSchema>;
-declare const ConfigSchema: z.ZodObject<{
-    minimumPasswordLength: z.ZodDefault<z.ZodNumber>;
-    requireNumbers: z.ZodDefault<z.ZodBoolean>;
-    requireSymbols: z.ZodDefault<z.ZodBoolean>;
-    requireUppercase: z.ZodDefault<z.ZodBoolean>;
-    requireLowercase: z.ZodDefault<z.ZodBoolean>;
-}, "strip", z.ZodTypeAny, {
-    minimumPasswordLength: number;
-    requireNumbers: boolean;
-    requireSymbols: boolean;
-    requireUppercase: boolean;
-    requireLowercase: boolean;
-}, {
-    minimumPasswordLength?: number | undefined;
-    requireNumbers?: boolean | undefined;
-    requireSymbols?: boolean | undefined;
-    requireUppercase?: boolean | undefined;
-    requireLowercase?: boolean | undefined;
-}>;
-type Config = z.infer<typeof ConfigSchema>;
+type PublicString = Classified<"public", string>;
+type PIIString = Classified<"pii", string>;
+type SecretString = Classified<"secret", string>;
+type TokenString = Classified<"token", string>;
+type CredentialString = Classified<"credential", string>;
+declare function isClassified(value: unknown): value is Classified<DataClassification, unknown>;
+declare function classificationOf(value: unknown): DataClassification | undefined;
+/**
+ * Intentionally explicit: use this when you need the raw string (e.g. building an HTTP header).
+ * Prefer passing classified values to safe sinks/policies instead of revealing early.
+ */
+declare function reveal<T>(value: Classified<DataClassification, T>): T;
+declare const PublicStringSchema: z.ZodEffects<z.ZodString, Readonly<{
+    kind: "public";
+    value: string;
+    [TYPESECURE_SYMBOL]: true;
+}>, string>;
+declare const PIIStringSchema: z.ZodEffects<z.ZodString, Readonly<{
+    kind: "pii";
+    value: string;
+    [TYPESECURE_SYMBOL]: true;
+}>, string>;
+declare const SecretStringSchema: z.ZodEffects<z.ZodString, Readonly<{
+    kind: "secret";
+    value: string;
+    [TYPESECURE_SYMBOL]: true;
+}>, string>;
+declare const TokenStringSchema: z.ZodEffects<z.ZodString, Readonly<{
+    kind: "token";
+    value: string;
+    [TYPESECURE_SYMBOL]: true;
+}>, string>;
+declare const CredentialStringSchema: z.ZodEffects<z.ZodString, Readonly<{
+    kind: "credential";
+    value: string;
+    [TYPESECURE_SYMBOL]: true;
+}>, string>;
+declare function publicText(value: string): PublicString;
+declare function piiText(value: string): PIIString;
+declare function secretText(value: string): SecretString;
+declare function token(value: string): TokenString;
+declare function credential(value: string): CredentialString;
 
-/**
- * Creates a hash of the input string using the specified algorithm
- * @param input - The string to hash
- * @param options - Hash options
- * @returns The hashed string
- */
-declare function hash(input: string, options?: Partial<HashOptions>): string;
-/**
- * Verifies if an input matches a previously hashed value
- * @param input - The plain text to verify
- * @param hashedValue - The hashed value to compare against
- * @param options - Hash options
- * @returns True if the input matches the hash, false otherwise
- */
-declare function verifyHash(input: string, hashedValue: string, options?: Partial<HashOptions>): boolean;
-/**
- * Creates a HMAC (Hash-based Message Authentication Code) of the input
- * @param input - The input message
- * @param key - The secret key
- * @param options - Hash options
- * @returns The HMAC signature
- */
-declare function hmac(input: string, key: string, options?: Partial<HashOptions>): string;
-/**
- * Performs a secure password hashing using PBKDF2 (default), Argon2, or bcrypt simulation
- * Note: This is a simplified implementation. For production, consider using a specialized library
- * @param password - The password to hash
- * @param options - Password hash options
- * @returns An object containing the hash, salt, and parameters
- */
-declare function hashPassword(password: string, options?: Partial<PasswordHashOptions>): {
-    hash: string;
-    salt: string;
-    params: PasswordHashOptions;
+type RedactOptions = Readonly<{
+    /**
+     * If true, redact values for suspicious keys even if they aren't classified.
+     * Defaults to true.
+     */
+    guessByKey?: boolean;
+    /**
+     * Placeholder format for redacted values.
+     * Defaults to "[REDACTED:<kind>]".
+     */
+    placeholder?: (kind: DataClassification | "unknown") => string;
+    /**
+     * Max depth to traverse to avoid pathological structures.
+     * Defaults to 25.
+     */
+    maxDepth?: number;
+}>;
+declare function redact<T>(value: T, options?: RedactOptions): T;
+declare function safeJsonStringify(value: unknown, options?: RedactOptions, space?: number): string;
+/**
+ * Convenience logger that will redact classified data and suspicious keys.
+ * You can pass your own logger implementation (pino, winston, console, etc).
+ */
+declare function safeLoggerAdapter(logger: Pick<Console, "info" | "warn" | "error" | "debug" | "log">): {
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+    debug: (...args: unknown[]) => void;
+    log: (...args: unknown[]) => void;
 };
 /**
- * Verifies a password against a previously hashed password
- * @param password - The password to verify
- * @param hash - The previously generated hash
- * @param salt - The salt used in the original hash
- * @param options - Password hash options (must match those used in hashPassword)
- * @returns True if the password matches, false otherwise
- */
-declare function verifyPassword(password: string, hash: string, salt: string, options?: Partial<PasswordHashOptions>): boolean;
-/**
- * Performs a constant-time comparison of two strings to prevent timing attacks
- * @param a - First string to compare
- * @param b - Second string to compare
- * @param options - Timing safe comparison options
- * @returns True if both strings are equal, false otherwise
- */
-declare function timingSafeEqual(a: string, b: string, options?: Partial<TimingSafeOptions>): boolean;
-/**
- * Generates a cryptographically secure random string
- * @param length - The length of the random string in bytes
- * @param encoding - The encoding to use for the output
- * @returns A random string in the specified encoding
+ * Helper for cases where you must emit a raw header value.
+ * Prefer using the policy layer to validate crossings before revealing.
  */
-declare function generateRandomBytes(length?: number, encoding?: 'hex' | 'base64'): string;
+declare function httpAuthorizationBearer(tokenValue: TokenString): string;
 
+type PolicyAction = "log" | "network" | "storage" | "analytics";
+type PolicyDecision = Readonly<{
+    allowed: boolean;
+    reason?: string;
+    detectedKinds?: DataClassification[];
+}>;
+type Policy = Readonly<{
+    name: string;
+    allow: Record<PolicyAction, ReadonlySet<DataClassification>>;
+    redactBefore?: ReadonlySet<PolicyAction>;
+    redaction?: RedactOptions;
+}>;
+declare function defaultPolicy(): Policy;
+declare function decide(policy: Policy, action: PolicyAction, data: unknown): PolicyDecision;
+declare function assertAllowed(policy: Policy, action: PolicyAction, data: unknown): void;
+type AuditEvent = Readonly<{
+    at: number;
+    policy: string;
+    action: PolicyAction;
+    decision: PolicyDecision;
+}>;
+declare function audit(policy: Policy, action: PolicyAction, data: unknown): AuditEvent;
 /**
- * A const enum for security levels, used for warnings
- * @public
- */
-declare enum SecurityLevel {
-    HIGH = "HIGH",
-    MEDIUM = "MEDIUM",
-    LOW = "LOW",
-    INSECURE = "INSECURE"
-}
-/**
- * Returns the security level of the encryption options
- * @param options - The encryption options
- * @returns The security level
- */
-declare function getSecurityLevel(options: EncryptionOptions): SecurityLevel;
-/**
- * Encrypts the provided text using the specified encryption options
- * @param text - The text to encrypt
- * @param key - The encryption key
- * @param options - Encryption options
- * @returns The encrypted text
- */
-declare function encrypt(text: string, key: string, options?: Partial<EncryptionOptions>): string;
-/**
- * Decrypts the provided encrypted text using the specified options
- * @param encryptedText - The text to decrypt
- * @param key - The decryption key
- * @param options - Encryption options
- * @returns The decrypted text
- */
-declare function decrypt(encryptedText: string, key: string, options?: Partial<EncryptionOptions>): string;
-/**
- * Generates a random encryption key
- * @param length - Length of the key in bytes
- * @returns A random key as a hex string
- */
-declare function generateKey(length?: number): string;
-
-/**
- * Calculates the entropy of a password in bits
- * @param password - The password to calculate entropy for
- * @returns The entropy in bits
- */
-declare function calculatePasswordEntropy(password: string): number;
-/**
- * Analyzes patterns in the password that might reduce its effective entropy
- * @param password - The password to analyze
- * @returns The entropy reduction (0 to 1)
- */
-declare function analyzePasswordPatterns(password: string): {
-    entropyReduction: number;
-    patterns: string[];
-};
-/**
- * Checks the strength of a password using both rule-based criteria and entropy
- * @param password - The password to check
- * @param config - Password configuration options
- * @returns A PasswordStrength object containing score and feedback
- */
-declare function checkPasswordStrength(password: string, config?: Partial<Config>): PasswordStrength;
-/**
- * Generates a secure random password based on configuration
- * @param config - Password configuration options
- * @returns A random secure password
+ * Safe sink example: log with enforcement + redaction (if configured).
  */
-declare function generateSecurePassword(config?: Partial<Config>): string;
+declare function policyLog(policy: Policy, logger: Pick<Console, "info" | "warn" | "error" | "debug" | "log">, level: keyof Pick<Console, "info" | "warn" | "error" | "debug" | "log">, ...args: unknown[]): void;
 
-export { type Config, ConfigSchema, type EncryptionOptions, EncryptionOptionsSchema, type HashOptions, HashOptionsSchema, type PasswordHashOptions, PasswordHashOptionsSchema, type PasswordStrength, PasswordStrengthSchema, SecurityLevel, type TimingSafeOptions, TimingSafeOptionsSchema, analyzePasswordPatterns, calculatePasswordEntropy, checkPasswordStrength, decrypt, encrypt, generateKey, generateRandomBytes, generateSecurePassword, getSecurityLevel, hash, hashPassword, hmac, timingSafeEqual, verifyHash, verifyPassword };
+export { type AuditEvent, type Classified, type CredentialString, CredentialStringSchema, type DataClassification, type PIIString, PIIStringSchema, type Policy, type PolicyAction, type PolicyDecision, type PublicString, PublicStringSchema, type RedactOptions, type SecretString, SecretStringSchema, type TokenString, TokenStringSchema, assertAllowed, audit, classificationOf, credential, decide, defaultPolicy, httpAuthorizationBearer, isClassified, piiText, policyLog, publicText, redact, reveal, safeJsonStringify, safeLoggerAdapter, secretText, token };