@obbyx/obyte 0.0.0-stage → 0.1.1

package/src/channel/definition.ts

@@ -0,0 +1,114 @@
+import obyte from 'obyte';
+import { type Verdict, accept, isPlainObject, reject } from '../core/result.js';
+
+/**
+ * AA payment channels (aa-channels-lib, base AA v1.1).
+ *
+ * Party A is the payee (seller, x402 `payTo`), party B the payer (client).
+ * A channel address is derived from its parameters, so binding a payment to a
+ * seller is a matter of recomputing the address (ADR-0003): parameters are
+ * taken from the on-chain definition, never trusted from a package alone.
+ */
+export const CHANNEL_BASE_AA = '4IRUGAUUCAQ6QRQLG4SNOLOE6VW2STWZ';
+
+export interface ChannelParams {
+  readonly addressA: string;
+  readonly addressB: string;
+  /** `'base'` for bytes, otherwise a 44-char asset id. */
+  readonly asset: string;
+  readonly salt?: string;
+  /** Dispute window in seconds. */
+  readonly timeout: number;
+}
+
+export type ChannelDefinition = readonly [
+  'autonomous agent',
+  { readonly base_aa: string; readonly params: ChannelParams },
+];
+
+/** obyte.js `isValidAddress` as a type guard; it also rejects non-strings. */
+export function isAddress(value: unknown): value is string {
+  return typeof value === 'string' && obyte.utils.isValidAddress(value);
+}
+
+const ASSET_RE = /^[A-Za-z0-9+/]{43}=$/;
+
+export function isAssetId(value: unknown): value is string {
+  return value === 'base' || (typeof value === 'string' && ASSET_RE.test(value));
+}
+
+export function validateChannelParams(params: unknown): Verdict<ChannelParams> {
+  if (!isPlainObject(params)) return reject('invalid_channel_params', 'Params must be an object');
+  const { addressA, addressB, asset, salt, timeout } = params;
+  const extra = Object.keys(params).filter(
+    (k) => !['addressA', 'addressB', 'asset', 'salt', 'timeout'].includes(k),
+  );
+  if (extra.length > 0)
+    return reject('invalid_channel_params', `Unexpected params: ${extra.join(', ')}`);
+  if (!isAddress(addressA) || !isAddress(addressB)) {
+    return reject('invalid_channel_params', 'addressA and addressB must be valid addresses');
+  }
+  if (addressA === addressB) return reject('invalid_channel_params', 'Parties must differ');
+  if (!isAssetId(asset)) return reject('invalid_channel_params', 'Invalid asset');
+  if (salt !== undefined && (typeof salt !== 'string' || salt.length === 0 || salt.length > 100)) {
+    return reject('invalid_channel_params', 'Invalid salt');
+  }
+  if (!Number.isSafeInteger(timeout) || (timeout as number) <= 0) {
+    return reject('invalid_channel_params', 'timeout must be a positive integer (seconds)');
+  }
+  return accept({
+    addressA,
+    addressB,
+    asset,
+    ...(salt === undefined ? {} : { salt: salt as string }),
+    timeout: timeout as number,
+  });
+}
+
+export function channelDefinition(params: ChannelParams): ChannelDefinition {
+  // Key order matters for nothing (JSON source string sorts keys) but is kept
+  // identical to aa-channels-lib for readability.
+  const p: ChannelParams = {
+    addressA: params.addressA,
+    addressB: params.addressB,
+    asset: params.asset,
+    ...(params.salt === undefined ? {} : { salt: params.salt }),
+    timeout: params.timeout,
+  };
+  return ['autonomous agent', { base_aa: CHANNEL_BASE_AA, params: p }];
+}
+
+export function channelAddress(params: ChannelParams): string {
+  return obyte.utils.getChash160(channelDefinition(params) as unknown as unknown[]);
+}
+
+/**
+ * Parses an on-chain AA definition and returns its channel parameters if it
+ * is an instance of the supported base AA whose address matches `address`.
+ */
+export function parseChannelDefinition(
+  address: string,
+  definition: unknown,
+): Verdict<ChannelParams> {
+  if (
+    !Array.isArray(definition) ||
+    definition.length !== 2 ||
+    definition[0] !== 'autonomous agent' ||
+    !isPlainObject(definition[1])
+  ) {
+    return reject('invalid_channel_definition', 'Not a parameterized AA definition');
+  }
+  const body = definition[1];
+  if (body['base_aa'] !== CHANNEL_BASE_AA) {
+    return reject(
+      'invalid_channel_definition',
+      'AA is not an instance of the supported channel base AA',
+    );
+  }
+  const params = validateChannelParams(body['params']);
+  if (!params.ok) return params;
+  if (channelAddress(params.value) !== address) {
+    return reject('invalid_channel_definition', 'Definition does not match the channel address');
+  }
+  return params;
+}

