@ultimat3/core 1.0.0

package/src/context.ts

@@ -0,0 +1,210 @@
+// Single responsibility: the ambient request context. Authz, tracing, locale, tz and the
+// service bag reach every layer through AsyncLocalStorage instead of being threaded as
+// parameters — otherwise every signature in the framework grows a `ctx` argument twice.
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { type Actor, anonymousActor } from './actor';
+import { type Clock, systemClock } from './clock';
+import { UltimateError } from './errors';
+import { traceId as newTraceId, uuid } from './ids';
+import { type Logger, logger as rootLogger, setLoggerContextFields } from './logger';
+import { type Role, resolveRole } from './roles';
+import { installedServices, isManagedService } from './service';
+
+/**
+ * Augment to attach typed services (`ctx.posts`, `ctx.jobs`, `ctx.mail`):
+ *
+ * ```ts
+ * declare module '@ultimat3/core' {
+ *   interface CtxServices { readonly posts: PostRepo }
+ * }
+ * ```
+ */
+export interface CtxServices {
+  readonly [service: string]: unknown;
+}
+
+export interface ServiceBag {
+  readonly [service: string]: unknown;
+}
+
+export interface Ctx extends CtxServices {
+  readonly requestId: string;
+  /** W3C trace id — the same value crosses HTTP -> job -> live query. */
+  readonly traceId: string;
+  readonly actor: Actor;
+  /** BCP-47 tag. */
+  readonly locale: string;
+  /** IANA time zone. Never format a date without it. */
+  readonly tz: string;
+  readonly buildId: string;
+  readonly role: Role;
+  readonly clock: Clock;
+  now(): Date;
+  readonly logger: Logger;
+  readonly signal: AbortSignal;
+  /** Late-bound services, for anything not worth a type augmentation. */
+  readonly services: ServiceBag;
+}
+
+export interface CtxInit {
+  readonly requestId?: string | undefined;
+  readonly traceId?: string | undefined;
+  readonly actor?: Actor | undefined;
+  readonly locale?: string | undefined;
+  readonly tz?: string | undefined;
+  readonly buildId?: string | undefined;
+  readonly role?: Role | undefined;
+  readonly clock?: Clock | undefined;
+  readonly logger?: Logger | undefined;
+  readonly signal?: AbortSignal | undefined;
+  readonly services?: ServiceBag | undefined;
+}
+
+export type CtxPatch = Omit<CtxInit, 'requestId'>;
+
+const storage = new AsyncLocalStorage<Ctx>();
+
+const neverAborted = new AbortController().signal;
+
+export const DEFAULT_LOCALE = 'en';
+export const DEFAULT_TIME_ZONE = 'UTC';
+
+function buildId(): string {
+  return process.env['BUILD_ID'] ?? 'dev';
+}
+
+export function createContext(init: CtxInit = {}): Ctx {
+  const clock = init.clock ?? systemClock;
+  const requestId = init.requestId ?? uuid(clock);
+  const trace = init.traceId ?? newTraceId();
+  const base = init.logger ?? rootLogger;
+  const explicit: ServiceBag = Object.freeze({ ...(init.services ?? {}) });
+  const fields = {
+    requestId,
+    traceId: trace,
+    actor: init.actor ?? anonymousActor(),
+    locale: init.locale ?? DEFAULT_LOCALE,
+    tz: init.tz ?? DEFAULT_TIME_ZONE,
+    buildId: init.buildId ?? buildId(),
+    role: init.role ?? resolveRole(),
+    clock,
+    now: () => clock.now(),
+    logger: base.child({ requestId, traceId: trace }),
+    signal: init.signal ?? neverAborted,
+  };
+  // A registered service (`defineService`) closes over the ctx it is built for — actor, clock,
+  // tz — so it has to run HERE, against this exact call's fields, rather than once at boot and
+  // be cached: a cached instance would answer every impersonated actor with the first one's
+  // tenant. `preview` carries everything a factory may read except a sibling service, which is
+  // what stops factories from depending on one another's instances. Explicit `init.services`
+  // wins over an auto-installed one of the same name — a test's hand-built mock overrides the
+  // real thing on purpose.
+  const preview = Object.freeze({ ...explicit, ...fields, services: explicit }) as Ctx;
+  const services: ServiceBag = Object.freeze({ ...installedServices(preview), ...explicit });
+  const ctx = {
+    // Services ride ON the context, not only under `ctx.services`: `CtxServices` exists to be
+    // augmented, so `ctx.posts` has to BE the service. Spread first, so a service that collides
+    // with a framework field (`actor`, `logger`) loses — it stays reachable as
+    // `ctx.services.actor`, and the context's own meaning never depends on what an app named a
+    // service. The assertion is the one thing this package cannot prove: an augmentation
+    // declares which services exist, only the boot code knows whether it passed them, or
+    // registered a factory for them. So a service nothing installed reads as `undefined`
+    // through `ctx.posts` — this is a frozen plain object, and it stays one on purpose: a
+    // get-trap proxy that threw on absent keys would also throw on `await ctx` (the runtime
+    // probes `.then`), on `JSON.stringify`, and on every optional-property check.
+    // `useService(name)` is the path that names the failure instead of leaving a bare
+    // `TypeError` at the first call: it throws `X_SERVICE_MISSING`, with the installed names
+    // and the fix.
+    ...services,
+    ...fields,
+    services,
+  } as Ctx;
+  return Object.freeze(ctx);
+}
+
+export function runWithContext<T>(ctx: Ctx, fn: () => T): T {
+  return storage.run(ctx, fn);
+}
+
+/** The context, or `undefined` outside a request. Prefer `useContext()` in app code. */
+export function tryUseContext(): Ctx | undefined {
+  return storage.getStore();
+}
+
+export function useContext(): Ctx {
+  const ctx = storage.getStore();
+  if (ctx === undefined) {
+    throw new UltimateError({
+      code: 'X_NO_CONTEXT',
+      cause: 'useContext() was called outside of runWithContext()',
+      fix: 'wrap the entry point in runWithContext(createContext({ ... }), fn)',
+    });
+  }
+  return ctx;
+}
+
+export function hasContext(): boolean {
+  return storage.getStore() !== undefined;
+}
+
+/**
+ * Derive a narrowed context — impersonation, a locale switch, a per-step abort signal.
+ * `requestId` is deliberately not patchable: one request, one id.
+ */
+export function withChildContext<T>(patch: CtxPatch, fn: () => T): T {
+  const parent = useContext();
+  // A factory-managed service was built for the PARENT's actor; forwarding it verbatim into an
+  // impersonated child would answer every call with the parent's tenant. `createContext` below
+  // rebuilds every registered factory fresh against the child's own actor, so only services no
+  // factory owns — a hand-built mock nothing registered — carry forward unrebuilt.
+  const carried = Object.fromEntries(
+    Object.entries(parent.services).filter(([name]) => !isManagedService(name)),
+  );
+  const child = createContext({
+    requestId: parent.requestId,
+    traceId: patch.traceId ?? parent.traceId,
+    actor: patch.actor ?? parent.actor,
+    locale: patch.locale ?? parent.locale,
+    tz: patch.tz ?? parent.tz,
+    buildId: parent.buildId,
+    role: patch.role ?? parent.role,
+    clock: patch.clock ?? parent.clock,
+    logger: patch.logger ?? parent.logger,
+    signal: patch.signal ?? parent.signal,
+    services: { ...carried, ...(patch.services ?? {}) },
+  });
+  return storage.run(child, fn);
+}
+
+/** Resolve a late-bound service. Throws `X_SERVICE_MISSING` rather than returning undefined. */
+export function useService<T>(name: string): T {
+  const ctx = useContext();
+  const service = ctx.services[name];
+  if (service === undefined) {
+    throw new UltimateError({
+      code: 'X_SERVICE_MISSING',
+      cause: `"${name}" is not on ctx.services (have: ${Object.keys(ctx.services).join(', ')})`,
+      fix: `pass it in createContext({ services: { ${name} } })`,
+      meta: { name },
+    });
+  }
+  return service as T;
+}
+
+/** Throws `X_ABORTED` if the caller has gone away — call before expensive work. */
+export function throwIfAborted(ctx: Ctx = useContext()): void {
+  if (!ctx.signal.aborted) return;
+  throw new UltimateError({
+    code: 'X_ABORTED',
+    cause: `request ${ctx.requestId} was aborted by the caller`,
+    fix: 'no action needed — stop work and return',
+    meta: { requestId: ctx.requestId },
+  });
+}
+
+// Every log line inside a request gets the ids for free.
+setLoggerContextFields(() => {
+  const ctx = storage.getStore();
+  return ctx === undefined ? undefined : { requestId: ctx.requestId, traceId: ctx.traceId };
+});

