@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.
Files changed (35) hide show
  1. package/README.md +332 -368
  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/docs/effect.md +2 -2
  34. package/package.json +2 -2
  35. package/dist/package/policy-readers.d.ts +0 -23
@@ -0,0 +1,61 @@
1
+ /**
2
+ * The Requirement of an app, route or widget guard and of a package
3
+ * manifest, and its one pure evaluator (ARC-009, Q98). A Requirement is
4
+ * serializable; the evaluator reads the capabilities of an Access Snapshot
5
+ * and never evaluates a Data Policy (AC-152).
6
+ */
7
+ import type { AccessCapabilityMode, AccessCapabilityReference, AccessModeArguments } from "./capabilities.js";
8
+ /**
9
+ * A serializable Requirement on one capability: a policy capability and a
10
+ * guard. The holder needs the node at `mode` or higher.
11
+ */
12
+ export type AccessCapabilityRequirement = Readonly<{
13
+ mode: AccessCapabilityMode;
14
+ requires: string;
15
+ }>;
16
+ /** The holder holds the node or any node below it (rule 3, AC-004). */
17
+ export type AccessEntryRequirement = Readonly<{
18
+ enters: string;
19
+ }>;
20
+ /** A Requirement on one node: what `useMissing` lists. */
21
+ export type AccessRequirementLeaf = AccessCapabilityRequirement | AccessEntryRequirement;
22
+ /** One Requirement type for app, route and widget guards (AC-150). */
23
+ export type AccessRequirement = AccessRequirementLeaf | Readonly<{
24
+ allOf: readonly AccessRequirement[];
25
+ }> | Readonly<{
26
+ anyOf: readonly AccessRequirement[];
27
+ }>;
28
+ /** One capability that a principal holds, as the Access Snapshot lists it. */
29
+ export type AccessHeldCapability = Readonly<{
30
+ code: string;
31
+ mode: AccessCapabilityMode;
32
+ }>;
33
+ /** Whether the Requirement holds, and the leaves that fail when it does not. */
34
+ export type AccessRequirementResult = Readonly<{
35
+ allowed: boolean;
36
+ missing: readonly AccessRequirementLeaf[];
37
+ }>;
38
+ /**
39
+ * Requires a capability: `requires(core.admin.users, "read")`,
40
+ * `requires(core.mcp)` or a code that another package declares.
41
+ */
42
+ export declare const requires: <const Reference extends AccessCapabilityReference>(capability: Reference, ...[mode]: AccessModeArguments<Reference>) => AccessCapabilityRequirement;
43
+ /** Enters a surface, a section or an app: `enters(core.studio)`. */
44
+ export declare const enters: (capability: AccessCapabilityReference) => AccessEntryRequirement;
45
+ type Requirements = readonly [AccessRequirement, ...AccessRequirement[]];
46
+ /** Every Requirement holds. */
47
+ export declare const allOf: (...requirements: Requirements) => Readonly<{
48
+ allOf: readonly AccessRequirement[];
49
+ }>;
50
+ /** At least one Requirement holds. */
51
+ export declare const anyOf: (...requirements: Requirements) => Readonly<{
52
+ anyOf: readonly AccessRequirement[];
53
+ }>;
54
+ /**
55
+ * The one evaluator of a Requirement over the capabilities of an Access
56
+ * Snapshot: `allowed`, and the leaves that fail (empty when allowed).
57
+ */
58
+ export declare const evaluateAccessRequirement: (requirement: AccessRequirement, held: readonly AccessHeldCapability[]) => AccessRequirementResult;
59
+ /** The mode in which the principal holds a capability, or `off`. */
60
+ export declare const accessCapabilityMode: (held: readonly AccessHeldCapability[], capability: AccessCapabilityReference) => AccessCapabilityMode | "off";
61
+ export {};
@@ -1,3 +1,4 @@
1
+ import type { AccessAudience, AccessAudienceDeclaration } from "../access/audience.js";
1
2
  import type { JsonObject } from "../foundation/json.js";
2
3
  import type { PackageSchemaProjection } from "../schema/projection.js";
3
4
  import type { PackageCodecSource } from "../schema/source.js";
@@ -64,29 +65,6 @@ export type DeclaredToolBindings = readonly (string | ToolBindingDeclaration)[];
64
65
  export declare const toolBindingDeclaration: (entry: string | ToolBindingDeclaration) => ToolBindingDeclaration;
65
66
  /** The first binding that repeats a `(tool, name)` pair, if any. */
66
67
  export declare const duplicateToolBinding: (tools: DeclaredToolBindings) => ToolBindingDeclaration | undefined;
