@astram/identity 0.1.2 → 0.2.1

package/dist/features/identity-feature.module.d.ts

@@ -0,0 +1,26 @@
+import { type DynamicModule } from '@nestjs/common';
+/**
+ * IdentityFeatureModule — the framework-owned identity FEATURE surface (company/user/role CRUD;
+ * more in later phases) as thin controllers over the engine's RecordsService. The CONSUMER imports
+ * `IdentityFeatureModule.forRoot()` alongside `ShieldModule.forRoot(...)` (ADR-0026) — @astram/guard
+ * never imports @astram/identity. `forRoot()` SELF-WIRES the engine (EngineModule.forRoot over the
+ * app's APP_DB_* env) + registers the identity objects + mounts the CRUD routes, so the consumer
+ * needs no separate engine setup.
+ *
+ * CONTROLLER ORDER: RoleController is kept ahead of any future grant-admin controller (Phase 4) with
+ * a conflicting `GET identity/roles/:uuid` path — a Nest route-precedence constraint.
+ */
+export declare class IdentityFeatureModule {
+    /**
+     * @param rootIds the framework's root allowlist — pass the SAME array given to
+     *   `ShieldModule.forRoot({ rootIds })`. It seeds the cross-tenant grant writer's
+     *   `isRoot` closure so a root caller who passes the route guard is not then denied
+     *   by the writer's own `decide()` (a route-allows/writer-denies split). Omitted ⇒
+     *   `isRoot` is always false (a non-root consumer works; only a root offering
+     *   cross-tenant grants needs it). See ADR-0026 + the template wiring.
+     */
+    static forRoot({ rootIds }?: {
+        rootIds?: readonly string[];
+    }): DynamicModule;
+}
+//# sourceMappingURL=identity-feature.module.d.ts.map

package/dist/features/identity-feature.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-feature.module.d.ts","sourceRoot":"","sources":["../../src/features/identity-feature.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAU,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAoE5D;;;;;;;;;;GAUG;AACH,qBACa,qBAAqB;IAChC;;;;;;;OAOG;IACH,MAAM,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,GAAE;QAAE,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;KAAO,GAAG,aAAa;CAkLjF"}

package/dist/features/identity-feature.module.js

