GAP-M4: BIP-322 Signature Format Standardization¶

Message Hash = SHA256_tag("BIP0322-signed-message", message)
             = SHA256(SHA256("BIP0322-signed-message") || SHA256("BIP0322-signed-message") || message)

to_spend:
  nVersion = 0
  vin[0].scriptSig = OP_0 PUSH32[message_hash]
  vout[0].scriptPubKey = message_challenge (address)

to_sign:
  vin[0].prevout = to_spend.txid:0
  vin[0].scriptWitness = message_signature
  vout[0].scriptPubKey = OP_RETURN

┌─────────────────────────────────────────────────────────────────────────────┐
│                           Signature Provider Interface                       │
│                           (Abstract Base Class)                              │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌─────────────────────┐  ┌─────────────────────┐  ┌─────────────────────┐  │
│  │  Ed25519Provider    │  │  BIP322Provider     │  │  HybridPQProvider   │  │
│  │  (Legacy/Fallback)  │  │  (BIP-340 Schnorr)  │  │  (Future: GAP-Q1)   │  │
│  └─────────────────────┘  └─────────────────────┘  └─────────────────────┘  │
│           │                        │                        │               │
│           └────────────────────────┼────────────────────────┘               │
│                                    │                                        │
│                                    ▼                                        │
│                    ┌───────────────────────────────┐                        │
│                    │   DualSignatureValidator      │                        │
│                    │   (Updated: Provider-based)   │                        │
│                    └───────────────────────────────┘                        │
│                                    │                                        │
│                                    ▼                                        │
│                    ┌───────────────────────────────┐                        │
│                    │     OverrideWorkflow          │                        │
│                    │     (Unchanged API)           │                        │
│                    └───────────────────────────────┘                        │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Risk Lead   │     │ Security Lead│     │   Proposer   │
└──────┬───────┘     └──────┬───────┘     └──────┬───────┘
       │                    │                    │
       │ sign(message)      │ sign(message)      │ request_override()
       ▼                    ▼                    ▼
┌──────────────────────────────────────────────────────────┐
│                   OverrideWorkflow                        │
│  ┌─────────────────────────────────────────────────────┐ │
│  │  DualSignatureValidator                              │ │
│  │  ┌─────────────────────┐ ┌────────────────────────┐ │ │
│  │  │ create_message_hash │ │ validate_signature     │ │ │
│  │  │ (BIP-340 tagged)    │ │ (provider-delegated)   │ │ │
│  │  └─────────────────────┘ └────────────────────────┘ │ │
│  │              │                      │               │ │
│  │              ▼                      ▼               │ │
│  │  ┌─────────────────────────────────────────────────┐│ │
│  │  │           SignatureProvider (interface)         ││ │
│  │  │  ┌──────────────┐  ┌──────────────────────────┐ ││ │
│  │  │  │ Ed25519      │  │ BIP322Provider           │ ││ │
│  │  │  │ (deprecated) │  │ • sign(key, msg_hash)    │ ││ │
│  │  │  │              │  │ • verify(sig, msg, pk)   │ ││ │
│  │  │  │              │  │ • generate_keypair()     │ ││ │
│  │  │  └──────────────┘  └──────────────────────────┘ ││ │
│  │  └─────────────────────────────────────────────────┘│ │
│  └─────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────┘

"""Cryptographic primitives for AEGIS."""
from .providers import SignatureProvider, Ed25519Provider, BIP322Provider
from .bip340 import tagged_hash, BIP322_TAG

"""BIP-340 tagged hash implementation."""
import hashlib

BIP322_TAG = b"BIP0322-signed-message"

def tagged_hash(tag: bytes, message: bytes) -> bytes:
    """
    Compute BIP-340 tagged hash.

    H_tag(m) = SHA256(SHA256(tag) || SHA256(tag) || m)

    Args:
        tag: Tag bytes (e.g., BIP322_TAG)
        message: Message to hash

    Returns:
        32-byte tagged hash
    """
    tag_hash = hashlib.sha256(tag).digest()
    return hashlib.sha256(tag_hash + tag_hash + message).digest()

"""Signature provider interface and implementations."""
from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import Protocol, Tuple

@dataclass
class SignatureResult:
    """Result of a signing operation."""
    signature: bytes
    public_key: bytes
    algorithm: str
    message_hash: bytes

