@attest-it/core 0.2.0 → 0.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.
package/dist/index.d.ts CHANGED
@@ -4,6 +4,21 @@ import { z } from 'zod';
4
4
  * Core types for attest-it attestation system.
5
5
  * @packageDocumentation
6
6
  */
7
+ /**
8
+ * Key provider configuration in settings.
9
+ * @public
10
+ */
11
+ interface KeyProviderSettings {
12
+ /** Provider type identifier */
13
+ type: string;
14
+ /** Provider-specific options */
15
+ options?: {
16
+ account?: string | undefined;
17
+ itemName?: string | undefined;
18
+ privateKeyPath?: string | undefined;
19
+ vault?: string | undefined;
20
+ } | undefined;
21
+ }
7
22
  /**
8
23
  * Settings from the configuration file.
9
24
  * @public
@@ -17,22 +32,71 @@ interface AttestItSettings {
17
32
  attestationsPath: string;
18
33
  /** Default command to execute for attestation (can be overridden per suite) */
19
34
  defaultCommand?: string;
35
+ /** Key provider configuration for signing attestations */
36
+ keyProvider?: KeyProviderSettings;
37
+ }
38
+ /**
39
+ * Team member configuration.
40
+ * @public
41
+ */
42
+ interface TeamMember {
43
+ /** Display name for the team member */
44
+ name: string;
45
+ /** Email address (optional) */
46
+ email?: string | undefined;
47
+ /** GitHub username (optional) */
48
+ github?: string | undefined;
49
+ /** Base64-encoded Ed25519 public key */
50
+ publicKey: string;
51
+ }
52
+ /**
53
+ * Fingerprint configuration for gates.
54
+ * @public
55
+ */
56
+ interface FingerprintConfig {
57
+ /** Glob patterns for paths to include in fingerprint */
58
+ paths: string[];
59
+ /** Patterns to exclude from fingerprint */
60
+ exclude?: string[] | undefined;
61
+ }
62
+ /**
63
+ * Gate definition - defines what needs to be signed and who can sign it.
64
+ * @public
65
+ */
66
+ interface GateConfig {
67
+ /** Human-readable name for the gate */
68
+ name: string;
69
+ /** Description of what this gate protects */
70
+ description: string;
71
+ /** Team member slugs authorized to sign for this gate */
72
+ authorizedSigners: string[];
73
+ /** Fingerprint configuration */
74
+ fingerprint: FingerprintConfig;
75
+ /** Maximum age before attestation expires (duration string like "30d", "7d", "24h") */
76
+ maxAge: string;
20
77
  }
21
78
  /**
22
79
  * Suite definition from the configuration file.
80
+ * Suites are CLI-layer extensions of gates with command execution capabilities.
23
81
  * @public
24
82
  */
