@parsifal-m/backstage-plugin-opa-node 0.1.0

package/README.md

@@ -0,0 +1,84 @@
+# Backstage Plugin OPA Node
+
+This package provides a Node.js service for integrating Open Policy Agent (OPA) with Backstage backend modules and plugins.
+
+Its a nice way to secure your backend routes using OPA!
+
+## Pre-requisites
+
+Simply run the yarn install command to add the package to your plugin:
+
+```bash
+yarn add @parsifal-m/backstage-plugin-opa-node
+```
+
+Add the dependency in your `plugin.ts` or `module.ts` file:
+
+```ts
+import { opaService } from '@parsifal-m/backstage-plugin-opa-node';
+
+export const yourPlugin = createBackendPlugin({
+  pluginId: 'your-plugin-id',
+  register(env) {
+    env.registerInit({
+      deps: {
+        // other dependencies...
+        userInfo: coreServices.userInfo,
+        httpRouter: coreServices.httpRouter,
+        catalog: catalogServiceRef,
+        // We add the OPA service as a dependency this will allow the plugin to use it
+        opa: opaService,
+      },
+      async init({
+        // other dependencies...
+        opa,
+      }) {
+        httpRouter.use(
+          await createRouter({
+            // other dependencies...
+            opa,
+          }),
+        );
+      },
+    });
+  },
+});
+```
+
+## What is it for?
+
+- Allows Backstage plugins and backend services to evaluate authorization and policy decisions using OPA.
+- Provides a simple API for sending policy inputs and receiving policy results from OPA.
+- Supports custom policy entry points and flexible input structures for fine-grained access control.
+- Enables centralized, declarative policy management for your Backstage environment.
+
+## Simple Usage Example
+
+Here's a minimal example of how to use `OpaService` in an Express route:
+
+```ts
+import { opaService } from '@parsifal-m/backstage-plugin-opa-node';
+
+app.post('/my-protected-route', async (req, res) => {
+  const input = {
+    method: req.method,
+    path: req.path,
+    headers: req.headers,
+    permission: { name: 'create-resource' },
+    // ...other input fields
+  };
+
+  const policyResult = await opa.evaluatePolicy(input, 'my_policy_entrypoint');
+  if (!policyResult.result || !policyResult.result.allow) {
+    return res.status(403).json({ error: 'Access Denied' });
+  }
+  // Proceed with your route logic
+  res.status(201).json({ success: true });
+});
+```
+
+## Getting Started
+
+I've set up a demo backend plugin that shows how to use this package to protect your backend endpoints using OPA. You can find it here: [opa-backend-demo](../opa-demo-backend/README.md)
+
+If you check out the `router.ts` file in that plugin, you'll see how to use the `OpaService` to evaluate policies before allowing access to certain endpoints.

package/dist/api/opaClient.cjs.js

@@ -0,0 +1,60 @@
+'use strict';
+
+class OpaClient {
+  logger;
+  config;
+  baseUrl;
+  constructor(config, logger) {
+    this.config = config;
+    this.logger = logger;
+    this.baseUrl = this.config.getString("openPolicyAgent.baseUrl");
+  }
+  async evaluatePolicy(input, entryPoint) {
+    if (!this.baseUrl) {
+      this.logger.error("The OPA URL is not set in the app-config!");
+      throw new Error("The OPA URL is not set in the app-config!");
+    }
+    if (!entryPoint) {
+      this.logger.error(
+        "You have not defined a policy entrypoint! Please provide one."
+      );
+      throw new Error(
+        "You have not defined a policy entrypoint! Please provide one."
+      );
+    }
+    if (!input) {
+      this.logger.error("The policy input is missing!");
+      throw new Error("The policy input is missing!");
+    }
+    const opaUrl = `${this.baseUrl}/v1/data/${entryPoint}`;
+    try {
+      const response = await fetch(opaUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({ input })
+      });
+      if (!response.ok) {
+        const message = `An error response was returned after sending the policy input to the OPA server: ${response.status} - ${response.statusText}`;
+        this.logger.error(message);
+        throw new Error(message);
+      }
+      const evalResult = await response.json();
+      this.logger.debug(
+        `Received data from OPA: ${JSON.stringify(evalResult)}`
+      );
+      return evalResult;
+    } catch (error) {
+      this.logger.error(
+        `An error occurred while sending the policy input to the OPA server: ${error}`
+      );
+      throw new Error(
+        `An error occurred while sending the policy input to the OPA server: ${error}`
+      );
+    }
+  }
+}
+
+exports.OpaClient = OpaClient;
+//# sourceMappingURL=opaClient.cjs.js.map

