Skip to content

docs: Add replay protection documentation with nonce/timestamp examples#149

Merged
Scottcjn merged 1 commit intoScottcjn:mainfrom
nifanpinc:docs/replay-protection
Mar 18, 2026
Merged

docs: Add replay protection documentation with nonce/timestamp examples#149
Scottcjn merged 1 commit intoScottcjn:mainfrom
nifanpinc:docs/replay-protection

Conversation

@nifanpinc
Copy link
Contributor

Summary

This PR adds comprehensive replay protection documentation to address #103.

Changes

  • Added Replay Protection section to README.md
  • Included nonce + timestamp validation pattern with code examples
  • Added server-side validation code in Python
  • Documented error codes (TIMESTAMP_STALE, NONCE_REUSED, SIGNATURE_INVALID)
  • Added idempotency guidance for message retries

Implementation Pattern

# Client-side: Include nonce + timestamp
envelope = BeaconEnvelope(
    kind="message",
    payload={"text": "Hello"},
    nonce=generate_monotonic_nonce(),
    timestamp=int(time.time())
)

# Server-side: Validate
if abs(time.time() - envelope.timestamp) > 30:
    raise ReplayError("TIMESTAMP_STALE")
if nonce_store.has_seen(envelope.nonce):
    raise ReplayError("NONCE_REUSED")

Checklist

  • Added clear code examples
  • Documented all error codes with resolutions
  • Included idempotency guidance
  • Referenced existing docs/SECURITY.md

Related

Closes #103

- Add nonce + timestamp validation pattern
- Include server-side validation code examples
- Document error codes for rejected messages
- Add idempotency guidance for retries

Closes Scottcjn#103
@github-actions github-actions bot added the size/XS PR: 1-10 lines label Mar 18, 2026
@Scottcjn Scottcjn merged commit 3d64cf6 into Scottcjn:main Mar 18, 2026
1 of 2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size/XS PR: 1-10 lines

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Feature request: message replay protection and idempotency examples in docs

2 participants