@resistdesign/voltra 3.0.0-alpha.2 → 3.0.0-alpha.21

package/api/ORM/DACUtils.d.ts

@@ -0,0 +1,270 @@
+/**
+ * @packageDocumentation
+ *
+ * DAC path and constraint helpers for ORM resources. These helpers build
+ * resource paths for types, items, and relationships so DAC rules can be
+ * defined consistently across CRUD and relationship operations.
+ *
+ * Example: allow reads on a type.
+ * ```ts
+ * import { DACConstraintType } from "../DataAccessControl";
+ * import { TypeOperation } from "../../common/TypeParsing/TypeInfo";
+ * import { getItemTypeDACConstraint } from "./DACUtils";
+ *
+ * const allowBooks = getItemTypeDACConstraint(
+ *   ["orm"],
+ *   TypeOperation.READ,
+ *   "Book",
+ *   DACConstraintType.ALLOW,
+ * );
+ * ```
+ */
+import { LiteralValue, TypeInfo, TypeInfoDataItem } from "../../common/TypeParsing/TypeInfo";
+import { ORMOperation } from "../../common/TypeInfoORM";
+import { BaseDACRole, DACConstraint, DACConstraintType, DACDataItemResourceAccessResultMap, DACRole } from "../DataAccessControl";
+import { BaseItemRelationshipInfo, ItemRelationshipOriginInfo } from "../../common/ItemRelationshipInfoTypes";
+/**
+ * Get the DAC Resource Path for a given operation performed using an ORM with the given DAC prefix.
+ * @returns Resource path for the ORM operation.
+ * */
+export declare const getORMDACResourcePath: (
+/**
+ * Path prefix identifying the ORM scope.
+ */
+prefixPath: LiteralValue[] | undefined, 
+/**
+ * ORM operation name to append to the path.
+ */
+operation: ORMOperation) => LiteralValue[];
+/**
+ * Get the DAC Resource Path for a given item type.
+ * @returns Resource path for the item type.
+ * */
+export declare const getItemTypeDACResourcePath: (
+/**
+ * Path prefix identifying the ORM scope.
+ */
+prefixPath: LiteralValue[] | undefined, 
+/**
+ * ORM operation name to append to the path.
+ */
+operation: ORMOperation, 
+/**
+ * Type name to append to the path.
+ */
+typeName: string) => LiteralValue[];
+/**
+ * Get the DAC Resource Path for a given data item.
+ * @returns Resource path for the data item.
+ * */
+export declare const getDataItemDACResourcePath: (
+/**
+ * Path prefix identifying the ORM scope.
+ */
+prefixPath: LiteralValue[] | undefined, 
+/**
+ * ORM operation name to append to the path.
+ */
+operation: ORMOperation, 
+/**
+ * Type name to append to the path.
+ */
+typeName: string, 
+/**
+ * Primary field value for the item.
+ */
+primaryKeyValue: LiteralValue) => LiteralValue[];
+/**
+ * Get the DAC Resource Path for a given item relationship origin.
+ * @returns Resource path for the relationship origin.
+ * */
+export declare const getItemRelationshipOriginDACResourcePath: (
+/**
+ * Path prefix identifying the ORM scope.
+ */
+prefixPath: LiteralValue[] | undefined, 
+/**
+ * ORM operation name to append to the path.
+ */
+operation: ORMOperation, 
+/**
+ * Relationship origin describing the source type and field.
+ */
+itemRelationshipOrigin: ItemRelationshipOriginInfo) => LiteralValue[];
+/**
+ * Get the DAC Resource Path for a given item relationship.
+ * @returns Resource path for the relationship instance.
+ * */
+export declare const getItemRelationshipDACResourcePath: (
+/**
+ * Path prefix identifying the ORM scope.
+ */
+prefixPath: LiteralValue[] | undefined, 
+/**
+ * ORM operation name to append to the path.
+ */
+operation: ORMOperation, 
+/**
+ * Relationship info containing source/target ids.
+ */
+itemRelationship: BaseItemRelationshipInfo) => LiteralValue[];
+/**
+ * Get the DAC Resource Path for a given data item with a specific field value.
+ * @returns Resource path for the field value.
+ * */
+export declare const getDataItemFieldValueDACResourcePath: (
+/**
+ * Base item resource path.
+ */
+itemPath: LiteralValue[], 
+/**
+ * Field name to append to the path.
+ */
+fieldName: string, 
+/**
+ * Field value to append to the path.
+ */
+fieldValue: LiteralValue) => LiteralValue[];
+/**
+ * Get a DAC Constraint for a given item type.
+ * @returns DAC constraint scoped to the type.
+ * */
+export declare const getItemTypeDACConstraint: (
+/**
+ * Path prefix identifying the ORM scope.
+ */
+prefixPath: LiteralValue[] | undefined, 
+/**
+ * ORM operation name to append to the path.
+ */
+operation: ORMOperation, 
+/**
+ * Type name to constrain.
+ */
+typeName: string, 
+/**
+ * Allow/deny constraint type.
+ */
+constraintType: DACConstraintType) => DACConstraint;
+/**
+ * Get a DAC Constraint for a given item relationship origin.
+ * @returns DAC constraint scoped to the relationship origin.
+ * */
+export declare const getItemRelationshipOriginDACConstraint: (
+/**
+ * Path prefix identifying the ORM scope.
+ */
+prefixPath: LiteralValue[] | undefined, 
+/**
+ * ORM operation name to append to the path.
+ */
+operation: ORMOperation, 
+/**
+ * Relationship origin describing the source type and field.
+ */
+itemRelationshipOrigin: ItemRelationshipOriginInfo, 
+/**
+ * Allow/deny constraint type.
+ */
+constraintType: DACConstraintType) => DACConstraint;
+/**
+ * Get a DAC Role for a given item type.
+ * @returns DAC role with a single type constraint.
+ * */
+export declare const getItemTypeDACRole: (
+/**
+ * Path prefix identifying the ORM scope.
+ */
+prefixPath: LiteralValue[] | undefined, 
+/**
+ * ORM operation name to constrain.
+ */
+operation: ORMOperation, 
+/**
+ * Type name to constrain.
+ */
+typeName: string, 
+/**
+ * Allow/deny constraint type.
+ */
+constraintType: DACConstraintType) => BaseDACRole;
+/**
+ * Get a DAC Role for a given item type.
+ * @returns DAC role with a single relationship-origin constraint.
+ * */
+export declare const getItemRelationshipOriginDACRole: (
+/**
+ * Path prefix identifying the ORM scope.
+ */
+prefixPath: LiteralValue[] | undefined, 
+/**
+ * ORM operation name to constrain.
+ */
+operation: ORMOperation, 
+/**
+ * Relationship origin describing the source type and field.
+ */
+itemRelationshipOrigin: ItemRelationshipOriginInfo, 
+/**
+ * Allow/deny constraint type.
+ */
+constraintType: DACConstraintType) => BaseDACRole;
+/**
+ * Get a DAC Role encompassing all operations for all types and relationships for an ORM with the given DAC prefix.
+ * @returns DAC role that covers all operations under the prefix.
+ * */
+export declare const getFullORMDACRole: (
+/**
+ * Path prefix identifying the ORM scope.
+ */
+prefixPath: LiteralValue[] | undefined, 
+/**
+ * Allow/deny constraint type.
+ */
+constraintType: DACConstraintType) => BaseDACRole;
+/**
+ * Get the access to a given data item resource for a given DAC role.
+ * @returns Access result map for the item and its fields.
+ * */
+export declare const getDACRoleHasAccessToDataItem: (
+/**
+ * Path prefix identifying the ORM scope.
+ */
+prefixPath: LiteralValue[], 
+/**
+ * ORM operation to evaluate.
+ */
+operation: ORMOperation, 
+/**
+ * Type name for the item.
+ */
+typeName: string, 
+/**
+ * Item to check access for.
+ */
+dataItem: Partial<TypeInfoDataItem>, 
+/**
+ * Type info describing fields and primary key.
+ */
+typeInfo: TypeInfo, 
+/**
+ * DAC role being evaluated.
+ */
+role: DACRole, 
+/**
+ * Lookup helper used to resolve roles by id.
+ */
+getDACRoleById: (id: string) => Promise<DACRole>, 
+/**
+ * SECURITY: Don't use this if you want realtime role resolution.
+ * */
+dacRoleCache?: Record<string, DACRole>) => Promise<DACDataItemResourceAccessResultMap>;
+/**
+ * Merge multiple DAC data item resource access result maps.
+ * @returns Merged access result map.
+ * */
+export declare const mergeDACDataItemResourceAccessResultMaps: (
+/**
+ * Result maps to merge into a single access map.
+ */
+...maps: DACDataItemResourceAccessResultMap[]) => DACDataItemResourceAccessResultMap;

