@imolko/ultra-event-signature 0.3.0-beta → 0.4.0-beta
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/README.md +140 -6
- package/docs/emitter-checklist.md +45 -5
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -169,13 +169,144 @@ used in a production key set, policy or image.
|
|
|
169
169
|
- **CLI** under `bin/` (spec 2): `generate`, `build` and `verify` — the flow
|
|
170
170
|
above. It reports the document digest and the key fingerprint and writes the
|
|
171
171
|
two bundle files.
|
|
172
|
-
- **CI component** (
|
|
173
|
-
|
|
172
|
+
- **CI component** (`templates/fact-key.yml`, spec 3): a reusable GitLab job
|
|
173
|
+
that builds and self-checks the bundle and, with `publish: true`, pushes it
|
|
174
|
+
as an OCI artifact and reports its manifest digest. Its self-test reproduces
|
|
175
|
+
the published vector with `publish: false` and needs no registry credentials.
|
|
174
176
|
|
|
175
177
|
Both are delivery, not custody. They receive key material as arguments, never
|
|
176
178
|
store it, and a valid bundle never grants the key any authority — the policy in
|
|
177
179
|
[03 — trust policy](docs/spec/03-trust-policy.md) decides what a key may sign.
|
|
178
180
|
|
|
181
|
+
## CI component for fact-keys
|
|
182
|
+
|
|
183
|
+
`templates/fact-key.yml` is a GitLab CI component that runs the publish step of
|
|
184
|
+
[07 §10](docs/spec/07-fact-key.md#10-emitter-pipeline) inside an emitter's
|
|
185
|
+
pipeline: it builds the bundle, re-runs the contract check a consumer will run,
|
|
186
|
+
optionally publishes the pair as an OCI artifact and reports the digests. It is
|
|
187
|
+
released with the package under the same tag (PJ-003), so the component and the
|
|
188
|
+
CLI that understands the format always travel together.
|
|
189
|
+
|
|
190
|
+
### Include
|
|
191
|
+
|
|
192
|
+
```yaml
|
|
193
|
+
include:
|
|
194
|
+
- component: $CI_SERVER_FQDN/imolko/ultra-stack/ultra-event-signature/fact-key@<tag>
|
|
195
|
+
inputs:
|
|
196
|
+
stage: deploy
|
|
197
|
+
library-package: "@imolko/ultra-event-signature@<tag>"
|
|
198
|
+
emitter: landlord
|
|
199
|
+
kid: landlord-2026a
|
|
200
|
+
source: landlord.imolko.com/tenants
|
|
201
|
+
types: com.nixailabs.landlord.v1.infra-provisioned,com.nixailabs.landlord.v1.infra-updated
|
|
202
|
+
# key-variable: FACT_KEY_PRIVATE_KEY
|
|
203
|
+
# registry-repository: "" # empty means $CI_REGISTRY_IMAGE
|
|
204
|
+
# publish: true
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
### Inputs
|
|
208
|
+
|
|
209
|
+
| Input | Required | Default | Meaning |
|
|
210
|
+
|---|---|---|---|
|
|
211
|
+
| `stage` | no | `deploy` | Stage that runs the job |
|
|
212
|
+
| `library-package` | **yes** | — | Exact npm spec or local tarball of the library |
|
|
213
|
+
| `emitter` | **yes** | — | Name the emitter publishes under |
|
|
214
|
+
| `kid` | **yes** | — | Key id, `^[A-Za-z0-9_.-]{1,128}$`; at most 119 when publishing (OCI tag limit) |
|
|
215
|
+
| `source` | **yes** | — | Frozen `source` the key signs for |
|
|
216
|
+
| `types` | **yes** | — | Comma-separated types, no wildcards |
|
|
217
|
+
| `key-variable` | no | `FACT_KEY_PRIVATE_KEY` | Name of the CI variable holding the PEM (multiline, base64 or a File variable) |
|
|
218
|
+
| `registry-repository` | no | `""` → `$CI_REGISTRY_IMAGE` | OCI repository to publish into |
|
|
219
|
+
| `publish` | no | `true` | Push the pair on a tag pipeline; `false` only leaves job artifacts |
|
|
220
|
+
| `oras-version` | no | `1.2.3` | `oras` release downloaded and verified against that release's checksums |
|
|
221
|
+
| `expected-document-sha256` | no | `""` | Pin the document digest; a mismatch fails the build |
|
|
222
|
+
| `expected-signature-hex` | no | `""` | Pin the raw signature in hex; used by the self-test |
|
|
223
|
+
|
|
224
|
+
`library-package` is also the version input of the component: the YAML fixes no
|
|
225
|
+
version of its own. Use the **exact spec of the same tag as the component**
|
|
226
|
+
(`fact-key@<tag>` with `@imolko/ultra-event-signature@<tag>`), or a local tarball
|
|
227
|
+
in the self-test. The repository publishes with `npm version` in memory, and the
|
|
228
|
+
tag points at the integration commit where `package.json` still says `0.0.0`, so
|
|
229
|
+
a default derived from the repository would not describe what was published.
|
|
230
|
+
`scripts/component.test.mjs` fails if the template pins a version or gives
|
|
231
|
+
`library-package` a default.
|
|
232
|
+
|
|
233
|
+
`types` is a comma-separated string because GitLab array inputs do not
|
|
234
|
+
interpolate reliably into `script`; the job splits it and passes one `--type` per
|
|
235
|
+
element.
|
|
236
|
+
|
|
237
|
+
### The key variable
|
|
238
|
+
|
|
239
|
+
The job never receives the key as an input. `key-variable` names the CI variable
|
|
240
|
+
that holds the private key; the job copies it into a `mktemp -d` directory
|
|
241
|
+
outside the workspace, sets mode `0600` under `umask 077`, passes the file path
|
|
242
|
+
to the CLI and deletes the directory with a `trap`. The key is never printed,
|
|
243
|
+
never put on a command line and never lands in the artifacts; a missing or
|
|
244
|
+
empty variable stops the job with a message before the CLI runs.
|
|
245
|
+
|
|
246
|
+
GitLab requires a **masked** variable to be a single line with no spaces, so a
|
|
247
|
+
multiline PEM cannot be masked directly. The component accepts three forms:
|
|
248
|
+
|
|
249
|
+
- a multiline PEM (handy for local runs and this repository's self-test);
|
|
250
|
+
- a base64-encoded PEM on one line — the form to use for a `masked` and
|
|
251
|
+
`protected` variable (`base64 -w0 key.pem`);
|
|
252
|
+
- a GitLab **File** variable: the value is the path to the file that holds the
|
|
253
|
+
PEM, which the job copies into its temporary directory.
|
|
254
|
+
|
|
255
|
+
The test key from [04 §1](docs/spec/04-conformance.md#1-the-test-key) is publicly
|
|
256
|
+
known and only belongs in the component's self-test. This repository does **not**
|
|
257
|
+
configure it as a GitLab variable: the job rebuilds it from `testKey.pkcs8Hex` in
|
|
258
|
+
[the vector](vectors/fact-signature.v1.json) with
|
|
259
|
+
[`scripts/test-key-fixture.mjs`](scripts/test-key-fixture.mjs) and exports it
|
|
260
|
+
under the name `key-variable` points to. The self-test therefore travels with
|
|
261
|
+
the commit — no project setting to provision, nothing to leak, and it runs on a
|
|
262
|
+
fork. The component still reads it as a variable, which is the interface an
|
|
263
|
+
emitter uses; in an emitter's project that variable holds a real key and is
|
|
264
|
+
masked **and** protected. The job exits non-zero when `fact-key build`'s
|
|
265
|
+
self-check is not `verified`, so an unverified bundle never reaches the registry.
|
|
266
|
+
|
|
267
|
+
### Publication, rotation and pinning
|
|
268
|
+
|
|
269
|
+
With `publish: true` the job runs only on a tag pipeline, as [07
|
|
270
|
+
§10](docs/spec/07-fact-key.md#10-emitter-pipeline) describes, and pushes
|
|
271
|
+
`fact-key.v1.json` and `fact-key.v1.sig` with the media types of [07
|
|
272
|
+
§2](docs/spec/07-fact-key.md#2-the-artifact) to
|
|
273
|
+
`<registry-repository>:fact-key-<kid>`, then reports the descriptor. `oras` is
|
|
274
|
+
downloaded from its official release and verified against the checksums that
|
|
275
|
+
release publishes, which protects the download, not the provenance of the
|
|
276
|
+
release: the version is pinned by `oras-version` and approved at review. A new key is
|
|
277
|
+
a new `kid` and therefore a new tag; **add-then-cut** rotation in
|
|
278
|
+
[03 §6](docs/spec/03-trust-policy.md#6-rotation-and-revocation) still applies, and
|
|
279
|
+
a `kid` is never reused for a different key.
|
|
280
|
+
|
|
281
|
+
Every run leaves `fact-key/fact-key.v1.json`, `fact-key.v1.sig` and
|
|
282
|
+
`digests.json` as job artifacts. `digests.json` carries `{kid, documentSha256,
|
|
283
|
+
fingerprintSha256, manifestDigest, package}`; with `publish: false`,
|
|
284
|
+
`manifestDigest` is `null`.
|
|
285
|
+
|
|
286
|
+
The consumer pins the **manifest digest** — the `manifestDigest` the job reports,
|
|
287
|
+
or `oras manifest fetch <repo>:fact-key-<kid> --descriptor` — together with the
|
|
288
|
+
bundle's `documentSha256` and `fingerprintSha256`, confirmed over a second
|
|
289
|
+
channel. Never pin the tag: a re-tag can move the name, not the digest already
|
|
290
|
+
reviewed. `oras` stamps a creation annotation on every push, so republishing the
|
|
291
|
+
same bundle under the same tag yields a different manifest digest; pin the digest
|
|
292
|
+
of the review that was actually approved. A consumer never fetches the bundle at
|
|
293
|
+
fact-verification time.
|
|
294
|
+
|
|
295
|
+
The component is consumed by tag from this repository. It is not published to
|
|
296
|
+
the GitLab CI/CD Catalog: that would require a `release:` job on a tag pipeline,
|
|
297
|
+
which this repository deliberately does not create.
|
|
298
|
+
|
|
299
|
+
### `generate` is not a job
|
|
300
|
+
|
|
301
|
+
The component builds, verifies and publishes; it never creates key material. The
|
|
302
|
+
pair comes from `fact-key generate` run once per rotation, locally or on a
|
|
303
|
+
protected ref ([07 §10](docs/spec/07-fact-key.md#10-emitter-pipeline)), and the
|
|
304
|
+
private half is moved into the emitter's secret store by the operator. CI has no
|
|
305
|
+
step that generates or rotates keys ([PJ-003](docs/adr/PJ-003-fact-key-cli-componente-ci-producto-lockstep.md)).
|
|
306
|
+
The bundle this job publishes is delivery, not custody: it proves the key is the
|
|
307
|
+
one the emitter published and that the publisher holds the private half, and it
|
|
308
|
+
grants no authority beyond the consumer's policy.
|
|
309
|
+
|
|
179
310
|
## Why a separate package
|
|
180
311
|
|
|
181
312
|
`@imolko/ultra-ddd` already has the two insertion points for event signing
|
|
@@ -204,6 +335,9 @@ emitters ──▶ @imolko/ultra-event-signature ◀── consumers
|
|
|
204
335
|
| [06 — delivery](docs/spec/06-delivery.md) | slices, test-first plan, gates, definition of done |
|
|
205
336
|
| [07 — the fact-key bundle](docs/spec/07-fact-key.md) | how an emitter publishes its public key, and how a consumer verifies the publication |
|
|
206
337
|
|
|
338
|
+
Delivery surfaces: the `fact-key` CLI in `bin/` (spec 2) and the GitLab CI
|
|
339
|
+
component in [`templates/fact-key.yml`](templates/fact-key.yml) (spec 3).
|
|
340
|
+
|
|
207
341
|
Machine-readable vectors: [`vectors/fact-signature.v1.json`](vectors/fact-signature.v1.json)
|
|
208
342
|
and [`vectors/fact-key.v1.json`](vectors/fact-key.v1.json).
|
|
209
343
|
|
|
@@ -213,10 +347,10 @@ and [`vectors/fact-key.v1.json`](vectors/fact-key.v1.json).
|
|
|
213
347
|
`signFact`, `verifyFact`, the key-set and trust-policy parsers, the
|
|
214
348
|
interoperability helpers and the fact-key API (`signFactKey`,
|
|
215
349
|
`verifyFactKeyBundle`, `factKeyFingerprint`). The `fact-key` CLI ships under
|
|
216
|
-
`bin
|
|
217
|
-
format and its vectors are frozen,
|
|
218
|
-
dependencies — the only runtime import in
|
|
219
|
-
`node:crypto`.
|
|
350
|
+
`bin/` and the reusable CI component lives in `templates/fact-key.yml`; both are
|
|
351
|
+
released with the package (PJ-003). The wire format and its vectors are frozen,
|
|
352
|
+
and the package still has zero runtime dependencies — the only runtime import in
|
|
353
|
+
`dist-node/index.js` is `node:crypto`.
|
|
220
354
|
|
|
221
355
|
The decisions this package serves are recorded in the store platform's project
|
|
222
356
|
tier: `PJ-049` (a fact is trusted by the key that signed it) and `PJ-050`
|
|
@@ -86,8 +86,9 @@ Never reuse a `kid` for a different key.
|
|
|
86
86
|
|
|
87
87
|
The public key arrives through review as a **fact-key bundle**: the signed
|
|
88
88
|
`fact-key.v1.json` document plus its detached `fact-key.v1.sig`. Generation of
|
|
89
|
-
key material is a manual, protected action.
|
|
90
|
-
`npm run build` (or as `fact-key` once installed)
|
|
89
|
+
key material is a manual, protected action. Inspection runs locally from `bin/`
|
|
90
|
+
after `npm run build` (or as `fact-key` once installed); delivery runs in the
|
|
91
|
+
emitter's pipeline:
|
|
91
92
|
|
|
92
93
|
1. **Generate once per rotation, in the emitter's custody.**
|
|
93
94
|
`fact-key generate --kid <kid> --out <dir>` writes `<kid>.private.pem` in mode
|
|
@@ -106,12 +107,51 @@ key material is a manual, protected action. Run the commands from `bin/` after
|
|
|
106
107
|
`{"kind":"verified", ...}` and exit `0`; anything else is a reason to stop
|
|
107
108
|
the delivery. Confirm the fingerprint with the reviewer over a second
|
|
108
109
|
channel.
|
|
110
|
+
4. **Publish from the emitter's pipeline with the CI component.** Add the
|
|
111
|
+
component to the pipeline and let it run the two checks above and push the
|
|
112
|
+
pair to the registry; do not reimplement the step in a local script.
|
|
113
|
+
|
|
114
|
+
```yaml
|
|
115
|
+
include:
|
|
116
|
+
- component: $CI_SERVER_FQDN/imolko/ultra-stack/ultra-event-signature/fact-key@<tag>
|
|
117
|
+
inputs:
|
|
118
|
+
library-package: "@imolko/ultra-event-signature@<tag>"
|
|
119
|
+
emitter: <emitter>
|
|
120
|
+
kid: <kid>
|
|
121
|
+
source: <source>
|
|
122
|
+
types: <type>,<type>
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
`library-package` must be the exact npm spec of the **same tag** as the
|
|
126
|
+
component; the YAML pins no version of its own. The job reads the private key
|
|
127
|
+
from the variable named by `key-variable` (`FACT_KEY_PRIVATE_KEY` by default),
|
|
128
|
+
keeps it in a `0600` temporary file outside the workspace and deletes it on
|
|
129
|
+
exit. GitLab's **masked** variables are single-line and space-free, so use a
|
|
130
|
+
base64 PEM (`base64 -w0 key.pem`) in a masked and protected variable, or a
|
|
131
|
+
**File** variable whose value is the path to the PEM; the multiline PEM is
|
|
132
|
+
accepted mainly for local runs and this repository's self-test. The job
|
|
133
|
+
publishes only on a tag pipeline with `publish: true`, pushes
|
|
134
|
+
`<registry-repository>:fact-key-<kid>` (default `$CI_REGISTRY_IMAGE`) with the
|
|
135
|
+
bundle media types and reports `documentSha256`, `fingerprintSha256` and
|
|
136
|
+
`manifestDigest` in `digests.json` (`{kid, documentSha256, fingerprintSha256,
|
|
137
|
+
manifestDigest, package}`). `publish: false` stops before the registry and only
|
|
138
|
+
leaves the files as job artifacts in any pipeline. There is deliberately no
|
|
139
|
+
`generate` job: creating the pair is step 1, not CI.
|
|
140
|
+
5. **Pin the manifest digest in the consumer.** Take the `manifestDigest` the
|
|
141
|
+
component reports (or `oras manifest fetch <repo>:fact-key-<kid>
|
|
142
|
+
--descriptor`) and record it in the consumer's configuration together with
|
|
143
|
+
the bundle's `documentSha256` and `fingerprintSha256`. The tag
|
|
144
|
+
`fact-key-<kid>` is a name, not the guarantee: a re-tag moves the name, not
|
|
145
|
+
the digest already reviewed. `oras` stamps a creation annotation on each
|
|
146
|
+
push, so republishing the same bytes yields a different manifest digest; pin
|
|
147
|
+
the digest of the approved publication, not of a retry. A rotation adds the
|
|
148
|
+
new `kid` and its digest before the emitter cuts over, and the old entry stays
|
|
149
|
+
while old facts still need to verify ([add-then-cut](#rotation-is-add-then-cut)).
|
|
109
150
|
|
|
110
151
|
The bundle is delivery, not custody: it proves the key is the one the emitter
|
|
111
152
|
published and that the publisher holds the private half, and it grants no
|
|
112
|
-
authority beyond the consumer's policy.
|
|
113
|
-
|
|
114
|
-
never a tag; a consumer never fetches the bundle at fact-verification time
|
|
153
|
+
authority beyond the consumer's policy. Verification stays offline: a consumer
|
|
154
|
+
never fetches the bundle at fact-verification time
|
|
115
155
|
([07 §8](spec/07-fact-key.md#8-publication)).
|
|
116
156
|
|
|
117
157
|
## The example key is public
|
package/package.json
CHANGED