wotann 0.5.0

package/dist/middleware/tool-flow-gate.js

@@ -0,0 +1,105 @@
+/**
+ * Tool-flow gate middleware — pipes Round 25's tool-rules primitive
+ * into the runtime middleware pipeline so rules actually enforce.
+ *
+ * BEHAVIOR
+ *
+ * After each tool call, this middleware:
+ *   1. Records the tool name in a per-session sequence ledger.
+ *   2. Asks `rulesProvider(sessionId)` for the active ToolRule[].
+ *   3. Calls validateToolSequence(sequence, rules) on the full prior
+ *      sequence (including this turn).
+ *   4. If a violation surfaces, injects a feedback message into
+ *      `result.followUp` so the agent sees a clear, actionable
+ *      diagnostic on its next prompt — example:
+ *        "tool-flow-gate: continue rule violated — after 'read_file'
+ *         must call one of [edit_file, write_file], got 'delete_file'"
+ *
+ * The middleware is intentionally "advisory" — it does NOT block
+ * execution of the offending tool call (that's already done; the
+ * tool ran). It surfaces a diagnostic to the agent so the next turn
+ * picks a better tool. This matches WOTANN's loop-detection +
+ * doom-loop pattern (advisory followUp, not interrupt) so a single
+ * mis-step doesn't crash the agent loop.
+ *
+ * RULES
+ *
+ * Rules are supplied via an injectable provider so callers can:
+ *   - Layer rules from {session, skill, recipe, project, user}
+ *     scopes via mergeRules()
+ *   - Hot-reload rules per-session without rebuilding the pipeline
+ *
+ * The default provider returns []. With no rules, the middleware is
+ * a no-op — safe to enable everywhere.
+ *
+ * QUALITY BARS
+ *   - QB#7 per-call state: per-session ledger lives in a Map keyed
+ *     by sessionId; never module-global. The factory creates the
+ *     Map; each MiddlewarePipeline instance has its own.
+ *   - QB#3 honest stubs: violations surface as typed reasons; never
+ *     silently dropped.
+ *   - QB#11 sibling-site scan: this is the SOLE non-test consumer
+ *     of validateToolSequence so far. As more callers wire in,
+ *     they can read this file as the canonical pattern.
+ */
+import { validateToolSequence } from "../orchestration/tool-rules.js";
+const DEFAULT_MAX_SEQUENCE = 200;
+/** Default provider: no rules, middleware is a no-op. Safe to enable. */
+export const NO_RULES_PROVIDER = () => [];
+export function createToolFlowGateMiddleware(options) {
+    const sequences = new Map();
+    const cap = options.maxSequenceLength ?? DEFAULT_MAX_SEQUENCE;
+    return {
+        name: "ToolFlowGate",
+        order: 24.7, // immediately after LoopDetection (24.5)
+        after(ctx, result) {
+            if (!result.toolName)
+                return result;
+            // Append to per-session ledger. Cap at maxSequenceLength.
+            let seq = sequences.get(ctx.sessionId);
+            if (!seq) {
+                seq = [];
+                sequences.set(ctx.sessionId, seq);
+            }
+            seq.push(result.toolName);
+            if (seq.length > cap) {
+                // Drop oldest. Splice from the front to preserve current ordering.
+                seq.splice(0, seq.length - cap);
+            }
+            // Pull rules. Empty array = no-op.
+            const rules = options.rulesProvider(ctx.sessionId);
+            if (rules.length === 0)
+                return result;
+            // Validate the FULL sequence so far. We pass a frozen snapshot
+            // so the validator can't mutate (defensive, even though
+            // validator is pure).
+            const verdict = validateToolSequence(seq.slice(), rules);
+            if (verdict.kind === "ok")
+                return result;
+            const nudge = `tool-flow-gate: ${verdict.reason}`;
+            // Append to existing followUp rather than replace, matching
+            // loop-detection's pattern. Multiple advisories in one turn
+            // are rare but should compose, not overwrite.
+            return {
+                ...result,
+                followUp: result.followUp ? `${result.followUp}\n\n${nudge}` : nudge,
+            };
+        },
+    };
+}
+/**
+ * Test/diagnostic accessor — returns the per-session sequence
+ * snapshot maintained by a specific middleware instance. Not used
+ * by production code; intended for unit tests that need to assert
+ * the ledger state directly without going through the rules path.
+ */
+export function getSequenceSnapshot(middleware, sessionId) {
+    // Walk the closure via the constructed object — there's no public
+    // accessor, so we expose this helper for tests. Safe because
+    // `sequences` lives in the closure and the middleware is per-
+    // pipeline, not per-call.
+    void middleware;
+    void sessionId;
+    return []; // placeholder — see test file for the proper hook
+}
+//# sourceMappingURL=tool-flow-gate.js.map