25
83
  interface SuiteConfig {
84
+ /** Reference to a gate (if present, inherits gate configuration) */
85
+ gate?: string;
26
86
  /** Human-readable description of what this suite tests */
27
87
  description?: string;
28
- /** Glob patterns for npm packages to include in fingerprint */
29
- packages: string[];
88
+ /** Glob patterns for npm packages to include in fingerprint (legacy/backward compatibility) */
89
+ packages?: string[];
30
90
  /** Additional file patterns to include in fingerprint */
31
91
  files?: string[];
32
92
  /** Patterns to ignore when computing fingerprint */
33
93
  ignore?: string[];
34
94
  /** Command to execute for this suite (overrides defaultCommand) */
35
95
  command?: string;
96
+ /** Timeout for command execution (duration string) */
97
+ timeout?: string;
98
+ /** Whether the command is interactive */
99
+ interactive?: boolean;
36
100
  /** Other suite names that, when changed, invalidate this suite's attestation */
37
101
  invalidates?: string[];
38
102
  /** Array of suite names this suite depends on */
@@ -47,6 +111,10 @@ interface AttestItConfig {
47
111
  version: 1;
48
112
  /** Global settings for attestation behavior */
49
113
  settings: AttestItSettings;
114
+ /** Team members mapped by slug */
115
+ team?: Record<string, TeamMember>;
116
+ /** Gates defining authorization and fingerprinting */
117
+ gates?: Record<string, GateConfig>;
50
118
  /** Named test suites with their configurations */
51
119
  suites: Record<string, SuiteConfig>;
52
120
  /** Named groups of suites */
@@ -112,70 +180,281 @@ interface SuiteVerificationResult {
112
180
  * Zod schema for the full configuration file.
113
181
  */
114
182
  declare const configSchema: z.ZodObject<{
183
+ gates: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
184
+ authorizedSigners: z.ZodArray<z.ZodString, "many">;
185
+ description: z.ZodString;
186
+ fingerprint: z.ZodObject<{
187
+ exclude: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
188
+ paths: z.ZodArray<z.ZodString, "many">;
189
+ }, "strict", z.ZodTypeAny, {
190
+ exclude?: string[] | undefined;
191
+ paths: string[];
192
+ }, {
193
+ exclude?: string[] | undefined;
194
+ paths: string[];
195
+ }>;
196
+ maxAge: z.ZodEffects<z.ZodString, string, string>;
197
+ name: z.ZodString;
198
+ }, "strict", z.ZodTypeAny, {
199
+ authorizedSigners: string[];
200
+ description: string;
201
+ fingerprint: {
202
+ exclude?: string[] | undefined;
203
+ paths: string[];
204
+ };
205
+ maxAge: string;
206
+ name: string;
207
+ }, {
208
+ authorizedSigners: string[];
209
+ description: string;
210
+ fingerprint: {
211
+ exclude?: string[] | undefined;
212
+ paths: string[];
213
+ };
214
+ maxAge: string;
215
+ name: string;
216
+ }>>>;
115
217
  groups: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>>;
116
218
  settings: z.ZodDefault<z.ZodObject<{
117
219
  attestationsPath: z.ZodDefault<z.ZodString>;
118
220
  defaultCommand: z.ZodOptional<z.ZodString>;
221
+ keyProvider: z.ZodOptional<z.ZodObject<{
222
+ options: z.ZodOptional<z.ZodObject<{
223
+ account: z.ZodOptional<z.ZodString>;
224
+ itemName: z.ZodOptional<z.ZodString>;
225
+ privateKeyPath: z.ZodOptional<z.ZodString>;
226
+ vault: z.ZodOptional<z.ZodString>;
227
+ }, "strict", z.ZodTypeAny, {
228
+ account?: string | undefined;
229
+ itemName?: string | undefined;
230
+ privateKeyPath?: string | undefined;
231
+ vault?: string | undefined;
232
+ }, {
233
+ account?: string | undefined;
234
+ itemName?: string | undefined;
235
+ privateKeyPath?: string | undefined;
236
+ vault?: string | undefined;
237
+ }>>;
238
+ type: z.ZodUnion<[z.ZodEnum<["filesystem", "1password"]>, z.ZodString]>;
239
+ }, "strict", z.ZodTypeAny, {
240
+ options?: {
241
+ account?: string | undefined;
242
+ itemName?: string | undefined;
243
+ privateKeyPath?: string | undefined;
244
+ vault?: string | undefined;
245
+ } | undefined;
246
+ type: string;
247
+ }, {
248
+ options?: {
249
+ account?: string | undefined;
250
+ itemName?: string | undefined;
251
+ privateKeyPath?: string | undefined;
252
+ vault?: string | undefined;
253
+ } | undefined;
254
+ type: string;
255
+ }>>;
119
256
  maxAgeDays: z.ZodDefault<z.ZodNumber>;
120
257
  publicKeyPath: z.ZodDefault<z.ZodString>;
121
258
  }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
122
259
  attestationsPath: z.ZodDefault<z.ZodString>;
123
260
  defaultCommand: z.ZodOptional<z.ZodString>;
261
+ keyProvider: z.ZodOptional<z.ZodObject<{
262
+ options: z.ZodOptional<z.ZodObject<{
263
+ account: z.ZodOptional<z.ZodString>;
264
+ itemName: z.ZodOptional<z.ZodString>;
265
+ privateKeyPath: z.ZodOptional<z.ZodString>;
266
+ vault: z.ZodOptional<z.ZodString>;
267
+ }, "strict", z.ZodTypeAny, {
268
+ account?: string | undefined;
269
+ itemName?: string | undefined;
270
+ privateKeyPath?: string | undefined;
271
+ vault?: string | undefined;
272
+ }, {
273
+ account?: string | undefined;
274
+ itemName?: string | undefined;
275
+ privateKeyPath?: string | undefined;
276
+ vault?: string | undefined;
277
+ }>>;
278
+ type: z.ZodUnion<[z.ZodEnum<["filesystem", "1password"]>, z.ZodString]>;
279
+ }, "strict", z.ZodTypeAny, {
280
+ options?: {
281
+ account?: string | undefined;
282
+ itemName?: string | undefined;
283
+ privateKeyPath?: string | undefined;
284
+ vault?: string | undefined;
285
+ } | undefined;
286
+ type: string;
287
+ }, {
288
+ options?: {
289
+ account?: string | undefined;
290
+ itemName?: string | undefined;
291
+ privateKeyPath?: string | undefined;
292
+ vault?: string | undefined;
293
+ } | undefined;
294
+ type: string;
295
+ }>>;
124
296
  maxAgeDays: z.ZodDefault<z.ZodNumber>;
125
297
  publicKeyPath: z.ZodDefault<z.ZodString>;
126
298
  }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
127
299
  attestationsPath: z.ZodDefault<z.ZodString>;
128
300
  defaultCommand: z.ZodOptional<z.ZodString>;
301
+ keyProvider: z.ZodOptional<z.ZodObject<{
302
+ options: z.ZodOptional<z.ZodObject<{
303
+ account: z.ZodOptional<z.ZodString>;
304
+ itemName: z.ZodOptional<z.ZodString>;
305
+ privateKeyPath: z.ZodOptional<z.ZodString>;
306
+ vault: z.ZodOptional<z.ZodString>;
307
+ }, "strict", z.ZodTypeAny, {
308
+ account?: string | undefined;
309
+ itemName?: string | undefined;
310
+ privateKeyPath?: string | undefined;
311
+ vault?: string | undefined;
312
+ }, {
313
+ account?: string | undefined;
314
+ itemName?: string | undefined;
315
+ privateKeyPath?: string | undefined;
316
+ vault?: string | undefined;
317
+ }>>;
318
+ type: z.ZodUnion<[z.ZodEnum<["filesystem", "1password"]>, z.ZodString]>;
319
+ }, "strict", z.ZodTypeAny, {
320
+ options?: {
321
+ account?: string | undefined;
322
+ itemName?: string | undefined;
323
+ privateKeyPath?: string | undefined;
324
+ vault?: string | undefined;
325
+ } | undefined;
326
+ type: string;
327
+ }, {
328
+ options?: {
329
+ account?: string | undefined;
330
+ itemName?: string | undefined;
331
+ privateKeyPath?: string | undefined;
332
+ vault?: string | undefined;
333
+ } | undefined;
334
+ type: string;
335
+ }>>;
129
336
  maxAgeDays: z.ZodDefault<z.ZodNumber>;
130
337
  publicKeyPath: z.ZodDefault<z.ZodString>;
131
338
  }, z.ZodTypeAny, "passthrough">>>;
132
- suites: z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodObject<{
339
+ suites: z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodObject<{
133
340
  command: z.ZodOptional<z.ZodString>;
134
341
  depends_on: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
135
342
  description: z.ZodOptional<z.ZodString>;
136
343
  files: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
344
+ gate: z.ZodOptional<z.ZodString>;
137
345
  ignore: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
346
+ interactive: z.ZodOptional<z.ZodBoolean>;
138
347
  invalidates: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
139
- packages: z.ZodArray<z.ZodString, "many">;
348
+ packages: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
349
+ timeout: z.ZodOptional<z.ZodString>;
140
350
  }, "strict", z.ZodTypeAny, {
141
351
  command?: string | undefined;
142
352
  depends_on?: string[] | undefined;
143
353
  description?: string | undefined;
144
354
  files?: string[] | undefined;
355
+ gate?: string | undefined;
356
+ ignore?: string[] | undefined;
357
+ interactive?: boolean | undefined;
358
+ invalidates?: string[] | undefined;
359
+ packages?: string[] | undefined;
360
+ timeout?: string | undefined;
361
+ }, {
362
+ command?: string | undefined;
363
+ depends_on?: string[] | undefined;
364
+ description?: string | undefined;
365
+ files?: string[] | undefined;
366
+ gate?: string | undefined;
145
367
  ignore?: string[] | undefined;
368
+ interactive?: boolean | undefined;
146
369
  invalidates?: string[] | undefined;
147
- packages: string[];
370
+ packages?: string[] | undefined;
371
+ timeout?: string | undefined;
372
+ }>, {
373
+ command?: string | undefined;
374
+ depends_on?: string[] | undefined;
375
+ description?: string | undefined;
376
+ files?: string[] | undefined;
377
+ gate?: string | undefined;
378
+ ignore?: string[] | undefined;
379
+ interactive?: boolean | undefined;
380
+ invalidates?: string[] | undefined;
381
+ packages?: string[] | undefined;
382
+ timeout?: string | undefined;
148
383
  }, {
149
384
  command?: string | undefined;
150
385
  depends_on?: string[] | undefined;
151
386
  description?: string | undefined;
152
387
  files?: string[] | undefined;
388
+ gate?: string | undefined;
153
389
  ignore?: string[] | undefined;
390
+ interactive?: boolean | undefined;
154
391
  invalidates?: string[] | undefined;
155
- packages: string[];
392
+ packages?: string[] | undefined;
393
+ timeout?: string | undefined;
156
394
  }>>, Record<string, {
157
395
  command?: string | undefined;
158
396
  depends_on?: string[] | undefined;
159
397
  description?: string | undefined;
160
398
  files?: string[] | undefined;
399
+ gate?: string | undefined;
161
400
  ignore?: string[] | undefined;
401
+ interactive?: boolean | undefined;
162
402
  invalidates?: string[] | undefined;
163
- packages: string[];
403
+ packages?: string[] | undefined;
404
+ timeout?: string | undefined;
164
405
  }>, Record<string, {
165
406
  command?: string | undefined;
166
407
  depends_on?: string[] | undefined;
167
408
  description?: string | undefined;
168
409
  files?: string[] | undefined;
410
+ gate?: string | undefined;
169
411
  ignore?: string[] | undefined;
412
+ interactive?: boolean | undefined;
170
413
  invalidates?: string[] | undefined;
171
- packages: string[];
414
+ packages?: string[] | undefined;
415
+ timeout?: string | undefined;
172
416
  }>>;
417
+ team: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
418
+ email: z.ZodOptional<z.ZodString>;
419
+ github: z.ZodOptional<z.ZodString>;
420
+ name: z.ZodString;
421
+ publicKey: z.ZodString;
422
+ }, "strict", z.ZodTypeAny, {
423
+ email?: string | undefined;
424
+ github?: string | undefined;
425
+ name: string;
426
+ publicKey: string;
427
+ }, {
428
+ email?: string | undefined;
429
+ github?: string | undefined;
430
+ name: string;
431
+ publicKey: string;
432
+ }>>>;
173
433
  version: z.ZodLiteral<1>;
174
434
  }, "strict", z.ZodTypeAny, {
435
+ gates?: Record<string, {
436
+ authorizedSigners: string[];
437
+ description: string;
438
+ fingerprint: {
439
+ exclude?: string[] | undefined;
440
+ paths: string[];
441
+ };
442
+ maxAge: string;
443
+ name: string;
444
+ }> | undefined;
175
445
  groups?: Record<string, string[]> | undefined;
176
446
  settings: {
177
447
  attestationsPath: string;
178
448
  defaultCommand?: string | undefined;
449
+ keyProvider?: {
450
+ options?: {
451
+ account?: string | undefined;
452
+ itemName?: string | undefined;
453
+ privateKeyPath?: string | undefined;
454
+ vault?: string | undefined;
455
+ } | undefined;
456
+ type: string;
457
+ } | undefined;
179
458
  maxAgeDays: number;
180
459
  publicKeyPath: string;
181
460
  } & { [k: string]: unknown };
@@ -184,16 +463,70 @@ declare const configSchema: z.ZodObject<{
184
463
  depends_on?: string[] | undefined;
185
464
  description?: string | undefined;
186
465
  files?: string[] | undefined;
466
+ gate?: string | undefined;
187
467
  ignore?: string[] | undefined;
468
+ interactive?: boolean | undefined;
188
469
  invalidates?: string[] | undefined;
189
- packages: string[];
470
+ packages?: string[] | undefined;
471
+ timeout?: string | undefined;
190
472
  }>;
473
+ team?: Record<string, {
474
+ email?: string | undefined;
475
+ github?: string | undefined;
476
+ name: string;
477
+ publicKey: string;
478
+ }> | undefined;
191
479
  version: 1;
192
480
  }, {
481
+ gates?: Record<string, {
482
+ authorizedSigners: string[];
483
+ description: string;
484
+ fingerprint: {
485
+ exclude?: string[] | undefined;
486
+ paths: string[];
487
+ };
488
+ maxAge: string;
489
+ name: string;
490
+ }> | undefined;
193
491
  groups?: Record<string, string[]> | undefined;
194
492
  settings?: undefined | z.objectInputType<{
195
493
  attestationsPath: z.ZodDefault<z.ZodString>;
196
494
  defaultCommand: z.ZodOptional<z.ZodString>;
495
+ keyProvider: z.ZodOptional<z.ZodObject<{
496
+ options: z.ZodOptional<z.ZodObject<{
497
+ account: z.ZodOptional<z.ZodString>;
498
+ itemName: z.ZodOptional<z.ZodString>;
499
+ privateKeyPath: z.ZodOptional<z.ZodString>;
500
+ vault: z.ZodOptional<z.ZodString>;
501
+ }, "strict", z.ZodTypeAny, {
502
+ account?: string | undefined;
503
+ itemName?: string | undefined;
504
+ privateKeyPath?: string | undefined;
505
+ vault?: string | undefined;
506
+ }, {
507
+ account?: string | undefined;
508
+ itemName?: string | undefined;
509
+ privateKeyPath?: string | undefined;
510
+ vault?: string | undefined;
511
+ }>>;
512
+ type: z.ZodUnion<[z.ZodEnum<["filesystem", "1password"]>, z.ZodString]>;
513
+ }, "strict", z.ZodTypeAny, {
514
+ options?: {
515
+ account?: string | undefined;
516
+ itemName?: string | undefined;
517
+ privateKeyPath?: string | undefined;
518
+ vault?: string | undefined;
519
+ } | undefined;
520
+ type: string;
521
+ }, {
522
+ options?: {
523
+ account?: string | undefined;
524
+ itemName?: string | undefined;
525
+ privateKeyPath?: string | undefined;
526
+ vault?: string | undefined;
527
+ } | undefined;
528
+ type: string;
529
+ }>>;
197
530
  maxAgeDays: z.ZodDefault<z.ZodNumber>;
198
531
  publicKeyPath: z.ZodDefault<z.ZodString>;
199
532
  }, z.ZodTypeAny, "passthrough">;
@@ -202,10 +535,19 @@ declare const configSchema: z.ZodObject<{
202
535
  depends_on?: string[] | undefined;
203
536
  description?: string | undefined;
204
537
  files?: string[] | undefined;
538
+ gate?: string | undefined;
205
539
  ignore?: string[] | undefined;
540
+ interactive?: boolean | undefined;
206
541
  invalidates?: string[] | undefined;
207
- packages: string[];
542
+ packages?: string[] | undefined;
543
+ timeout?: string | undefined;
208
544
  }>;
545
+ team?: Record<string, {
546
+ email?: string | undefined;
547
+ github?: string | undefined;
548
+ name: string;
549
+ publicKey: string;
550
+ }> | undefined;
209
551
  version: 1;
210
552
  }>;
