docs(swagger): add JSDoc @openapi for auth endpoints
- POST /api/auth/login: rate-limited, sets httpOnly cookie, issues CSRF token - GET /api/auth/me: returns current authenticated user - GET /api/auth/csrf: refreshes CSRF token - POST /api/auth/logout: clears cookies, revokes Emby token - Include x-code-samples (curl, JS fetch, TypeScript) - Include x-integration-notes for cookie flow - Full JSON Schema with realistic examples
This commit is contained in:
+356
-5
@@ -24,7 +24,159 @@ const loginLimiter = rateLimit({
|
||||
message: { success: false, error: 'Too many login attempts, please try again later' }
|
||||
});
|
||||
|
||||
// Authenticate user with Emby
|
||||
/**
|
||||
* @openapi
|
||||
* /api/auth/login:
|
||||
* post:
|
||||
* tags: [Auth]
|
||||
* summary: Authenticate with Emby/Jellyfin
|
||||
* description: |
|
||||
* Authenticates a user against Emby/Jellyfin and sets session cookies.
|
||||
*
|
||||
* **Rate Limiting:** 10 failed attempts per 15 minutes per IP (successful attempts don't count).
|
||||
*
|
||||
* **Authentication Flow:**
|
||||
* 1. Send username and password in request body
|
||||
* 2. Server validates credentials with Emby/Jellyfin
|
||||
* 3. Server sets httpOnly signed cookie `emby_user` containing {id, name, isAdmin}
|
||||
* 4. Server sets `csrf_token` cookie (readable by JS for double-submit pattern)
|
||||
* 5. Response includes user data and CSRF token
|
||||
*
|
||||
* **Cookie Details:**
|
||||
* - `emby_user`: httpOnly, signed, sameSite=strict. Persistent if rememberMe=true (30 days), otherwise session cookie.
|
||||
* - `csrf_token`: httpOnly=false (JS-readable), sameSite=strict. Used for state-changing requests.
|
||||
*
|
||||
* **Security Notes:**
|
||||
* - Password must be 1-256 characters
|
||||
* - Username must be 1-128 characters
|
||||
* - Server rejects with 400 if input validation fails
|
||||
* - Server rejects with 401 if Emby authentication fails
|
||||
*
|
||||
* **x-integration-notes:** After successful login, subsequent requests must:
|
||||
* - Send the emby_user cookie (automatically by browser)
|
||||
* - Send the X-CSRF-Token header (from csrf_token cookie) for POST/PUT/PATCH/DELETE requests
|
||||
* - Use credentials: 'include' in fetch/axios to send cookies
|
||||
* security: []
|
||||
* requestBody:
|
||||
* required: true
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* type: object
|
||||
* required:
|
||||
* - username
|
||||
* - password
|
||||
* properties:
|
||||
* username:
|
||||
* type: string
|
||||
* minLength: 1
|
||||
* maxLength: 128
|
||||
* description: Emby/Jellyfin username
|
||||
* example: "john"
|
||||
* password:
|
||||
* type: string
|
||||
* minLength: 1
|
||||
* maxLength: 256
|
||||
* description: Emby/Jellyfin password
|
||||
* example: "password123"
|
||||
* rememberMe:
|
||||
* type: boolean
|
||||
* description: If true, cookie persists for 30 days; otherwise session cookie
|
||||
* example: false
|
||||
* example:
|
||||
* username: "john"
|
||||
* password: "password123"
|
||||
* rememberMe: false
|
||||
* responses:
|
||||
* '200':
|
||||
* description: Login successful
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* type: object
|
||||
* properties:
|
||||
* success:
|
||||
* type: boolean
|
||||
* example: true
|
||||
* user:
|
||||
* type: object
|
||||
* properties:
|
||||
* id:
|
||||
* type: string
|
||||
* description: Emby user ID
|
||||
* example: "abc123def456"
|
||||
* name:
|
||||
* type: string
|
||||
* description: Display name
|
||||
* example: "John Doe"
|
||||
* isAdmin:
|
||||
* type: boolean
|
||||
* description: Admin flag
|
||||
* example: false
|
||||
* csrfToken:
|
||||
* type: string
|
||||
* description: CSRF token for state-changing requests
|
||||
* example: "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
|
||||
* example:
|
||||
* success: true
|
||||
* user:
|
||||
* id: "abc123def456"
|
||||
* name: "John Doe"
|
||||
* isAdmin: false
|
||||
* csrfToken: "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
|
||||
* '400':
|
||||
* description: Invalid input (username or password fails validation)
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* $ref: '#/components/schemas/ErrorResponse'
|
||||
* example:
|
||||
* success: false
|
||||
* error: "Invalid username"
|
||||
* '401':
|
||||
* description: Invalid credentials (Emby authentication failed)
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* $ref: '#/components/schemas/ErrorResponse'
|
||||
* example:
|
||||
* success: false
|
||||
* error: "Invalid username or password"
|
||||
* x-code-samples:
|
||||
* - lang: curl
|
||||
* label: cURL
|
||||
* source: |
|
||||
* curl -X POST http://localhost:3001/api/auth/login \
|
||||
* -H "Content-Type: application/json" \
|
||||
* -c cookies.txt \
|
||||
* -d '{"username":"john","password":"password123"}'
|
||||
* - lang: JavaScript
|
||||
* label: JavaScript (fetch)
|
||||
* source: |
|
||||
* const response = await fetch('http://localhost:3001/api/auth/login', {
|
||||
* method: 'POST',
|
||||
* headers: { 'Content-Type': 'application/json' },
|
||||
* credentials: 'include',
|
||||
* body: JSON.stringify({ username: 'john', password: 'password123' })
|
||||
* });
|
||||
* const data = await response.json();
|
||||
* console.log(data.csrfToken); // Save this for subsequent requests
|
||||
* - lang: TypeScript
|
||||
* label: TypeScript
|
||||
* source: |
|
||||
* interface LoginResponse {
|
||||
* success: boolean;
|
||||
* user: { id: string; name: string; isAdmin: boolean };
|
||||
* csrfToken: string;
|
||||
* }
|
||||
* const response = await fetch('http://localhost:3001/api/auth/login', {
|
||||
* method: 'POST',
|
||||
* headers: { 'Content-Type': 'application/json' },
|
||||
* credentials: 'include',
|
||||
* body: JSON.stringify({ username: 'john', password: 'password123' })
|
||||
* });
|
||||
* const data: LoginResponse = await response.json();
|
||||
*/
|
||||
router.post('/login', loginLimiter, async (req, res) => {
|
||||
try {
|
||||
const { username, password, rememberMe } = req.body;
|
||||
@@ -129,7 +281,80 @@ function parseSessionCookie(req) {
|
||||
}
|
||||
}
|
||||
|
||||
// Get current authenticated user
|
||||
/**
|
||||
* @openapi
|
||||
* /api/auth/me:
|
||||
* get:
|
||||
* tags: [Auth]
|
||||
* summary: Get current authenticated user
|
||||
* description: |
|
||||
* Returns the currently authenticated user from the session cookie.
|
||||
*
|
||||
* **Authentication:** Requires valid `emby_user` cookie.
|
||||
*
|
||||
* **Response:**
|
||||
* - If authenticated: returns user data (id, name, isAdmin)
|
||||
* - If not authenticated: returns authenticated: false
|
||||
*
|
||||
* **Use Case:** Check if user is logged in and get user details without re-authenticating.
|
||||
* security:
|
||||
* - CookieAuth: []
|
||||
* responses:
|
||||
* '200':
|
||||
* description: User data (authenticated or not)
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* oneOf:
|
||||
* - type: object
|
||||
* properties:
|
||||
* authenticated:
|
||||
* type: boolean
|
||||
* example: true
|
||||
* user:
|
||||
* type: object
|
||||
* properties:
|
||||
* id:
|
||||
* type: string
|
||||
* example: "abc123def456"
|
||||
* name:
|
||||
* type: string
|
||||
* example: "John Doe"
|
||||
* isAdmin:
|
||||
* type: boolean
|
||||
* example: false
|
||||
* - type: object
|
||||
* properties:
|
||||
* authenticated:
|
||||
* type: boolean
|
||||
* example: false
|
||||
* examples:
|
||||
* authenticated:
|
||||
* authenticated: true
|
||||
* user:
|
||||
* id: "abc123def456"
|
||||
* name: "John Doe"
|
||||
* isAdmin: false
|
||||
* notAuthenticated:
|
||||
* authenticated: false
|
||||
* x-code-samples:
|
||||
* - lang: curl
|
||||
* label: cURL
|
||||
* source: |
|
||||
* curl -X GET http://localhost:3001/api/auth/me \
|
||||
* -b cookies.txt
|
||||
* - lang: JavaScript
|
||||
* label: JavaScript (fetch)
|
||||
* source: |
|
||||
* const response = await fetch('http://localhost:3001/api/auth/me', {
|
||||
* method: 'GET',
|
||||
* credentials: 'include'
|
||||
* });
|
||||
* const data = await response.json();
|
||||
* if (data.authenticated) {
|
||||
* console.log('User:', data.user.name);
|
||||
* }
|
||||
*/
|
||||
router.get('/me', (req, res) => {
|
||||
const user = parseSessionCookie(req);
|
||||
if (!user) return res.json({ authenticated: false });
|
||||
@@ -139,8 +364,57 @@ router.get('/me', (req, res) => {
|
||||
});
|
||||
});
|
||||
|
||||
// CSRF token refresh — lets the SPA get a new token without re-logging-in
|
||||
// (e.g. after a page reload where the JS variable was lost)
|
||||
/**
|
||||
* @openapi
|
||||
* /api/auth/csrf:
|
||||
* get:
|
||||
* tags: [Auth]
|
||||
* summary: Refresh CSRF token
|
||||
* description: |
|
||||
* Returns a fresh CSRF token and sets it as a cookie.
|
||||
*
|
||||
* **Purpose:** Lets the SPA get a new CSRF token without re-authenticating
|
||||
* (e.g., after a page reload where the JS variable containing the token was lost).
|
||||
*
|
||||
* **Authentication:** No authentication required (CSRF tokens are issued to all clients).
|
||||
*
|
||||
* **Cookie Details:**
|
||||
* - Sets `csrf_token` cookie (httpOnly=false, readable by JS)
|
||||
* - sameSite=strict, secure when TRUST_PROXY is set
|
||||
*
|
||||
* **Use Case:** Call this endpoint when your application needs a fresh CSRF token
|
||||
* for state-changing requests (POST/PUT/PATCH/DELETE).
|
||||
* security: []
|
||||
* responses:
|
||||
* '200':
|
||||
* description: CSRF token
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* type: object
|
||||
* properties:
|
||||
* csrfToken:
|
||||
* type: string
|
||||
* description: Fresh CSRF token for state-changing requests
|
||||
* example: "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
|
||||
* example:
|
||||
* csrfToken: "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
|
||||
* x-code-samples:
|
||||
* - lang: curl
|
||||
* label: cURL
|
||||
* source: |
|
||||
* curl -X GET http://localhost:3001/api/auth/csrf \
|
||||
* -c cookies.txt
|
||||
* - lang: JavaScript
|
||||
* label: JavaScript (fetch)
|
||||
* source: |
|
||||
* const response = await fetch('http://localhost:3001/api/auth/csrf', {
|
||||
* method: 'GET',
|
||||
* credentials: 'include'
|
||||
* });
|
||||
* const data = await response.json();
|
||||
* const csrfToken = data.csrfToken; // Use this in X-CSRF-Token header
|
||||
*/
|
||||
router.get('/csrf', (req, res) => {
|
||||
const csrfToken = crypto.randomBytes(32).toString('hex');
|
||||
res.cookie('csrf_token', csrfToken, {
|
||||
@@ -152,7 +426,84 @@ router.get('/csrf', (req, res) => {
|
||||
res.json({ csrfToken });
|
||||
});
|
||||
|
||||
// Logout
|
||||
/**
|
||||
* @openapi
|
||||
* /api/auth/logout:
|
||||
* post:
|
||||
* tags: [Auth]
|
||||
* summary: Logout
|
||||
* description: |
|
||||
* Clears session cookies and revokes the Emby/Jellyfin access token.
|
||||
*
|
||||
* **Authentication:** Requires valid `emby_user` cookie and `X-CSRF-Token` header.
|
||||
*
|
||||
* **Actions Performed:**
|
||||
* 1. Revokes the Emby/Jellyfin access token on the Emby server
|
||||
* 2. Clears the server-side token store
|
||||
* 3. Clears the `emby_user` cookie
|
||||
* 4. Clears the `csrf_token` cookie
|
||||
*
|
||||
* **Error Handling:** If Emby token revocation fails, the logout still succeeds
|
||||
* (cookies are cleared) but a warning is logged.
|
||||
*
|
||||
* **x-integration-notes:** After logout, the client must discard the CSRF token
|
||||
* and not attempt further authenticated requests until re-authenticating.
|
||||
* security:
|
||||
* - CookieAuth: []
|
||||
* - CsrfToken: []
|
||||
* responses:
|
||||
* '200':
|
||||
* description: Logout successful
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* type: object
|
||||
* properties:
|
||||
* success:
|
||||
* type: boolean
|
||||
* example: true
|
||||
* example:
|
||||
* success: true
|
||||
* '401':
|
||||
* description: Not authenticated (no valid session)
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* $ref: '#/components/schemas/ErrorResponse'
|
||||
* '403':
|
||||
* description: CSRF token missing or invalid
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* $ref: '#/components/schemas/ErrorResponse'
|
||||
* x-code-samples:
|
||||
* - lang: curl
|
||||
* label: cURL
|
||||
* source: |
|
||||
* # Get CSRF token first
|
||||
* CSRF_TOKEN=$(curl -s -c cookies.txt http://localhost:3001/api/auth/csrf | jq -r .csrfToken)
|
||||
* # Logout
|
||||
* curl -X POST http://localhost:3001/api/auth/logout \
|
||||
* -H "X-CSRF-Token: $CSRF_TOKEN" \
|
||||
* -b cookies.txt \
|
||||
* -c cookies.txt
|
||||
* - lang: JavaScript
|
||||
* label: JavaScript (fetch)
|
||||
* source: |
|
||||
* const csrfResponse = await fetch('http://localhost:3001/api/auth/csrf', {
|
||||
* method: 'GET',
|
||||
* credentials: 'include'
|
||||
* });
|
||||
* const { csrfToken } = await csrfResponse.json();
|
||||
*
|
||||
* const response = await fetch('http://localhost:3001/api/auth/logout', {
|
||||
* method: 'POST',
|
||||
* headers: { 'X-CSRF-Token': csrfToken },
|
||||
* credentials: 'include'
|
||||
* });
|
||||
* const data = await response.json();
|
||||
* console.log(data.success); // true
|
||||
*/
|
||||
router.post('/logout', async (req, res) => {
|
||||
const user = parseSessionCookie(req);
|
||||
if (user) {
|
||||
|
||||
Reference in New Issue
Block a user