@guinetik/primitives-ts 0.2.0 → 0.2.1

package/dist/index.d.ts

@@ -13,4 +13,6 @@ export * from './website.types';
 export * from './firestore.types';
 export * from './website-firestore.types';
 export * from './totp.types';
+export type { Security, SecurityChallengeOptions, SecurityChallengeResult } from './security.interface';
+export { SecurityLevel } from './security.interface';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,cAAc,cAAc,CAAC;AAG7B,cAAc,gBAAgB,CAAC;AAG/B,cAAc,iBAAiB,CAAC;AAGhC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,2BAA2B,CAAC;AAG1C,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,cAAc,cAAc,CAAC;AAG7B,cAAc,gBAAgB,CAAC;AAG/B,cAAc,iBAAiB,CAAC;AAGhC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,2BAA2B,CAAC;AAG1C,cAAc,cAAc,CAAC;AAG7B,YAAY,EAAE,QAAQ,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AACxG,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -23,6 +23,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SecurityLevel = void 0;
 // Auth types
 __exportStar(require("./auth.types"), exports);
 // System monitoring types
@@ -35,3 +36,5 @@ __exportStar(require("./firestore.types"), exports);
 __exportStar(require("./website-firestore.types"), exports);
 // TOTP/2FA types
 __exportStar(require("./totp.types"), exports);
+var security_interface_1 = require("./security.interface");
+Object.defineProperty(exports, "SecurityLevel", { enumerable: true, get: function () { return security_interface_1.SecurityLevel; } });

package/dist/security.interface.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Security Clearance Levels
+ *
+ * Hierarchical security levels similar to log levels.
+ * Higher numbers = stronger security requirements.
+ *
+ * Usage:
+ * - Sensitive operations specify minimum required level
+ * - System selects appropriate challenge based on user's available methods
+ * - User must have a method at or above the required level
+ *
+ * Example:
+ * ```typescript
+ * // Shell execution requires at least 2FA
+ * const executeCommand = withSecurityChallenge(fn, {
+ *   minLevel: SecurityLevel.TWO_FACTOR
+ * });
+ * ```
+ */
+export declare enum SecurityLevel {
+    /** Password confirmation - baseline, everyone has this */
+    PASSWORD = 1,
+    /** Two-factor authentication - authenticator app codes */
+    TWO_FACTOR = 2,
+    /** Biometric verification - fingerprint, face ID, etc. */
+    BIOMETRIC = 3,
+    /** Hardware security key - YubiKey, etc. */
+    HARDWARE_KEY = 4
+}
+/**
+ * Security Challenge Options
+ *
+ * Configuration for security challenge dialogs and verification flows
+ */
+export interface SecurityChallengeOptions {
+    /** Minimum security level required (defaults to PASSWORD) */
+    minLevel?: SecurityLevel;
+    /** Title shown in the challenge dialog */
+    title?: string;
+    /** Description/reason for the security challenge */
+    message?: string;
+    /** Additional context passed to the implementation */
+    context?: Record<string, any>;
+}
+/**
+ * Security - Abstract Security Challenge Interface
+ *
+ * Base interface for all security challenge implementations (2FA, biometric, SMS, etc.).
+ * Each implementation handles its own UI (dialog) and verification logic.
+ *
+ * Design Pattern: Strategy Pattern
+ * - Different security methods implement this interface
+ * - Each strategy encapsulates its own verification logic
+ * - Consumers don't need to know the implementation details
+ *
+ * Example Implementations:
+ * - Security2FactorChallenge (TOTP/authenticator apps)
+ * - SecurityBiometricChallenge (fingerprint/face ID)
+ * - SecuritySmsChallenge (SMS verification codes)
+ * - SecurityEmailChallenge (email verification codes)
+ *
+ * Usage:
+ * ```typescript
+ * const twoFactorSecurity = new Security2FactorChallenge();
+ * const verified = await twoFactorSecurity.challenge(userId, {
+ *   title: 'Delete Account',
+ *   message: 'This action cannot be undone'
+ * });
+ *
+ * if (verified) {
+ *   // Proceed with sensitive operation
+ * }
+ * ```
+ */
+export interface Security {
+    /**
+     * Initiates a security challenge for the user
+     *
+     * Shows the appropriate UI (dialog, prompt, biometric scanner, etc.)
+     * and waits for the user to complete the challenge.
+     *
+     * The promise resolves to:
+     * - `true` if the challenge succeeds (user verified)
+     * - `false` if the challenge fails or is cancelled
+     *
+     * Implementation Note:
+     * Each concrete implementation should:
+     * 1. Show its own UI (dialog, modal, native prompt, etc.)
+     * 2. Wait for user input/interaction
+     * 3. Verify the credentials/input
+     * 4. Resolve the promise based on verification result
+     *
+     * @param uid - User ID to verify against
+     * @param options - Challenge customization options
+     * @returns Promise resolving to true if verified, false otherwise
+     */
+    challenge(uid: string, options?: SecurityChallengeOptions): Promise<boolean>;
+    /**
+     * Gets the type identifier for this security implementation
+     *
+     * Used by the SecurityService registry to identify and retrieve
+     * the correct implementation.
+     *
+     * Examples: '2fa', 'biometric', 'password', 'hardware-key'
+     *
+     * @returns Unique identifier for this security type
+     */
+    getType(): string;
+    /**
+     * Gets the security level of this implementation
+     *
+     * Used by SecurityService to determine if this method meets
+     * the minimum required security level for an operation.
+     *
+     * @returns SecurityLevel enum value
+     */
+    getLevel(): SecurityLevel;
+    /**
+     * Checks if this security method is available for the user
+     *
+     * Some security methods may not be available depending on:
+     * - User hasn't enrolled (e.g., no 2FA setup)
+     * - Device capabilities (e.g., no biometric sensor)
+     * - Browser support (e.g., WebAuthn not supported)
+     *
+     * @param uid - User ID to check availability for
+     * @returns Promise resolving to true if available, false otherwise
+     */
+    isAvailable(uid: string): Promise<boolean>;
+}
+/**
+ * Security Challenge Result
+ *
+ * Extended result object that implementations can optionally return
+ * with additional metadata about the challenge
+ */
+export interface SecurityChallengeResult {
+    /** Whether the challenge succeeded */
+    verified: boolean;
+    /** Optional error message if verification failed */
+    error?: string;
+    /** Optional metadata (e.g., biometric sensor used, code expiry time) */
+    metadata?: Record<string, any>;
+}
+//# sourceMappingURL=security.interface.d.ts.map

