diff --git a/hub_ownership_recovery_design.md b/hub_ownership_recovery_design.md new file mode 100644 index 0000000..7b5fdc9 --- /dev/null +++ b/hub_ownership_recovery_design.md @@ -0,0 +1,192 @@ +# Decentralized Hub Ownership and Recovery Design (PKI-Based, No Blockchain) + +## 1. Keys and DIDs (Conceptual Model) + +For each Hub, define three logical components: + +### 1. Hub Owner Key (Kₒ) + +- Long‑term key pair defining the **owner** of the Hub DID. +- Private key never leaves the user's devices. +- DID example: `did:key:`. +- Ultimate authority for the Hub. + +### 2. Hub Operational Key (Kₕ) + +- Key pair used by the **server instance** running the Hub. +- Private key stored on the Hub backend server. +- Granted authority via a signed **delegation certificate** from Kₒ. + +### 3. Recovery Secret / Code (R) + +- High‑entropy secret generated **client-side** (NextJS). +- Used to derive Kₒ (e.g., `Kₒ = KDF(R, "hub-owner")`). +- Shown **only once**. +- **Never stored on any server.** + +### Additional Component: Passport DID (Dᴘ) + +The user's self-sovereign identity. Contains a verifiable claim linking +the user to ownership of the Hub DID. + +------------------------------------------------------------------------ + +## 2. Creating a Hub and Binding Ownership to a Passport + +### Step 1: Generate Owner Identity (Client-Side) + +1. Generate random secret `R`. +2. Derive owner key pair `Kₒ`. +3. Compute Hub DID: `Dᴴ = did:key:`. +4. Show recovery code R to user for offline storage. + +### Step 2: Create Operational Identity (Server-Side) + +1. Server generates new key pair `Kₕ`. +2. Client fetches `pub(Kₕ)` securely. + +### Step 3: Delegate Authority (Client → Server) + +Create a delegation certificate: + + { + hubDid: Dᴴ, + delegatedTo: pub(Kₕ), + privileges: ["serve-hub", "sign-hub-messages"], + issuedAt: t₀, + expiresAt: t₁ + } + +Sign the certificate with `Kₒ`, then upload it to the server. + +### Step 4: Bind Hub to Owner's Passport + +Add a verifiable claim: + +``` json +{ + "subject": Dᴘ, + "claim": { + "type": "HubOwnership", + "hubDid": Dᴴ, + "role": "owner" + } +} +``` + +Signed by the Passport key, optionally also by Kₒ. + +------------------------------------------------------------------------ + +## 3. Normal Operation + +When interacting with other Hubs, a Hub sends: - Hub DID (`Dᴴ`) - +Delegation certificate (`Kₒ → Kₕ`) - Its operational public key +(`pub(Kₕ)`) + +Peers verify: 1. Certificate signature matches `pub(Kₒ)` encoded in +`Dᴴ`. 2. Message signatures match `pub(Kₕ)`. 3. Ownership via Passport +profile (if desired). + +**Owner = controls Kₒ**\ +**Server = controls Kₕ (delegated)** + +------------------------------------------------------------------------ + +## 4. Handling a Server Compromise + +If a hacker takes over the server: - They gain `Kₕ`. - They **do not** +have `R` or `Kₒ`. + +The owner must: 1. Launch a new Hub on a new server. 2. Broadcast a +signed compromise notice. 3. Prove ownership via signatures from `Kₒ`. + +### 4.1 Reconstructing Kₒ from R (If Needed) + +User enters recovery code R on a safe device: - Derive +`Kₒ = KDF(R, "hub-owner")`. - Validate that its DID matches the Hub DID +Dᴴ. + +### 4.2 Create New Operational Key (Kₕ′) + +New server generates `Kₕ′`. + +Owner creates a new delegation certificate: + + Kₒ → Kₕ′ + +Owner also signs a **revocation** of the old operational key: + + { + hubDid: Dᴴ, + revokedKey: pub(Kₕ), + reason: "Server compromised", + revokedAt: t₂ + } + +### 4.3 Broadcasting the Recovery + +New Hub publishes: - `hubDid: Dᴴ` - new endpoint - new `pub(Kₕ′)` - new +delegation certificate - revocation of `pub(Kₕ)` - optional +Passport-signed confirmation + +The attacker cannot: - sign new delegations (requires `Kₒ`) - sign +revocations (requires `Kₒ`) - change the Hub DID (`pub(Kₒ)`) + +------------------------------------------------------------------------ + +## 5. Trust Decision Model (No Consensus) + +Each Hub or human owner decides independently what to trust. + +### Typical Validation Rules + +1. Accept only messages signed by an operational key currently + delegated by `Kₒ`. +2. Respect revocations signed by `Kₒ`. +3. Track a local chain of: + - delegations\ + - revocations\ + - Passport claims + +No global ledger required. + +### Human Decision Layer + +Owners may also use: - Out‑of‑band communication - Social trust - Direct +evidence from the Passport DID + +------------------------------------------------------------------------ + +## 6. Recovery Code Requirements + +The design satisfies your constraints: + +- **Never stored on a server.** +- Generated client-side only. +- Used only to derive `Kₒ` when recovering ownership. +- Never transmitted over the network. +- Attackers cannot derive R or Kₒ from any server compromise. + +------------------------------------------------------------------------ + +## 7. Optional Refinements + +- Multi-sig ownership (`Kₒ` split across devices). +- Time‑bound delegations. +- Owner-signed references to external identities (website, company + DID, etc.). +- More expressive Passport claims. + +------------------------------------------------------------------------ + +## Summary + +This design provides: - **Hub DID ownership backed by PKI**, no +blockchain needed. - **Recovery mechanism based on a secret code (R)** +that never touches servers. - **Revocation and redelegation** driven by +the owner key (Kₒ). - **Human‑centric trust decisions**, no consensus +protocol. + +The attacker cannot permanently hijack a Hub unless they obtain the +recovery code.