Policy Schema Reference

Reason codes are additive only and are never renamed. Every code named below, including the reserved one, is a permanent commitment once it ships. Amounts are integer minor units throughout, the same as everywhere else in this SDK.

Amount

Period

Worth stating plainly because it’s easy to conflate: every window Waysafe actually computes is a fixed calendar window — a calendar day, a Monday-start calendar week, a calendar month, each in the policy’s own timezone. None of them is a rolling window (the trailing N days from now, sliding forward every second). “No more than $500 in any rolling 30 days” and “no more than $500 per calendar month” are different guarantees — the first resets continuously, the second resets on the 1st regardless of when in the prior month spending happened. Only the second is expressible today.

Counterparty

Time

Velocity

Instrument

Evidence

The minimum merchant trust required for an ALLOW is a rule the engine enforces on every decision. It is not, today, a field a mandate can set.

Escalation

Invariants

The security properties a reviewer checks — not a summary of the tables above, a separate set of claims about how any policy, present or future, must compose.

1. Absence fails closed. An unset field never widens scope. Omitting per_transaction_max does not mean unlimited spend is intended — every mandate still has expires_at, a currency, and an unlisted disposition on both merchants and categories, each independently capable of stopping an action. A missing ceiling is a ceiling nobody set, not a ceiling of infinity.

2. Composition is most-restrictive-wins. Every dimension in evaluate() can only ever add a reason at its own tier or above; none can downgrade a decision another dimension already forced upward. Precedence is DENY > STEP_UP > ALLOW. Adding a rule to a policy can never widen what it already permitted. And a decision carries every reason code that applies at its winning tier, not just the first one evaluated — a request that’s both over the per-transaction cap and from an unlisted merchant returns both DENY_TRANSACTION_LIMIT_EXCEEDED and DENY_MERCHANT_NOT_ALLOWLISTED, so a receipt never hides a second real reason behind whichever check happened to run first.

3. Policy change requires mandate-creation authority. An approval authorizes one action. It can never mutate a policy — not the mandate it was decided under, not any other. Widening a limit, adding a merchant, or extending an expiry is a new mandate version, created with the same authority (and, today, the same WebAuthn ceremony) that created the first one — never a side effect of approving a transaction.

Approver Mandates

A step-up is not a pause waiting for a human. It is a second authorization, evaluated by the same evaluate() engine against a different mandate — the approver’s — producing the same decision shape, the same evidence entries, and the same reason codes as any other authorization.

The principal signs the approver’s authority once, at enrollment, using the same passkey ceremony that activates any mandate. escalation.approvers is set at mandate creation, alongside every other policy field, by the same signature. (No separate “update this mandate” ceremony exists yet — changing an existing mandate’s approver set means creating a new mandate, same as changing any other field today.) After that, approvals run at machine speed with no human present. The human is in the authority path, not the transaction path.

Because that one signature is what the whole model rests on, enrolling a second passkey for a principal that already has one requires a fresh prior authentication with an existing credential. That produces a single-use, expiring grant bound to that specific principal and credential. An adversarial review found that an authentication challenge could previously be answered with a registrationresponse, which enrolled an attacker’s own passkey against a victim principal. A later review found a second route to the same place: the signature a principal gives to confirm a policy could be redeemed as a passkey enrolment grant. Every challenge now records what it was issued for, and each ceremony accepts only its own purpose. A mismatch returns 400 challenge_purpose_mismatch.

An approver is any actor holding an approver mandate: a treasury service, a manager, a controller system, or the principal themselves. The human-in-the-loop, async-approval case most people picture first is the degenerate form of this model, not a separate mechanism from it — a human approving on their phone and a treasury service approving programmatically both resolve a step-up the identical way, through the identical engine.

An approver mandate is bounded by the same policy schema documented above — amount ceilings, merchant scope, time windows, velocity. An approver cannot approve outside its own mandate; it is a mandate, evaluated the same way any other is. And it is not free to approve: an approval writes a real, permanent ledger entry against the approver’s own mandate (never released), so its cumulative and velocity limits actually accumulate from the approvals it grants, not only from its own authorize() calls. A per-period cumulative cap on an approver mandate is a real ceiling on how much it can approve in that period, not just on how much it can spend directly.

An approval costs budget on both mandates, for two different reasons. The approver’s entry above is the ceiling on how much it may approve. The spending mandate also takes a hold at approval time, so the approved amount counts against the cap the principal actually signed. An adversarial review found that it did not: with reserve_on_step_up: false the spending mandate’s ledger was untouched by an approval, so an unlimited number of payments could be approved against its cap. A second review found a further case: several approvals that take no hold were each invisible to the others, so three $90 requests against a $100 limit could all be approved. An approval now re-checks the spending mandate’s own limit at the moment it is granted. The approver’s charge is a separate check. It is never a substitute for the spender’s.

Approval re-validates under the lock. Three things can lapse between a step-up being raised and an approver resolving it: the step-up’s own TTL, the spending mandate being revoked, and that mandate’s policy expires_at. All three are re-read inside the same row lock that takes the money, and any of them refuses the approval with its own code — DENY_STEP_UP_EXPIRED, DENY_MANDATE_REVOKED, DENY_MANDATE_EXPIRED. Before that review, all three were approved and executable; a revoked mandate’s pending step-up still went through.

