@endora-commerce/mod-auth 0.0.0-stage → 0.100.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Endora sp. z o.o. and the Endora Commerce contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,50 @@
-# Temporary Holding Version
+<!-- Generated by `pnpm --filter backend run manifests:generate`. Delete this line to take the file over; a README without it is never regenerated. -->
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @endora-commerce/mod-auth
+
+Authentication primitives — session cookies, bearer-token resolution, and request actor binding.
+
+## What this is
+
+An **Endora Commerce module package**. Its module id is `auth` — the identity of record in the platform's registries, in its migrations and in its setting, permission and translation codes.
+
+A module is not imported by application code. The platform discovers the extension packages an instance has installed, reads the manifest on the root subpath and composes the module from it, so installing this package and starting the instance is the whole integration.
+
+## Entry points
+
+| Import | Contents |
+| --- | --- |
+| `@endora-commerce/mod-auth` | the module manifest — its id, version, dependencies, settings and activation |
+| `@endora-commerce/mod-auth/backend` | the composition root the platform calls, with the entities, services, routes and workers it registers |
+
+## Depends on
+
+Everything below is a **peer** dependency, so the application resolves exactly one copy of each — two copies of a host or of React are a runtime failure rather than a type error. An entry marked *optional* is needed only by the layers that use it.
+
+**Endora packages**
+
+- `@endora-commerce/contracts`
+- `@endora-commerce/platform`
+
+**Third-party**
+
+- `@mikro-orm/core` ^6
+- `@mikro-orm/postgresql` ^6
+- `fastify` ^5
+- `fastify-plugin` ^5
+- `ioredis` ^5
+
+## What the tarball carries
+
+- `dist/` — the compiled JavaScript and its type declarations
+- `docs/` — the package’s own pages in the Endora Commerce documentation site
+
+## Install
+
+```bash
+pnpm add @endora-commerce/mod-auth
+```
+
+## Licence
+
+MIT — the text is in `LICENSE`, beside this file.

package/dist/backend/entities/session.entity.d.ts

@@ -0,0 +1,31 @@
+import { OptionalProps } from '@mikro-orm/core';
+/**
+ * Persistent session row. Backed by Postgres; hot reads are cached in Redis by
+ * SessionService. See data-model.md § Domain 1 and R-11.
+ *
+ * `auth` is the permitted singular-exception module folder per Principle VI; this
+ * entity's table name remains `sessions` because class-to-table is still pluralised.
+ */
+export declare class Session {
+    [OptionalProps]?: 'id' | 'createdAt' | 'updatedAt';
+    id: string;
+    /** Opaque token shown to the client (cookie value). Never used for lookups directly —
+     *  we hash it before storing. The actual cookie sent to the client is `${id}.${tokenHash}`. */
+    tokenHash: string;
+    /** Null for admin-user sessions; set for customer-account sessions. */
+    customerAccountId?: string | null;
+    /** Null for customer sessions; set for admin-user sessions. */
+    adminUserId?: string | null;
+    /**
+     * When an admin-user is impersonating a customer, both `customerAccountId` (target)
+     * and `impersonatorAdminUserId` (the admin) are set — see R-12.
+     */
+    impersonatorAdminUserId?: string | null;
+    expiresAt: Date;
+    createdAt: Date;
+    updatedAt: Date;
+    lastSeenAt?: Date | null;
+    ipAddress?: string | null;
+    userAgent?: string | null;
+}
+//# sourceMappingURL=session.entity.d.ts.map

