@astram/identity 0.10.0 → 0.12.0

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

@@ -0,0 +1,27 @@
+import { StreamableFile } from '@nestjs/common';
+import { FilesService } from './files.service.js';
+/**
+ * `filename*` value for a stored name: C0 controls and DEL dropped, the rest UTF-8 percent-encoded
+ * byte by byte (a lone surrogate becomes U+FFFD via `Buffer.from`, so this never throws). Quotes,
+ * CR, LF, `;` and spaces are always encoded, so the name cannot split or extend the header.
+ */
+export declare function rfc5987FileName(name: string): string;
+/**
+ * FilesController — the framework download route `GET /files/:uuid` (file-storage SPEC §3, §5 K2).
+ *
+ * - Gated on `stored_file:read` by the global guard (Shield #2/#3); `UuidPipe` answers 400 for a
+ *   non-uuid before any service call. Record-level decide, the tenant wall, the key-prefix and
+ *   sha256 checks and the `file_access` audit all happen in `FilesService.open`.
+ * - Errors map at source: 501/503/403 come from `FilesService` with fixed messages; an engine
+ *   deny is rethrown here as the same 403 a missing row gets (SPEC §13: same body). Never echoes
+ *   the storage key or the name in an error.
+ * - Success headers: `Cache-Control: no-store` and `nosniff` via `@Header`; `Content-Type` (from
+ *   the record), `Content-Disposition` (attachment, RFC 5987 `filename*` only) and `Content-Length`
+ *   via `StreamableFile`, all set before the body is written. No express types needed.
+ */
+export declare class FilesController {
+    private readonly files;
+    constructor(files: FilesService);
+    download(uuid: string): Promise<StreamableFile>;
+}
+//# sourceMappingURL=files.controller.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"files.controller.d.ts","sourceRoot":"","sources":["../../../src/features/files/files.controller.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,cAAc,EAEf,MAAM,gBAAgB,CAAC;AAIxB,OAAO,EAAE,YAAY,EAAmB,MAAM,oBAAoB,CAAC;AAQnE;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAYpD;AAED;;;;;;;;;;;;GAYG;AACH,qBAEa,eAAe;IACd,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,YAAY;IAM1C,QAAQ,CAA0B,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;CAc/E"}

package/dist/features/files/files.controller.js

