@decionis/agentsafe 0.6.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (288) hide show
  1. package/README.md +68 -20
  2. package/dist/Cli.js +30 -3
  3. package/dist/Cli.js.map +1 -1
  4. package/dist/Index.d.ts +5 -3
  5. package/dist/Index.d.ts.map +1 -1
  6. package/dist/Index.js +3 -1
  7. package/dist/Index.js.map +1 -1
  8. package/dist/TrustedExecutor.d.ts.map +1 -1
  9. package/dist/TrustedExecutor.js +2 -0
  10. package/dist/TrustedExecutor.js.map +1 -1
  11. package/dist/acceptance/AcceptancePlan.d.ts +109 -0
  12. package/dist/acceptance/AcceptancePlan.d.ts.map +1 -0
  13. package/dist/acceptance/AcceptancePlan.js +128 -0
  14. package/dist/acceptance/AcceptancePlan.js.map +1 -0
  15. package/dist/acceptance/AcceptanceReport.d.ts +596 -0
  16. package/dist/acceptance/AcceptanceReport.d.ts.map +1 -0
  17. package/dist/acceptance/AcceptanceReport.js +361 -0
  18. package/dist/acceptance/AcceptanceReport.js.map +1 -0
  19. package/dist/acceptance/AcceptanceRun.d.ts +118 -0
  20. package/dist/acceptance/AcceptanceRun.d.ts.map +1 -0
  21. package/dist/acceptance/AcceptanceRun.js +419 -0
  22. package/dist/acceptance/AcceptanceRun.js.map +1 -0
  23. package/dist/acceptance/Coverage.d.ts +12 -0
  24. package/dist/acceptance/Coverage.d.ts.map +1 -0
  25. package/dist/acceptance/Coverage.js +48 -0
  26. package/dist/acceptance/Coverage.js.map +1 -0
  27. package/dist/acceptance/OutageDoubles.d.ts +34 -0
  28. package/dist/acceptance/OutageDoubles.d.ts.map +1 -0
  29. package/dist/acceptance/OutageDoubles.js +67 -0
  30. package/dist/acceptance/OutageDoubles.js.map +1 -0
  31. package/dist/acceptance/ZoneProbes.d.ts +368 -0
  32. package/dist/acceptance/ZoneProbes.d.ts.map +1 -0
  33. package/dist/acceptance/ZoneProbes.js +488 -0
  34. package/dist/acceptance/ZoneProbes.js.map +1 -0
  35. package/dist/adapters/JcsDigest.d.ts +6 -5
  36. package/dist/adapters/JcsDigest.d.ts.map +1 -1
  37. package/dist/adapters/JcsDigest.js +9 -8
  38. package/dist/adapters/JcsDigest.js.map +1 -1
  39. package/dist/adapters/mcp/McpGuard.d.ts +32 -3
  40. package/dist/adapters/mcp/McpGuard.d.ts.map +1 -1
  41. package/dist/adapters/mcp/McpGuard.js +29 -5
  42. package/dist/adapters/mcp/McpGuard.js.map +1 -1
  43. package/dist/adapters/mcp/McpIntentBinder.d.ts +18 -3
  44. package/dist/adapters/mcp/McpIntentBinder.d.ts.map +1 -1
  45. package/dist/adapters/mcp/McpIntentBinder.js +48 -1
  46. package/dist/adapters/mcp/McpIntentBinder.js.map +1 -1
  47. package/dist/adapters/mcp/McpInvocation.d.ts +9 -2
  48. package/dist/adapters/mcp/McpInvocation.d.ts.map +1 -1
  49. package/dist/adapters/mcp/McpInvocation.js.map +1 -1
  50. package/dist/cli/Accept.d.ts +9 -0
  51. package/dist/cli/Accept.d.ts.map +1 -0
  52. package/dist/cli/Accept.js +209 -0
  53. package/dist/cli/Accept.js.map +1 -0
  54. package/dist/cli/Actions.d.ts +16 -0
  55. package/dist/cli/Actions.d.ts.map +1 -0
  56. package/dist/cli/Actions.js +194 -0
  57. package/dist/cli/Actions.js.map +1 -0
  58. package/dist/cli/Arguments.d.ts +4 -0
  59. package/dist/cli/Arguments.d.ts.map +1 -1
  60. package/dist/cli/Arguments.js +12 -3
  61. package/dist/cli/Arguments.js.map +1 -1
  62. package/dist/cli/Commands.d.ts +1 -1
  63. package/dist/cli/Commands.d.ts.map +1 -1
  64. package/dist/cli/Commands.js +5 -0
  65. package/dist/cli/Commands.js.map +1 -1
  66. package/dist/cli/ConfigCommand.d.ts.map +1 -1
  67. package/dist/cli/ConfigCommand.js +10 -0
  68. package/dist/cli/ConfigCommand.js.map +1 -1
  69. package/dist/cli/Doctor.d.ts.map +1 -1
  70. package/dist/cli/Doctor.js +67 -1
  71. package/dist/cli/Doctor.js.map +1 -1
  72. package/dist/cli/Help.d.ts.map +1 -1
  73. package/dist/cli/Help.js +18 -1
  74. package/dist/cli/Help.js.map +1 -1
  75. package/dist/cli/Host.d.ts +5 -2
  76. package/dist/cli/Host.d.ts.map +1 -1
  77. package/dist/cli/Host.js +24 -2
  78. package/dist/cli/Host.js.map +1 -1
  79. package/dist/cli/Identity.d.ts +13 -1
  80. package/dist/cli/Identity.d.ts.map +1 -1
  81. package/dist/cli/Identity.js +25 -2
  82. package/dist/cli/Identity.js.map +1 -1
  83. package/dist/cli/Profile.d.ts +24 -0
  84. package/dist/cli/Profile.d.ts.map +1 -0
  85. package/dist/cli/Profile.js +168 -0
  86. package/dist/cli/Profile.js.map +1 -0
  87. package/dist/cli/Records.d.ts +15 -0
  88. package/dist/cli/Records.d.ts.map +1 -0
  89. package/dist/cli/Records.js +205 -0
  90. package/dist/cli/Records.js.map +1 -0
  91. package/dist/cli/Status.d.ts +23 -0
  92. package/dist/cli/Status.d.ts.map +1 -1
  93. package/dist/cli/Status.js +80 -18
  94. package/dist/cli/Status.js.map +1 -1
  95. package/dist/cli/VerifyAcceptance.d.ts +38 -0
  96. package/dist/cli/VerifyAcceptance.d.ts.map +1 -0
  97. package/dist/cli/VerifyAcceptance.js +143 -0
  98. package/dist/cli/VerifyAcceptance.js.map +1 -0
  99. package/dist/config/ConfigKeys.d.ts +2 -2
  100. package/dist/config/ConfigKeys.d.ts.map +1 -1
  101. package/dist/config/ConfigKeys.js +6 -0
  102. package/dist/config/ConfigKeys.js.map +1 -1
  103. package/dist/config/ExecutorConfig.d.ts +35 -1
  104. package/dist/config/ExecutorConfig.d.ts.map +1 -1
  105. package/dist/config/ExecutorConfig.js +53 -1
  106. package/dist/config/ExecutorConfig.js.map +1 -1
  107. package/dist/egress/ZoneHttpClient.d.ts +3 -0
  108. package/dist/egress/ZoneHttpClient.d.ts.map +1 -0
  109. package/dist/egress/ZoneHttpClient.js +72 -0
  110. package/dist/egress/ZoneHttpClient.js.map +1 -0
  111. package/dist/exposure/DecionisExposureLedger.d.ts +44 -0
  112. package/dist/exposure/DecionisExposureLedger.d.ts.map +1 -0
  113. package/dist/exposure/DecionisExposureLedger.js +175 -0
  114. package/dist/exposure/DecionisExposureLedger.js.map +1 -0
  115. package/dist/exposure/ExposureDeclaration.d.ts +68 -0
  116. package/dist/exposure/ExposureDeclaration.d.ts.map +1 -0
  117. package/dist/exposure/ExposureDeclaration.js +83 -0
  118. package/dist/exposure/ExposureDeclaration.js.map +1 -0
  119. package/dist/exposure/ExposureFacts.d.ts +61 -0
  120. package/dist/exposure/ExposureFacts.d.ts.map +1 -0
  121. package/dist/exposure/ExposureFacts.js +201 -0
  122. package/dist/exposure/ExposureFacts.js.map +1 -0
  123. package/dist/exposure/ExposureGate.d.ts +144 -0
  124. package/dist/exposure/ExposureGate.d.ts.map +1 -0
  125. package/dist/exposure/ExposureGate.js +446 -0
  126. package/dist/exposure/ExposureGate.js.map +1 -0
  127. package/dist/exposure/ExposureLedger.d.ts +93 -0
  128. package/dist/exposure/ExposureLedger.d.ts.map +1 -0
  129. package/dist/exposure/ExposureLedger.js +24 -0
  130. package/dist/exposure/ExposureLedger.js.map +1 -0
  131. package/dist/gateway/AttemptStore.d.ts +83 -0
  132. package/dist/gateway/AttemptStore.d.ts.map +1 -0
  133. package/dist/gateway/AttemptStore.js +229 -0
  134. package/dist/gateway/AttemptStore.js.map +1 -0
  135. package/dist/gateway/ForwardHandler.d.ts +50 -6
  136. package/dist/gateway/ForwardHandler.d.ts.map +1 -1
  137. package/dist/gateway/ForwardHandler.js +58 -14
  138. package/dist/gateway/ForwardHandler.js.map +1 -1
  139. package/dist/gateway/Gateway.d.ts +347 -15
  140. package/dist/gateway/Gateway.d.ts.map +1 -1
  141. package/dist/gateway/Gateway.js +1524 -63
  142. package/dist/gateway/Gateway.js.map +1 -1
  143. package/dist/gateway/GatewayConfig.d.ts +295 -0
  144. package/dist/gateway/GatewayConfig.d.ts.map +1 -1
  145. package/dist/gateway/GatewayConfig.js +485 -13
  146. package/dist/gateway/GatewayConfig.js.map +1 -1
  147. package/dist/gateway/GatewayManifest.d.ts +18 -0
  148. package/dist/gateway/GatewayManifest.d.ts.map +1 -0
  149. package/dist/gateway/GatewayManifest.js +42 -0
  150. package/dist/gateway/GatewayManifest.js.map +1 -0
  151. package/dist/gateway/GatewayMetrics.d.ts +12 -4
  152. package/dist/gateway/GatewayMetrics.d.ts.map +1 -1
  153. package/dist/gateway/GatewayMetrics.js +5 -0
  154. package/dist/gateway/GatewayMetrics.js.map +1 -1
  155. package/dist/gateway/GatewayReport.d.ts +39 -2
  156. package/dist/gateway/GatewayReport.d.ts.map +1 -1
  157. package/dist/gateway/GatewayReport.js +14 -0
  158. package/dist/gateway/GatewayReport.js.map +1 -1
  159. package/dist/gateway/HoldStore.d.ts +89 -0
  160. package/dist/gateway/HoldStore.d.ts.map +1 -0
  161. package/dist/gateway/HoldStore.js +280 -0
  162. package/dist/gateway/HoldStore.js.map +1 -0
  163. package/dist/gateway/InterceptedRequest.d.ts +55 -1
  164. package/dist/gateway/InterceptedRequest.d.ts.map +1 -1
  165. package/dist/gateway/InterceptedRequest.js +63 -1
  166. package/dist/gateway/InterceptedRequest.js.map +1 -1
  167. package/dist/gateway/PolicySelector.d.ts +5 -0
  168. package/dist/gateway/PolicySelector.d.ts.map +1 -0
  169. package/dist/gateway/PolicySelector.js +9 -0
  170. package/dist/gateway/PolicySelector.js.map +1 -0
  171. package/dist/gateway/RouteTable.d.ts +72 -7
  172. package/dist/gateway/RouteTable.d.ts.map +1 -1
  173. package/dist/gateway/RouteTable.js +133 -9
  174. package/dist/gateway/RouteTable.js.map +1 -1
  175. package/dist/gateway/ShadowLedger.d.ts +11 -0
  176. package/dist/gateway/ShadowLedger.d.ts.map +1 -1
  177. package/dist/gateway/ShadowLedger.js +11 -0
  178. package/dist/gateway/ShadowLedger.js.map +1 -1
  179. package/dist/gateway/SubjectSessions.d.ts +113 -0
  180. package/dist/gateway/SubjectSessions.d.ts.map +1 -0
  181. package/dist/gateway/SubjectSessions.js +219 -0
  182. package/dist/gateway/SubjectSessions.js.map +1 -0
  183. package/dist/gateway/TargetEffect.d.ts +74 -0
  184. package/dist/gateway/TargetEffect.d.ts.map +1 -0
  185. package/dist/gateway/TargetEffect.js +95 -0
  186. package/dist/gateway/TargetEffect.js.map +1 -0
  187. package/dist/gateway/TargetReader.d.ts +70 -0
  188. package/dist/gateway/TargetReader.d.ts.map +1 -0
  189. package/dist/gateway/TargetReader.js +106 -0
  190. package/dist/gateway/TargetReader.js.map +1 -0
  191. package/dist/gateway/Upstream.d.ts +26 -0
  192. package/dist/gateway/Upstream.d.ts.map +1 -1
  193. package/dist/gateway/Upstream.js +42 -3
  194. package/dist/gateway/Upstream.js.map +1 -1
  195. package/dist/hosted/TenantHost.d.ts +26 -6
  196. package/dist/hosted/TenantHost.d.ts.map +1 -1
  197. package/dist/hosted/TenantHost.js +45 -10
  198. package/dist/hosted/TenantHost.js.map +1 -1
  199. package/dist/hosted/TenantRegistry.d.ts +28 -0
  200. package/dist/hosted/TenantRegistry.d.ts.map +1 -1
  201. package/dist/hosted/TenantRegistry.js +60 -1
  202. package/dist/hosted/TenantRegistry.js.map +1 -1
  203. package/dist/http/GatewayHttpServer.d.ts +7 -0
  204. package/dist/http/GatewayHttpServer.d.ts.map +1 -1
  205. package/dist/http/GatewayHttpServer.js +103 -3
  206. package/dist/http/GatewayHttpServer.js.map +1 -1
  207. package/dist/identity/WorkloadJwtVerifier.d.ts +13 -0
  208. package/dist/identity/WorkloadJwtVerifier.d.ts.map +1 -1
  209. package/dist/identity/WorkloadJwtVerifier.js +40 -8
  210. package/dist/identity/WorkloadJwtVerifier.js.map +1 -1
  211. package/dist/incident/HaltSwitch.d.ts +10 -2
  212. package/dist/incident/HaltSwitch.d.ts.map +1 -1
  213. package/dist/incident/HaltSwitch.js +22 -2
  214. package/dist/incident/HaltSwitch.js.map +1 -1
  215. package/dist/incident/SecurityEvents.d.ts +18 -0
  216. package/dist/incident/SecurityEvents.d.ts.map +1 -1
  217. package/dist/incident/SecurityEvents.js +17 -0
  218. package/dist/incident/SecurityEvents.js.map +1 -1
  219. package/dist/limits/HardLimits.d.ts.map +1 -1
  220. package/dist/limits/HardLimits.js.map +1 -1
  221. package/dist/outcomes/CardOutcomeEvidence.d.ts +56 -0
  222. package/dist/outcomes/CardOutcomeEvidence.d.ts.map +1 -0
  223. package/dist/outcomes/CardOutcomeEvidence.js +211 -0
  224. package/dist/outcomes/CardOutcomeEvidence.js.map +1 -0
  225. package/dist/outcomes/CardOutcomeFact.d.ts +90 -0
  226. package/dist/outcomes/CardOutcomeFact.d.ts.map +1 -0
  227. package/dist/outcomes/CardOutcomeFact.js +76 -0
  228. package/dist/outcomes/CardOutcomeFact.js.map +1 -0
  229. package/dist/outcomes/CardOutcomeLedger.d.ts +26 -0
  230. package/dist/outcomes/CardOutcomeLedger.d.ts.map +1 -0
  231. package/dist/outcomes/CardOutcomeLedger.js +31 -0
  232. package/dist/outcomes/CardOutcomeLedger.js.map +1 -0
  233. package/dist/outcomes/CardOutcomeRecorder.d.ts +35 -0
  234. package/dist/outcomes/CardOutcomeRecorder.d.ts.map +1 -0
  235. package/dist/outcomes/CardOutcomeRecorder.js +84 -0
  236. package/dist/outcomes/CardOutcomeRecorder.js.map +1 -0
  237. package/dist/outcomes/CardOutcomes.d.ts +68 -0
  238. package/dist/outcomes/CardOutcomes.d.ts.map +1 -0
  239. package/dist/outcomes/CardOutcomes.js +191 -0
  240. package/dist/outcomes/CardOutcomes.js.map +1 -0
  241. package/dist/outcomes/CoreOutcomeEvidenceClient.d.ts +54 -0
  242. package/dist/outcomes/CoreOutcomeEvidenceClient.d.ts.map +1 -0
  243. package/dist/outcomes/CoreOutcomeEvidenceClient.js +116 -0
  244. package/dist/outcomes/CoreOutcomeEvidenceClient.js.map +1 -0
  245. package/dist/outcomes/FileCardOutcomeLedger.d.ts +36 -0
  246. package/dist/outcomes/FileCardOutcomeLedger.d.ts.map +1 -0
  247. package/dist/outcomes/FileCardOutcomeLedger.js +152 -0
  248. package/dist/outcomes/FileCardOutcomeLedger.js.map +1 -0
  249. package/dist/outcomes/OutcomeEvidence.d.ts +238 -0
  250. package/dist/outcomes/OutcomeEvidence.d.ts.map +1 -0
  251. package/dist/outcomes/OutcomeEvidence.js +130 -0
  252. package/dist/outcomes/OutcomeEvidence.js.map +1 -0
  253. package/dist/outcomes/OutcomeEvidencePublisher.d.ts +81 -0
  254. package/dist/outcomes/OutcomeEvidencePublisher.d.ts.map +1 -0
  255. package/dist/outcomes/OutcomeEvidencePublisher.js +189 -0
  256. package/dist/outcomes/OutcomeEvidencePublisher.js.map +1 -0
  257. package/dist/outcomes/OutcomeEvidenceStore.d.ts +57 -0
  258. package/dist/outcomes/OutcomeEvidenceStore.d.ts.map +1 -0
  259. package/dist/outcomes/OutcomeEvidenceStore.js +191 -0
  260. package/dist/outcomes/OutcomeEvidenceStore.js.map +1 -0
  261. package/dist/posture/ActionSpaceDrift.d.ts +40 -0
  262. package/dist/posture/ActionSpaceDrift.d.ts.map +1 -0
  263. package/dist/posture/ActionSpaceDrift.js +67 -0
  264. package/dist/posture/ActionSpaceDrift.js.map +1 -0
  265. package/dist/posture/DeploymentFingerprint.d.ts +88 -0
  266. package/dist/posture/DeploymentFingerprint.d.ts.map +1 -0
  267. package/dist/posture/DeploymentFingerprint.js +78 -0
  268. package/dist/posture/DeploymentFingerprint.js.map +1 -0
  269. package/dist/secrets/SecretStore.d.ts +6 -1
  270. package/dist/secrets/SecretStore.d.ts.map +1 -1
  271. package/dist/secrets/SecretStore.js.map +1 -1
  272. package/dist/service/EscalationResolver.d.ts +6 -6
  273. package/dist/service/EscalationResolver.d.ts.map +1 -1
  274. package/dist/service/EscalationResolver.js +8 -4
  275. package/dist/service/EscalationResolver.js.map +1 -1
  276. package/dist/service/Requests.d.ts +6 -0
  277. package/dist/service/Requests.d.ts.map +1 -1
  278. package/dist/service/Requests.js +9 -1
  279. package/dist/service/Requests.js.map +1 -1
  280. package/dist/service/TrustedExecutorService.d.ts +21 -1
  281. package/dist/service/TrustedExecutorService.d.ts.map +1 -1
  282. package/dist/service/TrustedExecutorService.js +54 -13
  283. package/dist/service/TrustedExecutorService.js.map +1 -1
  284. package/dist/verify/VerifyingProvider.d.ts +32 -6
  285. package/dist/verify/VerifyingProvider.d.ts.map +1 -1
  286. package/dist/verify/VerifyingProvider.js +16 -2
  287. package/dist/verify/VerifyingProvider.js.map +1 -1
  288. package/package.json +7 -6
