@waiaas/daemon 2.0.0-rc.1

package/dist/workflow/approval-workflow.js

@@ -0,0 +1,202 @@
+/**
+ * ApprovalWorkflow - APPROVAL tier owner sign-off management.
+ *
+ * Manages APPROVAL tier transactions through their approval lifecycle:
+ * - requestApproval: creates pending_approvals record, sets tx QUEUED
+ * - approve: owner signs off, sets tx EXECUTING
+ * - reject: owner rejects, sets tx CANCELLED
+ * - processExpiredApprovals: batch-expire timed-out approvals
+ *
+ * Timeout resolution follows 3-level priority:
+ * 1. Policy-specific approval_timeout (from rules)
+ * 2. Config policy_defaults_approval_timeout (global config)
+ * 3. 3600s hardcoded fallback
+ *
+ * Uses BEGIN IMMEDIATE for atomic approve/reject/expire to prevent
+ * concurrent race conditions.
+ *
+ * @see docs/33-time-lock-approval-mechanism.md
+ */
+import { WAIaaSError } from '@waiaas/core';
+import { generateId } from '../infrastructure/database/id.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Hardcoded fallback approval timeout in seconds */
+const DEFAULT_APPROVAL_TIMEOUT = 3600;
+// ---------------------------------------------------------------------------
+// ApprovalWorkflow
+// ---------------------------------------------------------------------------
+export class ApprovalWorkflow {
+    sqlite;
+    configTimeout;
+    constructor(deps) {
+        this.sqlite = deps.sqlite;
+        this.configTimeout = deps.config.policy_defaults_approval_timeout;
+    }
+    // -------------------------------------------------------------------------
+    // requestApproval
+    // -------------------------------------------------------------------------
+    /**
+     * Create a pending approval for an APPROVAL tier transaction.
+     *
+     * Sets the transaction status to QUEUED and creates a pending_approvals
+     * record with an expiration time based on the 3-level timeout priority.
+     *
+     * @param txId - The transaction ID
+     * @param options - Optional policy-specific timeout
+     * @returns The approval ID and expiration timestamp
+     */
+    requestApproval(txId, options) {
+        const approvalId = generateId();
+        const now = Math.floor(Date.now() / 1000);
+        const timeout = this.resolveTimeout(options?.policyTimeoutSeconds);
+        const expiresAt = now + timeout;
+        const txn = this.sqlite.transaction(() => {
+            // Set transaction status to QUEUED
+            this.sqlite
+                .prepare('UPDATE transactions SET status = ? WHERE id = ?')
+                .run('QUEUED', txId);
+            // Create pending_approvals record
+            this.sqlite
+                .prepare(`INSERT INTO pending_approvals (id, tx_id, required_by, expires_at, created_at)
+           VALUES (?, ?, ?, ?, ?)`)
+                .run(approvalId, txId, now, expiresAt, now);
+        });
+        txn.immediate();
+        return { approvalId, expiresAt };
+    }
+    // -------------------------------------------------------------------------
+    // approve
+    // -------------------------------------------------------------------------
+    /**
+     * Approve a pending APPROVAL transaction with owner signature.
+     *
+     * Atomically validates the approval, sets approvedAt + ownerSignature,
+     * transitions the transaction to EXECUTING, and clears reserved_amount.
+     *
+     * @param txId - The transaction ID
+     * @param ownerSignature - The owner's cryptographic signature
+     * @returns The transaction ID and approval timestamp
+     * @throws WAIaaSError APPROVAL_NOT_FOUND if no pending approval exists
+     * @throws WAIaaSError APPROVAL_TIMEOUT if the approval has expired
+     */
+    approve(txId, ownerSignature) {
+        const txn = this.sqlite.transaction(() => {
+            // Find pending approval
+            const approval = this.sqlite
+                .prepare(`SELECT id, tx_id, expires_at, approved_at, rejected_at
+           FROM pending_approvals
+           WHERE tx_id = ? AND approved_at IS NULL AND rejected_at IS NULL`)
+                .get(txId);
+            if (!approval) {
+                throw new WAIaaSError('APPROVAL_NOT_FOUND');
+            }
+            // Check expiration
+            const now = Math.floor(Date.now() / 1000);
+            if (approval.expires_at <= now) {
+                throw new WAIaaSError('APPROVAL_TIMEOUT');
+            }
+            // Set approvedAt + ownerSignature
+            this.sqlite
+                .prepare('UPDATE pending_approvals SET approved_at = ?, owner_signature = ? WHERE id = ?')
+                .run(now, ownerSignature, approval.id);
+            // Transition transaction to EXECUTING and clear reserved_amount + reserved_amount_usd
+            this.sqlite
+                .prepare('UPDATE transactions SET status = ?, reserved_amount = NULL, reserved_amount_usd = NULL WHERE id = ?')
+                .run('EXECUTING', txId);
+            return { txId, approvedAt: now };
+        });
+        return txn.immediate();
+    }
+    // -------------------------------------------------------------------------
+    // reject
+    // -------------------------------------------------------------------------
+    /**
+     * Reject a pending APPROVAL transaction.
+     *
+     * Atomically sets rejectedAt, transitions the transaction to CANCELLED,
+     * and clears reserved_amount.
+     *
+     * @param txId - The transaction ID
+     * @returns The transaction ID and rejection timestamp
+     * @throws WAIaaSError APPROVAL_NOT_FOUND if no pending approval exists
+     */
+    reject(txId) {
+        const txn = this.sqlite.transaction(() => {
+            // Find pending approval
+            const approval = this.sqlite
+                .prepare(`SELECT id, tx_id, expires_at, approved_at, rejected_at
+           FROM pending_approvals
+           WHERE tx_id = ? AND approved_at IS NULL AND rejected_at IS NULL`)
+                .get(txId);
+            if (!approval) {
+                throw new WAIaaSError('APPROVAL_NOT_FOUND');
+            }
+            const now = Math.floor(Date.now() / 1000);
+            // Set rejectedAt
+            this.sqlite
+                .prepare('UPDATE pending_approvals SET rejected_at = ? WHERE id = ?')
+                .run(now, approval.id);
+            // Transition transaction to CANCELLED and clear reserved_amount + reserved_amount_usd
+            this.sqlite
+                .prepare('UPDATE transactions SET status = ?, reserved_amount = NULL, reserved_amount_usd = NULL WHERE id = ?')
+                .run('CANCELLED', txId);
+            return { txId, rejectedAt: now };
+        });
+        return txn.immediate();
+    }
+    // -------------------------------------------------------------------------
+    // processExpiredApprovals
+    // -------------------------------------------------------------------------
+    /**
+     * Batch-expire pending approvals that have exceeded their timeout.
+     *
+     * For each expired approval: sets the transaction status to EXPIRED and
+     * clears reserved_amount. Does NOT set rejectedAt (expired != rejected).
+     *
+     * @param now - Current Unix epoch seconds
+     * @returns Count of expired approvals
+     */
+    processExpiredApprovals(now) {
+        const txn = this.sqlite.transaction(() => {
+            // Find expired approvals
+            const expired = this.sqlite
+                .prepare(`SELECT id, tx_id
+           FROM pending_approvals
+           WHERE expires_at <= ? AND approved_at IS NULL AND rejected_at IS NULL`)
+                .all(now);
+            if (expired.length === 0) {
+                return 0;
+            }
+            // Batch update: set transaction EXPIRED + clear reserved_amount + reserved_amount_usd
+            const updateTx = this.sqlite.prepare('UPDATE transactions SET status = ?, reserved_amount = NULL, reserved_amount_usd = NULL WHERE id = ?');
+            for (const row of expired) {
+                updateTx.run('EXPIRED', row.tx_id);
+            }
+            // Note: We intentionally do NOT set rejectedAt on the approval records.
+            // Expired != rejected. The approval simply timed out.
+            return expired.length;
+        });
+        return txn.immediate();
+    }
+    // -------------------------------------------------------------------------
+    // Private: Timeout resolution
+    // -------------------------------------------------------------------------
+    /**
+     * Resolve approval timeout with 3-level priority:
+     * 1. Policy-specific timeout (from options)
+     * 2. Config timeout (policy_defaults_approval_timeout)
+     * 3. 3600 hardcoded fallback
+     */
+    resolveTimeout(policyTimeoutSeconds) {
+        if (policyTimeoutSeconds !== undefined && policyTimeoutSeconds > 0) {
+            return policyTimeoutSeconds;
+        }
+        if (this.configTimeout !== undefined && this.configTimeout > 0) {
+            return this.configTimeout;
+        }
+        return DEFAULT_APPROVAL_TIMEOUT;
+    }
+}
+//# sourceMappingURL=approval-workflow.js.map