Authority is single-level: an approver may authorize transactions but may not mint another approver, and cannot escalate a step-up further. If the approver’s own evaluate() also returns STEP_UP for the action, the resolution declines with DENY_APPROVER_WOULD_ESCALATE — it does not chain to a second approver. A delegation-depth field is not currently reserved anywhere in packages/core, checked directly rather than assumed, so this stays documented as a gap rather than a reservation that doesn’t exist. The intent stands regardless of the naming: a delegation-depth field belongs in a future schema from the start, so chains can be added later without a migration.

Cycles. Rules 1 and 2 alone don’t stop mutual approval — mandate A naming B as approver and B naming A back would let each resolve the other’s step-ups with neither rule firing. A mandate naming itself (the degenerate 1-cycle) or two mandates naming each other (an exact mutual pair) is rejected at mandate creation, not at resolve time — DENY_APPROVER_CYCLE — checked by looking at whether the candidate approver’s own current policy already names the mandate being created back. Cycles of three or more (A names B, B names C, C names A) are not caught here — that would need a full graph walk across every mandate in an organization on every creation, which this build doesn’t do. That gap is accepted, not overlooked, because it’s bounded by the ledger rule just above: evaluate() in a longer cycle still runs against each approver’s own policy, and each approval still costs real, permanent budget on that approver’s own mandate — a cycle can’t be used to escalate authority without limit, only up to whatever the weakest link’s own signed cumulative cap allows. The threat model names this as a bounded risk rather than leaving it undiscussed.

Approval authorizes one action. It never mutates policy on either mandate. No raised cap, no extended window, no new approver. Approving a $9,000 purchase does not raise the mandate’s per-transaction ceiling for the next one. (It does write the real ledger entry described above; that’s ledger, not policy.)

Single-use and idempotent. A step-up resolves at most once. A second resolve attempt on an already-resolved (or already-expired) step-up — from the same approver, a different approver, or anyone else — replays the recorded outcome and its reason codes; it never re-runs evaluate(). Two approvers resolving the same step-up simultaneously, or an approval racing the TTL sweep, settle atomically: first writer wins, every other caller gets the recorded outcome back, never an error and never a second decision.

Step-up classes resolve differently, and the distinction matters:

(a) Needs-evidence (e.g. STEP_UP_MERCHANT_UNVERIFIED) would resolve the moment a better-attested source supplies the identifier — a rail’s own callback corroborating a domain, for instance — with no approver, no human, at machine speed. This class of automatic resolution is SPECIFIED, not built: no code today re-evaluates a pending step-up when new evidence arrives, only when a real approver mandate explicitly resolves it. What is real today is that the same underlying trust rule already runs on every fresh evaluation — a rail-attested merchant on a new request resolves to VERIFIED the same way it always does; nothing here re-checks a specific pending authorization automatically.

(b) Needs-higher-authority resolves via an approver mandate — real, shipped, described above and in the sequence below.

(c) Unresolvable is a DENY at evaluation time, not a step-up that sits waiting to expire. A hard ceiling denies outright rather than escalating something that was never going to be approvable.

Expiry and fail direction: an unresolved step-up expires to DENY. step_up.ttl_seconds and the sweep that applies it are implemented today, see Escalation above, and hold the same way whether the step-up is ever offered to an approver or not. An expiry releases any hold it was carrying. It does not yet write its own entry to the signed record, which is a known gap named in the threat model.

The full sequence:

authorize()  ->  STEP_UP, status PENDING_STEP_UP
resolveStepUp(authorizationId, approver)
  -> approver's evaluate() ALLOW  ->  status STEP_UP_APPROVED
  -> approver's evaluate() DENY/STEP_UP  ->  status STEP_UP_DECLINED
asExecutable(decision)  ->  non-null exactly when STEP_UP_APPROVED (same as a fresh ALLOW)
execute(executable, params)  ->  status EXECUTED

STEP_UP_APPROVED is executable the identical way AUTHORIZED is. asExecutable() has treated the two the same way since before approver mandates existed. Approver mandates changed only what can produce STEP_UP_APPROVED in the first place.

A closed gap, stated plainly: an agent credential could once resolve its own step-up. The same agent key that produced a STEP_UP decision could call the resolution endpoint on it immediately, with no human, no second credential, and no code path that refused it. For anyone holding that one key, STEP_UPcollapsed to the same outcome as ALLOW. It is closed by requiring the resolving credential to belong to a different, named approver mandate. It is rejected with DENY_STEP_UP_SELF_APPROVAL if it’s the same mandate, checked first, ahead of every other rule. An org-level credential — which has no agent identity at all — was never a valid resolver either, and still isn’t: it can never match a real approver mandate’s own agent key. Proven, not just described: the adversarial suite (apps/api/src/authorization/service.test.ts, server.test.ts) covers self-approval, a mandate not on the approvers list, an approver whose own policy caps below the amount, an approver at its own cumulative ceiling, TTL expiry racing resolution, the 1- and 2-cycle rejections at creation, a real runtime 3-cycle bounded by the ledger rule, and both concurrency races — plus a real, non-simulated Postgres regression test for a nested-transaction hazard the first live run against a real database surfaced.