package/api/ORM/ListItemUtils.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @packageDocumentation
+ *
+ * Utilities for list operations that wrap a driver with optional filtering and
+ * transformation. This is useful when you want client-side filtering but still
+ * reuse the driver paging contract.
+ */
+import { DataItemDBDriver } from "./drivers";
+import { TypeInfoDataItem } from "../../common/TypeParsing/TypeInfo";
+import { ListItemsConfig, ListItemsResults } from "../../common/SearchTypes";
+/**
+ * Execute a list items request against a data item driver.
+ *
+ * Notes:
+ * - If a filter is supplied, selected fields are not forwarded to the driver
+ *   to ensure the filter sees full items.
+ * - Transform runs after filter and before the response is returned.
+ * @returns List results with filtered/transformed items and cursor.
+ */
+export declare const executeDriverListItems: (
+/**
+ * Driver used to list items.
+ */
+driver: DataItemDBDriver<any, any>, 
+/**
+ * List configuration passed to the driver.
+ */
+config: ListItemsConfig, 
+/**
+ * Optional client-side filter predicate.
+ */
+filter?: (item: Partial<TypeInfoDataItem>) => boolean | Promise<boolean>, 
+/**
+ * Optional transform applied to each included item.
+ */
+transform?: (item: Partial<TypeInfoDataItem>) => Partial<TypeInfoDataItem> | Promise<Partial<TypeInfoDataItem>>, 
+/**
+ * Optional field selection passed to the driver when no filter is used.
+ */
+selectedFields?: (keyof TypeInfoDataItem)[]) => Promise<ListItemsResults<Partial<TypeInfoDataItem>>>;

