@astram/identity 0.1.1 → 0.2.0

package/dist/features/role/role.controller.js

@@ -0,0 +1,104 @@
+"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.RoleController = void 0;
+const common_1 = require("@nestjs/common");
+const guard_1 = require("@astram/guard");
+const role_service_js_1 = require("./role.service.js");
+const list_query_js_1 = require("../shared/list-query.js");
+// Role management is gated on `identity:role:<action>` grants. `role` is CONTROL-plane
+// for ALL actions — including read: the capped root is the identity administrator (the
+// identity-administrator model), so it may list/read roles AND manage them.
+let RoleController = class RoleController {
+    roles;
+    constructor(roles) {
+        this.roles = roles;
+    }
+    /**
+     * List roles — gated on `identity:role:read` (see class doc). Server-side DataTable:
+     * `?page&limit&search&sortBy&sortOrder`. Returns `{ total, rows, page, limit }` —
+     * `total` reflects the FILTERED set so the client can page the true result count.
+     */
+    async listRoles(query) {
+        const { page, limit, params } = (0, list_query_js_1.parseListQuery)(query);
+        const result = await this.roles.listRoles(params);
+        return { total: result.total, rows: result.rows, page, limit };
+    }
+    /** Create a role — gated on `identity:role:create`. */
+    async createRole(body) {
+        const id = await this.roles.createRole(body?.name ?? 'Untitled');
+        return { id };
+    }
+    /** Read one role — gated on `identity:role:read` (CONTROL-plane; root, the identity
+     *  administrator, may read roles). */
+    getRole(uuid) {
+        return this.roles.getRole(uuid);
+    }
+    /** Update a role — gated on `identity:role:update`. */
+    async updateRole(uuid, body) {
+        await this.roles.updateRole(uuid, body ?? {});
+        return { success: true };
+    }
+    /** Delete a role — gated on `identity:role:delete`. */
+    async deleteRole(uuid) {
+        await this.roles.deleteRole(uuid);
+        return { success: true };
+    }
+};
+exports.RoleController = RoleController;
+__decorate([
+    (0, common_1.Get)('roles'),
+    (0, guard_1.Classified)({ typeKey: 'role', action: 'read' }),
+    __param(0, (0, common_1.Query)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], RoleController.prototype, "listRoles", null);
+__decorate([
+    (0, common_1.Post)('roles'),
+    (0, guard_1.Classified)({ typeKey: 'role', action: 'create' }),
+    __param(0, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], RoleController.prototype, "createRole", null);
+__decorate([
+    (0, common_1.Get)('roles/:uuid'),
+    (0, guard_1.Classified)({ typeKey: 'role', action: 'read' }),
+    __param(0, (0, common_1.Param)('uuid')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", void 0)
+], RoleController.prototype, "getRole", null);
+__decorate([
+    (0, common_1.Put)('roles/:uuid'),
+    (0, guard_1.Classified)({ typeKey: 'role', action: 'update' }),
+    __param(0, (0, common_1.Param)('uuid')),
+    __param(1, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object]),
+    __metadata("design:returntype", Promise)
+], RoleController.prototype, "updateRole", null);
+__decorate([
+    (0, common_1.Delete)('roles/:uuid'),
+    (0, guard_1.Classified)({ typeKey: 'role', action: 'delete' }),
+    __param(0, (0, common_1.Param)('uuid')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", Promise)
+], RoleController.prototype, "deleteRole", null);
+exports.RoleController = RoleController = __decorate([
+    (0, common_1.Controller)('identity'),
+    __metadata("design:paramtypes", [role_service_js_1.RoleService])
+], RoleController);

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

@@ -0,0 +1,24 @@
+import { RecordsService, type RecordId } from '@astram/engine';
+import { type ListParams } from '../shared/list-query.js';
+/**
+ * RoleService — role CRUD on the paved road, via the framework's RecordsService
+ * facade. The facade supplies the acting identity (the request principal) —
+ * this service never threads a Principal. No raw SQL, no RECORD_ENGINE.
+ */
+export declare class RoleService {
+    private readonly records;
+    constructor(records: RecordsService);
+    /** Create a role. */
+    createRole(name: string): Promise<RecordId>;
+    /** List roles (tenant-scoped by the pipe), with paging/search/sort. */
+    listRoles(params?: ListParams): Promise<import("@astram/engine").RecordPage>;
+    /** Read a single role. */
+    getRole(uuid: string): Promise<import("@astram/engine").RecordView | null>;
+    /** Update a role. */
+    updateRole(uuid: string, patch: {
+        name?: string;
+    }): Promise<void>;
+    /** Delete a role. */
+    deleteRole(uuid: string): Promise<void>;
+}
+//# sourceMappingURL=role.service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"role.service.d.ts","sourceRoot":"","sources":["../../../src/features/role/role.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAK1E;;;;GAIG;AACH,qBACa,WAAW;IACV,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,cAAc;IAEpD,qBAAqB;IACrB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAI3C,uEAAuE;IACvE,SAAS,CAAC,MAAM,CAAC,EAAE,UAAU;IAI7B,0BAA0B;IAC1B,OAAO,CAAC,IAAI,EAAE,MAAM;IAIpB,qBAAqB;IACrB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjE,qBAAqB;IACrB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGxC"}

package/dist/features/role/role.service.js

@@ -0,0 +1,53 @@
+"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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RoleService = void 0;
+const common_1 = require("@nestjs/common");
+const engine_1 = require("@astram/engine");
+const list_query_js_1 = require("../shared/list-query.js");
+const ROLE_SEARCH_FIELDS = ['name'];
+const ROLE_SORT_FIELDS = ['name', 'createdAt'];
+/**
+ * RoleService — role CRUD on the paved road, via the framework's RecordsService
+ * facade. The facade supplies the acting identity (the request principal) —
+ * this service never threads a Principal. No raw SQL, no RECORD_ENGINE.
+ */
+let RoleService = class RoleService {
+    records;
+    constructor(records) {
+        this.records = records;
+    }
+    /** Create a role. */
+    createRole(name) {
+        return this.records.create('role', { fields: { name } });
+    }
+    /** List roles (tenant-scoped by the pipe), with paging/search/sort. */
+    listRoles(params) {
+        return this.records.list('role', (0, list_query_js_1.buildListQuery)(params, ROLE_SEARCH_FIELDS, ROLE_SORT_FIELDS));
+    }
+    /** Read a single role. */
+    getRole(uuid) {
+        return this.records.get('role', uuid);
+    }
+    /** Update a role. */
+    updateRole(uuid, patch) {
+        return this.records.update('role', uuid, { fields: patch });
+    }
+    /** Delete a role. */
+    deleteRole(uuid) {
+        return this.records.delete('role', uuid);
+    }
+};
+exports.RoleService = RoleService;
+exports.RoleService = RoleService = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [engine_1.RecordsService])
+], RoleService);

