@nika-open/nika 0.0.0-stage → 0.124.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 +202 -0
- package/README.md +776 -2
- package/dist/bin/nika.js +450 -0
- package/dist/index.cjs +5921 -0
- package/dist/index.d.cts +1913 -0
- package/dist/index.d.ts +1913 -0
- package/dist/index.js +5865 -0
- package/docs/README.md +69 -0
- package/docs/architecture.md +163 -0
- package/docs/compile.md +486 -0
- package/docs/errors.md +154 -0
- package/docs/glossary.md +41 -0
- package/docs/http-api.md +396 -0
- package/docs/migrating-to-0.116.md +164 -0
- package/docs/receipts.md +156 -0
- package/docs/runs.md +670 -0
- package/docs/server.md +543 -0
- package/docs/testing.md +244 -0
- package/docs/upgrading-to-0.123.md +190 -0
- package/openapi.json +3067 -0
- package/package.json +92 -4
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
# Migrating to 0.116
|
|
2
|
+
|
|
3
|
+
> This guide is history: it maps the 0.115 clients onto the one `Nika` class
|
|
4
|
+
> that 0.116 introduced. Moving from 0.120.x to the current 0.124.5 is
|
|
5
|
+
> [upgrading-to-0.123.md](upgrading-to-0.123.md).
|
|
6
|
+
|
|
7
|
+
Version 0.116 is an intentional breaking consolidation of the two published
|
|
8
|
+
0.115 clients into one `Nika` facade. This is a 0.x minor release, but existing
|
|
9
|
+
0.115 imports and method calls do not all remain source-compatible. Migrate in
|
|
10
|
+
a branch and run the packed-package gauntlets before upgrading production.
|
|
11
|
+
|
|
12
|
+
## Removed 0.115 surfaces
|
|
13
|
+
|
|
14
|
+
- The `@supernovae-st/nika-client/local` export and `LocalNika` class are
|
|
15
|
+
removed. Use `new Nika({ bin, cwd })`; call `check()`, `run()`, `events()`,
|
|
16
|
+
and `traceVerify()` on that instance.
|
|
17
|
+
- The root `nika.jobs` and `nika.workflows` namespaces are removed. Use the
|
|
18
|
+
facade methods shown below.
|
|
19
|
+
- `Nika.fromEnv()`, `nika.health()`, `Nika.verifyWebhook()`, and the exported
|
|
20
|
+
webhook helper are removed. Construct the client explicitly; health is now
|
|
21
|
+
an internal compatibility preflight. Keep webhook verification in the
|
|
22
|
+
application boundary that owns its signing format.
|
|
23
|
+
- Preview artifact, workflow-source/reload, and `runAndCollect` helpers are
|
|
24
|
+
removed instead of continuing as methods that always refuse.
|
|
25
|
+
- Node 18 and 20 are no longer supported; the package now requires Node 22 or
|
|
26
|
+
newer.
|
|
27
|
+
|
|
28
|
+
## Constructor migration
|
|
29
|
+
|
|
30
|
+
The 0.115 root constructor was HTTP-only. In 0.116, no URL means the native
|
|
31
|
+
process transport; supplying `url` and `token` selects HTTP. Remote `check()`
|
|
32
|
+
and `run()` also need a local Nika binary (`bin`, `NIKA_BIN`, or the exact
|
|
33
|
+
optional host payload package) because
|
|
34
|
+
the SDK captures and validates immutable snapshot bytes before admission.
|
|
35
|
+
The current by-name HTTP path also accepts contained workflow names without a
|
|
36
|
+
local engine; prefix a local file with `./` to retain snapshot capture.
|
|
37
|
+
|
|
38
|
+
```ts
|
|
39
|
+
// 0.115
|
|
40
|
+
const oldClient = new Nika({ url, token, timeout: 30_000 });
|
|
41
|
+
|
|
42
|
+
// 0.116
|
|
43
|
+
const nika = new Nika({
|
|
44
|
+
url,
|
|
45
|
+
token,
|
|
46
|
+
bin: process.env.NIKA_BIN,
|
|
47
|
+
requestTimeout: 30_000,
|
|
48
|
+
allowInsecureHttp: url.startsWith('http://127.0.0.1'),
|
|
49
|
+
});
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
`timeout`, retries, polling, concurrency, logger, and per-run `signal` options
|
|
53
|
+
from the old HTTP client are gone. Request and frame bounds are client
|
|
54
|
+
invariants; observe or cancel a returned run through its owned lifecycle.
|
|
55
|
+
|
|
56
|
+
## Method mapping
|
|
57
|
+
|
|
58
|
+
| 0.115 | 0.116 |
|
|
59
|
+
| --- | --- |
|
|
60
|
+
| `local.check(file)` | `nika.check(file)` |
|
|
61
|
+
| `local.run(file)` | `await nika.run(file)`, then `nika.events(run)` and `run.done` |
|
|
62
|
+
| `local.runToEnd(file)` | `const run = await nika.run(file); await run.done` |
|
|
63
|
+
| `local.traceVerify(path)` | No path-based replacement; retain the engine-issued receipt and call `nika.traceVerify(receipt)` |
|
|
64
|
+
| `nika.jobs.submit(workflow)` | `nika.run(workflow)` |
|
|
65
|
+
| `nika.jobs.status(id)` | retain the owned run; `nika.status(run)` |
|
|
66
|
+
| `nika.jobs.stream(id)` | `attachRun(id)`, then `events(run)` |
|
|
67
|
+
| `nika.jobs.cancel(id)` | `nika.cancel(run)` |
|
|
68
|
+
| `nika.workflows.list()` | `nika.listWorkflows()` |
|
|
69
|
+
| `nika.workflows.metadata(name)` | `nika.workflow(name)` |
|
|
70
|
+
|
|
71
|
+
In 0.116 the run handle was only `{ id, done }`. The Run now owns its
|
|
72
|
+
lifecycle: `run.events()`, `run.result()`, `run.status()` and `run.cancel()`,
|
|
73
|
+
with `run.done` kept as the alias of `run.result()`. The `nika.events(run)`,
|
|
74
|
+
`nika.cancel(run)` and `nika.status(run)` forms this guide shows still work
|
|
75
|
+
unchanged as deprecated wrappers, and `nika.events(run)` still yields the
|
|
76
|
+
protocol vocabulary; `run.events()` yields one lifecycle vocabulary on both
|
|
77
|
+
transports with that frame on `event.raw`. The wrappers stay through the 0.123
|
|
78
|
+
maintenance line; "Migrating to the Run-owned lifecycle" in
|
|
79
|
+
[runs.md](runs.md#migrating-to-the-run-owned-lifecycle) describes them.
|
|
80
|
+
|
|
81
|
+
The client-level methods reject a look-alike object and a run from another
|
|
82
|
+
client, so persist the job id and reattach after a process restart instead of
|
|
83
|
+
rebuilding a handle by hand.
|
|
84
|
+
|
|
85
|
+
`LocalNika.version()`, `dryRunPlan()`, and `test()` have no One SDK method.
|
|
86
|
+
Keep those CLI-facing probes in deployment/CI (`nika --version`,
|
|
87
|
+
`nika run --dry-run --json`, and `nika test`); the SDK does not emulate them.
|
|
88
|
+
|
|
89
|
+
## The check report changed shape
|
|
90
|
+
|
|
91
|
+
`check()` still returns `clean` and `exitCode`, but the object around them is
|
|
92
|
+
no longer the 0.115 `LocalCheckReport` (eleven curated fields plus a `raw`
|
|
93
|
+
escape hatch). It is the engine's own machine report, passed through: the
|
|
94
|
+
former `raw` contents are now the top level, `reportVersion` is
|
|
95
|
+
`report_version`, and `parseFatal` and `warnings` are gone. The engine emits
|
|
96
|
+
its identity under both casings (`engineVersion` and `engine_version`,
|
|
97
|
+
`buildSha` and `build_sha`, `specSha` and `spec_sha`, `checkReportVersion`
|
|
98
|
+
and `report_version`); read either, do not diff them. In TypeScript only
|
|
99
|
+
`report_version`, `clean`, and `exitCode` are typed; every other field,
|
|
100
|
+
including `cost`, `findings`, and `hints`, is `unknown` behind an index
|
|
101
|
+
signature, so strict callers narrow it themselves. Two problems that look like
|
|
102
|
+
findings (a missing `permits:` block, a missing `max_tokens:`) are reported
|
|
103
|
+
under `hints[]` (`{ kind, task, advice }`, no `code`), not `findings[]`, in
|
|
104
|
+
both versions.
|
|
105
|
+
|
|
106
|
+
`runToEnd()` returned `{ ok, exitCode, events[] }` with every event buffered.
|
|
107
|
+
`run.done` returns the terminal result only; the events ride `events(run)`
|
|
108
|
+
as a bounded iterator. In 0.116 a session retained 256 frames, below the 273 a
|
|
109
|
+
measured clean native run of 90 `mock/echo` tasks writes, so such a run had to
|
|
110
|
+
be observed concurrently or its prefix was gone. The default is now 4096 and a view opened
|
|
111
|
+
after the result replays every retained frame; past the bound it is refused
|
|
112
|
+
with `reason: 'replay_truncated'`, never shortened, and the result is
|
|
113
|
+
unaffected. An explicit `eventBufferSize` keeps its cap. The removed methods (`version()`, `dryRunPlan()`, path-based
|
|
114
|
+
`traceVerify()`) are absent, not stubbed: calling them throws a plain
|
|
115
|
+
`TypeError: … is not a function`, and a trace that only exists as a file
|
|
116
|
+
path in a later process has no SDK verification door in 0.116.
|
|
117
|
+
|
|
118
|
+
## New resident discovery
|
|
119
|
+
|
|
120
|
+
```ts
|
|
121
|
+
const names = await nika.listWorkflows();
|
|
122
|
+
const metadata = await nika.workflow(names[0]);
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
These methods require an HTTP client. A native-process client returns a typed
|
|
126
|
+
`NikaCompatibilityError` with capability `workflowCatalog`.
|
|
127
|
+
|
|
128
|
+
## Durable status
|
|
129
|
+
|
|
130
|
+
```ts
|
|
131
|
+
const run = await nika.run('flow.nika');
|
|
132
|
+
console.log(await nika.status(run));
|
|
133
|
+
console.log(await run.done);
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
`status(run)` is an observation, not terminal settlement. Keep `run.done` as
|
|
137
|
+
the sole terminal promise. Native-process runs refuse `status()` because a
|
|
138
|
+
short-lived process has no independent durable status authority.
|
|
139
|
+
|
|
140
|
+
## Durable run recovery
|
|
141
|
+
|
|
142
|
+
```ts
|
|
143
|
+
const recovered = await nika.attachRun(saved.jobId, {
|
|
144
|
+
lastEventId: saved.lastEventSequence,
|
|
145
|
+
});
|
|
146
|
+
for await (const event of nika.events(recovered)) {
|
|
147
|
+
await saveApplicationCheckpoint(recovered.id, event.sequence);
|
|
148
|
+
}
|
|
149
|
+
console.log(await recovered.done);
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
`attachRun()` is HTTP-only. It proves the job exists, returns a normal owned
|
|
153
|
+
run handle, and resumes the stream with `Last-Event-ID`. Save the job id and
|
|
154
|
+
event cursor in application durable state before the original process exits.
|
|
155
|
+
If more events arrive before the application subscribes than its configured
|
|
156
|
+
buffer can retain, `events()` refuses with `NikaEventBufferOverflowError`
|
|
157
|
+
instead of silently skipping a replay prefix.
|
|
158
|
+
|
|
159
|
+
## Contract and release alignment
|
|
160
|
+
|
|
161
|
+
Version 0.116 targets the engine train whose OpenAPI contract contains check,
|
|
162
|
+
jobs, status, events, cancellation, typed trace verification, resident
|
|
163
|
+
workflow discovery, and schedule CAS. Do not publish the SDK before the
|
|
164
|
+
matching engine release and native payload assets exist.
|
package/docs/receipts.md
ADDED
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
# Prove what ran: receipts, traces and signing keys
|
|
2
|
+
|
|
3
|
+
Every run leaves a *trace*: a tamper-evident, hash-chained record of what
|
|
4
|
+
happened, written by the engine (locally under `.nika/traces/` in its working
|
|
5
|
+
directory). With a signing key, the engine also *seals* the trace: it signs
|
|
6
|
+
the record when the run ends. The run hands your code a *receipt*, and
|
|
7
|
+
`traceVerify(receipt)` asks the engine to check the trace against it. The
|
|
8
|
+
package never reads a trace or does cryptography itself.
|
|
9
|
+
|
|
10
|
+
## What `traceVerify()` answers
|
|
11
|
+
|
|
12
|
+
Measured on engine 0.123.0 with the quick-start file:
|
|
13
|
+
|
|
14
|
+
| Where the run happened | `traceVerify()` answers | What it means |
|
|
15
|
+
|---|---|---|
|
|
16
|
+
| Local engine, with a key it can read | `{ verified: true, verdict: 'verified' }` | the record is sealed and matches the receipt |
|
|
17
|
+
| Local engine, no key it can read | `{ verified: false, verdict: 'invalid', reason: 'receipt_mismatch' }` | the run still succeeded, but its record is unsealed |
|
|
18
|
+
| `nika serve` with a key it can read | `{ verified: true, verdict: 'sealed', reason: 'sealed' }` | the job's journal is sealed and names this receipt's trace |
|
|
19
|
+
| `nika serve` without one | `{ verified: true, verdict: 'ok', reason: 'unsealed' }` | the job's journal is intact but unsigned |
|
|
20
|
+
|
|
21
|
+
- **Locally**, `traceVerify` runs the engine's verifier on the trace the
|
|
22
|
+
receipt names (`nika trace verify`), then checks that the receipt matches
|
|
23
|
+
the engine's evidence for it (`nika trace evidence`): `verified: true`
|
|
24
|
+
means both held. `receipt_mismatch` is also the answer for a tampered or
|
|
25
|
+
edited receipt: do not read every one as "just unsigned".
|
|
26
|
+
- **Over HTTP**, `traceVerify` asks the server for its verdict on the journal
|
|
27
|
+
it wrote for the job (`GET /v1/jobs/{id}/trace/verify`). The verdict is the
|
|
28
|
+
CLI's word, in lower case: `ok` (intact, unsigned), `sealed`, `anchored` and
|
|
29
|
+
`replayed` hold; `incomplete`, `tampered` and `broken` do not; `unchained`,
|
|
30
|
+
`empty`, `unreadable`, `refused`, `line-over-long` and `unknown` are the
|
|
31
|
+
CLI's refusal classes; `unavailable` means the server has no journal for the
|
|
32
|
+
job (refused before its first event, still queued, or a backend that keeps
|
|
33
|
+
none). `reason` is always present: beside a verdict that holds it names the
|
|
34
|
+
seal tier (`sealed`, `unsealed`). The package sets `verified: true` only for
|
|
35
|
+
a verdict that holds **and** names this receipt's `trace_id`.
|
|
36
|
+
|
|
37
|
+
> [!WARNING]
|
|
38
|
+
> **Over HTTP, check `proof.verified` first.** `verdict` and `reason` are the
|
|
39
|
+
> server's words about the job's journal: they stay `sealed` even when the
|
|
40
|
+
> receipt you passed does not match that journal, and then `verified` is
|
|
41
|
+
> `false` (measured on 0.123.0 with a receipt whose `trace_id` was changed).
|
|
42
|
+
> Treat a job as sealed only when
|
|
43
|
+
> `proof.verified && ['sealed', 'anchored', 'replayed'].includes(proof.verdict ?? '')`;
|
|
44
|
+
> `verified: true` with `verdict: 'ok'` means intact but unsigned.
|
|
45
|
+
|
|
46
|
+
> [!IMPORTANT]
|
|
47
|
+
> A verified receipt proves that the run's record is intact and matches the
|
|
48
|
+
> receipt. It does not prove that the workflow was right, or that a person
|
|
49
|
+
> read its output. The record is tamper-evident, not tamper-proof.
|
|
50
|
+
|
|
51
|
+
## Admitted, executed, sealed: three different facts
|
|
52
|
+
|
|
53
|
+
| Fact | How you see it | What it is not |
|
|
54
|
+
|---|---|---|
|
|
55
|
+
| **Admitted** | `run()` resolves with a `NikaRun`. A workflow the engine refuses makes `run()` throw `NikaOperationError` (`NIKA-SEC-004`, `NIKA-PARSE-005`, `NIKA-1708`…), and no run exists. `check()` shows the same verdict without running: `clean: false` and the findings. | Not a successful execution. |
|
|
56
|
+
| **Executed** | `run.result()` and `isNikaRunSucceeded(result)`. An admitted failure is data (`status: "failed"`). A human gate is `paused` (a `run.waiting` event), not success. | Not proof that the record is sealed. |
|
|
57
|
+
| **Sealed** | `result.receipt.sealed` and `traceVerify(receipt)`. Tamper-evident, not tamper-proof; not replayed unless you ask the CLI (`--replay`); not anchored without a sidecar. | Not "the workflow was correct", and not "a person read the output". |
|
|
58
|
+
|
|
59
|
+
Measured on engine 0.123.0 with the quick-start file: `run.events()` yields
|
|
60
|
+
the same six events with or without a signing key. With a key, the receipt
|
|
61
|
+
reads `sealed: true` and `traceVerify` returns
|
|
62
|
+
`{ verified: true, verdict: 'verified' }`. With an empty `HOME` and no key,
|
|
63
|
+
the same run **succeeds** with `sealed: false`, and `traceVerify` returns
|
|
64
|
+
`{ verified: false, verdict: 'invalid', reason: 'receipt_mismatch' }`, while
|
|
65
|
+
the engine's own `nika trace verify` still calls the journal chain OK and
|
|
66
|
+
unsealed. The event count that command prints counts journal entries; it is
|
|
67
|
+
not the number of `run.events()`.
|
|
68
|
+
|
|
69
|
+
**Watch the three facts from TypeScript, then one changed byte.**
|
|
70
|
+
|
|
71
|
+
<p align="center">
|
|
72
|
+
<picture>
|
|
73
|
+
<source media="(prefers-reduced-motion: reduce)" srcset="https://raw.githubusercontent.com/nika-open/nika-client/HEAD/media/stills/sdk-admitted-executed-sealed.png">
|
|
74
|
+
<img src="https://raw.githubusercontent.com/nika-open/nika-client/HEAD/media/gifs/sdk-admitted-executed-sealed.gif" alt="node gate.mts on a workflow that runs ls under permits: {} prints check refused · exit 2 and NIKA-SEC-004, then run not started: no run, no events, no trace; a one-line permits fix checks clean and runs. node prove.mts with no signing key prints receipt sealed false · 5 events and not verified · invalid · receipt_mismatch; after NIKA_KEYCHAIN=off nika key init it prints sealed true · 6 events and verified. node tamper.mts changes one byte on line 4 of the trace, and node verify.mts prints not verified · invalid and engine BROKEN at line 5" width="860">
|
|
75
|
+
</picture>
|
|
76
|
+
</p>
|
|
77
|
+
<p align="center"><sub>Admitted: <code>check()</code> and <code>run()</code> refuse the file and no run exists. Executed, not sealed: with no key the run succeeds and the receipt reads <code>sealed false</code> over 5 journal entries. Sealed: after <code>NIKA_KEYCHAIN=off nika key init</code> the next run of the same file has 6, the last one <code>run_sealed</code>, and verifies. Then one changed byte, and the stored receipt fails: <code>BROKEN at line 5</code>. Recorded from <code>@supernovae-st/nika</code> 0.124.0 and its bundled engine; the runs are <code>mock/echo</code> rehearsals.<br>▶ <a href="https://github.com/nika-open/nika-client/blob/main/media/videos/sdk-admitted-executed-sealed.mp4?raw=true">MP4</a> · <a href="https://github.com/nika-open/nika-client/blob/main/media/transcripts/sdk-admitted-executed-sealed.txt">transcript</a> · <a href="https://github.com/nika-open/nika-client/tree/main/scripts/media/scenes/sdk-admitted-executed-sealed">the programs it runs</a></sub></p>
|
|
78
|
+
|
|
79
|
+
## What a receipt carries
|
|
80
|
+
|
|
81
|
+
Pass a receipt back unchanged, and store it with what it proves.
|
|
82
|
+
|
|
83
|
+
- **A local run's receipt** carries the proof fields (`trace_path`,
|
|
84
|
+
`chain_head`, `chain_len`, `sealed`) with `trace_id`, `execution_id`,
|
|
85
|
+
`snapshot_digest` and `receipt_format`.
|
|
86
|
+
- **A `nika serve` job's receipt** carries the job's identity (`job_id`,
|
|
87
|
+
`execution_id`, `trace_id`, `snapshot_digest`, `origin`) and the
|
|
88
|
+
`chain_head`. Store it with the job id. A scheduled job's `origin` names the
|
|
89
|
+
firing; see [server.md](server.md#schedules).
|
|
90
|
+
|
|
91
|
+
A run receipt is not the per-call access receipt. What a model call asked of
|
|
92
|
+
its route and what the route read back (`nika/access-selection@1`: model,
|
|
93
|
+
effort and, when the file declares one, the service tier) is a row of the
|
|
94
|
+
task's frame in the journal the seal covers, not a field of the run receipt.
|
|
95
|
+
On a local run, read it with `readNikaAccessSelection`
|
|
96
|
+
([runs.md](runs.md#the-files-own-access-contract-runaccess)).
|
|
97
|
+
|
|
98
|
+
A trace can hold model outputs and file contents, so keep `.nika/` out of
|
|
99
|
+
git and treat traces as application data.
|
|
100
|
+
|
|
101
|
+
## Signing keys: where the engine finds them
|
|
102
|
+
|
|
103
|
+
Run-signing keys belong to the engine. `nika key init` mints one,
|
|
104
|
+
`nika key trust` prints its public key and fingerprint to enroll on other
|
|
105
|
+
machines, `nika key rotate` retires it and mints a new one (records signed
|
|
106
|
+
with a retired key stay verifiable), and, on Linux, `nika key align` copies a
|
|
107
|
+
Secret Service key to the files the other processes read.
|
|
108
|
+
|
|
109
|
+
Which key a process signs with depends on the process and, for `nika` run
|
|
110
|
+
from a terminal, on the platform. Nika 0.123 and later:
|
|
111
|
+
|
|
112
|
+
| Process | Opens an OS keychain? | Signs with, in this order |
|
|
113
|
+
|---|---|---|
|
|
114
|
+
| `nika` run from a terminal, on macOS | no: Nika 0.123 and later never open the keychain on macOS, even from a terminal (`nika doctor` says `the keychain is not opened by this ad-hoc build`) | `NIKA_RUN_KEY_FILE` + `NIKA_RUN_PUB_FILE`, then `~/.nika/keys/` |
|
|
115
|
+
| `nika` run from a terminal, on Linux | yes: the desktop's Secret Service, when one answers | `NIKA_RUN_KEY_FILE` + `NIKA_RUN_PUB_FILE`, the Secret Service, then `~/.nika/keys/` |
|
|
116
|
+
| the engine your app starts (`new Nika()`) | never: it has no terminal | `NIKA_RUN_KEY_FILE` + `NIKA_RUN_PUB_FILE`, then `~/.nika/keys/` |
|
|
117
|
+
| `nika serve` | never | `NIKA_RUN_KEY_FILE` + `NIKA_RUN_PUB_FILE`, then `~/.nika/keys/` |
|
|
118
|
+
|
|
119
|
+
So the key your app's runs use must be a file, and `NIKA_KEYCHAIN=off` makes
|
|
120
|
+
one on every platform:
|
|
121
|
+
|
|
122
|
+
- **A new machine.** `NIKA_KEYCHAIN=off ./node_modules/.bin/nika key init`
|
|
123
|
+
writes the key to `~/.nika/keys/` (mode `0600`), where every process reads
|
|
124
|
+
it.
|
|
125
|
+
- **Without the variable, on Linux.** From a terminal, `nika key init`
|
|
126
|
+
refuses with `run-signing key material already exists`, even on a new
|
|
127
|
+
machine: off macOS the engine cannot see whether the keychain already holds
|
|
128
|
+
a run-key, so it never risks replacing one. On a desktop,
|
|
129
|
+
`nika key init --force` then stores the key in the Secret Service only,
|
|
130
|
+
where your app's engine and `nika serve` never look. To repair that, run
|
|
131
|
+
`./node_modules/.bin/nika key align` once from a terminal: it copies the
|
|
132
|
+
Secret Service key to `~/.nika/keys/`, retiring any other file key it
|
|
133
|
+
replaces, so the CLI, your app and `nika serve` sign with one key.
|
|
134
|
+
- **Without the variable, on macOS.** `nika key init` from a terminal writes
|
|
135
|
+
the files too, unless the keychain holds a run-key that Nika 0.122 or older
|
|
136
|
+
stored there. Then it refuses, and the repair it names, `nika key align`,
|
|
137
|
+
cannot succeed with Nika 0.123 and later, which can neither read nor copy
|
|
138
|
+
that key: it exits with `this process does not open the keychain`. The
|
|
139
|
+
variable skips the keychain check and mints a new key as files, a new
|
|
140
|
+
signing identity beside the old keychain key.
|
|
141
|
+
- **CI and servers.** Give the engine an explicit pair through
|
|
142
|
+
`NIKA_RUN_KEY_FILE` and `NIKA_RUN_PUB_FILE`; `nika key init` with those two
|
|
143
|
+
variables set writes the pair there.
|
|
144
|
+
- **Rotation.** `NIKA_KEYCHAIN=off nika key rotate` retires the file key to
|
|
145
|
+
`~/.nika/keys/retired.pub` and writes the next one as files. Without the
|
|
146
|
+
variable, on a Linux desktop terminal, the new key would go to the Secret
|
|
147
|
+
Service, and your app would keep signing with the old file key.
|
|
148
|
+
- **Check it.** `nika doctor` prints a `run-key` line for the process that
|
|
149
|
+
runs it. To see what the engine your app starts sees, take the terminal
|
|
150
|
+
away: `./node_modules/.bin/nika doctor 2>&1 | cat` names the key file it
|
|
151
|
+
signs with, or says `none · runs stay unsigned`.
|
|
152
|
+
|
|
153
|
+
`NIKA_KEYCHAIN=off` skips only the keychain; the file and explicit-pair paths
|
|
154
|
+
stay. Store receipts and public trust material in your app. Never copy a
|
|
155
|
+
private run key into SDK configuration, source control, workflow inputs or an
|
|
156
|
+
HTTP request.
|