@kya-os/mcp 1.3.2 → 1.4.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 (88) hide show
  1. package/CHANGELOG.md +198 -1
  2. package/dist/delegation/index.d.ts +2 -1
  3. package/dist/delegation/index.d.ts.map +1 -1
  4. package/dist/delegation/index.js +2 -1
  5. package/dist/delegation/index.js.map +1 -1
  6. package/dist/delegation/scope-matcher.d.ts +35 -0
  7. package/dist/delegation/scope-matcher.d.ts.map +1 -0
  8. package/dist/delegation/scope-matcher.js +83 -0
  9. package/dist/delegation/scope-matcher.js.map +1 -0
  10. package/dist/delegation/vc-verifier.d.ts +1 -11
  11. package/dist/delegation/vc-verifier.d.ts.map +1 -1
  12. package/dist/delegation/vc-verifier.js +5 -19
  13. package/dist/delegation/vc-verifier.js.map +1 -1
  14. package/dist/errors.d.ts +1 -0
  15. package/dist/errors.d.ts.map +1 -1
  16. package/dist/errors.js +1 -0
  17. package/dist/errors.js.map +1 -1
  18. package/dist/index.d.ts +8 -3
  19. package/dist/index.d.ts.map +1 -1
  20. package/dist/index.js +9 -3
  21. package/dist/index.js.map +1 -1
  22. package/dist/middleware/with-kya-os.d.ts +88 -31
  23. package/dist/middleware/with-kya-os.d.ts.map +1 -1
  24. package/dist/middleware/with-kya-os.js +327 -88
  25. package/dist/middleware/with-kya-os.js.map +1 -1
  26. package/dist/policy/approval.d.ts +34 -0
  27. package/dist/policy/approval.d.ts.map +1 -0
  28. package/dist/policy/approval.js +29 -0
  29. package/dist/policy/approval.js.map +1 -0
  30. package/dist/policy/classifier.d.ts +38 -0
  31. package/dist/policy/classifier.d.ts.map +1 -0
  32. package/dist/policy/classifier.js +97 -0
  33. package/dist/policy/classifier.js.map +1 -0
  34. package/dist/policy/default-engine.d.ts +24 -0
  35. package/dist/policy/default-engine.d.ts.map +1 -0
  36. package/dist/policy/default-engine.js +41 -0
  37. package/dist/policy/default-engine.js.map +1 -0
  38. package/dist/policy/engine.d.ts +12 -0
  39. package/dist/policy/engine.d.ts.map +1 -0
  40. package/dist/policy/engine.js +2 -0
  41. package/dist/policy/engine.js.map +1 -0
  42. package/dist/policy/index.d.ts +6 -0
  43. package/dist/policy/index.d.ts.map +1 -0
  44. package/dist/policy/index.js +6 -0
  45. package/dist/policy/index.js.map +1 -0
  46. package/dist/policy/types.d.ts +52 -0
  47. package/dist/policy/types.d.ts.map +1 -0
  48. package/dist/policy/types.js +10 -0
  49. package/dist/policy/types.js.map +1 -0
  50. package/dist/proof/errors.d.ts +1 -0
  51. package/dist/proof/errors.d.ts.map +1 -1
  52. package/dist/proof/errors.js +4 -0
  53. package/dist/proof/errors.js.map +1 -1
  54. package/dist/proof/generator.d.ts +28 -4
  55. package/dist/proof/generator.d.ts.map +1 -1
  56. package/dist/proof/generator.js +48 -20
  57. package/dist/proof/generator.js.map +1 -1
  58. package/dist/proof/verifier.d.ts +32 -3
  59. package/dist/proof/verifier.d.ts.map +1 -1
  60. package/dist/proof/verifier.js +85 -6
  61. package/dist/proof/verifier.js.map +1 -1
  62. package/dist/providers/audit-log.d.ts +62 -0
  63. package/dist/providers/audit-log.d.ts.map +1 -0
  64. package/dist/providers/audit-log.js +75 -0
  65. package/dist/providers/audit-log.js.map +1 -0
  66. package/dist/providers/index.d.ts +3 -0
  67. package/dist/providers/index.d.ts.map +1 -1
  68. package/dist/providers/index.js +3 -0
  69. package/dist/providers/index.js.map +1 -1
  70. package/dist/providers/runtime-fetch.d.ts +73 -0
  71. package/dist/providers/runtime-fetch.d.ts.map +1 -0
  72. package/dist/providers/runtime-fetch.js +169 -0
  73. package/dist/providers/runtime-fetch.js.map +1 -0
  74. package/dist/providers/system-clock.d.ts +39 -0
  75. package/dist/providers/system-clock.d.ts.map +1 -0
  76. package/dist/providers/system-clock.js +49 -0
  77. package/dist/providers/system-clock.js.map +1 -0
  78. package/dist/types/protocol.d.ts +38 -3
  79. package/dist/types/protocol.d.ts.map +1 -1
  80. package/dist/types/protocol.js +44 -9
  81. package/dist/types/protocol.js.map +1 -1
  82. package/package.json +4 -2
  83. package/schemas/README.md +1 -1
  84. package/schemas/delegation-credential.json +2 -2
  85. package/schemas/detached-proof.json +12 -3
  86. package/schemas/handshake-request.json +1 -1
  87. package/schemas/handshake-response.json +1 -1
  88. package/schemas/well-known-mcpi.json +1 -1
