@kya-os/checkpoint-shared 1.2.0 → 1.3.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 (53) hide show
  1. package/README.md +1 -1
  2. package/dist/beacon-types/index.d.mts +10 -1
  3. package/dist/beacon-types/index.d.ts +10 -1
  4. package/dist/beacon-types/index.js +20 -1
  5. package/dist/beacon-types/index.mjs +20 -2
  6. package/dist/browser.d.mts +6 -1
  7. package/dist/browser.d.ts +6 -1
  8. package/dist/browser.js +1 -1
  9. package/dist/browser.mjs +1 -1
  10. package/dist/canonical-signer/index.js +31 -2
  11. package/dist/canonical-signer/index.mjs +31 -2
  12. package/dist/deploy/index.d.mts +827 -0
  13. package/dist/deploy/index.d.ts +827 -0
  14. package/dist/deploy/index.js +458 -0
  15. package/dist/deploy/index.mjs +433 -0
  16. package/dist/gateway/index.d.mts +575 -0
  17. package/dist/gateway/index.d.ts +575 -0
  18. package/dist/gateway/index.js +98 -0
  19. package/dist/gateway/index.mjs +88 -0
  20. package/dist/index.d.mts +3071 -871
  21. package/dist/index.d.ts +3071 -871
  22. package/dist/index.js +3344 -1308
  23. package/dist/index.mjs +4593 -2667
  24. package/dist/mcpi/agentshield-api/index.d.mts +47 -0
  25. package/dist/mcpi/agentshield-api/index.d.ts +47 -0
  26. package/dist/mcpi/agentshield-api/index.js +2 -0
  27. package/dist/mcpi/agentshield-api/index.mjs +1 -0
  28. package/dist/mcpi/approval-grant/index.d.mts +79 -0
  29. package/dist/mcpi/approval-grant/index.d.ts +79 -0
  30. package/dist/mcpi/approval-grant/index.js +157 -0
  31. package/dist/mcpi/approval-grant/index.mjs +150 -0
  32. package/dist/mcpi/dashboard-config/index.d.mts +14075 -0
  33. package/dist/mcpi/dashboard-config/index.d.ts +14075 -0
  34. package/dist/mcpi/dashboard-config/index.js +517 -0
  35. package/dist/mcpi/dashboard-config/index.mjs +492 -0
  36. package/dist/mcpi/multibase-ed25519.d.mts +8 -0
  37. package/dist/mcpi/multibase-ed25519.d.ts +8 -0
  38. package/dist/mcpi/multibase-ed25519.js +125 -0
  39. package/dist/mcpi/multibase-ed25519.mjs +119 -0
  40. package/dist/signals/index.d.mts +158 -0
  41. package/dist/signals/index.d.ts +158 -0
  42. package/dist/signals/index.js +1574 -0
  43. package/dist/signals/index.mjs +1544 -0
  44. package/dist/test-fixtures/index.d.mts +53 -8
  45. package/dist/test-fixtures/index.d.ts +53 -8
  46. package/dist/test-fixtures/index.js +164 -7
  47. package/dist/test-fixtures/index.mjs +158 -8
  48. package/dist/tool-protection/index.d.mts +1120 -0
  49. package/dist/tool-protection/index.d.ts +1120 -0
  50. package/dist/tool-protection/index.js +370 -0
  51. package/dist/tool-protection/index.mjs +338 -0
  52. package/package.json +54 -8
  53. package/src/data/compiled/merged-rules.json +8 -2