package/dist/workflow/approval-workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-workflow.js","sourceRoot":"","sources":["../../src/workflow/approval-workflow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAC;AAG9D,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,qDAAqD;AACrD,MAAM,wBAAwB,GAAG,IAAI,CAAC;AAyCtC,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E,MAAM,OAAO,gBAAgB;IACV,MAAM,CAAiB;IACvB,aAAa,CAAS;IAEvC,YAAY,IAA0B;QACpC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,MAAM,CAAC,gCAAgC,CAAC;IACpE,CAAC;IAED,4EAA4E;IAC5E,kBAAkB;IAClB,4EAA4E;IAE5E;;;;;;;;;OASG;IACH,eAAe,CAAC,IAAY,EAAE,OAAgC;QAC5D,MAAM,UAAU,GAAG,UAAU,EAAE,CAAC;QAChC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;QAC1C,MAAM,OAAO,GAAG,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE,oBAAoB,CAAC,CAAC;QACnE,MAAM,SAAS,GAAG,GAAG,GAAG,OAAO,CAAC;QAEhC,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE;YACvC,mCAAmC;YACnC,IAAI,CAAC,MAAM;iBACR,OAAO,CAAC,iDAAiD,CAAC;iBAC1D,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;YAEvB,kCAAkC;YAClC,IAAI,CAAC,MAAM;iBACR,OAAO,CACN;kCACwB,CACzB;iBACA,GAAG,CAAC,UAAU,EAAE,IAAI,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC;QAChD,CAAC,CAAC,CAAC;QAEH,GAAG,CAAC,SAAS,EAAE,CAAC;QAEhB,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC;IACnC,CAAC;IAED,4EAA4E;IAC5E,UAAU;IACV,4EAA4E;IAE5E;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,IAAY,EAAE,cAAsB;QAC1C,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE;YACvC,wBAAwB;YACxB,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM;iBACzB,OAAO,CACN;;2EAEiE,CAClE;iBACA,GAAG,CAAC,IAAI,CAAmC,CAAC;YAE/C,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,MAAM,IAAI,WAAW,CAAC,oBAAoB,CAAC,CAAC;YAC9C,CAAC;YAED,mBAAmB;YACnB,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;YAC1C,IAAI,QAAQ,CAAC,UAAU,IAAI,GAAG,EAAE,CAAC;gBAC/B,MAAM,IAAI,WAAW,CAAC,kBAAkB,CAAC,CAAC;YAC5C,CAAC;YAED,kCAAkC;YAClC,IAAI,CAAC,MAAM;iBACR,OAAO,CACN,gFAAgF,CACjF;iBACA,GAAG,CAAC,GAAG,EAAE,cAAc,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC;YAEzC,sFAAsF;YACtF,IAAI,CAAC,MAAM;iBACR,OAAO,CACN,qGAAqG,CACtG;iBACA,GAAG,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;YAE1B,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC;QACnC,CAAC,CAAC,CAAC;QAEH,OAAO,GAAG,CAAC,SAAS,EAAE,CAAC;IACzB,CAAC;IAED,4EAA4E;IAC5E,SAAS;IACT,4EAA4E;IAE5E;;;;;;;;;OASG;IACH,MAAM,CAAC,IAAY;QACjB,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE;YACvC,wBAAwB;YACxB,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM;iBACzB,OAAO,CACN;;2EAEiE,CAClE;iBACA,GAAG,CAAC,IAAI,CAAmC,CAAC;YAE/C,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,MAAM,IAAI,WAAW,CAAC,oBAAoB,CAAC,CAAC;YAC9C,CAAC;YAED,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;YAE1C,iBAAiB;YACjB,IAAI,CAAC,MAAM;iBACR,OAAO,CAAC,2DAA2D,CAAC;iBACpE,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC;YAEzB,sFAAsF;YACtF,IAAI,CAAC,MAAM;iBACR,OAAO,CACN,qGAAqG,CACtG;iBACA,GAAG,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;YAE1B,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC;QACnC,CAAC,CAAC,CAAC;QAEH,OAAO,GAAG,CAAC,SAAS,EAAE,CAAC;IACzB,CAAC;IAED,4EAA4E;IAC5E,0BAA0B;IAC1B,4EAA4E;IAE5E;;;;;;;;OAQG;IACH,uBAAuB,CAAC,GAAW;QACjC,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE;YACvC,yBAAyB;YACzB,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM;iBACxB,OAAO,CACN;;iFAEuE,CACxE;iBACA,GAAG,CAAC,GAAG,CAAyC,CAAC;YAEpD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACzB,OAAO,CAAC,CAAC;YACX,CAAC;YAED,sFAAsF;YACtF,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAClC,qGAAqG,CACtG,CAAC;YAEF,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;gBAC1B,QAAQ,CAAC,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;YACrC,CAAC;YAED,wEAAwE;YACxE,sDAAsD;YAEtD,OAAO,OAAO,CAAC,MAAM,CAAC;QACxB,CAAC,CAAC,CAAC;QAEH,OAAO,GAAG,CAAC,SAAS,EAAE,CAAC;IACzB,CAAC;IAED,4EAA4E;IAC5E,8BAA8B;IAC9B,4EAA4E;IAE5E;;;;;OAKG;IACK,cAAc,CAAC,oBAA6B;QAClD,IAAI,oBAAoB,KAAK,SAAS,IAAI,oBAAoB,GAAG,CAAC,EAAE,CAAC;YACnE,OAAO,oBAAoB,CAAC;QAC9B,CAAC;QACD,IAAI,IAAI,CAAC,aAAa,KAAK,SAAS,IAAI,IAAI,CAAC,aAAa,GAAG,CAAC,EAAE,CAAC;YAC/D,OAAO,IAAI,CAAC,aAAa,CAAC;QAC5B,CAAC;QACD,OAAO,wBAAwB,CAAC;IAClC,CAAC;CACF"}

