@spfn/auth 0.1.0-alpha.0 → 0.1.0-alpha.86

package/dist/lib/session.js

@@ -0,0 +1,126 @@
+// src/lib/session.ts
+import * as jose from "jose";
+function calculateEntropy(str) {
+  const len = str.length;
+  const frequencies = /* @__PURE__ */ new Map();
+  for (const char of str) {
+    frequencies.set(char, (frequencies.get(char) || 0) + 1);
+  }
+  let entropy = 0;
+  for (const count of frequencies.values()) {
+    const probability = count / len;
+    entropy -= probability * Math.log2(probability);
+  }
+  return entropy;
+}
+async function getSessionSecret() {
+  const secret = process.env.SPFN_AUTH_SESSION_SECRET || // New prefixed version (recommended)
+  process.env.SESSION_SECRET;
+  if (!secret) {
+    throw new Error("SPFN_AUTH_SESSION_SECRET environment variable is not set");
+  }
+  if (secret.length < 32) {
+    throw new Error("SPFN_AUTH_SESSION_SECRET must be at least 32 characters long");
+  }
+  const encoder = new TextEncoder();
+  const data = encoder.encode(secret);
+  const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+  return new Uint8Array(hashBuffer);
+}
+async function sealSession(data, ttl = 60 * 60 * 24 * 7) {
+  const secret = await getSessionSecret();
+  return await new jose.EncryptJWT({ data }).setProtectedHeader({ alg: "dir", enc: "A256GCM" }).setIssuedAt().setExpirationTime(`${ttl}s`).setIssuer("spfn-auth").setAudience("spfn-client").encrypt(secret);
+}
+async function unsealSession(jwt) {
+  const secret = await getSessionSecret();
+  try {
+    const { payload } = await jose.jwtDecrypt(jwt, secret, {
+      issuer: "spfn-auth",
+      audience: "spfn-client"
+    });
+    return payload.data;
+  } catch (err) {
+    if (err instanceof jose.errors.JWTExpired) {
+      throw new Error("Session expired");
+    }
+    if (err instanceof jose.errors.JWEDecryptionFailed) {
+      throw new Error("Invalid session");
+    }
+    if (err instanceof jose.errors.JWTClaimValidationFailed) {
+      throw new Error("Session validation failed");
+    }
+    throw new Error("Failed to unseal session");
+  }
+}
+async function getSessionInfo(jwt) {
+  const secret = await getSessionSecret();
+  try {
+    const { payload } = await jose.jwtDecrypt(jwt, secret);
+    return {
+      issuedAt: new Date(payload.iat * 1e3),
+      expiresAt: new Date(payload.exp * 1e3),
+      issuer: payload.iss || "",
+      audience: Array.isArray(payload.aud) ? payload.aud[0] : payload.aud || ""
+    };
+  } catch (err) {
+    if (process.env.NODE_ENV !== "production") {
+      console.warn("[Session] Failed to get session info:", err instanceof Error ? err.message : "Unknown error");
+    }
+    return null;
+  }
+}
+async function shouldRefreshSession(jwt, thresholdHours = 24) {
+  const info = await getSessionInfo(jwt);
+  if (!info) {
+    return true;
+  }
+  const hoursRemaining = (info.expiresAt.getTime() - Date.now()) / (1e3 * 60 * 60);
+  return hoursRemaining < thresholdHours;
+}
+function validateSessionSecret() {
+  try {
+    const secret = process.env.SPFN_AUTH_SESSION_SECRET || // New prefixed version (recommended)
+    process.env.SESSION_SECRET;
+    if (!secret) {
+      return { valid: false, error: "SPFN_AUTH_SESSION_SECRET is not set" };
+    }
+    const length = secret.length;
+    const uniqueChars = new Set(secret).size;
+    const entropy = calculateEntropy(secret);
+    if (length < 32) {
+      return {
+        valid: false,
+        error: `SPFN_AUTH_SESSION_SECRET too short (${length} chars, minimum 32)`,
+        details: { length, uniqueChars, entropy }
+      };
+    }
+    if (uniqueChars < 16) {
+      return {
+        valid: false,
+        error: `SPFN_AUTH_SESSION_SECRET has low diversity (${uniqueChars} unique chars, minimum 16)`,
+        details: { length, uniqueChars, entropy }
+      };
+    }
+    if (entropy < 3.5) {
+      return {
+        valid: false,
+        error: `SPFN_AUTH_SESSION_SECRET has low entropy (${entropy.toFixed(2)} bits/char, minimum 3.5). Use a more random secret.`,
+        details: { length, uniqueChars, entropy }
+      };
+    }
+    return {
+      valid: true,
+      details: { length, uniqueChars, entropy }
+    };
+  } catch (err) {
+    return { valid: false, error: "Failed to validate SPFN_AUTH_SESSION_SECRET" };
+  }
+}
+export {
+  getSessionInfo,
+  sealSession,
+  shouldRefreshSession,
+  unsealSession,
+  validateSessionSecret
+};
+//# sourceMappingURL=session.js.map

