@veducio/keja 0.0.0-stage → 0.3.0

package/src/vault/client.ts

@@ -0,0 +1,282 @@
+import { DependencyNotMet, projectError } from "../errors/framework-errors.ts";
+import { processValue } from "../process/slot.ts";
+import type { VaultSettings } from "../project/config.ts";
+
+const state = processValue("vault", () => ({
+  active: null as VaultSettings | null,
+  fetch: undefined as VaultClientOptions["fetch"] | undefined,
+}));
+
+export class VaultError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "VaultError";
+  }
+}
+
+export type VaultClientOptions = {
+  address?: string;
+  token?: string;
+  namespace?: string;
+  mount?: string;
+  fetch?: (url: string, init?: RequestInit) => Promise<Response>;
+};
+
+export function setVault(settings: VaultSettings | null) {
+  state.active = settings;
+  state.fetch = undefined;
+}
+
+export async function connectVault(
+  settings: VaultSettings,
+  fetchImpl?: VaultClientOptions["fetch"],
+) {
+  const fetch = fetchImpl ?? globalThis.fetch;
+  let response: Response;
+  try {
+    response = await fetch(`${settings.address}/v1/auth/token/lookup-self`, {
+      headers: vaultHeaders(settings.token, settings.namespace),
+    });
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : "request failed";
+    throw projectError("vaultInit", detail);
+  }
+  if (!response.ok) {
+    throw projectError(
+      "vaultInit",
+      (await vaultFailure(response, "auth/token/lookup-self")).message,
+    );
+  }
+  setVault(settings);
+  state.fetch = fetchImpl;
+}
+
+export function createVault(options: VaultClientOptions = {}) {
+  const address = vaultAddress(options.address ?? envValue("VAULT_ADDR"));
+  const token = required(
+    options.token ?? envValue("VAULT_TOKEN"),
+    "VAULT_TOKEN",
+  );
+  const namespace = options.namespace ?? envValue("VAULT_NAMESPACE");
+  const mount = secretMount(
+    options.mount ?? envValue("VAULT_KV_MOUNT") ?? "secret",
+  );
+  const fetchImpl = options.fetch ?? fetch;
+  const headers = () => vaultHeaders(token, namespace);
+  return {
+    async secret<
+      Data extends Record<string, unknown> = Record<string, unknown>,
+    >(path: string) {
+      const secretPath = normalizePath(path);
+      const response = await fetchImpl(
+        `${address}/v1/${mount}/data/${secretPath}`,
+        {
+          headers: headers(),
+        },
+      );
+      if (!response.ok) {
+        throw await vaultFailure(response, `${mount}/${secretPath}`);
+      }
+      const body = (await response.json()) as {
+        data?: { data?: Data };
+      };
+      if (!body.data?.data || typeof body.data.data !== "object") {
+        throw new VaultError(`Vault secret ${mount}/${secretPath} has no data`);
+      }
+      return body.data.data;
+    },
+    transitKey(mountName: string, key: string) {
+      const transit = secretMount(mountName);
+      const name = secretMount(key);
+      return vaultSend<{ type?: unknown; latest_version?: unknown }>(
+        fetchImpl,
+        `${address}/v1/${transit}/keys/${name}`,
+        { headers: headers() },
+        `${transit}/keys/${name}`,
+      );
+    },
+    transitSign(mountName: string, key: string, body: TransitSignBody) {
+      const transit = secretMount(mountName);
+      const name = secretMount(key);
+      return vaultSend<{ signature?: unknown }>(
+        fetchImpl,
+        `${address}/v1/${transit}/sign/${name}`,
+        {
+          method: "POST",
+          headers: jsonHeaders(headers()),
+          body: JSON.stringify(body),
+        },
+        `${transit}/sign/${name}`,
+      );
+    },
+    transitVerify(mountName: string, key: string, body: TransitVerifyBody) {
+      const transit = secretMount(mountName);
+      const name = secretMount(key);
+      return vaultSend<{ valid?: unknown }>(
+        fetchImpl,
+        `${address}/v1/${transit}/verify/${name}`,
+        {
+          method: "POST",
+          headers: jsonHeaders(headers()),
+          body: JSON.stringify(body),
+        },
+        `${transit}/verify/${name}`,
+      );
+    },
+  };
+}
+
+export function openVault(feature: string) {
+  const settings = requireVaultSettings(feature);
+  return createVault({
+    address: settings.address,
+    token: settings.token,
+    namespace: settings.namespace ?? undefined,
+    mount: settings.mount,
+    fetch: state.fetch,
+  });
+}
+
+export function requireVaultSettings(feature: string) {
+  if (!state.active) {
+    throw new DependencyNotMet(feature, "vault");
+  }
+  return state.active;
+}
+
+type TransitSignBody = {
+  input: string;
+  hash_algorithm?: string;
+  marshaling_algorithm?: string;
+  signature_algorithm?: string;
+};
+
+type TransitVerifyBody = TransitSignBody & {
+  signature: string;
+};
+
+export function vaultSecret<
+  Data extends Record<string, unknown> = Record<string, unknown>,
+>(path: string, options?: VaultClientOptions) {
+  if (!options) {
+    if (!state.active) {
+      throw new DependencyNotMet("vaultSecret", "vault");
+    }
+    return createVault({
+      address: state.active.address,
+      token: state.active.token,
+      namespace: state.active.namespace ?? undefined,
+      mount: state.active.mount,
+      fetch: state.fetch,
+    }).secret<Data>(path);
+  }
+  return createVault(options).secret<Data>(path);
+}
+
+function vaultAddress(value: string | null) {
+  if (!value) {
+    throw new VaultError("VAULT_ADDR is required");
+  }
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new VaultError("VAULT_ADDR must be an absolute http or https URL");
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new VaultError("VAULT_ADDR must be an absolute http or https URL");
+  }
+  return url.href.replace(/\/$/, "");
+}
+
+function secretMount(value: string) {
+  const mount = value.trim().replace(/^\/+|\/+$/g, "");
+  if (!/^[A-Za-z0-9_-]+$/.test(mount)) {
+    throw new VaultError(`invalid Vault mount: ${value}`);
+  }
+  return mount;
+}
+
+function normalizePath(path: string) {
+  const cleaned = path.trim().replace(/^\/+|\/+$/g, "");
+  const parts = cleaned.split("/");
+  if (
+    !cleaned ||
+    parts.some((part) => part.length === 0 || part === "." || part === "..")
+  ) {
+    throw new VaultError(`invalid Vault secret path: ${path}`);
+  }
+  return parts.map((part) => encodeURIComponent(part)).join("/");
+}
+
+async function vaultSend<Data>(
+  fetchImpl: VaultClientOptions["fetch"],
+  url: string,
+  init: RequestInit,
+  path: string,
+) {
+  const fetch = fetchImpl ?? globalThis.fetch;
+  const response = await fetch(url, init);
+  if (!response.ok) {
+    throw await vaultFailure(response, path);
+  }
+  const body = (await response.json()) as { data?: Data };
+  if (!body.data || typeof body.data !== "object") {
+    throw new VaultError(`Vault ${path} has no data`);
+  }
+  return body.data;
+}
+
+function jsonHeaders(headers: Headers) {
+  headers.set("Content-Type", "application/json");
+  return headers;
+}
+
+function vaultHeaders(token: string, namespace: string | null) {
+  const headers = new Headers({ "X-Vault-Token": token });
+  if (namespace) {
+    headers.set("X-Vault-Namespace", namespace);
+  }
+  return headers;
+}
+
+async function vaultFailure(response: Response, path: string) {
+  const errors = await vaultErrors(response);
+  if (response.status === 404) {
+    return new VaultError(`Vault secret ${path} was not found`);
+  }
+  const detail = errors.length > 0 ? `: ${errors.join(", ")}` : "";
+  return new VaultError(
+    `Vault rejected ${path} with status ${response.status}${detail}`,
+  );
+}
+
+async function vaultErrors(response: Response) {
+  try {
+    const body = (await response.json()) as { errors?: unknown };
+    if (!Array.isArray(body.errors)) {
+      return [];
+    }
+    return body.errors.filter(
+      (item): item is string => typeof item === "string",
+    );
+  } catch {
+    return [];
+  }
+}
+
+function required(value: string | null, name: string) {
+  if (!value) {
+    throw new VaultError(`${name} is required`);
+  }
+  return value;
+}
+
+function envValue(name: string) {
+  const runtime = globalThis as {
+    Bun?: { env?: Record<string, string | undefined> };
+  };
+  const value = runtime.Bun?.env?.[name] ?? process.env[name];
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : null;
+}

