@parsifal-m/plugin-permission-backend-module-opa-wrapper/dist/index.d.ts

A Backstage backend module that integrates Open Policy Agent (OPA) with the Backstage Permission Framework for policy-based authorization.

import { Config } from '@backstage/config';
import * as _backstage_backend_plugin_api from '@backstage/backend-plugin-api';
import { LoggerService } from '@backstage/backend-plugin-api';

/**
 * Represents the input to a policy evaluation.
 *
 * This type is a record where the keys are strings and the values can be of any type.
 * It allows for flexible input structures to be passed to the policy evaluation function.
 *
 * @example
 * const input: PolicyInput = {
 *   user: {
 *     id: "123",
 *     role: "admin"
 *   },
 *   resource: {
 *     type: "document",
 *     id: "456"
 *   },
 *   action: "read"
 * };
 */
type PolicyInput = Record<string, unknown>;
/**
 * Represents the result of a policy evaluation.
 *
 * @property {string} decision_id - A unique identifier for the decision, useful for tracking and auditing purposes.
 * @property {object} result - The outcome of the policy evaluation.
 * @property {boolean} result.allow - Indicates whether the action is allowed based on the policy evaluation.
 *
 * @example
 * const result: PolicyResult = {
 *   decision_id: "abc-123-def-456",
 *   result: {
 *     allow: true
 *   }
 * };
 */
type PolicyResult = {
    decision_id: string;
    result: {
        allow: boolean;
    };
};
type PermissionsFrameworkPolicyInput = {
    permission: {
        name: string;
    };
    identity?: {
        user: string | undefined;
        claims: string[];
    };
};
type PermissionsFrameworkPolicyEvaluationResult = {
    result: string;
    pluginId?: string;
    resourceType?: string;
    conditions?: {
        anyOf?: {
            params: {
                [key: string]: any;
            };
            resourceType: string;
            rule: string;
        }[];
        allOf?: {
            params: {
                [key: string]: any;
            };
            resourceType: string;
            rule: string;
        }[];
        not?: {
            params: {
                [key: string]: any;
            };
            resourceType: string;
            rule: string;
        }[];
    };
};

/**
 * OpaClient is a class responsible for interacting with the OPA server.
 * It provides methods for evaluating policies by sending requests to the OPA server.
 */
declare class OpaClient {
    private readonly entryPoint?;
    private readonly baseUrl?;
    private readonly fallbackPolicyDecision?;
    private readonly logger;
    /**
     * Constructs a new OpaClient.
     * @param config - The backend configuration object.
     * @param logger - A logger instance
     */
    constructor(config: Config, logger: LoggerService);
    /**
     * Common HTTP request logic for OPA communication.
     */
    private makeOpaRequest;
    /**
     * Unified error handling with optional fallback policy support.
     */
    private handleOpaError;
    /**
     * Validates required configuration and parameters before making OPA requests.
     */
    private validateConfig;
    /**
     * Evaluates a backstage permissions framework policy against a given input.
     *
     * @param input - The input to evaluate the policy against.
     * @param entryPoint - The entry point into the OPA policy to use. You can optionally provide the entry point here, otherwise it will be taken from the app-config.
     */
    evaluatePermissionsFrameworkPolicy(input: PermissionsFrameworkPolicyInput, entryPoint?: string): Promise<PermissionsFrameworkPolicyEvaluationResult>;
    /**
     * Evaluates a generic policy by sending the input to the OPA server and returns the result.
     * This method does not include fallback policy support - it will throw errors if OPA is unavailable.
     *
     * @param input - The policy input to be evaluated.
     * @param entryPoint - The entry point in the OPA server where the policy is defined.
     * @returns A promise that resolves to the policy result.
     * @throws An error if the OPA server returns a non-OK response or if there is an issue with the request.
     */
    evaluatePolicy<T = PolicyResult>(input: PolicyInput, entryPoint: string): Promise<T>;
}

declare const permissionModuleOpaWrapper: _backstage_backend_plugin_api.BackendFeature;

export { OpaClient, permissionModuleOpaWrapper as default };