211
553
  /**
@@ -319,7 +661,7 @@ interface FingerprintResult {
319
661
  * Algorithm:
320
662
  * 1. List all files in packages (respecting ignore globs)
321
663
  * 2. Sort files lexicographically by relative path
322
- * 3. For each file: compute SHA256(relativePath + "\0" + content)
664
+ * 3. For each file: compute SHA256(relativePath + ":" + content)
323
665
  * 4. Concatenate all file hashes in sorted order
324
666
  * 5. Compute final SHA256 of concatenated hashes
325
667
  * 6. Return "sha256:" + hex(fingerprint)
@@ -352,8 +694,98 @@ declare function computeFingerprintSync(options: FingerprintOptions): Fingerprin
352
694
  declare function listPackageFiles(packages: string[], ignore?: string[], baseDir?: string): Promise<string[]>;
353
695
 
354
696
  /**
355
- * Attestation file I/O module with JSON canonicalization.
697
+ * Types and interfaces for key provider system.
698
+ *
699
+ * @remarks
700
+ * The key provider system abstracts key storage backends, allowing private keys
701
+ * to be stored in various locations (filesystem, 1Password, etc.) while maintaining
702
+ * a consistent interface for key retrieval and signing operations.
703
+ *
704
+ * @packageDocumentation
705
+ */
706
+ /**
707
+ * Configuration for a key provider instance.
708
+ * @public
356
709
  */
