@niwa-labs/host 0.0.0-stage → 0.0.0
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 +21 -0
- package/README.md +2 -2
- package/package.json +16 -4
- package/src/access-actions.ts +193 -0
- package/src/access-control.ts +333 -0
- package/src/call-operations.ts +176 -0
- package/src/cockpit-catalog.ts +99 -0
- package/src/describe.ts +55 -0
- package/src/doors.ts +272 -0
- package/src/host-types.ts +43 -0
- package/src/host.ts +3346 -0
- package/src/index.ts +10 -0
- package/src/plugin-install.ts +249 -0
- package/src/state.ts +261 -0
- package/src/stores.ts +131 -0
- package/test/abandon.test.ts +58 -0
- package/test/action-refusal-restart.test.ts +46 -0
- package/test/action-step.test.ts +363 -0
- package/test/action-wait-restart.test.ts +96 -0
- package/test/builtin-actions.test.ts +21 -0
- package/test/cancel-steps.test.ts +150 -0
- package/test/catch-up.test.ts +378 -0
- package/test/causes.test.ts +138 -0
- package/test/client.test.ts +190 -0
- package/test/cockpit-catalog.test.ts +118 -0
- package/test/crash-between-steps.test.ts +88 -0
- package/test/declared-values.test.ts +175 -0
- package/test/deep-nested-pause.test.ts +147 -0
- package/test/fixtures/action-step-host.ts +166 -0
- package/test/fixtures/action-wait-restart-host.ts +62 -0
- package/test/fixtures/catch-up-host.ts +91 -0
- package/test/fixtures/causes-host.ts +78 -0
- package/test/fixtures/client-host.ts +52 -0
- package/test/fixtures/crash-between-steps-host.ts +71 -0
- package/test/fixtures/declared-values-host.ts +110 -0
- package/test/fixtures/intercept-order-host.ts +112 -0
- package/test/fixtures/intercept-step-host.ts +106 -0
- package/test/fixtures/live-frames-host.ts +81 -0
- package/test/fixtures/long-wait-host.ts +78 -0
- package/test/fixtures/nested-wait-host.ts +120 -0
- package/test/fixtures/no-repeat-crash-host.ts +79 -0
- package/test/fixtures/plugin-replace-host.ts +176 -0
- package/test/fixtures/record-refusal-crash.ts +50 -0
- package/test/fixtures/recovery-contracts-host.ts +79 -0
- package/test/fixtures/repeated-write-host.ts +39 -0
- package/test/fixtures/replay-mismatch-host.ts +66 -0
- package/test/fixtures/single-writer-host.ts +113 -0
- package/test/fixtures/state-host.ts +118 -0
- package/test/fixtures/wait-restart-host.ts +82 -0
- package/test/guards.test.ts +448 -0
- package/test/handler-emit.test.ts +116 -0
- package/test/host.test.ts +114 -0
- package/test/intercept-adjust.test.ts +318 -0
- package/test/intercept-order.test.ts +276 -0
- package/test/intercept-step.test.ts +144 -0
- package/test/large-outcome.test.ts +60 -0
- package/test/live-frames.test.ts +150 -0
- package/test/live-ready.test.ts +61 -0
- package/test/long-wait.test.ts +168 -0
- package/test/nested-outcome.test.ts +75 -0
- package/test/nested-wait.test.ts +111 -0
- package/test/no-repeat-crash.test.ts +132 -0
- package/test/offer-replace.test.ts +39 -0
- package/test/plugin-async-setup.test.ts +22 -0
- package/test/plugin-copies.test.ts +87 -0
- package/test/plugin-emit.test.ts +43 -0
- package/test/plugin-install-failure.test.ts +121 -0
- package/test/plugin-install-hash.test.ts +57 -0
- package/test/plugin-needs.test.ts +80 -0
- package/test/plugin-replace.test.ts +225 -0
- package/test/plugin-uninstall.test.ts +70 -0
- package/test/plugin-version-copies.test.ts +53 -0
- package/test/plugin-version.test.ts +180 -0
- package/test/read-filter.test.ts +136 -0
- package/test/read-query.test.ts +92 -0
- package/test/record-admission.test.ts +294 -0
- package/test/recovery-contracts.test.ts +107 -0
- package/test/repeated-write.test.ts +119 -0
- package/test/replay-mismatch.test.ts +79 -0
- package/test/replay.test.ts +135 -0
- package/test/single-writer.test.ts +267 -0
- package/test/state.test.ts +246 -0
- package/test/step-by-name.test.ts +122 -0
- package/test/stores.test.ts +102 -0
- package/test/stream.test.ts +154 -0
- package/test/subscriber-stream.test.ts +71 -0
- package/test/subscribers.test.ts +101 -0
- package/test/subscriptions.test.ts +632 -0
- package/test/trace-call.test.ts +124 -0
- package/test/trigger-filter.test.ts +42 -0
- package/test/use-many.test.ts +151 -0
- package/test/wait-query.test.ts +117 -0
- package/test/wait-restart.test.ts +187 -0
- package/test/wire-read-access.test.ts +85 -0
- package/tsconfig.json +6 -0
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Calls a client names with an operation id of its own.
|
|
3
|
+
*
|
|
4
|
+
* A client that lost its connection while a call was on its way cannot tell whether the call was
|
|
5
|
+
* made. It asks again under the same id: the same action with the same input answers what the
|
|
6
|
+
* first call answered, from the journal, and is not made a second time; another call under the id
|
|
7
|
+
* is a conflict. The id is the caller's: the action runs under an operation id made from the caller
|
|
8
|
+
* and its id, so two callers never share one, and an action that keys its own work by the operation
|
|
9
|
+
* id (a send into a session) sees the same id on every retry.
|
|
10
|
+
*
|
|
11
|
+
* Only a call that began is written down: one the grant or the schema refused did nothing, and may
|
|
12
|
+
* be asked again with any body. A call that ended is answered as it ended, whole. A failure the
|
|
13
|
+
* action said did nothing (`effectPossible: false`) is made again, and so is any failure or cut-off
|
|
14
|
+
* of an action that may be repeated; an action that may not be repeated answers its failure again,
|
|
15
|
+
* and a call of it that was cut off before its end is refused, since nobody knows what it did.
|
|
16
|
+
*/
|
|
17
|
+
|
|
18
|
+
import { createHash } from "node:crypto";
|
|
19
|
+
|
|
20
|
+
import type { ActionName, ArtifactStore, Caller, NewRecord, OperationId, RecordId, RecordTypeName, Recovery, StoredRecord } from "@niwa-labs/core";
|
|
21
|
+
import { CORE_TYPES, RecordRefused, effectPossibleAfter, keptOutcome, newRecordId, stableJson, storedOutcome, streamId } from "@niwa-labs/core";
|
|
22
|
+
|
|
23
|
+
/** A retry under an operation id the journal cannot answer as asked. */
|
|
24
|
+
export class OperationRefusal extends Error {
|
|
25
|
+
constructor(
|
|
26
|
+
readonly code: "operation-conflict" | "operation-unknown" | "operation-unnamed",
|
|
27
|
+
message: string,
|
|
28
|
+
) {
|
|
29
|
+
super(message);
|
|
30
|
+
this.name = code;
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/** How a call under an operation ended, as the journal keeps it. */
|
|
35
|
+
type Settled =
|
|
36
|
+
| { status: "completed"; value: unknown }
|
|
37
|
+
| { status: "refused"; audit: RecordId }
|
|
38
|
+
| { status: "failed"; error: string; code?: string; effectPossible: boolean };
|
|
39
|
+
|
|
40
|
+
interface Began {
|
|
41
|
+
operation: OperationId;
|
|
42
|
+
action: ActionName;
|
|
43
|
+
digest: string;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/** What the operations need of the host: the records of an operation, and a way to commit records. */
|
|
47
|
+
export interface OperationsHost {
|
|
48
|
+
get(id: RecordId): StoredRecord | undefined;
|
|
49
|
+
/** The records of a type written under an operation id, oldest first. */
|
|
50
|
+
find(type: RecordTypeName, operation: OperationId): StoredRecord[];
|
|
51
|
+
commit(records: NewRecord[]): void;
|
|
52
|
+
/** Where an answer too large for a record is kept: the record holds its reference. */
|
|
53
|
+
readonly artifacts: ArtifactStore;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/** The operation id a caller's own id stands for. */
|
|
57
|
+
export function operationOf(caller: Caller, operation: string): OperationId {
|
|
58
|
+
const who = caller.kind !== "client" ? caller.kind : caller.principal === undefined ? `client:${caller.id}` : `${caller.principal.kind}:${caller.principal.id}`;
|
|
59
|
+
return `cop_${createHash("sha256").update(`${who}\0${operation}`).digest("hex").slice(0, 40)}` as OperationId;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
/** An error the first call ended with, given again. */
|
|
63
|
+
function answered(settled: Extract<Settled, { status: "failed" }>): Error {
|
|
64
|
+
const error = new Error(settled.error);
|
|
65
|
+
if (settled.code !== undefined) error.name = settled.code;
|
|
66
|
+
return error;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
export class CallOperations {
|
|
70
|
+
/** The calls under an operation that are running now: a retry waits for the one running. */
|
|
71
|
+
private readonly running = new Map<OperationId, { digest: string; answer: Promise<unknown> }>();
|
|
72
|
+
|
|
73
|
+
constructor(private readonly host: OperationsHost) {}
|
|
74
|
+
|
|
75
|
+
/**
|
|
76
|
+
* An operation id is kept for the caller that gave it, and a retry comes on a new connection: it
|
|
77
|
+
* finds its first call only when the caller is the same after the reconnect, which only a token
|
|
78
|
+
* says. A plain client is refused before anything runs, instead of being run again as a stranger.
|
|
79
|
+
*/
|
|
80
|
+
requireNamed(named: boolean, given: string): void {
|
|
81
|
+
if (named) return;
|
|
82
|
+
throw new OperationRefusal("operation-unnamed", `operation "${given}" needs a client that shows a token: without one a retry on a new connection is another caller and would run again`);
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/**
|
|
86
|
+
* Make a call under the caller's operation id once. `run` makes the call under the id, and says
|
|
87
|
+
* when the action itself begins; a call that is refused before that is not written down.
|
|
88
|
+
*/
|
|
89
|
+
async once(
|
|
90
|
+
caller: Caller,
|
|
91
|
+
given: string,
|
|
92
|
+
action: ActionName,
|
|
93
|
+
input: unknown,
|
|
94
|
+
recovery: Recovery | undefined,
|
|
95
|
+
run: (operation: OperationId, began: () => void, actor: Caller) => Promise<unknown>,
|
|
96
|
+
): Promise<unknown> {
|
|
97
|
+
const operation = operationOf(caller, given);
|
|
98
|
+
const digest = createHash("sha256").update(stableJson([action, input ?? null])).digest("hex");
|
|
99
|
+
const conflict = (): OperationRefusal =>
|
|
100
|
+
new OperationRefusal("operation-conflict", `operation "${given}" was another call: an id names one call, with one action and one input`);
|
|
101
|
+
|
|
102
|
+
const running = this.running.get(operation);
|
|
103
|
+
if (running !== undefined) {
|
|
104
|
+
if (running.digest !== digest) throw conflict();
|
|
105
|
+
return running.answer;
|
|
106
|
+
}
|
|
107
|
+
const first = this.host.find(CORE_TYPES.callBegan, operation)[0];
|
|
108
|
+
const began = first?.data as Began | undefined;
|
|
109
|
+
if (began !== undefined) {
|
|
110
|
+
if (began.digest !== digest) throw conflict();
|
|
111
|
+
const kept = (this.host.find(CORE_TYPES.callSettled, operation).at(-1)?.data as { outcome: unknown } | undefined)?.outcome;
|
|
112
|
+
const settled = kept === undefined ? undefined : (storedOutcome(kept, this.host.artifacts) as Settled);
|
|
113
|
+
if (settled?.status === "completed") return settled.value;
|
|
114
|
+
if (settled?.status === "refused") {
|
|
115
|
+
const audit = this.host.get(settled.audit);
|
|
116
|
+
if (audit === undefined) throw new Error(`missing record refusal "${settled.audit}"`);
|
|
117
|
+
throw RecordRefused.fromAudit(audit);
|
|
118
|
+
}
|
|
119
|
+
const repeatable = recovery === "repeat" || recovery === "repeat-with-key";
|
|
120
|
+
if (settled !== undefined && settled.effectPossible && !repeatable) throw answered(settled);
|
|
121
|
+
if (settled === undefined && !repeatable) {
|
|
122
|
+
throw new OperationRefusal("operation-unknown", `operation "${given}" was cut off before ${action} ended: it may have been done, and it is not made again`);
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
const answer = this.made(caller, first?.actor ?? caller, operation, action, digest, run);
|
|
127
|
+
this.running.set(operation, { digest, answer });
|
|
128
|
+
try {
|
|
129
|
+
return await answer;
|
|
130
|
+
} finally {
|
|
131
|
+
this.running.delete(operation);
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
private async made(
|
|
136
|
+
caller: Caller,
|
|
137
|
+
actor: Caller,
|
|
138
|
+
operation: OperationId,
|
|
139
|
+
action: ActionName,
|
|
140
|
+
digest: string,
|
|
141
|
+
run: (operation: OperationId, began: () => void, actor: Caller) => Promise<unknown>,
|
|
142
|
+
): Promise<unknown> {
|
|
143
|
+
let began = false;
|
|
144
|
+
const settle = (outcome: Settled): void => {
|
|
145
|
+
if (!began) return;
|
|
146
|
+
// An answer larger than a record should hold is kept as an artifact, as a step's is.
|
|
147
|
+
const kept = outcome.status === "completed" ? keptOutcome(outcome, this.host.artifacts) : outcome;
|
|
148
|
+
this.host.commit([this.record(caller, CORE_TYPES.callSettled, { operation, action, digest, outcome: kept })]);
|
|
149
|
+
};
|
|
150
|
+
try {
|
|
151
|
+
const value = await run(operation, () => {
|
|
152
|
+
began = true;
|
|
153
|
+
this.host.commit([this.record(caller, CORE_TYPES.callBegan, { operation, action, digest } satisfies Began)]);
|
|
154
|
+
}, actor);
|
|
155
|
+
settle({ status: "completed", value: value ?? null });
|
|
156
|
+
return value;
|
|
157
|
+
} catch (error) {
|
|
158
|
+
if (error instanceof RecordRefused) {
|
|
159
|
+
settle({status: "refused", audit: error.audit.id});
|
|
160
|
+
throw error;
|
|
161
|
+
}
|
|
162
|
+
settle({
|
|
163
|
+
status: "failed",
|
|
164
|
+
error: error instanceof Error ? error.message : String(error),
|
|
165
|
+
...(error instanceof Error ? { code: error.name } : {}),
|
|
166
|
+
effectPossible: effectPossibleAfter(error),
|
|
167
|
+
});
|
|
168
|
+
throw error;
|
|
169
|
+
}
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
private record(caller: Caller, type: (typeof CORE_TYPES)["callBegan" | "callSettled"], data: unknown): NewRecord {
|
|
173
|
+
const id = newRecordId("cop");
|
|
174
|
+
return { id, stream: streamId("calls"), type, schema: 1, data, actor: caller, cause: null, root: id };
|
|
175
|
+
}
|
|
176
|
+
}
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The catalogue of cockpit modules: what the plugins offer (`COCKPIT_MODULE`), listed with the hash of each
|
|
3
|
+
* module's code.
|
|
4
|
+
*
|
|
5
|
+
* A module is not imported here. It is a source file inside its plugin's tree, and the web server builds it for the
|
|
6
|
+
* browser. Its hash covers the entry and every local file it imports, so a changed file is a new address and no cache
|
|
7
|
+
* serves old code.
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
import { createHash } from "node:crypto";
|
|
11
|
+
import { existsSync, readFileSync, statSync } from "node:fs";
|
|
12
|
+
import { dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
|
|
13
|
+
|
|
14
|
+
import type { CockpitModuleOffer, Offered } from "@niwa-labs/plugin";
|
|
15
|
+
import type { CatalogAnswer } from "@niwa-labs/client";
|
|
16
|
+
|
|
17
|
+
const LOADERS = { ".ts": "ts", ".tsx": "tsx", ".js": "js", ".jsx": "jsx", ".mjs": "js", ".mts": "ts" } as const;
|
|
18
|
+
const EXTENSIONS = [".tsx", ".ts", ".jsx", ".js", ".mts", ".mjs"];
|
|
19
|
+
const ID = /^[a-z][a-z0-9]*(?:[-.][a-z0-9]+)*$/;
|
|
20
|
+
|
|
21
|
+
function isFile(path: string): boolean {
|
|
22
|
+
return existsSync(path) && statSync(path).isFile();
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
/** The file a relative import names, with the extensions and the index file a bundler would try; undefined when none. */
|
|
26
|
+
function resolveLocal(from: string, specifier: string): string | undefined {
|
|
27
|
+
const base = resolve(dirname(from), specifier);
|
|
28
|
+
const candidates = [base, ...EXTENSIONS.map((ext) => `${base}${ext}`), ...EXTENSIONS.map((ext) => join(base, `index${ext}`))];
|
|
29
|
+
return candidates.find(isFile);
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** The local files a source imports: the relative specifiers only, those that name a file. */
|
|
33
|
+
function localImports(file: string, source: string): string[] {
|
|
34
|
+
const loader = LOADERS[extname(file) as keyof typeof LOADERS];
|
|
35
|
+
if (loader === undefined) return [];
|
|
36
|
+
let found: ReturnType<Bun.Transpiler["scanImports"]>;
|
|
37
|
+
try {
|
|
38
|
+
found = new Bun.Transpiler({ loader }).scanImports(source);
|
|
39
|
+
} catch {
|
|
40
|
+
// A file that does not parse is part of the module and imports nothing here: the build says what is wrong with it.
|
|
41
|
+
return [];
|
|
42
|
+
}
|
|
43
|
+
return found
|
|
44
|
+
.map((entry) => entry.path)
|
|
45
|
+
.filter((path) => path.startsWith("."))
|
|
46
|
+
.flatMap((path) => resolveLocal(file, path) ?? []);
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/** The sha256 of a file and of every local file it imports, each by its path relative to the entry. */
|
|
50
|
+
export function closureHash(entry: string): string {
|
|
51
|
+
const files = new Map<string, Uint8Array>();
|
|
52
|
+
const queue = [entry];
|
|
53
|
+
for (let file = queue.pop(); file !== undefined; file = queue.pop()) {
|
|
54
|
+
if (files.has(file)) continue;
|
|
55
|
+
const bytes = readFileSync(file);
|
|
56
|
+
files.set(file, bytes);
|
|
57
|
+
queue.push(...localImports(file, bytes.toString("utf8")));
|
|
58
|
+
}
|
|
59
|
+
const hash = createHash("sha256");
|
|
60
|
+
for (const [file, bytes] of [...files].sort(([a], [b]) => a.localeCompare(b))) {
|
|
61
|
+
hash.update(`${relative(dirname(entry), file)}\0`).update(bytes).update("\0");
|
|
62
|
+
}
|
|
63
|
+
return hash.digest("hex");
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
function fileHash(file: string): string {
|
|
67
|
+
return createHash("sha256").update(readFileSync(file)).digest("hex");
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/** Why an offer cannot be listed, undefined when it can. */
|
|
71
|
+
function problemWith(offer: CockpitModuleOffer): string | undefined {
|
|
72
|
+
if (!ID.test(offer.id)) return `the id "${offer.id}" is not lowercase words joined by - or .`;
|
|
73
|
+
for (const file of [offer.entry, ...(offer.styles ?? [])]) {
|
|
74
|
+
if (!isAbsolute(file)) return `${file} is not an absolute path`;
|
|
75
|
+
if (!isFile(file)) return `${file} is not a file`;
|
|
76
|
+
}
|
|
77
|
+
return undefined;
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/**
|
|
81
|
+
* The modules the plugins offer, in the order the plugins were installed. An offer that is not a module (a bad id, a
|
|
82
|
+
* file that is not there) is an error of the plugin that made it, said when the catalogue is read.
|
|
83
|
+
*/
|
|
84
|
+
export function catalogOf(offers: readonly Offered<CockpitModuleOffer>[], versionOf: (plugin: string) => string): CatalogAnswer {
|
|
85
|
+
return {
|
|
86
|
+
modules: offers.map(({ plugin, value }) => {
|
|
87
|
+
const problem = problemWith(value);
|
|
88
|
+
if (problem !== undefined) throw new TypeError(`plugin "${plugin}" offers the cockpit module "${value.id}": ${problem}`);
|
|
89
|
+
return {
|
|
90
|
+
id: value.id,
|
|
91
|
+
plugin,
|
|
92
|
+
version: versionOf(plugin),
|
|
93
|
+
entry: value.entry,
|
|
94
|
+
hash: closureHash(value.entry),
|
|
95
|
+
styles: (value.styles ?? []).map((file) => ({ file, hash: fileHash(file) })),
|
|
96
|
+
};
|
|
97
|
+
}),
|
|
98
|
+
};
|
|
99
|
+
}
|
package/src/describe.ts
ADDED
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* describe.ts — niwa's self-description, generated from the registered actions and record types
|
|
3
|
+
*. There is no second list: a plugin that declares an action
|
|
4
|
+
* adds it to the description with no change here.
|
|
5
|
+
*
|
|
6
|
+
* The schemas are rendered as JSON Schema from the same zod schemas the host validates with
|
|
7
|
+
*. A member with no JSON Schema equivalent renders as "anything".
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
import type {
|
|
11
|
+
Action,
|
|
12
|
+
ActionDescription,
|
|
13
|
+
Description,
|
|
14
|
+
RecordDescription,
|
|
15
|
+
RecordType,
|
|
16
|
+
} from "@niwa-labs/core";
|
|
17
|
+
import { toJsonSchema } from "@niwa-labs/core";
|
|
18
|
+
|
|
19
|
+
/** What the description is built from: the registered declarations, not the host. */
|
|
20
|
+
export interface Describable {
|
|
21
|
+
actions: Iterable<Action<any, any>>;
|
|
22
|
+
types: Iterable<RecordType<any>>;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
/** One action, as the description shows it. */
|
|
26
|
+
export function describeAction(action: Action<any, any>): ActionDescription {
|
|
27
|
+
return {
|
|
28
|
+
name: action.name,
|
|
29
|
+
description: action.description,
|
|
30
|
+
recovery: action.recovery,
|
|
31
|
+
effect: action.effect,
|
|
32
|
+
...(action.world === undefined ? {} : { world: action.world }),
|
|
33
|
+
...(action.idempotent === undefined ? {} : { idempotent: action.idempotent }),
|
|
34
|
+
...(action.destructive === undefined ? {} : { destructive: action.destructive }),
|
|
35
|
+
input: toJsonSchema(action.input, "input"),
|
|
36
|
+
output: toJsonSchema(action.output, "output"),
|
|
37
|
+
};
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/** One record type, as the description shows it. */
|
|
41
|
+
export function describeRecordType(type: RecordType<any>): RecordDescription {
|
|
42
|
+
return {
|
|
43
|
+
name: type.name,
|
|
44
|
+
version: type.version,
|
|
45
|
+
schema: toJsonSchema(type.schema, "input"),
|
|
46
|
+
};
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/** The actions and the record types, in the order they were declared. */
|
|
50
|
+
export function describe(source: Describable): Description {
|
|
51
|
+
return {
|
|
52
|
+
actions: [...source.actions].map(describeAction),
|
|
53
|
+
types: [...source.types].map(describeRecordType),
|
|
54
|
+
};
|
|
55
|
+
}
|
package/src/doors.ts
ADDED
|
@@ -0,0 +1,272 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Doors: who a connection is, and what it may do.
|
|
3
|
+
*
|
|
4
|
+
* A token is a short random string a client shows in `hello`. The host keeps `HMAC(host.key,
|
|
5
|
+
* token)` in the journal, never the token, and the table folds from those records, so a restart
|
|
6
|
+
* knows every token it made. What a connection is called does not matter: only the token says
|
|
7
|
+
* who it is. The grants, the profiles and the switch are records too; the table is what they say.
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
import { createHmac, randomBytes, randomInt } from "node:crypto";
|
|
11
|
+
import { chmodSync, existsSync, readFileSync, writeFileSync } from "node:fs";
|
|
12
|
+
import { z } from "zod";
|
|
13
|
+
|
|
14
|
+
import {
|
|
15
|
+
GrantedData,
|
|
16
|
+
ClosedData,
|
|
17
|
+
HOST_KEY_FILE,
|
|
18
|
+
OWNER,
|
|
19
|
+
grantIdSchema,
|
|
20
|
+
principalSchema,
|
|
21
|
+
OWNER_GRANT,
|
|
22
|
+
OWNER_GRANT_ID,
|
|
23
|
+
RuleSpecSchema,
|
|
24
|
+
grant,
|
|
25
|
+
grantId,
|
|
26
|
+
ASK_SCOPES,
|
|
27
|
+
CORE,
|
|
28
|
+
} from "@niwa-labs/core";
|
|
29
|
+
import type { GrantEntry, Standing, Caller, Grant, GrantId, Principal, StoredRecord, Token, TokenMac } from "@niwa-labs/core";
|
|
30
|
+
|
|
31
|
+
/** The longest a token is, in characters. Short on purpose: the label of "who I am", not a vault. */
|
|
32
|
+
const TOKEN_LENGTH = 4;
|
|
33
|
+
const TOKEN_ALPHABET = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
|
|
34
|
+
|
|
35
|
+
/** A new random token. */
|
|
36
|
+
export function newToken(): Token {
|
|
37
|
+
let text = "";
|
|
38
|
+
for (let at = 0; at < TOKEN_LENGTH; at += 1) text += TOKEN_ALPHABET[randomInt(TOKEN_ALPHABET.length)];
|
|
39
|
+
return text as Token;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/** The key the host signs tokens with, kept in the home with rights for the owner only. */
|
|
43
|
+
export function loadHostKey(home: string): Buffer {
|
|
44
|
+
const path = `${home}/${HOST_KEY_FILE}`;
|
|
45
|
+
if (existsSync(path)) return Buffer.from(readFileSync(path, "utf8").trim(), "hex");
|
|
46
|
+
const key = randomBytes(32);
|
|
47
|
+
writeFileSync(path, `${key.toString("hex")}\n`, { mode: 0o600 });
|
|
48
|
+
chmodSync(path, 0o600);
|
|
49
|
+
return key;
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/** The data of a `niwa.access.issued` record. */
|
|
53
|
+
export const IssuedData = z.object({
|
|
54
|
+
mac: z.string().min(1),
|
|
55
|
+
principal: principalSchema,
|
|
56
|
+
});
|
|
57
|
+
|
|
58
|
+
/** The grant the owner has: it is the host's own, not a record. */
|
|
59
|
+
export { OWNER_GRANT_ID };
|
|
60
|
+
|
|
61
|
+
/** The grant of a connection with no token, or one the host did not make: the `default` profile, not a record. */
|
|
62
|
+
export const DEFAULT_GRANT_ID: GrantId = grantId("default");
|
|
63
|
+
|
|
64
|
+
/** The data of a `niwa.access.profile` record. */
|
|
65
|
+
export const ProfileData = z.strictObject({
|
|
66
|
+
name: z.string().min(1),
|
|
67
|
+
rules: z.array(RuleSpecSchema),
|
|
68
|
+
});
|
|
69
|
+
|
|
70
|
+
/** The data of a `niwa.access.switched` record. */
|
|
71
|
+
export const SwitchedData = z.strictObject({ all: z.enum(["on", "off"]) });
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* The data of a `niwa.access.answered` record: the owner's answer to a call that asked.
|
|
75
|
+
*
|
|
76
|
+
* `run` stays in force while the grant lives; `once` and `always` are written down as they were
|
|
77
|
+
* given, and `always` also writes a grant.
|
|
78
|
+
*/
|
|
79
|
+
export const AnsweredData = z.strictObject({
|
|
80
|
+
grant: grantIdSchema,
|
|
81
|
+
principal: principalSchema,
|
|
82
|
+
name: z.string().min(1),
|
|
83
|
+
target: z.string().min(1).optional(),
|
|
84
|
+
scope: z.enum(ASK_SCOPES),
|
|
85
|
+
});
|
|
86
|
+
|
|
87
|
+
/** The data of a `niwa.access.decided` record. */
|
|
88
|
+
export const DecidedData = z.object({
|
|
89
|
+
principal: principalSchema,
|
|
90
|
+
verb: z.string(),
|
|
91
|
+
name: z.string(),
|
|
92
|
+
grant: grantIdSchema.optional(),
|
|
93
|
+
outcome: z.enum(["allowed", "denied"]),
|
|
94
|
+
rule: z.string().optional(),
|
|
95
|
+
/** The scope of the owner's answer that let the call through, when the rule asked. */
|
|
96
|
+
answered: z.enum(ASK_SCOPES).optional(),
|
|
97
|
+
reason: z.string().optional(),
|
|
98
|
+
missing: z.string().optional(),
|
|
99
|
+
/** The step of a run the decision was made at. */
|
|
100
|
+
step: z.string().optional(),
|
|
101
|
+
/** The version of the policy that narrowed the grant: the sha256 of the `allow` of a run. */
|
|
102
|
+
policy: z.string().optional(),
|
|
103
|
+
});
|
|
104
|
+
|
|
105
|
+
const answerKey = (id: GrantId, name: string, target: string | undefined): string =>
|
|
106
|
+
`${id}\u0000${name}${target === undefined ? "" : `@${target}`}`;
|
|
107
|
+
|
|
108
|
+
const keyOf = (principal: Principal): string => `${principal.kind}:${principal.id}`;
|
|
109
|
+
|
|
110
|
+
/** The tokens, the grants, the profiles and the switch the host made, folded from the journal. */
|
|
111
|
+
export class Doors {
|
|
112
|
+
private readonly holders = new Map<TokenMac, Principal>();
|
|
113
|
+
private readonly grants = new Map<GrantId, GrantEntry>();
|
|
114
|
+
/** The latest grant of each principal: a session that is resumed gets a new token and a new grant. */
|
|
115
|
+
private readonly current = new Map<string, GrantId>();
|
|
116
|
+
private readonly profiles = new Map<string, Grant>();
|
|
117
|
+
/** What the owner answered `run` to: an action and its target, by the grant they were answered for. */
|
|
118
|
+
private readonly runAnswers = new Set<string>();
|
|
119
|
+
private all: "on" | "off" = "on";
|
|
120
|
+
|
|
121
|
+
constructor(private readonly key: Buffer) {}
|
|
122
|
+
|
|
123
|
+
/** The MAC the journal keeps for a token. */
|
|
124
|
+
macOf(secret: Token): TokenMac {
|
|
125
|
+
return createHmac("sha256", this.key).update(secret).digest("hex") as TokenMac;
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
/** Take a record of the journal in: the table is what the records, in order, say. */
|
|
129
|
+
fold(stored: StoredRecord): void {
|
|
130
|
+
switch (stored.type) {
|
|
131
|
+
case CORE.accessIssued: {
|
|
132
|
+
const issued = IssuedData.safeParse(stored.data);
|
|
133
|
+
if (issued.success) this.hold(issued.data.mac as TokenMac, issued.data.principal);
|
|
134
|
+
return;
|
|
135
|
+
}
|
|
136
|
+
case CORE.accessGranted: {
|
|
137
|
+
const granted = GrantedData.safeParse(stored.data);
|
|
138
|
+
if (!granted.success) return;
|
|
139
|
+
const id = grantId(stored.id);
|
|
140
|
+
this.grants.set(id, {
|
|
141
|
+
id,
|
|
142
|
+
principal: granted.data.principal,
|
|
143
|
+
grant: grant(granted.data.rules),
|
|
144
|
+
...(granted.data.parent === undefined ? {} : { parent: granted.data.parent }),
|
|
145
|
+
});
|
|
146
|
+
this.current.set(keyOf(granted.data.principal), id);
|
|
147
|
+
return;
|
|
148
|
+
}
|
|
149
|
+
case CORE.accessClosed: {
|
|
150
|
+
const closed = ClosedData.safeParse(stored.data);
|
|
151
|
+
const held = closed.success ? this.grants.get(closed.data.grant) : undefined;
|
|
152
|
+
if (closed.success && held !== undefined) this.grants.set(held.id, { ...held, closed: closed.data.reason });
|
|
153
|
+
return;
|
|
154
|
+
}
|
|
155
|
+
case CORE.accessProfile: {
|
|
156
|
+
const set = ProfileData.safeParse(stored.data);
|
|
157
|
+
if (set.success) this.profiles.set(set.data.name, grant(set.data.rules));
|
|
158
|
+
return;
|
|
159
|
+
}
|
|
160
|
+
case CORE.accessAnswered: {
|
|
161
|
+
const answered = AnsweredData.safeParse(stored.data);
|
|
162
|
+
if (answered.success && answered.data.scope === "run") {
|
|
163
|
+
this.runAnswers.add(answerKey(answered.data.grant, answered.data.name, answered.data.target));
|
|
164
|
+
}
|
|
165
|
+
return;
|
|
166
|
+
}
|
|
167
|
+
case CORE.accessSwitched: {
|
|
168
|
+
const switched = SwitchedData.safeParse(stored.data);
|
|
169
|
+
if (switched.success) this.all = switched.data.all;
|
|
170
|
+
return;
|
|
171
|
+
}
|
|
172
|
+
}
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
/** Is this token one of the table's? A token the host never made is nobody's. */
|
|
176
|
+
holderOf(secret: Token | undefined): Principal | undefined {
|
|
177
|
+
if (secret === undefined) return undefined;
|
|
178
|
+
return this.holders.get(this.macOf(secret));
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
/** Did the host make a token for this principal? A connection with no token, or one the host did not make, holds none. */
|
|
182
|
+
holds(principal: Principal): boolean {
|
|
183
|
+
for (const held of this.holders.values()) if (keyOf(held) === keyOf(principal)) return true;
|
|
184
|
+
return false;
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
/** Does this MAC belong to a token already made? */
|
|
188
|
+
has(mac: TokenMac): boolean {
|
|
189
|
+
return this.holders.has(mac);
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
/** A token that is not in the table yet: the token is short, so a draw that hits one is made again. */
|
|
193
|
+
fresh(): Token {
|
|
194
|
+
for (;;) {
|
|
195
|
+
const candidate = newToken();
|
|
196
|
+
if (!this.holders.has(this.macOf(candidate))) return candidate;
|
|
197
|
+
}
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
/** The grant a principal holds now, closed or not; undefined when nothing ever limited it. */
|
|
201
|
+
grantOf(principal: Principal): GrantEntry | undefined {
|
|
202
|
+
const id = this.current.get(keyOf(principal));
|
|
203
|
+
return id === undefined ? undefined : this.grants.get(id);
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
/** A grant by its id. The owner's is the host's own. */
|
|
207
|
+
grantById(id: GrantId): GrantEntry | undefined {
|
|
208
|
+
if (id === OWNER_GRANT_ID) return { id, principal: OWNER, grant: OWNER_GRANT };
|
|
209
|
+
return this.grants.get(id);
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
/** The grants a grant came from, nearest first. */
|
|
213
|
+
chainOf(id: GrantId): GrantEntry[] {
|
|
214
|
+
const chain: GrantEntry[] = [];
|
|
215
|
+
for (let at = this.grantById(id); at !== undefined && chain.length < 64; ) {
|
|
216
|
+
chain.push(at);
|
|
217
|
+
at = at.parent === undefined ? undefined : this.grantById(at.parent.grant);
|
|
218
|
+
}
|
|
219
|
+
return chain;
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
/** The principals that were born from this one and still hold a living grant. */
|
|
223
|
+
childrenOf(principal: Principal): GrantEntry[] {
|
|
224
|
+
const children: GrantEntry[] = [];
|
|
225
|
+
for (const id of this.current.values()) {
|
|
226
|
+
const held = this.grants.get(id);
|
|
227
|
+
if (held === undefined || held.closed !== undefined) continue;
|
|
228
|
+
if (held.parent !== undefined && keyOf(held.parent.principal) === keyOf(principal)) children.push(held);
|
|
229
|
+
}
|
|
230
|
+
return children;
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
/** Did the owner answer `run` for this action, with this target, for this grant? */
|
|
234
|
+
answeredRun(id: GrantId, name: string, target: string | undefined): boolean {
|
|
235
|
+
return this.runAnswers.has(answerKey(id, name, target));
|
|
236
|
+
}
|
|
237
|
+
|
|
238
|
+
/** The profile of this name, when the owner set one. */
|
|
239
|
+
profileOf(name: string): Grant | undefined {
|
|
240
|
+
return this.profiles.get(name);
|
|
241
|
+
}
|
|
242
|
+
|
|
243
|
+
/** The profiles the owner set. */
|
|
244
|
+
profileNames(): string[] {
|
|
245
|
+
return [...this.profiles.keys()];
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
/** The emergency switch. */
|
|
249
|
+
switched(): "on" | "off" {
|
|
250
|
+
return this.all;
|
|
251
|
+
}
|
|
252
|
+
|
|
253
|
+
/** What a caller stands on: its own grant, or nothing at all when nothing limits it. A connection with no token is left to the access control, which puts it on the `default` profile. */
|
|
254
|
+
standing(caller: Caller): Standing {
|
|
255
|
+
if (caller.kind !== "client") return { kind: "unlimited" };
|
|
256
|
+
const principal = caller.principal;
|
|
257
|
+
if (principal?.kind === "owner") return { kind: "limited", id: OWNER_GRANT_ID, grant: OWNER_GRANT };
|
|
258
|
+
if (this.all === "off") return { kind: "off" };
|
|
259
|
+
const held = principal === undefined ? undefined : this.grantOf(principal);
|
|
260
|
+
if (held === undefined) return { kind: "unlimited" };
|
|
261
|
+
if (held.closed !== undefined) return { kind: "closed", id: held.id, reason: held.closed };
|
|
262
|
+
return { kind: "limited", id: held.id, grant: held.grant };
|
|
263
|
+
}
|
|
264
|
+
|
|
265
|
+
/** The owner has one token at a time: a new one drops the earlier, so an old token stops working. */
|
|
266
|
+
private hold(mac: TokenMac, principal: Principal): void {
|
|
267
|
+
if (principal.kind === "owner") {
|
|
268
|
+
for (const [known, other] of this.holders) if (other.kind === "owner") this.holders.delete(known);
|
|
269
|
+
}
|
|
270
|
+
this.holders.set(mac, principal);
|
|
271
|
+
}
|
|
272
|
+
}
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
// How a host is opened, and what a host is.
|
|
2
|
+
import type { Caller, Clock, Grant, PluginName, Principal, Token } from "@niwa-labs/core";
|
|
3
|
+
import type { Plugin } from "@niwa-labs/plugin";
|
|
4
|
+
import type { NiwaApi } from "@niwa-labs/client";
|
|
5
|
+
|
|
6
|
+
/** How a host is opened. */
|
|
7
|
+
export interface HostOptions {
|
|
8
|
+
/** The home of the host: where its journal, its socket and its state live. */
|
|
9
|
+
home: string;
|
|
10
|
+
/** Take the journal even from a living holder. */
|
|
11
|
+
takeover?: boolean;
|
|
12
|
+
/** What `niwa.host.stop` does. Default: close the host. A process that serves it ends itself here. */
|
|
13
|
+
onStop?: () => void;
|
|
14
|
+
/**
|
|
15
|
+
* The clock of this host.
|
|
16
|
+
*
|
|
17
|
+
* One host has one clock: everything that asks what time it is, or that waits for a moment to
|
|
18
|
+
* come, asks it. The default is the real clock; a test may give the host a clock it moves by
|
|
19
|
+
* hand, so that a week of work is watched without a week of waiting.
|
|
20
|
+
*/
|
|
21
|
+
clock?: Clock;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
export interface Host extends NiwaApi {
|
|
25
|
+
/**
|
|
26
|
+
* Install or replace plugins, in the order given (same name = replace).
|
|
27
|
+
*
|
|
28
|
+
* Stops at the first plugin that cannot be installed and throws `PluginInstallFailed` naming it:
|
|
29
|
+
* the plugins before it stay installed, the ones after it are not tried.
|
|
30
|
+
*/
|
|
31
|
+
use(...plugins: Plugin[]): void;
|
|
32
|
+
/** Remove a plugin's registrations. Its records stay. */
|
|
33
|
+
unload(name: PluginName): void;
|
|
34
|
+
/** The plugin that is installed under this name, as it was given to `use`. */
|
|
35
|
+
installed(name: PluginName): Plugin | undefined;
|
|
36
|
+
/** Open the journal as the only writer, resume work, catch up, listen for clients. */
|
|
37
|
+
serve(): Promise<void>;
|
|
38
|
+
/**
|
|
39
|
+
* Make a token for a principal, for a process that connects by itself (a plugin that lives out
|
|
40
|
+
* of process, an external client). In-process only: nothing over the wire makes tokens.
|
|
41
|
+
*/
|
|
42
|
+
issueToken(principal: Principal, opts?: { grant?: Grant; parent?: Caller }): Token;
|
|
43
|
+
}
|