package/dist/lib/session.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/lib/session.ts"],"sourcesContent":["/**\n * @spfn/auth - Client Session Management\n *\n * Uses Jose JWE (JSON Web Encryption) to securely store session data in cookies\n * More efficient than Iron Session with better Edge Runtime support\n */\n\nimport * as jose from 'jose';\n\nexport interface SessionData\n{\n    userId: string;\n    privateKey: string;     // Base64 encoded DER\n    keyId: string;\n    algorithm: 'ES256' | 'RS256';\n}\n\n/**\n * Calculate Shannon entropy of a string\n * Returns entropy in bits per character\n *\n * @param str - String to calculate entropy for\n * @returns Entropy value (0 to ~6.6 bits for printable ASCII)\n */\nfunction calculateEntropy(str: string): number\n{\n    const len = str.length;\n    const frequencies = new Map<string, number>();\n\n    // Count character frequencies\n    for (const char of str)\n    {\n        frequencies.set(char, (frequencies.get(char) || 0) + 1);\n    }\n\n    // Calculate Shannon entropy\n    let entropy = 0;\n    for (const count of frequencies.values())\n    {\n        const probability = count / len;\n        entropy -= probability * Math.log2(probability);\n    }\n\n    return entropy;\n}\n\n/**\n * Get session secret from environment\n * Must be at least 32 characters (256-bit)\n *\n * Derives a 32-byte key using SHA-256 to ensure compatibility with Jose A256GCM\n */\nasync function getSessionSecret(): Promise<Uint8Array>\n{\n    const secret =\n        process.env.SPFN_AUTH_SESSION_SECRET ||  // New prefixed version (recommended)\n        process.env.SESSION_SECRET;               // Legacy fallback\n\n    if (!secret)\n    {\n        throw new Error('SPFN_AUTH_SESSION_SECRET environment variable is not set');\n    }\n\n    if (secret.length < 32)\n    {\n        throw new Error('SPFN_AUTH_SESSION_SECRET must be at least 32 characters long');\n    }\n\n    // Derive a 32-byte key using SHA-256 for A256GCM compatibility\n    // Use Web Crypto API for universal compatibility (browser + Node.js)\n    const encoder = new TextEncoder();\n    const data = encoder.encode(secret);\n    const hashBuffer = await crypto.subtle.digest('SHA-256', data);\n    return new Uint8Array(hashBuffer);\n}\n\n/**\n * Seal session data into encrypted JWT (JWE)\n *\n * @param data - Session data to encrypt\n * @param ttl - Time to live in seconds (default: 7 days)\n * @returns Encrypted JWT string\n */\nexport async function sealSession(\n    data: SessionData,\n    ttl: number = 60 * 60 * 24 * 7 // 7 days\n): Promise<string>\n{\n    const secret = await getSessionSecret();\n\n    return await new jose.EncryptJWT({ data })\n        .setProtectedHeader({ alg: 'dir', enc: 'A256GCM' })\n        .setIssuedAt()\n        .setExpirationTime(`${ttl}s`)\n        .setIssuer('spfn-auth')\n        .setAudience('spfn-client')\n        .encrypt(secret);\n}\n\n/**\n * Unseal encrypted JWT (JWE) to session data\n *\n * @param jwt - Encrypted JWT string\n * @returns Session data\n * @throws Error if session is invalid or expired\n */\nexport async function unsealSession(jwt: string): Promise<SessionData>\n{\n    const secret = await getSessionSecret();\n\n    try\n    {\n        const { payload } = await jose.jwtDecrypt(jwt, secret, {\n            issuer: 'spfn-auth',\n            audience: 'spfn-client',\n        });\n\n        return payload.data as SessionData;\n    }\n    catch (err)\n    {\n        if (err instanceof jose.errors.JWTExpired)\n        {\n            throw new Error('Session expired');\n        }\n\n        if (err instanceof jose.errors.JWEDecryptionFailed)\n        {\n            throw new Error('Invalid session');\n        }\n\n        if (err instanceof jose.errors.JWTClaimValidationFailed)\n        {\n            throw new Error('Session validation failed');\n        }\n\n        throw new Error('Failed to unseal session');\n    }\n}\n\n/**\n * Get session metadata without decrypting\n *\n * @param jwt - Encrypted JWT string\n * @returns Session metadata or null if invalid\n */\nexport async function getSessionInfo(jwt: string): Promise<{\n    issuedAt: Date;\n    expiresAt: Date;\n    issuer: string;\n    audience: string;\n} | null>\n{\n    const secret = await getSessionSecret();\n\n    try\n    {\n        const { payload } = await jose.jwtDecrypt(jwt, secret);\n\n        return {\n            issuedAt: new Date(payload.iat! * 1000),\n            expiresAt: new Date(payload.exp! * 1000),\n            issuer: payload.iss || '',\n            audience: Array.isArray(payload.aud) ? payload.aud[0] : payload.aud || '',\n        };\n    }\n    catch (err)\n    {\n        // Log error for debugging but return null for graceful handling\n        if (process.env.NODE_ENV !== 'production')\n        {\n            console.warn('[Session] Failed to get session info:', err instanceof Error ? err.message : 'Unknown error');\n        }\n        return null;\n    }\n}\n\n/**\n * Check if session is about to expire (within threshold)\n *\n * @param jwt - Encrypted JWT string\n * @param thresholdHours - Hours before expiry to trigger refresh (default: 24)\n * @returns True if session should be refreshed\n */\nexport async function shouldRefreshSession(\n    jwt: string,\n    thresholdHours: number = 24\n): Promise<boolean>\n{\n    const info = await getSessionInfo(jwt);\n\n    if (!info)\n    {\n        return true;\n    }\n\n    const hoursRemaining = (info.expiresAt.getTime() - Date.now()) / (1000 * 60 * 60);\n\n    return hoursRemaining < thresholdHours;\n}\n\n/**\n * Validate session secret strength\n * Call this at startup to ensure proper configuration\n *\n * Validation criteria:\n * - Minimum 32 characters (256-bit)\n * - Minimum 16 unique characters\n * - Minimum 3.5 bits/char Shannon entropy (good randomness)\n */\nexport function validateSessionSecret(): {\n    valid: boolean;\n    error?: string;\n    details?: {\n        length: number;\n        uniqueChars: number;\n        entropy: number;\n    };\n}\n{\n    try\n    {\n        const secret =\n            process.env.SPFN_AUTH_SESSION_SECRET ||  // New prefixed version (recommended)\n            process.env.SESSION_SECRET;               // Legacy fallback\n\n        if (!secret)\n        {\n            return { valid: false, error: 'SPFN_AUTH_SESSION_SECRET is not set' };\n        }\n\n        const length = secret.length;\n        const uniqueChars = new Set(secret).size;\n        const entropy = calculateEntropy(secret);\n\n        // Check length (minimum 32 chars for 256-bit)\n        if (length < 32)\n        {\n            return {\n                valid: false,\n                error: `SPFN_AUTH_SESSION_SECRET too short (${length} chars, minimum 32)`,\n                details: { length, uniqueChars, entropy },\n            };\n        }\n\n        // Check unique character diversity\n        if (uniqueChars < 16)\n        {\n            return {\n                valid: false,\n                error: `SPFN_AUTH_SESSION_SECRET has low diversity (${uniqueChars} unique chars, minimum 16)`,\n                details: { length, uniqueChars, entropy },\n            };\n        }\n\n        // Check Shannon entropy (3.5 bits/char is good randomness)\n        // For reference:\n        // - Random lowercase: ~4.7 bits/char\n        // - Random alphanumeric: ~5.2 bits/char\n        // - Random printable ASCII: ~6.6 bits/char\n        // - \"aaaaaaa...\": ~0 bits/char\n        // - \"abcabcabc...\": ~1.58 bits/char\n        if (entropy < 3.5)\n        {\n            return {\n                valid: false,\n                error: `SPFN_AUTH_SESSION_SECRET has low entropy (${entropy.toFixed(2)} bits/char, minimum 3.5). Use a more random secret.`,\n                details: { length, uniqueChars, entropy },\n            };\n        }\n\n        return {\n            valid: true,\n            details: { length, uniqueChars, entropy },\n        };\n    }\n    catch (err)\n    {\n        return { valid: false, error: 'Failed to validate SPFN_AUTH_SESSION_SECRET' };\n    }\n}"],"mappings":"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","names":[]}

package/dist/lib/types/api.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @spfn/auth - API Response Types
+ *
+ * Auth-specific types for API endpoints
+ * For standard ApiResponse type, import from '@spfn/core/types/api-response'
+ */
+/**
+ * Session types
+ */
+interface SessionPayload {
+    userId: string;
+    role?: string;
+}
+/**
+ * RBAC types
+ */
+interface Permission {
+    resource: string;
+    action: string;
+}
+/**
+ * API Response Types for specific endpoints
+ */
+interface CheckAccountExistsData {
+    exists: boolean;
+    identifier: string;
+    identifierType: 'email' | 'phone';
+}
+interface LoginData {
+    token: string;
+    user: {
+        id: string;
+        email?: string;
+        phone?: string;
+        role: string;
+        emailVerifiedAt?: string;
+        phoneVerifiedAt?: string;
+    };
+    passwordChangeRequired: boolean;
+}
+interface ChangePasswordData {
+    success: boolean;
+}
+
+export type { ChangePasswordData, CheckAccountExistsData, LoginData, Permission, SessionPayload };

package/dist/lib/types/api.js

@@ -0,0 +1 @@
+//# sourceMappingURL=api.js.map

package/dist/lib/types/api.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/lib/types/index.d.ts

@@ -0,0 +1,3 @@
+export { ChangePasswordData, CheckAccountExistsData, LoginData, Permission, SessionPayload } from './api.js';
+export { ApiResponseSchema, ErrorResponseSchema, SuccessResponseSchema } from './schemas.js';
+import '@sinclair/typebox';