pepr 0.0.0-development

package/src/lib/storage.ts

@@ -0,0 +1,192 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { clone } from "ramda";
+import Log from "./logger";
+
+export type DataOp = "add" | "remove";
+export type DataStore = Record<string, string>;
+export type DataSender = (op: DataOp, keys: string[], value?: string) => void;
+export type DataReceiver = (data: DataStore) => void;
+export type Unsubscribe = () => void;
+
+const MAX_WAIT_TIME = 15000;
+export interface PeprStore {
+  /**
+   * Returns the current value associated with the given key, or null if the given key does not exist.
+   */
+  getItem(key: string): string | null;
+  /**
+   * Removes all key/value pairs, if there are any.
+   */
+  clear(): void;
+  /**
+   * Removes the key/value pair with the given key, if a key/value pair with the given key exists.
+   */
+  removeItem(key: string): void;
+  /**
+   * Sets the value of the pair identified by key to value, creating a new key/value pair if none existed for key previously.
+   */
+  setItem(key: string, value: string): void;
+
+  /**
+   * Subscribe to changes in the store. This API behaves similarly to the [Svelte Store API](https://vercel.com/docs/beginner-sveltekit/svelte-stores#using-the-store).
+   *
+   * @param listener - The callback to be invoked when the store changes.
+   * @returns A function to unsubscribe from the listener.
+   */
+  subscribe(listener: DataReceiver): Unsubscribe;
+
+  /**
+   * Register a function to be called when the store is ready.
+   */
+  onReady(callback: DataReceiver): void;
+
+  /**
+   * Sets the value of the pair identified by key to value, creating a new key/value pair if none existed for key previously.
+   * Resolves when the key/value show up in the store.
+   */
+  setItemAndWait(key: string, value: string): Promise<void>;
+
+  /**
+   * Remove the value of the key.
+   * Resolves when the key does not show up in the store.
+   */
+  removeItemAndWait(key: string): Promise<void>;
+}
+
+/**
+ * A key-value data store that can be used to persist data that should be shared across Pepr controllers and capabilities.
+ *
+ * The API is similar to the [Storage API](https://developer.mozilla.org/docs/Web/API/Storage)
+ */
+export class Storage implements PeprStore {
+  #store: DataStore = {};
+  #send!: DataSender;
+  #subscribers: Record<number, DataReceiver> = {};
+  #subscriberId = 0;
+  #readyHandlers: DataReceiver[] = [];
+
+  registerSender = (send: DataSender) => {
+    this.#send = send;
+  };
+
+  receive = (data: DataStore) => {
+    Log.debug(data, `Pepr store data received`);
+    this.#store = data || {};
+
+    this.#onReady();
+
+    // Notify all subscribers
+    for (const idx in this.#subscribers) {
+      // Send a unique clone of the store to each subscriber
+      this.#subscribers[idx](clone(this.#store));
+    }
+  };
+
+  getItem = (key: string) => {
+    // Return null if the value is the empty string
+    return this.#store[key] || null;
+  };
+
+  clear = () => {
+    this.#dispatchUpdate("remove", Object.keys(this.#store));
+  };
+
+  removeItem = (key: string) => {
+    this.#dispatchUpdate("remove", [key]);
+  };
+
+  setItem = (key: string, value: string) => {
+    this.#dispatchUpdate("add", [key], value);
+  };
+
+  /**
+   * Creates a promise and subscribes to the store, the promise resolves when
+   * the key and value are seen in the store.
+   *
+   * @param key - The key to add into the store
+   * @param value - The value of the key
+   * @returns
+   */
+  setItemAndWait = (key: string, value: string) => {
+    this.#dispatchUpdate("add", [key], value);
+    return new Promise<void>((resolve, reject) => {
+      const unsubscribe = this.subscribe(data => {
+        if (data[key] === value) {
+          unsubscribe();
+          resolve();
+        }
+      });
+
+      // If promise has not resolved before MAX_WAIT_TIME reject
+      setTimeout(() => {
+        unsubscribe();
+        return reject();
+      }, MAX_WAIT_TIME);
+    });
+  };
+
+  /**
+   * Creates a promise and subscribes to the store, the promise resolves when
+   * the key is removed from the store.
+   *
+   * @param key - The key to add into the store
+   * @returns
+   */
+  removeItemAndWait = (key: string) => {
+    this.#dispatchUpdate("remove", [key]);
+    return new Promise<void>((resolve, reject) => {
+      const unsubscribe = this.subscribe(data => {
+        if (!Object.hasOwn(data, key)) {
+          unsubscribe();
+          resolve();
+        }
+      });
+
+      // If promise has not resolved before MAX_WAIT_TIME reject
+      setTimeout(() => {
+        unsubscribe();
+        return reject();
+      }, MAX_WAIT_TIME);
+    });
+  };
+
+  subscribe = (subscriber: DataReceiver) => {
+    const idx = this.#subscriberId++;
+    this.#subscribers[idx] = subscriber;
+    return () => this.unsubscribe(idx);
+  };
+
+  onReady = (callback: DataReceiver) => {
+    this.#readyHandlers.push(callback);
+  };
+
+  /**
+   * Remove a subscriber from the list of subscribers.
+   * @param idx - The index of the subscriber to remove.
+   */
+  unsubscribe = (idx: number) => {
+    delete this.#subscribers[idx];
+  };
+
+  #onReady = () => {
+    // Notify all ready handlers with a clone of the store
+    for (const handler of this.#readyHandlers) {
+      handler(clone(this.#store));
+    }
+
+    // Make this a noop so that it can't be called again
+    this.#onReady = () => {};
+  };
+
+  /**
+   * Dispatch an update to the store and notify all subscribers.
+   * @param  op - The type of operation to perform.
+   * @param  keys - The keys to update.
+   * @param  [value] - The new value.
+   */
+  #dispatchUpdate = (op: DataOp, keys: string[], value?: string) => {
+    this.#send(op, keys, value);
+  };
+}

