@kici-dev/engine 0.1.15 → 0.1.16

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.
@@ -0,0 +1,407 @@
1
+ /**
2
+ * SLSA v1.0 build-provenance schema for KiCI.
3
+ *
4
+ * Models the in-toto Statement v1 envelope and the SLSA v1.0 provenance
5
+ * predicate as Zod schemas, plus a KiCI-specialized statement schema that pins
6
+ * the KiCI literals and types the KiCI-owned build parameters. This is the
7
+ * single source of truth shared by the agent (produces attestations) and the
8
+ * `kici verify-attestation` CLI (consumes them).
9
+ *
10
+ * Pure schema + types — no Node-only dependencies, so the dashboard can import
11
+ * it for typed artifact rendering. Exported at the subpath
12
+ * `@kici-dev/engine/provenance/schema`.
13
+ *
14
+ * Spec references:
15
+ * - in-toto Statement v1: https://github.com/in-toto/attestation/blob/main/spec/v1/statement.md
16
+ * - SLSA v1.0 provenance: https://slsa.dev/spec/v1.0/provenance
17
+ */
18
+ import { z } from 'zod';
19
+ /** in-toto Statement `_type` value (pinned). */
20
+ export declare const IN_TOTO_STATEMENT_TYPE = "https://in-toto.io/Statement/v1";
21
+ /** SLSA v1.0 provenance `predicateType` value (pinned). */
22
+ export declare const SLSA_PROVENANCE_PREDICATE_TYPE = "https://slsa.dev/provenance/v1";
23
+ /** KiCI workflow `buildType` URI (we own this namespace). */
24
+ export declare const KICI_WORKFLOW_BUILD_TYPE = "https://kici.dev/buildtypes/workflow/v1";
25
+ /**
26
+ * Known digest algorithms KiCI emits or tests reference. The digest map itself
27
+ * (`digestSetSchema`) keeps its keys open for forward-compatibility; this enum
28
+ * documents the common set so producer code and tests don't repeat literals.
29
+ */
30
+ export declare const DigestAlgorithm: z.ZodEnum<{
31
+ sha256: "sha256";
32
+ sha512: "sha512";
33
+ sha1: "sha1";
34
+ gitCommit: "gitCommit";
35
+ dirHash: "dirHash";
36
+ }>;
37
+ export type DigestAlgorithm = z.infer<typeof DigestAlgorithm>;
38
+ /**
39
+ * in-toto digest set: a map of algorithm name → lowercase-hex digest. Keys are
40
+ * open (forward-compat); at least one entry is required.
41
+ */
42
+ export declare const digestSetSchema: z.ZodRecord<z.ZodString, z.ZodString>;
43
+ export type DigestSet = z.infer<typeof digestSetSchema>;
44
+ /**
45
+ * in-toto ResourceDescriptor. Reused for `resolvedDependencies` and
46
+ * `byproducts`. Per spec, at least one of name / uri / digest must be present.
47
+ */
48
+ export declare const resourceDescriptorSchema: z.ZodObject<{
49
+ name: z.ZodOptional<z.ZodString>;
50
+ uri: z.ZodOptional<z.ZodString>;
51
+ digest: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
52
+ content: z.ZodOptional<z.ZodString>;
53
+ downloadLocation: z.ZodOptional<z.ZodString>;
54
+ mediaType: z.ZodOptional<z.ZodString>;
55
+ annotations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
56
+ }, z.core.$strip>;
57
+ export type ResourceDescriptor = z.infer<typeof resourceDescriptorSchema>;
58
+ /**
59
+ * in-toto Statement subject entry: a resource descriptor that MUST carry a
60
+ * digest (the verifier matches the subject digest against the artifact).
61
+ */
62
+ export declare const subjectSchema: z.ZodObject<{
63
+ name: z.ZodOptional<z.ZodString>;
64
+ uri: z.ZodOptional<z.ZodString>;
65
+ digest: z.ZodRecord<z.ZodString, z.ZodString>;
66
+ mediaType: z.ZodOptional<z.ZodString>;
67
+ annotations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
68
+ }, z.core.$strip>;
69
+ export type Subject = z.infer<typeof subjectSchema>;
70
+ /** SLSA `builder`: identity of the build platform. `id` is a required URI. */
71
+ export declare const builderSchema: z.ZodObject<{
72
+ id: z.ZodString;
73
+ builderDependencies: z.ZodOptional<z.ZodArray<z.ZodObject<{
74
+ name: z.ZodOptional<z.ZodString>;
75
+ uri: z.ZodOptional<z.ZodString>;
76
+ digest: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
77
+ content: z.ZodOptional<z.ZodString>;
78
+ downloadLocation: z.ZodOptional<z.ZodString>;
79
+ mediaType: z.ZodOptional<z.ZodString>;
80
+ annotations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
81
+ }, z.core.$strip>>>;
82
+ version: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
83
+ }, z.core.$strip>;
84
+ export type Builder = z.infer<typeof builderSchema>;
85
+ /** SLSA `metadata`: build-invocation metadata. */
86
+ export declare const buildMetadataSchema: z.ZodObject<{
87
+ invocationId: z.ZodOptional<z.ZodString>;
88
+ startedOn: z.ZodOptional<z.ZodString>;
89
+ finishedOn: z.ZodOptional<z.ZodString>;
90
+ }, z.core.$strip>;
91
+ export type BuildMetadata = z.infer<typeof buildMetadataSchema>;
92
+ /** SLSA `buildDefinition`. `buildType` + `externalParameters` are required. */
93
+ export declare const buildDefinitionSchema: z.ZodObject<{
94
+ buildType: z.ZodString;
95
+ externalParameters: z.ZodRecord<z.ZodString, z.ZodUnknown>;
96
+ internalParameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
97
+ resolvedDependencies: z.ZodOptional<z.ZodArray<z.ZodObject<{
98
+ name: z.ZodOptional<z.ZodString>;
99
+ uri: z.ZodOptional<z.ZodString>;
100
+ digest: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
101
+ content: z.ZodOptional<z.ZodString>;
102
+ downloadLocation: z.ZodOptional<z.ZodString>;
103
+ mediaType: z.ZodOptional<z.ZodString>;
104
+ annotations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
105
+ }, z.core.$strip>>>;
106
+ }, z.core.$strip>;
107
+ export type BuildDefinition = z.infer<typeof buildDefinitionSchema>;
108
+ /** SLSA `runDetails`. `builder` is required. */
109
+ export declare const runDetailsSchema: z.ZodObject<{
110
+ builder: z.ZodObject<{
111
+ id: z.ZodString;
112
+ builderDependencies: z.ZodOptional<z.ZodArray<z.ZodObject<{
113
+ name: z.ZodOptional<z.ZodString>;
114
+ uri: z.ZodOptional<z.ZodString>;
115
+ digest: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
116
+ content: z.ZodOptional<z.ZodString>;
117
+ downloadLocation: z.ZodOptional<z.ZodString>;
118
+ mediaType: z.ZodOptional<z.ZodString>;
119
+ annotations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
120
+ }, z.core.$strip>>>;
121
+ version: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
122
+ }, z.core.$strip>;
123
+ metadata: z.ZodOptional<z.ZodObject<{
124
+ invocationId: z.ZodOptional<z.ZodString>;
125
+ startedOn: z.ZodOptional<z.ZodString>;
126
+ finishedOn: z.ZodOptional<z.ZodString>;
127
+ }, z.core.$strip>>;
128
+ byproducts: z.ZodOptional<z.ZodArray<z.ZodObject<{
129
+ name: z.ZodOptional<z.ZodString>;
130
+ uri: z.ZodOptional<z.ZodString>;
131
+ digest: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
132
+ content: z.ZodOptional<z.ZodString>;
133
+ downloadLocation: z.ZodOptional<z.ZodString>;
134
+ mediaType: z.ZodOptional<z.ZodString>;
135
+ annotations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
136
+ }, z.core.$strip>>>;
137
+ }, z.core.$strip>;
138
+ export type RunDetails = z.infer<typeof runDetailsSchema>;
139
+ /** SLSA v1.0 provenance predicate. */
140
+ export declare const slsaProvenancePredicateSchema: z.ZodObject<{
141
+ buildDefinition: z.ZodObject<{
142
+ buildType: z.ZodString;
143
+ externalParameters: z.ZodRecord<z.ZodString, z.ZodUnknown>;
144
+ internalParameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
145
+ resolvedDependencies: z.ZodOptional<z.ZodArray<z.ZodObject<{
146
+ name: z.ZodOptional<z.ZodString>;
147
+ uri: z.ZodOptional<z.ZodString>;
148
+ digest: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
149
+ content: z.ZodOptional<z.ZodString>;
150
+ downloadLocation: z.ZodOptional<z.ZodString>;
151
+ mediaType: z.ZodOptional<z.ZodString>;
152
+ annotations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
153
+ }, z.core.$strip>>>;
154
+ }, z.core.$strip>;
155
+ runDetails: z.ZodObject<{
156
+ builder: z.ZodObject<{
157
+ id: z.ZodString;
158
+ builderDependencies: z.ZodOptional<z.ZodArray<z.ZodObject<{
159
+ name: z.ZodOptional<z.ZodString>;
160
+ uri: z.ZodOptional<z.ZodString>;
161
+ digest: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
162
+ content: z.ZodOptional<z.ZodString>;
163
+ downloadLocation: z.ZodOptional<z.ZodString>;
164
+ mediaType: z.ZodOptional<z.ZodString>;
165
+ annotations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
166
+ }, z.core.$strip>>>;
167
+ version: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
168
+ }, z.core.$strip>;
169
+ metadata: z.ZodOptional<z.ZodObject<{
170
+ invocationId: z.ZodOptional<z.ZodString>;
171
+ startedOn: z.ZodOptional<z.ZodString>;
172
+ finishedOn: z.ZodOptional<z.ZodString>;
173
+ }, z.core.$strip>>;
174
+ byproducts: z.ZodOptional<z.ZodArray<z.ZodObject<{
175
+ name: z.ZodOptional<z.ZodString>;
176
+ uri: z.ZodOptional<z.ZodString>;
177
+ digest: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
178
+ content: z.ZodOptional<z.ZodString>;
179
+ downloadLocation: z.ZodOptional<z.ZodString>;
180
+ mediaType: z.ZodOptional<z.ZodString>;
181
+ annotations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
182
+ }, z.core.$strip>>>;
183
+ }, z.core.$strip>;
184
+ }, z.core.$strip>;
185
+ export type SlsaProvenancePredicate = z.infer<typeof slsaProvenancePredicateSchema>;
186
+ /** Predicate-agnostic in-toto Statement v1 envelope. */
187
+ export declare const inTotoStatementSchema: z.ZodObject<{
188
+ _type: z.ZodLiteral<"https://in-toto.io/Statement/v1">;
189
+ subject: z.ZodArray<z.ZodObject<{
190
+ name: z.ZodOptional<z.ZodString>;
191
+ uri: z.ZodOptional<z.ZodString>;
192
+ digest: z.ZodRecord<z.ZodString, z.ZodString>;
193
+ mediaType: z.ZodOptional<z.ZodString>;
194
+ annotations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
195
+ }, z.core.$strip>>;
196
+ predicateType: z.ZodString;
197
+ predicate: z.ZodRecord<z.ZodString, z.ZodUnknown>;
198
+ }, z.core.$strip>;
199
+ export type InTotoStatement = z.infer<typeof inTotoStatementSchema>;
200
+ /** KiCI workflow external parameters: the workflow source coordinates. */
201
+ export declare const kiciWorkflowExternalParametersSchema: z.ZodObject<{
202
+ workflow: z.ZodObject<{
203
+ repository: z.ZodString;
204
+ ref: z.ZodString;
205
+ path: z.ZodString;
206
+ }, z.core.$strip>;
207
+ }, z.core.$loose>;
208
+ export type KiciWorkflowExternalParameters = z.infer<typeof kiciWorkflowExternalParametersSchema>;
209
+ /** KiCI workflow internal parameters: run-scoped build context. */
210
+ export declare const kiciWorkflowInternalParametersSchema: z.ZodObject<{
211
+ commit: z.ZodOptional<z.ZodString>;
212
+ runId: z.ZodOptional<z.ZodString>;
213
+ jobId: z.ZodOptional<z.ZodString>;
214
+ }, z.core.$loose>;
215
+ export type KiciWorkflowInternalParameters = z.infer<typeof kiciWorkflowInternalParametersSchema>;
216
+ /** KiCI build definition: pins the buildType and types the workflow params. */
217
+ export declare const kiciBuildDefinitionSchema: z.ZodObject<{
218
+ resolvedDependencies: z.ZodOptional<z.ZodArray<z.ZodObject<{
219
+ name: z.ZodOptional<z.ZodString>;
220
+ uri: z.ZodOptional<z.ZodString>;
221
+ digest: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
222
+ content: z.ZodOptional<z.ZodString>;
223
+ downloadLocation: z.ZodOptional<z.ZodString>;
224
+ mediaType: z.ZodOptional<z.ZodString>;
225
+ annotations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
226
+ }, z.core.$strip>>>;
227
+ buildType: z.ZodLiteral<"https://kici.dev/buildtypes/workflow/v1">;
228
+ externalParameters: z.ZodObject<{
229
+ workflow: z.ZodObject<{
230
+ repository: z.ZodString;
231
+ ref: z.ZodString;
232
+ path: z.ZodString;
233
+ }, z.core.$strip>;
234
+ }, z.core.$loose>;
235
+ internalParameters: z.ZodOptional<z.ZodObject<{
236
+ commit: z.ZodOptional<z.ZodString>;
237
+ runId: z.ZodOptional<z.ZodString>;
238
+ jobId: z.ZodOptional<z.ZodString>;
239
+ }, z.core.$loose>>;
240
+ }, z.core.$strip>;
241
+ export type KiciBuildDefinition = z.infer<typeof kiciBuildDefinitionSchema>;
242
+ /** KiCI run details: types builder.version with the KiCI component versions. */
243
+ export declare const kiciRunDetailsSchema: z.ZodObject<{
244
+ metadata: z.ZodOptional<z.ZodObject<{
245
+ invocationId: z.ZodOptional<z.ZodString>;
246
+ startedOn: z.ZodOptional<z.ZodString>;
247
+ finishedOn: z.ZodOptional<z.ZodString>;
248
+ }, z.core.$strip>>;
249
+ byproducts: z.ZodOptional<z.ZodArray<z.ZodObject<{
250
+ name: z.ZodOptional<z.ZodString>;
251
+ uri: z.ZodOptional<z.ZodString>;
252
+ digest: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
253
+ content: z.ZodOptional<z.ZodString>;
254
+ downloadLocation: z.ZodOptional<z.ZodString>;
255
+ mediaType: z.ZodOptional<z.ZodString>;
256
+ annotations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
257
+ }, z.core.$strip>>>;
258
+ builder: z.ZodObject<{
259
+ id: z.ZodString;
260
+ builderDependencies: z.ZodOptional<z.ZodArray<z.ZodObject<{
261
+ name: z.ZodOptional<z.ZodString>;
262
+ uri: z.ZodOptional<z.ZodString>;
263
+ digest: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
264
+ content: z.ZodOptional<z.ZodString>;
265
+ downloadLocation: z.ZodOptional<z.ZodString>;
266
+ mediaType: z.ZodOptional<z.ZodString>;
267
+ annotations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
268
+ }, z.core.$strip>>>;
269
+ version: z.ZodOptional<z.ZodObject<{
270
+ 'kici-orchestrator': z.ZodString;
271
+ 'kici-agent': z.ZodString;
272
+ }, z.core.$loose>>;
273
+ }, z.core.$strip>;
274
+ }, z.core.$strip>;
275
+ export type KiciRunDetails = z.infer<typeof kiciRunDetailsSchema>;
276
+ /** KiCI SLSA provenance predicate. */
277
+ export declare const kiciProvenancePredicateSchema: z.ZodObject<{
278
+ buildDefinition: z.ZodObject<{
279
+ resolvedDependencies: z.ZodOptional<z.ZodArray<z.ZodObject<{
280
+ name: z.ZodOptional<z.ZodString>;
281
+ uri: z.ZodOptional<z.ZodString>;
282
+ digest: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
283
+ content: z.ZodOptional<z.ZodString>;
284
+ downloadLocation: z.ZodOptional<z.ZodString>;
285
+ mediaType: z.ZodOptional<z.ZodString>;
286
+ annotations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
287
+ }, z.core.$strip>>>;
288
+ buildType: z.ZodLiteral<"https://kici.dev/buildtypes/workflow/v1">;
289
+ externalParameters: z.ZodObject<{
290
+ workflow: z.ZodObject<{
291
+ repository: z.ZodString;
292
+ ref: z.ZodString;
293
+ path: z.ZodString;
294
+ }, z.core.$strip>;
295
+ }, z.core.$loose>;
296
+ internalParameters: z.ZodOptional<z.ZodObject<{
297
+ commit: z.ZodOptional<z.ZodString>;
298
+ runId: z.ZodOptional<z.ZodString>;
299
+ jobId: z.ZodOptional<z.ZodString>;
300
+ }, z.core.$loose>>;
301
+ }, z.core.$strip>;
302
+ runDetails: z.ZodObject<{
303
+ metadata: z.ZodOptional<z.ZodObject<{
304
+ invocationId: z.ZodOptional<z.ZodString>;
305
+ startedOn: z.ZodOptional<z.ZodString>;
306
+ finishedOn: z.ZodOptional<z.ZodString>;
307
+ }, z.core.$strip>>;
308
+ byproducts: z.ZodOptional<z.ZodArray<z.ZodObject<{
309
+ name: z.ZodOptional<z.ZodString>;
310
+ uri: z.ZodOptional<z.ZodString>;
311
+ digest: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
312
+ content: z.ZodOptional<z.ZodString>;
313
+ downloadLocation: z.ZodOptional<z.ZodString>;
314
+ mediaType: z.ZodOptional<z.ZodString>;
315
+ annotations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
316
+ }, z.core.$strip>>>;
317
+ builder: z.ZodObject<{
318
+ id: z.ZodString;
319
+ builderDependencies: z.ZodOptional<z.ZodArray<z.ZodObject<{
320
+ name: z.ZodOptional<z.ZodString>;
321
+ uri: z.ZodOptional<z.ZodString>;
322
+ digest: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
323
+ content: z.ZodOptional<z.ZodString>;
324
+ downloadLocation: z.ZodOptional<z.ZodString>;
325
+ mediaType: z.ZodOptional<z.ZodString>;
326
+ annotations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
327
+ }, z.core.$strip>>>;
328
+ version: z.ZodOptional<z.ZodObject<{
329
+ 'kici-orchestrator': z.ZodString;
330
+ 'kici-agent': z.ZodString;
331
+ }, z.core.$loose>>;
332
+ }, z.core.$strip>;
333
+ }, z.core.$strip>;
334
+ }, z.core.$strip>;
335
+ export type KiciProvenancePredicate = z.infer<typeof kiciProvenancePredicateSchema>;
336
+ /** KiCI provenance Statement: pins `_type` + `predicateType` + KiCI predicate. */
337
+ export declare const kiciProvenanceStatementSchema: z.ZodObject<{
338
+ _type: z.ZodLiteral<"https://in-toto.io/Statement/v1">;
339
+ subject: z.ZodArray<z.ZodObject<{
340
+ name: z.ZodOptional<z.ZodString>;
341
+ uri: z.ZodOptional<z.ZodString>;
342
+ digest: z.ZodRecord<z.ZodString, z.ZodString>;
343
+ mediaType: z.ZodOptional<z.ZodString>;
344
+ annotations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
345
+ }, z.core.$strip>>;
346
+ predicateType: z.ZodLiteral<"https://slsa.dev/provenance/v1">;
347
+ predicate: z.ZodObject<{
348
+ buildDefinition: z.ZodObject<{
349
+ resolvedDependencies: z.ZodOptional<z.ZodArray<z.ZodObject<{
350
+ name: z.ZodOptional<z.ZodString>;
351
+ uri: z.ZodOptional<z.ZodString>;
352
+ digest: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
353
+ content: z.ZodOptional<z.ZodString>;
354
+ downloadLocation: z.ZodOptional<z.ZodString>;
355
+ mediaType: z.ZodOptional<z.ZodString>;
356
+ annotations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
357
+ }, z.core.$strip>>>;
358
+ buildType: z.ZodLiteral<"https://kici.dev/buildtypes/workflow/v1">;
359
+ externalParameters: z.ZodObject<{
360
+ workflow: z.ZodObject<{
361
+ repository: z.ZodString;
362
+ ref: z.ZodString;
363
+ path: z.ZodString;
364
+ }, z.core.$strip>;
365
+ }, z.core.$loose>;
366
+ internalParameters: z.ZodOptional<z.ZodObject<{
367
+ commit: z.ZodOptional<z.ZodString>;
368
+ runId: z.ZodOptional<z.ZodString>;
369
+ jobId: z.ZodOptional<z.ZodString>;
370
+ }, z.core.$loose>>;
371
+ }, z.core.$strip>;
372
+ runDetails: z.ZodObject<{
373
+ metadata: z.ZodOptional<z.ZodObject<{
374
+ invocationId: z.ZodOptional<z.ZodString>;
375
+ startedOn: z.ZodOptional<z.ZodString>;
376
+ finishedOn: z.ZodOptional<z.ZodString>;
377
+ }, z.core.$strip>>;
378
+ byproducts: z.ZodOptional<z.ZodArray<z.ZodObject<{
379
+ name: z.ZodOptional<z.ZodString>;
380
+ uri: z.ZodOptional<z.ZodString>;
381
+ digest: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
382
+ content: z.ZodOptional<z.ZodString>;
383
+ downloadLocation: z.ZodOptional<z.ZodString>;
384
+ mediaType: z.ZodOptional<z.ZodString>;
385
+ annotations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
386
+ }, z.core.$strip>>>;
387
+ builder: z.ZodObject<{
388
+ id: z.ZodString;
389
+ builderDependencies: z.ZodOptional<z.ZodArray<z.ZodObject<{
390
+ name: z.ZodOptional<z.ZodString>;
391
+ uri: z.ZodOptional<z.ZodString>;
392
+ digest: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
393
+ content: z.ZodOptional<z.ZodString>;
394
+ downloadLocation: z.ZodOptional<z.ZodString>;
395
+ mediaType: z.ZodOptional<z.ZodString>;
396
+ annotations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
397
+ }, z.core.$strip>>>;
398
+ version: z.ZodOptional<z.ZodObject<{
399
+ 'kici-orchestrator': z.ZodString;
400
+ 'kici-agent': z.ZodString;
401
+ }, z.core.$loose>>;
402
+ }, z.core.$strip>;
403
+ }, z.core.$strip>;
404
+ }, z.core.$strip>;
405
+ }, z.core.$strip>;
406
+ export type KiciProvenanceStatement = z.infer<typeof kiciProvenanceStatementSchema>;
407
+ //# sourceMappingURL=schema.d.ts.map
@@ -0,0 +1,143 @@
1
+ import "../chunk-gOLHoazu.js";
2
+ import { z } from "zod";
3
+ //#region src/provenance/schema.ts
4
+ /**
5
+ * SLSA v1.0 build-provenance schema for KiCI.
6
+ *
7
+ * Models the in-toto Statement v1 envelope and the SLSA v1.0 provenance
8
+ * predicate as Zod schemas, plus a KiCI-specialized statement schema that pins
9
+ * the KiCI literals and types the KiCI-owned build parameters. This is the
10
+ * single source of truth shared by the agent (produces attestations) and the
11
+ * `kici verify-attestation` CLI (consumes them).
12
+ *
13
+ * Pure schema + types — no Node-only dependencies, so the dashboard can import
14
+ * it for typed artifact rendering. Exported at the subpath
15
+ * `@kici-dev/engine/provenance/schema`.
16
+ *
17
+ * Spec references:
18
+ * - in-toto Statement v1: https://github.com/in-toto/attestation/blob/main/spec/v1/statement.md
19
+ * - SLSA v1.0 provenance: https://slsa.dev/spec/v1.0/provenance
20
+ */
21
+ /** in-toto Statement `_type` value (pinned). */
22
+ const IN_TOTO_STATEMENT_TYPE = "https://in-toto.io/Statement/v1";
23
+ /** SLSA v1.0 provenance `predicateType` value (pinned). */
24
+ const SLSA_PROVENANCE_PREDICATE_TYPE = "https://slsa.dev/provenance/v1";
25
+ /** KiCI workflow `buildType` URI (we own this namespace). */
26
+ const KICI_WORKFLOW_BUILD_TYPE = "https://kici.dev/buildtypes/workflow/v1";
27
+ /**
28
+ * Known digest algorithms KiCI emits or tests reference. The digest map itself
29
+ * (`digestSetSchema`) keeps its keys open for forward-compatibility; this enum
30
+ * documents the common set so producer code and tests don't repeat literals.
31
+ */
32
+ const DigestAlgorithm = z.enum([
33
+ "sha256",
34
+ "sha512",
35
+ "sha1",
36
+ "gitCommit",
37
+ "dirHash"
38
+ ]);
39
+ /** Lowercase hex string (in-toto requires lowercase-hex digest encoding). */
40
+ const lowercaseHex = z.string().regex(/^[0-9a-f]+$/, "digest value must be lowercase hex");
41
+ /**
42
+ * in-toto digest set: a map of algorithm name → lowercase-hex digest. Keys are
43
+ * open (forward-compat); at least one entry is required.
44
+ */
45
+ const digestSetSchema = z.record(z.string().min(1), lowercaseHex).refine((d) => Object.keys(d).length > 0, { message: "digest must contain at least one algorithm" });
46
+ /**
47
+ * in-toto ResourceDescriptor. Reused for `resolvedDependencies` and
48
+ * `byproducts`. Per spec, at least one of name / uri / digest must be present.
49
+ */
50
+ const resourceDescriptorSchema = z.object({
51
+ name: z.string().optional(),
52
+ uri: z.string().optional(),
53
+ digest: digestSetSchema.optional(),
54
+ content: z.string().optional(),
55
+ downloadLocation: z.string().optional(),
56
+ mediaType: z.string().optional(),
57
+ annotations: z.record(z.string(), z.unknown()).optional()
58
+ }).refine((rd) => rd.name !== void 0 || rd.uri !== void 0 || rd.digest !== void 0, { message: "resource descriptor requires at least one of name, uri, or digest" });
59
+ /**
60
+ * in-toto Statement subject entry: a resource descriptor that MUST carry a
61
+ * digest (the verifier matches the subject digest against the artifact).
62
+ */
63
+ const subjectSchema = z.object({
64
+ name: z.string().optional(),
65
+ uri: z.string().optional(),
66
+ digest: digestSetSchema,
67
+ mediaType: z.string().optional(),
68
+ annotations: z.record(z.string(), z.unknown()).optional()
69
+ });
70
+ /** SLSA `builder`: identity of the build platform. `id` is a required URI. */
71
+ const builderSchema = z.object({
72
+ id: z.string(),
73
+ builderDependencies: z.array(resourceDescriptorSchema).optional(),
74
+ version: z.record(z.string(), z.string()).optional()
75
+ });
76
+ /** SLSA `metadata`: build-invocation metadata. */
77
+ const buildMetadataSchema = z.object({
78
+ invocationId: z.string().optional(),
79
+ startedOn: z.string().datetime({ offset: true }).optional(),
80
+ finishedOn: z.string().datetime({ offset: true }).optional()
81
+ });
82
+ /** SLSA `buildDefinition`. `buildType` + `externalParameters` are required. */
83
+ const buildDefinitionSchema = z.object({
84
+ buildType: z.string(),
85
+ externalParameters: z.record(z.string(), z.unknown()),
86
+ internalParameters: z.record(z.string(), z.unknown()).optional(),
87
+ resolvedDependencies: z.array(resourceDescriptorSchema).optional()
88
+ });
89
+ /** SLSA `runDetails`. `builder` is required. */
90
+ const runDetailsSchema = z.object({
91
+ builder: builderSchema,
92
+ metadata: buildMetadataSchema.optional(),
93
+ byproducts: z.array(resourceDescriptorSchema).optional()
94
+ });
95
+ /** SLSA v1.0 provenance predicate. */
96
+ const slsaProvenancePredicateSchema = z.object({
97
+ buildDefinition: buildDefinitionSchema,
98
+ runDetails: runDetailsSchema
99
+ });
100
+ /** Predicate-agnostic in-toto Statement v1 envelope. */
101
+ const inTotoStatementSchema = z.object({
102
+ _type: z.literal(IN_TOTO_STATEMENT_TYPE),
103
+ subject: z.array(subjectSchema).min(1),
104
+ predicateType: z.string(),
105
+ predicate: z.record(z.string(), z.unknown())
106
+ });
107
+ /** KiCI workflow external parameters: the workflow source coordinates. */
108
+ const kiciWorkflowExternalParametersSchema = z.object({ workflow: z.object({
109
+ repository: z.string(),
110
+ ref: z.string(),
111
+ path: z.string()
112
+ }) }).passthrough();
113
+ /** KiCI workflow internal parameters: run-scoped build context. */
114
+ const kiciWorkflowInternalParametersSchema = z.object({
115
+ commit: z.string().optional(),
116
+ runId: z.string().optional(),
117
+ jobId: z.string().optional()
118
+ }).passthrough();
119
+ /** KiCI build definition: pins the buildType and types the workflow params. */
120
+ const kiciBuildDefinitionSchema = buildDefinitionSchema.extend({
121
+ buildType: z.literal(KICI_WORKFLOW_BUILD_TYPE),
122
+ externalParameters: kiciWorkflowExternalParametersSchema,
123
+ internalParameters: kiciWorkflowInternalParametersSchema.optional()
124
+ });
125
+ /** KiCI run details: types builder.version with the KiCI component versions. */
126
+ const kiciRunDetailsSchema = runDetailsSchema.extend({ builder: builderSchema.extend({ version: z.object({
127
+ "kici-orchestrator": z.string(),
128
+ "kici-agent": z.string()
129
+ }).passthrough().optional() }) });
130
+ /** KiCI SLSA provenance predicate. */
131
+ const kiciProvenancePredicateSchema = z.object({
132
+ buildDefinition: kiciBuildDefinitionSchema,
133
+ runDetails: kiciRunDetailsSchema
134
+ });
135
+ /** KiCI provenance Statement: pins `_type` + `predicateType` + KiCI predicate. */
136
+ const kiciProvenanceStatementSchema = inTotoStatementSchema.extend({
137
+ predicateType: z.literal(SLSA_PROVENANCE_PREDICATE_TYPE),
138
+ predicate: kiciProvenancePredicateSchema
139
+ });
140
+ //#endregion
141
+ export { DigestAlgorithm, IN_TOTO_STATEMENT_TYPE, KICI_WORKFLOW_BUILD_TYPE, SLSA_PROVENANCE_PREDICATE_TYPE, buildDefinitionSchema, buildMetadataSchema, builderSchema, digestSetSchema, inTotoStatementSchema, kiciBuildDefinitionSchema, kiciProvenancePredicateSchema, kiciProvenanceStatementSchema, kiciRunDetailsSchema, kiciWorkflowExternalParametersSchema, kiciWorkflowInternalParametersSchema, resourceDescriptorSchema, runDetailsSchema, slsaProvenancePredicateSchema, subjectSchema };
142
+
143
+ //# sourceMappingURL=schema.js.map
@@ -10,11 +10,26 @@
10
10
  * Schema version 11: adds LockInlineValue type for pure function inline evaluation.