package/dist/backend/entities/session.entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.entity.d.ts","sourceRoot":"","sources":["../../../src/backend/entities/session.entity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,aAAa,EAAwB,MAAM,iBAAiB,CAAC;AAIrF;;;;;;GAMG;AACH,qBAEa,OAAO;IAClB,CAAC,aAAa,CAAC,CAAC,EAAE,IAAI,GAAG,WAAW,GAAG,WAAW,CAAC;IAInD,EAAE,EAAE,MAAM,CAAgB;IAE1B;mGAC+F;IAG/F,SAAS,EAAG,MAAM,CAAC;IAEnB,uEAAuE;IAGvE,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAElC,+DAA+D;IAG/D,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5B;;;OAGG;IAEH,uBAAuB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAIxC,SAAS,EAAG,IAAI,CAAC;IAGjB,SAAS,EAAE,IAAI,CAAc;IAG7B,SAAS,EAAE,IAAI,CAAc;IAG7B,UAAU,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAGzB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAG1B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B"}

package/dist/backend/entities/session.entity.js

@@ -0,0 +1,95 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { Entity, Index, OptionalProps, PrimaryKey, Property } from '@mikro-orm/core';
+import { GlobalEntity } from '@endora-commerce/platform/tenancy';
+import { randomUUID } from 'crypto';
+/**
+ * Persistent session row. Backed by Postgres; hot reads are cached in Redis by
+ * SessionService. See data-model.md § Domain 1 and R-11.
+ *
+ * `auth` is the permitted singular-exception module folder per Principle VI; this
+ * entity's table name remains `sessions` because class-to-table is still pluralised.
+ */
+let Session = class Session {
+    [OptionalProps];
+    id = randomUUID();
+    /** Opaque token shown to the client (cookie value). Never used for lookups directly —
+     *  we hash it before storing. The actual cookie sent to the client is `${id}.${tokenHash}`. */
+    tokenHash;
+    /** Null for admin-user sessions; set for customer-account sessions. */
+    customerAccountId;
+    /** Null for customer sessions; set for admin-user sessions. */
+    adminUserId;
+    /**
+     * When an admin-user is impersonating a customer, both `customerAccountId` (target)
+     * and `impersonatorAdminUserId` (the admin) are set — see R-12.
+     */
+    impersonatorAdminUserId;
+    expiresAt;
+    createdAt = new Date();
+    updatedAt = new Date();
+    lastSeenAt;
+    ipAddress;
+    userAgent;
+};
+__decorate([
+    PrimaryKey({ type: 'uuid' }),
+    __metadata("design:type", String)
+], Session.prototype, "id", void 0);
+__decorate([
+    Property({ type: 'string', length: 128 }),
+    Index(),
+    __metadata("design:type", String)
+], Session.prototype, "tokenHash", void 0);
+__decorate([
+    Property({ type: 'uuid', nullable: true }),
+    Index(),
+    __metadata("design:type", Object)
+], Session.prototype, "customerAccountId", void 0);
+__decorate([
+    Property({ type: 'uuid', nullable: true }),
+    Index(),
+    __metadata("design:type", Object)
+], Session.prototype, "adminUserId", void 0);
+__decorate([
+    Property({ type: 'uuid', nullable: true }),
+    __metadata("design:type", Object)
+], Session.prototype, "impersonatorAdminUserId", void 0);
+__decorate([
+    Property({ type: 'datetime' }),
+    Index(),
+    __metadata("design:type", Date)
+], Session.prototype, "expiresAt", void 0);
+__decorate([
+    Property({ type: 'datetime', onCreate: () => new Date() }),
+    __metadata("design:type", Date)
+], Session.prototype, "createdAt", void 0);
+__decorate([
+    Property({ type: 'datetime', onUpdate: () => new Date() }),
+    __metadata("design:type", Date)
+], Session.prototype, "updatedAt", void 0);
+__decorate([
+    Property({ type: 'datetime', nullable: true }),
+    __metadata("design:type", Object)
+], Session.prototype, "lastSeenAt", void 0);
+__decorate([
+    Property({ type: 'string', length: 45, nullable: true }),
+    __metadata("design:type", Object)
+], Session.prototype, "ipAddress", void 0);
+__decorate([
+    Property({ type: 'string', length: 255, nullable: true }),
+    __metadata("design:type", Object)
+], Session.prototype, "userAgent", void 0);
+Session = __decorate([
+    GlobalEntity(),
+    Entity({ tableName: 'sessions' })
+], Session);
+export { Session };
+//# sourceMappingURL=session.entity.js.map