package/src/versioning/define.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import { defineRoute, response } from "../route/define.ts";
+import {
+  defineVersions,
+  parseReleasedAt,
+  resolveVersionToken,
+} from "./define.ts";
+
+const versions = defineVersions({
+  v1: { releasedAt: "2020-01-15" },
+  v2: { releasedAt: "01-06-2024" },
+}).versions;
+
+describe("parseReleasedAt", () => {
+  it("accepts calendar dates and unix timestamps", () => {
+    expect(parseReleasedAt("2020-09-20")).toBe(Date.UTC(2020, 8, 20));
+    expect(parseReleasedAt("20-09-2020")).toBe(Date.UTC(2020, 8, 20));
+    expect(parseReleasedAt(1_600_560_000)).toBe(1_600_560_000_000);
+    expect(parseReleasedAt(1_600_560_000_000)).toBe(1_600_560_000_000);
+    expect(parseReleasedAt("2020-13-40")).toBeNull();
+  });
+});
+
+describe("defineVersions", () => {
+  it("accepts v followed by a whole number", () => {
+    expect(
+      defineVersions({
+        v0: { releasedAt: "2020-01-15" },
+        v10: { releasedAt: "2024-06-01" },
+      }).versions.map((version) => version.number),
+    ).toEqual([0, 10]);
+  });
+
+  it("rejects a version that is not v followed by a whole number", () => {
+    expect(() =>
+      defineVersions({
+        "v1.2": { releasedAt: "2020-01-15" },
+      } as never),
+    ).toThrow("Version v1.2 must use the form v1, v2, v3");
+    expect(() =>
+      defineVersions({
+        v01: { releasedAt: "2020-01-15" },
+      } as never),
+    ).toThrow("Version v01 must use the form v1, v2, v3");
+  });
+});
+
+describe("defineRoute version", () => {
+  it("rejects a version that is not v followed by a whole number", () => {
+    expect(() =>
+      defineRoute({
+        method: "get",
+        path: "/users",
+        version: "v1.2",
+        responses: {
+          Ok: response({ code: 200, json: z.object({}) }),
+        },
+        handler: () => new Response(),
+      } as never),
+    ).toThrow("Version v1.2 must use the form v1, v2, v3");
+  });
+});
+
+describe("resolveVersionToken", () => {
+  it("selects the newest version that is not after the requested date", () => {
+    expect(resolveVersionToken("2020-09-20", versions)?.id).toBe("v1");
+    expect(resolveVersionToken("2024-06-01", versions)?.id).toBe("v2");
+    expect(resolveVersionToken("15-01-2020", versions)?.id).toBe("v1");
+    expect(resolveVersionToken("2019-01-01", versions)).toBeNull();
+  });
+
+  it("selects named versions and the latest keyword", () => {
+    expect(resolveVersionToken("v1", versions)?.id).toBe("v1");
+    expect(resolveVersionToken("v9", versions)).toBeNull();
+    expect(resolveVersionToken("latest", versions)?.id).toBe("v2");
+    expect(resolveVersionToken("CURRENT", versions)?.id).toBe("v2");
+  });
+});