class SignatureProvider(Protocol):
    """Protocol for signature providers."""

    @property
    def algorithm_name(self) -> str:
        """Return algorithm identifier (e.g., 'bip322', 'ed25519')."""
        ...

    def generate_keypair(self) -> Tuple[bytes, bytes]:
        """Generate (private_key, public_key) pair."""
        ...

    def sign(self, message_hash: bytes, private_key: bytes) -> bytes:
        """Sign message hash with private key."""
        ...

    def verify(self, signature: bytes, message_hash: bytes, public_key: bytes) -> bool:
        """Verify signature against message hash and public key."""
        ...

"""BIP-322 signature provider using btclib."""
import base64
from typing import Tuple

from btclib.ecc import Curve
from btclib.bip340 import sign as schnorr_sign, verify as schnorr_verify
from btclib.hashes import tagged_hash as btclib_tagged_hash

from .providers import SignatureProvider
from .bip340 import BIP322_TAG, tagged_hash

# secp256k1 curve for Bitcoin
SECP256K1 = Curve.secp256k1()

class BIP322Provider:
    """
    BIP-322 Simple signature provider.

    Uses BIP-340 Schnorr signatures on secp256k1 curve.
    Implements the Simple format (witness stack, base64-encoded).

    Security Properties:
        - 128-bit security level
        - Non-malleable (x-only pubkeys)
        - Batch-verifiable (future optimization)
        - Compatible with Bitcoin Taproot
    """

    @property
    def algorithm_name(self) -> str:
        return "bip322-simple"

    def generate_keypair(self) -> Tuple[bytes, bytes]:
        """
        Generate secp256k1 keypair for BIP-340 signing.

        Returns:
            (private_key, x_only_public_key) as 32-byte each
        """
        from btclib.ecc import SSA

        # Generate random private key
        private_key = SSA.gen_keys()

        # Get x-only public key (BIP-340 format)
        x_only_pubkey = private_key.pubkey.x.to_bytes(32, 'big')

        return private_key.key.to_bytes(32, 'big'), x_only_pubkey

    def create_message_hash(
        self,
        proposal_id: str,
        justification: str,
        failed_gates: list[str],
    ) -> bytes:
        """
        Create BIP-322 message hash for signing.

        Uses BIP-340 tagged hash with "BIP0322-signed-message" tag.

        Args:
            proposal_id: Proposal identifier
            justification: Override justification
            failed_gates: List of failed gate names

        Returns:
            32-byte message hash
        """
        import json

        canonical = json.dumps(
            {
                "proposal_id": proposal_id,
                "justification": justification,
                "failed_gates": sorted(failed_gates),
                "version": "1.0",
            },
            sort_keys=True,
        )

        return tagged_hash(BIP322_TAG, canonical.encode())

    def sign(self, message_hash: bytes, private_key: bytes) -> bytes:
        """
        Sign message hash with BIP-340 Schnorr.

        Args:
            message_hash: 32-byte message hash
            private_key: 32-byte secp256k1 private key

        Returns:
            64-byte Schnorr signature
        """
        return schnorr_sign(message_hash, private_key)

    def verify(
        self,
        signature: bytes,
        message_hash: bytes,
        public_key: bytes,
    ) -> bool:
        """
        Verify BIP-340 Schnorr signature.

        Args:
            signature: 64-byte signature
            message_hash: 32-byte message hash
            public_key: 32-byte x-only public key

        Returns:
            True if valid, False otherwise
        """
        try:
            return schnorr_verify(message_hash, public_key, signature)
        except Exception:
            return False

    def encode_simple(self, signature: bytes) -> str:
        """
        Encode signature in BIP-322 Simple format.

        Simple format: base64(witness_stack)
        For single-sig, witness = [signature]

        Args:
            signature: 64-byte Schnorr signature

        Returns:
            Base64-encoded witness stack
        """
        # Witness stack: length-prefixed signature
        # For simple single-sig: just the signature
        witness = bytes([len(signature)]) + signature
        return base64.b64encode(witness).decode('ascii')

    def decode_simple(self, encoded: str) -> bytes:
        """
        Decode BIP-322 Simple format to raw signature.

        Args:
            encoded: Base64-encoded witness stack

        Returns:
            64-byte Schnorr signature
        """
        witness = base64.b64decode(encoded)
        # Extract signature (skip length prefix)
        sig_len = witness[0]
        return witness[1:1+sig_len]

