typesecure 0.1.0 → 0.2.2

package/dist/index.d.ts

@@ -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 };