package/dist/features/shared/http.d.ts

@@ -0,0 +1,15 @@
+import type { Principal } from '@astram/engine';
+/** The authenticated request shape: the framework guard attaches `principal`. */
+export interface AuthedRequest {
+    principal: Principal;
+}
+/** Coerce an unknown field value to a string uuid or null. */
+export declare function asUuid(v: unknown): string | null;
+/**
+ * Coerce a stored effective-window bound to an epoch-ms number, or null. The
+ * `membership_posting` object stores these as `number` (BIGINT epoch-ms); the mariadb
+ * driver may hand a BIGINT back as a JS `number`, a `bigint`, or a numeric string, so
+ * normalize all three.
+ */
+export declare function asEpochMs(v: unknown): number | null;
+//# sourceMappingURL=http.d.ts.map

package/dist/features/shared/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../../src/features/shared/http.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,iFAAiF;AACjF,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,SAAS,CAAC;CACtB;AAED,8DAA8D;AAC9D,wBAAgB,MAAM,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAEhD;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAQnD"}

package/dist/features/shared/http.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.asUuid = asUuid;
+exports.asEpochMs = asEpochMs;
+/** Coerce an unknown field value to a string uuid or null. */
+function asUuid(v) {
+    return typeof v === 'string' && v.length > 0 ? v : null;
+}
+/**
+ * Coerce a stored effective-window bound to an epoch-ms number, or null. The
+ * `membership_posting` object stores these as `number` (BIGINT epoch-ms); the mariadb
+ * driver may hand a BIGINT back as a JS `number`, a `bigint`, or a numeric string, so
+ * normalize all three.
+ */
+function asEpochMs(v) {
+    if (typeof v === 'number')
+        return Number.isFinite(v) ? v : null;
+    if (typeof v === 'bigint')
+        return Number(v);
+    if (typeof v === 'string' && v.length > 0) {
+        const n = Number(v);
+        return Number.isFinite(n) ? n : null;
+    }
+    return null;
+}