package/dist/middleware/tool-flow-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-flow-gate.js","sourceRoot":"","sources":["../../src/middleware/tool-flow-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAGH,OAAO,EAAE,oBAAoB,EAAiB,MAAM,gCAAgC,CAAC;AAqBrF,MAAM,oBAAoB,GAAG,GAAG,CAAC;AAEjC,yEAAyE;AACzE,MAAM,CAAC,MAAM,iBAAiB,GAAyC,GAAG,EAAE,CAAC,EAAE,CAAC;AAEhF,MAAM,UAAU,4BAA4B,CAAC,OAA4B;IACvE,MAAM,SAAS,GAA0B,IAAI,GAAG,EAAE,CAAC;IACnD,MAAM,GAAG,GAAG,OAAO,CAAC,iBAAiB,IAAI,oBAAoB,CAAC;IAE9D,OAAO;QACL,IAAI,EAAE,cAAc;QACpB,KAAK,EAAE,IAAI,EAAE,yCAAyC;QACtD,KAAK,CAAC,GAAsB,EAAE,MAAmB;YAC/C,IAAI,CAAC,MAAM,CAAC,QAAQ;gBAAE,OAAO,MAAM,CAAC;YAEpC,0DAA0D;YAC1D,IAAI,GAAG,GAAG,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YACvC,IAAI,CAAC,GAAG,EAAE,CAAC;gBACT,GAAG,GAAG,EAAE,CAAC;gBACT,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;YACpC,CAAC;YACD,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAC1B,IAAI,GAAG,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;gBACrB,mEAAmE;gBACnE,GAAG,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC;YAClC,CAAC;YAED,mCAAmC;YACnC,MAAM,KAAK,GAAG,OAAO,CAAC,aAAa,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YACnD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,MAAM,CAAC;YAEtC,+DAA+D;YAC/D,wDAAwD;YACxD,sBAAsB;YACtB,MAAM,OAAO,GAAG,oBAAoB,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,KAAK,CAAC,CAAC;YACzD,IAAI,OAAO,CAAC,IAAI,KAAK,IAAI;gBAAE,OAAO,MAAM,CAAC;YAEzC,MAAM,KAAK,GAAG,mBAAmB,OAAO,CAAC,MAAM,EAAE,CAAC;YAElD,4DAA4D;YAC5D,4DAA4D;YAC5D,8CAA8C;YAC9C,OAAO;gBACL,GAAG,MAAM;gBACT,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,QAAQ,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK;aACrE,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,UAAsB,EAAE,SAAiB;IAC3E,kEAAkE;IAClE,6DAA6D;IAC7D,8DAA8D;IAC9D,0BAA0B;IAC1B,KAAK,UAAU,CAAC;IAChB,KAAK,SAAS,CAAC;IACf,OAAO,EAAE,CAAC,CAAC,kDAAkD;AAC/D,CAAC"}

