@signet-registry/operator 0.1.3 → 0.1.4

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,12 @@ 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
+ }
178
184
  async getAgentPublicationVerification(agentKey, version, apiToken) {
179
185
  return await this.fetchJson(`/v1/agents/${encodeURIComponent(agentKey)}/versions/${version}/verification`, undefined, apiToken);
180
186
  }
@@ -37,6 +37,41 @@ export function verifyDetachedSignature(input) {
37
37
  return false;
38
38
  }
39
39
  }
40
+ /**
41
+ * Mirrors the registry's verdict logic for detached provenance signatures.
42
+ * Fetch the canonical N-Quads artifact the signature binds
43
+ * (`provenance_sha256`, via \`GET /v1/artifacts/{sha256}\`), pass those bytes
44
+ * here, and pass the current export digest as \`currentProvenanceSha256\` to
45
+ * distinguish \`valid\` from \`stale\` after the provenance has grown.
46
+ */
47
+ export function verifyProvenanceSignature(input) {
48
+ const bytes = typeof input.canonicalRdfBytes === 'string'
49
+ ? Buffer.from(input.canonicalRdfBytes, 'utf8')
50
+ : input.canonicalRdfBytes;
51
+ const digest_matches = sha256Hex(bytes) === input.signature.provenance_sha256;
52
+ const publicKeyPem = input.resolvePublicKey(input.signature.key_ref);
53
+ const signature_valid = digest_matches && publicKeyPem !== undefined
54
+ ? verifyDetachedSignature({
55
+ algorithm: input.signature.algorithm,
56
+ publicKeyPem,
57
+ message: bytes,
58
+ signature: input.signature.signature,
59
+ })
60
+ : false;
61
+ const verdict = !digest_matches || !signature_valid
62
+ ? 'invalid'
63
+ : input.currentProvenanceSha256 !== undefined &&
64
+ input.signature.provenance_sha256 !== input.currentProvenanceSha256
65
+ ? 'stale'
66
+ : 'valid';
67
+ return {
68
+ key_ref: input.signature.key_ref,
69
+ algorithm: input.signature.algorithm,
70
+ digest_matches,
71
+ signature_valid,
72
+ verdict,
73
+ };
74
+ }
40
75
  export function verifyEnvelopeSignatures(input) {
41
76
  const canonical_json_sha256_matches = sha256Hex(Buffer.from(input.envelope.canonical_json, 'utf8')) === input.envelope.canonical_json_sha256;
42
77
  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, 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,8 @@ 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);
52
54
  return await runVerifyBrowserSession(env, command.args);
53
55
  case 'bootstrap':
54
56
  return await runBootstrapTest(env, command.args);