package/dist/backend/entities/session.entity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.entity.js","sourceRoot":"","sources":["../../../src/backend/entities/session.entity.ts"],"names":[],"mappings":";;;;;;;;;AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AACrF,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AACjE,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAEpC;;;;;;GAMG;AAGI,IAAM,OAAO,GAAb,MAAM,OAAO;IAClB,CAAC,aAAa,CAAC,CAAoC;IAInD,EAAE,GAAW,UAAU,EAAE,CAAC;IAE1B;mGAC+F;IAG/F,SAAS,CAAU;IAEnB,uEAAuE;IAGvE,iBAAiB,CAAiB;IAElC,+DAA+D;IAG/D,WAAW,CAAiB;IAE5B;;;OAGG;IAEH,uBAAuB,CAAiB;IAIxC,SAAS,CAAQ;IAGjB,SAAS,GAAS,IAAI,IAAI,EAAE,CAAC;IAG7B,SAAS,GAAS,IAAI,IAAI,EAAE,CAAC;IAG7B,UAAU,CAAe;IAGzB,SAAS,CAAiB;IAG1B,SAAS,CAAiB;CAC3B,CAAA;AA3CC;IADC,UAAU,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;;mCACH;AAM1B;IAFC,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;IACzC,KAAK,EAAE;;0CACW;AAKnB;IAFC,QAAQ,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAC1C,KAAK,EAAE;;kDAC0B;AAKlC;IAFC,QAAQ,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IAC1C,KAAK,EAAE;;4CACoB;AAO5B;IADC,QAAQ,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;;wDACH;AAIxC;IAFC,QAAQ,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;IAC9B,KAAK,EAAE;8BACI,IAAI;0CAAC;AAGjB;IADC,QAAQ,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC;8BAChD,IAAI;0CAAc;AAG7B;IADC,QAAQ,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC;8BAChD,IAAI;0CAAc;AAG7B;IADC,QAAQ,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;;2CACtB;AAGzB;IADC,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;;0CAC/B;AAG1B;IADC,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;;0CAChC;AA/Cf,OAAO;IAFnB,YAAY,EAAE;IACd,MAAM,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC;GACrB,OAAO,CAgDnB"}

package/dist/backend/index.d.ts

