blackcat-darkmesh-write

AO-native command layer for Blackcat Darkmesh. This repository hosts the write-side AO processes that enforce idempotent, authorized, and auditable changes to the canonical state maintained in blackcat-darkmesh-ao. No separate server-side authority exists; any bridge or admin client is only a transport adapter.

Scope

• In scope: AO command processes, handlers, idempotency registry, audit/event emission, publish workflow (draft → review → publish → rollback), validators and schemas, minimal adapters, deploy/verify scripts, fixtures, CI workflows.
• Out of scope: read/state model (lives in blackcat-darkmesh-ao), gateway rendering, frontend assets, secrets or signing keys.

Architecture Snapshot

• Role: command-first AO process set that owns write semantics, conflict detection, and append-only audit; delegates state materialization to blackcat-darkmesh-ao.
• Pipeline: command envelope → validation (schema + policy) → idempotency / anti-replay → handler → audit + event → downstream AO state update.
• Identity & auth: signed commands or capability tokens; gateway is never an implicit authority.
• Idempotence: requestId registry and optimistic expectedVersion guards to prevent duplicate writes.
• Audit: append-only log with correlation to requestId and actor; deterministic status codes.

Repository Layout (blueprint)

docs/              # command contracts, flows, failure modes, ADRs, runbooks
ao/                # AO command process and shared libs
  write/           # command handlers, routing
  shared/          # auth, idempotency, validation, audit
schemas/           # JSON schemas for command envelopes and actions
scripts/           # deploy | verify
fixtures/          # sample command envelopes and expected outcomes
tests/             # contract, conflict, and security tests
scripts/bridge/    # stub forwarder from write outbox to -ao
scripts/cli/       # local helpers (run command)
.github/workflows/ # CI entrypoint

Minimal Command Envelope

• Required tags: Action, Request-Id, Actor, Tenant, Expected-Version, Nonce, Signature-Ref, Timestamp.
• Core handlers (initial set): SaveDraftPage, PublishPageVersion, UpsertRoute, UpsertProduct, AssignRole, UpsertProfile, GrantEntitlement.
• Conflict strategy: reject on missing/expired nonce, replayed Request-Id, or mismatched Expected-Version; return prior result when replayed.

Development