package/src/cursor.ts

@@ -0,0 +1,116 @@
+// Single responsibility: the one keyset-cursor codec. A page position is signed here and
+// verified here, so the repo, the read primitive and the admin cannot drift into three formats
+// with three trust levels.
+//
+// Signed, not encrypted: the client already holds the rows the cursor points at. What the
+// signature buys is that a client cannot *invent* a position, and what `scope` buys is that a
+// cursor from one read cannot be replayed against another — either is `X_CURSOR_INVALID`, never
+// a silently wrong page. It is tamper-evidence, not authorization: policy still runs per page.
+
+import { UltimateError } from './errors';
+
+export interface CursorPayload {
+  /** What this cursor belongs to: one read plus its arguments. A cursor is not portable. */
+  readonly scope: string;
+  /** The ordering tuple of the last row on the page, in `orderBy` order. */
+  readonly key: readonly unknown[];
+  /** Primary key of that row — the tiebreak that makes the sort order total. */
+  readonly id: string;
+}
+
+export class CursorInvalidError extends UltimateError {
+  override readonly name = 'CursorInvalidError';
+
+  constructor(reason: string) {
+    super({
+      code: 'X_CURSOR_INVALID',
+      cause: `cursor rejected: ${reason}`,
+      fix: 'drop the cursor and request the first page again (after: null)',
+      meta: { reason },
+    });
+  }
+}
+
+/**
+ * Dev default so `x dev` pages without configuration. Production sets `ULTIMATE_CURSOR_SECRET`
+ * — a fixed literal rather than a per-process random one on purpose: a random secret would make
+ * a cursor issued by one instance fail on the next, and that failure only shows up under scale.
+ */
+const DEV_SECRET = 'ultimate-dev-cursor-secret';
+
+let secret = Bun.env['ULTIMATE_CURSOR_SECRET'] ?? DEV_SECRET;
+
+/** Set once at boot from the app secret. Rotating it invalidates every open cursor. */
+export function configureCursorSigning(next: string): void {
+  secret = next;
+}
+
+/** True while cursors are signed with the shipped dev key — `x doctor` reports it. */
+export function usesDevCursorSecret(): boolean {
+  return secret === DEV_SECRET;
+}
+
+/** `base64url(payload).signature`. Opaque by contract: callers must never parse it. */
+export function encodeCursor(payload: CursorPayload): string {
+  const body = encodeBody(JSON.stringify([payload.scope, payload.id, payload.key]));
+  return `${body}.${sign(body)}`;
+}
+
+/**
+ * The only way back. `scope` is required rather than optional because an optional check is one
+ * a call site can forget, and a forgotten check is a cursor from another query paging this one.
+ */
+export function decodeCursor(cursor: string, scope: string): CursorPayload {
+  const dot = cursor.lastIndexOf('.');
+  if (dot <= 0) throw new CursorInvalidError('not a signed cursor');
+  const body = cursor.slice(0, dot);
+  if (!sameSignature(sign(body), cursor.slice(dot + 1))) {
+    throw new CursorInvalidError('signature does not match — tampered with, or the secret rotated');
+  }
+
+  const parsed = parseBody(body);
+  if (!Array.isArray(parsed) || parsed.length !== 3) throw new CursorInvalidError('not a cursor');
+  const [encodedScope, id, key] = parsed as readonly unknown[];
+  if (typeof encodedScope !== 'string' || typeof id !== 'string' || !Array.isArray(key)) {
+    throw new CursorInvalidError('not a cursor');
+  }
+  if (encodedScope !== scope) {
+    throw new CursorInvalidError('it belongs to a different query, filter or sort order');
+  }
+  return { scope: encodedScope, key, id };
+}
+
+/** Truncated HMAC-SHA256. 128 bits is far past forging a page position. */
+function sign(body: string): string {
+  return new Bun.CryptoHasher('sha256', secret).update(body).digest('hex').slice(0, 32);
+}
+
+/** Constant time: the comparison must not leak how much of a forged signature was right. */
+function sameSignature(expected: string, actual: string): boolean {
+  if (expected.length !== actual.length) return false;
+  let difference = 0;
+  for (let index = 0; index < expected.length; index += 1) {
+    difference |= expected.charCodeAt(index) ^ actual.charCodeAt(index);
+  }
+  return difference === 0;
+}
+
+// A cursor travels in a query string and carries row values, so the encoding has to survive
+// both: base64url (no `+`, `/` or `=` for a caller to re-encode) over UTF-8 bytes — `btoa`
+// alone throws above code point 0xFF, and one accented title would break pagination.
+function encodeBody(text: string): string {
+  const bytes = new TextEncoder().encode(text);
+  let binary = '';
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replaceAll('=', '');
+}
+
+function parseBody(body: string): unknown {
+  const padded = body.replaceAll('-', '+').replaceAll('_', '/');
+  try {
+    const binary = atob(padded.padEnd(padded.length + ((4 - (padded.length % 4)) % 4), '='));
+    return JSON.parse(new TextDecoder().decode(Uint8Array.from(binary, (c) => c.charCodeAt(0))));
+  } catch {
+    throw new CursorInvalidError('payload is not readable');
+  }
+}

