unotoken 0.1.0

package/dist/signatures/email.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Email verification flow for unotoken device signatures.
+ *
+ * Orchestrates the email verification process:
+ * 1. User provides their email address
+ * 2. A 6-digit code is generated and sent via Resend
+ * 3. User enters the code to verify ownership
+ * 4. On success, email is saved to email-config.json as verified
+ *
+ * This module connects email-config (persistence) and resend (sending)
+ * into a cohesive verification flow.
+ *
+ * @module
+ */
+import { type EmailConfig } from './email-config.js';
+export interface PendingVerification {
+    /** The email address being verified */
+    email: string;
+    /** SHA-256 hash of the code (never store plaintext) */
+    codeHash: string;
+    /** When the code was generated (ISO 8601) */
+    createdAt: string;
+    /** When the code expires (ISO 8601) */
+    expiresAt: string;
+    /** Number of verification attempts made */
+    attempts: number;
+    /** Maximum allowed attempts */
+    maxAttempts: number;
+}
+export interface VerificationResult {
+    /** Whether the code was valid and email is now verified */
+    success: boolean;
+    /** Reason for failure (if not successful) */
+    reason?: 'invalid_code' | 'expired' | 'max_attempts' | 'no_pending';
+    /** Number of remaining attempts (if applicable) */
+    remainingAttempts?: number;
+}
+export interface InitiateVerificationResult {
+    /** Whether the verification email was sent successfully */
+    sent: boolean;
+    /** Error message if sending failed */
+    error?: string;
+    /** The pending verification state (for passing to verifyCode) */
+    pending?: PendingVerification;
+}
+/**
+ * Generate a cryptographically random 6-digit code.
+ *
+ * Uses crypto.randomInt (not Math.random) for security.
+ *
+ * @returns A 6-digit string (zero-padded)
+ */
+export declare function generateVerificationCode(): string;
+/**
+ * Hash a verification code with SHA-256.
+ *
+ * Codes are always stored as hashes, never plaintext.
+ *
+ * @param code - The plaintext 6-digit code
+ * @returns SHA-256 hex digest
+ */
+export declare function hashCode(code: string): string;
+/**
+ * Initiate email verification by sending a code.
+ *
+ * @param email - The email address to verify
+ * @param deviceFingerprint - Current device fingerprint (for rate limiting and context)
+ * @param deviceName - Current device name (for email context)
+ * @param baseDir - Optional base directory for config files
+ * @returns Result with sent status and pending verification state
+ */
+export declare function initiateVerification(email: string, deviceFingerprint: string, deviceName: string, baseDir?: string): Promise<InitiateVerificationResult>;
+/**
+ * Verify a code against a pending verification.
+ *
+ * @param pending - The pending verification state
+ * @param userCode - The code entered by the user
+ * @returns Verification result
+ */
+export declare function verifyCode(pending: PendingVerification, userCode: string): VerificationResult;
+/**
+ * Complete email verification by saving the config.
+ *
+ * Call this after verifyCode returns success.
+ *
+ * @param email - The verified email address
+ * @param resendApiKey - Optional custom Resend API key to persist
+ * @param baseDir - Optional base directory for config files
+ * @returns The saved email config
+ */
+export declare function completeVerification(email: string, resendApiKey?: string, baseDir?: string): EmailConfig;
+/**
+ * Check if the code expiry time has passed.
+ *
+ * @param pending - The pending verification
+ * @returns true if the code has expired
+ */
+export declare function isCodeExpired(pending: PendingVerification): boolean;
+/**
+ * Check if max attempts have been reached.
+ *
+ * @param pending - The pending verification
+ * @returns true if no more attempts are allowed
+ */
+export declare function isMaxAttemptsReached(pending: PendingVerification): boolean;
+//# sourceMappingURL=email.d.ts.map