package/dist/workflow/delay-queue.d.ts

@@ -0,0 +1,78 @@
+/**
+ * DelayQueue - manages DELAY tier transaction cooldown lifecycle.
+ *
+ * The DELAY tier is the second layer of the 3-tier security model.
+ * Transactions above a configurable threshold must wait before execution,
+ * giving the owner time to cancel suspicious activity.
+ *
+ * Lifecycle: PENDING -> QUEUED (with cooldown) -> EXECUTING (auto-execute after expiry)
+ *                                              -> CANCELLED (owner cancels during cooldown)
+ *
+ * Uses BEGIN IMMEDIATE for processExpired to prevent concurrent processing
+ * of the same transaction.
+ *
+ * @see docs/33-time-lock-approval-mechanism.md
+ */
+import type { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3';
+import type { Database as SQLiteDatabase } from 'better-sqlite3';
+import type * as schema from '../infrastructure/database/schema.js';
+export interface DelayQueueDeps {
+    db: BetterSQLite3Database<typeof schema>;
+    sqlite: SQLiteDatabase;
+}
+export interface QueueResult {
+    queuedAt: number;
+    expiresAt: number;
+}
+export interface ExpiredTransaction {
+    txId: string;
+    walletId: string;
+}
+/**
+ * Manages DELAY tier transaction cooldown: queue, cancel, auto-execute.
+ *
+ * Constructor takes dual DB pattern (Drizzle + raw better-sqlite3) same as
+ * DatabasePolicyEngine for BEGIN IMMEDIATE support.
+ */
+export declare class DelayQueue {
+    private readonly sqlite;
+    constructor(deps: DelayQueueDeps);
+    /**
+     * Queue a transaction for DELAY tier cooldown.
+     *
+     * Sets status to QUEUED, records queuedAt timestamp and delaySeconds in metadata.
+     *
+     * @param txId - Transaction ID to queue
+     * @param delaySeconds - Cooldown duration in seconds
+     * @returns { queuedAt, expiresAt } timestamps (Unix seconds)
+     */
+    queueDelay(txId: string, delaySeconds: number): QueueResult;
+    /**
+     * Cancel a QUEUED transaction during its cooldown window.
+     *
+     * Sets status to CANCELLED and clears reserved_amount.
+     *
+     * @param txId - Transaction ID to cancel
+     * @throws WAIaaSError TX_NOT_FOUND if transaction doesn't exist
+     * @throws WAIaaSError TX_ALREADY_PROCESSED if transaction is not QUEUED
+     */
+    cancelDelay(txId: string): void;
+    /**
+     * Find and transition expired QUEUED transactions to EXECUTING.
+     *
+     * Uses BEGIN IMMEDIATE to prevent concurrent processing of the same transaction.
+     * Reads delaySeconds from metadata JSON to calculate expiry.
+     *
+     * @param now - Current time in Unix seconds
+     * @returns Array of { txId, walletId } for pipeline to execute stages 5-6
+     */
+    processExpired(now: number): ExpiredTransaction[];
+    /**
+     * Check if a QUEUED transaction's cooldown has elapsed.
+     *
+     * @param txId - Transaction ID to check
+     * @returns true if cooldown has elapsed, false otherwise
+     */
+    isExpired(txId: string): boolean;
+}
+//# sourceMappingURL=delay-queue.d.ts.map

package/dist/workflow/delay-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delay-queue.d.ts","sourceRoot":"","sources":["../../src/workflow/delay-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACxE,OAAO,KAAK,EAAE,QAAQ,IAAI,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEjE,OAAO,KAAK,KAAK,MAAM,MAAM,sCAAsC,CAAC;AAMpE,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,qBAAqB,CAAC,OAAO,MAAM,CAAC,CAAC;IACzC,MAAM,EAAE,cAAc,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAMD;;;;;GAKG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;gBAE5B,IAAI,EAAE,cAAc;IAQhC;;;;;;;;OAQG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,WAAW;IAkC3D;;;;;;;;OAQG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IA8B/B;;;;;;;;OAQG;IACH,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,EAAE;IA+CjD;;;;;OAKG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;CAwBjC"}

package/dist/workflow/delay-queue.js

@@ -0,0 +1,174 @@
+/**
+ * DelayQueue - manages DELAY tier transaction cooldown lifecycle.
+ *
+ * The DELAY tier is the second layer of the 3-tier security model.
+ * Transactions above a configurable threshold must wait before execution,
+ * giving the owner time to cancel suspicious activity.
+ *
+ * Lifecycle: PENDING -> QUEUED (with cooldown) -> EXECUTING (auto-execute after expiry)
+ *                                              -> CANCELLED (owner cancels during cooldown)
+ *
+ * Uses BEGIN IMMEDIATE for processExpired to prevent concurrent processing
+ * of the same transaction.
+ *
+ * @see docs/33-time-lock-approval-mechanism.md
+ */
+import { WAIaaSError } from '@waiaas/core';
+// ---------------------------------------------------------------------------
+// DelayQueue
+// ---------------------------------------------------------------------------
+/**
+ * Manages DELAY tier transaction cooldown: queue, cancel, auto-execute.
+ *
+ * Constructor takes dual DB pattern (Drizzle + raw better-sqlite3) same as
+ * DatabasePolicyEngine for BEGIN IMMEDIATE support.
+ */
+export class DelayQueue {
+    sqlite;
+    constructor(deps) {
+        this.sqlite = deps.sqlite;
+    }
+    // -------------------------------------------------------------------------
+    // queueDelay
+    // -------------------------------------------------------------------------
+    /**
+     * Queue a transaction for DELAY tier cooldown.
+     *
+     * Sets status to QUEUED, records queuedAt timestamp and delaySeconds in metadata.
+     *
+     * @param txId - Transaction ID to queue
+     * @param delaySeconds - Cooldown duration in seconds
+     * @returns { queuedAt, expiresAt } timestamps (Unix seconds)
+     */
+    queueDelay(txId, delaySeconds) {
+        const queuedAt = Math.floor(Date.now() / 1000);
+        const expiresAt = queuedAt + delaySeconds;
+        // Read existing metadata and merge delaySeconds
+        const existing = this.sqlite
+            .prepare('SELECT metadata FROM transactions WHERE id = ?')
+            .get(txId);
+        let metadata = {};
+        if (existing?.metadata) {
+            try {
+                metadata = JSON.parse(existing.metadata);
+            }
+            catch {
+                // ignore parse errors, start fresh
+            }
+        }
+        metadata.delaySeconds = delaySeconds;
+        this.sqlite
+            .prepare(`UPDATE transactions
+         SET status = 'QUEUED', queued_at = ?, metadata = ?
+         WHERE id = ?`)
+            .run(queuedAt, JSON.stringify(metadata), txId);
+        return { queuedAt, expiresAt };
+    }
+    // -------------------------------------------------------------------------
+    // cancelDelay
+    // -------------------------------------------------------------------------
+    /**
+     * Cancel a QUEUED transaction during its cooldown window.
+     *
+     * Sets status to CANCELLED and clears reserved_amount.
+     *
+     * @param txId - Transaction ID to cancel
+     * @throws WAIaaSError TX_NOT_FOUND if transaction doesn't exist
+     * @throws WAIaaSError TX_ALREADY_PROCESSED if transaction is not QUEUED
+     */
+    cancelDelay(txId) {
+        const row = this.sqlite
+            .prepare('SELECT id, status FROM transactions WHERE id = ?')
+            .get(txId);
+        if (!row) {
+            throw new WAIaaSError('TX_NOT_FOUND', {
+                message: `Transaction ${txId} not found`,
+            });
+        }
+        if (row.status !== 'QUEUED') {
+            throw new WAIaaSError('TX_ALREADY_PROCESSED', {
+                message: `Transaction ${txId} is ${row.status}, not QUEUED`,
+            });
+        }
+        this.sqlite
+            .prepare(`UPDATE transactions
+         SET status = 'CANCELLED', reserved_amount = NULL
+         WHERE id = ?`)
+            .run(txId);
+    }
+    // -------------------------------------------------------------------------
+    // processExpired
+    // -------------------------------------------------------------------------
+    /**
+     * Find and transition expired QUEUED transactions to EXECUTING.
+     *
+     * Uses BEGIN IMMEDIATE to prevent concurrent processing of the same transaction.
+     * Reads delaySeconds from metadata JSON to calculate expiry.
+     *
+     * @param now - Current time in Unix seconds
+     * @returns Array of { txId, walletId } for pipeline to execute stages 5-6
+     */
+    processExpired(now) {
+        const sqlite = this.sqlite;
+        const txn = sqlite.transaction(() => {
+            // Select QUEUED transactions whose cooldown has elapsed.
+            // delaySeconds is stored in metadata JSON.
+            // Expiry check: queued_at + JSON_EXTRACT(metadata, '$.delaySeconds') <= now
+            const rows = sqlite
+                .prepare(`SELECT id, wallet_id
+           FROM transactions
+           WHERE status = 'QUEUED'
+             AND queued_at IS NOT NULL
+             AND metadata IS NOT NULL
+             AND (queued_at + CAST(JSON_EXTRACT(metadata, '$.delaySeconds') AS INTEGER)) <= ?`)
+                .all(now);
+            if (rows.length === 0) {
+                return [];
+            }
+            // Transition each expired transaction to EXECUTING
+            const updateStmt = sqlite.prepare(`UPDATE transactions SET status = 'EXECUTING' WHERE id = ? AND status = 'QUEUED'`);
+            const result = [];
+            for (const row of rows) {
+                const changes = updateStmt.run(row.id);
+                // Only include if we actually updated (guard against concurrent processing)
+                if (changes.changes > 0) {
+                    result.push({ txId: row.id, walletId: row.wallet_id });
+                }
+            }
+            return result;
+        });
+        // Execute with IMMEDIATE isolation
+        return txn.immediate();
+    }
+    // -------------------------------------------------------------------------
+    // isExpired
+    // -------------------------------------------------------------------------
+    /**
+     * Check if a QUEUED transaction's cooldown has elapsed.
+     *
+     * @param txId - Transaction ID to check
+     * @returns true if cooldown has elapsed, false otherwise
+     */
+    isExpired(txId) {
+        const row = this.sqlite
+            .prepare('SELECT queued_at, metadata FROM transactions WHERE id = ? AND status = ?')
+            .get(txId, 'QUEUED');
+        if (!row || !row.queued_at || !row.metadata) {
+            return false;
+        }
+        let metadata;
+        try {
+            metadata = JSON.parse(row.metadata);
+        }
+        catch {
+            return false;
+        }
+        const delaySeconds = metadata.delaySeconds;
+        if (typeof delaySeconds !== 'number') {
+            return false;
+        }
+        const now = Math.floor(Date.now() / 1000);
+        return (row.queued_at + delaySeconds) <= now;
+    }
+}
+//# sourceMappingURL=delay-queue.js.map

package/dist/workflow/delay-queue.js.map

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

package/dist/workflow/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Workflow module barrel export.
+ *
+ * Exports workflow services for DELAY and APPROVAL tier management.
+ */
+export { DelayQueue } from './delay-queue.js';
+export type { DelayQueueDeps, QueueResult, ExpiredTransaction } from './delay-queue.js';
+export { ApprovalWorkflow } from './approval-workflow.js';
+export { resolveOwnerState, OwnerLifecycleService, downgradeIfNoOwner, } from './owner-state.js';
+export type { OwnerState, OwnerLifecycleDeps } from './owner-state.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/workflow/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/workflow/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAExF,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/workflow/index.js

@@ -0,0 +1,9 @@
+/**
+ * Workflow module barrel export.
+ *
+ * Exports workflow services for DELAY and APPROVAL tier management.
+ */
+export { DelayQueue } from './delay-queue.js';
+export { ApprovalWorkflow } from './approval-workflow.js';
+export { resolveOwnerState, OwnerLifecycleService, downgradeIfNoOwner, } from './owner-state.js';
+//# sourceMappingURL=index.js.map

package/dist/workflow/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/workflow/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAG9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,kBAAkB,CAAC"}

package/dist/workflow/owner-state.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Owner 3-State Machine: NONE -> GRACE -> LOCKED.
+ *
+ * Manages the Owner lifecycle for wallets:
+ * - NONE: No owner registered. APPROVAL tier auto-downgrades to DELAY.
+ * - GRACE: Owner address set but not yet verified via signature.
+ *   Owner can be changed/removed with masterAuth only.
+ * - LOCKED: Owner verified via ownerAuth signature.
+ *   Owner change requires ownerAuth; removal blocked entirely.
+ *
+ * Provides:
+ * - resolveOwnerState(): pure function to determine state from wallet fields
+ * - OwnerLifecycleService: setOwner/removeOwner/markOwnerVerified with DB ops
+ * - downgradeIfNoOwner(): APPROVAL -> DELAY when no owner registered
+ *
+ * @see docs/34-owner-wallet-design.md
+ */
+import type { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3';
+import type { Database as SQLiteDatabase } from 'better-sqlite3';
+import type * as schema from '../infrastructure/database/schema.js';
+export type OwnerState = 'NONE' | 'GRACE' | 'LOCKED';
+interface WalletOwnerFields {
+    ownerAddress: string | null;
+    ownerVerified: boolean;
+}
+export interface OwnerLifecycleDeps {
+    db: BetterSQLite3Database<typeof schema>;
+    sqlite: SQLiteDatabase;
+}
+interface DowngradeResult {
+    tier: string;
+    downgraded: boolean;
+}
+/**
+ * Determine the Owner state from wallet fields.
+ *
+ * Pure function, no DB access, no side effects.
+ *
+ * @param wallet - Wallet fields { ownerAddress, ownerVerified }
+ * @returns 'NONE' | 'GRACE' | 'LOCKED'
+ */
+export declare function resolveOwnerState(wallet: WalletOwnerFields): OwnerState;
+/**
+ * Service managing Owner state transitions with DB persistence.
+ */
+export declare class OwnerLifecycleService {
+    private readonly sqlite;
+    constructor(deps: OwnerLifecycleDeps);
+    /**
+     * Set the owner address for a wallet.
+     *
+     * - NONE or GRACE: sets ownerAddress, ownerVerified = false
+     * - LOCKED: throws OWNER_ALREADY_CONNECTED
+     *
+     * @param walletId - Wallet ID
+     * @param ownerAddress - Owner wallet address to set
+     * @throws WAIaaSError OWNER_ALREADY_CONNECTED if in LOCKED state
+     */
+    setOwner(walletId: string, ownerAddress: string): void;
+    /**
+     * Remove the owner from a wallet.
+     *
+     * - GRACE: clears ownerAddress, ownerVerified = false
+     * - LOCKED: throws OWNER_ALREADY_CONNECTED
+     * - NONE: no-op (already no owner)
+     *
+     * @param walletId - Wallet ID
+     * @throws WAIaaSError OWNER_ALREADY_CONNECTED if in LOCKED state
+     */
+    removeOwner(walletId: string): void;
+    /**
+     * Mark the owner as verified (GRACE -> LOCKED transition).
+     *
+     * Called when ownerAuth middleware succeeds on any ownerAuth-protected route.
+     *
+     * - GRACE: sets ownerVerified = true
+     * - LOCKED: no-op (already verified)
+     * - NONE: throws OWNER_NOT_CONNECTED
+     *
+     * @param walletId - Wallet ID
+     * @throws WAIaaSError OWNER_NOT_CONNECTED if in NONE state
+     */
+    markOwnerVerified(walletId: string): void;
+    private getWalletRow;
+}
+/**
+ * If tier is APPROVAL and owner state is NONE, downgrade to DELAY.
+ *
+ * The caller should log a TX_DOWNGRADED_DELAY audit event when downgraded=true.
+ *
+ * @param wallet - Wallet fields for resolveOwnerState
+ * @param tier - Current policy tier
+ * @returns { tier, downgraded }
+ */
+export declare function downgradeIfNoOwner(wallet: WalletOwnerFields, tier: string): DowngradeResult;
+export {};
+//# sourceMappingURL=owner-state.d.ts.map

package/dist/workflow/owner-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"owner-state.d.ts","sourceRoot":"","sources":["../../src/workflow/owner-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACxE,OAAO,KAAK,EAAE,QAAQ,IAAI,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEjE,OAAO,KAAK,KAAK,MAAM,MAAM,sCAAsC,CAAC;AAMpE,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAErD,UAAU,iBAAiB;IACzB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,qBAAqB,CAAC,OAAO,MAAM,CAAC,CAAC;IACzC,MAAM,EAAE,cAAc,CAAC;CACxB;AAED,UAAU,eAAe;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,OAAO,CAAC;CACrB;AAMD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,UAAU,CAQvE;AAWD;;GAEG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;gBAE5B,IAAI,EAAE,kBAAkB;IAIpC;;;;;;;;;OASG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI;IAsBtD;;;;;;;;;OASG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IA2BnC;;;;;;;;;;;OAWG;IACH,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IA6BzC,OAAO,CAAC,YAAY;CAarB;AAMD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,iBAAiB,EAAE,IAAI,EAAE,MAAM,GAAG,eAAe,CAK3F"}