67
- /** Organization members an Agent may converse with: none, the ones administrators select, or every member. */
68
- export type AgentMemberAudience = "all" | "none" | "selected";
69
- /**
70
- * Code maximum of who may converse with an Agent, per caller class.
71
- * Administrators select concrete users and Organization Groups within it and
72
- * may only narrow it. Omitted fields admit nobody of that class.
73
- */
74
- export type AgentAudience<Application = DeclarationReference<"externalApplication">> = Readonly<{
75
- /** Opt-in: anonymous visitors that an allowed application brings may converse. */
76
- anonymous?: boolean;
77
- /** Applications that may invoke the Agent as a service or bring visitors. */
78
- applications?: readonly Application[];
79
- members?: AgentMemberAudience;
80
- /** "selected": administrators may admit Organization Groups. */
81
- organizationGroups?: "none" | "selected";
82
- }>;
83
- /** An `AgentAudience` in a manifest: applications are FQNs. */
84
- export type AgentAudienceDeclaration = AgentAudience<string>;
85
- /**
86
- * The rule a declared audience breaks, if any: visitors always arrive through
87
- * an application, and an application is listed at most once.
88
- */
89
- export declare const agentAudienceViolation: (audience: AgentAudienceDeclaration) => string | undefined;
90
68
  /** Standard Organization model tiers, most capable first. */
91
69
  export declare const agentModelTiers: readonly ["complex", "balanced", "fast", "super_fast"];
92
70
  export type AgentModelTier = (typeof agentModelTiers)[number];
