@astram/identity 0.1.2 → 0.2.0

package/dist/auth-facts-keys.d.ts

@@ -0,0 +1,3 @@
+export declare const identityAuthActionKeys: readonly string[];
+export declare const identityControlPlaneKeys: readonly string[];
+//# sourceMappingURL=auth-facts-keys.d.ts.map

package/dist/auth-facts-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-facts-keys.d.ts","sourceRoot":"","sources":["../src/auth-facts-keys.ts"],"names":[],"mappings":"AAgBA,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAEZ,CAAC;AAEzC,eAAO,MAAM,wBAAwB,EAAE,SAAS,MAAM,EAGd,CAAC"}

package/dist/auth-facts-keys.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.identityControlPlaneKeys = exports.identityAuthActionKeys = void 0;
+/**
+ * The framework identity permission-key universe, projected once from `identityObjects` via
+ * `@astram/guard`'s registry bridge. Exported for the consumer to pass into
+ * `ShieldModule.forRoot({ auth: true, identityActionKeys, identityControlPlaneKeys })` — so the
+ * auth-facts adapter (in guard) can expand `identity:*` grants + union root's control-plane keys
+ * WITHOUT guard importing this package (the sanctioned graph is identity → guard).
+ *
+ * ⚠ NO MODULE-INIT CYCLE: `identityObjects` is imported from the leaf `./objects.js` (NOT from
+ * `./index.js`, which re-exports THIS file). So the array is fully initialized before the
+ * `buildIdentityModuleRegistry(...)` call below runs at module-eval time.
+ */
+const guard_1 = require("@astram/guard");
+const objects_js_1 = require("./objects.js");
+const registry = (0, guard_1.buildIdentityModuleRegistry)(objects_js_1.identityObjects);
+exports.identityAuthActionKeys = registry
+    .listActions()
+    .map((a) => a.permissionKey);
+exports.identityControlPlaneKeys = registry
+    .listActions()
+    .filter((a) => a.plane === 'control')
+    .map((a) => a.permissionKey);

package/dist/cross-tenant-grant.object.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `cross_tenant_grant` — an AUTHORITY-ONLY @ObjectType, never CRUD'd through the
+ * RecordEngine pipe. Its sole purpose is to give `cross_tenant_grant` an entry in the
+ * core `ModuleRegistry` (via `module-registry.bridge.ts`) so `decide()` can answer the
+ * "may this principal share/accept/revoke a cross-tenant grant?" question the SAME way
+ * it answers every other object-type gate — no bespoke authority rule needed.
+ *
+ * `plane: 'control'` — WHO-MAY-GRANT is who-may-act administration (root allowed), the
+ * same posture as `role`/`company`. `system: true` (never `owned`/`tenantScoped`) — the
+ * table's row-level owner/tenant columns (`ctg_owning_tenant_uuid`,
+ * `ctg_grantee_tenant_uuid`) already encode the tenants the writer needs; that isolation
+ * is enforced by `CrossTenantGrantWriter` itself, not by the pipe's owner/tenant baseline.
+ *
+ * Mirrors `membership-posting.object.ts`'s shape (system, no trusted columns needed
+ * beyond the PK) — the engine's `validateAccess` requires `table` + at least one
+ * `@Field`; the PK satisfies that. Action vocabulary is NOT the CRUD `IDENTITY_ACTIONS`
+ * — see `@astram/guard`'s `identity-actions.ts`'s `actionsFor('cross_tenant_grant')` ->
+ * `CROSS_TENANT_GRANT_ACTIONS` (`share`/`accept`/`revoke`).
+ *
+ * Ported from astram3's frozen
+ * `server/src/features/authz/objects/cross-tenant-grant.object.ts`.
+ */
+export declare class CrossTenantGrant {
+    uuid: string;
+    owningTenantUuid: string;
+    granteeTenantUuid: string;
+}
+//# sourceMappingURL=cross-tenant-grant.object.d.ts.map

