pepr 0.1.27 → 0.1.28

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

@@ -0,0 +1,7 @@
+import { RootCmd } from "./root";
+export default function (program: RootCmd): void;
+export declare function buildModule(moduleDir: string): Promise<{
+    path: string;
+    cfg: any;
+    uuid: any;
+}>;

package/dist/src/cli/build.js

@@ -0,0 +1,95 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+import json from "@rollup/plugin-json";
+import nodeResolve from "@rollup/plugin-node-resolve";
+import typescript from "@rollup/plugin-typescript";
+import { promises as fs } from "fs";
+import { resolve } from "path";
+import { rollup } from "rollup";
+import Log from "../lib/logger";
+import { Webhook } from "../lib/k8s/webhook";
+export default function (program) {
+    program
+        .command("build")
+        .description("Build a Pepr Module for deployment")
+        .option("-d, --dir [directory]", "Pepr module directory", ".")
+        .action(async (opts) => {
+        // Build the module
+        const { cfg, path, uuid } = await buildModule(opts.dir);
+        // Read the compiled module code
+        const code = await fs.readFile(path, { encoding: "utf-8" });
+        // Generate a secret for the module
+        const webhook = new Webhook({
+            ...cfg.pepr,
+            description: cfg.description,
+        });
+        const yamlFile = `pepr-module-${uuid}.yaml`;
+        const yamlPath = resolve("dist", yamlFile);
+        const yaml = webhook.allYaml(code);
+        const zarfPath = resolve("dist", "zarf.yaml");
+        const zarf = webhook.zarfYaml(yamlFile);
+        await fs.writeFile(yamlPath, yaml);
+        await fs.writeFile(zarfPath, zarf);
+        Log.debug(`Module compiled successfully at ${path}`);
+        Log.info(`K8s resource for the module saved to ${yamlPath}`);
+    });
+}
+const externalLibs = [
+    /@kubernetes\/client-node(\/.*)?/,
+    "express",
+    "fast-json-patch",
+    "ramda",
+];
+export async function buildModule(moduleDir) {
+    try {
+        // Resolve the path to the module's package.json file
+        const cfgPath = resolve(moduleDir, "package.json");
+        const input = resolve(moduleDir, "pepr.ts");
+        // Read the module's UUID from the package.json filel
+        const moduleText = await fs.readFile(cfgPath, { encoding: "utf-8" });
+        const cfg = JSON.parse(moduleText);
+        const { uuid } = cfg.pepr;
+        const name = `pepr-${uuid}.js`;
+        // Exit if the module's UUID could not be found
+        if (!uuid) {
+            throw new Error("Could not load the uuid in package.json");
+        }
+        const plugins = [
+            nodeResolve({
+                preferBuiltins: true,
+            }),
+            json(),
+            typescript({
+                tsconfig: "./tsconfig.json",
+                declaration: false,
+                removeComments: true,
+                sourceMap: false,
+                include: ["**/*.ts"],
+            }),
+        ];
+        // Build the module using Rollup
+        const bundle = await rollup({
+            plugins,
+            external: externalLibs,
+            treeshake: true,
+            input,
+        });
+        // Write the module to the dist directory
+        await bundle.write({
+            dir: "dist",
+            format: "cjs",
+            entryFileNames: name,
+        });
+        return {
+            path: resolve("dist", name),
+            cfg,
+            uuid,
+        };
+    }
+    catch (e) {
+        // On any other error, exit with a non-zero exit code
+        Log.debug(e);
+        Log.error(e.message);
+        process.exit(1);
+    }
+}

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

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

package/dist/src/cli/capability.js

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+export default function (program) {
+    program
+        .command("new")
+        .description("Create a new Pepr Capability")
+        .option("-d, --dir [directory]", "Pepr module directory", ".")
+        .action(() => {
+        // TODO: Create a new capability
+        console.log("new");
+    });
+}

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

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

package/dist/src/cli/deploy.js

@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+import { promises as fs } from "fs";
+import { Webhook } from "../lib/k8s/webhook";
+import Log from "../lib/logger";
+import { buildModule } from "./build";
+import { prompt } from "prompts";
+export default function (program) {
+    program
+        .command("deploy")
+        .description("Deploy a Pepr Module")
+        .option("-d, --dir [directory]", "Pepr module directory", ".")
+        .option("-i, --image [image]", "Override the image tag")
+        .option("-f, --force", "Force redeployment")
+        .action(async (opts) => {
+        if (!opts.force) {
+            // Prompt the user to confirm
+            const confirm = await prompt({
+                type: "confirm",
+                name: "confirm",
+                message: "This will remove and redeploy the module. Continue?",
+            });
+            // Exit if the user doesn't confirm
+            if (!confirm.confirm) {
+                process.exit(0);
+            }
+        }
+        // Build the module
+        const { cfg, path } = await buildModule(opts.dir);
+        // Read the compiled module code
+        const code = await fs.readFile(path, { encoding: "utf-8" });
+        // Generate a secret for the module
+        const webhook = new Webhook({
+            ...cfg.pepr,
+            description: cfg.description,
+        });
+        if (opts.image) {
+            webhook.image = opts.image;
+        }
+        try {
+            await webhook.deploy(code);
+            Log.info(`Module deployed successfully`);
+        }
+        catch (e) {
+            Log.error(`Error deploying module: ${e}`);
+            process.exit(1);
+        }
+    });
+}

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

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

