Examples and Use Cases

---
name: my-app-user-authentication
version: 1.0.0
description: User authentication specification for My App
author: Your Name
email: [email protected]
license: MIT
step: 20
dependencies: my-app/database/specs[users-schema.md], my-app/security/specs[encryption.md#password]
---

## Overview
User authentication system supporting email/password and OAuth 2.0 (Google, Facebook).

## Requirements

### Libraries
- bcrypt ^5.1.0
- jsonwebtoken ^9.0.0
- passport ^0.6.0

### Installation
```bash
npm install bcrypt jsonwebtoken passport
```

## Workflow
1. User submits credentials
2. Validate input format
3. Check user existence in database
4. Verify password hash
5. Generate JWT token
6. Return token to client

## Details

### Function: authenticateUser

**Parameters:**
- email: string (required, valid email format)
- password: string (required, minimum 8 characters)

**Returns:**
- Promise<{ token: string, user: UserProfile }>

**Implementation:**
```typescript
export async function authenticateUser(
  email: string,
  password: string
): Promise<{ token: string; user: UserProfile }> {
  // Validate email format
  if (!isValidEmail(email)) {
    throw new ValidationError('Invalid email format');
  }

  // Query database for user
  const user = await db.users.findOne({ email });
  if (!user) {
    throw new AuthError('Invalid credentials');
  }

  // Verify password using bcrypt
  const isValid = await bcrypt.compare(password, user.passwordHash);
  if (!isValid) {
    throw new AuthError('Invalid credentials');
  }

  // Generate JWT token
  const token = jwt.sign(
    { userId: user.id, email: user.email },
    process.env.JWT_SECRET,
    { expiresIn: '24h' }
  );

  return { token, user: user.profile };
}
```

### Error Handling
- **ValidationError:** Invalid email format or password requirements not met
- **AuthError:** User not found or password mismatch
- **DatabaseError:** Database connection or query failure

### Testing Requirements
```typescript
describe('authenticateUser', () => {
  it('should return token for valid credentials', async () => {
    const result = await authenticateUser('[email protected]', 'Password123!');
    expect(result.token).toBeDefined();
    expect(result.user.email).toBe('[email protected]');
  });

  it('should throw ValidationError for invalid email', async () => {
    await expect(
      authenticateUser('invalid-email', 'Password123!')
    ).rejects.toThrow(ValidationError);
  });

  it('should throw AuthError for wrong password', async () => {
    await expect(
      authenticateUser('[email protected]', 'WrongPassword')
    ).rejects.toThrow(AuthError);
  });
});
```

---
name: my-app-user-profile
version: 1.0.0
description: User profile management
dependencies: my-app/database/specs[users-schema.md],
              *my-app/auth/specs[authentication.md],
              **https://cdn.example.com/shared/specs[validation.md]
---