package/dist/index.js CHANGED
@@ -16,9 +16,9 @@
16
16
  */
17
17
  // Error contract
18
18
  export { KYA_OS_ERROR_CODES, createKyaOsError, } from './errors.js';
19
- // Encoding utilities (RFC 4648 base64url, byte variants)
20
- export { base64urlEncodeFromBytes, base64urlDecodeToBytes, } from './utils/base64.js';
21
- export { wrapDelegationAsVC, extractDelegationFromVC, isDelegationCredentialExpired, isDelegationCredentialNotYetValid, validateDelegationCredential, validateDetachedProof, createNeedsAuthorizationError, isNeedsAuthorizationError, DELEGATION_CREDENTIAL_CONTEXT, DEFAULT_SESSION_TTL_MINUTES, DEFAULT_TIMESTAMP_SKEW_SECONDS, NONCE_LENGTH_BYTES, AUTH_NONCE_TTL_MS, ANON_NONCE_TTL_MS, } from './types/protocol.js';
19
+ // Encoding utilities (RFC 4648 base64url + standard base64, byte variants)
20
+ export { base64urlEncodeFromBytes, base64urlDecodeToBytes, bytesToBase64, base64ToBytes, } from './utils/base64.js';
21
+ export { wrapDelegationAsVC, extractDelegationFromVC, isDelegationCredentialExpired, isDelegationCredentialNotYetValid, validateDelegationCredential, validateDetachedProof, createNeedsAuthorizationError, isNeedsAuthorizationError, createNeedsApprovalError, isNeedsApprovalError, DELEGATION_CREDENTIAL_CONTEXT, DEFAULT_SESSION_TTL_MINUTES, DEFAULT_TIMESTAMP_SKEW_SECONDS, NONCE_LENGTH_BYTES, AUTH_NONCE_TTL_MS, ANON_NONCE_TTL_MS, } from './types/protocol.js';
22
22
  // Delegation module
23
23
  export { DelegationCredentialIssuer, createDelegationIssuer, } from './delegation/vc-issuer.js';
24
24
  export { DelegationCredentialVerifier, createDelegationVerifier, } from './delegation/vc-verifier.js';
@@ -49,8 +49,14 @@ export { SessionManager, createHandshakeRequest, validateHandshakeFormat, } from
49
49
  export { CryptoProvider, ClockProvider, FetchProvider, StorageProvider, NonceCacheProvider, IdentityProvider, } from './providers/base.js';
50
50
  export { MemoryStorageProvider, MemoryNonceCacheProvider, MemoryIdentityProvider, } from './providers/memory.js';
51
51
  export { NodeCryptoProvider } from './providers/node-crypto.js';
52
+ export { SystemClockProvider } from './providers/system-clock.js';
53
+ export { RuntimeFetchProvider } from './providers/runtime-fetch.js';
54
+ export { AuditLogProvider, MemoryAuditLogProvider, NoopAuditLogProvider, buildAuditRecord, } from './providers/audit-log.js';
52
55
  // Middleware
53
56
  export { createKyaOsMiddleware, withKyaOs, generateIdentity, } from './middleware/index.js';
57
+ // Policy-as-Code subsystem + step-up gate
58
+ export * from './policy/index.js';
59
+ export { matchScope, scopeSatisfies, } from './delegation/scope-matcher.js';
54
60
  // Logging
55
61
  export { logger, createDefaultConsoleLogger, } from './logging/index.js';
56
62
  // Ed25519 Constants
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
@@ -14,11 +14,15 @@
14
14
  * internally by `withKyaOs()` and for advanced use cases like the
