@axtary/approvals 0.0.1

package/README.md

@@ -0,0 +1,97 @@
+# @axtary/approvals
+
+Hosted approval queue contract for exact Axtary step-up approvals.
+
+This package is private workspace code while the hosted control plane API is being shaped.
+
+## What It Does
+
+- Creates pending approval queue items from normalized actions and `step_up` policy decisions.
+- Stores exact action hashes and payload hashes for reviewer trust.
+- Records request provenance so reviewers can tell whether a request came from the proxy, SDK, API, dashboard, or demo tooling.
+- Carries optional provider diff metadata so reviewers can inspect changed files and hunks before approving.
+- Approves queue items by producing `@axtary/actionpass` approval artifacts.
+- Denies queue items without producing executable approval evidence.
+- Exposes a small in-memory queue implementation for API route tests and local demos.
+- Persists hosted approval queue state to local JSON for development and self-hosted demos.
+- Provides an HTTP client and resolver that local proxy runtimes can use to fetch approved artifacts.
+
+## Contract
+
+The hosted control plane should coordinate approval state only. It should not hold downstream provider secrets or execute customer tool calls.
+
+Local enforcement remains in `@axtary/proxy`. When a queued item is approved, the proxy can fetch the approval artifact and submit it through its `approvalResolver`; ActionPass issuance still validates that the artifact binds to the exact action and payload.
+
+Queue items include provenance:
+
+```json
+{
+  "provenance": {
+    "source": "proxy",
+    "createdBy": "agent:codex-prod",
+    "sourceId": "codex-cli",
+    "createdFrom": "axtary.proxy"
+  }
+}
+```
+
+Existing local JSON records without provenance parse as `source: "api"` for compatibility.
+
+Queue items can also include provider-specific diff metadata:
+
+```json
+{
+  "diff": {
+    "provider": "github",
+    "summary": "1 modified file, 2 additions, 1 deletion",
+    "files": [
+      {
+        "path": "infra/prod/main.tf",
+        "status": "modified",
+        "additions": 2,
+        "deletions": 1,
+        "hunks": [
+          {
+            "header": "@@ -12,3 +12,4 @@",
+            "lines": [
+              { "type": "context", "oldLine": 12, "newLine": 12, "content": "..." },
+              { "type": "deletion", "oldLine": 13, "content": "..." },
+              { "type": "addition", "newLine": 13, "content": "..." }
+            ]
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## HTTP Shape
+
+The Next app exposes the first local hosted API contract:
+
+- `POST /api/approvals` creates a pending queue item from `{ action, decision }`.
+- `GET /api/approvals?status=pending` lists queued items.
+- `GET /api/approvals/:id` returns one queue item.
+- `POST /api/approvals/:id/approve` resolves an item and returns an approval artifact.
+- `POST /api/approvals/:id/deny` denies an item without returning approval evidence.
+- `POST /api/approvals/demo` creates a local dashboard exercise request with `source: "demo"`.
+
+Only `step_up` decisions can enter the queue.
+
+By default, the Next API routes persist local development queue state to `.axtary/approvals.json`, which is ignored by git. Set `AXTARY_APPROVAL_STORE_PATH` to choose a different JSON file, or `AXTARY_APPROVAL_STORE_MODE=memory` for ephemeral tests.
+
+## Proxy Resolver
+
+`createHostedApprovalResolver({ baseUrl })` returns a resolver compatible with the proxy `approvalResolver` shape:
+
+```ts
+import { createHostedApprovalResolver } from "@axtary/approvals";
+
+const approvalResolver = createHostedApprovalResolver({
+  baseUrl: "https://app.axtary.dev",
+  requestedBy: "agent:codex-prod",
+});
+```
+
+The resolver creates or reuses a deterministic approval request ID based on the action hash. It returns `null` while the request is pending or denied, and returns an approval artifact only after the hosted queue has approved the exact action payload.