@endora-commerce/mod-admin-users 0.100.0

package/dist/migrations/20260825T124801_admin_users_drop_legacy_two_factor_secret.d.ts

@@ -0,0 +1,25 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * Drops `admin_users.two_factor_secret`, the superseded admin 2FA column.
+ *
+ * This half is further gone than the customer one: the column has **no writer
+ * anywhere in the tree** — an entity declaration and the init DDL, and nothing
+ * else. Admin 2FA is `mfa`'s, over `mfa_enrolments`, with an encrypted secret
+ * and single-use recovery-code rows; `mfa`'s own init migration records this
+ * column as SUPERSEDED.
+ *
+ * **Nothing is destroyed.** Measured on the dev database on 2026-08-25:
+ * `admin_users` holds 3 rows, of which `count(two_factor_secret)` is 0. There
+ * is no client deployment and no production database. `down()` re-creates the
+ * column's shape and nothing else, because there has never been a value to
+ * restore.
+ *
+ * `two_factor_confirmed_at` deliberately stays — see the sibling migration in
+ * `customer_accounts` and
+ * `specs/087-tenant-scope-enforcement/superseded-2fa-analysis.md` §7.
+ */
+export declare class Migration20260825T124801AdminUsersDropLegacyTwoFactorSecret extends Migration {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}
+//# sourceMappingURL=20260825T124801_admin_users_drop_legacy_two_factor_secret.d.ts.map

package/dist/migrations/20260825T124801_admin_users_drop_legacy_two_factor_secret.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260825T124801_admin_users_drop_legacy_two_factor_secret.d.ts","sourceRoot":"","sources":["../../src/migrations/20260825T124801_admin_users_drop_legacy_two_factor_secret.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,2DAA4D,SAAQ,SAAS;IACzE,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC;IAInB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAGrC"}

package/dist/migrations/20260825T124801_admin_users_drop_legacy_two_factor_secret.js

@@ -0,0 +1,29 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * Drops `admin_users.two_factor_secret`, the superseded admin 2FA column.
+ *
+ * This half is further gone than the customer one: the column has **no writer
+ * anywhere in the tree** — an entity declaration and the init DDL, and nothing
+ * else. Admin 2FA is `mfa`'s, over `mfa_enrolments`, with an encrypted secret
+ * and single-use recovery-code rows; `mfa`'s own init migration records this
+ * column as SUPERSEDED.
+ *
+ * **Nothing is destroyed.** Measured on the dev database on 2026-08-25:
+ * `admin_users` holds 3 rows, of which `count(two_factor_secret)` is 0. There
+ * is no client deployment and no production database. `down()` re-creates the
+ * column's shape and nothing else, because there has never been a value to
+ * restore.
+ *
+ * `two_factor_confirmed_at` deliberately stays — see the sibling migration in
+ * `customer_accounts` and
+ * `specs/087-tenant-scope-enforcement/superseded-2fa-analysis.md` §7.
+ */
+export class Migration20260825T124801AdminUsersDropLegacyTwoFactorSecret extends Migration {
+    async up() {
+        this.addSql(`alter table "admin_users" drop column "two_factor_secret";`);
+    }
+    async down() {
+        this.addSql(`alter table "admin_users" add column "two_factor_secret" varchar(64) null;`);
+    }
+}
+//# sourceMappingURL=20260825T124801_admin_users_drop_legacy_two_factor_secret.js.map

package/dist/migrations/20260825T124801_admin_users_drop_legacy_two_factor_secret.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260825T124801_admin_users_drop_legacy_two_factor_secret.js","sourceRoot":"","sources":["../../src/migrations/20260825T124801_admin_users_drop_legacy_two_factor_secret.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,2DAA4D,SAAQ,SAAS;IAC/E,KAAK,CAAC,EAAE;QACf,IAAI,CAAC,MAAM,CAAC,4DAA4D,CAAC,CAAC;IAC5E,CAAC;IAEQ,KAAK,CAAC,IAAI;QACjB,IAAI,CAAC,MAAM,CAAC,4EAA4E,CAAC,CAAC;IAC5F,CAAC;CACF"}