package/src/versioning/define.ts

@@ -0,0 +1,173 @@
+import { projectError } from "../errors/framework-errors.ts";
+
+export type VersionDefinition = {
+  id: string;
+  number: number;
+  releasedAt: number;
+};
+
+const versionKey = /^v(0|[1-9]\d*)$/;
+const isoDate = /^(\d{4})-(\d{2})-(\d{2})$/;
+const dayMonthYear = /^(\d{2})-(\d{2})-(\d{4})$/;
+
+export function parseReleasedAt(value: string | number): number | null {
+  if (typeof value === "number") {
+    return unixMilliseconds(value);
+  }
+  const text = value.trim();
+  if (/^\d+$/.test(text)) {
+    return unixMilliseconds(Number(text));
+  }
+  const iso = isoDate.exec(text);
+  if (iso) {
+    return calendarUtc(Number(iso[1]), Number(iso[2]), Number(iso[3]));
+  }
+  const dmy = dayMonthYear.exec(text);
+  if (dmy) {
+    return calendarUtc(Number(dmy[3]), Number(dmy[2]), Number(dmy[1]));
+  }
+  return null;
+}
+
+type WholeNumber<Value extends string> = Value extends `${bigint}`
+  ? Value extends `-${string}` | `0${string}`
+    ? Value extends "0"
+      ? Value
+      : never
+    : Value
+  : never;
+
+export type VersionId<Value extends string> = Value extends `v${infer Rest}`
+  ? WholeNumber<Rest> extends never
+    ? never
+    : Value
+  : never;
+
+type VersionRecord = Record<string, { releasedAt: string | number }>;
+
+type CheckedVersions<Versions extends VersionRecord> = {
+  [Key in keyof Versions]: Key extends string
+    ? VersionId<Key> extends never
+      ? "Version must use the form v1, v2, v3"
+      : Versions[Key]
+    : never;
+};
+
+export function readVersionNumber(id: string): number | null {
+  const match = versionKey.exec(id);
+  if (!match) {
+    return null;
+  }
+  const number = Number(match[1]);
+  if (!Number.isSafeInteger(number) || String(number) !== match[1]) {
+    return null;
+  }
+  return number;
+}
+
+export function defineVersions<const Versions extends VersionRecord>(
+  versions: Versions & CheckedVersions<Versions>,
+) {
+  const parsed = Object.entries(versions).map(([id, version]) => {
+    const number = readVersionNumber(id);
+    if (number === null) {
+      throw projectError(
+        "invalidVersionId",
+        `Version ${id} must use the form v1, v2, v3`,
+      );
+    }
+    const releasedAt = parseReleasedAt(version.releasedAt);
+    if (releasedAt === null) {
+      throw projectError(
+        "invalidReleaseDate",
+        `Version ${id} has an invalid release date`,
+      );
+    }
+    return {
+      id,
+      number,
+      releasedAt,
+    };
+  });
+  return {
+    versions: parsed.sort(compareVersions),
+  };
+}
+
+export function isVersions(
+  value: unknown,
+): value is { versions: VersionDefinition[] } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "versions" in value &&
+    Array.isArray(value.versions)
+  );
+}
+
+export function newestVersion(versions: readonly VersionDefinition[]) {
+  return [...versions].sort(compareVersions).at(-1) ?? null;
+}
+
+export function resolveVersionToken(
+  token: string,
+  versions: readonly VersionDefinition[],
+) {
+  if (versions.length === 0) {
+    return null;
+  }
+  const keyword = token.toLowerCase();
+  if (keyword === "latest" || keyword === "current") {
+    return newestVersion(versions);
+  }
+  if (versionKey.test(token)) {
+    return versions.find((version) => version.id === token) ?? null;
+  }
+  const releasedAt = parseReleasedAt(token);
+  if (releasedAt === null) {
+    return null;
+  }
+  const eligible = versions.filter(
+    (version) => version.releasedAt <= releasedAt,
+  );
+  return newestVersion(eligible);
+}
+
+export function isAfterVersion(
+  candidate: VersionDefinition,
+  requested: VersionDefinition,
+) {
+  if (candidate.releasedAt !== requested.releasedAt) {
+    return candidate.releasedAt > requested.releasedAt;
+  }
+  return candidate.number > requested.number;
+}
+
+function unixMilliseconds(value: number) {
+  if (!Number.isFinite(value) || value < 0) {
+    return null;
+  }
+  return value >= 1_000_000_000_000 ? value : value * 1000;
+}
+
+function calendarUtc(year: number, month: number, day: number) {
+  if (month < 1 || month > 12 || day < 1 || day > 31) {
+    return null;
+  }
+  const date = new Date(Date.UTC(year, month - 1, day));
+  if (
+    date.getUTCFullYear() !== year ||
+    date.getUTCMonth() !== month - 1 ||
+    date.getUTCDate() !== day
+  ) {
+    return null;
+  }
+  return date.getTime();
+}
+
+function compareVersions(left: VersionDefinition, right: VersionDefinition) {
+  if (left.releasedAt !== right.releasedAt) {
+    return left.releasedAt - right.releasedAt;
+  }
+  return left.number - right.number;
+}

