@collective-intelligence/extensions-sdk 0.2.2 → 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.
Files changed (34) hide show
  1. package/README.md +329 -366
  2. package/dist/access/application-gate.d.ts +36 -0
  3. package/dist/access/audience.d.ts +43 -0
  4. package/dist/access/capabilities.d.ts +105 -0
  5. package/dist/access/conditions.d.ts +136 -0
  6. package/dist/access/core-catalog.d.ts +221 -0
  7. package/dist/access/declarations.d.ts +169 -0
  8. package/dist/access/document-policy.d.ts +31 -0
  9. package/dist/access/index.d.ts +62 -0
  10. package/dist/access/knowledge-policy.d.ts +87 -0
  11. package/dist/access/manifest.d.ts +161 -0
  12. package/dist/access/readers.d.ts +114 -0
  13. package/dist/access/requirement.d.ts +61 -0
  14. package/dist/components/agents.d.ts +12 -30
  15. package/dist/components/authoring-core.d.ts +3 -1
  16. package/dist/components/base.d.ts +1 -1
  17. package/dist/components/connector-instances.d.ts +0 -3
  18. package/dist/components/declaration.d.ts +3 -2
  19. package/dist/components/document-collections.d.ts +3 -32
  20. package/dist/components/external-application.d.ts +18 -90
  21. package/dist/components/knowledge.d.ts +1 -164
  22. package/dist/components/metadata-authoring.d.ts +24 -21
  23. package/dist/components/organization-settings.d.ts +7 -2
  24. package/dist/components/service-principal.d.ts +9 -4
  25. package/dist/components/studio.d.ts +22 -44
  26. package/dist/components/tools.d.ts +15 -8
  27. package/dist/components/workflows.d.ts +7 -0
  28. package/dist/index.d.ts +13 -11
  29. package/dist/index.js +2 -2
  30. package/dist/package/primitive-readers.d.ts +111 -24
  31. package/dist/package/readers.d.ts +2 -0
  32. package/dist/package/variables.d.ts +1 -2
  33. package/package.json +2 -2
  34. 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`, and
428
- `scopes`. `redirectUris` lists every accepted callback. An optional
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.applications` must name applications of the
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 code maximum of who may converse with the Agent, per caller
762
- class. An omitted field admits nobody of that class; an omitted `audience`
763
- admits nobody.
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 | Values | Admits |
766
- | -------------------- | ------------------------------- | ---------------------------------------------------------------------- |
767
- | `members` | `"all"`, `"selected"`, `"none"` | Organization members: every member, or the users administrators select |
768
- | `organizationGroups` | `"selected"`, `"none"` | Organization Groups that administrators select |
769
- | `applications` | application references | Applications that invoke the Agent as a service or bring visitors |
770
- | `anonymous` | `true` | Anonymous visitors that a listed application brings |
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: true,
778
+ anonymous: [storefront],
778
779
  applications: [storefront],