package/src/config/index.ts

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import { ObbyxError } from '../core/errors.js';
+
+/**
+ * Configuration is validated with zod at startup; an invalid config stops the
+ * process with a list of *all* problems rather than failing later at runtime.
+ * The same schemas generate the configuration reference in the docs.
+ */
+export class ConfigError extends ObbyxError {
+  readonly issues: readonly string[];
+
+  constructor(issues: readonly string[]) {
+    super('invalid_config', `Invalid configuration:\n  - ${issues.join('\n  - ')}`, {
+      details: { issues },
+    });
+    this.issues = issues;
+  }
+}
+
+export function loadConfig<S extends z.ZodType>(schema: S, source: unknown): z.output<S> {
+  const result = schema.safeParse(source);
+  if (!result.success) {
+    throw new ConfigError(
+      result.error.issues.map((issue) => {
+        const path = issue.path.length > 0 ? issue.path.join('.') : '(root)';
+        return `${path}: ${issue.message}`;
+      }),
+    );
+  }
+  return result.data;
+}
+
+/** Reusable env-var helpers. */
+export const envBoolean = z
+  .enum(['1', '0', 'true', 'false', 'yes', 'no'])
+  .transform((v) => v === '1' || v === 'true' || v === 'yes');
+
+export const envPort = z.coerce.number().int().min(1).max(65535);
+
+export const logLevelSchema = z.enum(['fatal', 'error', 'warn', 'info', 'debug', 'trace']);

package/src/core/amounts.ts

@@ -0,0 +1,116 @@
+import { ObbyxError } from './errors.js';
+
+/**
+ * Amounts are always integers in the asset's smallest units (invariant I5).
+ *
+ * - On the wire (x402 JSON) they are decimal strings.
+ * - Inside obbyx they are `bigint`.
+ * - They are converted to `number` only at the boundary with libraries that
+ *   require it (ocore, obyte.js, AA formulas), via {@link toSafeNumber}.
+ * - Prices are never computed with floating point.
+ */
+export type Amount = bigint;
+
+/** Largest amount accepted anywhere: every amount must round-trip through JS `number`. */
+export const MAX_AMOUNT: Amount = BigInt(Number.MAX_SAFE_INTEGER);
+
+const AMOUNT_RE = /^(0|[1-9][0-9]*)$/;
+const DISPLAY_RE = /^(0|[1-9][0-9]*)(\.([0-9]+))?$/;
+const MAX_DECIMALS = 18;
+
+export class AmountError extends ObbyxError {
+  constructor(message: string, details?: Record<string, unknown>) {
+    super('invalid_amount', message, details === undefined ? {} : { details });
+  }
+}
+
+function assertInRange(value: Amount, input: unknown): Amount {
+  if (value < 0n || value > MAX_AMOUNT) {
+    throw new AmountError('Amount is out of range', { input: String(input) });
+  }
+  return value;
+}
+
+function assertDecimals(decimals: number): void {
+  if (!Number.isInteger(decimals) || decimals < 0 || decimals > MAX_DECIMALS) {
+    throw new AmountError('Invalid number of decimals', { decimals });
+  }
+}
+
+/** Parses an atomic amount from its canonical decimal-string form ("0", "1500"). */
+export function parseAmount(input: string): Amount {
+  if (typeof input !== 'string' || !AMOUNT_RE.test(input)) {
+    throw new AmountError('Amount must be a non-negative integer string without leading zeros', {
+      input: String(input),
+    });
+  }
+  return assertInRange(BigInt(input), input);
+}
+
+/** Accepts a safe non-negative integer `number` (e.g. from ocore) and returns a bigint. */
+export function fromSafeNumber(input: number): Amount {
+  if (!Number.isSafeInteger(input) || input < 0) {
+    throw new AmountError('Amount must be a non-negative safe integer', { input });
+  }
+  return BigInt(input);
+}
+
+/** Canonical wire form. */
+export function formatAmount(value: Amount): string {
+  return assertInRange(value, value).toString();
+}
+
+/** Converts for libraries that only accept `number`; throws instead of losing precision. */
+export function toSafeNumber(value: Amount): number {
+  return Number(assertInRange(value, value));
+}
+
+export function addAmounts(a: Amount, b: Amount): Amount {
+  return assertInRange(a + b, `${a}+${b}`);
+}
+
+/** Subtraction that never goes below zero silently. */
+export function subAmounts(a: Amount, b: Amount): Amount {
+  if (b > a) {
+    throw new AmountError('Amount subtraction would be negative', {
+      a: a.toString(),
+      b: b.toString(),
+    });
+  }
+  return a - b;
+}
+
+/**
+ * Converts a human-readable amount ("0.25") into atomic units.
+ * Rejects more fractional digits than the asset supports instead of rounding.
+ */
+export function fromDisplay(input: string, decimals: number): Amount {
+  assertDecimals(decimals);
+  const match = typeof input === 'string' ? DISPLAY_RE.exec(input) : null;
+  if (!match) {
+    throw new AmountError('Display amount must look like "12" or "12.34"', {
+      input: String(input),
+    });
+  }
+  const whole = match[1] ?? '0';
+  const fraction = match[3] ?? '';
+  if (fraction.length > decimals) {
+    throw new AmountError('Display amount has more fractional digits than the asset allows', {
+      input,
+      decimals,
+    });
+  }
+  const atomic = BigInt(whole + fraction.padEnd(decimals, '0'));
+  return assertInRange(atomic, input);
+}
+
+/** Converts atomic units into a human-readable string without floating point. */
+export function toDisplay(value: Amount, decimals: number): string {
+  assertDecimals(decimals);
+  const digits = formatAmount(value);
+  if (decimals === 0) return digits;
+  const padded = digits.padStart(decimals + 1, '0');
+  const whole = padded.slice(0, -decimals);
+  const fraction = padded.slice(-decimals).replace(/0+$/, '');
+  return fraction.length > 0 ? `${whole}.${fraction}` : whole;
+}

