@empyria/common 0.1.0

package/.oxfmtrc.json

@@ -0,0 +1,9 @@
+{
+	"$schema": "./node_modules/oxfmt/configuration_schema.json",
+	"ignorePatterns": [],
+	"useTabs": true,
+	"tabWidth": 4,
+	"singleQuote": true,
+	"trailingComma": "all",
+	"semi": false
+}

package/AGENTS.md

@@ -0,0 +1,36 @@
+# AGENTS.md
+
+Shared backend services for higher-level components in **Principia**, a nanoservice
+framework built primarily on Bun: environment variable schemas, error definitions,
+Codogram (SMS/TOTP-style challenge codes), and Ata (JSON schema + validation).
+
+## Runtime
+
+- Requires Bun `>=1.4.0` or Node.js `>=26`, inherited from
+  [@empyria/classification](https://github.com/imrefazekas/empyria-classification)'s use of
+  native `Temporal`. See that repo's `AGENTS.md` — it's a **git dependency**, so this package
+  only sees its pushed commits, not local working-tree changes.
+- Plain ESM, no TypeScript, no build step.
+- Relative imports **must** include explicit `.js` extensions (`from './Errors.js'`, not
+  `'./Errors'`) — Bun tolerates missing ones, Node's ESM resolver doesn't.
+
+## Validation: one library only
+
+Schema validation runs on **`ata-validator`** exclusively (see [lib/Ata.js](./lib/Ata.js),
+[lib/Defaulter.js](./lib/Defaulter.js)). `ajv` was deliberately removed — don't reintroduce it
+or any second validator.
+
+## Layout
+
+- [index.js](./index.js) is the package entry point; it re-exports everything under `lib/`.
+  When adding a new `lib/*.js` module, remember to add its `export * from './lib/X.js'` line
+  here too — `Codogram.js` was missing from the barrel for a while and no one noticed.
+- `lib/Errors.js` defines `BaseErrors`, the catalog of pre-built error factories other modules
+  throw from (e.g. `throw new BaseErrors.EntityInvalid({...})`). Prefer adding to this catalog
+  over throwing ad hoc errors.
+- Tests live in `test/`, flat, one file per `lib/` module, using `bun:test`. Run via `bun run test`.
+
+## Style
+
+- Formatting is enforced by oxfmt ([.oxfmtrc.json](./.oxfmtrc.json)): tabs, single quotes, no
+  semicolons, trailing commas. Run `bun run format:fix` before committing.

package/README.md

@@ -0,0 +1,71 @@
+# @empyria/common
+
+Shared backend services for higher-level components in **Principia**, a nanoservice
+framework built primarily on Bun: environment variable schemas, error definitions,
+Codogram (SMS/TOTP-style challenge codes), and Ata (JSON schema building blocks and
+validation).
+
+## Requirements
+
+- Bun `>=1.4.0` or Node.js `>=26`
+- Plain ESM, no build step, no TypeScript
+
+Both requirements come from [@empyria/classification](https://github.com/imrefazekas/empyria-classification),
+which this package depends on and which uses the native `Temporal` global for all
+date/time handling.
+
+## Install
+
+```bash
+bun add @empyria/common
+```
+
+## Usage
+
+```js
+import { createEnv, BaseErrors, generateCodogram, validate, string } from '@empyria/common'
+
+const envSchema = createEnv({ API_KEY: string() })
+
+throw new BaseErrors.EntityInvalid({ type: 'User', id: 42 })
+
+const pin = generateCodogram('PIN')
+```
+
+Everything is re-exported from the package root via [index.js](./index.js). Individual
+modules under `lib/` can also be imported directly if you only need one:
+
+```js
+import { defineSchema } from '@empyria/common/lib/Ata.js'
+```
+
+## Modules
+
+| Module                                 | Purpose                                                                                                                                                                                                                                             |
+| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [index.js](./index.js)                 | Package entry point; re-exports every module below plus Moleculer meta helpers (`moleculerMeta`, `moleculerPrincipiaMeta`) and workflow ID helpers (`workflowName`, `workflowId`, `identifyWorkflow`).                                              |
+| [lib/Errors.js](./lib/Errors.js)       | `PrincipiaError`, the `ErrorCreator` factory, and `BaseErrors` — Principia's catalog of pre-built, templated errors.                                                                                                                                |
+| [lib/Env.js](./lib/Env.js)             | `createEnv` — builds a service's environment-variable JSON schema from Principia-wide defaults.                                                                                                                                                     |
+| [lib/Ata.js](./lib/Ata.js)             | JSON schema building blocks (`string`, `number`, `bool`, `enumType`, `email`, `password`, `ip4`, `ip6`, ...) and validation (`defineSchema`, `createValidator`, `validate`), built on [ata-validator](https://www.npmjs.com/package/ata-validator). |
+| [lib/Codogram.js](./lib/Codogram.js)   | `generateCodogram` — one-time challenge codes (PIN, alphanumeric, alphabetic) for SMS/TOTP-style verification flows.                                                                                                                                |
+| [lib/Defaulter.js](./lib/Defaulter.js) | `defaultsFromSchema` — builds a fully-populated default object for a JSON schema.                                                                                                                                                                   |
+
+Every exported function is documented with JSDoc directly in its source file — hovering
+a function in VSCode or Zed shows its parameters and return type without any extra
+tooling, since both editors read JSDoc from plain `.js` files automatically.
+
+Tests live under [test/](./test/), one file per module, separate from the `lib/` sources.
+
+## Scripts
+
+```bash
+bun run format       # check formatting (oxfmt)
+bun run format:fix   # apply formatting
+bun run lint         # lint (oxlint)
+bun run lint:fix     # lint and fix
+bun run test         # run tests with coverage
+```
+
+## License
+
+MIT © Imre Fazekas

package/index.js

@@ -0,0 +1,102 @@
+import { randomUUID as uuid } from 'node:crypto'
+
+import { TRANS } from '@empyria/classification'
+
+import { PrincipiaError, ErrorCreator, BaseErrors } from './lib/Errors.js'
+import { createEnv } from './lib/Env.js'
+
+export * from './lib/Ata.js'
+
+export * from './lib/Codogram.js'
+
+export * from './lib/Defaulter.js'
+
+export { PrincipiaError, ErrorCreator, BaseErrors, createEnv }
+
+/** Role tag Moleculer assigns to every Principia microservice. */
+export const MOLECULER_SERVICE_ROLE = 'microservice'
+
+/** The federation's own actor/federation ID, used for system-originated calls. */
+export const PRINCIPIA_FEDERATION_ID =
+	process.env.PRINCIPIA_FEDERATION_ID ?? '563ac2a1-3fe3-4c5f-b20f-6f33e5cbd680'
+
+/**
+ * Builds a Moleculer call-context `meta` object carrying Principia's actor/tracing fields.
+ * @param {Object} params
+ * @param {string} params.actor - ID of the user/service making the call.
+ * @param {string} params.federation - Federation the call belongs to.
+ * @param {string} params.flowID - ID correlating this call with the rest of its business flow.
+ * @param {string} params.processID - ID correlating this call with the rest of its process/workflow run.
+ * @param {string} params.role - Caller's role (see {@link MOLECULER_SERVICE_ROLE}).
+ * @param {string} params.tokenKey - Auth token key for the call.
+ * @returns {{user: {actor: string, federation: string, flowID: string, processID: string, role: string}, tokenKey: string}}
+ */
+export function moleculerMeta({ actor, federation, flowID, processID, role, tokenKey }) {
+	return {
+		user: {
+			actor,
+			federation,
+			flowID,
+			processID,
+			role,
+		},
+		tokenKey,
+	}
+}
+
+/**
+ * Builds a {@link moleculerMeta} object for a system-originated (Principia-as-actor) call,
+ * generating a `flowID`/`processID` when not supplied.
+ * @param {Object} params
+ * @param {string} [params.flowID] - Flow correlation ID; a new UUID is generated if omitted.
+ * @param {string} [params.processID] - Process correlation ID; a new UUID is generated if omitted.
+ * @param {string} params.tokenKey - Auth token key for the call.
+ * @returns {ReturnType<typeof moleculerMeta>}
+ */
+export function moleculerPrincipiaMeta({ flowID, processID, tokenKey }) {
+	return moleculerMeta({
+		actor: PRINCIPIA_FEDERATION_ID,
+		federation: PRINCIPIA_FEDERATION_ID,
+		flowID: flowID ?? uuid(),
+		processID: processID ?? uuid(),
+		role: MOLECULER_SERVICE_ROLE,
+		tokenKey,
+	})
+}
+
+/**
+ * Builds the stable `service:handler` name for a workflow, transliterated/upper-cased via `TRANS`.
+ * @param {Object} workflow
+ * @param {string} workflow.service - Owning service name.
+ * @param {string} workflow.handler - Handler name within that service.
+ * @returns {string} The workflow's normalized name.
+ */
+export const workflowName = (workflow) => {
+	return TRANS(`${workflow?.service}:${workflow?.handler}`)
+}
+
+/**
+ * Builds a unique workflow instance ID: {@link workflowName} plus a fresh UUID.
+ * @param {Object} workflow - See {@link workflowName}.
+ * @returns {string} `"SERVICE:HANDLER:<uuid>"`.
+ */
+export function workflowId(workflow) {
+	return `${workflowName(workflow)}:${uuid()}`
+}
+
+/**
+ * Parses a workflow ID (as produced by {@link workflowId}) back into its service/handler.
+ * @param {string} workflowId - A `"SERVICE:HANDLER:<uuid>"`-shaped ID.
+ * @returns {{service: string, handler: string}}
+ * @throws {PrincipiaError} If `workflowId` doesn't have at least three `:`-separated components.
+ */
+export const identifyWorkflow = (workflowId) => {
+	const components = workflowId?.split(':')
+	if (!components || components.length < 3) {
+		throw new PrincipiaError('Invalid workflow ID format')
+	}
+	return {
+		service: components[0],
+		handler: components[1],
+	}
+}

package/lib/Ata.js

@@ -0,0 +1,248 @@
+import { Validator, renderPretty, renderCompact, renderJSON } from 'ata-validator'
+
+import { cloneSelected, defined } from '@empyria/classification'
+import { BaseErrors } from './Errors.js'
+
+/** Regex pattern (string form) matching a single email address. */
+export const P_EMAIL =
+	"[a-z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$" // '[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,4}$'
+
+/** Regex pattern (string form) requiring lower-case, upper-case, digit, and 8+ length. */
+export const P_PASS = '(?=.*[a-z])(?=.*[A-Z])(?=.*[0-9])(?=.{8,})'
+
+/** Regex pattern (string form) matching an IPv4 address. */
+export const P_IPv4 =
+	'(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]\\d|\\d)(?:\\.(?:25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]\\d|\\d)){3}$'
+
+const v6segment = '[a-fA-F\\d]{1,4}'
+/** Regex pattern (string form) matching an IPv6 address (including IPv4-mapped forms). */
+export const P_IPv6 = `
+(?:
+(?:${v6segment}:){7}(?:${v6segment}|:)|
+(?:${v6segment}:){6}(?:${P_IPv4}|:${v6segment}|:)|
+(?:${v6segment}:){5}(?::${P_IPv4}|(?::${v6segment}){1,2}|:)|
+(?:${v6segment}:){4}(?:(?::${v6segment}){0,1}:${P_IPv4}|(?::${v6segment}){1,3}|:)|
+(?:${v6segment}:){3}(?:(?::${v6segment}){0,2}:${P_IPv4}|(?::${v6segment}){1,4}|:)|
+(?:${v6segment}:){2}(?:(?::${v6segment}){0,3}:${P_IPv4}|(?::${v6segment}){1,5}|:)|
+(?:${v6segment}:){1}(?:(?::${v6segment}){0,4}:${P_IPv4}|(?::${v6segment}){1,6}|:)|
+(?::(?:(?::${v6segment}){0,5}:${P_IPv4}|(?::${v6segment}){1,7}|:))
+)(?:%[0-9a-zA-Z]{1,})?$`
+	.replace(/\s*\/\/.*$/gm, '')
+	.replace(/\n/g, '')
+	.trim()
+
+/**
+ * Builds a function that clones only the keys declared on a schema's `properties`.
+ * @param {Object} schema - JSON schema with a `properties` map.
+ * @returns {(obj: Object) => Object} Function that shallow-clones an object down to those keys.
+ */
+export function cloneBySchema(schema) {
+	const keys = Object.keys(schema.properties)
+	return (obj) => cloneSelected(obj, keys)
+}
+
+/**
+ * Builds a JSON schema object from a flat map of property schemas.
+ * @param {Object} schemaDef - Map of property name to its JSON schema.
+ * @param {Object} [options={}]
+ * @param {boolean} [options.strict] - If true, disallows properties not listed in `schemaDef`.
+ * @returns {Object} A JSON schema: `{ type: 'object', properties, required: <all keys>, additionalProperties }`.
+ */
+export function defineSchema(schemaDef, options = {}) {
+	const schema = {
+		type: 'object',
+		properties: schemaDef,
+		required: Object.keys(schemaDef),
+		additionalProperties: !options.strict,
+	}
+
+	return schema
+}
+
+/**
+ * Builds a validating function for a JSON schema.
+ * @param {Object} schema - JSON schema to validate against.
+ * @param {Object} [options] - Forwarded to `ata-validator`'s `Validator` constructor
+ *   (`coerceTypes`, `removeAdditional`, `useDefaults`, ...). Left unset, validation is
+ *   strict: a schema expecting `type: 'number'` rejects `"32"`. Pass `{ coerceTypes: true }`
+ *   for input that's inherently string-typed, such as `process.env` (see `createEnv`).
+ * @returns {(data: *) => *} Function that returns `data` unchanged if valid.
+ * @throws {PrincipiaError} `BaseErrors.ValidationError` (with a pretty-rendered violation list
+ *   in its `validation` param) if `data` doesn't satisfy the schema.
+ */
+export function createValidator(schema, options) {
+	const v = new Validator(schema, options)
+
+	return (data) => {
+		const result = v.validate(data)
+		if (!result.valid) {
+			throw new BaseErrors.ValidationError({
+				name: schema.title || schema.name || '',
+				value: '',
+				validation: renderPretty(result.errors),
+			})
+		}
+		return data
+	}
+}
+
+/**
+ * Validates `input` against `schema` in one call.
+ * @param {Object} schema - JSON schema to validate against.
+ * @param {*} input - Value to validate.
+ * @param {Object} [options] - Forwarded to {@link createValidator} (see its docs).
+ * @returns {*} `input` unchanged, if valid.
+ * @throws {PrincipiaError} `BaseErrors.ValidationError` if `input` doesn't satisfy the schema.
+ */
+export function validate(schema, input, options) {
+	const validateInput = createValidator(schema, options)
+	const validatedInput = validateInput(input)
+
+	return validatedInput
+}
+
+/**
+ * Re-exported from `ata-validator`:
+ * - `renderCompact(errors)` renders a validation error list compactly (one line each).
+ * - `renderJSON(errors)` renders a validation error list as JSON.
+ */
+export { renderCompact, renderJSON }
+
+/**
+ * JSON schema for a boolean property.
+ * @param {boolean} [defaultValue] - Default value, if any.
+ * @returns {Object} `{ type: 'boolean', default? }`.
+ */
+export function bool(defaultValue) {
+	const schema = {
+		type: 'boolean',
+	}
+	if (defined(defaultValue)) schema.default = Boolean(defaultValue)
+	return schema
+}
+
+/**
+ * JSON schema for a string property.
+ * @param {string} [defaultValue] - Default value, if any.
+ * @param {number} [minLength] - Minimum string length, if greater than 0.
+ * @returns {Object} `{ type: 'string', default?, minLength? }`.
+ */
+export function string(defaultValue, minLength) {
+	const schema = {
+		type: 'string',
+	}
+	if (defined(defaultValue)) schema.default = `${defaultValue}`
+	if (minLength > 0) schema.minLength = minLength
+	return schema
+}
+
+/**
+ * JSON schema for an enumerated property.
+ * @param {Array} list - Allowed values.
+ * @param {*} [defaultValue] - Default value, if any.
+ * @returns {Object} `{ enum: list, default? }`.
+ */
+export function enumType(list, defaultValue) {
+	const schema = {
+		enum: list,
+	}
+	if (defined(defaultValue)) schema.default = defaultValue
+	return schema
+}
+
+/**
+ * JSON schema for a log-level environment variable, defaulting to `'info'`.
+ * @returns {Object} Enum schema over the standard Pino/Moleculer log levels.
+ */
+export function logLevel() {
+	return enumType(['fatal', 'error', 'warn', 'info', 'debug', 'trace', 'silent'], 'info')
+}
+
+/**
+ * JSON schema for a temp-folder path, defaulting to `'./tmp'`.
+ * @returns {Object} String schema.
+ */
+export function tmpFile() {
+	return string('./tmp')
+}
+
+/**
+ * JSON schema for a log-file path, defaulting to `'./tmp/moleculer.log'`.
+ * @returns {Object} String schema.
+ */
+export function logFile() {
+	return string('./tmp/moleculer.log')
+}
+
+/**
+ * JSON schema for a `NODE_ENV`-style environment variable, defaulting to `'local'`.
+ * Includes `'test'` because `bun test` (and most JS test runners) set `NODE_ENV=test`
+ * automatically — omitting it means any app validating `process.env` at import time
+ * (see `createEnv`) can never run its own test suite.
+ * @returns {Object} Enum schema over `'production' | 'development' | 'local' | 'test'`.
+ */
+export function nodeEnv() {
+	return enumType(['production', 'development', 'local', 'test'], 'local')
+}
+
+/**
+ * JSON schema for a numeric property.
+ * @param {number} [defaultValue] - Default value, if any.
+ * @returns {Object} `{ type: 'number', default? }`.
+ */
+export function number(defaultValue) {
+	const schema = {
+		type: 'number',
+	}
+	if (defined(defaultValue)) schema.default = Number(defaultValue)
+	return schema
+}
+
+/**
+ * JSON schema for an email-address string, pattern-matched against {@link P_EMAIL}.
+ * @returns {Object} String schema with `pattern` and `description` set.
+ */
+export function email() {
+	return {
+		type: 'string',
+		pattern: P_EMAIL,
+		description: 'Email address',
+	}
+}
+
+/**
+ * JSON schema for a password string, pattern-matched against {@link P_PASS}
+ * (requires lower-case, upper-case, a digit, and at least 8 characters).
+ * @returns {Object} String schema with `pattern` and `description` set.
+ */
+export function password() {
+	return {
+		type: 'string',
+		pattern: P_PASS,
+		description: 'password',
+	}
+}
+
+/**
+ * JSON schema for an IPv4-address string, pattern-matched against {@link P_IPv4}.
+ * @returns {Object} String schema with `pattern` and `description` set.
+ */
+export function ip4() {
+	return {
+		type: 'string',
+		pattern: P_IPv4,
+		description: 'IP address v4',
+	}
+}
+
+/**
+ * JSON schema for an IPv6-address string, pattern-matched against {@link P_IPv6}.
+ * @returns {Object} String schema with `pattern` and `description` set.
+ */
+export function ip6() {
+	return {
+		type: 'string',
+		pattern: P_IPv6,
+		description: 'IP address v6',
+	}
+}

package/lib/Codogram.js

@@ -0,0 +1,46 @@
+import { enumise } from '@empyria/classification'
+
+import Clerobee from 'clerobee'
+import { BaseErrors } from './Errors.js'
+
+const clerobee = new Clerobee(process.env.PRINCIPIA_ID_LENGTH || 32)
+
+const CPIN = 'PIN'
+const CODE = 'Code'
+const CABC = 'ABC'
+const CABN = 'ABC Num'
+/** The set of codogram type identifiers accepted by {@link generateCodogram}. */
+const CODOGRAM_LIST = [CPIN, CODE, CABC, CABN]
+/** {@link CODOGRAM_LIST}, normalized into a `{NAME: value}` enum via `enumise`. */
+const CODOGRAMS = enumise(CODOGRAM_LIST)
+
+const CPIN_LENGTH = 6
+const CODE_LENGTH = 16
+const CABC_LENGTH = 6
+const CABN_LENGTH = 6
+
+/**
+ * Generates a one-time codogram (challenge code) for SMS/TOTP-style verification flows.
+ * @param {string} type - One of {@link CODOGRAM_LIST}: `'PIN'` (numeric), `'Code'` (alphanumeric),
+ *   `'ABC'` (alphabetic), or `'ABC Num'` (alphanumeric via Clerobee).
+ * @param {Object} [options={}]
+ * @param {number} [options.length] - Overrides the type's default length.
+ * @returns {number|string} A numeric PIN for `'PIN'`, otherwise an upper-cased string.
+ * @throws {PrincipiaError} `BaseErrors.UnrecognisedType` if `type` isn't one of {@link CODOGRAM_LIST}.
+ */
+export function generateCodogram(type, options = {}) {
+	switch (type) {
+		case CPIN:
+			return Math.floor(Math.random() * Math.pow(10, options.length || CPIN_LENGTH))
+		case CODE:
+			return clerobee.generate(options.length || CODE_LENGTH).toUpperCase()
+		case CABC:
+			return clerobee.generateAbcString(options.length || CABC_LENGTH).toUpperCase()
+		case CABN:
+			return clerobee.generateAbcNumString(options.length || CABN_LENGTH).toUpperCase()
+		default:
+			throw new BaseErrors.UnrecognisedType({ type })
+	}
+}
+
+export { CODOGRAM_LIST, CODOGRAMS }

package/lib/Defaulter.js

@@ -0,0 +1,45 @@
+import { Validator } from 'ata-validator'
+
+/**
+ * Recursively builds an object populated with each property's schema `default`
+ * (or a type-appropriate empty value for required properties without one).
+ * @param {Object} schema - A JSON schema (object type, with `properties`).
+ * @returns {Object} The built object; `{}` if `schema` isn't an object schema.
+ */
+function buildEmpty(schema) {
+	if (schema.type === 'object' && schema.properties) {
+		const obj = {}
+		for (const [key, prop] of Object.entries(schema.properties)) {
+			if (prop.type === 'object') {
+				obj[key] = prop.default ?? buildEmpty(prop)
+			} else if (!schema.required?.includes(key)) {
+				continue
+			}
+
+			if (prop.type === 'array') {
+				obj[key] = prop.default ?? []
+			} else if (prop.type === 'string') {
+				obj[key] = prop.default ?? ''
+			} else if (prop.type === 'boolean') {
+				obj[key] = prop.default ?? false
+			} else if (prop.type === 'number' || prop.type === 'integer') {
+				obj[key] = prop.default ?? 0
+			}
+		}
+		return obj
+	}
+	return {}
+}
+
+/**
+ * Builds a fully-populated default object for a JSON schema: every property gets its
+ * schema `default`, falling back to a type-appropriate empty value, then runs the
+ * result through an ata-validator `Validator` to fill in anything `buildEmpty` missed.
+ * @param {Object} schema - A JSON schema (object type, with `properties`).
+ * @returns {Object} The schema's default object.
+ */
+export function defaultsFromSchema(schema) {
+	const obj = buildEmpty(schema)
+	new Validator(schema).validate(obj)
+	return obj
+}

package/lib/Env.js

@@ -0,0 +1,34 @@
+import { defineSchema, bool, number, tmpFile, string, logLevel, logFile, nodeEnv } from './Ata.js'
+
+/** Environment schema shared by every Principia microservice. */
+const DEFAULT_SERVICE_SCHEMA = {
+	PRINCIPIA_ID_LENGTH: number(32),
+
+	TMP_FOLDER: tmpFile(),
+
+	LOG_LEVEL: logLevel(),
+	LOG_FILE: logFile(),
+
+	NODE_ENV: nodeEnv(),
+
+	RESET: bool(false),
+
+	MOLECULER_TRANSPORTER: string('TCP'),
+
+	MOLECULER_CACHE_ENABLED: bool(false),
+	MOLECULER_CACHE_PREFIX: string('Principia'),
+	MOLECULER_CACHE_URL: string('redis://redis:6379/15'),
+
+	RESTATE_ADMIN_URL: string('http://restate:9070'),
+	RESTATE_URL: string('http://restate:9071'),
+}
+
+/**
+ * Builds a JSON schema for a microservice's environment variables, merging the
+ * Principia-wide defaults with any service-specific additions/overrides.
+ * @param {Object} [specificSchema] - Additional or overriding property schemas, keyed by env var name.
+ * @returns {Object} A JSON schema object (see `defineSchema` in `./Ata.js`).
+ */
+export function createEnv(specificSchema) {
+	return defineSchema(Object.assign({}, DEFAULT_SERVICE_SCHEMA, specificSchema))
+}

package/lib/Errors.js

@@ -0,0 +1,166 @@
+import { inherits } from 'util'
+
+import { templating } from '@empyria/classification'
+
+/**
+ * Principia's base error type. Carries a machine-readable `errorName`/`errorCode`
+ * alongside the usual `message`, and captures its own stack trace.
+ * @constructor
+ * @param {string} message - Human-readable error message.
+ * @param {string} [errorName] - Machine-readable error identifier.
+ * @param {number} [errorCode] - Numeric error code.
+ */
+let PrincipiaError = function (message, errorName, errorCode) {
+	this.message = message
+	this.errorName = errorName
+	this.errorCode = errorCode
+	Error.captureStackTrace(this, PrincipiaError)
+}
+inherits(PrincipiaError, Error)
+
+/**
+ * Builds a reusable error factory from a template.
+ * @param {Object} [options={}]
+ * @param {number} [options.errorCode] - Numeric error code, used as the fallback `errorName`.
+ * @param {string} [options.errorName] - Machine-readable error identifier.
+ * @param {string} [options.message] - Message template with `{param}` placeholders (see
+ *   `templating` in `@empyria/classification`).
+ * @returns {(opts?: Object) => PrincipiaError} Function that, given template values, returns a
+ *   new {@link PrincipiaError} with its `message` filled in and `params` set to the values used.
+ */
+let ErrorCreator = function (options = {}) {
+	let errorCode = options.errorCode
+	let args = Object.assign({}, options)
+	delete args['message']
+	delete args['code']
+	delete args['errorCode']
+	let fnc = function (opts = {}) {
+		let newArgs = Object.assign({}, args, opts)
+		let message = templating(options.message, newArgs)
+		let resultError = new PrincipiaError(message, options.errorName || errorCode, errorCode)
+		resultError.params = newArgs
+		return resultError
+	}
+	return fnc
+}
+
+/**
+ * Principia's catalog of pre-built error factories, one per well-known failure case.
+ * Each entry is a function built via {@link ErrorCreator} — call it with the template's
+ * parameters (e.g. `BaseErrors.EntityInvalid({ type: 'User', id: 42 })`) to get a
+ * {@link PrincipiaError} instance ready to `throw`.
+ */
+let BaseErrors = {
+	InvalidModel: ErrorCreator({
+		errorCode: 599993,
+		errorName: 'InvalidModel',
+		message: 'Model {name} is not a valid definition',
+	}),
+	Exceeded: ErrorCreator({
+		errorCode: 599994,
+		errorName: 'Exceeded',
+		message: 'Limit of {limit} is exceeded',
+	}),
+	NotConnected: ErrorCreator({
+		errorCode: 599995,
+		errorName: 'NotConnected',
+		message: '{service} is not connected',
+	}),
+	ConnectorMandatory: ErrorCreator({
+		errorCode: 599996,
+		errorName: 'ConnectorMandatory',
+		message: 'Presence of a Connector instance is mandatory',
+	}),
+	NotInited: ErrorCreator({
+		errorCode: 599997,
+		errorName: 'NotInited',
+		message: 'Principia is not inited',
+	}),
+	UnImplemented: ErrorCreator({
+		errorCode: 599998,
+		errorName: 'UnImplemented',
+		message: 'Service {service} is not implemented',
+	}),
+	ValidationError: ErrorCreator({
+		errorCode: 599999,
+		errorName: 'ValidationError',
+		message: '{name} ({value}) failed on input parameter schema validation: {validation}',
+	}),
+	DataNotRecognised: ErrorCreator({
+		errorCode: 600000,
+		errorName: 'DataNotRecognised',
+		message: 'Data type:{type} uid:{uid} is not recognised',
+	}),
+	UnrecognisedType: ErrorCreator({
+		errorCode: 600001,
+		errorName: 'UnrecognisedType',
+		message: 'Entity type {type} is not recognised',
+	}),
+	MissingData: ErrorCreator({
+		errorCode: 600002,
+		errorName: 'MissingData',
+		message: "Data '{type}' is missing",
+	}),
+	InformationInvalid: ErrorCreator({
+		errorCode: 600003,
+		errorName: 'InformationInvalid',
+		message: 'Data {type} is not valid',
+	}),
+	EntityInvalid: ErrorCreator({
+		errorCode: 600004,
+		errorName: 'EntityInvalid',
+		message: '{type}:{id} is not valid',
+	}),
+	DataNotOwned: ErrorCreator({
+		errorCode: 600005,
+		errorName: 'DataNotOwned',
+		message: 'Data type:{type} uid:{uid} is not owned',
+	}),
+	HistoryViolation: ErrorCreator({
+		errorCode: 600006,
+		errorName: 'HistoryViolation',
+		message: 'History violation with data type:{type} uid:{uid}',
+	}),
+	InvalidBinding: ErrorCreator({
+		errorCode: 600007,
+		errorName: 'InvalidBinding',
+		message: 'Binding {uid1} with {uid2} is not valid',
+	}),
+	ConnectedServiceMissing: ErrorCreator({
+		errorCode: 600008,
+		errorName: 'ConnectedServiceMissing',
+		message: 'Connected service {service} is missing',
+	}),
+	ServiceVoilation: ErrorCreator({
+		errorCode: 600009,
+		errorName: 'ServiceVoilation',
+		message: 'Requested {service} maneuver is not permitted.',
+	}),
+	Illegalchange: ErrorCreator({
+		errorCode: 600010,
+		errorName: 'Illegalchange',
+		message: 'Requested {alter} change on entity {entity} is not permitted.',
+	}),
+	InternalUnknownError: ErrorCreator({
+		errorCode: 600011,
+		errorName: 'InternalUnknownError',
+		message: 'Error: {message} {code}',
+	}),
+	AlternedData: ErrorCreator({
+		errorCode: 600012,
+		errorName: 'AlternedData',
+		message: 'Data {data} has been altered. {message}',
+	}),
+	AlreadyRegisteredError: ErrorCreator({
+		errorCode: 600013,
+		errorName: 'AlreadyRegisteredError',
+		message: 'User with {data} has already registered. Please sign in instead.',
+	}),
+	ServiceFailureError: ErrorCreator({
+		errorCode: 600014,
+		errorName: 'ServiceFailureError',
+		message: 'Error: {service} failed with: {message}',
+	}),
+}
+
+export { PrincipiaError, ErrorCreator, BaseErrors }

package/package.json

@@ -0,0 +1,35 @@
+{
+	"name": "@empyria/common",
+	"version": "0.1.0",
+	"description": "Shared backend goodies for Principia",
+	"license": "MIT",
+	"author": "Imre Fazekas <imre.fazekas@icloud.com>",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/imrefazekas/empyria-common.git"
+	},
+	"type": "module",
+	"main": "./index.js",
+	"scripts": {
+		"format": "bun oxfmt --check",
+		"format:fix": "bun oxfmt",
+		"lint": "bun oxlint",
+		"lint:fix": "bun oxlint --fix",
+		"test": "bun test --coverage",
+		"test:watch": "bun test --watch"
+	},
+	"dependencies": {
+		"@empyria/classification": "0.1.0",
+		"ata-validator": "1.6.1",
+		"clerobee": "1.0.8",
+		"ms": "2.1.3"
+	},
+	"devDependencies": {
+		"oxfmt": "0.63.0",
+		"oxlint": "1.78.0"
+	},
+	"engines": {
+		"bun": ">=1.4.0",
+		"node": ">=26"
+	}
+}

package/test/Ata.test.js

@@ -0,0 +1,185 @@
+import { describe, test, expect } from 'bun:test'
+import {
+	P_EMAIL,
+	P_PASS,
+	P_IPv4,
+	P_IPv6,
+	cloneBySchema,
+	defineSchema,
+	validate,
+	bool,
+	string,
+	enumType,
+	logLevel,
+	tmpFile,
+	logFile,
+	nodeEnv,
+	number,
+	email,
+	password,
+	ip4,
+	ip6,
+	renderCompact,
+	renderJSON,
+} from '../lib/Ata.js'
+import { PrincipiaError } from '../lib/Errors.js'
+
+describe('P_EMAIL', () => {
+	const re = new RegExp(`^${P_EMAIL}`, 'i')
+
+	test('matches a well-formed email', () => {
+		expect(re.test('user@example.com')).toBe(true)
+	})
+
+	test('rejects a non-dot character standing in for the label separator', () => {
+		// Regression test: the pattern's inter-label separator used to be an unescaped
+		// `.` (matches any character) instead of a literal dot.
+		expect(re.test('user@example!com')).toBe(false)
+	})
+})
+
+describe('P_PASS', () => {
+	const re = new RegExp(P_PASS)
+
+	test('matches a password with lower, upper, digit, and 8+ length', () => {
+		expect(re.test('Abcdefg1')).toBe(true)
+	})
+
+	test('rejects a password missing a digit', () => {
+		expect(re.test('Abcdefgh')).toBe(false)
+	})
+})
+
+describe('P_IPv4', () => {
+	const re = new RegExp(`^${P_IPv4}`)
+
+	test('matches a valid IPv4 address', () => {
+		expect(re.test('192.168.0.1')).toBe(true)
+	})
+
+	test('rejects an out-of-range octet', () => {
+		expect(re.test('999.168.0.1')).toBe(false)
+	})
+})
+
+describe('P_IPv6', () => {
+	const re = new RegExp(`^${P_IPv6}`)
+
+	test('matches the loopback address', () => {
+		expect(re.test('::1')).toBe(true)
+	})
+
+	test('rejects a plain non-IPv6 string', () => {
+		expect(re.test('not-an-ip')).toBe(false)
+	})
+})
+
+describe('defineSchema', () => {
+	test('builds an object schema requiring every key', () => {
+		expect(defineSchema({ a: string('x') })).toEqual({
+			type: 'object',
+			properties: { a: { type: 'string', default: 'x' } },
+			required: ['a'],
+			additionalProperties: true,
+		})
+	})
+
+	test('disallows extra properties when strict', () => {
+		expect(defineSchema({ a: string() }, { strict: true }).additionalProperties).toBe(false)
+	})
+})
+
+describe('cloneBySchema', () => {
+	test('keeps only the keys declared on the schema', () => {
+		const cloner = cloneBySchema({ properties: { a: {}, b: {} } })
+		expect(cloner({ a: 1, b: 2, c: 3 })).toEqual({ a: 1, b: 2 })
+	})
+})
+
+describe('createValidator / validate', () => {
+	const schema = defineSchema({ name: string() })
+
+	test('returns the input unchanged when valid', () => {
+		expect(validate(schema, { name: 'Bob' })).toEqual({ name: 'Bob' })
+	})
+
+	test('throws a PrincipiaError with a rendered message when invalid', () => {
+		try {
+			validate(schema, {})
+			throw new Error('should have thrown')
+		} catch (err) {
+			expect(err).toBeInstanceOf(PrincipiaError)
+			expect(err.errorName).toBe('ValidationError')
+			expect(err.message).toContain('name')
+		}
+	})
+
+	test('is strict by default: a numeric string is rejected for a number schema', () => {
+		const numSchema = defineSchema({ port: number() })
+		expect(() => validate(numSchema, { port: '4040' })).toThrow(PrincipiaError)
+	})
+
+	test('options are forwarded to the underlying Validator (coerceTypes)', () => {
+		// Regression test: process.env values are always strings (e.g. `PORT=4040` is
+		// `"4040"`, not `4040`) — env-parsing callers need this to avoid rejecting every
+		// explicitly-set numeric/boolean variable. See apps/*/env.js in empyria-nano-services.
+		const numSchema = defineSchema({ port: number() })
+		expect(validate(numSchema, { port: '4040' }, { coerceTypes: true })).toEqual({ port: 4040 })
+	})
+})
+
+describe('schema builders', () => {
+	test('bool sets a default when provided', () => {
+		expect(bool(true)).toEqual({ type: 'boolean', default: true })
+		expect(bool()).toEqual({ type: 'boolean' })
+	})
+
+	test('string sets default and minLength when provided', () => {
+		expect(string('x', 3)).toEqual({ type: 'string', default: 'x', minLength: 3 })
+	})
+
+	test('number sets a default when provided', () => {
+		expect(number(5)).toEqual({ type: 'number', default: 5 })
+	})
+
+	test('enumType sets the allowed list and default', () => {
+		expect(enumType(['a', 'b'], 'a')).toEqual({ enum: ['a', 'b'], default: 'a' })
+	})
+
+	test('logLevel defaults to info', () => {
+		expect(logLevel().default).toBe('info')
+		expect(logLevel().enum).toContain('debug')
+	})
+
+	test('tmpFile defaults to ./tmp', () => {
+		expect(tmpFile()).toEqual({ type: 'string', default: './tmp' })
+	})
+
+	test('logFile defaults to ./tmp/moleculer.log', () => {
+		expect(logFile()).toEqual({ type: 'string', default: './tmp/moleculer.log' })
+	})
+
+	test('nodeEnv defaults to local and allows test', () => {
+		// Regression test: bun test (and most JS test runners) set NODE_ENV=test
+		// automatically. Omitting it from the enum would make it impossible for any app
+		// validating process.env at import time to run its own test suite.
+		expect(nodeEnv()).toEqual({
+			enum: ['production', 'development', 'local', 'test'],
+			default: 'local',
+		})
+	})
+
+	test('email/password/ip4/ip6 reference their patterns', () => {
+		expect(email().pattern).toBe(P_EMAIL)
+		expect(password().pattern).toBe(P_PASS)
+		expect(ip4().pattern).toBe(P_IPv4)
+		expect(ip6().pattern).toBe(P_IPv6)
+	})
+})
+
+describe('renderCompact / renderJSON re-exports', () => {
+	test('are re-exported from ata-validator', () => {
+		expect(typeof renderCompact).toBe('function')
+		expect(typeof renderJSON).toBe('function')
+	})
+})

package/test/Codogram.test.js

@@ -0,0 +1,41 @@
+import { describe, test, expect } from 'bun:test'
+import { generateCodogram, CODOGRAM_LIST, CODOGRAMS } from '../lib/Codogram.js'
+import { PrincipiaError } from '../lib/Errors.js'
+
+describe('generateCodogram', () => {
+	test('PIN: numeric within the default digit range', () => {
+		const result = generateCodogram('PIN')
+		expect(Number.isInteger(result)).toBe(true)
+		expect(result).toBeGreaterThanOrEqual(0)
+		expect(result).toBeLessThan(1000000)
+	})
+
+	test('Code: upper-cased alphanumeric of the requested length', () => {
+		const result = generateCodogram('Code', { length: 10 })
+		expect(result).toBe(result.toUpperCase())
+		expect(result.length).toBe(10)
+	})
+
+	test('ABC: upper-cased alphabetic string', () => {
+		const result = generateCodogram('ABC')
+		expect(result).toBe(result.toUpperCase())
+		expect(typeof result).toBe('string')
+	})
+
+	test('ABC Num: upper-cased alphanumeric string', () => {
+		const result = generateCodogram('ABC Num')
+		expect(result).toBe(result.toUpperCase())
+		expect(typeof result).toBe('string')
+	})
+
+	test('throws for an unrecognised type', () => {
+		expect(() => generateCodogram('nonsense')).toThrow(PrincipiaError)
+	})
+})
+
+describe('CODOGRAM_LIST / CODOGRAMS', () => {
+	test('CODOGRAMS is a normalized-name map over CODOGRAM_LIST', () => {
+		expect(CODOGRAM_LIST).toEqual(['PIN', 'Code', 'ABC', 'ABC Num'])
+		expect(CODOGRAMS).toEqual({ PIN: 'PIN', CODE: 'Code', ABC: 'ABC', ABC_NUM: 'ABC Num' })
+	})
+})

package/test/Defaulter.test.js

@@ -0,0 +1,34 @@
+import { describe, test, expect } from 'bun:test'
+import { defaultsFromSchema } from '../lib/Defaulter.js'
+
+describe('defaultsFromSchema', () => {
+	test('uses each property default when present', () => {
+		const schema = {
+			type: 'object',
+			properties: {
+				name: { type: 'string', default: 'Bob' },
+				age: { type: 'number', default: 30 },
+			},
+			required: ['name', 'age'],
+		}
+		expect(defaultsFromSchema(schema)).toEqual({ name: 'Bob', age: 30 })
+	})
+
+	test('falls back to a type-appropriate empty value for required properties without a default', () => {
+		const schema = {
+			type: 'object',
+			properties: {
+				name: { type: 'string' },
+				active: { type: 'boolean' },
+				count: { type: 'number' },
+				tags: { type: 'array' },
+			},
+			required: ['name', 'active', 'count', 'tags'],
+		}
+		expect(defaultsFromSchema(schema)).toEqual({ name: '', active: false, count: 0, tags: [] })
+	})
+
+	test('returns an empty object for a non-object schema', () => {
+		expect(defaultsFromSchema({ type: 'string' })).toEqual({})
+	})
+})

package/test/Env.test.js

@@ -0,0 +1,18 @@
+import { describe, test, expect } from 'bun:test'
+import { createEnv } from '../lib/Env.js'
+
+describe('createEnv', () => {
+	test('includes the shared service defaults plus service-specific additions', () => {
+		const schema = createEnv({ CUSTOM_FLAG: { type: 'boolean' } })
+		expect(schema.type).toBe('object')
+		expect(schema.properties.NODE_ENV.default).toBe('local')
+		expect(schema.properties.PRINCIPIA_ID_LENGTH.default).toBe(32)
+		expect(schema.properties.CUSTOM_FLAG).toEqual({ type: 'boolean' })
+		expect(schema.required).toContain('CUSTOM_FLAG')
+	})
+
+	test('does not include connector-only settings', () => {
+		const schema = createEnv()
+		expect(schema.properties.PRINCIPIA_MONGO_URI).toBeUndefined()
+	})
+})

package/test/Errors.test.js

@@ -0,0 +1,55 @@
+import { describe, test, expect } from 'bun:test'
+import { PrincipiaError, ErrorCreator, BaseErrors } from '../lib/Errors.js'
+
+describe('PrincipiaError', () => {
+	test('carries message, errorName, and errorCode', () => {
+		const err = new PrincipiaError('Something broke', 'SomeError', 12345)
+		expect(err).toBeInstanceOf(Error)
+		expect(err.message).toBe('Something broke')
+		expect(err.errorName).toBe('SomeError')
+		expect(err.errorCode).toBe(12345)
+		expect(typeof err.stack).toBe('string')
+	})
+})
+
+describe('ErrorCreator', () => {
+	test('builds a factory that templates the message and stores params', () => {
+		const factory = ErrorCreator({
+			errorCode: 1,
+			errorName: 'Custom',
+			message: 'Value {value} is bad',
+		})
+		const err = factory({ value: 42 })
+		expect(err).toBeInstanceOf(PrincipiaError)
+		expect(err.message).toBe('Value 42 is bad')
+		expect(err.errorName).toBe('Custom')
+		expect(err.errorCode).toBe(1)
+		// errorName (unlike message/code/errorCode) is not stripped from the template args,
+		// so it ends up alongside the call-time params.
+		expect(err.params).toEqual({ errorName: 'Custom', value: 42 })
+	})
+
+	test('falls back to errorCode as errorName when none is given', () => {
+		const factory = ErrorCreator({ errorCode: 2, message: 'plain' })
+		expect(factory().errorName).toBe(2)
+	})
+})
+
+describe('BaseErrors', () => {
+	test('EntityInvalid uses its own error name, not a copy-pasted one', () => {
+		const err = BaseErrors.EntityInvalid({ type: 'User', id: 42 })
+		expect(err.errorName).toBe('EntityInvalid')
+		expect(err.errorCode).toBe(600004)
+		expect(err.message).toBe('User:42 is not valid')
+	})
+
+	test('UnrecognisedType templates its message', () => {
+		const err = BaseErrors.UnrecognisedType({ type: 'Widget' })
+		expect(err.message).toBe('Entity type Widget is not recognised')
+	})
+
+	test('ValidationError templates its message', () => {
+		const err = BaseErrors.ValidationError({ name: 'X', value: 'y', validation: 'z' })
+		expect(err.message).toBe('X (y) failed on input parameter schema validation: z')
+	})
+})

package/test/index.test.js

@@ -0,0 +1,76 @@
+import { describe, test, expect } from 'bun:test'
+import {
+	MOLECULER_SERVICE_ROLE,
+	PRINCIPIA_FEDERATION_ID,
+	moleculerMeta,
+	moleculerPrincipiaMeta,
+	workflowName,
+	workflowId,
+	identifyWorkflow,
+	PrincipiaError,
+} from '../index.js'
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+describe('moleculerMeta', () => {
+	test('shapes the actor/tracing fields under user, plus tokenKey', () => {
+		expect(
+			moleculerMeta({
+				actor: 'a',
+				federation: 'f',
+				flowID: 'flow',
+				processID: 'proc',
+				role: 'role',
+				tokenKey: 'key',
+			}),
+		).toEqual({
+			user: { actor: 'a', federation: 'f', flowID: 'flow', processID: 'proc', role: 'role' },
+			tokenKey: 'key',
+		})
+	})
+})
+
+describe('moleculerPrincipiaMeta', () => {
+	test('uses the federation ID as actor/federation and generates missing IDs', () => {
+		// Regression test: this used to call an unimported `uuid()` and throw ReferenceError.
+		const meta = moleculerPrincipiaMeta({ tokenKey: 'key' })
+		expect(meta.user.actor).toBe(PRINCIPIA_FEDERATION_ID)
+		expect(meta.user.federation).toBe(PRINCIPIA_FEDERATION_ID)
+		expect(meta.user.role).toBe(MOLECULER_SERVICE_ROLE)
+		expect(meta.user.flowID).toMatch(UUID_RE)
+		expect(meta.user.processID).toMatch(UUID_RE)
+	})
+
+	test('keeps explicitly provided flowID/processID', () => {
+		const meta = moleculerPrincipiaMeta({ flowID: 'f1', processID: 'p1', tokenKey: 'key' })
+		expect(meta.user.flowID).toBe('f1')
+		expect(meta.user.processID).toBe('p1')
+	})
+})
+
+describe('workflowName', () => {
+	test('joins and normalizes service:handler', () => {
+		expect(workflowName({ service: 'my svc', handler: 'do-thing' })).toBe('MYSVC:DO-THING')
+	})
+})
+
+describe('workflowId', () => {
+	test('appends a UUID to the workflow name', () => {
+		const id = workflowId({ service: 'svc', handler: 'h' })
+		const [name, handler, uuidPart] = id.split(':')
+		expect(`${name}:${handler}`).toBe('SVC:H')
+		expect(uuidPart).toMatch(UUID_RE)
+	})
+})
+
+describe('identifyWorkflow', () => {
+	test('parses back the service and handler', () => {
+		const id = workflowId({ service: 'svc', handler: 'h' })
+		expect(identifyWorkflow(id)).toEqual({ service: 'SVC', handler: 'H' })
+	})
+
+	test('throws a PrincipiaError for a malformed ID', () => {
+		expect(() => identifyWorkflow('too:short')).toThrow(PrincipiaError)
+		expect(() => identifyWorkflow(undefined)).toThrow(PrincipiaError)
+	})
+})