@open-policy-agent/opa-wasm
    TypeScript icon, indicating that this package has built-in type declarations

    1.7.0 • Public • Published

    Work in Progress -- Contributions welcome!!

    Open Policy Agent WebAssemby NPM Module

    This is the source for the @open-policy-agent/opa-wasm NPM module which is a small SDK for using WebAssembly (wasm) compiled Open Policy Agent Rego policies.

    Getting Started

    Install the module

    npm install @open-policy-agent/opa-wasm
    

    Usage

    There are only a couple of steps required to start evaluating the policy.

    Import the module

    const { loadPolicy } = require("@open-policy-agent/opa-wasm");

    Load the policy

    loadPolicy(policyWasm);

    The loadPolicy function returns a Promise with the loaded policy. Typically this means loading it in an async function like:

    const policy = await loadPolicy(policyWasm);

    Or something like:

    loadPolicy(policyWasm).then((policy) => {
      // evaluate or save the policy
    }, (error) => {
      console.error("Failed to load policy: " + error);
    });

    The policyWasm needs to be either the raw byte array of the compiled policy Wasm file, or a WebAssembly module.

    For example:

    const fs = require("fs");
    
    const policyWasm = fs.readFileSync("policy.wasm");

    Alternatively the bytes can be pulled in remotely from a fetch or in some cases (like CloudFlare Workers) the Wasm binary can be loaded directly into the javascript context through external APIs.

    Evaluate the Policy

    The loaded policy object returned from loadPolicy() has a couple of important APIs for policy evaluation:

    setData(data) -- Provide an external data document for policy evaluation.

    • data MUST be a serializable object or ArrayBuffer, which assumed to be a well-formed stringified JSON

    evaluate(input) -- Evaluates the policy using any loaded data and the supplied input document.

    • input parameter MAY be an object, primitive literal or ArrayBuffer, which assumed to be a well-formed stringified JSON

    ArrayBuffer supported in the APIs above as a performance optimisation feature, given that either network or file system provided contents can easily be represented as ArrayBuffer in a very performant way.

    Example:

    input = '{"path": "/", "role": "admin"}';
    
    loadPolicy(policyWasm).then((policy) => {
      resultSet = policy.evaluate(input);
      if (resultSet == null) {
        console.error("evaluation error");
      }
      if (resultSet.length == 0) {
        console.log("undefined");
      }
      console.log("allowed = " + allowed[0].result);
    }).catch((error) => {
      console.error("Failed to load policy: ", error);
    });

    For any opa build created WASM binaries the result set, when defined, will contain a result key with the value of the compiled entrypoint. See https://www.openpolicyagent.org/docs/latest/wasm/ for more details.

    Writing the policy

    See https://www.openpolicyagent.org/docs/latest/how-do-i-write-policies/

    Compiling the policy

    Either use the Compile REST API or opa build CLI tool.

    For example, with OPA v0.20.5+:

    opa build -t wasm -e example/allow example.rego

    Which is compiling the example.rego policy file with the result set to data.example.allow. The result will be an OPA bundle with the policy.wasm binary included. See ./examples for a more comprehensive example.

    See opa build --help for more details.

    Development

    Lint and Format checks

    This project is using Deno's lint and formatter tools in CI. With deno installed locally, the same checks can be invoked using npm:

    • npm run lint
    • npm run fmt -- this will fix the formatting
    • npm run fmt:check -- this happens in CI

    All of these operate on git-tracked files, so make sure you've committed the code you'd like to see checked. Alternatively, you can invoke deno lint my_new_file.js directly, too.

    Build

    The published package provides four different entrypoints for consumption:

    1. A CommonJS module for consumption with older versions of Node or those using require():
      const { loadPolicy } = require("@open-policy-agent/opa-wasm");
    2. An ESM module for consumption with newer versions of Node:
      import { loadPolicy } from "@open-policy-agent/opa-wasm";
    3. An ESM module for consumption in modern browsers (this will contain all dependencies already bundled and can be used standalone).
      <script type="module">
      import opa from 'https://unpkg.com/@open-policy-agent/opa-wasm@latest/dist/opa-wasm-browser.esm.js';
      opa.loadPolicy(...);
      </script>
    4. A script for consumption in all browsers (this will export an opa global variable).
      <script src="https://unpkg.com/@open-policy-agent/opa-wasm@latest/dist/opa-wasm-browser.js"></script>
      <script>
      opa.loadPolicy(...);
      </script>

    The browser builds are generated in the ./build.sh script and use esbuild. All exports are defined in the exports field in the package.json file. More detials on how these work are described in the Conditional Exports documentation.

    For TypeScript projects we also generate an opa.d.ts declaration file that will give correct typings and is also defined under the types field in the package.json.

    Install

    npm i @open-policy-agent/opa-wasm

    DownloadsWeekly Downloads

    34,519

    Version

    1.7.0

    License

    Apache-2.0

    Unpacked Size

    898 kB

    Total Files

    23

    Last publish

    Collaborators

    • patrick-styra
    • styrainc
    • srenatus