RFC: Client-Side Encryption by fforbeck · Pull Request #56 · storacha/RFC

fforbeck · 2025-06-10T17:41:41Z

Problem: Our current encryption requires users to manage crypto wallets & has no fallback if Lit Protocol is down. This blocks mainstream adoption.

Solution: Add social login authentication (Google/Discord/etc) via Lit Providers + PKPs, and use our Gateway as fallback system that works when Lit is unavailable. Storacha pays all crypto costs transparently.

Key Benefits:

Zero crypto knowledge needed - users authenticate with existing social accounts
Browser compatibility - works in web apps, not just Node.js
Resilient architecture - files accessible even during Lit outages
Security improvements - fixes current revocation gaps

Impact: Transforms encryption from "developer power-user feature" into mainstream privacy solution that competes with centralized providers on UX while maintaining security through client-side encryption.

BravoNatalie · 2025-06-18T19:28:54Z

client-side-encryption.md

+This RFC addresses the identified limitations through a strategy that maintains the security properties of the existing system while improving usability, reliability, and enterprise sales opportunities. The proposal introduces **seven key improvements**:
+
+### 2.1 Hybrid Architecture: Lit Protocol + Google KMS
+


Why not give customers the option to integrate their own KMS solution?
I know it would add some complexity, but it could help reduce our role as a centralized party in the privacy setup, at least from the perspective of our direct customers. It might also lower the cost for them to use private data.

Great idea. I just don't know what it would require in terms of time and development effort. I believe we could start simple with one cloud provider’s KMS (e.g., Google KMS). Then, if demand grows, incrementally add Bring Your Own Key as a premium enterprise feature.

I think that if this is something we might want in the future, then during development we could prioritize implementing it with an interface, and use the Google KMS solution as an adapter. That way, it keeps things flexible and it shouldn’t require too much effort.

alanshaw

Do we need to restrict gateway access to Google KMS? Can it also do the Lit flow?

alanshaw · 2025-06-19T10:56:10Z

client-side-encryption.md

+
+- **Privacy Tier**: Lit Protocol end-to-end encryption for maximum privacy
+- **Compliance Tier**: Google KMS with enterprise certifications (SOC 2, FIPS 140-2, ISO 27001)
+- **Hybrid Tier**: Lit Protocol + KMS backup for redundancy


Suggestion: offer compliance/hybrid to business plan holders only.

I think it makes sense to offer the Compliance tier for Business plan holders only, but the Hybrid tier could be beneficial for Lite users as well, because they will have Lit and may want a fallback strategy that doesn't rely on Lit only. WDYT?

client-side-encryption.md

alanshaw · 2025-06-19T11:11:46Z

client-side-encryption.md

+
+- **User Registration Process**
+
+  - When users create PKPs through social authentication, their PKP addresses are automatically added to Storacha's allowlist


Can you speak to how this works? How does Lit know a minted PKP should be added to our allowlist?

This is described in section 2.3 Payment Delegation System, but every time a new user is onboarded, we need to send a request to the Payment Delegation System API to include that new PKP as a payee that will consume credits from the Storacha Payer account.

client-side-encryption.md

alanshaw · 2025-06-19T12:44:21Z

client-side-encryption.md

+
+### 2.4 Revocation System Implementation
+
+Implement a new endpoint for revocation checking that validates delegation status during both Lit Action execution and gateway-based decryption. This closes the security gap where revoked delegations continue to grant access.


The gateway based decryption has been pitched as a fallback if Lit is unavailable up until this point. Is gateway decryption a feature in itself? Can the gateway use Lit also? Why would the gateway not just return the decrypted DEK and let the client do the decryption as before?

So the question is whether "gateway" needs to be a part of this or if we just run a "trusted Lit fallback server" that you make the same request to, should the Lit request fail.

Separately, how does the key get in Google KMS as well as Lit? How does this fallback work?

Is gateway decryption a feature in itself?

Yes.

Can the gateway use Lit also?

Gateway could technically use Lit, but the whole point is to keep it as a reliable fallback separate from Lit (in case Lit becomes expensive or unstable).

Why would the gateway not just return the decrypted DEK

Great idea 🔥 We could still do client-side decryption as before, and it would preserve end-to-end encryption. I think it would cut the costs and simplify the decryption flow, the only thing that we would need to implement would be the Access Control - to return the DEK only if that request is authorized to decrypt the content. Also, for enterprise customers, we would need to check the compliance requirements. I liked this approach, sounds better, and we could return the DEK encrypted with the issuer's public key.

alanshaw · 2025-06-19T13:17:05Z

client-side-encryption.md

+    Note over User, GoogleKMS: Revocation Check - Gateway Implementation
+
+    alt Lit Protocol Unavailable
+        User->>Gateway: Request file with UCAN invocation


I guess you are looking for this to land - #60

Sweet! That's exactly what we need - I was thinking about limiting this usage to the CLI and SDK, but with this RFC in place, we can enable it for direct HTTP requests. Super cool!

alanshaw · 2025-06-19T13:21:03Z

client-side-encryption.md

+  "googleKMS": {
+    "keyName": "projects/PROJECT/locations/LOCATION/keyRings/RING/cryptoKeys/SPACE_ID",
+    "encryptedDEK": "kms_encrypted_dek"
+  }


