Add per-key configuration to enable/disable the BLS Proof of Possession (POP) endpoint, with comprehensive documentation and improved logging to guide operators. Currently, the /bls_prove_possession/{key} endpoint is always available for any configured BLS key, but operators need granular control over when this feature is enabled for security and operational reasons.

Current Behavior

Signatory fully implements BLS POP functionality with the /bls_prove_possession/{key} endpoint. The endpoint is always available for any configured BLS key with no way to disable it for specific keys or require explicit opt-in.

Why Configuration Control is Needed

Based on Octez's security model and operational best practices:

1. POP is a setup-time operation, not runtime: Only needed during initial key reveal, consensus key updates, and companion key registration. Not needed for daily signing operations.

2. Security principle: Octez's own signer has POP disabled by default and requires explicit opt-in. Signatory should follow the same secure-by-default approach.

3. Minimize attack surface: POP requests can confirm key existence (enumeration risk), potentially be used for DoS attacks on vault backends, and reveal cryptographic information about the key.

4. Operational lifecycle: Operators want to enable POP temporarily during key setup, then disable it during production operations, with different policies for different keys.

Requirements

1. Configuration Schema

Add allow_proof_of_possession field to per-key policy configuration.

Example configuration:

tezos:
  tz4YourMultisigKey:
    allow:
      block:
      attestation:
    allow_proof_of_possession: true  # Explicitly enable for this key
    
  tz4YourBakingKey:
    allow:
      block:
      attestation:
      attestation_with_dal:
    # allow_proof_of_possession: false (default - disabled)

Configuration requirements:

• Default: disabled - Secure by default, must explicitly enable per key
• Per-key control only - No global flag
• Simple boolean - true = allow, false or absent = deny
• Consistent with existing patterns - Follows same structure as other policy fields

2. Behavior Requirements

• POP requests for keys without allow_proof_of_possession: true must be denied with HTTP 403 Forbidden
• POP requests for keys with allow_proof_of_possession: true proceed normally
• Policy must be checked before any vault operations are performed
• Must work seamlessly with existing authentication and policy hook mechanisms

3. Logging Requirements

When POP request is denied:

• Log at WARN level
• Single-line message that clearly states POP is not allowed for the key
• Include the key hash
• Include actionable guidance: mention that allow_proof_of_possession: true must be set in config
• Include brief context on when POP is required (key reveals, consensus key updates, companion key registration)

When POP request is allowed:

• Log at INFO level when POP is requested
• Log at INFO level when POP completes successfully
• Include key hash and source IP for audit trail

Goal: Operators should never feel stuck - denied requests should clearly explain what to do next.

4. Documentation Requirements

Create comprehensive documentation covering:

When POP is Required

• Initial BLS key reveals (first transaction from a tz4 address)
• Consensus key updates (updating a delegate's consensus key to tz4)
• Companion key registration (registering a tz4 companion key for DAL)
• BLS multisig setup scenarios

When POP is NOT Needed

• Regular signing operations (blocks, attestations, transactions)
• After initial reveal is complete
• For non-BLS keys (tz1, tz2, tz3)

POP Lifecycle & Operational Patterns

Document typical workflows:

Initial Setup Pattern:

• Enable POP in config for new key
• Perform reveal operation with octez-client
• Disable POP after reveal succeeds
• Key is now ready for production signing

Multisig Pattern:

• Some multisig keys may need POP enabled permanently
• Document when and why this is needed

Mixed Deployment Pattern:

• Multiple keys at different lifecycle stages
• Some keys in production (POP disabled)
• Some keys being set up (POP enabled)
• Show example config

Security Considerations

• Why POP is disabled by default
• What information POP reveals
• Potential risks (enumeration, DoS)
• Best practice: Enable temporarily during setup, disable for production
• Why per-key control is better than global control

Troubleshooting Guide

Common scenarios and solutions:

• Error: POP not allowed → Add config setting
• Error: POP not supported → Check vault backend or key type
• Error: Key not in config → Add key to tezos section

Integration with Octez

• Which octez-client commands trigger POP requests
• How automatic POP generation works during reveals
• Compatibility notes

5. Testing Requirements

Tests must verify:

• POP requests denied by default (when field not set)
• POP requests allowed when explicitly enabled
• Correct HTTP status codes
• Logging includes helpful guidance
• Per-key policies work independently
• No interference with other policy mechanisms (JWT, authorized keys, policy hooks)

6. Backward Compatibility

This is a breaking change for users currently using BLS keys:

• Existing configs without allow_proof_of_possession will default to disabled
• Users will need to add the config setting to continue using POP
• Release notes must include clear migration guidance
• Consider transition period or warnings

7. Additional Considerations

Config Validation:

• Consider warning if allow_proof_of_possession: true is set for non-BLS keys

Metrics (optional enhancement):

• Consider adding metrics for POP request counts (allowed/denied)
• Useful for security monitoring and operational awareness

Future Enhancements (not required initially):

• Time-limited POP (auto-disable after timestamp)
• One-time POP (auto-disable after first use)
• Request count limits per key

Success Criteria

This feature is complete when:

1. ✅ Configuration option exists and works per-key
2. ✅ POP is denied by default (secure by default)
3. ✅ Denied requests log helpful, single-line guidance
4. ✅ Allowed requests log audit information
5. ✅ Comprehensive documentation covers all required topics
6. ✅ Tests verify deny/allow behavior
7. ✅ Release notes include migration guidance for existing BLS users

References

• Octez signer behavior: Disabled by default, requires explicit opt-in flag
• Octez protocol: POP required for BLS key reveals, consensus key updates, companion keys
• Security context: Prevents rogue key attacks in BLS aggregation scenarios