@astram/guide 0.2.26 → 0.2.28

package/CAPABILITIES.md

@@ -82,7 +82,14 @@ imports: [
 - **Live roles** — a role posting change, a grant change or a user disable bumps the permission
   version; the next request reloads facts and roles. No re-login needed.
 - **Engine errors → HTTP** — `AuthorizationDeniedError` → 403, `ValidationError` → 400,
-  `EngineUnavailableError` → 503 for your controllers too (global filter; id-free messages).
+  `EngineUnavailableError` → 503, `UniqueConflictError` → 409 `unique_conflict` for your
+  controllers too (global filter; id-free, value-free messages).
+- **Duplicate keys** — a create / update that hits a UNIQUE index throws `UniqueConflictError`
+  (`typeKey`, `constraint` = the index name, `rowIndex` for `createMany`). Match it with
+  `isUniqueConflict(err, '<constraint>')`, never by message text. Inside `transaction(fn)` the
+  transaction is then rollback-only (a further write is a 503): re-read in a fresh transaction for
+  the idempotent answer. On a tenant type, lead every UNIQUE index with the tenant column, or a
+  409 reveals that another tenant holds the value.
 
 ## Authentication and sessions (`@astram/guard`, `auth: true`)
 - `POST /auth/login` `{ identityHint, password }` → `{ session, tokens }`, or an MFA challenge.
@@ -748,6 +755,51 @@ upload(@Req() req: Record<string, unknown>) {
 - Not provided: malware scanning, per-tenant encryption of file bytes (SSE-S3 only), streaming
   downloads, dedup (each upload is its own record; `sha256` is returned so you can detect repeats).
 
+### Sharing an attached file with a role (`SHIELD_FILE_SHARE`, guard 0.33, identity 0.32; ADR-0040 addendum)
+Use this when users of a role in the same company must read a file attached to one of your records
+("the stewards of a source read its revision file"). Never write `record_share` yourself and never
+grant a tenant-wide `stored_file` rule for this.
+1. **Declare the attachment field** on your parent type: `@Field({ type: 'uuid', references:
+   'stored_file' })`. The type must be tenant-walled (a `trusted: 'tenantId'` field), data plane,
+   not global, not `operationReads`, with a uuid primary key, and the field must not be `trusted`.
+   A type that declares such a field but breaks a rule fails boot naming the type and field; boot
+   logs one line `file-share parents: <type> (<fields>)`.
+2. **Inject the port** in an app service (not an agent capability: that fails agent boot,
+   `inject_framework`):
+   ```ts
+   import { Inject } from '@nestjs/common';
+   import { SHIELD_FILE_SHARE, FileShareError, type FileSharePort } from '@astram/guard';
+   constructor(@Inject(SHIELD_FILE_SHARE) private readonly fileShare: FileSharePort) {}
+   const r = await this.fileShare.shareWithRole(fileId, roleId, { typeKey: 'source', id: sourceId });
+   // r = { created, effective, missing }
+   ```
+   It is request-scoped: actor and tenant come from the session, no argument names them. The caller
+   must be able to `update` the parent and read the file itself; the parent must reference the file
+   and the role must belong to the same company. Each call runs in one transaction (it joins yours;
+   a refusal then rolls yours back).
+3. **The role still needs `identity:stored_file:read`.** The port never grants it. Without it the
+   share is written and `shareWithRole` returns `{ effective: false, missing:
+   ['identity:stored_file:read'] }`; it works with no further call once the key is granted.
+4. **Revoke in the same transaction as the detach, deactivate or delete.** Call
+   `unshare(fileId, roleId, parent)` when you detach a file (it works after the detach) and
+   `revokeForParent(parent)` before you deactivate or delete the parent. A share outlives its reason
+   if you skip this. After a parent is already deleted, `revokeForParent` still works for a caller
+   holding the parent type's `delete` key. `reconcileFile(fileId)` removes the file's port rows
+   whose parent is gone, no longer references it or is no longer eligible (any user who can read
+   the file); `listForParent(parent)` returns `{ fileId, roleId, createdAtMs }[]`. Those ids are
+   for linking only: resolve them to labels (role name, file display name) before showing them,
+   and never show a raw id in the UI.
+- **Errors** (`FileShareError.code`, fixed messages, `httpStatus`): `file_share_invalid` 400
+  (malformed id, ineligible parent type), `file_share_not_found` 404 (any missing, hidden, foreign
+  or unattached id; root or tenantless caller), `file_share_denied` 403 (caller reads but may not
+  update the parent), `file_share_unavailable` 503 (database or audit outage; rolled back).
+- **Audit and owner view.** Each change writes `share.created` / `share.removed` with operation
+  `shield:file-share` (`FILE_SHARE_OPERATION` from `@astram/identity`), step, parent type and id,
+  never the file name. The file owner (or a user `decide()` allows to `update` the file) sees these
+  rows in `GET /identity/record-shares` as `via: <parent type label>`, `removable: false`; deleting
+  one there answers 403 `This share is managed by a linked record.`
+- Run `astram-migrate` before deploying (guard migration 126 on `record_share`); no env change.
+
 ## Database names and several environments on one server (`SHIELD_DB_NAMESPACE`, ADR-0037)
 - The framework uses four databases, `<ns>_app`, `<ns>_identity`, `<ns>_authz` and `<ns>_audit`,
   with its own accounts (`<ns>_core`, `<ns>_migrate`, `<ns>_audit_ops`, …). If you leave
@@ -972,11 +1024,20 @@ upload(@Req() req: Record<string, unknown>) {
   **propose**, and a person applies.
   - Declare what a change means with `defineProposalKind({ id, version, label, payloadSchema,
     targetTypes: [oneAppType], keys: { propose, review, apply }, plan, validate?, preview?,
-    distinctApprover?, maxItems?, expiryMs? })` (`@astram/identity`) and pass it to
-    `IdentityFeatureModule.forRoot({ proposalKinds })`. `plan` turns a payload into `create` /
-    `update` items on that one type; `plan` and `validate` get a read-only `ctx.records`. There is no
-    apply handler: the framework writes the approved items through the record pipe as the approver,
-    in one transaction, with read-back. The three keys are custom actions on an app type (ADR-0038).
+    distinctApprover?, maxItems?, expiryMs?, screen?, screenCodes?, submit? })` (`@astram/identity`)
+    and pass it to `IdentityFeatureModule.forRoot({ proposalKinds })`. `plan` turns a payload into
+    `create` / `update` items on that one type; `plan` and `validate` get a read-only `ctx.records`.
+    There is no apply handler: the framework writes the approved items through the record pipe as the
+    approver, in one transaction, with read-back. The three keys are custom actions on an app type
+    (ADR-0038).
+  - To check a draft before anything is stored (for example personal data in a label), give the kind
+    `screen({ payload, title, rationale, metadata }, ctx)` and the codes it may refuse with in
+    `screenCodes`. It runs on every submit path (the HTTP route, your own code through
+    `SHIELD_PROPOSAL_PORT`, the assistant). Return `{ refuse: '<code>' }` to refuse: the caller gets
+    422 `screened` with that code, and no proposal, audit row or notice is written. A throw or an
+    undeclared code refuses too (`screen_failed`). Do not screen in `validate`: its refusals are stored.
+    `submit: 'app-only'` stops the generic `POST /identity/proposals` route for that kind, so only your
+    own routes (through `SHIELD_PROPOSAL_PORT`) and the assistant can submit it.
   - A capability with `effect: 'propose'`, `proposes: [kindIds]` and `requires` including
     `identity:agent:propose` returns a draft `{ kind, payload, title, rationale?, metadata? }`; the
     framework submits it as the user. The model gets a handle and counts; the browser gets

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astram/guide",
-  "version": "0.2.26",
+  "version": "0.2.28",
   "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",