@@ -0,0 +1,120 @@
+import type { EntityManager } from '@mikro-orm/postgresql';
+import type { Redis } from 'ioredis';
+import type { ModuleContext } from '@endora-commerce/platform/kernel';
+import type { AdminPermissionChecker } from '@endora-commerce/platform/kernel';
+import { Session } from './entities/session.entity.js';
+import { SessionService } from './services/session-service.js';
+/**
+ * `auth` — the module every other module's guards read (feature 072, T078).
+ *
+ * Three things about this conversion are not shared with the modules that
+ * follow it, and each is a property of what `auth` is rather than of how it was
+ * written.
+ *
+ *  1. **Its plugin goes through `ctx.rootPlugin`, not `ctx.routes`.** It
+ *     contributes no routes; it decorates `request.actor`, which every module's
+ *     guards read. Both routes seams encapsulate, and a decoration applied
+ *     inside a Fastify child context is invisible to that context's siblings —
+ *     so registering it through either would leave every module but this one
+ *     with no actor.
+ *  2. **Its ports are the only ones a disabled `auth` could withdraw, and it
+ *     cannot be disabled.** `requireAdmin` gates 205 call sites across 60
+ *     modules; a platform whose admin guard is absent has no admin surface to
+ *     speak of, so the manifest declares the module non-deactivatable and the
+ *     orchestrator refuses to switch it off. The port gate is still registered
+ *     rather than skipped: the check that can never fire costs one predicate,
+ *     and an exception carved into the port machinery would cost a reader's
+ *     confidence in every other gate.
+ *  3. **It consumes `permissionService`, which `admin_roles` owns.** The
+ *     manifest declares that dependency (D-32); it is the edge that made `auth`
+ *     the first module to need `check:port-dependencies` to pass.
+ */
+/** What `auth` resolves: its own registrations, plus what it needs from elsewhere. */
+export interface AuthCradle {
+    readonly emFactory: () => EntityManager;
+    readonly redis: Redis;
+    /** `admin_roles`' permission checker, narrowed to what the guard uses. */
+    readonly permissionService: AdminPermissionChecker;
+    readonly sessionService: SessionService;
+    /**
+     * `api_keys`' bearer-token resolver. Registered by the composition root
+     * **after** this module composes: `api_keys` provides the port, and the
+     * single-pass composition orders it by the manifest graph rather than by
+     * this file. It is read per request, so the ordering is invisible here.
+     */
+    readonly apiKeyResolver: ((token: string) => Promise<{
+        apiKeyId: string;
+        scopes: string[];
+        organizationId?: string | null;
+        salesChannelId?: string | null;
+        customerAccountId?: string | null;
+    } | null>) | undefined;
+    /** Resolves a customer account to its organisation. Same late-binding story. */
+    readonly customerOrgResolver: ((customerAccountId: string) => Promise<string | null>) | undefined;
+}
+export declare function registerModule(ctx: ModuleContext): void;
+/**
+ * The module's persisted entity classes, on the `./backend` subpath, as one
+ * array and **no named class export** (D-168).
+ *
+ * This is the shape the platform reads when the package is *installed*: the
+ * boot-time loader (`src/packages/package-runtime.ts`, `exported['entities']`)
+ * and the static declaration reader (`scripts/lib/package-declarations.ts`),
+ * which is the third source of `check:module-boundary`'s `table→owner` map and
+ * the package pass of `check-entity-tenant-classification`. A missing array is
+ * answered with `[]` — zero entities registered, no error anywhere.
+ */
+export declare const entities: (typeof Session)[];
+/**
+ * The module's own implementation classes and guard factories, on the
+ * `./backend` subpath.
+ *
+ * They are published for the reason `pim_ergonode` publishes
+ * `ErgonodeRequestError`: a consumer that needs the **class** must get the one
+ * the platform composed. `SessionService` reaches `Session` and
+ * `AuthSessionReadService` reaches it too, so a second copy of either is a
+ * second `Session` — a class the ORM never discovered, and `em.find` answers a
+ * `MetadataError` rather than rows (D-160.6.1). Publishing them is what lets a
+ * consumer name one copy instead of resolving a filesystem path into this
+ * package's source.
+ *
+ * No module reaches any of these; the consumers today are `backend/test/`,
+ * which is why they are not on a `./ports` subpath — that one is contract
+ * surface (D-171) and these are implementations.
+ */
+/**
+ * What `request.actor` **is** — and it is no longer this package's to say
+ * (`specs/110-instance-repository/` T118b).
+ *
+ * `plugin.ts` used to declare the four actor kinds and a
+ * `declare module 'fastify'` block adding `actor` and `adminActor` to
+ * `FastifyRequest`, and this barrel re-exported the five type names.
+ * `specs/117-instance-bring-up/` FR-030 published them for a real reason: an
+ * ambient augmentation reaches a consumer's program only if the file declaring
+ * it is *in* that program, and the production composition root was getting it
+ * incidentally through a **value** import of `promoteAdminActor`. Retiring that
+ * import took the augmentation with it and thirty reads of `request.actor`
+ * stopped compiling.
+ *
+ * The block said relocating the augmentation *"would take `Session` with it"*.
+ * That premise was false and is what T118b measured: across `packages/`,
+ * `backend/`, `admin/` and `storefront/`, `actor.session` was read in **zero**
+ * files outside this package. So the vocabulary is
+ * `@endora-commerce/contracts`' {@link Actor} — session-free, importing neither
+ * Fastify nor the ORM — and the augmentation is the platform's, on
+ * `@endora-commerce/platform/http`. A consumer names one of those two; neither
+ * is a boundary reach, and no consumer needs a type-only import of a module any
+ * more.
+ *
+ * The five names are **not** re-exported from here. A re-export of a
+ * `@endora-commerce/contracts` type on this package's `./backend` barrel is
+ * what `module-package-entity-surface.test.ts` refuses under D-168: it cannot
+ * follow the specifier, so whether a named entity class comes through it is
+ * unknown rather than false. That is the same rule that stopped this file
+ * re-exporting the two cookie names when the package landed.
+ */
+export { SessionService } from './services/session-service.js';
+export { AuthSessionReadService, createAuthSessionPort } from './services/session-port.js';
+export { createRequireAdmin, createRequireAdminAny } from './require-admin.js';
+export { createRequireCustomer } from './require-customer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/backend/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/backend/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAEtE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAK/E,OAAO,EAAE,OAAO,EAAE,MAAM,8BAA8B,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,sFAAsF;AACtF,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,aAAa,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,0EAA0E;IAC1E,QAAQ,CAAC,iBAAiB,EAAE,sBAAsB,CAAC;IACnD,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,EACnB,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;QAC1B,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,EAAE,CAAC;QACjB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC/B,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC/B,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KACnC,GAAG,IAAI,CAAC,CAAC,GACV,SAAS,CAAC;IACd,gFAAgF;IAChF,QAAQ,CAAC,mBAAmB,EAAE,CAAC,CAAC,iBAAiB,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC,GAAG,SAAS,CAAC;CACnG;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,CA0HvD;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,QAAQ,oBAAY,CAAC;AA+BlC;;;;;;;;;;;;;;;;GAgBG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAC3F,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC/E,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/backend/index.js

