@selfauth/spec 0.0.0-stage → 0.2.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/dist/files.js ADDED
@@ -0,0 +1,25 @@
1
+ import { readFile } from "node:fs/promises";
2
+ import { fileURLToPath } from "node:url";
3
+ import { parseRequirements } from "./requirements.js";
4
+ /** Normative specification documents, in reading order. */
5
+ export const SPEC_FILES = [
6
+ "AUTHENTICATION_SPEC.md",
7
+ "AUTHORIZATION_SPEC.md",
8
+ "SECURITY_REQUIREMENTS.md",
9
+ "DATA_MODEL.md",
10
+ "ERRORS.md",
11
+ "CONFIGURATION_SPEC.md",
12
+ "CONFORMANCE.md",
13
+ "OPTIONAL_CAPABILITIES.md",
14
+ ];
15
+ /** Absolute path of the bundled `specs/` directory. */
16
+ export const SPEC_DIR = fileURLToPath(new URL("../specs/", import.meta.url));
17
+ export async function readSpecFile(name) {
18
+ return readFile(new URL(`../specs/${name}`, import.meta.url), "utf8");
19
+ }
20
+ /** Parse every requirement defined in the bundled specification. */
21
+ export async function loadRequirements() {
22
+ const all = await Promise.all(SPEC_FILES.map(async (name) => parseRequirements(await readSpecFile(name), name)));
23
+ return all.flat();
24
+ }
25
+ //# sourceMappingURL=files.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"files.js","sourceRoot":"","sources":["../src/files.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,iBAAiB,EAAoB,MAAM,mBAAmB,CAAC;AAExE,2DAA2D;AAC3D,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,wBAAwB;IACxB,uBAAuB;IACvB,0BAA0B;IAC1B,eAAe;IACf,WAAW;IACX,uBAAuB;IACvB,gBAAgB;IAChB,0BAA0B;CAClB,CAAC;AAEX,uDAAuD;AACvD,MAAM,CAAC,MAAM,QAAQ,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,WAAW,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAE7E,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAiC;IAClE,OAAO,QAAQ,CAAC,IAAI,GAAG,CAAC,YAAY,IAAI,EAAE,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC;AACxE,CAAC;AAED,oEAAoE;AACpE,MAAM,CAAC,KAAK,UAAU,gBAAgB;IACpC,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,GAAG,CAC3B,UAAU,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,iBAAiB,CAAC,MAAM,YAAY,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC,CAClF,CAAC;IACF,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC;AACpB,CAAC"}
@@ -0,0 +1,5 @@
1
+ export * from "./requirements.js";
2
+ export * from "./errors.js";
3
+ export * from "./config.js";
4
+ export * from "./files.js";
5
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}
package/dist/index.js ADDED
@@ -0,0 +1,5 @@
1
+ export * from "./requirements.js";
2
+ export * from "./errors.js";
3
+ export * from "./config.js";
4
+ export * from "./files.js";
5
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC"}
@@ -0,0 +1,34 @@
1
+ /**
2
+ * Requirement parsing for the SelfAuth specification (ADR 0007).
3
+ *
4
+ * A requirement is written in Markdown as:
5
+ * - **[AUTHN-LOGIN-001]** (MUST) Login MUST ...
6
+ */
7
+ export declare const REQUIREMENT_LEVELS: readonly ["MUST", "MUST NOT", "SHOULD", "SHOULD NOT", "MAY"];
8
+ export type RequirementLevel = (typeof REQUIREMENT_LEVELS)[number];
9
+ export interface Requirement {
10
+ /** Stable ID, e.g. `AUTHN-LOGIN-001`. */
11
+ id: string;
12
+ level: RequirementLevel;
13
+ /** True when the requirement has been withdrawn (`(WITHDRAWN)` marker). */
14
+ withdrawn: boolean;
15
+ /** Requirement text with Markdown line breaks collapsed. */
16
+ text: string;
17
+ /** Source document name, e.g. `AUTHENTICATION_SPEC.md`. */
18
+ source: string;
19
+ /** 1-based line number of the definition. */
20
+ line: number;
21
+ }
22
+ /** Shape of a requirement ID: AREA(-TOPIC)*-NNN. */
23
+ export declare const REQUIREMENT_ID_PATTERN: RegExp;
24
+ /** True for MUST / MUST NOT requirements, which require conformance coverage. */
25
+ export declare function isMandatory(requirement: Pick<Requirement, "level" | "withdrawn">): boolean;
26
+ /**
27
+ * Extract requirement definitions from one Markdown document.
28
+ * Continuation lines (indented, until a blank line or the next list item) are
29
+ * appended to the requirement text.
30
+ */
31
+ export declare function parseRequirements(markdown: string, source: string): Requirement[];
32
+ /** IDs referenced anywhere in a document as `[ID]` (definitions included). */
33
+ export declare function findRequirementReferences(markdown: string): string[];
34
+ //# sourceMappingURL=requirements.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"requirements.d.ts","sourceRoot":"","sources":["../src/requirements.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,kBAAkB,8DAA+D,CAAC;AAC/F,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnE,MAAM,WAAW,WAAW;IAC1B,yCAAyC;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,gBAAgB,CAAC;IACxB,2EAA2E;IAC3E,SAAS,EAAE,OAAO,CAAC;IACnB,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;CACd;AAED,oDAAoD;AACpD,eAAO,MAAM,sBAAsB,QAA6B,CAAC;AAQjE,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,OAAO,GAAG,WAAW,CAAC,GAAG,OAAO,CAI1F;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,EAAE,CA4BjF;AAED,8EAA8E;AAC9E,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAEpE"}
@@ -0,0 +1,53 @@
1
+ /**
2
+ * Requirement parsing for the SelfAuth specification (ADR 0007).
3
+ *
4
+ * A requirement is written in Markdown as:
5
+ * - **[AUTHN-LOGIN-001]** (MUST) Login MUST ...
6
+ */
7
+ export const REQUIREMENT_LEVELS = ["MUST", "MUST NOT", "SHOULD", "SHOULD NOT", "MAY"];
8
+ /** Shape of a requirement ID: AREA(-TOPIC)*-NNN. */
9
+ export const REQUIREMENT_ID_PATTERN = /[A-Z]+(?:-[A-Z]+)*-\d{3}/;
10
+ const DEFINITION = new RegExp(String.raw `^\s*-\s+\*\*\[(${REQUIREMENT_ID_PATTERN.source})\]\*\*\s+\((MUST NOT|MUST|SHOULD NOT|SHOULD|MAY)\)(\s+\(WITHDRAWN\))?\s*(.*)$`);
11
+ const REFERENCE = new RegExp(String.raw `\[(${REQUIREMENT_ID_PATTERN.source})\]`, "g");
12
+ /** True for MUST / MUST NOT requirements, which require conformance coverage. */
13
+ export function isMandatory(requirement) {
14
+ return (!requirement.withdrawn && (requirement.level === "MUST" || requirement.level === "MUST NOT"));
15
+ }
16
+ /**
17
+ * Extract requirement definitions from one Markdown document.
18
+ * Continuation lines (indented, until a blank line or the next list item) are
19
+ * appended to the requirement text.
20
+ */
21
+ export function parseRequirements(markdown, source) {
22
+ const lines = markdown.split(/\r?\n/);
23
+ const result = [];
24
+ let current;
25
+ lines.forEach((raw, index) => {
26
+ const match = DEFINITION.exec(raw);
27
+ if (match) {
28
+ current = {
29
+ id: match[1],
30
+ level: match[2],
31
+ withdrawn: match[3] !== undefined,
32
+ text: match[4].trim(),
33
+ source,
34
+ line: index + 1,
35
+ };
36
+ result.push(current);
37
+ return;
38
+ }
39
+ const continues = current && raw.trim() !== "" && /^\s+\S/.test(raw) && !/^\s*-\s/.test(raw);
40
+ if (continues && current) {
41
+ current.text = `${current.text} ${raw.trim()}`.trim();
42
+ }
43
+ else {
44
+ current = undefined;
45
+ }
46
+ });
47
+ return result;
48
+ }
49
+ /** IDs referenced anywhere in a document as `[ID]` (definitions included). */
50
+ export function findRequirementReferences(markdown) {
51
+ return [...markdown.matchAll(REFERENCE)].map((m) => m[1]);
52
+ }
53
+ //# sourceMappingURL=requirements.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"requirements.js","sourceRoot":"","sources":["../src/requirements.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,KAAK,CAAU,CAAC;AAiB/F,oDAAoD;AACpD,MAAM,CAAC,MAAM,sBAAsB,GAAG,0BAA0B,CAAC;AAEjE,MAAM,UAAU,GAAG,IAAI,MAAM,CAC3B,MAAM,CAAC,GAAG,CAAA,kBAAkB,sBAAsB,CAAC,MAAM,gFAAgF,CAC1I,CAAC;AAEF,MAAM,SAAS,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,CAAA,MAAM,sBAAsB,CAAC,MAAM,KAAK,EAAE,GAAG,CAAC,CAAC;AAEtF,iFAAiF;AACjF,MAAM,UAAU,WAAW,CAAC,WAAqD;IAC/E,OAAO,CACL,CAAC,WAAW,CAAC,SAAS,IAAI,CAAC,WAAW,CAAC,KAAK,KAAK,MAAM,IAAI,WAAW,CAAC,KAAK,KAAK,UAAU,CAAC,CAC7F,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB,EAAE,MAAc;IAChE,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACtC,MAAM,MAAM,GAAkB,EAAE,CAAC;IACjC,IAAI,OAAgC,CAAC;IAErC,KAAK,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE;QAC3B,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,KAAK,EAAE,CAAC;YACV,OAAO,GAAG;gBACR,EAAE,EAAE,KAAK,CAAC,CAAC,CAAE;gBACb,KAAK,EAAE,KAAK,CAAC,CAAC,CAAqB;gBACnC,SAAS,EAAE,KAAK,CAAC,CAAC,CAAC,KAAK,SAAS;gBACjC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAE,CAAC,IAAI,EAAE;gBACtB,MAAM;gBACN,IAAI,EAAE,KAAK,GAAG,CAAC;aAChB,CAAC;YACF,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACrB,OAAO;QACT,CAAC;QACD,MAAM,SAAS,GAAG,OAAO,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC7F,IAAI,SAAS,IAAI,OAAO,EAAE,CAAC;YACzB,OAAO,CAAC,IAAI,GAAG,GAAG,OAAO,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC;QACxD,CAAC;aAAM,CAAC;YACN,OAAO,GAAG,SAAS,CAAC;QACtB,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,yBAAyB,CAAC,QAAgB;IACxD,OAAO,CAAC,GAAG,QAAQ,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC,CAAC;AAC7D,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,50 @@
1
1
  {
2
2
  "name": "@selfauth/spec",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.2.0",
4
+ "description": "SelfAuth language-neutral authentication & authorization specification, requirement tooling, and configuration schema.",
5
+ "license": "MIT",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/thetejasmagade/selfauth.git",
9
+ "directory": "packages/spec"
10
+ },
11
+ "homepage": "https://github.com/thetejasmagade/selfauth/tree/main/packages/spec#readme",
12
+ "bugs": {
13
+ "url": "https://github.com/thetejasmagade/selfauth/issues"
14
+ },
15
+ "keywords": [
16
+ "selfauth",
17
+ "authentication",
18
+ "authorization",
19
+ "specification",
20
+ "conformance"
21
+ ],
22
+ "type": "module",
23
+ "exports": {
24
+ ".": {
25
+ "types": "./dist/index.d.ts",
26
+ "default": "./dist/index.js"
27
+ },
28
+ "./specs/*": "./specs/*",
29
+ "./package.json": "./package.json"
30
+ },
31
+ "files": [
32
+ "dist",
33
+ "specs"
34
+ ],
35
+ "engines": {
36
+ "node": ">=22"
37
+ },
38
+ "dependencies": {
39
+ "zod": "^4.6.7"
40
+ },
41
+ "publishConfig": {
42
+ "access": "public",
43
+ "provenance": true
44
+ },
45
+ "scripts": {
46
+ "build": "tsc -p tsconfig.build.json",
47
+ "typecheck": "tsc -p tsconfig.json --noEmit",
48
+ "test": "vitest run"
49
+ }
6
50
  }