@@ -0,0 +1,433 @@
1
+ import { z } from 'zod';
2
+
3
+ // src/deploy/index.ts
4
+ var KYA_OS_EVENTS_PATH = "/api/v1/kya-os/events";
5
+ var DidStringSchema = z.string().min(8, "DID must be at least 8 characters").regex(/^did:[a-z0-9]+:\S+$/, "DID must match format did:<method>:<method-specific-id>");
6
+ var FlyRegionSchema = z.enum([
7
+ "ams",
8
+ // Amsterdam, Netherlands
9
+ "arn",
10
+ // Stockholm, Sweden
11
+ "atl",
12
+ // Atlanta, Georgia (US)
13
+ "bog",
14
+ // Bogotá, Colombia
15
+ "bos",
16
+ // Boston, Massachusetts (US)
17
+ "cdg",
18
+ // Paris, France
19
+ "den",
20
+ // Denver, Colorado (US)
21
+ "dfw",
22
+ // Dallas, Texas (US)
23
+ "ewr",
24
+ // Secaucus, NJ (US)
25
+ "eze",
26
+ // Ezeiza, Argentina
27
+ "fra",
28
+ // Frankfurt, Germany
29
+ "gdl",
30
+ // Guadalajara, Mexico
31
+ "gig",
32
+ // Rio de Janeiro, Brazil
33
+ "gru",
34
+ // São Paulo, Brazil
35
+ "hkg",
36
+ // Hong Kong
37
+ "iad",
38
+ // Ashburn, Virginia (US)
39
+ "jnb",
40
+ // Johannesburg, South Africa
41
+ "lax",
42
+ // Los Angeles, California (US)
43
+ "lhr",
44
+ // London, United Kingdom
45
+ "mad",
46
+ // Madrid, Spain
47
+ "mia",
48
+ // Miami, Florida (US)
49
+ "nrt",
50
+ // Tokyo, Japan
51
+ "ord",
52
+ // Chicago, Illinois (US)
53
+ "otp",
54
+ // Bucharest, Romania
55
+ "phx",
56
+ // Phoenix, Arizona (US)
57
+ "qro",
58
+ // Querétaro, Mexico
59
+ "scl",
60
+ // Santiago, Chile
61
+ "sea",
62
+ // Seattle, Washington (US)
63
+ "sin",
64
+ // Singapore
65
+ "sjc",
66
+ // San Jose, California (US)
67
+ "syd",
68
+ // Sydney, Australia
69
+ "waw",
70
+ // Warsaw, Poland
71
+ "yul",
72
+ // Montreal, Canada
73
+ "yyz"
74
+ // Toronto, Canada
75
+ ]);
76
+ var HostingModeSchema = z.enum(["byok", "managed", "managed-byoa"]);
77
+ var AuditAssuranceProfileSchema = z.enum(["AAP-0", "AAP-1", "AAP-2", "AAP-3", "AAP-4"]);
78
+ var AuditDeliveryModeSchema = z.enum(["best-effort", "buffered", "required"]);
79
+ var AuditDeploymentConfigSchema = z.object({
80
+ enabled: z.boolean(),
81
+ requestedProfile: AuditAssuranceProfileSchema,
82
+ delivery: AuditDeliveryModeSchema,
83
+ evidenceMode: z.enum(["none", "encrypted-separate", "encrypted-inline"]),
84
+ retentionClass: z.string().min(1).max(128),
85
+ retentionDays: z.number().int().min(0).max(3650),
86
+ residency: z.enum(["inherit-project", "us", "eu", "global"]),
87
+ keyCustody: z.enum(["none", "checkpoint-managed", "customer-managed-kms"]),
88
+ recorderTopology: z.enum(["none", "self-hosted", "managed", "verified-mirror"])
89
+ }).strict().superRefine((value, context) => {
90
+ if (!value.enabled && value.requestedProfile !== "AAP-0") {
91
+ context.addIssue({
92
+ code: z.ZodIssueCode.custom,
93
+ path: ["requestedProfile"],
94
+ message: "Disabled audit configuration must request AAP-0"
95
+ });
96
+ }
97
+ if (value.enabled && value.requestedProfile === "AAP-0") {
98
+ context.addIssue({
99
+ code: z.ZodIssueCode.custom,
100
+ path: ["requestedProfile"],
101
+ message: "Enabled audit configuration must request AAP-1 or higher"
102
+ });
103
+ }
104
+ if (Number(value.requestedProfile.slice(-1)) >= 2 && value.delivery === "best-effort") {
105
+ context.addIssue({
106
+ code: z.ZodIssueCode.custom,
107
+ path: ["delivery"],
108
+ message: "AAP-2 or higher cannot use best-effort delivery"
109
+ });
110
+ }
111
+ if (!value.enabled && (value.keyCustody !== "none" || value.recorderTopology !== "none")) {
112
+ context.addIssue({
113
+ code: z.ZodIssueCode.custom,
114
+ message: "Disabled audit configuration cannot claim key custody or recorder topology"
115
+ });
116
+ }
117
+ });
118
+ var NEW_MANAGED_AUDIT_DEPLOYMENT_DEFAULT = Object.freeze({
119
+ enabled: true,
120
+ requestedProfile: "AAP-2",
121
+ delivery: "buffered",
122
+ evidenceMode: "encrypted-separate",
123
+ retentionClass: "integrity-ledger",
124
+ retentionDays: 365,
125
+ residency: "inherit-project",
126
+ keyCustody: "checkpoint-managed",
127
+ recorderTopology: "managed"
128
+ });
129
+ var ABSENT_AUDIT_DEPLOYMENT_CONFIG = Object.freeze({
130
+ enabled: false,
131
+ requestedProfile: "AAP-0",
132
+ delivery: "best-effort",
133
+ evidenceMode: "none",
134
+ retentionClass: "none",
135
+ retentionDays: 0,
136
+ residency: "inherit-project",
137
+ keyCustody: "none",
138
+ recorderTopology: "none"
139
+ });
140
+ var AuditRuntimeCapabilitiesSchema = z.object({
141
+ recorderTopology: z.enum(["none", "self-hosted", "managed", "verified-mirror"]),
142
+ delivery: AuditDeliveryModeSchema,
143
+ journalDurability: z.enum(["none", "ephemeral", "durable"]),
144
+ atomicAppend: z.boolean(),
145
+ sourceHighWater: z.boolean(),
146
+ merkleCheckpoints: z.boolean(),
147
+ independentObservation: z.boolean(),
148
+ supportingAnchors: z.array(z.enum(["worm", "rfc3161", "scitt"])),
149
+ evidenceRetention: z.enum(["none", "inline", "separate"])
150
+ }).strict();
151
+ var AuditRuntimeCanaryResultSchema = z.object({
152
+ passed: z.boolean(),
153
+ observedAt: z.number().int().nonnegative(),
154
+ capabilities: AuditRuntimeCapabilitiesSchema,
155
+ checks: z.array(
156
+ z.object({
157
+ id: z.string().min(1).max(128),
158
+ passed: z.boolean()
159
+ }).strict()
160
+ ).min(1),
161
+ bundleHash: z.string().min(1).max(256).optional()
162
+ }).strict().superRefine((value, context) => {
163
+ if (value.passed !== value.checks.every((check) => check.passed)) {
164
+ context.addIssue({
165
+ code: z.ZodIssueCode.custom,
166
+ path: ["passed"],
167
+ message: "Canary result must equal the aggregate of its mechanical checks"
168
+ });
169
+ }
170
+ });
171
+ function requiredAuditRuntimeCanaryChecks(capabilities) {
172
+ const checks = [
173
+ "recorder_round_trip",
174
+ "verified_receipt",
175
+ "idempotent_retry",
176
+ "event_identity_conflict",
177
+ "source_state"
178
+ ];
179
+ if (capabilities.delivery === "buffered") checks.push("buffered_outbox");
180
+ if (capabilities.evidenceRetention !== "none") checks.push("evidence_write_verified");
181
+ return checks;
182
+ }
183
+ var AuditDeploymentReadinessSchema = z.object({
184
+ requestedProfile: AuditAssuranceProfileSchema,
185
+ effectiveProfile: AuditAssuranceProfileSchema,
186
+ status: z.enum(["disabled", "ready", "degraded"]),
187
+ capabilities: AuditRuntimeCapabilitiesSchema.nullable(),
188
+ canary: AuditRuntimeCanaryResultSchema.nullable(),
189
+ reasonCodes: z.array(z.string().min(1).max(128))
190
+ }).strict();
191
+ var PROFILE_BY_LEVEL = ["AAP-0", "AAP-1", "AAP-2", "AAP-3", "AAP-4"];
192
+ function resolveAuditDeploymentReadiness(config, capabilities, canary) {
193
+ const requested = AuditDeploymentConfigSchema.parse(config ?? ABSENT_AUDIT_DEPLOYMENT_CONFIG);
194
+ const observedCanary = canary ? AuditRuntimeCanaryResultSchema.parse(canary) : null;
195
+ if (!requested.enabled) {
196
+ return {
197
+ requestedProfile: "AAP-0",
198
+ effectiveProfile: "AAP-0",
199
+ status: "disabled",
200
+ capabilities: capabilities ?? null,
201
+ canary: observedCanary,
202
+ reasonCodes: ["audit_not_configured"]
203
+ };
204
+ }
205
+ const observedCapabilities = capabilities ?? observedCanary?.capabilities;
206
+ if (!observedCapabilities) {
207
+ return {
208
+ requestedProfile: requested.requestedProfile,
209
+ effectiveProfile: "AAP-0",
210
+ status: "degraded",
211
+ capabilities: null,
212
+ canary: observedCanary,
213
+ reasonCodes: ["runtime_capabilities_unavailable"]
214
+ };
215
+ }
216
+ const observed = AuditRuntimeCapabilitiesSchema.parse(observedCapabilities);
217
+ if (!observedCanary) {
218
+ return {
219
+ requestedProfile: requested.requestedProfile,
220
+ effectiveProfile: "AAP-0",
221
+ status: "degraded",
222
+ capabilities: observed,
223
+ canary: null,
224
+ reasonCodes: ["runtime_canary_required"]
225
+ };
226
+ }
227
+ if (!observedCanary.passed || JSON.stringify(observedCanary.capabilities) !== JSON.stringify(observed)) {
228
+ return {
229
+ requestedProfile: requested.requestedProfile,
230
+ effectiveProfile: "AAP-0",
231
+ status: "degraded",
232
+ capabilities: observed,
233
+ canary: observedCanary,
234
+ reasonCodes: [
235
+ observedCanary.passed ? "runtime_canary_capability_mismatch" : "runtime_canary_failed"
236
+ ]
237
+ };
238
+ }
239
+ const passedChecks = new Set(
240
+ observedCanary.checks.filter((check) => check.passed).map((check) => check.id)
241
+ );
242
+ if (requiredAuditRuntimeCanaryChecks(observed).some((check) => !passedChecks.has(check))) {
243
+ return {
244
+ requestedProfile: requested.requestedProfile,
245
+ effectiveProfile: "AAP-0",
246
+ status: "degraded",
247
+ capabilities: observed,
248
+ canary: observedCanary,
249
+ reasonCodes: ["runtime_canary_incomplete"]
250
+ };
251
+ }
252
+ let maximum = 0;
253
+ const reasons = [];
254
+ if (observed.recorderTopology !== requested.recorderTopology) {
255
+ reasons.push("recorder_topology_mismatch");
256
+ }
257
+ const deliveryRank = { "best-effort": 0, buffered: 1, required: 2 };
258
+ if (deliveryRank[observed.delivery] < deliveryRank[requested.delivery]) {
259
+ reasons.push("delivery_mode_mismatch");
260
+ }
261
+ const expectedEvidence = requested.evidenceMode === "none" ? "none" : requested.evidenceMode === "encrypted-inline" ? "inline" : "separate";
262
+ if (expectedEvidence !== observed.evidenceRetention) {
263
+ reasons.push("evidence_retention_mismatch");
264
+ }
265
+ if (reasons.length > 0) {
266
+ return {
267
+ requestedProfile: requested.requestedProfile,
268
+ effectiveProfile: "AAP-0",
269
+ status: "degraded",
270
+ capabilities: observed,
271
+ canary: observedCanary,
272
+ reasonCodes: reasons
273
+ };
274
+ }
275
+ if (observed.recorderTopology !== "none" && observed.journalDurability !== "none") maximum = 1;
276
+ else reasons.push("recorder_or_journal_unavailable");
277
+ if (maximum >= 1 && observed.journalDurability === "durable" && observed.atomicAppend && observed.delivery !== "best-effort") {
278
+ maximum = 2;
279
+ } else if (Number(requested.requestedProfile.slice(-1)) >= 2) {
280
+ reasons.push("durable_atomic_buffered_append_unavailable");
281
+ }
282
+ if (maximum >= 2 && observed.merkleCheckpoints && observed.sourceHighWater) maximum = 3;
283
+ else if (Number(requested.requestedProfile.slice(-1)) >= 3) {
284
+ reasons.push("checkpoint_or_source_high_water_unavailable");
285
+ }
286
+ if (maximum >= 3 && observed.independentObservation && observed.supportingAnchors.length > 0) {
287
+ maximum = 4;
288
+ } else if (Number(requested.requestedProfile.slice(-1)) >= 4) {
289
+ reasons.push("independent_observation_or_anchor_unavailable");
290
+ }
291
+ const requestedLevel = Number(requested.requestedProfile.slice(-1));
292
+ const effectiveLevel = Math.min(requestedLevel, maximum);
293
+ return {
294
+ requestedProfile: requested.requestedProfile,
295
+ effectiveProfile: PROFILE_BY_LEVEL[effectiveLevel],
296
+ status: effectiveLevel === requestedLevel && reasons.length === 0 ? "ready" : "degraded",
297
+ capabilities: observed,
298
+ canary: observedCanary,
299
+ reasonCodes: reasons
300
+ };
301
+ }
302
+ var ManagedDeployStepStatusSchema = z.enum([
303
+ "pending",
304
+ "in_progress",
305
+ "completed",
306
+ "failed",
307
+ "skipped"
308
+ ]);
309
+ var HeartbeatRequestSchema = z.object({
310
+ /** Agent DID this heartbeat is for */
311
+ agentDid: DidStringSchema,
312
+ /** Current compute process status */
313
+ status: z.enum(["starting", "running", "error", "stopping"]),
314
+ /** @kya-os/compute package version (from package.json) */
315
+ computeVersion: z.string().min(1).max(50),
316
+ /** Installed OpenClaw version (from npm ls) */
317
+ openclawVersion: z.string().max(50).optional(),
318
+ /** Fly machine ID (from FLY_MACHINE_ID env var) */
319
+ machineId: z.string().max(255).optional(),
320
+ /** Seconds since compute process started */
321
+ uptimeSeconds: z.number().nonnegative().optional(),
322
+ /** Current RSS memory in MB */
323
+ memoryMb: z.number().nonnegative().optional()
324
+ });
325
+ var StopCommandSchema = z.object({
326
+ type: z.literal("stop")
327
+ }).strict();
328
+ var RestartCommandSchema = z.object({
329
+ type: z.literal("restart")
330
+ }).strict();
331
+ var UpdateConfigCommandSchema = z.object({
332
+ type: z.literal("update_config")
333
+ }).strict();
334
+ var UpdateVersionCommandSchema = z.object({
335
+ type: z.literal("update_version"),
336
+ payload: z.object({
337
+ /** Target OpenClaw version to install */
338
+ version: z.string().min(1).max(50)
339
+ })
340
+ }).strict();
341
+ var ComputeCommandSchema = z.discriminatedUnion("type", [
342
+ StopCommandSchema,
343
+ RestartCommandSchema,
344
+ UpdateConfigCommandSchema,
345
+ UpdateVersionCommandSchema
346
+ ]);
347
+ var HeartbeatResponseSchema = z.object({
348
+ /** Always true for successful heartbeats */
349
+ ack: z.literal(true),
350
+ /** Pending commands for the compute process to execute */
351
+ commands: z.array(ComputeCommandSchema).default([]),
352
+ /** ISO timestamp of last config change (compute compares to detect updates) */
353
+ configUpdatedAt: z.string().datetime().optional()
354
+ });
355
+ var ConfigBundleSchema = z.object({
356
+ /** Schema version — 2 for managed bundles */
357
+ version: z.number().int().positive(),
358
+ /** Kill switch — if true, compute must exit immediately */
359
+ killed: z.boolean(),
360
+ /** Target OpenClaw version to install */
361
+ openclawVersion: z.string().min(1).max(50),
362
+ /** Agent personality/system prompt file contents (max 100KB) */
363
+ soulFile: z.string().max(1e5).nullable(),
364
+ /** Gateway auth token for OpenClaw */
365
+ gatewayToken: z.string().min(1).max(500),
366
+ /** Channel configurations */
367
+ channels: z.object({
368
+ telegram: z.object({
369
+ enabled: z.boolean(),
370
+ token: z.string().optional()
371
+ }).optional(),
372
+ discord: z.object({
373
+ enabled: z.boolean(),
374
+ token: z.string().optional()
375
+ }).optional(),
376
+ slack: z.object({
377
+ enabled: z.boolean(),
378
+ token: z.string().optional(),
379
+ appToken: z.string().optional()
380
+ }).optional(),
381
+ whatsapp: z.object({
382
+ enabled: z.boolean()
383
+ }).strict().optional()
384
+ }),
385
+ /** AI provider configuration — key is decrypted, sent over TLS */
386
+ aiProvider: z.object({
387
+ type: z.enum(["anthropic", "openai"]),
388
+ apiKey: z.string().min(1).max(500),
389
+ /**
390
+ * Optional base URL override. When set, OpenClaw routes all provider
391
+ * traffic through this URL instead of the provider's default endpoint.
392
+ * Used by managed deployments where AgentShield issues a per-deployment
393
+ * gateway token and proxies to the upstream provider with budget tracking.
394
+ */
395
+ baseUrl: z.string().url().optional()
396
+ }),
397
+ /**
398
+ * Optional OpenClaw heartbeat interval (`agents.defaults.heartbeat.every`).
399
+ * Drives how often OpenClaw wakes the agent for HEARTBEAT.md processing —
400
+ * the primary token-cost lever. Examples: "30m" (active), "6h" (idle),
401
+ * "off" (dormant — heartbeat disabled entirely). When absent, the patcher
402
+ * preserves whatever value already lives in openclaw.json (OpenClaw's
403
+ * built-in default of "30m").
404
+ */
405
+ heartbeatEvery: z.string().min(1).max(20).optional(),
406
+ /**
407
+ * Optional override for `agents.defaults.model.primary` (e.g.
408
+ * "anthropic/claude-haiku-4-5" for idle agents). When absent, the patcher
409
+ * derives the model from `aiProvider.type` as before. Format must be
410
+ * "<provider>/<model-id>".
411
+ */
412
+ modelOverride: z.string().min(1).max(100).optional(),
413
+ /** ISO timestamp of last config modification */
414
+ updatedAt: z.string().datetime()
415
+ });
416
+ var ControlStatusSchema = z.object({
417
+ /** Whether the agent runtime is healthy */
418
+ healthy: z.boolean(),
419
+ /** Seconds since compute process started */
420
+ uptimeSeconds: z.number().nonnegative(),
421
+ /** Installed OpenClaw version */
422
+ openclawVersion: z.string().min(1).max(50),
423
+ /** @kya-os/compute version */
424
+ computeVersion: z.string().min(1).max(50),
425
+ /** Number of active WS connections to control server */
426
+ activeConnections: z.number().int().nonnegative(),
427
+ /** Current RSS memory in MB */
428
+ memoryMb: z.number().nonnegative(),
429
+ /** CPU usage percentage (0-100) */
430
+ cpuPercent: z.number().nonnegative().max(100)
431
+ });
432
+
433
+ export { ABSENT_AUDIT_DEPLOYMENT_CONFIG, AuditAssuranceProfileSchema, AuditDeliveryModeSchema, AuditDeploymentConfigSchema, AuditDeploymentReadinessSchema, AuditRuntimeCanaryResultSchema, AuditRuntimeCapabilitiesSchema, ComputeCommandSchema, ConfigBundleSchema, ControlStatusSchema, DidStringSchema, FlyRegionSchema, HeartbeatRequestSchema, HeartbeatResponseSchema, HostingModeSchema, KYA_OS_EVENTS_PATH, ManagedDeployStepStatusSchema, NEW_MANAGED_AUDIT_DEPLOYMENT_DEFAULT, RestartCommandSchema, StopCommandSchema, UpdateConfigCommandSchema, UpdateVersionCommandSchema, requiredAuditRuntimeCanaryChecks, resolveAuditDeploymentReadiness };