@flowdular/sdk 0.3.0 → 0.3.1

package/.ai/platform-capabilities.md

@@ -50,7 +50,7 @@ Read this file before writing or implementing a spec. It replaces scanning `modu
 
 **Automations triggers.** Two mechanisms in `automations.core`. A schedule uses a cadence string in one of two forms (`modules/automations/src/domain/cadence.ts`): `every:N`, where `N` is whole minutes from 1 to 10080 and the unit is implicit, or `cron:<minute> <hour> <day of month> <month> <day of week>`, five fields with no seconds, at most 100 characters, each field `*`, a number, a three letter month or weekday name, a list, a range, or any of those with a step (`*/15`, `9-17/4`); both day fields restricted means either matches. A cron slot is a wall clock time in the workspace zone from the shared `system.core.timeZone` setting, stored in UTC; a wall time a daylight saving change removes is skipped and one that occurs twice fires at the first of the two. An expression the module cannot honour is refused at save with `INVALID_CADENCE`. Missed slots are skipped, never replayed. An inbound webhook posts to `POST /api/automations/triggers/:id/fire`, authenticated by an HMAC signature in `x-flowdular-signature` with `x-flowdular-timestamp` inside a 5 minute window and a 16 KB body cap, answering `202 { accepted, runId }`. Targets are pluggable through `automations.targets.v1`; the shipped kinds are `agent` and `workflow`.
 
-**CLI extensions.** A module contributes `pnpm flowdular <namespace> <action>` through `src/cli/commands.json` plus `defineCliExtension` (`packages/cli-protocol/src/index.ts`), declared in `module.json` under `cli`. The first path segment must equal the module id's first segment and may not be a reserved group (`help`, `doctor`, `capability`, `spec`, `blueprint`, `module`, `migration`, `setup`). Each command carries a `CapabilityDescriptor` with `id`, `version`, `summary`, `risk: 'read' | 'workspace-write' | 'process' | 'external' | 'destructive'`, `requiresApprovedSpec`, `supportsDryRun`, optional `localOnly` and `confirmation`. The runner refuses `external` always and non-local `destructive` always, gates `localOnly` to `development` and `test`, and treats every write command as a dry run without `--apply`.
+**CLI extensions.** A module contributes `pnpm flowdular <namespace> <action>` through `src/cli/commands.json` plus `defineCliExtension` (`packages/cli-protocol/src/index.ts`), declared in `module.json` under `cli`. The first path segment must equal the module id's first segment and may not be a reserved group (`help`, `doctor`, `capability`, `spec`, `blueprint`, `module`, `migration`, `setup`). Each command carries a `CapabilityDescriptor` with `id`, `version`, `summary`, `risk: 'read' | 'workspace-write' | 'process' | 'external' | 'destructive'`, `requiresApprovedSpec`, `supportsDryRun`, optional `localOnly` and `confirmation`. The runner refuses `external` and non-local `destructive` commands unless `--grant <token> --tenant <id>` carries a verified approval grant for the capability and the invocation digest, gates `localOnly` to `development` and `test`, and treats every write command as a dry run without `--apply`.
 
 **Translations.** The shipped locales are `en` and `pl`. A module keeps a flat bundle per locale in `translations/<locale>.json`, imports them in `src/client/contribution.tsrx` and returns `translations: { en, pl }`. Keys resolve fully qualified as `<first module segment>.<key>` through `t()`. `flowdular module validate` reports `TRANSLATION_FILE_MISSING`, `TRANSLATION_PARSE_ERROR`, `TRANSLATION_KEYS_MISMATCH` and `TRANSLATION_KEY_MISSING`.
 
@@ -66,7 +66,7 @@ Read this file before writing or implementing a spec. It replaces scanning `modu
 
 **Connectors.** `connectors.core` (optional) is the governed way out to an external system. A module ships a connector definition through the public capability `connectors.definitions.v1` (`modules/connectors/src/domain/definitions.ts`): `register({ key, moduleId, label, authKinds, operations: [{ key, label, method, path, inputSchema, outputSchema }], defaultAllowedHosts, allowedPorts? })` (ports default to 443 only), and the platform ships `http-json`. An owner creates an instance behind `connectors.instances.manage` with a base URL, sealed credentials under `FD_CONNECTORS_SECRET_KEY`, a host allowlist and two consent flags, `allowWorkflows` and `allowAgents`, both off. A call goes through `connectors.calls.v1`: `call({ tenantId, instanceId, operation, input, caller: 'test' | 'workflow' | 'agent', callerRef? })`, which enforces status, consent for that caller kind, the egress policy (https, no private addresses, no redirects, timeout and size caps) and logs the call without any body; `consented(tenantId, instanceId, caller)` answers admission alone. The agent tool `connectors.call` is declared `workspace-write` with the harness consent gate `connectors.instance-consent` (`AgentToolConsent` in `packages/harness/src/runtime.ts`), carries the full action contract (`idempotency: 'required'` backed by a per-call key ledger) so workflows may use it, has no HTTP route of its own, and dials only the addresses the egress policy verified, so the ceiling is raised per instance by the owner's consent, never by a declaration.
 
