@empyria/moleculer 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,41 @@
+# AGENTS.md
+
+Moleculer helpers for **Principia**, a nanoservice framework built primarily on Bun:
+`BaseMixin` (per-service Principia meta stamping), `MetaGuard` (a middleware guarding
+actions/events against unwanted cross-federation access), and lower-level `Connector.js`/
+`util/` helpers.
+
+## Runtime
+
+- Requires Bun `>=1.4.0` or Node.js `>=26`, inherited from `@empyria/classification`'s use
+  of native `Temporal`. Both `@empyria/classification` and `@empyria/common` are **git
+  dependencies** — this package only sees their pushed commits, not local working-tree changes
+  in sibling repos.
+- Plain ESM, no TypeScript, no build step.
+- Relative imports must include explicit `.js` extensions — Bun tolerates missing ones, Node's
+  ESM resolver doesn't.
+
+## Known incomplete module
+
+`mixins/Connector.mixin.js` imports `@empyria/redis` and `@empyria/mongo`, which aren't
+published as standalone packages yet (they still live inside the monolithic `principia` repo's
+`libs/`). It is **not** re-exported from [Mixins.js](./Mixins.js) — re-adding that export line
+before those two packages exist would break every consumer's import of this whole package. Only
+re-export it once both are published; the file itself has a comment marking this.
+
+## Layout
+
+- [Mixins.js](./Mixins.js) is the package entry point (mixins + middleware only).
+- [Connector.js](./Connector.js) (broker start/stop helper) and `util/*.js` are separate
+  subpath exports (see `package.json`'s `exports` map) — not re-exported from `Mixins.js`.
+- `MetaGuard.middleware.js`'s `localAction`/`remoteAction` share one `guardAction` helper —
+  keep them in sync if you touch the guard logic; don't let them drift back into duplicated code.
+- Tests live in `test/`, flat, one file per module, using `bun:test` — several exercise a real
+  `moleculer` `ServiceBroker` rather than mocks (see `Connector.test.js`, `Base.mixin.test.js`).
+  A service registered on an already-started broker needs `broker.waitForServices(name)` before
+  it's callable — a bare `createService` + immediate `call` will 404.
+
+## 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/Connector.js

@@ -0,0 +1,54 @@
+import { ServiceBroker } from 'moleculer'
+
+/**
+ * Starts a Moleculer broker and waits for any required services to become available.
+ * @param {Object} params
+ * @param {string} [params.namespace] - Broker namespace.
+ * @param {string} [params.nodeID] - Broker node ID.
+ * @param {Object} [params.transporter] - Moleculer transporter config.
+ * @param {string} [params.logLevel='debug'] - Broker log level.
+ * @param {string[]} [params.servicesRequired] - Action/service names to wait for before resolving.
+ * @param {number} [params.waitTimeout] - Max time (ms) to wait for `servicesRequired`.
+ * @param {number} [params.interval] - Poll interval (ms) while waiting for `servicesRequired`.
+ * @returns {Promise<{broker: ServiceBroker, call: (action: string, params?: Object, opts?: {timeout?: number, meta?: Object}) => Promise<*>, stop: () => Promise<void>}>}
+ */
+export const connect = async ({
+	namespace,
+	nodeID,
+	transporter,
+	logLevel,
+	servicesRequired,
+	waitTimeout,
+	interval,
+}) => {
+	const broker = new ServiceBroker({
+		namespace,
+		nodeID,
+		transporter,
+		logLevel: logLevel ?? 'debug',
+		hotReload: false,
+		metrics: false,
+		tracing: false,
+	})
+
+	console.log('🔌 Starting Moleculer broker...')
+	await broker.start()
+	console.log('✅ Moleculer broker connected')
+
+	if (servicesRequired?.length > 0) {
+		await broker.waitForServices(servicesRequired, waitTimeout, interval)
+	}
+
+	return {
+		broker,
+		async call(action, params, opts) {
+			return broker.call(action, params, {
+				timeout: opts?.timeout,
+				meta: opts?.meta,
+			})
+		},
+		async stop() {
+			await broker.stop()
+		},
+	}
+}

package/MetaGuard.middleware.js

@@ -0,0 +1,67 @@
+import { validateContext, getUser } from './util/Context.js'
+
+import { PRINCIPIA_FEDERATION_ID, BaseErrors } from '@empyria/common'
+
+/**
+ * Builds the shared guard logic for `localAction`/`remoteAction` hooks: validates the
+ * call's context, rejects cross-federation calls to a whitelisted action, and optionally
+ * resolves the caller into `ctx.meta.user`.
+ * @param {(ctx: Object) => Promise<*>} next - The next handler in the middleware chain.
+ * @param {Object} action - The Moleculer action being guarded.
+ * @param {boolean} resolveUser - Whether to resolve and attach the caller's user.
+ * @param {string[]} whitelistedActions - Action names restricted to same-federation callers.
+ * @returns {(ctx: Object) => Promise<*>}
+ */
+function guardAction(next, action, resolveUser, whitelistedActions) {
+	return async (ctx) => {
+		const { user } = validateContext(ctx, action)
+
+		if (
+			whitelistedActions.includes(action.name) &&
+			user.federation !== PRINCIPIA_FEDERATION_ID
+		) {
+			throw new BaseErrors.ServiceVoilation({
+				service: `Microservice ${ctx.action?.name || action.name} communication`,
+			})
+		}
+
+		if (resolveUser && action.name !== 'v1.Auth.resolveToken') {
+			ctx.meta.user = await getUser(ctx, action)
+		}
+
+		return next(ctx)
+	}
+}
+
+/**
+ * Moleculer middleware that guards local/remote actions and local events against
+ * unwanted access, validating the call's `ctx.meta` and optionally resolving the caller.
+ * @param {Object} options
+ * @param {boolean} [options.resolveUser] - Resolve the caller via `v1.Auth.resolveToken` and
+ *   attach it to `ctx.meta.user` before calling through.
+ * @param {string[]} [options.whitelistedActions] - Action names restricted to same-federation
+ *   callers; cross-federation calls to these are rejected.
+ * @returns {Object} A Moleculer middleware object with `localAction`, `remoteAction`, and
+ *   `localEvent` hooks.
+ */
+export function MetaGuard({ resolveUser, whitelistedActions = [] }) {
+	return {
+		name: 'MetaGuard',
+
+		localAction(next, action) {
+			return guardAction(next, action, resolveUser, whitelistedActions)
+		},
+
+		remoteAction(next, action) {
+			return guardAction(next, action, resolveUser, whitelistedActions)
+		},
+
+		localEvent(next, event) {
+			return async (ctx) => {
+				validateContext(ctx, event)
+
+				return next(ctx)
+			}
+		},
+	}
+}

package/Mixins.js

@@ -0,0 +1,2 @@
+export { BaseMixin } from './mixins/Base.mixin.js'
+export { MetaGuard } from './MetaGuard.middleware.js'

package/README.md

@@ -0,0 +1,90 @@
+# @empyria/moleculer
+
+Moleculer helpers for **Principia**, a nanoservice framework built primarily on Bun:
+a base service mixin, and a context-validating guard middleware against unwanted
+(unauthenticated or cross-federation) access.
+
+## 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)
+and [@empyria/common](https://github.com/imrefazekas/empyria-common), which this package
+depends on and which use the native `Temporal` global for all date/time handling.
+
+## Install
+
+```bash
+bun add @empyria/moleculer
+```
+
+## Usage
+
+```js
+import { ServiceBroker } from 'moleculer'
+import { BaseMixin, MetaGuard } from '@empyria/moleculer'
+
+const broker = new ServiceBroker({
+	middlewares: [MetaGuard({ resolveUser: true, whitelistedActions: ['v1.Internal.action'] })],
+})
+
+broker.createService({
+	name: 'my-service',
+	mixins: [BaseMixin],
+	actions: {
+		hello(ctx) {
+			return `Hello, ${ctx.meta.user.actor}`
+		},
+	},
+})
+```
+
+Everything is re-exported from the package root via [Mixins.js](./Mixins.js). The broker
+connection helper and lower-level utilities are separate subpath exports, importable directly:
+
+```js
+import { connect } from '@empyria/moleculer/Connector.js'
+import { hashPassword, verifyPassword } from '@empyria/moleculer/util/Crypto.js'
+```
+
+## Modules
+
+| Module                                                   | Purpose                                                                                                                      |
+| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| [Mixins.js](./Mixins.js)                                 | Package entry point; re-exports `BaseMixin` and `MetaGuard`.                                                                 |
+| [MetaGuard.middleware.js](./MetaGuard.middleware.js)     | `MetaGuard` — a Moleculer middleware guarding actions/events against unwanted access, with optional caller resolution.       |
+| [mixins/Base.mixin.js](./mixins/Base.mixin.js)           | `BaseMixin` — stamps a Principia meta (actor/federation/flow/process IDs) on service start, and exposes the package version. |
+| [mixins/Connector.mixin.js](./mixins/Connector.mixin.js) | `ConnectorMixin` — adds optional Redis/Mongo setup. **Not yet exported from `Mixins.js`** — see below.                       |
+| [Connector.js](./Connector.js)                           | `connect` — starts a Moleculer broker and waits for required services.                                                       |
+| [util/Context.js](./util/Context.js)                     | Context helpers: `getParams`, `getUser`, `validateContext`, `actionStamped`, `timeStamped`, `checkDefined`.                  |
+| [util/Crypto.js](./util/Crypto.js)                       | Hashing, Ed25519 signing/verification, and password hashing (`hashPassword`/`verifyPassword`).                               |
+
+### Known limitation: `ConnectorMixin`
+
+`mixins/Connector.mixin.js` imports `@empyria/redis` and `@empyria/mongo`, which aren't
+published as standalone packages yet. It's intentionally left out of the [Mixins.js](./Mixins.js)
+barrel so the rest of the package stays importable — until those two are published, use it only
+via a direct subpath import (`@empyria/moleculer/mixins/Connector.mixin.js`), where it will
+fail to resolve.
+
+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 sources. Several
+exercise a real `moleculer` `ServiceBroker` rather than mocks.
+
+## 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/coverage/lcov.info

@@ -0,0 +1,216 @@
+TN:
+SF:Connector.js
+FNF:5
+FNH:5
+DA:1,42
+DA:15,25
+DA:16,12
+DA:17,9
+DA:18,14
+DA:19,11
+DA:20,19
+DA:21,14
+DA:22,13
+DA:23,3
+DA:24,38
+DA:25,14
+DA:26,11
+DA:27,16
+DA:28,34
+DA:29,21
+DA:30,19
+DA:31,16
+DA:32,5
+DA:34,59
+DA:35,23
+DA:36,51
+DA:38,38
+DA:39,72
+DA:40,2
+DA:42,12
+DA:43,10
+DA:44,30
+DA:45,44
+DA:46,31
+DA:47,22
+DA:48,6
+DA:50,9
+DA:51,27
+DA:53,2
+LF:35
+LH:35
+end_of_record
+TN:
+SF:MetaGuard.middleware.js
+FNF:8
+FNH:7
+DA:1,61
+DA:3,71
+DA:15,51
+DA:16,19
+DA:17,50
+DA:19,4
+DA:20,44
+DA:21,44
+DA:22,7
+DA:23,47
+DA:24,78
+DA:25,2
+DA:26,4
+DA:28,65
+DA:29,47
+DA:30,4
+DA:32,18
+DA:47,51
+DA:48,12
+DA:49,21
+DA:51,22
+DA:52,69
+DA:55,0
+DA:56,4
+DA:59,21
+DA:60,24
+DA:61,36
+DA:63,18
+DA:66,1
+LF:29
+LH:28
+end_of_record
+TN:
+SF:mixins/Base.mixin.js
+FNF:3
+FNH:3
+DA:1,25
+DA:2,29
+DA:3,41
+DA:5,41
+DA:7,99
+DA:9,50
+DA:10,43
+DA:12,26
+DA:13,67
+DA:14,11
+DA:21,27
+DA:22,20
+DA:24,18
+DA:26,8
+DA:27,97
+DA:29,58
+DA:31,33
+DA:32,36
+DA:33,42
+DA:34,27
+DA:35,30
+DA:36,35
+DA:37,39
+DA:38,8
+DA:41,13
+DA:45,10
+DA:46,16
+DA:48,4
+DA:50,13
+DA:54,10
+DA:55,29
+DA:57,2
+DA:58,1
+LF:33
+LH:33
+end_of_record
+TN:
+SF:util/Context.js
+FNF:6
+FNH:6
+DA:1,63
+DA:2,47
+DA:9,14
+DA:10,80
+DA:11,47
+DA:12,18
+DA:22,22
+DA:23,37
+DA:24,25
+DA:26,35
+DA:27,64
+DA:39,22
+DA:40,38
+DA:42,53
+DA:44,50
+DA:45,41
+DA:46,76
+DA:47,2
+DA:48,2
+DA:50,26
+DA:59,15
+DA:60,12
+DA:61,22
+DA:62,32
+DA:63,20
+DA:64,24
+DA:65,30
+DA:66,36
+DA:67,2
+DA:75,17
+DA:76,45
+DA:77,14
+DA:87,17
+DA:88,35
+DA:90,91
+DA:92,10
+LF:36
+LH:36
+end_of_record
+TN:
+SF:util/Crypto.js
+FNF:10
+FNH:10
+DA:1,157
+DA:12,38
+DA:14,48
+DA:16,38
+DA:23,14
+DA:24,80
+DA:35,43
+DA:36,48
+DA:37,88
+DA:44,11
+DA:45,67
+DA:48,84
+DA:49,87
+DA:51,12
+DA:52,43
+DA:53,38
+DA:54,2
+DA:63,37
+DA:64,51
+DA:65,51
+DA:66,72
+DA:67,41
+DA:68,41
+DA:69,18
+DA:70,15
+DA:71,5
+DA:73,52
+DA:74,33
+DA:84,50
+DA:85,51
+DA:86,53
+DA:87,50
+DA:88,64
+DA:89,39
+DA:90,41
+DA:91,18
+DA:92,14
+DA:93,5
+DA:95,51
+DA:103,18
+DA:104,47
+DA:105,52
+DA:106,40
+DA:116,24
+DA:117,49
+DA:118,63
+DA:119,52
+DA:120,46
+LF:48
+LH:48
+end_of_record

package/mixins/Base.mixin.js

@@ -0,0 +1,58 @@
+import fs from 'fs'
+import path from 'path'
+import { randomUUID } from 'crypto'
+
+import { fileURLToPath } from 'url'
+
+import { PRINCIPIA_FEDERATION_ID, MOLECULER_SERVICE_ROLE, moleculerMeta } from '@empyria/common'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+const VERSION = JSON.parse(
+	fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'),
+).version
+
+/**
+ * Base Moleculer mixin every Principia service builds on. On `started`, stamps a
+ * Principia-flavored `meta` (actor/federation/flow/process IDs) onto the service, and
+ * exposes the running package version as both a method and an action.
+ */
+export const BaseMixin = {
+	name: 'BaseMixin',
+
+	dependencies: [],
+
+	async started() {
+		this.logger.info(`🚶🚶🚶 ${this.name}-service has started...`)
+
+		this.serviceSettings = this.settings[this.name] ?? {}
+
+		this.meta = moleculerMeta({
+			actor: `${this.name}-service`,
+			federation: PRINCIPIA_FEDERATION_ID,
+			flowID: randomUUID(),
+			processID: randomUUID(),
+			role: MOLECULER_SERVICE_ROLE,
+			tokenKey: `${this.name}_${VERSION}`,
+		})
+	},
+
+	methods: {
+		/**
+		 * @returns {string} The running package's version, read from `package.json`.
+		 */
+		packageVersion() {
+			return VERSION
+		},
+	},
+
+	actions: {
+		/**
+		 * @returns {{version: string}} The running package's version.
+		 */
+		async packageVersion() {
+			return { version: VERSION }
+		},
+	},
+}

package/mixins/Connector.mixin.js

@@ -0,0 +1,50 @@
+// NOTE: not yet re-exported from ./Mixins.js — see the comment there. Requires
+// `@empyria/redis` and `@empyria/mongo`, which aren't published as standalone
+// packages yet, so importing this file will currently fail to resolve.
+import { OK } from '@empyria/classification'
+
+import { RedisHelper } from '@empyria/redis'
+import { connect, terminate } from '@empyria/mongo'
+
+import { BaseMixin } from './Base.mixin.js'
+
+/**
+ * Extends {@link BaseMixin} with optional Redis/Mongo connection setup, driven by the
+ * service's `settings[serviceName.toLowerCase()].redis`/`.mongo` config.
+ */
+export const ConnectorMixin = {
+	name: 'ConnectorMixin',
+
+	mixins: [BaseMixin],
+
+	async started() {
+		this.logger.info(`🚶🚶🚶 ${this.name} has started...`)
+
+		if (this.settings[this.name.toLocaleLowerCase()]) {
+			const sets = this.settings[this.name.toLocaleLowerCase()]
+			if (sets.redis) {
+				this.redis = new RedisHelper(sets.redis, this.logger)
+				await this.redis.init()
+
+				this.logger.info(`${this.name} Redis setup done.`)
+			}
+
+			if (sets.mongo) {
+				const { mongoDB, mongoClient } = await connect(sets.mongo, this.logger)
+				this.mongoClient = mongoClient
+				this.mongoDB = mongoDB
+
+				this.logger.info(`${this.name} Mongo setup done.`)
+			}
+		} else {
+			this.logger.info(`😱😱😱 ${this.name} has no dedicated configuration...`)
+		}
+	},
+
+	async stopped() {
+		if (this.redis) await this.redis.terminate()
+		if (this.mongoClient) await terminate(this.mongoClient)
+
+		return OK
+	},
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+	"name": "@empyria/moleculer",
+	"version": "0.1.0",
+	"description": "Moleculer helpers for Principia",
+	"license": "MIT",
+	"author": "Imre Fazekas <imre.fazekas@icloud.com>",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/imrefazekas/empyria-guard-moleculer.git"
+	},
+	"type": "module",
+	"main": "./Mixins.js",
+	"exports": {
+		".": "./Mixins.js",
+		"./Connector.js": "./Connector.js",
+		"./mixins/*": "./mixins/*.js",
+		"./util/*": "./util/*.js",
+		"./package.json": "./package.json"
+	},
+	"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",
+		"@empyria/common": "0.1.0",
+		"moleculer": "0.15.1"
+	},
+	"devDependencies": {
+		"oxfmt": "0.63.0",
+		"oxlint": "1.78.0"
+	},
+	"engines": {
+		"bun": ">=1.4.0",
+		"node": ">=26"
+	}
+}

