feat(admin): privileged admin module with two-step rotation and audit events

- Two-step admin rotation (propose_admin / accept_admin / cancel_admin).
  Incoming admin must prove key control before handoff completes, preventing
  lockout from typos or uncontrolled keys. cancel_admin lets current admin
  withdraw a pending proposal.

- require_admin() helper loads admin from storage and calls require_auth();
  cannot be spoofed by mismatched signers.

- set_token: update treasury token address with old/new audit event.

- pause / unpause: circuit-breaker for file_claim and vote_on_claim;
  existing votes and tallies are unaffected.

- drain: emergency treasury recovery; admin must authorize; amount > 0
  enforced before token::transfer is invoked.

- initialize guard: AlreadyInitialized prevents re-initialization attacks.

- All mutations emit structured events keyed on ('admin', '<action>') so
  NestJS admin_audit_log can route by topic[1] without per-action parsers.

- Cargo.toml: added testutils feature flag for test-only entrypoints.

- storage.rs: added Paused, PendingAdmin DataKey variants and helpers.

- token.rs: removed dead_code allow now that drain uses transfer.

- Centralization disclosure, multisig guidance, and future timelock seams
  documented inline in admin.rs for auditors.

- 20 tests covering: full privilege matrix, two-step rotation, hijack
  prevention, event emission, zero/negative drain, double-initialize.

Author: zeekman

contracts/niffyinsure/Cargo.toml

@@ -8,6 +8,11 @@ publish = false
 [lib]
 crate-type = ["cdylib", "rlib"]
 
+[features]
+# Enables test-only contract entrypoints gated behind this feature.
+# Never enable in production WASM builds.
+testutils = ["soroban-sdk/testutils"]
+
 [dependencies]
 soroban-sdk = { version = "=23.5.3", features = [] }
 

contracts/niffyinsure/src/admin.rs

