@kya-os/checkpoint-shared 1.9.0 → 1.11.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 (207) hide show
  1. package/CHANGELOG.md +113 -0
  2. package/README.md +1 -1
  3. package/dist/base64url-BbVG8f-v.js +65 -0
  4. package/dist/base64url-D2MvsR20.mjs +49 -0
  5. package/dist/base64url-D2MvsR20.mjs.map +1 -0
  6. package/dist/beacon-forward-secret/index.d.mts +4 -0
  7. package/dist/beacon-forward-secret/index.d.mts.map +1 -0
  8. package/dist/beacon-forward-secret/index.d.ts +4 -0
  9. package/dist/beacon-forward-secret/index.d.ts.map +1 -0
  10. package/dist/beacon-forward-secret/index.js +15 -0
  11. package/dist/beacon-forward-secret/index.mjs +15 -0
  12. package/dist/beacon-forward-secret/index.mjs.map +1 -0
  13. package/dist/beacon-types/index.d.mts +53 -1
  14. package/dist/beacon-types/index.d.mts.map +1 -1
  15. package/dist/beacon-types/index.d.ts +53 -1
  16. package/dist/beacon-types/index.d.ts.map +1 -1
  17. package/dist/beacon-types/index.js +86 -1
  18. package/dist/beacon-types/index.mjs +77 -2
  19. package/dist/beacon-types/index.mjs.map +1 -1
  20. package/dist/{browser-posture-5fPrsxx7.d.mts → browser-posture-WPk0kl9u.d.mts} +18 -1
  21. package/dist/browser-posture-WPk0kl9u.d.mts.map +1 -0
  22. package/dist/{browser-posture-CCR1kh5e.d.ts → browser-posture-_y6BcdXw.d.ts} +18 -1
  23. package/dist/browser-posture-_y6BcdXw.d.ts.map +1 -0
  24. package/dist/browser-posture-cookie.mjs.map +1 -1
  25. package/dist/browser-posture-proof-verifier.js +136 -5
  26. package/dist/browser-posture-proof-verifier.mjs +134 -2
  27. package/dist/browser-posture-proof-verifier.mjs.map +1 -0
  28. package/dist/browser-posture-proof.d.mts +1 -1
  29. package/dist/browser-posture-proof.d.ts +1 -1
  30. package/dist/browser-posture-proof.js +1 -1
  31. package/dist/browser-posture-proof.mjs +1 -1
  32. package/dist/browser-posture-report.d.mts +17 -0
  33. package/dist/browser-posture-report.d.mts.map +1 -1
  34. package/dist/browser-posture-report.d.ts +17 -0
  35. package/dist/browser-posture-report.d.ts.map +1 -1
  36. package/dist/browser-posture.d.mts +1 -1
  37. package/dist/browser-posture.d.ts +1 -1
  38. package/dist/browser-posture.js +53 -5
  39. package/dist/browser-posture.mjs +53 -5
  40. package/dist/browser-posture.mjs.map +1 -1
  41. package/dist/browser.d.mts +10 -0
  42. package/dist/browser.d.mts.map +1 -1
  43. package/dist/browser.d.ts +10 -0
  44. package/dist/browser.d.ts.map +1 -1
  45. package/dist/browser.js +1 -1
  46. package/dist/browser.mjs +1 -1
  47. package/dist/browser.mjs.map +1 -1
  48. package/dist/canonical-signer/index.d.mts.map +1 -1
  49. package/dist/canonical-signer/index.d.ts.map +1 -1
  50. package/dist/canonical-signer/index.js +0 -4
  51. package/dist/canonical-signer/index.mjs +0 -4
  52. package/dist/canonical-signer/index.mjs.map +1 -1
  53. package/dist/{client-ip-B7w-uHfS.d.ts → client-ip-8KneiMK0.d.mts} +12 -2
  54. package/dist/{client-ip-B7w-uHfS.d.mts.map → client-ip-8KneiMK0.d.mts.map} +1 -1
  55. package/dist/{client-ip-B7w-uHfS.d.mts → client-ip-8KneiMK0.d.ts} +12 -2
  56. package/dist/{client-ip-B7w-uHfS.d.ts.map → client-ip-8KneiMK0.d.ts.map} +1 -1
  57. package/dist/{client-ip-B8wFzJ5f.js → client-ip-BEmLC4I4.js} +71 -0
  58. package/dist/{client-ip-DIJyr6px.mjs → client-ip-DlHx7GGh.mjs} +61 -2
  59. package/dist/client-ip-DlHx7GGh.mjs.map +1 -0
  60. package/dist/client-ip.d.mts +2 -2
  61. package/dist/client-ip.d.ts +2 -2
  62. package/dist/client-ip.js +3 -1
  63. package/dist/client-ip.mjs +2 -2
  64. package/dist/deploy/index.d.mts +1 -0
  65. package/dist/deploy/index.d.mts.map +1 -1
  66. package/dist/deploy/index.d.ts +1 -0
  67. package/dist/deploy/index.d.ts.map +1 -1
  68. package/dist/deploy/index.js +14 -2
  69. package/dist/deploy/index.mjs +14 -2
  70. package/dist/deploy/index.mjs.map +1 -1
  71. package/dist/{detection-reason-mapping-CQexNvR7.d.ts → detection-reason-mapping-BemDaDED.d.mts} +5 -2
  72. package/dist/detection-reason-mapping-BemDaDED.d.mts.map +1 -0
  73. package/dist/{detection-reason-mapping-CQexNvR7.d.mts → detection-reason-mapping-BemDaDED.d.ts} +5 -2
  74. package/dist/detection-reason-mapping-BemDaDED.d.ts.map +1 -0
  75. package/dist/{detection-reason-mapping-B9RSkOs8.js → detection-reason-mapping-BxYaQ8kb.js} +33 -8
  76. package/dist/{detection-reason-mapping-BGymWIPl.mjs → detection-reason-mapping-j-7bXsVb.mjs} +29 -10
  77. package/dist/detection-reason-mapping-j-7bXsVb.mjs.map +1 -0
  78. package/dist/errors/index.d.mts +4 -0
  79. package/dist/errors/index.d.mts.map +1 -1
  80. package/dist/errors/index.d.ts +4 -0
  81. package/dist/errors/index.d.ts.map +1 -1
  82. package/dist/errors/index.js +24 -8
  83. package/dist/errors/index.mjs +24 -8
  84. package/dist/errors/index.mjs.map +1 -1
  85. package/dist/{fetcher-D2vjr7jB.d.mts → fetcher-CTKz07jg.d.mts} +13 -3
  86. package/dist/fetcher-CTKz07jg.d.mts.map +1 -0
  87. package/dist/{fetcher-C8qvwdnA.d.ts → fetcher-DCr920hx.d.ts} +13 -3
  88. package/dist/fetcher-DCr920hx.d.ts.map +1 -0
  89. package/dist/gateway-client-ip.js +1 -1
  90. package/dist/gateway-client-ip.mjs +1 -1
  91. package/dist/host-adapter/index.d.mts +1 -1
  92. package/dist/host-adapter/index.d.ts +1 -1
  93. package/dist/identity-cookie/index.d.mts +14 -0
  94. package/dist/identity-cookie/index.d.mts.map +1 -0
  95. package/dist/identity-cookie/index.d.ts +14 -0
  96. package/dist/identity-cookie/index.d.ts.map +1 -0
  97. package/dist/identity-cookie/index.js +45 -0
  98. package/dist/identity-cookie/index.mjs +43 -0
  99. package/dist/identity-cookie/index.mjs.map +1 -0
  100. package/dist/{index-DnFsmr_o.d.ts → index-Cdv_FH0H.d.ts} +2 -2
  101. package/dist/{index-DnFsmr_o.d.ts.map → index-Cdv_FH0H.d.ts.map} +1 -1
  102. package/dist/{index-rvw5Bz-r.d.mts → index-DL_dmQBY.d.mts} +2 -2
  103. package/dist/{index-rvw5Bz-r.d.mts.map → index-DL_dmQBY.d.mts.map} +1 -1
  104. package/dist/index.d.mts +641 -169
  105. package/dist/index.d.mts.map +1 -1
  106. package/dist/index.d.ts +641 -169
  107. package/dist/index.d.ts.map +1 -1
  108. package/dist/index.js +819 -210
  109. package/dist/index.mjs +765 -200
  110. package/dist/index.mjs.map +1 -1
  111. package/dist/kya-http.d.mts +2 -2
  112. package/dist/kya-http.d.ts +2 -2
  113. package/dist/kya-http.js +7 -2
  114. package/dist/kya-http.mjs +2 -2
  115. package/dist/mcpi/dashboard-config/index.mjs.map +1 -1
  116. package/dist/patterns-CdTh7LU2.d.mts +35 -0
  117. package/dist/patterns-CdTh7LU2.d.mts.map +1 -0
  118. package/dist/patterns-CdTh7LU2.d.ts +35 -0
  119. package/dist/patterns-CdTh7LU2.d.ts.map +1 -0
  120. package/dist/{patterns-CiMpbdAF.js → patterns-CnNxRnaK.js} +3 -130
  121. package/dist/{patterns-D4OAsNQY.mjs → patterns-CpRk9R3M.mjs} +5 -96
  122. package/dist/patterns-CpRk9R3M.mjs.map +1 -0
  123. package/dist/patterns.d.mts +2 -2
  124. package/dist/patterns.d.ts +2 -2
  125. package/dist/patterns.js +1 -7
  126. package/dist/patterns.mjs +2 -2
  127. package/dist/policy/fetcher.d.mts +2 -2
  128. package/dist/policy/fetcher.d.ts +2 -2
  129. package/dist/policy/fetcher.js +100 -8
  130. package/dist/policy/fetcher.mjs +99 -9
  131. package/dist/policy/fetcher.mjs.map +1 -1
  132. package/dist/policy/schemas.d.mts +1 -1
  133. package/dist/policy/schemas.d.ts +1 -1
  134. package/dist/proxy-assertion-mapping-BVwXVSMZ.mjs +81 -0
  135. package/dist/proxy-assertion-mapping-BVwXVSMZ.mjs.map +1 -0
  136. package/dist/proxy-assertion-mapping-BxhENrcY.d.mts +70 -0
  137. package/dist/proxy-assertion-mapping-BxhENrcY.d.mts.map +1 -0
  138. package/dist/proxy-assertion-mapping-D64AyZfG.js +85 -0
  139. package/dist/proxy-assertion-mapping-DhAynFqG.d.ts +70 -0
  140. package/dist/proxy-assertion-mapping-DhAynFqG.d.ts.map +1 -0
  141. package/dist/proxy-assertions.d.mts +2 -0
  142. package/dist/proxy-assertions.d.ts +2 -0
  143. package/dist/proxy-assertions.js +4 -0
  144. package/dist/proxy-assertions.mjs +3 -0
  145. package/dist/reason-codes.d.mts +2 -2
  146. package/dist/reason-codes.d.ts +2 -2
  147. package/dist/reason-codes.js +3 -2
  148. package/dist/reason-codes.mjs +2 -2
  149. package/dist/{registered-sid-D6KCaT1E.d.ts → registered-sid-BgDhdj2l.d.mts} +24 -2
  150. package/dist/registered-sid-BgDhdj2l.d.mts.map +1 -0
  151. package/dist/{registered-sid-D6KCaT1E.d.mts → registered-sid-BgDhdj2l.d.ts} +24 -2
  152. package/dist/registered-sid-BgDhdj2l.d.ts.map +1 -0
  153. package/dist/{registered-sid-DVGTSH0L.js → registered-sid-DG1tSSvl.js} +162 -4
  154. package/dist/{registered-sid-26hNxp6t.mjs → registered-sid-D__xiDPu.mjs} +134 -6
  155. package/dist/registered-sid-D__xiDPu.mjs.map +1 -0
  156. package/dist/{schemas-m-GqyfyO.d.mts → schemas-BhC88D1-.d.mts} +5 -5
  157. package/dist/{schemas-m-GqyfyO.d.mts.map → schemas-BhC88D1-.d.mts.map} +1 -1
  158. package/dist/{schemas-CGKHzcMV.d.ts → schemas-DZa1ouGs.d.ts} +5 -5
  159. package/dist/{schemas-CGKHzcMV.d.ts.map → schemas-DZa1ouGs.d.ts.map} +1 -1
  160. package/dist/signals/index.d.mts.map +1 -1
  161. package/dist/signals/index.d.ts.map +1 -1
  162. package/dist/signals/index.js +4 -0
  163. package/dist/signals/index.mjs +4 -0
  164. package/dist/signals/index.mjs.map +1 -1
  165. package/dist/timezone-country-B6PkDyNP.d.mts +15 -0
  166. package/dist/timezone-country-B6PkDyNP.d.mts.map +1 -0
  167. package/dist/timezone-country-B6PkDyNP.d.ts +15 -0
  168. package/dist/timezone-country-B6PkDyNP.d.ts.map +1 -0
  169. package/dist/timezone-country-CROxU2Tl.js +505 -0
  170. package/dist/timezone-country-CrrnkOdy.mjs +489 -0
  171. package/dist/timezone-country-CrrnkOdy.mjs.map +1 -0
  172. package/dist/timezone-country.d.mts +2 -0
  173. package/dist/timezone-country.d.ts +2 -0
  174. package/dist/timezone-country.js +6 -0
  175. package/dist/timezone-country.mjs +3 -0
  176. package/dist/tool-protection/index.mjs.map +1 -1
  177. package/fixtures/detection/cloudflare-alias-parity.json +383 -0
  178. package/fixtures/detection/reason-codes.json +3 -1
  179. package/fixtures/detection/signal-exposure-example.json +1 -1
  180. package/fixtures/iana-tzdata/backward +375 -0
  181. package/fixtures/iana-tzdata/renamed-zones.json +21 -0
  182. package/fixtures/iana-tzdata/version +1 -0
  183. package/fixtures/iana-tzdata/zone.tab +448 -0
  184. package/fixtures/workbench/management-session.v1.json +20 -0
  185. package/fixtures/workbench/model-credentials.v1.json +8 -0
  186. package/fixtures/workbench/task-grant.v1.json +37 -0
  187. package/package.json +25 -3
  188. package/src/data/compiled/merged-rules.json +9 -7
  189. package/dist/browser-posture-5fPrsxx7.d.mts.map +0 -1
  190. package/dist/browser-posture-CCR1kh5e.d.ts.map +0 -1
  191. package/dist/browser-posture-proof-verifier-DvsOmFrM.js +0 -202
  192. package/dist/browser-posture-proof-verifier-I0HP2Ics.mjs +0 -180
  193. package/dist/browser-posture-proof-verifier-I0HP2Ics.mjs.map +0 -1
  194. package/dist/client-ip-DIJyr6px.mjs.map +0 -1
  195. package/dist/detection-reason-mapping-BGymWIPl.mjs.map +0 -1
  196. package/dist/detection-reason-mapping-CQexNvR7.d.mts.map +0 -1
  197. package/dist/detection-reason-mapping-CQexNvR7.d.ts.map +0 -1
  198. package/dist/fetcher-C8qvwdnA.d.ts.map +0 -1
  199. package/dist/fetcher-D2vjr7jB.d.mts.map +0 -1
  200. package/dist/patterns-Bp40cwh2.d.mts +0 -110
  201. package/dist/patterns-Bp40cwh2.d.mts.map +0 -1
  202. package/dist/patterns-Bp40cwh2.d.ts +0 -110
  203. package/dist/patterns-Bp40cwh2.d.ts.map +0 -1
  204. package/dist/patterns-D4OAsNQY.mjs.map +0 -1
  205. package/dist/registered-sid-26hNxp6t.mjs.map +0 -1
  206. package/dist/registered-sid-D6KCaT1E.d.mts.map +0 -1
  207. package/dist/registered-sid-D6KCaT1E.d.ts.map +0 -1