11
11
  * Schema version 14: adds declarative cache specs to LockJob and LockStep.
12
12
  * Schema version 15: adds per-job init config(s) to LockJob.
13
+ * Schema version 16: adds normalized approval config to LockWorkflow/LockJob/LockStep.
13
14
  */
14
15
  import { z } from 'zod';
15
16
  import type { ProviderType } from '../provider/types.js';
17
+ import type { ApproverClause } from '../approval/types.js';
16
18
  /** Schema version - increment on breaking changes */
17
- export declare const SCHEMA_VERSION: 15;
19
+ export declare const SCHEMA_VERSION: 16;
20
+ /**
21
+ * Normalized approval config carried in the lock file. Produced by the compiler
22
+ * from an SDK `requireApproval` at any of the three levels; consumed by the
23
+ * orchestrator dispatch gate (and the agent step round-trip for step scope).
24
+ */
25
+ export interface LockApproval {
26
+ /** AND list of approver clauses; empty means "any approval-capable member". */
27
+ readonly clauses: ApproverClause[];
28
+ /** Human label for the gate. */
29
+ readonly reason?: string;
30
+ /** Per-gate expiry override (seconds); falls back to the org default. */
31
+ readonly timeoutSeconds?: number;
32
+ }
18
33
  /**
19
34
  * Source file reference with meaningful path.
20
35
  * Format: file is relative path from git root, export uses hash syntax.
@@ -315,6 +330,8 @@ export interface LockStep {
315
330
  readonly line: number;
316
331
  readonly column: number;
317
332
  };
333
+ /** Normalized approval gate; when set the step pauses for a human approval. */
334
+ readonly approval?: LockApproval;
318
335
  }