710
+ interface KeyProviderConfig {
711
+ /** Provider type identifier */
712
+ type: string;
713
+ /** Provider-specific configuration */
714
+ options: Record<string, unknown>;
715
+ }
716
+ /**
717
+ * Result of a key retrieval operation.
718
+ * @public
719
+ */
720
+ interface KeyRetrievalResult {
721
+ /**
722
+ * Path to the private key file.
723
+ * For ephemeral providers, this is a temporary file that must be cleaned up.
724
+ */
725
+ keyPath: string;
726
+ /**
727
+ * Cleanup function to call after signing is complete.
728
+ * For filesystem provider, this is a no-op.
729
+ * For 1Password provider, this securely deletes the temp file.
730
+ */
731
+ cleanup: () => Promise<void>;
732
+ }
733
+ /**
734
+ * Result of key generation.
735
+ * @public
736
+ */
737
+ interface KeyGenerationResult {
738
+ /** Path or reference to the private key */
739
+ privateKeyRef: string;
740
+ /** Path to the public key file (always filesystem for commit to repo) */
741
+ publicKeyPath: string;
742
+ /** Human-readable storage location description */
743
+ storageDescription: string;
744
+ }
745
+ /**
746
+ * Options for key generation via provider.
747
+ * @public
748
+ */
749
+ interface KeygenProviderOptions {
750
+ /** Path for public key output (always filesystem) */
751
+ publicKeyPath: string;
752
+ /** Overwrite existing keys */
753
+ force?: boolean;
754
+ }
755
+ /**
756
+ * Abstract interface for key storage providers.
757
+ * @public
758
+ */
759
+ interface KeyProvider {
760
+ /** Unique identifier for this provider type */
761
+ readonly type: string;
762
+ /** Human-readable name for display */
763
+ readonly displayName: string;
764
+ /**
765
+ * Check if this provider is available on the current system.
766
+ */
767
+ isAvailable(): Promise<boolean>;
768
+ /**
769
+ * Check if a key exists in this provider.
770
+ * @param keyRef - Provider-specific key reference
771
+ */
772
+ keyExists(keyRef: string): Promise<boolean>;
773
+ /**
774
+ * Retrieve the private key for signing.
775
+ * Returns a temporary file path that can be passed to OpenSSL.
776
+ * Caller MUST call cleanup() after signing is complete.
777
+ */
778
+ getPrivateKey(keyRef: string): Promise<KeyRetrievalResult>;
779
+ /**
780
+ * Generate a new keypair and store the private key.
781
+ * Public key is always written to filesystem for repository commit.
782
+ */
783
+ generateKeyPair(options: KeygenProviderOptions): Promise<KeyGenerationResult>;
784
+ /**
785
+ * Get the configuration needed to use this provider.
786
+ */
787
+ getConfig(): KeyProviderConfig;
788
+ }
357
789
 
358
790
  /**
359
791
  * Read attestations file from disk (async).
@@ -475,8 +907,12 @@ interface WriteSignedAttestationsOptions {
475
907
  filePath: string;
476
908
  /** Array of attestations to write */
477
909
  attestations: Attestation[];
478
- /** Path to the private key for signing */
479
- privateKeyPath: string;
910
+ /** Path to the private key for signing (legacy) */
911
+ privateKeyPath?: string;
912
+ /** Key provider for signing */
913
+ keyProvider?: KeyProvider;
914
+ /** Key reference for the provider */
915
+ keyRef?: string;
480
916
  }
481
917
  /**
482
918
  * Options for reading and verifying signed attestations.
@@ -562,8 +998,12 @@ interface KeygenOptions {
562
998
  * @public
563
999
  */
564
1000
  interface SignOptions {
565
- /** Path to the private key file */
566
- privateKeyPath: string;
1001
+ /** Path to the private key file (legacy) */
1002
+ privateKeyPath?: string;
1003
+ /** Key provider to use for retrieving the private key */
1004
+ keyProvider?: KeyProvider;
1005
+ /** Key reference for the provider */
1006
+ keyRef?: string;
567
1007
  /** Data to sign (string or Buffer) */
568
1008
  data: Buffer | string;
569
1009
  }
@@ -609,7 +1049,7 @@ declare function getDefaultPublicKeyPath(): string;
609
1049
  * @throws Error if OpenSSL fails or keys exist without force
610
1050
  * @public
611
1051
  */
612
- declare function generateKeyPair(options?: KeygenOptions): Promise<KeyPaths>;
1052
+ declare function generateKeyPair$1(options?: KeygenOptions): Promise<KeyPaths>;
613
1053
  /**
614
1054
  * Sign data using an RSA private key with SHA-256.
615
1055
  *
@@ -621,7 +1061,7 @@ declare function generateKeyPair(options?: KeygenOptions): Promise<KeyPaths>;
621
1061
  * @throws Error if signing fails
622
1062
  * @public
623
1063
  */
624
- declare function sign(options: SignOptions): Promise<string>;
1064
+ declare function sign$1(options: SignOptions): Promise<string>;
625
1065
  /**
626
1066
  * Verify a signature using an RSA public key with SHA-256.
627
1067
  *
@@ -633,7 +1073,7 @@ declare function sign(options: SignOptions): Promise<string>;
633
1073
  * @throws Error if verification fails (not just invalid signature)
634
1074
  * @public
635
1075
  */
636
- declare function verify(options: VerifyOptions$1): Promise<boolean>;
1076
+ declare function verify$1(options: VerifyOptions$1): Promise<boolean>;
637
1077
  /**
638
1078
  * Set restrictive permissions on a private key file.
639
1079
  * @param keyPath - Path to the private key
@@ -641,6 +1081,65 @@ declare function verify(options: VerifyOptions$1): Promise<boolean>;
641
1081
  */
642
1082
  declare function setKeyPermissions(keyPath: string): Promise<void>;
643
1083
 
1084
+ /**
1085
+ * Ed25519 cryptographic operations using Node.js native crypto module.
1086
+ *
1087
+ * @remarks
1088
+ * This module provides Ed25519 digital signature operations using Node.js
1089
+ * native crypto support (available in Node 18+). Ed25519 offers better security
1090
+ * and performance than RSA-2048 with much smaller key and signature sizes.
1091
+ *
1092
+ * @packageDocumentation
1093
+ */
1094
+ /**
1095
+ * An Ed25519 keypair with base64-encoded public key and PEM-encoded private key.
1096
+ * @public
1097
+ */
1098
+ interface KeyPair {
1099
+ /** Base64-encoded public key (raw 32 bytes, ~44 characters) */
1100
+ publicKey: string;
1101
+ /** PEM-encoded private key */
1102
+ privateKey: string;
1103
+ }
1104
+ /**
1105
+ * Generate a new Ed25519 keypair.
1106
+ *
1107
+ * @returns A keypair with base64-encoded public key and PEM-encoded private key
1108
+ * @throws Error if key generation fails
1109
+ * @public
1110
+ */
1111
+ declare function generateKeyPair(): KeyPair;
1112
+ /**
1113
+ * Sign data with an Ed25519 private key.
1114
+ *
1115
+ * @param data - Data to sign (Buffer or UTF-8 string)
1116
+ * @param privateKeyPem - PEM-encoded private key
1117
+ * @returns Base64-encoded signature
1118
+ * @throws Error if signing fails
1119
+ * @public
1120
+ */
1121
+ declare function sign(data: Buffer | string, privateKeyPem: string): string;
1122
+ /**
1123
+ * Verify an Ed25519 signature.
1124
+ *
1125
+ * @param data - Original data that was signed
1126
+ * @param signature - Base64-encoded signature to verify
1127
+ * @param publicKeyBase64 - Base64-encoded public key (raw 32 bytes)
1128
+ * @returns true if signature is valid, false otherwise
1129
+ * @throws Error if verification fails (not just invalid signature)
1130
+ * @public
1131
+ */
1132
+ declare function verify(data: Buffer | string, signature: string, publicKeyBase64: string): boolean;
1133
+ /**
1134
+ * Extract the public key from an Ed25519 private key.
1135
+ *
1136
+ * @param privateKeyPem - PEM-encoded private key
1137
+ * @returns Base64-encoded public key (raw 32 bytes)
1138
+ * @throws Error if extraction fails
1139
+ * @public
1140
+ */
1141
+ declare function getPublicKeyFromPrivate(privateKeyPem: string): string;
1142
+
644
1143
  /**
645
1144
  * Verification logic for attestations.
646
1145
  * @packageDocumentation
@@ -689,6 +1188,679 @@ interface VerifyResult {
689
1188
  */
690
1189
  declare function verifyAttestations(options: VerifyOptions): Promise<VerifyResult>;
691
1190
 
