@resistdesign/voltra 0.0.0-alpha.0

package/README.md

@@ -0,0 +1,86 @@
+# Voltra
+
+![Voltra Logo Inverse 2025.svg](https://docs.voltra.app/images/Voltra%20Logo%20Inverse%202025.svg "Voltra")
+
+<style>
+
+.nav-button {
+  background: linear-gradient(145deg, #b285c9, #5e3a76); color: white; border: none; border-radius: 50px; padding:
+15px 30px; font-size: 18px; font-weight: bold; box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1), 0
+8px 15px rgba(0, 0, 0, 0.1); transition: all 0.3s ease; cursor: pointer; text-decoration: none; display: inline-block;"
+onmouseover="this.style.background='linear-gradient(145deg, #a374b9, #4d2d61)'; this.style.boxShadow='0 6px 8px rgba(0,
+0, 0, 0.2), 0 12px 20px rgba(0, 0, 0, 0.2)'; this.style.transform='translateY(-2px)';" onmouseout="
+this.style.background='linear-gradient(145deg, #b285c9, #5e3a76)'; this.style.boxShadow='0 4px 6px rgba(0, 0, 0, 0.1), 0
+8px 15px rgba(0, 0, 0, 0.1)'; this.style.transform='translateY(0)';
+}
+
+</style>
+
+------------
+
+<a class="nav-button" href="https://docs.voltra.app">See The Demos</a>
+
+## Usage
+
+### Install
+
+```bash
+yarn add @resistdesign/voltra
+```
+
+## With our powers combined!
+
+<table style="border: 0 solid black;">
+<tbody>
+<tr>
+<td>Voltra is a state-of-the-art platform designed to streamline the creation of cloud infrastructure and complex web
+applications. It features a robust API with RPC, CORS, and versatile authentication options, alongside dynamic app
+development tools like TypeScript-driven form generation. The platform excels in Infrastructure as Code (IaC), offering
+features like chainable stacks and comprehensive parameter support. Its intuitive interface simplifies the addition of
+databases, storage, authentication, and functions through easy-to-use packs. Furthermore, Voltra enhances development
+workflows with advanced state management, and a smart, lightweight routing system for React
+front-end apps.</td>
+<td><img src="https://docs.voltra.app/images/Voltra%20Robot%20Coming%20Together.png" style="width: 200em;" /></td>
+</tr>
+</tbody>
+</table>
+
+## Features
+
+| API                                                                         | App                                           | IaC                                                           |
+|-----------------------------------------------------------------------------|-----------------------------------------------|---------------------------------------------------------------|
+| RPC                                                                         | Easy Layout                                   | Full Parameter Support: Groups/Labels/Types/etc...            |
+| Auth: Public/Secured/Role Based                                             | State Management                              | Packs: Easy to add Database/Storage/Auth/Functions/etc...     |
+| Routing: Nesting/Handlers/Injected Handlers                                 | Routing: Param Handlers/Parallel Routes/Hooks | Utilities: Patching Stacks/Constants/Standard Includes/etc... |
+| ORM: TypeScript Type Driven Auto-generated Data Contexts with Relationships |                                               | Typed Build Spec Creation                                     |
+|                                                                             |                                               | Typed Resource Parameters                                     |
+
+## Releasing
+
+Voltra publishes npm packages from GitHub Releases. The release tag is used verbatim
+as the npm package version, so it must be valid SemVer without a leading `v`.
+
+### Stable releases
+
+Use tags like:
+
+```
+3.0.0
+```
+
+### Pre-releases (alpha, beta, rc)
+
+Use tags like:
+
+```
+3.0.0-alpha.0
+3.0.0-beta.1
+3.0.0-rc.1
+```
+
+When the GitHub Release is marked as a prerelease, the npm publish step uses the
+`next` dist-tag instead of `latest`. Consumers can install prereleases with:
+
+```bash
+npm install @resistdesign/voltra@next
+```

package/package.json