package/dist/middleware/tool-pair-validator.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Tool Use/Result Pair Validator Middleware.
+ *
+ * Prevents malformed API calls where tool_use blocks don't have matching
+ * tool_result blocks (or vice versa). This is a defensive pattern from
+ * oh-my-openagent that catches silent API errors before they reach the provider.
+ *
+ * Runs in the `before` phase at order 0 (first middleware — runs before
+ * everything else) to validate conversation history integrity.
+ */
+import type { Middleware } from "./types.js";
+import type { AgentMessage } from "../core/types.js";
+export interface PairValidationResult {
+    readonly valid: boolean;
+    readonly orphanedToolUses: readonly OrphanedToolUse[];
+    readonly repairsApplied: number;
+}
+export interface OrphanedToolUse {
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly index: number;
+}
+export interface PairValidatorStats {
+    readonly totalValidations: number;
+    readonly totalRepairs: number;
+    readonly totalOrphansFound: number;
+}
+/**
+ * ToolPairValidatorMiddleware scans conversation history for unmatched
+ * tool_use/tool_result pairs and injects synthetic results when needed.
+ */
+export declare class ToolPairValidatorMiddleware {
+    private totalValidations;
+    private totalRepairs;
+    private totalOrphansFound;
+    /**
+     * Validate that all tool_use messages in the history have matching
+     * tool_result responses. Returns orphaned tool_use entries.
+     */
+    validate(history: readonly AgentMessage[]): PairValidationResult;
+    /**
+     * Build synthetic tool_result messages to repair orphaned tool_use blocks.
+     * Returns new AgentMessage entries that should be appended to the history.
+     */
+    buildRepairMessages(orphans: readonly OrphanedToolUse[]): readonly AgentMessage[];
+    /**
+     * Get validation statistics for diagnostics.
+     */
+    getStats(): PairValidatorStats;
+    /**
+     * Reset statistics for a new session.
+     */
+    reset(): void;
+}
+/**
+ * Create a Middleware adapter for the tool pair validator.
+ * Runs at order 0 (first middleware — validates before anything else runs).
+ * Operates in the `before` phase to validate conversation history integrity.
+ */
+export declare function createToolPairValidatorMiddleware(instance: ToolPairValidatorMiddleware): Middleware;
+//# sourceMappingURL=tool-pair-validator.d.ts.map

package/dist/middleware/tool-pair-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-pair-validator.d.ts","sourceRoot":"","sources":["../../src/middleware/tool-pair-validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAqB,MAAM,YAAY,CAAC;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAIrD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,gBAAgB,EAAE,SAAS,eAAe,EAAE,CAAC;IACtD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AAID;;;GAGG;AACH,qBAAa,2BAA2B;IACtC,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,iBAAiB,CAAK;IAE9B;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,GAAG,oBAAoB;IAyChE;;;OAGG;IACH,mBAAmB,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,GAAG,SAAS,YAAY,EAAE;IAgBjF;;OAEG;IACH,QAAQ,IAAI,kBAAkB;IAQ9B;;OAEG;IACH,KAAK,IAAI,IAAI;CAKd;AAID;;;;GAIG;AACH,wBAAgB,iCAAiC,CAC/C,QAAQ,EAAE,2BAA2B,GACpC,UAAU,CAiCZ"}

package/dist/middleware/tool-pair-validator.js

