# Private / Encrypted Inference v1.0 – Ephemeral Private Sessions (Draft Spec)

> Status: Early design draft\
> Scope: Extend private / encrypted inference from **dedicated private sessions** to **ephemeral private sessions**\
> Depends on: stability of v0 / v0.5 dedicated-session privacy flow first

***

### 1. Goal

v1.0 extends Cortensor’s privacy model from:

* **v0 / v0.5**
  * private **dedicated-node sessions**
  * static or semi-static ACL for key access

to:

* **v1.0**
  * private **ephemeral-node sessions**
  * dynamic ACL updates as ephemeral nodes are assigned and released

The core idea is:

> Keep the privacy model conceptually similar to dedicated sessions, but make the ACL lifecycle dynamic enough to follow ephemeral node assignment.

***

### 2. Why v1.0 Is Needed

Dedicated private sessions are comparatively simple:

* the dedicated miner set is known ahead of time
* allowlists can be configured once and reused
* session-scoped encryption works well with static membership

Ephemeral sessions are different:

* nodes are assigned dynamically
* nodes may change during the session lifecycle
* the set of nodes that should be allowed to obtain encryption keys is not fixed up front

So v1.0 needs a privacy model where:

* encryption remains **session-scoped**
* key access remains **ACL-based**
* but the ACL is updated **automatically** as ephemeral nodes enter and leave the session

***

### 3. Design Direction

#### 3.1 Reuse Existing PrivacySettingData

Current direction is to **reuse the existing `PrivacySettingData` module** rather than introduce a separate privacy data path for ephemeral sessions.

Why:

* keeps privacy state in one place
* avoids two parallel systems for dedicated vs ephemeral privacy
* lets routers and dashboards check one module for privacy status and allowed nodes
* reduces mental and implementation complexity

So v1.0 is not a “new privacy store”; it is an **extension of the existing privacy module**.

***

### 4. Core Model

#### 4.1 Dedicated vs Ephemeral Privacy in One Module

`PrivacySettingData` should evolve to support both:

* **dedicated private sessions**
* **ephemeral private sessions**

Conceptually, the module needs to know:

* whether a session is private
* what privacy mode the session uses
* which node addresses are currently allowed to obtain encryption keys for that session

A simple mental model:

* **Dedicated private session**
  * ACL changes rarely
  * nodes are manually configured / explicitly allowlisted
* **Ephemeral private session**
  * ACL changes automatically
  * nodes are inserted when assigned and removed when released

***

### 5. Session-Scoped Privacy Remains the Default

Even for ephemeral sessions, the design should stay **session-scoped**, not task-scoped.

That means:

* encryption keys are still derived from **session scope**
* nodes obtain key access because they are currently assigned to the session
* we do **not** create per-task encryption scopes in v1.0

This keeps the mental model aligned with v0.5:

> “If you are an allowed node for this private session, you can access that session’s scoped key while you are assigned.”

***

### 6. Ephemeral Privacy Lifecycle

#### 6.1 Enabling Privacy

When a user enables privacy on an **ephemeral session**:

1. Session is marked as:
   * private/encrypted
   * ephemeral privacy mode
2. The Session module becomes responsible for keeping ACL membership in sync with actual node assignment
3. Any ephemeral node assigned to that session is added to `PrivacySettingData` so it can request the session encryption key

#### 6.2 Node Assignment

When the Session module assigns an ephemeral node to a private session:

1. Session module performs the normal assignment flow
2. As part of that same flow, it adds the node address into `PrivacySettingData` for that session
3. From that point, the node is allowed to call:
   * session-scoped key issuance endpoint(s)
   * and decrypt session payloads for that private session

#### 6.3 Node Release

When an ephemeral node is released from that session:

1. Session module performs the normal release / cleanup flow
2. As part of that flow, it removes the node address from `PrivacySettingData`
3. From that point, the node should no longer be able to request session encryption keys for that session

This is the main difference from dedicated private sessions:

* dedicated = mostly static ACL
* ephemeral = ACL follows the assignment lifecycle

***

### 7. Session Module Responsibilities

v1.0 requires changes in the **Session module**, not just in the privacy module.

The Session module must add hooks in the places where ephemeral nodes are:

* assigned
* reassigned
* released
* force-removed
* expired / timed out

#### 7.1 Add Hook Points

The Session module should identify and instrument all lifecycle points where a node becomes “currently assigned” to a session.

At those points it should:

* call into `PrivacySettingData`
* add the node address to the session ACL if the session is private and ephemeral

#### 7.2 Remove Hook Points

Likewise, every place where a node is no longer authorized to serve that session should remove it from the ACL.

This includes:

* normal release
* replacement by another node
* timeout expiry
* cleanup after failure
* manual/admin release if supported

#### 7.3 Source of Truth

The Session module remains the **source of truth** for assignment state.

`PrivacySettingData` should not try to infer ephemeral membership by itself.

Instead:

* Session module decides who is assigned
* PrivacySettingData mirrors the allowed key-access set

That separation keeps the design simple:

* Session module = assignment authority
* PrivacySettingData = privacy/key ACL store

***

### 8. PrivacySettingData v1.0 Extension (Conceptual)