package/dist/api/opaClient.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"opaClient.cjs.js","sources":["../../src/api/opaClient.ts"],"sourcesContent":["import { LoggerService } from '@backstage/backend-plugin-api';\nimport { Config } from '@backstage/config';\nimport {\n  PolicyInput,\n  PolicyResult,\n} from '@parsifal-m/backstage-plugin-opa-common';\n\nexport class OpaClient {\n  private readonly logger: LoggerService;\n  private readonly config: Config;\n  private readonly baseUrl: string;\n\n  constructor(config: Config, logger: LoggerService) {\n    this.config = config;\n    this.logger = logger;\n    this.baseUrl = this.config.getString('openPolicyAgent.baseUrl');\n  }\n\n  async evaluatePolicy(\n    input: PolicyInput,\n    entryPoint: string,\n  ): Promise<PolicyResult> {\n    if (!this.baseUrl) {\n      this.logger.error('The OPA URL is not set in the app-config!');\n      throw new Error('The OPA URL is not set in the app-config!');\n    }\n\n    if (!entryPoint) {\n      this.logger.error(\n        'You have not defined a policy entrypoint! Please provide one.',\n      );\n      throw new Error(\n        'You have not defined a policy entrypoint! Please provide one.',\n      );\n    }\n\n    if (!input) {\n      this.logger.error('The policy input is missing!');\n      throw new Error('The policy input is missing!');\n    }\n\n    const opaUrl = `${this.baseUrl}/v1/data/${entryPoint}`;\n\n    try {\n      const response = await fetch(opaUrl, {\n        method: 'POST',\n        headers: {\n          'Content-Type': 'application/json',\n        },\n        body: JSON.stringify({ input }),\n      });\n\n      if (!response.ok) {\n        const message = `An error response was returned after sending the policy input to the OPA server: ${response.status} - ${response.statusText}`;\n        this.logger.error(message);\n        throw new Error(message);\n      }\n\n      const evalResult = (await response.json()) as PolicyResult;\n      this.logger.debug(\n        `Received data from OPA: ${JSON.stringify(evalResult)}`,\n      );\n\n      return evalResult;\n    } catch (error: unknown) {\n      this.logger.error(\n        `An error occurred while sending the policy input to the OPA server: ${error}`,\n      );\n      throw new Error(\n        `An error occurred while sending the policy input to the OPA server: ${error}`,\n      );\n    }\n  }\n}\n"],"names":[],"mappings":";;AAOO,MAAM,SAAU,CAAA;AAAA,EACJ,MAAA;AAAA,EACA,MAAA;AAAA,EACA,OAAA;AAAA,EAEjB,WAAA,CAAY,QAAgB,MAAuB,EAAA;AACjD,IAAA,IAAA,CAAK,MAAS,GAAA,MAAA;AACd,IAAA,IAAA,CAAK,MAAS,GAAA,MAAA;AACd,IAAA,IAAA,CAAK,OAAU,GAAA,IAAA,CAAK,MAAO,CAAA,SAAA,CAAU,yBAAyB,CAAA;AAAA;AAChE,EAEA,MAAM,cACJ,CAAA,KAAA,EACA,UACuB,EAAA;AACvB,IAAI,IAAA,CAAC,KAAK,OAAS,EAAA;AACjB,MAAK,IAAA,CAAA,MAAA,CAAO,MAAM,2CAA2C,CAAA;AAC7D,MAAM,MAAA,IAAI,MAAM,2CAA2C,CAAA;AAAA;AAG7D,IAAA,IAAI,CAAC,UAAY,EAAA;AACf,MAAA,IAAA,CAAK,MAAO,CAAA,KAAA;AAAA,QACV;AAAA,OACF;AACA,MAAA,MAAM,IAAI,KAAA;AAAA,QACR;AAAA,OACF;AAAA;AAGF,IAAA,IAAI,CAAC,KAAO,EAAA;AACV,MAAK,IAAA,CAAA,MAAA,CAAO,MAAM,8BAA8B,CAAA;AAChD,MAAM,MAAA,IAAI,MAAM,8BAA8B,CAAA;AAAA;AAGhD,IAAA,MAAM,MAAS,GAAA,CAAA,EAAG,IAAK,CAAA,OAAO,YAAY,UAAU,CAAA,CAAA;AAEpD,IAAI,IAAA;AACF,MAAM,MAAA,QAAA,GAAW,MAAM,KAAA,CAAM,MAAQ,EAAA;AAAA,QACnC,MAAQ,EAAA,MAAA;AAAA,QACR,OAAS,EAAA;AAAA,UACP,cAAgB,EAAA;AAAA,SAClB;AAAA,QACA,IAAM,EAAA,IAAA,CAAK,SAAU,CAAA,EAAE,OAAO;AAAA,OAC/B,CAAA;AAED,MAAI,IAAA,CAAC,SAAS,EAAI,EAAA;AAChB,QAAA,MAAM,UAAU,CAAoF,iFAAA,EAAA,QAAA,CAAS,MAAM,CAAA,GAAA,EAAM,SAAS,UAAU,CAAA,CAAA;AAC5I,QAAK,IAAA,CAAA,MAAA,CAAO,MAAM,OAAO,CAAA;AACzB,QAAM,MAAA,IAAI,MAAM,OAAO,CAAA;AAAA;AAGzB,MAAM,MAAA,UAAA,GAAc,MAAM,QAAA,CAAS,IAAK,EAAA;AACxC,MAAA,IAAA,CAAK,MAAO,CAAA,KAAA;AAAA,QACV,CAA2B,wBAAA,EAAA,IAAA,CAAK,SAAU,CAAA,UAAU,CAAC,CAAA;AAAA,OACvD;AAEA,MAAO,OAAA,UAAA;AAAA,aACA,KAAgB,EAAA;AACvB,MAAA,IAAA,CAAK,MAAO,CAAA,KAAA;AAAA,QACV,uEAAuE,KAAK,CAAA;AAAA,OAC9E;AACA,MAAA,MAAM,IAAI,KAAA;AAAA,QACR,uEAAuE,KAAK,CAAA;AAAA,OAC9E;AAAA;AACF;AAEJ;;;;"}

