fix(program): enforce canonical PDA validation on init

Restore canonical bump enforcement for instruction-provided PDA bumps while preserving a fast path for trusted stored bumps.

Add integration regressions that verify noncanonical-but-valid PDA addresses are rejected for escrow, allowed mint, receipt, and extensions initialization flows.

Author: dev-jodee

program/src/state/allowed_mint.rs

@@ -65,8 +65,14 @@ impl AllowedMint {
         mint: &Address,
     ) -> Result<&'a Self, ProgramError> {
         let state = Self::from_bytes(data)?;
-        let pda = AllowedMintPda::new(escrow, mint);
-        pda.validate_pda(account, program_id, state.bump)?;
+        let derived = Address::derive_address(
+            &[AllowedMintPda::PREFIX, escrow.as_ref(), mint.as_ref()],
+            Some(state.bump),
+            program_id,
+        );
+        if account.address() != &derived {
+            return Err(ProgramError::InvalidSeeds);
+        }
         Ok(state)
     }
 }

program/src/traits/pda.rs

@@ -21,12 +21,33 @@ pub trait PdaSeeds {
         Address::find_program_address(&seeds, program_id)
     }
 
-    /// Validate that account matches derived PDA using `create_program_address` (~1500 CU).
+    /// Validate that account matches the canonical PDA for these seeds.
     ///
-    /// Cheaper than `find_program_address` since bump is already known.
-    /// Use `validate_self` instead when the bump is stored in the account.
+    /// This enforces the canonical bump (highest valid bump) returned by
+    /// `find_program_address`.
     #[inline(always)]
