Security & Operations

Core’s package declares Node.js ≥20. The supplied Dockerfile uses Node 20 Alpine and the Compose example uses PostgreSQL 16 Alpine. These are repository defaults, not a broader compatibility or lifecycle-support promise.

Apply the release’s migrations before starting the service. PostgreSQL supplies durable storage; your team manages capacity, access, monitoring, replication and failover. The public health endpoint reports database health and ledger progress, so restrict its network exposure as appropriate.

HTTP snapshot creation requires a bearer token from WRITE_API_KEYS. Read and verification endpoints accept tokens from either READ_API_KEYS or WRITE_API_KEYS. Keys are service credentials with instance-wide access, not per-customer or end-user permissions.

The CLI connects directly to PostgreSQL through DATABASE_URL; HTTP API keys do not protect that path. Restrict database credentials and CLI access accordingly.

The Core server configures HTTP, without built-in TLS termination. Operators must provide secure transport and control ingress. Operators also choose database connection security, disk and backup encryption and secret storage.

Supply DATABASE_URL, READ_API_KEYS and WRITE_API_KEYS through your deployment configuration. Replace the public demo keys and database password before any shared deployment. Keep credentials and full payment details out of evidence payloads.

The default canonicalized payload limit is 1,048,576 bytes, configured by MAX_PAYLOAD_BYTES; HTTP request limits can also apply. Choose the minimum evidence necessary for your investigation needs.

Core hashes canonical JSON payloads with SHA-256. Each chain hash combines the instance-local sequence number, payload hash and previous chain hash. Verification recomputes these values and checks the stored links.

The hash covers state_payload, not every envelope field. Include important business references, source timestamps and rule versions inside the payload if you need them covered by its hash.

A database administrator who can rewrite records and recompute the chain remains inside the trust boundary. Stored hashes alone cannot establish an independent history or detect every deletion of a chain suffix. Protect database access and retain independent evidence of expected ledger progress where your review process requires it.

Integrity verification does not validate upstream facts, application decisions or real-world execution. Core does not provide a compliance certification, legal non-repudiation guarantee or availability SLA.

Back up snapshots, idempotency records, migration history and database metadata. Test restores in an isolated environment, check the latest expected sequence and receipt timestamp, and verify representative sequence ranges.

Your team defines evidence retention. Startup cleanup of expired idempotency records is retry housekeeping, not evidence deletion or retention automation. Plan retention against chain verification requirements before changing stored evidence.

Back up the database, review release changes, apply pending migrations in a controlled deployment step, then check health and integrity. Keep historical migrations unchanged and test the upgrade and restore process outside production. Your application owns compatibility of its JSON payload shapes.

Contact founder@simple-states.com through the existing support channel. Share the affected version and a description without credentials or customer evidence. Review is best effort, with no response SLA. Please report privately and wait to disclose publicly until the issue can be reviewed.