pepr 0.1.27 → 0.1.29

package/dist/src/cli/init/templates.js

@@ -0,0 +1,229 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.capabilitySnippet = exports.capabilityHelloPeprTS = exports.readme = exports.prettierRC = exports.gitIgnore = exports.tsConfig = exports.genPkgJSON = exports.genPeprTS = void 0;
+const util_1 = require("util");
+const uuid_1 = require("uuid");
+const package_json_1 = require("../../../package.json");
+const utils_1 = require("./utils");
+function genPeprTS() {
+    return {
+        path: "pepr.ts",
+        data: `import { PeprModule } from "pepr";
+import cfg from "./package.json";
+import { HelloPepr } from "./capabilities/hello-pepr";
+
+/**
+ * This is the main entrypoint for the Pepr module. It is the file that is run when the module is started.
+ * This is where you register your configurations and capabilities with the module.
+ */
+new PeprModule(cfg, [
+  // "HelloPepr" is a demo capability that is included with Pepr. You can remove it if you want.
+  HelloPepr,
+
+  // Your additional capabilities go here
+]);    
+`,
+    };
+}
+exports.genPeprTS = genPeprTS;
+function genPkgJSON(opts) {
+    // Generate a random UUID for the module based on the module name
+    const uuid = (0, uuid_1.v5)(opts.name, (0, uuid_1.v4)());
+    // Generate a name for the module based on the module name
+    const name = (0, utils_1.sanitizeName)(opts.name);
+    // Make typescript a dev dependency
+    const { typescript } = package_json_1.dependencies;
+    const data = {
+        name,
+        version: "0.0.1",
+        description: opts.description,
+        keywords: ["pepr", "k8s", "policy-engine", "pepr-module", "security"],
+        pepr: {
+            name: opts.name.trim(),
+            version: package_json_1.version,
+            uuid,
+            onError: opts.errorBehavior,
+            alwaysIgnore: {
+                namespaces: [],
+                labels: [],
+            },
+        },
+        scripts: {
+            build: "pepr build",
+            start: "pepr dev",
+        },
+        dependencies: {
+            pepr: `^${package_json_1.version}`,
+        },
+        devDependencies: {
+            typescript,
+        },
+    };
+    return {
+        data,
+        path: "package.json",
+        print: (0, util_1.inspect)(data, false, 5, true),
+    };
+}
+exports.genPkgJSON = genPkgJSON;
+exports.tsConfig = {
+    path: "tsconfig.json",
+    data: {
+        compilerOptions: {
+            esModuleInterop: true,
+            lib: ["ES2020"],
+            moduleResolution: "node",
+            resolveJsonModule: true,
+            rootDir: ".",
+            strict: false,
+            target: "ES2020",
+        },
+        include: ["**/*.ts"],
+    },
+};
+exports.gitIgnore = {
+    path: ".gitignore",
+    data: `# Ignore node_modules
+  node_modules
+  dist
+`,
+};
+exports.prettierRC = {
+    path: ".prettierrc",
+    data: {
+        arrowParens: "avoid",
+        bracketSameLine: false,
+        bracketSpacing: true,
+        embeddedLanguageFormatting: "auto",
+        insertPragma: false,
+        printWidth: 80,
+        quoteProps: "as-needed",
+        requirePragma: false,
+        semi: true,
+        tabWidth: 2,
+        useTabs: false,
+    },
+};
+exports.readme = {
+    path: "README.md",
+    data: `# Pepr Module
+
+This is a Pepr module. It is a module that can be used with the [Pepr]() framework.
+
+The \`capabilities\` directory contains all the capabilities for this module. By default, 
+a capability is a single typescript file in the format of \`capability-name.ts\` that is 
+imported in the root \`pepr.ts\` file as \`import { HelloPepr } from "./capabilities/hello-pepr";\`. 
+Because this is typescript, you can organize this however you choose, e.g. creating a sub-folder 
+per-capability or common logic in shared files or folders.
+
+Example Structure:
+
+\`\`\`
+Module Root
+├── package.json
+├── pepr.ts
+└── capabilities
+    ├── example-one.ts
+    ├── example-three.ts
+    └── example-two.ts
+\`\`\`
+`,
+};
+exports.capabilityHelloPeprTS = {
+    path: "hello-pepr.ts",
+    data: `import { Capability, a } from "pepr";
+
+export const HelloPepr = new Capability({
+  name: "hello-pepr",
+  description: "A simple example capability to show how things work.",
+  namespaces: ["pepr-demo"],
+});
+
+// Use the 'When' function to create a new Capability Action
+const { When } = HelloPepr;
+  
+/**
+ * This is a single Capability Action. They can be in the same file or put imported from other files.
+ * In this exmaple, when a ConfigMap is created with the name \`example-1\`, then add a label and annotation.
+ *
+ * Equivelant to manually running:
+ * \`kubectl label configmap example-1 pepr=was-here\`
+ * \`kubectl annotate configmap example-1 pepr.dev=annotations-work-too\`
+ */
+When(a.ConfigMap)
+  .IsCreated()
+  .WithName("example-1")
+  .Then(request =>
+    request
+      .SetLabel("pepr", "was-here")
+      .SetAnnotation("pepr.dev", "annotations-work-too")
+  );
+
+/**
+ * This Capabiility Action does the exact same changes for example-2, except this time it uses the \`.ThenSet()\` feature.
+ * You can stack multiple \`.Then()\` calls, but only a single \`.ThenSet()\`
+ */
+When(a.ConfigMap)
+  .IsCreated()
+  .WithName("example-2")
+  .ThenSet({
+    metadata: {
+      labels: {
+        pepr: "was-here",
+      },
+      annotations: {
+        "pepr.dev": "annotations-work-too",
+      },
+    },
+  });
+
+/**
+ * This Capability Action combines different styles. Unlike the previous actions, this one will look for any ConfigMap
+ * in the \`pepr-demo\` namespace that has the label \`change=by-label\`. Note that all conditions added such as \`WithName()\`,
+ * \`WithLabel()\`, \`InNamespace()\`, are ANDs so all conditions must be true for the request to be procssed.
+ */
+When(a.ConfigMap)
+  .IsCreated()
+  .WithLabel("change", "by-label")
+  .Then(request => {
+    // The K8s object e are going to mutate
+    const cm = request.Raw;
+
+    // Get the username and uid of the K8s reuest
+    const { username, uid } = request.Request.userInfo;
+
+    // Store some data about the request in the configmap
+    cm.data["username"] = username;
+    cm.data["uid"] = uid;
+
+    // You can still mix other ways of making changes too
+    request.SetAnnotation("pepr.dev", "making-waves");
+  });    
+`,
+};
+exports.capabilitySnippet = {
+    path: "pepr.code-snippets",
+    data: `{
+  "Create a new Pepr capability": {
+    "prefix": "create pepr capability",
+    "body": [
+      "import { Capability, a } from 'pepr';",
+      "",
+      "export const $\{TM_FILENAME_BASE/(.*)/$\{1:/pascalcase}/} = new Capability({",
+      "\\tname: '$\{TM_FILENAME_BASE}',",
+      "\\tdescription: '$\{1:A brief description of this capability.}',",
+      "\\tnamespaces: [$\{2:}],",
+      "});",
+      "",
+      "// Use the 'When' function to create a new Capability Action",
+      "const { When } = $\{TM_FILENAME_BASE/(.*)/$\{1:/pascalcase}/};",
+      "",
+      "// When(a.<Kind>).Is<Event>().Then(change => change.<changes>",
+      "When($\{3:})"
+    ],
+    "description": "Creates a new Pepr capability with a specified description, and optional namespaces, and adds a When statement for the specified value."
+  }
+}`,
+};

