@veducio/keja 0.0.0-stage → 0.2.3

package/src/typeid/id.ts

@@ -0,0 +1,136 @@
+import { fromString, getSuffix, getType, typeid } from "typeid-js";
+
+const typePrefix = /^[a-z](?:[a-z_]{0,61}[a-z])?$/;
+const objectSegment = /^(?:v[0-9]+|[a-z](?:[a-z_]{0,61}[a-z])?)$/;
+
+export type ObjectRowMeta = {
+  _id: string;
+  _object: string;
+  _tenant: string;
+  _archived: false;
+  _createdAt: Date;
+  _updatedAt: Date;
+};
+
+export type CreateObjectRowOptions = {
+  tenant: string;
+  idPrefix?: string;
+};
+
+export type ParsedTypeId = {
+  prefix: string;
+  suffix: string;
+};
+
+export class TypeIdError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "TypeIdError";
+  }
+}
+
+export function objectTypeFromRoute(version: number, routePath: string) {
+  const segments = routePath.split("/").filter(Boolean);
+  if (segments.length === 0) {
+    throw new TypeIdError(
+      `route path must include at least one segment: ${routePath}`,
+    );
+  }
+  if (!Number.isInteger(version) || version < 1) {
+    throw new TypeIdError(`invalid API version: ${version}`);
+  }
+  for (const segment of segments) {
+    if (!typePrefix.test(segment)) {
+      throw new TypeIdError(
+        `invalid route segment "${segment}" in ${routePath}`,
+      );
+    }
+  }
+  return [`v${version}`, ...segments].join(".");
+}
+
+export function idPrefixFromObjectType(objectType: string) {
+  assertObjectType(objectType);
+  const prefix = objectType.split(".").at(-1);
+  if (!(prefix && typePrefix.test(prefix))) {
+    throw new TypeIdError(
+      `cannot derive type prefix from object type: ${objectType}`,
+    );
+  }
+  return prefix;
+}
+
+export function assertObjectType(objectType: string) {
+  const segments = objectType.split(".");
+  if (segments.length < 2) {
+    throw new TypeIdError(
+      `object type must be route-derived (e.g. v2.core.users), got: ${objectType}`,
+    );
+  }
+  for (const segment of segments) {
+    if (!objectSegment.test(segment)) {
+      throw new TypeIdError(
+        `invalid object type segment "${segment}" in ${objectType}`,
+      );
+    }
+  }
+  if (!/^v[0-9]+$/.test(segments[0] ?? "")) {
+    throw new TypeIdError(
+      `object type must start with vN (e.g. v2.core.users), got: ${objectType}`,
+    );
+  }
+}
+
+export function isObjectType(objectType: string) {
+  try {
+    assertObjectType(objectType);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function createTypeId(prefix: string) {
+  assertTypePrefix(prefix);
+  return typeid(prefix).toString();
+}
+
+export function isTypeId(value: string, prefix: string) {
+  return parseTypeId(value)?.prefix === prefix;
+}
+
+export function parseTypeId(value: string): ParsedTypeId | null {
+  try {
+    const parsed = fromString(value);
+    const prefix = getType(parsed);
+    if (!typePrefix.test(prefix)) {
+      return null;
+    }
+    return { prefix, suffix: getSuffix(parsed) };
+  } catch {
+    return null;
+  }
+}
+
+export function createObjectRow(
+  objectType: string,
+  options: CreateObjectRowOptions,
+): ObjectRowMeta {
+  assertObjectType(objectType);
+  const prefix = options.idPrefix ?? idPrefixFromObjectType(objectType);
+  const now = new Date();
+  return {
+    _id: createTypeId(prefix),
+    _object: objectType,
+    _tenant: options.tenant,
+    _archived: false,
+    _createdAt: now,
+    _updatedAt: now,
+  };
+}
+
+function assertTypePrefix(prefix: string) {
+  if (!typePrefix.test(prefix)) {
+    throw new TypeIdError(`invalid type prefix: ${prefix}`);
+  }
+}

package/src/typeid/owned.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from "vitest";
+import { createTypeId } from "./id.ts";
+import { assertOwnedCall, assertOwnedObject } from "./owned.ts";
+
+const now = new Date("2026-01-01T00:00:00.000Z");
+const row = {
+  _id: createTypeId("user"),
+  _object: "v2.user",
+  _tenant: "tenant_1",
+  _archived: false,
+  _createdAt: now,
+  _updatedAt: now,
+  actor_id: "232532fsarrw23",
+  active: true,
+  message: "wewesraewe wew eas",
+};
+
+describe("assertOwnedObject", () => {
+  it("accepts reserved fields plus domain columns", () => {
+    expect(assertOwnedObject(row)).toEqual(row);
+  });
+
+  it("rejects a reserved field that is not part of OwnedObjects", () => {
+    expect(() => assertOwnedObject({ ...row, _secret: "no" })).toThrow(
+      "OwnedObjects field _secret is reserved",
+    );
+    expect(() => assertOwnedObject({ ...row, _id: "user_short" })).toThrow(
+      "OwnedObjects _id must be a typeid",
+    );
+    expect(() =>
+      assertOwnedObject({
+        ...row,
+        _updatedAt: new Date("2025-01-01T00:00:00.000Z"),
+      }),
+    ).toThrow("OwnedObjects _updatedAt must be at or after _createdAt");
+  });
+});
+
+describe("assertOwnedCall", () => {
+  it("requires an insert to carry OwnedObjects", () => {
+    expect(() =>
+      assertOwnedCall("insert into notes (message) values ($1)", ["hi"]),
+    ).toThrow("insert must include _id");
+    expect(() =>
+      assertOwnedCall("insert into notes ", [{ message: "hi" }]),
+    ).toThrow("OwnedObjects _id must be a typeid");
+    expect(() => assertOwnedCall("insert into notes ", [row])).not.toThrow();
+    expect(() =>
+      assertOwnedCall("insert into notes ", [new InsertHelper([row])]),
+    ).not.toThrow();
+    expect(() =>
+      assertOwnedCall("insert into notes ", [
+        new InsertHelper([{ message: "hi" }]),
+      ]),
+    ).toThrow("OwnedObjects _id must be a typeid");
+  });
+
+  it("checks OwnedObjects fields on update and ignores reads", () => {
+    expect(() =>
+      assertOwnedCall("update notes set message = $1", [{ message: "next" }]),
+    ).not.toThrow();
+    expect(() =>
+      assertOwnedCall("update notes set _archived = $1", [
+        { _archived: "yes" },
+      ]),
+    ).toThrow("OwnedObjects _archived must be a boolean");
+    expect(() => assertOwnedCall("select * from notes", [])).not.toThrow();
+  });
+});
+
+class InsertHelper {
+  constructor(readonly value: readonly Record<string, unknown>[]) {}
+}

package/src/typeid/owned.ts

@@ -0,0 +1,193 @@
+import { isObjectType, parseTypeId, TypeIdError } from "./id.ts";
+
+const reserved = new Set([
+  "_id",
+  "_object",
+  "_tenant",
+  "_archived",
+  "_createdAt",
+  "_updatedAt",
+]);
+
+export type OwnedObject = {
+  _id: string;
+  _object: string;
+  _tenant: string;
+  _archived: boolean;
+  _createdAt: Date;
+  _updatedAt: Date;
+} & Record<string, unknown>;
+
+export function assertOwnedObject(value: unknown): OwnedObject {
+  const row = plainRow(value);
+  if (!row) {
+    throw new TypeIdError("OwnedObjects must be an object");
+  }
+  assertId(row._id);
+  assertObject(row._object);
+  assertTenant(row._tenant);
+  assertArchived(row._archived);
+  assertCreatedAt(row._createdAt);
+  assertUpdatedAt(row._createdAt, row._updatedAt);
+  assertDomainKeys(row);
+  return row as OwnedObject;
+}
+
+export function assertOwnedCall(sql: string, values: readonly unknown[]) {
+  const kind = writeKind(sql);
+  if (!kind) {
+    return;
+  }
+  const rows = rowsOf(values);
+  if (kind === "insert" && rows.length === 0) {
+    for (const column of reserved) {
+      if (!namesColumn(sql, column)) {
+        throw new TypeIdError(`insert must include ${column}`);
+      }
+    }
+    return;
+  }
+  for (const row of rows) {
+    if (kind === "insert") {
+      assertOwnedObject(row);
+      continue;
+    }
+    assertPresentFields(row);
+  }
+}
+
+function assertPresentFields(row: Record<string, unknown>) {
+  if ("_id" in row) {
+    assertId(row._id);
+  }
+  if ("_object" in row) {
+    assertObject(row._object);
+  }
+  if ("_tenant" in row) {
+    assertTenant(row._tenant);
+  }
+  if ("_archived" in row) {
+    assertArchived(row._archived);
+  }
+  if ("_createdAt" in row) {
+    assertCreatedAt(row._createdAt);
+  }
+  if ("_updatedAt" in row) {
+    const created = "_createdAt" in row ? row._createdAt : row._updatedAt;
+    assertUpdatedAt(created, row._updatedAt);
+  }
+  assertDomainKeys(row);
+}
+
+function assertId(value: unknown) {
+  if (typeof value !== "string" || !parseTypeId(value)) {
+    throw new TypeIdError("OwnedObjects _id must be a typeid");
+  }
+}
+
+function assertObject(value: unknown) {
+  if (typeof value !== "string" || !isObjectType(value)) {
+    throw new TypeIdError("OwnedObjects _object must be an object type");
+  }
+}
+
+function assertTenant(value: unknown) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new TypeIdError("OwnedObjects _tenant must be a tenant id");
+  }
+}
+
+function assertArchived(value: unknown) {
+  if (typeof value !== "boolean") {
+    throw new TypeIdError("OwnedObjects _archived must be a boolean");
+  }
+}
+
+function assertCreatedAt(value: unknown) {
+  if (!(value instanceof Date) || Number.isNaN(value.getTime())) {
+    throw new TypeIdError("OwnedObjects _createdAt must be a timestamp");
+  }
+}
+
+function assertUpdatedAt(created: unknown, updated: unknown) {
+  if (!(updated instanceof Date) || Number.isNaN(updated.getTime())) {
+    throw new TypeIdError("OwnedObjects _updatedAt must be a timestamp");
+  }
+  if (created instanceof Date && updated.getTime() < created.getTime()) {
+    throw new TypeIdError(
+      "OwnedObjects _updatedAt must be at or after _createdAt",
+    );
+  }
+}
+
+function assertDomainKeys(row: Record<string, unknown>) {
+  for (const key of Object.keys(row)) {
+    if (key.startsWith("_") && !reserved.has(key)) {
+      throw new TypeIdError(`OwnedObjects field ${key} is reserved`);
+    }
+  }
+}
+
+function writeKind(sql: string) {
+  const stripped = sql
+    .replace(/\/\*[\s\S]*?\*\//g, " ")
+    .replace(/--.*$/gm, " ")
+    .trim();
+  const word = stripped.match(/^[a-z]+/i)?.[0]?.toLowerCase();
+  if (word === "insert") {
+    return "insert";
+  }
+  if (word === "update") {
+    return "update";
+  }
+  if (word === "with" && /\binsert\b/i.test(stripped)) {
+    return "insert";
+  }
+  if (word === "with" && /\bupdate\b/i.test(stripped)) {
+    return "update";
+  }
+  return null;
+}
+
+function namesColumn(sql: string, column: string) {
+  return new RegExp(`(^|[^a-z0-9])${column}([^a-z0-9]|$)`, "i").test(sql);
+}
+
+function rowsOf(values: readonly unknown[]) {
+  const rows: Record<string, unknown>[] = [];
+  for (const value of values) {
+    if (Array.isArray(value)) {
+      rows.push(...rowsOf(value));
+      continue;
+    }
+    const row = plainRow(value);
+    if (row) {
+      rows.push(row);
+      continue;
+    }
+    const nested = helperRows(value);
+    if (nested) {
+      rows.push(...rowsOf(nested));
+    }
+  }
+  return rows;
+}
+
+function helperRows(value: unknown) {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+  const helper = value as { value?: unknown };
+  return Array.isArray(helper.value) ? helper.value : null;
+}
+
+function plainRow(value: unknown) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== Object.prototype && proto !== null) {
+    return null;
+  }
+  return value as Record<string, unknown>;
+}

