Security

docs/SECURITY.md

Hushroll Security Model

This document outlines the trust model, authorization boundaries, and key security controls in Hushroll v1.

1) Security Goals

Keep payroll-sensitive values confidential on-chain.
Ensure only authorized actors can perform payroll actions.
Prevent unauthorized approvals, department mutations, and token spending.
Preserve traceability through immutable event logs.

2) Trust and Threat Boundaries

Trusted Components

Smart contracts deployed by the project team.
FHE protocol primitives and ERC-7984 confidential token mechanics.
Wallet private keys controlled by each user.

Semi-trusted / external dependencies

Frontend runtime (can be manipulated by user/browser extensions; on-chain checks remain authoritative).
Subgraph indexer (used for UX/read models, not for authorization).

Primary threat classes addressed

Unauthorized state transitions (role/permission checks).
Approval process abuse (double voting / cross voting).
Unsupported-token payment execution.
Manager cross-department overreach.

3) Access Control Model

Employer

Registers payroll and configures approvers.
Onboards/updates/removes employees.
Creates payment/batch requests.
Manages departments (and selected manager-scoped delegation).

Approver

Votes on pending requests for payrolls where they are configured approvers.
Multi-sig threshold required to execute.

Employee

Receives confidential payments.
Can decrypt own authorized data.
Can interact with allowed employee-level flows.

Manager

Department-scoped operations under current contract policy.
Explicit scope checks prevent operations outside assigned departments.

4) Core Controls Implemented

Approval and Voting Controls

Threshold approvals (M-of-N) for multi-sig execution.
Threshold rejection model.
Duplicate voting blocked.
Cross-vote blocking (cannot approve then reject same request, or inverse).

Token and Payment Controls

Payment requests require supported token addresses.
Payroll execution uses confidential transfer from employer balance with operator authorization.
Operator management gated through factory/payroll ownership context.

Department Scope Controls

Department operations require employer or scoped manager authorization.
Manager-out-of-scope actions revert.
Department deactivation blocked while employees remain assigned.

Confidentiality Controls

Salaries/net amounts are encrypted handles, not plaintext storage.
Authorization-based decryption only.
Subgraph tracks metadata/events, not plaintext compensation values.

5) Security-Relevant Test Coverage (v1)

Covered in automated tests:

Multi-sig threshold execution behavior.
Single/batch approval and rejection paths.
Cross-vote guard behavior.
Unsupported token reverts.
Manager scope enforcement.
Department deactivation guard (non-empty -> revert).
Factory operator negative path before registration.
Deduction authorization and invalid-flow reverts.
Invoice precondition checks (including known regression guard path).

6) Known Limitations / Ongoing Work

Invoice module has validated preconditions and guards, but full UX-integrated happy path is targeted for v2 completion.
Deduction contracts are live; frontend/subgraph product flow is partially integrated in v1 and planned for full completion in v2.
Security posture improves further with dedicated audits and formal verification for production deployment.

7) Operational Security Guidance

Use hardware wallets for employer/approver accounts in production.
Keep signer roles separated by policy (ops vs approval authority).
Use multi-sig mode for organizations with compliance requirements.
Restrict deployment and upgrade key custody.
Treat frontend checks as UX guards; rely on on-chain checks as source of truth.

There aren’t any published security advisories