@@ -0,0 +1,103 @@
+{
+  "name": "@resistdesign/voltra",
+  "version": "0.0.0-alpha.0",
+  "description": "With our powers combined!",
+  "homepage": "https://voltra.app",
+  "repository": "git@github.com:resistdesign/voltra.git",
+  "author": "Resist Design",
+  "license": "MIT",
+  "bin": {
+    "vest": "src/common/Testing/CLI.ts"
+  },
+  "files": [
+    "src/**/*",
+    "README.md",
+    "package.json",
+    "!src/iac/types/CloudFormationResourceSpecification.js"
+  ],
+  "scripts": {
+    "build": "tsc && yarn prep-dist",
+    "test": "ts-node src/common/Testing/CLI.ts ./src/**/*.spec.json",
+    "test:gen": "ts-node src/common/Testing/CLI.ts --generate ./src/**/*.spec.json",
+    "doc": "typedoc",
+    "doc:dev": "typedoc --watch",
+    "doc-to-site": "cp -r ./docs site-dist/app/",
+    "prep-dist": "cp package.json dist/ && cp README.md dist/ && cp .npmignore dist/",
+    "site:build:app": "parcel build site/app/index.html --dist-dir site-dist --target app && yarn finalize-site",
+    "site:build:api": "parcel build site/api/index.ts --target api --dist-dir site-dist --no-source-maps --no-optimize --no-scope-hoist",
+    "site:build:iac": "ts-node ./site/iac/index.ts",
+    "start": "parcel site/app/index.html --host docs-local.demo.voltra.app --dist-dir site-dist/app --https",
+    "finalize-site": "yarn doc && yarn doc-to-site && cp CNAME site-dist/app/ && cp -r ./images site-dist/app/",
+    "iac:types:gen": "ts-node ./src/iac/types/generate.ts"
+  },
+  "dependencies": {
+    "@aws-sdk/client-dynamodb": "^3.490.0",
+    "@aws-sdk/client-s3": "^3.490.0",
+    "@aws-sdk/s3-request-presigner": "^3.490.0",
+    "@aws-sdk/util-dynamodb": "^3.490.0",
+    "@picocss/pico": "^2.1.1",
+    "ace-builds": "^1.32.3",
+    "fast-glob": "^3.3.3",
+    "picocolors": "^1.1.1",
+    "react": "^18.2.0",
+    "react-ace": "^10.1.0",
+    "react-dom": "^18.3.1",
+    "styled-components": "^6.1.8",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.3",
+    "uuid": "^11.0.3",
+    "yaml": "^2.3.4"
+  },
+  "devDependencies": {
+    "@parcel/packager-raw-url": "2.13.3",
+    "@parcel/packager-ts": "2.13.3",
+    "@parcel/transformer-inline-string": "2.13.3",
+    "@parcel/transformer-typescript-types": "2.11.0",
+    "@parcel/transformer-webmanifest": "2.13.3",
+    "@types/cfn-response": "^1.0.8",
+    "@types/node": "^20.11.6",
+    "@types/react-dom": "^18.3.0",
+    "@types/styled-components": "^5.1.34",
+    "aws-lambda": "^1.0.7",
+    "aws-sdk": "^2.1545.0",
+    "buffer": "^5.5.0||^6.0.0",
+    "cfn-response": "^1.0.1",
+    "parcel": "^2.13.3",
+    "prettier": "^3.6.2",
+    "process": "^0.11.10",
+    "svgo": "^3",
+    "ts-morph": "^24.0.0",
+    "typedoc": "^0.25.8",
+    "typedoc-material-theme": "^1.0.2"
+  },
+  "targets": {
+    "app": {
+      "context": "browser",
+      "engines": {
+        "browsers": [
+          "last 2 version",
+          "not dead",
+          "> 0.2%"
+        ]
+      },
+      "includeNodeModules": true,
+      "outputFormat": "commonjs",
+      "isLibrary": false,
+      "scopeHoist": false
+    },
+    "api": {
+      "context": "node",
+      "engines": {
+        "node": ">=20"
+      },
+      "outputFormat": "commonjs",
+      "includeNodeModules": true,
+      "isLibrary": false,
+      "scopeHoist": false
+    }
+  },
+  "@parcel/transformer-js": {
+    "inlineFS": true,
+    "inlineEnvironment": true
+  }
+}

package/src/api/DataAccessControl.d.ts

