agentvault 1.0.2 → 1.0.5

package/dist/src/security/mfa-approval.d.ts

@@ -0,0 +1,219 @@
+/**
+ * Multi-Factor Agent Approval (human-approve protocol)
+ *
+ * Five-layer defence for every agent approval request:
+ *
+ *  1. TOTP + nonce chain
+ *     The agent generates its own TOTP seed once per branch (never transmitted).
+ *     Each challenge carries:
+ *       • currentNonce — monotonically incrementing counter (single-use)
+ *       • challengeHash — SHA-256(nonce ‖ branchId ‖ timestamp)
+ *     The approver replies: "APPROVE <TOTP-code> <nonce>"
+ *     The agent verifies the code against the stored seed and checks the nonce.
+ *     Replay protection: nonce is written to a used-set immediately after success.
+ *
+ *  2. Biometric fallback (WebAuthn / Secure Enclave)
+ *     When TOTP is unavailable, the approver signs the challengeHash with a
+ *     device-bound P-256 key (simulating iOS Face ID / Android fingerprint).
+ *     The private key never leaves the local Secure Enclave equivalent; only
+ *     the ECDSA signature is transmitted.  Verified against the enrolled public key.
+ *
+ *  3. One-time link (60 s)
+ *     Each challenge also generates a short-lived URL:
+ *       https://agentvault.approve/<requestId>?token=<hex>
+ *     Token = HMAC-SHA256(requestId ‖ nonce ‖ expiresAt, linkSigningKey)
+ *     The link dies on first use or after 60 seconds — whichever comes first.
+ *
+ *  4. Rate limiting
+ *     Max 3 successful approvals per signer per rolling hour.
+ *     Excess attempts are rejected and logged.
+ *
+ *  5. Anomaly detection
+ *     Each approver device has a fingerprint = SHA-256(hostname ‖ platform ‖ arch)[:16].
+ *     First approval from a new fingerprint for a known signer triggers:
+ *       • branch auto-lock
+ *       • anomaly-detected audit entry
+ *       • "Was this you?" ping flag stored in the audit entry (detail field)
+ *     The operator must call unlockBranch() with a fresh TOTP code to resume.
+ *     Replying YES via TOTP to the anomaly ping registers the device as trusted.
+ *
+ *  6. Audit log (local + ICP)
+ *     Every event (setup, challenge, approve, reject, anomaly, lock) is appended to
+ *     ~/.agentvault/mfa/audit-<branchId>.yaml for local forensics AND submitted
+ *     asynchronously to the ICP canister for tamper-evident on-chain storage.
+ *     The verifyMfaApproval() return value includes an auditToken
+ *     (HMAC over the approval payload) suitable for on-chain verification.
+ */
+import { type WebAuthnAssertion } from './webauthn.js';
+/** Result of setupMfa() — share the otpAuthUri with the approver once. */
+export interface MfaSetup {
+    branchId: string;
+    /** Base32-encoded TOTP secret — display once, then keep offline. */
+    totpSecretB32: string;
+    /** Scan this URI as a QR code in Authy / Google Authenticator. */
+    otpAuthUri: string;
+    createdAt: string;
+}
+/** Challenge issued to the approver for a specific request. */
+export interface MfaChallenge {
+    requestId: string;
+    branchId: string;
+    /** Monotonically incrementing, single-use nonce (stored on ICP in production). */
+    nonce: number;
+    timestamp: string;
+    /** SHA-256(nonce ‖ branchId ‖ timestamp) — binds the approval to this exact moment. */
+    challengeHash: string;
+    /** One-time approval URL — valid for 60 seconds or first click. */
+    approvalLink: string;
+    expiresAt: string;
+}
+/** Input for verifyMfaApproval() — TOTP path. */
+export interface MfaVerifyInput {
+    requestId: string;
+    branchId: string;
+    /** 6-digit TOTP code from the authenticator app. */
+    totpCode: string;
+    /** Nonce that was issued in the challenge (must match currentNonce). */
+    nonce: number;
+    /** Optional: override the auto-detected device fingerprint. */
+    deviceFingerprint?: string;
+}
+/** Input for verifyBiometricApproval() — biometric / WebAuthn path. */
+export interface MfaBiometricInput {
+    requestId: string;
+    branchId: string;
+    /** The challengeHash from issueChallenge() that the device signed. */
+    challengeHash: string;
+    /** WebAuthn assertion produced by signChallenge(). */
+    assertion: WebAuthnAssertion;
+    /** Nonce that was issued in the challenge (must match currentNonce). */
+    nonce: number;
+    /** Device fingerprint that owns the biometric credential. */
+    deviceFingerprint?: string;
+}
+/** Discriminated union returned by verifyMfaApproval() and verifyBiometricApproval(). */
+export type MfaVerifyResult = {
+    ok: true;
+    auditToken: string;
+    icpQueued?: boolean;
+} | {
+    ok: false;
+    reason: 'invalid-totp' | 'nonce-mismatch' | 'nonce-replayed' | 'rate-limited' | 'anomaly' | 'not-setup' | 'branch-locked' | 'biometric-not-enrolled' | 'biometric-signature-invalid' | 'biometric-counter-replay';
+};
+/** Event kinds recorded in the audit log. */
+export type MfaAuditEventType = 'setup' | 'challenge-issued' | 'approved' | 'approved-biometric' | 'rejected' | 'rate-limit-exceeded' | 'anomaly-detected' | 'anomaly-ping-sent' | 'branch-locked' | 'branch-unlocked';
+/** One entry in the immutable audit log.  Suitable for forwarding to the ICP canister. */
+export interface MfaAuditEntry {
+    id: string;
+    requestId: string;
+    branchId: string;
+    event: MfaAuditEventType;
+    nonce?: number;
+    /** SHA-256(nonce ‖ branchId ‖ timestamp) */
+    challengeHash?: string;
+    /** HMAC audit token returned on successful approval */
+    auditToken?: string;
+    deviceFingerprint?: string;
+    timestamp: string;
+    detail?: string;
+}
+/** Current MFA posture for a branch (no secrets exposed). */
+export interface MfaStatus {
+    configured: boolean;
+    locked: boolean;
+    currentNonce: number;
+    usedNonceCount: number;
+    createdAt?: string;
+}
+/**
+ * Validate a one-time approval link token.
+ * Returns the associated requestId on success, or an error reason.
+ */
+export declare function validateOtpToken(token: string): {
+    ok: true;
+    requestId: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Compute the device fingerprint for the current machine.
+ * Uses hostname + OS platform + CPU architecture, hashed to a short hex token.
+ */
+export declare function getDeviceFingerprint(): string;
+/**
+ * Explicitly register a device fingerprint for a signer.
+ * Call this after the operator has confirmed a new-device alert via secondary TOTP.
+ */
+export declare function registerDevice(signer: string, fingerprint: string): void;
+/**
+ * Initialise MFA for a branch.
+ *
+ * Generates a fresh 20-byte TOTP secret, stores it encrypted on disk,
+ * and returns the otpauth:// URI to be scanned once by the approver.
+ *
+ * @param branchId - Unique branch / workflow identifier (e.g. "pending-001")
+ */
+export declare function setupMfa(branchId: string): MfaSetup;
+/**
+ * Issue a challenge for a pending approval request.
+ *
+ * Increments the branch nonce, computes the challenge hash, and generates
+ * a 60-second one-time approval link.  The approver must reply with:
+ *   APPROVE <TOTP-code> <nonce>
+ *
+ * @param requestId - Approval request identifier (e.g. "pending-001")
+ * @param branchId  - Branch that owns the TOTP seed
+ */
+export declare function issueChallenge(requestId: string, branchId: string): MfaChallenge;
+/**
+ * Verify a TOTP code + nonce submitted by the approver.
+ *
+ * Runs all five security layers in order:
+ *   1. MFA setup / branch-lock check
+ *   2. Nonce match + replay detection
+ *   3. TOTP verification (±1 window for clock drift)
+ *   4. Rate-limit check (3 / hour)
+ *   5. Device-fingerprint anomaly detection
+ *
+ * On success, marks the nonce as consumed, appends an audit entry,
+ * and returns a cryptographic auditToken suitable for on-chain logging.
+ */
+export declare function verifyMfaApproval(input: MfaVerifyInput): MfaVerifyResult;
+/**
+ * Verify a biometric (WebAuthn) assertion instead of a TOTP code.
+ *
+ * This is the Layer 2 fallback path: used when TOTP is unavailable or the
+ * approver's device natively supports WebAuthn (iOS Face ID, Android fingerprint,
+ * YubiKey, etc.).
+ *
+ * The flow:
+ *   1. Caller obtains a challengeHash from issueChallenge().
+ *   2. Device signs it via signChallenge() (or browser WebAuthn API).
+ *   3. This function verifies the ECDSA signature, nonce, rate-limit, and anomaly.
+ *   4. On success an auditToken is returned identical to the TOTP path.
+ *
+ * @param input - { requestId, branchId, challengeHash, assertion, nonce, deviceFingerprint? }
+ */
+export declare function verifyBiometricApproval(input: MfaBiometricInput): MfaVerifyResult;
+/**
+ * Unlock a branch after an anomaly has been investigated.
+ *
+ * Requires a valid TOTP code to prevent unauthorised unlocking.
+ * Optionally registers the new device fingerprint so future approvals succeed.
+ *
+ * @param branchId      - Branch to unlock
+ * @param totpCode      - Fresh 6-digit TOTP code from the authenticator app
+ * @param newFingerprint - If provided, add this fingerprint to the known-device list
+ */
+export declare function unlockBranch(branchId: string, totpCode: string, newFingerprint?: string): boolean;
+/**
+ * Return the complete audit log for a branch.
+ * Suitable for piping to the ICP canister or displaying with `approve mfa audit`.
+ */
+export declare function getMfaAuditLog(branchId: string): MfaAuditEntry[];
+/**
+ * Return the current MFA posture for a branch (no secrets exposed).
+ */
+export declare function getMfaStatus(branchId: string): MfaStatus;
+//# sourceMappingURL=mfa-approval.d.ts.map

package/dist/src/security/mfa-approval.d.ts.map

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