You might want to put these in an array to imply a desired ordering?

alanshaw · 2025-06-19T13:23:09Z

client-side-encryption.md

+  },
+  "googleKMS": {
+    "keyName": "projects/PROJECT/locations/LOCATION/keyRings/RING/cryptoKeys/SPACE_ID",
+    "encryptedDEK": "kms_encrypted_dek"


What is it that stops a user going direct to google to get the key?

projects/PROJECT/locations/LOCATION/keyRings/RING/cryptoKeys/SPACE_ID is just a pointer, not a credential or access token. We control the KMS, and we need to grant access via IAM credentials for our services to access it, so the users can't fetch it.

alanshaw · 2025-06-19T13:44:50Z

client-side-encryption.md

+
+    alt Delegation Valid
+        RevocationAPI-->>LitProtocol: ✅ Active delegation
+        LitProtocol-->>Client: Return decrypted DEK


Should this be encrypted with the issuer public key?

YES! Good call!

alanshaw · 2025-06-19T13:48:30Z

client-side-encryption.md

+    participant User
+    participant StorachaClient
+    participant CryptoAdapter
+    participant LitSDK


What is the difference between LitSDK and Lit Protocol in these diagrams?

Same thing. I just missed that after several updates.

fforbeck · 2025-06-19T16:56:25Z

Do we need to restrict gateway access to Google KMS? Can it also do the Lit flow?

Gateway probably shouldn't decrypt via Lit. The idea is exactly to have a separate, reliable path (via Google KMS) if Lit is down or pricey. Also, mixing Lit into Gateway might complicate compliance stuff for enterprise customers. I think we would need more research to confirm this.

Co-authored-by: ash <alan@storacha.network>

BravoNatalie · 2025-06-20T14:12:48Z

client-side-encryption.md

+
+> Programmable Key Pairs (PKPs) are ECDSA public/private key pairs created by the Lit network using Distributed Key Generation (DKG). Each Lit node holds a share of the private key, and more than two-thirds of these shares must be collected to execute a given action (i.e. signing a transaction).
+> ref: https://developer.litprotocol.com/user-wallets/pkps/overview
+


I think this definition is a bit confusing, especially since the docs also mention that PKPs are NFTs.
So I would also add this:

The PKP is represented as an NFT, and whoever owns this NFT controls the key pair and can set custom signing logic or access rules.
ref: https://developer.litprotocol.com/user-wallets/pkps/quick-start#mint-a-pkp-and-add-permitted-scopes

BravoNatalie · 2025-06-20T14:28:19Z

client-side-encryption.md

+
+  - **Registration**: Storacha registers as a payer with its own PKP wallet and capacity credits
+  - **Key Management**: Maintains a secure master payer secret key for delegation database operations
+  - **Centralized Funding**: Funds capacity credits for all user operations through a single account, eliminating individual user payment complexity


I understand that we’re going to sponsor their usage, but I was wondering, beyond the plans that include access to private data, do we have a defined quota for capacity credits included in each plan? And will there be an extra charge if the user exceeds that limit?
Basically, what’s the maximum amount of capacity credits we’re allowing per plan?

RFC: Client-Side Encryption

796786a

fforbeck self-assigned this Jun 10, 2025

Added info about Lit default backup mechanism

628749e

fforbeck requested a review from a team June 10, 2025 17:58

fforbeck added 3 commits June 10, 2025 15:06

Added info about Stytch email auth flow

fe9611c

more fixes

1cdadf8

Update client-side-encryption.md

da77677

BravoNatalie reviewed Jun 18, 2025

View reviewed changes

fforbeck requested a review from a team June 19, 2025 12:20

alanshaw reviewed Jun 19, 2025

View reviewed changes

fforbeck and others added 2 commits June 19, 2025 13:59

Update client-side-encryption.md

f468708

Co-authored-by: ash <alan@storacha.network>

Update client-side-encryption.md

4dc767e

Co-authored-by: ash <alan@storacha.network>

BravoNatalie reviewed Jun 20, 2025

View reviewed changes

		This RFC addresses the identified limitations through a strategy that maintains the security properties of the existing system while improving usability, reliability, and enterprise sales opportunities. The proposal introduces seven key improvements:

		### 2.1 Hybrid Architecture: Lit Protocol + Google KMS


		- User Registration Process

		- When users create PKPs through social authentication, their PKP addresses are automatically added to Storacha's allowlist


		### 2.4 Revocation System Implementation

		Implement a new endpoint for revocation checking that validates delegation status during both Lit Action execution and gateway-based decryption. This closes the security gap where revoked delegations continue to grant access.


		> Programmable Key Pairs (PKPs) are ECDSA public/private key pairs created by the Lit network using Distributed Key Generation (DKG). Each Lit node holds a share of the private key, and more than two-thirds of these shares must be collected to execute a given action (i.e. signing a transaction).
		> ref: https://developer.litprotocol.com/user-wallets/pkps/overview

Conversation

fforbeck commented Jun 10, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alanshaw left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fforbeck commented Jun 19, 2025

Uh oh!

BravoNatalie Jun 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

BravoNatalie Jun 20, 2025 •

edited

Loading