package/api/ORM/ORMRouteMap.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @packageDocumentation
+ *
+ * Route map helpers that expose Type Info ORM operations over the Router layer.
+ * Use {@link getTypeInfoORMRouteMap} to bind ORM methods to route paths, with
+ * optional DAC enforcement and shared auth configuration.
+ *
+ * Example wiring:
+ * ```ts
+ * import { getTypeInfoORMRouteMap } from "./ORMRouteMap";
+ * import { addRouteMapToRouteMap } from "../Router";
+ *
+ * const ormRoutes = getTypeInfoORMRouteMap({ typeInfoMap, getDriver });
+ * const routeMap = addRouteMapToRouteMap({}, ormRoutes, "orm");
+ * ```
+ */
+import { BaseTypeInfoORMServiceConfig, TypeInfoORMDACConfig } from "./TypeInfoORMService";
+import { AuthInfo, RouteAuthConfig, RouteMap } from "../Router/Types";
+import { TypeInfoORMAPI } from "../../common/TypeInfoORM";
+/**
+ * A collection of errors that can occur when creating or using a Type Info ORM Route Map.
+ * */
+export declare enum TYPE_INFO_ORM_ROUTE_MAP_ERRORS {
+    MISSING_ACCESSING_ROLE = "MISSING_ACCESSING_ROLE",
+    MISSING_ACCESSING_ROLE_GETTER = "MISSING_ACCESSING_ROLE_GETTER"
+}
+/**
+ * A map of Type Info ORM API paths to method names.
+ * */
+export declare const TYPE_INFO_ORM_API_PATH_METHOD_NAME_MAP: Record<string, keyof TypeInfoORMAPI>;
+/**
+ * Get a route map for a Type Info ORM service.
+ *
+ * When DAC is enabled, `getAccessingRoleId` is required so each request can
+ * resolve the accessing role id. If omitted, the route map throws
+ * {@link TYPE_INFO_ORM_ROUTE_MAP_ERRORS.MISSING_ACCESSING_ROLE_GETTER}.
+ * @returns Route map binding API paths to ORM handlers.
+ */
+export declare const getTypeInfoORMRouteMap: (
+/**
+ * Base ORM service configuration for drivers and type info.
+ */
+config: BaseTypeInfoORMServiceConfig, 
+/**
+ * Optional DAC configuration excluding the accessing role.
+ */
+dacConfig?: TypeInfoORMDACConfig, 
+/**
+ * Optional getter to resolve the accessing role id from auth info.
+ */
+getAccessingRoleId?: (authInfo: AuthInfo) => string, 
+/**
+ * Optional route-level auth configuration.
+ */
+authConfig?: RouteAuthConfig) => RouteMap;