@@ -71,7 +73,7 @@ export function parseArgs(argv) {
71
73
  if (group === 'seed' && (action === 'skill' || action === 'agent' || action === 'bootstrap' || action === 'transparency-sample')) {
72
74
  return { group: 'seed', action, args };
73
75
  }
74
- if (group === 'verify' && (action === 'api' || action === 'mcp' || action === 'okta-config' || action === 'browser-session' || action === 'publication' || action === 'artifact')) {
76
+ if (group === 'verify' && (action === 'api' || action === 'mcp' || action === 'okta-config' || action === 'browser-session' || action === 'publication' || action === 'artifact' || action === 'provenance')) {
75
77
  return { group: 'verify', action, args };
76
78
  }
77
79
  if (group === 'bootstrap' && action === 'test') {
@@ -570,6 +572,112 @@ async function runVerifyPublication(env, args) {
570
572
  throw new Error('Publication did not verify.');
571
573
  }
572
574
  }
575
+ async function runVerifyProvenance(env, args) {
576
+ const skillKey = asString(args.skill);
577
+ const agentKey = asString(args.agent);
578
+ const version = Number(asString(args.version));
579
+ const strict = args.strict === true;
580
+ const apiToken = asString(args['api-token']);
581
+ if ((!skillKey && !agentKey) || (skillKey && agentKey) || !Number.isInteger(version) || version <= 0) {
582
+ throw new Error('Usage: registry-operator verify provenance (--skill <key> | --agent <key>) --version <n> [--strict] [--api-token <token>]');
583
+ }
584
+ const api = new HttpRegistryOperatorApiClient({ apiOrigin: env.API_ORIGIN, extraHeaders: cfAccessHeaders(env) });
585
+ const provenance = skillKey
586
+ ? await api.getSkillProvenance(skillKey, version, apiToken)
587
+ : await api.getAgentProvenance(agentKey, version, apiToken);
588
+ const evidence = provenance['evidence'];
589
+ const currentSha = typeof evidence?.canonical_rdf_sha256 === 'string' ? evidence.canonical_rdf_sha256 : undefined;
590
+ if (!currentSha) {
591
+ throw new Error('Provenance response did not include the canonical export evidence.');
592
+ }
593
+ // Transport integrity: fetch the canonical artifact at its digest and
594
+ // recompute the hash locally.
595
+ const { bytes: currentBytes } = await api.getArtifactBytes(currentSha, apiToken);
596
+ const transportDigestMatches = sha256Hex(currentBytes) === currentSha;
597
+ const servedSignatures = Array.isArray(provenance['provenance_signatures'])
598
+ ? provenance['provenance_signatures']
599
+ : [];
600
+ // Resolve every trusted signing key to its PEM (stored as a CAS artifact).
601
+ const publicKeys = new Map();
602
+ for (const keyRef of new Set(servedSignatures.map((row) => row.key_ref).filter(Boolean))) {
603
+ if (!keyRef)
604
+ continue;
605
+ try {
606
+ const key = await api.getPublicKey(keyRef, apiToken);
607
+ const artifacts = Array.isArray(key['artifacts']) ? key['artifacts'] : [];
608
+ const sha = parseArtifactUrnSha256(artifacts[0]?.artifact_urn);
609
+ if (!sha)
610
+ continue;
611
+ const { bytes } = await api.getArtifactBytes(sha, apiToken);
612
+ publicKeys.set(keyRef, new TextDecoder().decode(bytes));
613
+ }
614
+ catch {
615
+ // Unresolvable keys stay absent; their signatures fail verification.
616
+ }
617
+ }
618
+ // Reproduce each verdict locally: fetch the stored signature record, the
619
+ // canonical artifact it binds, and check the crypto against the key.
620
+ const signatures = [];
621
+ for (const row of servedSignatures) {
622
+ const recordSha = parseArtifactUrnSha256(row.artifact_urn);
623
+ let record = null;
624
+ try {
625
+ if (recordSha) {
626
+ const { bytes } = await api.getArtifactBytes(recordSha, apiToken);
627
+ record = JSON.parse(new TextDecoder().decode(bytes));
628
+ }
629
+ }
630
+ catch {
631
+ // Missing/unreadable signature record: the signature fails verification.
632
+ }
633
+ const key_ref = typeof record?.['key_ref'] === 'string' ? record['key_ref'] : (row.key_ref ?? '');
634
+ const algorithm = typeof record?.['algorithm'] === 'string' ? record['algorithm'] : (row.algorithm ?? '');
635
+ const provenance_sha256 = typeof record?.['provenance_sha256'] === 'string' ? record['provenance_sha256'] : (row.provenance_sha256 ?? '');
636
+ const signature = typeof record?.['signature'] === 'string' ? record['signature'] : undefined;
637
+ if (!signature || !provenance_sha256) {
638
+ signatures.push({ key_ref, algorithm, provenance_sha256, digest_matches: false, signature_valid: false, verdict: 'invalid' });
639
+ continue;
640
+ }
641
+ let signedBytes = null;
642
+ try {
643
+ const { bytes } = await api.getArtifactBytes(provenance_sha256, apiToken);
644
+ signedBytes = bytes;
645
+ }
646
+ catch {
647
+ // Missing/unreadable signed artifact: the signature fails verification.
648
+ }
649
+ if (!signedBytes) {
650
+ signatures.push({ key_ref, algorithm, provenance_sha256, digest_matches: false, signature_valid: false, verdict: 'invalid' });
651
+ continue;
652
+ }
653
+ signatures.push(verifyProvenanceSignature({
654
+ canonicalRdfBytes: signedBytes,
655
+ currentProvenanceSha256: currentSha,
656
+ signature: { key_ref, algorithm, provenance_sha256, signature },
657
+ resolvePublicKey: (ref) => publicKeys.get(ref),
658
+ }));
659
+ }
660
+ const validSignatures = signatures.filter((check) => check.verdict === 'valid').length;
661
+ const staleSignatures = signatures.filter((check) => check.verdict === 'stale').length;
662
+ const invalidSignatures = signatures.filter((check) => check.verdict === 'invalid').length;
663
+ const strictFailures = strict && validSignatures === 0 ? ['no current provenance signature'] : [];
664
+ const verified = transportDigestMatches && invalidSignatures === 0 && strictFailures.length === 0;
665
+ console.log(JSON.stringify({
666
+ entity: provenance['entity'] ?? null,
667
+ strict,
668
+ current_provenance_sha256: currentSha,
669
+ transport_digest_matches: transportDigestMatches,
670
+ signatures,
671
+ valid_signatures: validSignatures,
672
+ stale_signatures: staleSignatures,
673
+ invalid_signatures: invalidSignatures,
674
+ strict_failures: strictFailures,
675
+ verdict: verified ? 'verified' : 'unverified',
676
+ }, null, 2));
677
+ if (!verified) {
678
+ throw new Error('Provenance did not verify.');
679
+ }
680
+ }
573
681
  async function runVerifyArtifact(env, args) {
574
682
  const apiToken = asString(args['api-token']);
575
683
  const sha256 = asString(args.sha256) ?? parseArtifactUrnSha256(asString(args['artifact-urn']));
@@ -950,7 +1058,14 @@ async function runSignKeyless(env, args) {
950
1058
  async function createApiKey(env, plane, ownerLabel) {
951
1059
  const serviceDir = plane === 'api' ? path.join(env.REPO_ROOT, 'service', 'api') : path.join(env.REPO_ROOT, 'service', 'mcp');
952
1060
  const hostDatabaseUrl = await resolveHostDatabaseUrlForPlane(env, plane);
953
- const result = await runShell('npm', ['run', '--silent', 'create-api-key', '--', '--owner-label', ownerLabel], {
1061
+ const args = ['run', '--silent', 'create-api-key', '--', '--owner-label', ownerLabel];
1062
+ if (plane === 'api') {
1063
+ // Bootstrap/operator keys need write access: the API defaults
1064
+ // management-created keys to read-only and scope enforcement is on by
1065
+ // default, so seeding would fail with INSUFFICIENT_SCOPE without this.
1066
+ args.push('--scopes', 'read,write');
1067
+ }
1068
+ const result = await runShell('npm', args, {
954
1069
  cwd: serviceDir,
955
1070
  ...(hostDatabaseUrl ? { env: { DATABASE_URL: hostDatabaseUrl } } : {}),
956
1071
  });
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.4",
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",