package/dist/features/shared/list-query.d.ts

@@ -0,0 +1,44 @@
+import type { ListQuery } from '@astram/engine';
+/**
+ * A server-side DataTable query for a list method: paging window + optional
+ * free-text search term + optional sort. Every field is optional — an empty
+ * `{}` reproduces the pre-DataTable behavior (engine defaults).
+ */
+export interface ListParams {
+    limit?: number;
+    offset?: number;
+    search?: string;
+    sortBy?: string;
+    sortOrder?: 'asc' | 'desc';
+}
+/**
+ * Build the engine `ListQuery` from a feature `ListParams` + the type's field
+ * allowlists. Search maps to `{ fields, term }` only when the term is non-empty;
+ * `sortBy` is included ONLY when it is one of `sortFields` (a bad key is dropped
+ * so the engine never sees an unknown key → no 500). `limit`/`offset` pass through.
+ */
+export declare function buildListQuery(params: ListParams | undefined, searchFields: readonly string[], sortFields: readonly string[]): ListQuery;
+/** The raw `?page=&limit=&search=&sortBy=&sortOrder=` query bag for a list route. */
+export interface ListQueryDto {
+    page?: string;
+    limit?: string;
+    search?: string;
+    sortBy?: string;
+    sortOrder?: string;
+}
+/** The default + max page size for any DataTable list route. */
+export declare const DEFAULT_LIMIT = 25;
+export declare const MAX_LIMIT = 100;
+/**
+ * Parse the DataTable `?page&limit&search&sortBy&sortOrder` query into a normalized
+ * `{ page, limit, params }`. `page` ≥ 1 (default 1); `limit` clamped [1, MAX_LIMIT]
+ * (default 25); `offset = (page-1)*limit`; `search` trimmed, empty → omitted; `sortBy`
+ * passed through as a string (the SERVICE validates it against the type's sortable
+ * allowlist and ignores an unknown key). `sortOrder` defaults to 'asc'.
+ */
+export declare function parseListQuery(q: ListQueryDto | undefined): {
+    page: number;
+    limit: number;
+    params: ListParams;
+};
+//# sourceMappingURL=list-query.d.ts.map

package/dist/features/shared/list-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-query.d.ts","sourceRoot":"","sources":["../../../src/features/shared/list-query.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;CAC5B;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,UAAU,GAAG,SAAS,EAC9B,YAAY,EAAE,SAAS,MAAM,EAAE,EAC/B,UAAU,EAAE,SAAS,MAAM,EAAE,GAC5B,SAAS,CAkBX;AAED,qFAAqF;AACrF,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,gEAAgE;AAChE,eAAO,MAAM,aAAa,KAAK,CAAC;AAChC,eAAO,MAAM,SAAS,MAAM,CAAC;AAE7B;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,YAAY,GAAG,SAAS,GAAG;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,UAAU,CAAC;CACpB,CAmBA"}

