# v0.5 – Contract-Backed ACL for Dedicated Private Sessions (Session-Based Only)

> Status: Design aligned with current mock implementation\
> Scope: **Session-based privacy and key access only** (no task-level ACL)

***

### 1. Purpose and Scope

v0.5 introduces an **on-chain ACL layer** for **private, dedicated sessions**, replacing most router env-based ACL logic for these flows.

Key points:

* **Scope = session only**
  * Keys are derived and authorized **per `sessionId`**, not per task.
* **One-way privacy**
  * A session becomes *encrypted/private* the first time a miner is added.
  * It **cannot** be downgraded back to non-encrypted.
* **Router integration change**
  * Router must stop treating `ENCRYPTION_ALLOWED_LIST` as the primary ACL source for dedicated private sessions.
  * Router must read from the **session-level allowlist** in this module, **cache it**, and only fall back to env in explicit legacy/emergency modes.

This doc describes the **actual mock implementation**:

* State:
  * `sessionAllowedMiners`
  * `sessionAllowedMinerList`
  * `sessionAllowedMinerIndex`
  * `sessionEncryptionEnabled`
* Functions:
  * `addSessionAllowedMiner`
  * `removeSessionAllowedMiner`
  * `getAllowedMinersCount`
  * `getAllowedMiners`

Session ownership is still resolved via `SessionData` (not in this module).

***

### 2. On-Chain State (Current Mock Implementation)

#### 2.1 Allowlist Core

State layout:

* `mapping(uint256 => mapping(address => bool)) public sessionAllowedMiners;`\
  Membership mapping (already existed).
* `mapping(uint256 => address[]) private sessionAllowedMinerList;`\
  Backing array to enable enumeration/pagination (new, private).
* `mapping(uint256 => mapping(address => uint256)) private sessionAllowedMinerIndex;`\
  1-based index for O(1) removal via swap-and-pop (new, private).
* `mapping(uint256 => bool) public sessionEncryptionEnabled;`\
  Session-level privacy flag.

Semantics:

* `sessionAllowedMiners[sessionId][miner]`\
  → `true` if `miner` is currently allowlisted for that session.
* `sessionAllowedMinerList[sessionId]`\
  → backing array to enumerate allowlisted miners.
* `sessionAllowedMinerIndex[sessionId][miner]`\
  → 1-based index into `sessionAllowedMinerList[sessionId]`; `0` means “not present”.\
  Used for **O(1)** removal via swap-and-pop.
* `sessionEncryptionEnabled[sessionId]`\
  → privacy flag for that session:
  * `false` (default): session is not private/encrypted.
  * `true`: session is **private/encrypted**, cannot be turned off.

***

### 3. Functions and Behavior

#### 3.1 `addSessionAllowedMiner(sessionId, miner)`

Purpose:

* Add a miner to the allowlist for a session.
* Auto-enable session encryption on first use.

Key behavior:

* **Ownership guard**:
  * Only the **session owner** (from `SessionData`) can call this.
* **Idempotent**:
  * If `sessionAllowedMiners[sessionId][miner]` is already `true`, function is a no-op (beyond the ownership check).
* **When miner is not present**:
  1. Set `sessionAllowedMiners[sessionId][miner] = true`.
  2. Append `miner` to `sessionAllowedMinerList[sessionId]`.
  3. Set `sessionAllowedMinerIndex[sessionId][miner] = newIndex` (1-based).
* **Auto-encryption**:
  * If this is the *first* miner added for the session:
    * Set `sessionEncryptionEnabled[sessionId] = true`.
    * This is **one-way**: there is no function to set it back to `false`.

Complexity:

* Time: **O(1)** for membership check + append.
* Storage: grows with number of allowlisted miners per session.

***

#### 3.2 `removeSessionAllowedMiner(sessionId, miner)`

Purpose:

* Remove a miner from the allowlist in **O(1)** time.

Key behavior:

* **Ownership guard**:
  * Only the **session owner** (from `SessionData`) can call this.
* Removal pattern (swap-and-pop):
  * Look up `idx = sessionAllowedMinerIndex[sessionId][miner]`.
  * If `idx == 0`, miner not present → no-op or revert (implementation choice).
  * Else:
    * Compute `lastIdx = sessionAllowedMinerList[sessionId].length`.
    * If `idx != lastIdx`, swap:
      * `last = sessionAllowedMinerList[sessionId][lastIdx - 1]`.
      * `sessionAllowedMinerList[sessionId][idx - 1] = last`.
      * `sessionAllowedMinerIndex[sessionId][last] = idx`.
    * Pop the last element from `sessionAllowedMinerList[sessionId]`.
    * Set:
      * `sessionAllowedMinerIndex[sessionId][miner] = 0`.
      * `sessionAllowedMiners[sessionId][miner] = false`.