package/dist/index.cjs.js

@@ -0,0 +1,12 @@
+'use strict';
+
+var opaClient = require('./api/opaClient.cjs.js');
+var service = require('./lib/service.cjs.js');
+var DefaultOpaService = require('./service/DefaultOpaService.cjs.js');
+
+
+
+exports.OpaClient = opaClient.OpaClient;
+exports.opaService = service.opaService;
+exports.DefaultOpaService = DefaultOpaService.DefaultOpaService;
+//# sourceMappingURL=index.cjs.js.map

package/dist/index.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;"}

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+import * as _backstage_backend_plugin_api from '@backstage/backend-plugin-api';
+import { LoggerService } from '@backstage/backend-plugin-api';
+import { Config } from '@backstage/config';
+import { PolicyInput, PolicyResult } from '@parsifal-m/backstage-plugin-opa-common';
+
+declare class OpaClient {
+    private readonly logger;
+    private readonly config;
+    private readonly baseUrl;
+    constructor(config: Config, logger: LoggerService);
+    evaluatePolicy(input: PolicyInput, entryPoint: string): Promise<PolicyResult>;
+}
+
+/**
+ * OPA Service interface for evaluating policies.
+ *
+ * @public
+ */
+interface OpaService {
+    /**
+     * Evaluate a policy at the given entry point.
+     *
+     * @param input - The policy input data
+     * @param entryPoint - The OPA policy entry point d
+     * @returns Promise resolving to the policy evaluation result
+     */
+    evaluatePolicy<T = PolicyResult>(input: PolicyInput, entryPoint: string): Promise<T>;
+}
+declare class DefaultOpaService implements OpaService {
+    private readonly opaClient;
+    constructor(opaClient: OpaClient);
+    static create(options: {
+        config: Config;
+        logger: LoggerService;
+    }): DefaultOpaService;
+    evaluatePolicy<T = PolicyResult>(input: PolicyInput, entryPoint: string): Promise<T>;
+}
+
+declare const opaService: _backstage_backend_plugin_api.ServiceRef<OpaService, "plugin", "singleton">;
+
+export { DefaultOpaService, OpaClient, type OpaService, opaService };