package/src/core/errors.ts

@@ -0,0 +1,22 @@
+/**
+ * Base error for all obbyx packages.
+ *
+ * `code` is a stable machine-readable identifier. Payment-related errors use
+ * x402 reason codes (e.g. `invalid_exact_obyte_payload_signature`) so they can
+ * be mapped 1:1 to `invalidReason` / `errorReason` in facilitator responses.
+ */
+export class ObbyxError extends Error {
+  readonly code: string;
+  readonly details: Readonly<Record<string, unknown>> | undefined;
+
+  constructor(
+    code: string,
+    message: string,
+    options: { cause?: unknown; details?: Record<string, unknown> } = {},
+  ) {
+    super(message, options.cause === undefined ? undefined : { cause: options.cause });
+    this.name = new.target.name;
+    this.code = code;
+    this.details = options.details;
+  }
+}

package/src/core/networks.ts

@@ -0,0 +1,81 @@
+import { ObbyxError } from './errors.js';
+
+/**
+ * Obyte networks and their identifiers.
+ *
+ * - x402 v2 uses CAIP-2 identifiers. No `obyte` namespace exists in
+ *   ChainAgnostic/namespaces yet, so `obyte:livenet` / `obyte:testnet` are
+ *   provisional until agreed upstream (see docs/adr/0004-network-identifiers.md).
+ * - x402 v1 uses plain strings, so each network also has a v1 name.
+ *
+ * Every storage, lock and dedup key must include the network (invariant I4);
+ * use {@link networkKey} to build such keys.
+ */
+export type ObyteNetworkName = 'livenet' | 'testnet';
+export type Caip2 = `${string}:${string}`;
+
+export interface ObyteNetwork {
+  readonly name: ObyteNetworkName;
+  readonly caip2: Caip2;
+  readonly v1Name: string;
+  readonly testnet: boolean;
+  readonly defaultHubUrl: string;
+  readonly explorerUrl: string;
+}
+
+export const OBYTE_CAIP_FAMILY = 'obyte:*' as const;
+
+export const OBYTE_NETWORKS: Readonly<Record<ObyteNetworkName, ObyteNetwork>> = Object.freeze({
+  livenet: Object.freeze({
+    name: 'livenet',
+    caip2: 'obyte:livenet',
+    v1Name: 'obyte-livenet',
+    testnet: false,
+    defaultHubUrl: 'wss://obyte.org/bb',
+    explorerUrl: 'https://explorer.obyte.org',
+  }),
+  testnet: Object.freeze({
+    name: 'testnet',
+    caip2: 'obyte:testnet',
+    v1Name: 'obyte-testnet',
+    testnet: true,
+    defaultHubUrl: 'wss://obyte.org/bb-test',
+    explorerUrl: 'https://testnetexplorer.obyte.org',
+  }),
+});
+
+const BY_ID: ReadonlyMap<string, ObyteNetwork> = new Map(
+  Object.values(OBYTE_NETWORKS).flatMap((n) => [
+    [n.caip2, n],
+    [n.v1Name, n],
+  ]),
+);
+
+export class UnsupportedNetworkError extends ObbyxError {
+  constructor(id: string) {
+    super('invalid_network', `Unsupported Obyte network: ${id}`, { details: { network: id } });
+  }
+}
+
+/** Resolves a v2 CAIP-2 id or a v1 network name; throws for anything else. */
+export function getNetwork(id: string): ObyteNetwork {
+  const network = BY_ID.get(id);
+  if (!network) throw new UnsupportedNetworkError(id);
+  return network;
+}
+
+export function isObyteNetwork(id: string): boolean {
+  return BY_ID.has(id);
+}
+
+/** Builds a key namespaced by network, e.g. `obyte:testnet:unit:<hash>`. */
+export function networkKey(network: ObyteNetwork, ...parts: readonly string[]): string {
+  if (parts.length === 0 || parts.some((p) => p.length === 0)) {
+    throw new ObbyxError('invalid_key', 'networkKey requires non-empty parts');
+  }
+  return [network.caip2, ...parts].join(':');
+}
+
+export function explorerUnitUrl(network: ObyteNetwork, unit: string): string {
+  return `${network.explorerUrl}/${encodeURIComponent(unit)}`;
+}