package/dist/features/shared/list-query.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_LIMIT = exports.DEFAULT_LIMIT = void 0;
+exports.buildListQuery = buildListQuery;
+exports.parseListQuery = parseListQuery;
+/**
+ * Build the engine `ListQuery` from a feature `ListParams` + the type's field
+ * allowlists. Search maps to `{ fields, term }` only when the term is non-empty;
+ * `sortBy` is included ONLY when it is one of `sortFields` (a bad key is dropped
+ * so the engine never sees an unknown key → no 500). `limit`/`offset` pass through.
+ */
+function buildListQuery(params, searchFields, sortFields) {
+    const p = params ?? {};
+    const query = {};
+    if (typeof p.limit === 'number')
+        query.limit = p.limit;
+    if (typeof p.offset === 'number')
+        query.offset = p.offset;
+    const term = typeof p.search === 'string' ? p.search.trim() : '';
+    if (term.length > 0)
+        query.search = { fields: [...searchFields], term };
+    if (typeof p.sortBy === 'string' && sortFields.includes(p.sortBy)) {
+        query.sortBy = p.sortBy;
+        query.sortOrder = p.sortOrder === 'desc' ? 'desc' : 'asc';
+    }
+    return query;
+}
+/** The default + max page size for any DataTable list route. */
+exports.DEFAULT_LIMIT = 25;
+exports.MAX_LIMIT = 100;
+/**
+ * Parse the DataTable `?page&limit&search&sortBy&sortOrder` query into a normalized
+ * `{ page, limit, params }`. `page` ≥ 1 (default 1); `limit` clamped [1, MAX_LIMIT]
+ * (default 25); `offset = (page-1)*limit`; `search` trimmed, empty → omitted; `sortBy`
+ * passed through as a string (the SERVICE validates it against the type's sortable
+ * allowlist and ignores an unknown key). `sortOrder` defaults to 'asc'.
+ */
+function parseListQuery(q) {
+    const rawPage = Number.parseInt(q?.page ?? '', 10);
+    const page = Number.isFinite(rawPage) && rawPage >= 1 ? rawPage : 1;
+    const rawLimit = Number.parseInt(q?.limit ?? '', 10);
+    const limit = Number.isFinite(rawLimit) && rawLimit >= 1 ? Math.min(rawLimit, exports.MAX_LIMIT) : exports.DEFAULT_LIMIT;
+    const offset = (page - 1) * limit;
+    const search = typeof q?.search === 'string' ? q.search.trim() : '';
+    const sortBy = typeof q?.sortBy === 'string' && q.sortBy.length > 0 ? q.sortBy : undefined;
+    const sortOrder = q?.sortOrder === 'desc' ? 'desc' : 'asc';
+    const params = { limit, offset, sortOrder };
+    if (search.length > 0)
+        params.search = search;
+    if (sortBy)
+        params.sortBy = sortBy;
+    return { page, limit, params };
+}

package/dist/features/shared/named-option.d.ts

@@ -0,0 +1,6 @@
+/** A UI-safe option: `uuid` is the option value (a param), `name` is the display label. */
+export interface NamedOption {
+    uuid: string;
+    name: string;
+}
+//# sourceMappingURL=named-option.d.ts.map

package/dist/features/shared/named-option.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"named-option.d.ts","sourceRoot":"","sources":["../../../src/features/shared/named-option.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd"}

package/dist/features/shared/named-option.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/features/shared/record-resolver.d.ts

@@ -0,0 +1,11 @@
+import { RecordsService } from '@astram/engine';
+/**
+ * RecordResolverService — resolve a foreign uuid to its display record (name), via the
+ * RecordsService facade (no actor threading). Used to render uuids as names in list DTOs.
+ */
+export declare class RecordResolverService {
+    private readonly records;
+    constructor(records: RecordsService);
+    getRecord(typeKey: string, uuid: string): Promise<import("@astram/engine").RecordView | null>;
+}
+//# sourceMappingURL=record-resolver.d.ts.map

package/dist/features/shared/record-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-resolver.d.ts","sourceRoot":"","sources":["../../../src/features/shared/record-resolver.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;;GAGG;AACH,qBACa,qBAAqB;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,cAAc;IAEpD,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAGxC"}

package/dist/features/shared/record-resolver.js

@@ -0,0 +1,32 @@
+"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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RecordResolverService = void 0;
+const common_1 = require("@nestjs/common");
+const engine_1 = require("@astram/engine");
+/**
+ * RecordResolverService — resolve a foreign uuid to its display record (name), via the
+ * RecordsService facade (no actor threading). Used to render uuids as names in list DTOs.
+ */
+let RecordResolverService = class RecordResolverService {
+    records;
+    constructor(records) {
+        this.records = records;
+    }
+    getRecord(typeKey, uuid) {
+        return this.records.get(typeKey, uuid);
+    }
+};
+exports.RecordResolverService = RecordResolverService;
+exports.RecordResolverService = RecordResolverService = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [engine_1.RecordsService])
+], RecordResolverService);

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

