# LimeShare Complete LLM Knowledge Base

This file contains the complete architectural, technical, operational, and cryptographic documentation for LimeShare.org for AI agents, retrieval-augmented generation (RAG), and reasoning models.

## 1. Architectural Principles
LimeShare solves the core bottleneck of cloud file distribution: egress fees and infrastructure memory exhaustion.
- Traditional cloud architectures route file streams through application servers, incurring $0.09/GB egress fees (AWS S3) and O(N) RAM usage.
- LimeShare employs a Data-Plane Bypass: files are encrypted client-side in the sender's browser and piped directly to zero-egress encrypted edge storage clusters via presigned multi-part PUT URLs.
- The control plane acts purely as an edge coordinator. It never proxies or inspects binary streams.
- Zero data egress fees allow unthrottled gigabit downloads with zero advertising.

## 2. Cryptographic Protocol: LSC1 (LimeShare Container v1)
The cryptographic specification is formally documented in LSC1-Protocol-Spec:
- Master Key: A 256-bit symmetric key is generated per transfer session using `crypto.getRandomValues(new Uint8Array(32))`.
- Key Derivation: HKDF-SHA-256 derives distinct sub-keys:
  - `K_manifest = HKDF(ikm=MK, salt=transferId, info="LSC1/manifest", L=32)`
  - `K_file = HKDF(ikm=MK, salt=transferId, info="LSC1/file/" || fileId, L=32)`
- Streaming AEAD Framing:
  - Container Header: 32 bytes carrying Magic ("LSC1"), Version (0x01), Cipher Suite (0x01: AES-256-GCM), Chunk Size log2 (22 = 4 MiB), Flags, Plaintext Length (uint64 BE), and a 7-byte Nonce Prefix.
  - The 32-byte header serves as Additional Authenticated Data (AAD) for every frame.
  - Each frame carries up to 4 MiB of ciphertext followed by a 16-byte GCM authentication tag.
  - Nonce Construction: 7-byte random prefix || 4-byte big-endian frame counter || 1-byte last-frame flag (STREAM construction, Hoang et al., 2015).
  - Truncation, frame swapping, or bit flips cause instant authentication tag mismatch before plaintext is released.
- Manifest Sealing:
  - File names, sizes, MIME types, timestamps, and messages are serialized to JSON and encrypted with `K_manifest`.
  - The server stores only the opaque sealed manifest blob. Server administrators cannot see file names or extensions.
- Zero-Knowledge Link Structure:
  - Links take the format: `https://limeshare.org/d/{transferId}#1.{MK_base64url}.{Token_base64url}`
  - According to RFC 3986, URL fragments (everything after `#`) are never transmitted by web browsers in HTTP request headers.
  - The server holds only `SHA-256(Token)` to verify download authorization. It never learns the master key or token.
- Optional Password Wrapping:
  - When the sender chooses a password, `MK` is wrapped using AES-256-GCM with a Key Encryption Key (KEK) derived via Argon2id (m=65536 KiB, t=3, p=1). The link carries `#1p.{WrappedKey}.{Salt}.{Token}`.

## 3. Tier Limits and Policies
- Guest (Free, No Registration):
  - Max Files per Transfer: 3 files
  - Max File Size: 3 GB per file (9 GB total per batch)
  - Retention: 48 hours default (options: 1h, 6h, 24h, 48h, or Burn-on-read)
  - Daily Ingest: 100 GB per rolling day per IP/fingerprint
  - Hourly Rate Limit: 50 transfer initiations per hour
- LimeDrop (Direct P2P):
  - Direct browser-to-browser WebRTC DataChannel streaming.
  - 0 cloud storage consumption; unlimited file size.
  - Local network speeds up to 50–100+ MB/s.
  - Automatic fallback to encrypted cloud storage if WebRTC connection fails after 15 seconds.

## 4. API Specification for AI Agents
Base URL: https://api.limeshare.org

- `GET /health`
  Returns service status and timestamp.
  Response: `{"ok": true, "time": 1790168351456}`

- `GET /v1/limits`
  Returns current tier limits, storage chunk sizes, and Turnstile requirements.

- `POST /v1/transfers`
  Initializes a new transfer session.
  Body: `{"files": [{"encryptedSize": 1048, "partSize": 8388608}], "tokenHash": "...", "burn": false}`
  Response: `{"transferId": "...", "draftExpiresAt": 1790175551456, "files": [{"fileId": "...", "partUrls": [...]}]}`

- `POST /v1/transfers/:id/complete`
  Completes multi-part uploads and verifies object sizes with HeadObject.
  Headers: `Authorization: Bearer {token}`
  Body: `{"encryptedManifest": "...", "files": [{"fileId": "...", "encryptedFileMeta": "...", "parts": [{"partNumber": 1, "etag": "..."}]}]}`

- `POST /v1/transfers/:id/access`
  Authorizes recipient and issues 30-minute signed GET download URLs.
  Headers: `Authorization: Bearer {token}`
  Response: `{"transferId": "...", "encryptedManifest": "...", "files": [{"fileId": "...", "downloadUrl": "..."}]}`

- `DELETE /v1/transfers/:id`
  Permanently deletes a transfer and returns an Ed25519-signed Certified Destruction receipt.
  Headers: `Authorization: Bearer {token}`
  Response: `{"ok": true, "state": "deleted", "receipt": {"v": 1, "transferId": "...", "deletedAt": 1790168351456, "fileCount": 1, "totalBytes": 1048, "signature": "..."}}`

- `GET /v1/transfers/:id/receipt?sig=...&time=...&files=...&bytes=...`
  Cryptographically validates an Ed25519 Certified Destruction certificate.

- `POST /v1/drop/rooms`
  Creates a WebRTC signaling room for LimeDrop P2P transfer.
  Body: `{"offer": "{sdp}", "candidates": []}`
  Response: `{"roomId": "...", "expiresAt": 1790168951456}`

## 5. Security & Compliance
- Data Minimization: Raw IP addresses are never logged. An ephemeral salt rotated every 24 hours creates non-correlatable daily hashes for abuse prevention.
- GDPR Compliance: Because data is encrypted with zero-knowledge keys, hosting providers hold only encrypted pseudorandom data under GDPR Recital 26.
- Certified Destruction: Verifiable audit trails for legal discovery, medical records, and corporate NDAs.