package/dist/src/cli/dev.js

@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+import { spawn } from "child_process";
+import { watch } from "chokidar";
+import { promises as fs } from "fs";
+import { resolve } from "path";
+import { prompt } from "prompts";
+import { Webhook } from "../lib/k8s/webhook";
+import Log from "../lib/logger";
+import { buildModule } from "./build";
+export default function (program) {
+    program
+        .command("dev")
+        .description("Setup a local webhook development environment")
+        .option("-d, --dir [directory]", "Pepr module directory", ".")
+        .option("-h, --host [host]", "Host to listen on", "host.docker.internal")
+        .action(async (opts) => {
+        // Prompt the user to confirm
+        const confirm = await prompt({
+            type: "confirm",
+            name: "confirm",
+            message: "This will remove and redeploy the module. Continue?",
+        });
+        // Exit if the user doesn't confirm
+        if (!confirm.confirm) {
+            process.exit(0);
+        }
+        // Build the module
+        const { cfg, path } = await buildModule(opts.dir);
+        // Read the compiled module code
+        const code = await fs.readFile(path, { encoding: "utf-8" });
+        // Generate a secret for the module
+        const webhook = new Webhook({
+            ...cfg.pepr,
+            description: cfg.description,
+        }, opts.host);
+        // Write the TLS cert and key to disk
+        await fs.writeFile("insecure-tls.crt", webhook.tls.pem.crt);
+        await fs.writeFile("insecure-tls.key", webhook.tls.pem.key);
+        try {
+            await webhook.deploy(code);
+            Log.info(`Module deployed successfully`);
+            const moduleFiles = resolve(opts.dir, "**", "*.ts");
+            const watcher = watch(moduleFiles);
+            const peprTS = resolve(opts.dir, "pepr.ts");
+            let program;
+            // Run the module once to start the server
+            runDev(peprTS);
+            // Watch for changes
+            watcher.on("ready", () => {
+                Log.info(`Watching for changes in ${moduleFiles}`);
+                watcher.on("all", async (event, path) => {
+                    Log.debug({ event, path }, "File changed");
+                    // Kill the running process
+                    if (program) {
+                        program.kill("SIGKILL");
+                    }
+                    // Start the process again
+                    program = runDev(peprTS);
+                });
+            });
+        }
+        catch (e) {
+            Log.error(`Error deploying module: ${e}`);
+            process.exit(1);
+        }
+    });
+}
+function runDev(path) {
+    try {
+        const program = spawn("./node_modules/.bin/ts-node", [path], {
+            env: {
+                ...process.env,
+                SSL_KEY_PATH: "insecure-tls.key",
+                SSL_CERT_PATH: "insecure-tls.crt",
+            },
+        });
+        program.stdout.on("data", data => console.log(data.toString()));
+        program.stderr.on("data", data => console.error(data.toString()));
+        program.on("close", code => {
+            Log.info(`Process exited with code ${code}`);
+        });
+        return program;
+    }
+    catch (e) {
+        Log.debug(e);
+        Log.error(`Error running module: ${e}`);
+        process.exit(1);
+    }
+}

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

@@ -0,0 +1 @@
+export {};

package/dist/src/cli/index.js

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+import { version } from "../../package.json";
+import { banner } from "./banner";
+import build from "./build";
+import capability from "./capability";
+import deploy from "./deploy";
+import dev from "./dev";
+import init from "./init";
+import { RootCmd } from "./root";
+import test from "./test";
+const program = new RootCmd();
+program
+    .version(version)
+    .description(`Pepr Kubernetes Thingy (v${version})`)
+    .action(() => {
+    if (program.args.length < 1) {
+        console.log(banner);
+        program.help();
+    }
+});
+init(program);
+build(program);
+capability(program);
+test(program);
+deploy(program);
+dev(program);
+program.parse();

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

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

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