package/dist/migrations/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The `./migrations` subpath — every migration class this module owns, as one
+ * ordered `migrations` array.
+ *
+ * The array is what the platform reads when this module is **installed**:
+ * `src/packages/package-runtime.ts` takes `exported['migrations']` and refuses
+ * the package outright when it is absent (D-168).
+ *
+ * Listed in ascending timestamp, which orders **this module's own** migrations
+ * and nothing else (feature 081). Where the block sits relative to every other
+ * module's is decided by the manifest `dependencies` graph.
+ *
+ * The **named** exports stay, and the asymmetry with `./backend` — which
+ * publishes an array and no entity class by name (D-168) — is deliberate.
+ * `db/migrations-registry.generated.ts` imports each class by name from this
+ * specifier, and a migration class name is contract in a way an entity class
+ * name is not: `mikro_orm_migrations` persists it, so it is a string every
+ * already-migrated database holds.
+ *
+ * A class that is in neither the array nor the barrel is a migration that does
+ * not run: `migration:pending` reports nothing pending and the first symptom
+ * is a query against a table nobody created.
+ */
+import { Migration20260425T053028AdminUsersInit } from './20260425T053028_admin_users_init.js';
+import { Migration20260819T155150AdminUsersFoldEmailCase } from './20260819T155150_admin_users_fold_email_case.js';
+import { Migration20260825T124801AdminUsersDropLegacyTwoFactorSecret } from './20260825T124801_admin_users_drop_legacy_two_factor_secret.js';
+export declare const migrations: (typeof Migration20260425T053028AdminUsersInit)[];
+export { Migration20260425T053028AdminUsersInit, Migration20260819T155150AdminUsersFoldEmailCase, Migration20260825T124801AdminUsersDropLegacyTwoFactorSecret, };
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/migrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,sCAAsC,EAAE,MAAM,uCAAuC,CAAC;AAC/F,OAAO,EAAE,+CAA+C,EAAE,MAAM,kDAAkD,CAAC;AACnH,OAAO,EAAE,2DAA2D,EAAE,MAAM,gEAAgE,CAAC;AAE7I,eAAO,MAAM,UAAU,mDAItB,CAAC;AAEF,OAAO,EACL,sCAAsC,EACtC,+CAA+C,EAC/C,2DAA2D,GAC5D,CAAC"}

package/dist/migrations/index.js

@@ -0,0 +1,33 @@
+/**
+ * The `./migrations` subpath — every migration class this module owns, as one
+ * ordered `migrations` array.
+ *
+ * The array is what the platform reads when this module is **installed**:
+ * `src/packages/package-runtime.ts` takes `exported['migrations']` and refuses
+ * the package outright when it is absent (D-168).
+ *
+ * Listed in ascending timestamp, which orders **this module's own** migrations
+ * and nothing else (feature 081). Where the block sits relative to every other
+ * module's is decided by the manifest `dependencies` graph.
+ *
+ * The **named** exports stay, and the asymmetry with `./backend` — which
+ * publishes an array and no entity class by name (D-168) — is deliberate.
+ * `db/migrations-registry.generated.ts` imports each class by name from this
+ * specifier, and a migration class name is contract in a way an entity class
+ * name is not: `mikro_orm_migrations` persists it, so it is a string every
+ * already-migrated database holds.
+ *
+ * A class that is in neither the array nor the barrel is a migration that does
+ * not run: `migration:pending` reports nothing pending and the first symptom
+ * is a query against a table nobody created.
+ */
+import { Migration20260425T053028AdminUsersInit } from './20260425T053028_admin_users_init.js';
+import { Migration20260819T155150AdminUsersFoldEmailCase } from './20260819T155150_admin_users_fold_email_case.js';
+import { Migration20260825T124801AdminUsersDropLegacyTwoFactorSecret } from './20260825T124801_admin_users_drop_legacy_two_factor_secret.js';
+export const migrations = [
+    Migration20260425T053028AdminUsersInit,
+    Migration20260819T155150AdminUsersFoldEmailCase,
+    Migration20260825T124801AdminUsersDropLegacyTwoFactorSecret,
+];
+export { Migration20260425T053028AdminUsersInit, Migration20260819T155150AdminUsersFoldEmailCase, Migration20260825T124801AdminUsersDropLegacyTwoFactorSecret, };
+//# sourceMappingURL=index.js.map