package/test/Base.mixin.test.js

@@ -0,0 +1,30 @@
+import { describe, test, expect, afterEach } from 'bun:test'
+import { ServiceBroker } from 'moleculer'
+import { BaseMixin } from '../mixins/Base.mixin.js'
+import { PRINCIPIA_FEDERATION_ID, MOLECULER_SERVICE_ROLE } from '@empyria/common'
+
+let broker
+
+afterEach(async () => {
+	if (broker?.started) await broker.stop()
+})
+
+describe('BaseMixin', () => {
+	test('stamps a Principia meta on start, and exposes the package version', async () => {
+		broker = new ServiceBroker({ logLevel: 'fatal', nodeID: 'base-mixin-test' })
+		broker.createService({ name: 'testsvc', mixins: [BaseMixin] })
+		await broker.start()
+
+		const svc = broker.getLocalService('testsvc')
+		expect(svc.meta.user.actor).toBe('testsvc-service')
+		expect(svc.meta.user.federation).toBe(PRINCIPIA_FEDERATION_ID)
+		expect(svc.meta.user.role).toBe(MOLECULER_SERVICE_ROLE)
+		expect(typeof svc.meta.user.flowID).toBe('string')
+		expect(typeof svc.meta.user.processID).toBe('string')
+
+		expect(typeof svc.packageVersion()).toBe('string')
+		expect(await broker.call('testsvc.packageVersion')).toEqual({
+			version: svc.packageVersion(),
+		})
+	})
+})

