@veducio/keja 0.0.0-stage → 0.3.0

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,128 @@
+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",
+        transit_key: null,
+        transit_mount: "transit",
+        grant_max_exp: 900,
+      },
+      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",
+          transit_key: null,
+          transit_mount: "transit",
+          grant_max_exp: 900,
+        },
+        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",
+    );
+  });
+});