package/dist/signatures/email.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"email.d.ts","sourceRoot":"","sources":["../../src/signatures/email.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,mBAAmB,CAAC;AAoB3B,MAAM,WAAW,mBAAmB;IAClC,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,kBAAkB;IACjC,2DAA2D;IAC3D,OAAO,EAAE,OAAO,CAAC;IACjB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,cAAc,GAAG,SAAS,GAAG,cAAc,GAAG,YAAY,CAAC;IACpE,mDAAmD;IACnD,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,0BAA0B;IACzC,2DAA2D;IAC3D,IAAI,EAAE,OAAO,CAAC;IACd,sCAAsC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,OAAO,CAAC,EAAE,mBAAmB,CAAC;CAC/B;AAID;;;;;;GAMG;AACH,wBAAgB,wBAAwB,IAAI,MAAM,CAGjD;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7C;AAID;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,MAAM,EACb,iBAAiB,EAAE,MAAM,EACzB,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,0BAA0B,CAAC,CAwDrC;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,mBAAmB,EAC5B,QAAQ,EAAE,MAAM,GACf,kBAAkB,CA2BpB;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,EACb,YAAY,CAAC,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE,MAAM,GACf,WAAW,CAqBb;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAEnE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAE1E"}

package/dist/signatures/email.js

@@ -0,0 +1,180 @@
+/**
+ * Email verification flow for unotoken device signatures.
+ *
+ * Orchestrates the email verification process:
+ * 1. User provides their email address
+ * 2. A 6-digit code is generated and sent via Resend
+ * 3. User enters the code to verify ownership
+ * 4. On success, email is saved to email-config.json as verified
+ *
+ * This module connects email-config (persistence) and resend (sending)
+ * into a cohesive verification flow.
+ *
+ * @module
+ */
+import { randomInt, createHash } from 'node:crypto';
+import { loadEmailConfig, saveEmailConfig, isValidEmail, } from './email-config.js';
+import { sendApprovalEmail, isRateLimited, } from './resend.js';
+// ─── Constants ──────────────────────────────────────────────────────
+/** Code length (6 digits) */
+const CODE_LENGTH = 6;
+/** Code expiry in milliseconds (5 minutes) */
+const CODE_EXPIRY_MS = 5 * 60 * 1000;
+/** Maximum verification attempts per code */
+const MAX_ATTEMPTS = 3;
+// ─── Code Generation ────────────────────────────────────────────────
+/**
+ * Generate a cryptographically random 6-digit code.
+ *
+ * Uses crypto.randomInt (not Math.random) for security.
+ *
+ * @returns A 6-digit string (zero-padded)
+ */
+export function generateVerificationCode() {
+    const code = randomInt(0, 10 ** CODE_LENGTH);
+    return code.toString().padStart(CODE_LENGTH, '0');
+}
+/**
+ * Hash a verification code with SHA-256.
+ *
+ * Codes are always stored as hashes, never plaintext.
+ *
+ * @param code - The plaintext 6-digit code
+ * @returns SHA-256 hex digest
+ */
+export function hashCode(code) {
+    return createHash('sha256').update(code).digest('hex');
+}
+// ─── Verification Flow ──────────────────────────────────────────────
+/**
+ * Initiate email verification by sending a code.
+ *
+ * @param email - The email address to verify
+ * @param deviceFingerprint - Current device fingerprint (for rate limiting and context)
+ * @param deviceName - Current device name (for email context)
+ * @param baseDir - Optional base directory for config files
+ * @returns Result with sent status and pending verification state
+ */
+export async function initiateVerification(email, deviceFingerprint, deviceName, baseDir) {
+    // Validate email format
+    if (!isValidEmail(email)) {
+        return {
+            sent: false,
+            error: `Invalid email address: ${email}`,
+        };
+    }
+    // Check rate limit
+    if (isRateLimited(deviceFingerprint)) {
+        return {
+            sent: false,
+            error: 'Rate limit exceeded. Maximum 3 verification emails per hour. Please wait before trying again.',
+        };
+    }
+    // Generate code
+    const code = generateVerificationCode();
+    const codeHash = hashCode(code);
+    const now = new Date();
+    const expiresAt = new Date(now.getTime() + CODE_EXPIRY_MS);
+    // Build context for the email
+    const context = {
+        deviceName,
+        timestamp: now.toISOString(),
+    };
+    // Send the email
+    const result = await sendApprovalEmail(email, code, context, deviceFingerprint, baseDir);
+    if (!result.success) {
+        return {
+            sent: false,
+            error: result.error ?? 'Failed to send verification email',
+        };
+    }
+    // Create pending verification state
+    const pending = {
+        email,
+        codeHash,
+        createdAt: now.toISOString(),
+        expiresAt: expiresAt.toISOString(),
+        attempts: 0,
+        maxAttempts: MAX_ATTEMPTS,
+    };
+    return { sent: true, pending };
+}
+/**
+ * Verify a code against a pending verification.
+ *
+ * @param pending - The pending verification state
+ * @param userCode - The code entered by the user
+ * @returns Verification result
+ */
+export function verifyCode(pending, userCode) {
+    // Check expiry
+    const now = new Date();
+    const expiresAt = new Date(pending.expiresAt);
+    if (now > expiresAt) {
+        return { success: false, reason: 'expired' };
+    }
+    // Check max attempts
+    if (pending.attempts >= pending.maxAttempts) {
+        return { success: false, reason: 'max_attempts' };
+    }
+    // Increment attempts
+    pending.attempts += 1;
+    // Verify code hash
+    const userHash = hashCode(userCode.trim());
+    if (userHash !== pending.codeHash) {
+        const remaining = pending.maxAttempts - pending.attempts;
+        if (remaining <= 0) {
+            return { success: false, reason: 'max_attempts', remainingAttempts: 0 };
+        }
+        return { success: false, reason: 'invalid_code', remainingAttempts: remaining };
+    }
+    return { success: true };
+}
+/**
+ * Complete email verification by saving the config.
+ *
+ * Call this after verifyCode returns success.
+ *
+ * @param email - The verified email address
+ * @param resendApiKey - Optional custom Resend API key to persist
+ * @param baseDir - Optional base directory for config files
+ * @returns The saved email config
+ */
+export function completeVerification(email, resendApiKey, baseDir) {
+    const config = {
+        email,
+        verified: true,
+        verifiedAt: new Date().toISOString(),
+    };
+    if (resendApiKey) {
+        config.resendApiKey = resendApiKey;
+    }
+    // Preserve existing custom Resend key if not explicitly provided
+    if (!resendApiKey) {
+        const existing = loadEmailConfig(baseDir);
+        if (existing?.resendApiKey) {
+            config.resendApiKey = existing.resendApiKey;
+        }
+    }
+    saveEmailConfig(config, baseDir);
+    return config;
+}
+/**
+ * Check if the code expiry time has passed.
+ *
+ * @param pending - The pending verification
+ * @returns true if the code has expired
+ */
+export function isCodeExpired(pending) {
+    return new Date() > new Date(pending.expiresAt);
+}
+/**
+ * Check if max attempts have been reached.
+ *
+ * @param pending - The pending verification
+ * @returns true if no more attempts are allowed
+ */
+export function isMaxAttemptsReached(pending) {
+    return pending.attempts >= pending.maxAttempts;
+}
+//# sourceMappingURL=email.js.map