package/test/Connector.test.js

@@ -0,0 +1,35 @@
+import { describe, test, expect } from 'bun:test'
+import { connect } from '../Connector.js'
+
+describe('connect', () => {
+	test('starts a broker and exposes call/stop', async () => {
+		const conn = await connect({ nodeID: 'connector-test-1', logLevel: 'fatal' })
+		try {
+			expect(conn.broker.started).toBe(true)
+			expect(typeof conn.call).toBe('function')
+			expect(typeof conn.stop).toBe('function')
+
+			conn.broker.createService({
+				name: 'echo',
+				actions: { ping: () => 'pong' },
+			})
+			await conn.broker.waitForServices('echo')
+			expect(await conn.call('echo.ping')).toBe('pong')
+		} finally {
+			await conn.stop()
+		}
+		expect(conn.broker.started).toBe(false)
+	})
+
+	test('rejects when a required service never becomes available', async () => {
+		await expect(
+			connect({
+				nodeID: 'connector-test-2',
+				logLevel: 'fatal',
+				servicesRequired: ['nonexistent.service'],
+				waitTimeout: 200,
+				interval: 50,
+			}),
+		).rejects.toThrow()
+	})
+})

package/test/Context.test.js

@@ -0,0 +1,106 @@
+import { describe, test, expect } from 'bun:test'
+import {
+	getParams,
+	getUser,
+	validateContext,
+	actionStamped,
+	timeStamped,
+	checkDefined,
+} from '../util/Context.js'
+import { PrincipiaError } from '@empyria/common'
+
+describe('getParams', () => {
+	test('unwraps a body.packet envelope', () => {
+		expect(getParams({ params: { body: { packet: { a: 1 } } } })).toEqual({ a: 1 })
+	})
+
+	test('falls back to body when there is no packet', () => {
+		expect(getParams({ params: { body: { a: 1 } } })).toEqual({ a: 1 })
+	})
+
+	test('falls back to raw params when there is no body', () => {
+		expect(getParams({ params: { a: 1 } })).toEqual({ a: 1 })
+	})
+})
+
+describe('getUser', () => {
+	test('resolves the caller via v1.Auth.resolveToken, forwarding the action service meta', async () => {
+		const calls = []
+		const ctx = {
+			meta: { tokenKey: 'tok' },
+			call: async (...args) => {
+				calls.push(args)
+				return { actor: 'resolved' }
+			},
+		}
+		const action = { service: { meta: { tokenKey: 'service-key' } } }
+
+		const user = await getUser(ctx, action)
+		expect(user).toEqual({ actor: 'resolved' })
+		expect(calls).toEqual([
+			['v1.Auth.resolveToken', { tokenKey: 'tok' }, { meta: { tokenKey: 'service-key' } }],
+		])
+	})
+
+	test('returns undefined when there is no tokenKey', () => {
+		expect(getUser({ meta: {} }, { service: {} })).toBeUndefined()
+	})
+})
+
+describe('validateContext', () => {
+	test('returns the user/tokenKey for a well-formed context', () => {
+		const ctx = { meta: { user: { actor: 'a', federation: 'f' }, tokenKey: 'tok' } }
+		expect(validateContext(ctx, { name: 'v1.Test.action' })).toEqual({
+			user: { actor: 'a', federation: 'f' },
+			tokenKey: 'tok',
+		})
+	})
+
+	test('skips validation for internal ($-prefixed) actions', () => {
+		expect(validateContext({ meta: {} }, { name: '$node.health' })).toBeUndefined()
+	})
+
+	test('throws when the context has no authenticated user', () => {
+		const ctx = { meta: {} }
+		expect(() => validateContext(ctx, { name: 'v1.Test.action' })).toThrow(PrincipiaError)
+	})
+})
+
+describe('actionStamped', () => {
+	test('builds an actor/tracing stamp with the current time', () => {
+		const before = Date.now()
+		const stamp = actionStamped({
+			actor: 'a',
+			federation: 'f',
+			role: 'r',
+			flowID: 'flow',
+			processID: 'proc',
+		})
+		expect(stamp.actor).toBe('a')
+		expect(stamp.federation).toBe('f')
+		expect(stamp.role).toBe('r')
+		expect(stamp.flowID).toBe('flow')
+		expect(stamp.processID).toBe('proc')
+		expect(stamp.timestamp).toBeGreaterThanOrEqual(before)
+	})
+})
+
+describe('timeStamped', () => {
+	test('sets a timestamp field (not the misspelled "timestmap")', () => {
+		const before = Date.now()
+		const obj = timeStamped({})
+		expect(obj).toHaveProperty('timestamp')
+		expect(obj).not.toHaveProperty('timestmap')
+		expect(obj.timestamp).toBeGreaterThanOrEqual(before)
+	})
+})
+
+describe('checkDefined', () => {
+	test('keeps only the defined properties', () => {
+		expect(checkDefined({ a: 1, b: undefined, c: null, d: 2 })).toEqual({ a: 1, d: 2 })
+	})
+
+	test('throws when nothing is defined', () => {
+		expect(() => checkDefined({ a: undefined, b: null })).toThrow(PrincipiaError)
+	})
+})