package/dist/migrations/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/migrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,sCAAsC,EAAE,MAAM,uCAAuC,CAAC;AAC/F,OAAO,EAAE,+CAA+C,EAAE,MAAM,kDAAkD,CAAC;AACnH,OAAO,EAAE,2DAA2D,EAAE,MAAM,gEAAgE,CAAC;AAE7I,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,sCAAsC;IACtC,+CAA+C;IAC/C,2DAA2D;CAC5D,CAAC;AAEF,OAAO,EACL,sCAAsC,EACtC,+CAA+C,EAC/C,2DAA2D,GAC5D,CAAC"}

package/docs/admin_users.md

@@ -0,0 +1,53 @@
+---
+title: admin_users
+description: Platform Administrator accounts + impersonation
+---
+
+# `admin_users`
+
+Platform Administrator accounts (separate from Customer Accounts), plus
+the impersonation flow.
+
+## Public surface
+
+User + role CRUD is gated by the `admin_users:manage` permission.
+
+| Verb + Path | Purpose |
+| --- | --- |
+| `POST /api/v1/auth/admin/login` | Admin login (2FA challenge if Role requires it) |
+| `POST /api/v1/auth/admin/logout` | Destroy admin session |
+| `GET /api/v1/admin/admin-users` | List admin users (deleted rows filtered) |
+| `POST /api/v1/admin/admin-users` | Create admin user; rejects dup email with `EMAIL_ALREADY_REGISTERED` |
+| `PATCH /api/v1/admin/admin-users/:id` | Update name / role assignment / status |
+| `DELETE /api/v1/admin/admin-users/:id` | Soft delete (sets `deletedAt` + `status='inactive'`) |
+| `GET /api/v1/admin/admin-roles` | List roles with their permission arrays |
+| `PUT /api/v1/admin/admin-roles/:code` | Upsert role by code; unknown permissions return 400 `VALIDATION_FAILED` |
+| `DELETE /api/v1/admin/admin-roles/:id` | Delete; refuses with 409 `ADMIN_ROLE_IN_USE` if any user is still assigned — **including a soft-deleted one**, whose assignment comes back when the account is restored. The refusal names which population holds the role (`details.code` is `assigned` or `assigned_to_deleted`) and how many there are |
+| `GET /api/v1/admin/permissions` | Canonical permission catalogue (module / code / label) used by the matrix UI |
+| `POST /api/v1/admin/organizations/:id/impersonate` | Begin impersonation; writes `impersonation.start` audit row before issuing the cookie |
+| `POST /api/v1/admin/impersonation/end` | Restore the original admin session |
+
+## Impersonation model
+
+`impersonation-service.ts` implements the switch-user pattern: starts a
+new session keyed to the target Customer + admin shadow id; ends cleanly,
+writing `impersonation.end`. Every action taken during an impersonated
+session carries both `actorAdminUserId` and `impersonatedCustomerAccountId`
+through the audit log.
+
+## Entities
+
+`AdminUser` (email, passwordHash, two-factor state, single `adminRoleId`,
+`status`, soft-delete `deletedAt`).
+
+`AdminRole` (code, display name, JSONB `permissions[]`,
+`requiresTwoFactor`). The wildcard `*` is bootstrap-only and rejected by
+the upsert route.
+
+## Extension points
+
+- **Custom login challenges** — slot before the password verify in
+  `admin-auth-service.ts`.
+- **Impersonation audit consumers** — every audit row with action
+  `impersonation.start|end` is structured the same way; downstream
+  reporting can join on those.

package/i18n/en.json