package/dist/signatures/email.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"email.js","sourceRoot":"","sources":["../../src/signatures/email.ts"],"names":[],"mappings":"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"}

package/dist/signatures/fingerprint.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Device fingerprinting for unotoken device signatures.
+ *
+ * Generates a stable, unique fingerprint for the current machine by combining:
+ * 1. Machine identity (hostname + OS platform + username)
+ * 2. A per-install random salt stored at ~/.yokotoken/device-install-id
+ *
+ * The per-install salt ensures that even identical VMs or containers get
+ * different fingerprints. The machine identity ensures that the same install
+ * on the same machine always produces the same fingerprint (deterministic).
+ *
+ * For cloud/container environments, each new container instance will generate
+ * a new device-install-id and thus a new fingerprint -- this is intentional,
+ * as each container is treated as a separate device.
+ *
+ * @module
+ */
+/**
+ * Get the path to the device-install-id file.
+ *
+ * @param baseDir - Optional base directory (default: ~/.yokotoken)
+ * @returns Absolute path to device-install-id
+ */
+export declare function getInstallIdPath(baseDir?: string): string;
+/**
+ * Read or create the per-install random salt.
+ *
+ * On first call, generates a 32-byte random value and persists it.
+ * On subsequent calls, reads the persisted value.
+ *
+ * @param baseDir - Optional base directory (default: ~/.yokotoken)
+ * @returns The install ID as a hex string
+ */
+export declare function ensureInstallId(baseDir?: string): string;
+/**
+ * Collect machine identity components.
+ *
+ * Returns a deterministic string derived from the machine's hostname,
+ * OS platform, and current username. This provides a "best effort"
+ * machine identity that is stable across restarts.
+ *
+ * @returns A colon-separated identity string
+ */
+export declare function getMachineIdentity(): string;
+/**
+ * Generate a stable device fingerprint.
+ *
+ * The fingerprint is a SHA-256 hash of:
+ *   machineIdentity + ":" + installId
+ *
+ * Properties:
+ * - Deterministic: same machine + same install-id = same fingerprint
+ * - Unique across machines: different hostname/OS/username = different hash
+ * - Unique across installs: different install-id = different hash (even on same machine)
+ * - Not reversible: SHA-256 hash cannot reveal machine details
+ *
+ * @param baseDir - Optional base directory for the install-id file (default: ~/.yokotoken)
+ * @returns A 64-character hex string (SHA-256 hash)
+ */
+export declare function generateDeviceFingerprint(baseDir?: string): string;
+/**
+ * Generate a user-friendly device name from system info.
+ *
+ * Format: "{username}@{hostname}" — human-readable but not guaranteed unique.
+ * Used as the default display name for a device in the known_devices registry.
+ *
+ * @returns A human-friendly device name string
+ */
+export declare function getDefaultDeviceName(): string;
+//# sourceMappingURL=fingerprint.d.ts.map

