AlexandrAI AGENTS.md
agents-md

Personal Work Agent Security and Secrets Agent Guide

Project-specific AGENTS.md guidance for Personal Work Agent HMAC signing, timestamp skew checks, idempotency keys, keyring/file/memory secret stores, redaction, and tests.

AGENTS.md

Guidance for coding agents working on Personal Work Agent security and secret-handling utilities.

Project Overview

The security boundary signs outbound requests, verifies signatures, checks timestamp skew, normalizes idempotency keys, stores provider and platform secrets, builds credential metadata, and redacts sensitive request data for internal logs.

Keep this layer small and explicit. It is a cross-cutting dependency for sync, connector validation, CLI token management, runtime process setup, and admin logging.

Project Map

  • src/workagent/security/hmac.py builds signed payloads, emits x-workagent headers, verifies signatures, and checks timestamp skew.
  • src/workagent/security/idempotency.py normalizes required idempotency keys.
  • src/workagent/runtime/secrets.py implements KeyringSecretStore, FileSecretStore, MemorySecretStore, and platform selection.
  • src/workagent/services/credentials.py resolves connector credentials and enabled state.
  • src/workagent/app/middleware.py redacts sensitive request metadata before logging.
  • src/workagent/runtime/process_env.py builds local engine process environment overrides.
  • tests/test_security_utils.py, test_secret_stores.py, test_secret_rotation.py, test_cli_tokens.py, and test_app_middleware.py cover the boundary.

Setup Commands

bashuv run pytest tests/test_security_utils.py tests/test_secret_stores.py tests/test_secret_rotation.py -q
uv run pytest tests/test_cli_tokens.py tests/test_app_middleware.py tests/test_credential_metadata.py -q
make lint

Change Rules For Agents

  • Keep HMAC payload construction stable unless every caller and verifier is migrated together.
  • Use hmac.compare_digest for signature checks.
  • Keep timestamp skew validation timezone-aware and tested.
  • Treat blank idempotency keys as errors.
  • Prefer platform keyring where available; keep file and memory stores testable.
  • Do not print or serialize secret values in CLI output, route logs, docs, or fixtures.
  • Keep redaction keys broad enough for token, secret, password, credential, authorization, and key-like fields.

Verification

bashuv run pytest tests/test_security_utils.py tests/test_secret_stores.py tests/test_app_middleware.py -q
make lint

For CLI token changes, also run token command tests. For sync signing changes, run sync client tests.

Security Notes

This boundary protects pairing secrets, platform tokens, provider keys, signatures, idempotency state, and local process credentials. Never include live values in public materials. Use placeholders in examples.

PR Checklist

  • Signing payload compatibility is preserved or migrated deliberately.
  • Secret stores remain covered across keyring, file, and memory paths.
  • Middleware redaction catches new sensitive fields.
  • Token CLI output stays redacted.