package/src/env.ts

@@ -0,0 +1,259 @@
+// Single responsibility: typed environment validation at boot. Every missing or malformed key
+// is reported in ONE error — an agent should never have to restart the process six times to
+// discover six missing variables.
+
+import { EnvMissingError } from './errors';
+import { redactKeys } from './logger';
+import { type Role, resolveRole } from './roles';
+
+export type EnvVarType = 'string' | 'url' | 'number' | 'integer' | 'port' | 'boolean' | 'enum';
+
+interface EnvVarCommon {
+  /**
+   * Omit for a required variable (the default). `required: false` is the only accepted
+   * loosening — there is one way to say "optional".
+   */
+  readonly required?: false | undefined;
+  /** Redacted in logs and masked in `x env check --json`. */
+  readonly secret?: boolean | undefined;
+  /** Only required when the process runs as one of these roles. */
+  readonly role?: Role | readonly Role[] | undefined;
+  readonly description?: string | undefined;
+  /** Overrides the generic fix line for this key. */
+  readonly fix?: string | undefined;
+}
+
+export interface EnvStringVar extends EnvVarCommon {
+  readonly type: 'string' | 'url';
+  readonly default?: string | undefined;
+  readonly pattern?: RegExp | undefined;
+}
+
+export interface EnvNumberVar extends EnvVarCommon {
+  readonly type: 'number' | 'integer' | 'port';
+  readonly default?: number | undefined;
+  readonly min?: number | undefined;
+  readonly max?: number | undefined;
+}
+
+export interface EnvBooleanVar extends EnvVarCommon {
+  readonly type: 'boolean';
+  readonly default?: boolean | undefined;
+}
+
+export interface EnvEnumVar<V extends string = string> extends EnvVarCommon {
+  readonly type: 'enum';
+  readonly values: readonly V[];
+  readonly default?: V | undefined;
+}
+
+export type EnvVarDecl = EnvStringVar | EnvNumberVar | EnvBooleanVar | EnvEnumVar;
+
+export type EnvSchema = Readonly<Record<string, EnvVarDecl>>;
+
+type EnvVarValue<D> = D extends { readonly type: 'enum'; readonly values: readonly (infer V)[] }
+  ? V
+  : D extends { readonly type: 'number' | 'integer' | 'port' }
+    ? number
+    : D extends { readonly type: 'boolean' }
+      ? boolean
+      : string;
+
+type EnvVarOptional<D> = D extends { readonly default: unknown }
+  ? false
+  : D extends { readonly role: unknown }
+    ? true
+    : D extends { readonly required: false }
+      ? true
+      : false;
+
+export type Env<S extends EnvSchema> = {
+  readonly [K in keyof S]: EnvVarOptional<S[K]> extends true
+    ? EnvVarValue<S[K]> | undefined
+    : EnvVarValue<S[K]>;
+};
+
+export interface EnvIssue {
+  readonly key: string;
+  readonly reason: 'missing' | 'invalid';
+  readonly expected: string;
+  /** Masked when the declaration is `secret: true`. */
+  readonly received: string | undefined;
+  readonly fix: string;
+}
+
+export interface EnvCheckReport {
+  readonly ok: boolean;
+  readonly issues: readonly EnvIssue[];
+  readonly values: Readonly<Record<string, unknown>>;
+}
+
+export interface EnvOptions {
+  readonly env?: Readonly<Record<string, string | undefined>> | undefined;
+  readonly role?: Role | undefined;
+  /** Register `secret: true` keys with the logger's redaction list. Default `true`. */
+  readonly redact?: boolean | undefined;
+}
+
+const TRUE_VALUES = new Set(['1', 'true', 'yes', 'on']);
+const FALSE_VALUES = new Set(['0', 'false', 'no', 'off']);
+
+function requiredForRole(decl: EnvVarDecl, role: Role): boolean {
+  if (decl.required === false) return false;
+  if (decl.role === undefined) return true;
+  return typeof decl.role === 'string' ? decl.role === role : decl.role.includes(role);
+}
+
+function expectation(decl: EnvVarDecl): string {
+  switch (decl.type) {
+    case 'enum':
+      return `one of ${decl.values.join(' | ')}`;
+    case 'port':
+      return 'an integer port 1-65535';
+    case 'integer':
+      return 'an integer';
+    case 'number':
+      return 'a number';
+    case 'boolean':
+      return `one of ${[...TRUE_VALUES, ...FALSE_VALUES].join(' | ')}`;
+    case 'url':
+      return 'an absolute URL';
+    default:
+      return 'a non-empty string';
+  }
+}
+
+function parseValue(decl: EnvVarDecl, raw: string): { ok: true; value: unknown } | { ok: false } {
+  switch (decl.type) {
+    case 'boolean': {
+      const lowered = raw.toLowerCase();
+      if (TRUE_VALUES.has(lowered)) return { ok: true, value: true };
+      if (FALSE_VALUES.has(lowered)) return { ok: true, value: false };
+      return { ok: false };
+    }
+    case 'number':
+    case 'integer':
+    case 'port': {
+      const value = Number(raw);
+      if (!Number.isFinite(value)) return { ok: false };
+      if (decl.type !== 'number' && !Number.isInteger(value)) return { ok: false };
+      if (decl.type === 'port' && (value < 1 || value > 65535)) return { ok: false };
+      if (decl.min !== undefined && value < decl.min) return { ok: false };
+      if (decl.max !== undefined && value > decl.max) return { ok: false };
+      return { ok: true, value };
+    }
+    case 'enum':
+      return (decl.values as readonly string[]).includes(raw)
+        ? { ok: true, value: raw }
+        : { ok: false };
+    case 'url':
+      return URL.canParse(raw) ? { ok: true, value: raw } : { ok: false };
+    default:
+      if (decl.pattern !== undefined && !decl.pattern.test(raw)) return { ok: false };
+      return { ok: true, value: raw };
+  }
+}
+
+/** Validate without throwing — this is what `x env check --json` prints. */
+export function checkEnv(schema: EnvSchema, options?: EnvOptions): EnvCheckReport {
+  const source = options?.env ?? (process.env as Record<string, string | undefined>);
+  const role = options?.role ?? resolveRole({ env: source });
+  const issues: EnvIssue[] = [];
+  const values: Record<string, unknown> = {};
+
+  for (const [key, decl] of Object.entries(schema)) {
+    const raw = source[key];
+    if (raw === undefined || raw === '') {
+      if (decl.default !== undefined) {
+        values[key] = decl.default;
+        continue;
+      }
+      if (requiredForRole(decl, role)) {
+        issues.push({
+          key,
+          reason: 'missing',
+          expected: expectation(decl),
+          received: undefined,
+          fix: decl.fix ?? `add ${key}= to .env`,
+        });
+      } else {
+        values[key] = undefined;
+      }
+      continue;
+    }
+    const parsed = parseValue(decl, raw);
+    if (parsed.ok) {
+      values[key] = parsed.value;
+      continue;
+    }
+    issues.push({
+      key,
+      reason: 'invalid',
+      expected: expectation(decl),
+      received: decl.secret === true ? '***' : raw,
+      fix: decl.fix ?? `set ${key} to ${expectation(decl)} in .env`,
+    });
+  }
+
+  return { ok: issues.length === 0, issues, values };
+}
+
+/**
+ * Validate the process environment against `schema` and return a frozen typed object.
+ * Throws `X_ENV_MISSING` listing EVERY offending key at once.
+ */
+export function defineEnv<const S extends EnvSchema>(schema: S, options?: EnvOptions): Env<S> {
+  const report = checkEnv(schema, options);
+
+  if (options?.redact !== false) {
+    const secrets = Object.entries(schema)
+      .filter(([, decl]) => decl.secret === true)
+      .map(([key]) => key);
+    if (secrets.length > 0) redactKeys(secrets);
+  }
+
+  if (!report.ok) {
+    const cause = report.issues
+      .map((issue) =>
+        issue.reason === 'missing'
+          ? `${issue.key} is missing (expected ${issue.expected})`
+          : `${issue.key}="${issue.received ?? ''}" is not ${issue.expected}`,
+      )
+      .join('; ');
+    const keys = report.issues.map((issue) => issue.key).join(' ');
+    throw new EnvMissingError({
+      cause,
+      fix: `add ${keys} to .env (copy .env.example), then run: x env check`,
+      meta: { issues: report.issues },
+    });
+  }
+
+  return Object.freeze(report.values) as Env<S>;
+}
+
+export interface EnvVarSummary {
+  readonly key: string;
+  readonly type: EnvVarType;
+  readonly required: boolean;
+  readonly secret: boolean;
+  readonly hasDefault: boolean;
+  readonly roles: readonly Role[] | 'all';
+  readonly description: string | undefined;
+}
+
+function rolesOf(role: Role | readonly Role[]): readonly Role[] {
+  return typeof role === 'string' ? [role] : role;
+}
+
+/** Declarations only, never values — safe to print, safe to commit to `x.manifest.json`. */
+export function describeEnv(schema: EnvSchema): readonly EnvVarSummary[] {
+  return Object.entries(schema).map(([key, decl]) => ({
+    key,
+    type: decl.type,
+    required: decl.required !== false,
+    secret: decl.secret === true,
+    hasDefault: decl.default !== undefined,
+    roles: decl.role === undefined ? 'all' : rolesOf(decl.role),
+    description: decl.description,
+  }));
+}