@@ -0,0 +1,247 @@
+"use strict";
+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 IdentityFeatureModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IdentityFeatureModule = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const engine_1 = require("@astram/engine");
+const guard_1 = require("@astram/guard");
+const objects_js_1 = require("../objects.js");
+const index_js_1 = require("./access/index.js");
+const company_service_js_1 = require("./company/company.service.js");
+const company_controller_js_1 = require("./company/company.controller.js");
+const role_service_js_1 = require("./role/role.service.js");
+const role_controller_js_1 = require("./role/role.controller.js");
+const user_service_js_1 = require("./user/user.service.js");
+const user_controller_js_1 = require("./user/user.controller.js");
+const membership_controller_js_1 = require("./membership/membership.controller.js");
+const membership_service_js_1 = require("./membership/membership.service.js");
+const posting_service_js_1 = require("./membership/posting.service.js");
+const org_catalog_controller_js_1 = require("./org-structure/org-catalog.controller.js");
+const org_catalog_service_js_1 = require("./org-structure/org-catalog.service.js");
+const record_resolver_js_1 = require("./shared/record-resolver.js");
+const posting_version_bump_js_1 = require("./membership/posting-version-bump.js");
+const permission_version_bumper_js_1 = require("./authz/permission-version.bumper.js");
+const record_authorization_js_1 = require("./authz/record-authorization.js");
+const db_permission_facts_adapter_js_1 = require("./authz/db-permission-facts.adapter.js");
+const access_bundle_store_js_1 = require("./authz/access-bundle-store.js");
+const grant_admin_service_js_1 = require("./authz/grant-admin.service.js");
+const grant_admin_controller_js_1 = require("./authz/grant-admin.controller.js");
+const catalog_reconcile_job_js_1 = require("./authz/catalog-reconcile.job.js");
+const access_bundle_reconcile_job_js_1 = require("./authz/access-bundle-reconcile.job.js");
+const catalog_bootstrap_provider_js_1 = require("./authz/catalog-bootstrap.provider.js");
+const mariadb_audit_reader_js_1 = require("./audit/mariadb-audit-reader.js");
+const directory_label_resolver_js_1 = require("./audit/directory-label-resolver.js");
+const audit_read_service_js_1 = require("./audit/audit-read.service.js");
+const audit_controller_js_1 = require("./audit/audit.controller.js");
+const cross_tenant_grant_read_service_js_1 = require("./cross-tenant/cross-tenant-grant-read.service.js");
+const cross_tenant_grant_controller_js_1 = require("./cross-tenant/cross-tenant-grant.controller.js");
+const grant_authorize_js_1 = require("./cross-tenant/grant-authorize.js");
+/** Map guard's env DbConfig → the engine's EngineDbConfig (adds the pool cap the engine needs). */
+function engineDbFromEnv() {
+    const db = (0, guard_1.loadDbConfig)();
+    return {
+        host: db.host,
+        port: db.port,
+        user: db.user,
+        password: db.password,
+        database: db.database,
+        // The engine's runtime CRUD pool cap. A conservative default; the app can raise it later via
+        // an explicit EngineModule.forRoot if it needs more. (ADR-0018 budget lives app-side.)
+        connectionLimit: Number(process.env.APP_DB_MAX_CONNECTIONS ?? 10),
+    };
+}
+/**
+ * IdentityFeatureModule — the framework-owned identity FEATURE surface (company/user/role CRUD;
+ * more in later phases) as thin controllers over the engine's RecordsService. The CONSUMER imports
+ * `IdentityFeatureModule.forRoot()` alongside `ShieldModule.forRoot(...)` (ADR-0026) — @astram/guard
+ * never imports @astram/identity. `forRoot()` SELF-WIRES the engine (EngineModule.forRoot over the
+ * app's APP_DB_* env) + registers the identity objects + mounts the CRUD routes, so the consumer
+ * needs no separate engine setup.
+ *
+ * CONTROLLER ORDER: RoleController is kept ahead of any future grant-admin controller (Phase 4) with
+ * a conflicting `GET identity/roles/:uuid` path — a Nest route-precedence constraint.
+ */
+let IdentityFeatureModule = IdentityFeatureModule_1 = class IdentityFeatureModule {
+    /**
+     * @param rootIds the framework's root allowlist — pass the SAME array given to
+     *   `ShieldModule.forRoot({ rootIds })`. It seeds the cross-tenant grant writer's
+     *   `isRoot` closure so a root caller who passes the route guard is not then denied
+     *   by the writer's own `decide()` (a route-allows/writer-denies split). Omitted ⇒
+     *   `isRoot` is always false (a non-root consumer works; only a root offering
+     *   cross-tenant grants needs it). See ADR-0026 + the template wiring.
+     */
+    static forRoot({ rootIds } = {}) {
+        // ONE shared shield_authz pool for the whole grant-admin stack (ADR-0011): the
+        // permission-version bumper, the AccessBundleStore, the GrantAdminService, and the two
+        // reconcile jobs all run over this single pool (don't open several). Opened once at
+        // forRoot() (not import time) — mirrors the pre-existing bump-pool pattern.
+        const authzPool = (0, record_authorization_js_1.createIdentityAuthzPool)();
+        const bumper = new permission_version_bumper_js_1.PermissionVersionBumper();
+        const postingVersionBump = {
+            bumpTenant: (tenantUuid) => bumper.bumpForTenant(tenantUuid, authzPool),
+        };
+        // The grant-admin collaborators built at forRoot() over the shared pool (mirrors the
+        // postingVersionBump closure pattern above).
+        const accessBundleStore = new access_bundle_store_js_1.AccessBundleStore(authzPool);
+        const grantAdminService = new grant_admin_service_js_1.GrantAdminService(authzPool, bumper, accessBundleStore);
+        // The core ModuleRegistry the catalog reconcile job needs, built from the identity
+        // object registrations (guard's bridge reflects decorated classes → registry).
+        const identityRegistry = (0, guard_1.buildIdentityModuleRegistry)([...objects_js_1.identityObjects]);
+        // Audit viewer (Phase 5): the AuditReader + LabelResolver over the SAME shared authzPool
+        // (the reader queries shield_audit + the resolver/actor-lookup query shield_app, both
+        // reachable by that pool). `auditNameToId` is the actor-name -> uuid reverse lookup for the
+        // actor filter (astram3's exact closure). A mariadb Pool.query(sql, params) structurally
+        // satisfies the reader/resolver's `AuditQueryable` — pass authzPool directly. Built at
+        // forRoot() (not via Nest DI) because it needs the hand-built pool, then provided useValue.
+        const auditReader = new mariadb_audit_reader_js_1.MariaDbAuditReader(authzPool);
+        const auditLabels = new directory_label_resolver_js_1.DirectoryLabelResolver(authzPool);
+        const auditNameToId = async (name) => {
+            const rows = (await authzPool.query('SELECT u_uuid AS id FROM `shield_app`.`users` WHERE u_username = ? LIMIT 1', [name]));
+            return rows[0]?.id ?? null;
+        };
+        const auditReadService = new audit_read_service_js_1.AuditReadService(auditReader, auditLabels, auditNameToId);
+        // Cross-tenant grants (Phase 6): the ENTIRE offer/accept/revoke surface, SELF-WIRED here
+        // over the SAME shared authzPool (no consumer code — astram3 hand-built this in its consumer
+        // authz.module, the anti-pattern this replaces). A SECOND DecisionAuthority is built over the
+        // same record-authorization inputs (matches astram3): the route guard's own decide() is the
+        // first; this one backs the writer's server-side re-verification.
+        const crossTenantAuthority = (0, guard_1.buildRecordAuthorization)((0, record_authorization_js_1.buildIdentityRecordAuthorization)(authzPool));
+        // The writer's `GrantAuthorizeFn`: decide()-backed, fail-closed (no try/catch — a throw
+        // propagates and the writer maps it to a retryable 503). isRoot ← the SAME rootIds the
+        // consumer passes to ShieldModule.forRoot (root-correctness for control-plane grants).
+        const authorizeCrossTenantGrant = (0, grant_authorize_js_1.makeAuthorizeCrossTenantGrant)({
+            authority: crossTenantAuthority,
+            readRoleIds: (principalId, tenantId) => (0, db_permission_facts_adapter_js_1.readRoleIdsForTenant)(authzPool, principalId, tenantId),
+            isRoot: (principalId) => (rootIds ?? []).includes(principalId),
+        });
+        // Audit bridge: map guard's `GrantAuditEvent` → the engine's `MariaDbAuditSink` (the SAME
+        // shield_audit.audit_log sink Phase 5's reader reads). The engine sink's `record(event, query)`
+        // takes a SECOND query fn (its rows commit on the pipe's txn); guard's `GrantAuditSink.record`
+        // takes ONE arg — so we adapt, running the write on the shared pool. The engine AuditEvent's
+        // `action` is an `Action` object (`{ key }`), while guard's is a 'grant.*' string — wrap it.
+        // AUDIT-ON-BOTH (ADR-0009 / invariant #6): a cross-tenant grant lifecycle event is filed under
+        // BOTH the owning tenant's AND the grantee tenant's audit trail — one row each — so a
+        // tenant-scoped auditor on EITHER side sees the event (a grantee-tenant auditor must see a
+        // grant accepted INTO their tenant, not just the owner's trail). Same tenant id twice (should
+        // never happen for a cross-tenant grant) is de-duped to ONE row.
+        // BEST-EFFORT: a throw here must NEVER fail the lifecycle write (the writer already swallows a
+        // sink throw; we also guard here so a mapping/DB error is inert).
+        const grantAuditSink = new engine_1.MariaDbAuditSink({}); // defaults: shield_audit.audit_log
+        const grantAudit = {
+            record: async (event) => {
+                try {
+                    const tenantIds = event.granteeTenantId && event.granteeTenantId !== event.owningTenantId
+                        ? [event.owningTenantId, event.granteeTenantId]
+                        : [event.owningTenantId];
+                    for (const tenantId of tenantIds) {
+                        await grantAuditSink.record({
+                            type: 'authentication',
+                            occurredAtMs: event.occurredAtMs,
+                            actorId: event.actorId,
+                            tenantId,
+                            action: { key: event.action },
+                            attributes: {
+                                ...event.attributes,
+                                owningTenantId: event.owningTenantId,
+                                granteeTenantId: event.granteeTenantId,
+                            },
+                        }, (sql, params) => authzPool.query(sql, params));
+                    }
+                }
+                catch {
+                    // Best-effort: an audit failure must not fail a legitimate lifecycle operation.
+                }
+            },
+        };
+        const crossTenantGrantWriter = new guard_1.CrossTenantGrantWriter({
+            db: authzPool,
+            authorize: authorizeCrossTenantGrant,
+            audit: grantAudit,
+        });
+        // The read side (inbox/mine/incoming/offerable-types) over the same pool + the merged object
+        // set (offerable = tenantScoped types only) + the per-type action vocabulary.
+        const crossTenantGrantReadService = new cross_tenant_grant_read_service_js_1.CrossTenantGrantReadService(authzPool, [...objects_js_1.identityObjects], guard_1.actionsFor);
+        return {
+            module: IdentityFeatureModule_1,
+            imports: [
+                // Collect the 3 identity access bundles into ENGINE_ALL_ACCESS_BUNDLES: forRoot does
+                // NOT take `accessBundles` — only forFeature accumulates them (engine.module.ts). MUST
+                // run BEFORE EngineModule.forRoot() below: `imports` array elements evaluate
+                // left-to-right, and forRoot's body snapshots the accumulator SYNCHRONOUSLY at call
+                // time (not in a DI factory) — so forFeature has to push into it first, or the
+                // snapshot is empty and no bundles reconcile into shield_authz.access_bundle.
+                engine_1.EngineModule.forFeature([], { accessBundles: index_js_1.identityAccessBundles }),
+                // The engine's runtime CRUD pipe + the identity object registrations.
+                engine_1.EngineModule.forRoot({ db: engineDbFromEnv(), registrations: [...objects_js_1.identityObjects] }),
+                // NestJS DiscoveryService/MetadataScanner — the boot bootstrap provider reflects the
+                // live controllers through this to build the OperationInventory.
+                core_1.DiscoveryModule,
+            ],
+            // Route order: RoleController stays AHEAD of GrantAdminController (documented Nest
+            // route-precedence constraint — the summary route `access/role-grants` dodges
+            // `roles/:uuid`, but Role is registered first regardless).
+            controllers: [
+                company_controller_js_1.CompanyController,
+                role_controller_js_1.RoleController,
+                grant_admin_controller_js_1.GrantAdminController,
+                user_controller_js_1.UserController,
+                membership_controller_js_1.MembershipController,
+                org_catalog_controller_js_1.OrgCatalogController,
+                // `identity/audit` collides with no other route — order-independent; appended last.
+                audit_controller_js_1.AuditController,
+                // Cross-tenant grants — its `cross-tenant-grants/*` paths collide with nothing; the
+                // controller's own method order keeps the static sub-paths (/inbox, /offerable-types)
+                // ahead of `/:uuid/*`. Appended after the existing controllers.
+                cross_tenant_grant_controller_js_1.CrossTenantGrantController,
+            ],
+            providers: [
+                company_service_js_1.CompanyService,
+                role_service_js_1.RoleService,
+                user_service_js_1.UserService,
+                membership_service_js_1.MembershipService,
+                posting_service_js_1.PostingService,
+                org_catalog_service_js_1.OrgCatalogService,
+                record_resolver_js_1.RecordResolverService,
+                { provide: posting_version_bump_js_1.POSTING_VERSION_BUMP, useValue: postingVersionBump },
+                // Grant-admin stack — all over the ONE shared authzPool.
+                { provide: access_bundle_store_js_1.AccessBundleStore, useValue: accessBundleStore },
+                { provide: grant_admin_service_js_1.GrantAdminService, useValue: grantAdminService },
+                // Audit read stack — built at forRoot() over the ONE shared authzPool, provided as a
+                // useValue (like GrantAdminService) so it carries the hand-built reader/resolver/lookup.
+                { provide: audit_read_service_js_1.AuditReadService, useValue: auditReadService },
+                // Cross-tenant grant stack (Phase 6) — the writer + read service, both over the ONE
+                // shared authzPool, provided useValue so the controller injects them with no consumer
+                // wiring (the out-of-the-box acceptance bar).
+                { provide: guard_1.SHIELD_CROSS_TENANT_GRANT_WRITER, useValue: crossTenantGrantWriter },
+                { provide: cross_tenant_grant_read_service_js_1.CrossTenantGrantReadService, useValue: crossTenantGrantReadService },
+                // The mutating half of auto-catalog: a single CatalogReconcileJob (post-boot pass +
+                // cron), over the shared pool + the identity registry.
+                { provide: catalog_reconcile_job_js_1.CatalogReconcileJob, useValue: new catalog_reconcile_job_js_1.CatalogReconcileJob(authzPool, identityRegistry) },
+                // The bundle half: reconciles the merged AccessBundleSpec[] (ENGINE_ALL_ACCESS_BUNDLES,
+                // reflected by the engine from identityAccessBundles) into shield_authz.access_bundle.
+                {
+                    provide: access_bundle_reconcile_job_js_1.AccessBundleReconcileJob,
+                    useFactory: (bundles) => new access_bundle_reconcile_job_js_1.AccessBundleReconcileJob(authzPool, bundles),
+                    inject: [engine_1.ENGINE_ALL_ACCESS_BUNDLES],
+                },
+                // Boot: read-only verifyGatable (fail-closed). Post-boot: kicks the jobs once (catalog
+                // THEN bundles) + schedules them (DISABLE_ALL_CRONS-gated). Injects DiscoveryService/
+                // MetadataScanner/Reflector (from DiscoveryModule above), the two jobs, and
+                // ENGINE_ALL_REGISTRATIONS (exported by EngineModule).
+                catalog_bootstrap_provider_js_1.CatalogBootstrapProvider,
+            ],
+            exports: [company_service_js_1.CompanyService, role_service_js_1.RoleService, user_service_js_1.UserService],
+        };
+    }
+};
+exports.IdentityFeatureModule = IdentityFeatureModule;
+exports.IdentityFeatureModule = IdentityFeatureModule = IdentityFeatureModule_1 = __decorate([
+    (0, common_1.Module)({})
+], IdentityFeatureModule);