@@ -97,7 +75,8 @@ export type AgentModelTier = (typeof agentModelTiers)[number];
97
75
  export type AgentDeclaration = PackagePrimitiveBase<"agent"> & Readonly<{
98
76
  dataAccess?: DataAccess<"agent">;
99
77
  activity?: AgentActivityPolicy;
100
- audience?: AgentAudienceDeclaration;
78
+ /** Who is offered the Agent (Resource Audience); absent offers it to nobody. */
79
+ audience?: AccessAudienceDeclaration;
101
80
  behavioralBoundaries: readonly string[];
102
81
  /**
103
82
  * Runs the Agent without the Organization Instructions. Omitted is
@@ -126,6 +105,8 @@ export type AgentDeclaration = PackagePrimitiveBase<"agent"> & Readonly<{
126
105
  }>;
127
106
  /** Portable governed Skill held by Agents and loaded on demand. */
128
107
  export type SkillDeclaration = PackagePrimitiveBase<"skill"> & Readonly<{
108
+ /** Who is offered the Skill (Resource Audience); absent offers it to nobody. */
109
+ audience?: AccessAudienceDeclaration;
129
110
  dataAccess?: DataAccess<"skill">;
130
111
  instructions: string;
131
112
  lifecycle: LifecycleOptions;
@@ -138,13 +119,13 @@ type Declaration<Definition> = Readonly<{
138
119
  presentation: ComponentPresentation;
139
120
  }>;
140
121
  /**
141
- * `skills`, `tools` and `audience.applications` take same-package handles or
142
- * FQN strings. Strings are resolved at install, not at compile time: an
143
- * unknown Skill, tool or application rejects the package. A `tools` entry may
144
- * be a `ToolBinding` that adds the binding's controls.
122
+ * `skills`, `tools` and the `audience` references take same-package handles
123
+ * or FQN strings. Strings are resolved at install, not at compile time: an
124
+ * unknown Skill, tool, Group, profile or application rejects the package. A
125
+ * `tools` entry may be a `ToolBinding` that adds the binding's controls.
145
126
  */
146
127
  export type AgentDefinitionInput = Omit<DefinitionOf<AgentDeclaration>, "audience" | "output" | "skills" | "tools"> & Readonly<{
147
- audience?: AgentAudience;
128
+ audience?: AccessAudience;
148
129
  output?: Readonly<{
149
130
  schema: PackageCodecSource;
150
131
  }>;
@@ -155,7 +136,8 @@ export type AgentDefinitionInput = Omit<DefinitionOf<AgentDeclaration>, "audienc
155
136
  * `tools` take same-package handles, FQN strings resolved at install, or
156
137
  * `ToolBinding`s, exactly as an Agent's do.
157
138
  */
158
- export type SkillDefinitionInput = Omit<DefinitionOf<SkillDeclaration>, "tools"> & Readonly<{
139
+ export type SkillDefinitionInput = Omit<DefinitionOf<SkillDeclaration>, "audience" | "tools"> & Readonly<{
140
+ audience?: AccessAudience;
159
141
  tools: readonly (DeclarationReference<"tool"> | ToolBinding)[];
160
142
  }>;
161
143
  /** Declares an Organization Agent materialized by package install. */
@@ -1,3 +1,4 @@
1
+ import type { AccessAudience } from "../access/audience.js";
1
2
  import type { JsonValue } from "../foundation/json.js";
2
3
  import type { FormDefinition, FormSchemaSource, PortableFormDefinition } from "../schema/forms.js";
3
4
  import type { ConsumerProfileId } from "../schema/profiles.js";
@@ -179,7 +180,8 @@ export type DecoderSource<Schema> = Schema extends PackageSchemaSource<unknown,
179
180
  export type CodecSource<Schema> = Schema extends PackageSchemaSource<infer Wire, infer Value, infer Native> ? Schema & PackageCodec<Wire, Value> & Readonly<{
180
181
  native: Native;
181
182
  }> : never;
182
- export type ToolDefinitionInput<InputSchema, OutputSchema> = Omit<DefinitionInput<ToolDeclaration>, "bindingSettings" | "input" | "output" | "settings"> & Readonly<{
183
+ export type ToolDefinitionInput<InputSchema, OutputSchema> = Omit<DefinitionInput<ToolDeclaration>, "audience" | "bindingSettings" | "input" | "output" | "settings"> & Readonly<{
184
+ audience?: AccessAudience;
183
185
  bindingSettings?: FormDefinition;
184
186
  input: DecoderSource<InputSchema>;
185
187
  output: CodecSource<OutputSchema>;
@@ -1,6 +1,6 @@
1
1
  import type { VisibilityCondition } from "../schema/forms.js";
2
2
  export type BindingScope = "organization" | "tenant";
3
- export type PackagePrimitiveKind = "agent" | "knowledgeEntityAdapter" | "connection" | "connectionInstance" | "externalDatasetProvider" | "managedDatasetProvider" | "datasetParser" | "datasetBlueprint" | "datasetTableTemplate" | "documentCollection" | "documentsConnector" | "knowledgeConnectorInstance" | "datasetConnectorInstance" | "knowledgeConnector" | "knowledgeConnectorOauth" | "domain" | "domainTemplate" | "emailProvider" | "eventListener" | "externalApplication" | "externalAppGateway" | "fieldTransformer" | "knowledgeEntitySchema" | "knowledgePolicy" | "notificationChannel" | "organizationGroup" | "organizationInstructions" | "organizationSettings" | "organizationSso" | "outboundMessagingProvider" | "remoteToolCollection" | "servicePrincipal" | "skill" | "skillTemplate" | "studioApp" | "studioAppTemplate" | "studioComponent" | "tool" | "toolCollection" | "toolSettingsOptions" | "workflow" | "workflowField" | "workflowFieldCollection" | "workflowNode" | "workflowNodeCollection" | "workflowTemplate";
3
+ export type PackagePrimitiveKind = "accessCapabilities" | "accessDocumentDataPolicy" | "accessGrantAxis" | "accessKnowledgeDataCondition" | "accessKnowledgeDataPolicy" | "accessMaxPrivileges" | "accessProfile" | "accessProfileGrant" | "agent" | "knowledgeEntityAdapter" | "connection" | "connectionInstance" | "externalDatasetProvider" | "managedDatasetProvider" | "datasetParser" | "datasetBlueprint" | "datasetTableTemplate" | "documentCollection" | "documentsConnector" | "knowledgeConnectorInstance" | "datasetConnectorInstance" | "knowledgeConnector" | "knowledgeConnectorOauth" | "domain" | "domainTemplate" | "emailProvider" | "eventListener" | "externalApplication" | "externalAppGateway" | "fieldTransformer" | "knowledgeEntitySchema" | "notificationChannel" | "organizationGroup" | "organizationInstructions" | "organizationSettings" | "organizationSso" | "outboundMessagingProvider" | "remoteToolCollection" | "servicePrincipal" | "skill" | "skillTemplate" | "studioApp" | "studioAppTemplate" | "studioComponent" | "tool" | "toolCollection" | "toolSettingsOptions" | "workflow" | "workflowField" | "workflowFieldCollection" | "workflowNode" | "workflowNodeCollection" | "workflowTemplate";
4
4
  export type PackagePrimitiveBase<Kind extends PackagePrimitiveKind> = Readonly<{
5
5
  description?: string;
6
6
  displayName: string;
@@ -2,7 +2,6 @@ import type { JsonObject, JsonValue } from "../foundation/json.js";
2
2
  import type { PackagePrimitiveBase } from "./base.js";
3
3
  import type { KnowledgeConnectorBindingExtraConfig, KnowledgeConnectorFieldMapRule } from "./connectors.js";
4
4
  import type { DatasetDefinition, DatasetFilter, DatasetSourceLocation } from "./datasets.js";
5
- import type { KnowledgePolicyDeclaration } from "./knowledge.js";
6
5
  import type { LifecycleOptions } from "./lifecycle.js";
7
6
  /** A slot uses install input or a declared connection, never embedded credentials. */
8
7
  export type ConnectorInstanceConnection = Readonly<{
@@ -92,7 +91,6 @@ export type KnowledgeConnectorInstancePipeline = Readonly<{
92
91
  }>;
93
92
  schedules?: readonly KnowledgeConnectorInstanceSchedule[];
94
93
  }>;
95
- export type KnowledgeConnectorInstanceDataPolicy = Omit<KnowledgePolicyDeclaration, "kind" | "version" | "displayName" | "description" | "icon" | "tags">;
96
94
  export type KnowledgeConnectorInstanceDeclaration = PackagePrimitiveBase<"knowledgeConnectorInstance"> & Readonly<{
97
95
  templateFqn: string;
98
96
  lifecycle: LifecycleOptions;
@@ -102,7 +100,6 @@ export type KnowledgeConnectorInstanceDeclaration = PackagePrimitiveBase<"knowle
102
100
  connections?: Readonly<Record<string, ConnectorInstanceConnection>>;
103
101
  entityBindings?: readonly KnowledgeConnectorInstanceEntityBinding[];
104
102
  pipelines?: readonly KnowledgeConnectorInstancePipeline[];
105
- dataPolicies?: readonly KnowledgeConnectorInstanceDataPolicy[];
106
103
  }>;
107
104
  export type DatasetConnectorInstanceDataPolicy = Readonly<{
108
105
  principals: readonly Readonly<{
@@ -1,3 +1,4 @@
1
+ import type { AccessPrimitiveDeclaration } from "../access/manifest.js";
1
2
  import type { AgentDeclaration, SkillDeclaration } from "./agents.js";
2
3
  import type { DomainDeclaration, DomainTemplateDeclaration, SkillTemplateDeclaration } from "./catalog.js";
3
4
  import type { ConnectionInstanceDeclaration } from "./connection-instances.js";
@@ -6,7 +7,7 @@ import type { ConnectionDeclaration, DatasetParserDeclaration, ExternalDatasetPr
6
7
  import type { DocumentCollectionDeclaration } from "./document-collections.js";
7
8
  import type { ExternalAppGatewayDeclaration } from "./external-app-gateway.js";
8
9
  import type { ExternalApplicationDeclaration } from "./external-application.js";
9
- import type { KnowledgeEntitySchemaDeclaration, KnowledgePolicyDeclaration } from "./knowledge.js";
10
+ import type { KnowledgeEntitySchemaDeclaration } from "./knowledge.js";
10
11
  import type { OrganizationGroupDeclaration } from "./organization-group.js";
11
12
  import type { OrganizationInstructionsDeclaration } from "./organization-instructions.js";
12
13
  import type { OrganizationSettingsDeclaration } from "./organization-settings.js";
@@ -15,4 +16,4 @@ import type { StudioAppDeclaration, StudioAppTemplateDeclaration, StudioComponen
15
16
  import type { DatasetBlueprintDeclaration, DatasetTableTemplateDeclaration } from "./templates.js";
16
17
  import type { FieldTransformerDeclaration, NotificationChannelDeclaration, RemoteToolCollectionDeclaration, ToolCollectionDeclaration, ToolDeclaration, ToolSettingsOptionsDeclaration } from "./tools.js";
17
18
  import type { WorkflowDeclaration, WorkflowFieldCollectionDeclaration, WorkflowFieldDeclaration, WorkflowNodeCollectionDeclaration, WorkflowNodeDeclaration, WorkflowTemplateDeclaration } from "./workflows.js";
18
- export type PackagePrimitiveDeclaration = ConnectionInstanceDeclaration | KnowledgeConnectorInstanceDeclaration | DatasetConnectorInstanceDeclaration | AgentDeclaration | OrganizationSsoDeclaration | KnowledgeEntityAdapterDeclaration | ConnectionDeclaration | DatasetParserDeclaration | DatasetBlueprintDeclaration | DatasetTableTemplateDeclaration | ExternalDatasetProviderDeclaration | ManagedDatasetProviderDeclaration | DocumentCollectionDeclaration | DocumentsConnectorDeclaration | KnowledgeConnectorDeclaration | KnowledgeConnectorOAuthDeclaration | DomainDeclaration | DomainTemplateDeclaration | EmailProviderDeclaration | EventListenerDeclaration | ExternalApplicationDeclaration | ExternalAppGatewayDeclaration | FieldTransformerDeclaration | KnowledgeEntitySchemaDeclaration | KnowledgePolicyDeclaration | NotificationChannelDeclaration | OrganizationGroupDeclaration | OrganizationInstructionsDeclaration | OrganizationSettingsDeclaration | OutboundMessagingProviderDeclaration | RemoteToolCollectionDeclaration | ServicePrincipalDeclaration | SkillDeclaration | SkillTemplateDeclaration | StudioAppDeclaration | StudioAppTemplateDeclaration | StudioComponentDeclaration | ToolCollectionDeclaration | ToolSettingsOptionsDeclaration | ToolDeclaration | WorkflowDeclaration | WorkflowFieldCollectionDeclaration | WorkflowFieldDeclaration | WorkflowNodeCollectionDeclaration | WorkflowNodeDeclaration | WorkflowTemplateDeclaration;
19
+ export type PackagePrimitiveDeclaration = AccessPrimitiveDeclaration | ConnectionInstanceDeclaration | KnowledgeConnectorInstanceDeclaration | DatasetConnectorInstanceDeclaration | AgentDeclaration | OrganizationSsoDeclaration | KnowledgeEntityAdapterDeclaration | ConnectionDeclaration | DatasetParserDeclaration | DatasetBlueprintDeclaration | DatasetTableTemplateDeclaration | ExternalDatasetProviderDeclaration | ManagedDatasetProviderDeclaration | DocumentCollectionDeclaration | DocumentsConnectorDeclaration | KnowledgeConnectorDeclaration | KnowledgeConnectorOAuthDeclaration | DomainDeclaration | DomainTemplateDeclaration | EmailProviderDeclaration | EventListenerDeclaration | ExternalApplicationDeclaration | ExternalAppGatewayDeclaration | FieldTransformerDeclaration | KnowledgeEntitySchemaDeclaration | NotificationChannelDeclaration | OrganizationGroupDeclaration | OrganizationInstructionsDeclaration | OrganizationSettingsDeclaration | OutboundMessagingProviderDeclaration | RemoteToolCollectionDeclaration | ServicePrincipalDeclaration | SkillDeclaration | SkillTemplateDeclaration | StudioAppDeclaration | StudioAppTemplateDeclaration | StudioComponentDeclaration | ToolCollectionDeclaration | ToolSettingsOptionsDeclaration | ToolDeclaration | WorkflowDeclaration | WorkflowFieldCollectionDeclaration | WorkflowFieldDeclaration | WorkflowNodeCollectionDeclaration | WorkflowNodeDeclaration | WorkflowTemplateDeclaration;
@@ -15,38 +15,10 @@ export type DocumentFolderTarget = Readonly<{
15
15
  drive?: never;
16
16
  folders?: never;
17
17
  }>;
18
- /** A group or a Service principal by FQN, or the whole Organization; never a user. */
19
- export type DeclaredRuleGrantee = Readonly<{
20
- fqn: string;
21
- kind: "group" | "servicePrincipal";
22
- }> | Readonly<{
23
- kind: "organization";
24
- }>;
25
- /**
26
- * The collection, or a folder. A folder that a Remote root names is a Remote
27
- * root target; any other folder is a subfolder below a Remote root.
28
- */
29
- export type DeclaredRuleTarget = Readonly<{
30
- kind: "collection";
31
- }> | Readonly<{
32
- folder: DocumentFolderTarget;
33
- kind: "folder";
34
- }>;
35
- /**
36
- * A Document access rule that the package declares and owns, with the meaning
37
- * of the same rule made by an administrator. An `allow` of `view_history`
38
- * needs an `allow` of `read` for the same grantee and target.
39
- */
40
- export type DeclaredRule = Readonly<{
41
- effect: "allow" | "deny";
42
- grantee: DeclaredRuleGrantee;
43
- permission: "manage" | "read" | "update" | "view_history";
44
- target: DeclaredRuleTarget;
45
- }>;
46
18
  /**
47
- * One Declared Connected collection, its Documents connector instance and its
48
- * Declared rules. The declaration `description` is the collection
49
- * description. No option creates a Local collection.
19
+ * One Declared Connected collection and its Documents connector instance.
20
+ * The declaration `description` is the collection description. No option
21
+ * creates a Local collection. Document Data Policies decide who reads it.
50
22
  */
51
23
  export type DocumentCollectionDeclaration = PackagePrimitiveBase<"documentCollection"> & Readonly<{
52
24
  /** An existing Connection by setup input, or a declared Connection. */
@@ -64,7 +36,6 @@ export type DocumentCollectionDeclaration = PackagePrimitiveBase<"documentCollec
64
36
  overviewInputMaxChars?: number | null;
65
37
  remoteRoots: readonly DocumentFolderTarget[];
66
38
  richEnrichment?: boolean | null;
67
- rules?: readonly DeclaredRule[];
68
39
  /** Scheduled sync; defaults to `true`. */
69
40
  syncEnabled?: boolean;
70
41
  title: string;
@@ -1,3 +1,4 @@
1
+ import type { AccessCapabilityNodeDeclaration } from "../access/capabilities.js";
1
2
  import type { VaryingDefinition } from "../package/variables.js";
2
3
  import type { PackagePrimitiveBase } from "./base.js";
3
4
  import type { LifecycleOptions } from "./lifecycle.js";
@@ -8,93 +9,21 @@ export type ExternalApplicationType = "confidential" | "public";
8
9
  */
9
10
  export type ExternalApplicationConsent = "inherit" | "ask" | "skip";
10
11
  export declare const externalApplicationConsents: readonly ["inherit", "ask", "skip"];
11
- /**
12
- * The target list of one binding kind: `all`, or the FQNs of the targets. An
13
- * omitted kind binds no target.
14
- */
15
- export type ExternalApplicationBindingTargets<Target> = "all" | readonly Target[];
16
- /** A Knowledge Entity Schema or Domain, with an optional row policy. */
17
- export type ExternalApplicationKnowledgeTarget = Readonly<{
18
- fqn: string;
19
- policy?: string;
20
- }>;
21
- /** The resources that a role sees without a Grant to the user. */
22
- export type ExternalApplicationDeclaredBindings = Readonly<{
23
- agents?: ExternalApplicationBindingTargets<string>;
24
- documents?: ExternalApplicationBindingTargets<string>;
25
- knowledge?: Readonly<{
26
- domains?: ExternalApplicationBindingTargets<ExternalApplicationKnowledgeTarget>;
27
- schemas?: ExternalApplicationBindingTargets<ExternalApplicationKnowledgeTarget>;
28
- }>;
29
- skills?: ExternalApplicationBindingTargets<string>;
30
- workflows?: ExternalApplicationBindingTargets<string>;
31
- }>;
32
- /**
33
- * The fields of every External App Role. `Key` is the union of the role keys
34
- * of the same list and `UserKey` the union of the User Role keys; a manifest
35
- * holds plain strings.
36
- */
37
- export type ExternalApplicationRoleBase<Key extends string = string, UserKey extends string = string> = Readonly<{
38
- /** Permissions that the application defines and checks itself. */
39
- appPermissions?: readonly string[];
40
- /** Keys of the User Roles that a holder of this role can assign. */
41
- assignRoles?: readonly NoInfer<UserKey>[];
42
- key: Key;
43
- /** Key of the declared role of the same kind that holds every permission of this role. */
44
- parent?: NoInfer<Key>;
45
- /** CI permissions, each one `resource:action`; resources may be namespaced. */
46
- platformPermissions: readonly string[];
47
- /** Key of a role that an earlier release declared and this one removed. */
48
- replaces?: string;
49
- /** `create: true` lets a holder of this role create External App Users. */
50
- users?: Readonly<{
51
- create: boolean;
52
- }>;
53
- }>;
54
- /**
55
- * A User Role. User Visibility shows the resources granted to the user;
56
- * Declared Visibility shows the `bindings` of the role.
57
- */
58
- export type ExternalApplicationUserRole<Key extends string = string> = ExternalApplicationRoleBase<Key, Key> & (Readonly<{
59
- visibility: "user";
60
- }> | Readonly<{
61
- bindings?: ExternalApplicationDeclaredBindings;
62
- visibility: "declared";
63
- }>);
64
- /** A Server Role: the role of a call that the application server makes. */
65
- export type ExternalApplicationServerRole<Key extends string = string, UserKey extends string = string> = ExternalApplicationRoleBase<Key, UserKey> & Readonly<{
66
- bindings?: ExternalApplicationDeclaredBindings;
67
- }>;
68
- /** A Group Role Binding: the members of one Group hold one User Role. */
69
- export type ExternalApplicationGroupBinding = Readonly<{
70
- /** `direct` covers the members of the Group only; `inherited` (the default) also covers its subgroups. */
71
- coverage?: "direct" | "inherited";
72
- /** FQN of the Group, in any package. */
73
- group: string;
74
- lifecycle: LifecycleOptions;
75
- /** Key of a declared User Role of the application. */
76
- role: string;
77
- }>;
78
- /**
79
- * The access model of the application. It keeps its shape: a Variable
80
- * Reference never stands in for one of its values.
81
- */
82
- type ExternalApplicationAccess = Readonly<{
83
- /** The Server Role of a server call that names no role; required with `serverRoles`. */
84
- defaultServerRole?: string;
85
- groupBindings?: readonly ExternalApplicationGroupBinding[];
86
- serverRoles?: readonly ExternalApplicationServerRole[];
87
- userRoles: readonly ExternalApplicationUserRole[];
88
- }>;
89
12
  /**
90
13
  * Portable External App definition. Tokens and client secrets are never
91
- * declared here; Dashboard rotate remains the credential path.
14
+ * declared here; Dashboard rotate remains the credential path. Access comes
15
+ * from grants of the app's capability tree: its root is the app gate.
92
16
  */
93
- export type ExternalApplicationDeclaration = PackagePrimitiveBase<"externalApplication"> & ExternalApplicationAccess & Readonly<{
17
+ export type ExternalApplicationDeclaration = PackagePrimitiveBase<"externalApplication"> & Readonly<{
94
18
  allowedOrigins: readonly string[];
95
19
  applicationConsent?: ExternalApplicationConsent;
96
20
  applicationType: ExternalApplicationType;
97
21
  audience: string;
22
+ /**
23
+ * The app's capabilities below its gate, the Switch whose code is the
24
+ * application FQN; each node carries its resolved kind.
25
+ */
26
+ capabilities?: Readonly<Record<string, AccessCapabilityNodeDeclaration>>;
98
27
  lifecycle: LifecycleOptions;
99
28
  postLogoutRedirectUris: readonly string[];
100
29
  /**
@@ -104,17 +33,16 @@ export type ExternalApplicationDeclaration = PackagePrimitiveBase<"externalAppli
104
33
  primaryRedirectUri?: string;
105
34
  /** Every accepted callback, including the primary redirect URI. */
106
35
  redirectUris: readonly string[];
107
- scopes: readonly string[];
108
36
  setupInstructions?: string;
109
37
  }>;
110
- /** The fields of the access model of the application. */
111
- export type ExternalApplicationAccessKey = keyof ExternalApplicationAccess;
112
- /** The declaration as manifest readers admit it, before substitution. */
113
- export type VaryingExternalApplication = ExternalApplicationAccess & VaryingDefinition<Omit<ExternalApplicationDeclaration, ExternalApplicationAccessKey>>;
114
38
  /**
115
- * Shared authoring and serialized admission invariant for callbacks, the
116
- * User Roles, the Server Roles with their Default Server Role and the Group
117
- * Role Bindings. A role violation starts with the field path of the role.
39
+ * The declaration as manifest readers admit it, before substitution. The
40
+ * capability tree takes no Package Variable: it names catalog nodes.
41
+ */
42
+ export type VaryingExternalApplication = VaryingDefinition<Omit<ExternalApplicationDeclaration, "capabilities">> & Pick<ExternalApplicationDeclaration, "capabilities">;
43
+ /**
44
+ * Shared authoring and serialized admission invariant of the callbacks and
45
+ * the consent override. Access comes from Access Profiles and Access Grants
46
+ * of the app gate and capabilities, never from OAuth scopes.
118
47
  */
119
- export declare const externalApplicationViolation: ({ applicationConsent, defaultServerRole, groupBindings, primaryRedirectUri, redirectUris, serverRoles, userRoles }: Pick<VaryingExternalApplication, "applicationConsent" | "defaultServerRole" | "groupBindings" | "primaryRedirectUri" | "redirectUris" | "serverRoles" | "userRoles">) => string | undefined;
120
- export {};
48
+ export declare const externalApplicationViolation: ({ applicationConsent, primaryRedirectUri, redirectUris }: Pick<VaryingExternalApplication, "applicationConsent" | "primaryRedirectUri" | "redirectUris">) => string | undefined;
@@ -32,7 +32,7 @@ export type KnowledgeFileFieldDeclaration = KnowledgeFileField & Readonly<{
32
32
  visibility?: KnowledgeFieldSemantics["mediaVisibility"];
33
33
  }>;
34
34
  /**
35
- * Explicit top-level references to Organization members or External App Users
35
+ * Explicit top-level references to Organization members or guests
36
36
  * of the Organization; the host generates UUID values. `accounts: true` makes
37
37
  * it the schema's accounts field (at most one per schema): the users it lists
38
38
  * act for the record. Only the host writes it.
@@ -206,167 +206,4 @@ export type KnowledgeEntitySchemaDeclaration = PackagePrimitiveBase<"knowledgeEn
206
206
  versioned?: boolean;
207
207
  versioningEnabled: boolean | null;
208
208
  }>;
209
- export type KnowledgePolicyDeclaration = PackagePrimitiveBase<"knowledgePolicy"> & Readonly<{
210
- effect: "allow" | "deny";
211
- /** Domain-attached policies target the domain FQN; schema policies target a schema FQN. */
212
- targetKind: "entity_domain" | "entity_schema";
213
- policyBody: KnowledgePolicyBody;
214
- policyType: "filter" | "gate";
215
- priority?: number;
216
- targetFqn: string;
217
- }>;
218
- /** Exact native Knowledge AST; no additional predicates or source-specific targets. */
219
- export type KnowledgePolicyRef = Readonly<{
220
- kind: "literal";
221
- value: JsonValue;
222
- }> | Readonly<{
223
- kind: "subject" | "resource";
224
- path: readonly string[];
225
- }>;
226
- export type KnowledgePolicyPredicate = Readonly<{
227
- op: "eq" | "neq" | "lt" | "lte" | "gt" | "gte";
228
- left: KnowledgePolicyRef;
229
- right: KnowledgePolicyRef;
230
- }> | Readonly<{
231
- op: "in";
232
- value: KnowledgePolicyRef;
233
- set: KnowledgePolicyRef;
234
- }> | Readonly<{
235
- op: "exists" | "is_null";
236
- ref: KnowledgePolicyRef;
237
- }> | Readonly<{
238
- op: "contains" | "starts_with";
239
- ref: KnowledgePolicyRef;
240
- value: KnowledgePolicyRef;
241
- }> | Readonly<{
242
- op: "const";
243
- value: boolean;
244
- }> | Readonly<{
245
- op: "not";
246
- arg: KnowledgePolicyPredicate;
247
- }> | Readonly<{
248
- op: "and" | "or";
249
- args: readonly KnowledgePolicyPredicate[];
250
- }>
251
- /**
252
- * An Entity Relation Field hop: true when `inner` holds for some live
253
- * entity that the record's own relation field `field` names. Inside
254
- * `inner`, `resource` refs read that target entity; `subject` refs are
255
- * unchanged. Hops nest, one per relation field. A hop belongs in `rule`,
256
- * only on an `entity_schema` policy, and `field` must be a forward relation
257
- * field of the schema the hop starts from.
258
- */
259
- | Readonly<{
260
- op: "relation_field";
261
- field: string;
262
- inner: KnowledgePolicyPredicate;
263
- }>;
264
- /**
265
- * A Knowledge policy: `subjectMatch` selects whom it applies to, `rule` which
266
- * records. `subject` refs read the caller as CI built it: `user.id`,
267
- * `groupIds`, `roles` and `access`. `roles` lists the keys of the user's
268
- * effective User Roles (`userRoles`) on the External App that makes the call;
269
- * it is empty for a call outside an External App. Match a role with
270
- * `{ op: "in", value: { kind: "literal", value: "<role key>" }, set: { kind: "subject", path: ["roles"] } }`.
271
- * `access` is `"read"` for get, list, search, facets, autocomplete and
272
- * retrieval, and `"write"` for create, update and delete;
273
- * the deciding operation sets it, never the caller. A policy that does not
274
- * test `access` applies to both. `resource` refs read `["id"]` or a `data`
275
- * path.
276
- *
277
- * Relation scope: `{ op: "relation_field", field, inner }` follows the
278
- * record's relation field `field` and tests `inner` on the entities it names;
279
- * `resource` refs in `inner` read the related entity. CI applies it to every
280
- * read and write of the record: lists, gets, searches, realtime events, and
281
- * creates and updates, which it checks on the related entity the write names.
282
- * Users read and write a task only when the task's `project` lists them in
283
- * its `members` accounts field, or when they have the `manager` User Role:
284
- *
285
- * ```ts
286
- * const projectMembersOnly: KnowledgePolicyBody = {
287
- * subjectMatch: { op: "const", value: true },
288
- * rule: {
289
- * op: "or",
290
- * args: [
291
- * { op: "in", value: { kind: "literal", value: "manager" }, set: { kind: "subject", path: ["roles"] } },
292
- * {
293
- * op: "relation_field",
294
- * field: "project",
295
- * inner: { op: "in", value: { kind: "subject", path: ["user", "id"] }, set: { kind: "resource", path: ["data", "members"] } }
296
- * }
297
- * ]
298
- * }
299
- * }
300
- * ```
301
- * Declare it on the task schema with `effect: "allow"` and `policyType:
302
- * "filter"`. Hops nest: a comment follows its `task`, then the task's
303
- * `project`:
304
- *
305
- * ```ts
306
- * const commentRule: KnowledgePolicyPredicate = {
307
- * op: "relation_field",
308
- * field: "task",
309
- * inner: {
310
- * op: "relation_field",
311
- * field: "project",
312
- * inner: { op: "in", value: { kind: "subject", path: ["user", "id"] }, set: { kind: "resource", path: ["data", "members"] } }
313
- * }
314
- * }
315
- * ```
316
- *
317
- * Write-only deny: users with the `member` User Role read every company but
318
- * write only the ones whose accounts field lists them.
319
- *
320
- * ```ts
321
- * const memberCompanyWrites: KnowledgePolicyBody = {
322
- * subjectMatch: {
323
- * op: "and",
324
- * args: [
325
- * { op: "in", value: { kind: "literal", value: "member" }, set: { kind: "subject", path: ["roles"] } },
326
- * { op: "eq", left: { kind: "subject", path: ["access"] }, right: { kind: "literal", value: "write" } }
327
- * ]
328
- * },
329
- * rule: {
330
- * op: "not",
331
- * arg: { op: "in", value: { kind: "subject", path: ["user", "id"] }, set: { kind: "resource", path: ["data", "accounts"] } }
332
- * }
333
- * }
334
- * ```
335
- * Declare it with `effect: "deny"` and `policyType: "filter"`.
336
- *
337
- * Field write rule: `writableFields` limits the writes an `allow` `filter`
338
- * policy on an entity schema or domain admits to updates that change only
339
- * the listed `data` paths. Users with the `operator` User Role update only
340
- * the status of every record:
341
- *
342
- * ```ts
343
- * const operatorStatusUpdates: KnowledgePolicyBody = {
344
- * subjectMatch: {
345
- * op: "and",
346
- * args: [
347
- * { op: "in", value: { kind: "literal", value: "operator" }, set: { kind: "subject", path: ["roles"] } },
348
- * { op: "eq", left: { kind: "subject", path: ["access"] }, right: { kind: "literal", value: "write" } }
349
- * ]
350
- * },
351
- * writableFields: [["data", "status"]]
352
- * }
353
- * ```
354
- */
355
- export type KnowledgePolicyBody = Readonly<{
356
- subjectMatch: KnowledgePolicyPredicate;
357
- rule?: KnowledgePolicyPredicate;
358
- /**
359
- * The `["data", key, ...]` paths an update this policy admits may change; a
360
- * change at or under a path is within it. Present only on an `allow`
361
- * `filter` policy on an entity schema or domain. CI compares the stored
362
- * record with the record the update would store: the update is admitted
363
- * only when one of the `allow` policies that admit the record has no
364
- * `writableFields`, or lists every changed path. A File or relation field
365
- * the update writes counts as changed; a change of the record's name,
366
- * description or external binding is outside every `writableFields`. Such
367
- * a policy admits no create or delete, and does not change
368
- * reads.
369
- */
370
- writableFields?: readonly (readonly string[])[];
371
- }>;
372
209
  export {};