package/src/lib/tls.ts

@@ -0,0 +1,90 @@
+import forge from "node-forge";
+
+const caName = "Pepr Ephemeral CA";
+
+export interface TLSOut {
+  ca: string;
+  crt: string;
+  key: string;
+  pem: {
+    ca: string;
+    crt: string;
+    key: string;
+  };
+}
+
+/**
+ * Generates a self-signed CA and server certificate with Subject Alternative Names (SANs) for the K8s webhook.
+ *
+ * @param {string} name - The name to use for the server certificate's Common Name and SAN DNS entry.
+ * @returns {TLSOut} - An object containing the Base64-encoded CA, server certificate, and server private key.
+ */
+export function genTLS(name: string): TLSOut {
+  // Generate a new CA key pair and create a self-signed CA certificate
+  const caKeys = forge.pki.rsa.generateKeyPair(2048);
+  const caCert = genCert(caKeys, caName, [{ name: "commonName", value: caName }]);
+
+  caCert.setExtensions([
+    {
+      name: "basicConstraints",
+      cA: true,
+    },
+    {
+      name: "keyUsage",
+      keyCertSign: true,
+      digitalSignature: true,
+      nonRepudiation: true,
+      keyEncipherment: true,
+      dataEncipherment: true,
+    },
+  ]);
+
+  // Generate a new server key pair and create a server certificate signed by the CA
+  const serverKeys = forge.pki.rsa.generateKeyPair(2048);
+  const serverCert = genCert(serverKeys, name, caCert.subject.attributes);
+
+  // Sign both certificates with the CA private key
+  caCert.sign(caKeys.privateKey, forge.md.sha256.create());
+  serverCert.sign(caKeys.privateKey, forge.md.sha256.create());
+
+  // Convert the keys and certificates to PEM format
+  const pem = {
+    ca: forge.pki.certificateToPem(caCert),
+    crt: forge.pki.certificateToPem(serverCert),
+    key: forge.pki.privateKeyToPem(serverKeys.privateKey),
+  };
+
+  // Base64-encode the PEM strings
+  const ca = Buffer.from(pem.ca).toString("base64");
+  const key = Buffer.from(pem.key).toString("base64");
+  const crt = Buffer.from(pem.crt).toString("base64");
+
+  return { ca, key, crt, pem };
+}
+
+function genCert(key: forge.pki.rsa.KeyPair, name: string, issuer: forge.pki.CertificateField[]) {
+  const crt = forge.pki.createCertificate();
+  crt.publicKey = key.publicKey;
+  crt.serialNumber = "01";
+  crt.validity.notBefore = new Date();
+  crt.validity.notAfter = new Date();
+  crt.validity.notAfter.setFullYear(crt.validity.notBefore.getFullYear() + 1);
+
+  // Add SANs to the server certificate
+  crt.setExtensions([
+    {
+      name: "subjectAltName",
+      altNames: [
+        {
+          type: 2, // DNS
+          value: name,
+        },
+      ],
+    },
+  ]);
+
+  // Set the server certificate's issuer to the CA
+  crt.setIssuer(issuer);
+
+  return crt;
+}