package/dist/src/cli/init/utils.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Sanitize a user input name to be used as a pepr module directory name
+ *
+ * @param name the user input name
+ * @returns the sanitized name
+ */
+export declare function sanitizeName(name: string): string;
+/**
+ * Creates a directory and throws an error if it already exists
+ *
+ * @param dir - The directory to create
+ */
+export declare function createDir(dir: string): Promise<void>;
+/**
+ * Write data to a file on disk
+ * @param path - The path to the file
+ * @param data - The data to write
+ * @returns A promise that resolves when the file has been written
+ */
+export declare function write(path: string, data: unknown): Promise<void>;

package/dist/src/cli/init/utils.js

@@ -0,0 +1,56 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.write = exports.createDir = exports.sanitizeName = void 0;
+const fs_1 = require("fs");
+/**
+ * Sanitize a user input name to be used as a pepr module directory name
+ *
+ * @param name the user input name
+ * @returns the sanitized name
+ */
+function sanitizeName(name) {
+    // Replace any characters outside of [^a-z0-9-] with "-"
+    let sanitized = name.toLowerCase().replace(/[^a-z0-9-]+/gi, "-");
+    // Remove any leading or trailing hyphens
+    sanitized = sanitized.replace(/^-+|-+$/g, "");
+    // Replace multiple hyphens with a single hyphen
+    sanitized = sanitized.replace(/--+/g, "-");
+    return sanitized;
+}
+exports.sanitizeName = sanitizeName;
+/**
+ * Creates a directory and throws an error if it already exists
+ *
+ * @param dir - The directory to create
+ */
+async function createDir(dir) {
+    try {
+        await fs_1.promises.mkdir(dir);
+    }
+    catch (err) {
+        // The directory already exists
+        if (err.code === "EEXIST") {
+            throw new Error(`Directory ${dir} already exists`);
+        }
+        else {
+            throw err;
+        }
+    }
+}
+exports.createDir = createDir;
+/**
+ * Write data to a file on disk
+ * @param path - The path to the file
+ * @param data - The data to write
+ * @returns A promise that resolves when the file has been written
+ */
+function write(path, data) {
+    // If the data is not a string, stringify it
+    if (typeof data !== "string") {
+        data = JSON.stringify(data, null, 2);
+    }
+    return fs_1.promises.writeFile(path, data);
+}
+exports.write = write;

