@astram/guide 0.2.28 → 0.2.30

package/CAPABILITIES.md

@@ -89,7 +89,13 @@ imports: [
   `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.
+  409 reveals that another tenant holds the value (the engine now warns at boot, naming the index).
+  Likewise give a `subtreeSubquery` type's scope column and its parent key the same character set
+  and collation: a mismatch is also warned at boot, and its reads fail with errno 1267.
+- **Moving a row out of scope** — a non-root update that sets a `readScope` type's scope column to a
+  value outside the actor's subtree answers `update_outside_write_scope` (403) before any write.
+  Mark the scope column `immutable: true` if rows must never move; otherwise in-subtree moves stay
+  allowed. A patch that re-sends the scope column costs one extra probe query.
 
 ## Authentication and sessions (`@astram/guard`, `auth: true`)
 - `POST /auth/login` `{ identityHint, password }` → `{ session, tokens }`, or an MFA challenge.
@@ -248,7 +254,8 @@ imports: [
   `company` = `{ name, departments?, branches?, roles?: [{ name, permissions }], users?:
   [{ username, email, company?, postings?: [{ role, department?, branch? }] }], agent?: { mode },
   children? }`. `agent.mode` (`off` | `synthetic`, identity 0.26) sets that company's AI assistant
-  mode (below); no `agent` key leaves it unchanged.
+  mode (below); no `agent` key leaves it unchanged. A file can never set `live`, and a run refuses
+  (`agent_mode_live_locked`) to change a company whose admins approved client data.
   Unknown fields, unknown permission keys (allowed: catalog keys plus `<feature>:*` and
   `<feature>:<type>:*`), duplicate usernames or emails and references to undeclared roles,
   departments or branches are refused before any write. No password, uuid or secret in the file.
@@ -915,7 +922,8 @@ grant a tenant-wide `stored_file` rule for this.
   server executes. The runtime never calls your app; each capability call it asks for runs inside the
   user's own streaming request, as that user, through the record pipe and `decide()`, recorded in
   `agent_action` before it runs. M1: **`read` and `compute` capabilities only**; no workers, no
-  writes or proposals (M3), no chat UI in the template, synthetic data only (Rule 8).
+  writes or proposals (M3), no chat UI in the template, synthetic data by default (Rule 8; real
+  client data is a separate gated path, see "Client data to a model provider" below).
 - **Capabilities.** `defineCapability({ id, version, title, description, effect: 'read' |
   'compute', dataClass: 'internal' | 'confidential' | 'restricted', requires: [keys], input,
   output, limits?, handler, toEvidence?, partial? })`, or `inject` + `factory` for app services.
@@ -979,6 +987,8 @@ grant a tenant-wide `stored_file` rule for this.
   - 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`.
+    Attaching reads no file content (metadata only); a user may start or continue with attachments at most
+    30 times a minute, then `429 attach_rate_limited` (retryable).
   - 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/`.
@@ -1053,6 +1063,76 @@ grant a tenant-wide `stored_file` rule for this.
     opts out and adds a caution to the kind's `review` / `apply` permission text. Terminal proposals
     are deleted after `PROPOSAL_RETENTION_DAYS` (365, 30–3650); their audit rows stay.
   - Not yet: a review page in the scaffolded template.
+- **Client-data approval routes (model-provider-client-data phase P2; guard, identity).** A tenant
+  admin approves sending this company's real data to ONE deployment-approved model provider profile.
+  The routes, the stored approvals and the audit trail are described here; how a run uses an approval
+  is in "Client data to a model provider" below. All routes are gated
+  on the new key `identity:agent:client_data_approve`, which is **assigned to no role by default**;
+  note that a role holding `identity:*` or `identity:agent:*` covers it, like `restricted_data`.
+  - `GET /identity/agent/client-data`: the deployment approvals (profile, provider, region, retention,
+    data classes, file content, contract reference, approved by / on; no secrets), whether two-person
+    approval is on, and this company's approvals with history, newest first (≤ 200; people shown by
+    name, never by id).
+  - `POST /identity/agent/client-data/approvals` `{ profile, dataClasses, fileContent, reason, code }`:
+    request an approval. `code` is the admin's own current authenticator code (step-up). With
+    two-person approval (the default) the request is `pending`; without it the approval is `active`
+    at once. `internal` is always included in the classes; the classes and the file flag cannot go
+    beyond the deployment approval.
+  - `POST …/approvals/:uuid/confirm` `{ code }`: a **different** administrator confirms a pending
+    request (step-up again); the deployment approval must still match.
+  - `POST …/approvals/:uuid/revoke` `{ reason }`: revoke a pending or active approval. No step-up
+    (revoking must be fast). The revocation is recorded in Redis first and then in the database; if
+    Redis cannot take it, nothing changes (`503 revoke_unavailable`, retry).
+  - Fixed error codes (`{ statusCode, code, message }`): `profile_not_client_data`,
+    `classes_exceed_deployment`, `file_content_not_allowed`, `invalid_request` (400);
+    `step_up_required`, `confirmer_is_requester`, `forbidden` (403); `approval_not_found` (404, also
+    another company's approval); `approval_pending_exists`, `approval_active_exists`,
+    `approval_not_pending`, `approval_not_revocable`, `approval_state_changed`, `deployment_changed`
+    (409); `too_many_requests` (429); `revoke_unavailable`, `authentication_unavailable`,
+    `unavailable` (503).
+  - An approval writes the company's mode `live`; revoking the last active one writes `off` (never
+    `synthetic`). Org bootstrap still sets `off` / `synthetic` only, and **refuses to change a `live`
+    company** (`agent_mode_live_locked`; revoke in the application first). The refusal comes with
+    `--apply`; a dry run shows the company as `live → <file mode>` and writes nothing. A company that
+    turns `live` after the plan was made is refused again under the row lock, so earlier steps of that
+    run may already have been applied.
+  - Every request, approval and revocation is an `admin_action` audit row
+    (`agent.client_data.requested` / `.approved` / `.revoked`) with the profile, provider, contract
+    reference, classes, file flag and reason; never data. Rows are never deleted.
+  - `@astram/agent` binds `SHIELD_AGENT_CLIENT_DATA_PROFILES` to the booted `client_data` profiles. A
+    profile that did not boot is not approvable: a request answers `400 profile_not_client_data`.
+- **Client data to a model provider (`@astram/agent`, model-provider-client-data).** Two approvals,
+  neither a code constant. (1) The deployment: a model profile with
+  `providerApproval: { scope: 'client_data', reference, region, retentionDays, dataClasses,
+  approvedBy, approvedOn, fileContent, providerSmoke: { id, date }, runtimeConformance: { id, date,
+  runtimeVersion } }` and the env `AGENT_CLIENT_DATA=1`. (2) The company: its administrators approve
+  the profile through the routes above, which writes mode `live`. Nothing changes unless
+  `AGENT_CLIENT_DATA=1` AND a `client_data` profile are both present. The process must not run with
+  `NODE_TLS_REJECT_UNAUTHORIZED=0` (or `false`): boot refuses it for a `client_data` profile and the
+  runtime client pins certificate verification.
+  - Env, read only with `AGENT_ENABLED=1` (with the agent disabled `AGENT_CLIENT_DATA` is ignored and
+    one fixed boot line says so): `AGENT_CLIENT_DATA` (`0` default | `1`) and
+    `AGENT_EGRESS_POLICY_ACK` (`<verificationId>@<YYYY-MM-DD>`, at most 180 days old).
+    `AgentModule.forRoot({ clientData: { twoPerson } })` defaults to `true`; `false` logs a warning at
+    every boot.
+  - A `client_data` profile boots only when, in this order, `env`, `masking`, `outbound_audit`,
+    `egress_verification`, `runtime_conformance`, `provider_smoke` and `https` hold (boot error
+    `modelProfiles.<name>: client_data_prerequisite (<which>)`; an `http:` runtime URL is refused in
+    every environment, loopback included). With all of them met the profile boots.
+  - A client-data run sends `dataScope: "client_data"` in its signed run request and only to a
+    runtime whose verified `GET /v0/info` lists `client_data` and the `data-scope` feature at an
+    agent-protocol minor at least the app's; otherwise the run ends `data_scope_unsupported` before
+    anything is sent (the runtime must be on agent-protocol 0.5 or later, over `https:`, ideally with
+    its durable state backend). Synthetic runs are unchanged. When the runtime lists `answers.v1`, an
+    answers turn also sends the structured answers (free text masked; the flattened message copy is
+    not). The app sends `history` unchanged: the runtime treats it as an untrusted data block
+    (agent-protocol 0.5, a runtime requirement).
+  - A run on a `live` company needs a booted `client_data` profile with an active approval, else
+    `403 agent_client_data_not_approved`. The approval is read on every call and every send (revoke
+    marker first, never cached); when it ends or narrows the task stops with `client_data_revoked`.
+    A capability's data class must be in the approval's classes. File content goes to the provider
+    only if the approval allows it (decided per run); org bootstrap still refuses a non-empty
+    `agent.fileProviders` outside development/test. Masking is always on.
 
 ## Available, but NOT wired to a data path (do not assume they protect data yet)
 - **Envelope encryption / per-tenant DEKs** (`createEncryptionService`, `LocalKekCrypto`): the

package/FRAMEWORK_RULES.md

@@ -180,9 +180,11 @@ makes every model call and never calls your app.
   lists rows returns how many exist, not only the page.
 - **No uuids to the model.** Return handles (`ctx.handle(uuid, typeKey)`) and declare handle inputs
   with `"x-astram-handle"`; never put a uuid, id or hex digest in a capability's output.
-- **Synthetic data only.** Enable a tenant (`agent: { mode: "synthetic" }` in the org bootstrap
-  file) only when it holds synthetic data. Never set a model profile's `providerApproval.scope` to
-  `client_data`; the framework refuses it until real data is approved.
+- **Synthetic data by default.** Enable a tenant (`agent: { mode: "synthetic" }` in the org bootstrap
+  file) only when it holds synthetic data. Do not set a model profile's `providerApproval.scope` to
+  `client_data` or `AGENT_CLIENT_DATA=1` unless the platform owner has approved real data for that
+  provider; the company's administrators then approve it in the application (see
+  "Client data to a model provider" in CAPABILITIES.md). Never write a `live` mode yourself.
 
 ---
 

package/package.json

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