@marinoscar/platform-api 0.0.0-stage → 0.1.0-next.11

package/dist/identity/identity.constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.constants.d.ts","sourceRoot":"","sources":["../../src/identity/identity.constants.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,gBAAgB,EAChB,uBAAuB,IAAI,WAAW,EACtC,iBAAiB,IAAI,KAAK,EAC1B,cAAc,GACf,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/identity/identity.constants.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ORG_ADMIN_ROLE = exports.ROLES = exports.PERMISSIONS = exports.DEFAULT_ORG_ROLE = void 0;
+// Internal: the names identity's own code has always used for its role and
+// permission ids (`PERMISSIONS.USERS_READ`, `ROLES.ADMIN`), bound to identity's
+// declarations. Not exported from the slice: the public names are
+// `IDENTITY_PERMISSION_IDS` and `IDENTITY_ROLE_IDS` (./identity.permissions.ts),
+// and the app's own `PERMISSIONS` covers every slice.
+var identity_permissions_1 = require("./identity.permissions");
+Object.defineProperty(exports, "DEFAULT_ORG_ROLE", { enumerable: true, get: function () { return identity_permissions_1.DEFAULT_ORG_ROLE; } });
+Object.defineProperty(exports, "PERMISSIONS", { enumerable: true, get: function () { return identity_permissions_1.IDENTITY_PERMISSION_IDS; } });
+Object.defineProperty(exports, "ROLES", { enumerable: true, get: function () { return identity_permissions_1.IDENTITY_ROLE_IDS; } });
+Object.defineProperty(exports, "ORG_ADMIN_ROLE", { enumerable: true, get: function () { return identity_permissions_1.ORG_ADMIN_ROLE; } });
+//# sourceMappingURL=identity.constants.js.map

package/dist/identity/identity.constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.constants.js","sourceRoot":"","sources":["../../src/identity/identity.constants.ts"],"names":[],"mappings":";;;AAAA,2EAA2E;AAC3E,gFAAgF;AAChF,kEAAkE;AAClE,iFAAiF;AACjF,sDAAsD;AACtD,+DAKgC;AAJ9B,wHAAA,gBAAgB,OAAA;AAChB,mHAAA,uBAAuB,OAAe;AACtC,6GAAA,iBAAiB,OAAS;AAC1B,sHAAA,cAAc,OAAA"}

package/dist/identity/identity.events.d.ts

