approval-md 0.0.1 → 0.2.0

package/docs/codex-enforced-session.md

@@ -0,0 +1,30 @@
+# Constrained Codex preparation
+
+approval codex prepare creates a review bundle for a future constrained Codex
+session. It is packaging and diagnostics, not activation.
+
+The bundle pins one macOS/Codex version, distinct Codex, broker and runner
+principals, disjoint active-worktree, primary-gate and root-owned installation
+roots, and one exact MCP executable plus argument vector. Its requirements
+template makes native Codex tools read-only, disables command network and the
+browser, computer-use, plugin and web-search surfaces, and allowlists only the
+strict MCP identity.
+
+Preparation writes only a new output directory. approval codex setup --check
+verifies the exact file set, SHA-256 index, instance schema and every generated
+template byte. A passing check means the inert bundle is internally consistent.
+
+approval codex doctor --strict --manifest PATH inspects host custody. It rejects
+unsupported manifest platforms or version declarations, missing or overlapping principals,
+overlapping roots, symlinks, path drift, non-root-owned or writable trusted
+ancestors, invocation drift, missing executables and a workspace writable by
+the Codex principal. APRV-325.1 also unconditionally reports broker-not-ready
+and runner-not-ready. POSIX ownership and mode cannot prove the absence of
+writable ACLs, so this slice executes no manifest-selected binary and reports
+both installed runtime versions unchecked.
+
+The package does not run a postinstall script, call sudo, edit Codex
+configuration, create accounts, load services, access credentials, start a
+model, or alter APPROVAL.md. A human or MDM system must eventually install and
+own the reviewed artifacts. APRV-325.2 and APRV-325.3 must provide the broker,
+runner and end-to-end denial evidence before the session can be called enforced.

package/package.json

@@ -1,10 +1,59 @@
 {
   "name": "approval-md",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "description": "Human approval for agent actions. CLI runtime for the approval.md convention (pre-release).",
-  "bin": { "approval": "./cli.js" },
-  "files": ["cli.js", "SPEC.md", "README.md"],
+  "type": "module",
+  "bin": {
+    "approval": "./cli.js"
+  },
+  "exports": {
+    "./adapters": {
+      "types": "./dist/src/adapters/public.d.ts",
+      "import": "./dist/src/adapters/public.js"
+    }
+  },
+  "files": [
+    "cli.js",
+    "dist/src",
+    "schema",
+    "docs/adapter-api.md",
+    "docs/cli-reference.md",
+    "SPEC.md",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "docs/codex-enforced-session.md",
+    "templates/codex"
+  ],
   "repository": "github:approval-md/approval.md",
   "homepage": "https://approval.md",
-  "license": "MIT"
+  "author": "Carter Crouch",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "codex:mcp": "node .codex/approval-mcp.mjs",
+    "typecheck": "tsc --noEmit",
+    "test": "tsc -p tsconfig.json && node scripts/run-tests.mjs",
+    "lint": "oxlint src tests",
+    "ci:local": "node scripts/ci-local.mjs",
+    "check:tier": "node scripts/classify-tier.mjs",
+    "check:changed": "node scripts/classify-tier.mjs --working-tree --run",
+    "conformance": "tsc -p tsconfig.json && node conformance/run.mjs"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "9.6.0",
+    "@types/node": "^26.1.2",
+    "oxlint": "^1.77.0",
+    "typescript": "^7.0.2"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "ajv": "8.20.0",
+    "ajv-formats": "3.0.1",
+    "better-sqlite3": "12.11.1",
+    "yaml": "2.9.0"
+  }
 }

package/schema/LICENSE

