Encrypted local state

Encrypted local state

Holaryn can protect classified local records, artifacts, and recovery archives with authenticated
envelope encryption. It is opt-in in this release while the implementation receives independent
security review.

What is protected

Encryption covers the write-only secret store; sensitive run-journal and local-memory fields;
chat artifacts, attachments, canvas and MCP payloads; sensitive device-invocation fields,
transfer chunks and artifacts; and encrypted recovery backups. Each domain has its own versioned
data key. Windows DPAPI or the operating-system credential vault normally wraps those keys; a
recovery-password provider is available for portable installations.

Some metadata remains readable so Holaryn can locate, expire, route, and repair records: ids,
timestamps, states, sizes, MIME types, digests and relationships. Numeric memory embeddings can
reveal similarity. Configuration, logs, operator/control-plane databases, explicit exports,
workspaces, model files, and externally hosted databases are not covered. The complete inventory
and threat model are in the encrypted-state ADR.

Encryption at rest does not protect data while an authorized running agent, connector, tool,
model provider, debugger, or operator is using it.

Before enabling

1. Stop every Holaryn host or CLI process using the state directory.
2. Choose a strong recovery password and store it separately from the machine and its backups.
3. Confirm you have enough free space for an encrypted pre-migration backup plus SQLite
   checkpointing.
4. Put the password in a process-scoped environment variable. Do not put it in shell history,
   a command argument, a project .env file, or source control.
5. Optionally place representative unique plaintext canaries in environment variables so the
   migration can prove they no longer occur in covered at-rest files.

PowerShell example:

$env:HOLARYN_ENCRYPTION_RECOVERY_PASSWORD = Read-Host "Recovery password" -MaskInput
$env:HOLARYN_TEST_CANARY = "unique-test-marker-already-present-in-covered-state"
holaryn encryption enable --provider os --canary-env HOLARYN_TEST_CANARY
Remove-Item Env:\HOLARYN_ENCRYPTION_RECOVERY_PASSWORD
Remove-Item Env:\HOLARYN_TEST_CANARY

On Windows, --provider os uses current-user DPAPI. On macOS and Linux it uses the configured
Keychain/libsecret-compatible keyring. Use --provider recovery only when you deliberately want
the recovery password to be the live wrapping provider.

Enabling creates and verifies encrypted-backups/first-enable-*.sxbak before it changes covered
state. The operation is checkpointed. If power is lost, stop the host again, restore the same
password environment variable, and run:

holaryn encryption migrate

Do not delete the encryption manifest, migration checkpoint, or pre-migration backup to “fix” a
locked or interrupted installation.

Inspect health

holaryn encryption status
holaryn encryption status --json

Settings → System → Encrypted local state shows the same non-secret provider, lock, data-key
version, migration, rotation and backup health. A locked status is fail-closed: Holaryn preserves
ciphertext rather than overwriting it.

For a recovery-password live provider, set HOLARYN_ENCRYPTION_PASSWORD before status; mutating
commands use HOLARYN_ENCRYPTION_RECOVERY_PASSWORD unless --password-env selects another
variable.

Rotate or change the wrapping provider

Stop the host. Activate new keys for every domain:

$env:HOLARYN_ENCRYPTION_RECOVERY_PASSWORD = Read-Host "Recovery password" -MaskInput
holaryn encryption rotate

Or rotate one domain:

holaryn encryption rotate --data-class memory

Old key versions remain readable so mixed-version data is safe. New writes use the active
version. Rewrap preserves the domain keys and data while changing their provider:

holaryn encryption rewrap --provider recovery
holaryn encryption rewrap --provider os

Changing providers is not a substitute for a tested backup.

Backup and recovery drill

Create a path-independent encrypted archive while the host is stopped:

holaryn encryption backup D:\offline\holaryn-2026-07-25.sxbak
holaryn encryption verify-backup D:\offline\holaryn-2026-07-25.sxbak

Copy the archive to another machine, install the same or a compatible Holaryn version, provide the
recovery password, and restore into a new empty directory:

holaryn encryption restore-backup `
  D:\offline\holaryn-2026-07-25.sxbak `
  D:\restore-drill\holaryn-state
holaryn encryption --state-dir D:\restore-drill\holaryn-state status

Never restore over live or non-empty state. Validate the recovered installation separately
before any deployment replacement.

Troubleshooting

• “key provider is locked” or DPAPI/keyring unavailable: use the same OS account and unlock
  its credential vault. For a recovery-password provider, supply the correct password variable.
• Wrong password or modified archive: authentication fails before restore publication.
  Retest a known-good independent copy; do not retry by deleting metadata.
• Migration interrupted: run migrate again with the same state directory and recovery
  material. Completed steps are not duplicated.
• Plaintext canary found: the migration remains in validation_failed. Keep the backup and
  checkpoint, inspect the reported relative path, classify it against the inventory, and do not
  declare cleanup complete.
• Corrupt/truncated ciphertext: preserve the state directory, stop writes, verify a recovery
  archive, and restore into a separate directory. Holaryn intentionally will not reset the record.
• Lost OS key and recovery material: the protected content may be unrecoverable. Preserve
  evidence and seek specialist help; recreating a manifest cannot recover the old data.