Skip to content

λPrize 0018 #75

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
weboko wants to merge 1 commit into
base: master
Choose a base branch
from
Draft

λPrize 0018 #75

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
159 changes: 159 additions & 0 deletions prizes/LP-0018.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,159 @@
---
dependencies: []
---

# LP-0018: Reusable Encrypted Document Vault for KYC/KYB [DRAFT]

**`Status: Draft`**
**`Logos Circle: N/A`**

## Overview

This prize funds a **customer-owned, reusable encrypted document vault** for KYC/KYB and sensitive corporate documents, built end-to-end on the Logos stack with no centralised server. A customer — a **person or a company** — uploads sensitive documents **once** (passport, proof of address, certificate of incorporation, UBO and shareholder documents, board/shareholder resolutions, tax and onboarding documents), stores them **encrypted** in Logos Storage, and later grants a specific recipient — a bank, an exchange, a lawyer — **time-boxed access to selected files or packages**. When the relationship ends, the customer **revokes future access**. No document, and no sensitive metadata, ever leaves the customer's control in the clear.

Files are encrypted on the owner's device, stored as ciphertext in Logos Storage, and addressed by CID. Access state lives in a **LEZ program** that acts as the trustless authority for grants, revocation, and tamper-evident audit anchoring. Per-recipient wrapped keys and scoped capabilities are delivered over **Logos messaging**, including to recipients who are offline at share time. A wallet recipient fetches the ciphertext and **decrypts locally** — no intermediary ever sees plaintext.

The deliverable has two required parts: a **reusable vault module/SDK** (client-side encryption, key wrapping, grant management, and the LEZ program client, making no assumptions about the surrounding UI) and an **end application** (a working Logos Basecamp app for the owner and the wallet recipient, built on top of the module).

## Motivation

Company-formation and entity-management providers, and their customers, re-submit the *same* sensitive document packs dozens of times across an entity's lifecycle: incorporation, then a bank account, then an exchange account, then audits, then renewals. Today this means PII copied into email, third-party portals, and shared drives — repetitive, operationally expensive, and impossible to expire, revoke, or audit. Once a document is emailed, the customer has lost all control over it forever.

The Logos stack enables a cleaner model:

- **Logos Storage** holds the encrypted bytes durably and content-addressed, learning nothing but "a ciphertext blob of size N exists."
- **Logos messaging** delivers small per-recipient wrapped keys and capabilities peer-to-peer, with store-and-forward for recipients who are offline at share time.
- A **LEZ program** holds access-grant and revocation state as the trustless authority, and anchors a tamper-evident audit digest — without ever touching the documents or any cleartext metadata.

This is **primarily an encrypted file vault with reusable, controlled sharing** — not an identity, attestation, or zero-knowledge project. No sample app in the Logos ecosystem yet composes these primitives into the canonical "encrypted, reusable, revocably-shared document vault." This prize fills that gap and, as a side-effect, produces a reusable encryption-and-sharing module for any Logos application that needs controlled distribution of sensitive files. A competitive prize is the right mechanism because the building blocks already exist (LP-0017 demonstrates CID anchoring, LP-0005 demonstrates on-chain attestation, LP-0016 demonstrates an on-chain membership/revocation registry); the unsolved, design-sensitive work is composing them with **correct security semantics** — client-side envelope encryption, per-recipient key wrapping, honest revocation, and zero sensitive data on-chain — which is best discovered by letting builders compete against a precise, testable target.

## Core Mechanism

The design is constrained by three properties of the stack that every submission must respect:

- **Logos Storage does not encrypt and has no access control**, and a CID is a bearer pointer to whatever bytes it addresses. Therefore client-side encryption is the *only* confidentiality boundary, and **CIDs of sensitive blobs must be treated as secrets**, never published in the clear.
- **Logos messaging caps payloads (~150 kB) and rate-limits publishing.** It is a channel for **keys and capabilities, not bulk files**. Documents go in Logos Storage; only wrapped keys, CIDs, and capabilities travel over messaging.
- **On-chain state is permanent and world-readable.** Raw files, cleartext metadata, identities, and cleartext sharing relationships must **never** be placed on-chain or in data-availability blobs; only opaque IDs, **salted** commitments, ciphertext CIDs, and wrapped-key references may be anchored.