package/dist/lib/service.cjs.js

@@ -0,0 +1,25 @@
+'use strict';
+
+var backendPluginApi = require('@backstage/backend-plugin-api');
+var DefaultOpaService = require('../service/DefaultOpaService.cjs.js');
+
+const opaService = backendPluginApi.createServiceRef({
+  id: "opa.service",
+  scope: "plugin",
+  defaultFactory: async (service) => backendPluginApi.createServiceFactory({
+    service,
+    deps: {
+      config: backendPluginApi.coreServices.rootConfig,
+      logger: backendPluginApi.coreServices.logger
+    },
+    factory({ config, logger }) {
+      return DefaultOpaService.DefaultOpaService.create({
+        config,
+        logger
+      });
+    }
+  })
+});
+
+exports.opaService = opaService;
+//# sourceMappingURL=service.cjs.js.map

package/dist/lib/service.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.cjs.js","sources":["../../src/lib/service.ts"],"sourcesContent":["import {\n  coreServices,\n  createServiceFactory,\n  createServiceRef,\n} from '@backstage/backend-plugin-api';\nimport { DefaultOpaService, OpaService } from '../../service';\n\nexport const opaService = createServiceRef<OpaService>({\n  id: 'opa.service',\n  scope: 'plugin',\n  defaultFactory: async service =>\n    createServiceFactory({\n      service,\n      deps: {\n        config: coreServices.rootConfig,\n        logger: coreServices.logger,\n      },\n      factory({ config, logger }) {\n        return DefaultOpaService.create({\n          config,\n          logger,\n        });\n      },\n    }),\n});\n"],"names":["createServiceRef","createServiceFactory","coreServices","DefaultOpaService"],"mappings":";;;;;AAOO,MAAM,aAAaA,iCAA6B,CAAA;AAAA,EACrD,EAAI,EAAA,aAAA;AAAA,EACJ,KAAO,EAAA,QAAA;AAAA,EACP,cAAA,EAAgB,OAAM,OAAA,KACpBC,qCAAqB,CAAA;AAAA,IACnB,OAAA;AAAA,IACA,IAAM,EAAA;AAAA,MACJ,QAAQC,6BAAa,CAAA,UAAA;AAAA,MACrB,QAAQA,6BAAa,CAAA;AAAA,KACvB;AAAA,IACA,OAAQ,CAAA,EAAE,MAAQ,EAAA,MAAA,EAAU,EAAA;AAC1B,MAAA,OAAOC,oCAAkB,MAAO,CAAA;AAAA,QAC9B,MAAA;AAAA,QACA;AAAA,OACD,CAAA;AAAA;AACH,GACD;AACL,CAAC;;;;"}

package/dist/service/DefaultOpaService.cjs.js

@@ -0,0 +1,20 @@
+'use strict';
+
+var opaClient = require('../api/opaClient.cjs.js');
+
+class DefaultOpaService {
+  opaClient;
+  constructor(opaClient) {
+    this.opaClient = opaClient;
+  }
+  static create(options) {
+    const opaClient$1 = new opaClient.OpaClient(options.config, options.logger);
+    return new DefaultOpaService(opaClient$1);
+  }
+  async evaluatePolicy(input, entryPoint) {
+    return this.opaClient.evaluatePolicy(input, entryPoint);
+  }
+}
+
+exports.DefaultOpaService = DefaultOpaService;
+//# sourceMappingURL=DefaultOpaService.cjs.js.map