@@ -0,0 +1,194 @@
+import { effectiveState } from '@endora-commerce/platform/kernel';
+import { authPlugin, promoteAdminActor } from './plugin.js';
+import { createRequireAdmin, createRequireAdminAny } from './require-admin.js';
+import { createRequireCustomer } from './require-customer.js';
+import { AuthSessionReadService, createAuthSessionPort } from './services/session-port.js';
+import { Session } from './entities/session.entity.js';
+import { SessionService } from './services/session-service.js';
+export function registerModule(ctx) {
+    ctx.di.register({
+        sessionService: ctx
+            .asFunction(({ emFactory, redis }) => new SessionService(emFactory, redis))
+            .singleton(),
+    });
+    // `requireAdmin` is the platform's single admin guard and the most-resolved
+    // name in the tree. It is a port because it is resolved by 60 other modules;
+    // `requireAdminAny` is the same guard with an any-of-these-codes predicate,
+    // and lives here for the same reason (`promoteAdminActor` plus a permission
+    // check are both this module's business).
+    //
+    // Both guards read `permissionService` **per check**, not at construction,
+    // and that is a correctness requirement rather than a style choice.
+    // `permissionService` is a port owned by `admin_roles`, so its resolution is
+    // gated on that module's effective state; a guard that captured the instance
+    // once would keep answering from it after the module went away, which is the
+    // permissive failure the gate exists to prevent. Awilix enforces the same
+    // thing from the other side — a singleton may not depend on the transient
+    // gate wrapper — so the two agree.
+    const permissionChecker = () => ({
+        hasPermission: (adminUserId, permission) => ctx.cradle().permissionService.hasPermission(adminUserId, permission),
+    });
+    // Feature 075 Phase P — the published session surface. `sessionService` keeps
+    // its registration for the four modules Phase C has not rewired yet; these two
+    // are what they rewire *to*, and the difference is that neither hands a
+    // `Session` entity across the boundary.
+    //
+    // `providePort` rather than `register`, even though `auth` is
+    // non-deactivatable and the gate can therefore never close: this module made
+    // that call already for `requireAdmin` (see the note above), and a second
+    // answer inside one module would be worse than either answer.
+    ctx.di.providePort('authSessionPort', ctx
+        .asFunction(({ sessionService }) => createAuthSessionPort(sessionService))
+        .singleton());
+    ctx.di.providePort('authSessionReadPort', ctx.asFunction(({ emFactory }) => new AuthSessionReadService(emFactory)).singleton());
+    ctx.di.providePort('requireAdmin', ctx.asFunction(() => createRequireAdmin({ permissionService: permissionChecker() })).singleton());
+    ctx.di.providePort('requireAdminAny', ctx
+        .asFunction(() => createRequireAdminAny({ permissionService: permissionChecker() }))
+        .singleton());
+    // The promotion the two admin guards above already perform, published under
+    // its own name (`specs/117-instance-bring-up/` FR-030). It is not a third
+    // guard: it decides nothing and refuses nobody, it moves `request.adminActor`
+    // into `request.actor` so that an admin route works on a request that also
+    // carries a customer session.
+    //
+    // It is a port for one consumer — the production composition root, which
+    // calls it inside the actor bridge it contributes to `mfa`. That root is
+    // moving into `@endora-commerce/platform` (`specs/110-instance-repository/`
+    // T118), and a platform file may not import a module (D-52, D-53), so the
+    // function's *exported* spelling stops being available to it while the
+    // container name survives the move. This is the drain condition the barrel
+    // below and `test/contract/kernel/harness-parity.test.ts` both named.
+    //
+    // `providePort` like its four neighbours, on the same reasoning: the gate can
+    // never close, because `auth` is non-deactivatable, and a second answer
+    // inside one module would be worse than either answer. No type argument, for
+    // symmetry with the two guards above — the shape is
+    // `AdminActorPromotion` in the platform's `kernel/ports/require-admin.ts`,
+    // deliberately off the `./kernel` barrel because no module resolves it.
+    ctx.di.providePort('promoteAdminActor', ctx.asFunction(() => promoteAdminActor).singleton());
+    // The customer-side twin, and the last guard either composition root still
+    // declared for itself (issue #43). Both roots had one — reading different
+    // request properties and disagreeing on every request shape — while 16 route
+    // surfaces took production's and 11 the harness's. It reads nothing but the
+    // actor, so unlike the two above it closes over no collaborator.
+    ctx.di.providePort('requireCustomer', ctx.asFunction(() => createRequireCustomer()).singleton());
+    ctx.rootPlugin('decorates request.actor and request.adminActor, which every module’s route ' +
+        'guards read — a decoration applied inside an encapsulated context would ' +
+        'reach none of them', async (app) => {
+        const cradle = ctx.cradle();
+        await app.register(authPlugin, {
+            sessionService: cradle.sessionService,
+            // Read per request, so a resolver the root registers after this module
+            // composed is still found. Passing the cradle read rather than the
+            // value is what makes the late binding work without a mutable holder.
+            //
+            // The presence probe is D-44's `degrades-without` guard, and the `?.`
+            // beside it does **not** replace it: optional chaining defends against
+            // "nobody registered this name", while `apiKeyResolver` is a gated port
+            // and a closed gate throws. Without the probe an operator switching
+            // `api_keys` off would turn every API-key request into a 503 from the
+            // request hook instead of the declared degradation, which is that such
+            // a request is simply not authenticated — the same answer a request
+            // presenting no key at all gets.
+            apiKeyResolver: async (token) => {
+                if (!effectiveState.isPresent('api_keys'))
+                    return null;
+                return (await cradle.apiKeyResolver?.(token)) ?? null;
+            },
+            customerOrgResolver: async (customerAccountId) => (await cradle.customerOrgResolver?.(customerAccountId)) ?? null,
+        });
+    });
+}
+/**
+ * The module's persisted entity classes, on the `./backend` subpath, as one
+ * array and **no named class export** (D-168).
+ *
+ * This is the shape the platform reads when the package is *installed*: the
+ * boot-time loader (`src/packages/package-runtime.ts`, `exported['entities']`)
+ * and the static declaration reader (`scripts/lib/package-declarations.ts`),
+ * which is the third source of `check:module-boundary`'s `table→owner` map and
+ * the package pass of `check-entity-tenant-classification`. A missing array is
+ * answered with `[]` — zero entities registered, no error anywhere.
+ */
+export const entities = [Session];
+/*
+ * **Actor promotion is no longer on this subpath**, and the deletion is the
+ * point rather than a tidy-up (`specs/117-instance-bring-up/` FR-030).
+ *
+ * `promoteAdminActor` was exported here for exactly one consumer, the
+ * production composition root, which calls it inside the actor bridge it
+ * contributes to `mfa`. The export said in its own words that it was published
+ * *"rather than relocated"* — correctly, because `auth` reads the function
+ * itself from `require-admin.ts` and promotion is about `request.actor` and
+ * `request.adminActor`, two decorations this module owns; `absolutizePublicUrl`
+ * could move to the platform (T040b, criterion 8) precisely because it had no
+ * consumer inside `email` and this one does. That reasoning is unchanged.
+ *
+ * What changed is the consumer. `specs/110-instance-repository/` T118 moves
+ * that root into `@endora-commerce/platform`, where importing a module is
+ * D-52/D-53's refusal — so the root's spelling had to stop being an import, and
+ * a value import does not retire by moving a type. It resolves the container
+ * name `promoteAdminActor` instead, which is the **further step** the old block
+ * here recorded as open and which `test/contract/kernel/harness-parity.test.ts`
+ * named as its drain condition: *"actor promotion published as a port, resolved
+ * from the container"*.
+ *
+ * The export is removed rather than left beside the registration, because two
+ * spellings of one seam is how a root comes to take the one that does not
+ * survive the move — and this file is where a future author would look for
+ * permission. The registration is above, in `registerModule`; the shape is
+ * `AdminActorPromotion` in the platform's `kernel/ports/require-admin.ts`.
+ */
+/**
+ * The module's own implementation classes and guard factories, on the
+ * `./backend` subpath.
+ *
+ * They are published for the reason `pim_ergonode` publishes
+ * `ErgonodeRequestError`: a consumer that needs the **class** must get the one
+ * the platform composed. `SessionService` reaches `Session` and
+ * `AuthSessionReadService` reaches it too, so a second copy of either is a
+ * second `Session` — a class the ORM never discovered, and `em.find` answers a
+ * `MetadataError` rather than rows (D-160.6.1). Publishing them is what lets a
+ * consumer name one copy instead of resolving a filesystem path into this
+ * package's source.
+ *
+ * No module reaches any of these; the consumers today are `backend/test/`,
+ * which is why they are not on a `./ports` subpath — that one is contract
+ * surface (D-171) and these are implementations.
+ */
+/**
+ * What `request.actor` **is** — and it is no longer this package's to say
+ * (`specs/110-instance-repository/` T118b).
+ *
+ * `plugin.ts` used to declare the four actor kinds and a
+ * `declare module 'fastify'` block adding `actor` and `adminActor` to
+ * `FastifyRequest`, and this barrel re-exported the five type names.
+ * `specs/117-instance-bring-up/` FR-030 published them for a real reason: an
+ * ambient augmentation reaches a consumer's program only if the file declaring
+ * it is *in* that program, and the production composition root was getting it
+ * incidentally through a **value** import of `promoteAdminActor`. Retiring that
+ * import took the augmentation with it and thirty reads of `request.actor`
+ * stopped compiling.
+ *
+ * The block said relocating the augmentation *"would take `Session` with it"*.
+ * That premise was false and is what T118b measured: across `packages/`,
+ * `backend/`, `admin/` and `storefront/`, `actor.session` was read in **zero**
+ * files outside this package. So the vocabulary is
+ * `@endora-commerce/contracts`' {@link Actor} — session-free, importing neither
+ * Fastify nor the ORM — and the augmentation is the platform's, on
+ * `@endora-commerce/platform/http`. A consumer names one of those two; neither
+ * is a boundary reach, and no consumer needs a type-only import of a module any
+ * more.
+ *
+ * The five names are **not** re-exported from here. A re-export of a
+ * `@endora-commerce/contracts` type on this package's `./backend` barrel is
+ * what `module-package-entity-surface.test.ts` refuses under D-168: it cannot
+ * follow the specifier, so whether a named entity class comes through it is
+ * unknown rather than false. That is the same rule that stopped this file
+ * re-exporting the two cookie names when the package landed.
+ */
+export { SessionService } from './services/session-service.js';
+export { AuthSessionReadService, createAuthSessionPort } from './services/session-port.js';
+export { createRequireAdmin, createRequireAdminAny } from './require-admin.js';
+export { createRequireCustomer } from './require-customer.js';
+//# sourceMappingURL=index.js.map

