pulseproof-sentinel

PPS Deployment Guide

This guide describes how to deploy PulseProof Sentinel Protocol, abbreviated PPS, in a realistic service environment.

PPS is experimental. Do not use it in production without security review.

1. Deployment Goals

A PPS deployment should provide:

secure key registration
nonce generation
Pulse verification
atomic state updates
rate limiting
audit logging
duress handling
recovery mechanisms
monitoring and alerting
privacy protection

2. Reference Architecture

+----------------+
| User Device    |
| Authenticator  |
+-------+--------+
        |
        | QR / Deep Link / API
        v
+----------------+        +------------------+
| Web/Mobile App |<------>| Relying Party    |
+----------------+        | Backend          |
                          +--------+---------+
                                   |
                 +-----------------+-----------------+
                 |                 |                 |
          +------v-----+    +------v-----+    +------v-----+
          | Nonce      |    | PPS State  |    | Audit Log  |
          | Store      |    | Database   |    | Store      |
          +------------+    +------------+    +------------+

3. Server Components

3.1. Registration Service

Handles:

user authentication before registration
registration nonce generation
registration payload verification
public key storage
duress key registration
device metadata storage

3.2. Challenge Service

Handles:

login or transaction challenge creation
nonce generation
policy object creation
transaction hash creation
QR code or deep link generation

3.3. Verification Service

Handles:

Pulse Token parsing
CBOR validation
signature verification
nonce validation
counter validation
rotation validation
policy validation
context validation
Trust Code validation
duress detection
threshold verification

3.4. Risk Engine

Handles:

device reputation
IP reputation
velocity checks
transaction limits
step-up authentication
duress response policy

3.5. Audit Service

Handles:

authentication logs
failed attempts
key rotations
duress events
threshold approvals
policy changes

4. Database Schema Example

This is an example schema. Adapt it to your database.

Devices

CREATE TABLE pps_devices (
  id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  user_id BIGINT UNSIGNED NOT NULL,
  kid VARCHAR(128) NOT NULL,
  current_pk VARCHAR(64) NOT NULL,
  key_seq BIGINT UNSIGNED NOT NULL DEFAULT 0,
  last_ctr BIGINT UNSIGNED NOT NULL DEFAULT 0,
  duress_pk VARCHAR(64) NULL,
  duress_key_seq BIGINT UNSIGNED NOT NULL DEFAULT 0,
  duress_last_ctr BIGINT UNSIGNED NOT NULL DEFAULT 0,
  revoked TINYINT(1) NOT NULL DEFAULT 0,
  created_at DATETIME NOT NULL,
  updated_at DATETIME NOT NULL,
  UNIQUE KEY unique_kid (kid),
  INDEX idx_user (user_id)
);

Nonces

CREATE TABLE pps_nonces (
  nonce VARCHAR(128) PRIMARY KEY,
  session_id VARCHAR(128) NOT NULL,
  user_id BIGINT UNSIGNED NULL,
  purpose VARCHAR(32) NOT NULL,
  created_at DATETIME NOT NULL,
  expires_at DATETIME NOT NULL,
  used TINYINT(1) NOT NULL DEFAULT 0,
  INDEX idx_session (session_id)
);

Threshold Groups

CREATE TABLE pps_threshold_groups (
  id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  gid VARCHAR(128) NOT NULL,
  user_id BIGINT UNSIGNED NOT NULL,
  rp_hash VARCHAR(64) NOT NULL,
  threshold TINYINT UNSIGNED NOT NULL,
  last_ctr BIGINT UNSIGNED NOT NULL DEFAULT 0,
  revoked TINYINT(1) NOT NULL DEFAULT 0,
  created_at DATETIME NOT NULL,
  updated_at DATETIME NOT NULL,
  UNIQUE KEY unique_gid (gid),
  INDEX idx_user (user_id)
);

Threshold Signers

CREATE TABLE pps_threshold_signers (
  id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  gid VARCHAR(128) NOT NULL,
  kid VARCHAR(128) NOT NULL,
  public_key VARCHAR(64) NOT NULL,
  revoked TINYINT(1) NOT NULL DEFAULT 0,
  created_at DATETIME NOT NULL,
  UNIQUE KEY unique_gid_kid (gid, kid)
);

Duress Events