package/dist/features/membership/membership.controller.d.ts

@@ -0,0 +1,77 @@
+import { MembershipService } from './membership.service.js';
+import { PostingService, type PostingInput } from './posting.service.js';
+import { RecordResolverService } from '../shared/record-resolver.js';
+/** A membership card for the API, with EVERY uuid resolved to a display name. */
+interface MembershipCardDto {
+    /** The membership id — used as a route param / react key, NEVER as a display field. */
+    membershipUuid: string;
+    companyUuid: string;
+    companyName: string;
+    isActive: boolean;
+    status: string;
+    postings: PostingCardDto[];
+}
+/** A posting for the API, with role/dept/branch uuids resolved to names. */
+interface PostingCardDto {
+    postingUuid: string;
+    roleUuid: string;
+    roleName: string;
+    departmentUuid: string | null;
+    departmentName: string | null;
+    branchUuid: string | null;
+    branchName: string | null;
+    /** Effective-window bounds as epoch-ms (BIGINT storage), or null = open-ended. */
+    effectiveFrom: number | null;
+    effectiveUntil: number | null;
+}
+export declare class MembershipController {
+    private readonly memberships;
+    private readonly postings;
+    private readonly resolver;
+    constructor(memberships: MembershipService, postings: PostingService, resolver: RecordResolverService);
+    /**
+     * The user's membership cards + their postings, with EVERY uuid resolved to a display
+     * NAME (companyName / roleName / departmentName / branchName). Raw `*_uuid` values are
+     * returned ONLY as ids/params for the client to key/route on — never as a display
+     * field. This is the non-negotiable no-raw-UUID rule enforced server-side.
+     */
+    listUserMemberships(userUuid: string): Promise<{
+        memberships: MembershipCardDto[];
+    }>;
+    /** Add the user to a company (creates an inactive membership card). */
+    addUserMembership(userUuid: string, body: {
+        companyUuid?: string;
+    }): Promise<{
+        id: import("@astram/engine").RecordId;
+    }>;
+    /**
+     * Update a membership — `isActive` flips activation through `setActive` (the one-active
+     * invariant); `status` is a plain field update. Activating requires the owning user so
+     * the invariant can deactivate the user's OTHER memberships.
+     */
+    updateMembership(membershipUuid: string, body: {
+        isActive?: boolean;
+        status?: string;
+        userUuid?: string;
+    }): Promise<{
+        success: boolean;
+    }>;
+    /** Remove a membership card (its postings cascade at the DB). */
+    removeMembership(membershipUuid: string): Promise<{
+        success: boolean;
+    }>;
+    /** Atomically replace a membership's full posting set (the diff sync). */
+    replacePostings(membershipUuid: string, body: {
+        postings?: PostingInput[];
+    }): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Resolve a record's display name via the RecordsService facade (`resolver.getRecord`), falling back to
+     * `(unknown)` for a missing/deleted record — NEVER leaking the uuid as the label. Used
+     * only to build human-readable membership/posting cards (rule: no raw UUIDs in the UI).
+     */
+    private resolveName;
+}
+export {};
+//# sourceMappingURL=membership.controller.d.ts.map