package/dist/cross-tenant-grant.object.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-tenant-grant.object.d.ts","sourceRoot":"","sources":["../src/cross-tenant-grant.object.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAOa,gBAAgB;IAE3B,IAAI,EAAG,MAAM,CAAC;IAGd,gBAAgB,EAAG,MAAM,CAAC;IAG1B,iBAAiB,EAAG,MAAM,CAAC;CAC5B"}

package/dist/cross-tenant-grant.object.js

@@ -0,0 +1,64 @@
+"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.CrossTenantGrant = void 0;
+const engine_1 = require("@astram/engine");
+/** The physical schema `cross_tenant_grant` lives in (migration 1710000000011). */
+const SCHEMA = 'shield_authz';
+/**
+ * `cross_tenant_grant` — an AUTHORITY-ONLY @ObjectType, never CRUD'd through the
+ * RecordEngine pipe. Its sole purpose is to give `cross_tenant_grant` an entry in the
+ * core `ModuleRegistry` (via `module-registry.bridge.ts`) so `decide()` can answer the
+ * "may this principal share/accept/revoke a cross-tenant grant?" question the SAME way
+ * it answers every other object-type gate — no bespoke authority rule needed.
+ *
+ * `plane: 'control'` — WHO-MAY-GRANT is who-may-act administration (root allowed), the
+ * same posture as `role`/`company`. `system: true` (never `owned`/`tenantScoped`) — the
+ * table's row-level owner/tenant columns (`ctg_owning_tenant_uuid`,
+ * `ctg_grantee_tenant_uuid`) already encode the tenants the writer needs; that isolation
+ * is enforced by `CrossTenantGrantWriter` itself, not by the pipe's owner/tenant baseline.
+ *
+ * Mirrors `membership-posting.object.ts`'s shape (system, no trusted columns needed
+ * beyond the PK) — the engine's `validateAccess` requires `table` + at least one
+ * `@Field`; the PK satisfies that. Action vocabulary is NOT the CRUD `IDENTITY_ACTIONS`
+ * — see `@astram/guard`'s `identity-actions.ts`'s `actionsFor('cross_tenant_grant')` ->
+ * `CROSS_TENANT_GRANT_ACTIONS` (`share`/`accept`/`revoke`).
+ *
+ * Ported from astram3's frozen
+ * `server/src/features/authz/objects/cross-tenant-grant.object.ts`.
+ */
+let CrossTenantGrant = class CrossTenantGrant {
+    uuid;
+    owningTenantUuid;
+    granteeTenantUuid;
+};
+exports.CrossTenantGrant = CrossTenantGrant;
+__decorate([
+    (0, engine_1.Field)({ column: 'ctg_uuid', type: 'uuid' }),
+    __metadata("design:type", String)
+], CrossTenantGrant.prototype, "uuid", void 0);
+__decorate([
+    (0, engine_1.Field)({ column: 'ctg_owning_tenant_uuid', type: 'uuid' }),
+    __metadata("design:type", String)
+], CrossTenantGrant.prototype, "owningTenantUuid", void 0);
+__decorate([
+    (0, engine_1.Field)({ column: 'ctg_grantee_tenant_uuid', type: 'uuid' }),
+    __metadata("design:type", String)
+], CrossTenantGrant.prototype, "granteeTenantUuid", void 0);
+exports.CrossTenantGrant = CrossTenantGrant = __decorate([
+    (0, engine_1.ObjectType)({
+        typeKey: 'cross_tenant_grant',
+        table: 'cross_tenant_grant',
+        schema: SCHEMA,
+        access: { plane: 'control', system: true },
+    }),
+    (0, engine_1.PrimaryKey)({ kind: 'uuid', column: 'ctg_uuid' })
+], CrossTenantGrant);

package/dist/features/access/access-admin.access.d.ts

@@ -0,0 +1,3 @@
+export declare class AccessAdminAccess {
+}
+//# sourceMappingURL=access-admin.access.d.ts.map