package/dist/security.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"security.interface.d.ts","sourceRoot":"","sources":["../src/security.interface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,oBAAY,aAAa;IACvB,0DAA0D;IAC1D,QAAQ,IAAI;IAEZ,0DAA0D;IAC1D,UAAU,IAAI;IAEd,0DAA0D;IAC1D,SAAS,IAAI;IAEb,4CAA4C;IAC5C,YAAY,IAAI;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,WAAW,QAAQ;IACvB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,wBAAwB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAE7E;;;;;;;;;OASG;IACH,OAAO,IAAI,MAAM,CAAC;IAElB;;;;;;;OAOG;IACH,QAAQ,IAAI,aAAa,CAAC;IAE1B;;;;;;;;;;OAUG;IACH,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5C;AAED;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,sCAAsC;IACtC,QAAQ,EAAE,OAAO,CAAC;IAClB,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAChC"}

package/dist/security.interface.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SecurityLevel = void 0;
+/**
+ * Security Clearance Levels
+ *
+ * Hierarchical security levels similar to log levels.
+ * Higher numbers = stronger security requirements.
+ *
+ * Usage:
+ * - Sensitive operations specify minimum required level
+ * - System selects appropriate challenge based on user's available methods
+ * - User must have a method at or above the required level
+ *
+ * Example:
+ * ```typescript
+ * // Shell execution requires at least 2FA
+ * const executeCommand = withSecurityChallenge(fn, {
+ *   minLevel: SecurityLevel.TWO_FACTOR
+ * });
+ * ```
+ */
+var SecurityLevel;
+(function (SecurityLevel) {
+    /** Password confirmation - baseline, everyone has this */
+    SecurityLevel[SecurityLevel["PASSWORD"] = 1] = "PASSWORD";
+    /** Two-factor authentication - authenticator app codes */
+    SecurityLevel[SecurityLevel["TWO_FACTOR"] = 2] = "TWO_FACTOR";
+    /** Biometric verification - fingerprint, face ID, etc. */
+    SecurityLevel[SecurityLevel["BIOMETRIC"] = 3] = "BIOMETRIC";
+    /** Hardware security key - YubiKey, etc. */
+    SecurityLevel[SecurityLevel["HARDWARE_KEY"] = 4] = "HARDWARE_KEY";
+})(SecurityLevel || (exports.SecurityLevel = SecurityLevel = {}));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guinetik/primitives-ts",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Shared TypeScript primitives for Guinetik projects",
   "author": "Guinetik",
   "license": "MIT",