@@ -0,0 +1,85 @@
+import { LiteralValue } from "../common/TypeParsing/TypeInfo";
+/**
+ * The possible types of a data access control (DAC) constraint.
+ * */
+export declare enum DACConstraintType {
+    ALLOW = "ALLOW",
+    DENY = "DENY"
+}
+/**
+ * A data access control (DAC) constraint.
+ * */
+export type DACConstraint = {
+    type: DACConstraintType;
+    resourcePath: LiteralValue[];
+    pathIsPrefix?: boolean;
+};
+/**
+ * The primary properties for a data access control (DAC) role.
+ * */
+export type BaseDACRole = {
+    childRoleIds?: string[];
+    constraints: DACConstraint[];
+};
+/**
+ * A data access control (DAC) role which has been stored and can be accessed by an `id`.
+ * */
+export type DACRole = {
+    id: string;
+} & BaseDACRole;
+/**
+ * The result of a data access control (DAC) check.
+ * */
+export type DACAccessResult = {
+    allowed: boolean;
+    denied: boolean;
+};
+/**
+ * The result of a data access control (DAC) check for a data item.
+ * */
+export type DACDataItemResourceAccessResultMap = DACAccessResult & {
+    fieldsResources?: Record<string, DACAccessResult>;
+};
+/**
+ * The result of matching a DAC path to a resource path.
+ * */
+export type DACPathMatchResults = {
+    prefixMatch: boolean;
+    exactMatch: boolean;
+};
+/**
+ * The prototype of a DAC wildcard signifier.
+ * */
+export declare const WILDCARD_SIGNIFIER_PROTOTYPE: Record<string, string>;
+/**
+ * Check if a given DAC path part value is a DAC wildcard signifier.
+ * */
+export declare const getValueIsWildcardSignifier: (value: any) => boolean;
+/**
+ * Check if a given DAC path matches a given resource path.
+ *
+ * Includes checking if the DAC path is a prefix of the
+ * resource path and if the DAC path is an exact match of
+ * the resource path.
+ *
+ * The DAC path can include wildcard signifier objects at
+ * various indices in order to facilitate dynamic matches
+ * and grouping by common resource aspects.
+ * */
+export declare const getDACPathsMatch: (dacPath: LiteralValue[], resourcePath: LiteralValue[]) => DACPathMatchResults;
+/**
+ * Get the flattened constraints of a DAC role.
+ * */
+export declare const getFlattenedDACConstraints: (role: DACRole, getDACRoleById: (id: string) => DACRole, 
+/**
+ * SECURITY: Don't use this if you want realtime role resolution.
+ * */
+dacRoleCache?: Record<string, DACRole>) => DACConstraint[];
+/**
+ * Get the access to a given resource for a given DAC role.
+ * */
+export declare const getResourceAccessByDACRole: (fullResourcePath: LiteralValue[], role: DACRole, getDACRoleById: (id: string) => DACRole, dacRoleCache?: Record<string, DACRole>) => DACAccessResult;
+/**
+ * Merge multiple DAC access results.
+ * */
+export declare const mergeDACAccessResults: (...results: DACAccessResult[]) => DACAccessResult;

package/src/api/DataAccessControl.js