package/dist/features/access/access-admin.access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access-admin.access.d.ts","sourceRoot":"","sources":["../../../src/features/access/access-admin.access.ts"],"names":[],"mappings":"AAOA,qBAOa,iBAAiB;CAAG"}

package/dist/features/access/access-admin.access.js

@@ -0,0 +1,27 @@
+"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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AccessAdminAccess = void 0;
+/**
+ * `access-admin` — the role-administration seed bundle from design §6. Full role
+ * lifecycle (managing roles + the access granted to them). Every key resolves to a
+ * REAL registered `identity:<type>:<action>`.
+ */
+const engine_1 = require("@astram/engine");
+let AccessAdminAccess = class AccessAdminAccess {
+};
+exports.AccessAdminAccess = AccessAdminAccess;
+exports.AccessAdminAccess = AccessAdminAccess = __decorate([
+    (0, engine_1.AccessBundle)({
+        key: 'access-admin',
+        module: 'identity',
+        label: 'Access Administration',
+        description: 'Manage roles and the access granted to them.',
+        permissions: [{ typeKey: 'role', actions: ['read', 'create', 'update', 'delete'] }],
+    })
+], AccessAdminAccess);

package/dist/features/access/company-admin.access.d.ts

@@ -0,0 +1,3 @@
+export declare class CompanyAdminAccess {
+}
+//# sourceMappingURL=company-admin.access.d.ts.map

package/dist/features/access/company-admin.access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"company-admin.access.d.ts","sourceRoot":"","sources":["../../../src/features/access/company-admin.access.ts"],"names":[],"mappings":"AAOA,qBAWa,kBAAkB;CAAG"}

package/dist/features/access/company-admin.access.js

@@ -0,0 +1,31 @@
+"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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CompanyAdminAccess = void 0;
+/**
+ * `company-admin` — the company-administration seed bundle from design §6. Full
+ * company lifecycle plus the read-only membership lookups a company-admin form needs.
+ * Every key resolves to a REAL registered `identity:<type>:<action>`.
+ */
+const engine_1 = require("@astram/engine");
+let CompanyAdminAccess = class CompanyAdminAccess {
+};
+exports.CompanyAdminAccess = CompanyAdminAccess;
+exports.CompanyAdminAccess = CompanyAdminAccess = __decorate([
+    (0, engine_1.AccessBundle)({
+        key: 'company-admin',
+        module: 'identity',
+        label: 'Company Administration',
+        description: 'Create and manage companies and their memberships.',
+        permissions: [
+            { typeKey: 'company', actions: ['read', 'create', 'update', 'delete'] },
+            { typeKey: 'company_membership', actions: ['read'] },
+            { typeKey: 'membership_posting', actions: ['read'] },
+        ],
+    })
+], CompanyAdminAccess);

package/dist/features/access/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Identity access-bundles barrel. Each `@AccessBundle` class is declared in its own
+ * `<bundle>.access.ts` (co-located with the feature it grants, per the design's
+ * "declare it where you build it" model). This barrel re-exports each class + the
+ * aggregate `identityAccessBundles` array passed to `EngineModule.forFeature(...,
+ * { accessBundles })`, which the engine collects into `ENGINE_ALL_ACCESS_BUNDLES` and
+ * the boot reconciler upserts into `shield_authz.access_bundle`.
+ */
+import { UserManagementAccess } from './user-management.access';
+export { UserManagementAccess } from './user-management.access';
+export { CompanyAdminAccess } from './company-admin.access';
+export { AccessAdminAccess } from './access-admin.access';
+/** All identity access bundles, collected into the engine at boot. */
+export declare const identityAccessBundles: (typeof UserManagementAccess)[];
+//# sourceMappingURL=index.d.ts.map

package/dist/features/access/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/features/access/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAIhE,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE1D,sEAAsE;AACtE,eAAO,MAAM,qBAAqB,iCAIjC,CAAC"}