package/dist/src/cli/init/walkthrough.d.ts

@@ -0,0 +1,7 @@
+import { Answers } from "prompts";
+export type InitOptions = Answers<"name" | "description" | "errorBehavior">;
+export declare function walkthrough(): Promise<InitOptions>;
+export declare function confirm(dirName: string, packageJSON: {
+    path: string;
+    print: string;
+}, peprTSPath: string): Promise<any>;

package/dist/src/cli/init/walkthrough.js

@@ -0,0 +1,84 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.confirm = exports.walkthrough = void 0;
+const fs_1 = require("fs");
+const prompts_1 = __importDefault(require("prompts"));
+const types_1 = require("../../lib/types");
+const templates_1 = require("./templates");
+const utils_1 = require("./utils");
+function walkthrough() {
+    const askName = {
+        type: "text",
+        name: "name",
+        message: "Enter a name for the new Pepr module. This will create a new directory based on the name.\n",
+        validate: async (val) => {
+            try {
+                const name = (0, utils_1.sanitizeName)(val);
+                await fs_1.promises.access(name, fs_1.promises.constants.F_OK);
+                return "A directory with this name already exists";
+            }
+            catch (e) {
+                return val.length > 2 || "The name must be at least 3 characters long";
+            }
+        },
+    };
+    const askDescription = {
+        type: "text",
+        name: "description",
+        message: "(Recommended) Enter a description for the new Pepr module.\n",
+    };
+    const askErrorBehavior = {
+        type: "select",
+        name: "errorBehavior",
+        validate: val => types_1.ErrorBehavior[val],
+        message: "How do you want Pepr to handle errors encountered during K8s operations?",
+        choices: [
+            {
+                title: "Ignore",
+                value: types_1.ErrorBehavior.ignore,
+                description: "Pepr will continue processing and generate an entry in the Pepr Controller log.",
+                selected: true,
+            },
+            {
+                title: "Log an audit event",
+                value: types_1.ErrorBehavior.audit,
+                description: "Pepr will continue processing and generate an entry in the Pepr Controller log as well as an audit event in the cluster.",
+            },
+            {
+                title: "Reject the operation",
+                value: types_1.ErrorBehavior.reject,
+                description: "Pepr will reject the operation and return an error to the client.",
+            },
+        ],
+    };
+    return (0, prompts_1.default)([askName, askDescription, askErrorBehavior]);
+}
+exports.walkthrough = walkthrough;
+async function confirm(dirName, packageJSON, peprTSPath) {
+    console.log(`
+  To be generated:
+
+    \x1b[1m${dirName}\x1b[0m
+    ├── \x1b[1m${templates_1.gitIgnore.path}\x1b[0m
+    ├── \x1b[1m${templates_1.prettierRC.path}\x1b[0m
+    ├── \x1b[1mcapabilties\x1b[0m
+    |   └── \x1b[1mhello-pepr.ts\x1b[0m     
+    ├── \x1b[1m${packageJSON.path}\x1b[0m
+${packageJSON.print.replace(/^/gm, "    │   ")}
+    ├── \x1b[1m${peprTSPath}\x1b[0m
+    ├── \x1b[1m${templates_1.readme.path}\x1b[0m
+    └── \x1b[1m${templates_1.tsConfig.path}\x1b[0m
+      `);
+    const confirm = await (0, prompts_1.default)({
+        type: "confirm",
+        name: "confirm",
+        message: "Create the new Pepr module?",
+    });
+    return confirm.confirm;
+}
+exports.confirm = confirm;