package/src/versioning/select.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import { defineRoute, response } from "../route/define.ts";
+import { defineVersions } from "./define.ts";
+import { selectRoute } from "./select.ts";
+
+const versions = defineVersions({
+  v1: { releasedAt: "2020-01-15" },
+  v2: { releasedAt: "2024-06-01" },
+}).versions;
+
+const user = z.object({ id: z.string() });
+
+const routes = [
+  defineRoute({
+    method: "get",
+    path: "/users/:id",
+    version: "v1",
+    request: { params: user },
+    responses: {
+      User: response({ code: 200, json: user }),
+    },
+    handler: ({ params, respond }) => respond.User(params),
+  }),
+  defineRoute({
+    method: "get",
+    path: "/reports",
+    version: "v2",
+    responses: {
+      Ready: response({ code: 200, json: z.object({ ok: z.literal(true) }) }),
+    },
+    handler: ({ respond }) => respond.Ready({ ok: true }),
+  }),
+];
+
+describe("selectRoute", () => {
+  it("uses the newest handler that is not after the requested version", () => {
+    const v2 = versions.find((version) => version.id === "v2");
+    const v1 = versions.find((version) => version.id === "v1");
+    if (!v2 || !v1) {
+      throw new Error("missing versions");
+    }
+    expect(
+      selectRoute(routes, versions, "GET", "/users/1", v2)?.route.version,
+    ).toBe("v1");
+    expect(selectRoute(routes, versions, "GET", "/reports", v1)).toBeNull();
+    expect(
+      selectRoute(routes, versions, "GET", "/reports", v2)?.route.version,
+    ).toBe("v2");
+  });
+
+  it("matches a route nested several segments deep", () => {
+    const v1 = versions.find((version) => version.id === "v1");
+    if (!v1) {
+      throw new Error("missing versions");
+    }
+    const deep = defineRoute({
+      method: "get",
+      path: "/orgs/:orgId/teams/:teamId/members/:memberId",
+      version: "v1",
+      responses: {
+        Member: response({ code: 200, json: z.object({ id: z.string() }) }),
+      },
+      handler: ({ respond }) => respond.Member({ id: "ada" }),
+    });
+    const selected = selectRoute(
+      [deep],
+      versions,
+      "GET",
+      "/orgs/acme/teams/core/members/ada",
+      v1,
+    );
+    expect(selected?.params).toEqual({
+      orgId: "acme",
+      teamId: "core",
+      memberId: "ada",
+    });
+  });
+});