@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+import { execSync } from "child_process";
+import { resolve } from "path";
+import Log from "../../lib/logger";
+import { capabilityHelloPeprTS, capabilitySnippet, genPeprTS, genPkgJSON, gitIgnore, prettierRC, readme, tsConfig, } from "./templates";
+import { createDir, sanitizeName, write } from "./utils";
+import { confirm, walkthrough } from "./walkthrough";
+export default function (program) {
+    program
+        .command("init")
+        .description("Initialize a new Pepr Module")
+        .action(async () => {
+        const response = await walkthrough();
+        const dirName = sanitizeName(response.name);
+        const packageJSON = genPkgJSON(response);
+        const peprTS = genPeprTS();
+        const confirmed = await confirm(dirName, packageJSON, peprTS.path);
+        if (confirmed) {
+            console.log("Creating new Pepr module...");
+            try {
+                await createDir(dirName);
+                await createDir(resolve(dirName, ".vscode"));
+                await createDir(resolve(dirName, "capabilities"));
+                await write(resolve(dirName, gitIgnore.path), gitIgnore.data);
+                await write(resolve(dirName, prettierRC.path), prettierRC.data);
+                await write(resolve(dirName, packageJSON.path), packageJSON.data);
+                await write(resolve(dirName, readme.path), readme.data);
+                await write(resolve(dirName, tsConfig.path), tsConfig.data);
+                await write(resolve(dirName, peprTS.path), peprTS.data);
+                await write(resolve(dirName, ".vscode", capabilitySnippet.path), capabilitySnippet.data);
+                await write(resolve(dirName, "capabilities", capabilityHelloPeprTS.path), capabilityHelloPeprTS.data);
+                // run npm install from the new directory
+                process.chdir(dirName);
+                execSync("npm install", {
+                    stdio: "inherit",
+                });
+                console.log(`New Pepr module created at ${dirName}`);
+                console.log(`Open VSCode or your editor of choice in ${dirName} to get started!`);
+            }
+            catch (e) {
+                Log.debug(e);
+                Log.error(e.message);
+                process.exit(1);
+            }
+        }
+    });
+}

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

@@ -0,0 +1,82 @@
+import { InitOptions } from "./walkthrough";
+export declare function genPeprTS(): {
+    path: string;
+    data: string;
+};
+export declare function genPkgJSON(opts: InitOptions): {
+    data: {
+        name: string;
+        version: string;
+        description: any;
+        keywords: string[];
+        pepr: {
+            name: any;
+            version: string;
+            uuid: string;
+            onError: any;
+            alwaysIgnore: {
+                namespaces: any[];
+                labels: any[];
+            };
+        };
+        scripts: {
+            build: string;
+            start: string;
+        };
+        dependencies: {
+            pepr: string;
+        };
+        devDependencies: {
+            typescript: string;
+        };
+    };
+    path: string;
+    print: string;
+};
+export declare const tsConfig: {
+    path: string;
+    data: {
+        compilerOptions: {
+            esModuleInterop: boolean;
+            lib: string[];
+            moduleResolution: string;
+            resolveJsonModule: boolean;
+            rootDir: string;
+            strict: boolean;
+            target: string;
+        };
+        include: string[];
+    };
+};
+export declare const gitIgnore: {
+    path: string;
+    data: string;
+};
+export declare const prettierRC: {
+    path: string;
+    data: {
+        arrowParens: string;
+        bracketSameLine: boolean;
+        bracketSpacing: boolean;
+        embeddedLanguageFormatting: string;
+        insertPragma: boolean;
+        printWidth: number;
+        quoteProps: string;
+        requirePragma: boolean;
+        semi: boolean;
+        tabWidth: number;
+        useTabs: boolean;
+    };
+};
+export declare const readme: {
+    path: string;
+    data: string;
+};
+export declare const capabilityHelloPeprTS: {
+    path: string;
+    data: string;
+};
+export declare const capabilitySnippet: {
+    path: string;
+    data: string;
+};

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

@@ -0,0 +1,224 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+import { inspect } from "util";
+import { v4 as uuidv4, v5 as uuidv5 } from "uuid";
+import { dependencies, version } from "../../../package.json";
+import { sanitizeName } from "./utils";
+export 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
+]);    
+`,
+    };
+}
+export function genPkgJSON(opts) {
+    // Generate a random UUID for the module based on the module name
+    const uuid = uuidv5(opts.name, uuidv4());
+    // Generate a name for the module based on the module name
+    const name = sanitizeName(opts.name);
+    // Make typescript a dev dependency
+    const { typescript } = 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,
+            uuid,
+            onError: opts.errorBehavior,
+            alwaysIgnore: {
+                namespaces: [],
+                labels: [],
+            },
+        },
+        scripts: {
+            build: "pepr build",
+            start: "pepr dev",
+        },
+        dependencies: {
+            pepr: `^${version}`,
+        },
+        devDependencies: {
+            typescript,
+        },
+    };
+    return {
+        data,
+        path: "package.json",
+        print: inspect(data, false, 5, true),
+    };
+}
+export const tsConfig = {
+    path: "tsconfig.json",
+    data: {
+        compilerOptions: {
+            esModuleInterop: true,
+            lib: ["ES2020"],
+            moduleResolution: "node",
+            resolveJsonModule: true,
+            rootDir: ".",
+            strict: false,
+            target: "ES2020",
+        },
+        include: ["**/*.ts"],
+    },
+};
+export const gitIgnore = {
+    path: ".gitignore",
+    data: `# Ignore node_modules
+  node_modules
+  dist
+`,
+};
+export const 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,
+    },
+};
+export const 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
+\`\`\`
+`,
+};
+export const 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");
+  });    
+`,
+};
+export const 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>;