@@ -0,0 +1,159 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeDACAccessResults = exports.getResourceAccessByDACRole = exports.getFlattenedDACConstraints = exports.getDACPathsMatch = exports.getValueIsWildcardSignifier = exports.WILDCARD_SIGNIFIER_PROTOTYPE = exports.DACConstraintType = void 0;
+/**
+ * The possible types of a data access control (DAC) constraint.
+ * */
+var DACConstraintType;
+(function (DACConstraintType) {
+    DACConstraintType["ALLOW"] = "ALLOW";
+    DACConstraintType["DENY"] = "DENY";
+})(DACConstraintType || (exports.DACConstraintType = DACConstraintType = {}));
+/**
+ * The prototype of a DAC wildcard signifier.
+ * */
+exports.WILDCARD_SIGNIFIER_PROTOTYPE = {
+    WILD_CARD: "*",
+};
+/**
+ * Check if a given DAC path part value is a DAC wildcard signifier.
+ * */
+const getValueIsWildcardSignifier = (value) => {
+    if (typeof value === "object" && value !== null) {
+        return Object.keys(exports.WILDCARD_SIGNIFIER_PROTOTYPE).every((key) => value[key] === exports.WILDCARD_SIGNIFIER_PROTOTYPE[key]);
+    }
+    return false;
+};
+exports.getValueIsWildcardSignifier = getValueIsWildcardSignifier;
+/**
+ * Check if a given DAC path matches a given resource path.
+ *
+ * Includes checking if the DAC path is a prefix of the
+ * resource path and if the DAC path is an exact match of
+ * the resource path.
+ *
+ * The DAC path can include wildcard signifier objects at
+ * various indices in order to facilitate dynamic matches
+ * and grouping by common resource aspects.
+ * */
+const getDACPathsMatch = (dacPath, resourcePath) => {
+    const results = {
+        prefixMatch: false,
+        exactMatch: false,
+    };
+    let allDACPartsMatch = true;
+    for (let i = 0; i < dacPath.length; i++) {
+        const part = dacPath[i];
+        const resourcePart = resourcePath[i];
+        if (!(0, exports.getValueIsWildcardSignifier)(part) && part !== resourcePart) {
+            allDACPartsMatch = false;
+            break;
+        }
+    }
+    if (allDACPartsMatch) {
+        results.prefixMatch = true;
+    }
+    if (dacPath.length !== resourcePath.length) {
+        const lastDACPart = dacPath[dacPath.length - 1];
+        const lastDACPartIsWildcard = (0, exports.getValueIsWildcardSignifier)(lastDACPart);
+        results.exactMatch = results.prefixMatch && lastDACPartIsWildcard;
+    }
+    else if (results.prefixMatch) {
+        results.exactMatch = true;
+    }
+    return results;
+};
+exports.getDACPathsMatch = getDACPathsMatch;
+/**
+ * Get the flattened constraints of a DAC role.
+ * */
+const getFlattenedDACConstraints = (role, getDACRoleById, 
+/**
+ * SECURITY: Don't use this if you want realtime role resolution.
+ * */
+dacRoleCache) => {
+    const { childRoleIds = [], constraints = [] } = role;
+    let flattenedConstraints = [...constraints];
+    for (const cRI of childRoleIds) {
+        let childRole;
+        if (dacRoleCache && dacRoleCache[cRI]) {
+            childRole = dacRoleCache[cRI];
+        }
+        else {
+            childRole = getDACRoleById(cRI);
+            if (dacRoleCache) {
+                dacRoleCache[cRI] = childRole;
+            }
+        }
+        flattenedConstraints = [
+            ...flattenedConstraints,
+            ...(0, exports.getFlattenedDACConstraints)(childRole, getDACRoleById, dacRoleCache),
+        ];
+    }
+    return flattenedConstraints;
+};
+exports.getFlattenedDACConstraints = getFlattenedDACConstraints;
+/**
+ * Get the access to a given resource for a given DAC role.
+ * */
+const getResourceAccessByDACRole = (fullResourcePath, role, getDACRoleById, dacRoleCache) => {
+    const flattenedConstraints = (0, exports.getFlattenedDACConstraints)(role, getDACRoleById, dacRoleCache);
+    let allowed = false, denied = false, lastAllowedPath = [], lastDeniedPath = [];
+    for (const constraint of flattenedConstraints) {
+        const { type, resourcePath: dacPath, pathIsPrefix } = constraint;
+        const { prefixMatch: dacPathIsPrefixOfResourcePath, exactMatch: dacPathIsExactMatch, } = (0, exports.getDACPathsMatch)(dacPath, fullResourcePath);
+        if (pathIsPrefix) {
+            if (dacPathIsPrefixOfResourcePath) {
+                if (type === DACConstraintType.ALLOW) {
+                    allowed = true;
+                    lastAllowedPath = dacPath;
+                    // IMPORTANT: Calculate specificity.
+                    if (lastAllowedPath.length > lastDeniedPath.length) {
+                        denied = false;
+                    }
+                }
+                else {
+                    denied = true;
+                    lastDeniedPath = dacPath;
+                    // IMPORTANT: Calculate specificity.
+                    if (lastDeniedPath.length > lastAllowedPath.length) {
+                        allowed = false;
+                    }
+                }
+            }
+        }
+        else {
+            if (dacPathIsExactMatch) {
+                lastAllowedPath = dacPath;
+                lastDeniedPath = dacPath;
+                if (type === DACConstraintType.ALLOW) {
+                    allowed = true;
+                }
+                else {
+                    denied = true;
+                }
+            }
+        }
+    }
+    return { allowed, denied };
+};
+exports.getResourceAccessByDACRole = getResourceAccessByDACRole;
+/**
+ * Merge multiple DAC access results.
+ * */
+const mergeDACAccessResults = (...results) => {
+    let newResult = {
+        allowed: false,
+        denied: false,
+    };
+    for (const r of results) {
+        const { allowed: rAllowed, denied: rDenied } = r;
+        const { allowed: nAllowed, denied: nDenied } = newResult;
+        newResult = {
+            allowed: rAllowed || nAllowed,
+            denied: rDenied || nDenied,
+        };
+    }
+    return newResult;
+};
+exports.mergeDACAccessResults = mergeDACAccessResults;

