@cedar-policy/cedar-wasm 3.2.0 → 3.2.2

package/README.md

@@ -4,8 +4,7 @@ An implementation of various cedar functions to enable developers to write types
 
 ## Installing
 
-Installing is simple, just run `npm i @cedar-policy/cedar-wasm` or install with whatever your favorite package manager is.
-
+Installing is simple, just run `npm i @cedar-policy/cedar-wasm --save` or install with whatever your favorite package manager is.
 
 ## Loading in webpack 5:
 
@@ -133,3 +132,20 @@ import('@cedar-policy/cedar-wasm').then(mod => {
 });
 ```
 
+## Alternate loading strategies
+
+If for some reason you cannot use es modules, we provide alternate sub-packages `web` and `nodejs` (defined as `exports` in the root package.json).
+
+The `nodejs` subpackage uses `fs` and CommonJS modules. To use it, you can import it like so:
+
+```
+const cedar = require('@cedar-policy/cedar-wasm/nodejs')
+```
+
+The `web` subpackage exposes an `initSync` function that you can use to load Cedar in scenarios where you want to load the wasm binary async for whatever reason. Using the `web` subpackage may also be necessary with some `jest` setups. Here's how you use the `web` subpackage:
+
+```
+const wasmBuffer = ... // `fetch` it or use `fs` to read it from `node_modules` in jest setupTests
+import * as cedarJsBindings from '@cedar-policy/cedar-wasm/web';
+cedarJsBindings.initSync(wasmBuffer);
+```

package/esm/README.md

@@ -0,0 +1,151 @@
+# cedar-wasm
+
+An implementation of various cedar functions to enable developers to write typescript and javascript applications using Cedar and wasm.
+
+## Installing
+
+Installing is simple, just run `npm i @cedar-policy/cedar-wasm --save` or install with whatever your favorite package manager is.
+
+## Loading in webpack 5:
+
+Minimal package.json for webpack including dev server:
+
+```
+{
+  "name": "webpack-ts-tester",
+  "version": "1.0.0",
+  "description": "", 
+  "private": true,
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "build": "webpack",
+    "dev": "webpack serve"
+  },  
+  "keywords": [], 
+  "author": "", 
+  "license": "ISC",
+  "dependencies": {
+    "@cedar-policy/cedar-wasm": "3.2.0"
+  },  
+  "devDependencies": {
+    "ts-loader": "^9.5.1",
+    "typescript": "^5.4.5",
+    "webpack": "^5.91.0",
+    "webpack-cli": "^5.1.4",
+    "webpack-dev-server": "^5.0.4"
+  }
+}
+```
+
+Minimal tsconfig:
+
+```
+{
+  "compilerOptions": {
+    "outDir": "./dist/",
+    "noImplicitAny": true,
+    "module": "es2020",
+    "target": "es5",
+    "jsx": "react",
+    "allowJs": true,
+    "moduleResolution": "node"
+  }
+}
+```
+
+Configure webpack.config.js:
+
+```
+const path = require('path');
+
+module.exports = { 
+  mode: 'development', // change this to suit you
+  entry: './src/index.ts',
+  module: {
+    rules: [
+      {   
+        test: /\.tsx?$/,
+        use: 'ts-loader',
+        exclude: /node_modules/,
+      },  
+    ],  
+  },  
+  resolve: {
+    extensions: ['.tsx', '.ts', '.js'],
+  },  
+  output: {
+    filename: 'bundle.js',
+    path: path.resolve(__dirname, 'dist'),
+  },  
+  experiments: {
+    asyncWebAssembly: true, // enables wasm support in webpack
+  },  
+  devServer: {
+    static: {
+      directory: path.join(__dirname, 'dist'),
+    },  
+    compress: true,
+    port: 8000,
+  }
+};
+```
+
+Finally, load the code from your `index.ts` file. We recommend dynamic imports:
+
+```
+import('@cedar-policy/cedar-wasm').then(mod => {
+  // cache it globally here or invoke functions like mod.getCedarVersion();
+});
+```
+
+
+
+## Loading in vite 5:
+
+Starting from the vite typescript template, install these two dependencies to enable wasm:
+
+```
+npm i --save-dev vite-plugin-top-level-await vite-plugin-wasm
+```
+
+Then add those two plugins to your vite config in `vite.config.js`:
+
+```
+import wasm from 'vite-plugin-wasm';
+import topLevelAwait from 'vite-plugin-top-level-await';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [
+    wasm(),
+    topLevelAwait()
+  ]
+});
+
+```
+
+Finally, load the code. We recommend dynamic imports:
+
+```
+import('@cedar-policy/cedar-wasm').then(mod => {
+  // cache it globally here or invoke functions like mod.getCedarVersion();
+});
+```
+
+## Alternate loading strategies
+
+If for some reason you cannot use es modules, we provide alternate sub-packages `web` and `nodejs` (defined as `exports` in the root package.json).
+
+The `nodejs` subpackage uses `fs` and CommonJS modules. To use it, you can import it like so:
+
+```
+const cedar = require('@cedar-policy/cedar-wasm/nodejs')
+```
+
+The `web` subpackage exposes an `initSync` function that you can use to load Cedar in scenarios where you want to load the wasm binary async for whatever reason. Using the `web` subpackage may also be necessary with some `jest` setups. Here's how you use the `web` subpackage:
+
+```
+const wasmBuffer = ... // `fetch` it or use `fs` to read it from `node_modules` in jest setupTests
+import * as cedarJsBindings from '@cedar-policy/cedar-wasm/web';
+cedarJsBindings.initSync(wasmBuffer);
+```

package/{cedar_wasm.d.ts → esm/cedar_wasm.d.ts}

@@ -71,6 +71,31 @@ export type CheckParseResult = { type: "success" } | { type: "error"; errors: st
 
 export type FormattingResult = { type: "success"; formatted_policy: string } | { type: "error"; errors: string[] };
 
+export type Schema = { human: string } | { json: SchemaJson };
+
+export type PolicySet = string | Record<string, string>;
+
+export interface SourceLocation {
+    start: number;
+    end: number;
+}
+
+export interface SourceLabel extends SourceLocation {
+    label: string | null;
+}
+
+export type Severity = "advice" | "warning" | "error";
+
+export interface DetailedError {
+    message: string;
+    help: string | null;
+    code: string | null;
+    url: string | null;
+    severity: Severity | null;
+    sourceLocations?: SourceLabel[];
+    related?: DetailedError[];
+}
+
 export type ValidationAnswer = { type: "failure"; errors: DetailedError[]; warnings: DetailedError[] } | { type: "success"; validationErrors: ValidationError[]; validationWarnings: ValidationError[]; otherWarnings: DetailedError[] };
 
 export interface ValidationError {
@@ -116,9 +141,9 @@ export interface EntityUIDStrings {
 }
 
 export interface AuthorizationCall {
-    principal: string|{type: string, id: string};
-    action: string|{type: string, id: string};
-    resource: string|{type: string, id: string};
+    principal: {type: string, id: string};
+    action: {type: string, id: string};
+    resource: {type: string, id: string};
     context: Record<string, CedarValueJson>;
     schema?: Schema;
     enableRequestValidation?: boolean;
@@ -142,31 +167,6 @@ export interface Response {
     diagnostics: Diagnostics;
 }
 
-export type Schema = { human: string } | { json: JsonValueWithNoDuplicateKeys };
-
-export type PolicySet = string | Record<string, string>;
-
-export interface SourceLocation {
-    start: number;
-    end: number;
-}
-
-export interface SourceLabel extends SourceLocation {
-    label: string | null;
-}
-
-export type Severity = "advice" | "warning" | "error";
-
-export interface DetailedError {
-    message: string;
-    help: string | null;
-    code: string | null;
-    url: string | null;
-    severity: Severity | null;
-    sourceLocations?: SourceLabel[];
-    related?: DetailedError[];
-}
-
 export type SchemaTypeVariant = { type: "String" } | { type: "Long" } | { type: "Boolean" } | { type: "Set"; element: SchemaType } | { type: "Record"; attributes: Record<SmolStr, TypeOfAttribute>; additionalAttributes: boolean } | { type: "Entity"; name: Name } | { type: "Extension"; name: Id };
 
 export type SchemaType = SchemaTypeVariant | { type: Name };
@@ -201,15 +201,7 @@ export interface NamespaceDefinition {
     actions: Record<SmolStr, ActionType>;
 }
 
-export type Schema = Record<string, NamespaceDefinition>;
-
-export type Decision = "Allow" | "Deny";
-
-export interface EntityJson {
-    uid: EntityUidJson;
-    attrs: Record<string, CedarValueJson>;
-    parents: EntityUidJson[];
-}
+export type SchemaJson = Record<string, NamespaceDefinition>;
 
 export type EntityUidJson = { __expr: string } | { __entity: TypeAndId } | TypeAndId;
 
@@ -225,6 +217,29 @@ export interface TypeAndId {
 
 export type CedarValueJson = { __expr: string } | { __entity: TypeAndId } | { __extn: FnAndArg } | boolean | number | string | CedarValueJson[] | { [key: string]: CedarValueJson } | null;
 
+export type Var = "principal" | "action" | "resource" | "context";
+
+export type Effect = "permit" | "forbid";
+
+export type Clause = { kind: "when"; body: Expr } | { kind: "unless"; body: Expr };
+
+export interface Policy {
+    effect: Effect;
+    principal: PrincipalConstraint;
+    action: ActionConstraint;
+    resource: ResourceConstraint;
+    conditions: Clause[];
+    annotations?: Record<string, string>;
+}
+
+export interface EntityJson {
+    uid: EntityUidJson;
+    attrs: Record<string, CedarValueJson>;
+    parents: EntityUidJson[];
+}
+
+export type Decision = "Allow" | "Deny";
+
 export type ActionInConstraint = { entity: EntityUidJson } | { entities: EntityUidJson[] };
 
 export interface PrincipalOrResourceIsConstraint {
@@ -248,21 +263,6 @@ export type ExprNoExt = { Value: CedarValueJson } | { Var: Var } | { Slot: strin
 
 export type Expr = ExprNoExt | ExtFuncCall;
 
-export type Var = "principal" | "action" | "resource" | "context";
-
-export type Clause = { kind: "when"; body: Expr } | { kind: "unless"; body: Expr };
-
-export interface Policy {
-    effect: Effect;
-    principal: PrincipalConstraint;
-    action: ActionConstraint;
-    resource: ResourceConstraint;
-    conditions: Clause[];
-    annotations?: Record<string, string>;
-}
-
-export type Effect = "permit" | "forbid";
-
 type SmolStr = string;
 type Name = string;
 type Id = string;

package/esm/cedar_wasm_bg.wasm.d.ts

@@ -0,0 +1,19 @@
+/* tslint:disable */
+/* eslint-disable */
+export const memory: WebAssembly.Memory;
+export function policyTextFromJson(a: number, b: number): number;
+export function policyTextToJson(a: number, b: number): number;
+export function checkParsePolicySet(a: number, b: number): number;
+export function checkParseTemplate(a: number, b: number): number;
+export function checkParseSchema(a: number, b: number): number;
+export function checkParseEntities(a: number, b: number, c: number, d: number): number;
+export function checkParseContext(a: number, b: number, c: number, d: number, e: number, f: number): number;
+export function formatPolicies(a: number, b: number, c: number, d: number): number;
+export function getCedarVersion(a: number): void;
+export function isAuthorized(a: number): number;
+export function validate(a: number): number;
+export function __wbindgen_malloc(a: number, b: number): number;
+export function __wbindgen_realloc(a: number, b: number, c: number, d: number): number;
+export function __wbindgen_add_to_stack_pointer(a: number): number;
+export function __wbindgen_free(a: number, b: number, c: number): void;
+export function __wbindgen_exn_store(a: number): void;

package/esm/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@cedar-policy/cedar-wasm",
+  "description": "Wasm bindings and typescript types for Cedar lib",
+  "version": "3.2.2",
+  "license": "Apache-2.0",
+  "files": [
+    "cedar_wasm_bg.wasm",
+    "cedar_wasm_bg.wasm.d.ts",
+    "cedar_wasm.js",
+    "cedar_wasm_bg.js",
+    "cedar_wasm.d.ts"
+  ],
+  "module": "cedar_wasm.js",
+  "types": "cedar_wasm.d.ts",
+  "sideEffects": [
+    "./cedar_wasm.js",
+    "./snippets/*"
+  ],
+  "type": "module"
+}

package/nodejs/README.md

@@ -0,0 +1,151 @@
+# cedar-wasm
+
+An implementation of various cedar functions to enable developers to write typescript and javascript applications using Cedar and wasm.
+
+## Installing
+
+Installing is simple, just run `npm i @cedar-policy/cedar-wasm --save` or install with whatever your favorite package manager is.
+
+## Loading in webpack 5:
+
+Minimal package.json for webpack including dev server:
+
+```
+{
+  "name": "webpack-ts-tester",
+  "version": "1.0.0",
+  "description": "", 
+  "private": true,
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "build": "webpack",
+    "dev": "webpack serve"
+  },  
+  "keywords": [], 
+  "author": "", 
+  "license": "ISC",
+  "dependencies": {
+    "@cedar-policy/cedar-wasm": "3.2.0"
+  },  
+  "devDependencies": {
+    "ts-loader": "^9.5.1",
+    "typescript": "^5.4.5",
+    "webpack": "^5.91.0",
+    "webpack-cli": "^5.1.4",
+    "webpack-dev-server": "^5.0.4"
+  }
+}
+```
+
+Minimal tsconfig:
+
+```
+{
+  "compilerOptions": {
+    "outDir": "./dist/",
+    "noImplicitAny": true,
+    "module": "es2020",
+    "target": "es5",
+    "jsx": "react",
+    "allowJs": true,
+    "moduleResolution": "node"
+  }
+}
+```
+
+Configure webpack.config.js:
+
+```
+const path = require('path');
+
+module.exports = { 
+  mode: 'development', // change this to suit you
+  entry: './src/index.ts',
+  module: {
+    rules: [
+      {   
+        test: /\.tsx?$/,
+        use: 'ts-loader',
+        exclude: /node_modules/,
+      },  
+    ],  
+  },  
+  resolve: {
+    extensions: ['.tsx', '.ts', '.js'],
+  },  
+  output: {
+    filename: 'bundle.js',
+    path: path.resolve(__dirname, 'dist'),
+  },  
+  experiments: {
+    asyncWebAssembly: true, // enables wasm support in webpack
+  },  
+  devServer: {
+    static: {
+      directory: path.join(__dirname, 'dist'),
+    },  
+    compress: true,
+    port: 8000,
+  }
+};
+```
+
+Finally, load the code from your `index.ts` file. We recommend dynamic imports:
+
+```
+import('@cedar-policy/cedar-wasm').then(mod => {
+  // cache it globally here or invoke functions like mod.getCedarVersion();
+});
+```
+
+
+
+## Loading in vite 5:
+
+Starting from the vite typescript template, install these two dependencies to enable wasm:
+
+```
+npm i --save-dev vite-plugin-top-level-await vite-plugin-wasm
+```
+
+Then add those two plugins to your vite config in `vite.config.js`:
+
+```
+import wasm from 'vite-plugin-wasm';
+import topLevelAwait from 'vite-plugin-top-level-await';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [
+    wasm(),
+    topLevelAwait()
+  ]
+});
+
+```
+
+Finally, load the code. We recommend dynamic imports:
+
+```
+import('@cedar-policy/cedar-wasm').then(mod => {
+  // cache it globally here or invoke functions like mod.getCedarVersion();
+});
+```
+
+## Alternate loading strategies
+
+If for some reason you cannot use es modules, we provide alternate sub-packages `web` and `nodejs` (defined as `exports` in the root package.json).
+
+The `nodejs` subpackage uses `fs` and CommonJS modules. To use it, you can import it like so:
+
+```
+const cedar = require('@cedar-policy/cedar-wasm/nodejs')
+```
+
+The `web` subpackage exposes an `initSync` function that you can use to load Cedar in scenarios where you want to load the wasm binary async for whatever reason. Using the `web` subpackage may also be necessary with some `jest` setups. Here's how you use the `web` subpackage:
+
+```
+const wasmBuffer = ... // `fetch` it or use `fs` to read it from `node_modules` in jest setupTests
+import * as cedarJsBindings from '@cedar-policy/cedar-wasm/web';
+cedarJsBindings.initSync(wasmBuffer);
+```