@@ -0,0 +1,398 @@
1
+ # Authentication specification
2
+
3
+ - **specVersion:** 0.1 (draft — open for review)
4
+ - **Normative language:** RFC 2119 / RFC 8174. Requirement format: ADR 0007.
5
+ - **Related:** [AUTHORIZATION_SPEC](AUTHORIZATION_SPEC.md) ·
6
+ [SECURITY_REQUIREMENTS](SECURITY_REQUIREMENTS.md) · [DATA_MODEL](DATA_MODEL.md) ·
7
+ [ERRORS](ERRORS.md) · [CONFIGURATION_SPEC](CONFIGURATION_SPEC.md) ·
8
+ [CONFORMANCE](CONFORMANCE.md)
9
+
10
+ This document defines **what** a compliant implementation does, in terms of
11
+ abstract *operations*, *inputs*, *outcomes* and *error codes*. It does not
12
+ depend on any framework, ORM, or database. Section 11 gives a non-normative
13
+ HTTP binding that the MVP adapters follow.
14
+
15
+ ## 1. Terms
16
+
17
+ | Term | Meaning |
18
+ | --- | --- |
19
+ | **User** | An account record identified by a user ID. |
20
+ | **Credential** | Secret material proving identity (MVP: a password hash). Stored separately from the user. |
21
+ | **Session** | Server-side record of an authenticated browser session, referenced by an opaque session token. |
22
+ | **Session token** | High-entropy random value held by the client (cookie). Only its hash is stored. |
23
+ | **One-time token** | High-entropy random value for password reset or email verification. Only its hash is stored. |
24
+ | **Normalized email** | The email form used for uniqueness and lookup (§2.2). |
25
+ | **Subject** | The authenticated user making a request. |
26
+
27
+ ## 2. Identity and accounts
28
+
29
+ ### 2.1 User identifiers
30
+
31
+ - **[IDENT-ID-001]** (MUST) Every user MUST have an immutable identifier
32
+ assigned by the server at creation.
33
+ - **[IDENT-ID-002]** (MUST) User identifiers exposed outside the server MUST NOT
34
+ be sequential or otherwise enumerable. UUIDv4, UUIDv7, or ≥ 128-bit random
35
+ identifiers satisfy this.
36
+ - **[IDENT-ID-003]** (MUST NOT) A user identifier MUST NOT be reassigned to a
37
+ different account, including after deletion.
38
+
39
+ ### 2.2 Email normalization and uniqueness
40
+
41
+ - **[IDENT-EMAIL-001]** (MUST) Before lookup or uniqueness comparison, an email
42
+ address MUST be normalized by: trimming leading/trailing whitespace, applying
43
+ Unicode NFC, and lower-casing the entire address.
44
+ - **[IDENT-EMAIL-002]** (MUST NOT) Normalization MUST NOT apply provider-specific
45
+ rules (removing dots, removing `+tag` suffixes, mapping domains).
46
+ - **[IDENT-EMAIL-003]** (MUST) The normalized email MUST be unique among users
47
+ that are not in the `deleted` state, enforced by the database (unique
48
+ constraint or index), not only by application code.
49
+ - **[IDENT-EMAIL-004]** (MUST) Email input MUST be rejected with
50
+ `VALIDATION_FAILED` if it is longer than 254 characters, has no `@`, has an
51
+ empty local part or domain, or contains whitespace or control characters
52
+ after trimming.
53
+ - **[IDENT-EMAIL-005]** (SHOULD) The address as entered (after trimming) SHOULD
54
+ be stored for display and correspondence alongside the normalized form.
55
+
56
+ ### 2.3 Account states
57
+
58
+ | State | Meaning | Can log in |
59
+ | --- | --- | --- |
60
+ | `pending` | Registered; email verification required and not yet completed | No (`EMAIL_NOT_VERIFIED`) |
61
+ | `active` | Normal account | Yes |
62
+ | `suspended` | Temporarily blocked by an administrator | No (`ACCOUNT_UNAVAILABLE`) |
63
+ | `disabled` | Deactivated by the user or an administrator | No (`ACCOUNT_UNAVAILABLE`) |
64
+ | `deleted` | Terminal; treated as non-existent | No (`INVALID_CREDENTIALS`) |
65
+
66
+ Allowed transitions:
67
+
68
+ ```text
69
+ pending ──verify email──► active
70
+ active ◄──admin──► suspended
71
+ pending | active | suspended ──user or admin──► disabled ──admin──► active
72
+ any state ──delete──► deleted (terminal)
73
+ ```
74
+
75
+ - **[IDENT-STATE-001]** (MUST) Every user MUST be in exactly one of the states
76
+ `pending`, `active`, `suspended`, `disabled`, `deleted`.
77
+ - **[IDENT-STATE-002]** (MUST NOT) Transitions not listed above MUST NOT be
78
+ possible; in particular `deleted` is terminal.
79
+ - **[IDENT-STATE-003]** (MUST) When a user enters `suspended`, `disabled` or
80
+ `deleted`, all of the user's sessions and outstanding one-time tokens MUST be
81
+ revoked in the same operation.
82
+ - **[IDENT-STATE-004]** (MUST) Session validation MUST reject sessions whose
83
+ user is not `active` (defense in depth, independent of
84
+ [IDENT-STATE-003]).
85
+ - **[IDENT-STATE-005]** (MUST) Every state change MUST record a security event
86
+ including the actor, previous state, and new state.
87
+
88
+ ### 2.4 Profile and credentials
89
+
90
+ - **[IDENT-PROFILE-001]** (MUST) Credentials (password hashes) MUST be stored in
91
+ a separate logical entity from the user/profile record (see
92
+ [DATA_MODEL](DATA_MODEL.md)).
93
+ - **[IDENT-PROFILE-002]** (MUST NOT) Operation responses MUST NOT include
94
+ password hashes, session tokens or their hashes, or one-time tokens or their
95
+ hashes. (Exception: the session token in the `Set-Cookie` header of the
96
+ operation that creates the session.)
97
+ - **[IDENT-PROFILE-003]** (MAY) Applications MAY attach additional profile
98
+ fields; these are application-owned and outside this specification.
99
+
100
+ ### 2.5 Account deletion and retention
101
+
102
+ - **[IDENT-DELETE-001]** (MUST) Deleting an account MUST: set state `deleted`,
103
+ revoke all sessions and one-time tokens, and delete the account's
104
+ credentials.
105
+ - **[IDENT-DELETE-002]** (MUST) After deletion the normalized email MUST be
106
+ released for re-registration (e.g. by clearing it on the tombstone), and the
107
+ stored email SHOULD be removed or irreversibly pseudonymized.
108
+ - **[IDENT-DELETE-003]** (MUST) User-initiated deletion MUST require
109
+ re-authentication with the current password.
110
+ - **[IDENT-DELETE-004]** (SHOULD) Security events MAY be retained after deletion
111
+ for the application's configured retention period, but SHOULD NOT retain the
112
+ email address in clear text.
113
+ - **[IDENT-DELETE-005]** (MUST) Adapters MUST document what data is retained
114
+ after deletion and for how long, so the application owner can meet their own
115
+ legal obligations.
116
+
117
+ ## 3. Registration — `register(email, password)`
118
+
119
+ Behavior depends on `emailVerification.mode` ([CONFIGURATION_SPEC](CONFIGURATION_SPEC.md)):
120
+ `required` (default), `optional`, or `off`.
121
+
122
+ **Default (private) behavior:** in every mode, registration never reveals
123
+ whether an email already has an account — the outcome is always `accepted`,
124
+ and registration never creates a session; the user logs in afterwards.
125
+ (Creating a session for new emails only would reveal which emails already
126
+ exist.)
127
+
128
+ **Opt-in (convenient) behavior:** a project may set
129
+ `authentication.registration.revealExistingEmail` to return `EMAIL_TAKEN`, and
130
+ then additionally `signInAfterRegistration` to log new users in immediately.
131
+ This is a deliberate privacy trade-off (§3.1).
132
+
133
+ - **[AUTHN-REG-001]** (MUST) Registration MUST validate the email
134
+ ([IDENT-EMAIL-004]) and password policy ([SEC-PWPOLICY-001] …) before creating
135
+ any record, returning `VALIDATION_FAILED` or `PASSWORD_POLICY_VIOLATION`.
136
+ - **[AUTHN-REG-002]** (MUST) Registration MUST ignore or reject any
137
+ client-supplied value for state, roles, permissions, email-verified flag, or
138
+ user ID (mass-assignment protection). New users receive only the configured
139
+ default role(s).
140
+ - **[AUTHN-REG-003]** (MUST) Registration MUST create the user and credential
141
+ atomically: either both exist afterwards or neither does.
142
+ - **[AUTHN-REG-004]** (MUST) In `required` mode, the new user MUST be created in
143
+ state `pending`, a verification email MUST be sent (§8), and no session MUST
144
+ be created. The outcome is `accepted`.
145
+ - **[AUTHN-REG-005]** (MUST) Unless `revealExistingEmail` is enabled, in every
146
+ verification mode registering an email that already belongs to a non-deleted
147
+ user MUST produce an outcome indistinguishable
148
+ from a new registration (same status, same body, no session), and MUST NOT
149
+ modify the existing account. The implementation SHOULD send the existing
150
+ owner a notification email instead.
151
+ - **[AUTHN-REG-006]** (MUST) (WITHDRAWN) Replaced by [AUTHN-REG-009]; the
152
+ `EMAIL_TAKEN` error and the optional immediate session were removed so that
153
+ no mode allows account enumeration.
154
+ - **[AUTHN-REG-007]** (MUST) Concurrent registrations for the same normalized
155
+ email MUST result in at most one account.
156
+ - **[AUTHN-REG-008]** (MUST) Registration MUST record a `user.registered`
157
+ security event for each account created.
158
+ - **[AUTHN-REG-009]** (MUST) In `optional` and `off` modes, the new user MUST be
159
+ created in state `active`. Unless `signInAfterRegistration` is enabled,
160
+ registration MUST NOT create a session and the outcome MUST be `accepted`,
161
+ exactly as in `required` mode. In `optional` mode
162
+ a verification email MUST still be sent.
163
+ - **[AUTHN-REG-010]** (MUST) Unless `revealExistingEmail` is enabled,
164
+ registering an existing email MUST perform password-hashing work of comparable
165
+ cost to a new registration, so response time does not reveal account
166
+ existence.
167
+
168
+ ### 3.1 Opt-in: revealing existing emails
169
+
170
+ - **[AUTHN-REG-011]** (MUST) When `revealExistingEmail` is enabled, registering
171
+ an email that belongs to a non-deleted user MUST fail with `EMAIL_TAKEN`, MUST
172
+ NOT modify the existing account, and MUST remain rate limited
173
+ ([SEC-RATE-002]).
174
+ - **[AUTHN-REG-012]** (MUST) `signInAfterRegistration` MUST be accepted only
175
+ when `revealExistingEmail` is enabled and the verification mode is `optional`
176
+ or `off`. When enabled, a successful registration MUST create a new session
177
+ exactly as login does (§6, [AUTHN-LOGIN-005]).
178
+ - **[AUTHN-REG-013]** (SHOULD) Login and password reset SHOULD stay
179
+ non-enumerating even when this option is enabled; the option only affects
180
+ registration.
181
+
182
+ ## 4. Login — `login(email, password)`
183
+
184
+ - **[AUTHN-LOGIN-001]** (MUST) Login MUST look up the user by normalized email
185
+ and verify the password against the stored hash using the hashing library's
186
+ verification function.
187
+ - **[AUTHN-LOGIN-002]** (MUST) If the user does not exist, is `deleted`, has no
188
+ password credential, or the password is wrong, login MUST fail with
189
+ `INVALID_CREDENTIALS`, with the same response in all four cases.
190
+ - **[AUTHN-LOGIN-003]** (MUST) When no matching user exists, the implementation
191
+ MUST still perform a password-hash verification of comparable cost (e.g.
192
+ against a fixed dummy hash) so response time does not reveal account
193
+ existence.
194
+ - **[AUTHN-LOGIN-004]** (MUST) The account state MUST be revealed only after
195
+ the password is verified: `pending` → `EMAIL_NOT_VERIFIED`; `suspended` or
196
+ `disabled` → `ACCOUNT_UNAVAILABLE`. No session is created in these cases.
197
+ - **[AUTHN-LOGIN-005]** (MUST) On success, the implementation MUST create a
198
+ **new** session (§6) and MUST NOT reuse or adopt any session token supplied by
199
+ the client (session-fixation protection). Any session token the client
200
+ already presented MUST be revoked.
201
+ - **[AUTHN-LOGIN-006]** (MUST) Login MUST be rate limited per normalized email
202
+ and per client address ([SEC-RATE-001]); limits apply whether or not the
203
+ account exists.
204
+ - **[AUTHN-LOGIN-007]** (SHOULD) If the stored hash uses parameters weaker than
205
+ the current configuration, the implementation SHOULD re-hash the password on
206
+ successful login ([SEC-HASH-004]).
207
+ - **[AUTHN-LOGIN-008]** (MUST) Login MUST record `auth.login.succeeded` or
208
+ `auth.login.failed` events. Failed events MUST NOT include the submitted
209
+ password.
210
+ - **[AUTHN-LOGIN-009]** (MUST) A successful login response MUST include the
211
+ current user (§7) and MUST NOT include the session token in the body.
212
+
213
+ ## 5. Logout
214
+
215
+ ### 5.1 `logout()`
216
+
217
+ - **[AUTHN-LOGOUT-001]** (MUST) Logout MUST revoke the current session
218
+ server-side; subsequent requests with that token MUST be unauthenticated.
219
+ - **[AUTHN-LOGOUT-002]** (MUST) Logout MUST instruct the client to delete the
220
+ session cookie (same name, path and attributes, expired).
221
+ - **[AUTHN-LOGOUT-003]** (MUST) Logout MUST be idempotent: calling it without a
222
+ valid session succeeds and reveals nothing.
223
+ - **[AUTHN-LOGOUT-004]** (MUST) Logout is a state-changing operation and MUST be
224
+ CSRF-protected ([SEC-CSRF-001]); it MUST NOT be reachable via a safe method
225
+ (e.g. HTTP `GET`).
226
+
227
+ ### 5.2 `logoutAll()` — logout from all devices
228
+
229
+ - **[AUTHN-LOGOUT-005]** (MUST) An authenticated user MUST be able to revoke all
230
+ of their sessions, including the current one, in one operation.
231
+ - **[AUTHN-LOGOUT-006]** (MUST) `logoutAll` MUST record an
232
+ `auth.sessions.revoked_all` security event.
233
+
234
+ ### 5.3 Session management (recommended)
235
+
236
+ - **[AUTHN-LOGOUT-007]** (SHOULD) Implementations SHOULD let a user list their
237
+ active sessions (creation time, last use, coarse client description — never
238
+ tokens) and revoke an individual session they own.
239
+
240
+ ## 6. Sessions
241
+
242
+ - **[AUTHN-SESS-001]** (MUST) Session tokens MUST be generated per
243
+ [SEC-TOKEN-001] (CSPRNG, ≥ 256 bits) and delivered only in a cookie meeting
244
+ [SEC-COOKIE-001].
245
+ - **[AUTHN-SESS-002]** (MUST) Only a SHA-256 (or stronger) hash of the session
246
+ token MUST be stored; lookup is by hash.
247
+ - **[AUTHN-SESS-003]** (MUST) Each session MUST have an **idle expiry** and an
248
+ **absolute expiry**. A session is valid only if: it exists, is not revoked,
249
+ `now < idleExpiresAt`, `now < absoluteExpiresAt`, and its user is `active`.
250
+ - **[AUTHN-SESS-004]** (MUST) Using a valid session MAY extend the idle expiry
251
+ (sliding), but MUST NOT extend it beyond the absolute expiry. The absolute
252
+ expiry MUST NOT be extended.
253
+ - **[AUTHN-SESS-005]** (MUST) An invalid, expired or revoked session token MUST
254
+ be treated as unauthenticated (`UNAUTHENTICATED` on protected operations);
255
+ the response MUST NOT reveal which condition applied.
256
+ - **[AUTHN-SESS-006]** (MUST) Revocation (logout, logoutAll, password change,
257
+ password reset, account state change) MUST take effect for the very next
258
+ request. Any cache of session state MUST honor this.
259
+ - **[AUTHN-SESS-007]** (SHOULD) Writes that extend idle expiry SHOULD be
260
+ throttled (`authentication.sessions.touchIntervalSeconds`, default 60) to
261
+ limit database load.
262
+ - **[AUTHN-SESS-008]** (SHOULD) Expired and revoked sessions SHOULD be purged
263
+ periodically by an application-controlled job.
264
+ - **[AUTHN-SESS-009]** (MAY) Implementations MAY record IP address and user
265
+ agent at session creation for display and auditing, but MUST NOT use them as
266
+ the sole means of authentication.
267
+
268
+ ## 7. Current user — `getCurrentUser()`
269
+
270
+ - **[AUTHN-ME-001]** (MUST) With a valid session, the operation MUST return the user's ID, email,
271
+ email-verified flag, state, role names, effective permissions, and session
272
+ expiry times. Without one, it MUST fail with `UNAUTHENTICATED`.
273
+ - **[AUTHN-ME-002]** (MUST) The roles and permissions returned MUST be treated
274
+ as informational, for UI purposes only ([AUTHZ-CORE-004]).
275
+ - **[AUTHN-ME-003]** (MUST) Responses to this and every other authentication
276
+ operation MUST carry `Cache-Control: no-store` (or the transport's
277
+ equivalent).
278
+
279
+ ## 8. Email verification
280
+
281
+ ### 8.1 `requestEmailVerification(email)` — (re)send
282
+
283
+ - **[AUTHN-VERIFY-001]** (MUST) The outcome MUST be `accepted` and
284
+ indistinguishable whether the email belongs to a `pending` user, an already
285
+ verified user, or no user ([SEC-ENUM-001]). A token is sent only to a user
286
+ whose email is not yet verified and whose state is `pending` or `active`
287
+ (the latter occurs in `optional` mode).
288
+ - **[AUTHN-VERIFY-002]** (MUST) Requests MUST be rate limited per normalized
289
+ email and per client address.
290
+ - **[AUTHN-VERIFY-003]** (SHOULD) Issuing a new verification token SHOULD
291
+ invalidate earlier unused verification tokens for the same user.
292
+
293
+ ### 8.2 `verifyEmail(token)`
294
+
295
+ - **[AUTHN-VERIFY-004]** (MUST) Verification tokens MUST be generated per
296
+ [SEC-TOKEN-001], stored only as hashes, and expire after the configured TTL
297
+ (default 24 h, maximum 7 days).
298
+ - **[AUTHN-VERIFY-005]** (MUST) A token MUST be accepted only if it exists, is
299
+ unused, is unexpired, and was issued for the user's **current** email
300
+ address. All other cases MUST fail with `TOKEN_INVALID` (one code for every failure reason).
301
+ - **[AUTHN-VERIFY-006]** (MUST) A token MUST be usable at most once, including
302
+ under concurrent use (atomic consume).
303
+ - **[AUTHN-VERIFY-007]** (MUST) Success MUST set the email-verified timestamp
304
+ and, if the user is `pending`, transition them to `active`.
305
+ - **[AUTHN-VERIFY-008]** (SHOULD NOT) Verification SHOULD NOT create a session;
306
+ the user logs in normally afterwards.
307
+ - **[AUTHN-VERIFY-009]** (MUST) Links in verification emails MUST be built from
308
+ the configured application base URL, never from request headers such as
309
+ `Host` or `X-Forwarded-Host`.
310
+
311
+ ## 9. Password change — `changePassword(currentPassword, newPassword)`
312
+
313
+ - **[AUTHN-PWCHG-001]** (MUST) The operation MUST require a valid session and
314
+ the correct current password; a wrong current password MUST fail with
315
+ `INVALID_CREDENTIALS` and MUST be rate limited like login.
316
+ - **[AUTHN-PWCHG-002]** (MUST) The new password MUST satisfy the password policy
317
+ ([SEC-PWPOLICY-001] …).
318
+ - **[AUTHN-PWCHG-003]** (MUST) On success, all of the user's **other** sessions
319
+ MUST be revoked. The current session MUST either be kept or replaced with a
320
+ newly issued session (recommended: replace).
321
+ - **[AUTHN-PWCHG-004]** (MUST) On success, outstanding password-reset tokens for
322
+ the user MUST be invalidated.
323
+ - **[AUTHN-PWCHG-005]** (SHOULD) The user SHOULD be notified by email that their
324
+ password changed.
325
+ - **[AUTHN-PWCHG-006]** (MUST) A `password.changed` security event MUST be
326
+ recorded.
327
+
328
+ ## 10. Password reset
329
+
330
+ ### 10.1 `requestPasswordReset(email)`
331
+
332
+ - **[AUTHN-RESET-001]** (MUST) The outcome MUST be `accepted` and
333
+ indistinguishable whether or not the email belongs to an account
334
+ ([SEC-ENUM-001]).
335
+ - **[AUTHN-RESET-002]** (MUST) A reset token MUST be issued and emailed only
336
+ for users in state `active` or `pending`, never for `suspended`, `disabled`
337
+ or `deleted` users.
338
+ - **[AUTHN-RESET-003]** (MUST) Reset tokens MUST be generated per
339
+ [SEC-TOKEN-001], stored only as hashes, and expire after the configured TTL
340
+ (default 30 minutes, maximum 60 minutes).
341
+ - **[AUTHN-RESET-004]** (MUST) Issuing a new reset token MUST invalidate any
342
+ earlier unused reset tokens for the same user.
343
+ - **[AUTHN-RESET-005]** (MUST) Requests MUST be rate limited per normalized
344
+ email and per client address.
345
+ - **[AUTHN-RESET-006]** (MUST) Reset links MUST be built from the configured
346
+ application base URL ([AUTHN-VERIFY-009]).
347
+
348
+ ### 10.2 `resetPassword(token, newPassword)`
349
+
350
+ - **[AUTHN-RESET-007]** (MUST) A token MUST be accepted only if it exists, is
351
+ unused, is unexpired, and its user is `active` or `pending`. All other cases
352
+ MUST fail with `TOKEN_INVALID`.
353
+ - **[AUTHN-RESET-008]** (MUST) The new password MUST satisfy the password policy.
354
+ A policy violation MUST NOT consume the token.
355
+ - **[AUTHN-RESET-009]** (MUST) A token MUST be usable at most once, including
356
+ under concurrent use (atomic consume).
357
+ - **[AUTHN-RESET-010]** (MUST) On success, **all** of the user's sessions MUST be
358
+ revoked and all other reset tokens invalidated.
359
+ - **[AUTHN-RESET-011]** (MAY) If the user is `pending`, a successful reset MAY
360
+ mark the email verified and activate the account, since the token proves
361
+ control of the mailbox.
362
+ - **[AUTHN-RESET-012]** (SHOULD NOT) A successful reset SHOULD NOT create a
363
+ session automatically.
364
+ - **[AUTHN-RESET-013]** (MUST) `password.reset.requested` (only when a token was
365
+ actually issued) and `password.reset.completed` events MUST be recorded, and
366
+ the user SHOULD be notified by email after completion.
367
+
368
+ ## 11. HTTP binding (non-normative, used by MVP adapters)
369
+
370
+ All bodies are JSON. All routes are under a configurable prefix (default
371
+ `/auth`). Errors use the envelope in [ERRORS](ERRORS.md).
372
+
373
+ | Operation | Method & path | Success |
374
+ | --- | --- | --- |
375
+ | register | `POST /auth/register` | `202 {status:"accepted"}` by default (never sets a cookie) · `409 EMAIL_TAKEN` with `revealExistingEmail` · `201 {user}` + `Set-Cookie` with `signInAfterRegistration` |
376
+ | login | `POST /auth/login` | `200 {user, csrfToken?}` + `Set-Cookie` |
377
+ | logout | `POST /auth/logout` | `204` + expired cookie |
378
+ | logoutAll | `POST /auth/logout-all` | `204` + expired cookie |
379
+ | getCurrentUser | `GET /auth/me` | `200 {user, session, csrfToken?}` |
380
+ | listSessions | `GET /auth/sessions` | `200 {sessions}` |
381
+ | revokeSession | `DELETE /auth/sessions/:id` | `204` |
382
+ | requestEmailVerification | `POST /auth/email/verification` | `202 {status:"accepted"}` |
383
+ | verifyEmail | `POST /auth/email/verify` `{token}` | `200 {status:"verified"}` |
384
+ | changePassword | `POST /auth/password/change` | `200 {status:"changed", csrfToken?}` + rotated cookie |
385
+ | requestPasswordReset | `POST /auth/password/reset-request` | `202 {status:"accepted"}` |
386
+ | resetPassword | `POST /auth/password/reset` `{token, newPassword}` | `204` |
387
+ | deleteAccount | `POST /auth/account/delete` `{currentPassword}` | `204` + expired cookie |
388
+ | setAccountState | `POST /auth/admin/users/:id/state` `{state}` | `204` |
389
+ | assignRole | `POST /auth/admin/users/:id/roles` `{role}` | `204` |
390
+ | removeRole | `DELETE /auth/admin/users/:id/roles/:role` | `204` |
391
+
392
+ `csrfToken` is present only when `http.csrf.mode` is `token`; clients send it
393
+ back in the CSRF header. In `header` mode clients send `X-SelfAuth-CSRF: 1`.
394
+
395
+ Email links point to **frontend** pages (e.g. `/verify-email#token=…`,
396
+ `/reset-password#token=…`) that submit the token with `POST`. Putting the token
397
+ in the URL fragment keeps it out of server logs and `Referer` headers; see
398
+ [SEC-TOKEN-005].