@@ -1 +1 @@
1
- {"version":3,"file":"index.mjs","names":[],"sources":["../../src/tool-protection/default-required-scopes.ts","../../src/tool-protection/index.ts"],"sourcesContent":["/**\n * The scopes a tool entry is served with when it has none of its own.\n *\n * The edge and the runtime let a credential through a protected tool when it\n * carries every scope in the tool's served `requiredScopes`, so a protected\n * tool served with `[]` opens to ANY valid credential for the resource. Every\n * writer of `bouncer_configs.discovered_tools` stores a scope through this one\n * rule, so a tool never reaches the served map with an empty list.\n *\n * @module @kya-os/checkpoint-shared/tool-protection\n */\n\n/** The fields of a stored tool entry this rule reads. Stored rows are untyped JSON. */\nexport interface ToolScopeSources {\n /** The entry's own served scopes. */\n requiredScopes?: unknown;\n /** The legacy key proof discovery wrote: the scope the runtime reported (`scopeId`). */\n scopes?: unknown;\n /** The security schemes a server declared for the tool; oauth2 entries carry `scopes`. */\n securitySchemes?: unknown;\n /** The capability the tool gates on, from server registration. */\n capability?: unknown;\n}\n\n/** The longest scope a consent request carries. */\nexport const MAX_DEFAULT_SCOPE_LENGTH = 200;\n\nconst EXECUTE_SUFFIX = ':execute';\n\n/** Outside the RFC 6749 scope-token alphabet: printable ASCII except space, `\"` and `\\`. */\nconst NON_SCOPE_TOKEN_CHARS = /[^\\x21\\x23-\\x5B\\x5D-\\x7E]/gu;\n\nfunction scopeList(value: unknown): string[] | undefined {\n return Array.isArray(value) && value.length > 0 && value.every((item) => typeof item === 'string')\n ? value\n : undefined;\n}\n\nfunction declaredOauthScopes(schemes: unknown): string[] {\n if (!Array.isArray(schemes)) return [];\n const scopes = schemes.flatMap((scheme: unknown) =>\n typeof scheme === 'object' &&\n scheme !== null &&\n (scheme as { type?: unknown }).type === 'oauth2' &&\n Array.isArray((scheme as { scopes?: unknown }).scopes)\n ? ((scheme as { scopes: unknown[] }).scopes.filter(\n (scope) => typeof scope === 'string' && scope.length > 0\n ) as string[])\n : []\n );\n return [...new Set(scopes)];\n}\n\n/**\n * `<name>:execute`, with the name reduced to the scope-token alphabet (the edge\n * drops other characters) and the whole scope at most\n * {@link MAX_DEFAULT_SCOPE_LENGTH} characters.\n */\nexport function executeScopeFor(toolName: string): string {\n const name = toolName\n .replace(NON_SCOPE_TOKEN_CHARS, '_')\n .slice(0, MAX_DEFAULT_SCOPE_LENGTH - EXECUTE_SUFFIX.length);\n return `${name}${EXECUTE_SUFFIX}`;\n}\n\n/**\n * The scopes to store for `toolName`: the first non-empty of\n *\n * 1. the entry's own `requiredScopes`, as stored;\n * 2. its legacy `scopes`, so a grant for the scope the runtime reported keeps matching;\n * 3. the oauth2 scopes its `securitySchemes` declare;\n * 4. its `capability`;\n * 5. {@link executeScopeFor}`(toolName)`.\n *\n * Never empty. An absent entry gets the last.\n */\nexport function defaultRequiredScopes(\n toolName: string,\n entry: ToolScopeSources | null | undefined\n): string[] {\n const own = scopeList(entry?.requiredScopes) ?? scopeList(entry?.scopes);\n if (own) return [...own];\n const declared = declaredOauthScopes(entry?.securitySchemes);\n if (declared.length > 0) return declared;\n if (typeof entry?.capability === 'string' && entry.capability.length > 0) {\n return [entry.capability];\n }\n return [executeScopeFor(toolName)];\n}\n","/**\n * KYA-OS Tool Protection Specification\n *\n * Core types for tool protection with delegation requirements.\n *\n * Consent Flow: type='none' → 2 screens, others → 3 screens (Auth→Consent→Success).\n * DelegationCredential (VC) is created when user confirms on Consent Screen.\n *\n * Ported into checkpoint-shared from `@kya-os/contracts/tool-protection` as part\n * of the E6 / C-series decommission (#2914 / #2917): checkpoint owns its product\n * types now that the DIF `@kya-os/mcp` core is protocol-only. The single external\n * dependency (`envVarNameSchema` from the contracts `vault` module) is inlined\n * below so this module pulls nothing from `@kya-os/contracts`.\n *\n * @module @kya-os/checkpoint-shared/tool-protection\n */\n\nimport { z } from 'zod';\n\nexport {\n defaultRequiredScopes,\n executeScopeFor,\n MAX_DEFAULT_SCOPE_LENGTH,\n type ToolScopeSources,\n} from './default-required-scopes';\n\n/**\n * Pattern for valid environment variable names (e.g., X_API_KEY, OPENAI_KEY).\n * Inlined from the former `@kya-os/contracts/vault` `ENV_VAR_PATTERN`.\n */\nconst ENV_VAR_PATTERN = /^[A-Z][A-Z0-9_]*$/;\n\n/**\n * Validates an env var name used by the `apikey` authorization requirement.\n * Inlined from the former `@kya-os/contracts/vault` `envVarNameSchema`.\n */\nconst envVarNameSchema = z\n .string()\n .regex(ENV_VAR_PATTERN, 'Must be a valid env var name (e.g., X_API_KEY)')\n .max(255);\n\n/**\n * Authorization Requirement - what auth is needed BEFORE consent screen.\n *\n * Types: none (2 screens), oauth/password/mdl/idv (3 screens), verifiable_credential (future).\n * The VC output is always a DelegationCredential created on consent confirmation.\n */\nexport type AuthorizationRequirement =\n | {\n /**\n * @deprecated Use 'oauth2' instead. Will be removed in v2.0.0.\n */\n type: 'oauth';\n provider: string; // \"github\", \"google\", etc.\n requiredScopes?: string[]; // Provider-specific scopes\n }\n | {\n /** OAuth 2.0 provider authentication (canonical) */\n type: 'oauth2';\n provider: string; // \"github\", \"google\", etc.\n requiredScopes?: string[]; // Provider-specific scopes\n }\n | {\n type: 'password';\n provider: string; // Credential provider ID (e.g., \"hardwareworld\", \"custom\")\n }\n | {\n type: 'mdl';\n issuer: string; // MDL issuer DID or identifier\n credentialType?: string; // Specific MDL credential type\n }\n | {\n type: 'idv';\n provider: string; // IDV provider name\n verificationLevel?: 'basic' | 'enhanced' | 'loa3';\n }\n | {\n /** Require user to present an existing VC */\n type: 'verifiable_credential';\n credentialType: string;\n issuer?: string;\n }\n | {\n /**\n * @deprecated Use 'verifiable_credential' instead. Will be removed in v2.0.0.\n * This is an alias for 'verifiable_credential' for backward compatibility.\n */\n type: 'credential';\n credentialType: string;\n issuer?: string;\n }\n | {\n /** WebAuthn/Passkey authentication */\n type: 'webauthn';\n rpId?: string; // Relying Party ID\n userVerification?: 'required' | 'preferred' | 'discouraged';\n }\n | {\n /** Sign-In with Ethereum (EIP-4361) */\n type: 'siwe';\n chainId?: number; // Ethereum chain ID (1 = mainnet, 137 = polygon, etc.)\n domain?: string; // Domain for SIWE message\n }\n | {\n /** API Key from per-user vault */\n type: 'apikey';\n envVarNames: string[]; // Env var names to resolve from vault (e.g., ['X_API_KEY'])\n headerMapping: Record<string, string>; // Map env var → HTTP header (e.g., { X_API_KEY: 'X-API-Key' })\n }\n | {\n type: 'none'; // Just consent checkbox, no external auth\n };\n\n/** Canonical authorization type values for type safety */\nexport const AUTHORIZATION_TYPES = {\n /** @deprecated Use OAUTH2 instead. Will be removed in v2.0.0. */\n OAUTH: 'oauth',\n /** OAuth 2.0 provider authentication (canonical) */\n OAUTH2: 'oauth2',\n PASSWORD: 'password',\n MDL: 'mdl',\n IDV: 'idv',\n VERIFIABLE_CREDENTIAL: 'verifiable_credential',\n /** WebAuthn/Passkey authentication */\n WEBAUTHN: 'webauthn',\n /** Sign-In with Ethereum (EIP-4361) */\n SIWE: 'siwe',\n /** API Key from per-user vault */\n APIKEY: 'apikey',\n NONE: 'none',\n} as const;\n\nexport type AuthorizationType = (typeof AUTHORIZATION_TYPES)[keyof typeof AUTHORIZATION_TYPES];\n\n/**\n * Tool Protection Definition\n *\n * Defines the protection requirements for a tool as per KYA-OS spec.\n * This is the canonical definition that all implementations must follow.\n */\nexport interface ToolProtection {\n /**\n * Whether this tool requires explicit delegation from the user\n */\n requiresDelegation: boolean;\n\n /**\n * The scopes required to execute this tool\n * Format: \"resource:action\" (e.g., \"files:read\", \"payment:send\")\n */\n requiredScopes: string[];\n\n /**\n * Risk level classification for the tool\n * Used to determine appropriate authorization flows\n */\n riskLevel?: 'low' | 'medium' | 'high' | 'critical';\n\n /**\n * OAuth provider name for this tool (Phase 2+)\n * If specified, this tool will use the specified OAuth provider.\n * If not specified, provider will be resolved via fallback strategies.\n * @example \"github\", \"google\", \"microsoft\"\n * @deprecated Use `authorization` field instead. Will be removed in Phase 3.\n */\n oauthProvider?: string;\n\n /**\n * Authorization requirement for this tool\n * If requiresDelegation=true, authorization must be specified (or inferred from legacy fields)\n */\n authorization?: AuthorizationRequirement;\n}\n\n/**\n * Tool Protection Map\n *\n * A mapping of tool names to their protection configurations.\n * This is how tool protections are typically stored and transmitted.\n */\nexport type ToolProtectionMap = Record<string, ToolProtection>;\n\n/**\n * Partial tool protection for updates (all fields optional)\n * Use this when accepting partial updates to tool protection settings\n */\nexport type PartialToolProtection = Partial<ToolProtection>;\n\n/**\n * Tool protection with explicit optional fields\n * Useful when TypeScript's Partial<T> doesn't preserve optional property access\n * Supports explicit null values to clear fields\n */\nexport type ToolProtectionUpdate = {\n requiresDelegation?: boolean;\n requiredScopes?: string[];\n riskLevel?: 'low' | 'medium' | 'high' | 'critical';\n oauthProvider?: string | null; // null explicitly clears the field\n authorization?: AuthorizationRequirement | null; // null explicitly clears the field\n};\n\n/**\n * Tool Protection Response\n *\n * The response format when querying for tool protections.\n * Used by tool protection services and APIs.\n */\nexport interface ToolProtectionResponse {\n /**\n * The tool protections keyed by tool name\n */\n toolProtections: ToolProtectionMap;\n\n /**\n * Optional metadata about the response\n */\n metadata?: {\n /**\n * When this configuration was last updated\n */\n lastUpdated?: string;\n\n /**\n * Version of the configuration\n */\n version?: string;\n\n /**\n * Source of the configuration\n */\n source?: string;\n };\n}\n\n/**\n * Delegation Required Error Data\n *\n * The standardized error data returned when a tool requires delegation\n * but none was provided. This is part of the KYA-OS error protocol.\n */\nexport interface DelegationRequiredErrorData {\n /**\n * The name of the tool that requires delegation\n */\n toolName: string;\n\n /**\n * The scopes required for this tool\n */\n requiredScopes: string[];\n\n /**\n * URL where the user can provide consent/delegation\n */\n consentUrl?: string;\n\n /**\n * Alternative field for consent URL (for compatibility)\n */\n authorizationUrl?: string;\n\n /**\n * Additional context about why delegation is required\n */\n reason?: string;\n}\n\n/**\n * Auth Required Error Data\n *\n * Machine-readable error returned when a tool requires per-user auth\n * (vault secret, OAuth, credential) but none is configured and no\n * static env fallback exists. MCP clients use this to present\n * actionable guidance (e.g., \"Add your PulseMCP API key\" with a link).\n *\n * Closes VAULT-11\n */\nexport interface AuthRequiredErrorData {\n /** Discriminator — always \"auth_required\" */\n error: 'auth_required';\n\n /** Which auth mechanism is missing */\n type: 'apikey' | 'oauth' | 'credential';\n\n /** For apikey: which env vars are missing */\n envVarNames?: string[];\n\n /** Dashboard URL where the user can configure the missing auth */\n configUrl: string;\n\n /** Human-readable fallback message */\n message: string;\n}\n\nexport const AuthRequiredErrorDataSchema = z.object({\n error: z.literal('auth_required'),\n type: z.enum(['apikey', 'oauth', 'credential']),\n envVarNames: z.array(z.string()).optional(),\n configUrl: z.string(),\n message: z.string(),\n});\n\n/**\n * Error class thrown when required auth is missing and no fallback exists.\n *\n * Caught by the tool-call handler in agent.ts and serialized as a\n * machine-readable MCP tool result so clients can present actionable UI.\n */\nexport class AuthRequiredError extends Error {\n public readonly type: AuthRequiredErrorData['type'];\n public readonly envVarNames?: string[];\n public readonly configUrl: string;\n\n constructor(opts: {\n type: AuthRequiredErrorData['type'];\n envVarNames?: string[];\n configUrl: string;\n message?: string;\n }) {\n const message =\n opts.message ??\n (opts.type === 'apikey' && opts.envVarNames?.length\n ? `API key required: configure ${opts.envVarNames.join(', ')} in your project settings.`\n : 'Authentication required to use this tool.');\n super(message);\n this.name = 'AuthRequiredError';\n this.type = opts.type;\n this.envVarNames = opts.envVarNames;\n this.configUrl = opts.configUrl;\n }\n\n /** Serialize to the wire format MCP clients expect */\n toJSON(): AuthRequiredErrorData {\n return {\n error: 'auth_required',\n type: this.type,\n ...(this.envVarNames && { envVarNames: this.envVarNames }),\n configUrl: this.configUrl,\n message: this.message,\n };\n }\n}\n\n/**\n * Legacy tool protection format (pre-authorization field)\n * Used during migration period to support both old and new formats\n */\nexport type LegacyToolProtection = Omit<ToolProtection, 'authorization'> & {\n oauthProvider?: string;\n};\n\n/**\n * Union type for both legacy and new formats\n * Useful during migration period when accepting tool protection input\n */\nexport type ToolProtectionInput = ToolProtection | LegacyToolProtection;\n\n/**\n * Zod Schemas for Validation\n */\n\nexport const AuthorizationRequirementSchema = z.discriminatedUnion('type', [\n // Deprecated: 'oauth' is an alias for 'oauth2'\n // Will be removed in v2.0.0. Use 'oauth2' instead.\n z.object({\n type: z.literal('oauth'),\n provider: z.string(),\n requiredScopes: z.array(z.string()).optional(),\n }),\n // OAuth 2.0 provider authentication (canonical)\n z.object({\n type: z.literal('oauth2'),\n provider: z.string(),\n requiredScopes: z.array(z.string()).optional(),\n }),\n z.object({\n type: z.literal('password'),\n provider: z.string(),\n }),\n z.object({\n type: z.literal('mdl'),\n issuer: z.string(),\n credentialType: z.string().optional(),\n }),\n z.object({\n type: z.literal('idv'),\n provider: z.string(),\n verificationLevel: z.enum(['basic', 'enhanced', 'loa3']).optional(),\n }),\n z.object({\n type: z.literal('verifiable_credential'),\n credentialType: z.string(),\n issuer: z.string().optional(),\n }),\n // Deprecated: 'credential' is an alias for 'verifiable_credential'\n // Will be removed in v2.0.0. Use 'verifiable_credential' instead.\n z.object({\n type: z.literal('credential'),\n credentialType: z.string(),\n issuer: z.string().optional(),\n }),\n // WebAuthn/Passkey authentication\n z.object({\n type: z.literal('webauthn'),\n rpId: z.string().optional(),\n userVerification: z.enum(['required', 'preferred', 'discouraged']).optional(),\n }),\n // Sign-In with Ethereum (EIP-4361)\n z.object({\n type: z.literal('siwe'),\n chainId: z.number().optional(),\n domain: z.string().optional(),\n }),\n // API Key from per-user vault\n z.object({\n type: z.literal('apikey'),\n envVarNames: z.array(envVarNameSchema).min(1),\n headerMapping: z.record(z.string(), z.string()),\n }),\n z.object({\n type: z.literal('none'),\n }),\n]);\n\nexport const ToolProtectionSchema = z.object({\n requiresDelegation: z.boolean(),\n requiredScopes: z.array(z.string()),\n riskLevel: z.enum(['low', 'medium', 'high', 'critical']).optional(),\n oauthProvider: z.string().optional(), // Phase 2: Tool-specific OAuth provider\n authorization: AuthorizationRequirementSchema.optional(),\n});\n\nexport const ToolProtectionMapSchema = z.record(z.string(), ToolProtectionSchema);\n\nexport const ToolProtectionResponseSchema = z.object({\n toolProtections: ToolProtectionMapSchema,\n metadata: z\n .object({\n lastUpdated: z.string().optional(),\n version: z.string().optional(),\n source: z.string().optional(),\n })\n .optional(),\n});\n\nexport const DelegationRequiredErrorDataSchema = z.object({\n toolName: z.string(),\n requiredScopes: z.array(z.string()),\n consentUrl: z.string().optional(),\n authorizationUrl: z.string().optional(),\n reason: z.string().optional(),\n});\n\n/**\n * Type Guards\n */\n\nexport function isToolProtection(obj: unknown): obj is ToolProtection {\n return ToolProtectionSchema.safeParse(obj).success;\n}\n\nexport function isToolProtectionMap(obj: unknown): obj is ToolProtectionMap {\n return ToolProtectionMapSchema.safeParse(obj).success;\n}\n\nexport function isToolProtectionResponse(obj: unknown): obj is ToolProtectionResponse {\n return ToolProtectionResponseSchema.safeParse(obj).success;\n}\n\nexport function isDelegationRequiredErrorData(obj: unknown): obj is DelegationRequiredErrorData {\n return DelegationRequiredErrorDataSchema.safeParse(obj).success;\n}\n\n/**\n * Type guard to check if an object is a valid AuthorizationRequirement\n */\nexport function isAuthorizationRequirement(obj: unknown): obj is AuthorizationRequirement {\n return AuthorizationRequirementSchema.safeParse(obj).success;\n}\n\n/**\n * Type guard to check if a ToolProtection has OAuth authorization\n * Checks for both 'oauth' (deprecated) and 'oauth2' (canonical)\n */\nexport function hasOAuthAuthorization(\n protection: ToolProtection\n): protection is ToolProtection & { authorization: { type: 'oauth' | 'oauth2' } } {\n return protection.authorization?.type === 'oauth' || protection.authorization?.type === 'oauth2';\n}\n\n/**\n * Type guard to check if a ToolProtection has password authorization\n */\nexport function hasPasswordAuthorization(\n protection: ToolProtection\n): protection is ToolProtection & { authorization: { type: 'password' } } {\n return protection.authorization?.type === 'password';\n}\n\n/**\n * Type guard to check if a ToolProtection requires a Verifiable Credential\n *\n * Note: Also returns true for deprecated 'credential' type (normalized to verifiable_credential)\n */\nexport function hasVerifiableCredentialAuthorization(\n protection: ToolProtection\n): protection is ToolProtection & {\n authorization: { type: 'verifiable_credential' | 'credential' };\n} {\n return (\n protection.authorization?.type === 'verifiable_credential' ||\n protection.authorization?.type === 'credential'\n );\n}\n\n/**\n * Type guard to check if a ToolProtection has API Key (vault) authorization\n */\nexport function hasApiKeyAuthorization(\n protection: ToolProtection\n): protection is ToolProtection & { authorization: { type: 'apikey' } } {\n return protection.authorization?.type === 'apikey';\n}\n\n/**\n * Validation Functions\n */\n\nexport function validateToolProtection(obj: unknown): ToolProtection {\n return ToolProtectionSchema.parse(obj);\n}\n\nexport function validateToolProtectionMap(obj: unknown): ToolProtectionMap {\n return ToolProtectionMapSchema.parse(obj);\n}\n\nexport function validateToolProtectionResponse(obj: unknown): ToolProtectionResponse {\n return ToolProtectionResponseSchema.parse(obj);\n}\n\nexport function validateDelegationRequiredErrorData(obj: unknown): DelegationRequiredErrorData {\n return DelegationRequiredErrorDataSchema.parse(obj);\n}\n\n/**\n * Utility Functions\n */\n\n/**\n * Check if a tool requires delegation\n */\nexport function toolRequiresDelegation(toolName: string, protections: ToolProtectionMap): boolean {\n const protection = protections[toolName];\n return protection?.requiresDelegation ?? false;\n}\n\n/**\n * Get required scopes for a tool\n */\nexport function getToolRequiredScopes(toolName: string, protections: ToolProtectionMap): string[] {\n const protection = protections[toolName];\n return protection?.requiredScopes ?? [];\n}\n\n/**\n * Get risk level for a tool\n */\nexport function getToolRiskLevel(\n toolName: string,\n protections: ToolProtectionMap\n): ToolProtection['riskLevel'] | undefined {\n return protections[toolName]?.riskLevel;\n}\n\n/**\n * Create a delegation required error\n */\nexport function createDelegationRequiredError(\n toolName: string,\n requiredScopes: string[],\n consentUrl?: string\n): DelegationRequiredErrorData {\n return {\n toolName,\n requiredScopes,\n consentUrl,\n authorizationUrl: consentUrl, // Include both for compatibility\n };\n}\n\n/**\n * Normalize tool protection configuration\n * Migrates legacy oauthProvider field to authorization object\n *\n * - Migrates `oauthProvider` → `authorization: { type: 'oauth', provider: ... }`\n * - Ensures `authorization` field is present when `requiresDelegation=true`\n * - Returns fully normalized ToolProtection object\n *\n * @param raw - Raw tool protection data (may have legacy fields or be partial)\n * @returns Normalized ToolProtection object\n *\n * // TODO: Remove normalizeToolProtection() when all tools migrated\n */\nexport function normalizeToolProtection(\n raw: ToolProtection | PartialToolProtection\n): ToolProtection {\n // Ensure we have required fields (provide defaults for partial input)\n const normalized: ToolProtection = {\n requiresDelegation: raw.requiresDelegation ?? false,\n requiredScopes: raw.requiredScopes ?? [],\n ...(raw.riskLevel && { riskLevel: raw.riskLevel }),\n ...(raw.oauthProvider && { oauthProvider: raw.oauthProvider }),\n };\n\n // If authorization is already present, use it\n if (raw.authorization) {\n normalized.authorization = raw.authorization;\n return normalized;\n }\n\n // Migrate oauthProvider to authorization\n if (raw.oauthProvider) {\n normalized.authorization = {\n type: 'oauth',\n provider: raw.oauthProvider,\n };\n // Keep oauthProvider for backward compatibility\n return normalized;\n }\n\n // Default for requiresDelegation=true without specific auth: type='none' (consent only)\n // But ONLY if authorization is missing entirely\n if (normalized.requiresDelegation && !normalized.authorization && !normalized.oauthProvider) {\n // We don't automatically set type='none' here to allow\n // ProviderResolver to do its scope inference fallback logic.\n // The fallback logic will eventually be moved into an AuthorizationService.\n return normalized;\n }\n\n return normalized;\n}\n\n// =============================================================================\n// CONSENT PROVIDER TYPES - Records what auth method was USED (not required)\n// =============================================================================\n\n/** Consent provider types - stored in delegation metadata to track auth method used */\nexport const CONSENT_PROVIDER_TYPES = {\n /** Consent-only mode - no authentication, just clickwrap agreement */\n NONE: 'none',\n /** OAuth2 provider authentication */\n OAUTH2: 'oauth2',\n /** Password-based authentication (email/password, username/password) */\n PASSWORD: 'password',\n /** @deprecated Use PASSWORD instead. Alias for backward compatibility */\n CREDENTIAL: 'credential',\n /** Email magic link authentication */\n MAGIC_LINK: 'magic_link',\n /** One-time password (SMS/email code) */\n OTP: 'otp',\n} as const;\n\nexport type ConsentProviderType =\n (typeof CONSENT_PROVIDER_TYPES)[keyof typeof CONSENT_PROVIDER_TYPES];\n\n/**\n * Determine consent provider type based on available identity information\n *\n * This is the single source of truth for consent provider type determination.\n *\n * @param hasOAuthIdentity - Whether OAuth identity is available\n * @param isPasswordFlow - Whether this is a password/credential flow\n * @param isMagicLinkFlow - Whether this is a magic link flow\n * @param isOtpFlow - Whether this is an OTP flow\n * @returns The consent provider type\n */\nexport function determineConsentProviderType(\n hasOAuthIdentity: boolean,\n isPasswordFlow: boolean = false,\n isMagicLinkFlow: boolean = false,\n isOtpFlow: boolean = false\n): ConsentProviderType {\n if (isPasswordFlow) {\n return CONSENT_PROVIDER_TYPES.PASSWORD;\n }\n if (isMagicLinkFlow) {\n return CONSENT_PROVIDER_TYPES.MAGIC_LINK;\n }\n if (isOtpFlow) {\n return CONSENT_PROVIDER_TYPES.OTP;\n }\n if (hasOAuthIdentity) {\n return CONSENT_PROVIDER_TYPES.OAUTH2;\n }\n return CONSENT_PROVIDER_TYPES.NONE;\n}\n\n/**\n * Get a human-readable label for an authorization requirement type\n */\nexport function getAuthorizationTypeLabel(auth: AuthorizationRequirement): string {\n switch (auth.type) {\n case 'oauth':\n case 'oauth2':\n return auth.provider\n ? auth.provider.charAt(0).toUpperCase() + auth.provider.slice(1)\n : 'OAuth Provider';\n case 'password':\n return 'Password Authentication';\n case 'mdl':\n return \"Mobile Driver's License\";\n case 'idv':\n return 'Identity Verification';\n case 'verifiable_credential':\n return auth.credentialType || 'Verifiable Credential';\n case 'credential':\n // Deprecated: treat as verifiable_credential\n return auth.credentialType || 'Verifiable Credential';\n case 'webauthn':\n return 'Passkey / WebAuthn';\n case 'siwe':\n return 'Sign-In with Ethereum';\n case 'apikey':\n return 'API Key (Vault)';\n case 'none':\n return 'Consent Only';\n default: {\n // Closed union — this default is unreachable for well-typed input.\n return 'Unknown';\n }\n }\n}\n\n/**\n * Get a unique key for an authorization requirement (for React keys, caching, etc.)\n */\nexport function getAuthorizationTypeKey(auth: AuthorizationRequirement): string {\n switch (auth.type) {\n case 'oauth':\n // Keep original key format for backward compatibility with existing cache entries\n // Handle undefined provider gracefully (may come from loose API response types)\n return auth.provider ? `oauth:${auth.provider}` : 'oauth';\n case 'oauth2':\n return auth.provider ? `oauth2:${auth.provider}` : 'oauth2';\n case 'password':\n return auth.provider ? `password:${auth.provider}` : 'password';\n case 'mdl':\n // Keep trailing colon for backward compatibility with existing cache entries\n return `mdl:${auth.issuer || 'unknown'}:${auth.credentialType || ''}`;\n case 'idv':\n // Keep trailing colon for backward compatibility with existing cache entries\n return `idv:${auth.provider || 'unknown'}:${auth.verificationLevel || ''}`;\n case 'verifiable_credential':\n return `vc:${auth.issuer || 'any'}:${auth.credentialType || 'unknown'}`;\n case 'credential':\n // Deprecated: treat as verifiable_credential\n return `vc:${auth.issuer || 'any'}:${auth.credentialType || 'unknown'}`;\n case 'webauthn':\n return `webauthn:${auth.rpId || 'default'}`;\n case 'siwe':\n return `siwe:${auth.chainId || 1}:${auth.domain || 'any'}`;\n case 'apikey':\n return `apikey:${[...auth.envVarNames].sort().join(',')}`;\n case 'none':\n return 'none';\n default: {\n // Closed union — this default is unreachable for well-typed input.\n return 'unknown';\n }\n }\n}\n\n/**\n * Normalize authorization requirement type\n *\n * Normalizes deprecated types to their canonical equivalents:\n * - 'oauth' → 'oauth2'\n * - 'credential' → 'verifiable_credential'\n *\n * This function should be called at runtime boundaries when processing\n * authorization requirements.\n *\n * @param auth - Authorization requirement (may contain deprecated types)\n * @param options - Normalization options\n * @returns Normalized authorization requirement\n *\n * @example\n * ```typescript\n * const normalized = normalizeAuthorizationType(\n * { type: 'oauth', provider: 'github' },\n * { warn: true }\n * );\n * // Returns: { type: 'oauth2', provider: 'github' }\n * // Logs: DEPRECATION warning\n * ```\n */\nexport function normalizeAuthorizationType(\n auth: AuthorizationRequirement,\n options: { warn?: boolean; logger?: (message: string) => void } = {}\n): AuthorizationRequirement {\n const { warn = true, logger = console.warn } = options;\n\n // Normalize 'oauth' to 'oauth2'\n if (auth.type === 'oauth') {\n if (warn) {\n logger(\n `DEPRECATION: Authorization type 'oauth' is deprecated and will be removed in v2.0.0. ` +\n `Please update to 'oauth2'. ` +\n `See https://github.com/modelcontextprotocol-identity/xmcp-i/blob/main/docs/migrations/oauth-to-oauth2.md`\n );\n }\n\n // Normalize to oauth2\n const normalized = {\n type: 'oauth2' as const,\n provider: auth.provider,\n ...(auth.requiredScopes !== undefined && { requiredScopes: auth.requiredScopes }),\n };\n\n return normalized;\n }\n\n // Normalize 'credential' to 'verifiable_credential'\n if (auth.type === 'credential') {\n if (warn) {\n logger(\n `DEPRECATION: Authorization type 'credential' is deprecated and will be removed in v2.0.0. ` +\n `Please update to 'verifiable_credential'. ` +\n `See https://github.com/modelcontextprotocol-identity/xmcp-i/blob/main/docs/migrations/credential-to-verifiable_credential.md`\n );\n }\n\n // Normalize to verifiable_credential\n const normalized = {\n type: 'verifiable_credential' as const,\n credentialType: auth.credentialType,\n ...(auth.issuer !== undefined && { issuer: auth.issuer }),\n };\n\n return normalized;\n }\n\n // No normalization needed\n return auth;\n}\n"],"mappings":"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"}
1
+ {"version":3,"file":"index.mjs","names":[],"sources":["../../src/tool-protection/default-required-scopes.ts","../../src/tool-protection/index.ts"],"sourcesContent":["/**\n * The scopes a tool entry is served with when it has none of its own.\n *\n * The edge and the runtime let a credential through a protected tool when it\n * carries every scope in the tool's served `requiredScopes`, so a protected\n * tool served with `[]` opens to ANY valid credential for the resource. Every\n * writer of `bouncer_configs.discovered_tools` stores a scope through this one\n * rule, so a tool never reaches the served map with an empty list.\n *\n * @module @kya-os/checkpoint-shared/tool-protection\n */\n\n/** The fields of a stored tool entry this rule reads. Stored rows are untyped JSON. */\nexport interface ToolScopeSources {\n /** The entry's own served scopes. */\n requiredScopes?: unknown;\n /** The legacy key proof discovery wrote: the scope the runtime reported (`scopeId`). */\n scopes?: unknown;\n /** The security schemes a server declared for the tool; oauth2 entries carry `scopes`. */\n securitySchemes?: unknown;\n /** The capability the tool gates on, from server registration. */\n capability?: unknown;\n}\n\n/** The longest scope a consent request carries. */\nexport const MAX_DEFAULT_SCOPE_LENGTH = 200;\n\nconst EXECUTE_SUFFIX = ':execute';\n\n/** Outside the RFC 6749 scope-token alphabet: printable ASCII except space, `\"` and `\\`. */\nconst NON_SCOPE_TOKEN_CHARS = /[^\\x21\\x23-\\x5B\\x5D-\\x7E]/gu;\n\nfunction scopeList(value: unknown): string[] | undefined {\n return Array.isArray(value) && value.length > 0 && value.every((item) => typeof item === 'string')\n ? value\n : undefined;\n}\n\nfunction declaredOauthScopes(schemes: unknown): string[] {\n if (!Array.isArray(schemes)) return [];\n const scopes = schemes.flatMap((scheme: unknown) =>\n typeof scheme === 'object' &&\n scheme !== null &&\n (scheme as { type?: unknown }).type === 'oauth2' &&\n Array.isArray((scheme as { scopes?: unknown }).scopes)\n ? ((scheme as { scopes: unknown[] }).scopes.filter(\n (scope) => typeof scope === 'string' && scope.length > 0\n ) as string[])\n : []\n );\n return [...new Set(scopes)];\n}\n\n/**\n * `<name>:execute`, with the name reduced to the scope-token alphabet (the edge\n * drops other characters) and the whole scope at most\n * {@link MAX_DEFAULT_SCOPE_LENGTH} characters.\n */\nexport function executeScopeFor(toolName: string): string {\n const name = toolName\n .replace(NON_SCOPE_TOKEN_CHARS, '_')\n .slice(0, MAX_DEFAULT_SCOPE_LENGTH - EXECUTE_SUFFIX.length);\n return `${name}${EXECUTE_SUFFIX}`;\n}\n\n/**\n * The scopes to store for `toolName`: the first non-empty of\n *\n * 1. the entry's own `requiredScopes`, as stored;\n * 2. its legacy `scopes`, so a grant for the scope the runtime reported keeps matching;\n * 3. the oauth2 scopes its `securitySchemes` declare;\n * 4. its `capability`;\n * 5. {@link executeScopeFor}`(toolName)`.\n *\n * Never empty. An absent entry gets the last.\n */\nexport function defaultRequiredScopes(\n toolName: string,\n entry: ToolScopeSources | null | undefined\n): string[] {\n const own = scopeList(entry?.requiredScopes) ?? scopeList(entry?.scopes);\n if (own) return [...own];\n const declared = declaredOauthScopes(entry?.securitySchemes);\n if (declared.length > 0) return declared;\n if (typeof entry?.capability === 'string' && entry.capability.length > 0) {\n return [entry.capability];\n }\n return [executeScopeFor(toolName)];\n}\n","/**\n * KYA-OS Tool Protection Specification\n *\n * Core types for tool protection with delegation requirements.\n *\n * Consent Flow: type='none' → 2 screens, others → 3 screens (Auth→Consent→Success).\n * DelegationCredential (VC) is created when user confirms on Consent Screen.\n *\n * Ported into checkpoint-shared from `@kya-os/contracts/tool-protection` as part\n * of the E6 / C-series decommission (#2914 / #2917): checkpoint owns its product\n * types now that the DIF `@kya-os/mcp` core is protocol-only. The single external\n * dependency (`envVarNameSchema` from the contracts `vault` module) is inlined\n * below so this module pulls nothing from `@kya-os/contracts`.\n *\n * @module @kya-os/checkpoint-shared/tool-protection\n */\n\nimport { z } from 'zod';\n\nexport {\n defaultRequiredScopes,\n executeScopeFor,\n MAX_DEFAULT_SCOPE_LENGTH,\n type ToolScopeSources,\n} from './default-required-scopes';\n\n/**\n * Pattern for valid environment variable names (e.g., X_API_KEY, OPENAI_KEY).\n * Inlined from the former `@kya-os/contracts/vault` `ENV_VAR_PATTERN`.\n */\nconst ENV_VAR_PATTERN = /^[A-Z][A-Z0-9_]*$/;\n\n/**\n * Validates an env var name used by the `apikey` authorization requirement.\n * Inlined from the former `@kya-os/contracts/vault` `envVarNameSchema`.\n */\nconst envVarNameSchema = z\n .string()\n .regex(ENV_VAR_PATTERN, 'Must be a valid env var name (e.g., X_API_KEY)')\n .max(255);\n\n/**\n * Authorization Requirement - what auth is needed BEFORE consent screen.\n *\n * Types: none (2 screens), oauth/password/mdl/idv (3 screens), verifiable_credential (future).\n * The VC output is always a DelegationCredential created on consent confirmation.\n */\nexport type AuthorizationRequirement =\n | {\n /**\n * @deprecated Use 'oauth2' instead. Will be removed in v2.0.0.\n */\n type: 'oauth';\n provider: string; // \"github\", \"google\", etc.\n requiredScopes?: string[]; // Provider-specific scopes\n }\n | {\n /** OAuth 2.0 provider authentication (canonical) */\n type: 'oauth2';\n provider: string; // \"github\", \"google\", etc.\n requiredScopes?: string[]; // Provider-specific scopes\n }\n | {\n type: 'password';\n provider: string;\n }\n | {\n type: 'mdl';\n issuer: string; // MDL issuer DID or identifier\n credentialType?: string; // Specific MDL credential type\n }\n | {\n type: 'idv';\n provider: string; // IDV provider name\n verificationLevel?: 'basic' | 'enhanced' | 'loa3';\n }\n | {\n /** Require user to present an existing VC */\n type: 'verifiable_credential';\n credentialType: string;\n issuer?: string;\n }\n | {\n /**\n * @deprecated Use 'verifiable_credential' instead. Will be removed in v2.0.0.\n * This is an alias for 'verifiable_credential' for backward compatibility.\n */\n type: 'credential';\n credentialType: string;\n issuer?: string;\n }\n | {\n /** WebAuthn/Passkey authentication */\n type: 'webauthn';\n rpId?: string; // Relying Party ID\n userVerification?: 'required' | 'preferred' | 'discouraged';\n }\n | {\n /** Sign-In with Ethereum (EIP-4361) */\n type: 'siwe';\n chainId?: number; // Ethereum chain ID (1 = mainnet, 137 = polygon, etc.)\n domain?: string; // Domain for SIWE message\n }\n | {\n /** API Key from per-user vault */\n type: 'apikey';\n envVarNames: string[]; // Env var names to resolve from vault (e.g., ['X_API_KEY'])\n headerMapping: Record<string, string>; // Map env var → HTTP header (e.g., { X_API_KEY: 'X-API-Key' })\n }\n | {\n type: 'none'; // Just consent checkbox, no external auth\n };\n\n/** Canonical authorization type values for type safety */\nexport const AUTHORIZATION_TYPES = {\n /** @deprecated Use OAUTH2 instead. Will be removed in v2.0.0. */\n OAUTH: 'oauth',\n /** OAuth 2.0 provider authentication (canonical) */\n OAUTH2: 'oauth2',\n PASSWORD: 'password',\n MDL: 'mdl',\n IDV: 'idv',\n VERIFIABLE_CREDENTIAL: 'verifiable_credential',\n /** WebAuthn/Passkey authentication */\n WEBAUTHN: 'webauthn',\n /** Sign-In with Ethereum (EIP-4361) */\n SIWE: 'siwe',\n /** API Key from per-user vault */\n APIKEY: 'apikey',\n NONE: 'none',\n} as const;\n\nexport type AuthorizationType = (typeof AUTHORIZATION_TYPES)[keyof typeof AUTHORIZATION_TYPES];\n\n/**\n * Tool Protection Definition\n *\n * Defines the protection requirements for a tool as per KYA-OS spec.\n * This is the canonical definition that all implementations must follow.\n */\nexport interface ToolProtection {\n /**\n * Whether this tool requires explicit delegation from the user\n */\n requiresDelegation: boolean;\n\n /**\n * The scopes required to execute this tool\n * Format: \"resource:action\" (e.g., \"files:read\", \"payment:send\")\n */\n requiredScopes: string[];\n\n /**\n * Risk level classification for the tool\n * Used to determine appropriate authorization flows\n */\n riskLevel?: 'low' | 'medium' | 'high' | 'critical';\n\n /**\n * OAuth provider name for this tool (Phase 2+)\n * If specified, this tool will use the specified OAuth provider.\n * If not specified, provider will be resolved via fallback strategies.\n * @example \"github\", \"google\", \"microsoft\"\n * @deprecated Use `authorization` field instead. Will be removed in Phase 3.\n */\n oauthProvider?: string;\n\n /**\n * Authorization requirement for this tool\n * If requiresDelegation=true, authorization must be specified (or inferred from legacy fields)\n */\n authorization?: AuthorizationRequirement;\n}\n\n/**\n * Tool Protection Map\n *\n * A mapping of tool names to their protection configurations.\n * This is how tool protections are typically stored and transmitted.\n */\nexport type ToolProtectionMap = Record<string, ToolProtection>;\n\n/**\n * Partial tool protection for updates (all fields optional)\n * Use this when accepting partial updates to tool protection settings\n */\nexport type PartialToolProtection = Partial<ToolProtection>;\n\n/**\n * Tool protection with explicit optional fields\n * Useful when TypeScript's Partial<T> doesn't preserve optional property access\n * Supports explicit null values to clear fields\n */\nexport type ToolProtectionUpdate = {\n requiresDelegation?: boolean;\n requiredScopes?: string[];\n riskLevel?: 'low' | 'medium' | 'high' | 'critical';\n oauthProvider?: string | null; // null explicitly clears the field\n authorization?: AuthorizationRequirement | null; // null explicitly clears the field\n};\n\n/**\n * Tool Protection Response\n *\n * The response format when querying for tool protections.\n * Used by tool protection services and APIs.\n */\nexport interface ToolProtectionResponse {\n /**\n * The tool protections keyed by tool name\n */\n toolProtections: ToolProtectionMap;\n\n /**\n * Optional metadata about the response\n */\n metadata?: {\n /**\n * When this configuration was last updated\n */\n lastUpdated?: string;\n\n /**\n * Version of the configuration\n */\n version?: string;\n\n /**\n * Source of the configuration\n */\n source?: string;\n };\n}\n\n/**\n * Delegation Required Error Data\n *\n * The standardized error data returned when a tool requires delegation\n * but none was provided. This is part of the KYA-OS error protocol.\n */\nexport interface DelegationRequiredErrorData {\n /**\n * The name of the tool that requires delegation\n */\n toolName: string;\n\n /**\n * The scopes required for this tool\n */\n requiredScopes: string[];\n\n /**\n * URL where the user can provide consent/delegation\n */\n consentUrl?: string;\n\n /**\n * Alternative field for consent URL (for compatibility)\n */\n authorizationUrl?: string;\n\n /**\n * Additional context about why delegation is required\n */\n reason?: string;\n}\n\n/**\n * Auth Required Error Data\n *\n * Machine-readable error returned when a tool requires per-user auth\n * (vault secret, OAuth, credential) but none is configured and no\n * static env fallback exists. MCP clients use this to present\n * actionable guidance (e.g., \"Add your PulseMCP API key\" with a link).\n *\n * Closes VAULT-11\n */\nexport interface AuthRequiredErrorData {\n /** Discriminator — always \"auth_required\" */\n error: 'auth_required';\n\n /** Which auth mechanism is missing */\n type: 'apikey' | 'oauth' | 'credential';\n\n /** For apikey: which env vars are missing */\n envVarNames?: string[];\n\n /** Dashboard URL where the user can configure the missing auth */\n configUrl: string;\n\n /** Human-readable fallback message */\n message: string;\n}\n\nexport const AuthRequiredErrorDataSchema = z.object({\n error: z.literal('auth_required'),\n type: z.enum(['apikey', 'oauth', 'credential']),\n envVarNames: z.array(z.string()).optional(),\n configUrl: z.string(),\n message: z.string(),\n});\n\n/**\n * Error class thrown when required auth is missing and no fallback exists.\n *\n * Caught by the tool-call handler in agent.ts and serialized as a\n * machine-readable MCP tool result so clients can present actionable UI.\n */\nexport class AuthRequiredError extends Error {\n public readonly type: AuthRequiredErrorData['type'];\n public readonly envVarNames?: string[];\n public readonly configUrl: string;\n\n constructor(opts: {\n type: AuthRequiredErrorData['type'];\n envVarNames?: string[];\n configUrl: string;\n message?: string;\n }) {\n const message =\n opts.message ??\n (opts.type === 'apikey' && opts.envVarNames?.length\n ? `API key required: configure ${opts.envVarNames.join(', ')} in your project settings.`\n : 'Authentication required to use this tool.');\n super(message);\n this.name = 'AuthRequiredError';\n this.type = opts.type;\n this.envVarNames = opts.envVarNames;\n this.configUrl = opts.configUrl;\n }\n\n /** Serialize to the wire format MCP clients expect */\n toJSON(): AuthRequiredErrorData {\n return {\n error: 'auth_required',\n type: this.type,\n ...(this.envVarNames && { envVarNames: this.envVarNames }),\n configUrl: this.configUrl,\n message: this.message,\n };\n }\n}\n\n/**\n * Legacy tool protection format (pre-authorization field)\n * Used during migration period to support both old and new formats\n */\nexport type LegacyToolProtection = Omit<ToolProtection, 'authorization'> & {\n oauthProvider?: string;\n};\n\n/**\n * Union type for both legacy and new formats\n * Useful during migration period when accepting tool protection input\n */\nexport type ToolProtectionInput = ToolProtection | LegacyToolProtection;\n\n/**\n * Zod Schemas for Validation\n */\n\nexport const AuthorizationRequirementSchema = z.discriminatedUnion('type', [\n // Deprecated: 'oauth' is an alias for 'oauth2'\n // Will be removed in v2.0.0. Use 'oauth2' instead.\n z.object({\n type: z.literal('oauth'),\n provider: z.string(),\n requiredScopes: z.array(z.string()).optional(),\n }),\n // OAuth 2.0 provider authentication (canonical)\n z.object({\n type: z.literal('oauth2'),\n provider: z.string(),\n requiredScopes: z.array(z.string()).optional(),\n }),\n z.object({\n type: z.literal('password'),\n provider: z.string(),\n }),\n z.object({\n type: z.literal('mdl'),\n issuer: z.string(),\n credentialType: z.string().optional(),\n }),\n z.object({\n type: z.literal('idv'),\n provider: z.string(),\n verificationLevel: z.enum(['basic', 'enhanced', 'loa3']).optional(),\n }),\n z.object({\n type: z.literal('verifiable_credential'),\n credentialType: z.string(),\n issuer: z.string().optional(),\n }),\n // Deprecated: 'credential' is an alias for 'verifiable_credential'\n // Will be removed in v2.0.0. Use 'verifiable_credential' instead.\n z.object({\n type: z.literal('credential'),\n credentialType: z.string(),\n issuer: z.string().optional(),\n }),\n // WebAuthn/Passkey authentication\n z.object({\n type: z.literal('webauthn'),\n rpId: z.string().optional(),\n userVerification: z.enum(['required', 'preferred', 'discouraged']).optional(),\n }),\n // Sign-In with Ethereum (EIP-4361)\n z.object({\n type: z.literal('siwe'),\n chainId: z.number().optional(),\n domain: z.string().optional(),\n }),\n // API Key from per-user vault\n z.object({\n type: z.literal('apikey'),\n envVarNames: z.array(envVarNameSchema).min(1),\n headerMapping: z.record(z.string(), z.string()),\n }),\n z.object({\n type: z.literal('none'),\n }),\n]);\n\nexport const ToolProtectionSchema = z.object({\n requiresDelegation: z.boolean(),\n requiredScopes: z.array(z.string()),\n riskLevel: z.enum(['low', 'medium', 'high', 'critical']).optional(),\n oauthProvider: z.string().optional(), // Phase 2: Tool-specific OAuth provider\n authorization: AuthorizationRequirementSchema.optional(),\n});\n\nexport const ToolProtectionMapSchema = z.record(z.string(), ToolProtectionSchema);\n\nexport const ToolProtectionResponseSchema = z.object({\n toolProtections: ToolProtectionMapSchema,\n metadata: z\n .object({\n lastUpdated: z.string().optional(),\n version: z.string().optional(),\n source: z.string().optional(),\n })\n .optional(),\n});\n\nexport const DelegationRequiredErrorDataSchema = z.object({\n toolName: z.string(),\n requiredScopes: z.array(z.string()),\n consentUrl: z.string().optional(),\n authorizationUrl: z.string().optional(),\n reason: z.string().optional(),\n});\n\n/**\n * Type Guards\n */\n\nexport function isToolProtection(obj: unknown): obj is ToolProtection {\n return ToolProtectionSchema.safeParse(obj).success;\n}\n\nexport function isToolProtectionMap(obj: unknown): obj is ToolProtectionMap {\n return ToolProtectionMapSchema.safeParse(obj).success;\n}\n\nexport function isToolProtectionResponse(obj: unknown): obj is ToolProtectionResponse {\n return ToolProtectionResponseSchema.safeParse(obj).success;\n}\n\nexport function isDelegationRequiredErrorData(obj: unknown): obj is DelegationRequiredErrorData {\n return DelegationRequiredErrorDataSchema.safeParse(obj).success;\n}\n\n/**\n * Type guard to check if an object is a valid AuthorizationRequirement\n */\nexport function isAuthorizationRequirement(obj: unknown): obj is AuthorizationRequirement {\n return AuthorizationRequirementSchema.safeParse(obj).success;\n}\n\n/**\n * Type guard to check if a ToolProtection has OAuth authorization\n * Checks for both 'oauth' (deprecated) and 'oauth2' (canonical)\n */\nexport function hasOAuthAuthorization(\n protection: ToolProtection\n): protection is ToolProtection & { authorization: { type: 'oauth' | 'oauth2' } } {\n return protection.authorization?.type === 'oauth' || protection.authorization?.type === 'oauth2';\n}\n\n/**\n * Type guard to check if a ToolProtection has password authorization\n */\nexport function hasPasswordAuthorization(\n protection: ToolProtection\n): protection is ToolProtection & { authorization: { type: 'password' } } {\n return protection.authorization?.type === 'password';\n}\n\n/**\n * Type guard to check if a ToolProtection requires a Verifiable Credential\n *\n * Note: Also returns true for deprecated 'credential' type (normalized to verifiable_credential)\n */\nexport function hasVerifiableCredentialAuthorization(\n protection: ToolProtection\n): protection is ToolProtection & {\n authorization: { type: 'verifiable_credential' | 'credential' };\n} {\n return (\n protection.authorization?.type === 'verifiable_credential' ||\n protection.authorization?.type === 'credential'\n );\n}\n\n/**\n * Type guard to check if a ToolProtection has API Key (vault) authorization\n */\nexport function hasApiKeyAuthorization(\n protection: ToolProtection\n): protection is ToolProtection & { authorization: { type: 'apikey' } } {\n return protection.authorization?.type === 'apikey';\n}\n\n/**\n * Validation Functions\n */\n\nexport function validateToolProtection(obj: unknown): ToolProtection {\n return ToolProtectionSchema.parse(obj);\n}\n\nexport function validateToolProtectionMap(obj: unknown): ToolProtectionMap {\n return ToolProtectionMapSchema.parse(obj);\n}\n\nexport function validateToolProtectionResponse(obj: unknown): ToolProtectionResponse {\n return ToolProtectionResponseSchema.parse(obj);\n}\n\nexport function validateDelegationRequiredErrorData(obj: unknown): DelegationRequiredErrorData {\n return DelegationRequiredErrorDataSchema.parse(obj);\n}\n\n/**\n * Utility Functions\n */\n\n/**\n * Check if a tool requires delegation\n */\nexport function toolRequiresDelegation(toolName: string, protections: ToolProtectionMap): boolean {\n const protection = protections[toolName];\n return protection?.requiresDelegation ?? false;\n}\n\n/**\n * Get required scopes for a tool\n */\nexport function getToolRequiredScopes(toolName: string, protections: ToolProtectionMap): string[] {\n const protection = protections[toolName];\n return protection?.requiredScopes ?? [];\n}\n\n/**\n * Get risk level for a tool\n */\nexport function getToolRiskLevel(\n toolName: string,\n protections: ToolProtectionMap\n): ToolProtection['riskLevel'] | undefined {\n return protections[toolName]?.riskLevel;\n}\n\n/**\n * Create a delegation required error\n */\nexport function createDelegationRequiredError(\n toolName: string,\n requiredScopes: string[],\n consentUrl?: string\n): DelegationRequiredErrorData {\n return {\n toolName,\n requiredScopes,\n consentUrl,\n authorizationUrl: consentUrl, // Include both for compatibility\n };\n}\n\n/**\n * Normalize tool protection configuration\n * Migrates legacy oauthProvider field to authorization object\n *\n * - Migrates `oauthProvider` → `authorization: { type: 'oauth', provider: ... }`\n * - Ensures `authorization` field is present when `requiresDelegation=true`\n * - Returns fully normalized ToolProtection object\n *\n * @param raw - Raw tool protection data (may have legacy fields or be partial)\n * @returns Normalized ToolProtection object\n *\n * // TODO: Remove normalizeToolProtection() when all tools migrated\n */\nexport function normalizeToolProtection(\n raw: ToolProtection | PartialToolProtection\n): ToolProtection {\n // Ensure we have required fields (provide defaults for partial input)\n const normalized: ToolProtection = {\n requiresDelegation: raw.requiresDelegation ?? false,\n requiredScopes: raw.requiredScopes ?? [],\n ...(raw.riskLevel && { riskLevel: raw.riskLevel }),\n ...(raw.oauthProvider && { oauthProvider: raw.oauthProvider }),\n };\n\n // If authorization is already present, use it\n if (raw.authorization) {\n normalized.authorization = raw.authorization;\n return normalized;\n }\n\n // Migrate oauthProvider to authorization\n if (raw.oauthProvider) {\n normalized.authorization = {\n type: 'oauth',\n provider: raw.oauthProvider,\n };\n // Keep oauthProvider for backward compatibility\n return normalized;\n }\n\n // Default for requiresDelegation=true without specific auth: type='none' (consent only)\n // But ONLY if authorization is missing entirely\n if (normalized.requiresDelegation && !normalized.authorization && !normalized.oauthProvider) {\n // We don't automatically set type='none' here to allow\n // ProviderResolver to do its scope inference fallback logic.\n // The fallback logic will eventually be moved into an AuthorizationService.\n return normalized;\n }\n\n return normalized;\n}\n\n// =============================================================================\n// CONSENT PROVIDER TYPES - Records what auth method was USED (not required)\n// =============================================================================\n\n/** Consent provider types - stored in delegation metadata to track auth method used */\nexport const CONSENT_PROVIDER_TYPES = {\n /** Consent-only mode - no authentication, just clickwrap agreement */\n NONE: 'none',\n /** OAuth2 provider authentication */\n OAUTH2: 'oauth2',\n /** Password-based authentication (email/password, username/password) */\n PASSWORD: 'password',\n /** @deprecated Use PASSWORD instead. Alias for backward compatibility */\n CREDENTIAL: 'credential',\n /** Email magic link authentication */\n MAGIC_LINK: 'magic_link',\n /** One-time password (SMS/email code) */\n OTP: 'otp',\n} as const;\n\nexport type ConsentProviderType =\n (typeof CONSENT_PROVIDER_TYPES)[keyof typeof CONSENT_PROVIDER_TYPES];\n\n/**\n * Determine consent provider type based on available identity information\n *\n * This is the single source of truth for consent provider type determination.\n *\n * @param hasOAuthIdentity - Whether OAuth identity is available\n * @param isPasswordFlow - Whether this is a password/credential flow\n * @param isMagicLinkFlow - Whether this is a magic link flow\n * @param isOtpFlow - Whether this is an OTP flow\n * @returns The consent provider type\n */\nexport function determineConsentProviderType(\n hasOAuthIdentity: boolean,\n isPasswordFlow: boolean = false,\n isMagicLinkFlow: boolean = false,\n isOtpFlow: boolean = false\n): ConsentProviderType {\n if (isPasswordFlow) {\n return CONSENT_PROVIDER_TYPES.PASSWORD;\n }\n if (isMagicLinkFlow) {\n return CONSENT_PROVIDER_TYPES.MAGIC_LINK;\n }\n if (isOtpFlow) {\n return CONSENT_PROVIDER_TYPES.OTP;\n }\n if (hasOAuthIdentity) {\n return CONSENT_PROVIDER_TYPES.OAUTH2;\n }\n return CONSENT_PROVIDER_TYPES.NONE;\n}\n\n/**\n * Get a human-readable label for an authorization requirement type\n */\nexport function getAuthorizationTypeLabel(auth: AuthorizationRequirement): string {\n switch (auth.type) {\n case 'oauth':\n case 'oauth2':\n return auth.provider\n ? auth.provider.charAt(0).toUpperCase() + auth.provider.slice(1)\n : 'OAuth Provider';\n case 'password':\n return 'Password Authentication';\n case 'mdl':\n return \"Mobile Driver's License\";\n case 'idv':\n return 'Identity Verification';\n case 'verifiable_credential':\n return auth.credentialType || 'Verifiable Credential';\n case 'credential':\n // Deprecated: treat as verifiable_credential\n return auth.credentialType || 'Verifiable Credential';\n case 'webauthn':\n return 'Passkey / WebAuthn';\n case 'siwe':\n return 'Sign-In with Ethereum';\n case 'apikey':\n return 'API Key (Vault)';\n case 'none':\n return 'Consent Only';\n default: {\n // Closed union — this default is unreachable for well-typed input.\n return 'Unknown';\n }\n }\n}\n\n/**\n * Get a unique key for an authorization requirement (for React keys, caching, etc.)\n */\nexport function getAuthorizationTypeKey(auth: AuthorizationRequirement): string {\n switch (auth.type) {\n case 'oauth':\n // Keep original key format for backward compatibility with existing cache entries\n // Handle undefined provider gracefully (may come from loose API response types)\n return auth.provider ? `oauth:${auth.provider}` : 'oauth';\n case 'oauth2':\n return auth.provider ? `oauth2:${auth.provider}` : 'oauth2';\n case 'password':\n return auth.provider ? `password:${auth.provider}` : 'password';\n case 'mdl':\n // Keep trailing colon for backward compatibility with existing cache entries\n return `mdl:${auth.issuer || 'unknown'}:${auth.credentialType || ''}`;\n case 'idv':\n // Keep trailing colon for backward compatibility with existing cache entries\n return `idv:${auth.provider || 'unknown'}:${auth.verificationLevel || ''}`;\n case 'verifiable_credential':\n return `vc:${auth.issuer || 'any'}:${auth.credentialType || 'unknown'}`;\n case 'credential':\n // Deprecated: treat as verifiable_credential\n return `vc:${auth.issuer || 'any'}:${auth.credentialType || 'unknown'}`;\n case 'webauthn':\n return `webauthn:${auth.rpId || 'default'}`;\n case 'siwe':\n return `siwe:${auth.chainId || 1}:${auth.domain || 'any'}`;\n case 'apikey':\n return `apikey:${[...auth.envVarNames].sort().join(',')}`;\n case 'none':\n return 'none';\n default: {\n // Closed union — this default is unreachable for well-typed input.\n return 'unknown';\n }\n }\n}\n\n/**\n * Normalize authorization requirement type\n *\n * Normalizes deprecated types to their canonical equivalents:\n * - 'oauth' → 'oauth2'\n * - 'credential' → 'verifiable_credential'\n *\n * This function should be called at runtime boundaries when processing\n * authorization requirements.\n *\n * @param auth - Authorization requirement (may contain deprecated types)\n * @param options - Normalization options\n * @returns Normalized authorization requirement\n *\n * @example\n * ```typescript\n * const normalized = normalizeAuthorizationType(\n * { type: 'oauth', provider: 'github' },\n * { warn: true }\n * );\n * // Returns: { type: 'oauth2', provider: 'github' }\n * // Logs: DEPRECATION warning\n * ```\n */\nexport function normalizeAuthorizationType(\n auth: AuthorizationRequirement,\n options: { warn?: boolean; logger?: (message: string) => void } = {}\n): AuthorizationRequirement {\n const { warn = true, logger = console.warn } = options;\n\n // Normalize 'oauth' to 'oauth2'\n if (auth.type === 'oauth') {\n if (warn) {\n logger(\n `DEPRECATION: Authorization type 'oauth' is deprecated and will be removed in v2.0.0. ` +\n `Please update to 'oauth2'. ` +\n `See https://github.com/modelcontextprotocol-identity/xmcp-i/blob/main/docs/migrations/oauth-to-oauth2.md`\n );\n }\n\n // Normalize to oauth2\n const normalized = {\n type: 'oauth2' as const,\n provider: auth.provider,\n ...(auth.requiredScopes !== undefined && { requiredScopes: auth.requiredScopes }),\n };\n\n return normalized;\n }\n\n // Normalize 'credential' to 'verifiable_credential'\n if (auth.type === 'credential') {\n if (warn) {\n logger(\n `DEPRECATION: Authorization type 'credential' is deprecated and will be removed in v2.0.0. ` +\n `Please update to 'verifiable_credential'. ` +\n `See https://github.com/modelcontextprotocol-identity/xmcp-i/blob/main/docs/migrations/credential-to-verifiable_credential.md`\n );\n }\n\n // Normalize to verifiable_credential\n const normalized = {\n type: 'verifiable_credential' as const,\n credentialType: auth.credentialType,\n ...(auth.issuer !== undefined && { issuer: auth.issuer }),\n };\n\n return normalized;\n }\n\n // No normalization needed\n return auth;\n}\n"],"mappings":"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"}
@@ -0,0 +1,383 @@
1
+ {
2
+ "description": "Cloudflare bot-score alias rule shared by the engine (stages/scoring.rs signals_from_details) and buildVerdictEvidence (core/verdict-evidence.ts). A scanner_misclassification_hint whose metadata.cf_bot_score is a non-negative integer equal to a transport.cloudflare_bot_management signal's contributes nothing to the Noisy-OR combination; both signals stay in the published list. expectedConfidence is the combiner output on the 0-100 scale including the 0.10 prior.",
3
+ "aliasSource": "scanner_misclassification_hint",
4
+ "rootSource": "transport.cloudflare_bot_management",
5
+ "cases": [
6
+ {
7
+ "label": "same score",
8
+ "droppedAliasCount": 1,
9
+ "expectedConfidence": 42.4,
10
+ "signals": [
11
+ {
12
+ "signalType": "network",
13
+ "confidence": 90,
14
+ "weight": 0.4,
15
+ "source": "scanner_misclassification_hint",
16
+ "explanation": "",
17
+ "metadata": {
18
+ "cf_bot_score": 10
19
+ }
20
+ },
21
+ {
22
+ "signalType": "network",
23
+ "confidence": 90,
24
+ "weight": 0.4,
25
+ "source": "transport.cloudflare_bot_management",
26
+ "explanation": "",
27
+ "metadata": {
28
+ "cf_bot_score": 10
29
+ }
30
+ }
31
+ ]
32
+ },
33
+ {
34
+ "label": "different score",
35
+ "droppedAliasCount": 0,
36
+ "expectedConfidence": 63.136,
37
+ "signals": [
38
+ {
39
+ "signalType": "network",
40
+ "confidence": 90,
41
+ "weight": 0.4,
42
+ "source": "scanner_misclassification_hint",
43
+ "explanation": "",
44
+ "metadata": {
45
+ "cf_bot_score": 10
46
+ }
47
+ },
48
+ {
49
+ "signalType": "network",
50
+ "confidence": 90,
51
+ "weight": 0.4,
52
+ "source": "transport.cloudflare_bot_management",
53
+ "explanation": "",
54
+ "metadata": {
55
+ "cf_bot_score": 9
56
+ }
57
+ }
58
+ ]
59
+ },
60
+ {
61
+ "label": "other root source",
62
+ "droppedAliasCount": 0,
63
+ "expectedConfidence": 63.136,
64
+ "signals": [
65
+ {
66
+ "signalType": "network",
67
+ "confidence": 90,
68
+ "weight": 0.4,
69
+ "source": "scanner_misclassification_hint",
70
+ "explanation": "",
71
+ "metadata": {
72
+ "cf_bot_score": 10
73
+ }
74
+ },
75
+ {
76
+ "signalType": "network",
77
+ "confidence": 90,
78
+ "weight": 0.4,
79
+ "source": "ip_intelligence",
80
+ "explanation": "",
81
+ "metadata": {
82
+ "cf_bot_score": 10
83
+ }
84
+ }
85
+ ]
86
+ },
87
+ {
88
+ "label": "alias score absent",
89
+ "droppedAliasCount": 0,
90
+ "expectedConfidence": 63.136,
91
+ "signals": [
92
+ {
93
+ "signalType": "network",
94
+ "confidence": 90,
95
+ "weight": 0.4,
96
+ "source": "scanner_misclassification_hint",
97
+ "explanation": ""
98
+ },
99
+ {
100
+ "signalType": "network",
101
+ "confidence": 90,
102
+ "weight": 0.4,
103
+ "source": "transport.cloudflare_bot_management",
104
+ "explanation": "",
105
+ "metadata": {
106
+ "cf_bot_score": 10
107
+ }
108
+ }
109
+ ]
110
+ },
111
+ {
112
+ "label": "root score absent",
113
+ "droppedAliasCount": 0,
114
+ "expectedConfidence": 63.136,
115
+ "signals": [
116
+ {
117
+ "signalType": "network",
118
+ "confidence": 90,
119
+ "weight": 0.4,
120
+ "source": "scanner_misclassification_hint",
121
+ "explanation": "",
122
+ "metadata": {
123
+ "cf_bot_score": 10
124
+ }
125
+ },
126
+ {
127
+ "signalType": "network",
128
+ "confidence": 90,
129
+ "weight": 0.4,
130
+ "source": "transport.cloudflare_bot_management",
131
+ "explanation": ""
132
+ }
133
+ ]
134
+ },
135
+ {
136
+ "label": "both scores absent",
137
+ "droppedAliasCount": 0,
138
+ "expectedConfidence": 63.136,
139
+ "signals": [
140
+ {
141
+ "signalType": "network",
142
+ "confidence": 90,
143
+ "weight": 0.4,
144
+ "source": "scanner_misclassification_hint",
145
+ "explanation": ""
146
+ },
147
+ {
148
+ "signalType": "network",
149
+ "confidence": 90,
150
+ "weight": 0.4,
151
+ "source": "transport.cloudflare_bot_management",
152
+ "explanation": ""
153
+ }
154
+ ]
155
+ },
156
+ {
157
+ "label": "null scores",
158
+ "droppedAliasCount": 0,
159
+ "expectedConfidence": 63.136,
160
+ "signals": [
161
+ {
162
+ "signalType": "network",
163
+ "confidence": 90,
164
+ "weight": 0.4,
165
+ "source": "scanner_misclassification_hint",
166
+ "explanation": "",
167
+ "metadata": {
168
+ "cf_bot_score": null
169
+ }
170
+ },
171
+ {
172
+ "signalType": "network",
173
+ "confidence": 90,
174
+ "weight": 0.4,
175
+ "source": "transport.cloudflare_bot_management",
176
+ "explanation": "",
177
+ "metadata": {
178
+ "cf_bot_score": null
179
+ }
180
+ }
181
+ ]
182
+ },
183
+ {
184
+ "label": "string scores",
185
+ "droppedAliasCount": 0,
186
+ "expectedConfidence": 63.136,
187
+ "signals": [
188
+ {
189
+ "signalType": "network",
190
+ "confidence": 90,
191
+ "weight": 0.4,
192
+ "source": "scanner_misclassification_hint",
193
+ "explanation": "",
194
+ "metadata": {
195
+ "cf_bot_score": "10"
196
+ }
197
+ },
198
+ {
199
+ "signalType": "network",
200
+ "confidence": 90,
201
+ "weight": 0.4,
202
+ "source": "transport.cloudflare_bot_management",
203
+ "explanation": "",
204
+ "metadata": {
205
+ "cf_bot_score": "10"
206
+ }
207
+ }
208
+ ]
209
+ },
210
+ {
211
+ "label": "root score null",
212
+ "droppedAliasCount": 0,
213
+ "expectedConfidence": 63.136,
214
+ "signals": [
215
+ {
216
+ "signalType": "network",
217
+ "confidence": 90,
218
+ "weight": 0.4,
219
+ "source": "scanner_misclassification_hint",
220
+ "explanation": "",
221
+ "metadata": {
222
+ "cf_bot_score": 10
223
+ }
224
+ },
225
+ {
226
+ "signalType": "network",
227
+ "confidence": 90,
228
+ "weight": 0.4,
229
+ "source": "transport.cloudflare_bot_management",
230
+ "explanation": "",
231
+ "metadata": {
232
+ "cf_bot_score": null
233
+ }
234
+ }
235
+ ]
236
+ },
237
+ {
238
+ "label": "negative scores",
239
+ "droppedAliasCount": 0,
240
+ "expectedConfidence": 63.136,
241
+ "signals": [
242
+ {
243
+ "signalType": "network",
244
+ "confidence": 90,
245
+ "weight": 0.4,
246
+ "source": "scanner_misclassification_hint",
247
+ "explanation": "",
248
+ "metadata": {
249
+ "cf_bot_score": -1
250
+ }
251
+ },
252
+ {
253
+ "signalType": "network",
254
+ "confidence": 90,
255
+ "weight": 0.4,
256
+ "source": "transport.cloudflare_bot_management",
257
+ "explanation": "",
258
+ "metadata": {
259
+ "cf_bot_score": -1
260
+ }
261
+ }
262
+ ]
263
+ },
264
+ {
265
+ "label": "fractional scores",
266
+ "droppedAliasCount": 0,
267
+ "expectedConfidence": 63.136,
268
+ "signals": [
269
+ {
270
+ "signalType": "network",
271
+ "confidence": 90,
272
+ "weight": 0.4,
273
+ "source": "scanner_misclassification_hint",
274
+ "explanation": "",
275
+ "metadata": {
276
+ "cf_bot_score": 10.5
277
+ }
278
+ },
279
+ {
280
+ "signalType": "network",
281
+ "confidence": 90,
282
+ "weight": 0.4,
283
+ "source": "transport.cloudflare_bot_management",
284
+ "explanation": "",
285
+ "metadata": {
286
+ "cf_bot_score": 10.5
287
+ }
288
+ }
289
+ ]
290
+ },
291
+ {
292
+ "label": "alias alone",
293
+ "droppedAliasCount": 0,
294
+ "expectedConfidence": 42.4,
295
+ "signals": [
296
+ {
297
+ "signalType": "network",
298
+ "confidence": 90,
299
+ "weight": 0.4,
300
+ "source": "scanner_misclassification_hint",
301
+ "explanation": "",
302
+ "metadata": {
303
+ "cf_bot_score": 10
304
+ }
305
+ }
306
+ ]
307
+ },
308
+ {
309
+ "label": "two aliases one root",
310
+ "droppedAliasCount": 2,
311
+ "expectedConfidence": 42.4,
312
+ "signals": [
313
+ {
314
+ "signalType": "network",
315
+ "confidence": 90,
316
+ "weight": 0.4,
317
+ "source": "scanner_misclassification_hint",
318
+ "explanation": "",
319
+ "metadata": {
320
+ "cf_bot_score": 10
321
+ }
322
+ },
323
+ {
324
+ "signalType": "network",
325
+ "confidence": 90,
326
+ "weight": 0.4,
327
+ "source": "scanner_misclassification_hint",
328
+ "explanation": "",
329
+ "metadata": {
330
+ "cf_bot_score": 10
331
+ }
332
+ },
333
+ {
334
+ "signalType": "network",
335
+ "confidence": 90,
336
+ "weight": 0.4,
337
+ "source": "transport.cloudflare_bot_management",
338
+ "explanation": "",
339
+ "metadata": {
340
+ "cf_bot_score": 10
341
+ }
342
+ }
343
+ ]
344
+ },
345
+ {
346
+ "label": "independent evidence still accumulates",
347
+ "droppedAliasCount": 1,
348
+ "expectedConfidence": 65.44,
349
+ "signals": [
350
+ {
351
+ "signalType": "network",
352
+ "confidence": 90,
353
+ "weight": 0.4,
354
+ "source": "scanner_misclassification_hint",
355
+ "explanation": "",
356
+ "metadata": {
357
+ "cf_bot_score": 10
358
+ }
359
+ },
360
+ {
361
+ "signalType": "network",
362
+ "confidence": 90,
363
+ "weight": 0.4,
364
+ "source": "transport.cloudflare_bot_management",
365
+ "explanation": "",
366
+ "metadata": {
367
+ "cf_bot_score": 10
368
+ }
369
+ },
370
+ {
371
+ "signalType": "fingerprint",
372
+ "confidence": 80,
373
+ "weight": 0.5,
374
+ "source": "ua_tls_mismatch",
375
+ "explanation": "",
376
+ "metadata": {
377
+ "cf_bot_score": null
378
+ }
379
+ }
380
+ ]
381
+ }
382
+ ]
383
+ }
@@ -14,7 +14,7 @@
14
14
  },
