@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.
- package/LICENSE +21 -0
- package/README.md +24 -2
- package/dist/config.d.ts +181 -0
- package/dist/config.d.ts.map +1 -0
- package/dist/config.js +301 -0
- package/dist/config.js.map +1 -0
- package/dist/errors.d.ts +20 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +42 -0
- package/dist/errors.js.map +1 -0
- package/dist/files.d.ts +9 -0
- package/dist/files.d.ts.map +1 -0
- package/dist/files.js +25 -0
- package/dist/files.js.map +1 -0
- package/dist/index.d.ts +5 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +5 -0
- package/dist/index.js.map +1 -0
- package/dist/requirements.d.ts +34 -0
- package/dist/requirements.d.ts.map +1 -0
- package/dist/requirements.js +53 -0
- package/dist/requirements.js.map +1 -0
- package/package.json +47 -3
- package/specs/AUTHENTICATION_SPEC.md +398 -0
- package/specs/AUTHORIZATION_SPEC.md +135 -0
- package/specs/CONFIGURATION_SPEC.md +117 -0
- package/specs/CONFORMANCE.md +125 -0
- package/specs/DATA_MODEL.md +140 -0
- package/specs/ERRORS.md +50 -0
- package/specs/OPTIONAL_CAPABILITIES.md +63 -0
- package/specs/SECURITY_REQUIREMENTS.md +243 -0
|
@@ -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.
|