779
- members: "selected",
780
- organizationGroups: "selected"
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
- - Administrators select concrete users and Organization Groups inside this
789
- maximum. They can only narrow it; they cannot widen it.
790
- - Organization administrators get no bypass for a declared Agent. An
791
- administrator outside the audience must add themselves to converse.
792
- - `anonymous: true` needs at least one application in `applications`:
793
- visitors always arrive through an application. An anonymous visitor runs
794
- only the Agent's own bindings, never the application's service authority.
795
- - `declareAgent` throws a `TypeError` for `anonymous: true` without an
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 with one Organization Role
888
- and memberships in Groups declared by the same package. `version` is required
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
- `organizationRole` is `organization_admin`, `organization_operator`, or
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. Deployment
920
- confirmation and runtime authorization belong to the Host.
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
- defaultRole: "organization_member"
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` and `defaultRole` (`organization_admin`,
1046
- `organization_operator`, or `organization_member`) are required. Retired roles
1047
- such as `organization_user` and Tenant roles are rejected by manifest admission. `applicationConsent` is `ask` or `skip`.
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
- ## External application roles
1095
-
1096
- `declareExternalApplication` requires `userRoles` and accepts three optional
1097
- access fields: `serverRoles`, `defaultServerRole` and `groupBindings`. A
1098
- further optional field, `applicationConsent`, overrides the Application Consent
1099
- rule of the Organization for this application: `inherit` (the default) follows
1100
- the Organization, `ask` always prompts, `skip` never prompts.
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
- export const clinic = declareExternalApplication({
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
- // ...applicationType, audience, redirectUris, scopes, lifecycle
1106
- userRoles: [
1107
- {
1108
- key: "doctor",
1109
- platformPermissions: ["knowledge:read", "knowledge:manage"],
1110
- appPermissions: ["appointments:book"],
1111
- users: { create: true },
1112
- assignRoles: ["patient"],
1113
- visibility: "user"
1114
- },
1115
- {
1116
- key: "patient",
1117
- platformPermissions: [],
1118
- visibility: "declared",
1119
- bindings: {
1120
- knowledge: {
1121
- schemas: [
1122
- { fqn: "acme.clinic.schemas.appointment", policy: "own-rows" }
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
- serverRoles: [
1136
- {
1137
- key: "server",
1138
- platformPermissions: ["knowledge:read"],
1139
- users: { create: true },
1140
- assignRoles: ["patient"],
1141
- bindings: { workflows: "all" }
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
- defaultServerRole: "server",
1145
- groupBindings: [
1146
- {
1147
- group: doctorsGroup,
1148
- role: "doctor",
1149
- lifecycle: { deployMode: "upsert", readonly: true }
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
- - Every role has `key`, `platformPermissions`, and the optional fields
1159
- `parent`, `appPermissions`, `users: { create }`, `assignRoles` and
1160
- `replaces` (`ExternalApplicationRoleBase`).
1161
- - A User Role (`ExternalApplicationUserRole`) has `visibility`. `"user"`
1162
- (User Visibility) shows the resources that CI grants to the user; such a
1163
- role declares no `bindings`. `"declared"` (Declared Visibility) shows the
1164
- optional `bindings` of the role.
1165
- - A Server Role (`ExternalApplicationServerRole`) is the role of a call that
1166
- the application server makes. It has the optional `bindings`. When
1167
- `serverRoles` is not empty, `defaultServerRole` is required and names one of
1168
- them; the host uses it when a server call names no role.
1169
- - `bindings` is an `ExternalApplicationDeclaredBindings`: `knowledge.schemas`
1170
- and `knowledge.domains` list `{ fqn, policy? }` targets; `agents`, `skills`,
1171
- `workflows` and `documents` list FQNs. Each kind is `"all"` or a list; an
1172
- omitted kind binds nothing. The SDK checks the shape only; the host resolves
1173
- the FQNs.
1174
- - A `key` matches `^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$`, holds at most 64
1175
- characters, and is declared one time among the User Roles and the Server
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 access model of an External Application (`userRoles`,
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
@@ -1510,7 +1638,7 @@ const tools = declareRemoteToolCollection({
1510
1638
  definition: {
1511
1639
  gatewayRef: "com.example.nest.gateways.main",
1512
1640
  operationReferences: ["com.example.nest/greetings/greet@1.0.0"],
1513
- defaultVisibility: [{ effect: "allow", subject: "organization" }]
1641
+ audience: { organization: true }
1514
1642
  }
1515
1643
  })
1516
1644
  // Include tools and the referenced Gateway declaration in the package.
@@ -1524,13 +1652,43 @@ beginning with a letter or digit. References use
1524
1652
  strings of at most 128 characters. Every reference must match the declared
1525
1653
  Gateway, and the selection must be nonempty and unique.
1526
1654
 
1527
- The declaration shares `category` and `defaultVisibility` with ordinary Tool
1655
+ The declaration shares `category` and `audience` with ordinary Tool
1528
1656
  collections and supports normal identity and presentation metadata. Its closed
1529
1657
  metadata contains no executable implementation, schema sidecar, authorization
1530
1658
  override or credential. These constraints apply during authoring and serialized
1531
1659
  manifest admission. The Host validates the package-owned Gateway Connection and approved
1532
1660
  operations at installation; this declaration grants no execution authority.
1533
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
+
1534
1692
  ### Portable workflow pauses
1535
1693
 
1536
1694
  `PackageWorkflowNodeResult<Output>` admits a `directive: "pause"` result with
@@ -2142,9 +2300,10 @@ The [Nest declaration example](../../../demo/external-app-nest/apps/extensions/s
2142
2300
 
2143
2301
  `declareDocumentCollection` declares one Declared Connected collection: a
2144
2302
  Connected collection whose identity is the declaration FQN. One
2145
- `documentCollection` manifest holds the collection settings, its Connection,
2146
- its Remote roots and its nested Declared rules; no other kind declares a rule,
2147
- and no option creates a Local collection.
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`).
2148
2307
 
