@selfauth/spec 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,243 @@
1
+ # Security requirements
2
+
3
+ - **specVersion:** 0.1 (draft — open for review)
4
+ - **Related:** [AUTHENTICATION_SPEC](AUTHENTICATION_SPEC.md) ·
5
+ [AUTHORIZATION_SPEC](AUTHORIZATION_SPEC.md) ·
6
+ [CONFIGURATION_SPEC](CONFIGURATION_SPEC.md)
7
+
8
+ Cross-cutting rules every adapter must meet. Implementations MUST use
9
+ established, maintained libraries for every cryptographic primitive; SelfAuth
10
+ never defines custom cryptography.
11
+
12
+ ## 1. Password hashing
13
+
14
+ - **[SEC-HASH-001]** (MUST) Passwords MUST be hashed with Argon2id using a
15
+ maintained library. Where an adapter's platform has no maintained Argon2id
16
+ implementation, the fallback (scrypt, then bcrypt) MUST be recorded in an ADR.
17
+ - **[SEC-HASH-002]** (MUST) Argon2id parameters MUST be at least
18
+ m = 19 MiB, t = 2, p = 1 (or m = 46 MiB, t = 1, p = 1), with a random salt of
19
+ ≥ 16 bytes generated per hash by the library. Parameters are configurable
20
+ (`authentication.password.hashing`) but MUST NOT be configurable below these
21
+ floors.
22
+ - **[SEC-HASH-003]** (MUST) Hashes MUST be stored in a self-describing format
23
+ (PHC string) that records algorithm and parameters.
24
+ - **[SEC-HASH-004]** (SHOULD) Hashes with parameters below the current
25
+ configuration SHOULD be upgraded on the next successful verification.
26
+ - **[SEC-HASH-005]** (MUST) Before hashing or verifying, passwords MUST be
27
+ normalized with Unicode NFKC and MUST NOT be otherwise altered (no trimming,
28
+ no case folding, no silent truncation). This keeps hashes portable between
29
+ adapters in different languages.
30
+ - **[SEC-HASH-006]** (MUST) Hashing MUST NOT block the server's request-handling
31
+ thread/event loop for other requests (use the library's asynchronous or
32
+ worker-based API where the platform requires it).
33
+ - **[SEC-HASH-007]** (MUST NOT) Passwords MUST NOT be stored, logged, cached,
34
+ or transmitted anywhere in recoverable form, including reversible encryption.
35
+
36
+ ## 2. Password policy
37
+
38
+ - **[SEC-PWPOLICY-001]** (MUST) Passwords MUST have a minimum length, configurable,
39
+ default **12** characters, and the configuration MUST reject values below 8.
40
+ (NIST SP 800-63B-4 recommends 15 for passwords used as a single factor;
41
+ projects may raise the default.)
42
+ - **[SEC-PWPOLICY-002]** (MUST) A maximum length MUST be enforced before hashing
43
+ (default 128 characters; never below 64) to bound hashing cost; over-long
44
+ passwords fail with `PASSWORD_POLICY_VIOLATION`, never by truncation.
45
+ - **[SEC-PWPOLICY-003]** (MUST) All Unicode characters, including spaces, MUST be
46
+ accepted. Composition rules (e.g. "one digit, one symbol") MUST NOT be
47
+ required.
48
+ - **[SEC-PWPOLICY-004]** (SHOULD) Passwords SHOULD be checked against a list of
49
+ common/breached passwords bundled with the application (offline by default).
50
+ Online breach-check services MAY be offered only as opt-in configuration
51
+ (ADR 0002).
52
+ - **[SEC-PWPOLICY-005]** (MUST NOT) Periodic forced password rotation MUST NOT
53
+ be required by default.
54
+ - **[SEC-PWPOLICY-006]** (SHOULD) A password equal to the user's email address
55
+ (case-insensitively) SHOULD be rejected.
56
+
57
+ ## 3. Random values and one-time tokens
58
+
59
+ - **[SEC-TOKEN-001]** (MUST) Session tokens, password-reset tokens, and
60
+ email-verification tokens MUST contain at least 256 bits of entropy from the
61
+ platform's cryptographically secure random number generator, encoded as
62
+ base64url (or hex).
63
+ - **[SEC-TOKEN-002]** (MUST) Only a SHA-256 (or stronger) hash of each token MUST
64
+ be stored. Tokens MUST be looked up by hash; raw tokens MUST NOT be persisted.
65
+ - **[SEC-TOKEN-003]** (MUST) One-time tokens MUST be single-use, have a bounded
66
+ expiry, be bound to one user and one purpose (a reset token is never accepted
67
+ as a verification token or vice versa), and be consumed atomically.
68
+ - **[SEC-TOKEN-004]** (MUST) All token failures (unknown, expired, used, wrong
69
+ purpose, user no longer eligible) MUST produce the single error code
70
+ `TOKEN_INVALID`.
71
+ - **[SEC-TOKEN-005]** (MUST) Pages that receive tokens via links MUST send
72
+ `Referrer-Policy: no-referrer`; email links SHOULD carry tokens in the URL
73
+ fragment and the page SHOULD submit them with `POST`.
74
+
75
+ ## 4. Cookies
76
+
77
+ - **[SEC-COOKIE-001]** (MUST) The session cookie MUST be `HttpOnly`, `Secure`,
78
+ `Path=/`, and `SameSite=Lax` or `Strict` (default `Lax`). It MUST NOT be
79
+ readable by client-side script.
80
+ - **[SEC-COOKIE-002]** (MUST) In production the cookie name MUST default to
81
+ `__Host-session` (which forbids a `Domain` attribute). A `Domain` attribute
82
+ MUST NOT be set unless explicitly configured.
83
+ - **[SEC-COOKIE-003]** (MUST) `Secure` MAY be disabled only for development on
84
+ `http://localhost`, only by explicit configuration, and MUST cause a startup
85
+ error if the environment is production.
86
+ - **[SEC-COOKIE-004]** (MUST) The cookie expiry (`Max-Age`/`Expires`) MUST NOT
87
+ exceed the session's absolute expiry.
88
+ - **[SEC-COOKIE-005]** (MUST) Cross-site deployments that require
89
+ `SameSite=None` MUST be an explicit configuration choice and MUST still meet
90
+ §5 (token-based CSRF protection becomes mandatory).
91
+
92
+ ## 5. CSRF and cross-origin requests
93
+
94
+ - **[SEC-CSRF-001]** (MUST) Every state-changing operation authenticated by
95
+ cookie — and the login and registration operations — MUST be CSRF-protected.
96
+ - **[SEC-CSRF-002]** (MUST) Safe methods (HTTP `GET`, `HEAD`, `OPTIONS`) MUST NOT
97
+ change state.
98
+ - **[SEC-CSRF-003]** (MUST) For unsafe methods, the server MUST verify the
99
+ request origin: reject if `Sec-Fetch-Site` is `cross-site`, or if `Origin`
100
+ is present and not in the configured trusted-origins list. If neither
101
+ `Origin` nor `Sec-Fetch-Site` is present, the request MUST be rejected unless
102
+ it carries a valid CSRF token (§5 SEC-CSRF-004).
103
+ - **[SEC-CSRF-004]** (MUST) In addition to origin verification, unsafe requests
104
+ MUST present either (a) a CSRF token bound to the session (synchronizer or
105
+ signed double-submit token), or (b) a required custom request header (default
106
+ `X-SelfAuth-CSRF: 1`) with a CORS policy that never allows untrusted origins.
107
+ Option (a) is mandatory when `SameSite=None` is configured.
108
+ - **[SEC-CSRF-005]** (MUST) CSRF failures MUST return `CSRF_FAILED` and record a
109
+ `csrf.rejected` event (rate limited).
110
+ - **[SEC-CORS-001]** (MUST NOT) The server MUST NOT reflect arbitrary `Origin`
111
+ values in `Access-Control-Allow-Origin` together with
112
+ `Access-Control-Allow-Credentials: true`; allowed origins come from explicit
113
+ configuration only.
114
+ - **[SEC-REDIRECT-001]** (MUST) Any post-login or post-action redirect target
115
+ accepted from the client MUST be validated as a same-origin relative path
116
+ (open-redirect protection).
117
+
118
+ ## 6. Rate limiting and brute-force protection
119
+
120
+ - **[SEC-RATE-001]** (MUST) Login and password-change attempts MUST be limited
121
+ per normalized email (or user) and per client address. Defaults: 5 failed
122
+ attempts per account per 15 minutes, 100 attempts per address per 15
123
+ minutes, with exponential back-off.
124
+ - **[SEC-RATE-002]** (MUST) Registration, password-reset requests, and
125
+ verification resends MUST be limited per normalized email and per client
126
+ address.
127
+ - **[SEC-RATE-003]** (MUST NOT) Rate limiting MUST NOT permanently lock accounts
128
+ automatically; blocks are temporary.
129
+ - **[SEC-RATE-004]** (MUST) Rate-limited requests MUST fail with `RATE_LIMITED`
130
+ and SHOULD include a retry-after hint. The rate-limited response MUST be the
131
+ same whether or not the account exists.
132
+ - **[SEC-RATE-005]** (MUST) The client address MUST be derived from the
133
+ connection unless trusted proxies are explicitly configured; forwarding
134
+ headers (`X-Forwarded-For`, `Forwarded`) MUST NOT be trusted by default.
135
+ - **[SEC-RATE-006]** (SHOULD) Production deployments with more than one
136
+ application instance SHOULD use a shared rate-limit store; adapters MUST
137
+ document when their default store is per-process.
138
+
139
+ ## 7. Account enumeration
140
+
141
+ - **[SEC-ENUM-001]** (MUST) Login, password-reset request, verification resend,
142
+ and registration (unless `revealExistingEmail` is enabled) MUST return responses that are
143
+ indistinguishable (status code, body, headers other than request IDs)
144
+ whether or not an account exists.
145
+ - **[SEC-ENUM-002]** (MUST) (WITHDRAWN) Replaced by [SEC-ENUM-004].
146
+ - **[SEC-ENUM-004]** (MUST) Settings that permit account enumeration MUST be
147
+ off by default, MUST be enabled explicitly in configuration, and adapters MUST
148
+ document them as a privacy trade-off. Diagnostic tooling (`selfauth doctor`)
149
+ MUST warn when one is enabled.
150
+ - **[SEC-ENUM-003]** (SHOULD) Response timing SHOULD NOT reveal account
151
+ existence; in particular work such as sending email SHOULD be done in a way
152
+ that does not lengthen only the "account exists" path (e.g. queued).
153
+
154
+ ## 8. Secrets and environment configuration
155
+
156
+ - **[SEC-SECRET-001]** (MUST NOT) Secrets (database credentials, email provider
157
+ keys, CSRF signing keys) MUST NOT appear in the SelfAuth configuration file,
158
+ generated source code, or committed files. They are read from the
159
+ environment.
160
+ - **[SEC-SECRET-002]** (MUST) Generators MUST create `.env.example` with
161
+ placeholder values only, and MUST ensure `.env` is git-ignored.
162
+ - **[SEC-SECRET-003]** (MUST) Required configuration (including the application
163
+ base URL and any signing key) MUST be validated at startup; the application
164
+ MUST refuse to start if it is missing or invalid.
165
+ - **[SEC-SECRET-004]** (MUST) Signing keys, when used, MUST be ≥ 256 bits of
166
+ random data and SHOULD support rotation (accept previous key while issuing
167
+ with the current one).
168
+
169
+ ## 9. Security events (audit)
170
+
171
+ - **[SEC-AUDIT-001]** (MUST) Implementations MUST record at least these events:
172
+ `user.registered`, `auth.login.succeeded`, `auth.login.failed`,
173
+ `auth.logout`, `auth.sessions.revoked_all`, `password.changed`,
174
+ `password.reset.requested`, `password.reset.completed`, `email.verified`,
175
+ `account.state_changed`, `role.assigned`, `role.removed`,
176
+ `role.permissions_changed`, `rate_limit.triggered`, `csrf.rejected`.
177
+ - **[SEC-AUDIT-002]** (MUST) Each event MUST record: type, timestamp, outcome,
178
+ user ID (if known), actor ID (if different), client address, user agent, and
179
+ request ID where available, plus event-specific metadata.
180
+ - **[SEC-AUDIT-003]** (MUST NOT) Event metadata MUST NOT contain passwords,
181
+ password hashes, session tokens, one-time tokens, or their hashes.
182
+ - **[SEC-AUDIT-004]** (MUST) The generated code MUST NOT expose an operation that
183
+ updates or deletes individual security events; retention/purging is a
184
+ separate, application-controlled job.
185
+ - **[SEC-AUDIT-005]** (SHOULD) Security events SHOULD be written through a sink
186
+ interface so applications can forward them to their own logging/SIEM.
187
+
188
+ ## 10. Logging and error output
189
+
190
+ - **[SEC-LOG-001]** (MUST) Application logs MUST redact: request fields named
191
+ `password`, `currentPassword`, `newPassword`, `token`; `Cookie`,
192
+ `Set-Cookie`, and `Authorization` headers; and any value matching a session
193
+ or one-time token.
194
+ - **[SEC-LOG-002]** (MUST NOT) Error responses in production MUST NOT include
195
+ stack traces, SQL, internal identifiers of other users, or library error
196
+ messages.
197
+ - **[SEC-LOG-003]** (SHOULD) Every response SHOULD carry a request ID that also
198
+ appears in logs and security events, to correlate incidents.
199
+
200
+ ## 11. Transport and headers
201
+
202
+ - **[SEC-HTTP-001]** (MUST) Authentication responses MUST include
203
+ `Cache-Control: no-store`.
204
+ - **[SEC-HTTP-002]** (MUST) Production deployments MUST serve authentication over
205
+ HTTPS; adapters SHOULD document HSTS.
206
+ - **[SEC-HTTP-003]** (MUST) Request body size for authentication operations MUST
207
+ be bounded (`http.bodyLimitBytes`, default 16 KiB).
208
+
209
+ ## 12. Threat model (summary)
210
+
211
+ Assets: credentials, session tokens, one-time tokens, account state, role
212
+ assignments, security events, personal data (email).
213
+
214
+ Actors: anonymous internet attacker; authenticated low-privilege user;
215
+ attacker with read access to a database backup; malicious site visited by a
216
+ user (CSRF); attacker who can inject script into the app (XSS).
217
+
218
+ | Threat / abuse case | Mitigation (requirements) |
219
+ | --- | --- |
220
+ | Credential stuffing, password guessing | SEC-RATE-001, SEC-RATE-003, SEC-PWPOLICY-004, AUTHN-LOGIN-006 |
221
+ | Account enumeration (login, reset, register, timing) | SEC-ENUM-001, SEC-ENUM-003, AUTHN-LOGIN-002/003, AUTHN-REG-005/009/010 (opt-out: AUTHN-REG-011, SEC-ENUM-004) |
222
+ | Database leak → offline cracking / token reuse | SEC-HASH-001…003, SEC-TOKEN-002, AUTHN-SESS-002 |
223
+ | Session fixation | AUTHN-LOGIN-005 |
224
+ | Session theft via XSS | SEC-COOKIE-001 (HttpOnly); XSS prevention itself is application-owned |
225
+ | Stolen session after password change/reset | AUTHN-PWCHG-003, AUTHN-RESET-010, AUTHN-SESS-006 |
226
+ | CSRF, login CSRF | SEC-CSRF-001…005, SEC-CORS-001, SEC-COOKIE-001 |
227
+ | Reset/verify token replay or race | SEC-TOKEN-003, AUTHN-RESET-009, AUTHN-VERIFY-006 |
228
+ | Token leakage via Referer / logs | SEC-TOKEN-005, SEC-LOG-001 |
229
+ | Host-header poisoning of reset links | AUTHN-VERIFY-009, AUTHN-RESET-006 |
230
+ | Mass assignment of role/state at registration | AUTHN-REG-002, AUTHZ-ADMIN-005 |
231
+ | Privilege escalation via role delegation | AUTHZ-ADMIN-002, AUTHZ-ADMIN-003 |
232
+ | IDOR / horizontal access | AUTHZ-RES-001…006 |
233
+ | Trusting frontend role checks | AUTHZ-CORE-003, AUTHZ-CORE-004 |
234
+ | DoS via long passwords / large bodies | SEC-PWPOLICY-002, SEC-HTTP-003, SEC-HASH-006 |
235
+ | Spoofed client IP evading rate limits | SEC-RATE-005 |
236
+ | Lockout of victims by attackers | SEC-RATE-003 |
237
+ | Open redirect after login | SEC-REDIRECT-001 |
238
+ | Secrets committed to repository | SEC-SECRET-001, SEC-SECRET-002 |
239
+ | Repudiation of admin actions | AUTHZ-ADMIN-001, SEC-AUDIT-001…004 |
240
+
241
+ Out of scope for this spec: XSS and injection prevention in application code,
242
+ infrastructure hardening, email deliverability, and phishing — the adapters
243
+ document recommended practices.