package/dist/features/access/index.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.identityAccessBundles = exports.AccessAdminAccess = exports.CompanyAdminAccess = exports.UserManagementAccess = void 0;
+/**
+ * Identity access-bundles barrel. Each `@AccessBundle` class is declared in its own
+ * `<bundle>.access.ts` (co-located with the feature it grants, per the design's
+ * "declare it where you build it" model). This barrel re-exports each class + the
+ * aggregate `identityAccessBundles` array passed to `EngineModule.forFeature(...,
+ * { accessBundles })`, which the engine collects into `ENGINE_ALL_ACCESS_BUNDLES` and
+ * the boot reconciler upserts into `shield_authz.access_bundle`.
+ */
+const user_management_access_1 = require("./user-management.access");
+const company_admin_access_1 = require("./company-admin.access");
+const access_admin_access_1 = require("./access-admin.access");
+var user_management_access_2 = require("./user-management.access");
+Object.defineProperty(exports, "UserManagementAccess", { enumerable: true, get: function () { return user_management_access_2.UserManagementAccess; } });
+var company_admin_access_2 = require("./company-admin.access");
+Object.defineProperty(exports, "CompanyAdminAccess", { enumerable: true, get: function () { return company_admin_access_2.CompanyAdminAccess; } });
+var access_admin_access_2 = require("./access-admin.access");
+Object.defineProperty(exports, "AccessAdminAccess", { enumerable: true, get: function () { return access_admin_access_2.AccessAdminAccess; } });
+/** All identity access bundles, collected into the engine at boot. */
+exports.identityAccessBundles = [
+    user_management_access_1.UserManagementAccess,
+    company_admin_access_1.CompanyAdminAccess,
+    access_admin_access_1.AccessAdminAccess,
+];

package/dist/features/access/user-management.access.d.ts

@@ -0,0 +1,3 @@
+export declare class UserManagementAccess {
+}
+//# sourceMappingURL=user-management.access.d.ts.map

package/dist/features/access/user-management.access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-management.access.d.ts","sourceRoot":"","sources":["../../../src/features/access/user-management.access.ts"],"names":[],"mappings":"AAQA,qBAca,oBAAoB;CAAG"}

package/dist/features/access/user-management.access.js

@@ -0,0 +1,35 @@
+"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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UserManagementAccess = void 0;
+/**
+ * `user-management` — the cross-type seed bundle from design §3.1. Lets an admin
+ * grant "manage users" as ONE named unit: full user lifecycle plus the read-only
+ * lookups the user-admin forms need (role/department/branch) plus company-membership
+ * administration. Every key resolves to a REAL registered `identity:<type>:<action>`.
+ */
+const engine_1 = require("@astram/engine");
+let UserManagementAccess = class UserManagementAccess {
+};
+exports.UserManagementAccess = UserManagementAccess;
+exports.UserManagementAccess = UserManagementAccess = __decorate([
+    (0, engine_1.AccessBundle)({
+        key: 'user-management',
+        module: 'identity',
+        label: 'User Management',
+        description: 'Create, edit and assign users to companies.',
+        permissions: [
+            { typeKey: 'user', actions: ['read', 'create', 'update', 'delete'] },
+            { typeKey: 'role', actions: ['read'] },
+            { typeKey: 'department', actions: ['read'] },
+            { typeKey: 'branch', actions: ['read'] },
+            { typeKey: 'company_membership', actions: ['read', 'create', 'update', 'delete'] },
+            { typeKey: 'membership_posting', actions: ['read', 'update'] },
+        ],
+    })
+], UserManagementAccess);

package/dist/features/audit/audit-read.service.d.ts

