@collective-intelligence/extensions-sdk 0.1.17 → 0.1.19
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
CHANGED
|
@@ -452,9 +452,8 @@ Users; every other User field accepts Organization members only.
|
|
|
452
452
|
|
|
453
453
|
At most one User field per schema sets `accounts: true`
|
|
454
454
|
(`accounts: { accounts: true, multiple: true }`). It becomes the schema's
|
|
455
|
-
accounts field: the users it lists act for the record
|
|
456
|
-
|
|
457
|
-
for that schema.
|
|
455
|
+
accounts field: the users it lists act for the record. Only the host writes
|
|
456
|
+
it, and a policy can read it as `resource` path `["data", "accounts"]`.
|
|
458
457
|
|
|
459
458
|
`declareKnowledgeEntitySchema` declares File fields in `fileFields`, keyed by
|
|
460
459
|
top-level property key. Each declaration takes `multiple`, `accepts` (matched
|
|
@@ -2167,13 +2166,15 @@ Use your actual exact dependency release, executable/schema FQNs, source locatio
|
|
|
2167
2166
|
and authorized Organization reader UUID. Knowledge policies use the native
|
|
2168
2167
|
`{ subjectMatch, rule? }` AST, including recursive comparisons and logical
|
|
2169
2168
|
predicates. The old `{ version, rules }` shape is rejected. `subject` refs read
|
|
2170
|
-
the caller as CI built it: `user.id`, `
|
|
2171
|
-
|
|
2172
|
-
|
|
2173
|
-
|
|
2174
|
-
|
|
2175
|
-
|
|
2176
|
-
to
|
|
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:
|
|
2177
2178
|
|
|
2178
2179
|
```ts
|
|
2179
2180
|
const memberCompanyWrites = declareKnowledgePolicy({
|
|
@@ -2192,9 +2193,9 @@ const memberCompanyWrites = declareKnowledgePolicy({
|
|
|
2192
2193
|
op: "and",
|
|
2193
2194
|
args: [
|
|
2194
2195
|
{
|
|
2195
|
-
op: "
|
|
2196
|
-
|
|
2197
|
-
|
|
2196
|
+
op: "in",
|
|
2197
|
+
value: { kind: "literal", value: "member" },
|
|
2198
|
+
set: { kind: "subject", path: ["roles"] }
|
|
2198
2199
|
},
|
|
2199
2200
|
{
|
|
2200
2201
|
op: "eq",
|
|
@@ -2207,8 +2208,8 @@ const memberCompanyWrites = declareKnowledgePolicy({
|
|
|
2207
2208
|
op: "not",
|
|
2208
2209
|
arg: {
|
|
2209
2210
|
op: "in",
|
|
2210
|
-
value: { kind: "
|
|
2211
|
-
set: { kind: "
|
|
2211
|
+
value: { kind: "subject", path: ["user", "id"] },
|
|
2212
|
+
set: { kind: "resource", path: ["data", "accounts"] }
|
|
2212
2213
|
}
|
|
2213
2214
|
}
|
|
2214
2215
|
}
|
|
@@ -2216,6 +2217,53 @@ const memberCompanyWrites = declareKnowledgePolicy({
|
|
|
2216
2217
|
})
|
|
2217
2218
|
```
|
|
2218
2219
|
|
|
2220
|
+
A field write rule limits what an `allow` `filter` policy on an entity schema
|
|
2221
|
+
or domain admits to updates of the listed `data` paths. `writableFields` is a
|
|
2222
|
+
non-empty list of `["data", key, ...]` paths; a change at or under a path is
|
|
2223
|
+
within it. CI compares the stored record with the record the update would
|
|
2224
|
+
store: a value it resends unchanged is no change, but a key a `"replace"`
|
|
2225
|
+
update omits is removed and so changed. The update is admitted only when one of the `allow` policies that admit
|
|
2226
|
+
the record has no `writableFields` or lists every changed path; a `deny`
|
|
2227
|
+
policy still refuses it. A File or relation field the update writes counts as
|
|
2228
|
+
changed, and a change of the record's name, description or external binding is
|
|
2229
|
+
outside every `writableFields`. A policy with `writableFields` admits no
|
|
2230
|
+
create, delete or relation write and does not change reads. For example, users
|
|
2231
|
+
with the `operator` User Role may update only the status:
|
|
2232
|
+
|
|
2233
|
+
```ts
|
|
2234
|
+
const operatorStatusUpdates = declareKnowledgePolicy({
|
|
2235
|
+
manifest: {
|
|
2236
|
+
fqn: "com.acme.actions.policies.operator_status_updates",
|
|
2237
|
+
version: "1.0.0"
|
|
2238
|
+
},
|
|
2239
|
+
presentation: { displayName: "Operators update only the status" },
|
|
2240
|
+
definition: {
|
|
2241
|
+
effect: "allow",
|
|
2242
|
+
policyType: "filter",
|
|
2243
|
+
targetKind: "entity_schema",
|
|
2244
|
+
targetFqn: "com.acme.actions.action",
|
|
2245
|
+
policyBody: {
|
|
2246
|
+
subjectMatch: {
|
|
2247
|
+
op: "and",
|
|
2248
|
+
args: [
|
|
2249
|
+
{
|
|
2250
|
+
op: "in",
|
|
2251
|
+
value: { kind: "literal", value: "operator" },
|
|
2252
|
+
set: { kind: "subject", path: ["roles"] }
|
|
2253
|
+
},
|
|
2254
|
+
{
|
|
2255
|
+
op: "eq",
|
|
2256
|
+
left: { kind: "subject", path: ["access"] },
|
|
2257
|
+
right: { kind: "literal", value: "write" }
|
|
2258
|
+
}
|
|
2259
|
+
]
|
|
2260
|
+
},
|
|
2261
|
+
writableFields: [["data", "status"]]
|
|
2262
|
+
}
|
|
2263
|
+
}
|
|
2264
|
+
})
|
|
2265
|
+
```
|
|
2266
|
+
|
|
2219
2267
|
Schema/domain targets cover all sources. Dataset grants use existing
|
|
2220
2268
|
user/service principals and native operations, fields, `sensitiveFields`, row
|
|
2221
2269
|
filters and budgets.
|
|
@@ -30,8 +30,7 @@ export type KnowledgeFileFieldDeclaration = KnowledgeFileField & Readonly<{
|
|
|
30
30
|
* Explicit top-level references to Organization members or External App Users
|
|
31
31
|
* of the Organization; the host generates UUID values. `accounts: true` makes
|
|
32
32
|
* it the schema's accounts field (at most one per schema): the users it lists
|
|
33
|
-
* act for the record
|
|
34
|
-
* `linkedCompanyIds`.
|
|
33
|
+
* act for the record. Only the host writes it.
|
|
35
34
|
*/
|
|
36
35
|
export type KnowledgeUserField = Readonly<{
|
|
37
36
|
accounts?: true;
|
|
@@ -270,35 +269,69 @@ export type KnowledgePolicyPredicate = Readonly<{
|
|
|
270
269
|
/**
|
|
271
270
|
* A Knowledge policy: `subjectMatch` selects whom it applies to, `rule` which
|
|
272
271
|
* records. `subject` refs read the caller as CI built it: `user.id`,
|
|
273
|
-
* `
|
|
274
|
-
* `
|
|
272
|
+
* `groupIds`, `roles` and `access`. `roles` lists the keys of the user's
|
|
273
|
+
* effective User Roles (`userRoles`) on the External App that makes the call;
|
|
274
|
+
* it is empty for a call outside an External App. Match a role with
|
|
275
|
+
* `{ op: "in", value: { kind: "literal", value: "<role key>" }, set: { kind: "subject", path: ["roles"] } }`.
|
|
275
276
|
* `access` is `"read"` for get, list, search, facets, autocomplete, traverse
|
|
276
277
|
* and retrieval, and `"write"` for create, update, delete and relation writes;
|
|
277
278
|
* the deciding operation sets it, never the caller. A policy that does not
|
|
278
279
|
* test `access` applies to both. `resource` refs read `["id"]` or a `data`
|
|
279
280
|
* path.
|
|
280
281
|
*
|
|
281
|
-
* Write-only deny:
|
|
282
|
+
* Write-only deny: users with the `member` User Role read every company but
|
|
283
|
+
* write only the ones whose accounts field lists them.
|
|
282
284
|
*
|
|
283
285
|
* ```ts
|
|
284
286
|
* const memberCompanyWrites: KnowledgePolicyBody = {
|
|
285
287
|
* subjectMatch: {
|
|
286
288
|
* op: "and",
|
|
287
289
|
* args: [
|
|
288
|
-
* { op: "
|
|
290
|
+
* { op: "in", value: { kind: "literal", value: "member" }, set: { kind: "subject", path: ["roles"] } },
|
|
289
291
|
* { op: "eq", left: { kind: "subject", path: ["access"] }, right: { kind: "literal", value: "write" } }
|
|
290
292
|
* ]
|
|
291
293
|
* },
|
|
292
294
|
* rule: {
|
|
293
295
|
* op: "not",
|
|
294
|
-
* arg: { op: "in", value: { kind: "
|
|
296
|
+
* arg: { op: "in", value: { kind: "subject", path: ["user", "id"] }, set: { kind: "resource", path: ["data", "accounts"] } }
|
|
295
297
|
* }
|
|
296
298
|
* }
|
|
297
299
|
* ```
|
|
298
300
|
* Declare it with `effect: "deny"` and `policyType: "filter"`.
|
|
301
|
+
*
|
|
302
|
+
* Field write rule: `writableFields` limits the writes an `allow` `filter`
|
|
303
|
+
* policy on an entity schema or domain admits to updates that change only
|
|
304
|
+
* the listed `data` paths. Users with the `operator` User Role update only
|
|
305
|
+
* the status of every record:
|
|
306
|
+
*
|
|
307
|
+
* ```ts
|
|
308
|
+
* const operatorStatusUpdates: KnowledgePolicyBody = {
|
|
309
|
+
* subjectMatch: {
|
|
310
|
+
* op: "and",
|
|
311
|
+
* args: [
|
|
312
|
+
* { op: "in", value: { kind: "literal", value: "operator" }, set: { kind: "subject", path: ["roles"] } },
|
|
313
|
+
* { op: "eq", left: { kind: "subject", path: ["access"] }, right: { kind: "literal", value: "write" } }
|
|
314
|
+
* ]
|
|
315
|
+
* },
|
|
316
|
+
* writableFields: [["data", "status"]]
|
|
317
|
+
* }
|
|
318
|
+
* ```
|
|
299
319
|
*/
|
|
300
320
|
export type KnowledgePolicyBody = Readonly<{
|
|
301
321
|
subjectMatch: KnowledgePolicyPredicate;
|
|
302
322
|
rule?: KnowledgePolicyPredicate;
|
|
323
|
+
/**
|
|
324
|
+
* The `["data", key, ...]` paths an update this policy admits may change; a
|
|
325
|
+
* change at or under a path is within it. Present only on an `allow`
|
|
326
|
+
* `filter` policy on an entity schema or domain. CI compares the stored
|
|
327
|
+
* record with the record the update would store: the update is admitted
|
|
328
|
+
* only when one of the `allow` policies that admit the record has no
|
|
329
|
+
* `writableFields`, or lists every changed path. A File or relation field
|
|
330
|
+
* the update writes counts as changed; a change of the record's name,
|
|
331
|
+
* description or external binding is outside every `writableFields`. Such
|
|
332
|
+
* a policy admits no create, delete or relation write, and does not change
|
|
333
|
+
* reads.
|
|
334
|
+
*/
|
|
335
|
+
writableFields?: readonly (readonly string[])[];
|
|
303
336
|
}>;
|
|
304
337
|
export {};
|