> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nullpass.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Security Features

> Security architecture and best practices

<Warning>
  **Internal Documentation Only:** If you're not a Null Tools developer, you can close this documentation or visit the [Apps section](/apps/coming-soon) to learn more about using Null Pass in your applications.
</Warning>

## Security Architecture

Null Pass implements multiple layers of security to protect user data and system integrity.

## Authentication Security

<AccordionGroup>
  <Accordion title="Password Hashing" icon="lock">
    **Algorithm:** bcrypt with 10 rounds

    * Passwords are never stored in plain text
    * Each password has unique salt
    * Hash comparison prevents timing attacks
    * Minimum 8 characters required
  </Accordion>

  <Accordion title="JWT Tokens" icon="key">
    **Token Structure:**

    * Contains userId and email
    * Signed with JWT\_SECRET
    * Expires after 7 days (configurable)
    * Stored in database with encrypted IP

    **Security:**

    * Tokens validated on every request
    * Expired tokens rejected
    * No token refresh mechanism (re-login required)
  </Accordion>

  <Accordion title="Two-Factor Authentication" icon="shield-check">
    **Implementation:** TOTP (Time-based One-Time Password)

    * 6-digit codes, 30-second period
    * Window of 2 (allows clock drift)
    * Secret stored in database
    * QR code generation for easy setup
  </Accordion>
</AccordionGroup>

## Data Protection

<AccordionGroup>
  <Accordion title="IP Address Encryption" icon="eye-slash">
    IP addresses are encrypted before storage:

    * User-specific encryption key
    * Decrypted only for display to same user
    * Prevents IP tracking across users
    * Encryption key derived from user ID

    **Implementation:** `lib/ip-utils.ts`
  </Accordion>

  <Accordion title="Password Storage" icon="database">
    * Never logged or exposed
    * Hashed with bcrypt before storage
    * No password history kept
    * Current password required for changes
  </Accordion>

  <Accordion title="Sensitive Data" icon="lock">
    Protected data:

    * Passwords (hashed)
    * 2FA secrets (stored, encrypted at rest if DB encryption enabled)
    * IP addresses (encrypted)
    * JWT tokens (not logged)
  </Accordion>
</AccordionGroup>

## Request Protection

<AccordionGroup>
  <Accordion title="Arcjet Integration" icon="shield">
    Multi-layer protection:

    * Rate limiting (token bucket)
    * Bot detection
    * Shield protection
    * Email validation
    * Sensitive info detection
  </Accordion>

  <Accordion title="CORS" icon="globe">
    Cross-Origin Resource Sharing:

    * Validates origin headers
    * Returns appropriate CORS headers
    * Prevents unauthorized cross-origin requests
  </Accordion>

  <Accordion title="Input Validation" icon="check">
    All inputs validated with Zod:

    * Type checking
    * Format validation
    * Length limits
    * Required field checks
  </Accordion>
</AccordionGroup>

## Session Security

<AccordionGroup>
  <Accordion title="Session Management" icon="clock">
    * Sessions expire after 7 days
    * IP address tracked (encrypted)
    * Users can view and revoke sessions
    * Session reuse for same IP
    * Automatic expiration cleanup
  </Accordion>

  <Accordion title="Session Storage" icon="database">
    * Stored in database (PostgreSQL)
    * Token stored with session
    * IP address encrypted
    * Expiration tracked
    * Cascade delete on user deletion
  </Accordion>
</AccordionGroup>

## Audit Logging

All critical actions are logged:

* User registration
* Login/logout
* Password changes
* 2FA enable/disable
* Profile updates
* Session creation/deletion
* Service access changes

**Audit Log Fields:**

* Action type (`AuditAction` enum)
* User ID
* Timestamp
* Additional data (JSON)

## Account Security

<AccordionGroup>
  <Accordion title="Account Ban" icon="ban">
    Users can be banned:

    * `banned` flag in database
    * Prevents all authentication
    * Logged in audit trail
  </Accordion>

  <Accordion title="Account Disable" icon="toggle-off">
    Users can be disabled:

    * `disabled` flag in database
    * Prevents authentication
    * Separate from ban (different use case)
  </Accordion>
</AccordionGroup>

## Environment Security

<ResponseField name="JWT_SECRET" type="string" required>
  Must be strong, random secret. Never commit to version control.
</ResponseField>

<ResponseField name="DATABASE_URL" type="string" required>
  Use connection string with SSL in production.
</ResponseField>

<ResponseField name="ARCJET_KEY" type="string" required>
  Keep Arcjet API key secure.
</ResponseField>

## Best Practices

<Warning>
  **For Production:**

  * Use strong JWT\_SECRET (minimum 32 characters, random)
  * Enable database encryption at rest
  * Use HTTPS only
  * Regularly rotate secrets
  * Monitor audit logs
  * Keep dependencies updated
</Warning>

<Tip>
  * Never log passwords or tokens
  * Use environment variables for secrets
  * Implement proper CORS policies
  * Regular security audits
  * Monitor failed login attempts
</Tip>

## Security Checklist

Use this checklist to verify all security measures are properly configured before deploying to production:

* [ ] Strong JWT\_SECRET configured
* [ ] Database uses SSL connection
* [ ] HTTPS enforced in production
* [ ] CORS properly configured
* [ ] Rate limiting active
* [ ] Audit logging enabled
* [ ] Regular security updates
* [ ] Secrets not in version control
* [ ] Database backups encrypted
* [ ] Error messages don't leak sensitive info

<Tip>
  You can check off items in this checklist as you verify each security measure. This helps ensure nothing is missed during deployment.
</Tip>