@@ -0,0 +1,92 @@
+import type { AuditEvent, LabelResolver } from '@astram/core';
+export interface AuditRow {
+    readonly occurredAt: number;
+    readonly actorLabel: string;
+    readonly action: string;
+    readonly tenantLabel: string;
+    readonly detail: Record<string, unknown>;
+}
+export interface AuditFilters {
+    readonly type?: string;
+    readonly actorName?: string;
+    readonly tenantFilter?: string;
+    readonly before?: string;
+    readonly limit?: number;
+}
+export interface AuditPrincipal {
+    readonly id: string;
+    readonly tenantId: string;
+    readonly isRoot: boolean;
+}
+/** name -> actorId reverse lookup (for the actor filter). Returns null when unknown. */
+export type ActorNameResolver = (name: string) => Promise<string | null>;
+/**
+ * The tenant/type/actor SCOPE query shared by BOTH the page read and the total count. Building
+ * ONE of these and feeding it into both is what guarantees a non-root's total counts ONLY its
+ * own tenant (invariant #4: tenant isolation — the count must never widen past the page). `type`
+ * carries the action-key filter as the concrete reader's `AuditEvent['type']`.
+ */
+export interface CountQuery {
+    readonly tenantId: string;
+    readonly type?: AuditEvent['type'];
+    readonly actorId?: string;
+}
+/**
+ * The scope query plus the page window (offset + limit) for {@link PagedAuditReader.read}. Mirrors
+ * the concrete `MariaDbAuditReader.read` param shape (all window fields optional) so the concrete
+ * reader is structurally assignable to {@link PagedAuditReader}; the service always supplies both.
+ */
+export interface PagedReadQuery extends CountQuery {
+    readonly limit?: number;
+    readonly offset?: number;
+    readonly before?: string;
+}
+/**
+ * The numbered-pagination read port used by {@link AuditReadService.listPage}: an offset-windowed
+ * `read` and a scope-matched `count`. Defined LOCALLY here (not in `@astram/core`, which is
+ * frozen); the concrete `MariaDbAuditReader` is structurally assignable to it. NOT declared as
+ * `extends AuditReader` because its `read` widens the query shape (offset), which the frozen
+ * core `AuditReadQuery` does not carry.
+ */
+export interface PagedAuditReader {
+    read(query: PagedReadQuery): Promise<readonly AuditEvent[]>;
+    count(query: CountQuery): Promise<number>;
+}
+/**
+ * The audit viewer read-model wrapper (design §2, §3): derives scope from the PRINCIPAL
+ * (never client input), reverse-resolves an actor name to an id, then serves a NUMBERED
+ * (offset + total) page — a scope-matched `count` for the total and an offset-windowed `read`
+ * for the rows — resolving actor/tenant labels DIRECTLY and stripping every raw id so the
+ * response carries labels only (ADR-0012).
+ */
+export declare class AuditReadService {
+    private readonly reader;
+    private readonly labels;
+    private readonly actorNameResolver;
+    constructor(reader: PagedAuditReader, labels: LabelResolver, actorNameResolver: ActorNameResolver);
+    /**
+     * A numbered (offset + total) audit page. Scope is derived from the PRINCIPAL ALONE — a
+     * non-root is pinned to its own tenant (tenantFilter ignored); a root gets the all-tenants
+     * sentinel, OPTIONALLY narrowed by tenantFilter. That SAME scope feeds BOTH the count and the
+     * page read, so the total can never leak another tenant's row count (invariant #4). A
+     * reader/count/resolver throw PROPAGATES (fail-closed) — we do not catch.
+     */
+    listPage(principal: AuditPrincipal, filters: {
+        page?: number;
+        limit?: number;
+        type?: string;
+        actorName?: string;
+        tenantFilter?: string;
+    }): Promise<{
+        rows: AuditRow[];
+        total: number;
+        page: number;
+        limit: number;
+    }>;
+    /**
+     * Remove obvious raw-uuid-bearing keys from the attributes detail so no raw id leaks.
+     * Keeps non-id fields; drops keys ending in `Uuid`/`Id`/`_uuid`/`_id` and any uuid-shaped value.
+     */
+    private stripIds;
+}
+//# sourceMappingURL=audit-read.service.d.ts.map