2149
2308
  ```ts
2150
2309
  import {
@@ -2166,24 +2325,7 @@ export const hrPolicies = declareDocumentCollection({
2166
2325
  connection: { setupKey: "microsoft365" },
2167
2326
  title: "HR Policies",
2168
2327
  indexContent: true,
2169
- remoteRoots: [{ drive: vars.hrDrive, folders: ["Policies"] }],
2170
- rules: [
2171
- {
2172
- grantee: { kind: "group", fqn: "acme.hr" },
2173
- target: { kind: "collection" },
2174
- permission: "read",
2175
- effect: "allow"
2176
- },
2177
- {
2178
- grantee: { kind: "organization" },
2179
- target: {
2180
- kind: "folder",
2181
- folder: { drive: vars.hrDrive, folders: ["Policies", "Board"] }
2182
- },
2183
- permission: "read",
2184
- effect: "deny"
2185
- }
2186
- ]
2328
+ remoteRoots: [{ drive: vars.hrDrive, folders: ["Policies"] }]
2187
2329
  }
2188
2330
  })
2189
2331
  ```
@@ -2199,20 +2341,11 @@ export const hrPolicies = declareDocumentCollection({
2199
2341
  collection description. `indexContent` and `indexOverview` default to
2200
2342
  `false`; `overviewInputMaxChars` and `richEnrichment` follow "File overview
2201
2343
  settings". `syncEnabled` defaults to `true`.
2202
- - A Remote root and a rule target folder are a path `{ drive, folders }` or a
2344
+ - A Remote root is a path `{ drive, folders }` or a
2203
2345
  `{ remoteId }` for a path that is ambiguous. On Microsoft 365, `drive` is the
2204
2346
  drive title `<siteName> / <libraryName>` that the browse route shows; an
2205
2347
  empty `folders` names the drive. Each value may be a Package Variable, so
2206
2348
  one release serves environments with different folders.
2207
- - A Declared rule needs a `grantee`, a `target`, a `permission` (`read`,
2208
- `update`, `manage` or `view_history`) and an `effect` (`allow` or `deny`),
2209
- with the meaning of the same rule made by an administrator. The grantee is a
2210
- group or a Service principal by FQN, or the whole Organization; a user ID or
2211
- an External App role is not a grantee. The target is the collection or a
2212
- folder: a folder that a Remote root names is a Remote root target, any other
2213
- folder a subfolder below a Remote root.
2214
- - An `allow` of `view_history` needs an `allow` of `read` for the same grantee
2215
- and target; the declaration and the manifest reader refuse it otherwise.
2216
2349
 
2217
2350
  ## Concrete connector configuration
2218
2351
 
@@ -2225,8 +2358,8 @@ release dependencies at installation. Every bundle requires
2225
2358
  `init_only` creates absent configuration and preserves existing content; `upsert`
2226
2359
  reconciles owned content through baseline/live merge. `readonly` governs manual
2227
2360
  configuration edits across the bundle. Child bindings, pipelines, schedules and
2228
- policies share that lifecycle; runtime data, cursors and authorized execution are
2229
- separate.
2361
+ the Dataset `dataPolicy` share that lifecycle; runtime data, cursors and
2362
+ authorized execution are separate.
2230
2363
 
2231
2364
  An entity binding of a Knowledge gateway connector may declare
2232
2365
  `pushEntityMatch: "unique_fields"`. A pushed record then joins the live entity
@@ -2287,26 +2420,6 @@ const customers = declareKnowledgeConnectorInstance({
2287
2420
  }
2288
2421
  ]
2289
2422
  }
2290
- ],
2291
- dataPolicies: [
2292
- {
2293
- fqn: "com.acme.sales.policies.customer_read",
2294
- targetKind: "entity_schema",
2295
- targetFqn: "com.acme.sales.customer",
2296
- policyType: "filter",
2297
- effect: "allow",
2298
- policyBody: {
2299
- subjectMatch: {
2300
- op: "eq",
2301
- left: { kind: "subject", path: ["user", "id"] },
2302
- right: {
2303
- kind: "literal",
2304
- value: "7f824c46-54f3-41aa-b0b5-3951fabf952a"
2305
- }
2306
- },
2307
- rule: { op: "const", value: true }
2308
- }
2309
- }
2310
2423
  ]
