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`

Key Functions:

createPolicy() - Store access conditions on-chain
logAttempt() - Record access attempts
isPolicyValid() - 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

​Architecture Overview

​System Architecture

​Components

​Client-Side Encryption

​IPFS Storage

​Smart Contracts

​Backend API

​Data Flow

​Creating a Link

​Accessing Content

​Security Boundaries

​Technology Stack