@collective-intelligence/extensions-sdk 0.1.18 → 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
@@ -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`, `user.role` (organization membership
2170
- role), `groupIds` and `access`. CI sets `access` to `"read"`
2171
- for get, list, search, facets, autocomplete, traverse and retrieval, and to
2172
- `"write"` for create, update, delete and relation writes; a policy that does not
2173
- test it applies to both. For example, this `deny` `filter` policy lets
2174
- `member`-role users read every company but write only the ones whose accounts
2175
- field lists them:
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: "eq",
2195
- left: { kind: "subject", path: ["user", "role"] },
2196
- right: { kind: "literal", value: "member" }
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,53 @@ const memberCompanyWrites = declareKnowledgePolicy({
2215
2217
  })
2216
2218
  ```
2217
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
+
2218
2267
  Schema/domain targets cover all sources. Dataset grants use existing
2219
2268
  user/service principals and native operations, fields, `sensitiveFields`, row
2220
2269
  filters and budgets.
@@ -269,22 +269,25 @@ export type KnowledgePolicyPredicate = Readonly<{
269
269
  /**
270
270
  * A Knowledge policy: `subjectMatch` selects whom it applies to, `rule` which
271
271
  * records. `subject` refs read the caller as CI built it: `user.id`,
272
- * `user.role` (the organization membership role), `groupIds` and `access`.
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"] } }`.
273
276
  * `access` is `"read"` for get, list, search, facets, autocomplete, traverse
274
277
  * and retrieval, and `"write"` for create, update, delete and relation writes;
275
278
  * the deciding operation sets it, never the caller. A policy that does not
276
279
  * test `access` applies to both. `resource` refs read `["id"]` or a `data`
277
280
  * path.
278
281
  *
279
- * Write-only deny: members read every company but write only the ones whose
280
- * accounts field lists them.
282
+ * Write-only deny: users with the `member` User Role read every company but
283
+ * write only the ones whose accounts field lists them.
281
284
  *
282
285
  * ```ts
283
286
  * const memberCompanyWrites: KnowledgePolicyBody = {
284
287
  * subjectMatch: {
285
288
  * op: "and",
286
289
  * args: [
287
- * { op: "eq", left: { kind: "subject", path: ["user", "role"] }, right: { kind: "literal", value: "member" } },
290
+ * { op: "in", value: { kind: "literal", value: "member" }, set: { kind: "subject", path: ["roles"] } },
288
291
  * { op: "eq", left: { kind: "subject", path: ["access"] }, right: { kind: "literal", value: "write" } }
289
292
  * ]
290
293
  * },
@@ -295,9 +298,40 @@ export type KnowledgePolicyPredicate = Readonly<{
295
298
  * }
296
299
  * ```
297
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
+ * ```
298
319
  */
299
320
  export type KnowledgePolicyBody = Readonly<{
300
321
  subjectMatch: KnowledgePolicyPredicate;
301
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[])[];
302
336
  }>;
303
337
  export {};