2311
2424
  }
2312
2425
  })
@@ -2361,162 +2474,12 @@ export default declarePackage({
2361
2474
  })
2362
2475
  ```
2363
2476
 
2364
- Use your actual exact dependency release, executable/schema FQNs, source location,
2365
- and authorized Organization reader UUID. Knowledge policies use the native
2366
- `{ subjectMatch, rule? }` AST, including recursive comparisons and logical
2367
- predicates. The old `{ version, rules }` shape is rejected. `subject` refs read
2368
- the caller as CI built it: `user.id`, `groupIds`, `roles` and `access`.
2369
- `roles` lists the keys of the user's effective User Roles (`userRoles`) on the
2370
- External App that makes the call, for example `["sales_manager"]`; it is empty
2371
- for a call outside an External App. Match a role with `in` on the subject path
2372
- `["roles"]`. CI sets `access` to `"read"` for get, list, search, facets,
2373
- autocomplete and retrieval, and to `"write"` for create, update and delete; a
2374
- policy that does not test it applies to both. For
2375
- example, this `deny` `filter` policy lets users with the `member` User Role read
2376
- every company but write only the ones whose accounts field lists them:
2377
-
2378
- ```ts
2379
- const memberCompanyWrites = declareKnowledgePolicy({
2380
- manifest: {
2381
- fqn: "com.acme.members.policies.member_company_writes",
2382
- version: "1.0.0"
2383
- },
2384
- presentation: { displayName: "Members write only their linked companies" },
2385
- definition: {
2386
- effect: "deny",
2387
- policyType: "filter",
2388
- targetKind: "entity_schema",
2389
- targetFqn: "com.acme.members.company",
2390
- policyBody: {
2391
- subjectMatch: {
2392
- op: "and",
2393
- args: [
2394
- {
2395
- op: "in",
2396
- value: { kind: "literal", value: "member" },
2397
- set: { kind: "subject", path: ["roles"] }
2398
- },
2399
- {
2400
- op: "eq",
2401
- left: { kind: "subject", path: ["access"] },
2402
- right: { kind: "literal", value: "write" }
2403
- }
2404
- ]
2405
- },
2406
- rule: {
2407
- op: "not",
2408
- arg: {
2409
- op: "in",
2410
- value: { kind: "subject", path: ["user", "id"] },
2411
- set: { kind: "resource", path: ["data", "accounts"] }
2412
- }
2413
- }
2414
- }
2415
- }
2416
- })
2417
- ```
2418
-
2419
- A relation scope follows a relation field of the record:
2420
- `{ op: "relation_field", field, inner }` holds when `inner` holds for some live
2421
- entity that the record's relation field `field` names, and `resource` refs in
2422
- `inner` read that related entity. CI applies it to every read and write of the
2423
- record: lists, gets, searches, facets, realtime events, deletes, and creates and
2424
- updates, which it checks on the related entity the write names. Hops nest. For
2425
- example, users read and write a task only when its `project` lists them in the
2426
- project's `members` accounts field, or when they have the `manager` User Role:
2427
-
2428
- ```ts
2429
- const projectMembers = {
2430
- op: "in",
2431
- value: { kind: "subject", path: ["user", "id"] },
2432
- set: { kind: "resource", path: ["data", "members"] }
2433
- } as const
2434
-
2435
- const projectTasks = declareKnowledgePolicy({
2436
- manifest: { fqn: "com.acme.work.policies.project_tasks", version: "1.0.0" },
2437
- presentation: { displayName: "Project members work on its tasks" },
2438
- definition: {
2439
- effect: "allow",
2440
- policyType: "filter",
2441
- targetKind: "entity_schema",
2442
- targetFqn: "com.acme.work.task",
2443
- policyBody: {
2444
- subjectMatch: { op: "const", value: true },
2445
- rule: {
2446
- op: "or",
2447
- args: [
2448
- {
2449
- op: "in",
2450
- value: { kind: "literal", value: "manager" },
2451
- set: { kind: "subject", path: ["roles"] }
2452
- },
2453
- { op: "relation_field", field: "project", inner: projectMembers }
2454
- ]
2455
- }
2456
- }
2457
- }
2458
- })
2459
- ```
2460
-
2461
- A comment on a task follows its `task`, then the task's `project`, with the
2462
- rule `{ op: "relation_field", field: "task", inner: { op: "relation_field",
2463
- field: "project", inner: projectMembers } }`. A hop to a deleted entity names
2464
- nothing. Hops belong in `rule`, never in `subjectMatch`, and only on a policy
2465
- that targets one entity schema; a hop holds no `direction`. CI refuses at
2466
- deploy a `field` that is not a forward relation field of the schema the hop
2467
- starts from. The Record Relation forms are retired: manifest parsing refuses
2468
- `relation_exists`, the `{ op: "relation_field", relationSchemaId, direction,
2469
- inner }` form and the policy kinds `relation_schema` and `relation_domain` with
2470
- an error that names the retired form or kind.
2471
-
2472
- A field write rule limits what an `allow` `filter` policy on an entity schema
2473
- or domain admits to updates of the listed `data` paths. `writableFields` is a
2474
- non-empty list of `["data", key, ...]` paths; a change at or under a path is
2475
- within it. CI compares the stored record with the record the update would
2476
- store: a value it resends unchanged is no change, but a key a `"replace"`
2477
- update omits is removed and so changed. The update is admitted only when one of the `allow` policies that admit
2478
- the record has no `writableFields` or lists every changed path; a `deny`
2479
- policy still refuses it. A File or relation field the update writes counts as
2480
- changed, and a change of the record's name, description or external binding is
2481
- outside every `writableFields`. A policy with `writableFields` admits no
2482
- create, delete or relation write and does not change reads. For example, users
2483
- with the `operator` User Role may update only the status:
2484
-
2485
- ```ts
2486
- const operatorStatusUpdates = declareKnowledgePolicy({
2487
- manifest: {
2488
- fqn: "com.acme.actions.policies.operator_status_updates",
2489
- version: "1.0.0"
2490
- },
2491
- presentation: { displayName: "Operators update only the status" },
2492
- definition: {
2493
- effect: "allow",
2494
- policyType: "filter",
2495
- targetKind: "entity_schema",
2496
- targetFqn: "com.acme.actions.action",
2497
- policyBody: {
2498
- subjectMatch: {
2499
- op: "and",
2500
- args: [
2501
- {
2502
- op: "in",
2503
- value: { kind: "literal", value: "operator" },
2504
- set: { kind: "subject", path: ["roles"] }
2505
- },
2506
- {
2507
- op: "eq",
2508
- left: { kind: "subject", path: ["access"] },
2509
- right: { kind: "literal", value: "write" }
2510
- }
2511
- ]
2512
- },
2513
- writableFields: [["data", "status"]]
2514
- }
2515
- }
2516
- })
2517
- ```
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").
2518
2481
 
2519
- Schema/domain targets cover all sources. Dataset grants use existing
2482
+ Dataset grants use existing
2520
2483
  user/service principals and native operations, fields, `sensitiveFields`, row
2521
2484
  filters and budgets.
2522
2485