Command Gateway Architect

---
name: command-gateway-architect
description: 'Design a single server-side-mediated write path — a command bus — for protected mutations in a multi-tenant SaaS: a command registry plus a per-command pipeline (validate payload → authenticate the actor from the token, never from client-supplied identity → derive trusted target tenant/resource scope → authorize that resolved target against policy → idempotency → execute → emit audit + domain events → safe error envelope), plus the no-direct-client-writes invariant for protected actions. Produces the command catalog, the pipeline contract, and an enforcement-point map. Use when mutations are scattered across endpoints or client SDKs, when tenant scope is read from the request body, or when adding a sensitive write. Do NOT use for the external API/webhook contract (api-event-architect), the role/permission policy itself (authorization-matrix-designer), or the audit record schema (audit-log-architect) — this dispatches through them.'
---

# Command Gateway Architect

**Reading key:** SaaS means software as a service; SDK means software
development kit; RPC means remote procedure call; RLS means row-level
security; DLQ means dead-letter queue; DB means database; SQL means Structured
Query Language; UUID means universally unique identifier. `authz` means
authorization and `txn` means a database transaction.

## Purpose

A multi-tenant SaaS leaks and corrupts data through the same door: writes
that skip a check because each endpoint re-implements its own. This skill
designs the opposite — one server-side-mediated write path (a command bus)
that every protected mutation flows through, so validation, actor
authentication, trusted target derivation, authorization, idempotency, audit,
and event emission happen in ONE ordered pipeline instead of being copied,
half-applied, and forgotten per route. The deliverable is a command catalog,
a per-command pipeline contract with the steps fixed in order, and an
enforcement-point map that proves no protected write reaches the datastore
around the gateway. The load-bearing invariant is the one attackers probe:
the actor and the tenant scope are derived server-side from trusted rows,
never accepted from the client.

## Use When

- Use when: mutations are scattered across many endpoints or a client SDK
  writes to the datastore directly, and the same checks are re-implemented
  (inconsistently) per write.
- Use when: a request supplies its own `tenant_id`, `user_id`, `role`, or
  `owner_id` on a write path and the server trusts it — the classic
  cross-tenant / privilege-escalation write.
- Use when: adding a sensitive or irreversible mutation (billing change,
  role grant, data export, deletion) and it needs a single audited,
  idempotent path rather than a bespoke handler.
- Use when: retries or double-submits cause duplicate side effects and the
  write path has no idempotency contract.
- Do NOT use when: the subject is the EXTERNAL contract — public REST/GraphQL
  shape, versioning, webhooks, partner rate limits — that is
  `api-event-architect`; the gateway is what those endpoints dispatch INTO.
- Do NOT use when: the question is WHO may do WHAT (roles × permissions ×
  resources) — that policy is `authorization-matrix-designer`; the gateway
  ENFORCES it at the authorize step, it does not author it.
- Do NOT use when: the subject is the audit record schema, taxonomy, or
  tamper-evidence — that is `audit-log-architect`; the gateway EMITS records
  into it.
- Do NOT use when: designing the INTERNAL event backbone (topics, partitions,
  DLQ) the emitted domain events ride — that is `streaming-event-architect`.

## Inputs to Inspect

1. The current write surface: every route/handler/RPC/client-SDK path that
   mutates state, and which of them re-derive checks locally vs share them.
2. Where tenant and actor context come from today on each write — token
   claims vs request body vs path param — flagging every client-supplied
   scope value on a write.
3. The authorization model in force (`authorization-matrix-designer` output
   if present): roles, object-level rules, deny-by-default posture — the
   policy the authorize step will call.
4. The audit taxonomy (`audit-log-architect` output if present): which
   actions must produce audit records and the required fields.
5. Existing idempotency handling: any dedup keys, unique constraints, or
   "retry made two charges" incident history.
6. The datastore access paths: can clients reach tables directly (e.g.
   client-side SDK + row policies) — which determines whether the gateway
   can be the ONLY write path or must be paired with datastore-level denial.

## Workflow

1. **Inventory commands, not endpoints.** Name each protected mutation as a
   command (`CreateInvoice`, `GrantRole`, `DeleteWorkspace`) with its inputs,
   the resource it touches, and its side effects. Group synonymous
   endpoints that do the same write into one command.