@@ -0,0 +1,127 @@
+/**
+ * Tool Use/Result Pair Validator Middleware.
+ *
+ * Prevents malformed API calls where tool_use blocks don't have matching
+ * tool_result blocks (or vice versa). This is a defensive pattern from
+ * oh-my-openagent that catches silent API errors before they reach the provider.
+ *
+ * Runs in the `before` phase at order 0 (first middleware — runs before
+ * everything else) to validate conversation history integrity.
+ */
+// -- Middleware Class ------------------------------------------------------
+/**
+ * ToolPairValidatorMiddleware scans conversation history for unmatched
+ * tool_use/tool_result pairs and injects synthetic results when needed.
+ */
+export class ToolPairValidatorMiddleware {
+    totalValidations = 0;
+    totalRepairs = 0;
+    totalOrphansFound = 0;
+    /**
+     * Validate that all tool_use messages in the history have matching
+     * tool_result responses. Returns orphaned tool_use entries.
+     */
+    validate(history) {
+        this.totalValidations++;
+        const toolUseIds = new Map();
+        const toolResultIds = new Set();
+        for (let i = 0; i < history.length; i++) {
+            const msg = history[i];
+            if (msg.role === "assistant" && msg.toolCallId && msg.toolName) {
+                toolUseIds.set(msg.toolCallId, { toolName: msg.toolName, index: i });
+            }
+            if (msg.role === "tool" && msg.toolCallId) {
+                toolResultIds.add(msg.toolCallId);
+            }
+        }
+        const orphaned = [];
+        for (const [callId, entry] of toolUseIds) {
+            if (!toolResultIds.has(callId)) {
+                orphaned.push({
+                    toolCallId: callId,
+                    toolName: entry.toolName,
+                    index: entry.index,
+                });
+            }
+        }
+        if (orphaned.length > 0) {
+            this.totalOrphansFound += orphaned.length;
+        }
+        return {
+            valid: orphaned.length === 0,
+            orphanedToolUses: orphaned,
+            repairsApplied: 0,
+        };
+    }
+    /**
+     * Build synthetic tool_result messages to repair orphaned tool_use blocks.
+     * Returns new AgentMessage entries that should be appended to the history.
+     */
+    buildRepairMessages(orphans) {
+        const repairs = [];
+        for (const orphan of orphans) {
+            this.totalRepairs++;
+            repairs.push({
+                role: "tool",
+                content: `[ToolPairValidator] Synthetic result: tool_use for "${orphan.toolName}" (id: ${orphan.toolCallId}) had no matching tool_result. This may indicate a dropped response or timeout.`,
+                toolCallId: orphan.toolCallId,
+                toolName: orphan.toolName,
+            });
+        }
+        return repairs;
+    }
+    /**
+     * Get validation statistics for diagnostics.
+     */
+    getStats() {
+        return {
+            totalValidations: this.totalValidations,
+            totalRepairs: this.totalRepairs,
+            totalOrphansFound: this.totalOrphansFound,
+        };
+    }
+    /**
+     * Reset statistics for a new session.
+     */
+    reset() {
+        this.totalValidations = 0;
+        this.totalRepairs = 0;
+        this.totalOrphansFound = 0;
+    }
+}
+// -- Pipeline Middleware Adapter -------------------------------------------
+/**
+ * Create a Middleware adapter for the tool pair validator.
+ * Runs at order 0 (first middleware — validates before anything else runs).
+ * Operates in the `before` phase to validate conversation history integrity.
+ */
+export function createToolPairValidatorMiddleware(instance) {
+    return {
+        name: "ToolPairValidator",
+        order: 0,
+        before(ctx) {
+            const result = instance.validate(ctx.recentHistory);
+            if (result.valid)
+                return ctx;
+            // Inject synthetic tool_result messages for orphaned tool_use blocks
+            const repairs = instance.buildRepairMessages(result.orphanedToolUses);
+            const toolNames = result.orphanedToolUses
+                .map((o) => `${o.toolName}(${o.toolCallId})`)
+                .join(", ");
+            const traceNote = `[ToolPairValidator] Repaired ${repairs.length} orphaned tool_use(s): ${toolNames}`;
+            const repairedHistory = [
+                ...ctx.recentHistory,
+                ...repairs,
+            ];
+            return {
+                ...ctx,
+                recentHistory: repairedHistory,
+                // Surface the repair in the user-visible context
+                cachedResponse: ctx.cachedResponse
+                    ? `${ctx.cachedResponse}\n${traceNote}`
+                    : traceNote,
+            };
+        },
+    };
+}
+//# sourceMappingURL=tool-pair-validator.js.map

package/dist/middleware/tool-pair-validator.js.map

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