The module needs additional state so it can represent both dedicated and ephemeral private sessions.

Conceptually it should track:

* private flag for a session
* privacy mode for a session
  * dedicated
  * ephemeral
* allowed node addresses for that session
* optional metadata to distinguish:
  * manually added dedicated nodes
  * dynamically assigned ephemeral nodes

A simple conceptual structure:

* `sessionPrivacyEnabled[sessionId] -> bool`
* `sessionPrivacyMode[sessionId] -> enum { NONE, DEDICATED, EPHEMERAL }`
* `sessionAllowedMiners[sessionId][node] -> bool`

Optional future distinction:

* `sessionAllowedMinerSource[sessionId][node] -> enum { MANUAL, EPHEMERAL_ASSIGNMENT }`

That distinction is not strictly required for first implementation, but it may help with:

* debugging
* dashboards
* avoiding accidental removal of manually configured entries

***

### 9. Key Issuance Flow in v1.0

The encryption-key access pattern remains conceptually the same as v0.5:

1. Node receives an encrypted session payload
2. Node requests the session key from the router
3. Router verifies:
   * caller signature
   * session scope
   * ACL membership in `PrivacySettingData`
4. If authorized, router returns the session-scoped encryption key

What changes in v1.0 is **how the ACL gets populated**:

* dedicated sessions → mostly manual / owner-managed
* ephemeral sessions → Session module updates it dynamically

So from the router’s point of view, the key issuance path may stay almost the same:

* check session privacy enabled
* check node membership in privacy ACL
* issue session-scoped key if allowed

The complexity is shifted into Session-module lifecycle hooks.

***

### 10. Dashboard / UX Implications

#### 10.1 Private Ephemeral Session Enablement

When users enable privacy on an ephemeral session, the dashboard should clearly communicate:

* this is a private/encrypted ephemeral session
* assigned nodes will be dynamically granted temporary key access
* nodes removed from the session will lose key access

#### 10.2 Comparison to Dedicated Privacy

Dashboard should make the distinction visible:

* **Dedicated private session**
  * fixed / manually managed node ACL
* **Ephemeral private session**
  * dynamic ACL based on live assignment

This helps users understand why the node list can change over time for ephemeral sessions.

#### 10.3 Warnings / Constraints

UI should also warn that:

* privacy for ephemeral sessions may be more operationally complex than dedicated sessions
* dynamic membership means debugging may require viewing assignment history
* encryption still disables raw streaming-style flows if full payload encryption is used

***

### 11. Audit / Observability

Because ephemeral ACL membership is dynamic, observability becomes more important in v1.0.

At minimum, the system should record:

* when privacy was enabled for a session
* which nodes were added to ACL due to assignment
* which nodes were removed due to release
* why a node was removed:
  * normal release
  * timeout
  * failure
  * manual intervention

This can be implemented via:

* events in `PrivacySettingData`
* session events in the Session module
* dashboard history views

Without this, ephemeral privacy will be hard to debug.

***

### 12. Security Model

#### 12.1 Principle

A node should only be able to access a private session key if:

* it is currently assigned to that session, and
* the Session module has inserted it into the ACL

#### 12.2 Removal Matters

The remove path is just as important as the add path.

If removed nodes remain in the ACL too long, then:

* old nodes may continue to request keys after they should no longer serve the session

So v1.0 security depends on:

* correct add hooks
* correct remove hooks
* reliable cleanup on edge cases

#### 12.3 Session-Scoped Simplicity

Not introducing task-based encryption in v1.0 helps reduce security mistakes:

* no per-task ACL churn
* no task-by-task router updates
* less coordination overhead

That is why session scope remains the right design for this phase.

***

### 13. What Is Not in Scope Yet

This is still **rough design work**, not final implementation.

Not in scope yet:

* final storage layout for all new mappings
* exact function signatures
* exact event list
* exact dashboard UI flow
* full test matrix
* task-scoped privacy
* advanced key leasing / expiry policies
* TEE-backed private ephemeral sessions

Those can come after the dedicated-session path is stable and the ephemeral design is refined further.

***

### 14. Current Status

What has been done so far:

* rough design pass over the Session module
* identification of likely hook points where ephemeral nodes need to be:
  * added to privacy ACL
  * removed from privacy ACL
* high-level decision to **reuse `PrivacySettingData`** rather than create a new privacy path

What has **not** happened yet:

* implementation
* testing
* finalized storage / interface spec

So this document should be treated as:

> an early architectural direction for v1.0, not a final implementation contract

***

### 15. Summary

v1.0 extends private / encrypted inference from **dedicated private sessions** to **ephemeral private sessions** by reusing the existing `PrivacySettingData` module and making the **Session module** responsible for dynamic ACL updates.

The key model is:

* privacy stays **session-scoped**
* Session module adds assigned ephemeral nodes into privacy ACL
* Session module removes them again when released
* router continues to issue encryption keys based on session-scoped ACL membership

In one sentence:

> v1.0 keeps the dedicated-session privacy model intact, but makes it dynamic enough for ephemeral node assignment and release, without introducing a separate privacy data path or task-scoped encryption.