@signet-registry/operator 0.1.3 → 0.1.5

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/LICENSE CHANGED
@@ -1,6 +1,7 @@
1
1
  BSD 3-Clause License
2
2
 
3
3
  Copyright (c) 2026, Derek C.
4
+ Copyright (c) 2026, Pablo Ferrari (@pabshazon)
4
5
 
5
6
  Redistribution and use in source and binary forms, with or without
6
7
  modification, are permitted provided that the following conditions are met:
@@ -175,6 +175,18 @@ export class HttpRegistryOperatorApiClient {
175
175
  async getSkillPublicationVerification(skillKey, version, apiToken) {
176
176
  return await this.fetchJson(`/v1/skills/${encodeURIComponent(skillKey)}/versions/${version}/verification`, undefined, apiToken);
177
177
  }
178
+ async getSkillProvenance(skillKey, version, apiToken) {
179
+ return await this.fetchJson(`/v1/skills/${encodeURIComponent(skillKey)}/versions/${version}/provenance`, undefined, apiToken);
180
+ }
181
+ async getAgentProvenance(agentKey, version, apiToken) {
182
+ return await this.fetchJson(`/v1/agents/${encodeURIComponent(agentKey)}/versions/${version}/provenance`, undefined, apiToken);
183
+ }
184
+ async getSkillReportSignatures(skillKey, version, apiToken) {
185
+ return await this.fetchJson(`/v1/skills/${encodeURIComponent(skillKey)}/versions/${version}/report-signatures`, undefined, apiToken);
186
+ }
187
+ async getAgentReportSignatures(agentKey, version, apiToken) {
188
+ return await this.fetchJson(`/v1/agents/${encodeURIComponent(agentKey)}/versions/${version}/report-signatures`, undefined, apiToken);
189
+ }
178
190
  async getAgentPublicationVerification(agentKey, version, apiToken) {
179
191
  return await this.fetchJson(`/v1/agents/${encodeURIComponent(agentKey)}/versions/${version}/verification`, undefined, apiToken);
180
192
  }
@@ -11,6 +11,25 @@ function parseSignatureBytes(signature) {
11
11
  }
12
12
  throw new Error('Signature must use a supported encoding prefix such as base64: or hex:.');
13
13
  }
14
+ /**
15
+ * Mirrors the registry's trusted-key resolver: a key is usable only when its
16
+ * status is `trusted` and the current time is inside its validity window
17
+ * (`valid_from` inclusive, `valid_to` exclusive; absent bounds are
18
+ * unlimited). Revoked/expired/not-yet-valid keys must stay out of local
19
+ * verification so CLI verdicts match the server's
20
+ * `trusted_public_key_resolved` semantics.
21
+ */
22
+ export function isTrustedKeyUsableAt(properties, nowIso) {
23
+ if (properties['trust_status'] !== 'trusted')
24
+ return false;
25
+ const validFrom = typeof properties['valid_from'] === 'string' ? properties['valid_from'] : undefined;
26
+ const validTo = typeof properties['valid_to'] === 'string' ? properties['valid_to'] : undefined;
27
+ if (validFrom && nowIso < validFrom)
28
+ return false;
29
+ if (validTo && nowIso >= validTo)
30
+ return false;
31
+ return true;
32
+ }
14
33
  // Mirrors the algorithms accepted by the registry core so operator verification
15
34
  // reproduces the server verdict locally.
16
35
  export function verifyDetachedSignature(input) {
@@ -37,6 +56,41 @@ export function verifyDetachedSignature(input) {
37
56
  return false;
38
57
  }
39
58
  }