-**Approvals.** `approvals.core` (optional) turns a policy's `requiresApproval` into a request people decide. A module opens one through the public capability `approvals.requests.v1` (`modules/approvals/src/domain/capability.ts`): `open({ tenantId, subjectModule, subjectRef, permission, action, title, summary?, requesterAccountId, requirement, onResolved? })`, plus `get`, `list` and `cancel`. Eligible deciders are resolved at open from the requirement's role key and scope (both, when both are named; the requester never decides), re-read at decision time, and a request needs `decisions` approvals before `expiresInDays` runs out. Open is idempotent per subject while a request is pending, and a requirement that resolves to nobody, to too few or to more than 200 deciders is refused with a stable code. Decisions are an append-only ledger behind `approvals.requests.read`, `approvals.requests.decide` and `approvals.requests.manage`; deciders and requesters are notified through the kinds `approval-requested` and `approval-decided`. The subject module learns the outcome from `onResolved`, which runs once per terminal state after the deciding transaction commits, or by reading the request back.
+**Approvals.** `approvals.core` (optional) turns a policy's `requiresApproval` into a request people decide. A module opens one through the public capability `approvals.requests.v1` (`modules/approvals/src/domain/capability.ts`): `open({ tenantId, subjectModule, subjectRef, permission, action, title, summary?, requesterAccountId, requirement, onResolved? })`, plus `get`, `list` and `cancel`. Eligible deciders are resolved at open from the requirement's role key and scope (both, when both are named; the requester never decides), re-read at decision time, and a request needs `decisions` approvals before `expiresInDays` runs out. Open is idempotent per subject while a request is pending, and a requirement that resolves to nobody, to too few or to more than 200 deciders is refused with a stable code. Decisions are an append-only ledger behind `approvals.requests.read`, `approvals.requests.decide` and `approvals.requests.manage`; deciders and requesters are notified through the kinds `approval-requested` and `approval-decided`. The subject module learns the outcome from `onResolved`, which runs once per terminal state after the deciding transaction commits, or by reading the request back. A request whose `subjectRef` is `encodeCapabilitySubjectRef({ capabilityId, inputDigest })` yields, once approved, a signed token through `grant(tenantId, id, subjectModule)`, handed only to the module that opened it; the CLI runner takes it as `--grant` (valid until expiry) and the harness as `AgentExecutionRequest.grants` (one tool call per grant), both bound to the tenant, the capability id and `approvalInputDigest` of the input.
 
 **Documents.** `documents.core` (optional) owns file attachments of any record. A screen uploads through `POST /api/documents/upload` with the raw body and the headers `x-document-filename`, `x-document-owner-module`, `x-document-record-ref` and `x-document-description`, lists with `GET /api/documents?ownerModule=&recordRef=`, opens through `POST /api/documents/read-url` (a short-lived storage URL) and deletes through `POST /api/documents/delete`, all behind `documents.files.read` or `documents.files.manage` with CSRF first. A module reads its own records' attachments through the public capability `documents.attachments.v1` (`modules/documents/src/domain/attachments.ts`): `list(tenantId, ownerModule, recordRef)`, `open(tenantId, ownerModule, recordRef, id)` answering `{ contentType, bytes, filename, body }` or null for anything not readable (unknown, another pair, deleted, infected) and `delete(tenantId, ownerModule, recordRef, id)`; the reference pair is a scope, the caller's permission on its own record is the authorization, and the storage key never leaves documents.core. Checksums, scan verdicts and the object limits come from the storage port.
 

package/.ai/policies/capabilities.yaml

@@ -84,6 +84,12 @@ core:
     confirmation: restore-database
     supportsDryRun: true
     effect: 'replaces the configured database with the backup in <dir> (pg_restore --clean --if-exists, or a staged replacement of the embedded data directory); refuses BACKUP_ADAPTER_MISMATCH across adapters and warns BACKUP_KEY_MISMATCH when the running environment holds keys the backup was not taken with'
+  database.restore.production:
+    command: pnpm flowdular database restore-production --input <dir> --target <database> --grant <token> --tenant <id> [--allow-key-mismatch] [--platform-url <origin>|--platform-stopped] --apply --confirm restore-database
+    risk: destructive
+    confirmation: restore-database
+    supportsDryRun: true
+    effect: 'the same restore without localOnly, so it runs in any environment but only under a verified approval grant (see approvals.destructive-not-local; the grant binds --input, --target and every other capability flag); --target must repeat the database of the migrator DSN (the embedded data directory for pglite) or RESTORE_TARGET_MISMATCH; MIGRATOR_ROLE_REQUIRED when FD_DATABASE_MIGRATOR_URL is absent or equals FD_DATABASE_URL; a key divergence is a BACKUP_KEY_MISMATCH refusal unless --allow-key-mismatch is part of the approved invocation; with --apply, PLATFORM_RUNNING while <origin>/api/health (from --platform-url, else http://127.0.0.1:$FD_PORT) answers, and PLATFORM_STATE_UNKNOWN when no endpoint is named or the probe times out unless --platform-stopped attests the platform is down'
   workspace.state.migrate:
     command: pnpm flowdular setup migrate-state [--apply --confirm migrate-legacy-state]
     risk: destructive
@@ -146,6 +152,24 @@ modules:
       risk: process
       supportsDryRun: true
       note: re-seals stored trigger secrets with the current encryption key; batches of 200 rows in one tenant-scoped transaction each, idempotent, and never prints a secret
+  documents.core:
+    documents.storage.rotate:
+      command: pnpm flowdular documents secrets-rotate [--apply]
+      risk: process
+      supportsDryRun: true
+      note: re-seals stored document objects in place with the current storage encryption key; batches of 200 rows in one tenant-scoped transaction each, idempotent, leaves an object under an unknown key or one that fails authentication as it is, and never prints object content
+  exports.core:
+    exports.storage.rotate:
+      command: pnpm flowdular exports secrets-rotate [--apply]
+      risk: process
+      supportsDryRun: true
+      note: re-seals stored export files in place with the current storage encryption key; batches of 200 rows in one tenant-scoped transaction each, idempotent, leaves a file under an unknown key or one that fails authentication as it is, and never prints file content
+  connectors.core:
+    connectors.secrets.rotate:
+      command: pnpm flowdular connectors secrets-rotate [--apply]
+      risk: process
+      supportsDryRun: true
+      note: re-seals stored connector credentials with the current encryption key and recomputes their fingerprints under it; batches of 200 rows in one tenant-scoped transaction each, idempotent, leaves a row under an unknown key as it is, and never prints a credential
   notifications.core:
     notifications.secrets.rotate:
       command: pnpm flowdular notifications secrets-rotate [--apply]
@@ -240,14 +264,18 @@ modules:
 
 # packages/cli/src/runner.ts, runExtensionCommand, in evaluation order.
 approvals:
-  external: refused with APPROVAL_VERIFIER_REQUIRED (no signed approval verifier exists)
-  destructive-not-local: refused with APPROVAL_VERIFIER_REQUIRED
+  external: the same grant check as destructive-not-local; APPROVAL_VERIFIER_REQUIRED without a token or key
+  destructive-not-local: needs --grant <token> --tenant <id>, an approval grant verified under FD_APPROVAL_GRANT_KEY against the tenant, the capability id and the invocation digest (positional arguments plus every flag except --root, --json, --confirm, --grant and --tenant, so --apply is bound and an approval names the applied run, never a dry run); APPROVAL_VERIFIER_REQUIRED without a token or key, APPROVAL_GRANT_INVALID, APPROVAL_GRANT_EXPIRED or APPROVAL_GRANT_MISMATCH otherwise; the runner records no use, so a grant replays until it expires
   localOnly: refused with LOCAL_ONLY_CAPABILITY unless FD_ENV or NODE_ENV is development or test (unset counts as development)
   requiresApprovedSpec: needs --spec <path>; APPROVED_SPEC_REQUIRED, SPEC_VALIDATION_FAILED or SPEC_NOT_APPROVED otherwise
   destructive-apply: --apply needs --confirm <descriptor.confirmation>; CONFIRMATION_REQUIRED otherwise
   non-read-without-dry-run: EXPLICIT_APPLY_REQUIRED without --apply
   dry-run: non-read with supportsDryRun and no --apply runs with apply=false and warns "Dry run only. No writes were authorized."
 
+harnessGate:
+  localOnlyTools: CLI tools whose capability is localOnly are refused by the harness with TOOL_LOCAL_ONLY outside development and test, grant or not
+  grantedTools: external tools and non-local destructive CLI tools are offered only when the run carries a grant verified for the tool id and the input digest; one tool call per grant (APPROVAL_GRANT_CONSUMED afterwards); the consent gate still applies
+
 moduleExtensions:
   discovery: module.json cli.catalog (src/cli/commands.json), schema-validated without executing code
   loadImplementation: module.json cli.entry imported only when the command runs (packages/cli/src/extensions.ts loadCliCommand)
@@ -259,6 +287,5 @@ moduleExtensions:
 planned:
   - migration.plan (served by "migration apply" without --apply, which is a read-only dry run)
   - migration.apply.remote
-  - destructive.execute (signed approval receipts)
   - redaction of *_TOKEN, *_SECRET, *_PASSWORD, DATABASE_URL in a shared logger (only packages/ai-provider/src/errors.ts redactSecrets exists)
   - persisted CLI audit (CommandEnvelope carries a random auditId and evidence per invocation; nothing stores it)

package/.ai/references/catalog/module.json

@@ -3,7 +3,7 @@
 	"schemaVersion": 1,
 	"id": "catalog.core",
 	"package": "@flowdular/module-catalog",