@@ -0,0 +1,39 @@
+import { UserService } from './user.service.js';
+import { type ListQueryDto } from '../shared/list-query.js';
+export declare class UserController {
+    private readonly users;
+    constructor(users: UserService);
+    /**
+     * List users — gated on `identity:user:read` (see class doc). Server-side DataTable:
+     * `?page&limit&search&sortBy&sortOrder`. Returns `{ total, rows, page, limit }` —
+     * `total` reflects the FILTERED set so the client can page the true result count.
+     */
+    listUsers(query: ListQueryDto): Promise<{
+        total: number;
+        rows: readonly import("packages/engine/dist/types.js").RecordView[];
+        page: number;
+        limit: number;
+    }>;
+    /** Create a user — gated on `identity:user:create`. */
+    createUser(body: {
+        username?: string;
+    }): Promise<{
+        id: import("packages/engine/dist/types.js").RecordId;
+    }>;
+    /** Read one user — gated on `identity:user:read` (CONTROL-plane; root, the identity
+     *  administrator, may read users). */
+    getUser(uuid: string): Promise<import("packages/engine/dist/types.js").RecordView | null>;
+    /** Update a user — gated on `identity:user:update`. */
+    updateUser(uuid: string, body: {
+        username?: string;
+        email?: string;
+        status?: string;
+    }): Promise<{
+        success: boolean;
+    }>;
+    /** Delete a user — gated on `identity:user:delete`. */
+    deleteUser(uuid: string): Promise<{
+        success: boolean;
+    }>;
+}
+//# sourceMappingURL=user.controller.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"user.controller.d.ts","sourceRoot":"","sources":["../../../src/features/user/user.controller.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAK5E,qBACa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,WAAW;IAE/C;;;;OAIG;IAGG,SAAS,CAAU,KAAK,EAAE,YAAY;;;;;;IAM5C,uDAAuD;IAGjD,UAAU,CAAS,IAAI,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE;;;IAKpD;0CACsC;IAGtC,OAAO,CAAgB,IAAI,EAAE,MAAM;IAInC,uDAAuD;IAGjD,UAAU,CACC,IAAI,EAAE,MAAM,EACnB,IAAI,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;;;IAMtE,uDAAuD;IAGjD,UAAU,CAAgB,IAAI,EAAE,MAAM;;;CAI7C"}

package/dist/features/user/user.controller.js