319
336
  /**
320
337
  * Inline expression value for pure dynamic functions.
@@ -391,6 +408,8 @@ export interface LockJob {
391
408
  * (`requests`) and kernel-side enforcement (`limits`) on the spawned agent.
392
409
  */
393
410
  readonly resources?: import('../scaler/resource-types.js').ResourceRequest;
411
+ /** Normalized approval gate; when set the job is held before dispatch. */
412
+ readonly approval?: LockApproval;
394
413
  }
395
414
  /**
396
415
  * Dynamic job generator reference.
@@ -460,6 +479,8 @@ export interface LockWorkflow {
460
479
  };
461
480
  /** Whole-run wall-clock timeout in milliseconds. Read by the orchestrator at run creation to set the run deadline. */
462
481
  readonly timeout?: number;
482
+ /** Normalized approval gate; when set the whole run is held before any job dispatches. */
483
+ readonly approval?: LockApproval;
463
484
  }
464
485
  /**
465
486
  * Complete lock file structure.
@@ -13,9 +13,10 @@ import { z } from "zod";
13
13
  * Schema version 11: adds LockInlineValue type for pure function inline evaluation.
14
14
  * Schema version 14: adds declarative cache specs to LockJob and LockStep.
15
15
  * Schema version 15: adds per-job init config(s) to LockJob.
16
+ * Schema version 16: adds normalized approval config to LockWorkflow/LockJob/LockStep.
16
17
  */
