david
bbe0757ab6
Implement complete refresh token flow for improved security: - Short-lived access tokens (configurable, default 1h) - Long-lived refresh tokens (configurable, default 7d) - Automatic token rotation on refresh - Token revocation for proper logout Domain layer: - Add RefreshToken entity with validation and revocation - Add RefreshTokenRepository interface Application layer: - Add RefreshTokenHandler for token refresh operations - Add RevokeTokenHandler for single token revocation - Add RevokeAllTokensHandler for user-wide revocation Infrastructure layer: - Implement SQLite RefreshTokenRepository - Add refresh_tokens table migration with indexes - Add parseDuration helper for flexible time configuration HTTP layer: - Add POST /api/v1/auth/refresh endpoint - Add POST /api/v1/auth/logout endpoint - Update login/register to return refresh tokens - Improve Swagger documentation with clear descriptions Configuration: - Update .env.example with secure token expiry defaults - Add support for minute/hour/day duration formats Tests: - Fix test suite to work with new signatures - All existing tests passing
796 lines
20 KiB
YAML
796 lines
20 KiB
YAML
basePath: /api/v1
|
|
definitions:
|
|
http.AuthResponse:
|
|
properties:
|
|
refresh_token:
|
|
type: string
|
|
token:
|
|
type: string
|
|
user_id:
|
|
type: string
|
|
type: object
|
|
http.CreateHabitRequest:
|
|
properties:
|
|
carry_over:
|
|
type: boolean
|
|
description:
|
|
type: string
|
|
frequency:
|
|
$ref: '#/definitions/value_objects.Frequency'
|
|
is_negative:
|
|
type: boolean
|
|
name:
|
|
type: string
|
|
specific_dates:
|
|
items:
|
|
type: integer
|
|
type: array
|
|
specific_days:
|
|
items:
|
|
type: integer
|
|
type: array
|
|
target_value:
|
|
type: number
|
|
type:
|
|
$ref: '#/definitions/value_objects.HabitType'
|
|
type: object
|
|
http.ErrorResponse:
|
|
properties:
|
|
error:
|
|
type: string
|
|
type: object
|
|
http.HabitEntriesResponse:
|
|
properties:
|
|
entries:
|
|
items:
|
|
$ref: '#/definitions/http.HabitEntryResponse'
|
|
type: array
|
|
limit:
|
|
type: integer
|
|
page:
|
|
type: integer
|
|
total:
|
|
type: integer
|
|
type: object
|
|
http.HabitEntryResponse:
|
|
properties:
|
|
completed_at:
|
|
type: string
|
|
habit_id:
|
|
type: string
|
|
id:
|
|
type: string
|
|
scheduled_date:
|
|
type: string
|
|
value:
|
|
type: number
|
|
type: object
|
|
http.HealthResponse:
|
|
properties:
|
|
database:
|
|
type: string
|
|
status:
|
|
type: string
|
|
uptime:
|
|
type: string
|
|
type: object
|
|
http.LoginRequest:
|
|
properties:
|
|
email:
|
|
type: string
|
|
password:
|
|
type: string
|
|
type: object
|
|
http.LogoutRequest:
|
|
properties:
|
|
refresh_token:
|
|
type: string
|
|
type: object
|
|
http.MarkHabitRequest:
|
|
properties:
|
|
scheduled_date:
|
|
type: string
|
|
value:
|
|
type: number
|
|
type: object
|
|
http.RefreshRequest:
|
|
properties:
|
|
refresh_token:
|
|
type: string
|
|
type: object
|
|
http.RegisterRequest:
|
|
properties:
|
|
email:
|
|
type: string
|
|
password:
|
|
type: string
|
|
timezone:
|
|
type: string
|
|
type: object
|
|
http.TodaysHabitResponse:
|
|
properties:
|
|
id:
|
|
type: string
|
|
is_carried_over:
|
|
type: boolean
|
|
is_negative:
|
|
type: boolean
|
|
name:
|
|
type: string
|
|
scheduled_date:
|
|
type: string
|
|
target_value:
|
|
type: number
|
|
type:
|
|
$ref: '#/definitions/value_objects.HabitType'
|
|
type: object
|
|
http.UpdateHabitRequest:
|
|
properties:
|
|
carry_over:
|
|
type: boolean
|
|
description:
|
|
type: string
|
|
name:
|
|
type: string
|
|
specific_dates:
|
|
items:
|
|
type: integer
|
|
type: array
|
|
specific_days:
|
|
items:
|
|
type: integer
|
|
type: array
|
|
target_value:
|
|
type: number
|
|
type: object
|
|
http.UserHabitResponse:
|
|
properties:
|
|
carry_over:
|
|
type: boolean
|
|
frequency:
|
|
$ref: '#/definitions/value_objects.Frequency'
|
|
id:
|
|
type: string
|
|
is_negative:
|
|
type: boolean
|
|
name:
|
|
type: string
|
|
specific_days:
|
|
items:
|
|
type: integer
|
|
type: array
|
|
target_value:
|
|
type: number
|
|
type:
|
|
$ref: '#/definitions/value_objects.HabitType'
|
|
type: object
|
|
queries.HabitStatsDTO:
|
|
properties:
|
|
completion_rate:
|
|
type: number
|
|
completions_this_month:
|
|
type: integer
|
|
completions_this_week:
|
|
type: integer
|
|
current_streak:
|
|
type: integer
|
|
habit_id:
|
|
type: string
|
|
habit_name:
|
|
type: string
|
|
longest_streak:
|
|
type: integer
|
|
total_completions:
|
|
type: integer
|
|
type: object
|
|
value_objects.Frequency:
|
|
enum:
|
|
- DAILY
|
|
- WEEKLY
|
|
- MONTHLY
|
|
type: string
|
|
x-enum-varnames:
|
|
- FrequencyDaily
|
|
- FrequencyWeekly
|
|
- FrequencyMonthly
|
|
value_objects.HabitType:
|
|
enum:
|
|
- BOOLEAN
|
|
- COUNTER
|
|
- VALUE
|
|
type: string
|
|
x-enum-varnames:
|
|
- HabitTypeBoolean
|
|
- HabitTypeCounter
|
|
- HabitTypeValue
|
|
info:
|
|
contact:
|
|
name: API Support
|
|
url: https://github.com/davidfolch/apocapoc-api
|
|
description: Self-hosted habit tracking service
|
|
license:
|
|
name: MIT
|
|
url: https://opensource.org/licenses/MIT
|
|
termsOfService: http://swagger.io/terms/
|
|
title: Apocapoc API
|
|
version: "1.0"
|
|
paths:
|
|
/auth/login:
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Authenticate user with email and password. Returns both access
|
|
token and refresh token. The access token is used for API requests, the refresh
|
|
token is used to obtain new access tokens when they expire.
|
|
parameters:
|
|
- description: Login credentials
|
|
in: body
|
|
name: request
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/http.LoginRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: Returns access token, refresh token, and user ID
|
|
schema:
|
|
$ref: '#/definitions/http.AuthResponse'
|
|
"400":
|
|
description: Invalid request body
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
"401":
|
|
description: Invalid email or password
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
"500":
|
|
description: Internal server error
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
summary: Login user
|
|
tags:
|
|
- auth
|
|
/auth/logout:
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Revoke the refresh token to invalidate the user session. After
|
|
logout, the refresh token cannot be used to obtain new access tokens. The
|
|
user will need to login again. Always call this endpoint before clearing tokens
|
|
from client storage to ensure proper session termination.
|
|
parameters:
|
|
- description: Refresh token to revoke
|
|
in: body
|
|
name: request
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/http.LogoutRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: Successfully logged out - the refresh token is now invalid
|
|
schema:
|
|
additionalProperties:
|
|
type: string
|
|
type: object
|
|
"400":
|
|
description: Invalid request body or missing refresh token
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
"404":
|
|
description: Refresh token not found (already revoked or never existed)
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
"500":
|
|
description: Internal server error
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
summary: Logout user
|
|
tags:
|
|
- auth
|
|
/auth/refresh:
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: 'Exchange a valid refresh token for a new access token and refresh
|
|
token pair. IMPORTANT: The old refresh token is automatically revoked and
|
|
you receive a NEW refresh token - always update both tokens in storage. Use
|
|
this endpoint when the access token expires to maintain the user session without
|
|
requiring re-login.'
|
|
parameters:
|
|
- description: Current refresh token
|
|
in: body
|
|
name: request
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/http.RefreshRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: Returns NEW access token and NEW refresh token - the old refresh
|
|
token is now invalid
|
|
schema:
|
|
$ref: '#/definitions/http.AuthResponse'
|
|
"400":
|
|
description: Invalid request body
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
"401":
|
|
description: Invalid or expired refresh token
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
"500":
|
|
description: Internal server error
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
summary: Refresh access token
|
|
tags:
|
|
- auth
|
|
/auth/register:
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Create a new user account and receive both access token and refresh
|
|
token. Store both tokens securely - the refresh token is used to obtain new
|
|
access tokens when they expire.
|
|
parameters:
|
|
- description: 'Registration data (password requires: min 8 chars, uppercase,
|
|
lowercase, digit, special char)'
|
|
in: body
|
|
name: request
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/http.RegisterRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"201":
|
|
description: Returns access token, refresh token, and user ID
|
|
schema:
|
|
$ref: '#/definitions/http.AuthResponse'
|
|
"400":
|
|
description: 'Invalid input: email format, password requirements, or timezone'
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
"409":
|
|
description: Email already registered
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
"500":
|
|
description: Internal server error
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
summary: Register a new user
|
|
tags:
|
|
- auth
|
|
/habits:
|
|
get:
|
|
description: Get all active habits for the authenticated user
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
items:
|
|
$ref: '#/definitions/http.UserHabitResponse'
|
|
type: array
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
"500":
|
|
description: Internal Server Error
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Get all user habits
|
|
tags:
|
|
- habits
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Create a new habit for the authenticated user
|
|
parameters:
|
|
- description: Habit data
|
|
in: body
|
|
name: request
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/http.CreateHabitRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"201":
|
|
description: Created
|
|
schema:
|
|
additionalProperties:
|
|
type: string
|
|
type: object
|
|
"400":
|
|
description: Bad Request
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
"500":
|
|
description: Internal Server Error
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Create a new habit
|
|
tags:
|
|
- habits
|
|
/habits/{id}:
|
|
delete:
|
|
description: Archive (soft delete) a habit
|
|
parameters:
|
|
- description: Habit ID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
additionalProperties:
|
|
type: string
|
|
type: object
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
"403":
|
|
description: Forbidden
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
"404":
|
|
description: Not Found
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
"500":
|
|
description: Internal Server Error
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Archive habit
|
|
tags:
|
|
- habits
|
|
get:
|
|
description: Get a specific habit by ID
|
|
parameters:
|
|
- description: Habit ID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
$ref: '#/definitions/http.UserHabitResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
"403":
|
|
description: Forbidden
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
"404":
|
|
description: Not Found
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
"500":
|
|
description: Internal Server Error
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Get habit by ID
|
|
tags:
|
|
- habits
|
|
put:
|
|
consumes:
|
|
- application/json
|
|
description: Update an existing habit
|
|
parameters:
|
|
- description: Habit ID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
- description: Update data
|
|
in: body
|
|
name: request
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/http.UpdateHabitRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
additionalProperties:
|
|
type: string
|
|
type: object
|
|
"400":
|
|
description: Bad Request
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
"403":
|
|
description: Forbidden
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
"404":
|
|
description: Not Found
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
"500":
|
|
description: Internal Server Error
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Update habit
|
|
tags:
|
|
- habits
|
|
/habits/{id}/entries:
|
|
get:
|
|
description: Get entries (completion history) for a habit with optional date
|
|
filtering and pagination
|
|
parameters:
|
|
- description: Habit ID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
- description: Start date (YYYY-MM-DD)
|
|
in: query
|
|
name: from
|
|
type: string
|
|
- description: End date (YYYY-MM-DD)
|
|
in: query
|
|
name: to
|
|
type: string
|
|
- description: Page number
|
|
in: query
|
|
name: page
|
|
type: integer
|
|
- description: Page size (max 100)
|
|
in: query
|
|
name: limit
|
|
type: integer
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
$ref: '#/definitions/http.HabitEntriesResponse'
|
|
"400":
|
|
description: Bad Request
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
"403":
|
|
description: Forbidden
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
"404":
|
|
description: Not Found
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
"500":
|
|
description: Internal Server Error
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Get habit entries
|
|
tags:
|
|
- habits
|
|
/habits/{id}/entries/{date}:
|
|
delete:
|
|
description: Delete a habit entry (unmark completion)
|
|
parameters:
|
|
- description: Habit ID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
- description: Date (YYYY-MM-DD)
|
|
in: path
|
|
name: date
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
additionalProperties:
|
|
type: string
|
|
type: object
|
|
"400":
|
|
description: Bad Request
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
"403":
|
|
description: Forbidden
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
"404":
|
|
description: Not Found
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
"500":
|
|
description: Internal Server Error
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Unmark habit
|
|
tags:
|
|
- habits
|
|
/habits/{id}/mark:
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Mark a habit as completed for a specific date
|
|
parameters:
|
|
- description: Habit ID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
- description: Mark data
|
|
in: body
|
|
name: request
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/http.MarkHabitRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
additionalProperties:
|
|
type: string
|
|
type: object
|
|
"400":
|
|
description: Bad Request
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
"404":
|
|
description: Not Found
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
"409":
|
|
description: Conflict
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
"500":
|
|
description: Internal Server Error
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Mark habit as complete
|
|
tags:
|
|
- habits
|
|
/habits/today:
|
|
get:
|
|
description: Get all habits scheduled for today for the authenticated user
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
items:
|
|
$ref: '#/definitions/http.TodaysHabitResponse'
|
|
type: array
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
"500":
|
|
description: Internal Server Error
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Get today's habits
|
|
tags:
|
|
- habits
|
|
/health:
|
|
get:
|
|
description: Get API health status including database connectivity and uptime
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
$ref: '#/definitions/http.HealthResponse'
|
|
"503":
|
|
description: Service Unavailable
|
|
schema:
|
|
$ref: '#/definitions/http.HealthResponse'
|
|
summary: Health check
|
|
tags:
|
|
- system
|
|
/stats/habits/{id}:
|
|
get:
|
|
description: Get statistics for a specific habit including streaks and completion
|
|
rates
|
|
parameters:
|
|
- description: Habit ID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
$ref: '#/definitions/queries.HabitStatsDTO'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
"403":
|
|
description: Forbidden
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
"404":
|
|
description: Not Found
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
"500":
|
|
description: Internal Server Error
|
|
schema:
|
|
$ref: '#/definitions/http.ErrorResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Get habit statistics
|
|
tags:
|
|
- stats
|
|
securityDefinitions:
|
|
BearerAuth:
|
|
description: Type "Bearer" followed by a space and JWT token.
|
|
in: header
|
|
name: Authorization
|
|
type: apiKey
|
|
swagger: "2.0"
|