@astram/guide 0.2.23 → 0.2.25

package/CAPABILITIES.md

@@ -625,10 +625,34 @@ upload(@Req() req: Record<string, unknown>) {
   name: multer reports it as an unexpected file), `empty`, `bad_request` (malformed or truncated
   multipart, raw control characters in part headers); 413 `too_large`; 415 `type_not_allowed`,
   `content_mismatch`. Raw UTF-8 and RFC 5987 (`filename*=UTF-8''…`) file names decode to the
-  same name. Size: the route cap defaults to the profile's configured cap
-  (`OBJECT_STORAGE_MAX_BYTES` under `storage: 'env'`, else 10 MiB); `maxBytes` can only lower it.
-  Profiles: `xlsx` only (50 MiB hard ceiling for any profile, route or env value). Needs
+  same name. Size: the route cap defaults to the profile's configured cap (below); `maxBytes` can
+  only lower it. A route naming a profile the app did not register aborts boot. Needs
   `@nestjs/platform-express` (an optional peer; the scaffold has it).
+- **Profiles** — turn them on with `ShieldModule.forRoot({ fileProfiles: ['xlsx', 'csv', 'pdf', 'docx'] })`
+  (default `['xlsx']`; an unknown, repeated or empty list aborts boot). You cannot define your own.
+  | Profile | Default cap | Declared types accepted (stored as the first) | Content check |
+  |---|---|---|---|
+  | `xlsx` | 10 MiB | spreadsheetml `.sheet` | ZIP + `[Content_Types].xml` names a spreadsheetml main part |
+  | `csv` | 10 MiB | `text/csv`, `application/csv`, `text/plain`, `application/vnd.ms-excel` | valid UTF-8 (BOM allowed), no NUL byte, not blank |
+  | `pdf` | 20 MiB | `application/pdf`, `application/x-pdf` | `%PDF-` in the first KiB, `%%EOF` in the last KiB, not encrypted (`/Encrypt`) |
+  | `docx` | 10 MiB | wordprocessingml `.document` (`.docx` only, not `.docm`) | ZIP + `[Content_Types].xml` names a wordprocessingml main part |
+
+  Caps: when `OBJECT_STORAGE_MAX_BYTES` is set (under `storage: 'env'`) it is the cap of every
+  registered profile; unset, each keeps its default. 50 MiB is the hard ceiling for any profile,
+  route or env value. The stored type is always the profile's first type, whatever allowed type
+  the browser declared.
+- **Archive limits (`ZIP_LIMITS`, xlsx and docx)** — read from the zip's central directory before
+  anything is decompressed; a breach is 415 `content_mismatch`: at most 10 000 entries, 256 MiB
+  declared uncompressed in total, a compression ratio of at most 100 for any entry over 1 MiB,
+  methods stored/deflate only, no encrypted entry, no zip64, one `[Content_Types].xml`, a
+  well-formed end record and central directory, no entry name with `..`, `\`, a leading `/`, a
+  drive letter or a control character, and no nested archive (`.zip`, `.jar`, `.7z`, `.rar`,
+  `.gz`, `.tar`, `.xlsm`, `.docm`, `.xlsx`/`.docx`/`.pptx` outside the embeddings folders, or a
+  stored entry that is itself a zip).
+  Embedded Office objects (`.xlsx`, `.docx`, `.pptx`) are allowed under `word/embeddings/` and
+  `xl/embeddings/` (a Word chart keeps its data there); they count toward the limits and are never
+  opened. Files Office, LibreOffice, Google and common zip libraries write pass; a file with bytes
+  added after the zip's end record (some mail gateways pad attachments) is refused.
 - **`FilesService`** (provided by `IdentityFeatureModule`) — `store(intake)`, `open(uuid)`,
   `remove(uuid)`. No actor argument: tenant, owner and audit actor come from the session. `store`
   puts the object at `t/<tenant>/<uuid>`, then creates the record (gate, tenant stamp, audit); a
@@ -638,7 +662,8 @@ upload(@Req() req: Record<string, unknown>) {
   your own record that points at the file. Missing and foreign answer the same 403; non-uuid 400.
   The bytes are re-hashed against the stored sha256. Headers: `Content-Disposition: attachment`
   (RFC 5987 name), `X-Content-Type-Options: nosniff`, `Cache-Control: no-store`, and
-  `Content-Type` from the record when it is an allowlisted type, else `application/octet-stream`.
+  `Content-Type` from the record when it is the type of a registered profile, else
+  `application/octet-stream`.
 - **Status codes** — storage not configured (no `storage` option or `OBJECT_STORAGE_BUCKET`
   unset) ⇒ 501 from `FilesService` and the route; store down, stored object missing or sha256
   mismatch ⇒ 503 with a fixed message.
@@ -649,13 +674,14 @@ upload(@Req() req: Record<string, unknown>) {
   `OBJECT_STORAGE_ENDPOINT` (`https:`; `http:` only in development/test or to a loopback host),
   `OBJECT_STORAGE_REGION` (default `us-east-1`), `OBJECT_STORAGE_ACCESS_KEY_ID`,
   `OBJECT_STORAGE_SECRET_ACCESS_KEY`, `OBJECT_STORAGE_SSE` (`AES256` only),
-  `OBJECT_STORAGE_MAX_BYTES` (plain decimal bytes, no leading zeros; the per-file cap for the
-  `xlsx` profile and every `FileIntake` route). Outside development/test the two credentials must be
+  `OBJECT_STORAGE_MAX_BYTES` (plain decimal bytes, no leading zeros; when set, the per-file cap
+  for every registered profile and so every `FileIntake` route; unset, each profile's default). Outside development/test the two credentials must be
   `secret-ref:` values resolved at boot; a literal is refused. With `storage: 'env'` the bucket is
   pinged at boot (probe put/get/delete under `_probe/`); failure aborts boot.
-- **Your xlsx parser must cap entry count and total uncompressed size.** The framework checks only
-  the zip header and `[Content_Types].xml`, not every entry, so a zip bomb in another part passes
-  the upload check.
+- **Your xlsx/docx parser must still bound what it inflates.** The upload checks the sizes each
+  entry declares; only `[Content_Types].xml` is decompressed. A parser must stop when real output
+  passes the limits, and must not open embedded objects. Csv row/column and pdf page limits are
+  the parser's too.
 - **Lint wall** — the scaffold bans `multer`, `@aws-sdk/*`, `minio`, `fs` / `node:fs` (and
   `/promises`) in `src/features/**`: use `FileIntake` and `FilesService`, never the bucket.
 - Roles that upload need `stored_file:create` (FilesService creates the record as the caller), but app code must create `stored_file` rows only through `FilesService.store()` — never `records.create('stored_file', …)` / `createMany`, which would let a caller set its own `storageKey` (downloads still refuse a key outside the caller's tenant, KI #137).
@@ -831,6 +857,28 @@ upload(@Req() req: Record<string, unknown>) {
 - **Migrations** 111–113 (identity) add `agent_task`, `agent_action`, `agent_tenant_setting` to
   `<ns>_identity`. Single layout: re-run `db-provision --layout single` after migrating; check with
   `db-verify-grants` and the app's layout flags.
+- **Reading attached files (G-037 D2a, opt-in).** `AgentModule.forRoot({ files: { enabled: true } })`
+  registers framework capabilities `files.read_sheet@1` (xlsx/csv, ≤ 200 rows a call), `files.profile_sheet@1`
+  (per-column type, empty and distinct counts, min/max, top values, computed in code),
+  `files.read_pdf_text@1` (text layer, ≤ 10 pages), `files.read_doc_text@1` (docx text, ≤ 20000 chars) and
+  `schema.describe@1` (the object types the user can read, never rows). Requires `identity:stored_file:read`.
+  - Files enter a conversation as `attachments` (0–8 `stored_file` uuids your own `FileIntake` route returned)
+    on `POST /agent/tasks` and on `continue` with a message. The runtime only ever gets task handles; any file
+    the user cannot open answers one `404 attachment_unavailable`; a bad list `400 invalid_request`.
+  - Every byte is parsed by the isolated analyser `@astram/file-analyser` (Python): never formulas, macros,
+    links or embedded objects. Run it as the sidecar container (`docker-compose.analyser.yml` in the
+    scaffold: no network, read-only, non-root) or as the hardened systemd unit in the package's `deploy/`.
+    Env (read only when `files` is on): `AGENT_FILE_ANALYSER_SOCKET` (required),
+    `AGENT_FILE_ANALYSER_TIMEOUT_MS` (12000, 1000–60000).
+  - File content is `confidential` and goes only to a model provider the company lists for file content:
+    org bootstrap `agent: { mode, fileProviders: [...] }` (migration 114, audited
+    `agent.tenant_file_providers.set`). Empty (default) ⇒ no file capability in the manifest. A non-empty
+    list is refused outside development/test while the synthetic-data rule stands, and personal-data
+    masking (not built yet) is a prerequisite before real data.
+  - Totals the assistant states come from `profile_sheet` or `aggregate`, never from adding rows it read.
+    Ids inside file content reach the model as `[id]`.
+  - Not yet: the attach control in the scaffold UI (the client service supports `attachments`), the
+    workbook map (D2b), marking an upload `restricted`.
 
 ## Available, but NOT wired to a data path (do not assume they protect data yet)
 - **Envelope encryption / per-tenant DEKs** (`createEncryptionService`, `LocalKekCrypto`): the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astram/guide",
-  "version": "0.2.23",
+  "version": "0.2.25",
   "license": "MIT",
   "description": "Astram framework — the AI/dev GUIDE layer (ADR-0025). Ships the framework's hard rules + capabilities manifest as installed, upgrade-refreshed docs. A consumer app's CLAUDE.md references FRAMEWORK_RULES.md from this package; `npm update` replaces it wholesale so new rules arrive cleanly, while the app's own .astram/guide/ layer is never touched. This is the framework-owned FLOOR: an app rule may tighten it, never weaken it.",
   "type": "commonjs",