@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
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.mjs","names":[],"sources":["../../src/tool-protection/index.ts"],"sourcesContent":["/**\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\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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"}
@@ -0,0 +1,142 @@
1
+ [
2
+ {
3
+ "name": "cloudflare: score 0 means not-computed, never a real score",
4
+ "cloudflareRequestCf": { "botManagement": { "score": 0, "verifiedBot": false } },
5
+ "policy": { "platform": "cloudflare" },
6
+ "expected": { "verifiedBot": false, "source": "cloudflare-bot-management" }
7
+ },
8
+ {
9
+ "name": "cloudflare: score 1 is the minimum real value",
10
+ "cloudflareRequestCf": { "botManagement": { "score": 1 } },
11
+ "policy": { "platform": "cloudflare" },
12
+ "expected": { "score": 1, "source": "cloudflare-bot-management" }
13
+ },
14
+ {
15
+ "name": "cloudflare: score 99 is the maximum real value",
16
+ "cloudflareRequestCf": { "botManagement": { "score": 99 } },
17
+ "policy": { "platform": "cloudflare" },
18
+ "expected": { "score": 99, "source": "cloudflare-bot-management" }
19
+ },
20
+ {
21
+ "name": "cloudflare: missing score stays absent",
22
+ "cloudflareRequestCf": { "botManagement": { "verifiedBot": true } },
23
+ "policy": { "platform": "cloudflare" },
24
+ "expected": { "verifiedBot": true, "source": "cloudflare-bot-management" }
25
+ },
26
+ {
27
+ "name": "cloudflare: out-of-range score (>99) normalizes to absent, not clamped",
28
+ "cloudflareRequestCf": { "botManagement": { "score": 150 } },
29
+ "policy": { "platform": "cloudflare" },
30
+ "expected": { "source": "cloudflare-bot-management" }
31
+ },
32
+ {
33
+ "name": "cloudflare: negative score normalizes to absent",
34
+ "cloudflareRequestCf": { "botManagement": { "score": -1 } },
35
+ "policy": { "platform": "cloudflare" },
36
+ "expected": { "source": "cloudflare-bot-management" }
37
+ },
38
+ {
39
+ "name": "cloudflare: non-integer score normalizes to absent (defensive against malformed input)",
40
+ "cloudflareRequestCf": { "botManagement": { "score": 42.5 } },
41
+ "policy": { "platform": "cloudflare" },
42
+ "expected": { "source": "cloudflare-bot-management" }
43
+ },
44
+ {
45
+ "name": "cloudflare: verifiedBot true carried through",
46
+ "cloudflareRequestCf": { "botManagement": { "score": 5, "verifiedBot": true } },
47
+ "policy": { "platform": "cloudflare" },
48
+ "expected": { "score": 5, "verifiedBot": true, "source": "cloudflare-bot-management" }
49
+ },
50
+ {
51
+ "name": "cloudflare: ja4 carried through",
52
+ "cloudflareRequestCf": { "botManagement": { "ja4": "t13d1516h2_8daaf6152771_02713d6af862" } },
53
+ "policy": { "platform": "cloudflare" },
54
+ "expected": {
55
+ "ja4": "t13d1516h2_8daaf6152771_02713d6af862",
56
+ "source": "cloudflare-bot-management"
57
+ }
58
+ },
59
+ {
60
+ "name": "cloudflare: empty-string ja4 normalizes to absent",
61
+ "cloudflareRequestCf": { "botManagement": { "ja4": "" } },
62
+ "policy": { "platform": "cloudflare" },
63
+ "expected": { "source": "cloudflare-bot-management" }
64
+ },
65
+ {
66
+ "name": "cloudflare: asn and asOrganization are top-level request.cf fields, not nested in botManagement",
67
+ "cloudflareRequestCf": { "asn": 13335, "asOrganization": "Cloudflare, Inc." },
68
+ "policy": { "platform": "cloudflare" },
69
+ "expected": {
70
+ "asn": 13335,
71
+ "asOrganization": "Cloudflare, Inc.",
72
+ "source": "cloudflare-bot-management"
73
+ }
74
+ },
75
+ {
76
+ "name": "cloudflare: non-positive asn normalizes to absent",
77
+ "cloudflareRequestCf": { "asn": 0 },
78
+ "policy": { "platform": "cloudflare" },
79
+ "expected": { "source": "cloudflare-bot-management" }
80
+ },
81
+ {
82
+ "name": "cloudflare: full request.cf resolves every field together",
83
+ "cloudflareRequestCf": {
84
+ "botManagement": {
85
+ "score": 72,
86
+ "verifiedBot": false,
87
+ "ja4": "t13d1516h2_8daaf6152771_02713d6af862"
88
+ },
89
+ "asn": 15169,
90
+ "asOrganization": "Google LLC"
91
+ },
92
+ "policy": { "platform": "cloudflare" },
93
+ "expected": {
94
+ "score": 72,
95
+ "verifiedBot": false,
96
+ "ja4": "t13d1516h2_8daaf6152771_02713d6af862",
97
+ "asn": 15169,
98
+ "asOrganization": "Google LLC",
99
+ "source": "cloudflare-bot-management"
100
+ }
101
+ },
102
+ {
103
+ "name": "cloudflare: absent request.cf (Bot Management not enabled on zone) resolves cleanly absent",
104
+ "policy": { "platform": "cloudflare" },
105
+ "expected": { "source": "none" }
106
+ },
107
+ {
108
+ "name": "cloudflare: null request.cf resolves cleanly absent",
109
+ "cloudflareRequestCf": null,
110
+ "policy": { "platform": "cloudflare" },
111
+ "expected": { "source": "none" }
112
+ },
113
+ {
114
+ "name": "non-cloudflare platforms (vercel/trusted-proxy/direct): no bot-management surface, always resolves absent even when a cloudflare candidate is present",
115
+ "cloudflareRequestCf": { "botManagement": { "score": 5 } },
116
+ "policy": { "platform": "vercel" },
117
+ "expected": { "source": "none" }
118
+ },
119
+ {
120
+ "name": "explicit: trusted explicit override wins over policy resolution",
121
+ "cloudflareRequestCf": { "botManagement": { "score": 5 } },
122
+ "explicitBotSignals": { "score": 88, "verifiedBot": true },
123
+ "explicitBotSignalsTrusted": true,
124
+ "policy": { "platform": "cloudflare" },
125
+ "expected": { "score": 88, "verifiedBot": true, "source": "explicit" }
126
+ },
127
+ {
128
+ "name": "explicit: untrusted explicit override is ignored, falls through to policy",
129
+ "cloudflareRequestCf": { "botManagement": { "score": 5 } },
130
+ "explicitBotSignals": { "score": 88 },
131
+ "explicitBotSignalsTrusted": false,
132
+ "policy": { "platform": "cloudflare" },
133
+ "expected": { "score": 5, "source": "cloudflare-bot-management" }
134
+ },
135
+ {
136
+ "name": "explicit: score 0 in an explicit override also normalizes to absent",
137
+ "explicitBotSignals": { "score": 0, "verifiedBot": true },
138
+ "explicitBotSignalsTrusted": true,
139
+ "policy": { "platform": "cloudflare" },
140
+ "expected": { "verifiedBot": true, "source": "explicit" }
141
+ }
142
+ ]
@@ -0,0 +1,421 @@
1
+ [
2
+ {
3
+ "name": "missing iss",
4
+ "field": "iss",
5
+ "valid": false,
6
+ "remove": true
7
+ },
8
+ {
9
+ "name": "missing aud",
10
+ "field": "aud",
11
+ "valid": false,
12
+ "remove": true
13
+ },
14
+ {
15
+ "name": "missing v",
16
+ "field": "v",
17
+ "valid": false,
18
+ "remove": true
19
+ },
20
+ {
21
+ "name": "missing project_id",
22
+ "field": "project_id",
23
+ "valid": false,
24
+ "remove": true
25
+ },
26
+ {
27
+ "name": "missing origin",
28
+ "field": "origin",
29
+ "valid": false,
30
+ "remove": true
31
+ },
32
+ {
33
+ "name": "missing session_id",
34
+ "field": "session_id",
35
+ "valid": false,
36
+ "remove": true
37
+ },
38
+ {
39
+ "name": "missing binding",
40
+ "field": "binding",
41
+ "valid": false,
42
+ "remove": true
43
+ },
44
+ {
45
+ "name": "missing verdict",
46
+ "field": "verdict",
47
+ "valid": false,
48
+ "remove": true
49
+ },
50
+ {
51
+ "name": "missing score",
52
+ "field": "score",
53
+ "valid": false,
54
+ "remove": true
55
+ },
56
+ {
57
+ "name": "missing scorer_version",
58
+ "field": "scorer_version",
59
+ "valid": false,
60
+ "remove": true
61
+ },
62
+ {
63
+ "name": "missing reasons",
64
+ "field": "reasons",
65
+ "valid": false,
66
+ "remove": true
67
+ },
68
+ {
69
+ "name": "missing iat",
70
+ "field": "iat",
71
+ "valid": false,
72
+ "remove": true
73
+ },
74
+ {
75
+ "name": "missing exp",
76
+ "field": "exp",
77
+ "valid": false,
78
+ "remove": true
79
+ },
80
+ {
81
+ "name": "numeric iss",
82
+ "field": "iss",
83
+ "valid": false,
84
+ "value": 42
85
+ },
86
+ {
87
+ "name": "numeric aud",
88
+ "field": "aud",
89
+ "valid": false,
90
+ "value": 42
91
+ },
92
+ {
93
+ "name": "numeric project_id",
94
+ "field": "project_id",
95
+ "valid": false,
96
+ "value": 42
97
+ },
98
+ {
99
+ "name": "numeric origin",
100
+ "field": "origin",
101
+ "valid": false,
102
+ "value": 42
103
+ },
104
+ {
105
+ "name": "numeric session_id",
106
+ "field": "session_id",
107
+ "valid": false,
108
+ "value": 42
109
+ },
110
+ {
111
+ "name": "numeric binding",
112
+ "field": "binding",
113
+ "valid": false,
114
+ "value": 42
115
+ },
116
+ {
117
+ "name": "numeric verdict",
118
+ "field": "verdict",
119
+ "valid": false,
120
+ "value": 42
121
+ },
122
+ {
123
+ "name": "wrong issuer",
124
+ "field": "iss",
125
+ "valid": false,
126
+ "value": "other-issuer"
127
+ },
128
+ {
129
+ "name": "wrong audience",
130
+ "field": "aud",
131
+ "valid": false,
132
+ "value": "https://other.test"
133
+ },
134
+ {
135
+ "name": "audience list containing origin",
136
+ "field": "aud",
137
+ "valid": true,
138
+ "value": ["https://other.test", "https://example.test"]
139
+ },
140
+ {
141
+ "name": "audience list without origin",
142
+ "field": "aud",
143
+ "valid": false,
144
+ "value": ["https://other.test"]
145
+ },
146
+ {
147
+ "name": "v 1",
148
+ "field": "v",
149
+ "valid": false,
150
+ "value": "1"
151
+ },
152
+ {
153
+ "name": "v 1.1",
154
+ "field": "v",
155
+ "valid": false,
156
+ "value": 1.1
157
+ },
158
+ {
159
+ "name": "session_id session",
160
+ "field": "session_id",
161
+ "valid": false,
162
+ "value": "session"
163
+ },
164
+ {
165
+ "name": "session_id 00000000-0000-0000-0000-000000",
166
+ "field": "session_id",
167
+ "valid": true,
168
+ "value": "00000000-0000-0000-0000-000000000000"
169
+ },
170
+ {
171
+ "name": "binding AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
172
+ "field": "binding",
173
+ "valid": false,
174
+ "value": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
175
+ },
176
+ {
177
+ "name": "verdict trusted",
178
+ "field": "verdict",
179
+ "valid": false,
180
+ "value": "trusted"
181
+ },
182
+ {
183
+ "name": "score 0.9",
184
+ "field": "score",
185
+ "valid": false,
186
+ "value": "0.9"
187
+ },
188
+ {
189
+ "name": "score -0.1",
190
+ "field": "score",
191
+ "valid": false,
192
+ "value": -0.1
193
+ },
194
+ {
195
+ "name": "score 1.1",
196
+ "field": "score",
197
+ "valid": false,
198
+ "value": 1.1
199
+ },
200
+ {
201
+ "name": "scorer_version 0",
202
+ "field": "scorer_version",
203
+ "valid": false,
204
+ "value": 0
205
+ },
206
+ {
207
+ "name": "scorer_version 1.5",
208
+ "field": "scorer_version",
209
+ "valid": false,
210
+ "value": 1.5
211
+ },
212
+ {
213
+ "name": "scorer_version 1",
214
+ "field": "scorer_version",
215
+ "valid": false,
216
+ "value": "1"
217
+ },
218
+ {
219
+ "name": "reasons {}",
220
+ "field": "reasons",
221
+ "valid": false,
222
+ "value": {}
223
+ },
224
+ {
225
+ "name": "reasons [1]",
226
+ "field": "reasons",
227
+ "valid": false,
228
+ "value": [1]
229
+ },
230
+ {
231
+ "name": "reasons ['xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
232
+ "field": "reasons",
233
+ "valid": false,
234
+ "value": [
235
+ "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
236
+ ]
237
+ },
238
+ {
239
+ "name": "reasons ['a', 'a', 'a', 'a', 'a', 'a',",
240
+ "field": "reasons",
241
+ "valid": false,
242
+ "value": ["a", "a", "a", "a", "a", "a", "a", "a", "a"]
243
+ },
244
+ {
245
+ "name": "iat 1700000000",
246
+ "field": "iat",
247
+ "valid": false,
248
+ "value": "1700000000"
249
+ },
250
+ {
251
+ "name": "iat 1700000000.5",
252
+ "field": "iat",
253
+ "valid": false,
254
+ "value": 1700000000.5
255
+ },
256
+ {
257
+ "name": "iat -1",
258
+ "field": "iat",
259
+ "valid": false,
260
+ "value": -1
261
+ },
262
+ {
263
+ "name": "exp 1700000060",
264
+ "field": "exp",
265
+ "valid": false,
266
+ "value": "1700000060"
267
+ },
268
+ {
269
+ "name": "exp 1700000060.5",
270
+ "field": "exp",
271
+ "valid": false,
272
+ "value": 1700000060.5
273
+ },
274
+ {
275
+ "name": "exp 0",
276
+ "field": "exp",
277
+ "valid": false,
278
+ "value": 0
279
+ },
280
+ {
281
+ "name": "nbf 1700000001",
282
+ "field": "nbf",
283
+ "valid": false,
284
+ "value": 1700000001
285
+ },
286
+ {
287
+ "name": "nbf 1700000000",
288
+ "field": "nbf",
289
+ "valid": false,
290
+ "value": "1700000000"
291
+ },
292
+ {
293
+ "name": "valid score None",
294
+ "field": "score",
295
+ "valid": true,
296
+ "value": null
297
+ },
298
+ {
299
+ "name": "valid score 0",
300
+ "field": "score",
301
+ "valid": true,
302
+ "value": 0
303
+ },
304
+ {
305
+ "name": "valid score 1",
306
+ "field": "score",
307
+ "valid": true,
308
+ "value": 1
309
+ },
310
+ {
311
+ "name": "valid reasons []",
312
+ "field": "reasons",
313
+ "valid": true,
314
+ "value": []
315
+ },
316
+ {
317
+ "name": "valid reasons ['xxxxxxxxxxxxx",
318
+ "field": "reasons",
319
+ "valid": true,
320
+ "value": [
321
+ "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
322
+ "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
323
+ "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
324
+ "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
325
+ "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
326
+ "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
327
+ "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
328
+ "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
329
+ ]
330
+ },
331
+ {
332
+ "name": "valid verdict human",
333
+ "field": "verdict",
334
+ "valid": true,
335
+ "value": "human"
336
+ },
337
+ {
338
+ "name": "valid verdict insufficient",
339
+ "field": "verdict",
340
+ "valid": true,
341
+ "value": "insufficient"
342
+ },
343
+ {
344
+ "name": "valid iat 1700000005",
345
+ "field": "iat",
346
+ "valid": true,
347
+ "value": 1700000005
348
+ },
349
+ {
350
+ "name": "valid exp 1700000120",
351
+ "field": "exp",
352
+ "valid": true,
353
+ "value": 1700000120
354
+ },
355
+ {
356
+ "name": "valid nbf 1700000000",
357
+ "field": "nbf",
358
+ "valid": true,
359
+ "value": 1700000000
360
+ },
361
+ {
362
+ "name": "iat beyond skew",
363
+ "field": "iat",
364
+ "valid": false,
365
+ "value": 1700000006
366
+ },
367
+ {
368
+ "name": "expired",
369
+ "field": "exp",
370
+ "valid": false,
371
+ "value": 1700000000
372
+ },
373
+ {
374
+ "name": "oversized lifetime",
375
+ "field": "exp",
376
+ "valid": false,
377
+ "value": 1700000121
378
+ },
379
+ {
380
+ "name": "scorer version maximum",
381
+ "field": "scorer_version",
382
+ "value": 2147483647,
383
+ "valid": true
384
+ },
385
+ {
386
+ "name": "scorer version overflow",
387
+ "field": "scorer_version",
388
+ "value": 2147483648,
389
+ "valid": false
390
+ },
391
+ {
392
+ "name": "huge timestamp",
393
+ "field": "iat",
394
+ "value": 100000000000000000000000000,
395
+ "valid": false
396
+ },
397
+ {
398
+ "name": "unsafe timestamp",
399
+ "field": "iat",
400
+ "value": 9007199254740992,
401
+ "valid": false
402
+ },
403
+ {
404
+ "name": "numeric mixed audience",
405
+ "field": "aud",
406
+ "value": ["https://example.test", 1],
407
+ "valid": false
408
+ },
409
+ {
410
+ "name": "empty project",
411
+ "field": "project_id",
412
+ "value": "",
413
+ "valid": false
414
+ },
415
+ {
416
+ "name": "oversized project",
417
+ "field": "project_id",
418
+ "value": "ppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppppp",
419
+ "valid": false
420
+ }
421
+ ]