@forgezero/runtime 0.1.0

package/dist/queue.js

@@ -0,0 +1,246 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined")
+    return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/queue.ts
+var systemClock = { now: () => Date.now() };
+var UNITS = { s: 1000, m: 60000, h: 3600000, d: 86400000 };
+function durationMs(value) {
+  if (typeof value === "number")
+    return value;
+  const match = /^(\d+)([smhd])$/.exec(value);
+  if (!match)
+    throw new Error(`"${value}" is not a duration like 30s, 5m, 1h, 1d.`);
+  return Number(match[1]) * UNITS[match[2]];
+}
+var MODES = ["standalone", "cluster"];
+function memoryStore(clock = systemClock) {
+  const messages = new Map;
+  const leases = new Map;
+  let fences = 0;
+  const all = (queue) => messages.get(queue) ?? [];
+  return {
+    mode: "standalone",
+    async append(queue, message) {
+      messages.set(queue, [...all(queue), message]);
+    },
+    async findByDedupe(queue, dedupeKey, sinceMs) {
+      return all(queue).find((message) => message.dedupeKey === dedupeKey && message.enqueuedAtMs >= sinceMs) ?? null;
+    },
+    async claimKey(queue, owner, ttlMs, nowMs) {
+      const ready = all(queue).filter((message) => message.status === "ready" && message.availableAtMs <= nowMs);
+      for (const message of ready.sort((a, b) => a.sequence - b.sequence)) {
+        const held = leases.get(`${queue}\x00${message.key}`);
+        if (held && held.untilMs > nowMs)
+          continue;
+        fences += 1;
+        const lease = { key: message.key, fence: fences, untilMs: nowMs + ttlMs, owner };
+        leases.set(`${queue}\x00${message.key}`, lease);
+        return lease;
+      }
+      return null;
+    },
+    async renewKey(queue, lease, ttlMs, nowMs) {
+      const held = leases.get(`${queue}\x00${lease.key}`);
+      if (!held || held.fence !== lease.fence)
+        return false;
+      held.untilMs = nowMs + ttlMs;
+      return true;
+    },
+    async releaseKey(queue, lease) {
+      const held = leases.get(`${queue}\x00${lease.key}`);
+      if (held?.fence === lease.fence)
+        leases.delete(`${queue}\x00${lease.key}`);
+    },
+    async readKey(queue, key, nowMs, limit) {
+      return all(queue).filter((message) => message.key === key && message.status === "ready" && message.availableAtMs <= nowMs).sort((a, b) => a.sequence - b.sequence).slice(0, limit);
+    },
+    async update(queue, id, patch) {
+      const message = all(queue).find((entry) => entry.id === id);
+      if (message)
+        Object.assign(message, patch);
+    },
+    async stats(queue) {
+      const list = all(queue);
+      return {
+        ready: list.filter((message) => message.status === "ready").length,
+        leased: list.filter((message) => message.status === "leased").length,
+        dead: list.filter((message) => message.status === "dead").length,
+        keys: new Set(list.filter((message) => message.status === "ready").map((m) => m.key)).size
+      };
+    },
+    async dead(queue, limit) {
+      return all(queue).filter((message) => message.status === "dead").sort((a, b) => b.sequence - a.sequence).slice(0, limit);
+    }
+  };
+}
+function createQueue(options) {
+  const {
+    name,
+    store,
+    handler,
+    concurrency = 4,
+    leaseMs = 30000,
+    maxAttempts = 5,
+    backoffMs = 1000,
+    maxBackoffMs = 60000,
+    dedupeWindowMs = 300000,
+    batch = 32,
+    clock = systemClock,
+    owner = `worker-${Math.trunc(clock.now())}`
+  } = options;
+  if (options.require && store.mode !== options.require) {
+    throw new Error(`Queue "${name}" requires a ${options.require} store but was given a ${store.mode} one. ` + "A memory store loses everything on restart.");
+  }
+  let sequence = 0;
+  let running = false;
+  let inFlight = 0;
+  const held = new Set;
+  const backoffFor = (attempt) => Math.min(maxBackoffMs, backoffMs * 2 ** Math.max(0, attempt - 1));
+  async function enqueue(args) {
+    if (!args.key)
+      throw new Error("Every message needs a key — it is what orders the work.");
+    const nowMs = clock.now();
+    if (args.dedupeKey) {
+      const existing = await store.findByDedupe(name, args.dedupeKey, nowMs - dedupeWindowMs);
+      if (existing)
+        return { id: existing.id, duplicate: true };
+    }
+    sequence += 1;
+    const message = {
+      id: `${name}-${nowMs}-${sequence}`,
+      key: args.key,
+      body: args.body,
+      sequence,
+      status: "ready",
+      attempts: 0,
+      availableAtMs: nowMs + (args.delayMs ?? 0),
+      dedupeKey: args.dedupeKey,
+      enqueuedAtMs: nowMs
+    };
+    await store.append(name, message);
+    return { id: message.id, duplicate: false };
+  }
+  async function drainKey(lease) {
+    try {
+      for (let taken = 0;taken < batch; taken += 1) {
+        const nowMs = clock.now();
+        if (!await store.renewKey(name, lease, leaseMs, nowMs))
+          return;
+        const [message] = await store.readKey(name, lease.key, nowMs, 1);
+        if (!message)
+          return;
+        await store.update(name, message.id, { status: "leased", attempts: message.attempts + 1 });
+        try {
+          await handler({ ...message, attempts: message.attempts + 1 }, {
+            holdsKey: () => store.renewKey(name, lease, leaseMs, clock.now()),
+            log: (line) => options.onError?.({ ...message }, line),
+            attempt: message.attempts + 1
+          });
+          await store.update(name, message.id, { status: "done", completedAtMs: clock.now() });
+        } catch (cause) {
+          const attempts = message.attempts + 1;
+          const reason = cause instanceof Error ? cause.message : String(cause);
+          options.onError?.(message, cause);
+          if (attempts >= maxAttempts) {
+            await store.update(name, message.id, { status: "dead", lastError: reason });
+            continue;
+          }
+          await store.update(name, message.id, {
+            status: "ready",
+            lastError: reason,
+            availableAtMs: clock.now() + backoffFor(attempts)
+          });
+          return;
+        }
+      }
+    } finally {
+      await store.releaseKey(name, lease);
+      held.delete(lease.key);
+    }
+  }
+  async function tick() {
+    const claimed = [];
+    while (inFlight + claimed.length < concurrency) {
+      const lease = await store.claimKey(name, owner, leaseMs, clock.now());
+      if (!lease)
+        break;
+      if (held.has(lease.key))
+        break;
+      held.add(lease.key);
+      claimed.push(lease);
+    }
+    if (claimed.length === 0)
+      return 0;
+    inFlight += claimed.length;
+    try {
+      await Promise.all(claimed.map((lease) => drainKey(lease)));
+    } finally {
+      inFlight -= claimed.length;
+    }
+    return claimed.length;
+  }
+  return {
+    enqueue,
+    tick,
+    async drain(maxPasses = 100) {
+      for (let pass = 0;pass < maxPasses; pass += 1) {
+        if (await tick() === 0)
+          return;
+      }
+    },
+    start(intervalMs = 200) {
+      if (running)
+        return;
+      running = true;
+      const loop = async () => {
+        while (running) {
+          try {
+            if (await tick() === 0)
+              await new Promise((r) => setTimeout(r, intervalMs));
+          } catch {
+            await new Promise((r) => setTimeout(r, intervalMs));
+          }
+        }
+      };
+      loop();
+    },
+    stop() {
+      running = false;
+    },
+    mode: store.mode,
+    stats: () => store.stats(name),
+    dead: (limit = 50) => store.dead(name, limit),
+    async revive(id) {
+      await store.update(name, id, { status: "ready", attempts: 0, availableAtMs: clock.now() });
+    }
+  };
+}
+var VERSION = "0.1.0";
+function clusterStore(adapter) {
+  return {
+    mode: "cluster",
+    append: (queue, message) => adapter.insert(queue, message),
+    findByDedupe: (queue, dedupeKey, sinceMs) => adapter.findDuplicate(queue, dedupeKey, sinceMs),
+    claimKey: (queue, owner, ttlMs, nowMs) => adapter.takeKey({ queue, owner, untilMs: nowMs + ttlMs, nowMs }),
+    renewKey: (queue, lease, ttlMs, nowMs) => adapter.extendKey(queue, lease.key, lease.fence, nowMs + ttlMs),
+    releaseKey: (queue, lease) => adapter.dropKey(queue, lease.key, lease.fence),
+    readKey: (queue, key, nowMs, limit) => adapter.readReady(queue, key, nowMs, limit),
+    update: (queue, id, patch) => adapter.patch(queue, id, patch),
+    stats: (queue) => adapter.counts(queue),
+    dead: (queue, limit) => adapter.deadLetter(queue, limit)
+  };
+}
+export {
+  systemClock,
+  memoryStore,
+  durationMs,
+  createQueue,
+  clusterStore,
+  VERSION,
+  MODES
+};

