@collective-intelligence/extensions-sdk 0.1.18 → 0.1.20
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +111 -10
- package/dist/components/knowledge.d.ts +91 -4
- package/dist/index.js +2 -2
- package/dist/package/policy-readers.d.ts +7 -1
- package/dist/package/primitive-readers.d.ts +2 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2166,13 +2166,15 @@ Use your actual exact dependency release, executable/schema FQNs, source locatio
|
|
|
2166
2166
|
and authorized Organization reader UUID. Knowledge policies use the native
|
|
2167
2167
|
`{ subjectMatch, rule? }` AST, including recursive comparisons and logical
|
|
2168
2168
|
predicates. The old `{ version, rules }` shape is rejected. `subject` refs read
|
|
2169
|
-
the caller as CI built it: `user.id`, `
|
|
2170
|
-
|
|
2171
|
-
|
|
2172
|
-
|
|
2173
|
-
|
|
2174
|
-
|
|
2175
|
-
|
|
2169
|
+
the caller as CI built it: `user.id`, `groupIds`, `roles` and `access`.
|
|
2170
|
+
`roles` lists the keys of the user's effective User Roles (`userRoles`) on the
|
|
2171
|
+
External App that makes the call, for example `["sales_manager"]`; it is empty
|
|
2172
|
+
for a call outside an External App. Match a role with `in` on the subject path
|
|
2173
|
+
`["roles"]`. CI sets `access` to `"read"` for get, list, search, facets,
|
|
2174
|
+
autocomplete, traverse and retrieval, and to `"write"` for create, update,
|
|
2175
|
+
delete and relation writes; a policy that does not test it applies to both. For
|
|
2176
|
+
example, this `deny` `filter` policy lets users with the `member` User Role read
|
|
2177
|
+
every company but write only the ones whose accounts field lists them:
|
|
2176
2178
|
|
|
2177
2179
|
```ts
|
|
2178
2180
|
const memberCompanyWrites = declareKnowledgePolicy({
|
|
@@ -2191,9 +2193,9 @@ const memberCompanyWrites = declareKnowledgePolicy({
|
|
|
2191
2193
|
op: "and",
|
|
2192
2194
|
args: [
|
|
2193
2195
|
{
|
|
2194
|
-
op: "
|
|
2195
|
-
|
|
2196
|
-
|
|
2196
|
+
op: "in",
|
|
2197
|
+
value: { kind: "literal", value: "member" },
|
|
2198
|
+
set: { kind: "subject", path: ["roles"] }
|
|
2197
2199
|
},
|
|
2198
2200
|
{
|
|
2199
2201
|
op: "eq",
|
|
@@ -2215,6 +2217,105 @@ const memberCompanyWrites = declareKnowledgePolicy({
|
|
|
2215
2217
|
})
|
|
2216
2218
|
```
|
|
2217
2219
|
|
|
2220
|
+
A relation scope follows a relation field of the record:
|
|
2221
|
+
`{ op: "relation_field", field, inner }` holds when `inner` holds for some live
|
|
2222
|
+
entity that the record's relation field `field` names, and `resource` refs in
|
|
2223
|
+
`inner` read that related entity. CI applies it to every read and write of the
|
|
2224
|
+
record: lists, gets, searches, facets, realtime events, deletes, and creates and
|
|
2225
|
+
updates, which it checks on the related entity the write names. Hops nest. For
|
|
2226
|
+
example, users read and write a task only when its `project` lists them in the
|
|
2227
|
+
project's `members` accounts field, or when they have the `manager` User Role:
|
|
2228
|
+
|
|
2229
|
+
```ts
|
|
2230
|
+
const projectMembers = {
|
|
2231
|
+
op: "in",
|
|
2232
|
+
value: { kind: "subject", path: ["user", "id"] },
|
|
2233
|
+
set: { kind: "resource", path: ["data", "members"] }
|
|
2234
|
+
} as const
|
|
2235
|
+
|
|
2236
|
+
const projectTasks = declareKnowledgePolicy({
|
|
2237
|
+
manifest: { fqn: "com.acme.work.policies.project_tasks", version: "1.0.0" },
|
|
2238
|
+
presentation: { displayName: "Project members work on its tasks" },
|
|
2239
|
+
definition: {
|
|
2240
|
+
effect: "allow",
|
|
2241
|
+
policyType: "filter",
|
|
2242
|
+
targetKind: "entity_schema",
|
|
2243
|
+
targetFqn: "com.acme.work.task",
|
|
2244
|
+
policyBody: {
|
|
2245
|
+
subjectMatch: { op: "const", value: true },
|
|
2246
|
+
rule: {
|
|
2247
|
+
op: "or",
|
|
2248
|
+
args: [
|
|
2249
|
+
{
|
|
2250
|
+
op: "in",
|
|
2251
|
+
value: { kind: "literal", value: "manager" },
|
|
2252
|
+
set: { kind: "subject", path: ["roles"] }
|
|
2253
|
+
},
|
|
2254
|
+
{ op: "relation_field", field: "project", inner: projectMembers }
|
|
2255
|
+
]
|
|
2256
|
+
}
|
|
2257
|
+
}
|
|
2258
|
+
}
|
|
2259
|
+
})
|
|
2260
|
+
```
|
|
2261
|
+
|
|
2262
|
+
A comment on a task follows its `task`, then the task's `project`, with the
|
|
2263
|
+
rule `{ op: "relation_field", field: "task", inner: { op: "relation_field",
|
|
2264
|
+
field: "project", inner: projectMembers } }`. A hop to a deleted entity names
|
|
2265
|
+
nothing. Hops belong in `rule`, never in `subjectMatch`, and only on a policy
|
|
2266
|
+
that targets one entity schema; a hop does not mix `field` with
|
|
2267
|
+
`relationSchemaId` or `direction`. CI refuses at deploy a `field` that is not a
|
|
2268
|
+
forward relation field of the schema the hop starts from. The
|
|
2269
|
+
older `{ op: "relation_field", relationSchemaId, direction, inner }` form names
|
|
2270
|
+
a relation schema; CI does not evaluate it and treats it as true.
|
|
2271
|
+
|
|
2272
|
+
A field write rule limits what an `allow` `filter` policy on an entity schema
|
|
2273
|
+
or domain admits to updates of the listed `data` paths. `writableFields` is a
|
|
2274
|
+
non-empty list of `["data", key, ...]` paths; a change at or under a path is
|
|
2275
|
+
within it. CI compares the stored record with the record the update would
|
|
2276
|
+
store: a value it resends unchanged is no change, but a key a `"replace"`
|
|
2277
|
+
update omits is removed and so changed. The update is admitted only when one of the `allow` policies that admit
|
|
2278
|
+
the record has no `writableFields` or lists every changed path; a `deny`
|
|
2279
|
+
policy still refuses it. A File or relation field the update writes counts as
|
|
2280
|
+
changed, and a change of the record's name, description or external binding is
|
|
2281
|
+
outside every `writableFields`. A policy with `writableFields` admits no
|
|
2282
|
+
create, delete or relation write and does not change reads. For example, users
|
|
2283
|
+
with the `operator` User Role may update only the status:
|
|
2284
|
+
|
|
2285
|
+
```ts
|
|
2286
|
+
const operatorStatusUpdates = declareKnowledgePolicy({
|
|
2287
|
+
manifest: {
|
|
2288
|
+
fqn: "com.acme.actions.policies.operator_status_updates",
|
|
2289
|
+
version: "1.0.0"
|
|
2290
|
+
},
|
|
2291
|
+
presentation: { displayName: "Operators update only the status" },
|
|
2292
|
+
definition: {
|
|
2293
|
+
effect: "allow",
|
|
2294
|
+
policyType: "filter",
|
|
2295
|
+
targetKind: "entity_schema",
|
|
2296
|
+
targetFqn: "com.acme.actions.action",
|
|
2297
|
+
policyBody: {
|
|
2298
|
+
subjectMatch: {
|
|
2299
|
+
op: "and",
|
|
2300
|
+
args: [
|
|
2301
|
+
{
|
|
2302
|
+
op: "in",
|
|
2303
|
+
value: { kind: "literal", value: "operator" },
|
|
2304
|
+
set: { kind: "subject", path: ["roles"] }
|
|
2305
|
+
},
|
|
2306
|
+
{
|
|
2307
|
+
op: "eq",
|
|
2308
|
+
left: { kind: "subject", path: ["access"] },
|
|
2309
|
+
right: { kind: "literal", value: "write" }
|
|
2310
|
+
}
|
|
2311
|
+
]
|
|
2312
|
+
},
|
|
2313
|
+
writableFields: [["data", "status"]]
|
|
2314
|
+
}
|
|
2315
|
+
}
|
|
2316
|
+
})
|
|
2317
|
+
```
|
|
2318
|
+
|
|
2218
2319
|
Schema/domain targets cover all sources. Dataset grants use existing
|
|
2219
2320
|
user/service principals and native operations, fields, `sensitiveFields`, row
|
|
2220
2321
|
filters and budgets.
|
|
@@ -265,26 +265,82 @@ export type KnowledgePolicyPredicate = Readonly<{
|
|
|
265
265
|
relationSchemaId: string;
|
|
266
266
|
direction: "out" | "in";
|
|
267
267
|
inner: KnowledgePolicyPredicate;
|
|
268
|
+
}>
|
|
269
|
+
/**
|
|
270
|
+
* An Entity Relation Field hop: true when `inner` holds for some live
|
|
271
|
+
* entity that the record's own relation field `field` names. Inside
|
|
272
|
+
* `inner`, `resource` refs read that target entity; `subject` refs are
|
|
273
|
+
* unchanged. Hops nest, one per relation field. A hop belongs in `rule`,
|
|
274
|
+
* only on an `entity_schema` policy, and `field` must be a forward relation
|
|
275
|
+
* field of the schema the hop starts from.
|
|
276
|
+
*/
|
|
277
|
+
| Readonly<{
|
|
278
|
+
op: "relation_field";
|
|
279
|
+
field: string;
|
|
280
|
+
inner: KnowledgePolicyPredicate;
|
|
268
281
|
}>;
|
|
269
282
|
/**
|
|
270
283
|
* A Knowledge policy: `subjectMatch` selects whom it applies to, `rule` which
|
|
271
284
|
* records. `subject` refs read the caller as CI built it: `user.id`,
|
|
272
|
-
* `
|
|
285
|
+
* `groupIds`, `roles` and `access`. `roles` lists the keys of the user's
|
|
286
|
+
* effective User Roles (`userRoles`) on the External App that makes the call;
|
|
287
|
+
* it is empty for a call outside an External App. Match a role with
|
|
288
|
+
* `{ op: "in", value: { kind: "literal", value: "<role key>" }, set: { kind: "subject", path: ["roles"] } }`.
|
|
273
289
|
* `access` is `"read"` for get, list, search, facets, autocomplete, traverse
|
|
274
290
|
* and retrieval, and `"write"` for create, update, delete and relation writes;
|
|
275
291
|
* the deciding operation sets it, never the caller. A policy that does not
|
|
276
292
|
* test `access` applies to both. `resource` refs read `["id"]` or a `data`
|
|
277
293
|
* path.
|
|
278
294
|
*
|
|
279
|
-
*
|
|
280
|
-
*
|
|
295
|
+
* Relation scope: `{ op: "relation_field", field, inner }` follows the
|
|
296
|
+
* record's relation field `field` and tests `inner` on the entities it names;
|
|
297
|
+
* `resource` refs in `inner` read the related entity. CI applies it to every
|
|
298
|
+
* read and write of the record: lists, gets, searches, realtime events, and
|
|
299
|
+
* creates and updates, which it checks on the related entity the write names.
|
|
300
|
+
* Users read and write a task only when the task's `project` lists them in
|
|
301
|
+
* its `members` accounts field, or when they have the `manager` User Role:
|
|
302
|
+
*
|
|
303
|
+
* ```ts
|
|
304
|
+
* const projectMembersOnly: KnowledgePolicyBody = {
|
|
305
|
+
* subjectMatch: { op: "const", value: true },
|
|
306
|
+
* rule: {
|
|
307
|
+
* op: "or",
|
|
308
|
+
* args: [
|
|
309
|
+
* { op: "in", value: { kind: "literal", value: "manager" }, set: { kind: "subject", path: ["roles"] } },
|
|
310
|
+
* {
|
|
311
|
+
* op: "relation_field",
|
|
312
|
+
* field: "project",
|
|
313
|
+
* inner: { op: "in", value: { kind: "subject", path: ["user", "id"] }, set: { kind: "resource", path: ["data", "members"] } }
|
|
314
|
+
* }
|
|
315
|
+
* ]
|
|
316
|
+
* }
|
|
317
|
+
* }
|
|
318
|
+
* ```
|
|
319
|
+
* Declare it on the task schema with `effect: "allow"` and `policyType:
|
|
320
|
+
* "filter"`. Hops nest: a comment follows its `task`, then the task's
|
|
321
|
+
* `project`:
|
|
322
|
+
*
|
|
323
|
+
* ```ts
|
|
324
|
+
* const commentRule: KnowledgePolicyPredicate = {
|
|
325
|
+
* op: "relation_field",
|
|
326
|
+
* field: "task",
|
|
327
|
+
* inner: {
|
|
328
|
+
* op: "relation_field",
|
|
329
|
+
* field: "project",
|
|
330
|
+
* inner: { op: "in", value: { kind: "subject", path: ["user", "id"] }, set: { kind: "resource", path: ["data", "members"] } }
|
|
331
|
+
* }
|
|
332
|
+
* }
|
|
333
|
+
* ```
|
|
334
|
+
*
|
|
335
|
+
* Write-only deny: users with the `member` User Role read every company but
|
|
336
|
+
* write only the ones whose accounts field lists them.
|
|
281
337
|
*
|
|
282
338
|
* ```ts
|
|
283
339
|
* const memberCompanyWrites: KnowledgePolicyBody = {
|
|
284
340
|
* subjectMatch: {
|
|
285
341
|
* op: "and",
|
|
286
342
|
* args: [
|
|
287
|
-
* { op: "
|
|
343
|
+
* { op: "in", value: { kind: "literal", value: "member" }, set: { kind: "subject", path: ["roles"] } },
|
|
288
344
|
* { op: "eq", left: { kind: "subject", path: ["access"] }, right: { kind: "literal", value: "write" } }
|
|
289
345
|
* ]
|
|
290
346
|
* },
|
|
@@ -295,9 +351,40 @@ export type KnowledgePolicyPredicate = Readonly<{
|
|
|
295
351
|
* }
|
|
296
352
|
* ```
|
|
297
353
|
* Declare it with `effect: "deny"` and `policyType: "filter"`.
|
|
354
|
+
*
|
|
355
|
+
* Field write rule: `writableFields` limits the writes an `allow` `filter`
|
|
356
|
+
* policy on an entity schema or domain admits to updates that change only
|
|
357
|
+
* the listed `data` paths. Users with the `operator` User Role update only
|
|
358
|
+
* the status of every record:
|
|
359
|
+
*
|
|
360
|
+
* ```ts
|
|
361
|
+
* const operatorStatusUpdates: KnowledgePolicyBody = {
|
|
362
|
+
* subjectMatch: {
|
|
363
|
+
* op: "and",
|
|
364
|
+
* args: [
|
|
365
|
+
* { op: "in", value: { kind: "literal", value: "operator" }, set: { kind: "subject", path: ["roles"] } },
|
|
366
|
+
* { op: "eq", left: { kind: "subject", path: ["access"] }, right: { kind: "literal", value: "write" } }
|
|
367
|
+
* ]
|
|
368
|
+
* },
|
|
369
|
+
* writableFields: [["data", "status"]]
|
|
370
|
+
* }
|
|
371
|
+
* ```
|
|
298
372
|
*/
|
|
299
373
|
export type KnowledgePolicyBody = Readonly<{
|
|
300
374
|
subjectMatch: KnowledgePolicyPredicate;
|
|
301
375
|
rule?: KnowledgePolicyPredicate;
|
|
376
|
+
/**
|
|
377
|
+
* The `["data", key, ...]` paths an update this policy admits may change; a
|
|
378
|
+
* change at or under a path is within it. Present only on an `allow`
|
|
379
|
+
* `filter` policy on an entity schema or domain. CI compares the stored
|
|
380
|
+
* record with the record the update would store: the update is admitted
|
|
381
|
+
* only when one of the `allow` policies that admit the record has no
|
|
382
|
+
* `writableFields`, or lists every changed path. A File or relation field
|
|
383
|
+
* the update writes counts as changed; a change of the record's name,
|
|
384
|
+
* description or external binding is outside every `writableFields`. Such
|
|
385
|
+
* a policy admits no create, delete or relation write, and does not change
|
|
386
|
+
* reads.
|
|
387
|
+
*/
|
|
388
|
+
writableFields?: readonly (readonly string[])[];
|
|
302
389
|
}>;
|
|
303
390
|
export {};
|