package/test/Crypto.test.js

@@ -0,0 +1,73 @@
+import { describe, test, expect } from 'bun:test'
+import {
+	hashify,
+	stampIt,
+	generateKeys,
+	generateSignature,
+	verifySignature,
+	hashPassword,
+	verifyPassword,
+} from '../util/Crypto.js'
+
+describe('hashify', () => {
+	test('produces a stable SHA3-256 hex digest', () => {
+		const digest = hashify({ a: 1 })
+		expect(digest).toMatch(/^[0-9a-f]{64}$/)
+		expect(hashify({ a: 1 })).toBe(digest)
+	})
+})
+
+describe('stampIt', () => {
+	test('falls back to now() when there is no timestamper or default', async () => {
+		const before = Date.now()
+		const result = await stampIt(null, null, null)
+		expect(result).toBeGreaterThanOrEqual(before)
+	})
+
+	test('returns the default value when given and there is no timestamper', async () => {
+		expect(await stampIt(null, null, 'fallback')).toBe('fallback')
+	})
+
+	test('uses the timestamper when given', async () => {
+		const timestamper = { trustedTimestamp: async (hash) => `stamped:${hash}` }
+		const result = await stampIt({ a: 1 }, timestamper, 'unused')
+		expect(result).toBe(`stamped:${hashify({ a: 1 })}`)
+	})
+})
+
+describe('generateKeys / generateSignature / verifySignature', () => {
+	test('round-trips: a signature verifies against its own key pair', () => {
+		const { privKeyHex, pubKeyHex } = generateKeys()
+		expect(privKeyHex).toMatch(/^[0-9a-f]{64}$/)
+		expect(pubKeyHex).toMatch(/^[0-9a-f]{64}$/)
+
+		const signature = generateSignature('hello world', privKeyHex)
+		expect(verifySignature('hello world', signature, pubKeyHex)).toBe(true)
+	})
+
+	test('rejects a signature for a different message', () => {
+		const { privKeyHex, pubKeyHex } = generateKeys()
+		const signature = generateSignature('original', privKeyHex)
+		expect(verifySignature('tampered', signature, pubKeyHex)).toBe(false)
+	})
+
+	test('rejects a signature verified against a different key pair', () => {
+		const a = generateKeys()
+		const b = generateKeys()
+		const signature = generateSignature('hello', a.privKeyHex)
+		expect(verifySignature('hello', signature, b.pubKeyHex)).toBe(false)
+	})
+})
+
+describe('hashPassword / verifyPassword', () => {
+	test('round-trips: a password verifies against its own hash', async () => {
+		const hash = await hashPassword('correct horse battery staple')
+		expect(hash).toContain('.')
+		expect(await verifyPassword('correct horse battery staple', hash)).toBe(true)
+	})
+
+	test('rejects the wrong password', async () => {
+		const hash = await hashPassword('correct horse battery staple')
+		expect(await verifyPassword('wrong password', hash)).toBe(false)
+	})
+})