@@ -0,0 +1,124 @@
+import type { Logger } from '@nestjs/common';
+/**
+ * The event names identity emits.
+ *
+ * - `identity.user.created`: a user record was created (first sign-in, or the
+ *   test-auth login).
+ * - `identity.membership.changed`: a membership was created, re-activated,
+ *   suspended, given another org role, or removed.
+ * - `identity.org.switched`: a session switched its active organization.
+ * - `identity.login.succeeded`: a sign-in with any provider ended in a session.
+ * - `identity.org.created`: an administrator created an organization.
+ *
+ * @example
+ * ```ts
+ * @OnEvent(IDENTITY_EVENTS.USER_CREATED)
+ * onUserCreated(event: IdentityUserCreatedEvent) { ... }
+ * ```
+ *
+ * @extensionPoint event
+ * @stability experimental
+ */
+export declare const IDENTITY_EVENTS: {
+    /** A user record was created. Payload: {@link IdentityUserCreatedEvent}. */
+    readonly USER_CREATED: "identity.user.created";
+    /** A membership changed. Payload: {@link IdentityMembershipChangedEvent}. */
+    readonly MEMBERSHIP_CHANGED: "identity.membership.changed";
+    /** A session switched organization. Payload: {@link IdentityOrgSwitchedEvent}. */
+    readonly ORG_SWITCHED: "identity.org.switched";
+    /** A sign-in succeeded. Payload: {@link IdentityLoginSucceededEvent}. */
+    readonly LOGIN_SUCCEEDED: "identity.login.succeeded";
+    /** An organization was created. Payload: {@link IdentityOrgCreatedEvent}. */
+    readonly ORG_CREATED: "identity.org.created";
+};
+/**
+ * Payload of `identity.user.created`.
+ *
+ * @stability experimental
+ */
+export interface IdentityUserCreatedEvent {
+    /** The new user's id. */
+    userId: string;
+    /** The new user's email. */
+    email: string;
+    /** How the user was created: the sign-in provider's id (`google`, `github`) or `test-auth`. */
+    source: string;
+    /** The organization the user joined at creation, or `null` (multi-org mode). */
+    orgId: string | null;
+}
+/**
+ * What happened to a membership.
+ *
+ * @stability experimental
+ */
+export type IdentityMembershipChange = 'created' | 'reactivated' | 'role_changed' | 'status_changed' | 'removed';
+/**
+ * Payload of `identity.membership.changed`.
+ *
+ * @stability experimental
+ */
+export interface IdentityMembershipChangedEvent {
+    /** The member's user id. */
+    userId: string;
+    /** The organization. */
+    orgId: string;
+    /** What happened. */
+    change: IdentityMembershipChange;
+    /** The org role after the change, or `null` when the membership was removed. */
+    role: string | null;
+    /** Who made the change, or `null` for the system (a sign-in claiming an invitation). */
+    actorUserId: string | null;
+}
+/**
+ * Payload of `identity.org.switched`.
+ *
+ * @stability experimental
+ */
+export interface IdentityOrgSwitchedEvent {
+    /** The user whose session switched. */
+    userId: string;
+    /** The organization the session acts in from now on. */
+    orgId: string;
+}
+/**
+ * Payload of `identity.login.succeeded`: emitted after the session was issued,
+ * for every provider (Google included). Carries ids and the provider id only:
+ * no email, no token, no profile.
+ *
+ * @stability experimental
+ */
+export interface IdentityLoginSucceededEvent {
+    /** The signed-in user. */
+    userId: string;
+    /** The provider id the person signed in with (`google`, `github`). */
+    provider: string;
+    /** True when this sign-in created the user. */
+    isNewUser: boolean;
+}
+/**
+ * Payload of `identity.org.created`.
+ *
+ * @stability experimental
+ */
+export interface IdentityOrgCreatedEvent {
+    /** The new organization's id. */
+    orgId: string;
+    /** The administrator who created it. */
+    createdBy: string;
+}
+/** The emitter shape identity needs: `EventEmitter2`'s `emit`. */
+interface EventEmitterLike {
+    emit(event: string, payload: unknown): boolean;
+}
+/**
+ * Emits one identity event, swallowing (and logging) a listener's error so it
+ * never fails the operation that raised the event. No-op without an emitter.
+ *
+ * @param emitter - the app's `EventEmitter2`, when one is registered.
+ * @param logger - where a listener's failure is logged.
+ * @param event - the event name.
+ * @param payload - the payload.
+ */
+export declare function emitIdentityEvent(emitter: EventEmitterLike | undefined | null, logger: Pick<Logger, 'warn'>, event: (typeof IDENTITY_EVENTS)[keyof typeof IDENTITY_EVENTS], payload: IdentityUserCreatedEvent | IdentityMembershipChangedEvent | IdentityOrgSwitchedEvent | IdentityLoginSucceededEvent | IdentityOrgCreatedEvent): void;
+export {};
+//# sourceMappingURL=identity.events.d.ts.map

package/dist/identity/identity.events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.events.d.ts","sourceRoot":"","sources":["../../src/identity/identity.events.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,eAAe;IAC1B,4EAA4E;;IAE5E,6EAA6E;;IAE7E,kFAAkF;;IAElF,yEAAyE;;IAEzE,6EAA6E;;CAErE,CAAC;AAEX;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,yBAAyB;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,+FAA+F;IAC/F,MAAM,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAAG,SAAS,GAAG,aAAa,GAAG,cAAc,GAAG,gBAAgB,GAAG,SAAS,CAAC;AAEjH;;;;GAIG;AACH,MAAM,WAAW,8BAA8B;IAC7C,4BAA4B;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,qBAAqB;IACrB,MAAM,EAAE,wBAAwB,CAAC;IACjC,gFAAgF;IAChF,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,wFAAwF;IACxF,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,MAAM,WAAW,2BAA2B;IAC1C,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;IACjB,+CAA+C;IAC/C,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,kEAAkE;AAClE,UAAU,gBAAgB;IACxB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC;CAChD;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,gBAAgB,GAAG,SAAS,GAAG,IAAI,EAC5C,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5B,KAAK,EAAE,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,OAAO,eAAe,CAAC,EAC7D,OAAO,EACH,wBAAwB,GACxB,8BAA8B,GAC9B,wBAAwB,GACxB,2BAA2B,GAC3B,uBAAuB,GAC1B,IAAI,CAON"}

package/dist/identity/identity.events.js

