@signet-registry/operator 0.0.0-stage → 0.1.3
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 +28 -0
- package/README.md +191 -2
- package/dist/clients/api.js +245 -0
- package/dist/clients/mcp.js +118 -0
- package/dist/clients/verify.js +71 -0
- package/dist/config/env.js +42 -0
- package/dist/keyless.js +52 -0
- package/dist/main.js +7 -0
- package/dist/operator.js +1498 -0
- package/dist/transparency/sample-graph.js +203 -0
- package/dist/types.js +111 -0
- package/examples/bootstrap/agents/bootstrap-agent.md +5 -0
- package/examples/bootstrap/agents/bootstrap-ops-agent.md +8 -0
- package/examples/bootstrap/bootstrap.manifest.json +107 -0
- package/examples/bootstrap/skills/bootstrap-example.md +8 -0
- package/examples/bootstrap/skills/bootstrap-ops.md +8 -0
- package/examples/demo/agents/registry-agent.md +34 -0
- package/examples/demo/demo.manifest.json +90 -0
- package/examples/demo/skills/registry-mcp.md +74 -0
- package/examples/demo/skills/tame-llama.md +37 -0
- package/examples/signet-demo/agents/signet-demo-agent.md +39 -0
- package/examples/signet-demo/agents/signet-security-agent.md +36 -0
- package/examples/signet-demo/signet-demo.manifest.json +219 -0
- package/examples/signet-demo/skills/access-review.md +40 -0
- package/examples/signet-demo/skills/certification-workflow.md +39 -0
- package/examples/signet-demo/skills/governance-audit.md +39 -0
- package/examples/signet-demo/skills/graph-explorer.md +38 -0
- package/examples/signet-demo/skills/mcp-onboarding.md +39 -0
- package/examples/signet-demo/skills/policy-authoring.md +39 -0
- package/examples/signet-demo/skills/provenance-audit.md +39 -0
- package/examples/signet-demo/skills/registry-search.md +38 -0
- package/examples/signet-demo/skills/secrets-hygiene.md +39 -0
- package/examples/signet-demo/skills/skill-authoring.md +40 -0
- package/examples/transparency/README.md +39 -0
- package/examples/transparency/sample-graph.spec.json +16 -0
- package/package.json +52 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
BSD 3-Clause License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026, Derek C.
|
|
4
|
+
|
|
5
|
+
Redistribution and use in source and binary forms, with or without
|
|
6
|
+
modification, are permitted provided that the following conditions are met:
|
|
7
|
+
|
|
8
|
+
1. Redistributions of source code must retain the above copyright notice, this
|
|
9
|
+
list of conditions and the following disclaimer.
|
|
10
|
+
|
|
11
|
+
2. Redistributions in binary form must reproduce the above copyright notice,
|
|
12
|
+
this list of conditions and the following disclaimer in the documentation
|
|
13
|
+
and/or other materials provided with the distribution.
|
|
14
|
+
|
|
15
|
+
3. Neither the name of the copyright holder nor the names of its
|
|
16
|
+
contributors may be used to endorse or promote products derived from
|
|
17
|
+
this software without specific prior written permission.
|
|
18
|
+
|
|
19
|
+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
20
|
+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
21
|
+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
22
|
+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
|
|
23
|
+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
24
|
+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
|
25
|
+
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
|
|
26
|
+
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
|
27
|
+
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
28
|
+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,192 @@
|
|
|
1
|
-
|
|
1
|
+
## `client/registry-cli` — Registry Operator CLI
|
|
2
2
|
|
|
3
|
-
This
|
|
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,245 @@
|
|
|
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 getAgentPublicationVerification(agentKey, version, apiToken) {
|
|
179
|
+
return await this.fetchJson(`/v1/agents/${encodeURIComponent(agentKey)}/versions/${version}/verification`, undefined, apiToken);
|
|
180
|
+
}
|
|
181
|
+
async listPublicKeys(apiToken) {
|
|
182
|
+
return await this.fetchJson('/v1/public-keys', undefined, apiToken);
|
|
183
|
+
}
|
|
184
|
+
async getPublicKey(keyRef, apiToken) {
|
|
185
|
+
return await this.fetchJson(`/v1/public-keys/${encodeURIComponent(keyRef)}`, undefined, apiToken);
|
|
186
|
+
}
|
|
187
|
+
async getArtifactBytes(sha256, apiToken) {
|
|
188
|
+
const headers = this.buildHeaders(undefined, apiToken);
|
|
189
|
+
const response = await (this.deps.fetchFn ?? fetch)(new URL(`/v1/artifacts/${sha256}`, this.deps.apiOrigin), {
|
|
190
|
+
headers,
|
|
191
|
+
});
|
|
192
|
+
if (!response.ok) {
|
|
193
|
+
const errorBody = (await response.json().catch(() => undefined));
|
|
194
|
+
throw new RegistryOperatorApiError(errorBody?.error?.message ?? `Registry API request failed (${response.status})`, response.status, errorBody?.error?.code);
|
|
195
|
+
}
|
|
196
|
+
const bytes = new Uint8Array(await response.arrayBuffer());
|
|
197
|
+
const contentDigest = response.headers.get('content-digest');
|
|
198
|
+
return {
|
|
199
|
+
bytes,
|
|
200
|
+
...(contentDigest ? { contentDigest } : {}),
|
|
201
|
+
};
|
|
202
|
+
}
|
|
203
|
+
async createSkillDetachedSignature(skillKey, version, input, apiToken) {
|
|
204
|
+
return await this.fetchJson(`/v1/skills/${encodeURIComponent(skillKey)}/versions/${version}/signatures`, { method: 'POST', body: JSON.stringify(input) }, apiToken);
|
|
205
|
+
}
|
|
206
|
+
async postSkillVersionAction(action, input, apiToken) {
|
|
207
|
+
await this.fetchJson(`/v1/skills/${encodeURIComponent(input.skill_key)}/versions/${input.version}/${action}`, {
|
|
208
|
+
method: 'POST',
|
|
209
|
+
body: JSON.stringify({
|
|
210
|
+
author: input.author,
|
|
211
|
+
...(input.note ? { note: input.note } : {}),
|
|
212
|
+
...(input.prepared_publication_urn
|
|
213
|
+
? { prepared_publication_urn: input.prepared_publication_urn }
|
|
214
|
+
: {}),
|
|
215
|
+
...(input.signatures ? { signatures: input.signatures } : {}),
|
|
216
|
+
}),
|
|
217
|
+
}, apiToken);
|
|
218
|
+
}
|
|
219
|
+
buildHeaders(init, apiToken) {
|
|
220
|
+
const headers = new Headers(init?.headers);
|
|
221
|
+
headers.set('accept', 'application/json');
|
|
222
|
+
if (init?.body) {
|
|
223
|
+
headers.set('content-type', 'application/json');
|
|
224
|
+
}
|
|
225
|
+
if (apiToken) {
|
|
226
|
+
headers.set('authorization', `Bearer ${apiToken}`);
|
|
227
|
+
}
|
|
228
|
+
for (const [key, value] of Object.entries(this.deps.extraHeaders ?? {})) {
|
|
229
|
+
headers.set(key, value);
|
|
230
|
+
}
|
|
231
|
+
return headers;
|
|
232
|
+
}
|
|
233
|
+
async fetchJson(apiPath, init, apiToken) {
|
|
234
|
+
const headers = this.buildHeaders(init, apiToken);
|
|
235
|
+
const response = await (this.deps.fetchFn ?? fetch)(new URL(apiPath, this.deps.apiOrigin), {
|
|
236
|
+
...init,
|
|
237
|
+
headers,
|
|
238
|
+
});
|
|
239
|
+
if (!response.ok) {
|
|
240
|
+
const errorBody = (await response.json().catch(() => undefined));
|
|
241
|
+
throw new RegistryOperatorApiError(errorBody?.error?.message ?? `Registry API request failed (${response.status})`, response.status, errorBody?.error?.code);
|
|
242
|
+
}
|
|
243
|
+
return (await response.json());
|
|
244
|
+
}
|
|
245
|
+
}
|
|
@@ -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
|
+
}
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
import { createHash, createPublicKey, verify as verifySignature } from 'node:crypto';
|
|
2
|
+
export function sha256Hex(input) {
|
|
3
|
+
return createHash('sha256').update(input).digest('hex');
|
|
4
|
+
}
|
|
5
|
+
function parseSignatureBytes(signature) {
|
|
6
|
+
if (signature.startsWith('base64:')) {
|
|
7
|
+
return Buffer.from(signature.slice('base64:'.length), 'base64');
|
|
8
|
+
}
|
|
9
|
+
if (signature.startsWith('hex:')) {
|
|
10
|
+
return Buffer.from(signature.slice('hex:'.length), 'hex');
|
|
11
|
+
}
|
|
12
|
+
throw new Error('Signature must use a supported encoding prefix such as base64: or hex:.');
|
|
13
|
+
}
|
|
14
|
+
// Mirrors the algorithms accepted by the registry core so operator verification
|
|
15
|
+
// reproduces the server verdict locally.
|
|
16
|
+
export function verifyDetachedSignature(input) {
|
|
17
|
+
try {
|
|
18
|
+
const key = createPublicKey(input.publicKeyPem);
|
|
19
|
+
const signatureBytes = parseSignatureBytes(input.signature);
|
|
20
|
+
const message = typeof input.message === 'string' ? Buffer.from(input.message, 'utf8') : input.message;
|
|
21
|
+
switch (input.algorithm) {
|
|
22
|
+
case 'ed25519':
|
|
23
|
+
case 'ed448':
|
|
24
|
+
return verifySignature(null, message, key, signatureBytes);
|
|
25
|
+
case 'rsa-sha256':
|
|
26
|
+
case 'ecdsa-p256-sha256':
|
|
27
|
+
case 'ecdsa-sha256':
|
|
28
|
+
return verifySignature('sha256', message, key, signatureBytes);
|
|
29
|
+
case 'ecdsa-p384-sha384':
|
|
30
|
+
case 'ecdsa-sha384':
|
|
31
|
+
return verifySignature('sha384', message, key, signatureBytes);
|
|
32
|
+
default:
|
|
33
|
+
return false;
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
catch {
|
|
37
|
+
return false;
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
export function verifyEnvelopeSignatures(input) {
|
|
41
|
+
const canonical_json_sha256_matches = sha256Hex(Buffer.from(input.envelope.canonical_json, 'utf8')) === input.envelope.canonical_json_sha256;
|
|
42
|
+
const signatures = input.envelope.detached_signatures.map((signature) => {
|
|
43
|
+
const signedPayload = signature.signed_payload ?? 'canonical_json';
|
|
44
|
+
const expectedDigest = signedPayload === 'canonical_rdf' ? input.envelope.canonical_rdf_sha256 : input.envelope.canonical_json_sha256;
|
|
45
|
+
const digest_matches = expectedDigest !== undefined && signature.envelope_sha256 === expectedDigest;
|
|
46
|
+
const message = signedPayload === 'canonical_rdf'
|
|
47
|
+
? input.canonicalRdfBytes
|
|
48
|
+
: Buffer.from(input.envelope.canonical_json, 'utf8');
|
|
49
|
+
const publicKeyPem = message ? input.resolvePublicKey(signature.key_ref) : undefined;
|
|
50
|
+
const signature_valid = digest_matches && publicKeyPem !== undefined && message !== undefined
|
|
51
|
+
? verifyDetachedSignature({
|
|
52
|
+
algorithm: signature.algorithm,
|
|
53
|
+
publicKeyPem,
|
|
54
|
+
message,
|
|
55
|
+
signature: signature.signature,
|
|
56
|
+
})
|
|
57
|
+
: false;
|
|
58
|
+
return {
|
|
59
|
+
key_ref: signature.key_ref,
|
|
60
|
+
algorithm: signature.algorithm,
|
|
61
|
+
signed_payload: signedPayload,
|
|
62
|
+
digest_matches,
|
|
63
|
+
signature_valid,
|
|
64
|
+
};
|
|
65
|
+
});
|
|
66
|
+
return {
|
|
67
|
+
canonical_json_sha256_matches,
|
|
68
|
+
signatures,
|
|
69
|
+
all_signatures_valid: signatures.every((signature) => signature.signature_valid),
|
|
70
|
+
};
|
|
71
|
+
}
|