@@ -0,0 +1,104 @@
+"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.UserController = void 0;
+const common_1 = require("@nestjs/common");
+const guard_1 = require("@astram/guard");
+const user_service_js_1 = require("./user.service.js");
+const list_query_js_1 = require("../shared/list-query.js");
+// User management is gated on `identity:user:<action>` grants. `user` is CONTROL-plane
+// for ALL actions — including read: the capped root is the identity administrator (the
+// identity-administrator model), so it may list/read users AND manage them.
+let UserController = class UserController {
+    users;
+    constructor(users) {
+        this.users = users;
+    }
+    /**
+     * List users — gated on `identity:user:read` (see class doc). Server-side DataTable:
+     * `?page&limit&search&sortBy&sortOrder`. Returns `{ total, rows, page, limit }` —
+     * `total` reflects the FILTERED set so the client can page the true result count.
+     */
+    async listUsers(query) {
+        const { page, limit, params } = (0, list_query_js_1.parseListQuery)(query);
+        const result = await this.users.listUsers(params);
+        return { total: result.total, rows: result.rows, page, limit };
+    }
+    /** Create a user — gated on `identity:user:create`. */
+    async createUser(body) {
+        const id = await this.users.createUser(body?.username ?? 'Untitled');
+        return { id };
+    }
+    /** Read one user — gated on `identity:user:read` (CONTROL-plane; root, the identity
+     *  administrator, may read users). */
+    getUser(uuid) {
+        return this.users.getUser(uuid);
+    }
+    /** Update a user — gated on `identity:user:update`. */
+    async updateUser(uuid, body) {
+        await this.users.updateUser(uuid, body ?? {});
+        return { success: true };
+    }
+    /** Delete a user — gated on `identity:user:delete`. */
+    async deleteUser(uuid) {
+        await this.users.deleteUser(uuid);
+        return { success: true };
+    }
+};
+exports.UserController = UserController;
+__decorate([
+    (0, common_1.Get)('users'),
+    (0, guard_1.Classified)({ typeKey: 'user', action: 'read' }),
+    __param(0, (0, common_1.Query)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], UserController.prototype, "listUsers", null);
+__decorate([
+    (0, common_1.Post)('users'),
+    (0, guard_1.Classified)({ typeKey: 'user', action: 'create' }),
+    __param(0, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], UserController.prototype, "createUser", null);
+__decorate([
+    (0, common_1.Get)('users/:uuid'),
+    (0, guard_1.Classified)({ typeKey: 'user', action: 'read' }),
+    __param(0, (0, common_1.Param)('uuid')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", void 0)
+], UserController.prototype, "getUser", null);
+__decorate([
+    (0, common_1.Put)('users/:uuid'),
+    (0, guard_1.Classified)({ typeKey: 'user', action: 'update' }),
+    __param(0, (0, common_1.Param)('uuid')),
+    __param(1, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object]),
+    __metadata("design:returntype", Promise)
+], UserController.prototype, "updateUser", null);
+__decorate([
+    (0, common_1.Delete)('users/:uuid'),
+    (0, guard_1.Classified)({ typeKey: 'user', action: 'delete' }),
+    __param(0, (0, common_1.Param)('uuid')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", Promise)
+], UserController.prototype, "deleteUser", null);
+exports.UserController = UserController = __decorate([
+    (0, common_1.Controller)('identity'),
+    __metadata("design:paramtypes", [user_service_js_1.UserService])
+], UserController);

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

@@ -0,0 +1,26 @@
+import { RecordsService, type RecordId } from '@astram/engine';
+import { type ListParams } from '../shared/list-query.js';
+/**
+ * UserService — user (principal) CRUD on the paved road, via the framework's
+ * RecordsService facade. The facade supplies the acting identity (the request
+ * principal) — this service never threads a Principal. No raw SQL, no RECORD_ENGINE.
+ */
+export declare class UserService {
+    private readonly records;
+    constructor(records: RecordsService);
+    /** Create a user. */
+    createUser(username: string): Promise<RecordId>;
+    /** List users (tenant-scoped by the pipe), with paging/search/sort. */
+    listUsers(params?: ListParams): Promise<import("@astram/engine").RecordPage>;
+    /** Read a single user. */
+    getUser(uuid: string): Promise<import("@astram/engine").RecordView | null>;
+    /** Update a user. */
+    updateUser(uuid: string, patch: {
+        username?: string;
+        email?: string;
+        status?: string;
+    }): Promise<void>;
+    /** Delete a user. */
+    deleteUser(uuid: string): Promise<void>;
+}
+//# sourceMappingURL=user.service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"user.service.d.ts","sourceRoot":"","sources":["../../../src/features/user/user.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/D,OAAO,EAAkB,KAAK,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAK1E;;;;GAIG;AACH,qBACa,WAAW;IACV,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,cAAc;IAEpD,qBAAqB;IACrB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAI/C,uEAAuE;IACvE,SAAS,CAAC,MAAM,CAAC,EAAE,UAAU;IAI7B,0BAA0B;IAC1B,OAAO,CAAC,IAAI,EAAE,MAAM;IAIpB,qBAAqB;IACrB,UAAU,CACR,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAC5D,OAAO,CAAC,IAAI,CAAC;IAIhB,qBAAqB;IACrB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAGxC"}

package/dist/features/user/user.service.js

@@ -0,0 +1,53 @@
+"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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UserService = void 0;
+const common_1 = require("@nestjs/common");
+const engine_1 = require("@astram/engine");
+const list_query_js_1 = require("../shared/list-query.js");
+const USER_SEARCH_FIELDS = ['username', 'email'];
+const USER_SORT_FIELDS = ['username', 'email', 'status', 'createdAt'];
+/**
+ * UserService — user (principal) CRUD on the paved road, via the framework's
+ * RecordsService facade. The facade supplies the acting identity (the request
+ * principal) — this service never threads a Principal. No raw SQL, no RECORD_ENGINE.
+ */
+let UserService = class UserService {
+    records;
+    constructor(records) {
+        this.records = records;
+    }
+    /** Create a user. */
+    createUser(username) {
+        return this.records.create('user', { fields: { username } });
+    }
+    /** List users (tenant-scoped by the pipe), with paging/search/sort. */
+    listUsers(params) {
+        return this.records.list('user', (0, list_query_js_1.buildListQuery)(params, USER_SEARCH_FIELDS, USER_SORT_FIELDS));
+    }
+    /** Read a single user. */
+    getUser(uuid) {
+        return this.records.get('user', uuid);
+    }
+    /** Update a user. */
+    updateUser(uuid, patch) {
+        return this.records.update('user', uuid, { fields: patch });
+    }
+    /** Delete a user. */
+    deleteUser(uuid) {
+        return this.records.delete('user', uuid);
+    }
+};
+exports.UserService = UserService;
+exports.UserService = UserService = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [engine_1.RecordsService])
+], UserService);