@@ -0,0 +1,94 @@
+"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.FilesController = void 0;
+exports.rfc5987FileName = rfc5987FileName;
+const common_1 = require("@nestjs/common");
+const engine_1 = require("@astram/engine");
+const guard_1 = require("@astram/guard");
+const identity_error_interceptor_js_1 = require("../shared/identity-error.interceptor.js");
+const files_service_js_1 = require("./files.service.js");
+/** Same text as `FilesService`'s 403, so an engine deny and a missing row answer one body (§13). */
+const MSG_FORBIDDEN = 'Forbidden';
+/** RFC 5987 `attr-char` (RFC 8187 §3.2.1): every other UTF-8 byte is percent-encoded. */
+const ATTR_CHAR = /^[A-Za-z0-9!#$&+\-.^_`|~]$/;
+/**
+ * `filename*` value for a stored name: C0 controls and DEL dropped, the rest UTF-8 percent-encoded
+ * byte by byte (a lone surrogate becomes U+FFFD via `Buffer.from`, so this never throws). Quotes,
+ * CR, LF, `;` and spaces are always encoded, so the name cannot split or extend the header.
+ */
+function rfc5987FileName(name) {
+    // eslint-disable-next-line no-control-regex
+    const cleaned = name.replace(/[\u0000-\u001f\u007f]/g, '');
+    let out = '';
+    for (const byte of Buffer.from(cleaned.length > 0 ? cleaned : 'download', 'utf8')) {
+        const ch = String.fromCharCode(byte);
+        out +=
+            byte < 0x80 && ATTR_CHAR.test(ch)
+                ? ch
+                : `%${byte.toString(16).toUpperCase().padStart(2, '0')}`;
+    }
+    return out;
+}
+/**
+ * FilesController — the framework download route `GET /files/:uuid` (file-storage SPEC §3, §5 K2).
+ *
+ * - Gated on `stored_file:read` by the global guard (Shield #2/#3); `UuidPipe` answers 400 for a
+ *   non-uuid before any service call. Record-level decide, the tenant wall, the key-prefix and
+ *   sha256 checks and the `file_access` audit all happen in `FilesService.open`.
+ * - Errors map at source: 501/503/403 come from `FilesService` with fixed messages; an engine
+ *   deny is rethrown here as the same 403 a missing row gets (SPEC §13: same body). Never echoes
+ *   the storage key or the name in an error.
+ * - Success headers: `Cache-Control: no-store` and `nosniff` via `@Header`; `Content-Type` (from
+ *   the record), `Content-Disposition` (attachment, RFC 5987 `filename*` only) and `Content-Length`
+ *   via `StreamableFile`, all set before the body is written. No express types needed.
+ */
+let FilesController = class FilesController {
+    files;
+    constructor(files) {
+        this.files = files;
+    }
+    async download(uuid) {
+        let file;
+        try {
+            file = await this.files.open(uuid);
+        }
+        catch (cause) {
+            if (cause instanceof engine_1.AuthorizationDeniedError)
+                throw new common_1.ForbiddenException(MSG_FORBIDDEN);
+            throw cause;
+        }
+        return new common_1.StreamableFile(Buffer.from(file.bytes), {
+            type: file.contentType,
+            disposition: `attachment; filename*=UTF-8''${rfc5987FileName(file.originalName)}`,
+            length: file.bytes.byteLength,
+        });
+    }
+};
+exports.FilesController = FilesController;
+__decorate([
+    (0, common_1.Get)(':uuid'),
+    (0, guard_1.Classified)({ typeKey: 'stored_file', action: 'read' }),
+    (0, common_1.Header)('Cache-Control', 'no-store'),
+    (0, common_1.Header)('X-Content-Type-Options', 'nosniff'),
+    __param(0, (0, common_1.Param)('uuid', guard_1.UuidPipe)),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", Promise)
+], FilesController.prototype, "download", null);
+exports.FilesController = FilesController = __decorate([
+    (0, common_1.Controller)('files'),
+    (0, common_1.UseInterceptors)(identity_error_interceptor_js_1.IdentityErrorInterceptor),
+    __metadata("design:paramtypes", [files_service_js_1.FilesService])
+], FilesController);

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

@@ -0,0 +1,87 @@
+import type { AuditSink, IngestedFile, ObjectStore } from '@astram/core';
+import { type RecordsService } from '@astram/engine';
+/**
+ * The canonical content types the intake allowlist can store: today the `xlsx` profile, the only
+ * profile `ShieldModule` registers on `SHIELD_FILE_INGEST`. Pass the app's own list when it
+ * registers more profiles.
+ */
+export declare const DEFAULT_SERVABLE_CONTENT_TYPES: readonly string[];
+/** What `store()` takes: the ingest result (server-built key, sha256, canonical type) plus bytes. */
+export interface StoreFileInput extends IngestedFile {
+    readonly bytes: Uint8Array;
+}
+/** What `store()` returns to the caller. Never carries the storage key (SPEC §5 I). */
+export interface StoredFileSummary {
+    readonly uuid: string;
+    readonly sha256: string;
+    readonly sizeBytes: number;
+    readonly contentType: string;
+    readonly originalName: string;
+}
+/** What `open()` returns (SPEC §5 J). Never carries the storage key. */
+export interface OpenedFile {
+    readonly bytes: Uint8Array;
+    readonly contentType: string;
+    readonly originalName: string;
+    readonly sizeBytes: number;
+}
+/**
+ * FilesService — stored files on the engine pipe (file-storage SPEC §5 I-K).
+ *
+ * - The `stored_file` row is written ONLY here (KI #4): the key comes from `FileIntake` (built from
+ *   the session tenant) and is re-checked against the actor's tenant before any put or create.
+ *   Tenant and owner are stamped by the pipe from the session (Shield #7), never sent from here.
+ * - Every row access goes through `RecordsService` (record gate, tenant wall, read scope, audit);
+ *   no DB pool, no bypass flag (Shield #3, #9). The bucket is read only in `open()`, after the gate.
+ * - Errors map at source: 501 when no store is bound, 503 (fixed message) for store failures and
+ *   integrity faults, 403 (fixed message) for missing, foreign or denied rows alike.
+ * - No actor argument (SPEC §5 I-K): the key tenant and the `file_access` audit actor come from
+ *   `RecordsService.requestPrincipal()`, the same principal the engine stamps and gates with, so
+ *   key tenant, row tenant/owner and audit actor cannot diverge. No principal ⇒ fail closed.
+ * - The engine does not audit its own denials, so a 403 from open/remove writes a `file_access`
+ *   failure event (`denied_or_missing`, no key, no name). Logs carry the storage key only.
+ */
+export declare class FilesService {
+    private readonly records;
+    private readonly objectStore;
+    private readonly audit;
+    private readonly logger;
+    private orphans;
+    constructor(records: RecordsService, objectStore: ObjectStore | null, audit: AuditSink, servableContentTypes?: readonly string[]);
+    /** Lower-cased allowlisted type -> its canonical spelling (what `open()` may serve). */
+    private readonly servable;
+    /**
+     * KI #13: the download Content-Type is re-checked against the intake allowlist, never taken
+     * from the row as-is. Anything else (a row written outside FileIntake, a profile since
+     * removed) is served as `application/octet-stream`.
+     */
+    private servableType;
+    /** Objects left behind by a failed compensating or post-commit delete since boot. */
+    get orphanedObjectCount(): number;
+    /** Put the bytes, then create the `stored_file` record; on create failure delete the object. */
+    store(intake: StoreFileInput): Promise<StoredFileSummary>;
+    /** Read a file under record-level decide, with the key and sha256 re-checked (SPEC §5 J). */
+    open(uuid: string): Promise<OpenedFile>;
+    /**
+     * Hard delete (team default): the record in a transaction (gated and audited by the pipe), the
+     * object after commit, then one `file_access` delete event (SPEC §5 K). A foreign key is never
+     * passed to the store.
+     */
+    remove(uuid: string): Promise<void>;
+    private requireStore;
+    /**
+     * Delete an object; true when the store confirmed it. On failure log the key only, count the
+     * orphan and answer false. Never throws.
+     */
+    private deleteObject;
+    /**
+     * A `file_access` failure event for a 403 (missing, foreign, malformed or engine-denied: one
+     * reason, since the caller may not learn which). Best effort; the 403 is thrown regardless.
+     */
+    private auditDenied;
+    /** A `file_access` failure event (best effort; the 503 is thrown regardless). */
+    private auditFailure;
+    /** `target` is the fetched row, or for a denial only the requested uuid (null if malformed). */
+    private event;
+}
+//# sourceMappingURL=files.service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"files.service.d.ts","sourceRoot":"","sources":["../../../src/features/files/files.service.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAc,SAAS,EAAE,YAAY,EAAE,WAAW,EAAa,MAAM,cAAc,CAAC;AAEhG,OAAO,EAGL,KAAK,cAAc,EAEpB,MAAM,gBAAgB,CAAC;AAYxB;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,EAAE,SAAS,MAAM,EAA8B,CAAC;AAE3F,qGAAqG;AACrG,MAAM,WAAW,cAAe,SAAQ,YAAY;IAClD,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;CAC5B;AAED,uFAAuF;AACvF,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,wEAAwE;AACxE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAqBD;;;;;;;;;;;;;;;GAeG;AACH,qBACa,YAAY;IAKrB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,KAAK;IANxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiC;IACxD,OAAO,CAAC,OAAO,CAAK;gBAGD,OAAO,EAAE,cAAc,EACvB,WAAW,EAAE,WAAW,GAAG,IAAI,EAC/B,KAAK,EAAE,SAAS,EACjC,oBAAoB,GAAE,SAAS,MAAM,EAAmC;IAK1E,wFAAwF;IACxF,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA8B;IAEvD;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAKpB,qFAAqF;IACrF,IAAI,mBAAmB,IAAI,MAAM,CAEhC;IAED,gGAAgG;IAC1F,KAAK,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA4C/D,6FAA6F;IACvF,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAyD7C;;;;OAIG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAyCzC,OAAO,CAAC,YAAY;IAOpB;;;OAGG;YACW,YAAY;IAa1B;;;OAGG;YACW,WAAW;IAczB,iFAAiF;YACnE,YAAY;IAQ1B,gGAAgG;IAChG,OAAO,CAAC,KAAK;CAwBd"}

package/dist/features/files/files.service.js

@@ -0,0 +1,311 @@
+"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 FilesService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FilesService = exports.DEFAULT_SERVABLE_CONTENT_TYPES = void 0;
+const node_crypto_1 = require("node:crypto");
+const common_1 = require("@nestjs/common");
+const core_1 = require("@astram/core");
+const engine_1 = require("@astram/engine");
+const TYPE_KEY = 'stored_file';
+/** Fixed messages: never a key, a name, bytes or a store detail (SPEC §11 secrets, §13). */
+const MSG_NOT_CONFIGURED = 'File storage is not configured';
+const MSG_UNAVAILABLE = 'File storage is unavailable';
+const MSG_FORBIDDEN = 'Forbidden';
+/** Served when a stored content type is not one the intake allowlist produces (KI #13). */
+const OCTET_STREAM = 'application/octet-stream';
+/**
+ * The canonical content types the intake allowlist can store: today the `xlsx` profile, the only
+ * profile `ShieldModule` registers on `SHIELD_FILE_INGEST`. Pass the app's own list when it
+ * registers more profiles.
+ */
+exports.DEFAULT_SERVABLE_CONTENT_TYPES = core_1.XLSX_PROFILE.contentTypes;
+/**
+ * True when `key` is exactly `t/<tenantId>/<uuid>` for this tenant (KI #4). Both segments must be
+ * canonical uuids, so a traversal (`..`), an extra segment or a shared string prefix
+ * (`t/<tenant>extra/…`) never matches.
+ */
+function keyBelongsTo(key, tenantId) {
+    const tenant = (0, engine_1.canonicalUuid)(tenantId);
+    if (tenant === null || typeof key !== 'string')
+        return false;
+    const parts = key.split('/');
+    return (parts.length === 3 &&
+        parts[0] === 't' &&
+        parts[1] === tenant &&
+        (0, engine_1.canonicalUuid)(parts[2]) === parts[2]);
+}
+const sha256Hex = (bytes) => (0, node_crypto_1.createHash)('sha256').update(bytes).digest('hex');
+/**
+ * FilesService — stored files on the engine pipe (file-storage SPEC §5 I-K).
+ *
+ * - The `stored_file` row is written ONLY here (KI #4): the key comes from `FileIntake` (built from
+ *   the session tenant) and is re-checked against the actor's tenant before any put or create.
+ *   Tenant and owner are stamped by the pipe from the session (Shield #7), never sent from here.
+ * - Every row access goes through `RecordsService` (record gate, tenant wall, read scope, audit);
+ *   no DB pool, no bypass flag (Shield #3, #9). The bucket is read only in `open()`, after the gate.
+ * - Errors map at source: 501 when no store is bound, 503 (fixed message) for store failures and
+ *   integrity faults, 403 (fixed message) for missing, foreign or denied rows alike.
+ * - No actor argument (SPEC §5 I-K): the key tenant and the `file_access` audit actor come from
+ *   `RecordsService.requestPrincipal()`, the same principal the engine stamps and gates with, so
+ *   key tenant, row tenant/owner and audit actor cannot diverge. No principal ⇒ fail closed.
+ * - The engine does not audit its own denials, so a 403 from open/remove writes a `file_access`
+ *   failure event (`denied_or_missing`, no key, no name). Logs carry the storage key only.
+ */
+let FilesService = FilesService_1 = class FilesService {
+    records;
+    objectStore;
+    audit;
+    logger = new common_1.Logger(FilesService_1.name);
+    orphans = 0;
+    constructor(records, objectStore, audit, servableContentTypes = exports.DEFAULT_SERVABLE_CONTENT_TYPES) {
+        this.records = records;
+        this.objectStore = objectStore;
+        this.audit = audit;
+        this.servable = new Map(servableContentTypes.map((t) => [t.toLowerCase(), t]));
+    }
+    /** Lower-cased allowlisted type -> its canonical spelling (what `open()` may serve). */
+    servable;
+    /**
+     * KI #13: the download Content-Type is re-checked against the intake allowlist, never taken
+     * from the row as-is. Anything else (a row written outside FileIntake, a profile since
+     * removed) is served as `application/octet-stream`.
+     */
+    servableType(stored) {
+        if (typeof stored !== 'string')
+            return OCTET_STREAM;
+        return this.servable.get(stored.toLowerCase()) ?? OCTET_STREAM;
+    }
+    /** Objects left behind by a failed compensating or post-commit delete since boot. */
+    get orphanedObjectCount() {
+        return this.orphans;
+    }
+    /** Put the bytes, then create the `stored_file` record; on create failure delete the object. */
+    async store(intake) {
+        const store = this.requireStore();
+        const actor = this.records.requestPrincipal();
+        if (!keyBelongsTo(intake.storageKey, actor.tenantId)) {
+            // A key outside the session tenant never reaches the bucket or the table (KI #4).
+            throw new common_1.ForbiddenException(MSG_FORBIDDEN);
+        }
+        const key = intake.storageKey;
+        try {
+            await store.put(key, intake.bytes, {
+                contentType: intake.contentType,
+                sha256: intake.sha256,
+            });
+        }
+        catch (cause) {
+            this.logger.error(`file put failed (${errorName(cause)}): ${key}`);
+            throw new common_1.ServiceUnavailableException(MSG_UNAVAILABLE);
+        }
+        let uuid;
+        try {
+            const id = await this.records.create(TYPE_KEY, {
+                fields: {
+                    storageKey: key,
+                    sha256: intake.sha256,
+                    contentType: intake.contentType,
+                    sizeBytes: intake.sizeBytes,
+                    originalName: intake.originalName,
+                    createdAt: Date.now(),
+                },
+            });
+            uuid = String(id);
+        }
+        catch (cause) {
+            await this.deleteObject(store, key, 'compensating');
+            throw cause;
+        }
+        return {
+            uuid,
+            sha256: intake.sha256,
+            sizeBytes: intake.sizeBytes,
+            contentType: intake.contentType,
+            originalName: intake.originalName,
+        };
+    }
+    /** Read a file under record-level decide, with the key and sha256 re-checked (SPEC §5 J). */
+    async open(uuid) {
+        const store = this.requireStore();
+        const actor = this.records.requestPrincipal();
+        const id = (0, engine_1.canonicalUuid)(uuid);
+        let row;
+        try {
+            if (id === null)
+                throw new common_1.ForbiddenException(MSG_FORBIDDEN);
+            row = await this.records.get(TYPE_KEY, id);
+            if (row === null)
+                throw new common_1.ForbiddenException(MSG_FORBIDDEN);
+        }
+        catch (cause) {
+            if (isDenial(cause))
+                await this.auditDenied(actor, 'read', id);
+            throw cause;
+        }
+        const f = row.fields;
+        const recordTenant = f.tenantId;
+        if (!keyBelongsTo(f.storageKey, recordTenant)) {
+            // The row points outside its own tenant: an integrity fault, never a cross-tenant read.
+            this.logger.error(`stored_file ${String(row.id)} key outside its tenant prefix; refused`);
+            await this.auditFailure(row, actor, 'key_prefix_mismatch');
+            throw new common_1.ServiceUnavailableException(MSG_UNAVAILABLE);
+        }
+        const key = f.storageKey;
+        let bytes;
+        try {
+            ({ bytes } = await store.get(key));
+        }
+        catch (cause) {
+            if (cause instanceof core_1.ObjectNotFoundError) {
+                this.logger.error(`stored object missing: ${key}`);
+                await this.auditFailure(row, actor, 'object_missing');
+            }
+            else {
+                this.logger.error(`file get failed (${errorName(cause)}): ${key}`);
+            }
+            throw new common_1.ServiceUnavailableException(MSG_UNAVAILABLE);
+        }
+        const sha = typeof f.sha256 === 'string' ? f.sha256.toLowerCase() : '';
+        if (sha.length !== 64 || sha256Hex(bytes) !== sha) {
+            this.logger.error(`stored object failed its sha256 check: ${key}`);
+            await this.auditFailure(row, actor, 'sha256_mismatch');
+            throw new common_1.ServiceUnavailableException(MSG_UNAVAILABLE);
+        }
+        const sizeBytes = Number(f.sizeBytes);
+        // Fail closed: no bytes leave without their read event (a sink error propagates).
+        await this.audit.record(this.event(actor, 'read', row, { sha256: sha, sizeBytes, outcome: 'success' }));
+        return {
+            bytes,
+            contentType: this.servableType(f.contentType),
+            originalName: String(f.originalName),
+            sizeBytes,
+        };
+    }
+    /**
+     * Hard delete (team default): the record in a transaction (gated and audited by the pipe), the
+     * object after commit, then one `file_access` delete event (SPEC §5 K). A foreign key is never
+     * passed to the store.
+     */
+    async remove(uuid) {
+        const store = this.requireStore();
+        const actor = this.records.requestPrincipal();
+        const id = (0, engine_1.canonicalUuid)(uuid);
+        let row;
+        let key;
+        try {
+            if (id === null)
+                throw new common_1.ForbiddenException(MSG_FORBIDDEN);
+            ({ row, key } = await this.records.transaction(async (tx) => {
+                const found = await tx.get(TYPE_KEY, id);
+                if (found === null)
+                    throw new common_1.ForbiddenException(MSG_FORBIDDEN);
+                await tx.delete(TYPE_KEY, id);
+                const k = found.fields.storageKey;
+                return { row: found, key: keyBelongsTo(k, found.fields.tenantId) ? k : null };
+            }));
+        }
+        catch (cause) {
+            if (isDenial(cause))
+                await this.auditDenied(actor, 'delete', id);
+            throw cause;
+        }
+        let objectDeleted = false;
+        if (key === null) {
+            this.logger.error(`stored_file ${String(row.id)} key outside its tenant prefix; object not deleted`);
+        }
+        else {
+            objectDeleted = await this.deleteObject(store, key, 'post-commit');
+        }
+        try {
+            await this.audit.record(this.event(actor, 'delete', row, { objectDeleted, outcome: 'success' }));
+        }
+        catch (cause) {
+            // The record delete is committed and audited by the pipe (`admin_action`); a failed
+            // file_access row must not invite a retry that now answers 403.
+            this.logger.error(`file_access delete audit failed (${errorName(cause)})`);
+        }
+    }
+    requireStore() {
+        if (this.objectStore === null || this.objectStore === undefined) {
+            throw new common_1.NotImplementedException(MSG_NOT_CONFIGURED);
+        }
+        return this.objectStore;
+    }
+    /**
+     * Delete an object; true when the store confirmed it. On failure log the key only, count the
+     * orphan and answer false. Never throws.
+     */
+    async deleteObject(store, key, phase) {
+        try {
+            await store.delete(key);
+            return true;
+        }
+        catch (cause) {
+            this.orphans += 1;
+            this.logger.error(`orphaned object after ${phase} delete failed (${errorName(cause)}): ${key}`);
+            return false;
+        }
+    }
+    /**
+     * A `file_access` failure event for a 403 (missing, foreign, malformed or engine-denied: one
+     * reason, since the caller may not learn which). Best effort; the 403 is thrown regardless.
+     */
+    async auditDenied(actor, action, id) {
+        try {
+            await this.audit.record(this.event(actor, action, id, { outcome: 'failure', reason: 'denied_or_missing' }));
+        }
+        catch (cause) {
+            this.logger.error(`file_access denial audit failed (${errorName(cause)})`);
+        }
+    }
+    /** A `file_access` failure event (best effort; the 503 is thrown regardless). */
+    async auditFailure(row, actor, reason) {
+        try {
+            await this.audit.record(this.event(actor, 'read', row, { outcome: 'failure', reason }));
+        }
+        catch (cause) {
+            this.logger.error(`file_access failure audit failed (${errorName(cause)})`);
+        }
+    }
+    /** `target` is the fetched row, or for a denial only the requested uuid (null if malformed). */
+    event(actor, action, target, attributes) {
+        const row = typeof target === 'string' || target === null ? null : target;
+        const recordId = row !== null ? String(row.id) : target;
+        const recordTenant = row !== null ? (0, engine_1.canonicalUuid)(row.fields.tenantId) : null;
+        return {
+            type: 'file_access',
+            occurredAtMs: Date.now(),
+            actorId: actor.id,
+            tenantId: actor.tenantId,
+            action: { key: action },
+            resource: {
+                level: 'record',
+                typeKey: TYPE_KEY,
+                ...(recordId !== null ? { recordId } : {}),
+                ...(recordTenant !== null ? { tenantId: recordTenant } : {}),
+            },
+            attributes,
+        };
+    }
+};
+exports.FilesService = FilesService;
+exports.FilesService = FilesService = FilesService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [Function, Object, Object, Array])
+], FilesService);
+/** A 403-class outcome: our own missing/foreign/malformed refusal or an engine gate deny. */
+function isDenial(cause) {
+    return cause instanceof common_1.ForbiddenException || cause instanceof engine_1.AuthorizationDeniedError;
+}
+function errorName(cause) {
+    return cause instanceof Error ? cause.name : 'error';
+}