package/src/core/result.ts

@@ -0,0 +1,23 @@
+/**
+ * Outcome of a check. Rejections carry a stable `reason` code (x402 style) and a
+ * human-readable message; they are expected outcomes, not exceptions.
+ */
+export type Verdict<T> =
+  | { readonly ok: true; readonly value: T }
+  | { readonly ok: false; readonly reason: string; readonly message: string };
+
+export function accept<T>(value: T): Verdict<T> {
+  return { ok: true, value };
+}
+
+export function reject<T = never>(reason: string, message: string): Verdict<T> {
+  return { ok: false, reason, message };
+}
+
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+export function hasOnlyKeys(obj: Record<string, unknown>, allowed: ReadonlySet<string>): boolean {
+  return Object.keys(obj).every((k) => allowed.has(k));
+}

package/src/index.ts

@@ -0,0 +1,58 @@
+export { ObbyxError } from './core/errors.js';
+export { type Verdict, accept, reject } from './core/result.js';
+export {
+  type Amount,
+  AmountError,
+  MAX_AMOUNT,
+  addAmounts,
+  formatAmount,
+  fromDisplay,
+  fromSafeNumber,
+  parseAmount,
+  subAmounts,
+  toDisplay,
+  toSafeNumber,
+} from './core/amounts.js';
+export {
+  type Caip2,
+  type ObyteNetwork,
+  type ObyteNetworkName,
+  OBYTE_CAIP_FAMILY,
+  OBYTE_NETWORKS,
+  UnsupportedNetworkError,
+  explorerUnitUrl,
+  getNetwork,
+  isObyteNetwork,
+  networkKey,
+} from './core/networks.js';
+export {
+  SIGNED_PACKAGE_VERSIONS,
+  type SigDefinition,
+  type SignedPackage,
+  type VerifiedPackage,
+  isSigDefinition,
+  verifySignature,
+  verifySignedPackage,
+} from './signing/signed-message.js';
+export {
+  CHANNEL_BASE_AA,
+  type ChannelDefinition,
+  type ChannelParams,
+  channelAddress,
+  channelDefinition,
+  isAddress,
+  isAssetId,
+  parseChannelDefinition,
+  validateChannelParams,
+} from './channel/definition.js';
+export {
+  DEFAULT_MAX_UNIT_BYTES,
+  EXACT_REASONS,
+  EXACT_UNIT_VERSIONS,
+  type ExactExpectation,
+  type ExactUnitFacts,
+  type InputRef,
+  compareOutputs,
+  expectedCommissions,
+  validateExactUnit,
+} from './unit/exact-unit.js';