@@ -0,0 +1,219 @@
1
+ import { createHash, randomBytes } from "node:crypto";
2
+ import { JwtError } from "../identity/WorkloadJwtVerifier.js";
3
+ import { SESSION_HEADER, SUBJECT_TOKEN_HEADER } from "./GatewayConfig.js";
4
+ /** RFC 8693's grant type, and the token types a subject token may be stated as. */
5
+ export const TOKEN_EXCHANGE_GRANT = "urn:ietf:params:oauth:grant-type:token-exchange";
6
+ const JWT_TOKEN_TYPES = new Set([
7
+ "urn:ietf:params:oauth:token-type:jwt",
8
+ "urn:ietf:params:oauth:token-type:id_token",
9
+ "urn:ietf:params:oauth:token-type:access_token",
10
+ ]);
11
+ /** What the exchange issues: an opaque token for this gateway, never a bearer anywhere else. */
12
+ export const ISSUED_TOKEN_TYPE = "urn:ietf:params:oauth:token-type:access_token";
13
+ /** The most sessions held at once; beyond it a new one is refused rather than an old one dropped. */
14
+ export const MAX_SESSIONS = 10_000;
15
+ /** The longest a subject token may be, in characters; a longer one is not a short-lived token. */
16
+ const MAX_TOKEN_LENGTH = 8_192;
17
+ /** How old a subject token may be: a short-lived token, minted for the conversation at hand. */
18
+ export const MAX_SUBJECT_TOKEN_AGE_SECONDS = 3_600;
19
+ /**
20
+ * The operator's identity provider: a signature from its key set, its issuer
21
+ * exactly, the gateway's audience, a token at most an hour old, and the
22
+ * subject in the configured claim, a string or a number of at most 200
23
+ * characters. Who the customer is, is the provider's statement; the gateway
24
+ * only pins it.
25
+ */
26
+ export class IssuerSubjectVerifier {
27
+ jwt;
28
+ issuer;
29
+ claim;
30
+ constructor(jwt, issuer, claim) {
31
+ this.jwt = jwt;
32
+ this.issuer = issuer;
33
+ this.claim = claim;
34
+ }
35
+ async verify(token) {
36
+ const verified = await this.jwt.verify(token);
37
+ if (verified.issuer !== this.issuer)
38
+ throw new JwtError("JWT_ISSUER_UNKNOWN");
39
+ const raw = verified.claims[this.claim];
40
+ const subject = typeof raw === "string"
41
+ ? raw
42
+ : typeof raw === "number" && Number.isFinite(raw)
43
+ ? String(raw)
44
+ : null;
45
+ if (subject === null || subject.length === 0 || subject.length > 200) {
46
+ throw new JwtError("JWT_SUBJECT_UNKNOWN");
47
+ }
48
+ return { subject, expiresAt: Number(verified.claims.exp) * 1_000 };
49
+ }
50
+ }
51
+ /**
52
+ * Subject-bound sessions. The app that starts an agent (a contact centre, a
53
+ * CRM, a customer's own portal) holds a short-lived token from its identity
54
+ * provider naming the customer in context. It gives the gateway that token,
55
+ * and the gateway pins the subject for the session:
56
+ *
57
+ * - by RFC 8693 token exchange: `POST /_agentsafe/v1/sessions` returns an
58
+ * opaque session token, which the agent presents in `AgentSafe-Session`;
59
+ * the gateway keeps only the token's digest, beside the subject;
60
+ * - or per request, the provider's token itself in `AgentSafe-Subject-Token`.
61
+ *
62
+ * Either way the subject comes from the provider's signature and nothing the
63
+ * agent sends can change it: the session token maps to a subject held here,
64
+ * and the provider's token is verified on every request. Both headers end at
65
+ * the gateway. A session lasts as long as this gateway process: it is held in
66
+ * memory, so behind several replicas present the provider's token per
67
+ * request, or keep a caller on one replica.
68
+ */
69
+ export class SubjectSessions {
70
+ verifier;
71
+ options;
72
+ sessions = new Map();
73
+ /**
74
+ * The session each subject token was last exchanged for, by the token's
75
+ * digest: exchanging a token again replaces its session rather than add
76
+ * one, so one token cannot fill the gateway's sessions.
77
+ */
78
+ byToken = new Map();
79
+ constructor(verifier, options) {
80
+ this.verifier = verifier;
81
+ this.options = options;
82
+ }
83
+ /** The sessions held now, expired ones dropped first. */
84
+ get size() {
85
+ this.expire();
86
+ return this.sessions.size;
87
+ }
88
+ /**
89
+ * RFC 8693 token exchange: a subject token in, a session token out. The
90
+ * request is the form the RFC defines; an actor token (delegation) is not
91
+ * accepted, and the only token issued is this gateway's session token. A
92
+ * token that does not verify is `invalid_request`, as the RFC says, with
93
+ * the stable code as its description and nothing from the token.
94
+ */
95
+ async exchange(form) {
96
+ const refuse = (error, description) => ({
97
+ status: 400,
98
+ body: { error, error_description: description },
99
+ });
100
+ const single = (name) => {
101
+ const values = form.getAll(name);
102
+ return values.length === 1 ? (values[0] ?? null) : null;
103
+ };
104
+ const grantType = single("grant_type");
105
+ if (grantType !== TOKEN_EXCHANGE_GRANT) {
106
+ return refuse("unsupported_grant_type", "TOKEN_EXCHANGE_ONLY");
107
+ }
108
+ const token = single("subject_token");
109
+ const tokenType = single("subject_token_type");
110
+ if (token === null || token.length === 0 || token.length > MAX_TOKEN_LENGTH) {
111
+ return refuse("invalid_request", "SUBJECT_TOKEN_MISSING");
112
+ }
113
+ if (tokenType === null || !JWT_TOKEN_TYPES.has(tokenType)) {
114
+ return refuse("invalid_request", "SUBJECT_TOKEN_TYPE_UNSUPPORTED");
115
+ }
116
+ const requested = form.getAll("requested_token_type");
117
+ if (requested.length > 1 || (requested.length === 1 && requested[0] !== ISSUED_TOKEN_TYPE)) {
118
+ return refuse("invalid_request", "REQUESTED_TOKEN_TYPE_UNSUPPORTED");
119
+ }
120
+ if (form.has("actor_token") || form.has("actor_token_type")) {
121
+ return refuse("invalid_request", "ACTOR_TOKEN_UNSUPPORTED");
122
+ }
123
+ let verified;
124
+ try {
125
+ verified = await this.verifier.verify(token);
126
+ }
127
+ catch (error) {
128
+ return refuse("invalid_request", error instanceof JwtError ? error.code : "JWT_INVALID");
129
+ }
130
+ this.expire();
131
+ const tokenDigest = SubjectSessions.digest(token);
132
+ const previous = this.byToken.get(tokenDigest);
133
+ if (previous !== undefined)
134
+ this.sessions.delete(previous);
135
+ if (this.sessions.size >= (this.options.maxSessions ?? MAX_SESSIONS)) {
136
+ return {
137
+ status: 503,
138
+ body: { error: "temporarily_unavailable", error_description: "SESSION_CAPACITY_EXCEEDED" },
139
+ };
140
+ }
141
+ const now = this.options.clock();
142
+ const expiresAt = Math.min(now + this.options.ttlSeconds * 1_000, verified.expiresAt);
143
+ const sessionToken = randomBytes(32).toString("base64url");
144
+ const digest = SubjectSessions.digest(sessionToken);
145
+ const session = {
146
+ subject: verified.subject,
147
+ expiresAt,
148
+ id: `sha256:${digest.slice(0, 12)}`,
149
+ };
150
+ this.sessions.set(digest, session);
151
+ this.byToken.set(tokenDigest, digest);
152
+ return {
153
+ status: 200,
154
+ body: {
155
+ access_token: sessionToken,
156
+ issued_token_type: ISSUED_TOKEN_TYPE,
157
+ token_type: "N_A",
158
+ expires_in: Math.max(Math.floor((expiresAt - now) / 1_000), 0),
159
+ },
160
+ session,
161
+ };
162
+ }
163
+ /**
164
+ * The session a request presents: null when it presents none, the session
165
+ * when it stands, and the refusal otherwise. A request may present one of
166
+ * the two headers, never both, since two would be two answers to whose
167
+ * session it is.
168
+ */
169
+ async resolve(headers) {
170
+ const sessionToken = headers[SESSION_HEADER];
171
+ const subjectToken = headers[SUBJECT_TOKEN_HEADER];
172
+ if (sessionToken !== undefined && subjectToken !== undefined)
173
+ return "SUBJECT_TOKEN_AMBIGUOUS";
174
+ if (sessionToken !== undefined) {
175
+ const digest = SubjectSessions.digest(sessionToken.trim());
176
+ const session = this.sessions.get(digest);
177
+ if (session === undefined)
178
+ return "SUBJECT_SESSION_INVALID";
179
+ if (session.expiresAt <= this.options.clock()) {
180
+ this.sessions.delete(digest);
181
+ return "SUBJECT_SESSION_INVALID";
182
+ }
183
+ return session;
184
+ }
185
+ if (subjectToken === undefined)
186
+ return null;
187
+ const token = subjectToken.trim();
188
+ if (token.length === 0 || token.length > MAX_TOKEN_LENGTH)
189
+ return "SUBJECT_TOKEN_INVALID";
190
+ try {
191
+ const verified = await this.verifier.verify(token);
192
+ if (verified.expiresAt <= this.options.clock())
193
+ return "SUBJECT_TOKEN_INVALID";
194
+ return {
195
+ subject: verified.subject,
196
+ expiresAt: verified.expiresAt,
197
+ id: `sha256:${SubjectSessions.digest(token).slice(0, 12)}`,
198
+ };
199
+ }
200
+ catch {
201
+ return "SUBJECT_TOKEN_INVALID";
202
+ }
203
+ }
204
+ expire() {
205
+ const now = this.options.clock();
206
+ for (const [digest, session] of this.sessions) {
207
+ if (session.expiresAt <= now)
208
+ this.sessions.delete(digest);
209
+ }
210
+ for (const [token, digest] of this.byToken) {
211
+ if (!this.sessions.has(digest))
212
+ this.byToken.delete(token);
213
+ }
214
+ }
215
+ static digest(token) {
216
+ return createHash("sha256").update(token, "utf8").digest("hex");
217
+ }
218
+ }
219
+ //# sourceMappingURL=SubjectSessions.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"SubjectSessions.js","sourceRoot":"","sources":["../../src/gateway/SubjectSessions.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,74 @@
1
+ import { type JsonObject, type TargetPrecondition } from "@decionis/agent-safe-pipeline";
2
+ import type { RegisteredEffect } from "../adapters/EffectEvidenceRegister.js";
3
+ /** The record the gateway writes for what it read back, beside the executor's BEAP record. */
4
+ export declare const GATEWAY_EFFECT_PROFILE = "agent-safe.gateway-effect/1";
5
+ export type Sha256 = `sha256:${string}`;
6
+ /**
7
+ * Why an attempt's effect stays `PENDING`: what the gateway was not asked to
8
+ * read back, or could not.
9
+ *
10
+ * - `EFFECT_UNDECLARED`: the write's operation names no effect, or no read;
11
+ * - `EFFECT_UNSTATED`: the call states none of the values its effect names;
12
+ * - `EFFECT_NOT_BOUND`: facts-only privacy, where no digest of the call's
13
+ * values may leave the gateway, so the grant commits to none;
14
+ * - `EFFECT_NOT_READ`: the upstream answered with a redirect, not a `2xx`;
15
+ * - `EFFECT_UNREADABLE`: the read after the write did not answer.
16
+ */
17
+ export type EffectPending = "EFFECT_UNDECLARED" | "EFFECT_UNSTATED" | "EFFECT_NOT_BOUND" | "EFFECT_NOT_READ" | "EFFECT_UNREADABLE";
18
+ /** What a write expects its read to state once it has landed, and the digest the grant commits to. */
19
+ export interface ExpectedEffect {
20
+ readonly expected: JsonObject;
21
+ readonly digest: Sha256;
22
+ }
23
+ /** What the gateway says about one forwarded attempt's effect, in the confirmation vocabulary. */
24
+ export interface EffectStatement {
25
+ readonly confirmation: "CONFIRMED" | "UNKNOWN" | "PENDING";
26
+ readonly reasonCodes: readonly string[];
27
+ }
28
+ /** One read after a write: the record the finalization carries, and what the report says. */
29
+ export interface ObservedEffect {
30
+ readonly record: RegisteredEffect;
31
+ readonly statement: EffectStatement;
32
+ }
33
+ /** What a read after a refusal showed: the target where it was, moved, or not stated. */
34
+ export type RefusalOutcome = "UNCHANGED" | "CHANGED" | "UNREADABLE";
35
+ /**
36
+ * The digest of an effect projection: SHA-256 over the RFC 8785 form of the
37
+ * operation that names it (`<profile>#<operation>`) and the projection. The
38
+ * one function makes the expected digest at capture and the observed one
39
+ * after the read, so equal projections are equal digests, which is all the
40
+ * authority compares. Only this gateway computes either, so it is total: a
41
+ * value another language's JSON writer would spell differently still has one
42
+ * digest here.
43
+ */
44
+ export declare function effectDigest(operation: string, projection: JsonObject): Sha256;
45
+ /**
46
+ * What a write's call lets the grant commit to: nothing when its operation
47
+ * names no effect (`null`), when the call states none of it (`{}`), or under
48
+ * facts-only privacy; otherwise the expectation and its digest.
49
+ */
50
+ export declare function expectEffect(operation: string, expected: JsonObject | null, factsOnly: boolean): ExpectedEffect | EffectPending;
51
+ /**
52
+ * The record of one read after a write, as the finalization carries it: the
53
+ * expectation against what the read stated, `null` when it did not answer.
54
+ * A match is `CONFIRMED`, the gateway's read-back being a method a profile
55
+ * declared; the authority still records it so only from an observer on its
56
+ * own allowlist. A difference is `UNKNOWN` with `EFFECT_MISMATCH`: something
57
+ * landed, and what it was is exactly what nobody can say. No answer is
58
+ * `PENDING`. The record carries digests, pointers and statuses: no value of
59
+ * the call or the answer.
60
+ */
61
+ export declare function effectRecord(input: {
62
+ readonly operation: string;
63
+ readonly effect: ExpectedEffect;
64
+ readonly observed: JsonObject | null;
65
+ readonly observedAt: string;
66
+ }): ObservedEffect;
67
+ /**
68
+ * A read after a refusal against the read before the decision: the version
69
+ * the same, another, or none stated. Unchanged says no write landed on that
70
+ * resource between the two reads, by any route; it says nothing about any
71
+ * other resource or any other time.
72
+ */
73
+ export declare function refusalOutcome(before: TargetPrecondition, after: TargetPrecondition | null): RefusalOutcome;
74
+ //# sourceMappingURL=TargetEffect.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"TargetEffect.d.ts","sourceRoot":"","sources":["../../src/gateway/TargetEffect.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,UAAU,EAEf,KAAK,kBAAkB,EACxB,MAAM,+BAA+B,CAAC;AAEvC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAE9E,8FAA8F;AAC9F,eAAO,MAAM,sBAAsB,gCAAgC,CAAC;AAEpE,MAAM,MAAM,MAAM,GAAG,UAAU,MAAM,EAAE,CAAC;AAExC;;;;;;;;;;GAUG;AACH,MAAM,MAAM,aAAa,GACrB,mBAAmB,GACnB,iBAAiB,GACjB,kBAAkB,GAClB,iBAAiB,GACjB,mBAAmB,CAAC;AAExB,sGAAsG;AACtG,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,kGAAkG;AAClG,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,YAAY,EAAE,WAAW,GAAG,SAAS,GAAG,SAAS,CAAC;IAC3D,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAED,6FAA6F;AAC7F,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;CACrC;AAED,yFAAyF;AACzF,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,SAAS,GAAG,YAAY,CAAC;AAMpE;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,GAAG,MAAM,CAE9E;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,UAAU,GAAG,IAAI,EAC3B,SAAS,EAAE,OAAO,GACjB,cAAc,GAAG,aAAa,CAKhC;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,UAAU,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B,GAAG,cAAc,CAyCjB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,kBAAkB,EAC1B,KAAK,EAAE,kBAAkB,GAAG,IAAI,GAC/B,cAAc,CAGhB"}
@@ -0,0 +1,95 @@
1
+ import { createHash } from "node:crypto";
2
+ import { Rfc8785, } from "@decionis/agent-safe-pipeline";
3
+ import { compareEffect } from "../adapters/EffectComparison.js";
4
+ /** The record the gateway writes for what it read back, beside the executor's BEAP record. */
5
+ export const GATEWAY_EFFECT_PROFILE = "agent-safe.gateway-effect/1";
6
+ function digest(value) {
7
+ return `sha256:${createHash("sha256").update(Rfc8785.stringify(value)).digest("hex")}`;
8
+ }
9
+ /**
10
+ * The digest of an effect projection: SHA-256 over the RFC 8785 form of the
11
+ * operation that names it (`<profile>#<operation>`) and the projection. The
12
+ * one function makes the expected digest at capture and the observed one
13
+ * after the read, so equal projections are equal digests, which is all the
14
+ * authority compares. Only this gateway computes either, so it is total: a
15
+ * value another language's JSON writer would spell differently still has one
16
+ * digest here.
17
+ */
18
+ export function effectDigest(operation, projection) {
19
+ return digest({ operation, effect: projection });
20
+ }
21
+ /**
22
+ * What a write's call lets the grant commit to: nothing when its operation
23
+ * names no effect (`null`), when the call states none of it (`{}`), or under
24
+ * facts-only privacy; otherwise the expectation and its digest.
25
+ */
26
+ export function expectEffect(operation, expected, factsOnly) {
27
+ if (expected === null)
28
+ return "EFFECT_UNDECLARED";
29
+ if (factsOnly)
30
+ return "EFFECT_NOT_BOUND";
31
+ if (Object.keys(expected).length === 0)
32
+ return "EFFECT_UNSTATED";
33
+ return { expected, digest: effectDigest(operation, expected) };
34
+ }
35
+ /**
36
+ * The record of one read after a write, as the finalization carries it: the
37
+ * expectation against what the read stated, `null` when it did not answer.
38
+ * A match is `CONFIRMED`, the gateway's read-back being a method a profile
39
+ * declared; the authority still records it so only from an observer on its
40
+ * own allowlist. A difference is `UNKNOWN` with `EFFECT_MISMATCH`: something
41
+ * landed, and what it was is exactly what nobody can say. No answer is
42
+ * `PENDING`. The record carries digests, pointers and statuses: no value of
43
+ * the call or the answer.
44
+ */
45
+ export function effectRecord(input) {
46
+ const { comparison, mismatched } = compareEffect(input.effect.expected, input.observed);
47
+ const confirmation = comparison === "MATCH" ? "CONFIRMED" : comparison === "MISMATCH" ? "UNKNOWN" : "PENDING";
48
+ const observedEffectDigest = input.observed === null ? null : effectDigest(input.operation, input.observed);
49
+ const evidence = {
50
+ profile: GATEWAY_EFFECT_PROFILE,
51
+ type: "EFFECT_EVIDENCE",
52
+ operation: input.operation,
53
+ observation_method: "READ_AFTER_WRITE",
54
+ expected_effect_digest: input.effect.digest,
55
+ observed_effect_digest: observedEffectDigest,
56
+ comparison,
57
+ mismatched_fields: [...mismatched],
58
+ confirmation: { status: confirmation },
59
+ evidence_status: input.observed === null ? "INCOMPLETE" : "COMPLETE",
60
+ observed_at: input.observedAt,
61
+ };
62
+ const reasonCodes = comparison === "MATCH"
63
+ ? []
64
+ : [comparison === "MISMATCH" ? "EFFECT_MISMATCH" : "EFFECT_UNREADABLE"];
65
+ return {
66
+ record: {
67
+ evidence,
68
+ outcome: "COMMITTED",
69
+ comparison,
70
+ mismatched,
71
+ confirmation,
72
+ observedEffectDigest,
73
+ expectedEffectDigest: input.effect.digest,
74
+ responseDigest: null,
75
+ providerReference: null,
76
+ observationMethod: "READ_AFTER_WRITE",
77
+ evidenceDigest: digest(evidence),
78
+ reasonCodes,
79
+ receipt: { comparison: "ABSENT", status: null, digest: null },
80
+ },
81
+ statement: { confirmation, reasonCodes },
82
+ };
83
+ }
84
+ /**
85
+ * A read after a refusal against the read before the decision: the version
86
+ * the same, another, or none stated. Unchanged says no write landed on that
87
+ * resource between the two reads, by any route; it says nothing about any
88
+ * other resource or any other time.
89
+ */
90
+ export function refusalOutcome(before, after) {
91
+ if (after === null)
92
+ return "UNREADABLE";
93
+ return after.version === before.version ? "UNCHANGED" : "CHANGED";
94
+ }
95
+ //# sourceMappingURL=TargetEffect.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"TargetEffect.js","sourceRoot":"","sources":["../../src/gateway/TargetEffect.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,70 @@
1
+ import type { ApiProfile, ApiRequest, TargetPrecondition } from "@decionis/agent-safe-pipeline";
2
+ import { type EffectPending, type ExpectedEffect, type ObservedEffect, type RefusalOutcome } from "./TargetEffect.js";
3
+ import type { Upstream } from "./Upstream.js";
4
+ /**
5
+ * What the gateway read of one profiled write's target before the authority
6
+ * was asked: the read its profile names, the precondition the answer stated,
7
+ * and what the grant commits the write's effect to, or why it commits to none.
8
+ */
9
+ export interface TargetPlan {
10
+ /** The write's operation in the profile. */
11
+ readonly operation: string;
12
+ readonly read: ApiRequest;
13
+ readonly precondition: TargetPrecondition;
14
+ readonly effect: ExpectedEffect | EffectPending;
15
+ }
16
+ /** Why a write was refused before the authority was asked: its target stated no usable version. */
17
+ export interface TargetRefusal {
18
+ readonly reasonCodes: readonly ["TARGET_STATE_UNREADABLE", string];
19
+ }
20
+ /** One read of a write's target after a refusal, against the read before the decision. */
21
+ export interface RefusalRead {
22
+ readonly outcome: RefusalOutcome;
23
+ readonly version: string | null;
24
+ readonly readAt: string;
25
+ }
26
+ export interface TargetReaderOptions {
27
+ readonly profile: ApiProfile;
28
+ readonly upstream: Upstream;
29
+ readonly clock: () => number;
30
+ /** The reason code for a send that threw, as the gateway names a failed forward. */
31
+ readonly failure: (error: unknown) => string;
32
+ }
33
+ /**
34
+ * The gateway's reads of a write's target, the one read its API profile
35
+ * names, at three moments: before the authority is asked, so the intent
36
+ * binds the version it is decided against; after an `ALLOW` the upstream
37
+ * answered with a `2xx`, so what landed is compared with what was
38
+ * authorised; and after a refusal, so the target is seen to have stayed
39
+ * where it was. Every read is a `GET` the gateway makes as itself
40
+ * (`Upstream.ownHeaders`), bounded like a forward, and nothing it reads is
41
+ * relayed to a caller.
42
+ */
43
+ export declare class TargetReader {
44
+ private readonly options;
45
+ constructor(options: TargetReaderOptions);
46
+ /**
47
+ * The plan for a write, or null when its operation names no read. A read
48
+ * that does not answer `2xx`, or whose answer states no usable version, is
49
+ * a refusal: the write is never decided against no version at all.
50
+ */
51
+ plan(operation: string, request: ApiRequest, factsOnly: boolean): Promise<TargetPlan | TargetRefusal | null>;
52
+ /** The read after a write the upstream answered `2xx`, against what the grant committed to. */
53
+ effect(plan: TargetPlan, effect: ExpectedEffect): Promise<ObservedEffect>;
54
+ /** The read after a refusal: the version now, against the one the decision was asked about. */
55
+ refusal(plan: TargetPlan): Promise<RefusalRead>;
56
+ /** An operation as the effect digest names it: `<profile>#<operation>`, as a precondition's source does. */
57
+ private named;
58
+ /**
59
+ * One `GET` of the target: its headers, which the relay already names in
60
+ * lower case, and its body when it is JSON; or why there is no answer to
61
+ * read, a status past `2xx` included (the transport delivers no `1xx`).
62
+ */
63
+ private read;
64
+ /**
65
+ * A read's query as a query string, each name and value percent-encoded:
66
+ * the exact values its profile operation names, one string each.
67
+ */
68
+ private static search;
69
+ }
70
+ //# sourceMappingURL=TargetReader.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"TargetReader.d.ts","sourceRoot":"","sources":["../../src/gateway/TargetReader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,UAAU,EACV,UAAU,EAEV,kBAAkB,EACnB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAIL,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,cAAc,EACpB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,4CAA4C;IAC5C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,aAAa,CAAC;CACjD;AAED,mGAAmG;AACnG,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,WAAW,EAAE,SAAS,CAAC,yBAAyB,EAAE,MAAM,CAAC,CAAC;CACpE;AAED,0FAA0F;AAC1F,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAID,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,MAAM,CAAC;IAC7B,oFAAoF;IACpF,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAAC;CAC9C;AAED;;;;;;;;;GASG;AACH,qBAAa,YAAY;IACJ,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,mBAAmB;IAEhE;;;;OAIG;IACU,IAAI,CACf,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,UAAU,EACnB,SAAS,EAAE,OAAO,GACjB,OAAO,CAAC,UAAU,GAAG,aAAa,GAAG,IAAI,CAAC;IAkB7C,+FAA+F;IAClF,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;IAatF,+FAA+F;IAClF,OAAO,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC;IAa5D,4GAA4G;IAC5G,OAAO,CAAC,KAAK;IAIb;;;;OAIG;YACW,IAAI;IA4BlB;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,MAAM;CAMtB"}
@@ -0,0 +1,106 @@
1
+ import { effectRecord, expectEffect, refusalOutcome, } from "./TargetEffect.js";
2
+ /**
3
+ * The gateway's reads of a write's target, the one read its API profile
4
+ * names, at three moments: before the authority is asked, so the intent
5
+ * binds the version it is decided against; after an `ALLOW` the upstream
6
+ * answered with a `2xx`, so what landed is compared with what was
7
+ * authorised; and after a refusal, so the target is seen to have stayed
8
+ * where it was. Every read is a `GET` the gateway makes as itself
9
+ * (`Upstream.ownHeaders`), bounded like a forward, and nothing it reads is
10
+ * relayed to a caller.
11
+ */
12
+ export class TargetReader {
13
+ options;
14
+ constructor(options) {
15
+ this.options = options;
16
+ }
17
+ /**
18
+ * The plan for a write, or null when its operation names no read. A read
19
+ * that does not answer `2xx`, or whose answer states no usable version, is
20
+ * a refusal: the write is never decided against no version at all.
21
+ */
22
+ async plan(operation, request, factsOnly) {
23
+ const { profile } = this.options;
24
+ const read = profile.stateRead(request);
25
+ if (read === null)
26
+ return null;
27
+ const answered = await this.read(read);
28
+ if ("code" in answered)
29
+ return { reasonCodes: ["TARGET_STATE_UNREADABLE", answered.code] };
30
+ const precondition = profile.precondition(operation, answered.answer, answered.at);
31
+ if (precondition === null) {
32
+ return { reasonCodes: ["TARGET_STATE_UNREADABLE", "TARGET_VERSION_UNSTATED"] };
33
+ }
34
+ return {
35
+ operation,
36
+ read,
37
+ precondition,
38
+ effect: expectEffect(this.named(operation), profile.expectedEffect(request), factsOnly),
39
+ };
40
+ }
41
+ /** The read after a write the upstream answered `2xx`, against what the grant committed to. */
42
+ async effect(plan, effect) {
43
+ const answered = await this.read(plan.read);
44
+ return effectRecord({
45
+ operation: this.named(plan.operation),
46
+ effect,
47
+ observed: "code" in answered
48
+ ? null
49
+ : this.options.profile.observedEffect(plan.operation, answered.answer, effect.expected),
50
+ observedAt: new Date(this.options.clock()).toISOString(),
51
+ });
52
+ }
53
+ /** The read after a refusal: the version now, against the one the decision was asked about. */
54
+ async refusal(plan) {
55
+ const answered = await this.read(plan.read);
56
+ const after = "code" in answered
57
+ ? null
58
+ : this.options.profile.precondition(plan.operation, answered.answer, answered.at);
59
+ return {
60
+ outcome: refusalOutcome(plan.precondition, after),
61
+ version: after?.version ?? null,
62
+ readAt: new Date(this.options.clock()).toISOString(),
63
+ };
64
+ }
65
+ /** An operation as the effect digest names it: `<profile>#<operation>`, as a precondition's source does. */
66
+ named(operation) {
67
+ return `${this.options.profile.id}#${operation}`;
68
+ }
69
+ /**
70
+ * One `GET` of the target: its headers, which the relay already names in
71
+ * lower case, and its body when it is JSON; or why there is no answer to
72
+ * read, a status past `2xx` included (the transport delivers no `1xx`).
73
+ */
74
+ async read(read) {
75
+ const { upstream } = this.options;
76
+ let status;
77
+ let headers;
78
+ let body;
79
+ try {
80
+ ({ status, headers, body } = await upstream.send("GET", read.path, TargetReader.search(read.query ?? {}), upstream.ownHeaders(), Buffer.alloc(0), upstream.signal()));
81
+ }
82
+ catch (error) {
83
+ return { code: this.options.failure(error) };
84
+ }
85
+ if (status >= 300)
86
+ return { code: `UPSTREAM_STATUS_${status}` };
87
+ const answer = { headers: Object.fromEntries(headers) };
88
+ const at = new Date(this.options.clock());
89
+ try {
90
+ return { answer: { ...answer, body: JSON.parse(body.toString()) }, at };
91
+ }
92
+ catch {
93
+ // A body that is not JSON states nothing there; its headers still may.
94
+ return { answer, at };
95
+ }
96
+ }
97
+ /**
98
+ * A read's query as a query string, each name and value percent-encoded:
99
+ * the exact values its profile operation names, one string each.
100
+ */
101
+ static search(query) {
102
+ const pairs = Object.entries(query).map(([name, value]) => `${encodeURIComponent(name)}=${encodeURIComponent(String(value))}`);
103
+ return pairs.length === 0 ? "" : `?${pairs.join("&")}`;
104
+ }
105
+ }
106
+ //# sourceMappingURL=TargetReader.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"TargetReader.js","sourceRoot":"","sources":["../../src/gateway/TargetReader.ts"],"names":[],"mappings":"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"}
@@ -21,6 +21,22 @@ export interface UpstreamOptions {
21
21
  readonly hostOnlyCookies?: boolean;
22
22
  /** Relay every response under a sandboxing content security policy (a hosted gateway). */
23
23
  readonly sandboxed?: boolean;
24
+ /**
25
+ * The credential the gateway presents in place of its caller: the header,
26
+ * lower-case, and its value, read at each request so a rotation applies at
27
+ * once. A caller's own value of that header is never forwarded.
28
+ */
29
+ readonly credential?: {
30
+ readonly header: string;
31
+ readonly value: () => string;
32
+ };
33
+ /**
34
+ * The gateway's own token, sent as `agentsafe-gateway-token` so the
35
+ * upstream can tell the request came through this gateway; read at each
36
+ * request, like the credential. A caller's value of it is never forwarded,
37
+ * with or without one.
38
+ */
39
+ readonly gatewayToken?: () => string;
24
40
  }
