Semi Trusted Roles

SEMI_TRUSTED_ROLES Skill (DAML)

Trigger Pattern: operator/admin/manager/registrar party as signatory or controller, authority-gated choices beyond pure parameter-setting Inject Into: Breadth agents, depth-state-trace Finding prefix: [DML-STR-N] Rules referenced: R2, R6, R10, R13

operator|admin|manager|registrar|issuer|guardian|custodian|controller|signatory|authority

DAML role context: there are no role modifiers. A "role" is a Party that appears as a signatory and/or as a controller of privileged choices. Authority is held by holding that party's submission rights; a choice's required authorizers are its controller parties (AND-joined), a create/archive requires the contract's signatory parties. An operator/admin party is therefore SEMI_TRUSTED: trusted to act within its choices, but its key may be compromised and its actions must be analyzed bidirectionally (R6) — what it can do TO users, and what users can do to exploit/grief it.

Step 1: Inventory Role Permissions

In {TEMPLATES}, find every choice whose controller includes {ROLE_PARTY} (operator/admin/etc.), and every template where {ROLE_PARTY} is a signatory. For each:

• Which (Template, field) does the choice's consequence create/archive (i.e. what state does it write)?
• Does the choice exercise another template's choice (one-hop authority propagation)?
• Parameters accepted from the caller (especially a caller-supplied ContractId or party)?
• Consume-mode (consuming/nonconsuming/pre/postconsuming)?

Auth patterns: controller operator, controller issuer, operator (joint), signatory operator (operator co-signs every successor), choice that re-fetches a contract and branches on a field the operator controls.

Step 2: Analyze Within-Scope Abuse (Direction 1 — role harms users)

For each permitted action, ask:

Timing Abuse (ledger-time ordered, no public mempool):

• Can the role exercise a choice at a harmful time (before a user's query-driven action, just before a deadline)?
• Can the role DELAY a choice (skip a settlement/registration crank) to harm users?

Parameter Abuse:

• Can the role pass a harmful value (inflated amount, wrong newOwner, attacker-controlled ContractId)?
• Are caller parameters validated in the choice body (assertMsg, ensure on the successor), or trusted implicitly?
• Can the role supply a forged config/whitelist ContractId the choice does not bind to a trusted issuer?

Sequence / Omission Abuse:

• Can the role exercise choices out of order (accept before propose, settle before finalize)?
• Can the role harm users by NOT exercising (never registering, never unlocking, never distributing)? Is there a recovery path if the role stops?

Step 3: Model Attack Scenarios

Scenario A: Authority-Timing Attack
1. {ROLE_PARTY} observes a user's pending action via on-chain ACS state
2. {ROLE_PARTY} submits role_choice() to land in a prior/same ledger
3. ACS changes before the user's transaction commits
4. Impact: {TIMING_IMPACT}
Note: no public mempool; ordering is ledger-time / submission based.

Scenario B: Parameter / Forged-CID Attack
1. {ROLE_PARTY} exercises {ROLE_CHOICE} with {MALICIOUS_PARAMS} (amount, recipient, or a lookalike ContractId)
2. Choice body does not validate against {EXPECTED_CONSTRAINTS} / does not bind the CID to the trusted issuer
3. Impact: {PARAM_IMPACT}

Scenario C: Key Compromise
1. {ROLE_PARTY}'s submission key is compromised
2. Attacker can exercise: {ROLE_CHOICES} and co-sign as signatory on: {SIGNATORY_TEMPLATES}
3. Maximum extractable / corruptible state: {MAX_DAMAGE}
4. Recovery: is there a choice to rotate/replace {ROLE_PARTY}? If the role is a hardcoded signatory, rotation may be impossible.

Step 4: Assess Mitigations

• Is the role action gated by a propose/accept two-step (multi-transaction) flow rather than a single unilateral choice?
• Is {ROLE_PARTY} a single party or a joint controller (AND of multiple parties, the DAML analog of multisig)?
• Does a rotation/replacement choice EXIST? If the role is a signatory baked into live contracts, replacing it may require re-creating every contract. If NO rotation path → FINDING: authority irrevocable. Min Medium if the role can mutate user-held contracts.
• Rate limits / caps tracked across transactions (accumulator template)?
• If the role is also a maintainer of a key, note: maintainers MUST be signatories — compromise of the maintainer party affects key uniqueness too.

DAML patterns: Propose→Accept (OperatorProposal create + Accept choice), joint controller a, b, an Admin contract whose signatory is a governance party.

Step 5: Model User-Side Exploitation (Direction 2 — R6, MANDATORY)

Predictability Analysis:

• Is the role's behavior predictable (a published schedule, a state-triggered crank, a queue)?
• Can users observe via the ACS when the role will act?
• Can users submit to land before the role in ledger order?

Scenario D: User Exploits Role Timing
1. User observes {ROLE_PARTY} exercises {ROLE_CHOICE} when {CONDITION} holds in the ACS
2. User submits a transaction to land before the role's
3. User benefits from the known impending state change. Impact: {USER_EXPLOIT_IMPACT}

Scenario E: User Griefs Role Preconditions
1. {ROLE_CHOICE} requires ACS state: {PRECONDITION} (a contract present, a key resolvable, an ensure satisfiable)
2. User archives/alters a contract the role's choice fetches, or creates a key-collision the role's lookupByKey trips on
3. Role's choice aborts (CONTRACT_NOT_FOUND / PreconditionFailed); protocol enters a degraded state. Impact: {GRIEF_IMPACT}

Scenario F: User Forces Suboptimal Role Action
1. User shapes ACS state so the honest role's policy chooses a harmful branch
2. Impact: {SUBOPTIMAL_IMPACT}

Scenario G: Stale State via Discrete Role Updates
1. A rate/config contract is only re-created when {ROLE_PARTY} exercises {UPDATE_CHOICE}
2. User acts at the stale rate, role updates, user exits. Impact: {RATE_ARBIT_IMPACT}