package/dist/features/audit/audit-read.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-read.service.d.ts","sourceRoot":"","sources":["../../../src/features/audit/audit-read.service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE9D,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED,wFAAwF;AACxF,MAAM,MAAM,iBAAiB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AAEzE;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IACnC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAe,SAAQ,UAAU;IAChD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC,CAAC;IAC5D,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC3C;AAMD;;;;;;GAMG;AACH,qBAAa,gBAAgB;IAEzB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,iBAAiB;gBAFjB,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,aAAa,EACrB,iBAAiB,EAAE,iBAAiB;IAGvD;;;;;;OAMG;IACG,QAAQ,CACZ,SAAS,EAAE,cAAc,EACzB,OAAO,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,GACnG,OAAO,CAAC;QAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAyD5E;;;OAGG;IACH,OAAO,CAAC,QAAQ;CAUjB"}

package/dist/features/audit/audit-read.service.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuditReadService = void 0;
+const ALL_TENANTS = '*';
+const DEFAULT_LIMIT = 50;
+const MAX_LIMIT = 200;
+/**
+ * The audit viewer read-model wrapper (design §2, §3): derives scope from the PRINCIPAL
+ * (never client input), reverse-resolves an actor name to an id, then serves a NUMBERED
+ * (offset + total) page — a scope-matched `count` for the total and an offset-windowed `read`
+ * for the rows — resolving actor/tenant labels DIRECTLY and stripping every raw id so the
+ * response carries labels only (ADR-0012).
+ */
+class AuditReadService {
+    reader;
+    labels;
+    actorNameResolver;
+    constructor(reader, labels, actorNameResolver) {
+        this.reader = reader;
+        this.labels = labels;
+        this.actorNameResolver = actorNameResolver;
+    }
+    /**
+     * A numbered (offset + total) audit page. Scope is derived from the PRINCIPAL ALONE — a
+     * non-root is pinned to its own tenant (tenantFilter ignored); a root gets the all-tenants
+     * sentinel, OPTIONALLY narrowed by tenantFilter. That SAME scope feeds BOTH the count and the
+     * page read, so the total can never leak another tenant's row count (invariant #4). A
+     * reader/count/resolver throw PROPAGATES (fail-closed) — we do not catch.
+     */
+    async listPage(principal, filters) {
+        // Scope is derived from the principal ALONE. A root gets the all-tenants sentinel,
+        // OPTIONALLY narrowed to one tenant via tenantFilter; an admin is pinned to their tenant
+        // and tenantFilter is ignored (cannot widen or cross).
+        let tenantId;
+        if (principal.isRoot) {
+            tenantId = filters.tenantFilter && filters.tenantFilter.length > 0 ? filters.tenantFilter : ALL_TENANTS;
+        }
+        else {
+            tenantId = principal.tenantId;
+        }
+        // Actor name -> id (server-side; uses the al_actor_id index). An unknown name yields an
+        // id that matches nothing → an empty page (correct, not an error).
+        let actorId;
+        if (filters.actorName && filters.actorName.length > 0) {
+            actorId = (await this.actorNameResolver(filters.actorName)) ?? ' no-such-actor';
+        }
+        // Clamp the client-supplied limit to [1, MAX_LIMIT]; a non-finite value falls back to
+        // DEFAULT_LIMIT (only an in-range-but-out-of-bounds number gets floored/capped). Floor the
+        // page to >= 1. offset uses the CLAMPED limit, so the window never diverges from read.limit.
+        const requestedLimit = Number.isFinite(filters.limit) ? filters.limit : DEFAULT_LIMIT;
+        const limit = Math.min(Math.max(1, requestedLimit), MAX_LIMIT);
+        const page = Number.isFinite(filters.page) && filters.page >= 1 ? Math.floor(filters.page) : 1;
+        const offset = (page - 1) * limit;
+        // ONE scope query — spread into BOTH the count and the page read so their tenant/type/actor
+        // WHERE is identical. A non-root's total therefore counts ONLY its own tenant (invariant #4).
+        const scopeQuery = {
+            tenantId,
+            ...(filters.type ? { type: filters.type } : {}),
+            ...(actorId ? { actorId } : {}),
+        };
+        // A throw in EITHER side propagates (fail-closed — a total must never silently be zero).
+        const [total, events] = await Promise.all([
+            this.reader.count(scopeQuery),
+            this.reader.read({ ...scopeQuery, limit, offset }),
+        ]);
+        // Resolve labels DIRECTLY (the core `auditView` engine is no longer in this path): actorLabel
+        // via labels.resolve('principal', ...) and tenantLabel via labels.resolve('tenant', ...) —
+        // same resolver, same no-raw-id guarantee. A resolver throw propagates (fail-closed).
+        const rows = await Promise.all(events.map(async (event) => ({
+            occurredAt: event.occurredAtMs,
+            actorLabel: await this.labels.resolve('principal', event.actorId),
+            action: event.action?.key
+                ?? event.action
+                ?? '(event)',
+            tenantLabel: await this.labels.resolve('tenant', event.tenantId),
+            detail: this.stripIds(event.attributes ?? {}),
+        })));
+        return { rows, total, page, limit };
+    }
+    /**
+     * Remove obvious raw-uuid-bearing keys from the attributes detail so no raw id leaks.
+     * Keeps non-id fields; drops keys ending in `Uuid`/`Id`/`_uuid`/`_id` and any uuid-shaped value.
+     */
+    stripIds(attrs) {
+        const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+        const out = {};
+        for (const [k, val] of Object.entries(attrs)) {
+            if (/uuid$|Id$|_id$/i.test(k))
+                continue;
+            if (typeof val === 'string' && UUID.test(val))
+                continue;
+            out[k] = val;
+        }
+        return out;
+    }
+}
+exports.AuditReadService = AuditReadService;

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