package/dist/schema-typebox.d.ts

@@ -0,0 +1,24 @@
+import type { TSchema, Static } from '@sinclair/typebox';
+import { type SchemaValidator } from './schema';
+/**
+ * TypeBox implementation of `SchemaValidator`.
+ *
+ * TypeBox is a peer dependency and optional: the interface is what
+ * `@forgezero/access` depends on, so a project using Zod pulls no TypeBox at
+ * all. Import this module only if you want it.
+ *
+ * TypeBox schemas ARE JSON Schema, so `toJsonSchema` is the identity and the
+ * shared restriction and form logic applies without translation. That is why it
+ * ships first — anything needing a conversion step gets to prove the interface
+ * survives one.
+ */
+export declare const typebox: SchemaValidator<TSchema>;
+/**
+ * Parse-or-throw, for call sites where a failure is a bug rather than user
+ * input. Route request validation uses `validate` and answers 422; this is for
+ * config read at boot, where continuing with a bad value is worse than
+ * refusing to start.
+ */
+export declare function parse<T extends TSchema>(schema: T, value: unknown): Static<T>;
+export { Type as T } from '@sinclair/typebox';
+export type { TSchema, Static } from '@sinclair/typebox';

package/dist/schema-typebox.js

@@ -0,0 +1,201 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined")
+    return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/schema.ts
+class SchemaError extends Error {
+  code;
+  path;
+  constructor(code, message, path) {
+    super(message);
+    this.code = code;
+    this.path = path;
+    this.name = "SchemaError";
+  }
+}
+var DEFAULT_RESTRICTIONS = {
+  maxDepth: 4,
+  maxFields: 100,
+  maxBytes: 64 * 1024,
+  forbidden: ["$ref", "$id", "$dynamicRef", "$dynamicAnchor", "$schema", "definitions", "$defs"]
+};
+function restrictJsonSchema(schema, limits = DEFAULT_RESTRICTIONS) {
+  const bytes = JSON.stringify(schema).length;
+  if (bytes > limits.maxBytes) {
+    throw new SchemaError("SCHEMA_TOO_LARGE", `Schema is ${bytes} bytes; the limit is ${limits.maxBytes}.`);
+  }
+  let fields = 0;
+  const walk = (node, depth, path) => {
+    if (node === null || typeof node !== "object")
+      return;
+    if (Array.isArray(node)) {
+      node.forEach((child, index) => walk(child, depth, `${path}[${index}]`));
+      return;
+    }
+    const record = node;
+    for (const keyword of limits.forbidden) {
+      if (keyword in record) {
+        throw new SchemaError("SCHEMA_FORBIDDEN_KEYWORD", `"${keyword}" is not permitted: it can point validation at a document we do not control.`, path || "(root)");
+      }
+    }
+    if (depth > limits.maxDepth) {
+      throw new SchemaError("SCHEMA_TOO_DEEP", `Nesting exceeds ${limits.maxDepth} levels.`, path || "(root)");
+    }
+    if (record.type === "object") {
+      const properties = record.properties ?? {};
+      const names = Object.keys(properties);
+      fields += names.length;
+      if (fields > limits.maxFields) {
+        throw new SchemaError("SCHEMA_TOO_WIDE", `Schema declares more than ${limits.maxFields} fields.`, path || "(root)");
+      }
+      if (record.additionalProperties !== false) {
+        throw new SchemaError("SCHEMA_OPEN_OBJECT", "Objects must set additionalProperties:false, or unvalidated fields pass through.", path || "(root)");
+      }
+      for (const name of names) {
+        walk(properties[name], depth + 1, path ? `${path}.${name}` : name);
+      }
+    }
+    if (record.type === "array" && record.items) {
+      walk(record.items, depth + 1, `${path}[]`);
+    }
+  };
+  walk(schema, 1, "");
+  return schema;
+}
+function deriveAnnotation(property) {
+  const raw = property["x-fz-derive"];
+  if (typeof raw !== "object" || raw === null)
+    return;
+  const spec = raw;
+  const scheme = typeof spec.scheme === "string" ? spec.scheme : undefined;
+  if (!scheme)
+    return;
+  return {
+    custody: spec.custody === "supplied" ? "supplied" : "derived",
+    scheme,
+    expose: typeof spec.expose === "string" ? spec.expose : undefined
+  };
+}
+function describeJsonSchema(schema, prefix = "") {
+  if (schema.type !== "object")
+    return [];
+  const properties = schema.properties ?? {};
+  const required = new Set(schema.required ?? []);
+  return Object.entries(properties).map(([name, property]) => {
+    const path = prefix ? `${prefix}.${name}` : name;
+    const kind = fieldKind(property);
+    const field = {
+      path,
+      label: property.title ?? humanise(name),
+      kind,
+      required: required.has(name),
+      description: property.description,
+      writeOnly: property.writeOnly === true ? true : undefined,
+      default: property.default,
+      format: property.format,
+      minLength: property.minLength,
+      maxLength: property.maxLength,
+      minimum: property.minimum,
+      maximum: property.maximum,
+      pattern: property.pattern,
+      derive: deriveAnnotation(property)
+    };
+    if (kind === "enum") {
+      return { ...field, options: property.enum ?? property.anyOf };
+    }
+    if (kind === "object") {
+      return { ...field, items: describeJsonSchema(property, path) };
+    }
+    if (kind === "array" && property.items) {
+      return {
+        ...field,
+        items: describeJsonSchema(property.items, path)
+      };
+    }
+    return field;
+  });
+}
+function fieldKind(property) {
+  if (Array.isArray(property.enum))
+    return "enum";
+  if (Array.isArray(property.anyOf) && property.anyOf.every((m) => typeof m === "object" && m !== null && ("const" in m))) {
+    return "enum";
+  }
+  switch (property.type) {
+    case "string":
+      return "string";
+    case "number":
+      return "number";
+    case "integer":
+      return "integer";
+    case "boolean":
+      return "boolean";
+    case "array":
+      return "array";
+    case "object":
+      return "object";
+    default:
+      return "unknown";
+  }
+}
+function humanise(name) {
+  const spaced = name.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[_-]+/g, " ").trim().toLowerCase();
+  return spaced.charAt(0).toUpperCase() + spaced.slice(1);
+}
+function readableFields(fields) {
+  return fields.filter((field) => !field.writeOnly).map((field) => field.items ? { ...field, items: readableFields(field.items) } : field);
+}
+function writeOnlyPaths(fields) {
+  return fields.flatMap((field) => [
+    ...field.writeOnly ? [field.path] : [],
+    ...field.items ? writeOnlyPaths(field.items) : []
+  ]);
+}
+var SCHEMA_VERSION = 1;
+var VERSION = "0.1.0";
+
+// src/schema-typebox.ts
+import { Value } from "@sinclair/typebox/value";
+import { Type } from "@sinclair/typebox";
+var typebox = {
+  name: "typebox",
+  validate(schema, value) {
+    const converted = Value.Convert(schema, value);
+    if (Value.Check(schema, converted)) {
+      return { ok: true, value: Value.Clean(schema, converted) };
+    }
+    return {
+      ok: false,
+      errors: [...Value.Errors(schema, converted)].map((error) => ({
+        path: error.path || "(root)",
+        message: error.message
+      }))
+    };
+  },
+  describeForm(schema) {
+    return describeJsonSchema(schema);
+  },
+  toJsonSchema(schema) {
+    return structuredClone(schema);
+  },
+  restrict(schema, limits) {
+    restrictJsonSchema(schema, limits);
+    return schema;
+  }
+};
+function parse(schema, value) {
+  const result = typebox.validate(schema, value);
+  if (result.ok)
+    return result.value;
+  const first = result.errors[0];
+  throw new SchemaError("SCHEMA_INVALID", first?.message ?? "Value does not match schema", first?.path);
+}
+export {
+  typebox,
+  parse,
+  Type as T
+};