@@ -0,0 +1,219 @@
+/// Privileged administration: admin rotation, token update, pause toggle, drain.
+///
+/// # Centralization disclosure (for users / auditors)
+///
+/// Community policyholders govern claim outcomes via DAO voting — no admin
+/// override exists on individual claims.  However, the following protocol
+/// parameters remain admin-controlled in the MVP:
+///
+/// - Token contract address (treasury asset)
+/// - Pause / unpause (emergency circuit-breaker)
+/// - Admin key itself (rotation)
+/// - Treasury drain (emergency fund recovery)
+///
+/// This is a deliberate MVP trade-off.  The seams for future decentralisation
+/// are documented below each function.  Production deployments SHOULD use a
+/// Stellar multisig account (e.g. 3-of-5 signers) as the admin address.
+///
+/// # Multisig guidance for production
+///
+/// Stellar natively supports weighted multisig via `set_options`.  Recommended
+/// setup:
+///   - Create a dedicated admin account with master weight 0.
+///   - Add 5 co-signer keys with weight 1 each; set thresholds to 3.
+///   - The resulting address is the `admin` passed to `initialize`.
+///   - All admin calls require 3-of-5 signatures in the transaction envelope.
+///   - For higher assurance, use a hardware-wallet-backed signer set.
+///
+/// # Future timelock / governance seam
+///
+/// Each privileged setter is a single function call today.  To add a timelock:
+///   1. Replace the direct write with a `Proposal { action, value, eta }` stored
+///      at `DataKey::Proposal(action_id)`.
+///   2. Add `execute_proposal(env, action_id)` that checks `env.ledger().timestamp()
+///      >= eta` before applying.
+///   3. The event schema below is already action-typed, so the NestJS
+///      `admin_audit_log` ingestion requires no changes.
+///
+/// # Event schema (machine-readable for NestJS ingestion)
+///
+/// Every mutation emits:
+///   topic:   ("admin", "<action_name>")
+///   payload: depends on action — see individual functions below.
+///
+/// The NestJS handler can key on `topic[1]` (the action symbol) to route to
+/// the correct `admin_audit_log` column without per-action parsers.
+use soroban_sdk::{contracttype, panic_with_error, symbol_short, Address, Env};
+
+use crate::storage;
+
+// ── Error codes ───────────────────────────────────────────────────────────────
+
+#[contracttype]
+#[derive(Copy, Clone, Debug, PartialEq)]
+#[repr(u32)]
+pub enum AdminError {
+    /// Caller is not the current admin.
+    Unauthorized = 100,
+    /// initialize() has already been called.
+    AlreadyInitialized = 101,
+    /// No pending admin proposal exists.
+    NoPendingAdmin = 102,
+    /// Caller is not the pending admin.
+    NotPendingAdmin = 103,
+    /// Supplied address is the zero/invalid sentinel.
+    InvalidAddress = 104,
+    /// Drain amount must be > 0.
+    InvalidDrainAmount = 105,
+}
+
+// ── Auth helper ───────────────────────────────────────────────────────────────
+
+/// Loads the admin, calls `require_auth()`, and returns the address.
+/// Panics with `AdminError::Unauthorized` if storage has no admin yet
+/// (should never happen after initialize, but guards against mis-ordering).
+pub fn require_admin(env: &Env) -> Address {
+    let admin = env
+        .storage()
+        .instance()
+        .get::<_, Address>(&storage::DataKey::Admin)
+        .unwrap_or_else(|| panic_with_error!(env, AdminError::Unauthorized));
+    admin.require_auth();
+    admin
+}
+
+// ── Admin rotation (two-step handoff) ────────────────────────────────────────
+//
+// Two-step pattern chosen over immediate replacement because:
+//   - Immediate replacement risks locking out the protocol if the new address
+//     is a typo or an uncontrolled key.
+//   - Two-step requires the incoming admin to prove key control before the
+//     handoff completes, eliminating that class of operational error.
+//
+// Flow:
+//   1. current admin calls propose_admin(new_admin)
+//   2. new_admin calls accept_admin()          → rotation complete
+//   OR current admin calls cancel_admin()      → proposal withdrawn
+//
+// Future timelock seam: step 1 could store an `eta` and step 2 could check it.
+
+/// Propose a new admin address.  The current admin must authorize.
+/// Emits: ("admin", "proposed") → (old_admin, new_admin)
+pub fn propose_admin(env: &Env, new_admin: Address) {
+    let current = require_admin(env);
+
+    // Reject zero-address / self-proposal is allowed (idempotent re-proposal)
+    // but the address must be a valid Soroban Address (type system guarantees this).
+
+    storage::set_pending_admin(env, &new_admin);
+
+    env.events().publish(
+        (symbol_short!("admin"), symbol_short!("proposed")),
+        (current, new_admin),
+    );
+}
+
+/// Accept a pending admin proposal.  The *new* (pending) admin must authorize.
+/// Emits: ("admin", "accepted") → (old_admin, new_admin)
+pub fn accept_admin(env: &Env) {
+    let pending = storage::get_pending_admin(env)
+        .unwrap_or_else(|| panic_with_error!(env, AdminError::NoPendingAdmin));
+
+    // The pending admin must sign — prevents hijack by unrelated signers
+    pending.require_auth();
+
+    let old_admin = storage::get_admin(env);
+    storage::set_admin(env, &pending);
+    storage::clear_pending_admin(env);
+
+    env.events().publish(
+        (symbol_short!("admin"), symbol_short!("accepted")),
+        (old_admin, pending),
+    );
+}
+
+/// Cancel a pending admin proposal.  Only the current admin may cancel.
+/// Emits: ("admin", "cancelled") → (current_admin, cancelled_pending)
+pub fn cancel_admin(env: &Env) {
+    let current = require_admin(env);
+    let pending = storage::get_pending_admin(env)
+        .unwrap_or_else(|| panic_with_error!(env, AdminError::NoPendingAdmin));
+
+    storage::clear_pending_admin(env);
+
+    env.events().publish(
+        (symbol_short!("admin"), symbol_short!("cancelled")),
+        (current, pending),
+    );
+}
+
+// ── Token update ──────────────────────────────────────────────────────────────
+//
+// Future governance seam: replace with a proposal + timelock so token
+// migrations are visible on-chain before they take effect.
+
+/// Update the treasury token contract address.
+/// Emits: ("admin", "token_set") → (old_token, new_token)
+pub fn set_token(env: &Env, new_token: Address) {
+    let _admin = require_admin(env);
+
+    let old_token = storage::get_token(env);
+    storage::set_token(env, &new_token);
+
+    env.events().publish(
+        (symbol_short!("admin"), symbol_short!("token")),
+        (old_token, new_token),
+    );
+}
+
+// ── Pause toggle ──────────────────────────────────────────────────────────────
+//
+// Pause blocks file_claim and vote_on_claim (see claim.rs).
+// It does NOT retroactively invalidate in-flight votes or tallies.
+// Future seam: add a community-vote-triggered unpause path.
+
+/// Pause the contract.  Admin must authorize.
+/// Emits: ("admin", "paused") → (admin)
+pub fn pause(env: &Env) {
+    let admin = require_admin(env);
+    storage::set_paused(env, true);
+    env.events()
+        .publish((symbol_short!("admin"), symbol_short!("paused")), (admin,));
+}
+
+/// Unpause the contract.  Admin must authorize.
+/// Emits: ("admin", "unpaused") → (admin)
+pub fn unpause(env: &Env) {
+    let admin = require_admin(env);
+    storage::set_paused(env, false);
+    env.events().publish(
+        (symbol_short!("admin"), symbol_short!("unpaused")),
+        (admin,),
+    );
+}
+
+// ── Treasury drain ────────────────────────────────────────────────────────────
+//
+// Emergency fund recovery.  Transfers `amount` stroops of the treasury token
+// from the contract to `recipient`.  Admin must authorize.
+//
+// Future governance seam: require a time-delayed proposal before drain executes,
+// giving policyholders a window to exit if they disagree with the action.
+
+/// Drain `amount` stroops from the contract treasury to `recipient`.
+/// Emits: ("admin", "drained") → (admin, recipient, amount)
+pub fn drain(env: &Env, recipient: Address, amount: i128) {
+    let admin = require_admin(env);
+
+    if amount <= 0 {
+        panic_with_error!(env, AdminError::InvalidDrainAmount);
+    }
+
+    let token = storage::get_token(env);
+    crate::token::transfer(env, &token, &env.current_contract_address(), &recipient, amount);
+
+    env.events().publish(
+        (symbol_short!("admin"), symbol_short!("drained")),
+        (admin, recipient, amount),
+    );
+}