package/dist/signatures/fingerprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.d.ts","sourceRoot":"","sources":["../../src/signatures/fingerprint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAeH;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAgBxD;AAID;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAa3C;AAID;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAMlE;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAW7C"}

package/dist/signatures/fingerprint.js

@@ -0,0 +1,123 @@
+/**
+ * Device fingerprinting for unotoken device signatures.
+ *
+ * Generates a stable, unique fingerprint for the current machine by combining:
+ * 1. Machine identity (hostname + OS platform + username)
+ * 2. A per-install random salt stored at ~/.yokotoken/device-install-id
+ *
+ * The per-install salt ensures that even identical VMs or containers get
+ * different fingerprints. The machine identity ensures that the same install
+ * on the same machine always produces the same fingerprint (deterministic).
+ *
+ * For cloud/container environments, each new container instance will generate
+ * a new device-install-id and thus a new fingerprint -- this is intentional,
+ * as each container is treated as a separate device.
+ *
+ * @module
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { hostname, platform, userInfo } from 'node:os';
+import path from 'node:path';
+import { getDeviceDir } from '../oauth/device-secret.js';
+// ─── Constants ──────────────────────────────────────────────────────
+const INSTALL_ID_FILENAME = 'device-install-id';
+const INSTALL_ID_BYTES = 32;
+// ─── Install ID (per-install salt) ──────────────────────────────────
+/**
+ * Get the path to the device-install-id file.
+ *
+ * @param baseDir - Optional base directory (default: ~/.yokotoken)
+ * @returns Absolute path to device-install-id
+ */
+export function getInstallIdPath(baseDir) {
+    return path.join(baseDir ?? getDeviceDir(), INSTALL_ID_FILENAME);
+}
+/**
+ * Read or create the per-install random salt.
+ *
+ * On first call, generates a 32-byte random value and persists it.
+ * On subsequent calls, reads the persisted value.
+ *
+ * @param baseDir - Optional base directory (default: ~/.yokotoken)
+ * @returns The install ID as a hex string
+ */
+export function ensureInstallId(baseDir) {
+    const dir = baseDir ?? getDeviceDir();
+    const idPath = getInstallIdPath(dir);
+    if (existsSync(idPath)) {
+        return readFileSync(idPath, 'utf-8').trim();
+    }
+    // Create directory if needed
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    const installId = randomBytes(INSTALL_ID_BYTES).toString('hex');
+    writeFileSync(idPath, installId + '\n', 'utf-8');
+    return installId;
+}
+// ─── Machine Identity ──────────────────────────────────────────────
+/**
+ * Collect machine identity components.
+ *
+ * Returns a deterministic string derived from the machine's hostname,
+ * OS platform, and current username. This provides a "best effort"
+ * machine identity that is stable across restarts.
+ *
+ * @returns A colon-separated identity string
+ */
+export function getMachineIdentity() {
+    const host = hostname();
+    const os = platform();
+    let username;
+    try {
+        username = userInfo().username;
+    }
+    catch {
+        // userInfo() can throw on some systems (e.g., containers without /etc/passwd)
+        username = process.env.USER || process.env.USERNAME || 'unknown';
+    }
+    return `${host}:${os}:${username}`;
+}
+// ─── Fingerprint Generation ─────────────────────────────────────────
+/**
+ * Generate a stable device fingerprint.
+ *
+ * The fingerprint is a SHA-256 hash of:
+ *   machineIdentity + ":" + installId
+ *
+ * Properties:
+ * - Deterministic: same machine + same install-id = same fingerprint
+ * - Unique across machines: different hostname/OS/username = different hash
+ * - Unique across installs: different install-id = different hash (even on same machine)
+ * - Not reversible: SHA-256 hash cannot reveal machine details
+ *
+ * @param baseDir - Optional base directory for the install-id file (default: ~/.yokotoken)
+ * @returns A 64-character hex string (SHA-256 hash)
+ */
+export function generateDeviceFingerprint(baseDir) {
+    const machineId = getMachineIdentity();
+    const installId = ensureInstallId(baseDir);
+    const input = `${machineId}:${installId}`;
+    return createHash('sha256').update(input).digest('hex');
+}
+/**
+ * Generate a user-friendly device name from system info.
+ *
+ * Format: "{username}@{hostname}" — human-readable but not guaranteed unique.
+ * Used as the default display name for a device in the known_devices registry.
+ *
+ * @returns A human-friendly device name string
+ */
+export function getDefaultDeviceName() {
+    const host = hostname();
+    let username;
+    try {
+        username = userInfo().username;
+    }
+    catch {
+        username = process.env.USER || process.env.USERNAME || 'unknown';
+    }
+    return `${username}@${host}`;
+}
+//# sourceMappingURL=fingerprint.js.map

