From 3dd0fade3d45439a82dccd79ef6d21381ccb58d6 Mon Sep 17 00:00:00 2001 From: Yehonal Date: Sat, 11 Jul 2026 22:48:25 +0000 Subject: [PATCH] Add PAM 0.6 memory records --- CHANGELOG.md | 32 + README.md | 3 + docs/amf-memory-v1.md | 160 +++++ docs/mcp-server.md | 49 +- memory/agent-memory/pam-runtime.md | 9 +- memory/agent-memory/pam.md | 13 + memory/pam.version.json | 9 +- ....3-to-0.6.0-agent-memory-fabric-records.md | 23 + package.json | 2 +- tools/lib/amf-memory-record.mjs | 606 ++++++++++++++++ tools/lib/mcp-tools.mjs | 54 +- tools/lib/memory-apply-proposal.mjs | 414 +++++++++-- tools/lib/memory-proposals.mjs | 152 ++++- tools/lib/secure-fs.mjs | 354 ++++++++++ tools/test-amf-memory-record.mjs | 644 ++++++++++++++++++ tools/test-pam-mcp-server.mjs | 81 +++ tools/test-secure-fs-locks.mjs | 174 +++++ 17 files changed, 2692 insertions(+), 87 deletions(-) create mode 100644 docs/amf-memory-v1.md create mode 100644 migrations/0.5.3-to-0.6.0-agent-memory-fabric-records.md create mode 100644 tools/lib/amf-memory-record.mjs create mode 100644 tools/lib/secure-fs.mjs create mode 100644 tools/test-amf-memory-record.mjs create mode 100644 tools/test-secure-fs-locks.mjs diff --git a/CHANGELOG.md b/CHANGELOG.md index e86dd49..541e0b0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,38 @@ ## Unreleased +## 0.6.0 - 2026-07-11 + +PAM 0.6.0 adds the optional `amf-memory/v1` Markdown record contract for +source-traceable, scope-aware durable memory. + +### Added + +- Zero-dependency contract-v1 frontmatter, lifecycle, scope, provenance, + opaque-ID, sealed-claim, RFC 3339 UTC, and canonical-path validation. +- Safe graph-v1 node projections that never expose sealed content or identity + references. +- `memory_record_validate` and `memory_propose_record` MCP tools. +- AMF record creation through the existing proposal/apply review boundary. + +### Safety + +- Person/relationship scopes and subjects, relationship claims, and + confidential or restricted visibility require an `AES-256-GCM` envelope with external + `keyRef` and canonical AAD hash. +- Proposal and apply enforce ancestor symlink rejection, no-follow reads, + revision/base-hash transitions, per-target locking, archive reservation, + recoverable atomic persistence, supersedes resolution, and real graph collision checks. +- Stale derived-graph warnings survive proposal, archive, and apply responses + with an explicit required graph-reindex follow-up. +- MCP never decrypts records and never creates a canonical record directly. + +### Compatibility + +- `memoryFormat` and `graphSchemaVersion` remain `graph-v1` and + `pam-graph-v1`. +- Existing logs, graphs, proposals, and MCP tools continue unchanged. + ## 0.5.0 - 2026-05-27 PAM 0.5.0 adds a measurable file-only retrieval gate for agents that cannot use diff --git a/README.md b/README.md index 89f3fca..bac457a 100644 --- a/README.md +++ b/README.md @@ -41,6 +41,9 @@ The important pieces are: compact graph-first runtime guide for everyday agent memory lookup. - [memory/graph/](memory/graph): AI-first JSONL graph memory. Agents can read it directly without Node, npm, a database, or embeddings. +- [docs/amf-memory-v1.md](docs/amf-memory-v1.md): optional source-traceable, + scope-aware Markdown record contract with sealed private bodies and safe + graph projections. - [memory/agent-memory/pam.md](memory/agent-memory/pam.md): the Portable Agent Memory constitution. This is the setup/protocol reference agents should follow when changing or auditing PAM itself. diff --git a/docs/amf-memory-v1.md b/docs/amf-memory-v1.md new file mode 100644 index 0000000..19be564 --- /dev/null +++ b/docs/amf-memory-v1.md @@ -0,0 +1,160 @@ +# AMF memory record v1 + +PAM 0.6.0 implements the public `amf-memory/v1` file-first contract used by +Agent Memory Fabric. It is additive: existing PAM logs and graph-v1 workspaces +continue to work unchanged. + +## Canonical file + +Each record is one Markdown file at: + +```text +memory/amf/records/.md +``` + +`` is the record's opaque `mem_`. The logical record is stored in YAML +frontmatter. PAM accepts a deterministic YAML subset: every top-level field is +one `key: value` line and nested objects/arrays use compact JSON, which is valid +YAML. Sealed records have an empty Markdown body. Plain records may use the body +only for non-claim commentary. + +```markdown +--- +schema: amf-memory/v1 +id: mem_11111111-1111-4111-8111-111111111111 +revision: 1 +claimType: decision +scope: {"type":"shared","id":"shared:global"} +visibility: shared +subjects: [{"identityId":"agent:22222222-2222-4222-8222-222222222222","role":"owner"}] +claim: {"encoding":"plain","text":"A portable source-backed decision."} +lifecycle: {"status":"active","validFrom":"2026-07-11T10:00:00Z","validTo":null,"supersedes":[],"revokedAt":null,"revocationReason":null} +provenance: [{"sourceType":"hermes-session","sourceId":"session-stable-id","eventId":"event-idempotency-key","contentSha256":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","capturedAt":"2026-07-11T10:00:00Z"}] +createdAt: 2026-07-11T10:00:00Z +updatedAt: 2026-07-11T10:00:00Z +--- +Optional non-claim commentary. +``` + +Unknown fields and unknown major schemas fail validation. Timestamps are strict +RFC 3339 UTC (`Z`), not local offsets. Provenance is non-empty and contains +pointers and hashes, never embedded RAW. + +## Sealed claims + +A claim must be sealed when any of these is true: + +- primary scope is `person` or `relationship`; +- a subject is a `person` or `relationship` identity; +- `claimType` is `relationship`; +- visibility is `confidential` or `restricted`. + +The sealed union is stored directly in `claim`: + +```json +{ + "encoding": "sealed", + "alg": "AES-256-GCM", + "kekId": "kek:", + "keyRef": "key:", + "iv": "<12 bytes, base64>", + "ciphertext": "", + "tag": "<16 bytes, base64>", + "aadSha256": "" +} +``` + +PAM validates the envelope but never decrypts it. The DEK and wrapped key stay +in the external key registry referenced by `keyRef`; they must not enter Git, +logs, proposal metadata, or the PAM graph. + +AAD is compact canonical JSON with object keys sorted recursively, encoded as +UTF-8. In addition to record routing fields, it binds the envelope algorithm +and external key identifiers: + +```json +{"schema":"...","id":"...","revision":1,"claimType":"...","scope":{},"visibility":"...","subjects":[],"envelope":{"alg":"AES-256-GCM","kekId":"kek:...","keyRef":"key:..."}} +``` + +PAM recomputes its SHA-256 and requires an exact `aadSha256` match. An IV of any +size other than 96 bits, a tag other than 128 bits, empty ciphertext, malformed +`keyRef`, or a mismatched AAD hash fails closed. The sealed record body must be +empty. + +## Revision and lifecycle safety + +Canonical lifecycle statuses are `active`, `superseded`, `revoked`, and +`expired`. `proposed` exists only in the proposal queue. + +For an edit of an existing record, PAM enforces all of the following both when +recording and applying the proposal: + +- `revision` is exactly the current revision plus one; +- the proposal's `expectedTargetSha256` equals the SHA-256 of the complete prior + file and `expectedRevision` equals its revision; +- ID, creation time, claim type, scope, and subjects are immutable; plaintext + claims are byte-for-byte immutable; +- visibility can narrow but cannot widen; +- provenance and `lifecycle.supersedes` are append-only; +- only `active` may transition to a terminal lifecycle state; +- `updatedAt` strictly increases. + +A claim correction is a new record that names the prior ID in +`lifecycle.supersedes`; it is not an in-place claim rewrite. +PAM resolves every named target inside the current workspace, rejects missing, +symlinked, or invalid targets, and refuses a target newer than the correction. +Provenance entries are ordered by `capturedAt`, and none may be later than the +record's `updatedAt`. + +Because revision is authenticated AAD, a sealed record revision necessarily +has a refreshed envelope. PAM requires it to remain sealed, checks the new AAD +hash, and rejects IV reuse. Verifying that the decrypted claim is unchanged is +the authorized Fabric curator's responsibility; PAM never receives the DEK. + +## Proposal/apply boundary + +Use `memory_propose_record` for creation or `memory_propose_edit` for a metadata +or lifecycle revision. `memory_apply_proposal` is the separate authorized apply +stage. Proposal and apply both reject symlinks in the target or any ancestor, +use no-follow reads, and revalidate schema, revision, hash and graph projection. +Apply is protected by proposal and per-target exclusive locks. Before touching +the target it reserves the final archive path with an atomic no-replace link, +so an archive collision cannot produce an untracked write. The reservation is +`applying`, never `applied`; after the target is atomically persisted and +fsynced it is finalized to `applied`. A retry recovers either state +idempotently and verifies the persisted content hash before reporting success. +An `applying` reservation is bound to the complete immutable proposal artifact, +including source, diff/provenance, rationale, findings, validation and any +future proposal fields—not only its id, target and content hash. A mismatch +cannot overwrite the reservation, persist the target, or remove the live +proposal. +If the live proposal still exists, recovery also requires the archive proposal +identity, target, proposed/persisted hashes, and validation-warning summary to +match before the proposal artifact can be removed. + +Each lock carries a PID, host, random nonce, acquisition time, and heartbeat. +Takeover is fail-closed: it is allowed only when the heartbeat is stale and the +same-host owner PID is provably dead. Foreign-host, malformed, fresh, or live +locks require operator review or a later retry. Heartbeat and release verify +both the owner token and inode, so an old owner cannot update or remove a lock +that has been replaced. + +The graph node returned by validation is derived. It is checked both standalone +and against the workspace's actual graph-v1 files. A collision with a +non-memory node fails. An older `memory-record` projection is allowed only as a +bounded stale derivative and produces a warning requiring regeneration after +apply. Sealed and non-shared claims project only a generic digest and never +identity IDs, ciphertext, scope IDs, or key references. + +That warning is durable across the whole review boundary. Proposal results and +artifacts, applied archives, and apply results expose `graphProjectionStale`, +`regenerateAfterApply`, and a required `npm run memory:graph:index` follow-up. +An apply coordinator must not discard that follow-up when marking its task done. + +## Validation + +```bash +npm test +npm run migrations:check +npm run mcp:smoke +``` diff --git a/docs/mcp-server.md b/docs/mcp-server.md index b8ecde5..67a9c25 100644 --- a/docs/mcp-server.md +++ b/docs/mcp-server.md @@ -7,15 +7,19 @@ markdown + JSONL contract is unchanged; the server is purely additive runtime. ## What you get The server runs locally over stdio (no network, no daemon, no port) and exposes -15 tools under the `pam` namespace: +17 tools under the `pam` namespace: - `pam_version`, `memory_state`, `maintenance_config`: context tools - `memory_list`, `memory_read`, `memory_search`: safe filesystem reads under `memory/` +- `memory_record_validate`: validates `amf-memory/v1` Markdown and returns a safe graph projection - `graph_query`, `graph_stats`, `graph_validate`, `graph_reindex`: graph tools - `memory_audit`: hygiene checks, returns findings - `memory_propose_edit`: records a proposal artifact under `memory/maintenance/proposals/`; never mutates the target file +- `memory_propose_record`: validates an AMF record and records a create proposal; never writes the record directly - `memory_append`: appends a dated section to a managed log; refuses unmanaged paths -- `memory_apply_proposal`: applies a previously-recorded proposal after re-validating against current content; archives the artifact +- `memory_apply_proposal`: applies a recorded proposal through an exclusive + `applying` reservation, atomic target persistence, `applied` finalization, + and idempotent recovery - `maintenance_run`: wraps the maintenance CLI (defaults to dry-run) Write paths through the server are bounded: @@ -25,7 +29,10 @@ Write paths through the server are bounded: - `memory_apply_proposal` only writes to whatever target a previously-recorded proposal already passed through the safety validator at propose time, and re-validates everything (protected paths, drift, graph integrity) before - applying. + applying. Archive collisions and proposal-identity mismatches fail closed + before target persistence. +- `memory_propose_record` is the only MCP path for creating an AMF record; + creation remains pending until `memory_apply_proposal` re-validates it. - `graph_reindex` writes only the derived `memory/graph/catalog.json`. - `maintenance_run` is gated by `config` and defaults to dry-run. @@ -135,7 +142,7 @@ set to the repo root. The exact config file location depends on your client. Each host prefixes MCP tools with the server name. Claude Code surfaces them as `mcp__pam__memory_audit`, `mcp__pam__graph_validate`, and so on. Cursor and Codex use similar prefixes. The unprefixed tool name within the server is -always one of the 15 listed above. +always one of the 17 listed above. ## Workspace selection @@ -162,8 +169,8 @@ one-file change in `tools/lib/mcp-transport.mjs`. ## Safety surface -`memory_propose_edit` is the only tool that produces an artifact intended for -review. It rejects, with a clear error message: +`memory_propose_edit` and `memory_propose_record` are the only tools that +produce artifacts intended for review. They reject, with a clear error message: - paths matching `config.protectedPaths` (`AGENTS.md`, `CLAUDE.md`, `memory/agent-memory/`, `memory/sources/`); - paths that resolve outside the workspace; @@ -172,11 +179,16 @@ review. It rejects, with a clear error message: - diffs over 64 KB; - unified-diff hunks whose `before` doesn't match current content; - JSONL edits whose result fails `validateGraph`. +- AMF records that fail schema, lifecycle, scope, provenance, sealing, or path + validation. Proposal artifacts are JSON files under `memory/maintenance/proposals/`. Applying a proposal is a manual step that the human takes after review, typically via `memory_apply_proposal` below. +For the record schema, sealed-claim rules, lifecycle constraints, and safe graph +projection, see [AMF memory record v1](amf-memory-v1.md). + ## Write tools ### `memory_append` @@ -210,9 +222,11 @@ Inputs: - `proposalId` (required): the id of a JSON artifact under `memory/maintenance/proposals/.json`. -The server: +The server uses this state machine: -1. Loads the proposal. +1. Acquires the exclusive proposal lock and loads the archive/proposal state. + A pending or `applying` operation also acquires the per-target lock before + target validation or persistence. 2. Re-runs the same safety checks `memory_propose_edit` ran at propose time (protected paths, workspace escape, symlinks). 3. Re-applies the diff against the *current* target content. If the file has @@ -220,8 +234,23 @@ The server: unified-diff hunks don't align), apply is rejected and the artifact is untouched. 4. For JSONL targets, runs `validateGraph` on the proposed result. -5. On success, writes the new content, renames the artifact to - `.applied.json` with `appliedAt` and `status: "applied"` added. +5. Exclusively reserves `.applied.json` with `status: "applying"` before + touching the target. The reservation binds the complete immutable proposal + identity. A pre-existing foreign, malformed, or mismatched archive is a + collision and fails closed without overwriting the archive, writing the + target, or deleting the live proposal. +6. Atomically persists and fsyncs the target, then reloads and verifies that + the same reservation still owns the archive path. +7. Finalizes the archive as `status: "applied"` with `appliedAt` and the + persisted content hash. +8. Removes the live `.json` proposal only after finalization succeeds. + +Retries are idempotent. A matching `applying` reservation resumes the operation +whether or not the target was already persisted. A matching `applied` archive +is recovered only after its proposal identity and target hash are verified; a +lingering live proposal is removed only after that verification. If persistence +succeeds but finalization does not, the live proposal and recoverable archive +state remain for a later retry. Drift detection is intentional. A proposal that fails apply is a signal that the target changed since review; re-run the curator, get a fresh proposal, diff --git a/memory/agent-memory/pam-runtime.md b/memory/agent-memory/pam-runtime.md index d25ab0a..48a517a 100644 --- a/memory/agent-memory/pam-runtime.md +++ b/memory/agent-memory/pam-runtime.md @@ -76,9 +76,12 @@ context." ## Updating Memory -For durable AI memory, add or update graph records first, then keep markdown -logs/indexes compatible. Do not store secrets, credentials, private data, raw -private conversations, or machine-specific paths. +For classic PAM memory, add or update graph records first, then keep markdown +logs/indexes compatible. When `pam.version.json` enables `amfMemoryV1`, the +canonical `memory/amf/records/` Markdown record comes first and its graph node is a +safe derived projection. Create it through the proposal/apply flow and validate +it again before graph maintenance. Do not store secrets, credentials, private +data, raw private conversations, or machine-specific paths in plaintext. In OpenClaw workspaces, first map PAM concepts to existing OpenClaw-native or workspace-owned memory. Write only PAM-owned files by default, and do not edit diff --git a/memory/agent-memory/pam.md b/memory/agent-memory/pam.md index 6384d8f..6cb9604 100644 --- a/memory/agent-memory/pam.md +++ b/memory/agent-memory/pam.md @@ -603,6 +603,19 @@ YYYY-MM-DD. Links or references to related notes, decisions, runbooks, or raw sources. ``` +### 8.4 Structured scoped memory records + +An implementation that needs machine-validated scopes, lifecycle, provenance, +or sealed private claims may enable the optional `amf-memory/v1` record +contract. These records remain Markdown-first and use the normal PAM +proposal/apply review boundary. + +The record file is canonical. Graph, full-text, vector, and external memory +engine entries are derived and replaceable. Person, relationship, +confidential, and restricted claims MUST be sealed; PAM validates their +envelope but does not own keys or decrypt content. See +`docs/amf-memory-v1.md` for the complete portable contract. + --- ## 9. llm-wiki role diff --git a/memory/pam.version.json b/memory/pam.version.json index c8115b1..96d5618 100644 --- a/memory/pam.version.json +++ b/memory/pam.version.json @@ -1,5 +1,5 @@ { - "pamVersion": "0.5.3", + "pamVersion": "0.6.0", "memoryFormat": "graph-v1", "graphSchemaVersion": "pam-graph-v1", "features": { @@ -16,7 +16,10 @@ "fileOnlyCoverage": true, "llmRetrievalBenchmark": true, "benchmarkThresholdGate": true, - "tightBenchmarkRegressionGate": true + "tightBenchmarkRegressionGate": true, + "amfMemoryV1": true, + "sealedMemoryRecords": true, + "memoryRecordMcpTools": true }, - "updated": "2026-06-02" + "updated": "2026-07-11" } diff --git a/migrations/0.5.3-to-0.6.0-agent-memory-fabric-records.md b/migrations/0.5.3-to-0.6.0-agent-memory-fabric-records.md new file mode 100644 index 0000000..f11be55 --- /dev/null +++ b/migrations/0.5.3-to-0.6.0-agent-memory-fabric-records.md @@ -0,0 +1,23 @@ +# 0.5.3 to 0.6.0 - Agent Memory Fabric records + +## Summary + +PAM 0.6.0 adds the optional `amf-memory/v1` Markdown record contract, safe +graph projections, and two MCP tools for validation and proposal creation. + +## Compatibility + +No conversion of existing logs or graph-v1 data is required. Workspaces may +continue using classic PAM only. `memoryFormat` remains `graph-v1`. + +## Adoption + +1. Confirm `memory/pam.version.json` advertises `amfMemoryV1`. +2. Read `docs/amf-memory-v1.md`. +3. Create complete records through `memory_propose_record`. +4. Review the proposal artifact under `memory/maintenance/proposals/`. +5. Apply it with `memory_apply_proposal`. +6. Treat the returned graph node as a derived projection. + +Person, relationship, confidential, and restricted records must be sealed +before proposal. PAM validates but does not manage encryption keys. diff --git a/package.json b/package.json index 4723ca4..77960e4 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "portable-agent-memory", - "version": "0.5.3", + "version": "0.6.0", "private": false, "description": "Markdown-first portable memory, wiki, and maintenance toolkit for AI agents.", "type": "module", diff --git a/tools/lib/amf-memory-record.mjs b/tools/lib/amf-memory-record.mjs new file mode 100644 index 0000000..0a8586e --- /dev/null +++ b/tools/lib/amf-memory-record.mjs @@ -0,0 +1,606 @@ +import crypto from "node:crypto"; +import fs from "node:fs"; +import path from "node:path"; + +import { loadGraph, validateGraph } from "../memory-graph.mjs"; +import { readFileNoFollowSync } from "./secure-fs.mjs"; +import { toPosixPath } from "./workspace.mjs"; + +const SCHEMA = "amf-memory/v1"; +const RECORD_FIELDS = new Set([ + "schema", + "id", + "revision", + "claimType", + "scope", + "visibility", + "subjects", + "claim", + "lifecycle", + "provenance", + "createdAt", + "updatedAt" +]); +const REQUIRED_FIELDS = [...RECORD_FIELDS]; +const RESERVED_CLAIM_TYPES = new Set([ + "fact", + "preference", + "event", + "decision", + "instruction", + "summary", + "relationship" +]); +const SCOPE_TYPES = new Set(["agent", "person", "relationship", "room", "domain", "shared"]); +const VISIBILITIES = new Set(["private", "restricted", "shared", "confidential"]); +const SUBJECT_ROLES = new Set(["subject", "object", "participant", "owner"]); +const LIFECYCLE_STATUSES = new Set(["active", "superseded", "revoked", "expired"]); +const MEMORY_ID_RE = /^mem_[A-Za-z0-9][A-Za-z0-9_-]{7,127}$/; +const OPAQUE_REF_RE = /^(?:agent|person|relationship|room|domain):[A-Za-z0-9][A-Za-z0-9._-]{2,127}$/; +const HASH_RE = /^[0-9a-f]{64}$/i; +const RFC3339_UTC_RE = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,9}))?Z$/; +const NAMESPACED_TYPE_RE = /^[a-z][a-z0-9_-]{0,31}:[a-z][a-z0-9._-]{0,63}$/; +const CLAIM_FIELDS = { + plain: new Set(["encoding", "text"]), + sealed: new Set(["encoding", "alg", "kekId", "keyRef", "iv", "ciphertext", "tag", "aadSha256"]) +}; +const LIFECYCLE_FIELDS = new Set([ + "status", + "validFrom", + "validTo", + "supersedes", + "revokedAt", + "revocationReason" +]); +const PROVENANCE_FIELDS = new Set([ + "sourceType", + "sourceId", + "eventId", + "contentSha256", + "capturedAt" +]); +const SUBJECT_FIELDS = new Set(["identityId", "role"]); + +function parseScalar(raw, lineNumber, errors) { + const value = raw.trim(); + if (value === "") return ""; + if (["null", "true", "false"].includes(value) + || value.startsWith("[") + || value.startsWith("{") + || value.startsWith('"')) { + try { + return JSON.parse(value); + } catch (error) { + errors.push(`frontmatter line ${lineNumber} has invalid JSON value: ${error.message}`); + return null; + } + } + if (/^-?(?:0|[1-9]\d*)(?:\.\d+)?$/.test(value)) return Number(value); + return value; +} + +function parseMemoryRecord(content) { + const errors = []; + if (typeof content !== "string" || !content.startsWith("---\n")) { + return { ok: false, errors: ["record must start with a YAML frontmatter delimiter"], metadata: {}, body: "" }; + } + const end = content.indexOf("\n---\n", 4); + if (end === -1) { + return { ok: false, errors: ["record frontmatter is not terminated"], metadata: {}, body: "" }; + } + const metadata = {}; + const lines = content.slice(4, end).split("\n"); + for (let index = 0; index < lines.length; index += 1) { + const line = lines[index]; + if (!line.trim() || line.trimStart().startsWith("#")) continue; + const match = /^([A-Za-z][A-Za-z0-9_]*):\s*(.*)$/.exec(line); + if (!match) { + errors.push(`frontmatter line ${index + 2} must use top-level key: value syntax`); + continue; + } + const [, key, raw] = match; + if (Object.hasOwn(metadata, key)) { + errors.push(`duplicate frontmatter key: ${key}`); + continue; + } + metadata[key] = parseScalar(raw, index + 2, errors); + } + return { ok: errors.length === 0, errors, metadata, body: content.slice(end + 5) }; +} + +function canonicalize(value) { + if (Array.isArray(value)) return `[${value.map(canonicalize).join(",")}]`; + if (value && typeof value === "object") { + return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalize(value[key])}`).join(",")}}`; + } + return JSON.stringify(value); +} + +function sha256(value) { + return crypto.createHash("sha256").update(value, "utf8").digest("hex"); +} + +function recordSha256(content) { + return sha256(String(content)); +} + +function isRfc3339Utc(value) { + if (typeof value !== "string") return false; + const match = RFC3339_UTC_RE.exec(value); + if (!match) return false; + const [, year, month, day, hour, minute, second] = match; + const timestamp = Date.parse(value); + if (!Number.isFinite(timestamp)) return false; + const date = new Date(timestamp); + return date.getUTCFullYear() === Number(year) + && date.getUTCMonth() + 1 === Number(month) + && date.getUTCDate() === Number(day) + && date.getUTCHours() === Number(hour) + && date.getUTCMinutes() === Number(minute) + && date.getUTCSeconds() === Number(second); +} + +function validateExactObject(value, label, allowed, errors) { + if (!value || typeof value !== "object" || Array.isArray(value)) { + errors.push(`${label} must be an object`); + return false; + } + for (const key of Object.keys(value)) { + if (!allowed.has(key)) errors.push(`${label} contains unknown field: ${key}`); + } + for (const key of allowed) { + if (!Object.hasOwn(value, key)) errors.push(`${label} is missing field: ${key}`); + } + return true; +} + +function decodeBase64(value, label, errors) { + if (typeof value !== "string" || value.length === 0 || value.length % 4 === 1 + || !/^[A-Za-z0-9+/_-]+={0,2}$/.test(value)) { + errors.push(`${label} must be non-empty base64`); + return null; + } + try { + const decoded = Buffer.from(value, "base64"); + if (decoded.length === 0 || decoded.toString("base64url") !== value.replace(/=+$/, "").replace(/\+/g, "-").replace(/\//g, "_")) { + errors.push(`${label} must be canonical base64 or base64url`); + return null; + } + return decoded; + } catch { + errors.push(`${label} must be valid base64`); + return null; + } +} + +function aadObjectFor(metadata) { + const aad = { + schema: metadata.schema, + id: metadata.id, + revision: metadata.revision, + claimType: metadata.claimType, + scope: metadata.scope, + visibility: metadata.visibility, + subjects: metadata.subjects + }; + if (metadata.claim?.encoding === "sealed") { + aad.envelope = { + alg: metadata.claim.alg, + kekId: metadata.claim.kekId, + keyRef: metadata.claim.keyRef + }; + } + return aad; +} + +function aadSha256For(metadata) { + return sha256(canonicalize(aadObjectFor(metadata))); +} + +function isScopeId(type, id) { + if (type === "shared") return id === "shared:global"; + return typeof id === "string" && id.startsWith(`${type}:`) && OPAQUE_REF_RE.test(id); +} + +function isIdentityRef(value) { + return typeof value === "string" && /^(?:agent|person|relationship):/.test(value) && OPAQUE_REF_RE.test(value); +} + +function validateSubjects(subjects, errors) { + if (!Array.isArray(subjects) || subjects.length === 0) { + errors.push("subjects must be a non-empty array"); + return; + } + const seen = new Set(); + for (let index = 0; index < subjects.length; index += 1) { + const subject = subjects[index]; + const label = `subjects[${index}]`; + if (!validateExactObject(subject, label, SUBJECT_FIELDS, errors)) continue; + if (!isIdentityRef(subject.identityId)) errors.push(`${label}.identityId must be an opaque canonical identity`); + if (!SUBJECT_ROLES.has(subject.role)) errors.push(`${label}.role is invalid`); + const key = `${subject.identityId}\0${subject.role}`; + if (seen.has(key)) errors.push("subjects must not contain duplicates"); + seen.add(key); + } +} + +function validateProvenance(metadata, errors) { + const provenance = metadata.provenance; + if (!Array.isArray(provenance) || provenance.length === 0) { + errors.push("provenance must be a non-empty array"); + return; + } + const seenEvents = new Set(); + let previousCapturedAt = -Infinity; + for (let index = 0; index < provenance.length; index += 1) { + const item = provenance[index]; + const label = `provenance[${index}]`; + if (!validateExactObject(item, label, PROVENANCE_FIELDS, errors)) continue; + if (typeof item.sourceType !== "string" || !/^[a-z][a-z0-9._-]{1,63}$/.test(item.sourceType)) { + errors.push(`${label}.sourceType is invalid`); + } + if (typeof item.sourceId !== "string" || item.sourceId.length < 1 || item.sourceId.length > 256) { + errors.push(`${label}.sourceId must be a stable pointer of at most 256 characters`); + } + if (typeof item.eventId !== "string" || item.eventId.length < 8 || item.eventId.length > 256) { + errors.push(`${label}.eventId must be a stable idempotency key`); + } else if (seenEvents.has(item.eventId)) { + errors.push("provenance eventId values must be unique"); + } + seenEvents.add(item.eventId); + if (!HASH_RE.test(String(item.contentSha256 ?? ""))) errors.push(`${label}.contentSha256 must be a SHA-256 digest`); + if (!isRfc3339Utc(item.capturedAt)) { + errors.push(`${label}.capturedAt must be RFC 3339 UTC`); + } else { + const capturedAt = Date.parse(item.capturedAt); + if (capturedAt < previousCapturedAt) errors.push("provenance must be ordered by capturedAt ascending"); + if (isRfc3339Utc(metadata.updatedAt) && capturedAt > Date.parse(metadata.updatedAt)) { + errors.push(`${label}.capturedAt must not be later than updatedAt`); + } + previousCapturedAt = capturedAt; + } + } +} + +function validateLifecycle(metadata, errors) { + const lifecycle = metadata.lifecycle; + if (!validateExactObject(lifecycle, "lifecycle", LIFECYCLE_FIELDS, errors)) return; + if (!LIFECYCLE_STATUSES.has(lifecycle.status)) errors.push("lifecycle.status is invalid"); + for (const key of ["validFrom", "validTo", "revokedAt"]) { + if (lifecycle[key] !== null && !isRfc3339Utc(lifecycle[key])) errors.push(`lifecycle.${key} must be null or RFC 3339 UTC`); + } + if (!Array.isArray(lifecycle.supersedes)) { + errors.push("lifecycle.supersedes must be an array"); + } else { + if (lifecycle.supersedes.some((id) => !MEMORY_ID_RE.test(String(id)))) errors.push("lifecycle.supersedes contains an invalid memory id"); + if (lifecycle.supersedes.includes(metadata.id)) errors.push("lifecycle.supersedes must not reference the record itself"); + if (new Set(lifecycle.supersedes).size !== lifecycle.supersedes.length) errors.push("lifecycle.supersedes must not contain duplicates"); + } + if (lifecycle.revocationReason !== null + && (typeof lifecycle.revocationReason !== "string" || lifecycle.revocationReason.trim() === "" || lifecycle.revocationReason.length > 512)) { + errors.push("lifecycle.revocationReason must be null or a non-empty string of at most 512 characters"); + } + if (lifecycle.status === "revoked") { + if (!isRfc3339Utc(lifecycle.revokedAt)) errors.push("revoked lifecycle requires revokedAt"); + if (typeof lifecycle.revocationReason !== "string" || lifecycle.revocationReason.trim() === "") { + errors.push("revoked lifecycle requires revocationReason"); + } + } else if (lifecycle.revokedAt !== null || lifecycle.revocationReason !== null) { + errors.push("only revoked lifecycle may set revokedAt or revocationReason"); + } + if (lifecycle.status === "expired" && !isRfc3339Utc(lifecycle.validTo)) { + errors.push("expired lifecycle requires validTo"); + } + if (isRfc3339Utc(lifecycle.validFrom) && isRfc3339Utc(lifecycle.validTo) + && Date.parse(lifecycle.validTo) < Date.parse(lifecycle.validFrom)) { + errors.push("lifecycle.validTo must not be earlier than validFrom"); + } + if (lifecycle.status === "expired" && isRfc3339Utc(lifecycle.validTo) && isRfc3339Utc(metadata.updatedAt) + && Date.parse(lifecycle.validTo) > Date.parse(metadata.updatedAt)) { + errors.push("expired lifecycle.validTo must not be later than updatedAt"); + } + if (lifecycle.status === "revoked" && isRfc3339Utc(lifecycle.revokedAt) && isRfc3339Utc(metadata.updatedAt) + && Date.parse(lifecycle.revokedAt) > Date.parse(metadata.updatedAt)) { + errors.push("lifecycle.revokedAt must not be later than updatedAt"); + } +} + +function validateClaim(metadata, body, errors) { + const claim = metadata.claim; + if (!claim || typeof claim !== "object" || Array.isArray(claim)) { + errors.push("claim must be an object"); + return; + } + const fields = CLAIM_FIELDS[claim.encoding]; + if (!fields) { + errors.push("claim.encoding must be plain or sealed"); + return; + } + validateExactObject(claim, "claim", fields, errors); + const subjectRequiresSealing = Array.isArray(metadata.subjects) + && metadata.subjects.some((subject) => /^(?:person|relationship):/.test(String(subject?.identityId ?? ""))); + const mustBeSealed = ["person", "relationship"].includes(metadata.scope?.type) + || metadata.claimType === "relationship" + || ["confidential", "restricted"].includes(metadata.visibility) + || subjectRequiresSealing; + if (mustBeSealed && claim.encoding !== "sealed") { + errors.push("person/relationship scope or subject, relationship claimType, and confidential/restricted visibility require a sealed claim"); + } + if (claim.encoding === "plain") { + if (typeof claim.text !== "string" || claim.text.trim() === "") errors.push("plain claim.text must not be empty"); + if (body.includes("```amf-sealed")) errors.push("plain record body must not contain a sealed envelope"); + return; + } + if (body.trim() !== "") errors.push("sealed record body must be empty"); + if (claim.alg !== "AES-256-GCM") errors.push("sealed claim.alg must be AES-256-GCM"); + if (typeof claim.kekId !== "string" || !/^kek:[A-Za-z0-9][A-Za-z0-9._-]{2,127}$/.test(claim.kekId)) { + errors.push("sealed claim.kekId must be an opaque versioned KEK id"); + } + if (typeof claim.keyRef !== "string" || !/^key:[A-Za-z0-9][A-Za-z0-9._-]{2,127}$/.test(claim.keyRef)) { + errors.push("sealed claim.keyRef must be an opaque external key reference"); + } + const iv = decodeBase64(claim.iv, "sealed claim.iv", errors); + const ciphertext = decodeBase64(claim.ciphertext, "sealed claim.ciphertext", errors); + const tag = decodeBase64(claim.tag, "sealed claim.tag", errors); + if (iv && iv.length !== 12) errors.push("sealed claim.iv must decode to 12 bytes"); + if (ciphertext && ciphertext.length === 0) errors.push("sealed claim.ciphertext must not be empty"); + if (tag && tag.length !== 16) errors.push("sealed claim.tag must decode to 16 bytes"); + if (!HASH_RE.test(String(claim.aadSha256 ?? ""))) { + errors.push("sealed claim.aadSha256 must be a SHA-256 digest"); + } else { + const expected = aadSha256For(metadata); + if (claim.aadSha256.toLowerCase() !== expected) errors.push(`sealed claim.aadSha256 must match canonical AAD (${expected})`); + } +} + +function statusForProjection(metadata) { + return metadata.lifecycle.status === "active" ? "confirmed" : "obsolete"; +} + +function plainDigest(text) { + return String(text) + .replace(/```[\s\S]*?```/g, " ") + .replace(/^#+\s*/gm, "") + .replace(/[`*_~>]/g, "") + .replace(/\s+/g, " ") + .trim() + .slice(0, 180); +} + +function recordPathFor(metadata) { + if (!MEMORY_ID_RE.test(String(metadata?.id ?? ""))) return null; + return toPosixPath(path.join("memory", "amf", "records", `${metadata.id}.md`)); +} + +function projectMemoryRecord(metadata, sourcePath = null) { + const mayProjectClaim = metadata.claim.encoding === "plain" + && metadata.scope.type === "shared" + && metadata.visibility === "shared"; + const digest = mayProjectClaim ? plainDigest(metadata.claim.text) : `Protected ${metadata.claimType} memory.`; + return { + id: metadata.id, + k: "memory-record", + n: mayProjectClaim ? (digest.slice(0, 80) || `${metadata.claimType} memory`) : "Protected memory record", + d: digest, + st: statusForProjection(metadata), + c: "high", + u: metadata.updatedAt.slice(0, 10), + src: sourcePath ?? recordPathFor(metadata), + tags: [SCHEMA, metadata.claimType, metadata.scope.type, metadata.lifecycle.status, metadata.claim.encoding] + }; +} + +function validateSupersedesInWorkspace(metadata, options, errors) { + const supersedes = Array.isArray(metadata.lifecycle?.supersedes) ? metadata.lifecycle.supersedes : []; + if (supersedes.length === 0 || options.resolveSupersedes === false) return; + if (!options.workspaceRoot) { + errors.push("workspaceRoot is required to resolve lifecycle.supersedes targets"); + return; + } + for (const memoryId of supersedes) { + if (!MEMORY_ID_RE.test(String(memoryId))) continue; + const targetPath = toPosixPath(path.join("memory", "amf", "records", `${memoryId}.md`)); + const absolute = path.join(options.workspaceRoot, targetPath); + if (!fs.existsSync(absolute)) { + errors.push(`lifecycle.supersedes target does not exist: ${memoryId}`); + continue; + } + try { + const targetContent = readFileNoFollowSync(options.workspaceRoot, absolute); + const target = validateMemoryRecord(targetContent, { + expectedPath: targetPath, + workspaceRoot: options.workspaceRoot, + resolveSupersedes: false, + checkWorkspaceGraph: false + }); + if (!target.ok) { + errors.push(`lifecycle.supersedes target is invalid (${memoryId}): ${target.errors.join("; ")}`); + } else if (isRfc3339Utc(metadata.updatedAt) && Date.parse(target.metadata.updatedAt) > Date.parse(metadata.updatedAt)) { + errors.push(`lifecycle.supersedes target is newer than this record: ${memoryId}`); + } + } catch (error) { + errors.push(`could not safely resolve lifecycle.supersedes target ${memoryId}: ${error.message}`); + } + } +} + +function validateProjectionInWorkspace(projection, options, errors, warnings) { + if (!options.workspaceRoot || options.checkWorkspaceGraph === false) return; + try { + const graph = loadGraph(options.workspaceRoot); + const baseline = validateGraph(graph); + if (!baseline.ok) { + errors.push(`workspace graph is invalid: ${baseline.errors.join("; ")}`); + return; + } + const existing = graph.nodes.find((node) => node.id === projection.id); + if (existing && existing.k !== "memory-record") { + errors.push(`graph id collision with non-memory-record node: ${projection.id}`); + return; + } + const candidateNodes = existing + ? graph.nodes.map((node) => node.id === projection.id ? projection : node) + : [...graph.nodes, projection]; + const candidate = validateGraph({ ...graph, nodes: candidateNodes }); + if (!candidate.ok) errors.push(`projected workspace graph is invalid: ${candidate.errors.join("; ")}`); + if (existing && canonicalize(existing) !== canonicalize(projection)) { + warnings.push(`derived graph projection is stale for ${projection.id}; regenerate it after apply`); + } + } catch (error) { + errors.push(`could not validate projection against workspace graph: ${error.message}`); + } +} + +function validateMemoryRecord(content, options = {}) { + const parsed = parseMemoryRecord(content); + const errors = [...parsed.errors]; + const warnings = []; + const metadata = parsed.metadata; + + for (const key of Object.keys(metadata)) { + if (!RECORD_FIELDS.has(key)) errors.push(`unknown frontmatter key: ${key}`); + } + for (const key of REQUIRED_FIELDS) { + if (!Object.hasOwn(metadata, key)) errors.push(`missing frontmatter key: ${key}`); + } + if (metadata.schema !== SCHEMA) errors.push(`schema must be ${SCHEMA}`); + if (!MEMORY_ID_RE.test(String(metadata.id ?? ""))) errors.push("id must be an opaque mem_"); + if (!Number.isInteger(metadata.revision) || metadata.revision < 1) errors.push("revision must be a positive integer"); + if (!RESERVED_CLAIM_TYPES.has(metadata.claimType) && !NAMESPACED_TYPE_RE.test(String(metadata.claimType ?? ""))) { + errors.push("claimType must be a v1 reserved value or a namespaced stable string"); + } + if (!metadata.scope || typeof metadata.scope !== "object" || Array.isArray(metadata.scope) + || Object.keys(metadata.scope).sort().join(",") !== "id,type") { + errors.push("scope must contain exactly type and id"); + } else { + if (!SCOPE_TYPES.has(metadata.scope.type)) errors.push("scope.type is invalid"); + if (!isScopeId(metadata.scope.type, metadata.scope.id)) errors.push("scope.id must be canonical and match scope.type"); + } + if (!VISIBILITIES.has(metadata.visibility)) errors.push("visibility is invalid"); + validateSubjects(metadata.subjects, errors); + validateClaim(metadata, parsed.body, errors); + validateLifecycle(metadata, errors); + validateProvenance(metadata, errors); + for (const key of ["createdAt", "updatedAt"]) { + if (!isRfc3339Utc(metadata[key])) errors.push(`${key} must be RFC 3339 UTC`); + } + if (isRfc3339Utc(metadata.createdAt) && isRfc3339Utc(metadata.updatedAt) + && Date.parse(metadata.updatedAt) < Date.parse(metadata.createdAt)) { + errors.push("updatedAt must not be earlier than createdAt"); + } + if (metadata.revision === 1 && isRfc3339Utc(metadata.createdAt) && isRfc3339Utc(metadata.updatedAt) + && metadata.createdAt !== metadata.updatedAt) { + errors.push("revision 1 must have identical createdAt and updatedAt"); + } + validateSupersedesInWorkspace(metadata, options, errors); + + const expectedPath = recordPathFor(metadata); + if (options.expectedPath && expectedPath && toPosixPath(options.expectedPath) !== expectedPath) { + errors.push(`record path must be ${expectedPath}`); + } + + let projection = null; + if (errors.length === 0) { + projection = projectMemoryRecord(metadata, expectedPath); + const graphValidation = validateGraph({ nodes: [projection], edges: [], aliases: [] }); + if (!graphValidation.ok) errors.push(`graph projection is invalid: ${graphValidation.errors.join("; ")}`); + else validateProjectionInWorkspace(projection, options, errors, warnings); + } + if (metadata.claim?.encoding === "plain" && !(metadata.scope?.type === "shared" && metadata.visibility === "shared")) { + warnings.push("non-shared plaintext claim is omitted from the graph projection"); + } + + return { + ok: errors.length === 0, + errors, + warnings, + metadata, + body: parsed.body, + expectedPath, + projection: errors.length === 0 ? projection : null, + aadSha256: errors.length === 0 && metadata.claim?.encoding === "sealed" ? aadSha256For(metadata) : null + }; +} + +function visibilityCanNarrow(from, to) { + const allowed = { + shared: new Set(["shared", "restricted", "confidential", "private"]), + restricted: new Set(["restricted", "confidential", "private"]), + confidential: new Set(["confidential", "private"]), + private: new Set(["private"]) + }; + return allowed[from]?.has(to) ?? false; +} + +function validateMemoryRecordTransition(currentContent, proposedContent, options = {}) { + const validationOptions = { + ...(options.expectedPath ? { expectedPath: options.expectedPath } : {}), + ...(options.workspaceRoot ? { workspaceRoot: options.workspaceRoot } : {}) + }; + const current = validateMemoryRecord(currentContent, validationOptions); + const proposed = validateMemoryRecord(proposedContent, validationOptions); + const errors = []; + if (!current.ok) errors.push(`current AMF record is invalid: ${current.errors.join("; ")}`); + if (!proposed.ok) errors.push(`proposed AMF record is invalid: ${proposed.errors.join("; ")}`); + if (errors.length > 0) return { ok: false, errors, current, proposed }; + + const oldRecord = current.metadata; + const newRecord = proposed.metadata; + if (newRecord.id !== oldRecord.id) errors.push("record id is immutable"); + if (newRecord.revision !== oldRecord.revision + 1) errors.push(`revision must increment exactly from ${oldRecord.revision} to ${oldRecord.revision + 1}`); + if (newRecord.createdAt !== oldRecord.createdAt) errors.push("createdAt is immutable"); + if (Date.parse(newRecord.updatedAt) <= Date.parse(oldRecord.updatedAt)) errors.push("updatedAt must increase on every revision"); + for (const key of ["claimType", "scope", "subjects"]) { + if (canonicalize(newRecord[key]) !== canonicalize(oldRecord[key])) errors.push(`${key} is immutable within a record; create a superseding record to correct the claim`); + } + if (oldRecord.claim.encoding === "plain" && canonicalize(newRecord.claim) !== canonicalize(oldRecord.claim)) { + errors.push("claim is immutable within a record; create a superseding record to correct the claim"); + } + if (oldRecord.claim.encoding === "sealed") { + if (newRecord.claim.encoding !== "sealed") errors.push("sealed claim must not be downgraded"); + if (newRecord.claim.iv === oldRecord.claim.iv) errors.push("sealed claim must use a new IV for every revision"); + } + if (!visibilityCanNarrow(oldRecord.visibility, newRecord.visibility)) errors.push("visibility must not widen across revisions"); + if (newRecord.provenance.length < oldRecord.provenance.length + || oldRecord.provenance.some((item, index) => canonicalize(item) !== canonicalize(newRecord.provenance[index]))) { + errors.push("provenance is append-only and existing entries must remain unchanged and ordered"); + } + const oldSupersedes = oldRecord.lifecycle.supersedes; + const newSupersedes = newRecord.lifecycle.supersedes; + if (newSupersedes.length < oldSupersedes.length + || oldSupersedes.some((id, index) => id !== newSupersedes[index])) { + errors.push("lifecycle.supersedes is append-only"); + } + const allowedTransitions = oldRecord.lifecycle.status === "active" + ? new Set(["active", "superseded", "revoked", "expired"]) + : new Set([oldRecord.lifecycle.status]); + if (!allowedTransitions.has(newRecord.lifecycle.status)) { + errors.push(`invalid lifecycle transition ${oldRecord.lifecycle.status} -> ${newRecord.lifecycle.status}`); + } + if (options.expectedRevision !== undefined && options.expectedRevision !== oldRecord.revision) { + errors.push(`expectedRevision ${options.expectedRevision} does not match current revision ${oldRecord.revision}`); + } + const currentHash = recordSha256(currentContent); + if (options.expectedTargetSha256 !== undefined && options.expectedTargetSha256 !== currentHash) { + errors.push("current record SHA-256 does not match proposal base hash"); + } + return { ok: errors.length === 0, errors, current, proposed, currentHash }; +} + +function isAmfRecordPath(relativePath) { + return /^memory\/amf\/records\/mem_[A-Za-z0-9][A-Za-z0-9_-]{7,127}\.md$/.test(toPosixPath(String(relativePath ?? ""))); +} + +export { + SCHEMA, + aadSha256For, + canonicalize, + isAmfRecordPath, + isRfc3339Utc, + parseMemoryRecord, + projectMemoryRecord, + recordPathFor, + recordSha256, + validateMemoryRecord, + validateMemoryRecordTransition +}; diff --git a/tools/lib/mcp-tools.mjs b/tools/lib/mcp-tools.mjs index 852b886..d1195fa 100644 --- a/tools/lib/mcp-tools.mjs +++ b/tools/lib/mcp-tools.mjs @@ -13,9 +13,10 @@ import { detectMemoryState } from "../memory-migration.mjs"; import { appendEntry } from "./memory-append.mjs"; import { applyProposal } from "./memory-apply-proposal.mjs"; +import { validateMemoryRecord } from "./amf-memory-record.mjs"; import { runAudit } from "./memory-audit.mjs"; import { memoryList, memoryRead, memorySearch } from "./memory-fs.mjs"; -import { proposeEdit } from "./memory-proposals.mjs"; +import { proposeEdit, proposeMemoryRecord } from "./memory-proposals.mjs"; import { loadWorkspaceConfig, toPosixPath } from "./workspace.mjs"; function readPamVersion(workspaceRoot) { @@ -87,6 +88,30 @@ function buildToolRegistry({ workspaceRoot, serverVersion }) { }, handler: async (args) => jsonResultContent(memoryRead(workspaceRoot, args?.path)) }, + { + name: "memory_record_validate", + description: "Validates an amf-memory/v1 Markdown record and returns its safe graph projection without decrypting sealed content.", + inputSchema: { + type: "object", + properties: { + path: { type: "string", description: "AMF record path under memory/amf/records/" } + }, + required: ["path"], + additionalProperties: false + }, + handler: async (args) => { + const record = memoryRead(workspaceRoot, args?.path); + const validation = validateMemoryRecord(record.content, { expectedPath: record.path, workspaceRoot }); + return jsonResultContent({ + status: validation.ok ? "valid" : "invalid", + path: record.path, + errors: validation.errors, + warnings: validation.warnings, + metadata: validation.metadata, + projection: validation.projection + }); + } + }, { name: "memory_search", description: "Substring or regex search across memory/ markdown and JSONL files.", @@ -213,7 +238,7 @@ function buildToolRegistry({ workspaceRoot, serverVersion }) { }, { name: "memory_apply_proposal", - description: "Applies a previously-recorded proposal (memory/maintenance/proposals/.json) to its target file. Re-validates path safety and re-applies the diff against current content (drift detection). On success, archives the artifact as .applied.json with appliedAt added.", + description: "Safely applies a recorded proposal after re-validating path safety, drift, and content. It exclusively reserves .applied.json as status applying, atomically persists the target, finalizes the archive as applied, then removes the live proposal. Retries recover idempotently; archive collisions or identity mismatches fail closed.", inputSchema: { type: "object", properties: { @@ -230,6 +255,31 @@ function buildToolRegistry({ workspaceRoot, serverVersion }) { return jsonResultContent(result); } }, + { + name: "memory_propose_record", + description: "Validates a complete amf-memory/v1 Markdown record and records a create proposal. It never writes the canonical record directly.", + inputSchema: { + type: "object", + properties: { + content: { type: "string", description: "Complete AMF Markdown record including frontmatter" }, + rationale: { type: "string" }, + findingIds: { type: "array", items: { type: "string" } } + }, + required: ["content", "rationale"], + additionalProperties: false + }, + handler: async (args) => { + const result = proposeMemoryRecord(workspaceRoot, loadConfig(), args ?? {}); + if (!result.ok) { + return jsonResultContent({ + status: "rejected", + error: result.error, + validation: result.validation ?? { ok: false, errors: [result.error] } + }); + } + return jsonResultContent(result); + } + }, { name: "memory_propose_edit", description: "Records a proposed edit as a JSON artifact under memory/maintenance/proposals/. Never mutates the target file. Rejects protected paths, escapes, oversize diffs, and JSONL edits that would invalidate the graph.", diff --git a/tools/lib/memory-apply-proposal.mjs b/tools/lib/memory-apply-proposal.mjs index 8339728..dddc91d 100644 --- a/tools/lib/memory-apply-proposal.mjs +++ b/tools/lib/memory-apply-proposal.mjs @@ -1,3 +1,4 @@ +import crypto from "node:crypto"; import fs from "node:fs"; import path from "node:path"; @@ -6,9 +7,18 @@ import { applyReplace, applyUnifiedDiff, parseUnifiedDiff, + summarizeAmfValidation, + validateAmfRecordTarget, validateGraphJsonl, validatePathSafety } from "./memory-proposals.mjs"; +import { isAmfRecordPath, recordSha256 } from "./amf-memory-record.mjs"; +import { + acquireExclusiveLock, + atomicWriteFileSync, + readFileNoFollowSync, + removeRegularFileNoFollowSync +} from "./secure-fs.mjs"; import { toPosixPath, workspaceRelative } from "./workspace.mjs"; function proposalPathFor(workspaceRoot, proposalId) { @@ -19,86 +29,378 @@ function appliedPathFor(workspaceRoot, proposalId) { return path.join(workspaceRoot, PROPOSALS_DIRNAME, `${proposalId}.applied.json`); } -function loadProposal(workspaceRoot, proposalId) { - if (typeof proposalId !== "string" || proposalId.trim() === "") { - return { ok: false, error: "proposalId is required" }; - } - if (proposalId.includes("/") || proposalId.includes("\\") || proposalId.includes("..")) { - return { ok: false, error: "proposalId must not contain path separators" }; - } - const absolute = proposalPathFor(workspaceRoot, proposalId); - if (!fs.existsSync(absolute)) { - return { ok: false, error: `proposal not found: ${proposalId}` }; +function validateProposalId(proposalId) { + if (typeof proposalId !== "string" || proposalId.trim() === "") return "proposalId is required"; + if (!/^[A-Za-z0-9][A-Za-z0-9-]{0,127}$/.test(proposalId) || proposalId.includes("..")) { + return "proposalId contains invalid characters or path separators"; } + return null; +} + +function readJsonArtifact(workspaceRoot, absolute, label) { try { - return { ok: true, record: JSON.parse(fs.readFileSync(absolute, "utf8")), absolute }; + return { ok: true, record: JSON.parse(readFileNoFollowSync(workspaceRoot, absolute)) }; } catch (error) { - return { ok: false, error: `proposal is not valid JSON: ${error.message}` }; + return { ok: false, error: `${label} is not valid safe JSON: ${error.message}` }; } } -function applyProposal(workspaceRoot, config, input) { - const { proposalId } = input ?? {}; - const loaded = loadProposal(workspaceRoot, proposalId); - if (!loaded.ok) return loaded; - const { record, absolute: proposalAbsolute } = loaded; +function canonicalJson(value) { + if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`; + if (value && typeof value === "object") { + return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(",")}}`; + } + return JSON.stringify(value); +} - const { targetPath, diff } = record; - if (typeof targetPath !== "string" || targetPath.trim() === "") { - return { ok: false, error: "proposal missing targetPath" }; +function proposalIdentity(record) { + return { + proposalId: record?.proposalId ?? null, + createdAt: record?.createdAt ?? null, + source: record?.source ?? null, + targetPath: record?.targetPath ?? null, + diff: record?.diff ?? null, + rationale: record?.rationale ?? null, + findingIds: Array.isArray(record?.findingIds) ? record.findingIds : [], + expectedRevision: record?.expectedRevision ?? null, + expectedTargetSha256: record?.expectedTargetSha256 ?? null, + proposedContentSha256: record?.proposedContentSha256 ?? null, + proposedContentLength: record?.proposedContentLength ?? null + }; +} + +function validationWarningSummary(validation) { + const summary = validation?.amfMemory ?? validation ?? {}; + return { + warnings: Array.isArray(summary.warnings) ? summary.warnings.map(String) : [], + graphProjectionStale: summary.graphProjectionStale === true, + regenerateAfterApply: summary.regenerateAfterApply === true, + followup: summary.followup ?? null + }; +} + +function validateAppliedArchiveBinding(proposalId, archive, proposal = null) { + const proposedHash = String(archive?.proposedContentSha256 ?? ""); + const persistedHash = String(archive?.persistedContentSha256 ?? ""); + if (archive?.status !== "applied" || archive?.proposalId !== proposalId + || typeof archive?.targetPath !== "string" + || !/^[0-9a-f]{64}$/i.test(proposedHash) + || !/^[0-9a-f]{64}$/i.test(persistedHash) + || proposedHash !== persistedHash) { + return "applied archive is malformed or belongs to another proposal"; + } + if (!proposal) return null; + if (proposal.proposalId !== proposalId + || canonicalJson(proposalIdentity(archive)) !== canonicalJson(proposalIdentity(proposal))) { + return "applied archive identity does not match the live proposal"; + } + if (proposal.proposedContentSha256 !== proposedHash) { + return "applied archive content hash does not match the live proposal"; } - if (!diff || typeof diff !== "object") { - return { ok: false, error: "proposal missing diff" }; + if (canonicalJson(validationWarningSummary(archive.validation)) + !== canonicalJson(validationWarningSummary(proposal.validation))) { + return "applied archive validation warnings do not match the live proposal"; } + return null; +} - const pathCheck = validatePathSafety(workspaceRoot, targetPath, config); - if (!pathCheck.ok) return { ok: false, error: pathCheck.error }; +function loadProposal(workspaceRoot, proposalId) { + const absolute = proposalPathFor(workspaceRoot, proposalId); + if (!fs.existsSync(absolute)) return { ok: false, error: `proposal not found: ${proposalId}` }; + const loaded = readJsonArtifact(workspaceRoot, absolute, "proposal"); + if (!loaded.ok) return loaded; + if (loaded.record.proposalId !== proposalId) return { ok: false, error: "proposal artifact id does not match requested id" }; + return { ok: true, record: loaded.record, absolute }; +} - const targetAbsolute = pathCheck.absolute; - if (!fs.existsSync(targetAbsolute)) { - return { ok: false, error: `target file does not exist: ${targetPath}` }; - } - const currentContent = fs.readFileSync(targetAbsolute, "utf8"); +function loadArchive(workspaceRoot, proposalId) { + const absolute = appliedPathFor(workspaceRoot, proposalId); + if (!fs.existsSync(absolute)) return { ok: true, exists: false, absolute, record: null }; + const loaded = readJsonArtifact(workspaceRoot, absolute, "applied archive"); + if (!loaded.ok) return loaded; + return { ok: true, exists: true, absolute, record: loaded.record }; +} - let proposedContent; +function renderProposedContent(targetPath, diff, currentContent) { + if (diff.kind === "create") { + if (!isAmfRecordPath(targetPath)) return { ok: false, error: "create proposals are restricted to AMF memory record paths" }; + if (typeof diff.content !== "string" || diff.content.trim() === "") return { ok: false, error: "create proposal requires content" }; + return { ok: true, content: diff.content }; + } if (diff.kind === "replace") { const applied = applyReplace(currentContent, diff); - if (!applied.ok) return { ok: false, error: applied.error }; - proposedContent = applied.next; - } else if (diff.kind === "unified-diff") { - if (typeof diff.patch !== "string" || diff.patch.trim() === "") { - return { ok: false, error: "unified-diff requires a patch string" }; - } + return applied.ok ? { ok: true, content: applied.next } : applied; + } + if (diff.kind === "unified-diff") { + if (typeof diff.patch !== "string" || diff.patch.trim() === "") return { ok: false, error: "unified-diff requires a patch string" }; const parsed = parseUnifiedDiff(diff.patch); - if (!parsed.ok) return { ok: false, error: parsed.error }; - const parsedTargetPosix = toPosixPath(parsed.targetPath); - if (parsedTargetPosix !== toPosixPath(targetPath)) { + if (!parsed.ok) return parsed; + if (toPosixPath(parsed.targetPath) !== toPosixPath(targetPath)) { return { ok: false, error: `diff target mismatch: ${parsed.targetPath} vs ${targetPath}` }; } const applied = applyUnifiedDiff(currentContent, parsed); - if (!applied.ok) return { ok: false, error: applied.error }; - proposedContent = applied.next; - } else { - return { ok: false, error: `unsupported diff kind: ${diff.kind}` }; + return applied.ok ? { ok: true, content: applied.next } : applied; } + return { ok: false, error: `unsupported diff kind: ${diff.kind}` }; +} - const graphValidation = validateGraphJsonl(workspaceRoot, targetPath, proposedContent); - if (!graphValidation.ok) return { ok: false, error: graphValidation.error }; - - const appliedAt = new Date().toISOString(); - const archivedAbsolute = appliedPathFor(workspaceRoot, proposalId); - const archivedRecord = { ...record, proposalId, appliedAt, status: "applied" }; - fs.writeFileSync(archivedAbsolute, `${JSON.stringify(archivedRecord, null, 2)}\n`, "utf8"); - fs.writeFileSync(targetAbsolute, proposedContent, "utf8"); - fs.rmSync(proposalAbsolute); - +function resultFromArchive(workspaceRoot, archive, recovered = false) { + const validation = archive.validation ?? null; return { ok: true, status: "applied", - target: toPosixPath(targetPath), - proposalArchivedAs: workspaceRelative(workspaceRoot, archivedAbsolute), - appliedAt + target: toPosixPath(archive.targetPath), + proposalArchivedAs: workspaceRelative(workspaceRoot, appliedPathFor(workspaceRoot, archive.proposalId)), + appliedAt: archive.appliedAt, + recovered, + validation, + warnings: validation?.warnings ?? [], + graphProjectionStale: validation?.graphProjectionStale ?? false, + regenerateAfterApply: validation?.regenerateAfterApply ?? false, + followup: validation?.followup ?? null }; } +function recoverAppliedArchive(workspaceRoot, config, proposalId, archive, liveProposal = null) { + const bindingError = validateAppliedArchiveBinding(proposalId, archive, liveProposal?.record); + if (bindingError) return { ok: false, error: bindingError }; + const pathCheck = validatePathSafety(workspaceRoot, archive.targetPath, config); + if (!pathCheck.ok) return { ok: false, error: pathCheck.error }; + if (!fs.existsSync(pathCheck.absolute)) return { ok: false, error: "applied archive exists but target is missing" }; + try { + const content = readFileNoFollowSync(workspaceRoot, pathCheck.absolute); + if (recordSha256(content) !== archive.persistedContentSha256) { + return { ok: false, error: "applied archive target hash mismatch" }; + } + if (liveProposal) { + const refreshed = loadProposal(workspaceRoot, proposalId); + if (!refreshed.ok) return { ok: false, error: `could not revalidate live proposal before recovery: ${refreshed.error}` }; + const refreshedBindingError = validateAppliedArchiveBinding(proposalId, archive, refreshed.record); + if (refreshedBindingError) return { ok: false, error: refreshedBindingError }; + removeRegularFileNoFollowSync(workspaceRoot, refreshed.absolute); + } + return resultFromArchive(workspaceRoot, archive, true); + } catch (error) { + return { ok: false, error: `could not recover applied proposal: ${error.message}` }; + } +} + +const RESERVATION_OPERATION_FIELDS = new Set([ + "status", + "reservationId", + "reservedAt", + "appliedAt", + "persistedContentSha256" +]); + +function reservationProposalIdentity(record) { + if (!record || typeof record !== "object" || Array.isArray(record)) return null; + return Object.fromEntries( + Object.entries(record).filter(([key]) => !RESERVATION_OPERATION_FIELDS.has(key)) + ); +} + +function reservationMatches(reservation, proposal) { + return reservation?.status === "applying" + && typeof reservation.reservationId === "string" + && reservation.reservationId.trim() !== "" + && Number.isFinite(Date.parse(reservation.reservedAt)) + && canonicalJson(reservationProposalIdentity(reservation)) + === canonicalJson(reservationProposalIdentity(proposal)); +} + +function applyProposal(workspaceRoot, config, input, runtimeOptions = {}) { + const proposalId = input?.proposalId; + const lockOptions = runtimeOptions.lockOptions ?? {}; + const invalid = validateProposalId(proposalId); + if (invalid) return { ok: false, error: invalid }; + + const proposalAbsolute = proposalPathFor(workspaceRoot, proposalId); + const archivedAbsolute = appliedPathFor(workspaceRoot, proposalId); + if (!fs.existsSync(proposalAbsolute) && !fs.existsSync(archivedAbsolute)) { + return { ok: false, error: `proposal not found: ${proposalId}` }; + } + const proposalLockAbsolute = path.join(workspaceRoot, PROPOSALS_DIRNAME, `${proposalId}.lock`); + let proposalLock; + try { + proposalLock = acquireExclusiveLock(workspaceRoot, proposalLockAbsolute, lockOptions); + } catch (error) { + return { ok: false, error: error.message }; + } + + let targetLock; + function heartbeatLocks() { + try { + proposalLock?.heartbeat(); + targetLock?.heartbeat(); + return null; + } catch (error) { + return { ok: false, error: `lock ownership lost during apply: ${error.message}` }; + } + } + try { + const initialArchive = loadArchive(workspaceRoot, proposalId); + if (!initialArchive.ok) return initialArchive; + if (initialArchive.exists && initialArchive.record.status === "applied") { + let liveProposal = null; + if (fs.existsSync(proposalAbsolute)) { + const loaded = loadProposal(workspaceRoot, proposalId); + if (!loaded.ok) return loaded; + liveProposal = loaded; + } + const lockFailure = heartbeatLocks(); + if (lockFailure) return lockFailure; + return recoverAppliedArchive(workspaceRoot, config, proposalId, initialArchive.record, liveProposal); + } + + const loaded = loadProposal(workspaceRoot, proposalId); + if (!loaded.ok) return loaded; + const { record } = loaded; + const { targetPath, diff } = record; + if (typeof targetPath !== "string" || targetPath.trim() === "") return { ok: false, error: "proposal missing targetPath" }; + if (!diff || typeof diff !== "object") return { ok: false, error: "proposal missing diff" }; + const targetLockId = crypto.createHash("sha256").update(toPosixPath(targetPath)).digest("hex"); + const targetLockAbsolute = path.join(workspaceRoot, PROPOSALS_DIRNAME, `target-${targetLockId}.lock`); + try { + targetLock = acquireExclusiveLock(workspaceRoot, targetLockAbsolute, lockOptions); + } catch (error) { + return { ok: false, error: `target is already being modified: ${error.message}` }; + } + + const pathCheck = validatePathSafety(workspaceRoot, targetPath, config); + if (!pathCheck.ok) return { ok: false, error: pathCheck.error }; + if (!/^[0-9a-f]{64}$/i.test(String(record.proposedContentSha256 ?? ""))) { + return { ok: false, error: "proposal requires proposedContentSha256" }; + } + const targetAbsolute = pathCheck.absolute; + const targetExists = fs.existsSync(targetAbsolute); + let currentContent = ""; + if (targetExists) { + try { + currentContent = readFileNoFollowSync(workspaceRoot, targetAbsolute); + } catch (error) { + return { ok: false, error: error.message }; + } + } + const alreadyPersisted = targetExists && recordSha256(currentContent) === record.proposedContentSha256; + if (diff.kind === "create" && targetExists && !alreadyPersisted) return { ok: false, error: `create target already exists: ${targetPath}` }; + if (diff.kind !== "create" && !targetExists) return { ok: false, error: `target file does not exist: ${targetPath}` }; + + let proposedContent; + let recordValidation; + if (alreadyPersisted) { + proposedContent = currentContent; + recordValidation = validateAmfRecordTarget(targetPath, proposedContent, { + allowExistingRevision: true, + workspaceRoot + }); + if (!recordValidation.ok) return recordValidation; + } else { + if (isAmfRecordPath(targetPath) && targetExists + && (!Number.isInteger(record.expectedRevision) || !/^[0-9a-f]{64}$/i.test(String(record.expectedTargetSha256 ?? "")))) { + return { ok: false, error: "AMF revision proposal requires expectedRevision and expectedTargetSha256" }; + } + if (targetExists && record.expectedTargetSha256 !== null && record.expectedTargetSha256 !== undefined + && recordSha256(currentContent) !== record.expectedTargetSha256) { + return { ok: false, error: "target content does not match proposal base SHA-256 (drifted)" }; + } + const rendered = renderProposedContent(targetPath, diff, currentContent); + if (!rendered.ok) return { ok: false, error: rendered.error }; + proposedContent = rendered.content; + if (recordSha256(proposedContent) !== record.proposedContentSha256) { + return { ok: false, error: "proposed content SHA-256 does not match proposal artifact" }; + } + const graphValidation = validateGraphJsonl(workspaceRoot, targetPath, proposedContent); + if (!graphValidation.ok) return { ok: false, error: graphValidation.error }; + recordValidation = validateAmfRecordTarget(targetPath, proposedContent, targetExists + ? { + currentContent, + expectedRevision: record.expectedRevision, + expectedTargetSha256: record.expectedTargetSha256, + workspaceRoot + } + : { workspaceRoot }); + if (!recordValidation.ok) return recordValidation; + } + + const initialReservationMatches = initialArchive.exists && reservationMatches(initialArchive.record, record); + const reservationId = initialReservationMatches ? initialArchive.record.reservationId : crypto.randomUUID(); + if (initialArchive.exists && !initialReservationMatches) { + return { ok: false, error: "applied archive path is reserved by a different or malformed operation" }; + } + if (!initialArchive.exists) { + const lockFailure = heartbeatLocks(); + if (lockFailure) return lockFailure; + const reservation = { + ...record, + proposalId, + status: "applying", + reservationId, + reservedAt: new Date().toISOString() + }; + try { + atomicWriteFileSync(workspaceRoot, archivedAbsolute, `${JSON.stringify(reservation, null, 2)}\n`, { + exclusive: true, + mode: 0o600 + }); + } catch (error) { + return { ok: false, error: `could not reserve applied archive: ${error.message}` }; + } + } + + if (!alreadyPersisted) { + const lockFailure = heartbeatLocks(); + if (lockFailure) return lockFailure; + try { + atomicWriteFileSync(workspaceRoot, targetAbsolute, proposedContent, { + exclusive: diff.kind === "create", + mode: isAmfRecordPath(targetPath) ? 0o600 : undefined + }); + } catch (error) { + return { ok: false, error: `could not persist target atomically: ${error.message}` }; + } + } + + const reservationAfterTarget = loadArchive(workspaceRoot, proposalId); + if (!reservationAfterTarget.ok) return reservationAfterTarget; + if (!reservationAfterTarget.exists + || !reservationMatches(reservationAfterTarget.record, record) + || reservationAfterTarget.record.reservationId !== reservationId) { + return { ok: false, error: "target persisted but applied archive reservation changed; retry requires operator review", targetPersisted: true }; + } + + const appliedAt = new Date().toISOString(); + const validationSummary = summarizeAmfValidation(recordValidation.validation); + const archivedRecord = { + ...record, + proposalId, + appliedAt, + status: "applied", + reservationId, + persistedContentSha256: recordSha256(proposedContent), + validation: validationSummary + }; + const lockFailure = heartbeatLocks(); + if (lockFailure) return { ...lockFailure, targetPersisted: true }; + try { + atomicWriteFileSync(workspaceRoot, archivedAbsolute, `${JSON.stringify(archivedRecord, null, 2)}\n`, { mode: 0o600 }); + removeRegularFileNoFollowSync(workspaceRoot, proposalAbsolute); + } catch (error) { + return { + ok: false, + error: `target persisted with recoverable archive reservation: ${error.message}`, + targetPersisted: true + }; + } + return resultFromArchive(workspaceRoot, archivedRecord); + } finally { + try { + targetLock?.release(); + } catch {} + try { + proposalLock.release(); + } catch {} + } +} + export { applyProposal }; diff --git a/tools/lib/memory-proposals.mjs b/tools/lib/memory-proposals.mjs index fe349c1..8b27e26 100644 --- a/tools/lib/memory-proposals.mjs +++ b/tools/lib/memory-proposals.mjs @@ -3,6 +3,18 @@ import fs from "node:fs"; import path from "node:path"; import { validateGraph } from "../memory-graph.mjs"; +import { + isAmfRecordPath, + recordPathFor, + recordSha256, + validateMemoryRecord, + validateMemoryRecordTransition +} from "./amf-memory-record.mjs"; +import { + assertNoSymlinkPath, + atomicWriteFileSync, + readFileNoFollowSync +} from "./secure-fs.mjs"; import { isPathProtected, resolveInsideWorkspace, @@ -37,14 +49,13 @@ function validatePathSafety(workspaceRoot, relativePath, config) { } catch (error) { return { ok: false, error: error.message }; } - if (fs.existsSync(absolute)) { - const stats = fs.lstatSync(absolute); - if (stats.isSymbolicLink()) { - return { ok: false, error: "target path is a symlink" }; - } - if (!stats.isFile()) { + try { + assertNoSymlinkPath(workspaceRoot, absolute); + if (fs.existsSync(absolute) && !fs.lstatSync(absolute).isFile()) { return { ok: false, error: "target path is not a file" }; } + } catch (error) { + return { ok: false, error: error.message }; } const protectedPaths = Array.isArray(config?.protectedPaths) ? config.protectedPaths : []; if (isPathProtected(workspaceRoot, relativePath, protectedPaths)) { @@ -226,6 +237,54 @@ function validateGraphJsonl(workspaceRoot, targetRelative, proposedContent) { return { ok: true }; } +function validateAmfRecordTarget(targetRelative, proposedContent, options = {}) { + if (!isAmfRecordPath(targetRelative)) return { ok: true, validation: null }; + const validation = validateMemoryRecord(proposedContent, { + expectedPath: toPosixPath(targetRelative), + ...(options.workspaceRoot ? { workspaceRoot: options.workspaceRoot } : {}) + }); + if (!validation.ok) { + return { ok: false, error: `proposed AMF record fails validation: ${validation.errors.join("; ")}`, validation }; + } + if (options.currentContent !== undefined) { + const transition = validateMemoryRecordTransition(options.currentContent, proposedContent, { + expectedPath: toPosixPath(targetRelative), + workspaceRoot: options.workspaceRoot, + expectedRevision: options.expectedRevision, + expectedTargetSha256: options.expectedTargetSha256 + }); + if (!transition.ok) { + return { + ok: false, + error: `proposed AMF revision fails transition validation: ${transition.errors.join("; ")}`, + validation, + transition + }; + } + return { ok: true, validation, transition }; + } + if (!options.allowExistingRevision && validation.metadata.revision !== 1) { + return { ok: false, error: "new AMF records must start at revision 1", validation }; + } + return { ok: true, validation }; +} + +function summarizeAmfValidation(validation) { + if (!validation) return null; + const warnings = Array.isArray(validation.warnings) ? [...validation.warnings] : []; + const graphProjectionStale = warnings.some((warning) => /derived graph projection is stale/i.test(String(warning))); + return { + schema: validation.metadata.schema, + projection: validation.projection, + warnings, + graphProjectionStale, + regenerateAfterApply: graphProjectionStale, + followup: graphProjectionStale + ? { action: "graph_reindex", command: "npm run memory:graph:index", required: true } + : null + }; +} + function parseJsonlText(text, label) { const rows = []; const lines = text.split(/\r?\n/); @@ -258,11 +317,26 @@ function proposeEdit(workspaceRoot, config, input) { let currentContent = ""; if (fs.existsSync(pathCheck.absolute)) { - currentContent = fs.readFileSync(pathCheck.absolute, "utf8"); + try { + currentContent = readFileNoFollowSync(workspaceRoot, pathCheck.absolute); + } catch (error) { + return { ok: false, error: error.message }; + } } let proposedContent; - if (diff.kind === "replace") { + if (diff.kind === "create") { + if (!isAmfRecordPath(relativePath)) { + return { ok: false, error: "create proposals are restricted to memory/amf/records/.md" }; + } + if (fs.existsSync(pathCheck.absolute)) { + return { ok: false, error: `create target already exists: ${toPosixPath(relativePath)}` }; + } + if (typeof diff.content !== "string" || diff.content.trim() === "") { + return { ok: false, error: "create proposal requires content" }; + } + proposedContent = diff.content; + } else if (diff.kind === "replace") { const applied = applyReplace(currentContent, diff); if (!applied.ok) return { ok: false, error: applied.error }; proposedContent = applied.next; @@ -285,12 +359,16 @@ function proposeEdit(workspaceRoot, config, input) { const graphValidation = validateGraphJsonl(workspaceRoot, relativePath, proposedContent); if (!graphValidation.ok) return { ok: false, error: graphValidation.error }; + const recordValidation = validateAmfRecordTarget(relativePath, proposedContent, fs.existsSync(pathCheck.absolute) + ? { currentContent, workspaceRoot } + : { workspaceRoot }); + if (!recordValidation.ok) return recordValidation; const proposalsDir = path.join(workspaceRoot, PROPOSALS_DIRNAME); - fs.mkdirSync(proposalsDir, { recursive: true }); const proposalId = makeProposalId(); const proposalRelative = toPosixPath(path.join(PROPOSALS_DIRNAME, `${proposalId}.json`)); const proposalAbsolute = path.join(workspaceRoot, proposalRelative); + const amfMemory = summarizeAmfValidation(recordValidation.validation); const record = { proposalId, createdAt: new Date().toISOString(), @@ -299,16 +377,63 @@ function proposeEdit(workspaceRoot, config, input) { diff, rationale, findingIds: Array.isArray(findingIds) ? findingIds : [], - validation: { ok: true }, + expectedRevision: recordValidation.transition?.current.metadata.revision ?? null, + expectedTargetSha256: fs.existsSync(pathCheck.absolute) ? recordSha256(currentContent) : null, + proposedContentSha256: recordSha256(proposedContent), + validation: { + ok: true, + amfMemory, + warnings: amfMemory?.warnings ?? [], + graphProjectionStale: amfMemory?.graphProjectionStale ?? false, + regenerateAfterApply: amfMemory?.regenerateAfterApply ?? false, + followup: amfMemory?.followup ?? null + }, proposedContentLength: proposedContent.length }; - fs.writeFileSync(proposalAbsolute, `${JSON.stringify(record, null, 2)}\n`, "utf8"); + try { + atomicWriteFileSync(workspaceRoot, proposalAbsolute, `${JSON.stringify(record, null, 2)}\n`, { + exclusive: true, + mode: 0o600 + }); + } catch (error) { + return { ok: false, error: `could not record proposal: ${error.message}` }; + } return { ok: true, proposalId, proposalPath: workspaceRelative(workspaceRoot, proposalAbsolute), status: "recorded", - validation: { ok: true } + validation: record.validation + }; +} + +function proposeMemoryRecord(workspaceRoot, config, input) { + const { content, rationale, findingIds, source } = input ?? {}; + const validation = validateMemoryRecord(content, { workspaceRoot }); + if (!validation.ok) { + return { + ok: false, + error: `AMF record fails validation: ${validation.errors.join("; ")}`, + validation + }; + } + const targetPath = recordPathFor(validation.metadata); + const result = proposeEdit(workspaceRoot, config, { + path: targetPath, + rationale, + findingIds, + source: source ?? "pam-memory-record", + diff: { kind: "create", content } + }); + if (!result.ok) return result; + return { + ...result, + targetPath, + projection: validation.projection, + warnings: result.validation?.warnings ?? [], + graphProjectionStale: result.validation?.graphProjectionStale ?? false, + regenerateAfterApply: result.validation?.regenerateAfterApply ?? false, + followup: result.validation?.followup ?? null }; } @@ -319,7 +444,10 @@ export { applyUnifiedDiff, diffByteSize, parseUnifiedDiff, + proposeMemoryRecord, proposeEdit, + summarizeAmfValidation, + validateAmfRecordTarget, validateGraphJsonl, validatePathSafety }; diff --git a/tools/lib/secure-fs.mjs b/tools/lib/secure-fs.mjs new file mode 100644 index 0000000..a84e8b6 --- /dev/null +++ b/tools/lib/secure-fs.mjs @@ -0,0 +1,354 @@ +import crypto from "node:crypto"; +import fs from "node:fs"; +import os from "node:os"; +import path from "node:path"; + +const DEFAULT_LOCK_STALE_MS = 5 * 60 * 1000; +const DEFAULT_LOCK_HEARTBEAT_MS = 30 * 1000; + +function isInside(root, target) { + const relative = path.relative(root, target); + return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative)); +} + +function assertNoSymlinkPath(workspaceRoot, absolutePath, options = {}) { + const root = path.resolve(workspaceRoot); + const target = path.resolve(absolutePath); + if (!isInside(root, target)) throw new Error(`path escapes workspace: ${absolutePath}`); + const relative = path.relative(root, target); + let cursor = root; + for (const segment of relative.split(path.sep).filter(Boolean)) { + cursor = path.join(cursor, segment); + let stats; + try { + stats = fs.lstatSync(cursor); + } catch (error) { + if (error.code === "ENOENT" && options.allowMissing !== false) break; + throw error; + } + if (stats.isSymbolicLink()) throw new Error(`path contains symlink: ${path.relative(root, cursor)}`); + } + return target; +} + +function readFileNoFollowSync(workspaceRoot, absolutePath, encoding = "utf8") { + assertNoSymlinkPath(workspaceRoot, absolutePath, { allowMissing: false }); + const flags = fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0); + const fd = fs.openSync(absolutePath, flags); + try { + const stats = fs.fstatSync(fd); + if (!stats.isFile()) throw new Error(`path is not a regular file: ${absolutePath}`); + return fs.readFileSync(fd, encoding); + } finally { + fs.closeSync(fd); + } +} + +function atomicWriteFileSync(workspaceRoot, absolutePath, content, options = {}) { + const target = assertNoSymlinkPath(workspaceRoot, absolutePath); + const parent = path.dirname(target); + assertNoSymlinkPath(workspaceRoot, parent); + fs.mkdirSync(parent, { recursive: true, mode: 0o700 }); + assertNoSymlinkPath(workspaceRoot, parent, { allowMissing: false }); + + const realRoot = fs.realpathSync(workspaceRoot); + const realParent = fs.realpathSync(parent); + if (!isInside(realRoot, realParent)) throw new Error(`resolved parent escapes workspace: ${absolutePath}`); + const realTarget = path.join(realParent, path.basename(target)); + if (!options.exclusive && fs.existsSync(realTarget)) { + assertNoSymlinkPath(realRoot, realTarget, { allowMissing: false }); + const existing = fs.lstatSync(realTarget); + if (!existing.isFile()) throw new Error(`target is not a regular file: ${absolutePath}`); + } + + const temporary = path.join(realParent, `.${path.basename(target)}.${process.pid}.${crypto.randomBytes(8).toString("hex")}.tmp`); + const flags = fs.constants.O_WRONLY + | fs.constants.O_CREAT + | fs.constants.O_EXCL + | (fs.constants.O_NOFOLLOW ?? 0); + const mode = options.mode ?? (!options.exclusive && fs.existsSync(realTarget) ? fs.statSync(realTarget).mode & 0o777 : 0o600); + let fd; + try { + fd = fs.openSync(temporary, flags, mode); + fs.writeFileSync(fd, content, { encoding: options.encoding ?? "utf8" }); + fs.fsyncSync(fd); + fs.closeSync(fd); + fd = undefined; + if (options.exclusive) { + try { + fs.linkSync(temporary, realTarget); + } catch (error) { + if (error.code === "EEXIST") throw new Error(`target already exists: ${absolutePath}`); + throw error; + } + fs.unlinkSync(temporary); + } else { + if (fs.existsSync(realTarget) && fs.lstatSync(realTarget).isSymbolicLink()) { + throw new Error(`target path is a symlink: ${absolutePath}`); + } + fs.renameSync(temporary, realTarget); + } + const dirFd = fs.openSync(realParent, fs.constants.O_RDONLY); + try { + fs.fsyncSync(dirFd); + } finally { + fs.closeSync(dirFd); + } + } catch (error) { + if (fd !== undefined) fs.closeSync(fd); + try { + fs.rmSync(temporary); + } catch {} + throw error; + } +} + +function lockOwnerMatches(actual, expected) { + return actual?.version === 1 + && actual.pid === expected.pid + && actual.host === expected.host + && actual.nonce === expected.nonce; +} + +function readLockSnapshot(workspaceRoot, absolutePath) { + assertNoSymlinkPath(workspaceRoot, absolutePath, { allowMissing: false }); + const flags = fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0); + const fd = fs.openSync(absolutePath, flags); + try { + const stats = fs.fstatSync(fd); + if (!stats.isFile()) throw new Error(`lock path is not a regular file: ${absolutePath}`); + let owner; + try { + owner = JSON.parse(fs.readFileSync(fd, "utf8")); + } catch (error) { + throw new Error(`lock owner is not valid JSON: ${error.message}`); + } + if (owner?.version !== 1 + || !Number.isInteger(owner?.pid) || owner.pid < 1 + || typeof owner?.host !== "string" || owner.host === "" + || typeof owner?.nonce !== "string" || !/^[a-f0-9]{32,128}$/i.test(owner.nonce) + || !Number.isFinite(Date.parse(owner?.acquiredAt)) + || !Number.isFinite(Date.parse(owner?.heartbeatAt))) { + throw new Error("lock owner metadata is malformed"); + } + return { owner, stats }; + } finally { + fs.closeSync(fd); + } +} + +function sameInode(left, right) { + return left.dev === right.dev && left.ino === right.ino; +} + +function localProcessState(owner, host) { + if (owner.host !== host) return "unknown"; + try { + process.kill(owner.pid, 0); + return "alive"; + } catch (error) { + if (error?.code === "ESRCH") return "dead"; + return "unknown"; + } +} + +function lockIsStale(snapshot, nowMs, staleMs) { + const recordedHeartbeat = Date.parse(snapshot.owner.heartbeatAt); + const lastHeartbeat = Math.max(recordedHeartbeat, snapshot.stats.mtimeMs); + return nowMs - lastHeartbeat >= staleMs; +} + +function writeLockOwner(fd, owner) { + fs.writeFileSync(fd, `${JSON.stringify(owner)}\n`, "utf8"); + fs.fsyncSync(fd); +} + +function cleanupRegularFile(absolutePath) { + try { + const stats = fs.lstatSync(absolutePath); + if (stats.isFile()) fs.rmSync(absolutePath); + } catch (error) { + if (error?.code !== "ENOENT") throw error; + } +} + +function restoreQuarantinedLock(quarantinePath, absolutePath) { + try { + fs.linkSync(quarantinePath, absolutePath); + } catch (error) { + if (error?.code !== "EEXIST") throw error; + } + if (fs.existsSync(absolutePath)) { + cleanupRegularFile(quarantinePath); + } +} + +function acquireExclusiveLock(workspaceRoot, absolutePath, options = {}) { + assertNoSymlinkPath(workspaceRoot, path.dirname(absolutePath), { allowMissing: false }); + const staleMs = Number.isFinite(options.staleMs) && options.staleMs >= 50 + ? options.staleMs + : DEFAULT_LOCK_STALE_MS; + const heartbeatMs = options.heartbeatMs === 0 + ? 0 + : (Number.isFinite(options.heartbeatMs) && options.heartbeatMs >= 10 + ? Math.min(options.heartbeatMs, Math.max(10, Math.floor(staleMs / 3))) + : Math.min(DEFAULT_LOCK_HEARTBEAT_MS, Math.max(10, Math.floor(staleMs / 3)))); + const host = String(options.host || process.env.PAM_LOCK_HOST_ID || os.hostname()); + const now = typeof options.now === "function" ? options.now : () => new Date(); + const acquiredAt = now().toISOString(); + const owner = { + version: 1, + pid: process.pid, + host, + nonce: crypto.randomBytes(24).toString("hex"), + acquiredAt, + heartbeatAt: acquiredAt + }; + const flags = fs.constants.O_WRONLY + | fs.constants.O_CREAT + | fs.constants.O_EXCL + | (fs.constants.O_NOFOLLOW ?? 0); + let fd; + let acquiredByTakeover = false; + try { + fd = fs.openSync(absolutePath, flags, 0o600); + try { + writeLockOwner(fd, owner); + } catch (writeError) { + fs.closeSync(fd); + fd = undefined; + cleanupRegularFile(absolutePath); + throw writeError; + } + } catch (error) { + if (error.code !== "EEXIST") throw error; + + let observed; + try { + observed = readLockSnapshot(workspaceRoot, absolutePath); + } catch (snapshotError) { + throw new Error(`proposal is already being applied; existing lock is unverifiable: ${snapshotError.message}`); + } + const state = localProcessState(observed.owner, host); + if (!lockIsStale(observed, now().getTime(), staleMs) || state !== "dead") { + throw new Error("proposal is already being applied"); + } + + const candidatePath = `${absolutePath}.${owner.nonce}.candidate`; + const quarantinePath = `${absolutePath}.${owner.nonce}.stale`; + let candidateFd; + try { + candidateFd = fs.openSync(candidatePath, flags, 0o600); + writeLockOwner(candidateFd, owner); + fs.renameSync(absolutePath, quarantinePath); + const quarantined = readLockSnapshot(workspaceRoot, quarantinePath); + if (!sameInode(observed.stats, quarantined.stats) + || !lockOwnerMatches(quarantined.owner, observed.owner)) { + restoreQuarantinedLock(quarantinePath, absolutePath); + throw new Error("proposal is already being applied; lock changed during stale takeover"); + } + try { + fs.linkSync(candidatePath, absolutePath); + } catch (linkError) { + if (linkError?.code === "EEXIST") { + cleanupRegularFile(quarantinePath); + throw new Error("proposal is already being applied"); + } + restoreQuarantinedLock(quarantinePath, absolutePath); + throw linkError; + } + try { + cleanupRegularFile(candidatePath); + } catch (candidateError) { + cleanupRegularFile(absolutePath); + restoreQuarantinedLock(quarantinePath, absolutePath); + throw candidateError; + } + try { + cleanupRegularFile(quarantinePath); + } catch {} + fd = candidateFd; + candidateFd = undefined; + acquiredByTakeover = true; + } catch (takeoverError) { + if (candidateFd !== undefined) fs.closeSync(candidateFd); + cleanupRegularFile(candidatePath); + if (fs.existsSync(quarantinePath) && !fs.existsSync(absolutePath)) { + try { + restoreQuarantinedLock(quarantinePath, absolutePath); + } catch {} + } + throw takeoverError; + } + } + + const ownedStats = fs.fstatSync(fd); + let released = false; + let heartbeatTimer = null; + + function verifyOwnership() { + let current; + try { + current = readLockSnapshot(workspaceRoot, absolutePath); + } catch (error) { + throw new Error(`lock ownership cannot be verified: ${error.message}`); + } + if (!sameInode(ownedStats, current.stats) || !lockOwnerMatches(current.owner, owner)) { + throw new Error("lock ownership changed; refusing owner operation"); + } + } + + function heartbeat() { + if (released) return false; + verifyOwnership(); + const heartbeatAt = now(); + fs.futimesSync(fd, heartbeatAt, heartbeatAt); + return true; + } + + if (heartbeatMs > 0) { + heartbeatTimer = setInterval(() => { + try { + heartbeat(); + } catch { + clearInterval(heartbeatTimer); + heartbeatTimer = null; + } + }, heartbeatMs); + heartbeatTimer.unref?.(); + } + + return { + owner: { ...owner }, + acquiredByTakeover, + heartbeat, + release() { + if (released) return false; + if (heartbeatTimer) clearInterval(heartbeatTimer); + heartbeatTimer = null; + try { + verifyOwnership(); + fs.rmSync(absolutePath); + } finally { + released = true; + fs.closeSync(fd); + } + return true; + } + }; +} + +function removeRegularFileNoFollowSync(workspaceRoot, absolutePath) { + assertNoSymlinkPath(workspaceRoot, absolutePath, { allowMissing: false }); + const stats = fs.lstatSync(absolutePath); + if (!stats.isFile()) throw new Error(`path is not a regular file: ${absolutePath}`); + fs.rmSync(absolutePath); +} + +export { + acquireExclusiveLock, + assertNoSymlinkPath, + atomicWriteFileSync, + readFileNoFollowSync, + removeRegularFileNoFollowSync +}; diff --git a/tools/test-amf-memory-record.mjs b/tools/test-amf-memory-record.mjs new file mode 100644 index 0000000..1cb1123 --- /dev/null +++ b/tools/test-amf-memory-record.mjs @@ -0,0 +1,644 @@ +import assert from "node:assert/strict"; +import crypto from "node:crypto"; +import fs from "node:fs"; +import os from "node:os"; +import path from "node:path"; +import test from "node:test"; + +import { + aadSha256For, + recordSha256, + validateMemoryRecord, + validateMemoryRecordTransition +} from "./lib/amf-memory-record.mjs"; +import { applyProposal } from "./lib/memory-apply-proposal.mjs"; +import { proposeEdit, proposeMemoryRecord } from "./lib/memory-proposals.mjs"; +import { atomicWriteFileSync } from "./lib/secure-fs.mjs"; + +const IDS = { + memory: "mem_11111111-1111-4111-8111-111111111111", + replacement: "mem_99999999-9999-4999-8999-999999999999", + agent: "agent:22222222-2222-4222-8222-222222222222", + person: "person:33333333-3333-4333-8333-333333333333", + relationship: "relationship:44444444-4444-4444-8444-444444444444" +}; + +function baseRecord(overrides = {}) { + return { + schema: "amf-memory/v1", + id: IDS.memory, + revision: 1, + claimType: "decision", + scope: { type: "shared", id: "shared:global" }, + visibility: "shared", + subjects: [{ identityId: IDS.agent, role: "owner" }], + claim: { encoding: "plain", text: "A reusable source-backed decision." }, + lifecycle: { + status: "active", + validFrom: "2026-07-11T10:00:00Z", + validTo: null, + supersedes: [], + revokedAt: null, + revocationReason: null + }, + provenance: [{ + sourceType: "test-session", + sourceId: "session-stable-0001", + eventId: "event-stable-0001", + contentSha256: "a".repeat(64), + capturedAt: "2026-07-11T10:00:00Z" + }], + createdAt: "2026-07-11T10:00:00Z", + updatedAt: "2026-07-11T10:00:00Z", + ...overrides + }; +} + +function sealedClaimFor(metadata, overrides = {}) { + const claim = { + encoding: "sealed", + alg: "AES-256-GCM", + kekId: "kek:version-0001", + keyRef: "key:external-record-key-0001", + iv: Buffer.alloc(12, 1).toString("base64"), + ciphertext: Buffer.from("ciphertext").toString("base64"), + tag: Buffer.alloc(16, 2).toString("base64"), + aadSha256: "", + ...overrides + }; + const withClaim = { ...metadata, claim }; + claim.aadSha256 = overrides.aadSha256 ?? aadSha256For(withClaim); + return claim; +} + +function recordContent(metadata, body = "") { + const lines = Object.entries(metadata).map(([key, value]) => { + const rendered = value !== null && typeof value === "object" ? JSON.stringify(value) : String(value); + return `${key}: ${rendered}`; + }); + return `---\n${lines.join("\n")}\n---\n${body}`; +} + +function makeWorkspace() { + const root = fs.mkdtempSync(path.join(os.tmpdir(), "pam-amf-record-")); + fs.mkdirSync(path.join(root, "memory", "graph"), { recursive: true }); + fs.writeFileSync(path.join(root, "memory", "graph", "nodes.jsonl"), "", "utf8"); + fs.writeFileSync(path.join(root, "memory", "graph", "edges.jsonl"), "", "utf8"); + fs.writeFileSync(path.join(root, "memory", "graph", "aliases.jsonl"), "", "utf8"); + return root; +} + +function writeStaleProjection(root) { + fs.writeFileSync(path.join(root, "memory", "graph", "nodes.jsonl"), JSON.stringify({ + id: IDS.memory, + k: "memory-record", + n: "Stale derived record", + d: "Stale projection.", + st: "confirmed", + c: "high", + u: "2026-07-10", + src: `memory/amf/records/${IDS.memory}.md` + }) + "\n", "utf8"); +} + +const config = { protectedPaths: ["memory/agent-memory", "memory/sources"] }; + +test("validates the exact contract-v1 shape, canonical path, and graph projection", () => { + const validation = validateMemoryRecord(recordContent(baseRecord(), "Non-claim commentary.\n")); + assert.equal(validation.ok, true, validation.errors.join("\n")); + assert.equal(validation.expectedPath, `memory/amf/records/${IDS.memory}.md`); + assert.equal(validation.projection.k, "memory-record"); + assert.match(validation.projection.d, /source-backed decision/); + assert.equal(JSON.stringify(validation.projection).includes(IDS.agent), false); + + const legacy = validateMemoryRecord(recordContent({ ...baseRecord(), scope_kind: "shared" })); + assert.equal(legacy.ok, false); + assert.match(legacy.errors.join("\n"), /unknown frontmatter key: scope_kind/); +}); + +test("seals person and relationship scopes, claim types, and related subjects", () => { + for (const overrides of [ + { scope: { type: "person", id: IDS.person }, visibility: "private" }, + { scope: { type: "relationship", id: IDS.relationship }, visibility: "restricted" }, + { claimType: "relationship" }, + { visibility: "restricted" }, + { subjects: [{ identityId: IDS.person, role: "subject" }], visibility: "private" } + ]) { + const validation = validateMemoryRecord(recordContent(baseRecord(overrides))); + assert.equal(validation.ok, false); + assert.match(validation.errors.join("\n"), /require a sealed claim/); + } + + const metadata = baseRecord({ + claimType: "fact", + scope: { type: "person", id: IDS.person }, + visibility: "confidential", + subjects: [{ identityId: IDS.person, role: "subject" }] + }); + metadata.claim = sealedClaimFor(metadata); + const sealed = validateMemoryRecord(recordContent(metadata)); + assert.equal(sealed.ok, true, sealed.errors.join("\n")); + assert.equal(sealed.projection.n, "Protected memory record"); + assert.equal(JSON.stringify(sealed.projection).includes(IDS.person), false); + assert.equal(JSON.stringify(sealed.projection).includes(metadata.claim.ciphertext), false); +}); + +test("validates keyRef, AES-GCM sizes, non-empty ciphertext, and canonical AAD hash", () => { + const metadata = baseRecord({ + scope: { type: "person", id: IDS.person }, + visibility: "confidential", + subjects: [{ identityId: IDS.person, role: "subject" }] + }); + metadata.claim = sealedClaimFor(metadata, { + keyRef: "not-a-key-ref", + iv: Buffer.alloc(11).toString("base64"), + ciphertext: "=", + tag: Buffer.alloc(15).toString("base64"), + aadSha256: "b".repeat(64) + }); + const validation = validateMemoryRecord(recordContent(metadata)); + assert.equal(validation.ok, false); + const errors = validation.errors.join("\n"); + assert.match(errors, /keyRef/); + assert.match(errors, /12 bytes/); + assert.match(errors, /ciphertext/); + assert.match(errors, /16 bytes/); + assert.match(errors, /canonical AAD/); +}); + +test("canonical AAD binds algorithm and external key identifiers", () => { + const metadata = baseRecord({ + scope: { type: "person", id: IDS.person }, + visibility: "confidential", + subjects: [{ identityId: IDS.person, role: "subject" }] + }); + metadata.claim = sealedClaimFor(metadata); + const valid = validateMemoryRecord(recordContent(metadata)); + assert.equal(valid.ok, true, valid.errors.join("\n")); + for (const mutation of [ + { alg: "AES-256-GCM-CHANGED" }, + { kekId: "kek:version-0002" }, + { keyRef: "key:external-record-key-0002" } + ]) { + const changed = { ...metadata, claim: { ...metadata.claim, ...mutation } }; + const rejected = validateMemoryRecord(recordContent(changed)); + assert.equal(rejected.ok, false); + assert.match(rejected.errors.join("\n"), /canonical AAD|alg/); + } +}); + +test("requires real RFC 3339 UTC timestamps", () => { + for (const invalid of ["2026-07-11T10:00:00+02:00", "2026-02-30T10:00:00Z", "2026-07-11 10:00:00Z"] ) { + const metadata = baseRecord({ updatedAt: invalid }); + const validation = validateMemoryRecord(recordContent(metadata)); + assert.equal(validation.ok, false); + assert.match(validation.errors.join("\n"), /updatedAt must be RFC 3339 UTC/); + } +}); + +test("provenance is chronological and cannot be captured after updatedAt", () => { + const future = baseRecord({ + provenance: [{ ...baseRecord().provenance[0], capturedAt: "2026-07-11T11:00:00Z" }] + }); + const futureValidation = validateMemoryRecord(recordContent(future)); + assert.equal(futureValidation.ok, false); + assert.match(futureValidation.errors.join("\n"), /must not be later than updatedAt/); + + const unordered = baseRecord({ + updatedAt: "2026-07-11T12:00:00Z", + revision: 2, + provenance: [ + { ...baseRecord().provenance[0], capturedAt: "2026-07-11T11:00:00Z" }, + { ...baseRecord().provenance[0], eventId: "event-stable-0002", capturedAt: "2026-07-11T10:30:00Z" } + ] + }); + const unorderedValidation = validateMemoryRecord(recordContent(unordered)); + assert.equal(unorderedValidation.ok, false); + assert.match(unorderedValidation.errors.join("\n"), /ordered by capturedAt ascending/); +}); + +test("enforces revision, base hash, immutable claim, append-only provenance, and lifecycle transitions", () => { + const current = recordContent(baseRecord(), "Commentary.\n"); + const nextMetadata = baseRecord({ + revision: 2, + updatedAt: "2026-07-11T11:00:00Z", + visibility: "shared", + provenance: [ + ...baseRecord().provenance, + { + sourceType: "operator-decision", + sourceId: "decision-stable-0002", + eventId: "event-stable-0002", + contentSha256: "b".repeat(64), + capturedAt: "2026-07-11T11:00:00Z" + } + ], + lifecycle: { ...baseRecord().lifecycle, status: "superseded" } + }); + const proposed = recordContent(nextMetadata, "Commentary.\n"); + const valid = validateMemoryRecordTransition(current, proposed, { + expectedPath: `memory/amf/records/${IDS.memory}.md`, + expectedRevision: 1, + expectedTargetSha256: recordSha256(current) + }); + assert.equal(valid.ok, true, valid.errors.join("\n")); + + const invalid = recordContent({ + ...nextMetadata, + revision: 3, + claim: { encoding: "plain", text: "Silently rewritten claim." }, + provenance: nextMetadata.provenance.slice(1), + lifecycle: { ...nextMetadata.lifecycle, status: "active" } + }); + const rejected = validateMemoryRecordTransition(current, invalid, { + expectedRevision: 1, + expectedTargetSha256: "f".repeat(64) + }); + assert.equal(rejected.ok, false); + const errors = rejected.errors.join("\n"); + assert.match(errors, /revision must increment exactly/); + assert.match(errors, /claim is immutable/); + assert.match(errors, /provenance is append-only/); + assert.match(errors, /base hash/); +}); + +test("sealed revisions refresh canonical AAD and reject IV reuse or downgrade", () => { + const currentMetadata = baseRecord({ + scope: { type: "person", id: IDS.person }, + visibility: "confidential", + subjects: [{ identityId: IDS.person, role: "subject" }] + }); + currentMetadata.claim = sealedClaimFor(currentMetadata); + const current = recordContent(currentMetadata); + + const nextMetadata = { + ...currentMetadata, + revision: 2, + updatedAt: "2026-07-11T11:00:00Z", + provenance: [ + ...currentMetadata.provenance, + { + sourceType: "operator-decision", + sourceId: "decision-stable-0002", + eventId: "event-stable-0002", + contentSha256: "b".repeat(64), + capturedAt: "2026-07-11T11:00:00Z" + } + ] + }; + nextMetadata.claim = sealedClaimFor(nextMetadata, { iv: Buffer.alloc(12, 3).toString("base64") }); + const next = recordContent(nextMetadata); + const valid = validateMemoryRecordTransition(current, next, { + expectedRevision: 1, + expectedTargetSha256: recordSha256(current) + }); + assert.equal(valid.ok, true, valid.errors.join("\n")); + + const reusedMetadata = { ...nextMetadata, claim: sealedClaimFor(nextMetadata, { iv: currentMetadata.claim.iv }) }; + const reused = validateMemoryRecordTransition(current, recordContent(reusedMetadata)); + assert.equal(reused.ok, false); + assert.match(reused.errors.join("\n"), /new IV/); +}); + +test("proposes and atomically applies a canonical AMF record", () => { + const root = makeWorkspace(); + const content = recordContent(baseRecord(), "Reviewed commentary.\n"); + const proposed = proposeMemoryRecord(root, config, { content, rationale: "Add reviewed record." }); + assert.equal(proposed.ok, true, proposed.error); + assert.equal(proposed.targetPath, `memory/amf/records/${IDS.memory}.md`); + assert.equal(fs.existsSync(path.join(root, proposed.targetPath)), false); + const applied = applyProposal(root, config, { proposalId: proposed.proposalId }); + assert.equal(applied.ok, true, applied.error); + assert.equal(fs.readFileSync(path.join(root, proposed.targetPath), "utf8"), content); + assert.equal(fs.statSync(path.join(root, proposed.targetPath)).mode & 0o777, 0o600); + assert.equal(applied.validation.schema, "amf-memory/v1"); +}); + +test("resolves every supersedes target through the workspace", () => { + const root = makeWorkspace(); + const previous = recordContent(baseRecord()); + const previousPath = `memory/amf/records/${IDS.memory}.md`; + fs.mkdirSync(path.dirname(path.join(root, previousPath)), { recursive: true }); + fs.writeFileSync(path.join(root, previousPath), previous, "utf8"); + + const replacementMetadata = baseRecord({ + id: IDS.replacement, + claim: { encoding: "plain", text: "Corrected source-backed decision." }, + lifecycle: { ...baseRecord().lifecycle, supersedes: [IDS.memory] }, + createdAt: "2026-07-11T12:00:00Z", + updatedAt: "2026-07-11T12:00:00Z" + }); + const valid = proposeMemoryRecord(root, config, { + content: recordContent(replacementMetadata), + rationale: "Superseding correction." + }); + assert.equal(valid.ok, true, valid.error); + + const missingMetadata = { + ...replacementMetadata, + lifecycle: { ...replacementMetadata.lifecycle, supersedes: ["mem_88888888-8888-4888-8888-888888888888"] } + }; + const missing = proposeMemoryRecord(root, config, { + content: recordContent(missingMetadata), + rationale: "Must resolve target." + }); + assert.equal(missing.ok, false); + assert.match(missing.error, /target does not exist/); +}); + +test("checks projection collisions against the actual workspace graph", () => { + const root = makeWorkspace(); + fs.writeFileSync(path.join(root, "memory", "graph", "nodes.jsonl"), JSON.stringify({ + id: IDS.memory, + k: "person", + n: "Colliding node", + d: "Not an AMF projection.", + st: "confirmed", + c: "high", + u: "2026-07-11", + src: "memory/index.md" + }) + "\n", "utf8"); + const rejected = proposeMemoryRecord(root, config, { + content: recordContent(baseRecord()), + rationale: "Must reject graph collision." + }); + assert.equal(rejected.ok, false); + assert.match(rejected.error, /graph id collision/); + + fs.writeFileSync(path.join(root, "memory", "graph", "nodes.jsonl"), JSON.stringify({ + id: IDS.memory, + k: "memory-record", + n: "Stale derived record", + d: "Stale projection.", + st: "confirmed", + c: "high", + u: "2026-07-10", + src: `memory/amf/records/${IDS.memory}.md` + }) + "\n", "utf8"); + const bounded = validateMemoryRecord(recordContent(baseRecord()), { workspaceRoot: root }); + assert.equal(bounded.ok, true, bounded.errors.join("\n")); + assert.match(bounded.warnings.join("\n"), /projection is stale/); + + const proposed = proposeMemoryRecord(root, config, { + content: recordContent(baseRecord()), + rationale: "Propagate the required graph reindex follow-up." + }); + assert.equal(proposed.ok, true, proposed.error); + assert.equal(proposed.graphProjectionStale, true); + assert.equal(proposed.regenerateAfterApply, true); + assert.equal(proposed.followup.command, "npm run memory:graph:index"); + const proposalArtifact = JSON.parse(fs.readFileSync(path.join(root, proposed.proposalPath), "utf8")); + assert.match(proposalArtifact.validation.warnings.join("\n"), /projection is stale/); + assert.equal(proposalArtifact.validation.amfMemory.graphProjectionStale, true); + assert.equal(proposalArtifact.validation.regenerateAfterApply, true); + + const applied = applyProposal(root, config, { proposalId: proposed.proposalId }); + assert.equal(applied.ok, true, applied.error); + assert.equal(applied.graphProjectionStale, true); + assert.equal(applied.regenerateAfterApply, true); + assert.deepEqual(applied.followup, { + action: "graph_reindex", + command: "npm run memory:graph:index", + required: true + }); + const appliedArtifact = JSON.parse(fs.readFileSync(path.join(root, applied.proposalArchivedAs), "utf8")); + assert.match(appliedArtifact.validation.warnings.join("\n"), /projection is stale/); + assert.equal(appliedArtifact.validation.graphProjectionStale, true); + assert.equal(appliedArtifact.validation.regenerateAfterApply, true); +}); + +test("proposal and apply reject symlinks in every ancestor", () => { + const root = makeWorkspace(); + const outside = fs.mkdtempSync(path.join(os.tmpdir(), "pam-amf-outside-")); + fs.mkdirSync(path.join(root, "memory", "amf"), { recursive: true }); + fs.symlinkSync(outside, path.join(root, "memory", "amf", "records")); + const content = recordContent(baseRecord()); + const proposed = proposeMemoryRecord(root, config, { content, rationale: "Must fail closed." }); + assert.equal(proposed.ok, false); + assert.match(proposed.error, /symlink/); + assert.equal(fs.readdirSync(outside).length, 0); +}); + +test("apply rechecks ancestors and refuses a symlink introduced after proposal", () => { + const root = makeWorkspace(); + const outside = fs.mkdtempSync(path.join(os.tmpdir(), "pam-amf-apply-outside-")); + const content = recordContent(baseRecord()); + const proposed = proposeMemoryRecord(root, config, { content, rationale: "Record before path substitution." }); + assert.equal(proposed.ok, true, proposed.error); + fs.mkdirSync(path.join(root, "memory", "amf"), { recursive: true }); + fs.symlinkSync(outside, path.join(root, "memory", "amf", "records")); + const applied = applyProposal(root, config, { proposalId: proposed.proposalId }); + assert.equal(applied.ok, false); + assert.match(applied.error, /symlink/); + assert.equal(fs.readdirSync(outside).length, 0); +}); + +test("apply validates old-to-new revision and requires a real proposal base hash", () => { + const root = makeWorkspace(); + const target = `memory/amf/records/${IDS.memory}.md`; + const current = recordContent(baseRecord()); + fs.mkdirSync(path.dirname(path.join(root, target)), { recursive: true }); + fs.writeFileSync(path.join(root, target), current, "utf8"); + const next = recordContent(baseRecord({ revision: 2, updatedAt: "2026-07-11T11:00:00Z" })); + const proposal = proposeEdit(root, config, { + path: target, + rationale: "Lifecycle metadata revision.", + diff: { kind: "replace", before: current, after: next } + }); + assert.equal(proposal.ok, true, proposal.error); + const artifactPath = path.join(root, proposal.proposalPath); + const artifact = JSON.parse(fs.readFileSync(artifactPath, "utf8")); + assert.equal(artifact.expectedRevision, 1); + assert.equal(artifact.expectedTargetSha256, recordSha256(current)); + artifact.expectedTargetSha256 = "f".repeat(64); + fs.writeFileSync(artifactPath, JSON.stringify(artifact), "utf8"); + const applied = applyProposal(root, config, { proposalId: proposal.proposalId }); + assert.equal(applied.ok, false); + assert.match(applied.error, /drifted|SHA-256/); + assert.equal(fs.readFileSync(path.join(root, target), "utf8"), current); +}); + +test("apply uses an exclusive proposal lock", () => { + const root = makeWorkspace(); + const content = recordContent(baseRecord()); + const proposed = proposeMemoryRecord(root, config, { content, rationale: "Exclusive apply." }); + assert.equal(proposed.ok, true, proposed.error); + const lockPath = path.join(root, "memory", "maintenance", "proposals", `${proposed.proposalId}.lock`); + fs.writeFileSync(lockPath, "held\n", { mode: 0o600 }); + const applied = applyProposal(root, config, { proposalId: proposed.proposalId }); + assert.equal(applied.ok, false); + assert.match(applied.error, /already being applied/); + assert.equal(fs.existsSync(path.join(root, proposed.targetPath)), false); +}); + +test("exclusive atomic writes never replace an existing path", () => { + const root = makeWorkspace(); + const target = path.join(root, "memory", "reserved.json"); + fs.writeFileSync(target, "original\n", "utf8"); + assert.throws( + () => atomicWriteFileSync(root, target, "replacement\n", { exclusive: true }), + /already exists/ + ); + assert.equal(fs.readFileSync(target, "utf8"), "original\n"); +}); + +test("archive collision fails before target persistence and applying reservation recovers", () => { + const root = makeWorkspace(); + const content = recordContent(baseRecord()); + const collision = proposeMemoryRecord(root, config, { content, rationale: "Archive collision." }); + assert.equal(collision.ok, true, collision.error); + const collisionArchive = path.join(root, "memory", "maintenance", "proposals", `${collision.proposalId}.applied.json`); + fs.writeFileSync(collisionArchive, JSON.stringify({ status: "foreign" }), "utf8"); + const blocked = applyProposal(root, config, { proposalId: collision.proposalId }); + assert.equal(blocked.ok, false); + assert.match(blocked.error, /reserved by a different|malformed/); + assert.equal(fs.existsSync(path.join(root, collision.targetPath)), false); + + const recoveryRoot = makeWorkspace(); + const recovery = proposeMemoryRecord(recoveryRoot, config, { content, rationale: "Crash recovery." }); + assert.equal(recovery.ok, true, recovery.error); + const proposalArtifact = JSON.parse(fs.readFileSync(path.join(recoveryRoot, recovery.proposalPath), "utf8")); + const recoveryArchive = path.join(recoveryRoot, "memory", "maintenance", "proposals", `${recovery.proposalId}.applied.json`); + fs.writeFileSync(recoveryArchive, JSON.stringify({ + ...proposalArtifact, + status: "applying", + reservationId: crypto.randomUUID(), + reservedAt: "2026-07-11T12:00:00Z" + }), "utf8"); + fs.mkdirSync(path.dirname(path.join(recoveryRoot, recovery.targetPath)), { recursive: true }); + fs.writeFileSync(path.join(recoveryRoot, recovery.targetPath), content, "utf8"); + const recovered = applyProposal(recoveryRoot, config, { proposalId: recovery.proposalId }); + assert.equal(recovered.ok, true, recovered.error); + assert.equal(JSON.parse(fs.readFileSync(recoveryArchive, "utf8")).status, "applied"); + assert.equal(fs.existsSync(path.join(recoveryRoot, recovery.proposalPath)), false); +}); + +test("applying reservation binds the complete immutable proposal identity", () => { + const root = makeWorkspace(); + const content = recordContent(baseRecord()); + const proposed = proposeMemoryRecord(root, config, { + content, + rationale: "Preserve reviewed proposal identity.", + findingIds: ["finding-reviewed-1"], + source: "reviewed-curator" + }); + assert.equal(proposed.ok, true, proposed.error); + const proposalAbsolute = path.join(root, proposed.proposalPath); + const proposalArtifact = JSON.parse(fs.readFileSync(proposalAbsolute, "utf8")); + const archiveAbsolute = path.join( + root, + "memory", + "maintenance", + "proposals", + `${proposed.proposalId}.applied.json` + ); + const forgedReservation = { + ...proposalArtifact, + source: "forged-curator", + rationale: "Substitute an unreviewed rationale.", + findingIds: ["finding-forged-1"], + diff: { + ...proposalArtifact.diff, + content: proposalArtifact.diff.content.replace("event-stable-0001", "event-forged-0001") + }, + status: "applying", + reservationId: crypto.randomUUID(), + reservedAt: "2026-07-11T12:00:00Z" + }; + assert.equal(forgedReservation.proposalId, proposalArtifact.proposalId); + assert.equal(forgedReservation.targetPath, proposalArtifact.targetPath); + assert.equal(forgedReservation.proposedContentSha256, proposalArtifact.proposedContentSha256); + fs.writeFileSync(archiveAbsolute, JSON.stringify(forgedReservation), "utf8"); + const archiveBeforeApply = fs.readFileSync(archiveAbsolute, "utf8"); + + const rejected = applyProposal(root, config, { proposalId: proposed.proposalId }); + assert.equal(rejected.ok, false); + assert.match(rejected.error, /reserved by a different|malformed/); + assert.equal(fs.existsSync(proposalAbsolute), true); + assert.equal(fs.existsSync(path.join(root, proposed.targetPath)), false); + assert.equal(fs.readFileSync(archiveAbsolute, "utf8"), archiveBeforeApply); +}); + +test("applied recovery rejects an unrelated archive and retains the live proposal", () => { + const root = makeWorkspace(); + const content = recordContent(baseRecord()); + const proposed = proposeMemoryRecord(root, config, { content, rationale: "Keep the real proposal." }); + assert.equal(proposed.ok, true, proposed.error); + const proposalAbsolute = path.join(root, proposed.proposalPath); + const proposalArtifact = JSON.parse(fs.readFileSync(proposalAbsolute, "utf8")); + const unrelatedPath = "memory/amf/records/mem_aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa.md"; + const unrelatedContent = recordContent(baseRecord({ id: "mem_aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa" })); + fs.mkdirSync(path.dirname(path.join(root, unrelatedPath)), { recursive: true }); + fs.writeFileSync(path.join(root, unrelatedPath), unrelatedContent, "utf8"); + const unrelatedHash = recordSha256(unrelatedContent); + const archiveAbsolute = path.join(root, "memory", "maintenance", "proposals", `${proposed.proposalId}.applied.json`); + fs.writeFileSync(archiveAbsolute, JSON.stringify({ + ...proposalArtifact, + targetPath: unrelatedPath, + proposedContentSha256: unrelatedHash, + persistedContentSha256: unrelatedHash, + status: "applied", + reservationId: crypto.randomUUID(), + appliedAt: "2026-07-11T12:00:00Z", + validation: null + }), "utf8"); + + const rejected = applyProposal(root, config, { proposalId: proposed.proposalId }); + assert.equal(rejected.ok, false); + assert.match(rejected.error, /identity does not match/); + assert.equal(fs.existsSync(proposalAbsolute), true); + assert.equal(fs.existsSync(path.join(root, proposed.targetPath)), false); +}); + +test("applied recovery binds and preserves the validation warning summary", () => { + const content = recordContent(baseRecord()); + const root = makeWorkspace(); + writeStaleProjection(root); + const proposed = proposeMemoryRecord(root, config, { content, rationale: "Recover with graph warning." }); + assert.equal(proposed.ok, true, proposed.error); + const proposalAbsolute = path.join(root, proposed.proposalPath); + const proposalArtifact = JSON.parse(fs.readFileSync(proposalAbsolute, "utf8")); + assert.match(proposalArtifact.validation.warnings.join("\n"), /projection is stale/); + fs.mkdirSync(path.dirname(path.join(root, proposed.targetPath)), { recursive: true }); + fs.writeFileSync(path.join(root, proposed.targetPath), content, "utf8"); + const archiveAbsolute = path.join(root, "memory", "maintenance", "proposals", `${proposed.proposalId}.applied.json`); + fs.writeFileSync(archiveAbsolute, JSON.stringify({ + ...proposalArtifact, + status: "applied", + reservationId: crypto.randomUUID(), + appliedAt: "2026-07-11T12:00:00Z", + persistedContentSha256: proposalArtifact.proposedContentSha256, + validation: proposalArtifact.validation.amfMemory + }), "utf8"); + + const recovered = applyProposal(root, config, { proposalId: proposed.proposalId }); + assert.equal(recovered.ok, true, recovered.error); + assert.equal(recovered.recovered, true); + assert.match(recovered.warnings.join("\n"), /projection is stale/); + assert.equal(recovered.graphProjectionStale, true); + assert.equal(recovered.regenerateAfterApply, true); + assert.equal(fs.existsSync(proposalAbsolute), false); + + const forgedRoot = makeWorkspace(); + writeStaleProjection(forgedRoot); + const forged = proposeMemoryRecord(forgedRoot, config, { content, rationale: "Reject changed warnings." }); + assert.equal(forged.ok, true, forged.error); + const forgedProposalAbsolute = path.join(forgedRoot, forged.proposalPath); + const forgedProposal = JSON.parse(fs.readFileSync(forgedProposalAbsolute, "utf8")); + fs.mkdirSync(path.dirname(path.join(forgedRoot, forged.targetPath)), { recursive: true }); + fs.writeFileSync(path.join(forgedRoot, forged.targetPath), content, "utf8"); + const forgedArchiveAbsolute = path.join(forgedRoot, "memory", "maintenance", "proposals", `${forged.proposalId}.applied.json`); + fs.writeFileSync(forgedArchiveAbsolute, JSON.stringify({ + ...forgedProposal, + status: "applied", + reservationId: crypto.randomUUID(), + appliedAt: "2026-07-11T12:00:00Z", + persistedContentSha256: forgedProposal.proposedContentSha256, + validation: { ...forgedProposal.validation.amfMemory, warnings: ["forged warning summary"] } + }), "utf8"); + + const warningMismatch = applyProposal(forgedRoot, config, { proposalId: forged.proposalId }); + assert.equal(warningMismatch.ok, false); + assert.match(warningMismatch.error, /validation warnings do not match/); + assert.equal(fs.existsSync(forgedProposalAbsolute), true); +}); diff --git a/tools/test-pam-mcp-server.mjs b/tools/test-pam-mcp-server.mjs index 5f1dd6c..ea97e45 100644 --- a/tools/test-pam-mcp-server.mjs +++ b/tools/test-pam-mcp-server.mjs @@ -72,6 +72,43 @@ function makeWorkspace() { return root; } +function amfRecordContent() { + const values = { + schema: "amf-memory/v1", + id: "mem_11111111-1111-4111-8111-111111111111", + revision: 1, + claimType: "decision", + scope: { type: "shared", id: "shared:global" }, + visibility: "shared", + subjects: [{ identityId: "agent:22222222-2222-4222-8222-222222222222", role: "owner" }], + claim: { encoding: "plain", text: "A portable, source-backed memory record." }, + lifecycle: { + status: "active", + validFrom: "2026-07-11T10:00:00Z", + validTo: null, + supersedes: [], + revokedAt: null, + revocationReason: null + }, + provenance: [{ + sourceType: "test-session", + sourceId: "session-stable-0001", + eventId: "event-stable-0001", + contentSha256: "a".repeat(64), + capturedAt: "2026-07-11T10:00:00Z" + }], + createdAt: "2026-07-11T10:00:00Z", + updatedAt: "2026-07-11T10:00:00Z" + }; + const metadata = Object.entries(values).map(([key, value]) => { + const rendered = value !== null && typeof value === "object" + ? JSON.stringify(value) + : String(value); + return `${key}: ${rendered}`; + }).join("\n"); + return `---\n${metadata}\n---\nNon-claim commentary.\n`; +} + function driveServer(workspaceRoot, requests, timeoutMs = 5000) { return new Promise((resolve, reject) => { const child = spawn(process.execPath, [SERVER_PATH, "--workspace", workspaceRoot], { @@ -140,6 +177,8 @@ test("server responds to initialize + tools/list", async () => { const toolNames = responses[1].result.tools.map((t) => t.name); assert.ok(toolNames.includes("memory_audit")); assert.ok(toolNames.includes("memory_propose_edit")); + assert.ok(toolNames.includes("memory_record_validate")); + assert.ok(toolNames.includes("memory_propose_record")); assert.ok(toolNames.includes("graph_validate")); }); @@ -203,3 +242,45 @@ test("server rejects memory_propose_edit on protected path", async () => { assert.equal(payload.status, "rejected"); assert.match(payload.error, /protected/i); }); + +test("server validates and records an AMF record proposal without applying it", async () => { + const root = makeWorkspace(); + const content = amfRecordContent(); + const responses = await driveServer(root, [ + { jsonrpc: "2.0", id: 1, method: "initialize", params: {} }, + { + jsonrpc: "2.0", + id: 2, + method: "tools/call", + params: { + name: "memory_propose_record", + arguments: { content, rationale: "Record reviewed portable memory." } + } + } + ]); + const payload = JSON.parse(responses[1].result.content[0].text); + assert.equal(payload.status, "recorded"); + assert.equal(payload.projection.k, "memory-record"); + assert.equal(fs.existsSync(path.join(root, payload.targetPath)), false); + assert.equal(fs.existsSync(path.join(root, payload.proposalPath)), true); +}); + +test("server returns a safe projection for a canonical AMF record", async () => { + const root = makeWorkspace(); + const relative = "memory/amf/records/mem_11111111-1111-4111-8111-111111111111.md"; + fs.mkdirSync(path.dirname(path.join(root, relative)), { recursive: true }); + fs.writeFileSync(path.join(root, relative), amfRecordContent(), "utf8"); + const responses = await driveServer(root, [ + { jsonrpc: "2.0", id: 1, method: "initialize", params: {} }, + { + jsonrpc: "2.0", + id: 2, + method: "tools/call", + params: { name: "memory_record_validate", arguments: { path: relative } } + } + ]); + const payload = JSON.parse(responses[1].result.content[0].text); + assert.equal(payload.status, "valid"); + assert.equal(payload.projection.k, "memory-record"); + assert.equal(payload.projection.src, relative); +}); diff --git a/tools/test-secure-fs-locks.mjs b/tools/test-secure-fs-locks.mjs new file mode 100644 index 0000000..deecc8d --- /dev/null +++ b/tools/test-secure-fs-locks.mjs @@ -0,0 +1,174 @@ +import assert from "node:assert/strict"; +import { spawn } from "node:child_process"; +import crypto from "node:crypto"; +import fs from "node:fs"; +import os from "node:os"; +import path from "node:path"; +import { pathToFileURL } from "node:url"; +import test from "node:test"; + +import { applyProposal } from "./lib/memory-apply-proposal.mjs"; +import { proposeEdit } from "./lib/memory-proposals.mjs"; +import { acquireExclusiveLock } from "./lib/secure-fs.mjs"; + +const PROPOSALS_DIR = path.join("memory", "maintenance", "proposals"); +const SHORT_LOCK_OPTIONS = { staleMs: 120, heartbeatMs: 0 }; + +function delay(milliseconds) { + return new Promise((resolve) => setTimeout(resolve, milliseconds)); +} + +function makeWorkspace() { + const root = fs.mkdtempSync(path.join(os.tmpdir(), "pam-lock-test-")); + fs.mkdirSync(path.join(root, "memory", "graph"), { recursive: true }); + fs.writeFileSync( + path.join(root, "memory", "knowledge-log.md"), + "# Knowledge Log\n\n## 2026-04-12 - Worker retries\n\nFive retries.\n", + "utf8" + ); + fs.writeFileSync( + path.join(root, "memory", "graph", "nodes.jsonl"), + '{"id":"project:pam","k":"project","n":"PAM","d":"Memory toolkit.","st":"confirmed","c":"high","u":"2026-05-05","src":"README.md"}\n', + "utf8" + ); + fs.writeFileSync(path.join(root, "memory", "graph", "edges.jsonl"), "", "utf8"); + fs.writeFileSync(path.join(root, "memory", "graph", "aliases.jsonl"), '{"a":"PAM","id":"project:pam"}\n', "utf8"); + return root; +} + +function defaultConfig() { + return { + protectedPaths: ["AGENTS.md", "CLAUDE.md", "memory/agent-memory", "memory/sources"] + }; +} + +function recordProposal(root) { + const result = proposeEdit(root, defaultConfig(), { + path: "memory/knowledge-log.md", + rationale: "exercise lock recovery", + diff: { + kind: "replace", + anchor: { headerLine: "## 2026-04-12 - Worker retries" }, + before: "## 2026-04-12 - Worker retries\n\nFive retries.\n", + after: "## 2026-04-12 - Worker retries\n\nFive retries after lock recovery.\n" + } + }); + assert.equal(result.ok, true, result.error); + return result.proposalId; +} + +async function spawnLockHolder(root, lockPath, lockOptions) { + const moduleUrl = pathToFileURL(path.join(import.meta.dirname, "lib", "secure-fs.mjs")).href; + const source = ` + import { acquireExclusiveLock } from ${JSON.stringify(moduleUrl)}; + acquireExclusiveLock( + process.env.PAM_TEST_ROOT, + process.env.PAM_TEST_LOCK, + JSON.parse(process.env.PAM_TEST_OPTIONS) + ); + process.stdout.write("LOCKED\\n"); + setInterval(() => {}, 1000); + `; + const child = spawn(process.execPath, ["--input-type=module", "-e", source], { + env: { + ...process.env, + PAM_TEST_ROOT: root, + PAM_TEST_LOCK: lockPath, + PAM_TEST_OPTIONS: JSON.stringify(lockOptions) + }, + stdio: ["ignore", "pipe", "pipe"] + }); + await new Promise((resolve, reject) => { + let stdout = ""; + let stderr = ""; + const timeout = setTimeout(() => reject(new Error(`lock holder startup timed out: ${stderr}`)), 5000); + child.stdout.on("data", (chunk) => { + stdout += chunk; + if (stdout.includes("LOCKED\n")) { + clearTimeout(timeout); + resolve(); + } + }); + child.stderr.on("data", (chunk) => { + stderr += chunk; + }); + child.once("exit", (code, signal) => { + clearTimeout(timeout); + reject(new Error(`lock holder exited before ready (${code ?? signal}): ${stderr}`)); + }); + }); + return child; +} + +async function crash(child) { + if (child.exitCode !== null || child.signalCode !== null) return; + const exited = new Promise((resolve) => child.once("exit", resolve)); + child.kill("SIGKILL"); + await exited; +} + +test("exclusive lock records owner identity and refuses to release a replacement inode/token", () => { + const root = makeWorkspace(); + const lockPath = path.join(root, PROPOSALS_DIR, "owner-safe.lock"); + fs.mkdirSync(path.dirname(lockPath), { recursive: true }); + const lock = acquireExclusiveLock(root, lockPath, SHORT_LOCK_OPTIONS); + const owner = JSON.parse(fs.readFileSync(lockPath, "utf8")); + assert.equal(owner.version, 1); + assert.equal(owner.pid, process.pid); + assert.equal(typeof owner.host, "string"); + assert.match(owner.nonce, /^[a-f0-9]{48}$/); + assert.ok(Date.parse(owner.acquiredAt)); + assert.ok(Date.parse(owner.heartbeatAt)); + + fs.rmSync(lockPath); + const replacement = { ...owner, nonce: crypto.randomBytes(24).toString("hex") }; + fs.writeFileSync(lockPath, `${JSON.stringify(replacement)}\n`, { mode: 0o600 }); + assert.throws(() => lock.release(), /ownership changed/i); + assert.equal(JSON.parse(fs.readFileSync(lockPath, "utf8")).nonce, replacement.nonce); +}); + +test("proposal lock takeover requires a stale lock whose subprocess owner is dead", async (t) => { + const root = makeWorkspace(); + const proposalId = recordProposal(root); + const lockPath = path.join(root, PROPOSALS_DIR, `${proposalId}.lock`); + const child = await spawnLockHolder(root, lockPath, SHORT_LOCK_OPTIONS); + t.after(() => crash(child)); + + await delay(180); + const whileAlive = applyProposal(root, defaultConfig(), { proposalId }, { lockOptions: SHORT_LOCK_OPTIONS }); + assert.equal(whileAlive.ok, false); + assert.match(whileAlive.error, /already being applied/i); + + await crash(child); + const afterCrash = applyProposal(root, defaultConfig(), { proposalId }, { lockOptions: SHORT_LOCK_OPTIONS }); + assert.equal(afterCrash.ok, true, afterCrash.error); + assert.equal(afterCrash.status, "applied"); + assert.equal(fs.existsSync(lockPath), false); +}); + +test("target lock heartbeat prevents takeover; dead fresh lock waits until stale before retry", async (t) => { + const root = makeWorkspace(); + const proposalId = recordProposal(root); + const targetPath = "memory/knowledge-log.md"; + const targetLockId = crypto.createHash("sha256").update(targetPath).digest("hex"); + const lockPath = path.join(root, PROPOSALS_DIR, `target-${targetLockId}.lock`); + const heartbeatOptions = { staleMs: 120, heartbeatMs: 20 }; + const child = await spawnLockHolder(root, lockPath, heartbeatOptions); + t.after(() => crash(child)); + + await delay(220); + const whileAlive = applyProposal(root, defaultConfig(), { proposalId }, { lockOptions: heartbeatOptions }); + assert.equal(whileAlive.ok, false); + assert.match(whileAlive.error, /target is already being modified/i); + + await crash(child); + const whileFresh = applyProposal(root, defaultConfig(), { proposalId }, { lockOptions: heartbeatOptions }); + assert.equal(whileFresh.ok, false); + assert.match(whileFresh.error, /target is already being modified/i); + + await delay(160); + const afterStale = applyProposal(root, defaultConfig(), { proposalId }, { lockOptions: heartbeatOptions }); + assert.equal(afterStale.ok, true, afterStale.error); + assert.equal(afterStale.status, "applied"); + assert.equal(fs.existsSync(lockPath), false); +});