@kya-os/checkpoint-shared 1.4.0 → 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 +32 -0
  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 +48 -44
  19. package/dist/browser-posture-report.d.mts.map +1 -0
  20. package/dist/browser-posture-report.d.ts +48 -44
  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 -75
  26. package/dist/browser-posture.d.mts.map +1 -0
  27. package/dist/browser-posture.d.ts +80 -75
  28. package/dist/browser-posture.d.ts.map +1 -0
  29. package/dist/browser-posture.js +159 -18993
  30. package/dist/browser-posture.mjs +158 -18990
  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 +339 -339
  57. package/dist/deploy/index.d.mts.map +1 -0
  58. package/dist/deploy/index.d.ts +339 -339
  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 +138 -132
  75. package/dist/gateway/index.d.mts.map +1 -0
  76. package/dist/gateway/index.d.ts +138 -132
  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 +14895 -14240
  89. package/dist/index.d.mts.map +1 -0
  90. package/dist/index.d.ts +14895 -14240
  91. package/dist/index.d.ts.map +1 -0
  92. package/dist/index.js +15180 -31025
  93. package/dist/index.mjs +15065 -30942
  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 +2323 -2318
  109. package/dist/mcpi/dashboard-config/index.d.mts.map +1 -0
  110. package/dist/mcpi/dashboard-config/index.d.ts +2323 -2318
  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 +343 -343
  147. package/dist/tool-protection/index.d.mts.map +1 -0
  148. package/dist/tool-protection/index.d.ts +343 -343
  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 +20 -6
@@ -1,338 +1,421 @@
1
- import { z } from 'zod';
1
+ import { z } from "zod";
2
2
 