@@ -0,0 +1,117 @@
+CC0 1.0 Universal
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator and
+subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for the
+purpose of contributing to a commons of creative, cultural and scientific
+works ("Commons") that the public can reliably and without fear of later
+claims of infringement build upon, modify, incorporate in other works, reuse
+and redistribute as freely as possible in any form whatsoever and for any
+purposes, including without limitation commercial purposes. These owners may
+contribute to the Commons to promote the ideal of a free culture and the
+further production of creative, cultural and scientific works, or to gain
+reputation or greater distribution for their Work in part through the use and
+efforts of others.
+
+For these and/or other purposes and motivations, and without any expectation
+of additional consideration or compensation, the person associating CC0 with a
+Work (the "Affirmer"), to the extent that he or she is an owner of Copyright
+and Related Rights in the Work, voluntarily elects to apply CC0 to the Work
+and publicly distribute the Work under its terms, with knowledge of his or her
+Copyright and Related Rights in the Work and the meaning and intended legal
+effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not limited
+to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display, communicate,
+  and translate a Work;
+
+  ii. moral rights retained by the original author(s) and/or performer(s);
+
+  iii. publicity and privacy rights pertaining to a person's image or likeness
+  depicted in a Work;
+
+  iv. rights protecting against unfair competition in regards to a Work,
+  subject to the limitations in paragraph 4(a), below;
+
+  v. rights protecting the extraction, dissemination, use and reuse of data in
+  a Work;
+
+  vi. database rights (such as those arising under Directive 96/9/EC of the
+  European Parliament and of the Council of 11 March 1996 on the legal
+  protection of databases, and under any national implementation thereof,
+  including any amended or successor version of such directive); and
+
+  vii. other similar, equivalent or corresponding rights throughout the world
+  based on applicable law or treaty, and any national implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention of,
+applicable law, Affirmer hereby overtly, fully, permanently, irrevocably and
+unconditionally waives, abandons, and surrenders all of Affirmer's Copyright
+and Related Rights and associated claims and causes of action, whether now
+known or unknown (including existing as well as future claims and causes of
+action), in the Work (i) in all territories worldwide, (ii) for the maximum
+duration provided by applicable law or treaty (including future time
+extensions), (iii) in any current or future medium and for any number of
+copies, and (iv) for any purpose whatsoever, including without limitation
+commercial, advertising or promotional purposes (the "Waiver"). Affirmer makes
+the Waiver for the benefit of each member of the public at large and to the
+detriment of Affirmer's heirs and successors, fully intending that such Waiver
+shall not be subject to revocation, rescission, cancellation, termination, or
+any other legal or equitable action to disrupt the quiet enjoyment of the Work
+by the public as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason be
+judged legally invalid or ineffective under applicable law, then the Waiver
+shall be preserved to the maximum extent permitted taking into account
+Affirmer's express Statement of Purpose. In addition, to the extent the Waiver
+is so judged Affirmer hereby grants to each affected person a royalty-free,
+non transferable, non sublicensable, non exclusive, irrevocable and
+unconditional license to exercise Affirmer's Copyright and Related Rights in
+the Work (i) in all territories worldwide, (ii) for the maximum duration
+provided by applicable law or treaty (including future time extensions), (iii)
+in any current or future medium and for any number of copies, and (iv) for any
+purpose whatsoever, including without limitation commercial, advertising or
+promotional purposes (the "License"). The License shall be deemed effective as
+of the date CC0 was applied by Affirmer to the Work. Should any part of the
+License for any reason be judged legally invalid or ineffective under
+applicable law, such partial invalidity or ineffectiveness shall not
+invalidate the remainder of the License, and in such case Affirmer hereby
+affirms that he or she will not (i) exercise any of his or her remaining
+Copyright and Related Rights in the Work or (ii) assert any associated claims
+and causes of action with respect to the Work, in either case contrary to
+Affirmer's express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+  a. No trademark or patent rights held by Affirmer are waived, abandoned,
+  surrendered, licensed or otherwise affected by this document.
+
+  b. Affirmer offers the Work as-is and makes no representations or warranties
+  of any kind concerning the Work, express, implied, statutory or otherwise,
+  including without limitation warranties of title, merchantability, fitness
+  for a particular purpose, non infringement, or the absence of latent or
+  other defects, accuracy, or the present or absence of errors, whether or not
+  discoverable, all to the greatest extent permissible under applicable law.
+
+  c. Affirmer disclaims responsibility for clearing rights of other persons
+  that may apply to the Work or any use thereof, including without limitation
+  any person's Copyright and Related Rights in the Work. Further, Affirmer
+  disclaims responsibility for obtaining any necessary consents, permissions
+  or other rights required for any use of the Work.
+
+  d. Affirmer understands and acknowledges that Creative Commons is not a
+  party to this document and has no duty or obligation with respect to this
+  CC0 or use of the Work.
+
+For more information, please see
+<http://creativecommons.org/publicdomain/zero/1.0/>
+

package/schema/codex-instance.schema.json