package/src/versioning/select.ts

@@ -0,0 +1,62 @@
+import type { RouteDefinition } from "../route/define.ts";
+import {
+  isAfterVersion,
+  type VersionDefinition,
+} from "../versioning/define.ts";
+
+export function matchPath(pattern: string, pathname: string) {
+  const expected = segments(pattern);
+  const actual = segments(pathname);
+  if (expected.length !== actual.length) {
+    return null;
+  }
+  const params: Record<string, string> = {};
+  for (const [index, part] of expected.entries()) {
+    const value = actual[index] ?? "";
+    if (part.startsWith(":")) {
+      params[part.slice(1)] = decodeURIComponent(value);
+      continue;
+    }
+    if (part !== value) {
+      return null;
+    }
+  }
+  return params;
+}
+
+export function selectRoute(
+  routes: readonly RouteDefinition[],
+  versions: readonly VersionDefinition[],
+  method: string,
+  pathname: string,
+  requested: VersionDefinition,
+) {
+  const matches = [];
+  for (const route of routes) {
+    if (route.method !== method.toLowerCase()) {
+      continue;
+    }
+    const params = matchPath(route.path, pathname);
+    if (!params) {
+      continue;
+    }
+    const version = versions.find((item) => item.id === route.version);
+    if (!version || isAfterVersion(version, requested)) {
+      continue;
+    }
+    matches.push({ route, params, version });
+  }
+  matches.sort((left, right) => {
+    if (left.version.releasedAt !== right.version.releasedAt) {
+      return right.version.releasedAt - left.version.releasedAt;
+    }
+    return right.version.number - left.version.number;
+  });
+  return matches[0] ?? null;
+}
+
+function segments(value: string) {
+  const normalized =
+    value.length > 1 && value.endsWith("/") ? value.slice(0, -1) : value;
+  return normalized.split("/").filter((part) => part.length > 0);
+}