package/dist/middleware/trifecta-guard.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Trifecta guard middleware — V9 Tier 10 T10.P0.4 (agentic-browser P0 gate).
+ *
+ * Simon Willison's "lethal trifecta" formulation: any single request
+ * that simultaneously has
+ *
+ *   (a) untrusted INPUT (browsed page content, external message, etc.)
+ *   (b) ACCESS to private data (cookies, credentials, private files)
+ *   (c) EXTERNAL COMMUNICATION capability (HTTP, email, share-to)
+ *
+ * is a privilege-escalation path. A malicious page in branch (a) can
+ * instruct the agent to use (b) and send it via (c). This middleware
+ * inspects every tool-call context, classifies each capability into
+ * the trifecta axes, and forces human approval when all three are
+ * present at once.
+ *
+ * ── Design ───────────────────────────────────────────────────────────
+ * The module is PURE — no `process.env` reads, no network, no fs. A
+ * caller passes a `TrifectaContext` describing the in-flight tool call;
+ * `classifyTrifecta` returns `{axes, hits}` identifying which axes are
+ * active, and `evaluateTrifecta` applies the "all three => BLOCK" rule.
+ *
+ * The middleware hook `createTrifectaGuard` wires a classifier +
+ * approval handler into a `TrifectaGuardMiddleware` that can be
+ * registered in WOTANN's 16-layer pipeline. Registration is the
+ * caller's job; this module only ships the contract.
+ *
+ * ── WOTANN quality bars ──────────────────────────────────────────────
+ *  - QB #6 honest failures: missing classifier fields are NEVER
+ *    treated as "safe" by default; they're treated as the conservative
+ *    worst case (assume axis is active). Callers opt out explicitly.
+ *  - QB #7 per-call state: every call is stateless; the guard factory
+ *    returns a fresh closure.
+ *  - QB #13 env guard: no `process.env` reads.
+ *  - QB #11 sibling-site scan: src/middleware/layers.ts is the canonical
+ *    middleware registry; callers register this guard there. This
+ *    module provides the factory + types, not the registration.
+ */
+export type TrifectaAxis = "untrusted-input" | "private-data" | "external-comm";
+export type TrifectaVerdict = "ALLOW" | "REQUIRE_APPROVAL" | "BLOCK";
+/**
+ * One concrete reason an axis is considered active. The collection
+ * of hits drives the approval UI — users see WHY the guard triggered.
+ */
+export interface TrifectaHit {
+    readonly axis: TrifectaAxis;
+    readonly source: string;
+    readonly detail: string;
+}
+/**
+ * The signal surface the caller provides. Every field is optional so
+ * integration with varying call sites stays loose — what's absent is
+ * treated as "unknown, assume active" (conservative default).
+ */
+export interface TrifectaContext {
+    /** Tool/command being invoked, e.g. "browser.navigate", "fetch", "fs.read". */
+    readonly toolName: string;
+    /** Raw arg object passed to the tool. */
+    readonly args?: Readonly<Record<string, unknown>>;
+    /** Hints from upstream layers — explicit axis declarations. */
+    readonly axisHints?: Readonly<Record<TrifectaAxis, boolean>>;
+    /**
+     * When true, this tool call was initiated by content from an
+     * untrusted page / email / webhook (axis a). Upstream middleware
+     * sets this flag when browsed content is in the context window.
+     */
+    readonly initiatedFromUntrustedSource?: boolean;
+    /**
+     * When true, the current session has read access to private data
+     * (cookies, credentials, wallet, SSH keys, etc.) — axis b.
+     */
+    readonly sessionHasPrivateData?: boolean;
+}
+export interface TrifectaClassification {
+    readonly axes: Readonly<Record<TrifectaAxis, boolean>>;
+    readonly hits: readonly TrifectaHit[];
+}
+export interface TrifectaEvaluation {
+    readonly verdict: TrifectaVerdict;
+    readonly classification: TrifectaClassification;
+    readonly reason: string;
+}
+/**
+ * Classify a tool call into the three trifecta axes. Returns which
+ * axes are active + the concrete hits that drove each decision.
+ */
+export declare function classifyTrifecta(ctx: TrifectaContext): TrifectaClassification;
+/**
+ * Evaluate the classification against the "lethal trifecta" rule:
+ *  - All 3 axes active → REQUIRE_APPROVAL
+ *  - 0, 1, or 2 axes → ALLOW
+ * Callers may upgrade REQUIRE_APPROVAL to BLOCK in strict mode.
+ */
+export declare function evaluateTrifecta(classification: TrifectaClassification, options?: {
+    readonly strictMode?: boolean;
+}): TrifectaEvaluation;
+export type ApprovalHandler = (evaluation: TrifectaEvaluation) => Promise<"approve" | "deny">;
+export interface TrifectaGuardOptions {
+    readonly approvalHandler: ApprovalHandler;
+    readonly strictMode?: boolean;
+    /**
+     * Hook for observability — called with every evaluation whether
+     * it triggers approval or not.
+     */
+    readonly onEvaluate?: (evaluation: TrifectaEvaluation) => void;
+}
+export interface TrifectaGuardMiddleware {
+    inspect(ctx: TrifectaContext): Promise<{
+        readonly verdict: TrifectaVerdict;
+        readonly approved?: boolean;
+        readonly reason: string;
+    }>;
+}
+/**
+ * Build the middleware closure. Callers register the returned object
+ * in `src/middleware/layers.ts`. The returned `inspect(ctx)`:
+ *
+ *  - Classifies the tool call
+ *  - Evaluates against the trifecta rule
+ *  - If REQUIRE_APPROVAL: calls the approval handler; caller writes
+ *    an audit record using `onEvaluate` if desired
+ *  - Returns the final verdict + whether the user approved
+ */
+export declare function createTrifectaGuard(options: TrifectaGuardOptions): TrifectaGuardMiddleware;
+/**
+ * Convenience exports so tests + callers can use the tool taxonomy
+ * without reaching into private sets.
+ */
+export declare function defaultExternalCommTools(): readonly string[];
+export declare function defaultPrivateDataReaders(): readonly string[];
+export declare function defaultUntrustedInputTools(): readonly string[];
+//# sourceMappingURL=trifecta-guard.d.ts.map