@@ -0,0 +1,82 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://approval.md/schema/codex-instance.schema.json",
+  "$comment": "CC0 1.0. See schema/LICENSE.",
+  "title": "Constrained Codex instance manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "instance_id", "platform", "codex_version", "node_version", "package_version", "paths", "principals", "invocation", "components"],
+  "properties": {
+    "schema_version": { "const": "approval.codex.instance.v1" },
+    "instance_id": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,62}$" },
+    "platform": { "const": "darwin" },
+    "codex_version": { "const": "0.152.1" },
+    "node_version": { "type": "string", "pattern": "^(?:2[0-9]|[3-9][0-9])\\.[0-9]+\\.[0-9]+$" },
+    "package_version": { "type": "string", "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(?:-[0-9A-Za-z.-]+)?$" },
+    "paths": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["install_root", "package_root", "workspace", "primary", "policy", "log", "manifest", "codex_executable", "node_executable", "mcp_executable", "broker_executable", "runner_executable"],
+      "properties": {
+        "install_root": { "$ref": "#/$defs/absolute_path" },
+        "package_root": { "$ref": "#/$defs/absolute_path" },
+        "workspace": { "$ref": "#/$defs/absolute_path" },
+        "primary": { "$ref": "#/$defs/absolute_path" },
+        "policy": { "$ref": "#/$defs/absolute_path" },
+        "log": { "$ref": "#/$defs/absolute_path" },
+        "manifest": { "$ref": "#/$defs/absolute_path" },
+        "codex_executable": { "$ref": "#/$defs/absolute_path" },
+        "node_executable": { "$ref": "#/$defs/absolute_path" },
+        "mcp_executable": { "$ref": "#/$defs/absolute_path" },
+        "broker_executable": { "$ref": "#/$defs/absolute_path" },
+        "runner_executable": { "$ref": "#/$defs/absolute_path" }
+      }
+    },
+    "principals": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["codex", "broker", "runner"],
+      "properties": {
+        "codex": { "const": "_approval_codex" },
+        "broker": { "const": "_approval_broker" },
+        "runner": { "const": "_approval_runner" }
+      }
+    },
+    "invocation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["command", "args"],
+      "properties": {
+        "command": { "$ref": "#/$defs/absolute_path" },
+        "args": {
+          "type": "array",
+          "prefixItems": [
+            { "const": "codex" },
+            { "const": "serve" },
+            { "const": "--manifest" },
+            { "$ref": "#/$defs/absolute_path" }
+          ],
+          "items": false,
+          "minItems": 4,
+          "maxItems": 4
+        }
+      }
+    },
+    "components": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["broker", "runner"],
+      "properties": {
+        "broker": { "const": "required-not-shipped" },
+        "runner": { "const": "required-not-shipped" }
+      }
+    }
+  },
+  "$defs": {
+    "absolute_path": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^/"
+    }
+  }
+}

package/schema/envelope.schema.json