59
+ /**
60
+ * Mirrors the registry's verdict logic for detached provenance signatures.
61
+ * Fetch the canonical N-Quads artifact the signature binds
62
+ * (`provenance_sha256`, via \`GET /v1/artifacts/{sha256}\`), pass those bytes
63
+ * here, and pass the current export digest as \`currentProvenanceSha256\` to
64
+ * distinguish \`valid\` from \`stale\` after the provenance has grown.
65
+ */
66
+ export function verifyProvenanceSignature(input) {
67
+ const bytes = typeof input.canonicalRdfBytes === 'string'
68
+ ? Buffer.from(input.canonicalRdfBytes, 'utf8')
69
+ : input.canonicalRdfBytes;
70
+ const digest_matches = sha256Hex(bytes) === input.signature.provenance_sha256;
71
+ const publicKeyPem = input.resolvePublicKey(input.signature.key_ref);
72
+ const signature_valid = digest_matches && publicKeyPem !== undefined
73
+ ? verifyDetachedSignature({
74
+ algorithm: input.signature.algorithm,
75
+ publicKeyPem,
76
+ message: bytes,
77
+ signature: input.signature.signature,
78
+ })
79
+ : false;
80
+ const verdict = !digest_matches || !signature_valid
81
+ ? 'invalid'
82
+ : input.currentProvenanceSha256 !== undefined &&
83
+ input.signature.provenance_sha256 !== input.currentProvenanceSha256
84
+ ? 'stale'
85
+ : 'valid';
86
+ return {
87
+ key_ref: input.signature.key_ref,
88
+ algorithm: input.signature.algorithm,
89
+ digest_matches,
90
+ signature_valid,
91
+ verdict,
92
+ };
93
+ }
40
94
  export function verifyEnvelopeSignatures(input) {
41
95
  const canonical_json_sha256_matches = sha256Hex(Buffer.from(input.envelope.canonical_json, 'utf8')) === input.envelope.canonical_json_sha256;
42
96
  const signatures = input.envelope.detached_signatures.map((signature) => {
package/dist/operator.js CHANGED
@@ -8,7 +8,7 @@ import { cfAccessHeaders, loadEnv } from './config/env.js';
8
8
  import { AgentSeedSpecSchema, BootstrapManifestSchema, SkillSeedSpecSchema, } from './types.js';
9
9
  import { HttpRegistryOperatorApiClient, RegistryOperatorApiError } from './clients/api.js';
10
10
  import { RegistryOperatorMcpClient } from './clients/mcp.js';
11
- import { sha256Hex, verifyEnvelopeSignatures } from './clients/verify.js';
11
+ import { sha256Hex, isTrustedKeyUsableAt, verifyEnvelopeSignatures, verifyProvenanceSignature } from './clients/verify.js';
12
12
  import { buildTransparencySampleGraphSpec, readTransparencySampleGraphSpec, seedTransparencySampleGraph, } from './transparency/sample-graph.js';
13
13
  const AuthCreateApiKeyResultSchema = z.object({
14
14
  token: z.string().min(1),
@@ -49,6 +49,10 @@ export async function runCli(argv) {
49
49
  return await runVerifyPublication(env, command.args);
50
50
  if (command.action === 'artifact')
51
51
  return await runVerifyArtifact(env, command.args);
52
+ if (command.action === 'provenance')
53
+ return await runVerifyProvenance(env, command.args);
54
+ if (command.action === 'report-signatures')
55
+ return await runVerifyReportSignatures(env, command.args);
52
56
  return await runVerifyBrowserSession(env, command.args);
53
57
  case 'bootstrap':
54
58
  return await runBootstrapTest(env, command.args);
@@ -71,7 +75,7 @@ export function parseArgs(argv) {
71
75
  if (group === 'seed' && (action === 'skill' || action === 'agent' || action === 'bootstrap' || action === 'transparency-sample')) {
72
76
  return { group: 'seed', action, args };
73
77
  }
74
- if (group === 'verify' && (action === 'api' || action === 'mcp' || action === 'okta-config' || action === 'browser-session' || action === 'publication' || action === 'artifact')) {
78
+ if (group === 'verify' && (action === 'api' || action === 'mcp' || action === 'okta-config' || action === 'browser-session' || action === 'publication' || action === 'artifact' || action === 'provenance' || action === 'report-signatures')) {
75
79
  return { group: 'verify', action, args };
76
80
  }
77
81
  if (group === 'bootstrap' && action === 'test') {
@@ -439,6 +443,39 @@ async function runVerifyMcp(env, args) {
439
443
  // Non-strict mode passes for a publication with no signatures (vacuous
440
444
  // validity); --strict additionally requires the server verdict, at least one
441
445
  // valid signature, and a matching frozen-envelope artifact when present.
446
+ /**
447
+ * Resolve trusted signing keys to their PEMs (stored as CAS artifacts),
448
+ * mirroring the registry's resolver: the key must be `trusted` and inside
449
+ * its validity window before its PEM is used. Revoked/expired/not-yet-valid
450
+ * keys stay absent so local verdicts match the server's
451
+ * `trusted_public_key_resolved` semantics (a revoked key's signatures must
452
+ * read as invalid, not verified).
453
+ */
454
+ async function loadTrustedPublicKeyPems(api, keyRefs, apiToken) {
455
+ const publicKeys = new Map();
456
+ const now = new Date().toISOString();
457
+ for (const keyRef of new Set(keyRefs)) {
458
+ if (!keyRef)
459
+ continue;
460
+ try {
461
+ const key = await api.getPublicKey(keyRef, apiToken);
462
+ const publicKey = key['public_key'];
463
+ const properties = publicKey?.properties;
464
+ if (!properties || !isTrustedKeyUsableAt(properties, now))
465
+ continue;
466
+ const artifacts = Array.isArray(key['artifacts']) ? key['artifacts'] : [];
467
+ const sha = parseArtifactUrnSha256(artifacts[0]?.artifact_urn);
468
+ if (!sha)
469
+ continue;
470
+ const { bytes } = await api.getArtifactBytes(sha, apiToken);
471
+ publicKeys.set(keyRef, new TextDecoder().decode(bytes));
472
+ }
473
+ catch {
474
+ // Unresolvable or untrusted keys stay absent; their signatures fail verification.
475
+ }
476
+ }
477
+ return publicKeys;
478
+ }
442
479
  async function runVerifyPublication(env, args) {
443
480
  const skillKey = asString(args.skill);
444
481
  const agentKey = asString(args.agent);
@@ -458,26 +495,14 @@ async function runVerifyPublication(env, args) {
458
495
  const signatures = Array.isArray(envelope['detached_signatures'])
459
496
  ? envelope['detached_signatures']
460
497
  : [];
461
- // Resolve every trusted signing key to its PEM (stored as a CAS artifact).
462
- // Keyless signatures carry no registered key: their trust policy lives with
463
- // the registry, so their verdict is taken from the server verification.
464
- const publicKeys = new Map();
465
- for (const keyRef of new Set(signatures.filter((signature) => !signature.keyless).map((signature) => signature.key_ref).filter(Boolean))) {
466
- if (!keyRef)
467
- continue;
468
- try {
469
- const key = await api.getPublicKey(keyRef, apiToken);
470
- const artifacts = Array.isArray(key['artifacts']) ? key['artifacts'] : [];
471
- const sha = parseArtifactUrnSha256(artifacts[0]?.artifact_urn);
472
- if (!sha)
473
- continue;
474
- const { bytes } = await api.getArtifactBytes(sha, apiToken);
475
- publicKeys.set(keyRef, new TextDecoder().decode(bytes));
476
- }
477
- catch {
478
- // Unresolvable keys stay absent; their signatures fail verification.
479
- }
480
- }
498
+ // Resolve every trusted signing key to its PEM, enforcing the same trust
499
+ // status + validity window as the registry. Keyless signatures carry no
500
+ // registered key: their trust policy lives with the registry, so their
501
+ // verdict is taken from the server verification.
502
+ const publicKeys = await loadTrustedPublicKeyPems(api, signatures
503
+ .filter((signature) => !signature.keyless)
504
+ .map((signature) => signature.key_ref)
505
+ .filter((keyRef) => Boolean(keyRef)), apiToken);
481
506
  const clientVerdict = verifyEnvelopeSignatures({
482
507
  envelope: {
483
508
  canonical_json: String(envelope['canonical_json'] ?? ''),
@@ -570,6 +595,205 @@ async function runVerifyPublication(env, args) {
570
595
  throw new Error('Publication did not verify.');
571
596
  }
572
597
  }
598
+ async function runVerifyProvenance(env, args) {
599
+ const skillKey = asString(args.skill);
600
+ const agentKey = asString(args.agent);
601
+ const version = Number(asString(args.version));
602
+ const strict = args.strict === true;
603
+ const apiToken = asString(args['api-token']);
604
+ if ((!skillKey && !agentKey) || (skillKey && agentKey) || !Number.isInteger(version) || version <= 0) {
605
+ throw new Error('Usage: registry-operator verify provenance (--skill <key> | --agent <key>) --version <n> [--strict] [--api-token <token>]');
606
+ }
607
+ const api = new HttpRegistryOperatorApiClient({ apiOrigin: env.API_ORIGIN, extraHeaders: cfAccessHeaders(env) });
608
+ const provenance = skillKey
609
+ ? await api.getSkillProvenance(skillKey, version, apiToken)
610
+ : await api.getAgentProvenance(agentKey, version, apiToken);
611
+ const evidence = provenance['evidence'];
612
+ const currentSha = typeof evidence?.canonical_rdf_sha256 === 'string' ? evidence.canonical_rdf_sha256 : undefined;
613
+ if (!currentSha) {
614
+ throw new Error('Provenance response did not include the canonical export evidence.');
615
+ }
616
+ // Transport integrity: fetch the canonical artifact at its digest and
617
+ // recompute the hash locally.
618
+ const { bytes: currentBytes } = await api.getArtifactBytes(currentSha, apiToken);
619
+ const transportDigestMatches = sha256Hex(currentBytes) === currentSha;
620
+ const servedSignatures = Array.isArray(provenance['provenance_signatures'])
621
+ ? provenance['provenance_signatures']
622
+ : [];
623
+ // Resolve every trusted signing key to its PEM, enforcing the same trust
624
+ // status + validity window as the registry.
625
+ const publicKeys = await loadTrustedPublicKeyPems(api, servedSignatures.map((row) => row.key_ref).filter((keyRef) => Boolean(keyRef)), apiToken);
626
+ // Reproduce each verdict locally: fetch the stored signature record, the
627
+ // canonical artifact it binds, and check the crypto against the key.
628
+ const signatures = [];
629
+ for (const row of servedSignatures) {
630
+ const recordSha = parseArtifactUrnSha256(row.artifact_urn);
631
+ let record = null;
632
+ try {
633
+ if (recordSha) {
634
+ const { bytes } = await api.getArtifactBytes(recordSha, apiToken);
635
+ record = JSON.parse(new TextDecoder().decode(bytes));
636
+ }
637
+ }
638
+ catch {
639
+ // Missing/unreadable signature record: the signature fails verification.
640
+ }
641
+ const key_ref = typeof record?.['key_ref'] === 'string' ? record['key_ref'] : (row.key_ref ?? '');
642
+ const algorithm = typeof record?.['algorithm'] === 'string' ? record['algorithm'] : (row.algorithm ?? '');
643
+ const provenance_sha256 = typeof record?.['provenance_sha256'] === 'string' ? record['provenance_sha256'] : (row.provenance_sha256 ?? '');
644
+ const signature = typeof record?.['signature'] === 'string' ? record['signature'] : undefined;
645
+ if (!signature || !provenance_sha256) {
646
+ signatures.push({ key_ref, algorithm, provenance_sha256, digest_matches: false, signature_valid: false, verdict: 'invalid' });
647
+ continue;
648
+ }
649
+ let signedBytes = null;
650
+ try {
651
+ const { bytes } = await api.getArtifactBytes(provenance_sha256, apiToken);
652
+ signedBytes = bytes;
653
+ }
654
+ catch {
655
+ // Missing/unreadable signed artifact: the signature fails verification.
656
+ }
657
+ if (!signedBytes) {
658
+ signatures.push({ key_ref, algorithm, provenance_sha256, digest_matches: false, signature_valid: false, verdict: 'invalid' });
659
+ continue;
660
+ }
661
+ signatures.push(verifyProvenanceSignature({
662
+ canonicalRdfBytes: signedBytes,
663
+ currentProvenanceSha256: currentSha,
664
+ signature: { key_ref, algorithm, provenance_sha256, signature },
665
+ resolvePublicKey: (ref) => publicKeys.get(ref),
666
+ }));
667
+ }
668
+ const validSignatures = signatures.filter((check) => check.verdict === 'valid').length;
669
+ const staleSignatures = signatures.filter((check) => check.verdict === 'stale').length;
670
+ const invalidSignatures = signatures.filter((check) => check.verdict === 'invalid').length;
671
+ const strictFailures = strict && validSignatures === 0 ? ['no current provenance signature'] : [];
672
+ const verified = transportDigestMatches && invalidSignatures === 0 && strictFailures.length === 0;
673
+ console.log(JSON.stringify({
674
+ entity: provenance['entity'] ?? null,
675
+ strict,
676
+ current_provenance_sha256: currentSha,
677
+ transport_digest_matches: transportDigestMatches,
678
+ signatures,
679
+ valid_signatures: validSignatures,
680
+ stale_signatures: staleSignatures,
681
+ invalid_signatures: invalidSignatures,
682
+ strict_failures: strictFailures,
683
+ verdict: verified ? 'verified' : 'unverified',
684
+ }, null, 2));
685
+ if (!verified) {
686
+ throw new Error('Provenance did not verify.');
687
+ }
688
+ }
689
+ async function runVerifyReportSignatures(env, args) {
690
+ const skillKey = asString(args.skill);
691
+ const agentKey = asString(args.agent);
692
+ const version = Number(asString(args.version));
693
+ const strict = args.strict === true;
694
+ const apiToken = asString(args['api-token']);
695
+ if ((!skillKey && !agentKey) || (skillKey && agentKey) || !Number.isInteger(version) || version <= 0) {
696
+ throw new Error('Usage: registry-operator verify report-signatures (--skill <key> | --agent <key>) --version <n> [--strict] [--api-token <token>]');
697
+ }
698
+ const api = new HttpRegistryOperatorApiClient({ apiOrigin: env.API_ORIGIN, extraHeaders: cfAccessHeaders(env) });
699
+ const served = skillKey
700
+ ? await api.getSkillReportSignatures(skillKey, version, apiToken)
701
+ : await api.getAgentReportSignatures(agentKey, version, apiToken);
702
+ const rows = Array.isArray(served['report_signatures'])
703
+ ? served['report_signatures']
704
+ : [];
705
+ // Resolve every trusted signing key to its PEM, enforcing the same trust
706
+ // status + validity window as the registry.
707
+ const publicKeys = await loadTrustedPublicKeyPems(api, rows.map((row) => row.key_ref).filter((keyRef) => Boolean(keyRef)), apiToken);
708
+ // Reproduce each verdict locally: the stored signature record, the target
709
+ // report (must still declare the signed digest), and the canonical RDF
710
+ // artifact the signature binds.
711
+ const signatures = [];
712
+ for (const row of rows) {
713
+ const recordSha = parseArtifactUrnSha256(row.artifact_urn);
714
+ let record = null;
715
+ try {
716
+ if (recordSha) {
717
+ const { bytes } = await api.getArtifactBytes(recordSha, apiToken);
718
+ record = JSON.parse(new TextDecoder().decode(bytes));
719
+ }
720
+ }
721
+ catch {
722
+ // Missing/unreadable signature record: the row fails verification.
723
+ }
724
+ const key_ref = typeof record?.['key_ref'] === 'string' ? record['key_ref'] : (row.key_ref ?? '');
725
+ const algorithm = typeof record?.['algorithm'] === 'string' ? record['algorithm'] : (row.algorithm ?? '');
726
+ const report_artifact_urn = typeof record?.['report_artifact_urn'] === 'string' ? record['report_artifact_urn'] : (row.report_artifact_urn ?? '');
727
+ const report_canonical_rdf_sha256 = typeof record?.['report_canonical_rdf_sha256'] === 'string'
728
+ ? record['report_canonical_rdf_sha256']
729
+ : (row.report_canonical_rdf_sha256 ?? '');
730
+ const signature = typeof record?.['signature'] === 'string' ? record['signature'] : undefined;
731
+ const failRow = {
732
+ key_ref,
733
+ algorithm,
734
+ report_artifact_present: false,
735
+ digest_matches: false,
736
+ signature_valid: false,
737
+ verdict: 'invalid',
738
+ };
739
+ if (!signature || !report_canonical_rdf_sha256) {
740
+ signatures.push(failRow);
741
+ continue;
742
+ }
743
+ const reportSha = parseArtifactUrnSha256(report_artifact_urn);
744
+ let report_artifact_present = false;
745
+ try {
746
+ if (reportSha) {
747
+ const { bytes } = await api.getArtifactBytes(reportSha, apiToken);
748
+ const parsed = JSON.parse(new TextDecoder().decode(bytes));
749
+ report_artifact_present = parsed.payload?.rdf?.canonical_rdf_sha256 === report_canonical_rdf_sha256;
750
+ }
751
+ }
752
+ catch {
753
+ report_artifact_present = false;
754
+ }
755
+ let signedBytes = null;
756
+ try {
757
+ const { bytes } = await api.getArtifactBytes(report_canonical_rdf_sha256, apiToken);
758
+ signedBytes = bytes;
759
+ }
760
+ catch {
761
+ // Missing/unreadable canonical artifact: the signature fails verification.
762
+ }
763
+ if (!signedBytes) {
764
+ signatures.push({ ...failRow, report_artifact_present });
765
+ continue;
766
+ }
767
+ const check = verifyProvenanceSignature({
768
+ canonicalRdfBytes: signedBytes,
769
+ signature: { key_ref, algorithm, provenance_sha256: report_canonical_rdf_sha256, signature },
770
+ resolvePublicKey: (ref) => publicKeys.get(ref),
771
+ });
772
+ signatures.push({
773
+ key_ref: check.key_ref,
774
+ algorithm: check.algorithm,
775
+ report_artifact_present,
776
+ digest_matches: check.digest_matches,
777
+ signature_valid: check.signature_valid,
778
+ verdict: report_artifact_present && check.verdict === 'valid' ? 'valid' : 'invalid',
779
+ });
780
+ }
781
+ const validSignatures = signatures.filter((check) => check.verdict === 'valid').length;
782
+ const invalidSignatures = signatures.filter((check) => check.verdict === 'invalid').length;
783
+ const strictFailures = strict && validSignatures === 0 ? ['no valid report signature'] : [];
784
+ const verified = invalidSignatures === 0 && strictFailures.length === 0;
785
+ console.log(JSON.stringify({
786
+ strict,
787
+ report_signatures: signatures,
788
+ valid_signatures: validSignatures,
789
+ invalid_signatures: invalidSignatures,
790
+ strict_failures: strictFailures,
791
+ verdict: verified ? 'verified' : 'unverified',
792
+ }, null, 2));
793
+ if (!verified) {
794
+ throw new Error('Report signatures did not verify.');
795
+ }
796
+ }
573
797
  async function runVerifyArtifact(env, args) {
574
798
  const apiToken = asString(args['api-token']);
575
799
  const sha256 = asString(args.sha256) ?? parseArtifactUrnSha256(asString(args['artifact-urn']));
@@ -950,7 +1174,14 @@ async function runSignKeyless(env, args) {
950
1174
  async function createApiKey(env, plane, ownerLabel) {
951
1175
  const serviceDir = plane === 'api' ? path.join(env.REPO_ROOT, 'service', 'api') : path.join(env.REPO_ROOT, 'service', 'mcp');
952
1176
  const hostDatabaseUrl = await resolveHostDatabaseUrlForPlane(env, plane);
953
- const result = await runShell('npm', ['run', '--silent', 'create-api-key', '--', '--owner-label', ownerLabel], {
1177
+ const args = ['run', '--silent', 'create-api-key', '--', '--owner-label', ownerLabel];
1178
+ if (plane === 'api') {
1179
+ // Bootstrap/operator keys need write access: the API defaults
1180
+ // management-created keys to read-only and scope enforcement is on by
1181
+ // default, so seeding would fail with INSUFFICIENT_SCOPE without this.
1182
+ args.push('--scopes', 'read,write');
1183
+ }
1184
+ const result = await runShell('npm', args, {
954
1185
  cwd: serviceDir,
955
1186
  ...(hostDatabaseUrl ? { env: { DATABASE_URL: hostDatabaseUrl } } : {}),
956
1187
  });
package/package.json CHANGED
@@ -1,8 +1,14 @@
1
1
  {
2
2
  "name": "@signet-registry/operator",
3
- "version": "0.1.3",
3
+ "version": "0.1.5",
4
4
  "description": "Operator/assistant CLI for the Signet registry: bootstrap, seed, and verify agents and skills.",
5
5
  "license": "BSD-3-Clause",
6
+ "contributors": [
7
+ {
8
+ "name": "Pablo Ferrari",
9
+ "url": "https://github.com/pabshazon"
10
+ }
11
+ ],
6
12
  "type": "module",
7
13
  "repository": {
8
14
  "type": "git",