package/dist/features/framework-schemas.token.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The framework database names `IdentityFeatureModule.forRoot` resolved (configurable-framework-db,
+ * ADR-0037), for identity services Nest constructs (e.g. `UserService`'s email-change audit sink),
+ * so they use the SAME set as every store forRoot builds, not a second env read. Internal to
+ * identity; guard's `FRAMEWORK_SCHEMAS` is checked equal at boot.
+ */
+export declare const IDENTITY_FRAMEWORK_SCHEMAS: unique symbol;
+//# sourceMappingURL=framework-schemas.token.d.ts.map

package/dist/features/framework-schemas.token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"framework-schemas.token.d.ts","sourceRoot":"","sources":["../../src/features/framework-schemas.token.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,eAAuC,CAAC"}

package/dist/features/framework-schemas.token.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IDENTITY_FRAMEWORK_SCHEMAS = void 0;
+/**
+ * The framework database names `IdentityFeatureModule.forRoot` resolved (configurable-framework-db,
+ * ADR-0037), for identity services Nest constructs (e.g. `UserService`'s email-change audit sink),
+ * so they use the SAME set as every store forRoot builds, not a second env read. Internal to
+ * identity; guard's `FRAMEWORK_SCHEMAS` is checked equal at boot.
+ */
+exports.IDENTITY_FRAMEWORK_SCHEMAS = Symbol('IDENTITY_FRAMEWORK_SCHEMAS');

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

@@ -1,4 +1,5 @@
 import { type DynamicModule } from '@nestjs/common';
+import { type FrameworkSchemas } from '@astram/core';
 import { type ObjectTypeInput } from '@astram/engine';
 /**
  * The boot check behind {@link IDENTITY_DECISION_AUTHORITY_CHECK}: with this module wired, the
@@ -8,6 +9,27 @@ import { type ObjectTypeInput } from '@astram/engine';
  * different registry. (Another source next to this one is refused by `ShieldModule` itself.)
  */
 export declare function assertRequestPathUsesIdentityAuthorization(authority: unknown): true;
+/**
+ * The boot check behind {@link IDENTITY_FRAMEWORK_SCHEMAS_CHECK} (configurable-framework-db,
+ * ADR-0037; reviewer R2): the names `IdentityFeatureModule.forRoot` resolved — and handed to the
+ * engine, the audit sinks, the reader and every identity store — must equal guard's
+ * `FRAMEWORK_SCHEMAS`, or engine/guard/identity would split across databases. A guard that
+ * provides no `FRAMEWORK_SCHEMAS` (older than this seam) may only run on the default names.
+ * Throws (fail closed) with the namespaces and names only.
+ */
+export declare function assertFrameworkSchemasAgree(identity: FrameworkSchemas, guard: FrameworkSchemas | null | undefined): true;
+/**
+ * The boot check behind {@link IDENTITY_FRAMEWORK_DATABASE_CHECK} (G-007 QA P2-5): the runtime
+ * database identity's engine and authz pool connect to (derived from `forRoot({ schemas })`)
+ * must equal guard's `APP_CONFIG.db.database`, or unqualified queries of guard and identity would
+ * land in different databases. No guard `APP_CONFIG` visible ⇒ nothing to compare. Throws (fail
+ * closed) with database names only.
+ */
+export declare function assertFrameworkDatabaseAgrees(identityDatabase: string, guardConfig: {
+    readonly db?: {
+        readonly database?: string;
+    };
+} | null | undefined): true;
 /**
  * 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
@@ -34,10 +56,16 @@ export declare class IdentityFeatureModule {
      *   cross-tenant / policy authority, grant ceiling, guided rule-builder schema and owner-share
      *   resolver. Without them a consumer type is unregistered everywhere (denied), not policy-
      *   authorable and not shareable ("type '…' is not registered — cannot share").
+     * @param schemas the resolved framework database names (configurable-framework-db, ADR-0037).
+     *   Absent ⇒ resolved ONCE here from `SHIELD_DB_NAMESPACE` (unset ⇒ `shield_*`; invalid ⇒
+     *   throws). The one set is handed to the engine (registrations + its audit sink), the seven
+     *   audit sinks, the audit reader and every identity store; a boot check refuses names that
+     *   differ from guard's `FRAMEWORK_SCHEMAS`. Never read per request.
      */
-    static forRoot({ rootIds, extraObjects, }?: {
+    static forRoot({ rootIds, extraObjects, schemas: givenSchemas, }?: {
         rootIds?: readonly string[];
         extraObjects?: readonly ObjectTypeInput[];
+        schemas?: FrameworkSchemas;
     }): DynamicModule;
 }
 //# sourceMappingURL=identity-feature.module.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"identity-feature.module.d.ts","sourceRoot":"","sources":["../../src/features/identity-feature.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpE,OAAO,EAYL,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AAgGxB;;;;;;GAMG;AACH,wBAAgB,0CAA0C,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI,CAUnF;AAoBD;;;;;;;;;;GAUG;AACH,qBACa,qBAAqB;IAChC;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,OAAO,CAAC,EACb,OAAO,EACP,YAAiB,GAClB,GAAE;QACD,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QAC5B,YAAY,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;KACtC,GAAG,aAAa;CAoevB"}
+{"version":3,"file":"identity-feature.module.d.ts","sourceRoot":"","sources":["../../src/features/identity-feature.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpE,OAAO,EAGL,KAAK,gBAAgB,EAEtB,MAAM,cAAc,CAAC;AACtB,OAAO,EAeL,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AA0GxB;;;;;;GAMG;AACH,wBAAgB,0CAA0C,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI,CAUnF;AAKD;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,gBAAgB,EAC1B,KAAK,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,GACzC,IAAI,CAuBN;AAKD;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAC3C,gBAAgB,EAAE,MAAM,EACxB,WAAW,EAAE;IAAE,QAAQ,CAAC,EAAE,CAAC,EAAE;QAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,GAC/E,IAAI,CAQN;AAwBD;;;;;;;;;;GAUG;AACH,qBACa,qBAAqB;IAChC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,OAAO,CAAC,EACb,OAAO,EACP,YAAiB,EACjB,OAAO,EAAE,YAAY,GACtB,GAAE;QACD,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QAC5B,YAAY,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;QAC1C,OAAO,CAAC,EAAE,gBAAgB,CAAC;KACvB,GAAG,aAAa;CA2jBvB"}