package/src/lib/types.ts

@@ -0,0 +1,215 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { GenericClass, GroupVersionKind, KubernetesObject } from "kubernetes-fluent-client";
+import { WatchAction } from "kubernetes-fluent-client/dist/fluent/types";
+
+import { PeprMutateRequest } from "./mutate-request";
+import { PeprValidateRequest } from "./validate-request";
+
+/**
+ * Specifically for parsing logs in monitor mode
+ */
+export interface ResponseItem {
+  uid?: string;
+  allowed: boolean;
+  status: {
+    message: string;
+  };
+}
+/**
+ * Recursively make all properties in T optional.
+ */
+export type DeepPartial<T> = {
+  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+
+/**
+ * The type of Kubernetes mutating webhook event that the action is registered for.
+ */
+export enum Event {
+  Create = "CREATE",
+  Update = "UPDATE",
+  Delete = "DELETE",
+  CreateOrUpdate = "CREATEORUPDATE",
+  Any = "*",
+}
+
+export interface CapabilityCfg {
+  /**
+   * The name of the capability. This should be unique.
+   */
+  name: string;
+  /**
+   * A description of the capability and what it does.
+   */
+  description: string;
+  /**
+   * List of namespaces that this capability applies to, if empty, applies to all namespaces (cluster-wide).
+   * This does not supersede the `alwaysIgnore` global configuration.
+   */
+  namespaces?: string[];
+}
+
+export interface CapabilityExport extends CapabilityCfg {
+  bindings: Binding[];
+  hasSchedule: boolean;
+}
+
+export type WhenSelector<T extends GenericClass> = {
+  /** Register an action to be executed when a Kubernetes resource is created or updated. */
+  IsCreatedOrUpdated: () => BindingAll<T>;
+  /** Register an action to be executed when a Kubernetes resource is created. */
+  IsCreated: () => BindingAll<T>;
+  /** Register ann action to be executed when a Kubernetes resource is updated. */
+  IsUpdated: () => BindingAll<T>;
+  /** Register an action to be executed when a Kubernetes resource is deleted. */
+  IsDeleted: () => BindingAll<T>;
+};
+
+export type Binding = {
+  event: Event;
+  isMutate?: boolean;
+  isValidate?: boolean;
+  isWatch?: boolean;
+  isQueue?: boolean;
+  readonly model: GenericClass;
+  readonly kind: GroupVersionKind;
+  readonly filters: {
+    name: string;
+    namespaces: string[];
+    labels: Record<string, string>;
+    annotations: Record<string, string>;
+  };
+  readonly mutateCallback?: MutateAction<GenericClass, InstanceType<GenericClass>>;
+  readonly validateCallback?: ValidateAction<GenericClass, InstanceType<GenericClass>>;
+  readonly watchCallback?: WatchAction<GenericClass, InstanceType<GenericClass>>;
+};
+
+export type BindingFilter<T extends GenericClass> = CommonActionChain<T> & {
+  /**
+   * Only apply the action if the resource has the specified label. If no value is specified, the label must exist.
+   * Note multiple calls to this method will result in an AND condition. e.g.
+   *
+   * ```ts
+   * When(a.Deployment)
+   *   .IsCreated()
+   *   .WithLabel("foo", "bar")
+   *   .WithLabel("baz", "qux")
+   *   .Mutate(...)
+   * ```
+   *
+   * Will only apply the action if the resource has both the `foo=bar` and `baz=qux` labels.
+   *
+   * @param key
+   * @param value
+   */
+  WithLabel: (key: string, value?: string) => BindingFilter<T>;
+  /**
+   * Only apply the action if the resource has the specified annotation. If no value is specified, the annotation must exist.
+   * Note multiple calls to this method will result in an AND condition. e.g.
+   *
+   * ```ts
+   * When(a.Deployment)
+   *   .IsCreated()
+   *   .WithAnnotation("foo", "bar")
+   *   .WithAnnotation("baz", "qux")
+   *   .Mutate(...)
+   * ```
+   *
+   * Will only apply the action if the resource has both the `foo=bar` and `baz=qux` annotations.
+   *
+   * @param key
+   * @param value
+   */
+  WithAnnotation: (key: string, value?: string) => BindingFilter<T>;
+};
+
+export type BindingWithName<T extends GenericClass> = BindingFilter<T> & {
+  /** Only apply the action if the resource name matches the specified name. */
+  WithName: (name: string) => BindingFilter<T>;
+};
+
+export type BindingAll<T extends GenericClass> = BindingWithName<T> & {
+  /** Only apply the action if the resource is in one of the specified namespaces.*/
+  InNamespace: (...namespaces: string[]) => BindingWithName<T>;
+};
+
+export type CommonActionChain<T extends GenericClass> = MutateActionChain<T> & {
+  /**
+   * Create a new MUTATE action with the specified callback function and previously specified
+   * filters.
+   *
+   * @since 0.13.0
+   *
+   * @param action The action to be executed when the Kubernetes resource is processed by the AdmissionController.
+   */
+  Mutate: (action: MutateAction<T, InstanceType<T>>) => MutateActionChain<T>;
+};
+
+export type ValidateActionChain<T extends GenericClass> = {
+  /**
+   * Establish a watcher for the specified resource. The callback function will be executed after the admission controller has
+   * processed the resource and the request has been persisted to the cluster.
+   *
+   * **Beta Function**: This method is still in early testing and edge cases may still exist.
+   *
+   * @since 0.14.0
+   *
+   * @param action
+   * @returns
+   */
+  Watch: (action: WatchAction<T, InstanceType<T>>) => void;
+
+  /**
+   * Establish a reconcile for the specified resource. The callback function will be executed after the admission controller has
+   * processed the resource and the request has been persisted to the cluster.
+   *
+   * **Beta Function**: This method is still in early testing and edge cases may still exist.
+   *
+   * @since 0.14.0
+   *
+   * @param action
+   * @returns
+   */
+  Reconcile: (action: WatchAction<T, InstanceType<T>>) => void;
+};
+
+export type MutateActionChain<T extends GenericClass> = ValidateActionChain<T> & {
+  /**
+   * Create a new VALIDATE action with the specified callback function and previously specified
+   * filters. Return the `request.Approve()` or `Request.Deny()` methods to approve or deny the request:
+   *
+   * @since 0.13.0
+   *
+   * @example
+   * ```ts
+   * When(a.Deployment)
+   *  .IsCreated()
+   *  .Validate(request => {
+   *    if (request.HasLabel("foo")) {
+   *     return request.Approve();
+   *    }
+   *
+   *   return request.Deny("Deployment must have label foo");
+   * });
+   * ```
+   *
+   * @param action The action to be executed when the Kubernetes resource is processed by the AdmissionController.
+   */
+  Validate: (action: ValidateAction<T, InstanceType<T>>) => ValidateActionChain<T>;
+};
+
+export type MutateAction<T extends GenericClass, K extends KubernetesObject = InstanceType<T>> = (
+  req: PeprMutateRequest<K>,
+) => Promise<void> | void | Promise<PeprMutateRequest<K>> | PeprMutateRequest<K>;
+
+export type ValidateAction<T extends GenericClass, K extends KubernetesObject = InstanceType<T>> = (
+  req: PeprValidateRequest<K>,
+) => Promise<ValidateActionResponse> | ValidateActionResponse;
+
+export type ValidateActionResponse = {
+  allowed: boolean;
+  statusCode?: number;
+  statusMessage?: string;
+};

package/src/lib/utils.ts

@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import Log from "./logger";
+
+/** Test if a string is ascii or not */
+export const isAscii = /^[\s\x20-\x7E]*$/;
+
+/**
+ * Encode all ascii values in a map to base64
+ * @param obj The object to encode
+ * @param skip A list of keys to skip encoding
+ */
+export function convertToBase64Map(obj: { data?: Record<string, string> }, skip: string[]) {
+  obj.data = obj.data ?? {};
+  for (const key in obj.data) {
+    const value = obj.data[key];
+    // Only encode ascii values
+    obj.data[key] = skip.includes(key) ? value : base64Encode(value);
+  }
+}
+
+/**
+ * Decode all ascii values in a map from base64 to utf-8
+ * @param obj The object to decode
+ * @returns A list of keys that were skipped
+ */
+export function convertFromBase64Map(obj: { data?: Record<string, string> }) {
+  const skip: string[] = [];
+
+  obj.data = obj.data ?? {};
+  for (const key in obj.data) {
+    if (obj.data[key] == undefined) {
+      obj.data[key] = "";
+    } else {
+      const decoded = base64Decode(obj.data[key]);
+      if (isAscii.test(decoded)) {
+        // Only decode ascii values
+        obj.data[key] = decoded;
+      } else {
+        skip.push(key);
+      }
+    }
+  }
+  Log.debug(`Non-ascii data detected in keys: ${skip}, skipping automatic base64 decoding`);
+  return skip;
+}
+
+/** Decode a base64 string */
+export function base64Decode(data: string) {
+  return Buffer.from(data, "base64").toString("utf-8");
+}
+
+/** Encode a string to base64 */
+export function base64Encode(data: string) {
+  return Buffer.from(data).toString("base64");
+}

package/src/lib/validate-processor.ts

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2023-Present The Pepr Authors
+
+import { kind } from "kubernetes-fluent-client";
+
+import { Capability } from "./capability";
+import { shouldSkipRequest } from "./filter";
+import { AdmissionRequest, ValidateResponse } from "./k8s";
+import Log from "./logger";
+import { convertFromBase64Map } from "./utils";
+import { PeprValidateRequest } from "./validate-request";
+
+export async function validateProcessor(
+  capabilities: Capability[],
+  req: AdmissionRequest,
+  reqMetadata: Record<string, string>,
+): Promise<ValidateResponse[]> {
+  const wrapped = new PeprValidateRequest(req);
+  const response: ValidateResponse[] = [];
+
+  // If the resource is a secret, decode the data
+  const isSecret = req.kind.version == "v1" && req.kind.kind == "Secret";
+  if (isSecret) {
+    convertFromBase64Map(wrapped.Raw as unknown as kind.Secret);
+  }
+
+  Log.info(reqMetadata, `Processing validation request`);
+
+  for (const { name, bindings, namespaces } of capabilities) {
+    const actionMetadata = { ...reqMetadata, name };
+
+    for (const action of bindings) {
+      // Skip this action if it's not a validation action
+      if (!action.validateCallback) {
+        continue;
+      }
+
+      const localResponse: ValidateResponse = {
+        uid: req.uid,
+        allowed: true, // Assume it's allowed until a validation check fails
+      };
+
+      // Continue to the next action without doing anything if this one should be skipped
+      if (shouldSkipRequest(action, req, namespaces)) {
+        continue;
+      }
+
+      const label = action.validateCallback.name;
+      Log.info(actionMetadata, `Processing validation action (${label})`);
+
+      try {
+        // Run the validation callback, if it fails set allowed to false
+        const resp = await action.validateCallback(wrapped);
+        localResponse.allowed = resp.allowed;
+
+        // If the validation callback returned a status code or message, set it in the Response
+        if (resp.statusCode || resp.statusMessage) {
+          localResponse.status = {
+            code: resp.statusCode || 400,
+            message: resp.statusMessage || `Validation failed for ${name}`,
+          };
+        }
+
+        Log.info(actionMetadata, `Validation action complete (${label}): ${resp.allowed ? "allowed" : "denied"}`);
+      } catch (e) {
+        // If any validation throws an error, note the failure in the Response
+        Log.error(actionMetadata, `Action failed: ${JSON.stringify(e)}`);
+        localResponse.allowed = false;
+        localResponse.status = {
+          code: 500,
+          message: `Action failed with error: ${JSON.stringify(e)}`,
+        };
+        return [localResponse];
+      }
+      response.push(localResponse);
+    }
+  }
+
+  return response;
+}