17
18
  /** Schema version - increment on breaking changes */
18
- const SCHEMA_VERSION = 15;
19
+ const SCHEMA_VERSION = 16;
19
20
  /** Type guard for inline expression values */
20
21
  function isLockInlineValue(value) {
21
22
  return typeof value === "object" && value !== null && value._type === "inline";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kici-dev/engine",
3
- "version": "0.1.15",
3
+ "version": "0.1.16",
4
4
  "description": "Shared business logic for the KiCI CI/CD stack: protocol, triggers, state machine, and provider interfaces used by the Platform relay, orchestrator, and compiler.",
5
5
  "keywords": [
6
6
  "ci",
@@ -65,6 +65,10 @@
65
65
  "import": "./dist/protocol/cluster-name.js",
66
66
  "types": "./dist/protocol/cluster-name.d.ts"
67
67
  },
68
+ "./provenance/schema": {
69
+ "import": "./dist/provenance/schema.js",
70
+ "types": "./dist/provenance/schema.d.ts"
71
+ },
68
72
  "./metrics/catalog": {
69
73
  "import": "./dist/metrics/metric-catalog.generated.js",
70
74
  "types": "./dist/metrics/metric-catalog.generated.d.ts"
package/sbom.spdx.json CHANGED
@@ -2,10 +2,10 @@
2
2
  "spdxVersion": "SPDX-2.3",
3
3
  "dataLicense": "CC0-1.0",
4
4
  "SPDXID": "SPDXRef-DOCUMENT",
5
- "name": "@kici-dev/engine@0.1.15",
6
- "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fengine/0.1.15/f9f3b4dd-cddc-43ee-a94e-621967a6b013",
5
+ "name": "@kici-dev/engine@0.1.16",
6
+ "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fengine/0.1.16/33d50570-d86e-4a27-b1c9-26cef35a15c7",
7
7
  "creationInfo": {
8
- "created": "2026-06-11T03:03:20Z",
8
+ "created": "2026-06-12T09:41:34Z",
9
9
  "creators": [
10
10
  "Tool: kici-sbom-generator"
11
11
  ]
@@ -54,7 +54,7 @@
54
54
  {
55
55
  "SPDXID": "SPDXRef-RootPackage",
56
56
  "name": "@kici-dev/engine",
57
- "versionInfo": "0.1.15",
57
+ "versionInfo": "0.1.16",
58
58
  "downloadLocation": "NOASSERTION",
59
59
  "filesAnalyzed": false,
60
60
  "licenseConcluded": "NOASSERTION",
@@ -65,7 +65,7 @@
65
65
  {
66
66
  "referenceCategory": "PACKAGE-MANAGER",
67
67
  "referenceType": "purl",
68
- "referenceLocator": "pkg:npm/%40kici-dev/engine@0.1.15"
68
+ "referenceLocator": "pkg:npm/%40kici-dev/engine@0.1.16"
69
69
  }
70
70
  ],
71
71
  "description": "Shared business logic for the KiCI CI/CD stack: protocol, triggers, state machine, and provider interfaces used by the Platform relay, orchestrator, and compiler.",