@@ -0,0 +1,74 @@
+"use strict";
+// =============================================================================
+// Identity's domain events (issue #727, PP-6.6)
+// =============================================================================
+//
+// Rung 4 of the extension contract: an app reacts to identity without editing
+// it, for example by creating its own profile row when a user is created.
+// Emitted on the app's `EventEmitter2` (`@nestjs/event-emitter`, which the app
+// registers with `EventEmitterModule.forRoot()`), AFTER the triggering write
+// committed, never inside a transaction.
+//
+// ⚠ `EventEmitter2` DISPATCHES SYNCHRONOUSLY, inside the request that caused
+// the event. A listener does small, bounded work or enqueues a job; anything
+// long-running is a queue job (CLAUDE.md, "Every long-running activity is a
+// queue job"). A throwing listener is caught and logged here, so it can never
+// fail the sign-in that raised the event.
+//
+// Payloads carry ids and closed values only: never a token, never a secret.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IDENTITY_EVENTS = void 0;
+exports.emitIdentityEvent = emitIdentityEvent;
+/**
+ * The event names identity emits.
+ *
+ * - `identity.user.created`: a user record was created (first sign-in, or the
+ *   test-auth login).
+ * - `identity.membership.changed`: a membership was created, re-activated,
+ *   suspended, given another org role, or removed.
+ * - `identity.org.switched`: a session switched its active organization.
+ * - `identity.login.succeeded`: a sign-in with any provider ended in a session.
+ * - `identity.org.created`: an administrator created an organization.
+ *
+ * @example
+ * ```ts
+ * @OnEvent(IDENTITY_EVENTS.USER_CREATED)
+ * onUserCreated(event: IdentityUserCreatedEvent) { ... }
+ * ```
+ *
+ * @extensionPoint event
+ * @stability experimental
+ */
+exports.IDENTITY_EVENTS = {
+    /** A user record was created. Payload: {@link IdentityUserCreatedEvent}. */
+    USER_CREATED: 'identity.user.created',
+    /** A membership changed. Payload: {@link IdentityMembershipChangedEvent}. */
+    MEMBERSHIP_CHANGED: 'identity.membership.changed',
+    /** A session switched organization. Payload: {@link IdentityOrgSwitchedEvent}. */
+    ORG_SWITCHED: 'identity.org.switched',
+    /** A sign-in succeeded. Payload: {@link IdentityLoginSucceededEvent}. */
+    LOGIN_SUCCEEDED: 'identity.login.succeeded',
+    /** An organization was created. Payload: {@link IdentityOrgCreatedEvent}. */
+    ORG_CREATED: 'identity.org.created',
+};
+/**
+ * Emits one identity event, swallowing (and logging) a listener's error so it
+ * never fails the operation that raised the event. No-op without an emitter.
+ *
+ * @param emitter - the app's `EventEmitter2`, when one is registered.
+ * @param logger - where a listener's failure is logged.
+ * @param event - the event name.
+ * @param payload - the payload.
+ */
+function emitIdentityEvent(emitter, logger, event, payload) {
+    if (!emitter)
+        return;
+    try {
+        emitter.emit(event, payload);
+    }
+    catch (error) {
+        logger.warn(`A listener of ${event} threw: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+//# sourceMappingURL=identity.events.js.map

package/dist/identity/identity.events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.events.js","sourceRoot":"","sources":["../../src/identity/identity.events.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,gDAAgD;AAChD,gFAAgF;AAChF,EAAE;AACF,8EAA8E;AAC9E,0EAA0E;AAC1E,+EAA+E;AAC/E,6EAA6E;AAC7E,yCAAyC;AACzC,EAAE;AACF,6EAA6E;AAC7E,6EAA6E;AAC7E,4EAA4E;AAC5E,8EAA8E;AAC9E,0CAA0C;AAC1C,EAAE;AACF,4EAA4E;AAC5E,gFAAgF;;;AAoIhF,8CAiBC;AAjJD;;;;;;;;;;;;;;;;;;;GAmBG;AACU,QAAA,eAAe,GAAG;IAC7B,4EAA4E;IAC5E,YAAY,EAAE,uBAAuB;IACrC,6EAA6E;IAC7E,kBAAkB,EAAE,6BAA6B;IACjD,kFAAkF;IAClF,YAAY,EAAE,uBAAuB;IACrC,yEAAyE;IACzE,eAAe,EAAE,0BAA0B;IAC3C,6EAA6E;IAC7E,WAAW,EAAE,sBAAsB;CAC3B,CAAC;AAwFX;;;;;;;;GAQG;AACH,SAAgB,iBAAiB,CAC/B,OAA4C,EAC5C,MAA4B,EAC5B,KAA6D,EAC7D,OAK2B;IAE3B,IAAI,CAAC,OAAO;QAAE,OAAO;IACrB,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAC/B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,IAAI,CAAC,iBAAiB,KAAK,WAAW,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACzG,CAAC;AACH,CAAC"}

package/dist/identity/identity.module.d.ts

@@ -0,0 +1,35 @@
+import { DynamicModule } from '@nestjs/common';
+import './auth/providers/google.provider';
+import { type IdentityModuleOptions } from './identity.options';
+/**
+ * The identity slice: authentication (JWT sessions, personal access tokens,
+ * worker-node credentials, Google sign-in and any registered provider), the
+ * guards and decorators every route uses, users, the allowlist, the device
+ * authorization flow, organizations, members, invitations and tenancy, with
+ * two server-only cleanup job types and their enqueue-only crons, and the
+ * `auth.*` and `tenancy.*` Doctor checks.
+ *
+ * @stability experimental
+ */
+export declare class IdentityModule {
+    /**
+     * The slice for one app.
+     *
+     * @param options - see {@link IdentityModuleOptions}.
+     * @returns the dynamic module. It provides `IDENTITY_OPTIONS` globally.
+     * @throws Error when an option is invalid, or `enableTestAuth` is set in production.
+     *
+     * @example
+     * ```ts
+     * IdentityModule.forRoot({
+     *   imports: [IdentityHostModule],
+     *   enableTestAuth: process.env.NODE_ENV !== 'production',
+     * });
+     * ```
+     *
+     * @extensionPoint option
+     * @stability experimental
+     */
+    static forRoot(options?: IdentityModuleOptions): DynamicModule;
+}
+//# sourceMappingURL=identity.module.d.ts.map

package/dist/identity/identity.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.module.d.ts","sourceRoot":"","sources":["../../src/identity/identity.module.ts"],"names":[],"mappings":"AAoBA,OAAO,EAAE,aAAa,EAAyD,MAAM,gBAAgB,CAAC;AAItG,OAAO,kCAAkC,CAAC;AAI1C,OAAO,EAAkD,KAAK,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAehH;;;;;;;;;GASG;AACH,qBACa,cAAc;IACzB;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,qBAA0B,GAAG,aAAa;CA6CnE"}

package/dist/identity/identity.module.js

@@ -0,0 +1,127 @@
+"use strict";
+// =============================================================================
+// IdentityModule: the identity slice's one composition entry point (issue #727)
+// =============================================================================
+//
+// `IdentityModule.forRoot(options)` mounts every identity module: sign-in and
+// tokens (`AuthModule`, with the allowlist, personal access tokens and
+// organizations it depends on), users, the device authorization flow and,
+// outside production when asked, the test login. The app binds identity's host
+// ports in its own `@Global()` module(s), passed as `options.imports`.
+//
+// MODULE ORDER IS THE APP'S OLD ORDER, on purpose. Nest discovers modules
+// depth-first, and the generated OpenAPI document lists paths in discovery
+// order. Sign-in (with the allowlist) first, then the host modules (where the
+// app's notification graph used to be reached), personal access tokens,
+// organizations, users and the device flow, so the document keeps its paths
+// in place (the device flow's block moves up, next to the other identity routes).
+//
+// Every identity module is a singleton: `forRoot` is called once per app.
+// =============================================================================
+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 IdentityModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IdentityModule = void 0;
+const common_1 = require("@nestjs/common");
+const auth_module_1 = require("./auth/auth.module");
+const auth_provider_registry_1 = require("./auth/providers/auth-provider.registry");
+require("./auth/providers/google.provider");
+const device_auth_module_1 = require("./device-auth/device-auth.module");
+const sign_in_policy_1 = require("./auth/sign-in-policy");
+const identity_metadata_service_1 = require("./metadata/identity-metadata.service");
+const identity_options_1 = require("./identity.options");
+const organizations_module_1 = require("./organizations/organizations.module");
+const pat_module_1 = require("./pat/pat.module");
+const roles_module_1 = require("./roles/roles.module");
+const test_auth_module_1 = require("./testing/test-auth.module");
+const users_module_1 = require("./users/users.module");
+/** A static module class created at run time: its metadata is scanned depth first. */
+function staticModule(name, metadata) {
+    const holder = { [name]: class {
+        } };
+    const cls = holder[name];
+    (0, common_1.Module)(metadata)(cls);
+    return cls;
+}
+/**
+ * The identity slice: authentication (JWT sessions, personal access tokens,
+ * worker-node credentials, Google sign-in and any registered provider), the
+ * guards and decorators every route uses, users, the allowlist, the device
+ * authorization flow, organizations, members, invitations and tenancy, with
+ * two server-only cleanup job types and their enqueue-only crons, and the
+ * `auth.*` and `tenancy.*` Doctor checks.
+ *
+ * @stability experimental
+ */
+let IdentityModule = IdentityModule_1 = class IdentityModule {
+    /**
+     * The slice for one app.
+     *
+     * @param options - see {@link IdentityModuleOptions}.
+     * @returns the dynamic module. It provides `IDENTITY_OPTIONS` globally.
+     * @throws Error when an option is invalid, or `enableTestAuth` is set in production.
+     *
+     * @example
+     * ```ts
+     * IdentityModule.forRoot({
+     *   imports: [IdentityHostModule],
+     *   enableTestAuth: process.env.NODE_ENV !== 'production',
+     * });
+     * ```
+     *
+     * @extensionPoint option
+     * @stability experimental
+     */
+    static forRoot(options = {}) {
+        const resolved = (0, identity_options_1.resolveIdentityModuleOptions)(options);
+        // Every registered sign-in provider's Passport strategy (Google first),
+        // registered before this call; the registry freezes at bootstrap.
+        // A provider that builds its strategy per request (`createStrategy`) has no class to provide.
+        const strategies = auth_provider_registry_1.authProviderRegistry.list().flatMap((provider) => (provider.strategy ? [provider.strategy] : []));
+        // Built as STATIC modules, never as a dynamic module's inline `imports`:
+        // Nest inserts a dynamic module's inline imports into the container
+        // eagerly, ahead of the depth-first scan, which would reorder every module
+        // (and the OpenAPI document) after them. Static metadata is scanned depth
+        // first, in the order written here.
+        const hostImports = staticModule('IdentityHostImportsModule', { imports: [...resolved.imports] });
+        const authProviders = staticModule('IdentityAuthProvidersModule', { imports: [auth_module_1.AuthModule], providers: strategies });
+        const composition = staticModule('IdentityCompositionModule', {
+            imports: [
+                auth_module_1.AuthModule,
+                authProviders,
+                hostImports,
+                pat_module_1.PatModule,
+                organizations_module_1.OrganizationsModule,
+                users_module_1.UsersModule,
+                roles_module_1.RolesModule,
+                device_auth_module_1.DeviceAuthModule,
+                ...(resolved.enableTestAuth ? [test_auth_module_1.TestAuthModule] : []),
+            ],
+        });
+        return {
+            module: IdentityModule_1,
+            global: true,
+            imports: [composition],
+            providers: [
+                { provide: identity_options_1.IDENTITY_OPTIONS, useValue: resolved },
+                // The metadata helpers over users.metadata and organizations.metadata (PP-14.27):
+                // global with this module, so an app service injects it without importing anything.
+                identity_metadata_service_1.IdentityMetadataService,
+                // The app's sign-in policy (PP-14.9), visible to `AuthService` because
+                // this module is global; absent when the app bound none.
+                ...(resolved.signInPolicy ? [{ provide: sign_in_policy_1.IDENTITY_SIGNIN_POLICY, ...resolved.signInPolicy }] : []),
+            ],
+            exports: [identity_options_1.IDENTITY_OPTIONS, identity_metadata_service_1.IdentityMetadataService, ...(resolved.signInPolicy ? [sign_in_policy_1.IDENTITY_SIGNIN_POLICY] : [])],
+        };
+    }
+};
+exports.IdentityModule = IdentityModule;
+exports.IdentityModule = IdentityModule = IdentityModule_1 = __decorate([
+    (0, common_1.Module)({})
+], IdentityModule);
+//# sourceMappingURL=identity.module.js.map

package/dist/identity/identity.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.module.js","sourceRoot":"","sources":["../../src/identity/identity.module.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,gFAAgF;AAChF,gFAAgF;AAChF,EAAE;AACF,8EAA8E;AAC9E,uEAAuE;AACvE,0EAA0E;AAC1E,+EAA+E;AAC/E,uEAAuE;AACvE,EAAE;AACF,0EAA0E;AAC1E,2EAA2E;AAC3E,8EAA8E;AAC9E,wEAAwE;AACxE,4EAA4E;AAC5E,kFAAkF;AAClF,EAAE;AACF,0EAA0E;AAC1E,gFAAgF;;;;;;;;;;AAEhF,2CAAsG;AAEtG,oDAAgD;AAChD,oFAA+E;AAC/E,4CAA0C;AAC1C,yEAAoE;AACpE,0DAA+D;AAC/D,oFAA+E;AAC/E,yDAAgH;AAChH,+EAA2E;AAC3E,iDAA6C;AAC7C,uDAAmD;AACnD,iEAA4D;AAC5D,uDAAmD;AAEnD,sFAAsF;AACtF,SAAS,YAAY,CAAC,IAAY,EAAE,QAAwB;IAC1D,MAAM,MAAM,GAAG,EAAE,CAAC,IAAI,CAAC,EAAE;SAAQ,EAAE,CAAC;IACpC,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAE,CAAC;IAC1B,IAAA,eAAM,EAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC;IACtB,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;GASG;AAEI,IAAM,cAAc,sBAApB,MAAM,cAAc;IACzB;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,OAAO,CAAC,UAAiC,EAAE;QAChD,MAAM,QAAQ,GAAG,IAAA,+CAA4B,EAAC,OAAO,CAAC,CAAC;QAEvD,wEAAwE;QACxE,kEAAkE;QAClE,8FAA8F;QAC9F,MAAM,UAAU,GAAG,6CAAoB,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAErH,yEAAyE;QACzE,oEAAoE;QACpE,2EAA2E;QAC3E,0EAA0E;QAC1E,oCAAoC;QACpC,MAAM,WAAW,GAAG,YAAY,CAAC,2BAA2B,EAAE,EAAE,OAAO,EAAE,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAClG,MAAM,aAAa,GAAG,YAAY,CAAC,6BAA6B,EAAE,EAAE,OAAO,EAAE,CAAC,wBAAU,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC,CAAC;QACpH,MAAM,WAAW,GAAG,YAAY,CAAC,2BAA2B,EAAE;YAC5D,OAAO,EAAE;gBACP,wBAAU;gBACV,aAAa;gBACb,WAAW;gBACX,sBAAS;gBACT,0CAAmB;gBACnB,0BAAW;gBACX,0BAAW;gBACX,qCAAgB;gBAChB,GAAG,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,iCAAc,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;aACrD;SACF,CAAC,CAAC;QAEH,OAAO;YACL,MAAM,EAAE,gBAAc;YACtB,MAAM,EAAE,IAAI;YACZ,OAAO,EAAE,CAAC,WAAW,CAAC;YACtB,SAAS,EAAE;gBACT,EAAE,OAAO,EAAE,mCAAgB,EAAE,QAAQ,EAAE,QAAQ,EAAE;gBACjD,kFAAkF;gBAClF,oFAAoF;gBACpF,mDAAuB;gBACvB,uEAAuE;gBACvE,yDAAyD;gBACzD,GAAG,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,uCAAsB,EAAE,GAAG,QAAQ,CAAC,YAAY,EAAc,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;aAC9G;YACD,OAAO,EAAE,CAAC,mCAAgB,EAAE,mDAAuB,EAAE,GAAG,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,uCAAsB,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;SACjH,CAAC;IACJ,CAAC;CACF,CAAA;AAhEY,wCAAc;yBAAd,cAAc;IAD1B,IAAA,eAAM,EAAC,EAAE,CAAC;GACE,cAAc,CAgE1B"}

package/dist/identity/identity.options.d.ts

@@ -0,0 +1,92 @@
+import type { DynamicModule, ForwardReference, Type } from '@nestjs/common';
+import type { PortBinding } from '../core/index';
+import type { SignInPolicy } from './auth/sign-in-policy';
+/**
+ * Injection token of the {@link ResolvedIdentityModuleOptions}, provided
+ * globally by `IdentityModule.forRoot()`. Optional to every consumer: a graph
+ * built without `forRoot` (a unit test) gets {@link DEFAULT_IDENTITY_OPTIONS}.
+ *
+ * @stability experimental
+ */
+export declare const IDENTITY_OPTIONS: unique symbol;
+/**
+ * What an app passes to `IdentityModule.forRoot()`.
+ *
+ * @stability experimental
+ */
+export interface IdentityModuleOptions {
+    /**
+     * The org role a new membership gets: every sign-up's role in the default
+     * organization and the role of an invitation that names none. Default
+     * `'viewer'`. Must be a seeded org role.
+     */
+    defaultOrgRole?: string;
+    /**
+     * The environment variable (read through `ConfigService`) holding the address
+     * that always bypasses the allowlist and becomes the first administrator.
+     * Default `'INITIAL_ADMIN_EMAIL'`.
+     */
+    initialAdminEmailEnv?: string;
+    /**
+     * Mounts the test-only login (`POST /api/auth/test/login`,
+     * `@marinoscar/platform-api/identity/testing`). Default `false`. Refused
+     * (boot error) when `NODE_ENV` is `production`.
+     */
+    enableTestAuth?: boolean;
+    /**
+     * The app's sign-in policy (PP-14.9): consulted for every provider after the
+     * allowlist and before any write, it can deny a sign-in with a reason or map
+     * roles onto a new user. Bound HERE and not by providing
+     * `IDENTITY_SIGNIN_POLICY` in an app module, which identity's internals would
+     * never see. Default: none (every sign-in the allowlist admits is allowed).
+     *
+     * @example
+     * ```ts
+     * IdentityModule.forRoot({ signInPolicy: { useClass: CompanyDomainPolicy } });
+     * ```
+     */
+    signInPolicy?: PortBinding<SignInPolicy>;
+    /**
+     * The modules that bind identity's host ports (`IDENTITY_NOTIFIER`,
+     * `USER_DEFAULTS`, `IDENTITY_JOBS`, `IDENTITY_NODE_CREDENTIALS`, ...). Each
+     * must be `@Global()`: `JwtAuthGuard` is instantiated in every module whose
+     * controllers use `@Auth()`, so the ports it needs must resolve there.
+     */
+    imports?: ReadonlyArray<Type<unknown> | DynamicModule | Promise<DynamicModule> | ForwardReference>;
+}
+/**
+ * The options after defaults, as `IDENTITY_OPTIONS` provides them.
+ *
+ * @stability experimental
+ */
+export interface ResolvedIdentityModuleOptions {
+    /** The org role of a new membership. */
+    readonly defaultOrgRole: string;
+    /** The variable holding the initial administrator's address. */
+    readonly initialAdminEmailEnv: string;
+    /** Whether the test-only login is mounted. */
+    readonly enableTestAuth: boolean;
+    /** The app's sign-in policy binding, when one was given. */
+    readonly signInPolicy?: PortBinding<SignInPolicy>;
+    /** The host-port modules. */
+    readonly imports: ReadonlyArray<Type<unknown> | DynamicModule | Promise<DynamicModule> | ForwardReference>;
+}
+/**
+ * The options a graph without `forRoot` behaves as.
+ *
+ * @stability experimental
+ */
+export declare const DEFAULT_IDENTITY_OPTIONS: ResolvedIdentityModuleOptions;
+/**
+ * Applies defaults and validates the options.
+ *
+ * @param options - the app's options.
+ * @param nodeEnv - the environment (`process.env.NODE_ENV` by default), for the test-auth guard.
+ * @returns the resolved, frozen options.
+ * @throws Error naming the field when an option is invalid, or when
+ *   `enableTestAuth` is requested in production.
+ *
+ * @stability experimental
+ */
+export declare function resolveIdentityModuleOptions(options?: IdentityModuleOptions, nodeEnv?: string | undefined): ResolvedIdentityModuleOptions;
+//# sourceMappingURL=identity.options.d.ts.map

package/dist/identity/identity.options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.options.d.ts","sourceRoot":"","sources":["../../src/identity/identity.options.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAE5E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAG1D;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,EAAE,OAAO,MAA4D,CAAC;AAEnG;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;;;;;;;OAWG;IACH,YAAY,CAAC,EAAE,WAAW,CAAC,YAAY,CAAC,CAAC;IACzC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,GAAG,gBAAgB,CAAC,CAAC;CACpG;AAED;;;;GAIG;AACH,MAAM,WAAW,6BAA6B;IAC5C,wCAAwC;IACxC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,gEAAgE;IAChE,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,8CAA8C;IAC9C,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,4DAA4D;IAC5D,QAAQ,CAAC,YAAY,CAAC,EAAE,WAAW,CAAC,YAAY,CAAC,CAAC;IAClD,6BAA6B;IAC7B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,GAAG,gBAAgB,CAAC,CAAC;CAC5G;AAED;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,6BAKrC,CAAC;AAKH;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,GAAE,qBAA0B,EACnC,OAAO,GAAE,MAAM,GAAG,SAAgC,GACjD,6BAA6B,CAmC/B"}

package/dist/identity/identity.options.js

@@ -0,0 +1,71 @@
+"use strict";
+// =============================================================================
+// `IdentityModule.forRoot()` options (issue #727, PP-6.6)
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_IDENTITY_OPTIONS = exports.IDENTITY_OPTIONS = void 0;
+exports.resolveIdentityModuleOptions = resolveIdentityModuleOptions;
+const identity_permissions_1 = require("./identity.permissions");
+/**
+ * Injection token of the {@link ResolvedIdentityModuleOptions}, provided
+ * globally by `IdentityModule.forRoot()`. Optional to every consumer: a graph
+ * built without `forRoot` (a unit test) gets {@link DEFAULT_IDENTITY_OPTIONS}.
+ *
+ * @stability experimental
+ */
+exports.IDENTITY_OPTIONS = Symbol.for('@marinoscar/platform/identity/OPTIONS');
+/**
+ * The options a graph without `forRoot` behaves as.
+ *
+ * @stability experimental
+ */
+exports.DEFAULT_IDENTITY_OPTIONS = Object.freeze({
+    defaultOrgRole: identity_permissions_1.DEFAULT_ORG_ROLE,
+    initialAdminEmailEnv: 'INITIAL_ADMIN_EMAIL',
+    enableTestAuth: false,
+    imports: Object.freeze([]),
+});
+const ENV_NAME = /^[A-Z][A-Z0-9_]*$/;
+const ROLE_NAME = /^[a-z][a-z0-9_]*$/;
+/**
+ * Applies defaults and validates the options.
+ *
+ * @param options - the app's options.
+ * @param nodeEnv - the environment (`process.env.NODE_ENV` by default), for the test-auth guard.
+ * @returns the resolved, frozen options.
+ * @throws Error naming the field when an option is invalid, or when
+ *   `enableTestAuth` is requested in production.
+ *
+ * @stability experimental
+ */
+function resolveIdentityModuleOptions(options = {}, nodeEnv = process.env.NODE_ENV) {
+    const defaultOrgRole = options.defaultOrgRole ?? exports.DEFAULT_IDENTITY_OPTIONS.defaultOrgRole;
+    if (!ROLE_NAME.test(defaultOrgRole)) {
+        throw new Error(`IdentityModule.forRoot: defaultOrgRole ${JSON.stringify(defaultOrgRole)} is not a role name.`);
+    }
+    if (defaultOrgRole === 'admin') {
+        throw new Error('IdentityModule.forRoot: defaultOrgRole cannot be "admin", a system role; use an org role such as "viewer".');
+    }
+    const initialAdminEmailEnv = options.initialAdminEmailEnv ?? exports.DEFAULT_IDENTITY_OPTIONS.initialAdminEmailEnv;
+    if (!ENV_NAME.test(initialAdminEmailEnv)) {
+        throw new Error(`IdentityModule.forRoot: initialAdminEmailEnv ${JSON.stringify(initialAdminEmailEnv)} is not an environment variable name.`);
+    }
+    const enableTestAuth = options.enableTestAuth ?? false;
+    if (enableTestAuth && nodeEnv === 'production') {
+        throw new Error('IdentityModule.forRoot: enableTestAuth is refused in production. The test login issues a session for any ' +
+            'address without a provider; pass enableTestAuth: process.env.NODE_ENV !== "production".');
+    }
+    const signInPolicy = options.signInPolicy;
+    if (signInPolicy !== undefined &&
+        !('useExisting' in signInPolicy || 'useClass' in signInPolicy || 'useFactory' in signInPolicy)) {
+        throw new Error('IdentityModule.forRoot: signInPolicy must be a binding: { useExisting }, { useClass } or { useFactory }.');
+    }
+    return Object.freeze({
+        defaultOrgRole,
+        initialAdminEmailEnv,
+        enableTestAuth,
+        ...(signInPolicy ? { signInPolicy } : {}),
+        imports: Object.freeze([...(options.imports ?? [])]),
+    });
+}
+//# sourceMappingURL=identity.options.js.map

package/dist/identity/identity.options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.options.js","sourceRoot":"","sources":["../../src/identity/identity.options.ts"],"names":[],"mappings":";AAAA,gFAAgF;AAChF,0DAA0D;AAC1D,gFAAgF;;;AA2GhF,oEAsCC;AA3ID,iEAA0D;AAE1D;;;;;;GAMG;AACU,QAAA,gBAAgB,GAAkB,MAAM,CAAC,GAAG,CAAC,uCAAuC,CAAC,CAAC;AAkEnG;;;;GAIG;AACU,QAAA,wBAAwB,GAAkC,MAAM,CAAC,MAAM,CAAC;IACnF,cAAc,EAAE,uCAAgB;IAChC,oBAAoB,EAAE,qBAAqB;IAC3C,cAAc,EAAE,KAAK;IACrB,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;CAC3B,CAAC,CAAC;AAEH,MAAM,QAAQ,GAAG,mBAAmB,CAAC;AACrC,MAAM,SAAS,GAAG,mBAAmB,CAAC;AAEtC;;;;;;;;;;GAUG;AACH,SAAgB,4BAA4B,CAC1C,UAAiC,EAAE,EACnC,UAA8B,OAAO,CAAC,GAAG,CAAC,QAAQ;IAElD,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,gCAAwB,CAAC,cAAc,CAAC;IACzF,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,cAAc,CAAC,EAAE,CAAC;QACpC,MAAM,IAAI,KAAK,CAAC,0CAA0C,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,sBAAsB,CAAC,CAAC;IAClH,CAAC;IACD,IAAI,cAAc,KAAK,OAAO,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,4GAA4G,CAAC,CAAC;IAChI,CAAC;IACD,MAAM,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,IAAI,gCAAwB,CAAC,oBAAoB,CAAC;IAC3G,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,oBAAoB,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CACb,gDAAgD,IAAI,CAAC,SAAS,CAAC,oBAAoB,CAAC,uCAAuC,CAC5H,CAAC;IACJ,CAAC;IACD,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,KAAK,CAAC;IACvD,IAAI,cAAc,IAAI,OAAO,KAAK,YAAY,EAAE,CAAC;QAC/C,MAAM,IAAI,KAAK,CACb,2GAA2G;YACzG,yFAAyF,CAC5F,CAAC;IACJ,CAAC;IACD,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAC1C,IACE,YAAY,KAAK,SAAS;QAC1B,CAAC,CAAC,aAAa,IAAI,YAAY,IAAI,UAAU,IAAI,YAAY,IAAI,YAAY,IAAI,YAAY,CAAC,EAC9F,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,0GAA0G,CAAC,CAAC;IAC9H,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,cAAc;QACd,oBAAoB;QACpB,cAAc;QACd,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC;KACrD,CAAC,CAAC;AACL,CAAC"}