package/dist/src/cli/root.d.ts

@@ -0,0 +1,4 @@
+import { Command } from "commander";
+export declare class RootCmd extends Command {
+    createCommand(name: string): Command;
+}

package/dist/src/cli/root.js

@@ -0,0 +1,21 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RootCmd = void 0;
+const commander_1 = require("commander");
+const logger_1 = __importDefault(require("../lib/logger"));
+class RootCmd extends commander_1.Command {
+    createCommand(name) {
+        const cmd = new commander_1.Command(name);
+        cmd.option("-l, --log-level [level]", "Log level: debug, info, warn, error", "info");
+        cmd.hook("preAction", run => {
+            logger_1.default.SetLogLevel(run.opts().logLevel);
+        });
+        return cmd;
+    }
+}
+exports.RootCmd = RootCmd;

package/dist/src/cli/test.d.ts

@@ -0,0 +1,2 @@
+import { RootCmd } from "./root";
+export default function (program: RootCmd): void;

package/dist/src/cli/test.js

@@ -0,0 +1,51 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const child_process_1 = require("child_process");
+const chokidar_1 = require("chokidar");
+const path_1 = require("path");
+const util_1 = require("util");
+const logger_1 = __importDefault(require("../lib/logger"));
+const build_1 = require("./build");
+const exec = (0, util_1.promisify)(child_process_1.exec);
+function default_1(program) {
+    program
+        .command("test")
+        .description("Test a Pepr Module locally")
+        .option("-d, --dir [directory]", "Pepr module directory", ".")
+        .option("-w, --watch", "Watch for changes and re-run the test")
+        .action(async (opts) => {
+        logger_1.default.info("Test Module");
+        await buildAndTest(opts.dir);
+        if (opts.watch) {
+            const moduleFiles = (0, path_1.resolve)(opts.dir, "**", "*.ts");
+            const watcher = (0, chokidar_1.watch)(moduleFiles);
+            watcher.on("ready", () => {
+                logger_1.default.info(`Watching for changes in ${moduleFiles}`);
+                watcher.on("all", async (event, path) => {
+                    logger_1.default.debug({ event, path }, "File changed");
+                    await buildAndTest(opts.dir);
+                });
+            });
+        }
+    });
+}
+exports.default = default_1;
+async function buildAndTest(dir) {
+    const { path } = await (0, build_1.buildModule)(dir);
+    logger_1.default.info(`Module built successfully at ${path}`);
+    try {
+        const { stdout, stderr } = await exec(`node ${path}`);
+        console.log(stdout);
+        console.log(stderr);
+    }
+    catch (e) {
+        logger_1.default.debug(e);
+        logger_1.default.error(`Error running module: ${e}`);
+        process.exit(1);
+    }
+}

package/dist/src/lib/capability.d.ts

@@ -0,0 +1,26 @@
+import { Binding, CapabilityCfg, GenericClass, HookPhase, WhenSelector } from "./types";
+/**
+ * A capability is a unit of functionality that can be registered with the Pepr runtime.
+ */
+export declare class Capability implements CapabilityCfg {
+    private _name;
+    private _description;
+    private _namespaces?;
+    private _mutateOrValidate;
+    private _bindings;
+    get bindings(): Binding[];
+    get name(): string;
+    get description(): string;
+    get namespaces(): string[];
+    get mutateOrValidate(): HookPhase;
+    constructor(cfg: CapabilityCfg);
+    /**
+     * The When method is used to register a capability action to be executed when a Kubernetes resource is
+     * processed by Pepr. The action will be executed if the resource matches the specified kind and any
+     * filters that are applied.
+     *
+     * @param model if using a custom KubernetesObject not available in `a.*`, specify the GroupVersionKind
+     * @returns
+     */
+    When: <T extends GenericClass>(model: T) => WhenSelector<T>;
+}

package/dist/src/lib/capability.js

