Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
docs(architecture): add issue 431 trigger rate-limit keying diagram
Alfredo Lopezfee4915101d4
diff --git a/docs/architecture/issue-431-workflow-trigger-rate-limit.png b/docs/architecture/issue-431-workflow-trigger-rate-limit.pngnew file mode 100644index 000000000..75f254dccBinary files /dev/null and b/docs/architecture/issue-431-workflow-trigger-rate-limit.png differdiff --git a/docs/architecture/issue-431-workflow-trigger-rate-limit.svg b/docs/architecture/issue-431-workflow-trigger-rate-limit.svgnew file mode 100644index 000000000..4304ece3c--- /dev/null+++ b/docs/architecture/issue-431-workflow-trigger-rate-limit.svg@@ -0,0 +1,169 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 940" role="img" aria-labelledby="title desc">+ <title id="title">Issue 431 - Current vs fixed workflow trigger rate-limit keying</title>+ <desc id="desc">external-rest-api always sends a service bearer and a user session token. On origin/dev the service bearer wins, so all users share one 10/min bucket. The fix keys on the verified Profile userId for the external lane and on the bearer only for mcp-host.</desc>+ <defs>+ <marker id="arrowBlue" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">+ <polygon points="0 0, 10 3.5, 0 7" fill="#2563eb"/>+ </marker>+ <marker id="arrowOrange" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">+ <polygon points="0 0, 10 3.5, 0 7" fill="#ea580c"/>+ </marker>+ <marker id="arrowGreen" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">+ <polygon points="0 0, 10 3.5, 0 7" fill="#059669"/>+ </marker>+ <marker id="arrowGray" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">+ <polygon points="0 0, 10 3.5, 0 7" fill="#6b7280"/>+ </marker>+ <style>+ .sans { font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif; }+ </style>+ </defs>++ <rect width="1200" height="940" fill="#ffffff"/>++ <text x="600" y="32" text-anchor="middle" class="sans" font-size="20" font-weight="700" fill="#111827">Issue 431 - Per-user workflow trigger rate limit</text>+ <text x="600" y="52" text-anchor="middle" class="sans" font-size="13" fill="#4b5563">External lane keys on verified userId. mcp-host lane keys on the bearer only.</text>++ <rect x="40" y="68" width="1120" height="148" rx="12" fill="#f8fafc" stroke="#cbd5e1" stroke-width="1.5" stroke-dasharray="6 4"/>+ <text x="56" y="88" class="sans" font-size="11" font-weight="700" fill="#64748b">PRODUCTION INGRESS - unchanged</text>++ <circle cx="96" cy="148" r="20" fill="#dbeafe" stroke="#2563eb" stroke-width="1.5"/>+ <circle cx="96" cy="141" r="6" fill="#1d4ed8"/>+ <path d="M85 166 C85 155 107 155 107 166" fill="none" stroke="#1d4ed8" stroke-width="2"/>+ <text x="96" y="188" text-anchor="middle" class="sans" font-size="12" font-weight="600" fill="#1e3a8a">User A</text>++ <circle cx="168" cy="148" r="20" fill="#dbeafe" stroke="#2563eb" stroke-width="1.5"/>+ <circle cx="168" cy="141" r="6" fill="#1d4ed8"/>+ <path d="M157 166 C157 155 179 155 179 166" fill="none" stroke="#1d4ed8" stroke-width="2"/>+ <text x="168" y="188" text-anchor="middle" class="sans" font-size="12" font-weight="600" fill="#1e3a8a">User B</text>++ <path d="M188 148 H220" stroke="#2563eb" stroke-width="2" fill="none" marker-end="url(#arrowBlue)"/>++ <rect x="228" y="116" width="248" height="64" rx="8" fill="#ffffff" stroke="#2563eb" stroke-width="1.5"/>+ <text x="352" y="142" text-anchor="middle" class="sans" font-size="13" font-weight="700" fill="#1e3a8a">external-rest-api</text>+ <text x="352" y="162" text-anchor="middle" class="sans" font-size="12" fill="#334155">Always sends BOTH headers</text>++ <path d="M476 148 H516" stroke="#2563eb" stroke-width="2.5" fill="none" marker-end="url(#arrowBlue)"/>+ <rect x="468" y="128" width="56" height="16" rx="3" fill="#f8fafc"/>+ <text x="496" y="140" text-anchor="middle" class="sans" font-size="11" fill="#1d4ed8">same req</text>++ <rect x="524" y="108" width="288" height="80" rx="8" fill="#eff6ff" stroke="#2563eb" stroke-width="1.5"/>+ <text x="668" y="132" text-anchor="middle" class="sans" font-size="12" font-weight="700" fill="#1e3a8a">Headers on every trigger</text>+ <text x="668" y="154" text-anchor="middle" class="sans" font-size="12" fill="#111827">Authorization: Bearer service</text>+ <text x="668" y="174" text-anchor="middle" class="sans" font-size="12" fill="#111827">x-user-session-token: user JWT</text>++ <path d="M812 148 H852" stroke="#6b7280" stroke-width="1.5" stroke-dasharray="4 2" fill="none" marker-end="url(#arrowGray)"/>++ <rect x="860" y="116" width="268" height="64" rx="8" fill="#ffffff" stroke="#64748b" stroke-width="1.5"/>+ <text x="994" y="142" text-anchor="middle" class="sans" font-size="13" font-weight="700" fill="#111827">control-api</text>+ <text x="994" y="162" text-anchor="middle" class="sans" font-size="12" fill="#4b5563">POST /external/.../trigger</text>++ <rect x="40" y="236" width="548" height="520" rx="12" fill="#fff7ed" stroke="#ea580c" stroke-width="1.5"/>+ <rect x="40" y="236" width="548" height="44" rx="12" fill="#ea580c"/>+ <rect x="40" y="264" width="548" height="16" fill="#ea580c"/>+ <text x="314" y="265" text-anchor="middle" class="sans" font-size="15" font-weight="700" fill="#ffffff">CURRENT on origin/dev - broken key order</text>++ <text x="64" y="308" class="sans" font-size="12" font-weight="700" fill="#9a3412">workflowTriggerRateLimitCredential()</text>++ <rect x="64" y="324" width="216" height="56" rx="8" fill="#fed7aa" stroke="#ea580c" stroke-width="2"/>+ <text x="172" y="346" text-anchor="middle" class="sans" font-size="13" font-weight="700" fill="#7c2d12">1. Service bearer WINS</text>+ <text x="172" y="366" text-anchor="middle" class="sans" font-size="11" fill="#9a3412">used even if user JWT is present</text>++ <path d="M172 380 V396" stroke="#ea580c" stroke-width="1.5" fill="none" marker-end="url(#arrowOrange)"/>++ <rect x="64" y="396" width="216" height="56" rx="8" fill="#ffffff" stroke="#fdba74" stroke-width="1.5"/>+ <text x="172" y="418" text-anchor="middle" class="sans" font-size="13" font-weight="600" fill="#78716c">2. User session token</text>+ <text x="172" y="438" text-anchor="middle" class="sans" font-size="11" fill="#a8a29e">skipped in production</text>++ <path d="M172 452 V468" stroke="#ea580c" stroke-width="1.5" fill="none" marker-end="url(#arrowOrange)"/>++ <rect x="64" y="468" width="216" height="56" rx="8" fill="#ffffff" stroke="#fdba74" stroke-width="1.5"/>+ <text x="172" y="490" text-anchor="middle" class="sans" font-size="13" font-weight="600" fill="#78716c">3. Admin cookie</text>+ <text x="172" y="510" text-anchor="middle" class="sans" font-size="11" fill="#a8a29e">Control UI fallback only</text>++ <path d="M280 352 H312" stroke="#ea580c" stroke-width="2" fill="none" marker-end="url(#arrowOrange)"/>+ <rect x="276" y="334" width="52" height="16" rx="3" fill="#fff7ed"/>+ <text x="302" y="346" text-anchor="middle" class="sans" font-size="11" fill="#c2410c">keys on 1</text>++ <rect x="320" y="324" width="244" height="56" rx="8" fill="#fee2e2" stroke="#dc2626" stroke-width="1.5"/>+ <text x="442" y="346" text-anchor="middle" class="sans" font-size="13" font-weight="700" fill="#991b1b">hash(service bearer)</text>+ <text x="442" y="366" text-anchor="middle" class="sans" font-size="11" fill="#b91c1c">same key for User A and User B</text>++ <path d="M442 380 V428" stroke="#ea580c" stroke-width="2" fill="none" marker-end="url(#arrowOrange)"/>++ <rect x="320" y="428" width="244" height="96" rx="8" fill="#fecaca" stroke="#dc2626" stroke-width="1.5"/>+ <text x="442" y="464" text-anchor="middle" class="sans" font-size="13" font-weight="700" fill="#7f1d1d">ONE PG bucket 10/min</text>+ <text x="442" y="488" text-anchor="middle" class="sans" font-size="12" fill="#991b1b">User A exhausts the shared quota</text>+ <text x="442" y="508" text-anchor="middle" class="sans" font-size="12" fill="#991b1b">User B is denied with 429</text>++ <rect x="64" y="676" width="500" height="56" rx="8" fill="#ffffff" stroke="#ea580c" stroke-width="1.5"/>+ <text x="314" y="698" text-anchor="middle" class="sans" font-size="13" font-weight="700" fill="#9a3412">Result: platform-wide fairness failure</text>+ <text x="314" y="718" text-anchor="middle" class="sans" font-size="12" fill="#c2410c">One noisy user blocks every other Profile user</text>++ <rect x="612" y="236" width="548" height="520" rx="12" fill="#ecfdf5" stroke="#059669" stroke-width="1.5"/>+ <rect x="612" y="236" width="548" height="44" rx="12" fill="#059669"/>+ <rect x="612" y="264" width="548" height="16" fill="#059669"/>+ <text x="886" y="265" text-anchor="middle" class="sans" font-size="15" font-weight="700" fill="#ffffff">NEW - verified userId + lane split</text>++ <text x="636" y="308" class="sans" font-size="12" font-weight="700" fill="#065f46">external: workflowTriggerRateLimitCredential()</text>++ <rect x="636" y="324" width="216" height="56" rx="8" fill="#86efac" stroke="#059669" stroke-width="2"/>+ <text x="744" y="346" text-anchor="middle" class="sans" font-size="13" font-weight="700" fill="#14532d">1. Verified userId</text>+ <text x="744" y="366" text-anchor="middle" class="sans" font-size="11" fill="#166534">user:claims.userId, not raw JWT</text>++ <path d="M744 380 V396" stroke="#059669" stroke-width="1.5" fill="none" marker-end="url(#arrowGreen)"/>++ <rect x="636" y="396" width="216" height="56" rx="8" fill="#ffffff" stroke="#6ee7b7" stroke-width="1.5"/>+ <text x="744" y="418" text-anchor="middle" class="sans" font-size="13" font-weight="600" fill="#065f46">2. Unverified session - IP</text>+ <text x="744" y="438" text-anchor="middle" class="sans" font-size="11" fill="#047857">rotation cannot mint a bucket</text>++ <path d="M744 452 V468" stroke="#059669" stroke-width="1.5" fill="none" marker-end="url(#arrowGreen)"/>++ <rect x="636" y="468" width="216" height="56" rx="8" fill="#ffffff" stroke="#6ee7b7" stroke-width="1.5"/>+ <text x="744" y="490" text-anchor="middle" class="sans" font-size="13" font-weight="600" fill="#065f46">3. Cookie, then bearer LAST</text>+ <text x="744" y="510" text-anchor="middle" class="sans" font-size="11" fill="#047857">only if no session header</text>++ <path d="M852 352 H884" stroke="#059669" stroke-width="2" fill="none" marker-end="url(#arrowGreen)"/>+ <rect x="848" y="334" width="52" height="16" rx="3" fill="#ecfdf5"/>+ <text x="874" y="346" text-anchor="middle" class="sans" font-size="11" fill="#047857">keys on 1</text>++ <rect x="892" y="324" width="244" height="200" rx="8" fill="#ffffff" stroke="#059669" stroke-width="1.5"/>+ <text x="1014" y="348" text-anchor="middle" class="sans" font-size="11" font-weight="700" fill="#047857">PER-ACCOUNT BUCKETS</text>++ <rect x="908" y="360" width="212" height="40" rx="6" fill="#d1fae5" stroke="#059669" stroke-width="1"/>+ <text x="1014" y="385" text-anchor="middle" class="sans" font-size="12" font-weight="700" fill="#065f46">hash(user:A)</text>++ <rect x="908" y="408" width="212" height="40" rx="6" fill="#d1fae5" stroke="#059669" stroke-width="1"/>+ <text x="1014" y="433" text-anchor="middle" class="sans" font-size="12" font-weight="700" fill="#065f46">hash(user:B)</text>++ <rect x="908" y="464" width="100" height="44" rx="6" fill="#bbf7d0" stroke="#059669" stroke-width="1"/>+ <text x="958" y="482" text-anchor="middle" class="sans" font-size="12" font-weight="700" fill="#14532d">Bucket A</text>+ <text x="958" y="498" text-anchor="middle" class="sans" font-size="11" fill="#166534">10/min A</text>++ <rect x="1020" y="464" width="100" height="44" rx="6" fill="#bbf7d0" stroke="#059669" stroke-width="1"/>+ <text x="1070" y="482" text-anchor="middle" class="sans" font-size="12" font-weight="700" fill="#14532d">Bucket B</text>+ <text x="1070" y="498" text-anchor="middle" class="sans" font-size="11" fill="#166534">10/min B</text>++ <rect x="636" y="544" width="500" height="52" rx="8" fill="#ffffff" stroke="#047857" stroke-width="1.5"/>+ <text x="886" y="566" text-anchor="middle" class="sans" font-size="12" font-weight="700" fill="#065f46">mcp-host lane: bearer only</text>+ <text x="886" y="584" text-anchor="middle" class="sans" font-size="11" fill="#047857">Injected x-user-session-token does not mint a new bucket</text>++ <rect x="636" y="676" width="500" height="56" rx="8" fill="#ffffff" stroke="#059669" stroke-width="1.5"/>+ <text x="886" y="698" text-anchor="middle" class="sans" font-size="13" font-weight="700" fill="#065f46">Result: A cannot exhaust B</text>+ <text x="886" y="718" text-anchor="middle" class="sans" font-size="12" fill="#047857">Same account keeps one bucket across token rotation</text>++ <rect x="40" y="776" width="1120" height="100" rx="12" fill="#111827"/>+ <text x="60" y="804" class="sans" font-size="14" font-weight="700" fill="#f8fafc">What we resolve</text>+ <text x="60" y="828" class="sans" font-size="13" fill="#e5e7eb">External lane: verified userId first. Unverified session header falls back to IP. mcp-host has its own bearer-only limiter.</text>+ <text x="60" y="848" class="sans" font-size="13" fill="#9ca3af">Same PG limiter, same 10/min, same sha256[:32] hash. Authz unchanged. Service bearer stays last resort when no session header is present.</text>++ <rect x="40" y="892" width="1120" height="32" rx="6" fill="#f8fafc" stroke="#e5e7eb"/>+ <line x1="60" y1="908" x2="92" y2="908" stroke="#2563eb" stroke-width="2.5"/>+ <text x="100" y="912" class="sans" font-size="11" fill="#374151">Request / headers</text>+ <line x1="248" y1="908" x2="280" y2="908" stroke="#ea580c" stroke-width="2"/>+ <text x="288" y="912" class="sans" font-size="11" fill="#374151">Current key path (shared bucket)</text>+ <line x1="520" y1="908" x2="552" y2="908" stroke="#059669" stroke-width="2"/>+ <text x="560" y="912" class="sans" font-size="11" fill="#374151">New key path (per-account buckets)</text>+ <line x1="800" y1="908" x2="832" y2="908" stroke="#6b7280" stroke-width="1.5" stroke-dasharray="4 2"/>+ <text x="840" y="912" class="sans" font-size="11" fill="#374151">Unchanged hop to control-api</text>+</svg>