-    fn validate_pda(&self, account: &AccountView, program_id: &Address, bump: u8) -> Result<(), ProgramError> {
+    fn validate_pda(&self, account: &AccountView, program_id: &Address, expected_bump: u8) -> Result<(), ProgramError> {
+        let (derived, bump) = self.derive_address(program_id);
+        if bump != expected_bump {
+            return Err(ProgramError::InvalidSeeds);
+        }
+        if account.address() != &derived {
+            return Err(ProgramError::InvalidSeeds);
+        }
+        Ok(())
+    }
+
+    /// Validate that account matches PDA derived with the provided bump.
+    ///
+    /// This does not enforce canonical bump selection. Use `validate_pda`
+    /// when canonical bump invariants must be enforced (e.g., account creation).
+    #[inline(always)]
+    fn validate_pda_with_bump(
+        &self,
+        account: &AccountView,
+        program_id: &Address,
+        bump: u8,
+    ) -> Result<(), ProgramError> {
         let seeds = self.seeds();
         let bump_arr = [bump];
         let mut seeds_with_bump = seeds;
@@ -62,7 +83,7 @@ pub trait PdaAccount: PdaSeeds {
     /// Validate that account matches derived PDA using stored bump
     #[inline(always)]
     fn validate_self(&self, account: &AccountView, program_id: &Address) -> Result<(), ProgramError> {
-        self.validate_pda(account, program_id, self.bump())
+        self.validate_pda_with_bump(account, program_id, self.bump())
     }
 }
 

tests/integration-tests/src/test_add_timelock.rs

@@ -2,9 +2,9 @@ use crate::{
     fixtures::{AddTimelockFixture, CreateEscrowFixture, SetImmutableFixture},
     utils::{
         assert_escrow_error, assert_extensions_header, assert_instruction_error, assert_timelock_extension,
-        find_escrow_pda, find_extensions_pda, test_empty_data, test_missing_signer, test_not_writable,
-        test_truncated_data, test_wrong_account, test_wrong_current_program, test_wrong_system_program, EscrowError,
-        InstructionTestFixture, TestContext, RANDOM_PUBKEY,
+        find_escrow_pda, find_extensions_pda, find_noncanonical_program_address, test_empty_data, test_missing_signer,
+        test_not_writable, test_truncated_data, test_wrong_account, test_wrong_current_program,
+        test_wrong_system_program, EscrowError, InstructionTestFixture, TestContext, RANDOM_PUBKEY,
     },
 };
 use solana_sdk::{instruction::InstructionError, signature::Signer};
@@ -53,6 +53,24 @@ fn test_add_timelock_invalid_extensions_bump() {
     assert_instruction_error(error, InstructionError::InvalidSeeds);
 }
 
+#[test]
+fn test_add_timelock_noncanonical_extensions_pda_rejected() {
+    let mut ctx = TestContext::new();
+    let test_ix = AddTimelockFixture::build_valid(&mut ctx);
+    let escrow = test_ix.instruction.accounts[2].pubkey;
+    let program_id = test_ix.instruction.program_id;
+
+    let (noncanonical_extensions, noncanonical_bump) =
+        find_noncanonical_program_address(&[b"extensions", escrow.as_ref()], &program_id)
+            .expect("expected at least one noncanonical bump");
+
+    let error = test_ix
+        .with_account_at(3, noncanonical_extensions)
+        .with_data_byte_at(1, noncanonical_bump)
+        .send_expect_error(&mut ctx);
+    assert_instruction_error(error, InstructionError::InvalidSeeds);
+}
+
 #[test]
 fn test_add_timelock_empty_data() {
     let mut ctx = TestContext::new();

tests/integration-tests/src/test_allow_mint.rs

@@ -2,8 +2,9 @@ use crate::{
     fixtures::{AllowMintFixture, AllowMintSetup},
     utils::{
         assert_account_exists, assert_allowed_mint_account, assert_escrow_error, assert_instruction_error,
-        find_allowed_mint_pda, test_missing_signer, test_not_writable, test_wrong_current_program,
-        test_wrong_system_program, EscrowError, InstructionTestFixture, TestContext, RANDOM_PUBKEY,
+        find_allowed_mint_pda, find_noncanonical_program_address, test_missing_signer, test_not_writable,
+        test_wrong_current_program, test_wrong_system_program, EscrowError, InstructionTestFixture, TestContext,
+        RANDOM_PUBKEY,
     },
 };
 use escrow_program_client::instructions::{AllowMintBuilder, SetImmutableBuilder};
@@ -64,6 +65,26 @@ fn test_allow_mint_invalid_bump() {
     assert_instruction_error(error, InstructionError::InvalidSeeds);
 }
 
+#[test]
+fn test_allow_mint_noncanonical_pda_rejected() {
+    let mut ctx = TestContext::new();
+    let setup = AllowMintSetup::new(&mut ctx);
+    let valid_ix = setup.build_instruction(&ctx);
+    let program_id = valid_ix.instruction.program_id;
+
+    let (noncanonical_allowed_mint, noncanonical_bump) = find_noncanonical_program_address(
+        &[b"allowed_mint", setup.escrow_pda.as_ref(), setup.mint_pubkey.as_ref()],
+        &program_id,
+    )
+    .expect("expected at least one noncanonical bump");
+
+    let error = valid_ix
+        .with_account_at(5, noncanonical_allowed_mint)
+        .with_data_byte_at(1, noncanonical_bump)
+        .send_expect_error(&mut ctx);
+    assert_instruction_error(error, InstructionError::InvalidSeeds);
+}
+
 #[test]
 fn test_allow_mint_wrong_admin() {
     let mut ctx = TestContext::new();

tests/integration-tests/src/test_create_escrow.rs

@@ -1,8 +1,8 @@
 use crate::{
     fixtures::CreateEscrowFixture,
     utils::{
-        assert_escrow_account, assert_escrow_mutability, assert_instruction_error, test_empty_data,
-        test_missing_signer, test_not_writable, test_wrong_account, test_wrong_current_program,
+        assert_escrow_account, assert_escrow_mutability, assert_instruction_error, find_noncanonical_program_address,
+        test_empty_data, test_missing_signer, test_not_writable, test_wrong_account, test_wrong_current_program,
         test_wrong_system_program, InstructionTestFixture, TestContext,
     },
 };
@@ -70,6 +70,25 @@ fn test_create_escrow_invalid_bump() {
     assert_instruction_error(error, InstructionError::InvalidSeeds);
 }
 
+#[test]
+fn test_create_escrow_noncanonical_bump_rejected() {
+    let mut ctx = TestContext::new();
+    let valid_ix = CreateEscrowFixture::build_valid(&mut ctx);
+
+    let escrow_seed = valid_ix.instruction.accounts[2].pubkey;
+    let program_id = valid_ix.instruction.program_id;
+    let (noncanonical_escrow, noncanonical_bump) =
+        find_noncanonical_program_address(&[b"escrow", escrow_seed.as_ref()], &program_id)
+            .expect("expected at least one noncanonical bump");
+
+    let error = valid_ix
+        .with_account_at(3, noncanonical_escrow)
+        .with_data_byte_at(1, noncanonical_bump)
+        .send_expect_error(&mut ctx);
+
+    assert_instruction_error(error, InstructionError::InvalidSeeds);
+}
+
 #[test]
 fn test_create_escrow_empty_data() {
     let mut ctx = TestContext::new();

tests/integration-tests/src/test_deposit.rs

@@ -4,10 +4,10 @@ use crate::{
         DEFAULT_DEPOSIT_AMOUNT,
     },
     utils::{
-        assert_custom_error, assert_escrow_error, assert_instruction_error, find_receipt_pda, test_empty_data,
-        test_missing_signer, test_not_writable, test_wrong_account, test_wrong_current_program, test_wrong_owner,
-        test_wrong_system_program, test_wrong_token_program, EscrowError, TestContext, TestInstruction,
-        TEST_HOOK_ALLOW_ID, TEST_HOOK_DENY_ERROR, TEST_HOOK_DENY_ID,
+        assert_custom_error, assert_escrow_error, assert_instruction_error, find_noncanonical_program_address,
+        find_receipt_pda, test_empty_data, test_missing_signer, test_not_writable, test_wrong_account,
+        test_wrong_current_program, test_wrong_owner, test_wrong_system_program, test_wrong_token_program, EscrowError,
+        TestContext, TestInstruction, TEST_HOOK_ALLOW_ID, TEST_HOOK_DENY_ERROR, TEST_HOOK_DENY_ID,
     },
 };
 use escrow_program_client::instructions::DepositBuilder;
@@ -84,6 +84,29 @@ fn test_deposit_invalid_bump() {
     assert_instruction_error(error, InstructionError::InvalidSeeds);
 }
 
+#[test]
+fn test_deposit_noncanonical_receipt_pda_rejected() {
+    let mut ctx = TestContext::new();
+    let setup = DepositSetup::new(&mut ctx);
+    let valid_ix = setup.build_instruction(&ctx);
+    let program_id = valid_ix.instruction.program_id;
+
+    let depositor = setup.depositor.pubkey();
+    let mint = setup.mint.pubkey();
+    let receipt_seed = setup.receipt_seed.pubkey();
+    let (noncanonical_receipt, noncanonical_bump) = find_noncanonical_program_address(
+        &[b"receipt", setup.escrow_pda.as_ref(), depositor.as_ref(), mint.as_ref(), receipt_seed.as_ref()],
+        &program_id,
+    )
+    .expect("expected at least one noncanonical bump");
+
+    let error = valid_ix
+        .with_account_at(5, noncanonical_receipt)
+        .with_data_byte_at(1, noncanonical_bump)
+        .send_expect_error(&mut ctx);
+    assert_instruction_error(error, InstructionError::InvalidSeeds);
+}
+
 #[test]
 fn test_deposit_wrong_token_program() {
     let mut ctx = TestContext::new();

tests/integration-tests/src/utils/pda_utils.rs

@@ -20,3 +20,23 @@ pub fn find_receipt_pda(escrow: &Pubkey, depositor: &Pubkey, mint: &Pubkey, rece
 pub fn find_allowed_mint_pda(escrow: &Pubkey, mint: &Pubkey) -> (Pubkey, u8) {
     AllowedMint::find_pda(escrow, mint)
 }
+
+pub fn find_noncanonical_program_address(seeds: &[&[u8]], program_id: &Pubkey) -> Option<(Pubkey, u8)> {
+    let (_, canonical_bump) = Pubkey::find_program_address(seeds, program_id);
+
+    for bump in (0u8..=u8::MAX).rev() {
+        if bump == canonical_bump {
+            continue;
+        }
+
+        let bump_seed = [bump];
+        let mut seeds_with_bump = seeds.to_vec();
+        seeds_with_bump.push(&bump_seed);
+
+        if let Ok(address) = Pubkey::create_program_address(&seeds_with_bump, program_id) {
+            return Some((address, bump));
+        }
+    }
+
+    None
+}