package/dist/backend/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/backend/index.ts"],"names":[],"mappings":"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"}

package/dist/backend/plugin.d.ts

@@ -0,0 +1,41 @@
+import type { FastifyInstance, FastifyRequest } from 'fastify';
+import '@endora-commerce/platform/http';
+import type { SessionService } from './services/session-service.js';
+/**
+ * Authentication plugin. Resolves the caller's identity into one of four forms and
+ * exposes pre-handler factories that gate routes.
+ *
+ * See research.md R-11, R-12 and contracts/README.md § Authentication.
+ */
+export interface AuthPluginOptions {
+    sessionService: SessionService;
+    /** Resolves an API key bearer token to an ApiKey actor. Installed by the api_keys module. */
+    apiKeyResolver?: (token: string) => Promise<{
+        apiKeyId: string;
+        scopes: string[];
+        organizationId?: string | null;
+        salesChannelId?: string | null;
+        customerAccountId?: string | null;
+    } | null>;
+    /**
+     * Resolves a customerAccountId to the customer's `organizationId`. Used to
+     * stamp `actor.organizationId` for customer + impersonation sessions so
+     * route handlers don't have to re-fetch the CustomerAccount per request.
+     */
+    customerOrgResolver?: (customerAccountId: string) => Promise<string | null>;
+    /** Cookie name used to carry customer (storefront) sessions. */
+    cookieName?: string;
+    /** Cookie name used to carry admin (Admin UI) sessions. */
+    adminCookieName?: string;
+}
+/**
+ * If the request carries a valid admin session (resolved into `request.adminActor`
+ * by the auth plugin) but its ambient `request.actor` is not already an admin,
+ * promote the admin candidate. Admin guards call this so an admin route works
+ * even when a customer session is simultaneously present on the same request.
+ */
+export declare function promoteAdminActor(request: FastifyRequest): void;
+declare function authPluginImpl(app: FastifyInstance, opts: AuthPluginOptions): Promise<void>;
+export declare const authPlugin: typeof authPluginImpl;
+export {};
+//# sourceMappingURL=plugin.d.ts.map

package/dist/backend/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/backend/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAa/D,OAAO,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAEpE;;;;;GAKG;AAuBH,MAAM,WAAW,iBAAiB;IAChC,cAAc,EAAE,cAAc,CAAC;IAC/B,6FAA6F;IAC7F,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;QAC1C,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,EAAE,CAAC;QACjB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC/B,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC/B,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KACnC,GAAG,IAAI,CAAC,CAAC;IACV;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,CAAC,iBAAiB,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5E,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAoBD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CAK/D;AAED,iBAAe,cAAc,CAAC,GAAG,EAAE,eAAe,EAAE,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuH1F;AAED,eAAO,MAAM,UAAU,uBAGrB,CAAC"}