The expected cryptographic model:

- **Per-file Data Encryption Key (DEK)**, random per file/version, authenticated cipher (e.g. AES-256-GCM); the file is encrypted client-side before upload.
- **Envelope encryption**: the DEK is wrapped to the owner's key and, on each share, **wrapped to the recipient's public key** (ECIES over the wallet curve) so only the intended recipient can unwrap it.
- **Revocation** is enforced by the LEZ grant registry for *future* access; a **hard** guarantee against a recipient who has not yet downloaded is achieved by **key rotation / re-encryption** (new DEK → new ciphertext → new CID → re-wrap only to the still-authorized set). Plaintext already downloaded — or a DEK already unwrapped together with ciphertext already fetched — is, by construction, **not revocable**, and the submission must say so plainly.

## Success Criteria

Applications must not depend on any centralised server or service. Files live in **Logos Storage**; access and audit state live in a **LEZ program**; key/capability delivery and peer coordination use **Logos messaging**.

### Functionality

- [ ] **Vault ownership**: a vault can be created for an owner that is either a **person** or a **company**, bound to a Logos wallet identity, and is the sole authority over grants for its files.
- [ ] **Client-side encryption**: files are encrypted on the owner's device with a per-file random DEK using an authenticated cipher before upload. It is demonstrable that the blob fetched from Logos Storage by CID is unintelligible without the DEK — Logos Storage only ever receives ciphertext, and the plaintext and DEK never leave the client in the clear.
- [ ] **Encrypted storage with streaming**: ciphertext blobs are stored in Logos Storage and addressed by CID; a file of at least 100 MB uploads and downloads via streaming without loading the whole file into memory.
- [ ] **Envelope encryption and per-recipient key wrapping**: the DEK is wrapped to the owner's key and, on sharing, wrapped to each recipient's public key (ECIES over the wallet curve) such that only the intended recipient can unwrap it.
- [ ] **Minimized, encrypted metadata**: document metadata (display name, document type, subject entity/person, jurisdiction, issue/expiry dates, use-case tags) is encrypted at rest; no sensitive metadata appears in cleartext on Logos Storage or on-chain. Files can be organised and filtered by type, entity, person, jurisdiction, expiry, and use case.
- [ ] **Document packages**: the owner can bundle selected file versions into a named package and share it as a unit; shared file versions are pinned so a later upload does not silently change what was shared.
- [ ] **On-chain grant registry**: a LEZ program is the authority for access state. A grant records its target (file/package reference), recipient, permissions (`view` vs `download`), and a mandatory `expiry`. The registry is queryable by grant and accepts batch submissions of at least 10 grants/anchors per transaction. The program contains only opaque IDs, salted commitments, ciphertext CIDs, and wrapped-key references — never raw files, cleartext metadata, identities, or cleartext grant relationships, and never unsalted hashes of low-entropy documents.
- [ ] **Capability and key delivery over Logos messaging**: for a wallet recipient, the wrapped DEK(s), CID(s), and a scoped, expiring capability are delivered over Logos messaging. A recipient who is **offline at share time** retrieves them on reconnect (store-and-forward). Bulk file bytes are never sent over messaging.
- [ ] **Local decryption by recipient**: a wallet recipient fetches the ciphertext from Logos Storage and unwraps the DEK with their wallet key locally; no intermediary sees plaintext.
- [ ] **Auto-expiry**: after a grant's `expiry`, view and download are refused with no owner action required.
- [ ] **Revocation of future access**: the owner can revoke a grant, after which the registry denies future access. For a hard guarantee against a recipient who has not yet downloaded, the system supports key rotation / re-encryption (new DEK → new ciphertext → new CID → re-wrap only to the still-authorized set). It is explicitly documented (in `docs/security.md`) that plaintext already downloaded, or a DEK already unwrapped together with ciphertext already fetched, cannot be revoked.
- [ ] **Tamper-evident audit anchoring**: audit events (grant created / revoked / expired, version uploaded, and — where observable — view/download) are recorded, and a periodic digest (e.g. a Merkle root) is anchored on LEZ so the log is tamper-evident without revealing any event contents.
- [ ] **(Optional, secondary) Attestations**: an issuer can attach a signed statement about a file or package (e.g. `passport_checked`, `verified_by:<issuer>`), verifiable on-chain following the LP-0005 verifier pattern, displayed alongside the file. The submission must document that an attestation does not replace the underlying document.