-	"version": "0.7.0",
+	"version": "0.7.1",
 	"profile": "full",
 	"capabilities": ["api", "database", "client", "translations"],
 	"platform": {

package/.ai/references/catalog/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@flowdular/module-catalog",
-	"version": "0.7.0",
+	"version": "0.7.1",
 	"type": "module",
 	"exports": {
 		".": "./src/index.ts",
@@ -16,7 +16,7 @@
 	"dependencies": {
 		"octane": "0.1.51",
 		"segment-state": "0.2.0",
-		"@flowdular/sdk": "0.2.4"
+		"@flowdular/sdk": "0.3.0"
 	},
 	"devDependencies": {
 		"@tsrx/typescript-plugin": "0.3.120",

package/.ai/references/catalog/spec/module.yaml

@@ -1,6 +1,6 @@
 schemaVersion: 1
 id: catalog.core
-specVersion: 0.7.0
+specVersion: 0.7.1
 status: approved
 name: Product Catalog Core
 description: Provides tenant-scoped products and services with stable SKUs, units, prices, currencies, and lifecycle state.

package/.ai/references/catalog.provenance.json

@@ -1,9 +1,9 @@
 {
 	"id": "catalog.core",
-	"version": "0.7.0",
+	"version": "0.7.1",
 	"repository": "Flowdular/official-modules",
-	"sourceCommit": "b8281b38498b1e3164e6619ec9e8fe922ad7dc10",
-	"artifactSha256": "6c98785c10fac14cb1a913c6462cb42e18fe824a7d0dd7620746605fd351441d",
+	"sourceCommit": "be391ac460e53e06a812fc9f0ea1260e2daa058f",
+	"artifactSha256": "7c645f660f44bb4c4540d32dd188d643aafb067f4c505a2722a7f2605a7b54b8",
 	"files": {
 		"LICENSE": "155d722071bad9d0d832482e06fd5a47f7034389cb63aabcb39f4282aa3499fc",
 		"migrations/0001_catalog_core.down.sql": "0962a1edf0bde959cd4facccf77bd5b634d6cc25f125a0c79a61770c8871093f",
@@ -15,9 +15,9 @@
 		"migrations/0004_catalog_idempotency_ledger.down.sql": "8ba72d8edc4d25ecf6d041888cf321690c25afdaf3723812ddd7d391d75370aa",
 		"migrations/0004_catalog_idempotency_ledger.up.sql": "41e86ba2051159c6cc9672bfae17c1d02051da975f1c43c566a2b66592673cb0",
 		"migrations/README.md": "2a15fd001713c2552a3c82b186246aa5fec136f43143cc2d9aa15bd491a09d41",
-		"module.json": "1b512c9b97bdec2155103f521a6545e558e50491f90c74a93d33cc74511d2125",
-		"package.json": "67d50dc95723d21bb44bbab54ae14fe89641c52b9f62ba065908f67ebcf0ed7a",
-		"spec/module.yaml": "ec931c78f351c7fc53f43fdd5ec9cd1a46db485f642648329bf1612883a3c958",
+		"module.json": "f2c66d18e3d54ef1ad8dcc3d26d1ee39a2982463dd3bc3fb26b159039933ed86",
+		"package.json": "3e05cf299b5cc5d948e4b3569bd93f2648a30b22f4f14d26bb31548a79529092",
+		"spec/module.yaml": "633a719d765d9779e2bf4ae0a608251767a62cbb4e15305dc13afcb1e52f14c9",
 		"src/acl/permissions.ts": "3375521a5a229736ffac5a948140ec347dc7a7e4fba80e778c0baaf9e0622590",
 		"src/agent/tools.ts": "3204d20886d2b864482adc1ed3303c653aebd207e16c4fce0c67a4979ea8db07",
 		"src/api/endpoints.ts": "34f1036e759353550be2acf67c6fa254afc790942d09489db2e76a082df5c3a3",

package/.ai/skills/cli-extension/SKILL.md

@@ -91,7 +91,7 @@ export default cliExtension;
 
 ## 4. What the runner does with the descriptor (`packages/cli/src/runner.ts`, `runExtensionCommand`)
 
-- `risk: 'external'`: refused with `APPROVAL_VERIFIER_REQUIRED`. `risk: 'destructive'` without `localOnly`: the same.
+- `risk: 'external'`, or `'destructive'` without `localOnly`: refused with `APPROVAL_VERIFIER_REQUIRED` unless `--grant <token> --tenant <id>` carries a verified approval grant for this capability and invocation digest (`APPROVAL_GRANT_INVALID`, `APPROVAL_GRANT_EXPIRED`, `APPROVAL_GRANT_MISMATCH` otherwise).
 - `localOnly: true`: refused with `LOCAL_ONLY_CAPABILITY` unless `FD_ENV` or `NODE_ENV` is `development` or `test` (unset counts as development).
 - `requiresApprovedSpec: true`: needs `--spec <path>` to a schema-valid spec with `status: approved`, otherwise `APPROVED_SPEC_REQUIRED`, `SPEC_VALIDATION_FAILED` or `SPEC_NOT_APPROVED`.
 - `destructive` with `--apply`: needs `--confirm <confirmation>` (`CONFIRMATION_REQUIRED`).

package/.ai/skills/deploy-operate/SKILL.md

@@ -81,9 +81,12 @@ Both are served by `platform/src/server/health.ts`. The shipped Docker and Kuber
 pnpm flowdular database backup --output <dir>                            # dry run
 pnpm flowdular database backup --output <dir> --apply
 pnpm flowdular database restore --input <dir> --apply --confirm restore-database
+pnpm flowdular database restore-production --input <dir> --target <db> --grant <token> --tenant <id> [--platform-url <origin>|--platform-stopped] --apply --confirm restore-database
 ```
 
-The trap: **the encryption keys live outside the database.** Agent provider credentials, agent run grants, workflow payloads and cursors, automation secrets and MFA secrets are all stored as ciphertext, and the keys are environment variables (`FD_AGENT_CREDENTIAL_KEY`, `FD_AGENT_RUN_GRANT_KEY`, `FD_WORKFLOWS_PAYLOAD_KEY`, `FD_WORKFLOWS_CURSOR_KEY`, `FD_AUTOMATIONS_CREDENTIAL_KEY`, `FD_AUTH_MFA_KEY`, `FD_NOTIFICATIONS_SECRET_KEY`, `FD_STORAGE_ENCRYPTION_KEY`, `FD_CONNECTORS_SECRET_KEY`, `FD_AUDIT_ANCHOR_KEY`). A database backup without the matching keys restores rows nobody can read, and rotating a key without re-encrypting orphans everything encrypted under the old one. Back the keys up separately, restore them together with the dump, and record which key version a dump belongs to.
+Production restores run `database.restore.production`: an approval grant bound to the exact flags, `--target` equal to the migrator DSN database, a separate migrator DSN, a key mismatch refused unless the approval included `--allow-key-mismatch`, and a refusal while the health endpoint answers. PITR for the compose stack is `infra/docker/pitr.sh` (see `infra/README.md`); in Kubernetes it is the managed provider's job.
+
+The trap: **the encryption keys live outside the database.** Agent provider credentials, agent run grants, workflow payloads and cursors, automation secrets, MFA secrets, stored objects and connector credentials are all stored as ciphertext, and the keys are environment variables (`FD_AGENT_CREDENTIAL_KEY`, `FD_AGENT_RUN_GRANT_KEY`, `FD_WORKFLOWS_PAYLOAD_KEY`, `FD_WORKFLOWS_CURSOR_KEY`, `FD_AUTOMATIONS_CREDENTIAL_KEY`, `FD_AUTH_MFA_KEY`, `FD_NOTIFICATIONS_SECRET_KEY`, `FD_STORAGE_ENCRYPTION_KEY`, `FD_CONNECTORS_SECRET_KEY`, `FD_AUDIT_ANCHOR_KEY`). A database backup without the matching keys restores rows nobody can read, and rotating a key without re-encrypting orphans everything encrypted under the old one; every sealing key has a `secrets-rotate` command in the runbook's rotation table, the storage key two (`documents` and `exports`). Back the keys up separately, restore them together with the dump, and record which key version a dump belongs to.
 
 ## 6. Rollback
 
@@ -92,6 +95,8 @@ The trap: **the encryption keys live outside the database.** Agent provider cred
 3. To take one module out of service without a redeploy: `pnpm flowdular module disable <id> --apply` (it is a dry run without `--apply`), then rebuild the composition and redeploy. Its tables stay.
 4. If the rollback is because of a key change, restore the previous key first; the image alone will not fix unreadable ciphertext.
 
+- For data loss between two dumps use PITR (`pitr.sh restore --target-time`), never a `.down.sql`.
+
 ## 7. Production checklist
 
 - `pnpm verify` and `pnpm build` pass on the commit being shipped (the image build runs both).
@@ -103,7 +108,7 @@ The trap: **the encryption keys live outside the database.** Agent provider cred
 - Sign-up closed (`FD_AUTH_ALLOW_SIGN_UP`) unless the deployment is public; the first owner created with `flowdular auth workspace-create` (see `docs/cli.md`).
 - Liveness on `/api/health`, readiness on `/api/ready`.
 - `pnpm flowdular migration verify` clean after rollout, and `pnpm flowdular doctor --json` reports `status: healthy`.
-- A restore has been rehearsed once, keys included.
+- A restore has been rehearsed once, keys included, and a PITR restore once from the newest base backup.
 
 ## Pitfalls
 

package/modules/approvals/migrations/0005_approvals_grant_audit.down.sql

@@ -0,0 +1,4 @@
+-- The issuance ledger carries no data any other table depends on.
+DROP POLICY IF EXISTS approvals_audit_tenant_policy ON approvals_audit;
+DROP INDEX IF EXISTS approvals_audit_request_idx;
+DROP TABLE IF EXISTS approvals_audit;

package/modules/approvals/migrations/0005_approvals_grant_audit.up.sql

@@ -0,0 +1,20 @@
+-- The grant an approved request yields is derived from the row and the key on
+-- every read, so nothing about the token itself is stored. What is stored is
+-- the fact of its issuance: one row per resolved request whose subject names
+-- a capability, with the capability, the input digest, the key that signs and
+-- the moment the grant stops verifying, written in the deciding transaction.
+CREATE TABLE IF NOT EXISTS approvals_audit (
+  id TEXT PRIMARY KEY,
+  tenant_id TEXT NOT NULL,
+  request_id TEXT NOT NULL,
+  action TEXT NOT NULL,
+  metadata_json TEXT NOT NULL,
+  occurred_at BIGINT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS approvals_audit_request_idx
+  ON approvals_audit (tenant_id, request_id, occurred_at, id);
+ALTER TABLE approvals_audit ENABLE ROW LEVEL SECURITY;
+ALTER TABLE approvals_audit FORCE ROW LEVEL SECURITY;
+CREATE POLICY approvals_audit_tenant_policy ON approvals_audit
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));

package/modules/approvals/module.json

@@ -3,7 +3,7 @@
 	"schemaVersion": 1,
 	"id": "approvals.core",
 	"package": "@flowdular/module-approvals",
-	"version": "0.1.13",
+	"version": "0.1.14",
 	"platformApi": "^0.1.0",
 	"profile": "full",
 	"capabilities": ["api", "database", "client", "translations"],

package/modules/approvals/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@flowdular/module-approvals",
-	"version": "0.1.13",
+	"version": "0.1.14",
 	"private": true,
 	"type": "module",
 	"exports": {

package/modules/approvals/spec/module.yaml

@@ -1,6 +1,6 @@
 schemaVersion: 2
 id: approvals.core
-specVersion: 0.1.13
+specVersion: 0.1.14
 status: approved
 name: Approvals Core
 description: Turns a policy decision that needs a person into an approval request with named requirements, a decision record that is append-only, notifications to the people who can decide, and a workflow node that waits for the decision, so every module delegates who may decide instead of writing its own approval state machine.
@@ -33,6 +33,7 @@ invariants:
   - A requirement naming both a role key and a scope is satisfied only by members holding both; a requirement that resolves to no eligible decider, to fewer deciders than the decisions it needs, or to more than 200 deciders is refused at open with a stable code and no request is created.
   - A member who gains eligibility after a request opened may decide it (eligibility is re-read at decision time) but is not listed as a decider, because the decider list is the snapshot taken at open.
   - approvals.core declares one data class to the platform registry while it composes, and performs its operations itself on its own lease under its own tenant transaction. approvals.core.requests holds the request row, the eligibility snapshot taken when it opened and every decision recorded on it, keeps them 400 days by default, sweeps only resolved requests in bounded batches so a request still asking is never taken from the people who have to answer it however old it is, and exports one workspace by keyset in bounded pages carrying each request with its decisions and their comments. An erasure removes the resolved requests the subject opened with their eligibility and decision rows, and keeps but redacts every row naming the subject in somebody else's request, a decision as well as an eligibility row of a pending request, writing a fixed marker over a comment and a tombstone unique to the row over the account, because the ledger is append-only and one fixed account value would collide with the unique decider index, or with the eligibility key, as soon as two erased subjects had answered or been eligible for the same request; the remaining deciders keep their own rows and no account of the subject survives; the answer counts the removals and the redactions apart, removed for the rows that went and redacted for the rows that stayed without the subject in them, and both fill the batch the run gave it so a pass that only redacted still moves the run on; the count answers every request the subject opened in any state.
+  - A request whose subject reference encodes a capability id and an input digest (the prefix capability, the id and the sha256 hex digest, separated by colons, within the subjectRef bound) yields, once approved, a grant signed with HMAC-SHA256 under FD_APPROVAL_GRANT_KEY that names the workspace, the capability, the digest, the request and a one hour window from the approving decision; the grant is derived from the row and the current key on every read of the grant operation of approvals.requests.v1, handed only to the subject module that opened the request and never stored, a previous key kept in FD_APPROVAL_GRANT_KEY_PREVIOUS still verifies grants it signed, no grant is yielded for a rejected, cancelled or expired request or once the window closed, the approving transaction writes one grant.issued row to the issuance ledger with the capability, the digest, the signing key id and the expiry, the agent harness admits one tool call per grant within a run and refuses the repeat, and the CLI runner, which runs outside the platform and records no use, accepts the same grant for the same invocation until the window closes.
   - Whether a member may read a request is settled before its state is reported. A member who is neither the requester, nor named by the eligibility snapshot, nor eligible now, nor holding approvals.requests.manage is answered as if the request did not exist, on the read, on a decision and on a cancellation alike, so none of them reveals that the request exists or what became of it.
 permissions:
   - id: approvals.requests.read
@@ -42,7 +43,7 @@ permissions:
   - id: approvals.requests.manage
     description: Read every request of the active workspace and cancel a pending one.
 dataOwnership:
-  - approvals.core owns approval requests, resolved eligibility snapshots and decision rows.
+  - approvals.core owns approval requests, resolved eligibility snapshots, decision rows and the grant issuance ledger.
   - The subject module owns the record the request gates and its own domain state; it changes that state only after reading the request's terminal state.
   - auth.core owns roles and memberships; eligibility is resolved through its public surface at creation and at decision time.
 entities:
@@ -267,6 +268,10 @@ decisions:
     question: Which data classes does approvals.core declare, how long are they kept, and what does an erasure leave behind?
     answer: One class, approvals.core.requests, covering requests, their eligibility rows and their decisions, kept 400 days by default. The sweep takes resolved requests only, with their eligibility and decision rows; a pending request is never swept however old it is. The export pages requests with their decisions and comments, keyset by id. An erasure removes the resolved requests the subject opened with their rows, and redacts rather than removes the rows naming the subject in somebody else's request, writing a fixed marker over a decision's comment and a per-row tombstone over the account on that decision and on the eligibility rows, in pending requests as well as resolved ones. The append-only ledger keeps its row count, a snapshot goes on reporting how many people could answer, the people who can still answer keep their own rows, and no account of the subject survives anywhere. The count answers how many requests the subject opened, in any state.
     decidedBy: default
+  - id: D-APPROVALS-GRANT
+    question: How does an approved request let the CLI runner or the harness run an external or destructive capability?
+    answer: The subject reference encodes the capability id and the digest of the exact invocation input; once approved the request yields a signed grant bound to the workspace, the capability, the digest and a one hour window, which the runner takes as the --grant flag and the harness as the run's grants. The token is read through the grant operation by the subject module alone, derived on read from the row and FD_APPROVAL_GRANT_KEY rather than stored, and the issuance is written to the ledger in the approving transaction; the harness spends a grant on one call, the runner cannot record use and is bounded by the window.
+    decidedBy: default
 acceptanceScenarios:
   - id: APPROVALS-OPEN
     given: A subject module needs a person to agree to an action on one of its records, with a role requirement and a count of 1.
@@ -312,6 +317,10 @@ acceptanceScenarios:
     given: A workspace holds more requests than one page of the inbox carries.
     when: A member pages through the inbox under a scope and a status filter.
     then: A page carries at most 200 requests (50 unless the request asks for more), ordered by createdAt in the requested direction with the id as the tie-break, and a full page answers an opaque cursor bound to the workspace, the member, the sort and the filters, so a cursor used under another workspace, sort or filter is refused rather than reinterpreted.
+  - id: APPROVALS-GRANT
+    given: A workspace with FD_APPROVAL_GRANT_KEY configured and a request opened with a subject reference that encodes a capability id and an input digest.
+    when: An eligible member approves it, another such request is rejected, a third cancelled and a fourth left to expire, and the key is later rotated with the old key kept as previous.
+    then: Reading the grant of the approved request through the capability as the subject module answers a grant that verifies for that workspace, capability and digest until one hour after the approving decision, the same token on every read under the same key and a token under the new key after the rotation that the rotated ring still verifies, the ledger carries one grant.issued row written with the approval naming the capability, the digest, the signing key id and the expiry, the rejected, cancelled and expired requests and an approved request whose subject names a record answer no grant and no ledger row, another module naming the request is answered no grant, and the retention sweep removes the ledger rows with the request.
   - id: APPROVALS-TENANT-BOUNDARY
     given: Two workspaces with requests and decisions.
     when: A runtime transaction bound to one workspace reads or writes any of them, or the expiry routing read runs.

package/modules/approvals/src/domain/capability.ts

@@ -50,6 +50,18 @@ export interface ApprovalsRequests {
 	 */
 	open(input: OpenApprovalInput): Promise<ApprovalRequest>;
 	get(tenantId: string, id: string): Promise<ApprovalRequest | null>;
+	/**
+	 * The signed token an approved request yields while its window is open:
+	 * what the CLI runner takes as `--grant` and the harness as `grants`. Only
+	 * a request whose `subjectRef` encodes a capability and an input digest
+	 * (`encodeCapabilitySubjectRef`) yields one, and only to the module that
+	 * opened it: `subjectModule` has to match the request's. Null otherwise.
+	 */
+	grant(
+		tenantId: string,
+		id: string,
+		subjectModule: string,
+	): Promise<string | null>;
 	/**
 	 * The first `limit` matches, newest first; two requests opened at the same
 	 * millisecond come in descending id order.

package/modules/approvals/src/domain/grant.ts

@@ -0,0 +1,69 @@
+import { APPROVAL_GRANT_INPUT_DIGEST_LENGTH } from '@flowdular/sdk/kernel';
+import { APPROVAL_LIMITS } from './capability.ts';
+
+/**
+ * How long after the approving decision the grant an approved request yields
+ * still verifies. The token is derived from the row and the key on every read,
+ * so the window is measured from `resolvedAt`, not from the read.
+ */
+export const APPROVAL_GRANT_TTL_MS = 60 * 60 * 1_000;
+
+const SUBJECT_PREFIX = 'capability:';
+const CAPABILITY_ID = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$/;
+const INPUT_DIGEST = new RegExp(
+	`^[a-f0-9]{${APPROVAL_GRANT_INPUT_DIGEST_LENGTH}}$`,
+);
+/* Prefix, id, one separator and the digest have to fit the subjectRef bound. */
+export const APPROVAL_GRANT_CAPABILITY_ID_LENGTH =
+	APPROVAL_LIMITS.subjectRef -
+	SUBJECT_PREFIX.length -
+	1 -
+	APPROVAL_GRANT_INPUT_DIGEST_LENGTH;
+
+/** The capability and the exact input an approval is asked for. */
+export interface CapabilitySubject {
+	readonly capabilityId: string;
+	/** `approvalInputDigest` of the invocation input, as the runner computes it. */
+	readonly inputDigest: string;
+}
+
+/**
+ * A `subjectRef` of the form `capability:<capabilityId>:<inputDigest>`. A
+ * request opened with it yields, once approved, a signed grant for exactly
+ * that capability and that input.
+ */
+export function encodeCapabilitySubjectRef(subject: CapabilitySubject): string {
+	if (
+		!CAPABILITY_ID.test(subject.capabilityId) ||
+		subject.capabilityId.length > APPROVAL_GRANT_CAPABILITY_ID_LENGTH
+	) {
+		throw new RangeError(
+			`capabilityId must be a lowercase dot-separated identifier of at most ${APPROVAL_GRANT_CAPABILITY_ID_LENGTH} characters.`,
+		);
+	}
+	if (!INPUT_DIGEST.test(subject.inputDigest)) {
+		throw new RangeError(
+			`inputDigest must be ${APPROVAL_GRANT_INPUT_DIGEST_LENGTH} lowercase hex characters.`,
+		);
+	}
+	return `${SUBJECT_PREFIX}${subject.capabilityId}:${subject.inputDigest}`;
+}
+
+/** Null for a subject reference that names a record rather than a capability. */
+export function decodeCapabilitySubjectRef(
+	subjectRef: string,
+): CapabilitySubject | null {
+	if (!subjectRef.startsWith(SUBJECT_PREFIX)) return null;
+	const separator = subjectRef.lastIndexOf(':');
+	const capabilityId = subjectRef.slice(SUBJECT_PREFIX.length, separator);
+	const inputDigest = subjectRef.slice(separator + 1);
+	if (
+		separator <= SUBJECT_PREFIX.length ||
+		!CAPABILITY_ID.test(capabilityId) ||
+		capabilityId.length > APPROVAL_GRANT_CAPABILITY_ID_LENGTH ||
+		!INPUT_DIGEST.test(inputDigest)
+	) {
+		return null;
+	}
+	return { capabilityId, inputDigest };
+}

package/modules/approvals/src/domain/types.ts

@@ -76,6 +76,20 @@ export interface ApprovalDecision {
 	readonly decidedAt: number;
 }
 
+/** What the ledger records about a request beyond its decisions. */
+export const APPROVAL_AUDIT_ACTIONS = ['grant.issued'] as const;
+
+export type ApprovalAuditAction = (typeof APPROVAL_AUDIT_ACTIONS)[number];
+
+export interface ApprovalAuditEntry {
+	readonly id: string;
+	readonly tenantId: string;
+	readonly requestId: string;
+	readonly action: ApprovalAuditAction;
+	readonly metadata: Readonly<Record<string, string | number>>;
+	readonly occurredAt: number;
+}
+
 /** What an erasure writes over the comment of a decision it keeps. */
 export const ERASED_DECISION_COMMENT = '[erased]';
 

package/modules/approvals/src/index.ts

@@ -30,6 +30,13 @@ export type {
 	ApprovalsRequests,
 	OpenApprovalInput,
 } from './domain/capability.ts';
+export {
+	APPROVAL_GRANT_CAPABILITY_ID_LENGTH,
+	APPROVAL_GRANT_TTL_MS,
+	decodeCapabilitySubjectRef,
+	encodeCapabilitySubjectRef,
+} from './domain/grant.ts';
+export type { CapabilitySubject } from './domain/grant.ts';
 
 export {
 	APPROVAL_DECISIONS,
@@ -38,6 +45,8 @@ export {
 	isTerminalApprovalStatus,
 } from './domain/types.ts';
 export type {
+	ApprovalAuditAction,
+	ApprovalAuditEntry,
 	ApprovalDecision,
 	ApprovalDecisionKind,
 	ApprovalMember,

package/modules/approvals/src/platform.ts

@@ -1,3 +1,4 @@
+import { approvalGrantKeyringFromEnvironment } from '@flowdular/sdk/kernel';
 import type {
 	PlatformServerComposition,
 	PlatformServerContext,
@@ -96,6 +97,9 @@ export function createServerComposition(
 			context.capabilities.get<NotificationPublisher>(
 				NOTIFICATIONS_PUBLISH_CAPABILITY,
 			),
+		/* Without FD_APPROVAL_GRANT_KEY an approved capability request yields no
+		   grant, and the runner and the harness keep refusing the capability. */
+		grants: approvalGrantKeyringFromEnvironment(context.environment),
 	});
 	/* The runtime opens its database leases lazily, so the capability is a
 	   forwarder rather than a resolved object: registration must not force a
@@ -106,6 +110,10 @@ export function createServerComposition(
 			open: async (input) => (await runtime.service()).capability().open(input),
 			get: async (tenantId, id) =>
 				(await runtime.service()).capability().get(tenantId, id),
+			grant: async (tenantId, id, subjectModule) =>
+				(await runtime.service())
+					.capability()
+					.grant(tenantId, id, subjectModule),
 			list: async (tenantId, filter) =>
 				(await runtime.service()).capability().list(tenantId, filter),
 			cancel: async (tenantId, id, actorAccountId) =>

package/modules/approvals/src/server/runtime.ts

@@ -7,6 +7,7 @@ import {
 	DATABASE_CAPABILITY_IDS,
 	DATABASE_DIALECT_IDS,
 } from '@flowdular/sdk/database';
+import type { ApprovalGrantKeyring } from '@flowdular/sdk/kernel';
 import type { JobRunner } from '@flowdular/sdk/server';
 import type { ApprovalMember } from '../domain/types.ts';
 import {
@@ -42,6 +43,8 @@ export interface ApprovalsRuntimeOptions {
 	readonly notifications?: NotificationPublisherResolver;
 	readonly callbacks?: ApprovalCallbackRegistry;
 	readonly repository?: ApprovalsRepository;
+	/** Signs the grant an approved capability request yields; absent means none. */
+	readonly grants?: ApprovalGrantKeyring | undefined;
 	readonly now?: () => number;
 }
 
@@ -122,6 +125,7 @@ export function createApprovalsRuntime(
 			...(options.notifications
 				? { notifications: options.notifications }
 				: {}),
+			...(options.grants ? { grants: options.grants } : {}),
 			...(options.now ? { now: options.now } : {}),
 		}));
 

package/modules/approvals/src/services/approvals-service.ts

@@ -1,12 +1,21 @@
 import { randomUUID } from 'node:crypto';
+import {
+	issueApprovalGrant,
+	type ApprovalGrantKeyring,
+} from '@flowdular/sdk/kernel';
 import {
 	APPROVAL_LIMITS,
 	type ApprovalRequestFilter,
 	type ApprovalsRequests,
 	type OpenApprovalInput,
 } from '../domain/capability.ts';
+import {
+	APPROVAL_GRANT_TTL_MS,
+	decodeCapabilitySubjectRef,
+} from '../domain/grant.ts';
 import {
 	APPROVAL_STATUSES,
+	type ApprovalAuditEntry,
 	type ApprovalDecideOutcome,
 	type ApprovalDecision,
 	type ApprovalListPage,
@@ -61,6 +70,8 @@ export interface ApprovalsServiceOptions {
 	readonly defaultExpiryDays: (tenantId: string) => number | Promise<number>;
 	readonly notifications?: NotificationPublisherResolver;
 	readonly callbacks?: ApprovalCallbackRegistry;
+	/** Signs the grant an approved capability request yields; absent means none is issued. */
+	readonly grants?: ApprovalGrantKeyring | undefined;
 	readonly now?: () => number;
 }
 
@@ -71,6 +82,7 @@ export class ApprovalsService {
 	readonly #defaultExpiryDays: ApprovalsServiceOptions['defaultExpiryDays'];
 	readonly #notifications: NotificationPublisherResolver | undefined;
 	readonly #callbacks: ApprovalCallbackRegistry;
+	readonly #grants: ApprovalGrantKeyring | undefined;
 	readonly #now: () => number;
 
 	constructor(options: ApprovalsServiceOptions) {
@@ -80,6 +92,7 @@ export class ApprovalsService {
 		this.#defaultExpiryDays = options.defaultExpiryDays;
 		this.#notifications = options.notifications;
 		this.#callbacks = options.callbacks ?? createApprovalCallbackRegistry();
+		this.#grants = options.grants;
 		this.#now = options.now ?? Date.now;
 	}
 
@@ -186,6 +199,48 @@ export class ApprovalsService {
 		);
 	}
 
+	/**
+	 * The grant an approved capability request yields, derived from the row and
+	 * the current key on every read: the same claims sign to the same token
+	 * under the same key, and a rotated key signs a fresh one that verifies the
+	 * same. Nothing is issued for any other state, or once the window closed.
+	 */
+	grantFor(request: ApprovalRequest): string | undefined {
+		if (!this.#grants || request.status !== 'approved') return undefined;
+		if (request.resolvedAt === null) return undefined;
+		const subject = decodeCapabilitySubjectRef(request.subjectRef);
+		if (!subject) return undefined;
+		const expiresAt = request.resolvedAt + APPROVAL_GRANT_TTL_MS;
+		if (expiresAt <= this.#now()) return undefined;
+		return issueApprovalGrant(this.#grants, {
+			tenantId: request.tenantId,
+			capabilityId: subject.capabilityId,
+			inputDigest: subject.inputDigest,
+			requestId: request.id,
+			issuedAt: request.resolvedAt,
+			expiresAt,
+			nonce: request.id,
+		}).token;
+	}
+
+	/* The token reaches only the module that asked the question: a holder of
+	   the capability naming another module's request is answered null. */
+	async grant(
+		tenantId: string,
+		id: string,
+		subjectModule: string,
+	): Promise<string | null> {
+		const module = bounded(
+			subjectModule,
+			'subjectModule',
+			1,
+			APPROVAL_LIMITS.subjectModule,
+		);
+		const request = await this.get(tenantId, id);
+		if (!request || request.subjectModule !== module) return null;
+		return this.grantFor(request) ?? null;
+	}
+
 	async detail(
 		tenantId: string,
 		id: string,
@@ -458,6 +513,8 @@ export class ApprovalsService {
 		return {
 			open: (input) => this.open(input),
 			get: (tenantId, id) => this.get(tenantId, id),
+			grant: (tenantId, id, subjectModule) =>
+				this.grant(tenantId, id, subjectModule),
 			list: (tenantId, filter) => this.list(tenantId, filter),
 			cancel: async (tenantId, id, actorAccountId) =>
 				(await this.cancel(tenantId, id, actorAccountId)).request,
@@ -476,6 +533,28 @@ export class ApprovalsService {
 		return request;
 	}
 
+	/* The moment a capability request is approved is the moment its grant can
+	   be read, so that is what the ledger records, under the deciding
+	   transaction, with what the grant will say and which key signs it. */
+	#grantIssued(resolved: ApprovalRequest): ApprovalAuditEntry | null {
+		if (!this.#grants || resolved.status !== 'approved') return null;
+		const subject = decodeCapabilitySubjectRef(resolved.subjectRef);
+		if (!subject || resolved.resolvedAt === null) return null;
+		return {
+			id: randomUUID(),
+			tenantId: resolved.tenantId,
+			requestId: resolved.id,
+			action: 'grant.issued',
+			metadata: {
+				capabilityId: subject.capabilityId,
+				inputDigest: subject.inputDigest,
+				keyId: this.#grants.keyId,
+				expiresAt: resolved.resolvedAt + APPROVAL_GRANT_TTL_MS,
+			},
+			occurredAt: resolved.resolvedAt,
+		};
+	}
+
 	/* Only a member who may read the request is told its state; every caller
 	   settles readability before this runs. */
 	#assertPending(request: ApprovalRequest): void {
@@ -512,6 +591,7 @@ export class ApprovalsService {
 			},
 			resolve,
 			resolvedAt: decidedAt,
+			audit: (resolved) => this.#grantIssued(resolved),
 		});
 		if (result.outcome === 'not-found') {
 			throw new ApprovalsServiceError(