package/dist/features/membership/membership.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"membership.controller.d.ts","sourceRoot":"","sources":["../../../src/features/membership/membership.controller.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,KAAK,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAGrE,iFAAiF;AACjF,UAAU,iBAAiB;IACzB,uFAAuF;IACvF,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,cAAc,EAAE,CAAC;CAC5B;AAED,4EAA4E;AAC5E,UAAU,cAAc;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,kFAAkF;IAClF,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AASD,qBACa,oBAAoB;IAE7B,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAFR,WAAW,EAAE,iBAAiB,EAC9B,QAAQ,EAAE,cAAc,EACxB,QAAQ,EAAE,qBAAqB;IAGlD;;;;;OAKG;IAGG,mBAAmB,CAAoB,QAAQ,EAAE,MAAM;;;IA0C7D,uEAAuE;IAGjE,iBAAiB,CACF,QAAQ,EAAE,MAAM,EAC3B,IAAI,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE;;;IAMxC;;;;OAIG;IAGG,gBAAgB,CACK,cAAc,EAAE,MAAM,EACvC,IAAI,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE;;;IAc1E,iEAAiE;IAG3D,gBAAgB,CAA0B,cAAc,EAAE,MAAM;;;IAKtE,0EAA0E;IAGpE,eAAe,CACM,cAAc,EAAE,MAAM,EACvC,IAAI,EAAE;QAAE,QAAQ,CAAC,EAAE,YAAY,EAAE,CAAA;KAAE;;;IAM7C;;;;OAIG;YACW,WAAW;CAM1B"}

