@nestjs-pipeline/job-context 0.2.0

package/README.md

@@ -0,0 +1,210 @@
+# @nestjs-pipeline/job-context
+
+[![npm version](https://img.shields.io/npm/v/@nestjs-pipeline/job-context.svg)](https://www.npmjs.com/package/@nestjs-pipeline/job-context)
+[![License](https://img.shields.io/npm/l/@nestjs-pipeline/job-context.svg)](https://www.npmjs.com/package/@nestjs-pipeline/job-context)
+
+The execution context of a request, carried into the queue jobs it enqueues: the tenant,
+the correlation id and the principal. A job then makes the decisions the request would
+have made. System-started work, such as a cron job, declares its context explicitly
+instead. Nothing falls back to a default tenant or an anonymous principal.
+
+It depends on no other pipeline package. It reads and restores the tenant and the
+correlation id through the sources it is given, usually `tenantSource` of
+[`@nestjs-pipeline/tenant`](https://github.com/aristoteliss/nestjs-pipeline/tree/master/packages/pipeline-tenant#readme)
+and `correlationSource` of
+[`@nestjs-pipeline/correlation`](https://github.com/aristoteliss/nestjs-pipeline/tree/master/packages/pipeline-correlation#readme),
+so pipelines a job dispatches get the same tenant and correlation id.
+
+## Installation
+
+```bash
+pnpm add @nestjs-pipeline/job-context @nestjs/common
+```
+
+Requires Node.js 22 or later.
+
+## Setup
+
+Implement `IJobPrincipal` over the application's authentication state, and register it
+with the tenants jobs may run in and the tenant and correlation id sources:
+
+`Capability`, `SessionRepository`, `SessionsModule`, `currentPrincipal`,
+`runAsPrincipal` and `SessionRevokedError` stand for the application's own authentication
+code.
+
+```typescript
+import { Injectable, Module } from '@nestjs/common';
+import { correlationSource } from '@nestjs-pipeline/correlation';
+import {
+  type IJobPrincipal,
+  JobContextModule,
+  type PrincipalReference,
+} from '@nestjs-pipeline/job-context';
+import { tenantSource } from '@nestjs-pipeline/tenant';
+
+@Injectable()
+export class SessionJobPrincipal implements IJobPrincipal<Capability> {
+  constructor(private readonly sessions: SessionRepository) {}
+
+  capture(): PrincipalReference | undefined {
+    const principal = currentPrincipal();
+    return principal && { id: principal.id, type: principal.type, sessionId: principal.sid };
+  }
+
+  async restore<T>(
+    principal: PrincipalReference,
+    work: () => Promise<T>,
+    grants?: readonly Capability[],
+  ): Promise<T> {
+    if (grants) return runAsPrincipal({ ...principal, grants }, work);
+    const session = await this.sessions.findActive(principal.sessionId, principal.id);
+    if (!session) throw new SessionRevokedError();
+    return runAsPrincipal(principal, work);
+  }
+}
+
+@Module({
+  imports: [
+    JobContextModule.forRoot({
+      principal: SessionJobPrincipal,
+      tenants: ['tenant_a', 'tenant_b'],
+      sources: { tenantId: tenantSource, correlationId: correlationSource },
+      imports: [SessionsModule],
+    }),
+  ],
+})
+export class JobsModule {}
+```
+
+`capture` reads the current principal when a job is enqueued; only its `id`, `type` and
+`sessionId` are kept. `restore` runs when the job does, inside the job's tenant and
+correlation id: it must re-check the principal against current state, bind it the way a
+request would, and throw to refuse the job.
+
+## Usage
+
+Stamp the payload when enqueuing, from inside the request or handler, so the tenant,
+correlation id and principal are current:
+
+```typescript
+import { InjectQueue } from '@nestjs/bullmq';
+import { EventsHandler, type IEventHandler } from '@nestjs/cqrs';
+import { withJobContext, type WithJobContext } from '@nestjs-pipeline/job-context';
+import type { Queue } from 'bullmq';
+
+type WelcomeEmail = { userId: string; email: string };
+
+@EventsHandler(UserRegisteredEvent)
+export class EnqueueWelcomeEmail implements IEventHandler<UserRegisteredEvent> {
+  constructor(
+    @InjectQueue(WELCOME_EMAIL_QUEUE)
+    private readonly queue: Queue<WithJobContext<WelcomeEmail>>,
+  ) {}
+
+  async handle({ userId, email }: UserRegisteredEvent) {
+    await this.queue.add('send', withJobContext({ userId, email }));
+  }
+}
+```
+
+Restore it in the processor. Place the decorator under the transport decorator:
+
+```typescript
+import { Processor, WorkerHost } from '@nestjs/bullmq';
+import { CommandBus } from '@nestjs/cqrs';
+import { InJobContext, type WithJobContext } from '@nestjs-pipeline/job-context';
+import type { Job } from 'bullmq';
+
+@Processor(WELCOME_EMAIL_QUEUE)
+export class SendWelcomeEmailProcessor extends WorkerHost {
+  constructor(private readonly commandBus: CommandBus) {
+    super();
+  }
+
+  @InJobContext()
+  async process(job: Job<WithJobContext<WelcomeEmail>>) {
+    await this.commandBus.execute(new SendWelcomeEmailCommand(job.data));
+  }
+}
+```
+
+`@InJobContext()` reads `data.jobContext` from the first argument (a BullMQ `Job`); pass
+`{ path: 'jobContext' }` for a transport that hands the payload itself.
+
+```typescript
+@EventPattern('user.registered')
+@InJobContext({ path: 'jobContext' })
+async onRegistered(@Payload() data: WithJobContext<WelcomeEmail>) {
+  await this.commandBus.execute(new SendWelcomeEmailCommand(data));
+}
+```
+
+A refused job throws `MissingJobContextError` or `InvalidJobContextError` before the method
+runs; let the queue mark it failed rather than retrying it, since the payload will not change.
+
+Declare system-started work:
+
+```typescript
+import { AsSystem } from '@nestjs-pipeline/job-context';
+import { Cron } from '@nestjs/schedule';
+
+@Cron('0 3 * * *')
+@AsSystem({
+  principal: { id: 'session-cleanup', type: 'service' },
+  grants: [{ action: 'delete', subject: 'Auth' }],
+})
+async purgeSessions() {
+  await this.commandBus.execute(new PurgeExpiredSessionsCommand());
+}
+```
+
+## Behavior
+
+- **`withJobContext(data)`** returns a copy of `data` with `jobContext`: the tenant and
+  the correlation id of the configured sources (a new one from the correlation source's
+  `create()` when none is active), and the captured principal. It throws `MissingJobContextError` without a
+  running `JobContextModule`, a tenant, or a principal, and `TypeError` for a payload that
+  is not a plain object.
+- **`@InJobContext()`** validates the payload's context before the method runs. It refuses
+  a missing context (`MissingJobContextError`), and a malformed one, an unconfigured
+  tenant, a correlation id the correlation source's `accepts` refuses
+  (`correlationSource` accepts at most 128 characters of `A-Z a-z 0-9 . _ ~ : / + = @ -`), or a
+  principal carrying any field beyond `id`, `type` and `sessionId`, such as grants
+  (`InvalidJobContextError`). It then runs the method inside the tenant, the correlation
+  id, and `restore(principal, work)`. The method becomes async.
+- **`@AsSystem({ principal, grants })`** runs the method once per configured tenant, one
+  after another, each with a new correlation id from `create()` and `restore(principal, work, grants)`. A
+  failing tenant does not stop the others; the method then rejects with an
+  `AggregateError` of the failures. Return values are discarded.
+- **`JobContextModule.forRoot`** registers the principal port, tenants and sources when the module
+  is instantiated and removes them at application shutdown. The decorators wrap methods
+  outside dependency injection, so they use the registration of the running application;
+  without one they fail closed. Register it once per application.
+
+## Security
+
+A payload is data: anyone who can write to the queue can write it. The package therefore
+carries an identity reference only, never grants, and `restore` decides what that
+identity may do now. Re-check a user's session and account in `restore`, so a revoked
+session or a deleted user refuses the job. Grants come only from `@AsSystem`, in code.
+The tenant must be one of the configured tenants.
+
+## API
+
+| Export | Kind | Description |
+| --- | --- | --- |
+| `withJobContext(data)` | function | Copies `data` and adds the current `jobContext` |
+| `InJobContext(options?)` | decorator | Runs a job method in its payload's context; `path` defaults to `'data.jobContext'` |
+| `AsSystem(options)` | decorator | Runs system work once per tenant as the declared principal and grants |
+| `JobContextModule.forRoot(options)` | module | Registers `principal` (a class), `tenants`, `sources` and optional `imports` |
+| `ContextSource`, `CorrelationSource`, `JobContextSources` | type | `{ current, run }`; the correlation source adds `create()` and `accepts(id)`; and the `{ tenantId, correlationId }` pair `sources` takes |
+| `IJobPrincipal<TGrant>` | interface | Application port: `capture()` and `restore(principal, work, grants?)` |
+| `PrincipalReference` | type | `{ id, type, sessionId? }` |
+| `JobContext`, `WithJobContext<T>` | type | The carried context, and a payload with it |
+| `MissingJobContextError`, `InvalidJobContextError` | error | Framework-neutral; map them in the consumer if needed |
+
+## License
+
+Dual-licensed under **AGPL-3.0-or-later** or a **Commercial License**. See
+[`LICENSE`](https://github.com/aristoteliss/nestjs-pipeline/blob/master/LICENSE) and [`COMMERCIAL_LICENSE.txt`](https://github.com/aristoteliss/nestjs-pipeline/blob/master/COMMERCIAL_LICENSE.txt)
+at the repository root.

package/dist/constants/job-context.constants.d.ts

@@ -0,0 +1,7 @@
+/** Injection token of the application's `IJobPrincipal`. */
+export declare const JOB_PRINCIPAL: unique symbol;
+/** Injection token of the configured tenant list. */
+export declare const JOB_TENANTS: unique symbol;
+/** Injection token of the tenant and correlation id sources. */
+export declare const JOB_SOURCES: unique symbol;
+//# sourceMappingURL=job-context.constants.d.ts.map

package/dist/constants/job-context.constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-context.constants.d.ts","sourceRoot":"","sources":["../../src/constants/job-context.constants.ts"],"names":[],"mappings":"AAEA,4DAA4D;AAC5D,eAAO,MAAM,aAAa,eAA0B,CAAC;AAErD,qDAAqD;AACrD,eAAO,MAAM,WAAW,eAAwB,CAAC;AAEjD,gEAAgE;AAChE,eAAO,MAAM,WAAW,eAAwB,CAAC"}

package/dist/constants/job-context.constants.js

@@ -0,0 +1,11 @@
+"use strict";
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JOB_SOURCES = exports.JOB_TENANTS = exports.JOB_PRINCIPAL = void 0;
+/** Injection token of the application's `IJobPrincipal`. */
+exports.JOB_PRINCIPAL = Symbol('JOB_PRINCIPAL');
+/** Injection token of the configured tenant list. */
+exports.JOB_TENANTS = Symbol('JOB_TENANTS');
+/** Injection token of the tenant and correlation id sources. */
+exports.JOB_SOURCES = Symbol('JOB_SOURCES');
+//# sourceMappingURL=job-context.constants.js.map

package/dist/constants/job-context.constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"job-context.constants.js","sourceRoot":"","sources":["../../src/constants/job-context.constants.ts"],"names":[],"mappings":";AAAA,sEAAsE;;;AAEtE,4DAA4D;AAC/C,QAAA,aAAa,GAAG,MAAM,CAAC,eAAe,CAAC,CAAC;AAErD,qDAAqD;AACxC,QAAA,WAAW,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC;AAEjD,gEAAgE;AACnD,QAAA,WAAW,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC"}

package/dist/decorators/as-system.decorator.d.ts

@@ -0,0 +1,32 @@
+import type { PrincipalReference } from '../interfaces/principal-reference.interface';
+/** Options of {@link AsSystem}. */
+export interface AsSystemOptions<TGrant = unknown> {
+    /** The service principal the work acts as. */
+    principal: PrincipalReference;
+    /** The principal's complete authorization; nothing else grants it anything. */
+    grants: readonly TGrant[];
+}
+/**
+ * Runs system-started work, such as a cron job, once per configured tenant.
+ * Each run has its own tenant, a new correlation id, and the declared service
+ * principal and grants, bound through the registered `IJobPrincipal`. Grants
+ * come only from this declaration, never from data.
+ *
+ * Tenants run one after another. A failing tenant does not stop the others;
+ * the method then rejects with an `AggregateError` of the failures. Its return
+ * values are discarded. Place it under the scheduling decorator.
+ *
+ * @example
+ * ```ts
+ * @Cron('0 3 * * *')
+ * @AsSystem({
+ *   principal: { id: 'session-cleanup', type: 'service' },
+ *   grants: [{ action: 'delete', subject: 'Auth' }],
+ * })
+ * async purgeSessions() {
+ *   await this.commandBus.execute(new PurgeExpiredSessionsCommand());
+ * }
+ * ```
+ */
+export declare function AsSystem<TGrant>(options: AsSystemOptions<TGrant>): MethodDecorator;
+//# sourceMappingURL=as-system.decorator.d.ts.map

package/dist/decorators/as-system.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"as-system.decorator.d.ts","sourceRoot":"","sources":["../../src/decorators/as-system.decorator.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,6CAA6C,CAAC;AAEtF,mCAAmC;AACnC,MAAM,WAAW,eAAe,CAAC,MAAM,GAAG,OAAO;IAC/C,8CAA8C;IAC9C,SAAS,EAAE,kBAAkB,CAAC;IAC9B,+EAA+E;IAC/E,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAC7B,OAAO,EAAE,eAAe,CAAC,MAAM,CAAC,GAC/B,eAAe,CA2CjB"}

package/dist/decorators/as-system.decorator.js

@@ -0,0 +1,58 @@
+"use strict";
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AsSystem = AsSystem;
+const principal_reference_1 = require("../helpers/principal-reference");
+const registration_1 = require("../helpers/registration");
+/**
+ * Runs system-started work, such as a cron job, once per configured tenant.
+ * Each run has its own tenant, a new correlation id, and the declared service
+ * principal and grants, bound through the registered `IJobPrincipal`. Grants
+ * come only from this declaration, never from data.
+ *
+ * Tenants run one after another. A failing tenant does not stop the others;
+ * the method then rejects with an `AggregateError` of the failures. Its return
+ * values are discarded. Place it under the scheduling decorator.
+ *
+ * @example
+ * ```ts
+ * @Cron('0 3 * * *')
+ * @AsSystem({
+ *   principal: { id: 'session-cleanup', type: 'service' },
+ *   grants: [{ action: 'delete', subject: 'Auth' }],
+ * })
+ * async purgeSessions() {
+ *   await this.commandBus.execute(new PurgeExpiredSessionsCommand());
+ * }
+ * ```
+ */
+function AsSystem(options) {
+    const reference = (0, principal_reference_1.toReference)(options.principal);
+    const grants = [...options.grants];
+    return (_target, _propertyKey, descriptor) => {
+        const original = descriptor.value;
+        descriptor.value = async function (...args) {
+            const { principal, tenants, sources } = (0, registration_1.activeRegistration)();
+            const failures = [];
+            const failed = [];
+            for (const tenant of tenants) {
+                try {
+                    await sources.tenantId.run(tenant, () => sources.correlationId.run(sources.correlationId.create(), () => principal.restore(reference, async () => original.apply(this, args), grants)));
+                }
+                catch (error) {
+                    failures.push(error);
+                    failed.push(tenant);
+                }
+            }
+            if (failures.length > 0) {
+                throw new AggregateError(failures, `System work failed in tenants: ${failed.join(', ')}`);
+            }
+        };
+        Object.defineProperty(descriptor.value, 'name', {
+            value: original.name,
+            configurable: true,
+        });
+        return descriptor;
+    };
+}
+//# sourceMappingURL=as-system.decorator.js.map

package/dist/decorators/as-system.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"as-system.decorator.js","sourceRoot":"","sources":["../../src/decorators/as-system.decorator.ts"],"names":[],"mappings":";AAAA,sEAAsE;;AAoCtE,4BA6CC;AA/ED,wEAA6D;AAC7D,0DAA6D;AAW7D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,SAAgB,QAAQ,CACtB,OAAgC;IAEhC,MAAM,SAAS,GAAG,IAAA,iCAAW,EAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEnC,OAAO,CAAC,OAAO,EAAE,YAAY,EAAE,UAA8B,EAAE,EAAE;QAC/D,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAwC,CAAC;QAErE,UAAU,CAAC,KAAK,GAAG,KAAK,WAEtB,GAAG,IAAe;YAElB,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,IAAA,iCAAkB,GAAE,CAAC;YAC7D,MAAM,QAAQ,GAAc,EAAE,CAAC;YAC/B,MAAM,MAAM,GAAa,EAAE,CAAC;YAC5B,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;gBAC7B,IAAI,CAAC;oBACH,MAAM,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,CACtC,OAAO,CAAC,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,EAAE,EAAE,GAAG,EAAE,CAC7D,SAAS,CAAC,OAAO,CACf,SAAS,EACT,KAAK,IAAI,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,EACtC,MAAM,CACP,CACF,CACF,CAAC;gBACJ,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;oBACrB,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBACtB,CAAC;YACH,CAAC;YACD,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACxB,MAAM,IAAI,cAAc,CACtB,QAAQ,EACR,kCAAkC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACtD,CAAC;YACJ,CAAC;QACH,CAAC,CAAC;QACF,MAAM,CAAC,cAAc,CAAC,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE;YAC9C,KAAK,EAAE,QAAQ,CAAC,IAAI;YACpB,YAAY,EAAE,IAAI;SACnB,CAAC,CAAC;QACH,OAAO,UAAU,CAAC;IACpB,CAAC,CAAC;AACJ,CAAC"}

package/dist/decorators/in-job-context.decorator.d.ts

@@ -0,0 +1,32 @@
+/** Options of {@link InJobContext}. */
+export interface InJobContextOptions {
+    /**
+     * Dot path to the job context in the method's first argument.
+     *
+     * @default 'data.jobContext' (a BullMQ `Job`)
+     */
+    path?: string;
+}
+/**
+ * Runs a job-processing method inside the context `withJobContext` stamped on
+ * its payload: the tenant, the correlation id, and the principal the registered
+ * `IJobPrincipal` re-checks and binds. The method becomes async.
+ *
+ * It fails closed before the method runs: a payload without a context, with a
+ * malformed one, with an unconfigured tenant, or with a principal carrying
+ * anything beyond `id`, `type` and `sessionId` is refused, and so is a
+ * principal `restore` rejects. Place it under the transport decorator.
+ *
+ * @example
+ * ```ts
+ * @Processor(WELCOME_EMAIL_QUEUE)
+ * export class SendWelcomeEmailProcessor extends WorkerHost {
+ *   @InJobContext()
+ *   async process(job: Job<WithJobContext<WelcomeEmail>>) {
+ *     await this.commandBus.execute(new SendWelcomeEmailCommand(job.data));
+ *   }
+ * }
+ * ```
+ */
+export declare function InJobContext(options?: InJobContextOptions): MethodDecorator;
+//# sourceMappingURL=in-job-context.decorator.d.ts.map

package/dist/decorators/in-job-context.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-job-context.decorator.d.ts","sourceRoot":"","sources":["../../src/decorators/in-job-context.decorator.ts"],"names":[],"mappings":"AAKA,uCAAuC;AACvC,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAWD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAC1B,OAAO,GAAE,mBAAwB,GAChC,eAAe,CA2BjB"}

package/dist/decorators/in-job-context.decorator.js

@@ -0,0 +1,53 @@
+"use strict";
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InJobContext = InJobContext;
+const parse_job_context_1 = require("../helpers/parse-job-context");
+const registration_1 = require("../helpers/registration");
+function readPath(value, segments) {
+    let current = value;
+    for (const segment of segments) {
+        if (typeof current !== 'object' || current === null)
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+/**
+ * Runs a job-processing method inside the context `withJobContext` stamped on
+ * its payload: the tenant, the correlation id, and the principal the registered
+ * `IJobPrincipal` re-checks and binds. The method becomes async.
+ *
+ * It fails closed before the method runs: a payload without a context, with a
+ * malformed one, with an unconfigured tenant, or with a principal carrying
+ * anything beyond `id`, `type` and `sessionId` is refused, and so is a
+ * principal `restore` rejects. Place it under the transport decorator.
+ *
+ * @example
+ * ```ts
+ * @Processor(WELCOME_EMAIL_QUEUE)
+ * export class SendWelcomeEmailProcessor extends WorkerHost {
+ *   @InJobContext()
+ *   async process(job: Job<WithJobContext<WelcomeEmail>>) {
+ *     await this.commandBus.execute(new SendWelcomeEmailCommand(job.data));
+ *   }
+ * }
+ * ```
+ */
+function InJobContext(options = {}) {
+    const segments = (options.path ?? 'data.jobContext').split('.');
+    return (_target, _propertyKey, descriptor) => {
+        const original = descriptor.value;
+        descriptor.value = async function (...args) {
+            const { principal, tenants, sources } = (0, registration_1.activeRegistration)();
+            const context = (0, parse_job_context_1.parseJobContext)(readPath(args[0], segments), tenants, sources.correlationId.accepts);
+            return sources.tenantId.run(context.tenantId, () => sources.correlationId.run(context.correlationId, () => principal.restore(context.principal, async () => original.apply(this, args))));
+        };
+        Object.defineProperty(descriptor.value, 'name', {
+            value: original.name,
+            configurable: true,
+        });
+        return descriptor;
+    };
+}
+//# sourceMappingURL=in-job-context.decorator.js.map

package/dist/decorators/in-job-context.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-job-context.decorator.js","sourceRoot":"","sources":["../../src/decorators/in-job-context.decorator.ts"],"names":[],"mappings":";AAAA,sEAAsE;;AA6CtE,oCA6BC;AAxED,oEAA+D;AAC/D,0DAA6D;AAY7D,SAAS,QAAQ,CAAC,KAAc,EAAE,QAA2B;IAC3D,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI;YAAE,OAAO,SAAS,CAAC;QACtE,OAAO,GAAI,OAAmC,CAAC,OAAO,CAAC,CAAC;IAC1D,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAgB,YAAY,CAC1B,UAA+B,EAAE;IAEjC,MAAM,QAAQ,GAAG,CAAC,OAAO,CAAC,IAAI,IAAI,iBAAiB,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAEhE,OAAO,CAAC,OAAO,EAAE,YAAY,EAAE,UAA8B,EAAE,EAAE;QAC/D,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAwC,CAAC;QAErE,UAAU,CAAC,KAAK,GAAG,KAAK,WAA0B,GAAG,IAAe;YAClE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,IAAA,iCAAkB,GAAE,CAAC;YAC7D,MAAM,OAAO,GAAG,IAAA,mCAAe,EAC7B,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,EAC3B,OAAO,EACP,OAAO,CAAC,aAAa,CAAC,OAAO,CAC9B,CAAC;YACF,OAAO,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,EAAE,CACjD,OAAO,CAAC,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,EAAE,CACpD,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,EAAE,KAAK,IAAI,EAAE,CAC9C,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAC3B,CACF,CACF,CAAC;QACJ,CAAC,CAAC;QACF,MAAM,CAAC,cAAc,CAAC,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE;YAC9C,KAAK,EAAE,QAAQ,CAAC,IAAI;YACpB,YAAY,EAAE,IAAI;SACnB,CAAC,CAAC;QACH,OAAO,UAAU,CAAC;IACpB,CAAC,CAAC;AACJ,CAAC"}

package/dist/errors/invalid-job-context.error.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Raised when a job payload's context is malformed, names an unconfigured
+ * tenant, or carries fields a principal reference must not have, such as
+ * grants. A payload is data written by whoever can write to the queue.
+ *
+ * @example
+ * ```ts
+ * throw new InvalidJobContextError('tenantId is not a configured tenant');
+ * ```
+ */
+export declare class InvalidJobContextError extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+//# sourceMappingURL=invalid-job-context.error.d.ts.map

package/dist/errors/invalid-job-context.error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invalid-job-context.error.d.ts","sourceRoot":"","sources":["../../src/errors/invalid-job-context.error.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM;CAIpC"}

package/dist/errors/invalid-job-context.error.js

@@ -0,0 +1,24 @@
+"use strict";
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidJobContextError = void 0;
+/**
+ * Raised when a job payload's context is malformed, names an unconfigured
+ * tenant, or carries fields a principal reference must not have, such as
+ * grants. A payload is data written by whoever can write to the queue.
+ *
+ * @example
+ * ```ts
+ * throw new InvalidJobContextError('tenantId is not a configured tenant');
+ * ```
+ */
+class InvalidJobContextError extends Error {
+    reason;
+    constructor(reason) {
+        super(`Invalid job context: ${reason}.`);
+        this.reason = reason;
+        this.name = InvalidJobContextError.name;
+    }
+}
+exports.InvalidJobContextError = InvalidJobContextError;
+//# sourceMappingURL=invalid-job-context.error.js.map

package/dist/errors/invalid-job-context.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invalid-job-context.error.js","sourceRoot":"","sources":["../../src/errors/invalid-job-context.error.ts"],"names":[],"mappings":";AAAA,sEAAsE;;;AAEtE;;;;;;;;;GASG;AACH,MAAa,sBAAuB,SAAQ,KAAK;IAC1B;IAArB,YAAqB,MAAc;QACjC,KAAK,CAAC,wBAAwB,MAAM,GAAG,CAAC,CAAC;QADtB,WAAM,GAAN,MAAM,CAAQ;QAEjC,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC,IAAI,CAAC;IAC1C,CAAC;CACF;AALD,wDAKC"}

package/dist/errors/missing-job-context.error.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Raised when a job would run, or be enqueued, without part of its execution
+ * context. A job never falls back to a default tenant or an anonymous principal.
+ *
+ * @example
+ * ```ts
+ * throw new MissingJobContextError('principal');
+ * ```
+ */
+export declare class MissingJobContextError extends Error {
+    readonly missing: string;
+    constructor(missing: string);
+}
+//# sourceMappingURL=missing-job-context.error.d.ts.map

package/dist/errors/missing-job-context.error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"missing-job-context.error.d.ts","sourceRoot":"","sources":["../../src/errors/missing-job-context.error.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM;gBAAf,OAAO,EAAE,MAAM;CAMrC"}

package/dist/errors/missing-job-context.error.js

@@ -0,0 +1,23 @@
+"use strict";
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MissingJobContextError = void 0;
+/**
+ * Raised when a job would run, or be enqueued, without part of its execution
+ * context. A job never falls back to a default tenant or an anonymous principal.
+ *
+ * @example
+ * ```ts
+ * throw new MissingJobContextError('principal');
+ * ```
+ */
+class MissingJobContextError extends Error {
+    missing;
+    constructor(missing) {
+        super(`Missing job context: ${missing}. A job never runs without it and never falls back to a default.`);
+        this.missing = missing;
+        this.name = MissingJobContextError.name;
+    }
+}
+exports.MissingJobContextError = MissingJobContextError;
+//# sourceMappingURL=missing-job-context.error.js.map

package/dist/errors/missing-job-context.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"missing-job-context.error.js","sourceRoot":"","sources":["../../src/errors/missing-job-context.error.ts"],"names":[],"mappings":";AAAA,sEAAsE;;;AAEtE;;;;;;;;GAQG;AACH,MAAa,sBAAuB,SAAQ,KAAK;IAC1B;IAArB,YAAqB,OAAe;QAClC,KAAK,CACH,wBAAwB,OAAO,kEAAkE,CAClG,CAAC;QAHiB,YAAO,GAAP,OAAO,CAAQ;QAIlC,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC,IAAI,CAAC;IAC1C,CAAC;CACF;AAPD,wDAOC"}

package/dist/helpers/parse-job-context.d.ts

@@ -0,0 +1,20 @@
+import type { JobContext } from '../interfaces/job-context.interface';
+/**
+ * Validates a job payload's context before anything runs with it. Every field
+ * is checked, unknown fields are refused, the tenant must be configured, and
+ * the correlation id must be one `acceptsCorrelationId` accepts.
+ *
+ * @param value - The payload's `jobContext` value, as read from the queue.
+ * @param tenants - The configured tenants.
+ * @param acceptsCorrelationId - The correlation source's `accepts`.
+ * @returns A context holding only the validated fields.
+ * @throws {MissingJobContextError} When `value` is `undefined`.
+ * @throws {InvalidJobContextError} For any other value that is not a valid context.
+ *
+ * @example
+ * ```ts
+ * const context = parseJobContext(job.data.jobContext, ['tenant_a'], sources.correlationId.accepts);
+ * ```
+ */
+export declare function parseJobContext(value: unknown, tenants: readonly string[], acceptsCorrelationId: (id: string) => boolean): JobContext;
+//# sourceMappingURL=parse-job-context.d.ts.map

package/dist/helpers/parse-job-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-job-context.d.ts","sourceRoot":"","sources":["../../src/helpers/parse-job-context.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAC;AAyBtE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,oBAAoB,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,GAC5C,UAAU,CAmCZ"}

package/dist/helpers/parse-job-context.js

@@ -0,0 +1,71 @@
+"use strict";
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseJobContext = parseJobContext;
+const invalid_job_context_error_1 = require("../errors/invalid-job-context.error");
+const missing_job_context_error_1 = require("../errors/missing-job-context.error");
+const principal_reference_1 = require("./principal-reference");
+const CONTEXT_FIELDS = new Set(['tenantId', 'correlationId', 'principal']);
+const PRINCIPAL_FIELDS = new Set(['id', 'type', 'sessionId']);
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isText(value) {
+    return typeof value === 'string' && value.trim() !== '';
+}
+function assertFields(value, allowed, name) {
+    const extra = Object.keys(value).find((key) => !allowed.has(key));
+    if (extra !== undefined) {
+        throw new invalid_job_context_error_1.InvalidJobContextError(`${name} carries the field "${extra}"`);
+    }
+}
+/**
+ * Validates a job payload's context before anything runs with it. Every field
+ * is checked, unknown fields are refused, the tenant must be configured, and
+ * the correlation id must be one `acceptsCorrelationId` accepts.
+ *
+ * @param value - The payload's `jobContext` value, as read from the queue.
+ * @param tenants - The configured tenants.
+ * @param acceptsCorrelationId - The correlation source's `accepts`.
+ * @returns A context holding only the validated fields.
+ * @throws {MissingJobContextError} When `value` is `undefined`.
+ * @throws {InvalidJobContextError} For any other value that is not a valid context.
+ *
+ * @example
+ * ```ts
+ * const context = parseJobContext(job.data.jobContext, ['tenant_a'], sources.correlationId.accepts);
+ * ```
+ */
+function parseJobContext(value, tenants, acceptsCorrelationId) {
+    if (value === undefined) {
+        throw new missing_job_context_error_1.MissingJobContextError('the payload has no jobContext');
+    }
+    if (!isRecord(value)) {
+        throw new invalid_job_context_error_1.InvalidJobContextError('jobContext is not an object');
+    }
+    assertFields(value, CONTEXT_FIELDS, 'jobContext');
+    const { tenantId, correlationId, principal } = value;
+    if (typeof tenantId !== 'string' || !tenants.includes(tenantId)) {
+        throw new invalid_job_context_error_1.InvalidJobContextError('tenantId is not a configured tenant');
+    }
+    if (typeof correlationId !== 'string' ||
+        !acceptsCorrelationId(correlationId)) {
+        throw new invalid_job_context_error_1.InvalidJobContextError('correlationId is malformed');
+    }
+    if (!isRecord(principal)) {
+        throw new invalid_job_context_error_1.InvalidJobContextError('principal is not an object');
+    }
+    assertFields(principal, PRINCIPAL_FIELDS, 'principal');
+    const { id, type, sessionId } = principal;
+    if (!isText(id) ||
+        !isText(type) ||
+        (sessionId !== undefined && !isText(sessionId))) {
+        throw new invalid_job_context_error_1.InvalidJobContextError('principal is malformed');
+    }
+    return {
+        tenantId,
+        correlationId,
+        principal: (0, principal_reference_1.toReference)({ id, type, sessionId }),
+    };
+}
+//# sourceMappingURL=parse-job-context.js.map

package/dist/helpers/parse-job-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-job-context.js","sourceRoot":"","sources":["../../src/helpers/parse-job-context.ts"],"names":[],"mappings":";AAAA,sEAAsE;;AA8CtE,0CAuCC;AAnFD,mFAA6E;AAC7E,mFAA6E;AAE7E,+DAAoD;AAEpD,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,CAAC,UAAU,EAAE,eAAe,EAAE,WAAW,CAAC,CAAC,CAAC;AAC3E,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;AAE9D,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,SAAS,MAAM,CAAC,KAAc;IAC5B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC;AAC1D,CAAC;AAED,SAAS,YAAY,CACnB,KAA8B,EAC9B,OAA4B,EAC5B,IAAY;IAEZ,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IAClE,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,kDAAsB,CAAC,GAAG,IAAI,uBAAuB,KAAK,GAAG,CAAC,CAAC;IAC3E,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,eAAe,CAC7B,KAAc,EACd,OAA0B,EAC1B,oBAA6C;IAE7C,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,kDAAsB,CAAC,+BAA+B,CAAC,CAAC;IACpE,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,kDAAsB,CAAC,6BAA6B,CAAC,CAAC;IAClE,CAAC;IACD,YAAY,CAAC,KAAK,EAAE,cAAc,EAAE,YAAY,CAAC,CAAC;IAClD,MAAM,EAAE,QAAQ,EAAE,aAAa,EAAE,SAAS,EAAE,GAAG,KAAK,CAAC;IACrD,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QAChE,MAAM,IAAI,kDAAsB,CAAC,qCAAqC,CAAC,CAAC;IAC1E,CAAC;IACD,IACE,OAAO,aAAa,KAAK,QAAQ;QACjC,CAAC,oBAAoB,CAAC,aAAa,CAAC,EACpC,CAAC;QACD,MAAM,IAAI,kDAAsB,CAAC,4BAA4B,CAAC,CAAC;IACjE,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,kDAAsB,CAAC,4BAA4B,CAAC,CAAC;IACjE,CAAC;IACD,YAAY,CAAC,SAAS,EAAE,gBAAgB,EAAE,WAAW,CAAC,CAAC;IACvD,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,SAAS,CAAC;IAC1C,IACE,CAAC,MAAM,CAAC,EAAE,CAAC;QACX,CAAC,MAAM,CAAC,IAAI,CAAC;QACb,CAAC,SAAS,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,EAC/C,CAAC;QACD,MAAM,IAAI,kDAAsB,CAAC,wBAAwB,CAAC,CAAC;IAC7D,CAAC;IACD,OAAO;QACL,QAAQ;QACR,aAAa;QACb,SAAS,EAAE,IAAA,iCAAW,EAAC,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;KAChD,CAAC;AACJ,CAAC"}

package/dist/helpers/principal-reference.d.ts

@@ -0,0 +1,12 @@
+import type { PrincipalReference } from '../interfaces/principal-reference.interface';
+/**
+ * Copies only the identity fields of `principal`, so grants or session data an
+ * application object also holds never reach a payload or a restore call.
+ *
+ * @example
+ * ```ts
+ * toReference({ id: 'u-1', type: 'user', sid: 's-1', grants: [] }); // { id: 'u-1', type: 'user' }
+ * ```
+ */
+export declare function toReference(principal: PrincipalReference): PrincipalReference;
+//# sourceMappingURL=principal-reference.d.ts.map