@@ -0,0 +1,119 @@
+"use strict";
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Capability = void 0;
+const k8s_1 = require("./k8s");
+const logger_1 = __importDefault(require("./logger"));
+const types_1 = require("./types");
+/**
+ * A capability is a unit of functionality that can be registered with the Pepr runtime.
+ */
+class Capability {
+    get bindings() {
+        return this._bindings;
+    }
+    get name() {
+        return this._name;
+    }
+    get description() {
+        return this._description;
+    }
+    get namespaces() {
+        return this._namespaces || [];
+    }
+    get mutateOrValidate() {
+        return this._mutateOrValidate;
+    }
+    constructor(cfg) {
+        // Currently everything is considered a mutation
+        this._mutateOrValidate = types_1.HookPhase.mutate;
+        this._bindings = [];
+        /**
+         * The When method is used to register a capability action to be executed when a Kubernetes resource is
+         * processed by Pepr. The action will be executed if the resource matches the specified kind and any
+         * filters that are applied.
+         *
+         * @param model if using a custom KubernetesObject not available in `a.*`, specify the GroupVersionKind
+         * @returns
+         */
+        this.When = (model) => {
+            const binding = {
+                // If the kind is not specified, use the default KubernetesObject
+                kind: (0, k8s_1.modelToGroupVersionKind)(model.name),
+                filters: {
+                    name: "",
+                    namespaces: [],
+                    labels: {},
+                    annotations: {},
+                },
+                callback: () => null,
+            };
+            const prefix = `${this._name}: ${model.name}`;
+            logger_1.default.info(`Binding created`, prefix);
+            const Then = (cb) => {
+                logger_1.default.info(`Binding action created`, prefix);
+                logger_1.default.debug(cb.toString(), prefix);
+                // Push the binding to the list of bindings for this capability as a new BindingAction
+                // with the callback function to preserve
+                this._bindings.push({
+                    ...binding,
+                    callback: cb,
+                });
+                // Now only allow adding actions to the same binding
+                return { Then };
+            };
+            const ThenSet = (merge) => {
+                // Add the new action to the binding
+                Then(req => req.Merge(merge));
+                return { Then };
+            };
+            function InNamespace(...namespaces) {
+                logger_1.default.debug(`Add namespaces filter ${namespaces}`, prefix);
+                binding.filters.namespaces.push(...namespaces);
+                return { WithLabel, WithAnnotation, WithName, Then, ThenSet };
+            }
+            function WithName(name) {
+                logger_1.default.debug(`Add name filter ${name}`, prefix);
+                binding.filters.name = name;
+                return { WithLabel, WithAnnotation, Then, ThenSet };
+            }
+            function WithLabel(key, value = "") {
+                logger_1.default.debug(`Add label filter ${key}=${value}`, prefix);
+                binding.filters.labels[key] = value;
+                return { WithLabel, WithAnnotation, Then, ThenSet };
+            }
+            const WithAnnotation = (key, value = "") => {
+                logger_1.default.debug(`Add annotation filter ${key}=${value}`, prefix);
+                binding.filters.annotations[key] = value;
+                return { WithLabel, WithAnnotation, Then, ThenSet };
+            };
+            const bindEvent = (event) => {
+                binding.event = event;
+                return {
+                    InNamespace,
+                    Then,
+                    ThenSet,
+                    WithAnnotation,
+                    WithLabel,
+                    WithName,
+                };
+            };
+            return {
+                IsCreatedOrUpdated: () => bindEvent(types_1.Event.CreateOrUpdate),
+                IsCreated: () => bindEvent(types_1.Event.Create),
+                IsUpdated: () => bindEvent(types_1.Event.Update),
+                IsDeleted: () => bindEvent(types_1.Event.Delete),
+            };
+        };
+        this._name = cfg.name;
+        this._description = cfg.description;
+        this._namespaces = cfg.namespaces;
+        logger_1.default.info(`Capability ${this._name} registered`);
+        logger_1.default.debug(cfg);
+    }
+}
+exports.Capability = Capability;

package/dist/src/lib/controller.d.ts

@@ -0,0 +1,13 @@
+import { ModuleConfig } from "./types";
+import { Capability } from "./capability";
+export declare class Controller {
+    private readonly config;
+    private readonly capabilities;
+    private readonly app;
+    constructor(config: ModuleConfig, capabilities: Capability[]);
+    /** Start the webhook server */
+    startServer: (port: number) => void;
+    private logger;
+    private healthz;
+    private mutate;
+}