@signet-registry/operator 0.0.0-stage → 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.
Files changed (36) hide show
  1. package/LICENSE +29 -0
  2. package/README.md +191 -2
  3. package/dist/clients/api.js +251 -0
  4. package/dist/clients/mcp.js +118 -0
  5. package/dist/clients/verify.js +106 -0
  6. package/dist/config/env.js +42 -0
  7. package/dist/keyless.js +52 -0
  8. package/dist/main.js +7 -0
  9. package/dist/operator.js +1613 -0
  10. package/dist/transparency/sample-graph.js +203 -0
  11. package/dist/types.js +111 -0
  12. package/examples/bootstrap/agents/bootstrap-agent.md +5 -0
  13. package/examples/bootstrap/agents/bootstrap-ops-agent.md +8 -0
  14. package/examples/bootstrap/bootstrap.manifest.json +107 -0
  15. package/examples/bootstrap/skills/bootstrap-example.md +8 -0
  16. package/examples/bootstrap/skills/bootstrap-ops.md +8 -0
  17. package/examples/demo/agents/registry-agent.md +34 -0
  18. package/examples/demo/demo.manifest.json +90 -0
  19. package/examples/demo/skills/registry-mcp.md +74 -0
  20. package/examples/demo/skills/tame-llama.md +37 -0
  21. package/examples/signet-demo/agents/signet-demo-agent.md +39 -0
  22. package/examples/signet-demo/agents/signet-security-agent.md +36 -0
  23. package/examples/signet-demo/signet-demo.manifest.json +219 -0
  24. package/examples/signet-demo/skills/access-review.md +40 -0
  25. package/examples/signet-demo/skills/certification-workflow.md +39 -0
  26. package/examples/signet-demo/skills/governance-audit.md +39 -0
  27. package/examples/signet-demo/skills/graph-explorer.md +38 -0
  28. package/examples/signet-demo/skills/mcp-onboarding.md +39 -0
  29. package/examples/signet-demo/skills/policy-authoring.md +39 -0
  30. package/examples/signet-demo/skills/provenance-audit.md +39 -0
  31. package/examples/signet-demo/skills/registry-search.md +38 -0
  32. package/examples/signet-demo/skills/secrets-hygiene.md +39 -0
  33. package/examples/signet-demo/skills/skill-authoring.md +40 -0
  34. package/examples/transparency/README.md +39 -0
  35. package/examples/transparency/sample-graph.spec.json +16 -0
  36. package/package.json +58 -4