Notes:

* **Does not** change `sessionEncryptionEnabled[sessionId]`:
  * Once encryption is enabled, the session stays private/encrypted even if list becomes empty.

Complexity:

* Time: **O(1)**.

***

#### 3.3 `getAllowedMinersCount(sessionId) → uint256`

Purpose:

* Return the size of the allowlist for a session.

Implementation:

* `return sessionAllowedMinerList[sessionId].length;`

Use:

* Call this first before pagination to ensure `offset < count`.

***

#### 3.4 `getAllowedMiners(sessionId, offset, limit) → address[]`

Purpose:

* Paged enumeration of allowlisted miners.

Constraints:

* `offset < totalCount` must hold, otherwise the call will revert.
* For an empty list (`totalCount == 0`), **any** call will revert:
  * Callers must always check `getAllowedMinersCount(sessionId)` first.

Usage:

1. Get total:
   * `uint256 total = getAllowedMinersCount(sessionId);`
2. Page through:
   * Ensure `offset < total`.
   * Fetch a page of size `limit` starting at `offset`.

Example:

* `offset = 0`, `limit = 50` to fetch first page.
* `offset = 50`, `limit = 50` for second page, etc.

Complexity:

* Time: **O(k)** where `k` = size of returned page (`limit`).

***

### 4. How Router Uses This ACL (v0.5, Session-Only)

#### 4.1 Privacy Flag

When a router handles a request for a given `sessionId`:

* Check:
  * `isPrivate = sessionEncryptionEnabled(sessionId);`
* If `isPrivate == true`:
  * Treat the session as **private/encrypted**.
  * All `/api/v2/completion` traffic for that session must:
    * Use **offchain payload v2** with encryption.
    * Disable streaming.
  * Key issuance must enforce ACL via `sessionAllowedMiners`.
* If `isPrivate == false`:
  * Session is non-private/plain.
  * Router can treat it as a normal (unencrypted) session unless explicitly configured otherwise.

***

#### 4.2 Key Issuance (`/api/v1/auth/payload_enc_key/session`)

For **miners**:

1. Caller sends:
   * `session_id`
   * `address` (or implied from signature)
   * `signature` over canonical scope string.
2. Router constructs scope string, for example:
   * `"session:" + session_id`
3. Router verifies signature (e.g., `verify_addr_str_message(scope_str)`).
4. Router verifies ACL:
   * If `sessionEncryptionEnabled(sessionId) == true`:
     * Check `sessionAllowedMiners(sessionId, minerAddr)` via the **public getter**.
   * Else:
     * For non-private sessions, router may still support legacy env-based logic if needed.
5. If `allowed == true`:
   * Derive scoped key with current `key_version`.
   * Return key + version to miner.

**Important:**\
Router implementation must be updated so that for **private dedicated sessions**:

* **Primary ACL is the contract**, not `ENCRYPTION_ALLOWED_LIST`.
* Env-based ACL is **optional fallback** and should be guarded by an explicit feature flag.

***

#### 4.3 Router Caching Strategy

Even though `sessionAllowedMiners` and `sessionEncryptionEnabled` are cheap to read:

* Routers should **cache** for hot sessions:
  * `sessionEncryptionEnabled(sessionId)`
  * Membership checks for active `(sessionId, minerAddr)` pairs.
* Cache invalidation/update should be driven by:
  * Events (if implemented), or
  * Periodic polling with TTL.

This is especially important when many miners are requesting keys for the same active sessions.

***

### 5. Interaction With v0 Private / Encrypted Inference

v0 private inference is **router-centric** and uses:

* Session-scoped encryption keys derived from an `ENCRYPTION_SEED`/keyring.
* Auth endpoints:
  * `/api/v1/auth/payload_enc_key/session`
* Offchain v2 encrypted payloads with metadata such as:
  * `alg`, `scope_type`, `session_id`, `key_version`, `nonce`, `tag`, `ciphertext`, `created_at`.

v0.5 changes **who is allowed** to get keys:

* Instead of `.env`-only ACL (`ENCRYPTION_ALLOWED_LIST`), dedicated private sessions use:
  * `sessionEncryptionEnabled[sessionId]`
  * `sessionAllowedMiners[sessionId][miner]`