package/dist/signatures/fingerprint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.js","sourceRoot":"","sources":["../../src/signatures/fingerprint.ts"],"names":[],"mappings":"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"}

package/dist/signatures/guard.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Device approval guard for unotoken.
+ *
+ * This module provides a guard that checks whether the current device is
+ * approved before allowing vault operations. It integrates:
+ * - Device fingerprinting (fingerprint.ts)
+ * - Known devices registry (devices.ts)
+ * - Email configuration (email-config.ts)
+ * - Approval codes (approval-codes.ts)
+ * - Email sending (resend.ts)
+ *
+ * The guard runs BEFORE vault unlock -- a new device cannot even attempt
+ * to unlock without approval.
+ *
+ * Usage patterns:
+ * 1. CLI (TTY): Prompts interactively for the 6-digit code
+ * 2. SDK (programmatic): Throws DeviceApprovalRequired with instructions
+ *
+ * Graceful degradation: If no email is configured, the guard allows the
+ * operation to proceed (signatures are opt-in via email config).
+ *
+ * @module
+ */
+export interface DeviceGuardOptions {
+    /** Base directory for config/database files (default: ~/.yokotoken) */
+    baseDir?: string;
+    /** Whether running in a TTY context (can prompt user). Default: auto-detect from process.stdin */
+    isTTY?: boolean;
+    /** Function to read a line from the user (for TTY prompting). Injected for testability. */
+    readLine?: (prompt: string) => Promise<string>;
+    /** Function to write output (for TTY messaging). Injected for testability. */
+    writeOutput?: (message: string) => void;
+    /** Function to write error output. Injected for testability. */
+    writeError?: (message: string) => void;
+}
+export interface DeviceGuardResult {
+    /** Whether the operation should proceed */
+    allowed: boolean;
+    /** Whether the device was newly approved during this check */
+    newlyApproved: boolean;
+    /** Whether the device was auto-approved (first device, no email needed) */
+    autoApproved: boolean;
+    /** Device name (for display) */
+    deviceName: string;
+    /** Device fingerprint */
+    fingerprint: string;
+    /** Reason the operation was blocked (if allowed = false) */
+    reason?: string;
+}
+/**
+ * Error thrown when a device requires approval but is used programmatically
+ * (no TTY to prompt the user).
+ *
+ * The caller (app/cloud service) is responsible for:
+ * 1. Sending the code via approveDevice()
+ * 2. Collecting the code from the user
+ * 3. Calling completeApproval() with the code
+ */
+export declare class DeviceApprovalRequired extends Error {
+    /** The device fingerprint that needs approval */
+    fingerprint: string;
+    /** The masked email where the code was sent (or null if not sent) */
+    maskedEmail: string | null;
+    /** Whether a code was actually sent */
+    codeSent: boolean;
+    constructor(fingerprint: string, maskedEmail: string | null, codeSent: boolean);
+}
+/**
+ * Check if the current device is approved and handle the approval flow.
+ *
+ * This is the main entry point for device checks. It should be called
+ * before any vault operation (unlock, get, set, list).
+ *
+ * Flow:
+ * 1. Generate device fingerprint
+ * 2. Check if device is known (auto-approves first device)
+ * 3. If known: allow operation, update last_seen
+ * 4. If unknown:
+ *    a. If no email configured: allow (graceful degradation)
+ *    b. If TTY: send code, prompt user, verify, register device
+ *    c. If no TTY: throw DeviceApprovalRequired
+ *
+ * @param options - Guard configuration
+ * @returns Result indicating whether the operation should proceed
+ * @throws DeviceApprovalRequired when used programmatically and device is unknown
+ */
+export declare function deviceGuard(options?: DeviceGuardOptions): Promise<DeviceGuardResult>;
+/**
+ * Programmatically approve a device with an approval code.
+ *
+ * For use by SDK consumers who caught DeviceApprovalRequired and collected
+ * the code from the user via their own UI.
+ *
+ * @param fingerprint - The device fingerprint from the error
+ * @param code - The 6-digit code entered by the user
+ * @param baseDir - Optional base directory for config/database files
+ * @returns Object with `approved` boolean and optional `reason`
+ */
+export declare function approveDevice(fingerprint: string, code: string, baseDir?: string): Promise<{
+    approved: boolean;
+    deviceName: string;
+    reason?: string;
+}>;
+/**
+ * Send an approval code to the user's configured email for a specific device.
+ *
+ * For use by SDK consumers who need to initiate the approval flow programmatically.
+ *
+ * @param fingerprint - The device fingerprint
+ * @param baseDir - Optional base directory for config/database files
+ * @returns Object with `sent` boolean, `maskedEmail`, and optional `error`
+ */
+export declare function sendDeviceApprovalCode(fingerprint: string, baseDir?: string): Promise<{
+    sent: boolean;
+    maskedEmail?: string;
+    error?: string;
+}>;
+//# sourceMappingURL=guard.d.ts.map

package/dist/signatures/guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../src/signatures/guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAUH,MAAM,WAAW,kBAAkB;IACjC,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kGAAkG;IAClG,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,2FAA2F;IAC3F,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/C,8EAA8E;IAC9E,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,gEAAgE;IAChE,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACxC;AAED,MAAM,WAAW,iBAAiB;IAChC,2CAA2C;IAC3C,OAAO,EAAE,OAAO,CAAC;IACjB,8DAA8D;IAC9D,aAAa,EAAE,OAAO,CAAC;IACvB,2EAA2E;IAC3E,YAAY,EAAE,OAAO,CAAC;IACtB,gCAAgC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,yBAAyB;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAID;;;;;;;;GAQG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,uCAAuC;IACvC,QAAQ,EAAE,OAAO,CAAC;gBAGhB,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,GAAG,IAAI,EAC1B,QAAQ,EAAE,OAAO;CAcpB;AAID;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,WAAW,CAC/B,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,iBAAiB,CAAC,CAwF5B;AAgJD;;;;;;;;;;GAUG;AACH,wBAAsB,aAAa,CACjC,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAsBrE;AAED;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAC1C,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA6ClE"}