1191
+ /**
1192
+ * Filesystem-based key provider implementation.
1193
+ *
1194
+ * @remarks
1195
+ * This provider stores private keys on the local filesystem, maintaining
1196
+ * backward compatibility with the existing attest-it key storage behavior.
1197
+ *
1198
+ * @packageDocumentation
1199
+ */
1200
+
1201
+ /**
1202
+ * Options for creating a FilesystemKeyProvider.
1203
+ * @public
1204
+ */
1205
+ interface FilesystemKeyProviderOptions {
1206
+ /** Path to the private key file (defaults to OS-specific config dir) */
1207
+ privateKeyPath?: string;
1208
+ }
1209
+ /**
1210
+ * Key provider that stores private keys on the filesystem.
1211
+ *
1212
+ * @remarks
1213
+ * This is the default provider and maintains backward compatibility with
1214
+ * existing attest-it installations. Private keys are stored at:
1215
+ * - macOS/Linux: ~/.config/attest-it/private.pem
1216
+ * - Windows: %APPDATA%\attest-it\private.pem
1217
+ *
1218
+ * @public
1219
+ */
1220
+ declare class FilesystemKeyProvider implements KeyProvider {
1221
+ readonly type = "filesystem";
1222
+ readonly displayName = "Filesystem";
1223
+ private readonly privateKeyPath;
1224
+ /**
1225
+ * Create a new FilesystemKeyProvider.
1226
+ * @param options - Provider options
1227
+ */
1228
+ constructor(options?: FilesystemKeyProviderOptions);
1229
+ /**
1230
+ * Check if this provider is available.
1231
+ * Filesystem provider is always available.
1232
+ */
1233
+ isAvailable(): Promise<boolean>;
1234
+ /**
1235
+ * Check if a key exists at the given path.
1236
+ * @param keyRef - Path to the private key file
1237
+ */
1238
+ keyExists(keyRef: string): Promise<boolean>;
1239
+ /**
1240
+ * Get the private key path for signing.
1241
+ * Returns the path directly with a no-op cleanup function.
1242
+ * @param keyRef - Path to the private key file
1243
+ */
1244
+ getPrivateKey(keyRef: string): Promise<KeyRetrievalResult>;
1245
+ /**
1246
+ * Generate a new keypair and store on filesystem.
1247
+ * @param options - Key generation options
1248
+ */
1249
+ generateKeyPair(options: KeygenProviderOptions): Promise<KeyGenerationResult>;
1250
+ /**
1251
+ * Get the configuration for this provider.
1252
+ */
1253
+ getConfig(): KeyProviderConfig;
1254
+ }
1255
+
1256
+ /**
1257
+ * 1Password-based key provider implementation.
1258
+ *
1259
+ * @remarks
1260
+ * This provider stores private keys in 1Password and retrieves them via the
1261
+ * `op` CLI tool. Keys are downloaded to a temporary file for signing and
1262
+ * securely deleted after use.
1263
+ *
1264
+ * @packageDocumentation
1265
+ */
1266
+
1267
+ /**
1268
+ * Options for creating a OnePasswordKeyProvider.
1269
+ * @public
1270
+ */
1271
+ interface OnePasswordKeyProviderOptions {
1272
+ /** 1Password account email (optional if only one account) */
1273
+ account?: string;
1274
+ /** Vault name or ID where the key is stored */
1275
+ vault: string;
1276
+ /** Item name in 1Password */
1277
+ itemName: string;
1278
+ }
1279
+ /**
1280
+ * Information about a 1Password account.
1281
+ * @public
1282
+ */
1283
+ interface OnePasswordAccount {
1284
+ /** Account UUID */
1285
+ account_uuid: string;
1286
+ /** User email address */
1287
+ email: string;
1288
+ /** Account URL */
1289
+ url: string;
1290
+ /** User UUID */
1291
+ user_uuid: string;
1292
+ }
1293
+ /**
1294
+ * Information about a 1Password vault.
1295
+ * @public
1296
+ */
1297
+ interface OnePasswordVault {
1298
+ /** Vault UUID */
1299
+ id: string;
1300
+ /** Vault name */
1301
+ name: string;
1302
+ }
1303
+ /**
1304
+ * Key provider that stores private keys in 1Password.
1305
+ *
1306
+ * @remarks
1307
+ * This provider requires the `op` CLI tool to be installed and authenticated.
1308
+ * Private keys are stored as documents in 1Password and downloaded to
1309
+ * temporary files for signing operations.
1310
+ *
1311
+ * @public
1312
+ */
1313
+ declare class OnePasswordKeyProvider implements KeyProvider {
1314
+ readonly type = "1password";
1315
+ readonly displayName = "1Password";
1316
+ private readonly account?;
1317
+ private readonly vault;
1318
+ private readonly itemName;
1319
+ /**
1320
+ * Create a new OnePasswordKeyProvider.
1321
+ * @param options - Provider options
1322
+ */
1323
+ constructor(options: OnePasswordKeyProviderOptions);
1324
+ /**
1325
+ * Check if the 1Password CLI is installed.
1326
+ * @returns True if `op` command is available
1327
+ */
1328
+ static isInstalled(): Promise<boolean>;
1329
+ /**
1330
+ * List all 1Password accounts.
1331
+ * @returns Array of account information
1332
+ */
1333
+ static listAccounts(): Promise<OnePasswordAccount[]>;
1334
+ /**
1335
+ * List vaults in a specific account.
1336
+ * @param account - Account email (optional if only one account)
1337
+ * @returns Array of vault information
1338
+ */
1339
+ static listVaults(account?: string): Promise<OnePasswordVault[]>;
1340
+ /**
1341
+ * Check if this provider is available.
1342
+ * Requires `op` CLI to be installed and authenticated.
1343
+ */
1344
+ isAvailable(): Promise<boolean>;
1345
+ /**
1346
+ * Check if a key exists in 1Password.
1347
+ * @param keyRef - Item name in 1Password
1348
+ */
1349
+ keyExists(keyRef: string): Promise<boolean>;
1350
+ /**
1351
+ * Get the private key from 1Password for signing.
1352
+ * Downloads to a temporary file and returns a cleanup function.
1353
+ * @param keyRef - Item name in 1Password
1354
+ * @throws Error if the key does not exist in 1Password
1355
+ */
1356
+ getPrivateKey(keyRef: string): Promise<KeyRetrievalResult>;
1357
+ /**
1358
+ * Generate a new keypair and store private key in 1Password.
1359
+ * Public key is written to filesystem for repository commit.
1360
+ * @param options - Key generation options
1361
+ */
1362
+ generateKeyPair(options: KeygenProviderOptions): Promise<KeyGenerationResult>;
1363
+ /**
1364
+ * Get the configuration for this provider.
1365
+ */
1366
+ getConfig(): KeyProviderConfig;
1367
+ }
1368
+
1369
+ /**
1370
+ * macOS Keychain-based key provider implementation.
1371
+ *
1372
+ * @remarks
1373
+ * This provider stores private keys in the macOS Keychain and retrieves them via the
1374
+ * `security` CLI tool. Keys are stored as base64-encoded strings and downloaded to
1375
+ * temporary files for signing operations, then securely deleted after use.
1376
+ *
1377
+ * @packageDocumentation
1378
+ */
1379
+
1380
+ /**
1381
+ * Options for creating a MacOSKeychainKeyProvider.
1382
+ * @public
1383
+ */
1384
+ interface MacOSKeychainKeyProviderOptions {
1385
+ /** Item name in keychain (e.g., "attest-it-private-key") */
1386
+ itemName: string;
1387
+ /** Path to the keychain file (optional, uses default keychain if not specified) */
1388
+ keychain?: string;
1389
+ }
1390
+ /**
1391
+ * Information about a macOS keychain.
1392
+ * @public
1393
+ */
1394
+ interface MacOSKeychain {
1395
+ /** Full path to the keychain file */
1396
+ path: string;
1397
+ /** Display name (filename without extension) */
1398
+ name: string;
1399
+ }
1400
+ /**
1401
+ * Key provider that stores private keys in macOS Keychain.
1402
+ *
1403
+ * @remarks
1404
+ * This provider requires macOS and uses the `security` CLI tool.
1405
+ * Private keys are stored as base64-encoded strings in the keychain and decoded
1406
+ * to temporary files for signing operations.
1407
+ *
1408
+ * @public
1409
+ */
1410
+ declare class MacOSKeychainKeyProvider implements KeyProvider {
1411
+ readonly type = "macos-keychain";
1412
+ readonly displayName = "macOS Keychain";
1413
+ private readonly itemName;
1414
+ private readonly keychain?;
1415
+ private static readonly ACCOUNT;
1416
+ /**
1417
+ * Create a new MacOSKeychainKeyProvider.
1418
+ * @param options - Provider options
1419
+ */
1420
+ constructor(options: MacOSKeychainKeyProviderOptions);
1421
+ /**
1422
+ * Check if this provider is available.
1423
+ * Only available on macOS platforms.
1424
+ */
1425
+ static isAvailable(): boolean;
1426
+ /**
1427
+ * List available keychains on the system.
1428
+ * @returns Array of keychain information
1429
+ */
1430
+ static listKeychains(): Promise<MacOSKeychain[]>;
1431
+ /**
1432
+ * Check if this provider is available on the current system.
1433
+ */
1434
+ isAvailable(): Promise<boolean>;
1435
+ /**
1436
+ * Check if a key exists in the keychain.
1437
+ * @param keyRef - Item name in keychain
1438
+ */
1439
+ keyExists(keyRef: string): Promise<boolean>;
1440
+ /**
1441
+ * Get the private key from keychain for signing.
1442
+ * Downloads to a temporary file and returns a cleanup function.
1443
+ * @param keyRef - Item name in keychain
1444
+ * @throws Error if the key does not exist in keychain
1445
+ */
1446
+ getPrivateKey(keyRef: string): Promise<KeyRetrievalResult>;
1447
+ /**
1448
+ * Generate a new keypair and store private key in keychain.
1449
+ * Public key is written to filesystem for repository commit.
1450
+ * @param options - Key generation options
1451
+ */
1452
+ generateKeyPair(options: KeygenProviderOptions): Promise<KeyGenerationResult>;
1453
+ /**
1454
+ * Get the configuration for this provider.
1455
+ */
1456
+ getConfig(): KeyProviderConfig;
1457
+ }
1458
+
1459
+ /**
1460
+ * Registry for key provider implementations.
1461
+ *
1462
+ * @remarks
1463
+ * The registry maintains a mapping of provider types to factory functions,
1464
+ * allowing dynamic creation of key providers based on configuration.
1465
+ *
1466
+ * @packageDocumentation
1467
+ */
1468
+
1469
+ /**
1470
+ * Type for a key provider factory function.
1471
+ * @public
1472
+ */
1473
+ type KeyProviderFactory = (config: KeyProviderConfig) => KeyProvider;
1474
+ /**
1475
+ * Registry for key provider implementations.
1476
+ *
1477
+ * @remarks
1478
+ * The registry allows registration of custom key providers and provides
1479
+ * a factory method to create provider instances from configuration.
1480
+ *
1481
+ * Note: This class is used as a namespace for static methods.
1482
+ * @public
1483
+ */
1484
+ declare class KeyProviderRegistry {
1485
+ private static providers;
1486
+ /**
1487
+ * Register a key provider factory.
1488
+ * @param type - Provider type identifier
1489
+ * @param factory - Factory function to create provider instances
1490
+ */
1491
+ static register(type: string, factory: KeyProviderFactory): void;
1492
+ /**
1493
+ * Create a key provider from configuration.
1494
+ * @param config - Provider configuration
1495
+ * @returns A key provider instance
1496
+ * @throws Error if the provider type is not registered
1497
+ */
1498
+ static create(config: KeyProviderConfig): KeyProvider;
1499
+ /**
1500
+ * Get all registered provider types.
1501
+ * @returns Array of provider type identifiers
1502
+ */
1503
+ static getProviderTypes(): string[];
1504
+ }
1505
+
1506
+ /**
1507
+ * Identity system types for attest-it v2.0.
1508
+ * @packageDocumentation
1509
+ */
1510
+ /**
1511
+ * Private key reference - points to where the key is stored.
1512
+ * @public
1513
+ */
1514
+ type PrivateKeyRef = {
1515
+ account: string;
1516
+ keychain?: string;
1517
+ service: string;
1518
+ type: 'keychain';
1519
+ } | {
1520
+ account?: string;
1521
+ field?: string;
1522
+ item: string;
1523
+ type: '1password';
1524
+ vault: string;
1525
+ } | {
1526
+ path: string;
1527
+ type: 'file';
1528
+ };
1529
+ /**
1530
+ * A single identity configuration.
1531
+ * @public
1532
+ */
1533
+ interface Identity {
1534
+ /** Identity name (unique identifier) */
1535
+ name: string;
1536
+ /** Email address associated with this identity */
1537
+ email?: string;
1538
+ /** GitHub username associated with this identity */
1539
+ github?: string;
1540
+ /** Base64 Ed25519 public key */
1541
+ publicKey: string;
1542
+ /** Reference to where the private key is stored */
1543
+ privateKey: PrivateKeyRef;
1544
+ }
1545
+ /**
1546
+ * The local config file structure at ~/.config/attest-it/config.yaml.
1547
+ * @public
1548
+ */
1549
+ interface LocalConfig {
1550
+ /** Name of the currently active identity */
1551
+ activeIdentity: string;
1552
+ /** Map of identity names to identity configurations */
1553
+ identities: Record<string, Identity>;
1554
+ }
1555
+
1556
+ /**
1557
+ * Configuration loading for local identity system.
1558
+ * @packageDocumentation
1559
+ */
1560
+
1561
+ /**
1562
+ * Set a custom home directory for attest-it configuration.
1563
+ * This is useful for testing or running with isolated state.
1564
+ *
1565
+ * @param dir - The directory to use, or null to reset to default
1566
+ * @public
1567
+ */
1568
+ declare function setAttestItHomeDir(dir: null | string): void;
1569
+ /**
1570
+ * Get the current attest-it home directory override.
1571
+ *
1572
+ * @returns The override directory, or null if using default
1573
+ * @public
1574
+ */
1575
+ declare function getAttestItHomeDir(): null | string;
1576
+ /**
1577
+ * Error thrown when local config validation fails.
1578
+ * @public
1579
+ */
1580
+ declare class LocalConfigValidationError extends Error {
1581
+ readonly issues: z.ZodIssue[];
1582
+ constructor(message: string, issues: z.ZodIssue[]);
1583
+ }
1584
+ /**
1585
+ * Get the path to the local config file.
1586
+ *
1587
+ * If a home directory override is set via setAttestItHomeDir(),
1588
+ * returns {homeDir}/config.yaml. Otherwise returns ~/.config/attest-it/config.yaml.
1589
+ *
1590
+ * @returns Path to the local config file
1591
+ * @public
1592
+ */
1593
+ declare function getLocalConfigPath(): string;
1594
+ /**
1595
+ * Get the attest-it configuration directory.
1596
+ *
1597
+ * If a home directory override is set via setAttestItHomeDir(),
1598
+ * returns that directory. Otherwise returns ~/.config/attest-it.
1599
+ *
1600
+ * @returns Path to the configuration directory
1601
+ * @public
1602
+ */
1603
+ declare function getAttestItConfigDir(): string;
1604
+ /**
1605
+ * Load and validate local config from file (async).
1606
+ *
1607
+ * @param configPath - Optional path to config file. If not provided, uses default location.
1608
+ * @returns Validated LocalConfig object, or null if file does not exist
1609
+ * @throws {LocalConfigValidationError} If validation fails
1610
+ * @public
1611
+ */
1612
+ declare function loadLocalConfig(configPath?: string): Promise<LocalConfig | null>;
1613
+ /**
1614
+ * Load and validate local config from file (sync).
1615
+ *
1616
+ * @param configPath - Optional path to config file. If not provided, uses default location.
1617
+ * @returns Validated LocalConfig object, or null if file does not exist
1618
+ * @throws {LocalConfigValidationError} If validation fails
1619
+ * @public
1620
+ */
1621
+ declare function loadLocalConfigSync(configPath?: string): LocalConfig | null;
1622
+ /**
1623
+ * Save local config to file (async).
1624
+ *
1625
+ * @param config - LocalConfig object to save
1626
+ * @param configPath - Optional path to config file. If not provided, uses default location.
1627
+ * @throws {Error} If write fails
1628
+ * @public
1629
+ */
1630
+ declare function saveLocalConfig(config: LocalConfig, configPath?: string): Promise<void>;
1631
+ /**
1632
+ * Save local config to file (sync).
1633
+ *
1634
+ * @param config - LocalConfig object to save
1635
+ * @param configPath - Optional path to config file. If not provided, uses default location.
1636
+ * @throws {Error} If write fails
1637
+ * @public
1638
+ */
1639
+ declare function saveLocalConfigSync(config: LocalConfig, configPath?: string): void;
1640
+ /**
1641
+ * Get the active identity from a config.
1642
+ *
1643
+ * @param config - LocalConfig object
1644
+ * @returns The active Identity, or undefined if not found
1645
+ * @public
1646
+ */
1647
+ declare function getActiveIdentity(config: LocalConfig): Identity | undefined;
1648
+
1649
+ /**
1650
+ * Authorization logic for attest-it v2.0.
1651
+ * @packageDocumentation
1652
+ */
1653
+
1654
+ /**
1655
+ * Check if a public key belongs to an authorized signer for a gate.
1656
+ *
1657
+ * @param config - The attest-it configuration
1658
+ * @param gateId - The gate identifier (slug)
1659
+ * @param publicKey - Base64-encoded Ed25519 public key to check
1660
+ * @returns true if the public key belongs to an authorized signer for the gate
1661
+ * @public
1662
+ */
1663
+ declare function isAuthorizedSigner(config: AttestItConfig, gateId: string, publicKey: string): boolean;
1664
+ /**
1665
+ * Get all team members authorized to sign for a gate.
1666
+ *
1667
+ * @param config - The attest-it configuration
1668
+ * @param gateId - The gate identifier (slug)
1669
+ * @returns Array of authorized team members, or empty array if gate not found
1670
+ * @public
1671
+ */
1672
+ declare function getAuthorizedSignersForGate(config: AttestItConfig, gateId: string): TeamMember[];
1673
+ /**
1674
+ * Find a team member by their public key.
1675
+ *
1676
+ * @param config - The attest-it configuration
1677
+ * @param publicKey - Base64-encoded Ed25519 public key
1678
+ * @returns The team member with matching public key, or undefined if not found
1679
+ * @public
1680
+ */
1681
+ declare function findTeamMemberByPublicKey(config: AttestItConfig, publicKey: string): TeamMember | undefined;
1682
+ /**
1683
+ * Get the gate configuration for a given gate ID.
1684
+ *
1685
+ * @param config - The attest-it configuration
1686
+ * @param gateId - The gate identifier (slug)
1687
+ * @returns The gate configuration, or undefined if not found
1688
+ * @public
1689
+ */
1690
+ declare function getGate(config: AttestItConfig, gateId: string): GateConfig | undefined;
1691
+ /**
1692
+ * Parse a duration string to milliseconds.
1693
+ * Uses the ms library to parse strings like "30d", "7d", "24h".
1694
+ *
1695
+ * @param duration - Duration string (e.g., "30d", "7d", "24h")
1696
+ * @returns Duration in milliseconds
1697
+ * @throws {Error} If duration string is invalid
1698
+ * @public
1699
+ */
1700
+ declare function parseDuration(duration: string): number;
1701
+
1702
+ /**
1703
+ * Seal types for attest-it v2.0.
1704
+ * @packageDocumentation
1705
+ */
1706
+ /**
1707
+ * A seal represents a cryptographic attestation that a gate's fingerprint
1708
+ * was signed by an authorized team member.
1709
+ * @public
1710
+ */
1711
+ interface Seal {
1712
+ /** Gate identifier (slug) */
1713
+ gateId: string;
1714
+ /** SHA-256 fingerprint of the gate's content in format "sha256:..." */
1715
+ fingerprint: string;
1716
+ /** ISO 8601 timestamp when the seal was created */
1717
+ timestamp: string;
1718
+ /** Team member slug who created the seal */
1719
+ sealedBy: string;
1720
+ /** Base64-encoded Ed25519 signature of gateId:fingerprint:timestamp */
1721
+ signature: string;
1722
+ }
1723
+ /**
1724
+ * The seals file structure stored at .attest-it/seals.json.
1725
+ * @public
1726
+ */
1727
+ interface SealsFile {
1728
+ /** Schema version for forward compatibility */
1729
+ version: 1;
1730
+ /** Map of gate slugs to their seals */
1731
+ seals: Record<string, Seal>;
1732
+ }
1733
+
1734
+ /**
1735
+ * Seal operations for creating, verifying, and managing seals.
1736
+ * @packageDocumentation
1737
+ */
1738
+
1739
+ /**
1740
+ * Options for creating a seal.
1741
+ * @public
1742
+ */
1743
+ interface CreateSealOptions {
1744
+ /** Gate identifier (slug) */
1745
+ gateId: string;
1746
+ /** SHA-256 fingerprint of the gate's content */
1747
+ fingerprint: string;
1748
+ /** Team member slug creating the seal */
1749
+ sealedBy: string;
1750
+ /** PEM-encoded Ed25519 private key for signing */
1751
+ privateKey: string;
1752
+ }
1753
+ /**
1754
+ * Result of seal signature verification.
1755
+ * @public
1756
+ */
1757
+ interface SignatureVerificationResult {
1758
+ /** Whether the seal signature is valid */
1759
+ valid: boolean;
1760
+ /** Error message if verification failed */
1761
+ error?: string;
1762
+ }
1763
+ /**
1764
+ * Create a seal by signing the canonical string: gateId:fingerprint:timestamp
1765
+ *
1766
+ * @param options - Seal creation options
1767
+ * @returns The created seal
1768
+ * @throws Error if signing fails
1769
+ * @public
1770
+ */
1771
+ declare function createSeal(options: CreateSealOptions): Seal;
1772
+ /**
1773
+ * Verify a seal's signature against the team member's public key.
1774
+ *
1775
+ * @param seal - The seal to verify
1776
+ * @param config - The attest-it configuration containing team members
1777
+ * @returns Verification result with success status and optional error message
1778
+ * @public
1779
+ */
1780
+ declare function verifySeal(seal: Seal, config: AttestItConfig): SignatureVerificationResult;
1781
+ /**
1782
+ * Read seals from the seals.json file (async).
1783
+ *
1784
+ * @param dir - Directory containing .attest-it/seals.json
1785
+ * @returns The seals file contents, or an empty seals file if the file doesn't exist
1786
+ * @throws Error if file exists but cannot be read or parsed
1787
+ * @public
1788
+ */
1789
+ declare function readSeals(dir: string): Promise<SealsFile>;
1790
+ /**
1791
+ * Read seals from the seals.json file (sync).
1792
+ *
1793
+ * @param dir - Directory containing .attest-it/seals.json
1794
+ * @returns The seals file contents, or an empty seals file if the file doesn't exist
1795
+ * @throws Error if file exists but cannot be read or parsed
1796
+ * @public
1797
+ */
1798
+ declare function readSealsSync(dir: string): SealsFile;
1799
+ /**
1800
+ * Write seals to the seals.json file (async).
1801
+ *
1802
+ * @param dir - Directory containing .attest-it/seals.json
1803
+ * @param sealsFile - The seals file to write
1804
+ * @throws Error if file cannot be written
1805
+ * @public
1806
+ */
1807
+ declare function writeSeals(dir: string, sealsFile: SealsFile): Promise<void>;
1808
+ /**
1809
+ * Write seals to the seals.json file (sync).
1810
+ *
1811
+ * @param dir - Directory containing .attest-it/seals.json
1812
+ * @param sealsFile - The seals file to write
1813
+ * @throws Error if file cannot be written
1814
+ * @public
1815
+ */
1816
+ declare function writeSealsSync(dir: string, sealsFile: SealsFile): void;
1817
+
1818
+ /**
1819
+ * Seal verification logic and states.
1820
+ * @packageDocumentation
1821
+ */
1822
+
1823
+ /**
1824
+ * Verification state for a gate's seal.
1825
+ * @public
1826
+ */
1827
+ type VerificationState = 'FINGERPRINT_MISMATCH' | 'INVALID_SIGNATURE' | 'MISSING' | 'STALE' | 'UNKNOWN_SIGNER' | 'VALID';
1828
+ /**
1829
+ * Result of verifying a single gate's seal.
1830
+ * @public
1831
+ */
1832
+ interface SealVerificationResult {
1833
+ /** Gate identifier */
1834
+ gateId: string;
1835
+ /** Verification state */
1836
+ state: VerificationState;
1837
+ /** The seal, if one exists */
1838
+ seal?: Seal;
1839
+ /** Human-readable message explaining the state */
1840
+ message?: string;
1841
+ }
1842
+ /**
1843
+ * Verify a single gate's seal.
1844
+ *
1845
+ * @param config - The attest-it configuration
1846
+ * @param gateId - Gate identifier to verify
1847
+ * @param seals - The seals file containing all seals
1848
+ * @param currentFingerprint - Current computed fingerprint for the gate
1849
+ * @returns Verification result for the gate
1850
+ * @public
1851
+ */
1852
+ declare function verifyGateSeal(config: AttestItConfig, gateId: string, seals: SealsFile, currentFingerprint: string): SealVerificationResult;
1853
+ /**
1854
+ * Verify all gates' seals.
1855
+ *
1856
+ * @param config - The attest-it configuration
1857
+ * @param seals - The seals file containing all seals
1858
+ * @param fingerprints - Map of gate IDs to their current fingerprints
1859
+ * @returns Array of verification results for all gates
1860
+ * @public
1861
+ */
1862
+ declare function verifyAllSeals(config: AttestItConfig, seals: SealsFile, fingerprints: Record<string, string>): SealVerificationResult[];
1863
+
692
1864
  /**
693
1865
  * @attest-it/core
694
1866
  *
@@ -701,4 +1873,4 @@ declare function verifyAttestations(options: VerifyOptions): Promise<VerifyResul
701
1873
  */