package/LICENSE ADDED
@@ -0,0 +1,29 @@
1
+ BSD 3-Clause License
2
+
3
+ Copyright (c) 2026, Derek C.
4
+ Copyright (c) 2026, Pablo Ferrari (@pabshazon)
5
+
6
+ Redistribution and use in source and binary forms, with or without
7
+ modification, are permitted provided that the following conditions are met:
8
+
9
+ 1. Redistributions of source code must retain the above copyright notice, this
10
+ list of conditions and the following disclaimer.
11
+
12
+ 2. Redistributions in binary form must reproduce the above copyright notice,
13
+ this list of conditions and the following disclaimer in the documentation
14
+ and/or other materials provided with the distribution.
15
+
16
+ 3. Neither the name of the copyright holder nor the names of its
17
+ contributors may be used to endorse or promote products derived from
18
+ this software without specific prior written permission.
19
+
20
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
23
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
24
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
26
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
27
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
package/README.md CHANGED
@@ -1,3 +1,192 @@
1
- # Temporary Holding Version
1
+ ## `client/registry-cli` — Registry Operator CLI
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ This package is the operator/assistant CLI for **Signet**.
4
+
5
+ Its first job is local-first bootstrap:
6
+ - bring the stack up or down
7
+ - clean local state safely
8
+ - create write credentials
9
+ - seed lifecycle-aware skills
10
+ - seed agents that reference those skills
11
+ - verify API and MCP discovery/load
12
+
13
+ ### Current direction
14
+ - target `service/api` for all management-plane writes
15
+ - target `service/mcp` for discovery/load verification
16
+ - keep bootstrap local-first
17
+ - keep real live-Okta proof as a second lane after the basic bootstrap path is green
18
+
19
+ ### Command shape
20
+ - `registry-operator local up`
21
+ - `registry-operator local down`
22
+ - `registry-operator local reset --force`
23
+ - `registry-operator auth create-api-key`
24
+ - `registry-operator seed skill`
25
+ - `registry-operator seed agent`
26
+ - `registry-operator seed bootstrap`
27
+ - `registry-operator seed transparency-sample`
28
+ - `registry-operator verify api`
29
+ - `registry-operator verify mcp` — re-hashes every fetched artifact locally
30
+ (`digest_verified` plus a content hash when not truncated)
31
+ - `registry-operator verify publication (--skill <key> | --agent <key>) --version <n> [--strict]`
32
+ — server verdicts plus client-side checks (canonical digest recomputation,
33
+ detached-signature verification against trusted keys fetched from the
34
+ registry). `--strict` additionally requires the server verdict, at least one
35
+ valid signature, and a matching frozen-envelope artifact; the command exits
36
+ non-zero when the publication does not verify.
37
+ - `registry-operator verify artifact (--sha256 <hex> | --artifact-urn <urn>)`
38
+ — downloads the bytes from `GET /v1/artifacts/{sha256}` and re-hashes them,
39
+ including the `Content-Digest` header when present; exits non-zero on
40
+ mismatch.
41
+ - `registry-operator verify okta-config`
42
+ - `registry-operator verify browser-session`
43
+ - `registry-operator bootstrap test`
44
+
45
+ ### Install / use as a CLI
46
+
47
+ The CLI is published as the npm package `@signet-registry/operator` with a
48
+ `registry-operator` bin.
49
+
50
+ Run without installing (npx):
51
+
52
+ ```bash
53
+ npx @signet-registry/operator --help
54
+ ```
55
+
56
+ Or install globally:
57
+
58
+ ```bash
59
+ npm install -g @signet-registry/operator
60
+ registry-operator --help
61
+ ```
62
+
63
+ A pre-built release tarball is also packaged under `release/` (via `npm pack`):
64
+
65
+ ```bash
66
+ npm run build
67
+ npm pack --pack-destination release/
68
+ npm install -g release/signet-registry-operator-<version>.tgz
69
+ ```
70
+
71
+ ### Deployed environments (edge access)
72
+
73
+ Deployed API/MCP hosts may sit behind an edge access layer (for example
74
+ Cloudflare Access). Machines outside the trusted network pass a service token;
75
+ the CLI applies it to both the API and MCP clients:
76
+
77
+ ```bash
78
+ export SIGNET_CF_ACCESS_CLIENT_ID=...
79
+ export SIGNET_CF_ACCESS_CLIENT_SECRET=...
80
+ export API_ORIGIN=https://signet-api.example.com
81
+ export MCP_ORIGIN=https://signet-mcp.example.com
82
+ ```
83
+
84
+ Or per-invocation flags: `--cf-access-client-id`, `--cf-access-client-secret`.
85
+ See `docs/adoption.md`.
86
+
87
+ ### Run locally
88
+
89
+ ```bash
90
+ cd signet/client/registry-cli
91
+ npm install
92
+ npm run dev -- bootstrap test --reset --force --up
93
+ ```
94
+
95
+ Default behavior:
96
+ - `bootstrap test` now points at the blessed first-user demo manifest
97
+ - default manifest: `examples/demo/demo.manifest.json`
98
+ - source-of-truth walkthrough: `../../docs/blessed-demo-path.md`
99
+ - CLI output now includes `graph_backend`, `cursor_mcp_config`, `next_prompts`, and token-safe artifact file paths
100
+ - when `--up` is used, the CLI now waits for `api`, `mcp`, and SPARQL/Fuseki readiness before seeding
101
+ - when `--reset` is used on a SPARQL-backed run, the CLI explicitly clears the dataset before bringing the stack back
102
+
103
+ ### Richer bootstrap packs
104
+ The bootstrap manifest now supports:
105
+ - pack metadata
106
+ - reusable defaults
107
+ - multi-skill / multi-agent packs
108
+ - item ids and dependency ordering
109
+ - profile-based selection
110
+ - skill refs by `skill_item_id`, `skill_key`, or `skill_urn`
111
+ - `bootstrap test --lane okta-browser` for the real-Okta verification lane
112
+
113
+ Blessed demo dry run:
114
+
115
+ ```bash
116
+ npm run dev -- bootstrap test --dry-run
117
+ ```
118
+
119
+ Legacy example pack dry run:
120
+
121
+ ```bash
122
+ npm run dev -- seed bootstrap --manifest examples/bootstrap/bootstrap.manifest.json --profile minimal --api-token "<token>" --dry-run
123
+ ```
124
+
125
+ Blessed demo proof:
126
+
127
+ ```bash
128
+ npm run dev -- bootstrap test --reset --force --up
129
+ ```
130
+
131
+ Transparency sample graph proof:
132
+
133
+ ```bash
134
+ npm run dev -- seed transparency-sample --api-token "<api-token>"
135
+ ```
136
+
137
+ Canonical committed transparency sample spec:
138
+
139
+ ```bash
140
+ npm run dev -- seed transparency-sample --spec examples/transparency/sample-graph.spec.json --dry-run
141
+ ```
142
+
143
+ This prints the committed sample shape without requiring the stack or an API token.
144
+
145
+ Seed that same committed sample through the real operator path:
146
+
147
+ ```bash
148
+ npm run dev -- seed transparency-sample --api-token "<api-token>" --spec examples/transparency/sample-graph.spec.json
149
+ ```
150
+
151
+ Optional smaller human-facing report instead of the full JSON payloads:
152
+
153
+ ```bash
154
+ npm run dev -- seed transparency-sample --api-token "<api-token>" --human-proof-report
155
+ ```
156
+
157
+ Optional explicit sample id and day:
158
+
159
+ ```bash
160
+ npm run dev -- seed transparency-sample --api-token "<api-token>" --sample-slug "demo" --day "2026-01-06"
161
+ ```
162
+
163
+ What this command does:
164
+ - seeds trusted public keys, a transparency log, witnesses, checkpoints, observations, and gossip over the real API
165
+ - prints the seeded sample metadata plus the resulting log, verification, and timeline payloads by default
166
+ - with `--human-proof-report`, prints a smaller proof-oriented summary for humans instead of the full payloads
167
+ - uses the same trust-story shape exercised by the transparency sample-graph e2e tests
168
+ - can also seed the committed sample spec under `examples/transparency/sample-graph.spec.json`
169
+
170
+ ### Real Okta bootstrap lane
171
+ The CLI now also supports a second operator lane for real Okta-backed bootstrap verification guidance.
172
+
173
+ It does not replace the browser flow.
174
+
175
+ Instead, it helps operators:
176
+ - validate the required API and webapp env/config state
177
+ - check stack health before the browser proof
178
+ - seed bootstrap content locally first if desired
179
+ - then follow the real browser-based proof documented in:
180
+ - `service/webapp/knowledge-manager/OKTA_BROWSER_FLOW_RUNBOOK.md`
181
+
182
+ Example:
183
+
184
+ ```bash
185
+ npm run dev -- verify okta-config
186
+ npm run dev -- verify browser-session
187
+ npm run dev -- bootstrap test --lane okta-browser --api-token "<api-token>" --mcp-token "<mcp-token>"
188
+ ```
189
+
190
+ Important boundary:
191
+ - this Okta lane is for the registry-admin surface
192
+ - it does not change the current decision to defer real Okta-backed ontology access through the Semantic Turkey / VocBench companion runtime
@@ -0,0 +1,251 @@
1
+ import { readFile } from 'node:fs/promises';
2
+ export class RegistryOperatorApiError extends Error {
3
+ status;
4
+ code;
5
+ constructor(message, status, code) {
6
+ super(message);
7
+ this.status = status;
8
+ this.code = code;
9
+ this.name = 'RegistryOperatorApiError';
10
+ }
11
+ }
12
+ export class HttpRegistryOperatorApiClient {
13
+ deps;
14
+ constructor(deps) {
15
+ this.deps = deps;
16
+ }
17
+ async createSkillDraft(plan, apiToken) {
18
+ const artifactContent = await readFile(plan.draft.artifact_path, 'utf8');
19
+ const result = await this.fetchJson(`/v1/skills/${encodeURIComponent(plan.draft.skill_key)}/drafts`, {
20
+ method: 'POST',
21
+ body: JSON.stringify({
22
+ author: plan.draft.author,
23
+ ...(plan.draft.display_name ? { display_name: plan.draft.display_name } : {}),
24
+ ...(plan.draft.description ? { description: plan.draft.description } : {}),
25
+ ...(plan.draft.source_path ? { source_path: plan.draft.source_path } : {}),
26
+ ...(plan.draft.commit_sha ? { commit_sha: plan.draft.commit_sha } : {}),
27
+ ...(plan.draft.git_tag ? { git_tag: plan.draft.git_tag } : {}),
28
+ ...(plan.draft.artifact_signature ? { artifact_signature: plan.draft.artifact_signature } : {}),
29
+ ...(plan.draft.lineage ? { lineage: plan.draft.lineage } : {}),
30
+ artifact: {
31
+ content: artifactContent,
32
+ encoding: 'utf8',
33
+ media_type: plan.draft.artifact_media_type,
34
+ original_path: plan.draft.source_path ?? plan.draft.artifact_path,
35
+ },
36
+ }),
37
+ }, apiToken);
38
+ const rawVersion = result.result.skill_version.properties['version'];
39
+ const version = typeof rawVersion === 'number' ? rawVersion : Number(rawVersion ?? 0);
40
+ return {
41
+ version,
42
+ artifactUrn: result.result.artifacts[0]?.artifact_urn,
43
+ };
44
+ }
45
+ async validateSkillVersion(input, apiToken) {
46
+ await this.postSkillVersionAction('validate', input, apiToken);
47
+ }
48
+ async publishSkillVersion(input, apiToken) {
49
+ await this.postSkillVersionAction('publish', input, apiToken);
50
+ }
51
+ async prepareSkillPublication(skillKey, version, input, apiToken) {
52
+ return await this.fetchJson(`/v1/skills/${encodeURIComponent(skillKey)}/versions/${version}/prepare-publication`, {
53
+ method: 'POST',
54
+ body: JSON.stringify({
55
+ author: input.author,
56
+ ...(input.note ? { note: input.note } : {}),
57
+ }),
58
+ }, apiToken);
59
+ }
60
+ async certifySkillVersion(input, apiToken) {
61
+ await this.postSkillVersionAction('certify', input, apiToken);
62
+ }
63
+ async prepareAgentPublication(agentKey, version, input, apiToken) {
64
+ return await this.fetchJson(`/v1/agents/${encodeURIComponent(agentKey)}/versions/${version}/prepare-publication`, {
65
+ method: 'POST',
66
+ body: JSON.stringify({
67
+ author: input.author,
68
+ ...(input.note ? { note: input.note } : {}),
69
+ }),
70
+ }, apiToken);
71
+ }
72
+ async publishAgentVersion(input, apiToken) {
73
+ await this.postAgentVersionAction('publish', input, apiToken);
74
+ }
75
+ async certifyAgentVersion(input, apiToken) {
76
+ await this.postAgentVersionAction('certify', input, apiToken);
77
+ }
78
+ async postAgentVersionAction(action, input, apiToken) {
79
+ await this.fetchJson(`/v1/agents/${encodeURIComponent(input.agent_key)}/versions/${input.version}/${action}`, {
80
+ method: 'POST',
81
+ body: JSON.stringify({
82
+ author: input.author,
83
+ ...(input.note ? { note: input.note } : {}),
84
+ ...(input.prepared_publication_urn
85
+ ? { prepared_publication_urn: input.prepared_publication_urn }
86
+ : {}),
87
+ ...(input.signatures ? { signatures: input.signatures } : {}),
88
+ }),
89
+ }, apiToken);
90
+ }
91
+ async getActiveSkillVersion(skillKey, apiToken) {
92
+ return await this.fetchJson(`/v1/skills/${encodeURIComponent(skillKey)}/active`, undefined, apiToken);
93
+ }
94
+ async getSkill(skillKey, apiToken) {
95
+ return await this.fetchJson(`/v1/skills/${encodeURIComponent(skillKey)}`, undefined, apiToken);
96
+ }
97
+ async createAgent(plan, apiToken) {
98
+ const artifactContent = plan.artifact_path ? await readFile(plan.artifact_path, 'utf8') : null;
99
+ return await this.fetchJson('/v1/agents', {
100
+ method: 'POST',
101
+ body: JSON.stringify({
102
+ agent_key: plan.agent_key,
103
+ ...(plan.harness_name ? { harness_name: plan.harness_name } : {}),
104
+ ...(plan.display_name ? { display_name: plan.display_name } : {}),
105
+ ...(plan.description ? { description: plan.description } : {}),
106
+ ...(plan.source_path ? { source_path: plan.source_path } : {}),
107
+ ...(artifactContent
108
+ ? {
109
+ artifact: {
110
+ content: artifactContent,
111
+ encoding: 'utf8',
112
+ media_type: plan.artifact_media_type ?? 'text/markdown',
113
+ original_path: plan.source_path ?? plan.artifact_path,
114
+ },
115
+ }
116
+ : {}),
117
+ ...(plan.skill_refs.length > 0 ? { skill_refs: plan.skill_refs } : {}),
118
+ }),
119
+ }, apiToken);
120
+ }
121
+ async getAgent(agentKey, apiToken) {
122
+ return await this.fetchJson(`/v1/agents/${encodeURIComponent(agentKey)}`, undefined, apiToken);
123
+ }
124
+ async createTrustedPublicKey(input, apiToken) {
125
+ return await this.fetchJson('/v1/public-keys', {
126
+ method: 'POST',
127
+ body: JSON.stringify(input),
128
+ }, apiToken);
129
+ }
130
+ async createTransparencyLog(input, apiToken) {
131
+ return await this.fetchJson('/v1/transparency-logs', {
132
+ method: 'POST',
133
+ body: JSON.stringify(input),
134
+ }, apiToken);
135
+ }
136
+ async createTransparencyWitness(logId, input, apiToken) {
137
+ return await this.fetchJson(`/v1/transparency-logs/${encodeURIComponent(logId)}/witnesses`, {
138
+ method: 'POST',
139
+ body: JSON.stringify(input),
140
+ }, apiToken);
141
+ }
142
+ async createTransparencyCheckpoint(logId, input, apiToken) {
143
+ return await this.fetchJson(`/v1/transparency-logs/${encodeURIComponent(logId)}/checkpoints`, {
144
+ method: 'POST',
145
+ body: JSON.stringify(input),
146
+ }, apiToken);
147
+ }
148
+ async createTransparencyObservation(logId, input, apiToken) {
149
+ return await this.fetchJson(`/v1/transparency-logs/${encodeURIComponent(logId)}/observations`, {
150
+ method: 'POST',
151
+ body: JSON.stringify(input),
152
+ }, apiToken);
153
+ }
154
+ async createTransparencyGossipEvent(logId, input, apiToken) {
155
+ return await this.fetchJson(`/v1/transparency-logs/${encodeURIComponent(logId)}/gossip-events`, {
156
+ method: 'POST',
157
+ body: JSON.stringify(input),
158
+ }, apiToken);
159
+ }
160
+ async getTransparencyLog(logId, apiToken) {
161
+ return await this.fetchJson(`/v1/transparency-logs/${encodeURIComponent(logId)}`, undefined, apiToken);
162
+ }
163
+ async getTransparencyLogVerification(logId, apiToken) {
164
+ return await this.fetchJson(`/v1/transparency-logs/${encodeURIComponent(logId)}/verification`, undefined, apiToken);
165
+ }
166
+ async getTransparencyLogTimeline(logId, apiToken) {
167
+ return await this.fetchJson(`/v1/transparency-logs/${encodeURIComponent(logId)}/timeline`, undefined, apiToken);
168
+ }
169
+ async getSkillPublicationEnvelope(skillKey, version, apiToken) {
170
+ return await this.fetchJson(`/v1/skills/${encodeURIComponent(skillKey)}/versions/${version}/publication-envelope`, undefined, apiToken);
171
+ }
172
+ async getAgentPublicationEnvelope(agentKey, version, apiToken) {
173
+ return await this.fetchJson(`/v1/agents/${encodeURIComponent(agentKey)}/versions/${version}/publication-envelope`, undefined, apiToken);
174
+ }
175
+ async getSkillPublicationVerification(skillKey, version, apiToken) {
176
+ return await this.fetchJson(`/v1/skills/${encodeURIComponent(skillKey)}/versions/${version}/verification`, undefined, apiToken);
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 getAgentPublicationVerification(agentKey, version, apiToken) {
185
+ return await this.fetchJson(`/v1/agents/${encodeURIComponent(agentKey)}/versions/${version}/verification`, undefined, apiToken);
186
+ }
187
+ async listPublicKeys(apiToken) {
188
+ return await this.fetchJson('/v1/public-keys', undefined, apiToken);
189
+ }
190
+ async getPublicKey(keyRef, apiToken) {
191
+ return await this.fetchJson(`/v1/public-keys/${encodeURIComponent(keyRef)}`, undefined, apiToken);
192
+ }
193
+ async getArtifactBytes(sha256, apiToken) {
194
+ const headers = this.buildHeaders(undefined, apiToken);
195
+ const response = await (this.deps.fetchFn ?? fetch)(new URL(`/v1/artifacts/${sha256}`, this.deps.apiOrigin), {
196
+ headers,
197
+ });
198
+ if (!response.ok) {
199
+ const errorBody = (await response.json().catch(() => undefined));
200
+ throw new RegistryOperatorApiError(errorBody?.error?.message ?? `Registry API request failed (${response.status})`, response.status, errorBody?.error?.code);
201
+ }
202
+ const bytes = new Uint8Array(await response.arrayBuffer());
203
+ const contentDigest = response.headers.get('content-digest');
204
+ return {
205
+ bytes,
206
+ ...(contentDigest ? { contentDigest } : {}),
207
+ };
208
+ }
209
+ async createSkillDetachedSignature(skillKey, version, input, apiToken) {
210
+ return await this.fetchJson(`/v1/skills/${encodeURIComponent(skillKey)}/versions/${version}/signatures`, { method: 'POST', body: JSON.stringify(input) }, apiToken);
211
+ }
212
+ async postSkillVersionAction(action, input, apiToken) {
213
+ await this.fetchJson(`/v1/skills/${encodeURIComponent(input.skill_key)}/versions/${input.version}/${action}`, {
214
+ method: 'POST',
215
+ body: JSON.stringify({
216
+ author: input.author,
217
+ ...(input.note ? { note: input.note } : {}),
218
+ ...(input.prepared_publication_urn
219
+ ? { prepared_publication_urn: input.prepared_publication_urn }
220
+ : {}),
221
+ ...(input.signatures ? { signatures: input.signatures } : {}),
222
+ }),
223
+ }, apiToken);
224
+ }
225
+ buildHeaders(init, apiToken) {
226
+ const headers = new Headers(init?.headers);
227
+ headers.set('accept', 'application/json');
228
+ if (init?.body) {
229
+ headers.set('content-type', 'application/json');
230
+ }
231
+ if (apiToken) {
232
+ headers.set('authorization', `Bearer ${apiToken}`);
233
+ }
234
+ for (const [key, value] of Object.entries(this.deps.extraHeaders ?? {})) {
235
+ headers.set(key, value);
236
+ }
237
+ return headers;
238
+ }
239
+ async fetchJson(apiPath, init, apiToken) {
240
+ const headers = this.buildHeaders(init, apiToken);
241
+ const response = await (this.deps.fetchFn ?? fetch)(new URL(apiPath, this.deps.apiOrigin), {
242
+ ...init,
243
+ headers,
244
+ });
245
+ if (!response.ok) {
246
+ const errorBody = (await response.json().catch(() => undefined));
247
+ throw new RegistryOperatorApiError(errorBody?.error?.message ?? `Registry API request failed (${response.status})`, response.status, errorBody?.error?.code);
248
+ }
249
+ return (await response.json());
250
+ }
251
+ }
@@ -0,0 +1,118 @@
1
+ import { Client } from '@modelcontextprotocol/sdk/client/index.js';
2
+ import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
3
+ import { sha256Hex } from './verify.js';
4
+ export class RegistryOperatorMcpError extends Error {
5
+ constructor(message) {
6
+ super(message);
7
+ this.name = 'RegistryOperatorMcpError';
8
+ }
9
+ }
10
+ export class RegistryOperatorMcpClient {
11
+ deps;
12
+ constructor(deps) {
13
+ this.deps = deps;
14
+ }
15
+ async verifyBootstrap(input) {
16
+ const client = new Client({ name: 'registry-operator', version: '0.1.0' });
17
+ const transport = new StreamableHTTPClientTransport(new URL('/mcp', this.deps.mcpOrigin), {
18
+ requestInit: {
19
+ headers: {
20
+ authorization: `Bearer ${input.token}`,
21
+ 'x-agent-client': 'registry-operator',
22
+ ...(this.deps.extraHeaders ?? {}),
23
+ },
24
+ },
25
+ });
26
+ try {
27
+ await client.connect(transport);
28
+ const tools = await client.listTools();
29
+ const toolNames = tools.tools.map((tool) => tool.name);
30
+ for (const required of [
31
+ 'registry.list_agents',
32
+ 'registry.get_agent',
33
+ 'registry.list_skills',
34
+ 'registry.get_skill',
35
+ 'registry.get_artifact',
36
+ ]) {
37
+ if (!toolNames.includes(required)) {
38
+ throw new RegistryOperatorMcpError(`Missing MCP tool: ${required}`);
39
+ }
40
+ }
41
+ await expectToolSuccess(await client.callTool({ name: 'registry.list_agents', arguments: {} }));
42
+ await expectToolSuccess(await client.callTool({ name: 'registry.list_skills', arguments: {} }));
43
+ const verifiedArtifacts = [];
44
+ const artifactChecks = [];
45
+ for (const agentKey of input.agentKeys) {
46
+ const result = await expectToolSuccess(await client.callTool({
47
+ name: 'registry.get_agent',
48
+ arguments: { agent_urn: `urn:sg:agent:${agentKey}` },
49
+ }));
50
+ const artifacts = readArtifacts(result, 'artifacts');
51
+ for (const artifactUrn of artifacts) {
52
+ artifactChecks.push(await verifyArtifactDigest(client, artifactUrn));
53
+ verifiedArtifacts.push(artifactUrn);
54
+ }
55
+ }
56
+ for (const skillKey of input.skillKeys) {
57
+ const result = await expectToolSuccess(await client.callTool({
58
+ name: 'registry.get_skill',
59
+ arguments: { skill_urn: `urn:sg:skill:${skillKey}` },
60
+ }));
61
+ const artifacts = readArtifacts(result, 'artifacts');
62
+ for (const artifactUrn of artifacts) {
63
+ artifactChecks.push(await verifyArtifactDigest(client, artifactUrn));
64
+ verifiedArtifacts.push(artifactUrn);
65
+ }
66
+ }
67
+ return { toolsChecked: toolNames, verifiedArtifacts, artifactChecks };
68
+ }
69
+ finally {
70
+ await transport.close().catch(() => undefined);
71
+ await client.close().catch(() => undefined);
72
+ }
73
+ }
74
+ }
75
+ async function expectToolSuccess(result) {
76
+ if (result.isError) {
77
+ throw new RegistryOperatorMcpError(readTextContent(result));
78
+ }
79
+ return readStructuredContent(result);
80
+ }
81
+ // Fetches an artifact through MCP and verifies it locally: the registry
82
+ // reports digest_verified, and when the content is not truncated the bytes
83
+ // returned are re-hashed against the declared digest. A mismatch fails the
84
+ // check; truncation is recorded as an unknown content hash rather than a pass.
85
+ async function verifyArtifactDigest(client, artifactUrn) {
86
+ const result = await expectToolSuccess(await client.callTool({
87
+ name: 'registry.get_artifact',
88
+ arguments: { artifact_urn: artifactUrn },
89
+ }));
90
+ const sha256 = typeof result['sha256'] === 'string' && result['sha256'].length > 0 ? result['sha256'] : null;
91
+ const content = typeof result['content'] === 'string' ? result['content'] : undefined;
92
+ const truncated = result['content_truncated'] === true;
93
+ const digestVerified = result['digest_verified'] === true;
94
+ const contentHashMatches = !truncated && sha256 !== null && content !== undefined ? sha256Hex(content) === sha256 : null;
95
+ if (!digestVerified || contentHashMatches === false) {
96
+ throw new RegistryOperatorMcpError(`Artifact ${artifactUrn} failed digest verification (digest_verified=${digestVerified}, content_hash_matches=${contentHashMatches ?? 'unknown'}).`);
97
+ }
98
+ return { artifact_urn: artifactUrn, sha256, digest_verified: digestVerified, content_hash_matches: contentHashMatches };
99
+ }
100
+ function readStructuredContent(result) {
101
+ return (result.structuredContent ?? {});
102
+ }
103
+ function readTextContent(result) {
104
+ const content = result.content ?? [];
105
+ const first = content[0];
106
+ return first?.type === 'text' ? (first.text ?? '') : '';
107
+ }
108
+ function readArtifacts(result, key) {
109
+ const raw = result[key];
110
+ if (!Array.isArray(raw)) {
111
+ return [];
112
+ }
113
+ return raw
114
+ .map((item) => (typeof item === 'object' && item && typeof item.artifact_urn === 'string'
115
+ ? item.artifact_urn
116
+ : null))
117
+ .filter((value) => Boolean(value));
118
+ }