2. **Fix the pipeline order and make it non-optional.** Every command runs
   the same ordered stages; the order is the security property:
   1. **Validate** the payload against a schema (shape, types, required,
      bounds) — reject malformed input before any authz work.
   2. **Authenticate the actor** from the verified token/session ONLY. The
      client never states who it is on a write.
   3. **Derive tenant/resource scope server-side** from trusted state. For an
      existing target, look up its row and read its real `tenant_id`; for a
      create, derive the destination from authenticated server-side context.
      A client-supplied scope value is never authority. Do not expose lookup
      details to the caller before authorization.
   4. **Authorize** the actor against policy for this command and the
      resolved target and tenant (deny-by-default; call
      `authorization-matrix-designer`'s rules). Confirm the actor may act in
      that tenant before executing the command.
   5. **Idempotency**: an idempotency key per mutating command; a repeated
      key returns the first result without re-executing side effects.
   6. **Execute** the state change transactionally.
   7. **Emit** audit record + domain event(s) as part of (or committed with)
      the same transaction so a successful write cannot skip its audit.
   8. **Return a safe error envelope** (see step 5).
3. **State the no-direct-client-writes invariant and how it is enforced.**
   The gateway is only a security boundary if writes cannot go around it.
   Name the backstop: datastore write-deny for clients (RLS/permission so
   direct client writes fail) so the gateway is the sole write authority,
   not merely the polite one.
4. **Design idempotency concretely.** Key source (client-supplied UUID vs
   derived business key), the dedup store and its retention, what "same
   request" means, and the response for a replayed key. Distinguish
   idempotency (safe replay) from concurrency control (optimistic version /
   row lock) — name both where the command needs them.
5. **Design the error envelope.** One shape for all failures: a stable
   machine code + safe message; validation errors field-scoped; authz
   failures return the SAME not-found/forbidden shape regardless of whether
   the row exists in another tenant (no existence oracle); never leak
   stack traces, SQL, or other tenants' identifiers. Defer the error MODEL
   itself to `error-taxonomy-designer` and leak review to
   `error-handling-security-reviewer` — this pins the envelope contract.
6. **Map enforcement points.** A table: command → validated? → actor from
   token? → authz rule → scope-derivation source → idempotent? → audit
   event → around-gateway path (must be none). Any "scope from body" or
   "no audit" cell is a finding.
7. **Deliver** the catalog, the pipeline contract, and the enforcement-point
   map in the Output Format, with every handoff (policy, audit, event
   transport) named, not restated.

## Output Format

```
COMMAND GATEWAY DESIGN — <system/domain>
Invariant: all protected writes flow through the gateway; direct client
  writes DENIED at <datastore backstop>. Actor + tenant scope = server-derived.
Command catalog:
  <Command — inputs — target resource — side effects — sensitive? y/n>
Pipeline contract (fixed order, every command):
  validate → authenticate(actor from token) → derive-scope(from trusted state) →
  authorize(<policy source, resolved target>) → idempotency(<key, store, retention>) →
  execute(txn) → emit(audit + events) → safe-error-envelope
Idempotency: <key source, dedup store, replay response, concurrency control>
Error envelope: <shape, codes, no-existence-oracle rule, leak rules>
Enforcement-point map: <command × stage table; findings flagged>
Handoffs: policy → authorization-matrix-designer; audit schema →
  audit-log-architect; event transport → streaming-event-architect;
  external contract → api-event-architect
Open questions / risks: <each with risk-if-wrong / who answers>
```

## Validation Checklist

- [ ] Every protected mutation appears as a command; no endpoint bypasses
      the pipeline.
- [ ] Actor identity is taken from the verified token on EVERY command —
      no command trusts a client-supplied actor/role.
- [ ] Tenant/resource scope is derived from trusted server state: existing
      targets from rows, creates from authenticated server context. No
      command treats request-body scope as authority.
- [ ] Authorization follows trusted target derivation, is deny-by-default,
      and delegates to the authorization model rather than a per-command copy.
- [ ] Every mutating command has an idempotency contract (key, store,
      replay response) — retries cannot double-apply side effects.
- [ ] A successful write cannot skip its audit record or event emission
      (same transaction / outbox).
- [ ] The around-the-gateway path is closed at the datastore, and that
      backstop is named — the invariant is enforced, not aspirational.
- [ ] Error envelope leaks nothing cross-tenant and gives no existence
      oracle; the error MODEL is deferred to `error-taxonomy-designer`.

## Gotchas

- A gateway that clients can bypass is documentation, not a control: if a
  client SDK can still write to tables directly, the pipeline's checks are
  optional. The datastore-level write-deny is the load-bearing half.
- Trusting `tenant_id` from the body "because the client already knows it"
  is the cross-tenant write bug in its purest form — the client knowing it
  is exactly why it cannot be trusted.
- Emitting the audit event AFTER the transaction commits, in a separate
  step, means a crash between them yields an unaudited write. Commit the
  record with the change (transactional outbox) or inside the same txn.
- Idempotency keyed on the whole request body breaks the moment a retried
  client adds a timestamp; key on a stable business identifier or a
  client-generated request id.
- Idempotency is not concurrency control: a replayed key and two DIFFERENT
  concurrent writers are different problems; the second needs a version
  check or lock, not a dedup store.
- Authorize-then-derive-scope in the wrong order authorizes against a
  client-claimed target: derive and confirm the real row's tenant, then
  authorize against THAT, or an attacker authorizes on their own object and
  acts on someone else's.
- A per-command bespoke error message is where existence oracles leak
  ("forbidden" vs "not found" tells the attacker the row exists) — one
  envelope, one shape.

## Stop Conditions

- The authorization policy the authorize step must call does not exist or is
  ambiguous → obtain it from `authorization-matrix-designer` or a human
  before fixing the pipeline; a gateway enforcing an undefined policy is a
  false assurance.
- Closing the around-the-gateway path requires changing live datastore
  permissions/RLS on a running system → this skill DESIGNS the backstop and
  the migration; executing permission changes against production follows the
  repo's approval path (`human-approval-boundary`) — do not run them here.
- A "make every write exactly-once end to end including external side
  effects" mandate survives → surface the honest decomposition
  (idempotent effects + at-least-once) and escalate; do not promise
  unqualified exactly-once.
- The write surface is so entangled that no single gateway can front it
  without a phased migration → present the migration sequence and the
  interim risk, and stop for a human to sequence it rather than declaring
  the invariant met.

## Supporting Files

- `evals/evals.json` — behavior cases: the scattered-writes design, the
  scope-from-body fix, the idempotency-vs-concurrency edge, and the
  exactly-once refusal.
- `evals/trigger-evals.json` — discrimination against `api-event-architect`
  (external contract), `authorization-matrix-designer` (policy vs
  enforcement), `audit-log-architect` (record schema vs emission), and
  `streaming-event-architect` (event transport).
- No `references/` — the pipeline contract and enforcement-point map above
  are the complete procedure; detail lives in the produced artifacts.