@crediolabs/policy-synth 0.1.17 → 0.2.0

package/src/contracts/policy-template/OZ_POLICY_TRAIT.md

@@ -1,196 +0,0 @@
-# OZ_POLICY_TRAIT.md — OpenZeppelin Stellar Accounts Pinned Trait Definitions
-
-> **Pinned at:** `OpenZeppelin/stellar-contracts@v0.8.0-rc.3`  
-> **Commit SHA:** `4114bb8e2d7f090bdd9f45731e0607071d5ecea2`  
-> **Permalink:** https://github.com/OpenZeppelin/stellar-contracts/blob/4114bb8e2d7f090bdd9f45731e0607071d5ecea2/packages/accounts/src/policies/mod.rs  
-> **Policy trait file:** https://github.com/OpenZeppelin/stellar-contracts/blob/4114bb8e2d7f090bdd9f45731e0607071d5ecea2/packages/accounts/src/policies/mod.rs  
-> **Storage file (Signer, ContextRule, add_context_rule):** https://github.com/OpenZeppelin/stellar-contracts/blob/4114bb8e2d7f090bdd9f45731e0607071d5ecea2/packages/accounts/src/smart_account/storage.rs  
-> **Verified:** 2026-07-24 by W3 agent
-
----
-
-## Policy Trait
-
-Source: `packages/accounts/src/policies/mod.rs` (permalinked above)
-
-```rust
-pub trait Policy {
-    type AccountParams: FromVal<Env, Val>;
-
-    fn enforce(
-        e: &Env,
-        context: Context,
-        authenticated_signers: Vec<Signer>,
-        context_rule: ContextRule,
-        smart_account: Address,
-    );
-
-    fn install(
-        e: &Env,
-        install_params: Self::AccountParams,
-        context_rule: ContextRule,
-        smart_account: Address,
-    );
-
-    fn uninstall(e: &Env, context_rule: ContextRule, smart_account: Address);
-}
-```
-
-### Key observations
-
-- `Policy::enforce` receives a **single `Context`** — the authorization context being enforced. It does **NOT** carry a `sub_invocations` field. Sub-invocations live under `InvokerContractAuthEntry::Contract(SubContractInvocation)` and are used for `authorize_as_current_contract`, not passed to `Policy::enforce`.
-- The `Context` type is defined in `soroban_sdk::auth::Context` (external, not in this repo).
-- `install` takes `Self::AccountParams` — the interpreter's `PolicyInstallParams` struct satisfies this via `FromVal` / `IntoVal`.
-- `uninstall` requires the `ContextRule` to be passed by the caller; the interpreter stores it to compute the `rule_id`.
-
----
-
-## Signer Enum
-
-Source: `packages/accounts/src/smart_account/storage.rs` lines 148–155 (permalinked above)
-
-```rust
-pub enum Signer {
-    Delegated(Address),
-    External(Address, Bytes),
-}
-```
-
-**Two variants only.** No `Key` variant. No `SmartAccount` variant. The verifier address + key bytes for an external signer are carried in the `External` variant itself. There is **no master/non-master discriminator** on the type.
-
----
-
-## ContextRuleType Enum
-
-Source: `packages/accounts/src/smart_account/storage.rs` lines 170–177
-
-```rust
-pub enum ContextRuleType {
-    Default,
-    CallContract(Address),
-    CreateContract(BytesN<32>),
-}
-```
-
----
-
-## ContextRule Struct
-
-Source: `packages/accounts/src/smart_account/storage.rs` lines 179–199
-
-```rust
-pub struct ContextRule {
-    pub id: u32,
-    pub context_type: ContextRuleType,
-    pub name: String,
-    pub signers: Vec<Signer>,
-    pub signer_ids: Vec<u32>,
-    pub policies: Vec<Address>,
-    pub policy_ids: Vec<u32>,
-    pub valid_until: Option<u32>,
-}
-```
-
----
-
-## add_context_rule Signature
-
-Source: `packages/accounts/src/smart_account/storage.rs` lines 620–645
-
-```rust
-pub fn add_context_rule(
-    e: &Env,
-    context_type: &ContextRuleType,
-    name: &String,
-    valid_until: Option<u32>,
-    signers: &Vec<Signer>,
-    policies: &Map<Address, Val>,
-) -> ContextRule
-```
-
-### Auth requirements
-
-- `add_context_rule` is called by the **smart account itself** (the contract owning the context rules).
-- Auth is enforced by Soroban's `require_auth` on the calling context — the smart account's master signer (or a delegated signer with sufficient weight) must authorize the call.
-- The interpreter's `install` function is called **within the same transaction** as `add_context_rule` and receives the same `smart_account` address.
-- The interpreter **cannot** read the smart account's master set; it receives only the already-authorized `ContextRule` and `smart_account` address.
-
-> **CORRECTED 2026-07-27 - do not read the line above as a safety guarantee.**
-> An earlier version of this file said the interpreter "does NOT need to" read the
-> master set because the master authorizes `add_context_rule` directly. The master
-> *can* authorize it. It is **not** true that only the master can.
->
-> Verified at this pinned commit: `storage.rs` states `add_policy` /
-> `add_context_rule` modify storage "without requiring authorization. Ensure proper
-> access control is implemented at the contract level"; `mod.rs:439` and `mod.rs:246`
-> implement that as `e.current_contract_address().require_auth()`, a self-auth
-> resolved through the account's own context rules; and `mod.rs:80` states that
-> "a `Default` rule matches any context".
->
-> Therefore any signer on a `Default` rule can attach or replace a policy - including
-> a delegated agent, on its own rule. See `plans/security-finding-install-authorization.md`.
-
-### Safe mechanism for master-only install
-
-Two-step install is the install **path**. It is NOT relied on as the authorization
-**guarantee**, because the auth it inherits is whatever the account's own rules permit:
-
-1. Owner calls `add_context_rule` with the interpreter address + initial rule.
-2. Interpreter's `install` is called within the same auth context.
-3. Re-install is structurally possible via `install_nonce` (stored nonce + 1 check).
-
-The guarantee comes from the interpreter pinning its own authorized installer set at
-first install for `(smart_account, rule_id)`, and denying later installs and
-uninstalls from outside that set with `MASTER_AUTH_REQUIRED`. Rotation goes through
-`rotate_master_signer_set(new_set)`, gated by the old set.
-
-`install_nonce` alone does not close this: it blocks replay of an *old* document, but
-a *fresh* looser document with `nonce + 1` would otherwise be accepted.
-
----
-
-## Framework Limits (OZ Hard Limits)
-
-Source: `packages/accounts/src/smart_account/storage.rs` (permalinked above)
-
-| Limit | Value |
-|---|---|
-| `maxPoliciesPerRule` | **5** |
-| `maxSignersPerRule` | **15** |
-| Per-account rule cap | **None** (OZ imposes no cap) |
-
-These are enforced by OZ internally; the interpreter enforces the same caps at install time.
-
----
-
-## add_policy (Second Attach Path)
-
-`add_context_rule` installs the rule + signers. A **second separate call** (`add_policy`) attaches a policy contract to an existing rule:
-
-```rust
-pub fn add_policy(
-    e: &Env,
-    context_rule_id: u32,
-    policy: Address,
-    install_param: Val,
-) -> u32
-```
-
-Parameters:
-- `context_rule_id: u32` — the rule to attach to
-- `policy: Address` — the policy contract address
-- `install_param: Val` — arbitrary `Val` passed to `Policy::install`; for the interpreter this is `PolicyInstallParams` as ScVal
-- Returns `u32` — the new policy id within the rule
-
-**Auth:** same pattern — `require_auth` on the smart account. The `policy` address must point to a deployed `Policy` contract.
-
----
-
-## Related Files
-
-| File | Purpose |
-|---|---|
-| `packages/accounts/src/smart_account/mod.rs` | Smart account contract entry points |
-| `packages/accounts/src/smart_account/storage.rs` | Signer, ContextRule, add_context_rule, add_policy |
-| `packages/accounts/src/policies/mod.rs` | Policy trait definition |
-| `packages/accounts/src/policies/oz_primitive.rs` | Built-in OZ policies (spending_limit, threshold) |