@@ -0,0 +1,5 @@
+{
+  "nav.adminUsers.label": "Users",
+  "actions.openAdminUsers.label": "Admin users",
+  "actions.openAdminUsers.description": "Accounts that can sign in to the Admin UI"
+}

package/i18n/pl.json

@@ -0,0 +1,5 @@
+{
+  "nav.adminUsers.label": "Użytkownicy",
+  "actions.openAdminUsers.label": "Użytkownicy panelu",
+  "actions.openAdminUsers.description": "Konta z dostępem do panelu administracyjnego"
+}

package/package.json

@@ -0,0 +1,100 @@
+{
+  "name": "@endora-commerce/mod-admin-users",
+  "version": "0.100.0",
+  "type": "module",
+  "sideEffects": false,
+  "description": "Admin user accounts, sessions, and impersonation flows.",
+  "license": "MIT",
+  "endora": {
+    "type": "module",
+    "id": "admin_users"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/endora-commerce/endora-commerce.git",
+    "directory": "packages/modules/admin_users"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/manifest.d.ts",
+      "default": "./dist/manifest.js"
+    },
+    "./backend": {
+      "types": "./dist/backend/index.d.ts",
+      "default": "./dist/backend/index.js"
+    },
+    "./migrations": {
+      "types": "./dist/migrations/index.d.ts",
+      "default": "./dist/migrations/index.js"
+    },
+    "./admin": {
+      "types": "./dist/admin/index.d.ts",
+      "default": "./dist/admin/index.js"
+    },
+    "./tailwind.css": "./tailwind.css",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "i18n",
+    "docs",
+    "tailwind.css"
+  ],
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "peerDependencies": {
+    "@fastify/cookie": "^11",
+    "@mikro-orm/core": "^6",
+    "@mikro-orm/migrations": "^6",
+    "@mikro-orm/postgresql": "^6",
+    "fastify": "^5",
+    "lucide-react": "^1",
+    "react": "^19",
+    "react-router-dom": "^7",
+    "@endora-commerce/admin-kit": "0.100.0",
+    "@endora-commerce/contracts": "0.100.0",
+    "@endora-commerce/platform": "0.100.0"
+  },
+  "peerDependenciesMeta": {
+    "@endora-commerce/admin-kit": {
+      "optional": true
+    },
+    "lucide-react": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-router-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@fastify/cookie": "^11.0.2",
+    "@fastify/type-provider-zod": "^1.0.0",
+    "@mikro-orm/core": "^6.6.13",
+    "@mikro-orm/migrations": "^6.6.13",
+    "@mikro-orm/postgresql": "^6.6.13",
+    "@types/node": "^22.9.0",
+    "@types/react": "^19.2.14",
+    "fastify": "^5.12.5",
+    "lucide-react": "^1.11.0",
+    "react": "^19.2.5",
+    "react-router-dom": "^7.18.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11",
+    "@endora-commerce/admin-kit": "0.100.0",
+    "@endora-commerce/contracts": "0.100.0",
+    "@endora-commerce/platform": "0.100.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.ui.json",
+    "typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.ui.json --noEmit",
+    "lint": "eslint src",
+    "test": "vitest run"
+  }
+}

package/tailwind.css

@@ -0,0 +1,14 @@
+/* @endora-commerce/mod-admin-users — AUTO-GENERATED by `pnpm --filter backend run manifests:generate`.
+ *
+ * The `@source` directives this package asks its host to scan
+ * (`specs/110-instance-repository/contracts/admin-stylesheet-composition.md` R1).
+ * They resolve relative to **this file**, so they hold wherever the package is
+ * installed — a workspace link here, `node_modules` in a client's instance.
+ *
+ * The `dist` line is what a published tarball ships and is what an instance
+ * scans; the `src` line is inert there and is what keeps `pnpm --filter admin
+ * run dev` reading source in this repository. Do not edit: run
+ * `pnpm --filter backend run manifests:generate`.
+ */
+@source "./dist/admin";
+@source "./src/admin";