package/src/api/ORM/DACUtils.d.ts

@@ -0,0 +1,60 @@
+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.
+ * */
+export declare const getORMDACResourcePath: (prefixPath: LiteralValue[] | undefined, operation: ORMOperation) => LiteralValue[];
+/**
+ * Get the DAC Resource Path for a given item type.
+ * */
+export declare const getItemTypeDACResourcePath: (prefixPath: LiteralValue[] | undefined, operation: ORMOperation, typeName: string) => LiteralValue[];
+/**
+ * Get the DAC Resource Path for a given data item.
+ * */
+export declare const getDataItemDACResourcePath: (prefixPath: LiteralValue[] | undefined, operation: ORMOperation, typeName: string, primaryKeyValue: LiteralValue) => LiteralValue[];
+/**
+ * Get the DAC Resource Path for a given item relationship origin.
+ * */
+export declare const getItemRelationshipOriginDACResourcePath: (prefixPath: LiteralValue[] | undefined, operation: ORMOperation, itemRelationshipOrigin: ItemRelationshipOriginInfo) => LiteralValue[];
+/**
+ * Get the DAC Resource Path for a given item relationship.
+ * */
+export declare const getItemRelationshipDACResourcePath: (prefixPath: LiteralValue[] | undefined, operation: ORMOperation, itemRelationship: BaseItemRelationshipInfo) => LiteralValue[];
+/**
+ * Get the DAC Resource Path for a given data item with a specific field value.
+ * */
+export declare const getDataItemFieldValueDACResourcePath: (itemPath: LiteralValue[], fieldName: string, fieldValue: LiteralValue) => LiteralValue[];
+/**
+ * Get a DAC Constraint for a given item type.
+ * */
+export declare const getItemTypeDACConstraint: (prefixPath: LiteralValue[] | undefined, operation: ORMOperation, typeName: string, constraintType: DACConstraintType) => DACConstraint;
+/**
+ * Get a DAC Constraint for a given item relationship origin.
+ * */
+export declare const getItemRelationshipOriginDACConstraint: (prefixPath: LiteralValue[] | undefined, operation: ORMOperation, itemRelationshipOrigin: ItemRelationshipOriginInfo, constraintType: DACConstraintType) => DACConstraint;
+/**
+ * Get a DAC Role for a given item type.
+ * */
+export declare const getItemTypeDACRole: (prefixPath: LiteralValue[] | undefined, operation: ORMOperation, typeName: string, constraintType: DACConstraintType) => BaseDACRole;
+/**
+ * Get a DAC Role for a given item type.
+ * */
+export declare const getItemRelationshipOriginDACRole: (prefixPath: LiteralValue[] | undefined, operation: ORMOperation, itemRelationshipOrigin: ItemRelationshipOriginInfo, constraintType: DACConstraintType) => BaseDACRole;
+/**
+ * Get a DAC Role encompassing all operations for all types and relationships for an ORM with the given DAC prefix.
+ * */
+export declare const getFullORMDACRole: (prefixPath: LiteralValue[] | undefined, constraintType: DACConstraintType) => BaseDACRole;
+/**
+ * Get the access to a given data item resource for a given DAC role.
+ * */
+export declare const getDACRoleHasAccessToDataItem: (prefixPath: LiteralValue[], operation: ORMOperation, typeName: string, dataItem: Partial<TypeInfoDataItem>, typeInfo: TypeInfo, role: DACRole, getDACRoleById: (id: string) => DACRole, 
+/**
+ * SECURITY: Don't use this if you want realtime role resolution.
+ * */
+dacRoleCache?: Record<string, DACRole>) => DACDataItemResourceAccessResultMap;
+/**
+ * Merge multiple DAC data item resource access result maps.
+ * */
+export declare const mergeDACDataItemResourceAccessResultMaps: (...maps: DACDataItemResourceAccessResultMap[]) => DACDataItemResourceAccessResultMap;