702
1874
  declare const version = "0.0.0";
703
1875
 
704
- export { type AttestItConfig, type AttestItSettings, type Attestation, type AttestationsFile, type Config, ConfigNotFoundError, ConfigValidationError, type VerifyOptions$1 as CryptoVerifyOptions, type FingerprintOptions, type FingerprintResult, type KeyPaths, type KeygenOptions, type ReadSignedAttestationsOptions, type SignOptions, SignatureInvalidError, type SuiteConfig, type SuiteVerificationResult, type VerificationStatus, type VerifyOptions, type VerifyResult, type WriteSignedAttestationsOptions, canonicalizeAttestations, checkOpenSSL, computeFingerprint, computeFingerprintSync, createAttestation, findAttestation, findConfigPath, generateKeyPair, getDefaultPrivateKeyPath, getDefaultPublicKeyPath, listPackageFiles, loadConfig, loadConfigSync, readAndVerifyAttestations, readAttestations, readAttestationsSync, removeAttestation, resolveConfigPaths, setKeyPermissions, sign, toAttestItConfig, upsertAttestation, verify, verifyAttestations, version, writeAttestations, writeAttestationsSync, writeSignedAttestations };
1876
+ export { type AttestItConfig, type AttestItSettings, type Attestation, type AttestationsFile, type Config, ConfigNotFoundError, ConfigValidationError, type CreateSealOptions, type VerifyOptions$1 as CryptoVerifyOptions, type KeyPair as Ed25519KeyPair, FilesystemKeyProvider, type FilesystemKeyProviderOptions, type FingerprintConfig, type FingerprintOptions, type FingerprintResult, type GateConfig, type Identity, type KeyGenerationResult, type KeyPaths, type KeyProvider, type KeyProviderConfig, type KeyProviderFactory, KeyProviderRegistry, type KeyProviderSettings, type KeyRetrievalResult, type KeygenOptions, type KeygenProviderOptions, type LocalConfig, LocalConfigValidationError, type MacOSKeychain, MacOSKeychainKeyProvider, type MacOSKeychainKeyProviderOptions, type OnePasswordAccount, OnePasswordKeyProvider, type OnePasswordKeyProviderOptions, type OnePasswordVault, type PrivateKeyRef, type ReadSignedAttestationsOptions, type Seal, type SealVerificationResult, type SealsFile, type SignOptions, SignatureInvalidError, type SignatureVerificationResult, type SuiteConfig, type SuiteVerificationResult, type TeamMember, type VerificationState, type VerificationStatus, type VerifyOptions, type VerifyResult, type WriteSignedAttestationsOptions, canonicalizeAttestations, checkOpenSSL, computeFingerprint, computeFingerprintSync, createAttestation, createSeal, findAttestation, findConfigPath, findTeamMemberByPublicKey, generateKeyPair as generateEd25519KeyPair, generateKeyPair$1 as generateKeyPair, getActiveIdentity, getAttestItConfigDir, getAttestItHomeDir, getAuthorizedSignersForGate, getDefaultPrivateKeyPath, getDefaultPublicKeyPath, getGate, getLocalConfigPath, getPublicKeyFromPrivate, isAuthorizedSigner, listPackageFiles, loadConfig, loadConfigSync, loadLocalConfig, loadLocalConfigSync, parseDuration, readAndVerifyAttestations, readAttestations, readAttestationsSync, readSeals, readSealsSync, removeAttestation, resolveConfigPaths, saveLocalConfig, saveLocalConfigSync, setAttestItHomeDir, setKeyPermissions, sign$1 as sign, sign as signEd25519, toAttestItConfig, upsertAttestation, verify$1 as verify, verifyAllSeals, verifyAttestations, verify as verifyEd25519, verifyGateSeal, verifySeal, version, writeAttestations, writeAttestationsSync, writeSeals, writeSealsSync, writeSignedAttestations };