contracts/niffyinsure/src/lib.rs

@@ -1,37 +0,0 @@
-#![no_std]
-
-mod claim;
-mod policy;
-#[allow(dead_code)] // used by policy.rs once feat/policy-lifecycle lands
-mod premium;
-mod storage;
-mod token;
-pub mod types;
-pub mod validate;
-
-use soroban_sdk::{contract, contractimpl, Address, Env};
-
-#[contract]
-pub struct NiffyInsure;
-
-#[contractimpl]
-impl NiffyInsure {
-    /// One-time initialisation: store admin and token contract address.
-    /// Must be called immediately after deployment.
-    pub fn initialize(env: Env, admin: Address, token: Address) {
-        storage::set_admin(&env, &admin);
-        storage::set_token(&env, &token);
-    }
-
-    // ── Policy domain ────────────────────────────────────────────────────
-    // generate_premium, initiate_policy, renew_policy, terminate_policy
-    // implemented in policy.rs — issue: feat/policy-lifecycle
-
-    // ── Claim domain ─────────────────────────────────────────────────────
-    // file_claim, vote_on_claim
-    // implemented in claim.rs — issue: feat/claim-voting
-
-    // ── Admin / treasury ─────────────────────────────────────────────────
-    // drain
-    // implemented in token.rs — issue: feat/admin
-}

contracts/niffyinsure/src/storage.rs

@@ -15,14 +15,17 @@ pub enum DataKey {
     Voters,
     /// Global monotonic claim id counter
     ClaimCounter,
+    /// Pause flag: if present and true the contract is paused
+    Paused,
+    /// Pending admin address for two-step rotation handoff.
+    /// Set by current admin via propose_admin; cleared on accept_admin or cancel_admin.
+    PendingAdmin,
 }
 
 pub fn set_admin(env: &Env, admin: &Address) {
     env.storage().instance().set(&DataKey::Admin, admin);
 }
 
-/// Used by initialize and admin drain (feat/admin).
-#[allow(dead_code)]
 pub fn get_admin(env: &Env) -> Address {
     env.storage().instance().get(&DataKey::Admin).unwrap()
 }
@@ -31,12 +34,35 @@ pub fn set_token(env: &Env, token: &Address) {
     env.storage().instance().set(&DataKey::Token, token);
 }
 
-/// Used by claim payout (feat/claim-voting).
-#[allow(dead_code)]
 pub fn get_token(env: &Env) -> Address {
     env.storage().instance().get(&DataKey::Token).unwrap()
 }
 
+pub fn is_paused(env: &Env) -> bool {
+    env.storage()
+        .instance()
+        .get(&DataKey::Paused)
+        .unwrap_or(false)
+}
+
+pub fn set_paused(env: &Env, paused: bool) {
+    env.storage().instance().set(&DataKey::Paused, &paused);
+}
+
+pub fn get_pending_admin(env: &Env) -> Option<Address> {
+    env.storage().instance().get(&DataKey::PendingAdmin)
+}
+
+pub fn set_pending_admin(env: &Env, pending: &Address) {
+    env.storage()
+        .instance()
+        .set(&DataKey::PendingAdmin, pending);
+}
+
+pub fn clear_pending_admin(env: &Env) {
+    env.storage().instance().remove(&DataKey::PendingAdmin);
+}
+
 /// Returns the next policy_id for `holder` and increments the counter.
 /// Used by feat/policy-lifecycle.
 #[allow(dead_code)]

contracts/niffyinsure/src/token.rs

@@ -1,8 +1,6 @@
 use soroban_sdk::{Address, Env};
 
 /// Invoke the SEP-41 `transfer` entry-point on an external token contract.
-/// Called from claim.rs once feat/claim-voting lands.
-#[allow(dead_code)]
 pub fn transfer(env: &Env, token: &Address, from: &Address, to: &Address, amount: i128) {
     let args = soroban_sdk::vec![
         env,