• Prereqs: lua5.4 (or luac) and python3.
• Static checks: scripts/verify/preflight.sh (JSON schema validation + Lua syntax).
• Contract smoke tests: LUA_PATH="?.lua;?/init.lua;ao/?.lua;ao/?/init.lua" lua5.4 scripts/verify/contracts.lua (or set RUN_CONTRACTS=1 to run during preflight).
• Conflict/security smoke tests: LUA_PATH="?.lua;?/init.lua;ao/?.lua;ao/?/init.lua" lua5.4 scripts/verify/conflicts.lua (or RUN_CONFLICTS=1).
• Batch fixtures: LUA_PATH="?.lua;?/init.lua;ao/?.lua;ao/?/init.lua" lua5.4 scripts/cli/batch_run.lua (or RUN_BATCH=1 in preflight) – compares fixtures to *.expected.json.
• Branches: main (releasable), develop (integration), feature/*, adr/*, release/*.
• Message contracts and schemas are public API; prefer additive changes over breaking ones.

Env toggles (write process)

• WRITE_REQUIRE_SIGNATURE=1 — reject commands without signatureRef.
• WRITE_REQUIRE_NONCE=1 — reject commands without nonce and block replay.
• WRITE_NONCE_TTL_SECONDS (default 300) and WRITE_NONCE_MAX (default 2048) — nonce cache sizing.
• WRITE_ALLOW_ANON=1 — allow missing actor/tenant (off by default).
• WRITE_SIG_TYPE=ed25519|ecdsa|hmac (prod default: ed25519); WRITE_SIG_PUBLIC (PEM) or WRITE_SIG_SECRET (hmac key) to verify signature.
• Optional JWT gate: set WRITE_JWT_HS_SECRET (HS256) and optionally WRITE_REQUIRE_JWT=1 to fail-closed; claims sub/tenant/role/nonce populate actor/tenant/role/nonce when missing.
• WRITE_WAL_PATH=/var/lib/ao/write-wal.ndjson — append-only WAL with request/response hashes.
• WRITE_IDEM_PATH=/var/lib/ao/write-idem.json — persist idempotent responses across restarts (optional).
• WRITE_OUTBOX_PATH=/var/lib/ao/write-outbox.json — persist outbox events (used by forwarders/export).
• Checksum watchdog: ops/systemd/write-checksum.service + scripts/verify/checksum_daemon.sh (set WRITE_WAL_PATH, WRITE_OUTBOX_PATH, CHECKSUM_INTERVAL_SEC).
• Resolver flags: WRITE_FLAGS_PATH=/etc/ao/resolver-flags.ndjson to block/readonly resolvers (shared with registry/AO); enforced before policy.
• Shipping/Tax export for AO: persist rates with WRITE_RATE_STORE_PATH and run scripts/export/rates.lua [rate_store] [shipping.ndjson] [tax.ndjson]; point AO to the outputs via AO_SHIPPING_RATES_PATH / AO_TAX_RATES_PATH.
• Dispute evidence payload: AddDisputeEvidence accepts evidence.url|hash|hashAlgo|type|note|fileName to carry provider links/hashes; stored in payment_disputes and can be sent via provider webhooks.
• WRITE_RL_WINDOW_SECONDS / WRITE_RL_MAX_REQUESTS — rate-limit per tenant+actor (default 60s / 200 reqs).
• Bridge/env for queue/HTTP: AO_ENDPOINT=https://... (optional); AO_API_KEY; DRY_RUN=1 or AO_BRIDGE_MODE=mock|off|http; AO_BRIDGE_RETRIES/AO_BRIDGE_BACKOFF_MS; AO_QUEUE_PATH (persisted queue), AO_QUEUE_LOG_PATH=/var/lib/ao/queue-log.ndjson, AO_QUEUE_MAX_RETRIES=5, AO_EXPECT_RESPONSE_HASH to enforce downstream body hash.
• Trust manifest signing (resolvers): set TRUST_MANIFEST_HMAC and run lua scripts/cli/trust_manifest_sign.lua manifest.json > manifest.signed.json; optionally set TRUST_MANIFEST_SIGNER.
• Key management: keep public keys under /etc/ao/keys, record their sha256sum in ops docs, rotate on a schedule; never store private keys in repos, artifacts, or CI logs.
• OTP/passwordless: OTP_TTL_SECONDS (default 300, min 30, max 3600), OTP_JWT_TTL_SECONDS (default 900) control IssueOtp/ExchangeOtp flow.

CLI helpers

• lua scripts/cli/run_command.lua ./fixtures/sample-save-draft.json — route a JSON command locally and print the response (uses in-memory state). A publish sample is at fixtures/sample-publish.json.
• RUN_BATCH=1 LUA_PATH="?.lua;?/init.lua;ao/?.lua;ao/?/init.lua" lua scripts/cli/batch_run.lua — run all fixtures and enforce matches to *.expected.json (CI uses this).
• Queue forwarder (persisted outbox → HTTP):
  AO_QUEUE_PATH=dev/outbox-queue.ndjson AO_QUEUE_LOG_PATH=dev/queue-log.ndjson AO_QUEUE_MAX_RETRIES=5 LUA_PATH="?.lua;?/init.lua;ao/?.lua;ao/?/init.lua" lua scripts/bridge/queue_forward.lua
• Health snapshot (write-side files & deps):
  WRITE_WAL_PATH=... WRITE_OUTBOX_PATH=... AO_QUEUE_PATH=... LUA_PATH="?.lua;?/init.lua;ao/?.lua;ao/?/init.lua" lua scripts/verify/health.lua

Bridge (stub)

• scripts/bridge/forward_outbox.lua reads the in-memory outbox (write._storage_outbox()) and logs events you would forward to blackcat-darkmesh-ao. Replace forward_event with signed POST to AO endpoint (registry/site process) in production.
• scripts/bridge/export_outbox.lua [outfile] dumps outbox to NDJSON (default dev/outbox.ndjson) for offline inspection or manual upload.
• scripts/bridge/forward_outbox_http.lua posts outbox events to AO_ENDPOINT (set DRY_RUN=1 to log only; optional AO_API_KEY, AO_SITE_ID tag).

Security Guard Rails

• No secrets or raw keys in AO state, manifests, or adapters.
• Gateways act only as clients; write process re-validates auth and policy.
• All comments and docs remain in English.

License

Blackcat Darkmesh Write Proprietary License (see LICENSE). External contributions require written permission from Black Cat Academy s. r. o.