15
15
  * low-level `Server` API or custom request handler patterns.
16
16
  */
17
- import { type CryptoProvider, FetchProvider } from "../providers/base.js";
17
+ import { type CryptoProvider, type FetchProvider } from "../providers/base.js";
18
+ import { AuditLogProvider } from "../providers/audit-log.js";
18
19
  import { SessionManager, type SessionConfig } from "../session/manager.js";
19
20
  import { ProofGenerator } from "../proof/generator.js";
20
21
  import { type DIDResolver, type StatusListResolver } from "../delegation/vc-verifier.js";
21
- import { type DelegationCredential } from "../types/protocol.js";
22
+ import { type DelegationCredential, type NeedsAuthorizationError } from "../types/protocol.js";
23
+ import { RiskClassifier } from "../policy/classifier.js";
24
+ import { type ApprovalGrant } from "../policy/approval.js";
25
+ import type { PolicyEngine } from "../policy/engine.js";
22
26
  export interface KyaOsIdentityConfig {
23
27
  did: string;
24
28
  kid: string;
@@ -48,34 +52,6 @@ export interface KyaOsDelegationConfig {
48
52
  * contain only ancestors (root -> parent) or the full chain (root -> leaf).
49
53
  */
50
54
  resolveDelegationChain?: (leafCredential: DelegationCredential) => Promise<DelegationCredential[]>;
51
- /**
52
- * When true, re-delegations (credentials with a `parentId`) MUST include
53
- * an `audience` constraint binding them to the verifying server's DID.
54
- *
55
- * This prevents confused-deputy attacks where a delegated credential is
56
- * forwarded to an unintended server. Without audience binding, any server
57
- * that receives the credential will accept it.
58
- *
59
- * Recommended for production. See: Alan Karp's transitive access analysis
60
- * and KYA-OS §11.6 (Confused Deputy Attacks).
61
- *
62
- * Default is `true` as of KYA-OS 1.3.x. Existing integrations that
63
- * issue re-delegations without an `audience` constraint can set this
64
- * to `false` to preserve legacy behavior; doing so logs a one-time
65
- * warning per process.
66
- */
67
- requireAudienceOnRedelegation?: boolean;
68
- /**
69
- * Compatibility mode for legacy integrations that cannot yet provide
70
- * full delegation-chain and status-list resolvers.
71
- *
72
- * WARNING: Enabling this weakens verification guarantees:
73
- * - Parent-linked delegations are accepted without chain resolution
74
- * - credentialStatus is accepted without StatusList checks
75
- *
76
- * Default is false (strict security behavior).
77
- */
78
- allowLegacyUnsafeDelegation?: boolean;
79
55
  }
80
56
  export interface KyaOsConfig {
81
57
  /** Agent identity (DID + key material) */
@@ -91,6 +67,12 @@ export interface KyaOsConfig {
91
67
  * In production, KYA-OS-aware runtimes should execute handshake before tool calls.
92
68
  */
93
69
  autoSession?: boolean;
70
+ /**
71
+ * Sink for retaining audit records of verified tool calls. Defaults to a
72
+ * no-op; supply an {@link AuditLogProvider} (e.g. a durable, append-only
73
+ * implementation) to capture an audit trail.
74
+ */
75
+ auditLog?: AuditLogProvider;
94
76
  }
95
77
  export interface KyaOsToolDefinition {
96
78
  name: string;
@@ -102,8 +84,16 @@ export interface KyaOsToolDefinition {
102
84
  [key: string]: unknown;
103
85
  };
104
86
  }
87
+ /**
88
+ * Per-call context threaded through the middleware wrappers (not part of the
89
+ * tool's public arguments). `wrapWithDelegation` populates `scopeId` so the
90
+ * proof and audit record reflect the scope the call was authorized under.
91
+ */
92
+ export interface KyaOsCallContext {
93
+ scopeId?: string;
94
+ }
105
95
  export interface KyaOsToolHandler<T extends Record<string, unknown> = Record<string, unknown>> {
106
- (args: T, sessionId?: string): Promise<{
96
+ (args: T, sessionId?: string, context?: KyaOsCallContext): Promise<{
107
97
  content: Array<{
108
98
  type: string;
109
99
  text: string;
@@ -177,7 +167,74 @@ export interface KyaOsMiddleware {
177
167
  wrapWithDelegation(toolName: string, config: {
178
168
  scopeId: string;
179
169
  consentUrl: string;
170
+ /**
171
+ * Optional presentation hook for the `needs_authorization` challenge.
172
+ * Given the structured challenge, return the tool-response content to emit
173
+ * (e.g. a markdown "Authorize" link for LLM / chat-style MCP clients that
174
+ * won't parse raw JSON). The signed challenge proof binds a `responseHash`
175
+ * over WHATEVER this returns, so the `authorizationUrl` stays tamper-evident
176
+ * regardless of presentation. Defaults to the structured challenge as JSON.
177
+ */
178
+ formatChallenge?: (challenge: NeedsAuthorizationError) => Array<{
179
+ type: "text";
180
+ text: string;
181
+ }>;
180
182
  }, handler: KyaOsToolHandler): KyaOsToolHandler;
183
+ /**
184
+ * Wrap a tool handler with a per-action policy / step-up gate.
185
+ *
186
+ * Compose after `wrapWithDelegation`. Classifies the action's risk and asks a
187
+ * pluggable PolicyEngine: allow → run handler; deny → signed denial proof;
188
+ * step_up → `needs_approval` until N-of-M signed approval grants (bound to the
189
+ * request hash) are supplied.
190
+ */
191
+ withPolicyGate?(toolName: string, handler: KyaOsToolHandler, opts?: PolicyGateOptions): KyaOsToolHandler;
192
+ }
193
+ export interface PolicyGateOptions {
194
+ /** Policy decision engine. Defaults to a fail-closed DefaultPolicyEngine. */
195
+ engine?: PolicyEngine;
196
+ /** Risk classifier. Defaults to the built-in RiskClassifier. */
197
+ classifier?: RiskClassifier;
198
+ /** Derive the resource namespace from the tool args (defaults to the tool name). */
199
+ resolveNamespace?: (args: Record<string, unknown>) => string;
200
+ /** Tool-arg key carrying approval grants on resume. Default "_kyaos_approvals". */
201
+ approvalsArgKey?: string;
202
+ /** Verifier for approval-grant signatures (identity-layer). Default: reject all. */
203
+ isValidApprovalSignature?: (grant: ApprovalGrant) => Promise<boolean>;
204
+ /**
205
+ * Whether a prior step already authorized this action's scope/identity.
206
+ *
207
+ * Defaults to FALSE (fail-closed): used standalone, withPolicyGate enforces no
208
+ * scope or identity, so it must NOT be trusted to allow on its own. When you
209
+ * compose it AFTER wrapWithDelegation (the expected usage), pass
210
+ * `scopeMatched: true` to signal that the delegated scope was already verified.
211
+ * Note: principal facts are projected from the (unverified) `_kyaos_delegation`
212
+ * arg on a best-effort basis and must not be treated as authenticated unless
213
+ * wrapWithDelegation ran first.
214
+ */
215
+ scopeMatched?: boolean;
181
216
  }
217
+ /**
218
+ * Create KYA-OS middleware for a standard MCP SDK Server.
219
+ *
220
+ * For most use cases, prefer {@link withKyaOs} from `./with-kya-os-server.ts`
221
+ * which wraps this function and (by default) auto-registers handshake +
222
+ * auto-attaches proofs.
223
+ *
224
+ * Use `createKyaOsMiddleware` directly when:
225
+ * - You use the low-level `Server` API (not `McpServer`)
226
+ * - You need custom request handler patterns
227
+ * - You want per-tool control over proof/delegation wrapping
228
+ *
229
+ * @param config - Agent identity and session configuration
230
+ * @param cryptoProvider - Platform-specific crypto implementation
231
+ * @returns Middleware components for session management and proof generation
232
+ *
233
+ * @remarks
234
+ * **Single-process only**: This middleware stores session state in memory using closure
235
+ * variables (`activeSessionId`, `sessionNonces`). It is NOT suitable for multi-instance
236
+ * deployments behind a load balancer. For distributed deployments, implement a custom
237
+ * `SessionStore` backed by Redis, DynamoDB, or similar and pass it via `config.session`.
238
+ */
182
239
  export declare function createKyaOsMiddleware(config: KyaOsConfig, cryptoProvider: CryptoProvider): KyaOsMiddleware;
183
240
  //# sourceMappingURL=with-kya-os.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"with-kya-os.d.ts","sourceRoot":"","sources":["../../src/middleware/with-kya-os.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"with-kya-os.d.ts","sourceRoot":"","sources":["../../src/middleware/with-kya-os.ts"],"names":[],"mappings":"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"}