@@ -0,0 +1,137 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://approval.md/schema/envelope.schema.json",
+  "$comment": "CC0 1.0. See schema/LICENSE.",
+  "title": "Task envelope",
+  "description": "SPEC.md §6: the value of the `approval:` frontmatter key on a Backlog.md-style task file. This schema governs that value only — sibling board keys (id, title, status) belong to Backlog.md and are out of scope. A task with no envelope is valid markdown; it simply cannot request side-effecting execution (§6).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["origin", "state"],
+  "properties": {
+    "origin": {
+      "type": "object",
+      "description": "SPEC.md §6.2: provenance of the task. MUST be present — an envelope with no traceable origin cannot be gated.",
+      "additionalProperties": false,
+      "required": ["app", "created_by"],
+      "properties": {
+        "app": {
+          "type": "string",
+          "minLength": 1,
+          "description": "SPEC.md §6.2 `origin.app` (MUST): source system that created this task (`example-capture`, `manual`, …)."
+        },
+        "created_by": {
+          "type": "string",
+          "pattern": "^(human|agent):.+",
+          "description": "SPEC.md §6.2 `origin.created_by` (MUST): `human:<id>` or `agent:<id>`. A bare identifier with no principal-kind prefix is rejected."
+        }
+      }
+    },
+    "route": {
+      "type": "object",
+      "description": "SPEC.md §6.2: routing of the task. Routing proposals from agents are events, never silent edits to this block.",
+      "additionalProperties": false,
+      "properties": {
+        "assignee": {
+          "type": "string",
+          "pattern": "^(human|agent:.+)$",
+          "description": "SPEC.md §6.2 `route.assignee` (SHOULD): the literal `human`, or `agent:<id>`. Note the asymmetry with `origin.created_by`: a human assignee is unqualified because the queue, not an id, is the destination."
+        },
+        "rationale": {
+          "type": "string",
+          "description": "SPEC.md §6.1: free-text justification for the routing decision, carried for audit and monitoring."
+        },
+        "confidence": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1,
+          "description": "SPEC.md §6.2 `route.confidence` (MAY): 0.0–1.0 routing confidence, used as a monitoring signal (§11). Never a gate on its own."
+        }
+      }
+    },
+    "state": {
+      "type": "string",
+      "enum": [
+        "proposed",
+        "awaiting",
+        "approved",
+        "executed",
+        "rejected",
+        "expired",
+        "revoked"
+      ],
+      "description": "SPEC.md §6.3: approval lifecycle state, distinct from the board `status`. A projection of the event log — the daemon writes it after the event is appended, never the reverse."
+    },
+    "actions": {
+      "type": "array",
+      "description": "SPEC.md §6.2 `actions[]`: declared side effects. MUST be present for execution; absent means the task cannot request an execution token (§7: a class MUST be declared before a token can be requested for it).",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["class", "idempotency_key"],
+        "properties": {
+          "class": {
+            "type": "string",
+            "pattern": "^[a-z0-9_-]+(\\.[a-z0-9_-]+)*$",
+            "description": "SPEC.md §7: dotted, hierarchical side-effect class (`communicate.email.external`, `financial.spend`). Lowercase dot-separated segments of [a-z0-9_-]; top-level namespaces are reserved by the spec, sub-classes are extensible."
+          },
+          "summary": {
+            "type": "string",
+            "description": "SPEC.md §6.2: one-line human-readable description of the effect, rendered into the approval request and the queue (§9)."
+          },
+          "reversible": {
+            "type": "boolean",
+            "description": "SPEC.md §7: whether the effect can be undone. `false` actions MUST NOT be eligible for `autonomous` regardless of policy — the runtime enforces that floor."
+          },
+          "est_cost_usd": {
+            "$ref": "#/$defs/usd_amount",
+            "description": "SPEC.md §6.2 (amended, APRV-121): estimated cost in USD as a decimal string (`\"0.02\"`), checked against task and policy budgets (conjunctively). A JSON number is refused at the write boundary: this value rides inside hashed material and cross-language float serialization is where byte-identical hashing breaks."
+          },
+          "idempotency_key": {
+            "type": "string",
+            "minLength": 1,
+            "description": "SPEC.md §6.2 (MUST per action): stable string; adapters MUST refuse to execute the same key twice."
+          },
+          "payload_hash": {
+            "type": "string",
+            "pattern": "^[a-f0-9]{64}$",
+            "description": "SPEC.md §6.2 (amended: MUST for `manual` actions, SHOULD otherwise): SHA-256 over the RFC 8785 canonical serialization of the action's concrete payload — for a message send, the full body and recipients; for `approval run`, the argv array and cwd; for a record write, the proposed record content. The payload itself is stored or referenced by the request so channels can display it; the hash is what approval binds to (§10). Optional here because this schema cannot know an action's resolved autonomy — the MUST for `manual` is enforced at request time by the gate, which refuses `payload-hash-required`."
+          }
+        }
+      }
+    },
+    "budget": {
+      "type": "object",
+      "description": "SPEC.md §6.2 `budget` (MAY): task-level caps, conjunctive with policy budgets — the stricter of the two binds.",
+      "additionalProperties": false,
+      "properties": {
+        "max_cost_usd": {
+          "$ref": "#/$defs/usd_amount",
+          "description": "SPEC.md §6.2 (amended, APRV-121): maximum total spend in USD across this task's actions, as a decimal string (`\"25\"`, `\"0.5\"`). Copied into the `task.registered` payload at registration, so it is hashed material and carries the same string rule as `est_cost_usd`."
+        },
+        "max_latency": {
+          "type": "string",
+          "pattern": "^[0-9]+(ms|s|m|h|d)$",
+          "description": "SPEC.md §6.1: duration string bounding how long the request may stay pending (`6h`, `30m`, `7d`). Integer magnitude plus one unit suffix."
+        }
+      }
+    }
+  },
+  "$defs": {
+    "usd_amount_string": {
+      "type": "string",
+      "pattern": "^(0|[1-9][0-9]*)(\\.[0-9]{0,5}[1-9])?$",
+      "description": "SPEC.md §6.2 (amended, APRV-121): a USD amount as a canonical decimal string. No sign, no exponent, no leading zeros, at most six fractional digits, and no trailing zeros beyond the last significant digit — one value has exactly one spelling, so two records carrying the same amount always hash the same way."
+    },
+    "usd_amount": {
+      "$ref": "#/$defs/usd_amount_string",
+      "description": "The write-boundary form of a USD amount: the decimal string, and nothing else. `validate(..., { mode: \"historical\" })` replaces this definition with `usd_amount_historical` so that records written before APRV-121 keep validating; nothing else in the runtime relaxes it."
+    },
+    "usd_amount_historical": {
+      "anyOf": [
+        { "$ref": "#/$defs/usd_amount_string" },
+        { "type": "number", "minimum": 0 }
+      ],
+      "description": "The read form: the decimal string, or the pre-APRV-121 JSON number. The log is append-only (SPEC.md §8), so a verifier must accept every shape the write boundary ever admitted. Used only in historical validation mode."
+    }
+  }
+}