Stop shipping vibes.Ship verified code.

1# Firebase Auth Pack v1.2 -- Requirements
2# Source: PRD + domain research + Firebase Admin SDK docs
3# 38 requirements extracted, validated against live API
4# 9 capabilities, 22 authenticated endpoints + 2 public
5
6requirements:
7  - id: REQ-001
8    title: Single token verification with optional revocation check
9    risk: high
10    acceptance_criteria:
11      - POST /verify accepts Firebase ID token in request body
12      - Optional checkRevoked flag triggers network revocation check
13      - Returns uid, email, emailVerified, claims, iss, aud, iat, exp
14      - Returns generic 401 for any verification failure
15      - Does NOT distinguish between failure reasons in HTTP response
16
17  - id: REQ-003
18    title: User lookup by UID, email, and phone
19    risk: medium
20    acceptance_criteria:
21      - GET /users/:uid returns full user profile
22      - GET /users/by-email/:email returns user by email
23      - GET /users/by-phone/:phone returns user by phone (E.164)
24      - POST /users/batch accepts up to 100 mixed identifiers
25      - Returns 404 for unknown user, 400 for malformed input
26
27  - id: REQ-005
28    title: User CRUD with batch operations
29    risk: medium
30    acceptance_criteria:
31      - POST /users creates user (email, password, displayName, phone)
32      - PATCH /users/:uid updates whitelisted properties
33      - DELETE /users/:uid deletes single user (204)
34      - POST /users/:uid/disable and /enable toggle account state
35      - POST /users/batch-delete accepts up to 1000 UIDs
36      - GET /users returns paginated listing (maxResults, pageToken)
37
38  - id: REQ-007
39    title: Custom claims management
40    risk: high
41    acceptance_criteria:
42      - PUT /users/:uid/claims sets claims (replaces all existing)
43      - DELETE /users/:uid/claims clears all claims (204)
44      - Reserved claim names validated before SDK call
45      - Claims size validated (max 1000 chars serialized)
46
47  - id: REQ-009
48    title: Session cookie lifecycle
49    risk: high
50    acceptance_criteria:
51      - POST /sessions creates cookie from ID token + expiresIn
52      - POST /sessions/verify validates cookie with optional revocation
53      - Duration validated (5 min to 14 days per Firebase limits)
54
55  - id: REQ-011
56    title: Custom tokens and refresh token revocation
57    risk: high
58    acceptance_criteria:
59      - POST /tokens/custom mints token for UID with optional claims
60      - POST /users/:uid/revoke invalidates all refresh tokens
61      - Returns tokensValidAfterTime for confirmation
62
63  - id: REQ-013
64    title: Email action link generation
65    risk: medium
66    acceptance_criteria:
67      - POST /email-actions/password-reset generates reset link
68      - POST /email-actions/verification generates verification link
69      - POST /email-actions/sign-in generates passwordless sign-in link
70      - sign-in requires actionCodeSettings with url + handleCodeInApp
71
72  # ... 31 more requirements (REQ-002 through REQ-038)
73  # Full file: github.com/useshipwright/shipwright/builds/firebase-auth/spec/
74
75non_functional_requirements:
76  - id: NFR-001
77    title: Token verification latency
78    target: "<50ms p99"
79  - id: NFR-002
80    title: Test coverage
81    target: ">80% line coverage"
82  - id: NFR-003
83    title: Startup time
84    target: "<3s to healthy"
85
86constraints:
87  framework: Fastify 5
88  language: TypeScript (strict mode)
89  runtime: Node.js 22 LTS
90  test_runner: vitest
91  package_manager: pnpm
92  container: Docker (multi-stage, non-root)