@@ -0,0 +1,35 @@
+import type { Principal } from '@astram/engine';
+import { AuditReadService } from './audit-read.service.js';
+/** The request shape after the enforcement guard attaches the resolved principal (mirrors
+ *  grant-admin.controller.ts's `AuthedRequest`). `isRoot` is read off the same
+ *  principal grant-admin uses via `req.principal?.id` — kept optional here for the same
+ *  reason grant-admin reads `req.principal?.id` defensively. */
+interface AuthedRequest {
+    principal: Principal & {
+        isRoot?: boolean;
+    };
+}
+/**
+ * `GET /identity/audit` — the audit viewer read endpoint (design §4). Scope is derived
+ * from the request principal by the service; the controller NEVER trusts a client-supplied
+ * tenant/scope. A service throw (reader/resolver outage) → 503 (fail-closed).
+ */
+export declare class AuditController {
+    private readonly service;
+    constructor(service: AuditReadService);
+    list(req: AuthedRequest, q: {
+        page?: string;
+        limit?: string;
+        type?: string;
+        actor?: string;
+        tenant?: string;
+    }): Promise<{
+        success: true;
+        data: unknown[];
+        total: number;
+        page: number;
+        limit: number;
+    }>;
+}
+export {};
+//# sourceMappingURL=audit.controller.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"audit.controller.d.ts","sourceRoot":"","sources":["../../../src/features/audit/audit.controller.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAIhD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAW3D;;;gEAGgE;AAChE,UAAU,aAAa;IACrB,SAAS,EAAE,SAAS,GAAG;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAC7C;AAED;;;;GAIG;AACH,qBACa,eAAe;IACd,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,gBAAgB;IAIhD,IAAI,CACD,GAAG,EAAE,aAAa,EAChB,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAC5F,OAAO,CAAC;QAAE,OAAO,EAAE,IAAI,CAAC;QAAC,IAAI,EAAE,OAAO,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CA8B3F"}

package/dist/features/audit/audit.controller.js