package/src/logger/index.ts

@@ -0,0 +1,234 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { createHash } from 'node:crypto';
+import { pino, type DestinationStream, type Level, type Logger, type LoggerOptions } from 'pino';
+
+/**
+ * Unified logger for all obbyx packages and apps (plan §7).
+ *
+ * - Structured JSON (pino), human-readable output in dev via pino-pretty.
+ * - Correlation fields (requestId, traceId, binding, proofId, ...) are taken
+ *   from an AsyncLocalStorage context, so every log line written while a
+ *   payment is processed carries them automatically — in the seller middleware,
+ *   the facilitator and the watcher alike.
+ * - Sensitive values (signatures, payment packages, signed units, API keys,
+ *   challenges, private keys) are never written; they are replaced by a short
+ *   SHA-256 fingerprint so they can still be correlated across logs.
+ * - Libraries never call `console`; they receive a Logger via DI and create
+ *   per-module children with {@link moduleLogger}.
+ */
+export type { Logger, Level } from 'pino';
+
+export const LOG_LEVELS: readonly Level[] = ['fatal', 'error', 'warn', 'info', 'debug', 'trace'];
+
+/** Correlation fields propagated through a payment flow. */
+export interface LogContext {
+  requestId?: string;
+  traceId?: string;
+  binding?: string;
+  proofId?: string;
+  network?: string;
+  scheme?: string;
+  x402Version?: number;
+  sellerId?: string;
+  aa?: string;
+  seq?: string;
+}
+
+const contextStorage = new AsyncLocalStorage<Readonly<LogContext>>();
+
+/**
+ * Runs `fn` with additional correlation fields. Nested calls merge with (and
+ * may override) the outer context.
+ */
+export function withLogContext<T>(fields: LogContext, fn: () => T): T {
+  const parent = contextStorage.getStore();
+  return contextStorage.run(Object.freeze({ ...parent, ...stripUndefined(fields) }), fn);
+}
+
+export function getLogContext(): Readonly<LogContext> {
+  return contextStorage.getStore() ?? {};
+}
+
+function stripUndefined(fields: LogContext): LogContext {
+  return Object.fromEntries(
+    Object.entries(fields).filter(([, v]) => v !== undefined),
+  ) as LogContext;
+}
+
+/**
+ * Short, stable fingerprint of a sensitive value: `sha256:<12 hex>`.
+ * Use it to log *that* a value was seen without revealing it.
+ */
+export function fingerprint(value: unknown): string {
+  const text = typeof value === 'string' ? value : stableStringify(value);
+  return `sha256:${createHash('sha256').update(text).digest('hex').slice(0, 12)}`;
+}
+
+function stableStringify(value: unknown): string {
+  if (value === undefined) return 'undefined';
+  return JSON.stringify(value, (_key, v: unknown) => {
+    if (typeof v === 'bigint') return v.toString();
+    if (v && typeof v === 'object' && !Array.isArray(v)) {
+      return Object.fromEntries(
+        Object.entries(v as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b)),
+      );
+    }
+    return v;
+  });
+}
+
+/**
+ * Field names whose values are bearer-sensitive or secret. They are redacted at
+ * the top level and up to three levels deep. Naming convention: code that logs
+ * such data must use one of these field names (enforced by tests and review).
+ */
+export const SENSITIVE_FIELDS: readonly string[] = [
+  'authentifiers',
+  'signedPackage',
+  'signed_package',
+  'sentByPeer',
+  'paymentPayload',
+  'paymentSignature',
+  'xPayment',
+  'joint',
+  'signedUnit',
+  'apiKey',
+  'authorization',
+  'cookie',
+  'challengeSignature',
+  'privateKey',
+  'mnemonic',
+  'seed',
+  'password',
+  'secret',
+];
+
+const SENSITIVE_HEADERS: readonly string[] = [
+  'payment-signature',
+  'x-payment',
+  'authorization',
+  'cookie',
+  'x-api-key',
+];
+
+function redactPaths(): string[] {
+  const paths: string[] = [];
+  for (const field of SENSITIVE_FIELDS) {
+    paths.push(field, `*.${field}`, `*.*.${field}`, `*.*.*.${field}`);
+  }
+  for (const header of SENSITIVE_HEADERS) {
+    paths.push(`headers["${header}"]`, `*.headers["${header}"]`);
+  }
+  return paths;
+}
+
+export interface CreateLoggerOptions {
+  /** Base level. Default: `info`. */
+  level?: Level;
+  /** Per-module overrides, e.g. `{ 'x402.exact': 'debug', hub: 'trace' }`. */
+  moduleLevels?: Readonly<Record<string, Level>>;
+  /** Service name written into every line (`service` field). */
+  service?: string;
+  /** Pretty-print for local development. */
+  pretty?: boolean;
+  /** Custom destination (tests, files). Ignored when `pretty` is set. */
+  destination?: DestinationStream;
+}
+
+const moduleLevelsByLogger = new WeakMap<Logger, Readonly<Record<string, Level>>>();
+
+export function createLogger(options: CreateLoggerOptions = {}): Logger {
+  const pinoOptions: LoggerOptions = {
+    level: options.level ?? 'info',
+    base: options.service === undefined ? {} : { service: options.service },
+    timestamp: pino.stdTimeFunctions.isoTime,
+    messageKey: 'msg',
+    formatters: { level: (label) => ({ level: label }) },
+    redact: { paths: redactPaths(), censor: (value) => redacted(value) },
+    serializers: { err: pino.stdSerializers.err },
+    mixin: () => ({ ...getLogContext() }),
+  };
+
+  const logger =
+    options.pretty === true
+      ? pino({ ...pinoOptions, transport: { target: 'pino-pretty', options: { colorize: true } } })
+      : options.destination === undefined
+        ? pino(pinoOptions)
+        : pino(pinoOptions, options.destination);
+
+  moduleLevelsByLogger.set(logger, options.moduleLevels ?? {});
+  return logger;
+}
+
+function redacted(value: unknown): string {
+  return value === undefined || value === null ? '[redacted]' : `[redacted ${fingerprint(value)}]`;
+}
+
+/**
+ * Child logger for a module (`x402.exact`, `hub`, `watcher.sync`, ...).
+ * Applies the most specific per-module level: `x402.exact.verify` inherits a
+ * level configured for `x402.exact` or `x402`.
+ */
+export function moduleLogger(
+  root: Logger,
+  module: string,
+  bindings: Record<string, unknown> = {},
+): Logger {
+  const levels = findModuleLevels(root);
+  const level = resolveModuleLevel(module, levels);
+  const child = root.child({ module, ...bindings }, level === undefined ? {} : { level });
+  moduleLevelsByLogger.set(child, levels);
+  return child;
+}
+
+function findModuleLevels(logger: Logger): Readonly<Record<string, Level>> {
+  return moduleLevelsByLogger.get(logger) ?? {};
+}
+
+export function resolveModuleLevel(
+  module: string,
+  levels: Readonly<Record<string, Level>>,
+): Level | undefined {
+  const parts = module.split('.');
+  for (let i = parts.length; i > 0; i--) {
+    const level = levels[parts.slice(0, i).join('.')];
+    if (level !== undefined) return level;
+  }
+  return undefined;
+}
+
+/**
+ * Parses `LOG_LEVELS="x402.exact=debug,hub=trace"`. Invalid entries throw so
+ * misconfiguration is visible at startup instead of silently ignored.
+ */
+export function parseModuleLevels(spec: string | undefined): Record<string, Level> {
+  const result: Record<string, Level> = {};
+  if (spec === undefined || spec.trim() === '') return result;
+  for (const entry of spec.split(',')) {
+    const [module, level] = entry.split('=').map((s) => s.trim());
+    if (!module || !level || !isLevel(level)) {
+      throw new Error(`Invalid LOG_LEVELS entry "${entry}" (expected module=level)`);
+    }
+    result[module] = level;
+  }
+  return result;
+}
+
+export function isLevel(value: string): value is Level {
+  return (LOG_LEVELS as readonly string[]).includes(value);
+}
+
+/** Builds a logger from standard env vars: LOG_LEVEL, LOG_LEVELS, LOG_PRETTY. */
+export function createLoggerFromEnv(
+  service: string,
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): Logger {
+  const level = env['LOG_LEVEL'] ?? 'info';
+  if (!isLevel(level)) throw new Error(`Invalid LOG_LEVEL "${level}"`);
+  return createLogger({
+    service,
+    level,
+    moduleLevels: parseModuleLevels(env['LOG_LEVELS']),
+    pretty: env['LOG_PRETTY'] === '1' || env['LOG_PRETTY'] === 'true',
+  });
+}