for authorization.

Env-based ACL can still exist for:

* Non-private sessions.
* Emergency overrides.
* Legacy testing environments.

But **for dedicated private sessions**, the on-chain ACL is canonical.

***

### 6. Dashboard / UX Flow

#### 6.1 Enabling a Dedicated Private Session

Typical flow:

1. User creates a session (`SessionData` + router).
2. Dashboard allows user to **configure a dedicated node address**.
3. When user chooses to **enable private mode**:
   * Dashboard calls `addSessionAllowedMiner(sessionId, dedicatedNodeAddr)` on-chain.
4. Effects:
   * `sessionAllowedMiners[sessionId][dedicatedNodeAddr] = true`.
   * `sessionEncryptionEnabled[sessionId] = true` (if first miner).
   * Dedicated node address appears in `sessionAllowedMinerList[sessionId]`.

Dashboard UX:

* Show a **one-way warning**:
  * Enabling privacy is **permanent** for this session.
  * Session will use encrypted offchain v2 payloads and **no streaming**.
  * Only allowlisted miners can obtain keys to decrypt payloads.

#### 6.2 Managing Allowlisted Miners

* Add a miner:
  * `addSessionAllowedMiner(sessionId, minerAddr)` (owner only).
* Remove a miner:
  * `removeSessionAllowedMiner(sessionId, minerAddr)` (owner only).
* Query size:
  * `count = getAllowedMinersCount(sessionId)`.
* Paginate:
  * Use `getAllowedMiners(sessionId, offset, limit)` with `offset < count`.

Notes:

* Removing all miners **does not** revert `sessionEncryptionEnabled[sessionId]` to `false`.
* Dashboard should surface this:
  * “Once privacy is enabled, this session stays private; you can change which miners are allowed, but not turn privacy off.”

***

### 7. Ownership & Guards

* **Only the session owner** (as defined in `SessionData`) can:
  * Add miners via `addSessionAllowedMiner`.
  * Remove miners via `removeSessionAllowedMiner`.

This keeps the ownership model simple:

* One source of truth for *who controls a session* (SessionData owner).
* Session-level ACL tracks *which miners are allowed* to serve its private workloads.

There is **no separate router-owner** in this module; router identity/ownership is enforced via `SessionData`.

***

### 8. Optional Next Improvements

The current mock implementation already covers:

* O(1) add/remove membership.
* Paged enumeration.
* One-way privacy enable flag.

Potential next steps:

1. **Events (recommended)**

   * `SessionEncryptionEnabled(sessionId, by, timestamp)`
   * `SessionMinerAllowedAdded(sessionId, miner, by, timestamp)`
   * `SessionMinerAllowedRemoved(sessionId, miner, by, timestamp)`

   These allow router processes to subscribe and immediately refresh caches instead of polling.
2. **Batch operations**

   * `addSessionAllowedMiners(sessionId, address[] miners)`
   * `removeSessionAllowedMiners(sessionId, address[] miners)`

   Most helpful when sessions need to add/remove many miners at once.
3. **Combined status view**

   * `getSessionPrivacyStatus(sessionId) returns (bool enabled, uint256 allowedCount)`

   Useful for:

   * Dashboards.
   * Router introspection APIs.
   * Scripts that need a quick privacy snapshot.

***

### 9. Summary

* v0.5 defines a **contract-backed, session-based ACL** for private dedicated sessions.
* Core state:
  * `sessionAllowedMiners[sessionId][miner]`
  * `sessionAllowedMinerList[sessionId]`
  * `sessionAllowedMinerIndex[sessionId][miner]`
  * `sessionEncryptionEnabled[sessionId]`
* Core behaviors:
  * `addSessionAllowedMiner` (idempotent, O(1), auto-enables encryption on first use).
  * `removeSessionAllowedMiner` (O(1) swap-and-pop).
  * `getAllowedMinersCount` and `getAllowedMiners` (paged enumeration).
* Router changes:
  * For **private dedicated sessions**, key issuance must use **this contract ACL**.
  * Env-based ACL becomes **legacy/emergency** only for these flows.
  * Router must be updated to **read from the contract, cache results**, and only fall back to env when explicitly configured.
* UX:
  * Privacy is **one-way per session**.
  * Dashboard aligns with contract behavior and enforces that once `sessionEncryptionEnabled` is `true`, it stays `true`.

This keeps v0.5 privacy **simple, session-scoped, and effective**, while still leaving room for future task-level scoping or more advanced privacy policies in later versions.