15
15
  "signal": {
16
16
  "detection/ua-pattern-match": "a signals[] entry with source === 'user_agent_pattern'",
17
- "detection/header-heuristic": "source === 'header_heuristic'",
17
+ "detection/header-heuristic": "source === 'header_heuristic' or a header contradiction rule id: 'page_load_on_json_post', 'client_hint_contradiction', 'browser_headers_without_user_agent', 'upgrade_insecure_requests_on_json_post', 'request_origin_mismatch', 'sec_fetch_user_on_background_request', 'grease_brand_mismatch', 'compression_headers_contradict_browser', 'accept_language_format_unusual'",
18
18
  "detection/ip-heuristic": "source === 'ip_heuristic'",
19
19
  "detection/vendor-ip-corroborated": "source === 'vendor_ip_feed'",
20
20
  "detection/ip-intelligence-proxy-signal": "source === 'ip_intelligence'",
@@ -30,6 +30,8 @@
30
30
  "detection/a2a-card-signal": "source === 'a2a_agent_card'",
31
31
  "detection/scanner-misclassification-hint-signal": "source === 'scanner_misclassification_hint'",
32
32
  "detection/client-headless-escalation-signal": "source === 'client_headless_escalation'",
33
+ "detection/automation-default-viewport": "source === 'client_viewport_tell'",
34
+ "detection/client-interaction-human": "source === 'client_interaction'",
33
35
  "detection/cloudflare-bot-management-signal": "source === 'transport.cloudflare_bot_management'",
34
36
  "detection/session-velocity-signal": "source === 'session_velocity'"
35
37
  },
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "$fixture": "detection/signal-exposure-example",
3
- "$spec": "KYA-1107: one full POST /api/v1/enforce response showing the always-on signal exposure (the Adobe Golden Snapshot example). Captured verbatim from the route-level test (signal-exposure.test.ts) against the deterministic GPTBot engine mock, whose signals mirror the engine's real emission shapes (api.rs signal_detail / vendor_feed_signal_detail).",
3
+ "$spec": "KYA-1107: one full POST /api/v1/enforce response showing the always-on signal exposure. Captured verbatim from the route-level test (signal-exposure.test.ts) against the deterministic GPTBot engine mock, whose signals mirror the engine's real emission shapes (api.rs signal_detail / vendor_feed_signal_detail).",
4
4
  "description": "The detection object's signals/reasonCodes/confidenceLevel/isAiCrawler fields are the exposure block carried on every detection payload; __tests__/signal-exposure.test.ts parses them against DetectionSignalExposureSchema, and generate-signal-exposure-docs.ts embeds this response verbatim in the generated reference, so example, schema, and docs stay in lockstep.",
5
5
  "response": {
6
6
  "success": true,