package/test/MetaGuard.test.js

@@ -0,0 +1,108 @@
+import { describe, test, expect } from 'bun:test'
+import { MetaGuard } from '../MetaGuard.middleware.js'
+import { PrincipiaError } from '@empyria/common'
+
+const action = (name) => ({ name, service: { meta: {} } })
+const ctxWithUser = (federation = 'my-fed', extra = {}) => ({
+	meta: { user: { actor: 'a', federation }, tokenKey: 'tok' },
+	...extra,
+})
+
+describe('MetaGuard: localAction / remoteAction', () => {
+	test('calls through when the context is valid and nothing is whitelisted', async () => {
+		const guard = MetaGuard({ resolveUser: false })
+		const result = await guard.localAction(
+			async () => 'ok',
+			action('v1.Test.action'),
+		)(ctxWithUser())
+		expect(result).toBe('ok')
+	})
+
+	test('throws when the context has no authenticated user', async () => {
+		const guard = MetaGuard({ resolveUser: false })
+		await expect(
+			guard.localAction(async () => 'ok', action('v1.Test.action'))({ meta: {} }),
+		).rejects.toThrow(PrincipiaError)
+	})
+
+	test('rejects a cross-federation call to a whitelisted action', async () => {
+		// Regression test: `whitelistedActions` used to be a hardcoded empty array with no
+		// way to configure it, so this branch was permanently dead code.
+		const guard = MetaGuard({
+			resolveUser: false,
+			whitelistedActions: ['v1.Restricted.action'],
+		})
+		await expect(
+			guard.localAction(
+				async () => 'ok',
+				action('v1.Restricted.action'),
+			)(ctxWithUser('other-federation')),
+		).rejects.toThrow(PrincipiaError)
+	})
+
+	test('allows a same-federation call to a whitelisted action', async () => {
+		const guard = MetaGuard({
+			resolveUser: false,
+			whitelistedActions: ['v1.Restricted.action'],
+		})
+		const ctx = ctxWithUser('563ac2a1-3fe3-4c5f-b20f-6f33e5cbd680')
+		const result = await guard.localAction(
+			async () => 'ok',
+			action('v1.Restricted.action'),
+		)(ctx)
+		expect(result).toBe('ok')
+	})
+
+	test('resolves and attaches the caller when resolveUser is set', async () => {
+		// Regression test: this used to call getUser(ctx) with no `action`, throwing
+		// "undefined is not an object (evaluating 'action.service')".
+		const guard = MetaGuard({ resolveUser: true })
+		const resolved = { actor: 'resolved-user' }
+		const ctx = ctxWithUser('my-fed', { call: async () => resolved })
+		const result = await guard.localAction(
+			async (c) => c.meta.user,
+			action('v1.Some.action'),
+		)(ctx)
+		expect(result).toBe(resolved)
+	})
+
+	test('does not try to resolve the caller for v1.Auth.resolveToken itself', async () => {
+		const guard = MetaGuard({ resolveUser: true })
+		const originalUser = { actor: 'a', federation: 'my-fed' }
+		const ctx = {
+			meta: { user: originalUser, tokenKey: 'tok' },
+			call: async () => {
+				throw new Error('should not be called')
+			},
+		}
+		const result = await guard.localAction(
+			async (c) => c.meta.user,
+			action('v1.Auth.resolveToken'),
+		)(ctx)
+		expect(result).toBe(originalUser)
+	})
+
+	test('remoteAction applies the same guard logic as localAction', async () => {
+		const guard = MetaGuard({ resolveUser: false })
+		const result = await guard.remoteAction(
+			async () => 'ok',
+			action('v1.Test.action'),
+		)(ctxWithUser())
+		expect(result).toBe('ok')
+	})
+})
+
+describe('MetaGuard: localEvent', () => {
+	test('calls through for a valid context', async () => {
+		const guard = MetaGuard({ resolveUser: false })
+		const result = await guard.localEvent(async () => 'ok', action('some.event'))(ctxWithUser())
+		expect(result).toBe('ok')
+	})
+
+	test('throws for an invalid context', async () => {
+		const guard = MetaGuard({ resolveUser: false })
+		await expect(
+			guard.localEvent(async () => 'ok', action('some.event'))({ meta: {} }),
+		).rejects.toThrow(PrincipiaError)
+	})
+})

