pulseproof-sentinel

PPS Threshold Guide

This guide explains threshold mode in PulseProof Sentinel Protocol, abbreviated PPS.

Threshold mode allows multiple devices to approve the same authentication or transaction.

1. Why Threshold Mode?

Some actions are too sensitive for a single device.

Examples:

Threshold mode requires multiple devices to approve the same Pulse.

2. PPS Version 1 Threshold Model

PPS version 1 uses n-of-m Ed25519 multisignature.

Example:

2-of-3:
  phone
  watch
  laptop

Any two devices can approve.

This is multisignature, not a true threshold signature.

Each device produces an independent Ed25519 signature over the same payload.

3. Multisig vs Threshold Signature

Multisig

signature_1 by device_1
signature_2 by device_2
server verifies both

Advantages:

Disadvantages:

True Threshold Signature

Example:

FROST

Advantages:

Disadvantages:

PPS version 1 chooses multisig for implementability.

Future PPS versions may define FROST-based profiles.

4. Threshold Group Registration

A threshold group contains:

gid
rp_hash
signers
threshold
last_ctr
revoked

Example:

{
  "gid": "base64url_group_id",
  "rp_hash": "base64url_sha256_rp",
  "threshold": 2,
  "signers": {
    "phone_kid": "base64url_phone_pk",
    "watch_kid": "base64url_watch_pk",
    "laptop_kid": "base64url_laptop_pk"
  }
}

The server stores public keys for each signer.

5. Threshold Pulse Payload

Threshold mode uses:

20: gid
21: thr

Threshold mode omits single-device ratchet fields:

4: kid
9: pk
10: next_pk
15: rot_seq

Example logical payload:

{
  "1": 1,
  "2": 2,
  "3": "PPS-ED25519-CBOR30",
  "5": "base64url_rp_hash",
  "6": 58972480,
  "7": 42,
  "8": 58972482,
  "11": "base64url_nonce",
  "12": "base64url_ctx",
  "13": "base64url_pol",
  "14": 67,
  "20": "base64url_gid",
  "21": 2
}

6. Threshold Signing Flow

1. Initiating device creates Pulse payload.
2. Payload is shared with other devices.
3. Each device verifies transaction details.
4. Each device asks for user confirmation.
5. Each device signs the same payload.
6. Signatures are collected.
7. Final envelope contains all signatures.
8. Server verifies required signatures.

7. Offline Co-Signing

Threshold mode can work offline using local channels.

Possible channels:

Example QR flow:

Phone creates payload QR.
Watch scans QR.
Watch signs.
Watch returns signature QR.
Phone collects signature.
Phone submits final Pulse.

Example BLE flow:

Phone broadcasts payload.
Watch receives payload.
Watch signs.
Watch sends signature back.
Phone assembles envelope.

8. Envelope With Multiple Signatures

The Pulse envelope signature map may contain multiple signatures:

{
  "m": "base64url_cbor_pulse_payload",
  "s": {
    "phone_kid": "base64url_signature_1",
    "watch_kid": "base64url_signature_2"
  }
}

The server verifies each signature over the same m message.

9. Threshold Verification

Server MUST:

  1. Load threshold group by gid.
  2. Reject if group is revoked.
  3. Verify thr equals stored threshold.
  4. Verify signature map contains at least thr distinct signers.
  5. Verify each signer is registered.
  6. Verify each signature using signer public key.
  7. Verify all signatures are over the same message.
  8. Verify nonce, epoch, expiration, context, policy, and AmountMark.
  9. Verify ctr > group_last_ctr.
  10. Update group_last_ctr.

Do not trust the client-provided threshold alone.

Always use the server-stored threshold.

10. Threshold Counter

Threshold groups should have a separate monotonic counter:

group_last_ctr

This prevents replay of threshold Pulses.

The counter is updated only after successful verification.

11. Threshold and Transaction Binding

Threshold mode is especially useful for transaction signing.

The context object should include:

tx_hash
session_id

Each co-signing device should display:

amount
currency
recipient
action
expiration
Trust Code
AmountMark

Users should approve only after verifying details.

12. Threshold Trust Code

For threshold mode, the Trust Code is derived after collecting required signatures.

trust_ikm = SHA256(cbor(signatures_map))

Individual devices may display local confirmation codes, but the final Trust Code is based on the full signature map.

13. Threshold and Duress

Threshold mode can be combined with duress.

Possible policies:

Policy A: Any Duress Signature Triggers Duress

If any required signer uses a duress key, the whole Pulse is treated as duress.

Policy B: Majority Duress

If most signers use duress keys, treat as duress.

Policy C: Primary Device Duress

Only the primary device’s duress key matters.

The policy must be explicit and tested.

14. UX Recommendations

Threshold UX should be clear.

Example initiating device:

Approval required

This transaction requires 2 devices.

Devices:
  Phone: approved
  Watch: waiting
  Laptop: waiting

Amount: 2,500,067 IRR
Trust Code: 49371867

Example secondary device:

Approve transaction?

Amount: 2,500,067 IRR
To: IR820540102680020817909002
Initiated by: Phone
Trust Code: 49371867

[Reject] [Approve]

15. Security Considerations

15.1. Device Diversity

Use different device types when possible:

phone + watch
phone + hardware key
phone + laptop

Avoid threshold devices that share the same backup or cloud sync if separation is required.

15.2. Coercion

Threshold does not prevent coercion of multiple devices.

Combine with duress mechanisms.

15.3. Malware

Malware on one device may be mitigated by requiring another device.

Malware on enough devices defeats threshold protection.

15.4. Relay Attacks

Offline local channels can be relayed.

Use short-lived challenges and user confirmation.

15.5. Signer Identification

In PPS v1 multisig, the server can see which devices signed.

If signer anonymity is required, consider future threshold signature profiles.

16. Future Threshold Profiles

Future PPS versions may define:

PPS-FROST-ED25519-CBOR30

Possible features:

17. Summary

PPS threshold mode provides offline multi-device approval using simple Ed25519 multisignature.

It is suitable for:

It is intentionally simple in version 1 to encourage implementation and review.