@kya-os/checkpoint-shared 1.3.1 → 1.5.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 (161) hide show
  1. package/CHANGELOG.md +127 -2
  2. package/dist/beacon-types/index.d.mts +441 -432
  3. package/dist/beacon-types/index.d.mts.map +1 -0
  4. package/dist/beacon-types/index.d.ts +441 -432
  5. package/dist/beacon-types/index.d.ts.map +1 -0
  6. package/dist/beacon-types/index.js +198 -182
  7. package/dist/beacon-types/index.mjs +197 -179
  8. package/dist/beacon-types/index.mjs.map +1 -0
  9. package/dist/browser-posture-cookie-Dmq9Brf_.d.mts +5 -0
  10. package/dist/browser-posture-cookie-Dmq9Brf_.d.mts.map +1 -0
  11. package/dist/browser-posture-cookie-Dmq9Brf_.d.ts +5 -0
  12. package/dist/browser-posture-cookie-Dmq9Brf_.d.ts.map +1 -0
  13. package/dist/browser-posture-cookie.d.mts +2 -0
  14. package/dist/browser-posture-cookie.d.ts +2 -0
  15. package/dist/browser-posture-cookie.js +1 -0
  16. package/dist/browser-posture-cookie.mjs +2 -0
  17. package/dist/browser-posture-cookie.mjs.map +1 -0
  18. package/dist/browser-posture-report.d.mts +50 -82
  19. package/dist/browser-posture-report.d.mts.map +1 -0
  20. package/dist/browser-posture-report.d.ts +50 -82
  21. package/dist/browser-posture-report.d.ts.map +1 -0
  22. package/dist/browser-posture-report.js +1 -1
  23. package/dist/browser-posture-report.mjs +2 -1
  24. package/dist/browser-posture-report.mjs.map +1 -0
  25. package/dist/browser-posture.d.mts +80 -111
  26. package/dist/browser-posture.d.mts.map +1 -0
  27. package/dist/browser-posture.d.ts +80 -111
  28. package/dist/browser-posture.d.ts.map +1 -0
  29. package/dist/browser-posture.js +143 -4164
  30. package/dist/browser-posture.mjs +142 -4161
  31. package/dist/browser-posture.mjs.map +1 -0
  32. package/dist/browser.d.mts +323 -316
  33. package/dist/browser.d.mts.map +1 -0
  34. package/dist/browser.d.ts +323 -316
  35. package/dist/browser.d.ts.map +1 -0
  36. package/dist/browser.js +1 -1
  37. package/dist/browser.mjs +2 -1
  38. package/dist/browser.mjs.map +1 -0
  39. package/dist/canonical-signer/index.d.mts +38 -33
  40. package/dist/canonical-signer/index.d.mts.map +1 -0
  41. package/dist/canonical-signer/index.d.ts +38 -33
  42. package/dist/canonical-signer/index.d.ts.map +1 -0
  43. package/dist/canonical-signer/index.js +411 -181
  44. package/dist/canonical-signer/index.mjs +383 -175
  45. package/dist/canonical-signer/index.mjs.map +1 -0
  46. package/dist/clearance.d.mts +30 -0
  47. package/dist/clearance.d.mts.map +1 -0
  48. package/dist/clearance.d.ts +30 -0
  49. package/dist/clearance.d.ts.map +1 -0
  50. package/dist/clearance.js +120 -0
  51. package/dist/clearance.mjs +112 -0
  52. package/dist/clearance.mjs.map +1 -0
  53. package/dist/client-ip-1y2iXAYW.js +237 -0
  54. package/dist/client-ip-HOfe6ucV.mjs +215 -0
  55. package/dist/client-ip-HOfe6ucV.mjs.map +1 -0
  56. package/dist/deploy/index.d.mts +375 -810
  57. package/dist/deploy/index.d.mts.map +1 -0
  58. package/dist/deploy/index.d.ts +375 -810
  59. package/dist/deploy/index.d.ts.map +1 -0
  60. package/dist/deploy/index.js +505 -413
  61. package/dist/deploy/index.mjs +504 -410
  62. package/dist/deploy/index.mjs.map +1 -0
  63. package/dist/errors/index.d.mts +101 -101
  64. package/dist/errors/index.d.mts.map +1 -0
  65. package/dist/errors/index.d.ts +101 -101
  66. package/dist/errors/index.d.ts.map +1 -0
  67. package/dist/errors/index.js +341 -314
  68. package/dist/errors/index.mjs +340 -311
  69. package/dist/errors/index.mjs.map +1 -0
  70. package/dist/external-jr_S4iSS.d.mts +4187 -0
  71. package/dist/external-jr_S4iSS.d.mts.map +1 -0
  72. package/dist/external-jr_S4iSS.d.ts +4187 -0
  73. package/dist/external-jr_S4iSS.d.ts.map +1 -0
  74. package/dist/gateway/index.d.mts +154 -550
  75. package/dist/gateway/index.d.mts.map +1 -0
  76. package/dist/gateway/index.d.ts +154 -550
  77. package/dist/gateway/index.d.ts.map +1 -0
  78. package/dist/gateway/index.js +117 -81
  79. package/dist/gateway/index.mjs +116 -78
  80. package/dist/gateway/index.mjs.map +1 -0
  81. package/dist/gateway-client-ip.d.mts +59 -0
  82. package/dist/gateway-client-ip.d.mts.map +1 -0
  83. package/dist/gateway-client-ip.d.ts +59 -0
  84. package/dist/gateway-client-ip.d.ts.map +1 -0
  85. package/dist/gateway-client-ip.js +149 -0
  86. package/dist/gateway-client-ip.mjs +139 -0
  87. package/dist/gateway-client-ip.mjs.map +1 -0
  88. package/dist/index.d.mts +15523 -38968
  89. package/dist/index.d.mts.map +1 -0
  90. package/dist/index.d.ts +15523 -38968
  91. package/dist/index.d.ts.map +1 -0
  92. package/dist/index.js +14950 -16029
  93. package/dist/index.mjs +14846 -15955
  94. package/dist/index.mjs.map +1 -0
  95. package/dist/mcpi/agentshield-api/index.d.mts +45 -44
  96. package/dist/mcpi/agentshield-api/index.d.mts.map +1 -0
  97. package/dist/mcpi/agentshield-api/index.d.ts +45 -44
  98. package/dist/mcpi/agentshield-api/index.d.ts.map +1 -0
  99. package/dist/mcpi/agentshield-api/index.js +0 -2
  100. package/dist/mcpi/agentshield-api/index.mjs +1 -1
  101. package/dist/mcpi/approval-grant/index.d.mts +63 -61
  102. package/dist/mcpi/approval-grant/index.d.mts.map +1 -0
  103. package/dist/mcpi/approval-grant/index.d.ts +63 -61
  104. package/dist/mcpi/approval-grant/index.d.ts.map +1 -0
  105. package/dist/mcpi/approval-grant/index.js +220 -140
  106. package/dist/mcpi/approval-grant/index.mjs +219 -137
  107. package/dist/mcpi/approval-grant/index.mjs.map +1 -0
  108. package/dist/mcpi/dashboard-config/index.d.mts +2395 -13915
  109. package/dist/mcpi/dashboard-config/index.d.mts.map +1 -0
  110. package/dist/mcpi/dashboard-config/index.d.ts +2395 -13915
  111. package/dist/mcpi/dashboard-config/index.d.ts.map +1 -0
  112. package/dist/mcpi/dashboard-config/index.js +605 -458
  113. package/dist/mcpi/dashboard-config/index.mjs +604 -455
  114. package/dist/mcpi/dashboard-config/index.mjs.map +1 -0
  115. package/dist/mcpi/multibase-ed25519.d.mts +10 -8
  116. package/dist/mcpi/multibase-ed25519.d.mts.map +1 -0
  117. package/dist/mcpi/multibase-ed25519.d.ts +10 -8
  118. package/dist/mcpi/multibase-ed25519.d.ts.map +1 -0
  119. package/dist/mcpi/multibase-ed25519.js +182 -106
  120. package/dist/mcpi/multibase-ed25519.mjs +181 -103
  121. package/dist/mcpi/multibase-ed25519.mjs.map +1 -0
  122. package/dist/patterns-CkRVOdtV.js +243 -0
  123. package/dist/patterns-DzkGy_qk.mjs +173 -0
  124. package/dist/patterns-DzkGy_qk.mjs.map +1 -0
  125. package/dist/project-verification-key-C3L5rd8a.js +41 -0
  126. package/dist/project-verification-key-CgSVX9_m.mjs +37 -0
  127. package/dist/project-verification-key-CgSVX9_m.mjs.map +1 -0
  128. package/dist/rolldown-runtime-iY2fYEqi.mjs +19 -0
  129. package/dist/schemas-BmjNLAE7.js +5677 -0
  130. package/dist/schemas-DxY-dk9y.mjs +5511 -0
  131. package/dist/schemas-DxY-dk9y.mjs.map +1 -0
  132. package/dist/signals/index.d.mts +125 -115
  133. package/dist/signals/index.d.mts.map +1 -0
  134. package/dist/signals/index.d.ts +125 -115
  135. package/dist/signals/index.d.ts.map +1 -0
  136. package/dist/signals/index.js +1693 -1536
  137. package/dist/signals/index.mjs +1692 -1533
  138. package/dist/signals/index.mjs.map +1 -0
  139. package/dist/test-fixtures/index.d.mts +124 -119
  140. package/dist/test-fixtures/index.d.mts.map +1 -0
  141. package/dist/test-fixtures/index.d.ts +124 -119
  142. package/dist/test-fixtures/index.d.ts.map +1 -0
  143. package/dist/test-fixtures/index.js +460 -228
  144. package/dist/test-fixtures/index.mjs +459 -225
  145. package/dist/test-fixtures/index.mjs.map +1 -0
  146. package/dist/tool-protection/index.d.mts +368 -1067
  147. package/dist/tool-protection/index.d.mts.map +1 -0
  148. package/dist/tool-protection/index.d.ts +368 -1067
  149. package/dist/tool-protection/index.d.ts.map +1 -0
  150. package/dist/tool-protection/index.js +366 -285
  151. package/dist/tool-protection/index.mjs +365 -282
  152. package/dist/tool-protection/index.mjs.map +1 -0
  153. package/fixtures/bot-signal-resolution.json +142 -0
  154. package/fixtures/browser-posture-claims.json +421 -0
  155. package/fixtures/browser-posture-headers.json +46 -0
  156. package/fixtures/detection/reason-codes.json +10 -1
  157. package/fixtures/kya-http/challenge.delegation.fetcher-200.json +9 -3
  158. package/fixtures/kya-http/challenge.delegation.full.json +9 -3
  159. package/fixtures/kya-http/challenge.delegation.minimal.json +9 -3
  160. package/fixtures/kya-http/error-codes.json +7 -2
  161. package/package.json +21 -7
@@ -0,0 +1,149 @@
1
+ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
2
+ const require_schemas = require('./schemas-BmjNLAE7.js');
3
+ const require_client_ip = require('./client-ip-1y2iXAYW.js');
4
+ let jose = require("jose");
5
+
6
+ //#region src/gateway-client-ip.ts
7
+ /**
8
+ * Signed client-identity token minted by the Checkpoint Cloudflare gateway
9
+ * worker and verified by an origin-side Checkpoint SDK (KYA-1121 follow-up).
10
+ *
11
+ * The gateway already forwards the connecting IP as the plain `KYA-Client-IP`
12
+ * / `X-Forwarded-For` headers (see `proxy.ts`), which every adapter behind a
13
+ * KNOWN, trusted peer (Cloudflare's own published edge ranges) can trust.
14
+ * Behind an additional untrusted hop - e.g. a PaaS's own reverse proxy
15
+ * (Railway, Render, Fly) sitting between Cloudflare and the origin - the
16
+ * origin's TCP peer is that PaaS's proxy, not Cloudflare, so the plain
17
+ * header can never be trusted there: any caller reaching the PaaS's edge
18
+ * directly could set it too. This ES256-signed JWS carries the SAME claim
19
+ * with a signature only the gateway's private key can produce, so an origin
20
+ * can trust it regardless of what sits between it and the gateway.
21
+ *
22
+ * One gateway-wide asymmetric key (not a per-project secret): the worker
23
+ * holds the private JWK (`GATEWAY_CLIENT_IP_SIGNING_JWK`), the platform
24
+ * publishes the public JWK at `/.well-known/jwks.json`
25
+ * (`GATEWAY_CLIENT_IP_PUBLIC_JWK`). Rotation is by `kid`.
26
+ */
27
+ const GATEWAY_CLIENT_IP_TOKEN_HEADER = "KYA-Client-IP-Token";
28
+ const GATEWAY_CLIENT_IP_ISSUER = "checkpoint:gateway-client-ip:v1";
29
+ const GATEWAY_CLIENT_IP_TYPE = "checkpoint-client-ip+jwt";
30
+ /**
31
+ * Token lifetime, seconds. A verifier MUST additionally bind `cid`/`host` to
32
+ * the request it's verifying (see {@link VerifyGatewayClientIpOptions}) -
33
+ * without that binding, a token captured on an untrusted hop within this
34
+ * window is replayable onto a DIFFERENT request the gateway never actually
35
+ * saw, and the `ip` it carries is not inert: it feeds the same IP-reputation
36
+ * and vendor-cross-match signals as any other resolved client IP, which do
37
+ * influence the engine's enforcement decision. Binding `cid` (unique per
38
+ * request) is what keeps a captured token scoped to the one request the
39
+ * gateway minted it for.
40
+ */
41
+ const GATEWAY_CLIENT_IP_TTL_SECONDS = 60;
42
+ /** Clock-skew allowance applied to `exp` (via jose's `clockTolerance`) and independently to `iat` below. */
43
+ const CLOCK_SKEW_SECONDS = 30;
44
+ function isIpv4Literal(value) {
45
+ const parts = value.split(".");
46
+ return parts.length === 4 && parts.every((part) => /^(0|[1-9]\d{0,2})$/.test(part) && Number(part) <= 255);
47
+ }
48
+ /** True when `value` is a literal IPv4 or IPv6 address - never resolves a hostname. */
49
+ function isIpLiteral(value) {
50
+ return isIpv4Literal(value) || require_client_ip.parseIpv6(value) !== null;
51
+ }
52
+ const GatewayClientIpClaimsSchema = require_schemas.object({
53
+ iss: require_schemas.literal(GATEWAY_CLIENT_IP_ISSUER),
54
+ aud: require_schemas.string().min(1),
55
+ ip: require_schemas.string().refine(isIpLiteral, "ip must be a literal IPv4 or IPv6 address"),
56
+ cid: require_schemas.string().min(1),
57
+ host: require_schemas.string().min(1),
58
+ iat: require_schemas.number().int().nonnegative(),
59
+ exp: require_schemas.number().int().positive()
60
+ });
61
+ /** The gateway's own EC P-256 public key, as published in `/.well-known/jwks.json`. */
62
+ const GatewayClientIpPublicJwkSchema = require_schemas.object({
63
+ kty: require_schemas.literal("EC"),
64
+ crv: require_schemas.literal("P-256"),
65
+ alg: require_schemas.literal("ES256"),
66
+ use: require_schemas.literal("sig"),
67
+ kid: require_schemas.string().min(1),
68
+ x: require_schemas.string().min(1),
69
+ y: require_schemas.string().min(1)
70
+ });
71
+ /** The private half the gateway worker holds (`GATEWAY_CLIENT_IP_SIGNING_JWK`). */
72
+ const GatewayClientIpPrivateJwkSchema = GatewayClientIpPublicJwkSchema.extend({ d: require_schemas.string().min(1) });
73
+ /**
74
+ * Import a gateway client-ip JWK (private or public half) into a usable jose
75
+ * key. Callers on a hot path - the gateway worker signs on every proxied
76
+ * request - should import once per isolate and reuse the resulting key
77
+ * rather than calling this per request.
78
+ */
79
+ async function importGatewayClientIpSigningKey(jwk) {
80
+ return (0, jose.importJWK)(jwk, "ES256");
81
+ }
82
+ /**
83
+ * Mint a compact JWS carrying the gateway's client-identity claim.
84
+ * `privateKey` must already be imported (see {@link importGatewayClientIpSigningKey}) -
85
+ * this function never imports a key itself, so a cached key can be reused
86
+ * across every signed request.
87
+ */
88
+ async function signGatewayClientIp(privateKey, kid, input, now = Math.floor(Date.now() / 1e3)) {
89
+ if (!kid || !input.aud || !input.cid || !input.host || !isIpLiteral(input.ip)) throw new Error("Invalid gateway client-ip signing input");
90
+ const claims = {
91
+ iss: GATEWAY_CLIENT_IP_ISSUER,
92
+ aud: input.aud,
93
+ ip: input.ip,
94
+ cid: input.cid,
95
+ host: input.host,
96
+ iat: now,
97
+ exp: now + 60
98
+ };
99
+ return new jose.SignJWT(claims).setProtectedHeader({
100
+ alg: "ES256",
101
+ typ: GATEWAY_CLIENT_IP_TYPE,
102
+ kid
103
+ }).sign(privateKey);
104
+ }
105
+ /**
106
+ * Verify a gateway client-ip token against a JWKS document (as served by
107
+ * `/.well-known/jwks.json`) and return its claims, or `null` on ANY failure
108
+ * - malformed token, unknown `kid`, wrong `alg`, a tampered/expired/
109
+ * mismatched claim, or a `cid`/`host` that doesn't match the request being
110
+ * verified. Never throws: a missing or invalid token must change nothing
111
+ * about the caller's IP resolution.
112
+ */
113
+ async function verifyGatewayClientIp(token, jwks, options) {
114
+ if (!token || !options.projectId || !options.expectedCid || !options.expectedHost) return null;
115
+ const now = options.now ?? Math.floor(Date.now() / 1e3);
116
+ try {
117
+ const ecKeys = jwks.keys.filter((key) => key.kty === "EC" && key.crv === "P-256");
118
+ if (ecKeys.length === 0) return null;
119
+ const getKey = (0, jose.createLocalJWKSet)({ keys: ecKeys });
120
+ const { payload } = await (0, jose.jwtVerify)(token, getKey, {
121
+ algorithms: ["ES256"],
122
+ issuer: GATEWAY_CLIENT_IP_ISSUER,
123
+ audience: options.projectId,
124
+ typ: GATEWAY_CLIENT_IP_TYPE,
125
+ currentDate: /* @__PURE__ */ new Date(now * 1e3),
126
+ clockTolerance: CLOCK_SKEW_SECONDS
127
+ });
128
+ const parsed = GatewayClientIpClaimsSchema.safeParse(payload);
129
+ if (!parsed.success) return null;
130
+ const claims = parsed.data;
131
+ if (claims.iat > now + CLOCK_SKEW_SECONDS || claims.exp > claims.iat + 60 || claims.cid !== options.expectedCid || claims.host !== options.expectedHost) return null;
132
+ return claims;
133
+ } catch {
134
+ return null;
135
+ }
136
+ }
137
+
138
+ //#endregion
139
+ exports.GATEWAY_CLIENT_IP_ISSUER = GATEWAY_CLIENT_IP_ISSUER;
140
+ exports.GATEWAY_CLIENT_IP_TOKEN_HEADER = GATEWAY_CLIENT_IP_TOKEN_HEADER;
141
+ exports.GATEWAY_CLIENT_IP_TTL_SECONDS = GATEWAY_CLIENT_IP_TTL_SECONDS;
142
+ exports.GATEWAY_CLIENT_IP_TYPE = GATEWAY_CLIENT_IP_TYPE;
143
+ exports.GatewayClientIpClaimsSchema = GatewayClientIpClaimsSchema;
144
+ exports.GatewayClientIpPrivateJwkSchema = GatewayClientIpPrivateJwkSchema;
145
+ exports.GatewayClientIpPublicJwkSchema = GatewayClientIpPublicJwkSchema;
146
+ exports.importGatewayClientIpSigningKey = importGatewayClientIpSigningKey;
147
+ exports.isIpLiteral = isIpLiteral;
148
+ exports.signGatewayClientIp = signGatewayClientIp;
149
+ exports.verifyGatewayClientIp = verifyGatewayClientIp;
@@ -0,0 +1,139 @@
1
+ import { _ as number, h as literal, v as object, x as string } from "./schemas-DxY-dk9y.mjs";
2
+ import { r as parseIpv6 } from "./client-ip-HOfe6ucV.mjs";
3
+ import { SignJWT, createLocalJWKSet, importJWK, jwtVerify } from "jose";
4
+
5
+ //#region src/gateway-client-ip.ts
6
+ /**
7
+ * Signed client-identity token minted by the Checkpoint Cloudflare gateway
8
+ * worker and verified by an origin-side Checkpoint SDK (KYA-1121 follow-up).
9
+ *
10
+ * The gateway already forwards the connecting IP as the plain `KYA-Client-IP`
11
+ * / `X-Forwarded-For` headers (see `proxy.ts`), which every adapter behind a
12
+ * KNOWN, trusted peer (Cloudflare's own published edge ranges) can trust.
13
+ * Behind an additional untrusted hop - e.g. a PaaS's own reverse proxy
14
+ * (Railway, Render, Fly) sitting between Cloudflare and the origin - the
15
+ * origin's TCP peer is that PaaS's proxy, not Cloudflare, so the plain
16
+ * header can never be trusted there: any caller reaching the PaaS's edge
17
+ * directly could set it too. This ES256-signed JWS carries the SAME claim
18
+ * with a signature only the gateway's private key can produce, so an origin
19
+ * can trust it regardless of what sits between it and the gateway.
20
+ *
21
+ * One gateway-wide asymmetric key (not a per-project secret): the worker
22
+ * holds the private JWK (`GATEWAY_CLIENT_IP_SIGNING_JWK`), the platform
23
+ * publishes the public JWK at `/.well-known/jwks.json`
24
+ * (`GATEWAY_CLIENT_IP_PUBLIC_JWK`). Rotation is by `kid`.
25
+ */
26
+ const GATEWAY_CLIENT_IP_TOKEN_HEADER = "KYA-Client-IP-Token";
27
+ const GATEWAY_CLIENT_IP_ISSUER = "checkpoint:gateway-client-ip:v1";
28
+ const GATEWAY_CLIENT_IP_TYPE = "checkpoint-client-ip+jwt";
29
+ /**
30
+ * Token lifetime, seconds. A verifier MUST additionally bind `cid`/`host` to
31
+ * the request it's verifying (see {@link VerifyGatewayClientIpOptions}) -
32
+ * without that binding, a token captured on an untrusted hop within this
33
+ * window is replayable onto a DIFFERENT request the gateway never actually
34
+ * saw, and the `ip` it carries is not inert: it feeds the same IP-reputation
35
+ * and vendor-cross-match signals as any other resolved client IP, which do
36
+ * influence the engine's enforcement decision. Binding `cid` (unique per
37
+ * request) is what keeps a captured token scoped to the one request the
38
+ * gateway minted it for.
39
+ */
40
+ const GATEWAY_CLIENT_IP_TTL_SECONDS = 60;
41
+ /** Clock-skew allowance applied to `exp` (via jose's `clockTolerance`) and independently to `iat` below. */
42
+ const CLOCK_SKEW_SECONDS = 30;
43
+ function isIpv4Literal(value) {
44
+ const parts = value.split(".");
45
+ return parts.length === 4 && parts.every((part) => /^(0|[1-9]\d{0,2})$/.test(part) && Number(part) <= 255);
46
+ }
47
+ /** True when `value` is a literal IPv4 or IPv6 address - never resolves a hostname. */
48
+ function isIpLiteral(value) {
49
+ return isIpv4Literal(value) || parseIpv6(value) !== null;
50
+ }
51
+ const GatewayClientIpClaimsSchema = object({
52
+ iss: literal(GATEWAY_CLIENT_IP_ISSUER),
53
+ aud: string().min(1),
54
+ ip: string().refine(isIpLiteral, "ip must be a literal IPv4 or IPv6 address"),
55
+ cid: string().min(1),
56
+ host: string().min(1),
57
+ iat: number().int().nonnegative(),
58
+ exp: number().int().positive()
59
+ });
60
+ /** The gateway's own EC P-256 public key, as published in `/.well-known/jwks.json`. */
61
+ const GatewayClientIpPublicJwkSchema = object({
62
+ kty: literal("EC"),
63
+ crv: literal("P-256"),
64
+ alg: literal("ES256"),
65
+ use: literal("sig"),
66
+ kid: string().min(1),
67
+ x: string().min(1),
68
+ y: string().min(1)
69
+ });
70
+ /** The private half the gateway worker holds (`GATEWAY_CLIENT_IP_SIGNING_JWK`). */
71
+ const GatewayClientIpPrivateJwkSchema = GatewayClientIpPublicJwkSchema.extend({ d: string().min(1) });
72
+ /**
73
+ * Import a gateway client-ip JWK (private or public half) into a usable jose
74
+ * key. Callers on a hot path - the gateway worker signs on every proxied
75
+ * request - should import once per isolate and reuse the resulting key
76
+ * rather than calling this per request.
77
+ */
78
+ async function importGatewayClientIpSigningKey(jwk) {
79
+ return importJWK(jwk, "ES256");
80
+ }
81
+ /**
82
+ * Mint a compact JWS carrying the gateway's client-identity claim.
83
+ * `privateKey` must already be imported (see {@link importGatewayClientIpSigningKey}) -
84
+ * this function never imports a key itself, so a cached key can be reused
85
+ * across every signed request.
86
+ */
87
+ async function signGatewayClientIp(privateKey, kid, input, now = Math.floor(Date.now() / 1e3)) {
88
+ if (!kid || !input.aud || !input.cid || !input.host || !isIpLiteral(input.ip)) throw new Error("Invalid gateway client-ip signing input");
89
+ const claims = {
90
+ iss: GATEWAY_CLIENT_IP_ISSUER,
91
+ aud: input.aud,
92
+ ip: input.ip,
93
+ cid: input.cid,
94
+ host: input.host,
95
+ iat: now,
96
+ exp: now + 60
97
+ };
98
+ return new SignJWT(claims).setProtectedHeader({
99
+ alg: "ES256",
100
+ typ: GATEWAY_CLIENT_IP_TYPE,
101
+ kid
102
+ }).sign(privateKey);
103
+ }
104
+ /**
105
+ * Verify a gateway client-ip token against a JWKS document (as served by
106
+ * `/.well-known/jwks.json`) and return its claims, or `null` on ANY failure
107
+ * - malformed token, unknown `kid`, wrong `alg`, a tampered/expired/
108
+ * mismatched claim, or a `cid`/`host` that doesn't match the request being
109
+ * verified. Never throws: a missing or invalid token must change nothing
110
+ * about the caller's IP resolution.
111
+ */
112
+ async function verifyGatewayClientIp(token, jwks, options) {
113
+ if (!token || !options.projectId || !options.expectedCid || !options.expectedHost) return null;
114
+ const now = options.now ?? Math.floor(Date.now() / 1e3);
115
+ try {
116
+ const ecKeys = jwks.keys.filter((key) => key.kty === "EC" && key.crv === "P-256");
117
+ if (ecKeys.length === 0) return null;
118
+ const getKey = createLocalJWKSet({ keys: ecKeys });
119
+ const { payload } = await jwtVerify(token, getKey, {
120
+ algorithms: ["ES256"],
121
+ issuer: GATEWAY_CLIENT_IP_ISSUER,
122
+ audience: options.projectId,
123
+ typ: GATEWAY_CLIENT_IP_TYPE,
124
+ currentDate: /* @__PURE__ */ new Date(now * 1e3),
125
+ clockTolerance: CLOCK_SKEW_SECONDS
126
+ });
127
+ const parsed = GatewayClientIpClaimsSchema.safeParse(payload);
128
+ if (!parsed.success) return null;
129
+ const claims = parsed.data;
130
+ if (claims.iat > now + CLOCK_SKEW_SECONDS || claims.exp > claims.iat + 60 || claims.cid !== options.expectedCid || claims.host !== options.expectedHost) return null;
131
+ return claims;
132
+ } catch {
133
+ return null;
134
+ }
135
+ }
136
+
137
+ //#endregion
138
+ export { GATEWAY_CLIENT_IP_ISSUER, GATEWAY_CLIENT_IP_TOKEN_HEADER, GATEWAY_CLIENT_IP_TTL_SECONDS, GATEWAY_CLIENT_IP_TYPE, GatewayClientIpClaimsSchema, GatewayClientIpPrivateJwkSchema, GatewayClientIpPublicJwkSchema, importGatewayClientIpSigningKey, isIpLiteral, signGatewayClientIp, verifyGatewayClientIp };
139
+ //# sourceMappingURL=gateway-client-ip.mjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"gateway-client-ip.mjs","names":["z.object","z.literal","z.string","z.number"],"sources":["../src/gateway-client-ip.ts"],"sourcesContent":["import { SignJWT, createLocalJWKSet, importJWK, jwtVerify, type JWK, type KeyLike } from 'jose';\nimport { z } from 'zod';\nimport { parseIpv6 } from './utils/client-ip';\n\nexport type { JWK, KeyLike } from 'jose';\n\n/**\n * Signed client-identity token minted by the Checkpoint Cloudflare gateway\n * worker and verified by an origin-side Checkpoint SDK (KYA-1121 follow-up).\n *\n * The gateway already forwards the connecting IP as the plain `KYA-Client-IP`\n * / `X-Forwarded-For` headers (see `proxy.ts`), which every adapter behind a\n * KNOWN, trusted peer (Cloudflare's own published edge ranges) can trust.\n * Behind an additional untrusted hop - e.g. a PaaS's own reverse proxy\n * (Railway, Render, Fly) sitting between Cloudflare and the origin - the\n * origin's TCP peer is that PaaS's proxy, not Cloudflare, so the plain\n * header can never be trusted there: any caller reaching the PaaS's edge\n * directly could set it too. This ES256-signed JWS carries the SAME claim\n * with a signature only the gateway's private key can produce, so an origin\n * can trust it regardless of what sits between it and the gateway.\n *\n * One gateway-wide asymmetric key (not a per-project secret): the worker\n * holds the private JWK (`GATEWAY_CLIENT_IP_SIGNING_JWK`), the platform\n * publishes the public JWK at `/.well-known/jwks.json`\n * (`GATEWAY_CLIENT_IP_PUBLIC_JWK`). Rotation is by `kid`.\n */\n\nexport const GATEWAY_CLIENT_IP_TOKEN_HEADER = 'KYA-Client-IP-Token';\nexport const GATEWAY_CLIENT_IP_ISSUER = 'checkpoint:gateway-client-ip:v1';\nexport const GATEWAY_CLIENT_IP_TYPE = 'checkpoint-client-ip+jwt';\n/**\n * Token lifetime, seconds. A verifier MUST additionally bind `cid`/`host` to\n * the request it's verifying (see {@link VerifyGatewayClientIpOptions}) -\n * without that binding, a token captured on an untrusted hop within this\n * window is replayable onto a DIFFERENT request the gateway never actually\n * saw, and the `ip` it carries is not inert: it feeds the same IP-reputation\n * and vendor-cross-match signals as any other resolved client IP, which do\n * influence the engine's enforcement decision. Binding `cid` (unique per\n * request) is what keeps a captured token scoped to the one request the\n * gateway minted it for.\n */\nexport const GATEWAY_CLIENT_IP_TTL_SECONDS = 60;\n/** Clock-skew allowance applied to `exp` (via jose's `clockTolerance`) and independently to `iat` below. */\nconst CLOCK_SKEW_SECONDS = 30;\n\nfunction isIpv4Literal(value: string): boolean {\n const parts = value.split('.');\n return (\n parts.length === 4 &&\n parts.every((part) => /^(0|[1-9]\\d{0,2})$/.test(part) && Number(part) <= 255)\n );\n}\n\n/** True when `value` is a literal IPv4 or IPv6 address - never resolves a hostname. */\nexport function isIpLiteral(value: string): boolean {\n // parseIpv6 is exported by client-ip.ts specifically for reuse by callers\n // that need to validate/mask an address, not just resolve one - reused\n // here rather than a second hand-rolled IPv6 parser.\n return isIpv4Literal(value) || parseIpv6(value) !== null;\n}\n\nexport const GatewayClientIpClaimsSchema = z.object({\n iss: z.literal(GATEWAY_CLIENT_IP_ISSUER),\n aud: z.string().min(1),\n ip: z.string().refine(isIpLiteral, 'ip must be a literal IPv4 or IPv6 address'),\n cid: z.string().min(1),\n host: z.string().min(1),\n iat: z.number().int().nonnegative(),\n exp: z.number().int().positive(),\n});\nexport type GatewayClientIpClaims = z.infer<typeof GatewayClientIpClaimsSchema>;\n\nexport interface GatewayClientIpInput {\n aud: string;\n ip: string;\n cid: string;\n host: string;\n}\n\n/** The gateway's own EC P-256 public key, as published in `/.well-known/jwks.json`. */\nexport const GatewayClientIpPublicJwkSchema = z.object({\n kty: z.literal('EC'),\n crv: z.literal('P-256'),\n alg: z.literal('ES256'),\n use: z.literal('sig'),\n kid: z.string().min(1),\n x: z.string().min(1),\n y: z.string().min(1),\n});\nexport type GatewayClientIpPublicJwk = z.infer<typeof GatewayClientIpPublicJwkSchema>;\n\n/** The private half the gateway worker holds (`GATEWAY_CLIENT_IP_SIGNING_JWK`). */\nexport const GatewayClientIpPrivateJwkSchema = GatewayClientIpPublicJwkSchema.extend({\n d: z.string().min(1),\n});\nexport type GatewayClientIpPrivateJwk = z.infer<typeof GatewayClientIpPrivateJwkSchema>;\n\n/**\n * Import a gateway client-ip JWK (private or public half) into a usable jose\n * key. Callers on a hot path - the gateway worker signs on every proxied\n * request - should import once per isolate and reuse the resulting key\n * rather than calling this per request.\n */\nexport async function importGatewayClientIpSigningKey(jwk: JWK): Promise<KeyLike | Uint8Array> {\n return importJWK(jwk, 'ES256');\n}\n\n/**\n * Mint a compact JWS carrying the gateway's client-identity claim.\n * `privateKey` must already be imported (see {@link importGatewayClientIpSigningKey}) -\n * this function never imports a key itself, so a cached key can be reused\n * across every signed request.\n */\nexport async function signGatewayClientIp(\n privateKey: KeyLike | Uint8Array,\n kid: string,\n input: GatewayClientIpInput,\n now: number = Math.floor(Date.now() / 1000)\n): Promise<string> {\n if (!kid || !input.aud || !input.cid || !input.host || !isIpLiteral(input.ip)) {\n throw new Error('Invalid gateway client-ip signing input');\n }\n const claims: GatewayClientIpClaims = {\n iss: GATEWAY_CLIENT_IP_ISSUER,\n aud: input.aud,\n ip: input.ip,\n cid: input.cid,\n host: input.host,\n iat: now,\n exp: now + GATEWAY_CLIENT_IP_TTL_SECONDS,\n };\n return new SignJWT(claims)\n .setProtectedHeader({ alg: 'ES256', typ: GATEWAY_CLIENT_IP_TYPE, kid })\n .sign(privateKey);\n}\n\nexport interface VerifyGatewayClientIpOptions {\n /** The project this token must be scoped to (`routingEntry.projectId` on the gateway side). */\n projectId: string;\n /**\n * The CURRENT request's own correlation id (the same value the gateway\n * forwards as `x-kya-correlation-id`) - must equal the token's `cid` claim.\n * This is the binding that makes replay impossible: without it, a token\n * captured on an untrusted hop verifies against ANY request presenting it\n * within the TTL, not just the one the gateway minted it for.\n */\n expectedCid: string;\n /**\n * The CURRENT request's own public hostname - must equal the token's\n * `host` claim. On the Java SDK's `RemoteIpResolver.gateway(options)`,\n * this is the host component of the gateway's `KYA-Original-Origin`\n * header, NOT `X-Forwarded-Host`: a PaaS's own reverse proxy in front of\n * the origin (Railway, Render, Fly) commonly rewrites the latter from its\n * own Host-header-based routing, which would make this binding never\n * match on exactly the topology it defends (Cursor Bugbot, high) - see\n * `proxy.ts`, which sets `KYA-Original-Origin` unconditionally on every\n * proxied request to the same `hostname` this token's `host` claim signs.\n */\n expectedHost: string;\n now?: number;\n}\n\n/**\n * Verify a gateway client-ip token against a JWKS document (as served by\n * `/.well-known/jwks.json`) and return its claims, or `null` on ANY failure\n * - malformed token, unknown `kid`, wrong `alg`, a tampered/expired/\n * mismatched claim, or a `cid`/`host` that doesn't match the request being\n * verified. Never throws: a missing or invalid token must change nothing\n * about the caller's IP resolution.\n */\nexport async function verifyGatewayClientIp(\n token: string | undefined | null,\n jwks: { keys: JWK[] },\n options: VerifyGatewayClientIpOptions\n): Promise<GatewayClientIpClaims | null> {\n if (!token || !options.projectId || !options.expectedCid || !options.expectedHost) return null;\n const now = options.now ?? Math.floor(Date.now() / 1000);\n try {\n // Only EC/P-256 keys are ever candidates - the JWKS also carries the\n // unrelated OAuth Ed25519 (OKP) key, which must never be considered here.\n const ecKeys = jwks.keys.filter((key) => key.kty === 'EC' && key.crv === 'P-256');\n if (ecKeys.length === 0) return null;\n const getKey = createLocalJWKSet({ keys: ecKeys });\n const { payload } = await jwtVerify(token, getKey, {\n algorithms: ['ES256'],\n issuer: GATEWAY_CLIENT_IP_ISSUER,\n audience: options.projectId,\n typ: GATEWAY_CLIENT_IP_TYPE,\n currentDate: new Date(now * 1000),\n clockTolerance: CLOCK_SKEW_SECONDS,\n });\n const parsed = GatewayClientIpClaimsSchema.safeParse(payload);\n if (!parsed.success) return null;\n const claims = parsed.data;\n // Business-rule bounds jose has no concept of: the token's OWN declared\n // lifetime must never exceed the fixed TTL (even if a bug ever minted a\n // longer-lived but validly-signed token), iat must not be unreasonably\n // far in the future, and cid/host must bind this token to THIS request -\n // without that check a captured token replays onto any other request.\n if (\n claims.iat > now + CLOCK_SKEW_SECONDS ||\n claims.exp > claims.iat + GATEWAY_CLIENT_IP_TTL_SECONDS ||\n claims.cid !== options.expectedCid ||\n claims.host !== options.expectedHost\n ) {\n return null;\n }\n return claims;\n } catch {\n return null;\n }\n}\n"],"mappings":"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"}