package/dist/schema.d.ts

@@ -0,0 +1,134 @@
+/**
+ * @forgezero/runtime/schema — one validation interface, pluggable implementations.
+ *
+ * The core of `@forgezero/access` accepts JSON Schema and depends on nothing.
+ * This package is what turns a real type system into something it can use, and
+ * what turns a schema into an admin form without per-field UI code.
+ *
+ * Three jobs, and the third is a security boundary rather than a convenience:
+ *
+ *   validate      does this value match
+ *   describeForm  what fields does an admin see, and which are write-only
+ *   restrict      refuse schemas that are unsafe to accept from a tenant
+ *
+ * TypeBox ships as `@forgezero/runtime/schema/typebox`. Zod and Valibot are new files,
+ * never edits here — that is the whole reason the interface exists.
+ */
+export declare class SchemaError extends Error {
+    readonly code: string;
+    readonly path?: string | undefined;
+    constructor(code: string, message: string, path?: string | undefined);
+}
+/**
+ * Limits on any schema accepted from outside our own source.
+ *
+ * These are the security boundary, not style:
+ *
+ *   `$ref`/`$id`  would let a tenant point the validator at a remote document
+ *   depth         unbounded nesting is a denial-of-service on validation
+ *   field count   the same, by width instead of depth
+ *   byte size     a schema is stored and re-parsed on every read
+ *   additionalProperties:false
+ *                 is what stops an unvalidated field riding into an envelope
+ *
+ * A schema authored in our own code is trusted and skips this. A schema a
+ * tenant submits never does.
+ */
+export interface Restrictions {
+    maxDepth: number;
+    maxFields: number;
+    maxBytes: number;
+    /** Keywords refused outright, wherever they appear. */
+    forbidden: readonly string[];
+}
+export declare const DEFAULT_RESTRICTIONS: Restrictions;
+export type FieldKind = 'string' | 'number' | 'integer' | 'boolean' | 'enum' | 'array' | 'object' | 'unknown';
+/**
+ * One rendered field. Deliberately flat and framework-agnostic: the admin UI
+ * maps this to inputs, and nothing here knows what a component is.
+ */
+export interface FormField {
+    /** Dotted path, so nested objects address unambiguously. */
+    path: string;
+    label: string;
+    kind: FieldKind;
+    required: boolean;
+    description?: string;
+    /**
+     * Never rendered with a value and never serialised back to a browser. This
+     * is what routes a credential into the vault instead of onto a page.
+     */
+    writeOnly?: boolean;
+    default?: unknown;
+    /** `enum` only. */
+    options?: readonly string[];
+    format?: string;
+    minLength?: number;
+    maxLength?: number;
+    minimum?: number;
+    maximum?: number;
+    pattern?: string;
+    /** `array` and `object` only — the shape of each child. */
+    items?: readonly FormField[];
+    /**
+     * ForgeZero generates this value; the tenant never types it and never holds
+     * it. Carried through from the schema's `x-fz-derive` annotation.
+     *
+     * A form MUST render this differently from an ordinary field, and the
+     * difference is not cosmetic. `derived` means the key material is generated
+     * from the master seed and exists in plaintext only inside a signing call —
+     * so there is no input to draw, and drawing an empty one invites somebody to
+     * paste a key that will be silently ignored. `supplied` means the tenant
+     * generates it and the vault only seals it, which IS an input, and a
+     * write-only one.
+     *
+     * Without this the two are indistinguishable in a form, and the failure is
+     * quiet in the worst direction: a user believes they have configured a
+     * signing key when the platform is using a different one entirely.
+     */
+    derive?: {
+        custody: 'derived' | 'supplied';
+        scheme: string;
+        expose?: string;
+    };
+}
+export type ValidationResult<T = unknown> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    errors: readonly {
+        path: string;
+        message: string;
+    }[];
+};
+/**
+ * What a validator must provide. Four functions.
+ *
+ * `toJsonSchema` is what stops the ecosystem fragmenting: stored config, the
+ * admin UI and the wire all speak JSON Schema, so a Zod tenant and a TypeBox
+ * tenant produce identical documents and either can read the other's.
+ */
+export interface SchemaValidator<S = unknown> {
+    readonly name: string;
+    validate<T = unknown>(schema: S, value: unknown): ValidationResult<T>;
+    describeForm(schema: S): readonly FormField[];
+    toJsonSchema(schema: S): Record<string, unknown>;
+    /** Throws `SchemaError` on violation. Returns the schema when acceptable. */
+    restrict(schema: S, limits?: Restrictions): S;
+}
+/**
+ * Restriction checking against JSON Schema, shared by every validator.
+ *
+ * Implemented once here rather than per-validator: this is the security
+ * boundary, and three implementations of it would be three chances to differ.
+ * A validator converts to JSON Schema and calls this.
+ */
+export declare function restrictJsonSchema(schema: Record<string, unknown>, limits?: Restrictions): Record<string, unknown>;
+export declare function describeJsonSchema(schema: Record<string, unknown>, prefix?: string): readonly FormField[];
+/** Fields safe to return to a browser — everything not marked `writeOnly`. */
+export declare function readableFields(fields: readonly FormField[]): readonly FormField[];
+/** Paths that must never leave the server. Used to strip before serialising. */
+export declare function writeOnlyPaths(fields: readonly FormField[]): readonly string[];
+export declare const SCHEMA_VERSION: 1;
+export declare const VERSION = "0.1.0";