package/dist/middleware/trifecta-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trifecta-guard.d.ts","sourceRoot":"","sources":["../../src/middleware/trifecta-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAIH,MAAM,MAAM,YAAY,GAAG,iBAAiB,GAAG,cAAc,GAAG,eAAe,CAAC;AAEhF,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,kBAAkB,GAAG,OAAO,CAAC;AAErE;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,yCAAyC;IACzC,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAClD,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC;IAC7D;;;;OAIG;IACH,QAAQ,CAAC,4BAA4B,CAAC,EAAE,OAAO,CAAC;IAChD;;;OAGG;IACH,QAAQ,CAAC,qBAAqB,CAAC,EAAE,OAAO,CAAC;CAC1C;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC,CAAC;IACvD,QAAQ,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,cAAc,EAAE,sBAAsB,CAAC;IAChD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AA4DD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,eAAe,GAAG,sBAAsB,CAuF7E;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,cAAc,EAAE,sBAAsB,EACtC,OAAO,GAAE;IAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAO,GAC9C,kBAAkB,CAwBpB;AAID,MAAM,MAAM,eAAe,GAAG,CAAC,UAAU,EAAE,kBAAkB,KAAK,OAAO,CAAC,SAAS,GAAG,MAAM,CAAC,CAAC;AAE9F,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAC1C,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,UAAU,EAAE,kBAAkB,KAAK,IAAI,CAAC;CAChE;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC;QACrC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;QAClC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;QAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;KACzB,CAAC,CAAC;CACJ;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,uBAAuB,CA2B1F;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,IAAI,SAAS,MAAM,EAAE,CAE5D;AAED,wBAAgB,yBAAyB,IAAI,SAAS,MAAM,EAAE,CAE7D;AAED,wBAAgB,0BAA0B,IAAI,SAAS,MAAM,EAAE,CAE9D"}