package/src/vault/client.test.ts

@@ -0,0 +1,122 @@
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  connectVault,
+  createVault,
+  setVault,
+  VaultError,
+  vaultSecret,
+} from "./client.ts";
+
+describe("createVault", () => {
+  afterEach(() => {
+    setVault(null);
+  });
+  it("reads a KV v2 secret and returns its data", async () => {
+    const calls: {
+      url: string;
+      token: string | null;
+      namespace: string | null;
+    }[] = [];
+    const client = createVault({
+      address: "https://vault.example/",
+      token: "s.token",
+      namespace: "apps",
+      fetch: async (url, init) => {
+        const headers = new Headers(init?.headers);
+        calls.push({
+          url,
+          token: headers.get("X-Vault-Token"),
+          namespace: headers.get("X-Vault-Namespace"),
+        });
+        return Response.json({
+          data: {
+            data: { password: "secret" },
+            metadata: { version: 3 },
+          },
+        });
+      },
+    });
+    await expect(client.secret("apps/keja")).resolves.toEqual({
+      password: "secret",
+    });
+    expect(calls).toEqual([
+      {
+        url: "https://vault.example/v1/secret/data/apps/keja",
+        token: "s.token",
+        namespace: "apps",
+      },
+    ]);
+  });
+
+  it("reports a missing secret without the token", async () => {
+    const client = createVault({
+      address: "https://vault.example",
+      token: "s.token",
+      mount: "kv",
+      fetch: async () =>
+        Response.json({ errors: ["permission denied"] }, { status: 403 }),
+    });
+    await expect(client.secret("apps/keja")).rejects.toThrow(
+      "Vault rejected kv/apps/keja with status 403: permission denied",
+    );
+    await expect(
+      createVault({
+        address: "https://vault.example",
+        token: "s.token",
+        fetch: async () => new Response(null, { status: 404 }),
+      }).secret("missing"),
+    ).rejects.toThrow(VaultError);
+  });
+
+  it("requires an address and a token", () => {
+    expect(() => createVault({ token: "s.token" })).toThrow(
+      "VAULT_ADDR is required",
+    );
+    expect(() => createVault({ address: "https://vault.example" })).toThrow(
+      "VAULT_TOKEN is required",
+    );
+  });
+
+  it("looks up the token before vaultSecret uses the config client", async () => {
+    const urls: string[] = [];
+    await connectVault(
+      {
+        address: "https://vault.example",
+        token: "s.token",
+        namespace: null,
+        mount: "secret",
+      },
+      async (url) => {
+        urls.push(url);
+        if (url.endsWith("/v1/auth/token/lookup-self")) {
+          return Response.json({ data: { id: "s.token" } });
+        }
+        return Response.json({ data: { data: { password: "secret" } } });
+      },
+    );
+    await expect(vaultSecret("apps/keja")).resolves.toEqual({
+      password: "secret",
+    });
+    expect(urls[0]).toBe("https://vault.example/v1/auth/token/lookup-self");
+  });
+
+  it("turns a rejected token lookup into a project error", async () => {
+    await expect(
+      connectVault(
+        {
+          address: "https://vault.example",
+          token: "s.token",
+          namespace: null,
+          mount: "secret",
+        },
+        async () =>
+          Response.json({ errors: ["permission denied"] }, { status: 403 }),
+      ),
+    ).rejects.toThrow(
+      "Vault rejected auth/token/lookup-self with status 403: permission denied",
+    );
+    expect(() => vaultSecret("apps/keja")).toThrow(
+      "vaultSecret requires vault",
+    );
+  });
+});

package/src/vault/client.ts

@@ -0,0 +1,191 @@
+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;
+  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: vaultHeaders(token, namespace),
+        },
+      );
+      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;
+    },
+  };
+}
+
+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("/");
+}
+
+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;
+}