@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
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Niwa Labs contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,3 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @niwa-labs/host
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The niwa host: `createNiwa`, plugin installation, subscriptions, state, secrets, access actions, the catalog of cockpit modules, and `serve`.
|
package/package.json
CHANGED
|
@@ -1,6 +1,18 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@niwa-labs/host",
|
|
3
|
-
"version": "0.0.0
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.0.0",
|
|
4
|
+
"license": "MIT",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"exports": {
|
|
7
|
+
".": "./src/index.ts"
|
|
8
|
+
},
|
|
9
|
+
"dependencies": {
|
|
10
|
+
"@niwa-labs/client": "0.0.0",
|
|
11
|
+
"@niwa-labs/core": "0.0.0",
|
|
12
|
+
"@niwa-labs/plugin": "0.0.0",
|
|
13
|
+
"zod": "^4.6.7"
|
|
14
|
+
},
|
|
15
|
+
"devDependencies": {
|
|
16
|
+
"@niwa-labs/testing": "0.0.0"
|
|
17
|
+
}
|
|
18
|
+
}
|
|
@@ -0,0 +1,193 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The actions of access: profiles, a grant changed or
|
|
3
|
+
* closed, the switch, and the two that say what a subject may do and why a call was refused.
|
|
4
|
+
*
|
|
5
|
+
* What changes a grant or a profile is the owner's: the host itself and its handlers are too,
|
|
6
|
+
* a client that is not the owner is not. Whether a subject may call these at all is its grant's
|
|
7
|
+
* business, like any other action.
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
import { z } from "zod";
|
|
11
|
+
|
|
12
|
+
import {
|
|
13
|
+
accessMine,
|
|
14
|
+
principalSchema,
|
|
15
|
+
action,
|
|
16
|
+
actionName,
|
|
17
|
+
RuleSpecSchema,
|
|
18
|
+
match,
|
|
19
|
+
specsOf,
|
|
20
|
+
DeniedError,
|
|
21
|
+
recordId,
|
|
22
|
+
} from "@niwa-labs/core";
|
|
23
|
+
import type { Doors } from "./doors.ts";
|
|
24
|
+
import type { AccessControl } from "./access-control.ts";
|
|
25
|
+
import type { Action, Caller } from "@niwa-labs/core";
|
|
26
|
+
|
|
27
|
+
const PROFILE_SET = actionName("access.profile.set");
|
|
28
|
+
const PROFILE_GET = actionName("access.profile.get");
|
|
29
|
+
const GRANT_CHANGE = actionName("access.grant.change");
|
|
30
|
+
const GRANT_CLOSE = actionName("access.grant.close");
|
|
31
|
+
const SWITCH = actionName("access.switch");
|
|
32
|
+
const EXPLAIN = actionName("access.explain");
|
|
33
|
+
|
|
34
|
+
const MINE = accessMine;
|
|
35
|
+
|
|
36
|
+
const Rules = z.array(RuleSpecSchema);
|
|
37
|
+
|
|
38
|
+
const GrantView = z.object({
|
|
39
|
+
id: z.string(),
|
|
40
|
+
principal: principalSchema,
|
|
41
|
+
rules: Rules,
|
|
42
|
+
closed: z.string().optional(),
|
|
43
|
+
parent: z.object({ principal: principalSchema, grant: z.string() }).optional(),
|
|
44
|
+
});
|
|
45
|
+
|
|
46
|
+
function requireOwner(caller: Caller, what: string): void {
|
|
47
|
+
if (caller.kind === "client" && caller.principal?.kind !== "owner") {
|
|
48
|
+
throw new DeniedError(`only the owner ${what}`);
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/** The actions, over the control that keeps the table. */
|
|
53
|
+
export function accessActions(control: AccessControl, doors: () => Doors): Action<any, any>[] {
|
|
54
|
+
return [
|
|
55
|
+
action(PROFILE_SET, {
|
|
56
|
+
description: "Sets a named grant that has no holder (default, rin, wf:<sub-…>). Only the owner. A subject that starts later gets a copy narrowed by its request; the ones that live are not touched.",
|
|
57
|
+
input: z.object({ name: z.string().min(1), rules: Rules }),
|
|
58
|
+
output: z.object({ name: z.string(), rules: Rules }),
|
|
59
|
+
recovery: "repeat",
|
|
60
|
+
effect: "record",
|
|
61
|
+
world: "niwa",
|
|
62
|
+
run: async (input, ctx) => {
|
|
63
|
+
requireOwner(ctx.caller, "sets a profile");
|
|
64
|
+
return { name: input.name, rules: specsOf(control.setProfile(ctx.caller, input.name, input.rules)) };
|
|
65
|
+
},
|
|
66
|
+
}),
|
|
67
|
+
action(PROFILE_GET, {
|
|
68
|
+
description: "A named grant and whether the owner set it. Without a name: the names that have one.",
|
|
69
|
+
input: z.object({ name: z.string().min(1).optional() }),
|
|
70
|
+
output: z.object({
|
|
71
|
+
names: z.array(z.string()),
|
|
72
|
+
name: z.string().optional(),
|
|
73
|
+
rules: Rules.optional(),
|
|
74
|
+
set: z.boolean().optional(),
|
|
75
|
+
}),
|
|
76
|
+
recovery: "repeat",
|
|
77
|
+
effect: "read",
|
|
78
|
+
world: "niwa",
|
|
79
|
+
run: async (input) => {
|
|
80
|
+
const names = control.profileNames();
|
|
81
|
+
if (input.name === undefined) return { names };
|
|
82
|
+
const found = control.profile(input.name);
|
|
83
|
+
if (found === undefined) throw new TypeError(`there is no profile "${input.name}"`);
|
|
84
|
+
return { names, name: input.name, rules: specsOf(found.rules), set: found.set };
|
|
85
|
+
},
|
|
86
|
+
}),
|
|
87
|
+
action(GRANT_CHANGE, {
|
|
88
|
+
description: "Gives a principal another grant. Only the owner. A grant that loses something closes its living children, except the runs that are going; one that only gains leaves them, and what starts next gets the new rights.",
|
|
89
|
+
input: z.object({ principal: principalSchema, rules: Rules }),
|
|
90
|
+
output: z.object({ grant: z.string(), closed: z.array(principalSchema) }),
|
|
91
|
+
recovery: "do-not-repeat",
|
|
92
|
+
effect: "record",
|
|
93
|
+
world: "niwa",
|
|
94
|
+
run: async (input, ctx) => {
|
|
95
|
+
requireOwner(ctx.caller, "changes a grant");
|
|
96
|
+
return control.change(ctx.caller, input.principal, input.rules);
|
|
97
|
+
},
|
|
98
|
+
}),
|
|
99
|
+
action(GRANT_CLOSE, {
|
|
100
|
+
description: "Closes the grant of a principal and, with it, the living ones that were born from it, except the runs that are going. Only the owner.",
|
|
101
|
+
input: z.object({ principal: principalSchema, reason: z.string().min(1).optional() }),
|
|
102
|
+
output: z.object({ closed: z.array(principalSchema) }),
|
|
103
|
+
recovery: "do-not-repeat",
|
|
104
|
+
effect: "record",
|
|
105
|
+
world: "niwa",
|
|
106
|
+
run: async (input, ctx) => {
|
|
107
|
+
requireOwner(ctx.caller, "closes a grant");
|
|
108
|
+
return { closed: control.close(ctx.caller, input.principal, input.reason ?? "closed by the owner") };
|
|
109
|
+
},
|
|
110
|
+
}),
|
|
111
|
+
action(SWITCH, {
|
|
112
|
+
description: "The emergency switch. `all: off` denies every call of anyone but the owner; `on` lifts it. Only the owner.",
|
|
113
|
+
input: z.object({ all: z.enum(["on", "off"]) }),
|
|
114
|
+
output: z.object({ all: z.enum(["on", "off"]) }),
|
|
115
|
+
recovery: "repeat",
|
|
116
|
+
effect: "record",
|
|
117
|
+
world: "niwa",
|
|
118
|
+
run: async (input, ctx) => {
|
|
119
|
+
requireOwner(ctx.caller, "moves the switch");
|
|
120
|
+
control.setSwitch(ctx.caller, input.all);
|
|
121
|
+
return { all: input.all };
|
|
122
|
+
},
|
|
123
|
+
}),
|
|
124
|
+
action(MINE, {
|
|
125
|
+
description: "What the caller may do: its own rules. A subject that nothing limits says so.",
|
|
126
|
+
input: z.object({}),
|
|
127
|
+
output: z.object({
|
|
128
|
+
principal: principalSchema.optional(),
|
|
129
|
+
grant: z.string().optional(),
|
|
130
|
+
unlimited: z.boolean(),
|
|
131
|
+
closed: z.string().optional(),
|
|
132
|
+
rules: Rules,
|
|
133
|
+
}),
|
|
134
|
+
recovery: "repeat",
|
|
135
|
+
effect: "read",
|
|
136
|
+
world: "niwa",
|
|
137
|
+
run: async (_input, ctx) => control.mine(ctx.caller),
|
|
138
|
+
}),
|
|
139
|
+
action(EXPLAIN, {
|
|
140
|
+
description: "Explains a decision: the rule that decided it, the grant, and the grants it came from. Takes the id of the decision record a refusal names, or of a record a subject wrote.",
|
|
141
|
+
input: z.object({ record: z.string().min(1) }),
|
|
142
|
+
output: z.object({
|
|
143
|
+
record: z.string(),
|
|
144
|
+
outcome: z.enum(["allowed", "denied", "written"]),
|
|
145
|
+
verb: z.string().optional(),
|
|
146
|
+
name: z.string().optional(),
|
|
147
|
+
rule: z.string().optional(),
|
|
148
|
+
reason: z.string().optional(),
|
|
149
|
+
missing: z.string().optional(),
|
|
150
|
+
grant: GrantView.optional(),
|
|
151
|
+
chain: z.array(GrantView),
|
|
152
|
+
}),
|
|
153
|
+
recovery: "repeat",
|
|
154
|
+
effect: "read",
|
|
155
|
+
world: "niwa",
|
|
156
|
+
run: async (input) => {
|
|
157
|
+
const table = doors();
|
|
158
|
+
const at = control.recordOf(recordId(input.record));
|
|
159
|
+
if (at === undefined) throw new TypeError(`there is no record "${input.record}"`);
|
|
160
|
+
const view = (entry: ReturnType<typeof table.grantById>): z.infer<typeof GrantView> | undefined =>
|
|
161
|
+
entry === undefined
|
|
162
|
+
? undefined
|
|
163
|
+
: {
|
|
164
|
+
id: entry.id,
|
|
165
|
+
principal: entry.principal,
|
|
166
|
+
rules: specsOf(entry.grant),
|
|
167
|
+
...(entry.closed === undefined ? {} : { closed: entry.closed }),
|
|
168
|
+
...(entry.parent === undefined ? {} : { parent: entry.parent }),
|
|
169
|
+
};
|
|
170
|
+
const decision = control.decisionOf(at);
|
|
171
|
+
const id = decision?.grant ?? (at.actor.kind === "client" ? at.actor.grant : undefined);
|
|
172
|
+
if (decision === undefined && id === undefined) {
|
|
173
|
+
throw new TypeError(`"${input.record}" is neither a decision nor a record written under a grant`);
|
|
174
|
+
}
|
|
175
|
+
const own = id === undefined ? undefined : table.grantById(id);
|
|
176
|
+
// A record a subject wrote has no decision of its own: the rule is the one for its type now.
|
|
177
|
+
const written = decision === undefined && own !== undefined ? match(own.grant, "emit", at.type) : undefined;
|
|
178
|
+
const chain = id === undefined ? [] : table.chainOf(id).slice(1);
|
|
179
|
+
return {
|
|
180
|
+
record: input.record,
|
|
181
|
+
outcome: decision?.outcome ?? "written",
|
|
182
|
+
...(decision === undefined ? {} : { verb: decision.verb, name: decision.name }),
|
|
183
|
+
...(decision?.rule === undefined ? {} : { rule: decision.rule }),
|
|
184
|
+
...(written === undefined ? {} : { rule: `${written.verb}:${written.name}` }),
|
|
185
|
+
...(decision?.reason === undefined ? {} : { reason: decision.reason }),
|
|
186
|
+
...(decision?.missing === undefined ? {} : { missing: decision.missing }),
|
|
187
|
+
...(view(own) === undefined ? {} : { grant: view(own) }),
|
|
188
|
+
chain: chain.flatMap((entry) => view(entry) ?? []),
|
|
189
|
+
};
|
|
190
|
+
},
|
|
191
|
+
}),
|
|
192
|
+
];
|
|
193
|
+
}
|
|
@@ -0,0 +1,333 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Access: the grants, the profiles and the switch as the host keeps them.
|
|
3
|
+
*
|
|
4
|
+
* Every change is a record and the table is folded from the records, so what this class does is
|
|
5
|
+
* write them: a grant issued for a principal, a grant closed, a profile set, the switch moved, a
|
|
6
|
+
* decision recorded. The decision itself is the pure `permit` of `intercept.ts`.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
import type { z } from "zod";
|
|
10
|
+
|
|
11
|
+
import { DEFAULT_GRANT_ID, DecidedData, Doors, OWNER_GRANT_ID } from "./doors.ts";
|
|
12
|
+
import type {
|
|
13
|
+
GrantEntry,
|
|
14
|
+
Standing,
|
|
15
|
+
Narrowed,
|
|
16
|
+
RuleSpec,
|
|
17
|
+
AskQuestion,
|
|
18
|
+
AskScope,
|
|
19
|
+
Caller,
|
|
20
|
+
Effect,
|
|
21
|
+
Grant,
|
|
22
|
+
GrantId,
|
|
23
|
+
NewRecord,
|
|
24
|
+
Principal,
|
|
25
|
+
RecordId,
|
|
26
|
+
RecordTypeName,
|
|
27
|
+
StoredRecord,
|
|
28
|
+
Verb,
|
|
29
|
+
} from "@niwa-labs/core";
|
|
30
|
+
import {
|
|
31
|
+
grant,
|
|
32
|
+
grantId,
|
|
33
|
+
narrow,
|
|
34
|
+
narrowed,
|
|
35
|
+
rule,
|
|
36
|
+
ruleText,
|
|
37
|
+
specOf,
|
|
38
|
+
specsOf,
|
|
39
|
+
CORE_TYPES,
|
|
40
|
+
newRecordId,
|
|
41
|
+
streamId,
|
|
42
|
+
} from "@niwa-labs/core";
|
|
43
|
+
import type { Permit } from "@niwa-labs/core/journal";
|
|
44
|
+
|
|
45
|
+
/** Whose grant a grant came from. */
|
|
46
|
+
interface Parent {
|
|
47
|
+
readonly principal: Principal;
|
|
48
|
+
readonly grant: GrantId;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/** What the control needs of the host: the table, and a way to commit records. */
|
|
52
|
+
export interface AccessHost {
|
|
53
|
+
/** The table, while the host serves. */
|
|
54
|
+
doors(): Doors;
|
|
55
|
+
/** Commit records; the table takes them in. */
|
|
56
|
+
commit(records: NewRecord[]): StoredRecord[];
|
|
57
|
+
/** Read a record. */
|
|
58
|
+
read(id: RecordId): StoredRecord | undefined;
|
|
59
|
+
/** The effect of an installed action; undefined for a name no plugin serves. */
|
|
60
|
+
effectOf(name: string): Effect | undefined;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/** The profile the owner has not set, as a plugin or the host declares it. */
|
|
64
|
+
type ProfileDefault = () => readonly RuleSpec[];
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* What a connection with no token may do when the owner says nothing else.
|
|
68
|
+
* `insert.report` is there because the hooks of a harness report what it did inside itself without a token.
|
|
69
|
+
*/
|
|
70
|
+
const DEFAULT_PROFILE: readonly RuleSpec[] = ["task.*", "message.send", "insert.report", "emit:wf.*", "box.net@registry.npmjs.org"];
|
|
71
|
+
|
|
72
|
+
/** The grants and the profiles of one host. */
|
|
73
|
+
export class AccessControl {
|
|
74
|
+
private readonly defaults = new Map<string, ProfileDefault>([["default", () => DEFAULT_PROFILE]]);
|
|
75
|
+
|
|
76
|
+
constructor(private readonly host: AccessHost) {}
|
|
77
|
+
|
|
78
|
+
/** Is the name that of an irreversible action: one a mask does not grant. */
|
|
79
|
+
readonly irreversible = (name: string): boolean => this.host.effectOf(name) === "irreversible";
|
|
80
|
+
|
|
81
|
+
/** A plugin names the profile it owns; the owner's own setting wins over it. */
|
|
82
|
+
declareProfile(name: string, rules: ProfileDefault): void {
|
|
83
|
+
this.defaults.set(name, rules);
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
/** The profiles the plugins declared, as they are now: what an install that fails puts back. */
|
|
87
|
+
declaredProfiles(): ReadonlyMap<string, ProfileDefault> {
|
|
88
|
+
return new Map(this.defaults);
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
/** Put the declared profiles back as `declaredProfiles` took them. */
|
|
92
|
+
restoreProfiles(declared: ReadonlyMap<string, ProfileDefault>): void {
|
|
93
|
+
this.defaults.clear();
|
|
94
|
+
for (const [name, rules] of declared) this.defaults.set(name, rules);
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
/**
|
|
98
|
+
* What a caller stands on. A connection with no token, or one the host did not make, is a client
|
|
99
|
+
* the host never issued a token to: it stands on the `default` profile, and only the owner's
|
|
100
|
+
* token is unlimited by it.
|
|
101
|
+
*/
|
|
102
|
+
standing(caller: Caller): Standing {
|
|
103
|
+
const doors = this.host.doors();
|
|
104
|
+
const standing = doors.standing(caller);
|
|
105
|
+
if (standing.kind !== "unlimited" || caller.kind !== "client") return standing;
|
|
106
|
+
const principal = caller.principal;
|
|
107
|
+
if (principal !== undefined && (principal.kind !== "client" || doors.holds(principal))) return standing;
|
|
108
|
+
return { kind: "limited", id: DEFAULT_GRANT_ID, grant: this.profile("default")?.rules ?? grant(DEFAULT_PROFILE) };
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/**
|
|
112
|
+
* What a caller may do, as a grant, or `"unlimited"` when nothing limits it. A caller whose grant
|
|
113
|
+
* was closed, or that the emergency switch stopped, has a grant with no rules.
|
|
114
|
+
*/
|
|
115
|
+
rightsOf(caller: Caller): Grant | "unlimited" {
|
|
116
|
+
const standing = this.standing(caller);
|
|
117
|
+
switch (standing.kind) {
|
|
118
|
+
case "unlimited":
|
|
119
|
+
return "unlimited";
|
|
120
|
+
case "limited":
|
|
121
|
+
return standing.grant;
|
|
122
|
+
case "closed":
|
|
123
|
+
case "off":
|
|
124
|
+
return grant([]);
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
/** The grant of the caller as the records carry it: set for a subject a grant limits. */
|
|
129
|
+
grantIdOf(caller: Caller): GrantId | undefined {
|
|
130
|
+
const standing = this.standing(caller);
|
|
131
|
+
if (standing.kind === "limited" || standing.kind === "closed") {
|
|
132
|
+
return standing.id === OWNER_GRANT_ID || standing.id === DEFAULT_GRANT_ID ? undefined : standing.id;
|
|
133
|
+
}
|
|
134
|
+
return undefined;
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
/** The rights of a subject started at the request of `caller`, or the masks it may not have. */
|
|
138
|
+
narrowFor(caller: Caller, requested: readonly RuleSpec[]): Narrowed {
|
|
139
|
+
const standing = this.standing(caller);
|
|
140
|
+
switch (standing.kind) {
|
|
141
|
+
case "unlimited":
|
|
142
|
+
return { rules: grant(requested) };
|
|
143
|
+
case "limited":
|
|
144
|
+
// The owner starts what it likes: its grant is `call:*`, and the verbs beyond calls are its own to hand out.
|
|
145
|
+
return standing.id === OWNER_GRANT_ID ? { rules: grant(requested) } : narrow(standing.grant, requested, { irreversible: this.irreversible });
|
|
146
|
+
case "closed":
|
|
147
|
+
case "off":
|
|
148
|
+
return { refused: requested.map((spec) => ruleText(rule(spec))) };
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
/** The record that issues a grant to a principal, with the grant it came from for attribution. */
|
|
153
|
+
grantRecord(principal: Principal, given: Grant, parent: Parent | undefined, actor: Caller = { kind: "host" }): NewRecord {
|
|
154
|
+
return this.record(CORE_TYPES.accessGranted, actor, {
|
|
155
|
+
principal,
|
|
156
|
+
rules: specsOf(given),
|
|
157
|
+
...(parent === undefined ? {} : { parent }),
|
|
158
|
+
});
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
/** The grant of a caller, as the parent of the subjects it starts. */
|
|
162
|
+
parentOf(caller: Caller): Parent | undefined {
|
|
163
|
+
if (caller.kind !== "client" || caller.principal === undefined) return undefined;
|
|
164
|
+
const standing = this.standing(caller);
|
|
165
|
+
if (standing.kind !== "limited" && standing.kind !== "closed") return undefined;
|
|
166
|
+
return { principal: caller.principal, grant: standing.id };
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
/** The profile of this name: the owner's setting, else what was declared for it. */
|
|
170
|
+
profile(name: string): { rules: Grant; set: boolean } | undefined {
|
|
171
|
+
const set = this.host.doors().profileOf(name);
|
|
172
|
+
if (set !== undefined) return { rules: set, set: true };
|
|
173
|
+
const declared = this.defaults.get(name);
|
|
174
|
+
return declared === undefined ? undefined : { rules: grant(declared()), set: false };
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
/** The names that have a profile. */
|
|
178
|
+
profileNames(): string[] {
|
|
179
|
+
return [...new Set([...this.defaults.keys(), ...this.host.doors().profileNames()])].sort();
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
/** The owner sets a profile. */
|
|
183
|
+
setProfile(by: Caller, name: string, rules: readonly RuleSpec[]): Grant {
|
|
184
|
+
const checked = grant(rules);
|
|
185
|
+
this.host.commit([this.record(CORE_TYPES.accessProfile, by, { name, rules: specsOf(checked) })]);
|
|
186
|
+
return checked;
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
/**
|
|
190
|
+
* The owner moves the emergency switch: `off` denies every call of anyone but the owner.
|
|
191
|
+
*/
|
|
192
|
+
setSwitch(by: Caller, all: "on" | "off"): void {
|
|
193
|
+
this.host.commit([this.record(CORE_TYPES.accessSwitched, by, { all })]);
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
/**
|
|
197
|
+
* Give a principal another grant. A grant that lost something closes its living children, except
|
|
198
|
+
* runs; one that only gained leaves them as they are, and what starts next gets the new rights.
|
|
199
|
+
*/
|
|
200
|
+
change(by: Caller, principal: Principal, rules: readonly RuleSpec[]): { grant: GrantId; closed: Principal[] } {
|
|
201
|
+
const doors = this.host.doors();
|
|
202
|
+
const before = doors.grantOf(principal);
|
|
203
|
+
if (before === undefined || before.closed !== undefined) {
|
|
204
|
+
throw new TypeError(`${principal.kind} "${principal.id}" holds no living grant`);
|
|
205
|
+
}
|
|
206
|
+
const after = grant(rules);
|
|
207
|
+
const issued = this.grantRecord(principal, after, before.parent, by);
|
|
208
|
+
const records: NewRecord[] = [issued];
|
|
209
|
+
const closed: Principal[] = [];
|
|
210
|
+
if (narrowed(before.grant, after, { irreversible: this.irreversible })) records.push(...this.closing(by, before, "its parent's grant was narrowed", closed, false));
|
|
211
|
+
this.host.commit(records);
|
|
212
|
+
return { grant: grantId(issued.id), closed };
|
|
213
|
+
}
|
|
214
|
+
|
|
215
|
+
/** Close the grant of a principal and, with it, the grants of everything that was born from it. */
|
|
216
|
+
close(by: Caller, principal: Principal, reason: string): Principal[] {
|
|
217
|
+
const held = this.host.doors().grantOf(principal);
|
|
218
|
+
if (held === undefined || held.closed !== undefined) {
|
|
219
|
+
throw new TypeError(`${principal.kind} "${principal.id}" holds no living grant`);
|
|
220
|
+
}
|
|
221
|
+
const closed: Principal[] = [];
|
|
222
|
+
this.host.commit(this.closing(by, held, reason, closed, true));
|
|
223
|
+
return closed;
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
/**
|
|
227
|
+
* The records that close a grant (when `self`) and the living ones below it, the deepest first.
|
|
228
|
+
* A run that is going keeps the grant it was born with: the cascade passes over it, and what is under it.
|
|
229
|
+
*/
|
|
230
|
+
private closing(by: Caller, from: GrantEntry, reason: string, closed: Principal[], self: boolean): NewRecord[] {
|
|
231
|
+
const records: NewRecord[] = [];
|
|
232
|
+
const doors = this.host.doors();
|
|
233
|
+
const below = (entry: GrantEntry): void => {
|
|
234
|
+
for (const child of doors.childrenOf(entry.principal)) {
|
|
235
|
+
if (child.principal.kind === "run") continue;
|
|
236
|
+
below(child);
|
|
237
|
+
records.push(this.record(CORE_TYPES.accessClosed, by, { grant: child.id, principal: child.principal, reason }));
|
|
238
|
+
closed.push(child.principal);
|
|
239
|
+
}
|
|
240
|
+
};
|
|
241
|
+
below(from);
|
|
242
|
+
if (self) {
|
|
243
|
+
records.push(this.record(CORE_TYPES.accessClosed, by, { grant: from.id, principal: from.principal, reason }));
|
|
244
|
+
closed.push(from.principal);
|
|
245
|
+
}
|
|
246
|
+
return records;
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
/** Does an answer of the owner already stand for this call: `run`, as long as the grant lives? */
|
|
250
|
+
answeredRun(question: AskQuestion): boolean {
|
|
251
|
+
return this.host.doors().answeredRun(question.grant, question.name, question.target);
|
|
252
|
+
}
|
|
253
|
+
|
|
254
|
+
/**
|
|
255
|
+
* Write down the owner's answer to a call that asked. `run` stays in force with the
|
|
256
|
+
* grant; `always` also gives the subject a grant with the exact action and target and no `ask`,
|
|
257
|
+
* a widening that touches nothing living. The rule that asked stays as it is: a sibling the
|
|
258
|
+
* owner was not asked about asks again.
|
|
259
|
+
*/
|
|
260
|
+
answered(question: AskQuestion, scope: AskScope): void {
|
|
261
|
+
const records: NewRecord[] = [
|
|
262
|
+
this.record(CORE_TYPES.accessAnswered, { kind: "host" }, {
|
|
263
|
+
grant: question.grant,
|
|
264
|
+
principal: question.principal,
|
|
265
|
+
name: question.name,
|
|
266
|
+
...(question.target === undefined ? {} : { target: question.target }),
|
|
267
|
+
scope,
|
|
268
|
+
}),
|
|
269
|
+
];
|
|
270
|
+
const held = this.host.doors().grantOf(question.principal);
|
|
271
|
+
if (scope === "always" && held !== undefined && held.closed === undefined && held.id === question.grant) {
|
|
272
|
+
const exact = `call:${question.name}${question.target === undefined ? "" : `@${question.target}`}`;
|
|
273
|
+
const kept = held.grant.rules.filter((have) => ruleText(have) !== exact).map(specOf);
|
|
274
|
+
records.push(this.grantRecord(question.principal, grant([...kept, exact]), held.parent));
|
|
275
|
+
}
|
|
276
|
+
this.host.commit(records);
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
/** Record one decision of a grant: who, what, which rule, and the outcome. */
|
|
280
|
+
decided(caller: Caller, standing: Standing, verb: Verb, name: string, answer: Permit, at?: { step?: string; policy?: string }): RecordId | undefined {
|
|
281
|
+
if (caller.kind !== "client" || caller.principal === undefined) return undefined;
|
|
282
|
+
if (standing.kind === "unlimited" || (standing.kind === "limited" && standing.id === OWNER_GRANT_ID)) return undefined;
|
|
283
|
+
const data = {
|
|
284
|
+
principal: caller.principal,
|
|
285
|
+
verb,
|
|
286
|
+
name,
|
|
287
|
+
...(answer.grant === undefined ? {} : { grant: answer.grant }),
|
|
288
|
+
outcome: answer.allowed ? "allowed" : "denied",
|
|
289
|
+
...(answer.rule === undefined ? {} : { rule: answer.rule }),
|
|
290
|
+
...(answer.allowed && answer.answered !== undefined ? { answered: answer.answered } : {}),
|
|
291
|
+
...(answer.allowed ? {} : { reason: answer.reason }),
|
|
292
|
+
...(answer.allowed || answer.missing === undefined ? {} : { missing: answer.missing }),
|
|
293
|
+
...(at?.step === undefined ? {} : { step: at.step }),
|
|
294
|
+
...(at?.policy === undefined ? {} : { policy: at.policy }),
|
|
295
|
+
};
|
|
296
|
+
const [stored] = this.host.commit([this.record(CORE_TYPES.accessDecided, caller, data)]);
|
|
297
|
+
return stored?.id;
|
|
298
|
+
}
|
|
299
|
+
|
|
300
|
+
/** The rules a subject has: what it may see of its own rights. */
|
|
301
|
+
mine(caller: Caller): { principal?: Principal; grant?: GrantId; unlimited: boolean; closed?: string; rules: RuleSpec[] } {
|
|
302
|
+
const principal = caller.kind === "client" ? caller.principal : undefined;
|
|
303
|
+
const standing = this.standing(caller);
|
|
304
|
+
const who = principal === undefined ? {} : { principal };
|
|
305
|
+
switch (standing.kind) {
|
|
306
|
+
case "unlimited":
|
|
307
|
+
return { ...who, unlimited: true, rules: [] };
|
|
308
|
+
case "off":
|
|
309
|
+
return { ...who, unlimited: false, rules: [] };
|
|
310
|
+
case "closed":
|
|
311
|
+
return { ...who, grant: standing.id, unlimited: false, closed: standing.reason, rules: [] };
|
|
312
|
+
case "limited":
|
|
313
|
+
return { ...who, grant: standing.id, unlimited: false, rules: specsOf(standing.grant) };
|
|
314
|
+
}
|
|
315
|
+
}
|
|
316
|
+
|
|
317
|
+
/** A record of the journal. */
|
|
318
|
+
recordOf(id: RecordId): StoredRecord | undefined {
|
|
319
|
+
return this.host.read(id);
|
|
320
|
+
}
|
|
321
|
+
|
|
322
|
+
/** What a decision record says; undefined for any other record. */
|
|
323
|
+
decisionOf(stored: StoredRecord): z.infer<typeof DecidedData> | undefined {
|
|
324
|
+
if (stored.type !== CORE_TYPES.accessDecided) return undefined;
|
|
325
|
+
const parsed = DecidedData.safeParse(stored.data);
|
|
326
|
+
return parsed.success ? parsed.data : undefined;
|
|
327
|
+
}
|
|
328
|
+
|
|
329
|
+
private record(type: RecordTypeName, actor: Caller, data: unknown): NewRecord {
|
|
330
|
+
const id = newRecordId("acc");
|
|
331
|
+
return { id, stream: streamId("access"), type, schema: 1, data, actor, cause: null, root: id };
|
|
332
|
+
}
|
|
333
|
+
}
|