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