ApiGateway

1# ApiGateway.intent
2# Domain: API gateway. Every request is authenticated, rate-limited, and routed by
3# one admission policy. Deny by default; never forward an unauthenticated call to a
4# protected route. The admission rule runs deterministically.
5
6mission AdmitRequest
7use product
8
9title "Authenticate, rate-limit, and route an inbound API request"
10for PlatformTeam
11
12goal
13  Admit a request only when it is authenticated, within its rate limit, and bound
14  for an allowed route.
15
16why
17  The gateway is the front door. A weak admission policy leaks protected routes,
18  lets one caller starve the rest, and forwards traffic nothing checked.
19
20requires
21  Route
22  RateLimitPolicy
23
24input
25  authenticated: Flag
26  routeAllowed: Flag
27  remainingQuota: Count
28  routeIsPublic: Flag
29
30output
31  decision: AdmissionResult
32
33guarantee an authenticated caller within quota reaches an allowed route
34  because the gateway must not block legitimate traffic it was built to serve
35  verify happy path routing test
36
37guarantee a caller over its rate limit is throttled, not served
38  because one caller must never exhaust capacity for everyone else
39  verify rate limit test
40
41never
42  forward an unauthenticated request to a protected route
43  route to a path outside the allowlist
44
45never forward an unauthenticated request to a protected route
46  because that is the exact bypass an API gateway exists to prevent
47  verify auth enforcement test
48
49never route to a path outside the allowlist
50  because an unlisted path is unowned surface with no contract behind it
51  verify route allowlist test
52
53# Admission is deny-by-default: only an explicit Allow forwards. `intent run` / `intent test`.
54decision AdmitRequest
55  inputs
56    authenticated
57    routeIsPublic
58    routeAllowed
59    remainingQuota
60  rule unknownRoute
61    when routeAllowed == false
62    return Reject
63  rule needsAuth
64    when routeIsPublic == false and authenticated == false
65    return Reject
66  rule overLimit
67    when remainingQuota <= 0
68    return Throttle
69  rule admit
70    when routeAllowed == true
71    return Forward
72  default
73    return Reject
74
75target
76  OpenAPI
77  Tests
78
79test AdmitRequest
80  case authenticated within quota is forwarded
81    given authenticated true, routeIsPublic false, routeAllowed true, remainingQuota 10
82    expect Forward
83  case unauthenticated to protected route is rejected
84    given authenticated false, routeIsPublic false, routeAllowed true, remainingQuota 10
85    expect Reject
86  case public route needs no auth
87    given authenticated false, routeIsPublic true, routeAllowed true, remainingQuota 10
88    expect Forward
89  case over rate limit is throttled
90    given authenticated true, routeIsPublic false, routeAllowed true, remainingQuota 0
91    expect Throttle
92  case unknown route is rejected
93    given authenticated true, routeIsPublic false, routeAllowed false, remainingQuota 10
94    expect Reject