3
- // src/tool-protection/index.ts
4
- var ENV_VAR_PATTERN = /^[A-Z][A-Z0-9_]*$/;
5
- var envVarNameSchema = z.string().regex(ENV_VAR_PATTERN, "Must be a valid env var name (e.g., X_API_KEY)").max(255);
6
- var AUTHORIZATION_TYPES = {
7
- /** @deprecated Use OAUTH2 instead. Will be removed in v2.0.0. */
8
- OAUTH: "oauth",
9
- /** OAuth 2.0 provider authentication (canonical) */
10
- OAUTH2: "oauth2",
11
- PASSWORD: "password",
12
- MDL: "mdl",
13
- IDV: "idv",
14
- VERIFIABLE_CREDENTIAL: "verifiable_credential",
15
- /** WebAuthn/Passkey authentication */
16
- WEBAUTHN: "webauthn",
17
- /** Sign-In with Ethereum (EIP-4361) */
18
- SIWE: "siwe",
19
- /** API Key from per-user vault */
20
- APIKEY: "apikey",
21
- NONE: "none"
3
+ //#region src/tool-protection/index.ts
4
+ /**
5
+ * KYA-OS Tool Protection Specification
6
+ *
7
+ * Core types for tool protection with delegation requirements.
8
+ *
9
+ * Consent Flow: type='none' → 2 screens, others → 3 screens (Auth→Consent→Success).
10
+ * DelegationCredential (VC) is created when user confirms on Consent Screen.
11
+ *
12
+ * Ported into checkpoint-shared from `@kya-os/contracts/tool-protection` as part
13
+ * of the E6 / C-series decommission (#2914 / #2917): checkpoint owns its product
14
+ * types now that the DIF `@kya-os/mcp` core is protocol-only. The single external
15
+ * dependency (`envVarNameSchema` from the contracts `vault` module) is inlined
16
+ * below so this module pulls nothing from `@kya-os/contracts`.
17
+ *
18
+ * @module @kya-os/checkpoint-shared/tool-protection
19
+ */
20
+ /**
21
+ * Validates an env var name used by the `apikey` authorization requirement.
22
+ * Inlined from the former `@kya-os/contracts/vault` `envVarNameSchema`.
23
+ */
24
+ const envVarNameSchema = z.string().regex(/^[A-Z][A-Z0-9_]*$/, "Must be a valid env var name (e.g., X_API_KEY)").max(255);
25
+ /** Canonical authorization type values for type safety */
26
+ const AUTHORIZATION_TYPES = {
27
+ /** @deprecated Use OAUTH2 instead. Will be removed in v2.0.0. */
28
+ OAUTH: "oauth",
29
+ /** OAuth 2.0 provider authentication (canonical) */
30
+ OAUTH2: "oauth2",
31
+ PASSWORD: "password",
32
+ MDL: "mdl",
33
+ IDV: "idv",
34
+ VERIFIABLE_CREDENTIAL: "verifiable_credential",
35
+ /** WebAuthn/Passkey authentication */
36
+ WEBAUTHN: "webauthn",
37
+ /** Sign-In with Ethereum (EIP-4361) */
38
+ SIWE: "siwe",
39
+ /** API Key from per-user vault */
40
+ APIKEY: "apikey",
41
+ NONE: "none"
22
42
  };
23
- var AuthRequiredErrorDataSchema = z.object({
24
- error: z.literal("auth_required"),
25
- type: z.enum(["apikey", "oauth", "credential"]),
26
- envVarNames: z.array(z.string()).optional(),
27
- configUrl: z.string(),
28
- message: z.string()
43
+ const AuthRequiredErrorDataSchema = z.object({
44
+ error: z.literal("auth_required"),
45
+ type: z.enum([
46
+ "apikey",
47
+ "oauth",
48
+ "credential"
49
+ ]),
50
+ envVarNames: z.array(z.string()).optional(),
51
+ configUrl: z.string(),
52
+ message: z.string()
29
53
  });
54
+ /**
55
+ * Error class thrown when required auth is missing and no fallback exists.
56
+ *
57
+ * Caught by the tool-call handler in agent.ts and serialized as a
58
+ * machine-readable MCP tool result so clients can present actionable UI.
59
+ */
30
60
  var AuthRequiredError = class extends Error {
31
- type;
32
- envVarNames;
33
- configUrl;
34
- constructor(opts) {
35
- const message = opts.message ?? (opts.type === "apikey" && opts.envVarNames?.length ? `API key required: configure ${opts.envVarNames.join(", ")} in your project settings.` : "Authentication required to use this tool.");
36
- super(message);
37
- this.name = "AuthRequiredError";
38
- this.type = opts.type;
39
- this.envVarNames = opts.envVarNames;
40
- this.configUrl = opts.configUrl;
41
- }
42
- /** Serialize to the wire format MCP clients expect */
43
- toJSON() {
44
- return {
45
- error: "auth_required",
46
- type: this.type,
47
- ...this.envVarNames && { envVarNames: this.envVarNames },
48
- configUrl: this.configUrl,
49
- message: this.message
50
- };
51
- }
61
+ type;
62
+ envVarNames;
63
+ configUrl;
64
+ constructor(opts) {
65
+ const message = opts.message ?? (opts.type === "apikey" && opts.envVarNames?.length ? `API key required: configure ${opts.envVarNames.join(", ")} in your project settings.` : "Authentication required to use this tool.");
66
+ super(message);
67
+ this.name = "AuthRequiredError";
68
+ this.type = opts.type;
69
+ this.envVarNames = opts.envVarNames;
70
+ this.configUrl = opts.configUrl;
71
+ }
72
+ /** Serialize to the wire format MCP clients expect */
73
+ toJSON() {
74
+ return {
75
+ error: "auth_required",
76
+ type: this.type,
77
+ ...this.envVarNames && { envVarNames: this.envVarNames },
78
+ configUrl: this.configUrl,
79
+ message: this.message
80
+ };
81
+ }
52
82
  };
53
- var AuthorizationRequirementSchema = z.discriminatedUnion("type", [
54
- // Deprecated: 'oauth' is an alias for 'oauth2'
55
- // Will be removed in v2.0.0. Use 'oauth2' instead.
56
- z.object({
57
- type: z.literal("oauth"),
58
- provider: z.string(),
59
- requiredScopes: z.array(z.string()).optional()
60
- }),
61
- // OAuth 2.0 provider authentication (canonical)
62
- z.object({
63
- type: z.literal("oauth2"),
64
- provider: z.string(),
65
- requiredScopes: z.array(z.string()).optional()
66
- }),
67
- z.object({
68
- type: z.literal("password"),
69
- provider: z.string()
70
- }),
71
- z.object({
72
- type: z.literal("mdl"),
73
- issuer: z.string(),
74
- credentialType: z.string().optional()
75
- }),
76
- z.object({
77
- type: z.literal("idv"),
78
- provider: z.string(),
79
- verificationLevel: z.enum(["basic", "enhanced", "loa3"]).optional()
80
- }),
81
- z.object({
82
- type: z.literal("verifiable_credential"),
83
- credentialType: z.string(),
84
- issuer: z.string().optional()
85
- }),
86
- // Deprecated: 'credential' is an alias for 'verifiable_credential'
87
- // Will be removed in v2.0.0. Use 'verifiable_credential' instead.
88
- z.object({
89
- type: z.literal("credential"),
90
- credentialType: z.string(),
91
- issuer: z.string().optional()
92
- }),
93
- // WebAuthn/Passkey authentication
94
- z.object({
95
- type: z.literal("webauthn"),
96
- rpId: z.string().optional(),
97
- userVerification: z.enum(["required", "preferred", "discouraged"]).optional()
98
- }),
99
- // Sign-In with Ethereum (EIP-4361)
100
- z.object({
101
- type: z.literal("siwe"),
102
- chainId: z.number().optional(),
103
- domain: z.string().optional()
104
- }),
105
- // API Key from per-user vault
106
- z.object({
107
- type: z.literal("apikey"),
108
- envVarNames: z.array(envVarNameSchema).min(1),
109
- headerMapping: z.record(z.string(), z.string())
110
- }),
111
- z.object({
112
- type: z.literal("none")
113
- })
83
+ /**
84
+ * Zod Schemas for Validation
85
+ */
86
+ const AuthorizationRequirementSchema = z.discriminatedUnion("type", [
87
+ z.object({
88
+ type: z.literal("oauth"),
89
+ provider: z.string(),
90
+ requiredScopes: z.array(z.string()).optional()
91
+ }),
92
+ z.object({
93
+ type: z.literal("oauth2"),
94
+ provider: z.string(),
95
+ requiredScopes: z.array(z.string()).optional()
96
+ }),
97
+ z.object({
98
+ type: z.literal("password"),
99
+ provider: z.string()
100
+ }),
101
+ z.object({
102
+ type: z.literal("mdl"),
103
+ issuer: z.string(),
104
+ credentialType: z.string().optional()
105
+ }),
106
+ z.object({
107
+ type: z.literal("idv"),
108
+ provider: z.string(),
109
+ verificationLevel: z.enum([
110
+ "basic",
111
+ "enhanced",
112
+ "loa3"
113
+ ]).optional()
114
+ }),
115
+ z.object({
116
+ type: z.literal("verifiable_credential"),
117
+ credentialType: z.string(),
118
+ issuer: z.string().optional()
119
+ }),
120
+ z.object({
121
+ type: z.literal("credential"),
122
+ credentialType: z.string(),
123
+ issuer: z.string().optional()
124
+ }),
125
+ z.object({
126
+ type: z.literal("webauthn"),
127
+ rpId: z.string().optional(),
128
+ userVerification: z.enum([
129
+ "required",
130
+ "preferred",
131
+ "discouraged"
132
+ ]).optional()
133
+ }),
134
+ z.object({
135
+ type: z.literal("siwe"),
136
+ chainId: z.number().optional(),
137
+ domain: z.string().optional()
138
+ }),
139
+ z.object({
140
+ type: z.literal("apikey"),
141
+ envVarNames: z.array(envVarNameSchema).min(1),
142
+ headerMapping: z.record(z.string(), z.string())
143
+ }),
144
+ z.object({ type: z.literal("none") })
114
145
  ]);
115
- var ToolProtectionSchema = z.object({
116
- requiresDelegation: z.boolean(),
117
- requiredScopes: z.array(z.string()),
118
- riskLevel: z.enum(["low", "medium", "high", "critical"]).optional(),
119
- oauthProvider: z.string().optional(),
120
- // Phase 2: Tool-specific OAuth provider
121
- authorization: AuthorizationRequirementSchema.optional()
146
+ const ToolProtectionSchema = z.object({
147
+ requiresDelegation: z.boolean(),
148
+ requiredScopes: z.array(z.string()),
149
+ riskLevel: z.enum([
150
+ "low",
151
+ "medium",
152
+ "high",
153
+ "critical"
154
+ ]).optional(),
155
+ oauthProvider: z.string().optional(),
156
+ authorization: AuthorizationRequirementSchema.optional()
122
157
  });
123
- var ToolProtectionMapSchema = z.record(z.string(), ToolProtectionSchema);
124
- var ToolProtectionResponseSchema = z.object({
125
- toolProtections: ToolProtectionMapSchema,
126
- metadata: z.object({
127
- lastUpdated: z.string().optional(),
128
- version: z.string().optional(),
129
- source: z.string().optional()
130
- }).optional()
158
+ const ToolProtectionMapSchema = z.record(z.string(), ToolProtectionSchema);
159
+ const ToolProtectionResponseSchema = z.object({
160
+ toolProtections: ToolProtectionMapSchema,
161
+ metadata: z.object({
162
+ lastUpdated: z.string().optional(),
163
+ version: z.string().optional(),
164
+ source: z.string().optional()
165
+ }).optional()
131
166
  });
132
- var DelegationRequiredErrorDataSchema = z.object({
133
- toolName: z.string(),
134
- requiredScopes: z.array(z.string()),
135
- consentUrl: z.string().optional(),
136
- authorizationUrl: z.string().optional(),
137
- reason: z.string().optional()
167
+ const DelegationRequiredErrorDataSchema = z.object({
168
+ toolName: z.string(),
169
+ requiredScopes: z.array(z.string()),
170
+ consentUrl: z.string().optional(),
171
+ authorizationUrl: z.string().optional(),
172
+ reason: z.string().optional()
138
173
  });
174
+ /**
175
+ * Type Guards
176
+ */
139
177
  function isToolProtection(obj) {
140
- return ToolProtectionSchema.safeParse(obj).success;
178
+ return ToolProtectionSchema.safeParse(obj).success;
141
179
  }
142
180
  function isToolProtectionMap(obj) {
143
- return ToolProtectionMapSchema.safeParse(obj).success;
181
+ return ToolProtectionMapSchema.safeParse(obj).success;
144
182
  }
145
183
  function isToolProtectionResponse(obj) {
146
- return ToolProtectionResponseSchema.safeParse(obj).success;
184
+ return ToolProtectionResponseSchema.safeParse(obj).success;
147
185
  }
148
186
  function isDelegationRequiredErrorData(obj) {
149
- return DelegationRequiredErrorDataSchema.safeParse(obj).success;
187
+ return DelegationRequiredErrorDataSchema.safeParse(obj).success;
150
188
  }
189
+ /**
190
+ * Type guard to check if an object is a valid AuthorizationRequirement
191
+ */
151
192
  function isAuthorizationRequirement(obj) {
152
- return AuthorizationRequirementSchema.safeParse(obj).success;
193
+ return AuthorizationRequirementSchema.safeParse(obj).success;
153
194
  }
195
+ /**
196
+ * Type guard to check if a ToolProtection has OAuth authorization
197
+ * Checks for both 'oauth' (deprecated) and 'oauth2' (canonical)
198
+ */
154
199
  function hasOAuthAuthorization(protection) {
155
- return protection.authorization?.type === "oauth" || protection.authorization?.type === "oauth2";
200
+ return protection.authorization?.type === "oauth" || protection.authorization?.type === "oauth2";
156
201
  }
202
+ /**
203
+ * Type guard to check if a ToolProtection has password authorization
204
+ */
157
205
  function hasPasswordAuthorization(protection) {
158
- return protection.authorization?.type === "password";
206
+ return protection.authorization?.type === "password";
159
207
  }
208
+ /**
209
+ * Type guard to check if a ToolProtection requires a Verifiable Credential
210
+ *
211
+ * Note: Also returns true for deprecated 'credential' type (normalized to verifiable_credential)
212
+ */
160
213
  function hasVerifiableCredentialAuthorization(protection) {
161
- return protection.authorization?.type === "verifiable_credential" || protection.authorization?.type === "credential";
214
+ return protection.authorization?.type === "verifiable_credential" || protection.authorization?.type === "credential";
162
215
  }
216
+ /**
217
+ * Type guard to check if a ToolProtection has API Key (vault) authorization
218
+ */
163
219
  function hasApiKeyAuthorization(protection) {
164
- return protection.authorization?.type === "apikey";
220
+ return protection.authorization?.type === "apikey";
165
221
  }
222
+ /**
223
+ * Validation Functions
224
+ */
166
225
  function validateToolProtection(obj) {
167
- return ToolProtectionSchema.parse(obj);
226
+ return ToolProtectionSchema.parse(obj);
168
227
  }
169
228
  function validateToolProtectionMap(obj) {
170
- return ToolProtectionMapSchema.parse(obj);
229
+ return ToolProtectionMapSchema.parse(obj);
171
230
  }
172
231
  function validateToolProtectionResponse(obj) {
173
- return ToolProtectionResponseSchema.parse(obj);
232
+ return ToolProtectionResponseSchema.parse(obj);
174
233
  }
175
234
  function validateDelegationRequiredErrorData(obj) {
176
- return DelegationRequiredErrorDataSchema.parse(obj);
235
+ return DelegationRequiredErrorDataSchema.parse(obj);
177
236
  }
237
+ /**
238
+ * Utility Functions
239
+ */
240
+ /**
241
+ * Check if a tool requires delegation
242
+ */
178
243
  function toolRequiresDelegation(toolName, protections) {
179
- const protection = protections[toolName];
180
- return protection?.requiresDelegation ?? false;
244
+ return protections[toolName]?.requiresDelegation ?? false;
181
245
  }
246
+ /**
247
+ * Get required scopes for a tool
248
+ */
182
249
  function getToolRequiredScopes(toolName, protections) {
183
- const protection = protections[toolName];
184
- return protection?.requiredScopes ?? [];
250
+ return protections[toolName]?.requiredScopes ?? [];
185
251
  }
252
+ /**
253
+ * Get risk level for a tool
254
+ */
186
255
  function getToolRiskLevel(toolName, protections) {
187
- return protections[toolName]?.riskLevel;
256
+ return protections[toolName]?.riskLevel;
188
257
  }
258
+ /**
259
+ * Create a delegation required error
260
+ */
189
261
  function createDelegationRequiredError(toolName, requiredScopes, consentUrl) {
190
- return {
191
- toolName,
192
- requiredScopes,
193
- consentUrl,
194
- authorizationUrl: consentUrl
195
- // Include both for compatibility
196
- };
262
+ return {
263
+ toolName,
264
+ requiredScopes,
265
+ consentUrl,
266
+ authorizationUrl: consentUrl
267
+ };
197
268
  }
269
+ /**
270
+ * Normalize tool protection configuration
271
+ * Migrates legacy oauthProvider field to authorization object
272
+ *
273
+ * - Migrates `oauthProvider` → `authorization: { type: 'oauth', provider: ... }`
274
+ * - Ensures `authorization` field is present when `requiresDelegation=true`
275
+ * - Returns fully normalized ToolProtection object
276
+ *
277
+ * @param raw - Raw tool protection data (may have legacy fields or be partial)
278
+ * @returns Normalized ToolProtection object
279
+ *
280
+ * // TODO: Remove normalizeToolProtection() when all tools migrated
281
+ */
198
282
  function normalizeToolProtection(raw) {
199
- const normalized = {
200
- requiresDelegation: raw.requiresDelegation ?? false,
201
- requiredScopes: raw.requiredScopes ?? [],
202
- ...raw.riskLevel && { riskLevel: raw.riskLevel },
203
- ...raw.oauthProvider && { oauthProvider: raw.oauthProvider }
204
- };
205
- if (raw.authorization) {
206
- normalized.authorization = raw.authorization;
207
- return normalized;
208
- }
209
- if (raw.oauthProvider) {
210
- normalized.authorization = {
211
- type: "oauth",
212
- provider: raw.oauthProvider
213
- };
214
- return normalized;
215
- }
216
- if (normalized.requiresDelegation && !normalized.authorization && !normalized.oauthProvider) {
217
- return normalized;
218
- }
219
- return normalized;
283
+ const normalized = {
284
+ requiresDelegation: raw.requiresDelegation ?? false,
285
+ requiredScopes: raw.requiredScopes ?? [],
286
+ ...raw.riskLevel && { riskLevel: raw.riskLevel },
287
+ ...raw.oauthProvider && { oauthProvider: raw.oauthProvider }
288
+ };
289
+ if (raw.authorization) {
290
+ normalized.authorization = raw.authorization;
291
+ return normalized;
292
+ }
293
+ if (raw.oauthProvider) {
294
+ normalized.authorization = {
295
+ type: "oauth",
296
+ provider: raw.oauthProvider
297
+ };
298
+ return normalized;
299
+ }
300
+ if (normalized.requiresDelegation && !normalized.authorization && !normalized.oauthProvider) return normalized;
301
+ return normalized;
220
302
  }
221
- var CONSENT_PROVIDER_TYPES = {
222
- /** Consent-only mode - no authentication, just clickwrap agreement */
223
- NONE: "none",
224
- /** OAuth2 provider authentication */
225
- OAUTH2: "oauth2",
226
- /** Password-based authentication (email/password, username/password) */
227
- PASSWORD: "password",
228
- /** @deprecated Use PASSWORD instead. Alias for backward compatibility */
229
- CREDENTIAL: "credential",
230
- /** Email magic link authentication */
231
- MAGIC_LINK: "magic_link",
232
- /** One-time password (SMS/email code) */
233
- OTP: "otp"
303
+ /** Consent provider types - stored in delegation metadata to track auth method used */
304
+ const CONSENT_PROVIDER_TYPES = {
305
+ /** Consent-only mode - no authentication, just clickwrap agreement */
306
+ NONE: "none",
307
+ /** OAuth2 provider authentication */
308
+ OAUTH2: "oauth2",
309
+ /** Password-based authentication (email/password, username/password) */
310
+ PASSWORD: "password",
311
+ /** @deprecated Use PASSWORD instead. Alias for backward compatibility */
312
+ CREDENTIAL: "credential",
313
+ /** Email magic link authentication */
314
+ MAGIC_LINK: "magic_link",
315
+ /** One-time password (SMS/email code) */
316
+ OTP: "otp"
234
317
  };
318
+ /**
319
+ * Determine consent provider type based on available identity information
320
+ *
321
+ * This is the single source of truth for consent provider type determination.
322
+ *
323
+ * @param hasOAuthIdentity - Whether OAuth identity is available
324
+ * @param isPasswordFlow - Whether this is a password/credential flow
325
+ * @param isMagicLinkFlow - Whether this is a magic link flow
326
+ * @param isOtpFlow - Whether this is an OTP flow
327
+ * @returns The consent provider type
328
+ */
235
329
  function determineConsentProviderType(hasOAuthIdentity, isPasswordFlow = false, isMagicLinkFlow = false, isOtpFlow = false) {
236
- if (isPasswordFlow) {
237
- return CONSENT_PROVIDER_TYPES.PASSWORD;
238
- }
239
- if (isMagicLinkFlow) {
240
- return CONSENT_PROVIDER_TYPES.MAGIC_LINK;
241
- }
242
- if (isOtpFlow) {
243
- return CONSENT_PROVIDER_TYPES.OTP;
244
- }
245
- if (hasOAuthIdentity) {
246
- return CONSENT_PROVIDER_TYPES.OAUTH2;
247
- }
248
- return CONSENT_PROVIDER_TYPES.NONE;
330
+ if (isPasswordFlow) return CONSENT_PROVIDER_TYPES.PASSWORD;
331
+ if (isMagicLinkFlow) return CONSENT_PROVIDER_TYPES.MAGIC_LINK;
332
+ if (isOtpFlow) return CONSENT_PROVIDER_TYPES.OTP;
333
+ if (hasOAuthIdentity) return CONSENT_PROVIDER_TYPES.OAUTH2;
334
+ return CONSENT_PROVIDER_TYPES.NONE;
249
335
  }
336
+ /**
337
+ * Get a human-readable label for an authorization requirement type
338
+ */
250
339
  function getAuthorizationTypeLabel(auth) {
251
- switch (auth.type) {
252
- case "oauth":
253
- case "oauth2":
254
- return auth.provider ? auth.provider.charAt(0).toUpperCase() + auth.provider.slice(1) : "OAuth Provider";
255
- case "password":
256
- return "Password Authentication";
257
- case "mdl":
258
- return "Mobile Driver's License";
259
- case "idv":
260
- return "Identity Verification";
261
- case "verifiable_credential":
262
- return auth.credentialType || "Verifiable Credential";
263
- case "credential":
264
- return auth.credentialType || "Verifiable Credential";
265
- case "webauthn":
266
- return "Passkey / WebAuthn";
267
- case "siwe":
268
- return "Sign-In with Ethereum";
269
- case "apikey":
270
- return "API Key (Vault)";
271
- case "none":
272
- return "Consent Only";
273
- default: {
274
- return "Unknown";
275
- }
276
- }
340
+ switch (auth.type) {
341
+ case "oauth":
342
+ case "oauth2": return auth.provider ? auth.provider.charAt(0).toUpperCase() + auth.provider.slice(1) : "OAuth Provider";
343
+ case "password": return "Password Authentication";
344
+ case "mdl": return "Mobile Driver's License";
345
+ case "idv": return "Identity Verification";
346
+ case "verifiable_credential": return auth.credentialType || "Verifiable Credential";
347
+ case "credential": return auth.credentialType || "Verifiable Credential";
348
+ case "webauthn": return "Passkey / WebAuthn";
349
+ case "siwe": return "Sign-In with Ethereum";
350
+ case "apikey": return "API Key (Vault)";
351
+ case "none": return "Consent Only";
352
+ default: return "Unknown";
353
+ }
277
354
  }
355
+ /**
356
+ * Get a unique key for an authorization requirement (for React keys, caching, etc.)
357
+ */
278
358
  function getAuthorizationTypeKey(auth) {
279
- switch (auth.type) {
280
- case "oauth":
281
- return auth.provider ? `oauth:${auth.provider}` : "oauth";
282
- case "oauth2":
283
- return auth.provider ? `oauth2:${auth.provider}` : "oauth2";
284
- case "password":
285
- return auth.provider ? `password:${auth.provider}` : "password";
286
- case "mdl":
287
- return `mdl:${auth.issuer || "unknown"}:${auth.credentialType || ""}`;
288
- case "idv":
289
- return `idv:${auth.provider || "unknown"}:${auth.verificationLevel || ""}`;
290
- case "verifiable_credential":
291
- return `vc:${auth.issuer || "any"}:${auth.credentialType || "unknown"}`;
292
- case "credential":
293
- return `vc:${auth.issuer || "any"}:${auth.credentialType || "unknown"}`;
294
- case "webauthn":
295
- return `webauthn:${auth.rpId || "default"}`;
296
- case "siwe":
297
- return `siwe:${auth.chainId || 1}:${auth.domain || "any"}`;
298
- case "apikey":
299
- return `apikey:${[...auth.envVarNames].sort().join(",")}`;
300
- case "none":
301
- return "none";
302
- default: {
303
- return "unknown";
304
- }
305
- }
359
+ switch (auth.type) {
360
+ case "oauth": return auth.provider ? `oauth:${auth.provider}` : "oauth";
361
+ case "oauth2": return auth.provider ? `oauth2:${auth.provider}` : "oauth2";
362
+ case "password": return auth.provider ? `password:${auth.provider}` : "password";
363
+ case "mdl": return `mdl:${auth.issuer || "unknown"}:${auth.credentialType || ""}`;
364
+ case "idv": return `idv:${auth.provider || "unknown"}:${auth.verificationLevel || ""}`;
365
+ case "verifiable_credential": return `vc:${auth.issuer || "any"}:${auth.credentialType || "unknown"}`;
366
+ case "credential": return `vc:${auth.issuer || "any"}:${auth.credentialType || "unknown"}`;
367
+ case "webauthn": return `webauthn:${auth.rpId || "default"}`;
368
+ case "siwe": return `siwe:${auth.chainId || 1}:${auth.domain || "any"}`;
369
+ case "apikey": return `apikey:${[...auth.envVarNames].sort().join(",")}`;
370
+ case "none": return "none";
371
+ default: return "unknown";
372
+ }
306
373
  }
374
+ /**
375
+ * Normalize authorization requirement type
376
+ *
377
+ * Normalizes deprecated types to their canonical equivalents:
378
+ * - 'oauth' → 'oauth2'
379
+ * - 'credential' → 'verifiable_credential'
380
+ *
381
+ * This function should be called at runtime boundaries when processing
382
+ * authorization requirements.
383
+ *
384
+ * @param auth - Authorization requirement (may contain deprecated types)
385
+ * @param options - Normalization options
386
+ * @returns Normalized authorization requirement
387
+ *
388
+ * @example
389
+ * ```typescript
390
+ * const normalized = normalizeAuthorizationType(
391
+ * { type: 'oauth', provider: 'github' },
392
+ * { warn: true }
393
+ * );
394
+ * // Returns: { type: 'oauth2', provider: 'github' }
395
+ * // Logs: DEPRECATION warning
396
+ * ```
397
+ */
307
398
  function normalizeAuthorizationType(auth, options = {}) {
308
- const { warn = true, logger = console.warn } = options;
309
- if (auth.type === "oauth") {
310
- if (warn) {
311
- logger(
312
- `DEPRECATION: Authorization type 'oauth' is deprecated and will be removed in v2.0.0. Please update to 'oauth2'. See https://github.com/modelcontextprotocol-identity/xmcp-i/blob/main/docs/migrations/oauth-to-oauth2.md`
313
- );
314
- }
315
- const normalized = {
316
- type: "oauth2",
317
- provider: auth.provider,
318
- ...auth.requiredScopes !== void 0 && { requiredScopes: auth.requiredScopes }
319
- };
320
- return normalized;
321
- }
322
- if (auth.type === "credential") {
323
- if (warn) {
324
- logger(
325
- `DEPRECATION: Authorization type 'credential' is deprecated and will be removed in v2.0.0. Please update to 'verifiable_credential'. See https://github.com/modelcontextprotocol-identity/xmcp-i/blob/main/docs/migrations/credential-to-verifiable_credential.md`
326
- );
327
- }
328
- const normalized = {
329
- type: "verifiable_credential",
330
- credentialType: auth.credentialType,
331
- ...auth.issuer !== void 0 && { issuer: auth.issuer }
332
- };
333
- return normalized;
334
- }
335
- return auth;
399
+ const { warn = true, logger = console.warn } = options;
400
+ if (auth.type === "oauth") {
401
+ if (warn) logger("DEPRECATION: Authorization type 'oauth' is deprecated and will be removed in v2.0.0. Please update to 'oauth2'. See https://github.com/modelcontextprotocol-identity/xmcp-i/blob/main/docs/migrations/oauth-to-oauth2.md");
402
+ return {
403
+ type: "oauth2",
404
+ provider: auth.provider,
405
+ ...auth.requiredScopes !== void 0 && { requiredScopes: auth.requiredScopes }
406
+ };
407
+ }
408
+ if (auth.type === "credential") {
409
+ if (warn) logger("DEPRECATION: Authorization type 'credential' is deprecated and will be removed in v2.0.0. Please update to 'verifiable_credential'. See https://github.com/modelcontextprotocol-identity/xmcp-i/blob/main/docs/migrations/credential-to-verifiable_credential.md");
410
+ return {
411
+ type: "verifiable_credential",
412
+ credentialType: auth.credentialType,
413
+ ...auth.issuer !== void 0 && { issuer: auth.issuer }
414
+ };
415
+ }
416
+ return auth;
336
417
  }
337
418
 
419
+ //#endregion
338
420
  export { AUTHORIZATION_TYPES, AuthRequiredError, AuthRequiredErrorDataSchema, AuthorizationRequirementSchema, CONSENT_PROVIDER_TYPES, DelegationRequiredErrorDataSchema, ToolProtectionMapSchema, ToolProtectionResponseSchema, ToolProtectionSchema, createDelegationRequiredError, determineConsentProviderType, getAuthorizationTypeKey, getAuthorizationTypeLabel, getToolRequiredScopes, getToolRiskLevel, hasApiKeyAuthorization, hasOAuthAuthorization, hasPasswordAuthorization, hasVerifiableCredentialAuthorization, isAuthorizationRequirement, isDelegationRequiredErrorData, isToolProtection, isToolProtectionMap, isToolProtectionResponse, normalizeAuthorizationType, normalizeToolProtection, toolRequiresDelegation, validateDelegationRequiredErrorData, validateToolProtection, validateToolProtectionMap, validateToolProtectionResponse };
421
+ //# sourceMappingURL=index.mjs.map