# Add at top of file
from src.crypto.providers import SignatureProvider
from src.crypto.bip322_provider import BIP322Provider
from src.crypto.ed25519_provider import Ed25519Provider  # Existing, wrapped

class DualSignatureValidator:
    """
    Validate dual signatures for override authorization.

    Supports multiple signature providers:
    - BIP322Provider: BIP-340 Schnorr (recommended)
    - Ed25519Provider: Ed25519 (legacy, deprecated)

    Provider is selected at initialization and applies to all operations.
    """

    REQUIRED_ROLES = {"risk_lead", "security_lead"}

    def __init__(
        self,
        expiration_hours: int = 24,
        provider: SignatureProvider | None = None,
    ):
        """
        Initialize validator with signature provider.

        Args:
            expiration_hours: Hours until override request expires
            provider: Signature provider (default: BIP322Provider)
        """
        self.expiration_hours = expiration_hours
        self.provider = provider or BIP322Provider()

    def create_message_hash(
        self,
        proposal_id: str,
        justification: str,
        failed_gates: list[str],
    ) -> str:
        """
        Create canonical message hash for signing.

        Uses provider-specific hash algorithm:
        - BIP322: BIP-340 tagged hash
        - Ed25519: SHA-256 of JSON

        Returns:
            Hex-encoded message hash
        """
        if hasattr(self.provider, 'create_message_hash'):
            return self.provider.create_message_hash(
                proposal_id, justification, failed_gates
            ).hex()
        else:
            # Fallback for legacy providers
            return self._legacy_message_hash(
                proposal_id, justification, failed_gates
            )

    def validate_signature(
        self,
        signature: str,
        message_hash: str,
        public_key: str,
    ) -> bool:
        """
        Validate signature using configured provider.

        Args:
            signature: Base64-encoded signature
            message_hash: Hex-encoded message hash
            public_key: Base64-encoded public key

        Returns:
            True if valid
        """
        try:
            sig_bytes = base64.b64decode(signature)
            msg_bytes = bytes.fromhex(message_hash)
            key_bytes = base64.b64decode(public_key)

            return self.provider.verify(sig_bytes, msg_bytes, key_bytes)
        except Exception as e:
            logger.warning(f"Signature validation failed: {e}")
            return False

import warnings

class Ed25519Provider:
    def __init__(self):
        warnings.warn(
            "Ed25519Provider is deprecated and will be removed in v2.0. "
            "Use BIP322Provider for new implementations.",
            DeprecationWarning,
            stacklevel=2
        )

signature_provider:
  type: string
  enum: ["bip322", "ed25519"]
  default: "bip322"
  description: "Signature algorithm for override workflow"
  deprecated_values:
    ed25519: "Deprecated in v1.2, removed in v2.0"

# Add new dependency
echo "btclib>=2023.7.12" >> requirements.txt
pip install -r requirements.txt

# Run existing tests (ensure no breakage)
pytest tests/workflows/test_override.py -v

# Create new test file
touch tests/crypto/test_bip322.py

# tests/crypto/test_bip322.py
import pytest
from src.crypto.bip340 import tagged_hash, BIP322_TAG

class TestBIP340TaggedHash:
    """BIP-322 test vectors from specification."""

    def test_empty_message(self):
        result = tagged_hash(BIP322_TAG, b"")
        expected = bytes.fromhex(
            "c90c269c4f8fcbe6880f72a721ddfbf1914268a794cbb21cfafee13770ae19f1"
        )
        assert result == expected

    def test_hello_world(self):
        result = tagged_hash(BIP322_TAG, b"Hello World")
        expected = bytes.fromhex(
            "f0eb03b1a75ac6d9847f55c624a99169b5dccba2a31f5b23bea77ba270de0a7a"
        )
        assert result == expected

# Add to existing CI
- name: Test BIP-322 module
  run: |
    pytest tests/crypto/ -v --cov=src/crypto
    pytest tests/workflows/test_override.py -v

# requirements.txt additions
btclib>=2023.7.12  # BIP-340 Schnorr, secp256k1