package/dist/features/membership/membership.controller.js

@@ -0,0 +1,174 @@
+"use strict";
+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);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MembershipController = void 0;
+const common_1 = require("@nestjs/common");
+const guard_1 = require("@astram/guard");
+const membership_service_js_1 = require("./membership.service.js");
+const posting_service_js_1 = require("./posting.service.js");
+const record_resolver_js_1 = require("../shared/record-resolver.js");
+const http_js_1 = require("../shared/http.js");
+// ── Memberships + postings ───────────────────────────────────────────────────
+//
+// Gated on the `company_membership` / `membership_posting` grants via `@Classified`
+// + the engine's mandatory in-pipe gate. Both are DATA-plane types, so the capped root
+// is denied them by construction — the membership admin surface is grant-driven, not
+// root-driven. Real per-company-admin scoping is a later permission-engine concern.
+let MembershipController = class MembershipController {
+    memberships;
+    postings;
+    resolver;
+    constructor(memberships, postings, resolver) {
+        this.memberships = memberships;
+        this.postings = postings;
+        this.resolver = resolver;
+    }
+    /**
+     * The user's membership cards + their postings, with EVERY uuid resolved to a display
+     * NAME (companyName / roleName / departmentName / branchName). Raw `*_uuid` values are
+     * returned ONLY as ids/params for the client to key/route on — never as a display
+     * field. This is the non-negotiable no-raw-UUID rule enforced server-side.
+     */
+    async listUserMemberships(userUuid) {
+        const rows = await this.memberships.listMemberships(userUuid);
+        const cards = [];
+        for (const m of rows) {
+            const membershipUuid = typeof m.id === 'string' ? m.id : String(m.id);
+            const companyUuid = (0, http_js_1.asUuid)(m.fields.companyUuid) ?? '';
+            const postingRows = await this.postings.listPostings(membershipUuid);
+            const postings = [];
+            for (const p of postingRows) {
+                const roleUuid = (0, http_js_1.asUuid)(p.fields.roleUuid) ?? '';
+                const departmentUuid = (0, http_js_1.asUuid)(p.fields.departmentUuid);
+                const branchUuid = (0, http_js_1.asUuid)(p.fields.branchUuid);
+                postings.push({
+                    postingUuid: typeof p.id === 'string' ? p.id : String(p.id),
+                    roleUuid,
+                    roleName: await this.resolveName('role', roleUuid),
+                    departmentUuid,
+                    departmentName: departmentUuid
+                        ? await this.resolveName('department', departmentUuid)
+                        : null,
+                    branchUuid,
+                    branchName: branchUuid ? await this.resolveName('branch', branchUuid) : null,
+                    effectiveFrom: (0, http_js_1.asEpochMs)(p.fields.effectiveFrom),
+                    effectiveUntil: (0, http_js_1.asEpochMs)(p.fields.effectiveUntil),
+                });
+            }
+            cards.push({
+                membershipUuid,
+                companyUuid,
+                companyName: companyUuid ? await this.resolveName('company', companyUuid) : '(unknown)',
+                isActive: Boolean(m.fields.isActive),
+                status: typeof m.fields.status === 'string' ? m.fields.status : 'active',
+                postings,
+            });
+        }
+        return { memberships: cards };
+    }
+    /** Add the user to a company (creates an inactive membership card). */
+    async addUserMembership(userUuid, body) {
+        const id = await this.memberships.addMembership(userUuid, body?.companyUuid ?? '');
+        return { id };
+    }
+    /**
+     * Update a membership — `isActive` flips activation through `setActive` (the one-active
+     * invariant); `status` is a plain field update. Activating requires the owning user so
+     * the invariant can deactivate the user's OTHER memberships.
+     */
+    async updateMembership(membershipUuid, body) {
+        if (body?.isActive === true) {
+            if (!body.userUuid) {
+                throw new common_1.ForbiddenException('userUuid is required to activate a membership');
+            }
+            await this.memberships.setActive(membershipUuid, body.userUuid);
+        }
+        if (typeof body?.status === 'string') {
+            await this.memberships.updateMembership(membershipUuid, { status: body.status });
+        }
+        return { success: true };
+    }
+    /** Remove a membership card (its postings cascade at the DB). */
+    async removeMembership(membershipUuid) {
+        await this.memberships.removeMembership(membershipUuid);
+        return { success: true };
+    }
+    /** Atomically replace a membership's full posting set (the diff sync). */
+    async replacePostings(membershipUuid, body) {
+        await this.postings.replacePostings(membershipUuid, body?.postings ?? []);
+        return { success: true };
+    }
+    /**
+     * Resolve a record's display name via the RecordsService facade (`resolver.getRecord`), falling back to
+     * `(unknown)` for a missing/deleted record — NEVER leaking the uuid as the label. Used
+     * only to build human-readable membership/posting cards (rule: no raw UUIDs in the UI).
+     */
+    async resolveName(typeKey, uuid) {
+        if (!uuid)
+            return '(unknown)';
+        const view = await this.resolver.getRecord(typeKey, uuid);
+        const name = view?.fields?.name;
+        return typeof name === 'string' && name.length > 0 ? name : '(unknown)';
+    }
+};
+exports.MembershipController = MembershipController;
+__decorate([
+    (0, common_1.Get)('users/:userUuid/memberships'),
+    (0, guard_1.Classified)({ typeKey: 'company_membership', action: 'read' }),
+    __param(0, (0, common_1.Param)('userUuid')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", Promise)
+], MembershipController.prototype, "listUserMemberships", null);
+__decorate([
+    (0, common_1.Post)('users/:userUuid/memberships'),
+    (0, guard_1.Classified)({ typeKey: 'company_membership', action: 'create' }),
+    __param(0, (0, common_1.Param)('userUuid')),
+    __param(1, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object]),
+    __metadata("design:returntype", Promise)
+], MembershipController.prototype, "addUserMembership", null);
+__decorate([
+    (0, common_1.Put)('memberships/:membershipUuid'),
+    (0, guard_1.Classified)({ typeKey: 'company_membership', action: 'update' }),
+    __param(0, (0, common_1.Param)('membershipUuid')),
+    __param(1, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object]),
+    __metadata("design:returntype", Promise)
+], MembershipController.prototype, "updateMembership", null);
+__decorate([
+    (0, common_1.Delete)('memberships/:membershipUuid'),
+    (0, guard_1.Classified)({ typeKey: 'company_membership', action: 'delete' }),
+    __param(0, (0, common_1.Param)('membershipUuid')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", Promise)
+], MembershipController.prototype, "removeMembership", null);
+__decorate([
+    (0, common_1.Put)('memberships/:membershipUuid/postings'),
+    (0, guard_1.Classified)({ typeKey: 'membership_posting', action: 'update' }),
+    __param(0, (0, common_1.Param)('membershipUuid')),
+    __param(1, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object]),
+    __metadata("design:returntype", Promise)
+], MembershipController.prototype, "replacePostings", null);
+exports.MembershipController = MembershipController = __decorate([
+    (0, common_1.Controller)('identity'),
+    __metadata("design:paramtypes", [membership_service_js_1.MembershipService,
+        posting_service_js_1.PostingService,
+        record_resolver_js_1.RecordResolverService])
+], MembershipController);