### Usability

- [ ] Provide the vault logic as a **module/SDK** with a documented API for: create vault, upload (encrypt), list, package, grant, revoke, rotate keys, query access status, and read audit — importable by other Logos apps without modification.
- [ ] Provide a **Logos Basecamp app GUI** with local build instructions, downloadable assets, and loadable in Logos app (Basecamp), covering the owner flow (upload, classify, package builder, sharing modal **with a prominent warning that downloading is permanent and only future access can be stopped**, access management with revoke and rotate, audit log) and the wallet-recipient flow (receive grant, fetch, decrypt, view/download).
- [ ] Provide an IDL for the LEZ program, using the [SPEL framework](https://github.com/logos-co/spel).

### Reliability

- [ ] Upload to Logos Storage and capability delivery over Logos messaging retry transient failures with exponential back-off and surface a clear error after exhausting retries.
- [ ] Grant creation and capability re-delivery are idempotent and deduplicated: re-delivering a capability or re-broadcasting a grant does not create duplicate grants or duplicate audit entries (messaging retention is best-effort, so the owner/registry must be able to re-deliver a capability).
- [ ] Transient Logos stack failures (storage or messaging unavailability) are handled gracefully: pending uploads, grants, and deliveries are queued and retried rather than silently dropped.

### Performance

- [ ] A file of at least 100 MB is encrypted, uploaded, downloaded, and decrypted via streaming without loading the whole file into memory.
- [ ] Document the compute unit (CU) cost of each on-chain operation, including anchoring a single grant and a batch of 50 grants/audit-digests in one transaction, on LEZ devnet/testnet. Note: LEZ's per-transaction compute budget may change during testnet.

### Supportability

- [ ] The LEZ program is deployed and tested on LEZ devnet/testnet.
- [ ] End-to-end integration tests covering upload → grant → deliver → decrypt → revoke run against a LEZ sequencer in standalone mode and are included in CI.
- [ ] CI must be green on the default branch.
- [ ] A README documents end-to-end usage: deployment steps, program addresses, and step-by-step instructions for creating a vault, uploading and classifying a file, building and sharing a package, receiving and decrypting as a recipient, and revoking — via both CLI and the Basecamp app.
- [ ] A reproducible end-to-end demo script is provided and works against a real local sequencer with `RISC0_DEV_MODE=0`.
- [ ] A recorded video demo of the end-to-end flow is included in the submission; the recording must show terminal output (including proof generation) to confirm `RISC0_DEV_MODE=0` was active.

## Scope

### In Scope

- A reusable, **wallet-native, fully decentralized** encrypted document vault: client-side encryption, Logos Storage for ciphertext, a LEZ program (with SPEL IDL) for grant/revocation state and audit/commitment anchoring, and Logos messaging for capability and key delivery.
- A standalone **vault module/SDK** extracted from the app logic, with a documented API and usage examples, reusable without depending on the Basecamp app.
- A **Logos Basecamp app** covering the owner and the wallet-recipient experience, built on the module.
- Document packages, file/package-scoped grants, `view`/`download` permissions, mandatory expiry, revocation of future access, and key rotation / re-encryption for strong revocation.
- A `docs/security.md` covering the encryption and key-management model, the **honest sharing/revocation semantics** (what can and cannot be revoked), the **never-on-chain** data classification, and a threat model.
- **Optional, secondary:** issuer-signed attestations attached to files/packages.

### Out of Scope

- **Centralised web-link / email-OTP recipient flow.** Serving recipients who do not run a Logos wallet (e.g. a bank analyst with only a browser) requires a hosted gateway that handles plaintext at view time, which contradicts the no-centralised-server requirement and is explicitly excluded. (It is a valuable real-world extension — see *Potential for Subsequent λ Prizes*.)
- **Replacing a counterparty's KYC/AML obligations**, or treating attestations as a substitute for the underlying documents.
- **Making already-downloaded plaintext revocable** — cryptographically impossible; it must be documented, not solved.
- **Selective disclosure, redaction, or zero-knowledge "verified without documents" proofs** — future directions, not this prize.
- **Full decentralized identity (DID/SSI)** as a deliverable; wallet identity is used purely as a keypair and authentication mechanism.
- **Hosted infrastructure** beyond what is required to run the Logos Basecamp app.

## Prize Structure

- **Total Prize:** $X
- **Effort:** Large

Leave the prize pool blank — this will be determined by the Logos team. Single winner by default.

## Eligibility

Open to any individual or team. Submissions must be original work. Teams must hold the rights to all submitted code and agree to license it under MIT or Apache-2.0.

## Submission Requirements

- Public repository (MIT or Apache-2.0) containing:
- the **vault module/SDK** (client-side encryption, key wrapping, grant management, LEZ program client) with public API, documentation, and usage examples,
- the **LEZ program** (grant/revocation registry and audit/commitment anchoring) with its SPEL IDL,
- the **Logos Basecamp app** built on the module without modifying it,
- a **CLI** for the full lifecycle (create vault, upload, package, grant, revoke, rotate, query status, audit),
- integration tests runnable in CI against a standalone LEZ sequencer.
- `docs/security.md` covering: the encryption and key-management model, sharing and revocation semantics (explicitly stating what cannot be revoked once plaintext is downloaded), the data classification of what is and is not placed on-chain, and a threat model (malicious recipient, compromised capability, metadata leakage, wallet/key loss and recovery, storage node cannot read plaintext).
- Deployed LEZ program on devnet/testnet with documented program address.
- Compute unit benchmarks for single-grant and 50-grant/audit-digest batch operations.
- GitHub issues filed for any problems encountered with Logos technology.
- A narrated video walkthrough in which the builder explains what they built and why, walks through the architecture and key implementation decisions, and demonstrates (see [demo requirements](../README.md#evaluation-policies)):
- a document encrypted client-side and uploaded to Logos Storage, with the raw blob shown to be unintelligible without the DEK,
- a package granted to a wallet recipient who is **offline at share time**, receiving the capability over Logos messaging on reconnect, fetching the ciphertext, and **decrypting locally**,
- expiry auto-denial, revocation of future access, and key rotation / re-encryption (showing the new version/CID),
- the on-chain grant registry and audit anchor, with terminal output showing proof generation to confirm `RISC0_DEV_MODE=0`,
- evidence that no plaintext and no sensitive metadata appear on-chain or on Logos Storage.

Submissions must include a FURPS self-assessment as part of the solution (see [solution template](../solutions/LP-0000.md)).

## Evaluation Process

By default, submissions are evaluated first-come-first-served against the success criteria. The first submission that meets **all** non-optional criteria wins.

Evaluators will independently clone the repository and run the demo script from a clean environment with `RISC0_DEV_MODE=0`; the script must succeed without modification. Evaluators may also ask technical follow-up questions to verify authorship and understanding of the implementation.

The following policies apply to all prizes (see [evaluation policies](../README.md#evaluation-policies)):

- **Submissions:** each builder (or team) is allowed a maximum of **3 submissions** per prize, with at most **one submission/review per week**.
- **Feedback:** initial evaluation feedback is limited to a pass/fail indication against the success criteria.

## Resources

- [LEZ GitHub repository](https://github.com/logos-blockchain/logos-execution-zone)
- [SPEL framework](https://github.com/logos-co/spel)
- [Logos Storage (Codex)](https://github.com/logos-storage) — content-addressed encrypted blob storage; streaming upload/download; no native encryption or access control, so client-side encryption is mandatory.
- [Logos messaging](https://github.com/logos-messaging) — store-and-forward delivery and ECIES payload encryption over the wallet curve; ~150 kB payload cap, so carry keys and capabilities, not bulk files.
- [Logos Basecamp](https://github.com/logos-co/logos-basecamp) and the Logos module SDKs (`logos-cpp-sdk`, `logos-rust-sdk`) and modules (`logos-storage-module`, `logos-waku-module`, `logos-delivery-module`, `logos-wallet-module`, `logos-capability-module`).
Loading