package/dist/service/DefaultOpaService.cjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DefaultOpaService.cjs.js","sources":["../../service/DefaultOpaService.ts"],"sourcesContent":["import { LoggerService } from '@backstage/backend-plugin-api';\nimport { OpaClient } from '../src/api/opaClient';\nimport { Config } from '@backstage/config';\nimport {\n  PolicyResult,\n  PolicyInput,\n} from '@parsifal-m/backstage-plugin-opa-common';\n\n/**\n * OPA Service interface for evaluating policies.\n *\n * @public\n */\nexport interface OpaService {\n  /**\n   * Evaluate a policy at the given entry point.\n   *\n   * @param input - The policy input data\n   * @param entryPoint - The OPA policy entry point d\n   * @returns Promise resolving to the policy evaluation result\n   */\n  evaluatePolicy<T = PolicyResult>(\n    input: PolicyInput,\n    entryPoint: string,\n  ): Promise<T>;\n}\n\nexport class DefaultOpaService implements OpaService {\n  private readonly opaClient: OpaClient;\n\n  constructor(opaClient: OpaClient) {\n    this.opaClient = opaClient;\n  }\n\n  static create(options: {\n    config: Config;\n    logger: LoggerService;\n  }): DefaultOpaService {\n    const opaClient = new OpaClient(options.config, options.logger);\n    return new DefaultOpaService(opaClient);\n  }\n\n  async evaluatePolicy<T = PolicyResult>(\n    input: PolicyInput,\n    entryPoint: string,\n  ): Promise<T> {\n    return this.opaClient.evaluatePolicy(input, entryPoint) as Promise<T>;\n  }\n}\n"],"names":["opaClient","OpaClient"],"mappings":";;;;AA2BO,MAAM,iBAAwC,CAAA;AAAA,EAClC,SAAA;AAAA,EAEjB,YAAY,SAAsB,EAAA;AAChC,IAAA,IAAA,CAAK,SAAY,GAAA,SAAA;AAAA;AACnB,EAEA,OAAO,OAAO,OAGQ,EAAA;AACpB,IAAA,MAAMA,cAAY,IAAIC,mBAAA,CAAU,OAAQ,CAAA,MAAA,EAAQ,QAAQ,MAAM,CAAA;AAC9D,IAAO,OAAA,IAAI,kBAAkBD,WAAS,CAAA;AAAA;AACxC,EAEA,MAAM,cACJ,CAAA,KAAA,EACA,UACY,EAAA;AACZ,IAAA,OAAO,IAAK,CAAA,SAAA,CAAU,cAAe,CAAA,KAAA,EAAO,UAAU,CAAA;AAAA;AAE1D;;;;"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@parsifal-m/backstage-plugin-opa-node",
+  "version": "0.1.0",
+  "license": "Apache-2.0",
+  "description": "Provides a Node.js service for integrating Open Policy Agent (OPA) with Backstage backend modules and plugins.",
+  "main": "dist/index.cjs.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public",
+    "main": "dist/index.cjs.js",
+    "types": "dist/index.d.ts"
+  },
+  "backstage": {
+    "role": "node-library",
+    "pluginId": "opa",
+    "pluginPackages": [
+      "@parsifal-m/backstage-plugin-opa-common",
+      "@parsifal-m/backstage-plugin-opa-node",
+      "@parsifal-m/plugin-opa-backend"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Parsifal-M/backstage-opa-plugins.git"
+  },
+  "keywords": [
+    "backstage",
+    "OPA",
+    "Open Policy Agent",
+    "authorization",
+    "RBAC"
+  ],
+  "scripts": {
+    "build": "backstage-cli package build",
+    "lint": "backstage-cli package lint",
+    "test": "backstage-cli package test",
+    "clean": "backstage-cli package clean",
+    "prepack": "backstage-cli package prepack",
+    "postpack": "backstage-cli package postpack"
+  },
+  "devDependencies": {
+    "@backstage/backend-test-utils": "^1.9.1",
+    "@backstage/cli": "^0.34.4"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@backstage/backend-plugin-api": "^1.4.4",
+    "@backstage/config": "^1.3.5",
+    "@parsifal-m/backstage-plugin-opa-common": "workspace:^"
+  },
+  "typesVersions": {
+    "*": {
+      "package.json": [
+        "package.json"
+      ]
+    }
+  }
+}