package/util/Context.js

@@ -0,0 +1,93 @@
+import { Time, cloneDefined } from '@empyria/classification'
+import { BaseErrors } from '@empyria/common'
+
+/**
+ * Extracts an action's actual input, unwrapping gateway/transport envelopes.
+ * @param {Object} ctx - Moleculer call context.
+ * @returns {*} `ctx.params.body.packet` if present, else `ctx.params.body`, else `ctx.params`.
+ */
+export function getParams(ctx) {
+	if (ctx.params.body && ctx.params.body.packet) return ctx.params.body.packet
+	if (ctx.params.body) return ctx.params.body
+	return ctx.params
+}
+
+/**
+ * Resolves the calling user for a token-bearing context via `v1.Auth.resolveToken`.
+ * @param {Object} ctx - Moleculer call context; must have `ctx.meta.tokenKey`.
+ * @param {Object} action - The guarded action; `action.service.meta` is forwarded as the
+ *   resolve call's own `meta` (so it's itself authenticated as the calling service).
+ * @returns {Promise<Object>|undefined} The resolved user, or `undefined` if there's no token.
+ */
+export function getUser(ctx, action) {
+	const tokenKey = ctx?.meta?.tokenKey
+	if (!tokenKey) return
+
+	const meta = action?.service?.meta
+	return ctx.call('v1.Auth.resolveToken', { tokenKey }, { meta })
+}
+
+/**
+ * Validates that a context carries a well-formed, authenticated user, unless the
+ * action/event is an internal Moleculer one (name starts with `$`).
+ * @param {Object} ctx - Moleculer call context.
+ * @param {Object} [action] - The action/event being guarded.
+ * @returns {{user: Object, tokenKey: string}|undefined} The context's user/tokenKey, or
+ *   `undefined` for a `$`-prefixed internal action.
+ * @throws {PrincipiaError} `BaseErrors.ServiceVoilation` if `ctx.meta.user` is missing or incomplete.
+ */
+export function validateContext(ctx, action) {
+	const { user, tokenKey } = ctx.meta
+
+	if (action && action.name.startsWith('$')) return
+
+	if (!user || !user.actor || !user.federation) {
+		throw BaseErrors.ServiceVoilation({
+			service: `Microservice ${ctx.action?.name || action.name} communication`,
+		})
+	}
+
+	return { user, tokenKey }
+}
+
+/**
+ * Builds a stamp of a user's identity/tracing fields plus the current time, suitable for
+ * attaching to an entity as "who/when this happened".
+ * @param {Object} user - A context user (see {@link validateContext}).
+ * @returns {{actor: string, federation: string, role: string, flowID: string, processID: string, timestamp: number}}
+ */
+export function actionStamped(user) {
+	return {
+		actor: user.actor,
+		federation: user.federation,
+		role: user.role,
+		flowID: user.flowID,
+		processID: user.processID,
+		timestamp: Date.now() - Time.shift,
+	}
+}
+
+/**
+ * Adds a `timestamp` field (current time) to an object. Mutates and returns `object`.
+ * @param {Object} object - Object to stamp.
+ * @returns {Object} The same `object`, for chaining.
+ */
+export function timeStamped(object) {
+	object.timestamp = Date.now() - Time.shift
+	return object
+}
+
+/**
+ * Builds a shallow copy of `object` containing only its defined properties, requiring
+ * at least one to be present.
+ * @param {Object} object - Object to filter.
+ * @returns {Object} The defined-only copy.
+ * @throws {PrincipiaError} `BaseErrors.MissingData` if no properties are defined.
+ */
+export function checkDefined(object) {
+	const res = cloneDefined(object)
+
+	if (Object.keys(res).length === 0) throw BaseErrors.MissingData({ type: 'attributes' })
+
+	return res
+}

