@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
@@ -0,0 +1,169 @@
1
+ import type { ComponentPresentation, DeclarationReference, DeclaredComponent } from "../components/authoring-core.js";
2
+ import type { PackagePrimitiveBase } from "../components/base.js";
3
+ import type { KnowledgeEntitySchemaDeclaration } from "../components/knowledge.js";
4
+ import type { LifecycleOptions } from "../components/lifecycle.js";
5
+ import type { AccessCapabilityGrant, AccessCapabilityNodeInput, AccessCapabilityTree } from "./capabilities.js";
6
+ import type { AccessGrantAxisReference, AccessGroupCoverage, AccessGroupReference } from "./conditions.js";
7
+ import type { AccessCapabilitiesDeclaration, AccessGrantableBy, AccessGrantAxisDeclaration, AccessKnowledgeEntityIdentifier, AccessMaxPrivilegesDeclaration, AccessPrimitiveDeclaration, AccessProfileAudience, AccessProfileDeclaration, AccessProfileGrantDeclaration } from "./manifest.js";
8
+ /** Identity of an access component; access components need no presentation. */
9
+ export type AccessComponentManifest<Fqn extends string = string> = Readonly<{
10
+ fqn: Fqn;
11
+ version: string;
12
+ }>;
13
+ /** The identity and presentation of an access component. */
14
+ export type AccessComponentIdentity<Fqn extends string = string> = Readonly<{
15
+ manifest: AccessComponentManifest<Fqn>;
16
+ /** Defaults to the FQN as display name. */
17
+ presentation?: ComponentPresentation;
18
+ }>;
19
+ export type AccessDeclarationInput<Definition, Fqn extends string = string> = AccessComponentIdentity<Fqn> & Readonly<{
20
+ definition: Definition;
21
+ }>;
22
+ /** A Knowledge entity schema by handle or by FQN. */
23
+ export type AccessKnowledgeSchemaReference = DeclaredComponent<KnowledgeEntitySchemaDeclaration> | string;
24
+ type AccessKind = AccessPrimitiveDeclaration["kind"];
25
+ type DefinitionFields<Kind extends AccessKind> = Omit<Extract<AccessPrimitiveDeclaration, {
26
+ kind: Kind;
27
+ }>, keyof PackagePrimitiveBase<Kind>>;
28
+ /** Refuses a definition key that the access vocabulary does not have. */
29
+ export declare const assertKnownKeys: <Definition extends object>(definition: Definition, known: readonly (keyof Definition & string)[], location: string) => void;
30
+ /** The optional lifecycle, checked when present. */
31
+ export declare const lifecycleField: (lifecycle: LifecycleOptions | undefined, location: string) => Readonly<{
32
+ lifecycle?: LifecycleOptions;
33
+ }>;
34
+ /** Builds the manifest of an access component from its identity, presentation and fields. */
35
+ export declare const accessManifest: <Kind extends AccessKind>(kind: Kind, input: AccessComponentIdentity, fields: DefinitionFields<Kind>) => Extract<AccessPrimitiveDeclaration, {
36
+ kind: Kind;
37
+ }>;
38
+ /**
39
+ * Shared authoring and serialized admission invariant: every capability entry
40
+ * references a node by code; a profile never declares a capability inline.
41
+ */
42
+ export declare const capabilityGrantsViolation: (capabilities: readonly AccessCapabilityGrant[]) => string | undefined;
43
+ type AccessCapabilitiesDefinition<Nodes extends Readonly<Record<string, AccessCapabilityNodeInput>>> = Readonly<{
44
+ /** Defaults to `admins`; `holders` makes Grant Authority require holding the node. */
45
+ grantableBy?: AccessGrantableBy;
46
+ lifecycle?: LifecycleOptions;
47
+ nodes: Nodes;
48
+ }>;
49
+ /** The declared component and the typed handles of its root and nodes. */
50
+ export type AccessCapabilitiesHandle<Nodes extends Readonly<Record<string, AccessCapabilityNodeInput>> = Readonly<Record<string, AccessCapabilityNodeInput>>> = DeclaredComponent<AccessCapabilitiesDeclaration> & AccessCapabilityTree<Readonly<{
51
+ children: Nodes;
52
+ kind: "readManage";
53
+ }>, "readManage">;
54
+ /**
55
+ * Declares a package's capability nodes below one Read/Manage root whose code
56
+ * is the declaration FQN. A node exists also when no profile grants it.
57
+ */
58
+ export declare const declareAccessCapabilities: <const Nodes extends Readonly<Record<string, AccessCapabilityNodeInput>>>(input: AccessDeclarationInput<AccessCapabilitiesDefinition<Nodes>>) => AccessCapabilitiesHandle<Nodes>;
59
+ /** The slug that keys a Grant Axis value in grants: the last segment of its FQN. */
60
+ export type AccessGrantAxisSlug<Fqn extends string> = Fqn extends `${string}.${infer Rest}` ? AccessGrantAxisSlug<Rest> : Fqn;
61
+ /** The slug that keys a Grant Axis value in grants: the last segment of its FQN. */
62
+ export declare const accessGrantAxisSlug: (fqn: string) => string;
63
+ /** A declared Grant Axis and the slug that keys its values in grants. */
64
+ export type AccessGrantAxisHandle<Slug extends string = string> = DeclaredComponent<AccessGrantAxisDeclaration> & Readonly<{
65
+ slug: Slug;
66
+ }>;
67
+ type AccessGrantAxisDefinition = Readonly<{
68
+ /** A single-valued self-relation field of the target; without it a value covers only itself. */
69
+ hierarchy?: string;
70
+ label: string;
71
+ lifecycle?: LifecycleOptions;
72
+ target: AccessKnowledgeSchemaReference;
73
+ }>;
74
+ /** Refuses a field key that the target schema handle does not declare; an FQN is checked at install. */
75
+ export declare const assertSchemaFields: (target: AccessKnowledgeSchemaReference, keys: readonly string[], location: string) => void;
76
+ /** Declares a Grant Axis on one Knowledge entity schema. */
77
+ export declare const declareAccessGrantAxis: <const Fqn extends string>(input: AccessDeclarationInput<AccessGrantAxisDefinition, Fqn>) => AccessGrantAxisHandle<AccessGrantAxisSlug<Fqn>>;
78
+ type AxisSlug<Axis> = Axis extends AccessGrantAxisHandle<infer Slug> ? Slug : Axis extends string ? AccessGrantAxisSlug<Axis> : string;
79
+ /** The slugs of the Grant Axes of a profile. */
80
+ export type AccessProfileAxisSlugs<Axes extends readonly AccessGrantAxisReference[]> = AxisSlug<Axes[number]>;
81
+ /** An Access Profile by handle or by FQN. */
82
+ export type AccessProfileReference = AccessProfileHandle | string;
83
+ export type AccessProfileDefinition<Axes extends readonly AccessGrantAxisReference[] = readonly AccessGrantAxisReference[]> = Readonly<{
84
+ audience: AccessProfileAudience;
85
+ /** Every grant of the profile sets one value for each of these axes; a `server` profile declares none. */
86
+ axes?: Axes;
87
+ /** Required with `admin.grants`; `"all"` grants every profile. */
88
+ canGrant?: "all" | readonly AccessProfileReference[];
89
+ capabilities: readonly AccessCapabilityGrant[];
90
+ lifecycle?: LifecycleOptions;
91
+ }>;
92
+ /** A declared Access Profile and its authored definition. */
93
+ export type AccessProfileHandle<Axes extends readonly AccessGrantAxisReference[] = readonly AccessGrantAxisReference[]> = DeclaredComponent<AccessProfileDeclaration> & Readonly<{
94
+ definition: AccessProfileDefinition<Axes>;
95
+ }>;
96
+ /**
97
+ * Shared authoring and serialized admission invariant (AC-012): a profile
98
+ * whose capabilities reach `admin.grants` at manage declares `canGrant`.
99
+ */
100
+ export declare const canGrantViolation: (profile: Pick<AccessProfileDeclaration, "canGrant" | "capabilities">) => string | undefined;
101
+ /**
102
+ * Shared authoring and serialized admission invariant (ARC-007): an app
103
+ * server credential holds one Tuple per `server` profile, with no axes.
104
+ */
105
+ export declare const serverAxesViolation: (profile: Pick<AccessProfileDeclaration, "audience" | "axes">) => string | undefined;
106
+ /**
107
+ * Declares an Access Profile: capability entries from `access.allow` and the
108
+ * Grant Axes its grants set. A profile never declares a capability inline.
109
+ */
110
+ export declare const declareAccessProfile: <const Axes extends readonly AccessGrantAxisReference[] = readonly []>(input: AccessDeclarationInput<AccessProfileDefinition<Axes>>) => AccessProfileHandle<Axes>;
111
+ /** Names one Knowledge entity by the value of one unique field: `knowledgeEntity({ code: "FR" })`. */
112
+ export declare const knowledgeEntity: (identifier: Readonly<Record<string, string>>) => AccessKnowledgeEntityIdentifier;
113
+ /** The recipient of a declared grant, as authored. */
114
+ export type AccessGranteeInput = Readonly<{
115
+ applicationServer: DeclarationReference<"externalApplication">;
116
+ }> | Readonly<{
117
+ applicationVisitors: DeclarationReference<"externalApplication">;
118
+ }> | Readonly<{
119
+ coverage: AccessGroupCoverage;
120
+ group: AccessGroupReference;
121
+ }> | Readonly<{
122
+ servicePrincipal: DeclarationReference<"servicePrincipal">;
123
+ }> | Readonly<{
124
+ user: Readonly<{
125
+ email: string;
126
+ }>;
127
+ }>;
128
+ /** The most characters of an Access Grant FQN. */
129
+ export declare const accessGrantFqnMaxLength = 320;
130
+ /** Shared authoring and serialized admission invariant of an Access Grant FQN. */
131
+ export declare const accessGrantFqnViolation: (fqn: string) => string | undefined;
132
+ /** Shared authoring and serialized admission invariant of a Knowledge Entity Identifier. */
133
+ export declare const knowledgeEntityIdentifierViolation: (value: AccessKnowledgeEntityIdentifier) => string | undefined;
134
+ type GrantAxes<Profile> = Profile extends AccessProfileHandle<infer Axes> ? [AccessProfileAxisSlugs<Axes>] extends [never] ? Readonly<{
135
+ axes?: never;
136
+ }> : Readonly<{
137
+ axes: Readonly<Record<AccessProfileAxisSlugs<Axes>, AccessKnowledgeEntityIdentifier>>;
138
+ }> : Readonly<{
139
+ axes?: Readonly<Record<string, AccessKnowledgeEntityIdentifier>>;
140
+ }>;
141
+ export type AccessProfileGrantDefinition<Profile extends AccessProfileReference = AccessProfileReference> = Readonly<{
142
+ grantee: AccessGranteeInput;
143
+ lifecycle?: LifecycleOptions;
144
+ profile: Profile;
145
+ }> & GrantAxes<Profile>;
146
+ /** A declared Access Grant. */
147
+ export type AccessProfileGrantHandle = DeclaredComponent<AccessProfileGrantDeclaration>;
148
+ /**
149
+ * Declares a static grant: one recipient, one profile, one Knowledge Entity
150
+ * Identifier per Grant Axis. The manifest FQN is the Access Grant FQN.
151
+ */
152
+ export declare const declareAccessProfileGrant: <const Profile extends AccessProfileReference>(input: AccessDeclarationInput<AccessProfileGrantDefinition<Profile>>) => AccessProfileGrantHandle;
153
+ type AccessMaxPrivilegesDefinition = Readonly<{
154
+ appliesTo: Readonly<{
155
+ apiKeyTemplate: string;
156
+ }> | Readonly<{
157
+ applicationTokens: DeclarationReference<"externalApplication">;
158
+ }>;
159
+ capabilities: readonly AccessCapabilityGrant[];
160
+ lifecycle?: LifecycleOptions;
161
+ }>;
162
+ /** A declared Max Privileges set. */
163
+ export type AccessMaxPrivilegesHandle = DeclaredComponent<AccessMaxPrivilegesDeclaration>;
164
+ /**
165
+ * Declares the capabilities that an app's user tokens or an API key template
166
+ * may use at most, for every user; never granted.
167
+ */
168
+ export declare const declareAccessMaxPrivileges: (input: AccessDeclarationInput<AccessMaxPrivilegesDefinition>) => AccessMaxPrivilegesHandle;
169
+ export {};
@@ -0,0 +1,31 @@
1
+ import type { DeclarationReference, DeclaredComponent } from "../components/authoring-core.js";
2
+ import type { DocumentFolderTarget } from "../components/document-collections.js";
3
+ import type { LifecycleOptions } from "../components/lifecycle.js";
4
+ import type { AccessDeclarationInput } from "./declarations.js";
5
+ import type { AccessDocumentDataOperation, AccessDocumentDataPolicyDeclaration } from "./manifest.js";
6
+ import type { AccessCapabilityRequirement } from "./requirement.js";
7
+ /** A folder of a document collection. */
8
+ export type AccessDocumentFolderInput = Readonly<{
9
+ collection: DeclarationReference<"documentCollection">;
10
+ target: DocumentFolderTarget;
11
+ }>;
12
+ /** The authored definition of a Document Data Policy: a collection or a folder. */
13
+ export type AccessDocumentDataPolicyDefinition = Readonly<{
14
+ capability: AccessCapabilityRequirement;
15
+ lifecycle?: LifecycleOptions;
16
+ operation: AccessDocumentDataOperation;
17
+ }> & (Readonly<{
18
+ collection: DeclarationReference<"documentCollection">;
19
+ folder?: never;
20
+ }> | Readonly<{
21
+ collection?: never;
22
+ folder: AccessDocumentFolderInput;
23
+ }>);
24
+ /** A declared Document Data Policy. */
25
+ export type AccessDocumentDataPolicyHandle = DeclaredComponent<AccessDocumentDataPolicyDeclaration>;
26
+ /**
27
+ * Opens one document collection or folder for one operation; no Grant Axes.
28
+ * `read` opens the current Version of each document, `history` its older
29
+ * Versions, `write` creates, updates and deletes.
30
+ */
31
+ export declare const declareAccessDocumentDataPolicy: (input: AccessDeclarationInput<AccessDocumentDataPolicyDefinition>) => AccessDocumentDataPolicyHandle;
@@ -0,0 +1,62 @@
1
+ import { accessGate } from "./application-gate.js";
2
+ import { allow } from "./capabilities.js";
3
+ import { and, contains, eq, exists, grantAxis, gt, gte, inGroup, inMyGroups, includesMe, isIn, isMe, isNull, lt, lte, neq, not, or, overlaps, resource, startsWith, subject, via } from "./conditions.js";
4
+ import { byCondition, field, map, relation, self, unscoped } from "./knowledge-policy.js";
5
+ import { allOf, anyOf, enters, requires } from "./requirement.js";
6
+ /**
7
+ * The access helpers in one namespace, so that generic names such as `and`,
8
+ * `or` and `eq` do not collide with other exports.
9
+ */
10
+ export declare const access: Readonly<{
11
+ accessGate: typeof accessGate;
12
+ allOf: typeof allOf;
13
+ allow: typeof allow;
14
+ and: typeof and;
15
+ anyOf: typeof anyOf;
16
+ byCondition: typeof byCondition;
17
+ contains: typeof contains;
18
+ enters: typeof enters;
19
+ eq: typeof eq;
20
+ exists: typeof exists;
21
+ field: typeof field;
22
+ grantAxis: typeof grantAxis;
23
+ gt: typeof gt;
24
+ gte: typeof gte;
25
+ inGroup: typeof inGroup;
26
+ inMyGroups: typeof inMyGroups;
27
+ includesMe: typeof includesMe;
28
+ isIn: typeof isIn;
29
+ isMe: typeof isMe;
30
+ isNull: typeof isNull;
31
+ lt: typeof lt;
32
+ lte: typeof lte;
33
+ map: typeof map;
34
+ neq: typeof neq;
35
+ not: typeof not;
36
+ or: typeof or;
37
+ overlaps: typeof overlaps;
38
+ relation: typeof relation;
39
+ requires: typeof requires;
40
+ resource: typeof resource;
41
+ self: typeof self;
42
+ startsWith: typeof startsWith;
43
+ subject: typeof subject;
44
+ unscoped: typeof unscoped;
45
+ via: typeof via;
46
+ }>;
47
+ export type { AccessApplicationCapabilities, AccessGate, ExternalApplicationHandle } from "./application-gate.js";
48
+ export type { AccessAudience, AccessAudienceDeclaration, AccessAudienceGroup } from "./audience.js";
49
+ export { capabilityCatalogNodes } from "./capabilities.js";
50
+ export type { AccessCapabilityArea, AccessCapabilityCatalogNode, AccessCapabilityGrant, AccessCapabilityHandle, AccessCapabilityIdentity, AccessCapabilityKind, AccessCapabilityMode, AccessCapabilityNodeDeclaration, AccessCapabilityNodeInput, AccessCapabilityReference, AccessCapabilityTree, AccessReadManageMode } from "./capabilities.js";
51
+ export type { AccessCondition, AccessConditionComparison, AccessConditionInput, AccessConditionLiteral, AccessConditionOperand, AccessConditionOperandInput, AccessGrantAxisOperand, AccessGrantAxisReference, AccessGroupCoverage, AccessGroupReference, AccessKnowledgeDataConditionHandle, AccessResourceOperand, AccessSubjectOperand } from "./conditions.js";
52
+ export { builtinGroups, coreCapabilities, coreSectionRequirements } from "./core-catalog.js";
53
+ export type { AccessSectionRequirement } from "./core-catalog.js";
54
+ export { accessGrantAxisSlug, declareAccessCapabilities, declareAccessGrantAxis, declareAccessMaxPrivileges, declareAccessProfile, declareAccessProfileGrant, knowledgeEntity } from "./declarations.js";
55
+ export type { AccessCapabilitiesHandle, AccessComponentManifest, AccessDeclarationInput, AccessGranteeInput, AccessGrantAxisHandle, AccessGrantAxisSlug, AccessKnowledgeSchemaReference, AccessMaxPrivilegesHandle, AccessProfileAxisSlugs, AccessProfileDefinition, AccessProfileGrantDefinition, AccessProfileGrantHandle, AccessProfileHandle, AccessProfileReference } from "./declarations.js";
56
+ export { declareAccessDocumentDataPolicy } from "./document-policy.js";
57
+ export type { AccessDocumentDataPolicyDefinition, AccessDocumentDataPolicyHandle, AccessDocumentFolderInput } from "./document-policy.js";
58
+ export { declareAccessKnowledgeDataCondition, declareAccessKnowledgeDataPolicy, declareCoreAccessPolicy, unreadConditionAxes } from "./knowledge-policy.js";
59
+ export type { AccessCorePolicy, AccessKnowledgeDataPolicyDefinition, AccessKnowledgeDataPolicyHandle } from "./knowledge-policy.js";
60
+ export type { AccessCanGrant, AccessCapabilitiesDeclaration, AccessConditionTest, AccessDataOperation, AccessDocumentDataOperation, AccessDocumentDataPolicyDeclaration, AccessDocumentFolder, AccessFieldSelection, AccessGrantableBy, AccessGrantAxisDeclaration, AccessGrantee, AccessKnowledgeDataConditionDeclaration, AccessKnowledgeDataPolicyDeclaration, AccessKnowledgeEntityIdentifier, AccessMaxPrivilegesDeclaration, AccessMaxPrivilegesTarget, AccessPolicyAxis, AccessPolicyPurpose, AccessPrimitiveDeclaration, AccessProfileAudience, AccessProfileDeclaration, AccessProfileGrantDeclaration, AxisBinding } from "./manifest.js";
61
+ export { accessCapabilityMode, evaluateAccessRequirement } from "./requirement.js";
62
+ export type { AccessCapabilityRequirement, AccessEntryRequirement, AccessHeldCapability, AccessRequirement, AccessRequirementLeaf, AccessRequirementResult } from "./requirement.js";
@@ -0,0 +1,87 @@
1
+ import type { DeclaredComponent } from "../components/authoring-core.js";
2
+ import type { LifecycleOptions } from "../components/lifecycle.js";
3
+ import type { AccessCondition, AccessConditionInput, AccessGrantAxisReference, AccessKnowledgeDataConditionHandle } from "./conditions.js";
4
+ import type { AccessDeclarationInput, AccessKnowledgeSchemaReference } from "./declarations.js";
5
+ import type { AccessConditionTest, AccessDataOperation, AccessDocumentDataOperation, AccessFieldSelection, AccessKnowledgeDataPolicyDeclaration, AccessPolicyAxis, AccessPolicyPurpose, AxisBinding } from "./manifest.js";
6
+ import type { AccessCapabilityRequirement } from "./requirement.js";
7
+ /** The axis value is the record's field value (one or many entity ids). */
8
+ export declare const field: (key: string) => AxisBinding;
9
+ /** The axis value is the record itself, by its entity id. */
10
+ export declare const self: () => AxisBinding;
11
+ /** The axis value is the `field` of the record that the reference field `key` points at. */
12
+ export declare const relation: (key: string, target: string) => AxisBinding;
13
+ /** Binds a Grant Axis to the record through a field, the record itself or a relation. */
14
+ export declare const map: (axis: AccessGrantAxisReference, binding: AxisBinding) => AccessPolicyAxis;
15
+ /** Binds a Grant Axis that the policy `where` reads through `grantAxis(axis)`. */
16
+ export declare const byCondition: (axis: AccessGrantAxisReference) => AccessPolicyAxis;
17
+ /** Ignores a Grant Axis for this data. */
18
+ export declare const unscoped: (axis: AccessGrantAxisReference) => AccessPolicyAxis;
19
+ /** The authored definition of a Knowledge Data Policy. */
20
+ export type AccessKnowledgeDataPolicyDefinition = Readonly<{
21
+ /** One rule per Grant Axis; an axis of a Tuple that no rule binds drops the Tuple (fail closed). */
22
+ axes?: readonly AccessPolicyAxis[];
23
+ capability: AccessCapabilityRequirement;
24
+ lifecycle?: LifecycleOptions;
25
+ operation: AccessDataOperation;
26
+ /** Ignores every axis that `axes` does not bind. */
27
+ otherAxes?: "unscoped";
28
+ /** Defaults to `access`; `administration` fills the administration slot. */
29
+ purpose?: AccessPolicyPurpose;
30
+ /** Read policies only; every field without it. */
31
+ readableFields?: AccessFieldSelection;
32
+ target: AccessKnowledgeSchemaReference;
33
+ where?: AccessConditionInput;
34
+ /** Write policies only; every field without it. */
35
+ writableFields?: AccessFieldSelection;
36
+ }>;
37
+ /** The field keys of a selection. */
38
+ export declare const selectionKeys: (selection: AccessFieldSelection | undefined) => readonly string[];
39
+ /**
40
+ * The `byCondition` axes that no `grantAxis` operand of `where` reads, in
41
+ * declaration order. `via` hops are read through. A `{ condition }` reference
42
+ * may read any axis: while one is present, the result is empty (undecided).
43
+ * Axes are compared as given, so manifest FQNs and stored ids both work.
44
+ */
45
+ export declare const unreadConditionAxes: (axes: readonly AccessPolicyAxis[], where?: AccessCondition) => readonly string[];
46
+ /**
47
+ * Shared authoring and serialized admission invariant of a Knowledge Data
48
+ * Policy: one rule per axis, a `byCondition` axis read by the `where`, field
49
+ * selections that match the operation.
50
+ */
51
+ export declare const knowledgeDataPolicyViolation: (policy: Pick<AccessKnowledgeDataPolicyDeclaration, "axes" | "operation" | "purpose" | "readableFields" | "where" | "writableFields">) => string | undefined;
52
+ /** A declared Knowledge Data Policy. */
53
+ export type AccessKnowledgeDataPolicyHandle = DeclaredComponent<AccessKnowledgeDataPolicyDeclaration>;
54
+ /**
55
+ * Declares a Knowledge Data Policy on one schema and one operation. An
56
+ * unknown field key of the target schema handle fails the package build.
57
+ */
58
+ export declare const declareAccessKnowledgeDataPolicy: (input: AccessDeclarationInput<AccessKnowledgeDataPolicyDefinition>) => AccessKnowledgeDataPolicyHandle;
59
+ type AccessKnowledgeDataConditionDefinition = Readonly<{
60
+ lifecycle?: LifecycleOptions;
61
+ target: AccessKnowledgeSchemaReference;
62
+ /** Test cases that `accessTest` runs with the in-memory evaluator. */
63
+ tests?: readonly AccessConditionTest[];
64
+ where: AccessConditionInput;
65
+ }>;
66
+ /** Declares a reusable, tested row predicate; its handle is a condition. */
67
+ export declare const declareAccessKnowledgeDataCondition: (input: AccessDeclarationInput<AccessKnowledgeDataConditionDefinition>) => AccessKnowledgeDataConditionHandle;
68
+ /**
69
+ * A core policy of the core built-in package; every axis is unscoped. A
70
+ * Documents policy may also open the older Versions with `history`.
71
+ */
72
+ export type AccessCorePolicy = Readonly<{
73
+ capability: AccessCapabilityRequirement;
74
+ /** Write only: the policy may write host-owned fields. */
75
+ includesHostOwned?: boolean;
76
+ /** `tenant` reaches every schema; `admin` and `default` fill an empty slot. */
77
+ kind: "admin" | "default" | "tenant";
78
+ }> & (Readonly<{
79
+ data: "datasets" | "knowledge";
80
+ operation: AccessDataOperation;
81
+ }> | Readonly<{
82
+ data: "documents";
83
+ operation: AccessDocumentDataOperation;
84
+ }>);
85
+ /** Declares a core policy; only the core built-in package declares them. */
86
+ export declare const declareCoreAccessPolicy: (policy: AccessCorePolicy) => AccessCorePolicy;
87
+ export {};
@@ -0,0 +1,161 @@
1
+ import type { PackagePrimitiveBase } from "../components/base.js";
2
+ import type { DocumentFolderTarget } from "../components/document-collections.js";
3
+ import type { LifecycleOptions } from "../components/lifecycle.js";
4
+ import type { JsonObject } from "../foundation/json.js";
5
+ import type { AccessCapabilityGrant, AccessCapabilityNodeDeclaration } from "./capabilities.js";
6
+ import type { AccessCondition, AccessGroupCoverage } from "./conditions.js";
7
+ import type { AccessCapabilityRequirement } from "./requirement.js";
8
+ /** Who may grant a profile that holds a node of this declaration (Grant Authority). */
9
+ export type AccessGrantableBy = "admins" | "holders";
10
+ /** A package's capability nodes; the declaration FQN is the code of its Read/Manage root. */
11
+ export type AccessCapabilitiesDeclaration = PackagePrimitiveBase<"accessCapabilities"> & Readonly<{
12
+ grantableBy: AccessGrantableBy;
13
+ lifecycle?: LifecycleOptions;
14
+ nodes: Readonly<Record<string, AccessCapabilityNodeDeclaration>>;
15
+ }>;
16
+ /** A perimeter dimension on one Knowledge entity schema; grants key its value by `accessGrantAxisSlug(fqn)`. */
17
+ export type AccessGrantAxisDeclaration = PackagePrimitiveBase<"accessGrantAxis"> & Readonly<{
18
+ /** The single-valued self-relation field that orders the hierarchy. */
19
+ hierarchy?: string;
20
+ label: string;
21
+ lifecycle?: LifecycleOptions;
22
+ /** FQN of the Knowledge entity schema. */
23
+ target: string;
24
+ }>;
25
+ export type AccessProfileAudience = "anonymous" | "server" | "user";
26
+ /** `"all"` grants every profile (D1); otherwise the FQNs of the grantable profiles. */
27
+ export type AccessCanGrant = "all" | readonly string[];
28
+ /** A set of capabilities plus the Grant Axes that every grant of it sets. */
29
+ export type AccessProfileDeclaration = PackagePrimitiveBase<"accessProfile"> & Readonly<{
30
+ audience: AccessProfileAudience;
31
+ /** FQNs of the Grant Axes. */
32
+ axes?: readonly string[];
33
+ canGrant?: AccessCanGrant;
34
+ capabilities: readonly AccessCapabilityGrant[];
35
+ lifecycle?: LifecycleOptions;
36
+ }>;
37
+ /** Names one Knowledge entity by the value of one unique field; resolved on write only. */
38
+ export type AccessKnowledgeEntityIdentifier = Readonly<{
39
+ knowledgeEntity: Readonly<{
40
+ field: string;
41
+ value: string;
42
+ }>;
43
+ }>;
44
+ /** The recipient of a declared grant. */
45
+ export type AccessGrantee = Readonly<{
46
+ applicationServer: string;
47
+ }> | Readonly<{
48
+ applicationVisitors: string;
49
+ }> | Readonly<{
50
+ coverage: AccessGroupCoverage;
51
+ group: Readonly<{
52
+ fqn: string;
53
+ }>;
54
+ }> | Readonly<{
55
+ servicePrincipal: string;
56
+ }> | Readonly<{
57
+ user: Readonly<{
58
+ email: string;
59
+ }>;
60
+ }>;
61
+ /** A declared Access Grant: its FQN is the Access Grant FQN. */
62
+ export type AccessProfileGrantDeclaration = PackagePrimitiveBase<"accessProfileGrant"> & Readonly<{
63
+ /** One Axis Value per Grant Axis of the profile, keyed by axis slug. */
64
+ axes?: Readonly<Record<string, AccessKnowledgeEntityIdentifier>>;
65
+ grantee: AccessGrantee;
66
+ lifecycle?: LifecycleOptions;
67
+ /** FQN of the Access Profile. */
68
+ profile: string;
69
+ }>;
70
+ /** An allow list (`["name"]`) or a deny list (`{ except: ["salary"] }`). */
71
+ export type AccessFieldSelection = readonly string[] | Readonly<{
72
+ except: readonly string[];
73
+ }>;
74
+ /** How a field value of a record yields the entity ids an axis matches. */
75
+ export type AxisBinding = Readonly<{
76
+ field: string;
77
+ }> | Readonly<{
78
+ relation: Readonly<{
79
+ field: string;
80
+ key: string;
81
+ }>;
82
+ }> | Readonly<{
83
+ self: true;
84
+ }>;
85
+ /** The rule of one Grant Axis in a policy. */
86
+ export type AccessPolicyAxis = Readonly<{
87
+ axis: string;
88
+ byCondition: true;
89
+ }> | Readonly<{
90
+ axis: string;
91
+ map: AxisBinding;
92
+ }> | Readonly<{
93
+ axis: string;
94
+ unscoped: true;
95
+ }>;
96
+ export type AccessDataOperation = "read" | "write";
97
+ /**
98
+ * The operation of a Document Data Policy: `read` opens the current Version,
99
+ * `history` the older Versions, `write` creates, updates and deletes.
100
+ */
101
+ export type AccessDocumentDataOperation = "history" | "read" | "write";
102
+ export type AccessPolicyPurpose = "access" | "administration";
103
+ /** A Knowledge Data Policy: one schema, one operation, one capability. */
104
+ export type AccessKnowledgeDataPolicyDeclaration = PackagePrimitiveBase<"accessKnowledgeDataPolicy"> & Readonly<{
105
+ axes?: readonly AccessPolicyAxis[];
106
+ capability: AccessCapabilityRequirement;
107
+ lifecycle?: LifecycleOptions;
108
+ operation: AccessDataOperation;
109
+ otherAxes?: "unscoped";
110
+ purpose: AccessPolicyPurpose;
111
+ readableFields?: AccessFieldSelection;
112
+ /** FQN of the Knowledge entity schema. */
113
+ target: string;
114
+ where?: AccessCondition;
115
+ writableFields?: AccessFieldSelection;
116
+ }>;
117
+ /** One test case of a Knowledge Data Condition. */
118
+ export type AccessConditionTest = Readonly<{
119
+ expected: boolean;
120
+ name: string;
121
+ record: JsonObject;
122
+ subject?: JsonObject;
123
+ }>;
124
+ /** A reusable, tested row predicate for a policy `where`. */
125
+ export type AccessKnowledgeDataConditionDeclaration = PackagePrimitiveBase<"accessKnowledgeDataCondition"> & Readonly<{
126
+ lifecycle?: LifecycleOptions;
127
+ /** FQN of the Knowledge entity schema. */
128
+ target: string;
129
+ tests?: readonly AccessConditionTest[];
130
+ where: AccessCondition;
131
+ }>;
132
+ /** A folder of one document collection. */
133
+ export type AccessDocumentFolder = Readonly<{
134
+ collection: string;
135
+ target: DocumentFolderTarget;
136
+ }>;
137
+ /** A Document Data Policy: one collection or folder, one operation, no axes. */
138
+ export type AccessDocumentDataPolicyDeclaration = PackagePrimitiveBase<"accessDocumentDataPolicy"> & Readonly<{
139
+ capability: AccessCapabilityRequirement;
140
+ lifecycle?: LifecycleOptions;
141
+ operation: AccessDocumentDataOperation;
142
+ }> & (Readonly<{
143
+ collection: string;
144
+ folder?: never;
145
+ }> | Readonly<{
146
+ collection?: never;
147
+ folder: AccessDocumentFolder;
148
+ }>);
149
+ /** What Max Privileges cap: the user tokens of an app, or the keys of an API key template. */
150
+ export type AccessMaxPrivilegesTarget = Readonly<{
151
+ apiKeyTemplate: string;
152
+ }> | Readonly<{
153
+ applicationTokens: string;
154
+ }>;
155
+ /** The capabilities that a token may use at most; never granted. */
156
+ export type AccessMaxPrivilegesDeclaration = PackagePrimitiveBase<"accessMaxPrivileges"> & Readonly<{
157
+ appliesTo: AccessMaxPrivilegesTarget;
158
+ capabilities: readonly AccessCapabilityGrant[];
159
+ lifecycle?: LifecycleOptions;
160
+ }>;
161
+ export type AccessPrimitiveDeclaration = AccessCapabilitiesDeclaration | AccessDocumentDataPolicyDeclaration | AccessGrantAxisDeclaration | AccessKnowledgeDataConditionDeclaration | AccessKnowledgeDataPolicyDeclaration | AccessMaxPrivilegesDeclaration | AccessProfileDeclaration | AccessProfileGrantDeclaration;
@@ -0,0 +1,114 @@
1
+ import type { ReadValue } from "../package/readers.js";
2
+ import type { AccessCapabilityGrant, AccessCapabilityNodeDeclaration } from "./capabilities.js";
3
+ import type { AccessCondition } from "./conditions.js";
4
+ import type { AccessConditionTest, AccessDocumentDataPolicyDeclaration, AccessFieldSelection, AccessGrantee, AccessKnowledgeEntityIdentifier, AccessMaxPrivilegesTarget, AccessPolicyAxis } from "./manifest.js";
5
+ import type { AccessCapabilityRequirement } from "./requirement.js";
6
+ /** The serialized capability nodes below an app gate, a Switch. */
7
+ export declare const applicationCapabilityNodes: ReadValue<Readonly<Record<string, AccessCapabilityNodeDeclaration>>>;
8
+ /** Serialized admission readers of the access component kinds. */
9
+ export declare const accessPrimitives: {
10
+ accessCapabilities: ReadValue<Readonly<{
11
+ description?: string;
12
+ displayName: string;
13
+ fqn: string;
14
+ icon?: string;
15
+ kind: "accessCapabilities";
16
+ tags?: readonly string[];
17
+ version: string;
18
+ }> & Readonly<{
19
+ grantableBy: import("./manifest.js").AccessGrantableBy;
20
+ lifecycle?: import("../index.js").LifecycleOptions;
21
+ nodes: Readonly<Record<string, AccessCapabilityNodeDeclaration>>;
22
+ }> & import("../index.js").JsonObject>;
23
+ accessDocumentDataPolicy: ReadValue<AccessDocumentDataPolicyDeclaration>;
24
+ accessGrantAxis: ReadValue<Readonly<{
25
+ description?: string;
26
+ displayName: string;
27
+ fqn: string;
28
+ icon?: string;
29
+ kind: "accessGrantAxis";
30
+ tags?: readonly string[];
31
+ version: string;
32
+ }> & Readonly<{
33
+ hierarchy?: string;
34
+ label: string;
35
+ lifecycle?: import("../index.js").LifecycleOptions;
36
+ target: string;
37
+ }> & import("../index.js").JsonObject>;
38
+ accessKnowledgeDataCondition: ReadValue<Readonly<{
39
+ description?: string;
40
+ displayName: string;
41
+ fqn: string;
42
+ icon?: string;
43
+ kind: "accessKnowledgeDataCondition";
44
+ tags?: readonly string[];
45
+ version: string;
46
+ }> & Readonly<{
47
+ lifecycle?: import("../index.js").LifecycleOptions;
48
+ target: string;
49
+ tests?: readonly AccessConditionTest[];
50
+ where: AccessCondition;
51
+ }> & import("../index.js").JsonObject>;
52
+ accessKnowledgeDataPolicy: ReadValue<Readonly<{
53
+ description?: string;
54
+ displayName: string;
55
+ fqn: string;
56
+ icon?: string;
57
+ kind: "accessKnowledgeDataPolicy";
58
+ tags?: readonly string[];
59
+ version: string;
60
+ }> & Readonly<{
61
+ axes?: readonly AccessPolicyAxis[];
62
+ capability: AccessCapabilityRequirement;
63
+ lifecycle?: import("../index.js").LifecycleOptions;
64
+ operation: import("./manifest.js").AccessDataOperation;
65
+ otherAxes?: "unscoped";
66
+ purpose: import("./manifest.js").AccessPolicyPurpose;
67
+ readableFields?: AccessFieldSelection;
68
+ target: string;
69
+ where?: AccessCondition;
70
+ writableFields?: AccessFieldSelection;
71
+ }> & import("../index.js").JsonObject>;
72
+ accessMaxPrivileges: ReadValue<Readonly<{
73
+ description?: string;
74
+ displayName: string;
75
+ fqn: string;
76
+ icon?: string;
77
+ kind: "accessMaxPrivileges";
78
+ tags?: readonly string[];
79
+ version: string;
80
+ }> & Readonly<{
81
+ appliesTo: AccessMaxPrivilegesTarget;
82
+ capabilities: readonly AccessCapabilityGrant[];
83
+ lifecycle?: import("../index.js").LifecycleOptions;
84
+ }> & import("../index.js").JsonObject>;
85
+ accessProfile: ReadValue<Readonly<{
86
+ description?: string;
87
+ displayName: string;
88
+ fqn: string;
89
+ icon?: string;
90
+ kind: "accessProfile";
91
+ tags?: readonly string[];
92
+ version: string;
93
+ }> & Readonly<{
94
+ audience: import("./manifest.js").AccessProfileAudience;
95
+ axes?: readonly string[];
96
+ canGrant?: import("./manifest.js").AccessCanGrant;
97
+ capabilities: readonly AccessCapabilityGrant[];
98
+ lifecycle?: import("../index.js").LifecycleOptions;
99
+ }> & import("../index.js").JsonObject>;
100
+ accessProfileGrant: ReadValue<Readonly<{
101
+ description?: string;
102
+ displayName: string;
103
+ fqn: string;
104
+ icon?: string;
105
+ kind: "accessProfileGrant";
106
+ tags?: readonly string[];
107
+ version: string;
108
+ }> & Readonly<{
109
+ axes?: Readonly<Record<string, AccessKnowledgeEntityIdentifier>>;
110
+ grantee: AccessGrantee;
111
+ lifecycle?: import("../index.js").LifecycleOptions;
112
+ profile: string;
113
+ }> & import("../index.js").JsonObject>;
114
+ };