@collective-intelligence/extensions-sdk 0.2.1 → 0.2.3
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 +332 -368
- package/dist/access/application-gate.d.ts +36 -0
- package/dist/access/audience.d.ts +43 -0
- package/dist/access/capabilities.d.ts +105 -0
- package/dist/access/conditions.d.ts +136 -0
- package/dist/access/core-catalog.d.ts +221 -0
- package/dist/access/declarations.d.ts +169 -0
- package/dist/access/document-policy.d.ts +31 -0
- package/dist/access/index.d.ts +62 -0
- package/dist/access/knowledge-policy.d.ts +87 -0
- package/dist/access/manifest.d.ts +161 -0
- package/dist/access/readers.d.ts +114 -0
- package/dist/access/requirement.d.ts +61 -0
- package/dist/components/agents.d.ts +12 -30
- package/dist/components/authoring-core.d.ts +3 -1
- package/dist/components/base.d.ts +1 -1
- package/dist/components/connector-instances.d.ts +0 -3
- package/dist/components/declaration.d.ts +3 -2
- package/dist/components/document-collections.d.ts +3 -32
- package/dist/components/external-application.d.ts +18 -90
- package/dist/components/knowledge.d.ts +1 -164
- package/dist/components/metadata-authoring.d.ts +24 -21
- package/dist/components/organization-settings.d.ts +7 -2
- package/dist/components/service-principal.d.ts +9 -4
- package/dist/components/studio.d.ts +22 -44
- package/dist/components/tools.d.ts +15 -8
- package/dist/components/workflows.d.ts +7 -0
- package/dist/index.d.ts +13 -11
- package/dist/index.js +2 -2
- package/dist/package/primitive-readers.d.ts +111 -24
- package/dist/package/readers.d.ts +2 -0
- package/dist/package/variables.d.ts +1 -2
- package/docs/effect.md +2 -2
- package/package.json +2 -2
- package/dist/package/policy-readers.d.ts +0 -23
package/README.md
CHANGED
|
@@ -424,8 +424,8 @@ also require the persisted Organization entity schema capabilities:
|
|
|
424
424
|
`displayNameExpression`, `embeddingConfig`, `persistFullFieldContributions`,
|
|
425
425
|
`usableAsDocumentScope`, and `versioningEnabled`. Domain declarations require
|
|
426
426
|
`versioningEnabled`. External applications require `applicationType`,
|
|
427
|
-
`audience`, `allowedOrigins`, `redirectUris`, `postLogoutRedirectUris
|
|
428
|
-
`
|
|
427
|
+
`audience`, `allowedOrigins`, `redirectUris`, and `postLogoutRedirectUris`.
|
|
428
|
+
`redirectUris` lists every accepted callback. An optional
|
|
429
429
|
`primaryRedirectUri` names the default callback; it must be one of
|
|
430
430
|
`redirectUris`, and declaration and manifest parsing reject any other value.
|
|
431
431
|
When it is absent, the first redirect URI is the primary. Tokens and client
|
|
@@ -753,31 +753,32 @@ Strings are an escape hatch, not a checked reference: TypeScript accepts any
|
|
|
753
753
|
string, including a misspelled FQN. Install resolves every reference against
|
|
754
754
|
the installed catalog and rolls the package back when one does not exist: held
|
|
755
755
|
`skills` must be approved Skills, Agent and Skill `tools` must be enabled tools
|
|
756
|
-
of the Organization, and `audience
|
|
757
|
-
Organization or of the same package.
|
|
756
|
+
of the Organization, and every `audience` reference must name a Group, profile
|
|
757
|
+
or application of the Organization or of the same package.
|
|
758
758
|
|
|
759
759
|
### Agent audience
|
|
760
760
|
|
|
761
|
-
`audience` is the
|
|
762
|
-
|
|
763
|
-
|
|
761
|
+
`audience` is the Agent's Resource Audience: to whom it is offered. Entries
|
|
762
|
+
only allow; an omitted or empty `audience` offers the Agent to nobody. Its
|
|
763
|
+
shape is the shared `AccessAudience` type.
|
|
764
764
|
|
|
765
|
-
| Field
|
|
766
|
-
|
|
|
767
|
-
| `
|
|
768
|
-
| `
|
|
769
|
-
| `
|
|
770
|
-
| `
|
|
765
|
+
| Field | Values | Offers the Agent to |
|
|
766
|
+
| -------------- | --------------------------------------- | ----------------------------------------- |
|
|
767
|
+
| `organization` | `true` | Every member of the Organization |
|
|
768
|
+
| `groups` | Group references, optionally `coverage` | Group members (`inherited` reaches below) |
|
|
769
|
+
| `profiles` | Access Profile references | The holders of each profile |
|
|
770
|
+
| `applications` | application references | The users of each app |
|
|
771
|
+
| `anonymous` | application references | The anonymous visitors of each app |
|
|
771
772
|
|
|
772
773
|
```ts
|
|
773
774
|
declareAgent({
|
|
774
775
|
definition: {
|
|
775
776
|
...role,
|
|
776
777
|
audience: {
|
|
777
|
-
anonymous:
|
|
778
|
+
anonymous: [storefront],
|
|
778
779
|
applications: [storefront],
|
|
779
|
-
|
|
780
|
-
|
|
780
|
+
groups: [{ coverage: "direct", group: salesTeam }],
|
|
781
|
+
organization: true
|
|
781
782
|
},
|
|
782
783
|
...
|
|
783
784
|
},
|
|
@@ -785,16 +786,14 @@ declareAgent({
|
|
|
785
786
|
})
|
|
786
787
|
```
|
|
787
788
|
|
|
788
|
-
-
|
|
789
|
-
|
|
790
|
-
|
|
791
|
-
|
|
792
|
-
-
|
|
793
|
-
|
|
794
|
-
|
|
795
|
-
|
|
796
|
-
application and for an application listed more than once. Manifest readers
|
|
797
|
-
reject the same audiences.
|
|
789
|
+
- Packages never name users; administrators add user entries in the
|
|
790
|
+
Dashboard. The `lifecycle` decides whether their edits survive a deploy:
|
|
791
|
+
`upsert` writes the declared audience again, `init_only` keeps the edits,
|
|
792
|
+
and `readonly` refuses them.
|
|
793
|
+
- A Group without `coverage` reaches its subgroups (`inherited`).
|
|
794
|
+
- `declareAgent` throws a `TypeError` for a key outside these five (such as
|
|
795
|
+
the retired `members` and `organizationGroups`) and for a reference listed
|
|
796
|
+
twice. Manifest readers reject the same audiences.
|
|
798
797
|
|
|
799
798
|
### Tool binding controls
|
|
800
799
|
|
|
@@ -884,8 +883,10 @@ export const salesGroup = declareOrganizationGroup({
|
|
|
884
883
|
|
|
885
884
|
## Service principal declarations
|
|
886
885
|
|
|
887
|
-
`servicePrincipal` declares one non-human identity
|
|
888
|
-
|
|
886
|
+
`servicePrincipal` declares one non-human identity and its memberships in
|
|
887
|
+
Groups declared by the same package. Its authority comes from the Access
|
|
888
|
+
Grants that name it (`declareAccessProfileGrant` with
|
|
889
|
+
`grantee: { servicePrincipal }`). `version` is required
|
|
889
890
|
common SDK primitive metadata; it has no default and is independent of the
|
|
890
891
|
package version. `name` becomes the manifest's `displayName`.
|
|
891
892
|
|
|
@@ -900,7 +901,6 @@ const importer = servicePrincipal({
|
|
|
900
901
|
fqn: "acme.directory.importer",
|
|
901
902
|
name: "Importer",
|
|
902
903
|
version: "1.0.0",
|
|
903
|
-
organizationRole: "organization_operator",
|
|
904
904
|
groups: [salesGroup, "acme.directory.groups.sales.inside-sales.emea"]
|
|
905
905
|
})
|
|
906
906
|
|
|
@@ -910,14 +910,17 @@ export const directory = declarePackage({
|
|
|
910
910
|
})
|
|
911
911
|
```
|
|
912
912
|
|
|
913
|
-
`
|
|
914
|
-
`organization_member`. `groups` is a required array; use `[]` for no memberships.
|
|
913
|
+
`groups` is a required array; use `[]` for no memberships.
|
|
915
914
|
A root Group handle or a root/subgroup FQN is accepted and serialized as an FQN
|
|
916
915
|
string. Both `declarePackage` and `parsePackageManifest` require each referenced
|
|
917
916
|
Group to be declared in that same manifest. A matching FQN prefix, a package
|
|
918
917
|
dependency, or a Group's external parent does not make a Group package-owned.
|
|
919
|
-
The declaration contains no credentials or runtime implementation
|
|
920
|
-
|
|
918
|
+
The declaration contains no credentials or runtime implementation; runtime
|
|
919
|
+
authorization belongs to the Host. `adminServicePrincipals(primitives)` lists
|
|
920
|
+
the principals that a declared grant makes administrators: a grant of
|
|
921
|
+
`core.profiles.organization-admin`, or of a profile of the package that holds an
|
|
922
|
+
`admin` capability at `manage`. A deploy asks for one confirmation for each of
|
|
923
|
+
them.
|
|
921
924
|
|
|
922
925
|
### Selecting a Workflow run-as principal
|
|
923
926
|
|
|
@@ -1015,7 +1018,7 @@ export const acmeSettings = declareOrganizationSettings({
|
|
|
1015
1018
|
domains: ["acme.example"],
|
|
1016
1019
|
connection: { setupKey: "okta" },
|
|
1017
1020
|
provisionMembers: true,
|
|
1018
|
-
|
|
1021
|
+
defaultProfile: "acme.directory.profiles.employee"
|
|
1019
1022
|
}
|
|
1020
1023
|
],
|
|
1021
1024
|
applicationConsent: "ask"
|
|
@@ -1042,9 +1045,11 @@ export const acmeSettings = declareOrganizationSettings({
|
|
|
1042
1045
|
Organization SSO declaration of the same package or `{ providerId }` of a
|
|
1043
1046
|
pinned dependency; the manifest stores `{ fqn }` or `{ providerId }`.
|
|
1044
1047
|
Credentials arrive only through `connection: { setupKey }`.
|
|
1045
|
-
`provisionMembers`
|
|
1046
|
-
`
|
|
1047
|
-
|
|
1048
|
+
`provisionMembers` is required. A provider that registers members
|
|
1049
|
+
(`provisionMembers: true`) needs `defaultProfile`, the FQN of the Access
|
|
1050
|
+
Profile that each member it registers is granted; manifest admission
|
|
1051
|
+
refuses the entry without it. The installer must be able to grant that
|
|
1052
|
+
profile, which has no Grant Axis. `applicationConsent` is `ask` or `skip`.
|
|
1048
1053
|
- `locale` holds `defaultLanguage`, `languages` and `timezone`. `governance`
|
|
1049
1054
|
holds `accessAuditRetentionMonths` and `maxGroupHierarchyDepth`, positive
|
|
1050
1055
|
integers. Domain claims, language codes and the depth range are host checks.
|
|
@@ -1091,133 +1096,258 @@ export const acmeInstructions = declareOrganizationInstructions({
|
|
|
1091
1096
|
`declarePackage` and `parsePackageManifest` both reject `bindingScopes` that
|
|
1092
1097
|
include `tenant`.
|
|
1093
1098
|
|
|
1094
|
-
##
|
|
1095
|
-
|
|
1096
|
-
|
|
1097
|
-
|
|
1098
|
-
|
|
1099
|
-
|
|
1100
|
-
|
|
1099
|
+
## Access declarations
|
|
1100
|
+
|
|
1101
|
+
The SDK root exports the access vocabulary: the `declareAccess*` functions,
|
|
1102
|
+
their handles, `coreCapabilities`, `builtinGroups`, `knowledgeEntity` and one
|
|
1103
|
+
frozen `access` namespace with the helpers (`access.allow`, `access.requires`,
|
|
1104
|
+
`access.map`, `access.isMe`, `access.and`, ...). The namespace keeps generic
|
|
1105
|
+
names such as `and`, `or` and `eq` apart from other exports. There is no access
|
|
1106
|
+
subpath export. `unreadConditionAxes(axes, where)` returns the `byCondition`
|
|
1107
|
+
axes that no `grantAxis` operand of a `where` reads, or none while the `where`
|
|
1108
|
+
holds a declared condition; hosts use it on the inlined `where`.
|
|
1109
|
+
|
|
1110
|
+
| Declaration | Declares |
|
|
1111
|
+
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1112
|
+
| `declareAccessCapabilities` | Capability nodes below one Read/Manage root whose code is the declaration FQN |
|
|
1113
|
+
| `declareAccessGrantAxis` | A Grant Axis on one Knowledge entity schema, with an optional `hierarchy` self-relation |
|
|
1114
|
+
| `declareAccessProfile` | An Access Profile: `allow` entries, the axes every grant sets, `audience`, `canGrant` |
|
|
1115
|
+
| `declareAccessProfileGrant` | A static grant: one recipient, one profile, one Knowledge Entity Identifier per axis |
|
|
1116
|
+
| `declareAccessKnowledgeDataPolicy` | A rule on one schema and one operation: capability, axis bindings, `where`, field lists |
|
|
1117
|
+
| `declareAccessKnowledgeDataCondition` | A reusable, tested row predicate for a policy `where` |
|
|
1118
|
+
| `declareAccessDocumentDataPolicy` | A rule on one document collection or folder and one operation; no axes. `read` opens the current Version, `history` the older Versions, `write` creates, updates and deletes |
|
|
1119
|
+
| `declareAccessMaxPrivileges` | The capabilities that an app's user tokens or an API key template may use at most |
|
|
1120
|
+
| `declareCoreAccessPolicy` | A core tenant, admin or default policy of the core built-in package; returns a plain value |
|
|
1121
|
+
|
|
1122
|
+
### Capabilities
|
|
1123
|
+
|
|
1124
|
+
A node is a Switch (off, on) or a Read/Manage node (off, read, manage; manage
|
|
1125
|
+
includes read). A child without `kind` takes the kind of its parent. The kind
|
|
1126
|
+
of a handle decides the mode argument: `access.allow(core.studio)`,
|
|
1127
|
+
`access.allow(core.admin.users, "manage")`. A string names a node that another
|
|
1128
|
+
package declares: `access.allow("acme.hr.candidates", "read")`; the installer
|
|
1129
|
+
resolves it.
|
|
1101
1130
|
|
|
1102
1131
|
```ts
|
|
1103
|
-
|
|
1132
|
+
import {
|
|
1133
|
+
access,
|
|
1134
|
+
coreCapabilities as core,
|
|
1135
|
+
declareAccessCapabilities,
|
|
1136
|
+
declareAccessProfile
|
|
1137
|
+
} from "@collective-intelligence/extensions-sdk"
|
|
1138
|
+
|
|
1139
|
+
const { allow } = access
|
|
1140
|
+
|
|
1141
|
+
export const hr = declareAccessCapabilities({
|
|
1104
1142
|
definition: {
|
|
1105
|
-
|
|
1106
|
-
|
|
1107
|
-
{
|
|
1108
|
-
|
|
1109
|
-
|
|
1110
|
-
|
|
1111
|
-
|
|
1112
|
-
|
|
1113
|
-
|
|
1114
|
-
|
|
1115
|
-
|
|
1116
|
-
|
|
1117
|
-
|
|
1118
|
-
|
|
1119
|
-
|
|
1120
|
-
|
|
1121
|
-
|
|
1122
|
-
|
|
1123
|
-
]
|
|
1124
|
-
},
|
|
1125
|
-
agents: ["acme.clinic.agents.booking"]
|
|
1126
|
-
}
|
|
1127
|
-
},
|
|
1128
|
-
{
|
|
1129
|
-
key: "anonymous",
|
|
1130
|
-
platformPermissions: [],
|
|
1131
|
-
visibility: "declared",
|
|
1132
|
-
bindings: { agents: ["acme.clinic.agents.booking"] }
|
|
1133
|
-
}
|
|
1143
|
+
grantableBy: "holders", // default "admins"
|
|
1144
|
+
nodes: {
|
|
1145
|
+
candidates: { kind: "readManage" },
|
|
1146
|
+
compensation: { kind: "readManage" }
|
|
1147
|
+
},
|
|
1148
|
+
lifecycle: { deployMode: "upsert", readonly: true }
|
|
1149
|
+
},
|
|
1150
|
+
manifest: { fqn: "acme.hr", version: "1.0.0" }
|
|
1151
|
+
})
|
|
1152
|
+
|
|
1153
|
+
export const hrProfile = declareAccessProfile({
|
|
1154
|
+
definition: {
|
|
1155
|
+
audience: "user",
|
|
1156
|
+
axes: [companyAxis, countryAxis],
|
|
1157
|
+
capabilities: [
|
|
1158
|
+
allow(core.studio),
|
|
1159
|
+
allow(hr.candidates, "manage"),
|
|
1160
|
+
allow(hr.compensation, "read")
|
|
1134
1161
|
],
|
|
1135
|
-
|
|
1136
|
-
|
|
1137
|
-
|
|
1138
|
-
|
|
1139
|
-
|
|
1140
|
-
|
|
1141
|
-
|
|
1142
|
-
|
|
1162
|
+
lifecycle: { deployMode: "upsert", readonly: true }
|
|
1163
|
+
},
|
|
1164
|
+
manifest: { fqn: "acme.hr.profiles.hr", version: "1.0.0" },
|
|
1165
|
+
presentation: { displayName: "HR" }
|
|
1166
|
+
})
|
|
1167
|
+
```
|
|
1168
|
+
|
|
1169
|
+
- A node exists when it is declared, also when no profile grants it. A profile
|
|
1170
|
+
never declares a capability inline: `capabilities` takes `access.allow`
|
|
1171
|
+
entries only.
|
|
1172
|
+
- `grantableBy: "holders"` makes Grant Authority require that a non-admin
|
|
1173
|
+
grantor holds the node at the same or a higher mode.
|
|
1174
|
+
- `canGrant` is `"all"` (every profile) or a list of profile handles or FQNs.
|
|
1175
|
+
- `coreCapabilities` is the core catalog. `capabilityCatalogNodes(catalog)`
|
|
1176
|
+
lists the nodes of the core catalog or of a capability handle as catalog
|
|
1177
|
+
rows, parents first. `coreSectionRequirements` lists the authority that each
|
|
1178
|
+
core Dashboard section shows.
|
|
1179
|
+
- Access components need no `presentation`; the display name defaults to the
|
|
1180
|
+
FQN.
|
|
1181
|
+
|
|
1182
|
+
### Axes and grants
|
|
1183
|
+
|
|
1184
|
+
The slug of a Grant Axis is the last segment of its FQN
|
|
1185
|
+
(`accessGrantAxisSlug`); grants key their Axis Values by slug. A grant of a
|
|
1186
|
+
profile handle must set exactly the axes of the profile, and TypeScript checks
|
|
1187
|
+
the keys.
|
|
1188
|
+
|
|
1189
|
+
```ts
|
|
1190
|
+
export const marketingItaly = declareAccessProfileGrant({
|
|
1191
|
+
definition: {
|
|
1192
|
+
profile: marketingProfile,
|
|
1193
|
+
grantee: { group: marketingItalyGroup, coverage: "inherited" },
|
|
1194
|
+
axes: {
|
|
1195
|
+
company: knowledgeEntity({ sapCode: "SAP-1000" }),
|
|
1196
|
+
country: knowledgeEntity({ code: "IT" })
|
|
1197
|
+
},
|
|
1198
|
+
lifecycle: { deployMode: "init_only", readonly: false }
|
|
1199
|
+
},
|
|
1200
|
+
manifest: { fqn: "acme.org.grants.marketing-italy", version: "1.0.0" }
|
|
1201
|
+
})
|
|
1202
|
+
```
|
|
1203
|
+
|
|
1204
|
+
- Grantees: `{ user: { email } }`, `{ group, coverage }` with a Group handle or
|
|
1205
|
+
`{ fqn }` (for example `builtinGroups.organization`), `{ servicePrincipal }`,
|
|
1206
|
+
`{ applicationServer }` and `{ applicationVisitors }`.
|
|
1207
|
+
- `knowledgeEntity({ code: "FR" })` names one entity by one unique field; the
|
|
1208
|
+
wire form is `{ "knowledgeEntity": { "field": "code", "value": "FR" } }`.
|
|
1209
|
+
- The manifest FQN of a declared grant is its Access Grant FQN: dot-separated
|
|
1210
|
+
segments that match `^[a-z0-9]+(?:-[a-z0-9]+)*$`, at most 320 characters.
|
|
1211
|
+
|
|
1212
|
+
### Knowledge Data Policies and Conditions
|
|
1213
|
+
|
|
1214
|
+
```ts
|
|
1215
|
+
const { field, isMe, map, not, eq, or, requires, resource } = access
|
|
1216
|
+
|
|
1217
|
+
export const visibleCandidate = declareAccessKnowledgeDataCondition({
|
|
1218
|
+
definition: {
|
|
1219
|
+
target: candidateSchema,
|
|
1220
|
+
where: or(not(eq(resource("restricted"), true)), isMe("recruiter")),
|
|
1221
|
+
tests: [{ name: "field missing", record: {}, expected: true }]
|
|
1222
|
+
},
|
|
1223
|
+
manifest: { fqn: "acme.hr.conditions.visible-candidate", version: "1.0.0" }
|
|
1224
|
+
})
|
|
1225
|
+
|
|
1226
|
+
export const candidatesRead = declareAccessKnowledgeDataPolicy({
|
|
1227
|
+
definition: {
|
|
1228
|
+
target: candidateSchema,
|
|
1229
|
+
operation: "read",
|
|
1230
|
+
capability: requires(hr.candidates, "read"),
|
|
1231
|
+
axes: [
|
|
1232
|
+
map(companyAxis, field("company")),
|
|
1233
|
+
map(countryAxis, field("country"))
|
|
1143
1234
|
],
|
|
1144
|
-
|
|
1145
|
-
|
|
1146
|
-
|
|
1147
|
-
|
|
1148
|
-
|
|
1149
|
-
|
|
1150
|
-
|
|
1151
|
-
|
|
1235
|
+
where: visibleCandidate,
|
|
1236
|
+
readableFields: { except: ["salary"] }
|
|
1237
|
+
},
|
|
1238
|
+
manifest: { fqn: "acme.hr.policies.candidates-read", version: "1.0.0" }
|
|
1239
|
+
})
|
|
1240
|
+
```
|
|
1241
|
+
|
|
1242
|
+
- Axis rules: `map(axis, field(key) | self() | relation(key, field))`,
|
|
1243
|
+
`byCondition(axis)` (the `where` reads `grantAxis(axis)`) and
|
|
1244
|
+
`unscoped(axis)`; `otherAxes: "unscoped"` ignores every unbound axis.
|
|
1245
|
+
- `readableFields` (read policies) and `writableFields` (write policies) take
|
|
1246
|
+
an allow list (`["status"]`) or a deny list (`{ except: ["salary"] }`).
|
|
1247
|
+
- `purpose: "administration"` fills the administration slot; the default is
|
|
1248
|
+
`access`.
|
|
1249
|
+
- Conditions: `and`, `or`, `not`, `eq`, `neq`, `lt`, `lte`, `gt`, `gte`, `isIn`,
|
|
1250
|
+
`overlaps`, `exists`, `isNull`, `contains`, `startsWith`; references
|
|
1251
|
+
`resource(key)`, `subject(path)` and `grantAxis(axis)`; `via(resource(key),
|
|
1252
|
+
condition)`; user-field operators `isMe`, `includesMe`, `inGroup` and
|
|
1253
|
+
`inMyGroups` with `coverage` `direct` or `inherited`. A declared condition
|
|
1254
|
+
handle works wherever a condition does.
|
|
1255
|
+
|
|
1256
|
+
These declarations fail the package build with a `TypeError`, and manifest
|
|
1257
|
+
readers refuse the same serialized forms:
|
|
1258
|
+
|
|
1259
|
+
- a capability entry that is not an `access.allow` entry, or an unknown
|
|
1260
|
+
definition field, such as `nodes` on a profile;
|
|
1261
|
+
- a mode on a Switch, or no mode on a Read/Manage node;
|
|
1262
|
+
- a field key that the target schema handle does not declare, in
|
|
1263
|
+
`readableFields`, `writableFields`, `field(key)` or `relation(key, ...)`;
|
|
1264
|
+
- a field list that does not match the operation, or two rules for one axis;
|
|
1265
|
+
- `grantAxis` under `not`, or a `byCondition` axis that no `grantAxis` operand
|
|
1266
|
+
of the `where` reads, at any depth and through `via` hops. A `where` that
|
|
1267
|
+
holds a declared condition passes here; the host checks it after it inlines
|
|
1268
|
+
that condition;
|
|
1269
|
+
- grant axes that differ from the axes of the profile handle, or an Access
|
|
1270
|
+
Grant FQN outside its grammar.
|
|
1271
|
+
|
|
1272
|
+
### Testing access with `accessTest`
|
|
1273
|
+
|
|
1274
|
+
`accessTest` from `@collective-intelligence/extensions-sdk-backend` evaluates
|
|
1275
|
+
declared packages in memory, per grant, as the engine does: catalog rules,
|
|
1276
|
+
axis hierarchies, policy slots with the given core policies, Field Read Masks,
|
|
1277
|
+
updates, Max Privileges and condition test cases.
|
|
1278
|
+
|
|
1279
|
+
```ts
|
|
1280
|
+
import { access } from "@collective-intelligence/extensions-sdk"
|
|
1281
|
+
import { accessTest } from "@collective-intelligence/extensions-sdk-backend"
|
|
1282
|
+
|
|
1283
|
+
const check = accessTest([orgPackage, hrPackage], { corePolicies, entities })
|
|
1284
|
+
const ada = check.as({
|
|
1285
|
+
user: "u-ada",
|
|
1286
|
+
grants: [{ profile: hrProfile, axes: { company: "x", country: "fr" } }]
|
|
1287
|
+
})
|
|
1288
|
+
ada.canRead(candidateSchema, record) // read policies
|
|
1289
|
+
ada.read(candidateSchema, record) // the record without masked fields
|
|
1290
|
+
ada.canUpdate(candidateSchema, stored, proposed) // one grant, one policy
|
|
1291
|
+
ada.holds(access.requires(hr.candidates, "manage"))
|
|
1292
|
+
check.conditionTests() // every declared condition test case
|
|
1293
|
+
```
|
|
1294
|
+
|
|
1295
|
+
## External applications
|
|
1296
|
+
|
|
1297
|
+
`declareExternalApplication` declares the OAuth client of an application and
|
|
1298
|
+
its capability tree: `allowedOrigins`, `applicationType`, `audience`,
|
|
1299
|
+
`postLogoutRedirectUris` and `redirectUris` are required; `capabilities`,
|
|
1300
|
+
`primaryRedirectUri`, `setupInstructions` and `applicationConsent` are
|
|
1301
|
+
optional. `applicationConsent` overrides the Application Consent rule of the
|
|
1302
|
+
Organization for this application: `inherit` (the default) follows the
|
|
1303
|
+
Organization, `ask` always prompts, `skip` never prompts.
|
|
1304
|
+
|
|
1305
|
+
```ts
|
|
1306
|
+
export const clinic = declareExternalApplication({
|
|
1307
|
+
definition: {
|
|
1308
|
+
allowedOrigins: ["https://clinic.example"],
|
|
1309
|
+
applicationType: "confidential",
|
|
1310
|
+
audience: "https://clinic.example",
|
|
1311
|
+
// Below the app gate; a node without `kind` is a Switch.
|
|
1312
|
+
capabilities: { charts: {}, records: { kind: "readManage" } },
|
|
1313
|
+
lifecycle: { deployMode: "upsert", readonly: true },
|
|
1314
|
+
postLogoutRedirectUris: ["https://clinic.example/signed-out"],
|
|
1315
|
+
redirectUris: ["https://clinic.example/api/auth/callback"]
|
|
1152
1316
|
},
|
|
1153
1317
|
manifest: { fqn: "acme.clinic.application", version: "1.0.0" },
|
|
1154
1318
|
presentation: { displayName: "Clinic" }
|
|
1155
1319
|
})
|
|
1320
|
+
|
|
1321
|
+
export const patient = declareAccessProfile({
|
|
1322
|
+
definition: {
|
|
1323
|
+
audience: "user",
|
|
1324
|
+
capabilities: [
|
|
1325
|
+
access.allow(access.accessGate(clinic)), // enter the app
|
|
1326
|
+
access.allow(access.accessGate(clinic).records, "read")
|
|
1327
|
+
]
|
|
1328
|
+
},
|
|
1329
|
+
manifest: { fqn: "acme.clinic.profiles.patient", version: "1.0.0" }
|
|
1330
|
+
})
|
|
1156
1331
|
```
|
|
1157
1332
|
|
|
1158
|
-
-
|
|
1159
|
-
|
|
1160
|
-
|
|
1161
|
-
|
|
1162
|
-
(
|
|
1163
|
-
|
|
1164
|
-
|
|
1165
|
-
|
|
1166
|
-
|
|
1167
|
-
`
|
|
1168
|
-
|
|
1169
|
-
|
|
1170
|
-
|
|
1171
|
-
|
|
1172
|
-
|
|
1173
|
-
|
|
1174
|
-
|
|
1175
|
-
|
|
1176
|
-
Roles of the application. A role keyed `anonymous` is a User Role with
|
|
1177
|
-
Declared Visibility.
|
|
1178
|
-
- A Platform Permission is a `resource:action` string. A resource may be
|
|
1179
|
-
namespaced, as in `ai:catalog:read`. Each colon-separated segment starts with
|
|
1180
|
-
a lowercase letter and contains only lowercase letters, digits or underscores;
|
|
1181
|
-
empty segments are invalid. The SDK checks syntax only: `a:b:c` is valid
|
|
1182
|
-
syntax, but the backend rejects permissions outside its known catalog.
|
|
1183
|
-
App Permissions are strings that the application defines.
|
|
1184
|
-
- `parent` is the key of another declared role of the same kind. A parent role
|
|
1185
|
-
holds every Platform Permission and App Permission of each of its children,
|
|
1186
|
-
and a role is not its own ancestor.
|
|
1187
|
-
- `assignRoles` lists keys of User Roles of the same application that a holder
|
|
1188
|
-
of the role can assign. `users.create` lets a holder create users.
|
|
1189
|
-
- `replaces` is the key of a role that an earlier release declared and this
|
|
1190
|
-
release removed. It cannot be a key of this release, and two roles cannot
|
|
1191
|
-
replace the same key.
|
|
1192
|
-
- The helper infers the declared keys, so TypeScript rejects a `parent`, an
|
|
1193
|
-
`assignRoles` entry, a `defaultServerRole` or a Group Role Binding `role`
|
|
1194
|
-
that is not a declared key of the right kind; the manifest stores plain
|
|
1195
|
-
strings.
|
|
1196
|
-
- `declareExternalApplication` throws a `TypeError` for each violation and
|
|
1197
|
-
manifest readers reject the same declarations; both use
|
|
1198
|
-
`externalApplicationViolation`. A violation message starts with the field
|
|
1199
|
-
path, for example `userRoles[1].parent:`.
|
|
1200
|
-
|
|
1201
|
-
## Group Role Bindings
|
|
1202
|
-
|
|
1203
|
-
`groupBindings` lists Group Role Bindings: the members of one Organization
|
|
1204
|
-
Group hold one User Role of the application. A package declares bindings only
|
|
1205
|
-
on its own external application.
|
|
1206
|
-
|
|
1207
|
-
- `group` is a `DeclarationReference<"organizationGroup">`: the handle that
|
|
1208
|
-
`declareOrganizationGroup` returns for a root Group of the same package, or
|
|
1209
|
-
the FQN string of any Group. Use the FQN string for a subgroup and for a
|
|
1210
|
-
Group that another package declares. TypeScript rejects a handle of another
|
|
1211
|
-
primitive kind. The manifest stores the FQN string in an
|
|
1212
|
-
`ExternalApplicationGroupBinding` item.
|
|
1213
|
-
- The SDK does not check that the Group exists; the host does.
|
|
1214
|
-
- `role` is the key of a User Role of the same declaration.
|
|
1215
|
-
- `coverage` is `"inherited"` (the default when omitted: members of subgroups
|
|
1216
|
-
also hold the role) or `"direct"` (members of the Group only).
|
|
1217
|
-
- `lifecycle` is a required `LifecycleOptions` of the binding, separate from
|
|
1218
|
-
the lifecycle of the application. An item with no `deployMode` or no
|
|
1219
|
-
`readonly` is rejected.
|
|
1220
|
-
- Two items cannot name the same Group and the same role.
|
|
1333
|
+
- The root of the tree is the app gate, a Switch whose code is the
|
|
1334
|
+
application FQN. A member, a guest or a tenant user enters the app only
|
|
1335
|
+
with a grant whose profile holds the gate or a node below it.
|
|
1336
|
+
`access.accessGate(app)` returns the gate handle and the handles of the
|
|
1337
|
+
declared capabilities; `access.accessGate("other.package.app")` names the
|
|
1338
|
+
gate of an app that another package declares.
|
|
1339
|
+
- The declaration holds no access model and no OAuth scopes. Access
|
|
1340
|
+
declarations give the application its access: a `server` profile granted
|
|
1341
|
+
to `{ applicationServer: clinic }` for the server's credentials, an
|
|
1342
|
+
`anonymous` profile granted to `{ applicationVisitors: clinic }` for
|
|
1343
|
+
signed-out visitors, `user` profiles granted to members, Groups or guests,
|
|
1344
|
+
and `declareAccessMaxPrivileges` with
|
|
1345
|
+
`appliesTo: { applicationTokens: clinic }`, which cuts every user token of
|
|
1346
|
+
the app. Without Max Privileges the application's user tokens read nothing.
|
|
1347
|
+
- `primaryRedirectUri` is one of `redirectUris`. `declareExternalApplication`
|
|
1348
|
+
throws a `TypeError` for a primary redirect URI outside `redirectUris`, an
|
|
1349
|
+
unknown consent value or a capability key outside the node grammar, and
|
|
1350
|
+
manifest readers reject the same declarations.
|
|
1221
1351
|
|
|
1222
1352
|
## Package Variables
|
|
1223
1353
|
|
|
@@ -1293,9 +1423,7 @@ export default declarePackage({
|
|
|
1293
1423
|
- A handle never fits `fqn`, `version`, `kind`, a reference to another
|
|
1294
1424
|
component by FQN (`templateFqn`, `schemaFqn`, ...), `lifecycle` or a schema
|
|
1295
1425
|
projection (`VaryingExcludedKey`); manifest readers reject a marker there
|
|
1296
|
-
with its path. The
|
|
1297
|
-
`serverRoles`, `defaultServerRole`, `groupBindings`) and the `provider` of
|
|
1298
|
-
an SSO entry keep their shape.
|
|
1426
|
+
with its path. The `provider` of an SSO entry keeps its shape.
|
|
1299
1427
|
- Manifest readers admit the marker in every other definition value and keep
|
|
1300
1428
|
it; cross-field rules that need the value run after substitution. The host
|
|
1301
1429
|
owns substitution; `isVariableReference(value)` recognizes a marker and
|
|
@@ -1364,8 +1492,9 @@ const source = definePackageSchema({
|
|
|
1364
1492
|
The SDK freezes its projections and source envelope but never mutates
|
|
1365
1493
|
or freezes the provider-native object. Declaration materialization normalizes
|
|
1366
1494
|
even directly implemented structural sources, so mutable projections, older
|
|
1367
|
-
dialects, and unresolved local references cannot leak into manifests.
|
|
1368
|
-
|
|
1495
|
+
dialects, and unresolved local references cannot leak into manifests. The
|
|
1496
|
+
Effect integration belongs in `@collective-intelligence/extensions-sdk-backend/effect`;
|
|
1497
|
+
the SDK family publishes no Zod adapter.
|
|
1369
1498
|
|
|
1370
1499
|
## Manifests and consumer profiles
|
|
1371
1500
|
|
|
@@ -1509,7 +1638,7 @@ const tools = declareRemoteToolCollection({
|
|
|
1509
1638
|
definition: {
|
|
1510
1639
|
gatewayRef: "com.example.nest.gateways.main",
|
|
1511
1640
|
operationReferences: ["com.example.nest/greetings/greet@1.0.0"],
|
|
1512
|
-
|
|
1641
|
+
audience: { organization: true }
|
|
1513
1642
|
}
|
|
1514
1643
|
})
|
|
1515
1644
|
// Include tools and the referenced Gateway declaration in the package.
|
|
@@ -1523,13 +1652,43 @@ beginning with a letter or digit. References use
|
|
|
1523
1652
|
strings of at most 128 characters. Every reference must match the declared
|
|
1524
1653
|
Gateway, and the selection must be nonempty and unique.
|
|
1525
1654
|
|
|
1526
|
-
The declaration shares `category` and `
|
|
1655
|
+
The declaration shares `category` and `audience` with ordinary Tool
|
|
1527
1656
|
collections and supports normal identity and presentation metadata. Its closed
|
|
1528
1657
|
metadata contains no executable implementation, schema sidecar, authorization
|
|
1529
1658
|
override or credential. These constraints apply during authoring and serialized
|
|
1530
1659
|
manifest admission. The Host validates the package-owned Gateway Connection and approved
|
|
1531
1660
|
operations at installation; this declaration grants no execution authority.
|
|
1532
1661
|
|
|
1662
|
+
### Tool and Tool collection audience
|
|
1663
|
+
|
|
1664
|
+
`declareTool`, `declareToolCollection` and `declareRemoteToolCollection` take
|
|
1665
|
+
an optional `audience` in `definition`: the thing's own Resource Audience, in
|
|
1666
|
+
the shared `AccessAudience` shape of the [Agent audience](#agent-audience).
|
|
1667
|
+
Entries only allow; an omitted `audience` offers the thing to nobody.
|
|
1668
|
+
|
|
1669
|
+
- Each thing is checked against its own entries. A collection's audience never
|
|
1670
|
+
offers the tools in it; every tool declares its own.
|
|
1671
|
+
- Tools and collections carry no component lifecycle: the declared audience is
|
|
1672
|
+
written once, by the deploy that creates the thing. Later administrator
|
|
1673
|
+
edits in the Dashboard stay.
|
|
1674
|
+
- A tool's `audience` takes effect when the package auto-instantiates the
|
|
1675
|
+
tool. A tool that an administrator adds in the Dashboard starts with the
|
|
1676
|
+
Organization.
|
|
1677
|
+
|
|
1678
|
+
```ts
|
|
1679
|
+
declareToolCollection({
|
|
1680
|
+
manifest: {
|
|
1681
|
+
fqn: "example.marketplace.collections.listings",
|
|
1682
|
+
version: "1.0.0"
|
|
1683
|
+
},
|
|
1684
|
+
presentation: { displayName: "Listings" },
|
|
1685
|
+
definition: {
|
|
1686
|
+
audience: { groups: [{ fqn: "example.marketplace.groups.staff" }] },
|
|
1687
|
+
toolFqns: ["example.marketplace.tools.search"]
|
|
1688
|
+
}
|
|
1689
|
+
})
|
|
1690
|
+
```
|
|
1691
|
+
|
|
1533
1692
|
### Portable workflow pauses
|
|
1534
1693
|
|
|
1535
1694
|
`PackageWorkflowNodeResult<Output>` admits a `directive: "pause"` result with
|
|
@@ -2141,9 +2300,10 @@ The [Nest declaration example](../../../demo/external-app-nest/apps/extensions/s
|
|
|
2141
2300
|
|
|
2142
2301
|
`declareDocumentCollection` declares one Declared Connected collection: a
|
|
2143
2302
|
Connected collection whose identity is the declaration FQN. One
|
|
2144
|
-
`documentCollection` manifest holds the collection settings, its Connection
|
|
2145
|
-
its Remote roots
|
|
2146
|
-
|
|
2303
|
+
`documentCollection` manifest holds the collection settings, its Connection and
|
|
2304
|
+
its Remote roots; no option creates a Local collection. Document Data Policies
|
|
2305
|
+
(`declareAccessDocumentDataPolicy`) decide who reads its current Versions
|
|
2306
|
+
(`read`), its older Versions (`history`) and who writes it (`write`).
|
|
2147
2307
|
|
|
2148
2308
|
```ts
|
|
2149
2309
|
import {
|
|
@@ -2165,24 +2325,7 @@ export const hrPolicies = declareDocumentCollection({
|
|
|
2165
2325
|
connection: { setupKey: "microsoft365" },
|
|
2166
2326
|
title: "HR Policies",
|
|
2167
2327
|
indexContent: true,
|
|
2168
|
-
remoteRoots: [{ drive: vars.hrDrive, folders: ["Policies"] }]
|
|
2169
|
-
rules: [
|
|
2170
|
-
{
|
|
2171
|
-
grantee: { kind: "group", fqn: "acme.hr" },
|
|
2172
|
-
target: { kind: "collection" },
|
|
2173
|
-
permission: "read",
|
|
2174
|
-
effect: "allow"
|
|
2175
|
-
},
|
|
2176
|
-
{
|
|
2177
|
-
grantee: { kind: "organization" },
|
|
2178
|
-
target: {
|
|
2179
|
-
kind: "folder",
|
|
2180
|
-
folder: { drive: vars.hrDrive, folders: ["Policies", "Board"] }
|
|
2181
|
-
},
|
|
2182
|
-
permission: "read",
|
|
2183
|
-
effect: "deny"
|
|
2184
|
-
}
|
|
2185
|
-
]
|
|
2328
|
+
remoteRoots: [{ drive: vars.hrDrive, folders: ["Policies"] }]
|
|
2186
2329
|
}
|
|
2187
2330
|
})
|
|
2188
2331
|
```
|
|
@@ -2198,20 +2341,11 @@ export const hrPolicies = declareDocumentCollection({
|
|
|
2198
2341
|
collection description. `indexContent` and `indexOverview` default to
|
|
2199
2342
|
`false`; `overviewInputMaxChars` and `richEnrichment` follow "File overview
|
|
2200
2343
|
settings". `syncEnabled` defaults to `true`.
|
|
2201
|
-
- A Remote root
|
|
2344
|
+
- A Remote root is a path `{ drive, folders }` or a
|
|
2202
2345
|
`{ remoteId }` for a path that is ambiguous. On Microsoft 365, `drive` is the
|
|
2203
2346
|
drive title `<siteName> / <libraryName>` that the browse route shows; an
|
|
2204
2347
|
empty `folders` names the drive. Each value may be a Package Variable, so
|
|
2205
2348
|
one release serves environments with different folders.
|
|
2206
|
-
- A Declared rule needs a `grantee`, a `target`, a `permission` (`read`,
|
|
2207
|
-
`update`, `manage` or `view_history`) and an `effect` (`allow` or `deny`),
|
|
2208
|
-
with the meaning of the same rule made by an administrator. The grantee is a
|
|
2209
|
-
group or a Service principal by FQN, or the whole Organization; a user ID or
|
|
2210
|
-
an External App role is not a grantee. The target is the collection or a
|
|
2211
|
-
folder: a folder that a Remote root names is a Remote root target, any other
|
|
2212
|
-
folder a subfolder below a Remote root.
|
|
2213
|
-
- An `allow` of `view_history` needs an `allow` of `read` for the same grantee
|
|
2214
|
-
and target; the declaration and the manifest reader refuse it otherwise.
|
|
2215
2349
|
|
|
2216
2350
|
## Concrete connector configuration
|
|
2217
2351
|
|
|
@@ -2224,8 +2358,8 @@ release dependencies at installation. Every bundle requires
|
|
|
2224
2358
|
`init_only` creates absent configuration and preserves existing content; `upsert`
|
|
2225
2359
|
reconciles owned content through baseline/live merge. `readonly` governs manual
|
|
2226
2360
|
configuration edits across the bundle. Child bindings, pipelines, schedules and
|
|
2227
|
-
|
|
2228
|
-
separate.
|
|
2361
|
+
the Dataset `dataPolicy` share that lifecycle; runtime data, cursors and
|
|
2362
|
+
authorized execution are separate.
|
|
2229
2363
|
|
|
2230
2364
|
An entity binding of a Knowledge gateway connector may declare
|
|
2231
2365
|
`pushEntityMatch: "unique_fields"`. A pushed record then joins the live entity
|
|
@@ -2286,26 +2420,6 @@ const customers = declareKnowledgeConnectorInstance({
|
|
|
2286
2420
|
}
|
|
2287
2421
|
]
|
|
2288
2422
|
}
|
|
2289
|
-
],
|
|
2290
|
-
dataPolicies: [
|
|
2291
|
-
{
|
|
2292
|
-
fqn: "com.acme.sales.policies.customer_read",
|
|
2293
|
-
targetKind: "entity_schema",
|
|
2294
|
-
targetFqn: "com.acme.sales.customer",
|
|
2295
|
-
policyType: "filter",
|
|
2296
|
-
effect: "allow",
|
|
2297
|
-
policyBody: {
|
|
2298
|
-
subjectMatch: {
|
|
2299
|
-
op: "eq",
|
|
2300
|
-
left: { kind: "subject", path: ["user", "id"] },
|
|
2301
|
-
right: {
|
|
2302
|
-
kind: "literal",
|
|
2303
|
-
value: "7f824c46-54f3-41aa-b0b5-3951fabf952a"
|
|
2304
|
-
}
|
|
2305
|
-
},
|
|
2306
|
-
rule: { op: "const", value: true }
|
|
2307
|
-
}
|
|
2308
|
-
}
|
|
2309
2423
|
]
|
|
2310
2424
|
}
|
|
2311
2425
|
})
|
|
@@ -2360,162 +2474,12 @@ export default declarePackage({
|
|
|
2360
2474
|
})
|
|
2361
2475
|
```
|
|
2362
2476
|
|
|
2363
|
-
Use your actual exact dependency release, executable/schema FQNs, source
|
|
2364
|
-
and
|
|
2365
|
-
|
|
2366
|
-
|
|
2367
|
-
the caller as CI built it: `user.id`, `groupIds`, `roles` and `access`.
|
|
2368
|
-
`roles` lists the keys of the user's effective User Roles (`userRoles`) on the
|
|
2369
|
-
External App that makes the call, for example `["sales_manager"]`; it is empty
|
|
2370
|
-
for a call outside an External App. Match a role with `in` on the subject path
|
|
2371
|
-
`["roles"]`. CI sets `access` to `"read"` for get, list, search, facets,
|
|
2372
|
-
autocomplete and retrieval, and to `"write"` for create, update and delete; a
|
|
2373
|
-
policy that does not test it applies to both. For
|
|
2374
|
-
example, this `deny` `filter` policy lets users with the `member` User Role read
|
|
2375
|
-
every company but write only the ones whose accounts field lists them:
|
|
2376
|
-
|
|
2377
|
-
```ts
|
|
2378
|
-
const memberCompanyWrites = declareKnowledgePolicy({
|
|
2379
|
-
manifest: {
|
|
2380
|
-
fqn: "com.acme.members.policies.member_company_writes",
|
|
2381
|
-
version: "1.0.0"
|
|
2382
|
-
},
|
|
2383
|
-
presentation: { displayName: "Members write only their linked companies" },
|
|
2384
|
-
definition: {
|
|
2385
|
-
effect: "deny",
|
|
2386
|
-
policyType: "filter",
|
|
2387
|
-
targetKind: "entity_schema",
|
|
2388
|
-
targetFqn: "com.acme.members.company",
|
|
2389
|
-
policyBody: {
|
|
2390
|
-
subjectMatch: {
|
|
2391
|
-
op: "and",
|
|
2392
|
-
args: [
|
|
2393
|
-
{
|
|
2394
|
-
op: "in",
|
|
2395
|
-
value: { kind: "literal", value: "member" },
|
|
2396
|
-
set: { kind: "subject", path: ["roles"] }
|
|
2397
|
-
},
|
|
2398
|
-
{
|
|
2399
|
-
op: "eq",
|
|
2400
|
-
left: { kind: "subject", path: ["access"] },
|
|
2401
|
-
right: { kind: "literal", value: "write" }
|
|
2402
|
-
}
|
|
2403
|
-
]
|
|
2404
|
-
},
|
|
2405
|
-
rule: {
|
|
2406
|
-
op: "not",
|
|
2407
|
-
arg: {
|
|
2408
|
-
op: "in",
|
|
2409
|
-
value: { kind: "subject", path: ["user", "id"] },
|
|
2410
|
-
set: { kind: "resource", path: ["data", "accounts"] }
|
|
2411
|
-
}
|
|
2412
|
-
}
|
|
2413
|
-
}
|
|
2414
|
-
}
|
|
2415
|
-
})
|
|
2416
|
-
```
|
|
2417
|
-
|
|
2418
|
-
A relation scope follows a relation field of the record:
|
|
2419
|
-
`{ op: "relation_field", field, inner }` holds when `inner` holds for some live
|
|
2420
|
-
entity that the record's relation field `field` names, and `resource` refs in
|
|
2421
|
-
`inner` read that related entity. CI applies it to every read and write of the
|
|
2422
|
-
record: lists, gets, searches, facets, realtime events, deletes, and creates and
|
|
2423
|
-
updates, which it checks on the related entity the write names. Hops nest. For
|
|
2424
|
-
example, users read and write a task only when its `project` lists them in the
|
|
2425
|
-
project's `members` accounts field, or when they have the `manager` User Role:
|
|
2426
|
-
|
|
2427
|
-
```ts
|
|
2428
|
-
const projectMembers = {
|
|
2429
|
-
op: "in",
|
|
2430
|
-
value: { kind: "subject", path: ["user", "id"] },
|
|
2431
|
-
set: { kind: "resource", path: ["data", "members"] }
|
|
2432
|
-
} as const
|
|
2433
|
-
|
|
2434
|
-
const projectTasks = declareKnowledgePolicy({
|
|
2435
|
-
manifest: { fqn: "com.acme.work.policies.project_tasks", version: "1.0.0" },
|
|
2436
|
-
presentation: { displayName: "Project members work on its tasks" },
|
|
2437
|
-
definition: {
|
|
2438
|
-
effect: "allow",
|
|
2439
|
-
policyType: "filter",
|
|
2440
|
-
targetKind: "entity_schema",
|
|
2441
|
-
targetFqn: "com.acme.work.task",
|
|
2442
|
-
policyBody: {
|
|
2443
|
-
subjectMatch: { op: "const", value: true },
|
|
2444
|
-
rule: {
|
|
2445
|
-
op: "or",
|
|
2446
|
-
args: [
|
|
2447
|
-
{
|
|
2448
|
-
op: "in",
|
|
2449
|
-
value: { kind: "literal", value: "manager" },
|
|
2450
|
-
set: { kind: "subject", path: ["roles"] }
|
|
2451
|
-
},
|
|
2452
|
-
{ op: "relation_field", field: "project", inner: projectMembers }
|
|
2453
|
-
]
|
|
2454
|
-
}
|
|
2455
|
-
}
|
|
2456
|
-
}
|
|
2457
|
-
})
|
|
2458
|
-
```
|
|
2459
|
-
|
|
2460
|
-
A comment on a task follows its `task`, then the task's `project`, with the
|
|
2461
|
-
rule `{ op: "relation_field", field: "task", inner: { op: "relation_field",
|
|
2462
|
-
field: "project", inner: projectMembers } }`. A hop to a deleted entity names
|
|
2463
|
-
nothing. Hops belong in `rule`, never in `subjectMatch`, and only on a policy
|
|
2464
|
-
that targets one entity schema; a hop holds no `direction`. CI refuses at
|
|
2465
|
-
deploy a `field` that is not a forward relation field of the schema the hop
|
|
2466
|
-
starts from. The Record Relation forms are retired: manifest parsing refuses
|
|
2467
|
-
`relation_exists`, the `{ op: "relation_field", relationSchemaId, direction,
|
|
2468
|
-
inner }` form and the policy kinds `relation_schema` and `relation_domain` with
|
|
2469
|
-
an error that names the retired form or kind.
|
|
2470
|
-
|
|
2471
|
-
A field write rule limits what an `allow` `filter` policy on an entity schema
|
|
2472
|
-
or domain admits to updates of the listed `data` paths. `writableFields` is a
|
|
2473
|
-
non-empty list of `["data", key, ...]` paths; a change at or under a path is
|
|
2474
|
-
within it. CI compares the stored record with the record the update would
|
|
2475
|
-
store: a value it resends unchanged is no change, but a key a `"replace"`
|
|
2476
|
-
update omits is removed and so changed. The update is admitted only when one of the `allow` policies that admit
|
|
2477
|
-
the record has no `writableFields` or lists every changed path; a `deny`
|
|
2478
|
-
policy still refuses it. A File or relation field the update writes counts as
|
|
2479
|
-
changed, and a change of the record's name, description or external binding is
|
|
2480
|
-
outside every `writableFields`. A policy with `writableFields` admits no
|
|
2481
|
-
create, delete or relation write and does not change reads. For example, users
|
|
2482
|
-
with the `operator` User Role may update only the status:
|
|
2483
|
-
|
|
2484
|
-
```ts
|
|
2485
|
-
const operatorStatusUpdates = declareKnowledgePolicy({
|
|
2486
|
-
manifest: {
|
|
2487
|
-
fqn: "com.acme.actions.policies.operator_status_updates",
|
|
2488
|
-
version: "1.0.0"
|
|
2489
|
-
},
|
|
2490
|
-
presentation: { displayName: "Operators update only the status" },
|
|
2491
|
-
definition: {
|
|
2492
|
-
effect: "allow",
|
|
2493
|
-
policyType: "filter",
|
|
2494
|
-
targetKind: "entity_schema",
|
|
2495
|
-
targetFqn: "com.acme.actions.action",
|
|
2496
|
-
policyBody: {
|
|
2497
|
-
subjectMatch: {
|
|
2498
|
-
op: "and",
|
|
2499
|
-
args: [
|
|
2500
|
-
{
|
|
2501
|
-
op: "in",
|
|
2502
|
-
value: { kind: "literal", value: "operator" },
|
|
2503
|
-
set: { kind: "subject", path: ["roles"] }
|
|
2504
|
-
},
|
|
2505
|
-
{
|
|
2506
|
-
op: "eq",
|
|
2507
|
-
left: { kind: "subject", path: ["access"] },
|
|
2508
|
-
right: { kind: "literal", value: "write" }
|
|
2509
|
-
}
|
|
2510
|
-
]
|
|
2511
|
-
},
|
|
2512
|
-
writableFields: [["data", "status"]]
|
|
2513
|
-
}
|
|
2514
|
-
}
|
|
2515
|
-
})
|
|
2516
|
-
```
|
|
2477
|
+
Use your actual exact dependency release, executable/schema FQNs, source
|
|
2478
|
+
location and Dataset principals. A Knowledge connector instance declares no
|
|
2479
|
+
policy: the package's Knowledge Data Policies decide who reads and writes the
|
|
2480
|
+
records it imports (see "Knowledge Data Policies and Conditions").
|
|
2517
2481
|
|
|
2518
|
-
|
|
2482
|
+
Dataset grants use existing
|
|
2519
2483
|
user/service principals and native operations, fields, `sensitiveFields`, row
|
|
2520
2484
|
filters and budgets.
|
|
2521
2485
|
|