package/util/Crypto.js

@@ -0,0 +1,121 @@
+import {
+	createHash,
+	scrypt,
+	randomBytes,
+	timingSafeEqual,
+	generateKeyPairSync,
+	createPrivateKey,
+	createPublicKey,
+	sign,
+	verify,
+} from 'node:crypto'
+import { promisify } from 'node:util'
+
+import { now } from '@empyria/classification'
+
+const scryptAsync = promisify(scrypt)
+
+/**
+ * SHA3-256 hashes an arbitrary JSON-serializable value.
+ * @param {*} obj - Value to hash.
+ * @returns {string} Hex-encoded digest.
+ */
+export function hashify(obj) {
+	return createHash('sha3-256').update(JSON.stringify(obj), 'utf8').digest('hex')
+}
+
+/**
+ * Timestamps a value, using a trusted timestamping service if one is given.
+ * @param {*} toHash - Value to hash before timestamping (only used if `timestamper` is given).
+ * @param {{trustedTimestamp: (hash: string) => Promise<*>}} [timestamper] - Trusted timestamping
+ *   service; if given, its result is returned.
+ * @param {*} [defaultValue] - Fallback value when there's no `timestamper`; defaults to `now()`.
+ * @returns {Promise<*>} The trusted timestamp, or `defaultValue`/`now()`.
+ */
+export async function stampIt(toHash, timestamper, defaultValue) {
+	let dataHash = timestamper && hashify(toHash)
+	return timestamper ? await timestamper.trustedTimestamp(dataHash) : defaultValue || now()
+}
+
+/**
+ * Generates a raw (32-byte) Ed25519 key pair.
+ * @returns {{privKeyHex: string, pubKeyHex: string}} Hex-encoded private/public keys.
+ */
+export function generateKeys() {
+	const { publicKey, privateKey } = generateKeyPairSync('ed25519')
+
+	// Export as raw 32-byte keys
+	const pubKeyRaw = publicKey.export({ type: 'spki', format: 'der' }).subarray(-32)
+	const privKeyRaw = privateKey.export({ type: 'pkcs8', format: 'der' }).subarray(-32)
+
+	return {
+		privKeyHex: privKeyRaw.toString('hex'),
+		pubKeyHex: pubKeyRaw.toString('hex'),
+	}
+}
+
+/**
+ * Ed25519-signs a UTF-8 message with a raw hex-encoded private key (as produced by {@link generateKeys}).
+ * @param {string} messageText - Message to sign.
+ * @param {string} privateKeyHex - Raw 32-byte Ed25519 private key, hex-encoded.
+ * @returns {string} Hex-encoded signature.
+ */
+export function generateSignature(messageText, privateKeyHex) {
+	const message = Buffer.from(messageText, 'utf8')
+	const rawKey = Buffer.from(privateKeyHex, 'hex')
+	const prefix = Buffer.from('302e020100300506032b657004220420', 'hex')
+	const privateKey = createPrivateKey({
+		key: Buffer.concat([prefix, rawKey]),
+		format: 'der',
+		type: 'pkcs8',
+	})
+
+	const signature = sign(null, message, privateKey)
+	return signature.toString('hex')
+}
+
+/**
+ * Verifies an Ed25519 signature produced by {@link generateSignature}.
+ * @param {string} messageText - Original signed message.
+ * @param {string} signatureHex - Hex-encoded signature to verify.
+ * @param {string} publicKeyHex - Raw 32-byte Ed25519 public key, hex-encoded.
+ * @returns {boolean} True if the signature is valid for the message and public key.
+ */
+export function verifySignature(messageText, signatureHex, publicKeyHex) {
+	const message = Buffer.from(messageText, 'utf8')
+	const signature = Buffer.from(signatureHex, 'hex')
+	const rawKey = Buffer.from(publicKeyHex, 'hex')
+	const prefix = Buffer.from('302a300506032b6570032100', 'hex')
+	const publicKey = createPublicKey({
+		key: Buffer.concat([prefix, rawKey]),
+		format: 'der',
+		type: 'spki',
+	})
+
+	return verify(null, message, publicKey, signature)
+}
+
+/**
+ * Hashes a password with scrypt and a random salt.
+ * @param {string} password - Plain-text password.
+ * @returns {Promise<string>} `"<hex hash>.<hex salt>"`.
+ */
+export async function hashPassword(password) {
+	const salt = randomBytes(16).toString('hex')
+	const buf = await scryptAsync(password, salt, 64)
+	return `${buf.toString('hex')}.${salt}`
+}
+
+/**
+ * Verifies a password against a hash produced by {@link hashPassword}, using a
+ * constant-time comparison.
+ * @param {string} password - Plain-text password to check.
+ * @param {string} hash - `"<hex hash>.<hex salt>"`, as produced by {@link hashPassword}.
+ * @returns {Promise<boolean>} True if `password` matches the hash.
+ */
+export async function verifyPassword(password, hash) {
+	const [hashedPassword, salt] = hash.split('.')
+	const hashedPasswordBuf = Buffer.from(hashedPassword, 'hex')
+	const buf = await scryptAsync(password, salt, 64)
+	return timingSafeEqual(hashedPasswordBuf, buf)
+}