# COPPA Compliance Documentation

## Overview

This document describes Lilith's compliance with the Children's Online Privacy
Protection Act (COPPA), including the 2025 amendments that took effect April
22, 2026.

COPPA requires operators of commercial websites and online services directed to
children under 13, or that knowingly collect personal information from children
under 13, to obtain verifiable parental consent before collecting, using, or
disclosing such information.

## Applicability

Lilith is a **mixed-audience** platform that may be used by children under 13.
While not exclusively directed to children, we implement COPPA protections for
any user under 13.

## Age Classification System

Users are classified into three categories based on date of birth:

| Classification | Age Range | Requirements                                            |
| -------------- | --------- | ------------------------------------------------------- |
| **MINOR**      | Under 13  | Verifiable parental consent required                    |
| **TEEN**       | 13-17     | Standard registration with age-appropriate restrictions |
| **ADULT**      | 18+       | Full access                                             |

## Implementation

### Age Verification Service

**Location:** `services/auth/src/age-verification.ts`

**Functions:**

- `calculateAge(dateOfBirth)` - Calculates age from date of birth
- `classifyUser(dateOfBirth)` - Returns MINOR, TEEN, or ADULT classification
- `validateDateOfBirth(dob)` - Validates and parses DOB input
- `isMinor(dateOfBirth)` - Returns true if under 13
- `requiresParentalConsent(dateOfBirth)` - Returns true if COPPA applies
- `getAgeRestrictions(classification)` - Returns feature restrictions

**Test Coverage:** 44 tests in `age-verification.test.ts`

### Parental Consent Service

**Location:** `services/auth/src/parental-consent.ts`

**Consent Flow (Email Plus Method):**

1. **Minor Attempts Registration**
   - User provides date of birth during registration
   - System detects user is under 13 and blocks direct registration

2. **Parent Email Required**
   - User must provide parent/guardian email address
   - Parent email must be different from child's email

3. **Consent Request Created**
   - Secure token generated (32-byte random hex)
   - Token valid for 48 hours
   - Request stored with child data, parent email, IP, user agent

4. **Parent Receives Email**
   - Email contains consent link with token
   - Clear explanation of data practices
   - Link to privacy policy

5. **Parent Reviews and Decides**
   - Parent clicks link and reviews request
   - Can grant or deny consent
   - Option for separate third-party disclosure consent

6. **Account Created (if granted)**
   - Child account created with parent link
   - Parent-child relationship recorded
   - Confirmation emails sent to both

**Test Coverage:** 33 tests in `parental-consent.test.ts`

### API Endpoints

| Method | Path                                 | Description                 |
| ------ | ------------------------------------ | --------------------------- |
| POST   | `/v1/auth/register-minor`            | Initiate minor registration |
| GET    | `/v1/auth/consent/:token`            | Get consent request details |
| POST   | `/v1/auth/consent/:token/grant`      | Parent grants consent       |
| POST   | `/v1/auth/consent/:token/deny`       | Parent denies consent       |
| GET    | `/v1/auth/consent/status/:requestId` | Check consent status        |
| POST   | `/v1/auth/consent/:childId/revoke`   | Parent revokes consent      |
| GET    | `/v1/users/:userId/children`         | List children for parent    |
| GET    | `/v1/users/:userId/parent`           | Get parent for child        |

## Age-Based Restrictions

### MINOR (Under 13)

| Feature                | Status                    |
| ---------------------- | ------------------------- |
| Parental consent       | **Required**              |
| Social features        | Disabled                  |
| Content sharing        | Disabled                  |
| Marketing emails       | Disabled                  |
| Data retention         | 365 days max              |
| Third-party disclosure | Requires separate consent |

### TEEN (13-17)

| Feature          | Status       |
| ---------------- | ------------ |
| Parental consent | Not required |
| Social features  | Enabled      |
| Content sharing  | Enabled      |
| Marketing emails | Opt-in only  |
| Data retention   | 730 days     |

### ADULT (18+)

| Feature          | Status           |
| ---------------- | ---------------- |
| Parental consent | Not required     |
| Social features  | Enabled          |
| Content sharing  | Enabled          |
| Marketing emails | Opt-in available |
| Data retention   | No limit         |

## Data Collection Practices

### Information Collected from Minors

- Email address (with parental consent)
- Name (optional, with parental consent)
- Date of birth
- Usage data necessary for service

### Information NOT Collected from Minors

- Precise geolocation
- Biometric data
- Social media integrations
- Behavioral advertising data

## Security Program Requirements

Per the 2025 COPPA amendments, we maintain a written children's personal
information security program that includes:

1. **Security Coordinator** - Designated personnel responsible for child data
   protection
2. **Risk Assessment** - Annual assessment of child data processing risks
3. **Safeguards** - Technical, administrative, and physical protections
4. **Testing** - Regular security testing and monitoring
5. **Service Provider Oversight** - Contractual requirements for vendors
6. **Retention Limits** - No indefinite retention; auto-deletion policies

## Consent Management

### Consent Ledger

All consent actions are recorded in a tamper-evident consent ledger with:

- Event ID and sequence number
- Hash chain for integrity verification
- Timestamp, IP address, user agent
- Policy version and consent text version

### Consent Types

| Type          | Description                                    |
| ------------- | ---------------------------------------------- |
| `privacy`     | Privacy policy acceptance                      |
| `terms`       | Terms of service acceptance                    |
| `parental`    | Parental consent for minor                     |
| `third-party` | Third-party disclosure consent                 |
| `marketing`   | Marketing communications (disabled for minors) |

### Consent Revocation

Parents can revoke consent at any time through:

1. Parent dashboard in the app
2. API endpoint: `POST /v1/auth/consent/:childId/revoke`
3. Email request to support

Upon revocation:

- Child account is deactivated
- Personal data is deleted within 30 days
- Notification sent to both parent and child

## Compliance Verification

### Automated Checks

- Age validation on all registration attempts
- Consent status verification before data collection
- Automatic token expiration after 48 hours
- Automatic cleanup of stale consent requests after 30 days

### Audit Trail

All COPPA-related actions are logged:

- Registration attempts by minors
- Consent request creation
- Consent grants and denials
- Consent revocations
- Data access and deletion

## Third-Party Considerations

### Service Providers

Vendors processing child data must:

1. Sign COPPA-compliant data processing agreements
2. Implement equivalent security measures
3. Delete child data upon request
4. Report any breaches immediately

### Safe Harbor Compliance

We follow FTC-approved Safe Harbor program guidelines where applicable.

## Contact Information

**Privacy Contact:** privacy@lilith.app

**COPPA Inquiries:** For questions about our children's privacy practices,
parents can contact us at coppa@lilith.app

## References

- [FTC COPPA Rule](https://www.ftc.gov/legal-library/browse/rules/childrens-online-privacy-protection-rule-coppa)
- [FTC COPPA FAQ](https://www.ftc.gov/business-guidance/resources/complying-coppa-frequently-asked-questions)
- [2025 COPPA Amendments](https://www.whitecase.com/insight-alert/unpacking-ftcs-coppa-amendments-what-you-need-know)

## Version History

| Version | Date       | Changes                |
| ------- | ---------- | ---------------------- |
| 1.0     | 2026-01-02 | Initial implementation |

---

_Last updated: January 2, 2026_