25
41
  /**
26
42
  * The policy a hosted gateway adds to every relayed response. A browser
@@ -54,10 +70,20 @@ export declare class Upstream {
54
70
  constructor(options: UpstreamOptions);
55
71
  get url(): string;
56
72
  get timeoutMs(): number;
73
+ /** Whether a value can be sent as one header: visible characters, spaces and tabs, nothing else. */
74
+ static isHeaderValue(value: string): boolean;
57
75
  /** The upstream URL for a path and query, under the configured base path. */
58
76
  target(path: string, search: string): string;
59
77
  /** The headers the upstream receives for a client's request, plus what the gateway adds. */
60
78
  headersFor(request: InterceptedRequest, extra?: Readonly<Record<string, string>>): Record<string, string>;
79
+ /**
80
+ * The headers of a read the gateway makes on its own behalf, of the target
81
+ * a write names: none of any caller's, only what the gateway presents as
82
+ * itself, its upstream credential and its gateway token, when it holds them.
83
+ */
84
+ ownHeaders(): Record<string, string>;
85
+ /** The headers, with the gateway's credential and token set over whatever they held. */
86
+ private identified;
61
87
  /**
62
88
  * Sends one request and reads the whole answer, bounded. A transport
63
89
  * failure throws; the caller decides what a failure after dispatch means.