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