@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/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
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"}
|
package/dist/index.d.ts
ADDED
|
@@ -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 @@
|
|
|
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.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
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].
|