@@ -0,0 +1,73 @@
+"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.AuditController = void 0;
+// audit.controller.ts
+const common_1 = require("@nestjs/common");
+const guard_1 = require("@astram/guard");
+// `AuditReadService` is the DI token for the constructor injection below, so it MUST be a
+// value import — a type-only import is erased at compile time, leaving NestJS with
+// `undefined` metadata and an "can't resolve dependencies" boot failure.
+const audit_read_service_js_1 = require("./audit-read.service.js");
+/**
+ * `GET /identity/audit` — the audit viewer read endpoint (design §4). Scope is derived
+ * from the request principal by the service; the controller NEVER trusts a client-supplied
+ * tenant/scope. A service throw (reader/resolver outage) → 503 (fail-closed).
+ */
+let AuditController = class AuditController {
+    service;
+    constructor(service) {
+        this.service = service;
+    }
+    async list(req, q) {
+        const principal = {
+            id: req.principal.id,
+            tenantId: req.principal.tenantId,
+            isRoot: req.principal.isRoot === true,
+        };
+        // `page`/`limit` are passed through ONLY when present AND finite — otherwise the key is
+        // OMITTED so `listPage` applies its own default + clamp/floor. A non-numeric value (e.g.
+        // `?page=abc`) parses to `NaN`, which is non-finite, so it is omitted rather than forwarded.
+        const page = Number(q.page);
+        const limit = Number(q.limit);
+        const filters = {
+            ...(q.page !== undefined && Number.isFinite(page) ? { page } : {}),
+            ...(q.limit !== undefined && Number.isFinite(limit) ? { limit } : {}),
+            ...(q.type ? { type: q.type } : {}),
+            ...(q.actor ? { actorName: q.actor } : {}),
+            ...(q.tenant ? { tenantFilter: q.tenant } : {}),
+        };
+        try {
+            const { rows, total, page: resolvedPage, limit: resolvedLimit, } = await this.service.listPage(principal, filters);
+            return { success: true, data: rows, total, page: resolvedPage, limit: resolvedLimit };
+        }
+        catch (err) {
+            throw new common_1.ServiceUnavailableException(`audit read unavailable: ${err.message}`);
+        }
+    }
+};
+exports.AuditController = AuditController;
+__decorate([
+    (0, common_1.Get)('audit'),
+    (0, guard_1.Classified)({ typeKey: 'role', action: 'read' }),
+    __param(0, (0, common_1.Req)()),
+    __param(1, (0, common_1.Query)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], AuditController.prototype, "list", null);
+exports.AuditController = AuditController = __decorate([
+    (0, common_1.Controller)('identity'),
+    __metadata("design:paramtypes", [audit_read_service_js_1.AuditReadService])
+], AuditController);

package/dist/features/audit/directory-label-resolver.d.ts

@@ -0,0 +1,14 @@
+import type { LabelResolver, LabelKind } from '@astram/core';
+import type { AuditQueryable } from './mariadb-audit-reader.js';
+/**
+ * The id->human-label chokepoint (ADR-0012, design §2.2). A deleted/unknown
+ * entity resolves to a FALLBACK label (never the id); a directory OUTAGE throws
+ * (fail-closed — a transient must not masquerade as a deletion).
+ */
+export declare class DirectoryLabelResolver implements LabelResolver {
+    private readonly db;
+    constructor(db: AuditQueryable);
+    resolve(kind: LabelKind, id: string, _tenantId?: string): Promise<string>;
+    private fallback;
+}
+//# sourceMappingURL=directory-label-resolver.d.ts.map

package/dist/features/audit/directory-label-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory-label-resolver.d.ts","sourceRoot":"","sources":["../../../src/features/audit/directory-label-resolver.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAIhE;;;;GAIG;AACH,qBAAa,sBAAuB,YAAW,aAAa;IAC9C,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,cAAc;IAEzC,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IA8B/E,OAAO,CAAC,QAAQ;CAMjB"}