Documentation Index
Fetch the complete documentation index at: https://docs.shieldhq.xyz/llms.txt
Use this file to discover all available pages before exploring further.
Architecture Overview
SHIELD uses a hybrid architecture combining client-side encryption, decentralized storage, and on-chain access control to provide trustless secure file sharing.
System Architecture
┌─────────────────────────────────────────────────────────────────────┐
│ USER BROWSER │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Encrypt │ │ SIWE │ │ Contract │ │ Decrypt │ │
│ │ (Web Crypto)│ │ Sign │ │ Calls │ │ (Web Crypto)│ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
└─────────┼────────────────┼────────────────┼────────────────┼──────┘
│ │ │ │
▼ │ │ ▼
┌─────────────────┐ │ │ ┌─────────────────┐
│ IPFS │◀──────┘ └──────▶│ IPFS │
│ (Pinata) │ │ (Pinata) │
└─────────────────┘ └─────────────────┘
▲ │
│ │
│ ▼
│ ┌─────────────────────────────┐
│ │ SHIELD API │
│ │ ┌──────────┐ ┌──────────┐ │
└──────────────────────────────│ │ Policy │ │ Access │ │
│ │ Store │ │ Logs │ │
│ └──────────┘ └──────────┘ │
└──────────┬─────────────────┘
│
▼
┌─────────────────────────────┐
│ BASE BLOCKCHAIN │
│ ┌─────────────────────┐ │
│ │ Shield Contract │ │
│ │ ┌───────────────┐ │ │
│ │ │ AccessPolicy │ │ │
│ │ │ Mapping │ │ │
│ │ └───────────────┘ │ │
│ └─────────────────────┘ │
└─────────────────────────────┘
Components
Client-Side Encryption
All encryption happens in the browser using the Web Crypto API:
- Algorithm: AES-GCM 256-bit
- Key Generation: Crypto.getRandomValues (CSPRNG)
- IV: 96-bit random nonce
- Authentication: Built-in GCM tag
// Simplified encryption flow
const key = await crypto.subtle.generateKey(
{ name: 'AES-GCM', length: 256 },
true,
['encrypt', 'decrypt']
);
const encrypted = await crypto.subtle.encrypt(
{ name: 'AES-GCM', iv },
key,
fileData
);
IPFS Storage
Encrypted content is stored on IPFS via Pinata:
- Gateway:
https://gateway.pinata.cloud/ipfs/{cid}
- Persistence: Pinned via Pinata API
- Content Addressing: CID uniquely identifies encrypted content
- Decentralization: Content available through any IPFS node
Smart Contracts
The Shield contract on Base manages access policies:
| Network | Contract Address |
|---|
| Base Mainnet | 0x4b8F46e5E3d95D78f30F80F1280fE7e5F92c8ce8 |
createPolicy() - Store access conditions on-chainlogAttempt() - Record access attemptsisPolicyValid() - Check policy status
Backend API
Node.js/Next.js API for off-chain operations:
- Policy Metadata: Maps policy ID to IPFS CID
- Authentication: SIWE signature verification
- Rate Limiting: Sliding window per IP/address
- Session Management: JWT with 1-hour expiry
Data Flow
Creating a Link
Generate Key
Browser generates AES-256 key using Web Crypto API
Encrypt Content
File/message encrypted locally, never leaves browser unencrypted
Upload to IPFS
Encrypted blob uploaded to Pinata, returns CID
Create Policy
User signs transaction to store access policy on Base
Store Metadata
Backend stores policy ID → CID mapping in PostgreSQL
Generate Link
URL created with policyId and secretKey (fragment)
Accessing Content
Verify SIWE
Recipient signs message proving wallet ownership
Check Policy
Backend queries contract: valid? expired? attempts?
Log Access
Recipient signs transaction calling logAttempt()
Fetch Content
Browser fetches encrypted blob from IPFS
Decrypt
Secret key from URL fragment decrypts content locally
Security Boundaries
| Component | Trust Level | Data Access |
|---|
| Browser | Trusted | Unencrypted content |
| IPFS | Untrusted | Encrypted content only |
| Smart Contract | Trustless | Policy metadata only |
| Backend API | Trusted | Non-sensitive metadata |
| Sender | Trusted | Original content |
| Recipient | Verified | Decrypted content |
Technology Stack
| Layer | Technology |
|---|
| Frontend | Next.js 16, React 19, TypeScript, Tailwind CSS |
| State | React Query, Wagmi, Viem |
| Wallet | RainbowKit, WalletConnect |
| Crypto | Web Crypto API (AES-GCM 256) |
| Contracts | Solidity 0.8.24, Hardhat |
| Network | Base (Ethereum L2) |
| Storage | IPFS via Pinata |
| Database | PostgreSQL (Neon) |
| Hosting | Vercel |