package/dist/features/membership/membership.service.d.ts

@@ -0,0 +1,73 @@
+/**
+ * MembershipService — the membership layer's write/read logic, built ENTIRELY on the
+ * injected RecordsService facade (which supplies the request principal and runs each op
+ * through the engine pipe). It never touches a pool, query runner, or raw SQL — every op
+ * is one-or-more facade calls, so the permission gate + anti-forgery write-context +
+ * audit + cross-tenant isolation are applied automatically.
+ *
+ * A `company_membership` is the first-class `(user, company)` scope with `is_active`
+ * (exactly one active per user) + `status`. This service owns the ONE invariant the DB
+ * cannot express — one-active-per-user — because there is no partial-unique on
+ * `cm_is_active`; `setActive` is the guard.
+ */
+import { RecordsService, type RecordId, type RecordView } from '@astram/engine';
+import { type PostingVersionBump } from './posting-version-bump.js';
+export declare class MembershipService {
+    private readonly records;
+    private readonly versionBump?;
+    constructor(records: RecordsService, versionBump?: (PostingVersionBump | null) | undefined);
+    /**
+     * Read a membership's tenant (its `companyUuid`) through the pipe, or `null` when
+     * unresolvable (→ no bump; fail-safe, never guesses a tenant). Used to target the
+     * permission-version bump at the company whose coarse grants a mutation changed.
+     */
+    private tenantOf;
+    /**
+     * Bump the permission version for each DISTINCT tenant in `tenantUuids` (best-effort +
+     * fail-safe): the mutation already succeeded, so a bump hiccup must NOT surface as an
+     * error that hides a successful membership change — the cache is invalidated by the next
+     * legit bump / the facts' natural TTL instead. No collaborator wired → no-op (prior
+     * behavior). `null`/empty entries are skipped (never bump a guessed tenant).
+     */
+    private bumpTenants;
+    /**
+     * Add a membership card for `(userUuid, companyUuid)`. New memberships are created
+     * INACTIVE (`isActive:false`) — activation is an explicit `setActive` call so the
+     * one-active invariant is never violated by a fresh add. A duplicate `(user, company)`
+     * hits the DB's UNIQUE constraint and the engine's error surfaces to the caller (NOT
+     * swallowed here). `createdBy` is stamped server-side (actorId-trusted).
+     */
+    addMembership(userUuid: string, companyUuid: string): Promise<RecordId>;
+    /** List a user's membership cards (tenant-scoped by the pipe). */
+    listMemberships(userUuid: string): Promise<readonly RecordView[]>;
+    /**
+     * Flip which of the user's memberships is active — the ONE-ACTIVE invariant. The service
+     * is the guard because the DB has no partial-unique on `cm_is_active`.
+     *
+     * ⚠️ ORDER IS LOAD-BEARING (fail-safe against a LOGIN LOCKOUT). The engine's `list` has
+     * no ORDER BY (PKs are random uuids → arbitrary row order) and each `update` is its OWN
+     * transaction (no cross-call atomicity). So this MUST activate the TARGET FIRST, then
+     * deactivate the others:
+     *   - Worst case of a mid-loop failure is then a transient TWO-active window, which is
+     *     RECOVERABLE — the credential resolver reads `is_active=1 LIMIT 1`, so it still
+     *     resolves a tenant and login works.
+     *   - The forbidden alternative (deactivate-old-then-activate-target) can leave a
+     *     ZERO-active window on a mid-failure → the resolver returns null → the user is
+     *     LOCKED OUT of login until an admin re-activates. Never do that.
+     *
+     * Guard: if `membershipUuid` is NOT one of the user's memberships, throw — otherwise the
+     * loop would deactivate everything and activate nothing (also a zero-active lockout).
+     */
+    setActive(membershipUuid: string, userUuid: string): Promise<void>;
+    /**
+     * Update a membership's mutable non-activity fields (currently `status`). Activity is
+     * flipped only via `setActive` to preserve the one-active invariant, so `isActive` is
+     * intentionally NOT a patch key here.
+     */
+    updateMembership(membershipUuid: string, patch: {
+        status?: string;
+    }): Promise<void>;
+    /** Remove a membership card (its postings cascade at the DB via FK ON DELETE CASCADE). */
+    removeMembership(membershipUuid: string): Promise<void>;
+}
+//# sourceMappingURL=membership.service.d.ts.map

package/dist/features/membership/membership.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"membership.service.d.ts","sourceRoot":"","sources":["../../../src/features/membership/membership.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,cAAc,EAAE,KAAK,QAAQ,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAChF,OAAO,EAAwB,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE1F,qBACa,iBAAiB;IAE1B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAQxB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;gBARZ,OAAO,EAAE,cAAc,EAQvB,WAAW,CAAC,GAAE,kBAAkB,GAAG,IAAI,aAAA;IAG1D;;;;OAIG;YACW,QAAQ;IAUtB;;;;;;OAMG;YACW,WAAW;IAYzB;;;;;;OAMG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAMvE,kEAAkE;IAC5D,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC;IAKvE;;;;;;;;;;;;;;;;;OAiBG;IACG,SAAS,CAAC,cAAc,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAqCxE;;;;OAIG;IACH,gBAAgB,CAAC,cAAc,EAAE,MAAM,EAAE,KAAK,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAWnF,0FAA0F;IACpF,gBAAgB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAU9D"}