CREATE TABLE pps_duress_events (
  id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  user_id BIGINT UNSIGNED NOT NULL,
  kid VARCHAR(128) NOT NULL,
  session_id VARCHAR(128) NULL,
  ip VARCHAR(45) NULL,
  user_agent TEXT NULL,
  created_at DATETIME NOT NULL,
  handled TINYINT(1) NOT NULL DEFAULT 0,
  INDEX idx_user (user_id)
);

5. Nonce Management

Nonces MUST be:

generated by a CSPRNG
at least 128 bits
single-use
time-limited
bound to a session or purpose

Recommended lifetime:

60 seconds

Recommended storage:

Redis or database with TTL

Example nonce record:

{
  "nonce": "base64url",
  "session_id": "base64url",
  "purpose": "login",
  "expires_at": "2026-07-23T12:01:00Z",
  "used": false
}

Mark nonce used only after successful verification.

6. Atomic State Updates

PPS state updates must be atomic.

Use database transactions and row locks.

Example:

SELECT * FROM pps_devices
WHERE kid = ?
FOR UPDATE;

Then verify and update:

UPDATE pps_devices
SET current_pk = ?,
    key_seq = ?,
    last_ctr = ?,
    updated_at = NOW()
WHERE kid = ?;

Never update counters before signature verification.

7. Rate Limiting

Rate limiting is mandatory for safe deployment.

Recommended limits:

failed attempts per account per 15 minutes
failed attempts per IP per hour
Trust Code attempt per session per 30 seconds

For Trust Code fallback:

8-digit code: strict rate limiting required
10-digit code: recommended
12-digit code: preferred

Use exponential backoff for repeated failures.

8. Logging

Log the following events:

registration
key rotation
successful authentication
failed authentication
nonce reuse
counter replay
invalid signature
Trust Code mismatch
duress event
threshold approval
device revocation
policy changes

Avoid logging:

private keys
full sensitive transaction data unless required
unnecessary personal data
raw biometric data

9. Monitoring and Alerts

Alert on:

sudden increase in failed authentications
repeated counter replay errors
repeated nonce reuse errors
duress events
impossible travel
high-value transactions
threshold failures
key state desynchronization
CBOR parsing anomalies

Duress alerts should be routed to a trained security response team.

10. Duress Response Playbook

When a Honey-Pulse is detected:

Do not reveal duress detection.
Return normal-looking success.
Restrict sensitive operations.
Limit transaction amounts.
Delay settlement if appropriate.
Create a silent security event.
Notify trained personnel.
Preserve audit logs.
Avoid automatic aggressive actions that may endanger the user.

Example outward response:

{
  "status": "ok"
}

Internal state:

{
  "risk_level": "duress",
  "account_mode": "restricted",
  "alert": "silent"
}

11. Migration From TOTP

A practical migration path:

Phase 1: Optional PPS

Keep TOTP enabled.
Allow users to register PPS devices.

Phase 2: Encourage PPS

Show security benefits.
Offer PPS for high-value actions.

Phase 3: Step-Up

Require PPS for sensitive operations.
Keep TOTP fallback for low-risk actions.

Phase 4: Deprecate TOTP

Remove TOTP for users with PPS devices.
Provide recovery options.

12. Recovery

Users may lose devices.

Recovery options:

secondary registered device
encrypted cloud backup
recovery codes
social recovery
admin-assisted recovery
time-locked recovery
threshold recovery

Recovery must be protected against social engineering.

13. Key Rotation

Devices should support periodic key rotation.

Rotation flow:

Authenticate with existing trusted device.
Generate new key pair.
Register new public key.
Revoke old key if appropriate.

PPS ratcheting provides automatic per-Pulse rotation in single-device mode.

14. High Availability

For production systems:

replicate nonce store
replicate PPS state database
use atomic transactions
avoid split-brain counter updates
use idempotency keys
monitor queue backlogs
test failover

15. Privacy

Recommended privacy practices:

use pairwise kid values per RP
avoid personal data in kid
hash IP addresses if stored
minimize user agent storage
encrypt logs
restrict access to duress events
define retention periods
comply with applicable privacy laws

16. Compliance

Depending on jurisdiction and industry, consider:

GDPR
PCI DSS
PSD2
SOC 2
ISO 27001
local banking regulations
local crypto-asset regulations

PPS does not automatically satisfy any compliance regime.

17. Production Checklist

Before production deployment: