> ## 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.

# Security Considerations

> Important security information for using and deploying SHIELD

# Security Considerations

This document covers security considerations for users and developers of SHIELD.

## For Users

### Link Security

The secure link is the only way to access encrypted content. Treat it accordingly:

<CardGroup cols={2}>
  <Card title="Copy Immediately" icon="copy">
    The link is only shown once. Screenshot or copy it immediately.
  </Card>

  <Card title="Share Securely" icon="share-nodes">
    Don't post links publicly. Use private channels (DMs, encrypted email).
  </Card>

  <Card title="Verify Recipient" icon="user-check">
    Double-check the wallet address before creating a policy.
  </Card>

  <Card title="Set Reasonable Limits" icon="clock">
    Don't set 1-hour expiration for someone in a different time zone.
  </Card>
</CardGroup>

### Wallet Security

Your wallet is your identity on SHIELD:

* **Never share** your private key or seed phrase
* **Verify** transaction details before signing
* **Use hardware wallets** for high-value accounts
* **Check** the URL is app.shieldhq.xyz before connecting

### Phishing Protection

Watch for these red flags:

| Legitimate                   | Phishing                  |
| ---------------------------- | ------------------------- |
| URL: `app.shieldhq.xyz`      | URL: `shield-app.xyz`     |
| Asks for SIWE signature      | Asks for private key      |
| Shows policy before signing  | Signs unknown transaction |
| HTTPS with valid certificate | Certificate warnings      |

### Content Visibility

Understand who can see what:

* **Before sharing**: Only you (encrypted on your device)
* **During sharing**: Only link holder (encryption key in URL)
* **After access**: Recipient has plaintext (save it if needed)
* **On-chain**: Only access metadata, never content

## For Developers

### Environment Variables

Never commit these to version control:

```bash theme={null}
# .env
POSTGRES_URL=postgresql://... # Database connection
PINATA_JWT=eyJ...             # IPFS pinning
JWT_SECRET=...                # Session signing
BASE_RPC_URL=...              # Base RPC endpoint
```

Use:

* `.env.example` for documentation
* `.env.local` for local development (gitignored)
* Platform env vars (Vercel, etc.) for production

### Database Security

PostgreSQL security checklist:

* [ ] Use connection pooling (PgBouncer)
* [ ] Enable SSL/TLS for connections
* [ ] Restrict IP allowlist
* [ ] Use strong passwords
* [ ] Enable query logging
* [ ] Regular backups

### API Security

Rate limiting is implemented:

```typescript theme={null}
// Default limits
const RATE_LIMITS = {
  createPolicy: '10 per minute',
  accessContent: '5 per minute',
  auth: '20 per 5 minutes',
  default: '100 per minute'
};
```

Customize in `src/lib/rateLimit.ts`.

### Smart Contract Security

Shield contract security features:

```solidity theme={null}
// Access control
require(msg.sender == policy.recipient, "Unauthorized");

// Replay protection
require(policy.attempts < policy.maxAttempts, "Max reached");

// Time validation
require(block.timestamp < policy.expiry, "Expired");

// State validation
require(policy.valid, "Policy invalid");
```

### Content Validation

Before uploading to IPFS:

* Validate file size limits
* Check MIME type if needed
* Scan for malware (if required)
* Sanitize filenames

### Dependency Security

Keep dependencies updated:

```bash theme={null}
# Audit dependencies
npm audit

# Check for known vulnerabilities
npm audit --audit-level high

# Update regularly
npm update
```

## Deployment Security

### Vercel Security

* Enable **Vercel Authentication** for deployments
* Use **Production Branch Protection**
* Enable **DDoS Protection**
* Configure **Custom Headers** for security

### Database Security (Neon)

```sql theme={null}
-- Create read-only user for API
CREATE USER shield_api WITH PASSWORD '...';
GRANT CONNECT ON DATABASE shield TO shield_api;
GRANT USAGE ON SCHEMA public TO shield_api;
GRANT SELECT, INSERT ON ALL TABLES IN SCHEMA public TO shield_api;
```

### Contract Deployment

Best practices:

1. **Test on Sepolia first**
2. **Verify source code** on BaseScan
3. **Use multisig** for admin functions
4. **Document** the deployment

## Incident Response

### Reporting Security Issues

Found a vulnerability? Contact us:

* **Email**: [shieldencrypted@gmail.com](mailto:shieldencrypted@gmail.com)
* **PGP**: [Key](https://shield.app/security.asc)
* **Bug Bounty**: [HackerOne](https://hackerone.com/shield)

### What to Include

* Description of the issue
* Steps to reproduce
* Potential impact
* Suggested fix (if any)

We aim to respond within 48 hours.

## Known Limitations

### Frontend Trust

Users must trust the JavaScript served by shield.app. Mitigations:

* Code is open source (auditable)
* Subresource Integrity (SRI) headers
* Content Security Policy (CSP)

### Browser Security

Encryption happens in the browser, which:

* Could have malware
* Could be using outdated browser
* Could have malicious extensions

Users are responsible for browser security.

### Social Engineering

Technical security can't prevent:

* Sending to wrong address (typo)
* Sharing link publicly
* Falling for phishing sites

User education is essential.

## Security Checklist

Before going to production:

* [ ] Environment variables secured
* [ ] Database SSL enabled
* [ ] Rate limiting configured
* [ ] CORS properly set
* [ ] Content Security Policy enabled
* [ ] Smart contract verified on BaseScan
* [ ] Dependencies audited
* [ ] Domain secured (DNSSEC, HTTPS)
* [ ] Monitoring alerts configured
* [ ] Incident response plan documented