diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 924b679..8abe8b3 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -17,8 +17,8 @@ jobs: - uses: actions/checkout@v4 with: repository: PapyrusReader/server - # Includes the private profile-photo API from server PR #42. - ref: 235fd051e2bf72283bcc6da4ecb2d1860b6ef332 + # Includes verified sign-in and the current library sync contracts. + ref: 0108e2db00fc907335616d37147159d804cb0030 path: .server - uses: astral-sh/setup-uv@v6 with: diff --git a/_static/openapi.json b/_static/openapi.json index 371715b..b54b87d 100644 --- a/_static/openapi.json +++ b/_static/openapi.json @@ -3838,6 +3838,56 @@ "title": "EndpointKind", "type": "string" }, + "Error": { + "description": "Standard error response.", + "properties": { + "error": { + "$ref": "#/components/schemas/ErrorDetail" + } + }, + "required": [ + "error" + ], + "title": "Error", + "type": "object" + }, + "ErrorDetail": { + "description": "Error detail structure.", + "properties": { + "code": { + "examples": [ + "VALIDATION_ERROR" + ], + "title": "Code", + "type": "string" + }, + "details": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Details" + }, + "message": { + "examples": [ + "Human-readable error message" + ], + "title": "Message", + "type": "string" + } + }, + "required": [ + "code", + "message" + ], + "title": "ErrorDetail", + "type": "object" + }, "ExportAnnotationsRequest": { "description": "Request for exporting annotations.", "properties": { @@ -4905,6 +4955,37 @@ "title": "Pagination", "type": "object" }, + "PendingVerificationResponse": { + "properties": { + "email": { + "format": "email", + "title": "Email", + "type": "string" + }, + "message": { + "default": "Check your email to verify your account, then sign in.", + "title": "Message", + "type": "string" + }, + "resend_after": { + "default": 60, + "minimum": 0.0, + "title": "Resend After", + "type": "integer" + }, + "status": { + "const": "verification_required", + "default": "verification_required", + "title": "Status", + "type": "string" + } + }, + "required": [ + "email" + ], + "title": "PendingVerificationResponse", + "type": "object" + }, "PowerSyncCrudMutation": { "description": "One owned library mutation uploaded from the PowerSync queue.", "properties": { @@ -4968,6 +5049,7 @@ "bookmarks", "book_shelves", "book_tags", + "reading_timers", "reading_goals", "reading_activities", "goal_periods" @@ -5816,6 +5898,23 @@ "title": "ResendVerificationRequest", "type": "object" }, + "ResendVerificationResponse": { + "properties": { + "message": { + "default": "If the email is registered, a verification link has been sent", + "title": "Message", + "type": "string" + }, + "resend_after": { + "default": 60, + "minimum": 0.0, + "title": "Resend After", + "type": "integer" + } + }, + "title": "ResendVerificationResponse", + "type": "object" + }, "ResetPasswordRequest": { "description": "Password reset request.", "properties": { @@ -7971,13 +8070,13 @@ "name": "Papyrus Support", "url": "https://github.com/PapyrusReader/papyrus" }, - "description": "\nREST API for Papyrus - a cross-platform book management application.\n\n## Overview\n\nThe Papyrus Server handles metadata storage and synchronization for the Papyrus\ne-book reader application. It provides endpoints for:\n\n- **Authentication**: User registration, login, OAuth, and session management\n- **Books**: CRUD operations for book metadata and file references\n- **Organization**: Shelves, tags, and series management\n- **Annotations**: Highlights, notes, and bookmarks\n- **Progress**: Reading sessions and statistics\n- **Goals**: Reading goal tracking\n- **Sync**: Cross-device synchronization\n- **Storage**: File storage backend configuration\n- **Files**: File upload/download (when server is file backend)\n\n## Authentication\n\nMost endpoints require authentication via JWT Bearer token. Obtain tokens\nthrough the `/v1/auth/register`, `/v1/auth/login`, or the\nbrowser-based `/v1/auth/oauth/google/start` flow.\n\n```\nAuthorization: Bearer \n```\n\nAccess tokens expire after `60` minutes.\nUse the refresh token to obtain new access tokens via `/v1/auth/refresh`.\n\n## Rate Limiting\n\nSync and file-upload limits are enforced per authenticated user, across sessions.\nAuthentication and OPDS relay limits are enforced per client IP. Limits are configurable:\n\n| Endpoint Category | Limit |\n|-------------------|-------|\n| Authentication | 5 requests/minute |\n| OPDS relay | 100 requests/minute |\n| File uploads | 60 requests/minute |\n| Sync transactions | 300 requests/minute |\n", + "description": "\nREST API for Papyrus - a cross-platform book management application.\n\n## Overview\n\nThe Papyrus Server handles metadata storage and synchronization for the Papyrus\ne-book reader application. It provides endpoints for:\n\n- **Authentication**: User registration, login, OAuth, and session management\n- **Books**: CRUD operations for book metadata and file references\n- **Organization**: Shelves, tags, and series management\n- **Annotations**: Highlights, notes, and bookmarks\n- **Progress**: Reading sessions and statistics\n- **Goals**: Reading goal tracking\n- **Sync**: Cross-device synchronization\n- **Storage**: File storage backend configuration\n- **Files**: File upload/download (when server is file backend)\n\n## Authentication\n\nMost endpoints require authentication via JWT Bearer token. Obtain tokens\nafter email verification through `/v1/auth/login` or the\nbrowser-based `/v1/auth/oauth/google/start` flow.\n\n```\nAuthorization: Bearer \n```\n\nAccess tokens expire after `60` minutes.\nUse the refresh token to obtain new access tokens via `/v1/auth/refresh`.\n\n## Rate Limiting\n\nSync and file-upload limits are enforced per authenticated user, across sessions.\nAuthentication and OPDS relay limits are enforced per client IP. Limits are configurable:\n\n| Endpoint Category | Limit |\n|-------------------|-------|\n| Authentication | 5 requests/minute |\n| OPDS relay | 100 requests/minute |\n| File uploads | 60 requests/minute |\n| Sync transactions | 300 requests/minute |\n", "license": { "name": "AGPL-3.0", "url": "https://www.gnu.org/licenses/agpl-3.0.html" }, "title": "Papyrus Server API", - "version": "0.0.4" + "version": "0.4.0" }, "openapi": "3.1.0", "paths": { @@ -9734,6 +9833,36 @@ }, "description": "Successful Response" }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Invalid request or VERIFICATION_TOKEN_INVALID." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Invalid, expired or revoked credentials." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "EMAIL_VERIFICATION_REQUIRED includes email and resend_after seconds." + }, "422": { "content": { "application/json": { @@ -9743,6 +9872,26 @@ } }, "description": "Validation Error" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "RATE_LIMIT_EXCEEDED with Retry-After and details.retry_after seconds." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "VERIFICATION_UNAVAILABLE with Retry-After: 60. Retry sign-in or resend after an uncertain registration outcome." } }, "summary": "Exchange an OAuth browser code for Papyrus tokens", @@ -9776,6 +9925,36 @@ }, "description": "Successful Response" }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Invalid request or VERIFICATION_TOKEN_INVALID." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Invalid, expired or revoked credentials." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "EMAIL_VERIFICATION_REQUIRED includes email and resend_after seconds." + }, "422": { "content": { "application/json": { @@ -9785,6 +9964,26 @@ } }, "description": "Validation Error" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "RATE_LIMIT_EXCEEDED with Retry-After and details.retry_after seconds." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "VERIFICATION_UNAVAILABLE with Retry-After: 60. Retry sign-in or resend after an uncertain registration outcome." } }, "summary": "Request password reset", @@ -9815,6 +10014,56 @@ } }, "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Invalid request or VERIFICATION_TOKEN_INVALID." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Invalid, expired or revoked credentials." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "EMAIL_VERIFICATION_REQUIRED includes email and resend_after seconds." + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "RATE_LIMIT_EXCEEDED with Retry-After and details.retry_after seconds." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "VERIFICATION_UNAVAILABLE with Retry-After: 60. Retry sign-in or resend after an uncertain registration outcome." } }, "summary": "Return the PowerSync signing JWKS", @@ -9848,6 +10097,36 @@ }, "description": "Successful Response" }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Invalid request or VERIFICATION_TOKEN_INVALID." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Invalid, expired or revoked credentials." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "EMAIL_VERIFICATION_REQUIRED includes email and resend_after seconds." + }, "422": { "content": { "application/json": { @@ -9857,6 +10136,26 @@ } }, "description": "Validation Error" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "RATE_LIMIT_EXCEEDED with Retry-After and details.retry_after seconds." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "VERIFICATION_UNAVAILABLE with Retry-After: 60. Retry sign-in or resend after an uncertain registration outcome." } }, "security": [ @@ -9895,6 +10194,36 @@ }, "description": "Successful Response" }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Invalid request or VERIFICATION_TOKEN_INVALID." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Invalid, expired or revoked credentials." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "EMAIL_VERIFICATION_REQUIRED includes email and resend_after seconds." + }, "422": { "content": { "application/json": { @@ -9904,6 +10233,26 @@ } }, "description": "Validation Error" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "RATE_LIMIT_EXCEEDED with Retry-After and details.retry_after seconds." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "VERIFICATION_UNAVAILABLE with Retry-After: 60. Retry sign-in or resend after an uncertain registration outcome." } }, "security": [ @@ -9942,20 +10291,70 @@ }, "description": "Successful Response" }, - "422": { + "400": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/HTTPValidationError" + "$ref": "#/components/schemas/Error" } } }, - "description": "Validation Error" - } - }, - "summary": "Login with email and password", - "tags": [ - "Auth" + "description": "Invalid request or VERIFICATION_TOKEN_INVALID." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Invalid, expired or revoked credentials." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "EMAIL_VERIFICATION_REQUIRED includes email and resend_after seconds." + }, + "422": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + }, + "description": "Validation Error" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "RATE_LIMIT_EXCEEDED with Retry-After and details.retry_after seconds." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "VERIFICATION_UNAVAILABLE with Retry-After: 60. Retry sign-in or resend after an uncertain registration outcome." + } + }, + "summary": "Login with email and password", + "tags": [ + "Auth" ] } }, @@ -9984,6 +10383,36 @@ "204": { "description": "Successful Response" }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Invalid request or VERIFICATION_TOKEN_INVALID." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Invalid, expired or revoked credentials." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "EMAIL_VERIFICATION_REQUIRED includes email and resend_after seconds." + }, "422": { "content": { "application/json": { @@ -9993,6 +10422,26 @@ } }, "description": "Validation Error" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "RATE_LIMIT_EXCEEDED with Retry-After and details.retry_after seconds." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "VERIFICATION_UNAVAILABLE with Retry-After: 60. Retry sign-in or resend after an uncertain registration outcome." } }, "security": [ @@ -10013,6 +10462,56 @@ "responses": { "204": { "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Invalid request or VERIFICATION_TOKEN_INVALID." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Invalid, expired or revoked credentials." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "EMAIL_VERIFICATION_REQUIRED includes email and resend_after seconds." + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "RATE_LIMIT_EXCEEDED with Retry-After and details.retry_after seconds." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "VERIFICATION_UNAVAILABLE with Retry-After: 60. Retry sign-in or resend after an uncertain registration outcome." } }, "security": [ @@ -10089,6 +10588,36 @@ }, "description": "Successful Response" }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Invalid request or VERIFICATION_TOKEN_INVALID." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Invalid, expired or revoked credentials." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "EMAIL_VERIFICATION_REQUIRED includes email and resend_after seconds." + }, "422": { "content": { "application/json": { @@ -10098,6 +10627,26 @@ } }, "description": "Validation Error" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "RATE_LIMIT_EXCEEDED with Retry-After and details.retry_after seconds." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "VERIFICATION_UNAVAILABLE with Retry-After: 60. Retry sign-in or resend after an uncertain registration outcome." } }, "summary": "Complete the Google OAuth browser callback", @@ -10132,6 +10681,36 @@ }, "description": "Successful Response" }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Invalid request or VERIFICATION_TOKEN_INVALID." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Invalid, expired or revoked credentials." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "EMAIL_VERIFICATION_REQUIRED includes email and resend_after seconds." + }, "422": { "content": { "application/json": { @@ -10141,6 +10720,26 @@ } }, "description": "Validation Error" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "RATE_LIMIT_EXCEEDED with Retry-After and details.retry_after seconds." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "VERIFICATION_UNAVAILABLE with Retry-After: 60. Retry sign-in or resend after an uncertain registration outcome." } }, "summary": "Start Google OAuth login flow", @@ -10163,6 +10762,56 @@ } }, "description": "Successful Response" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Invalid request or VERIFICATION_TOKEN_INVALID." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Invalid, expired or revoked credentials." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "EMAIL_VERIFICATION_REQUIRED includes email and resend_after seconds." + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "RATE_LIMIT_EXCEEDED with Retry-After and details.retry_after seconds." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "VERIFICATION_UNAVAILABLE with Retry-After: 60. Retry sign-in or resend after an uncertain registration outcome." } }, "security": [ @@ -10201,6 +10850,36 @@ }, "description": "Successful Response" }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Invalid request or VERIFICATION_TOKEN_INVALID." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Invalid, expired or revoked credentials." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "EMAIL_VERIFICATION_REQUIRED includes email and resend_after seconds." + }, "422": { "content": { "application/json": { @@ -10210,6 +10889,26 @@ } }, "description": "Validation Error" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "RATE_LIMIT_EXCEEDED with Retry-After and details.retry_after seconds." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "VERIFICATION_UNAVAILABLE with Retry-After: 60. Retry sign-in or resend after an uncertain registration outcome." } }, "summary": "Refresh access token", @@ -10237,12 +10936,42 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/AuthTokens" + "$ref": "#/components/schemas/PendingVerificationResponse" } } }, "description": "Successful Response" }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Invalid request or VERIFICATION_TOKEN_INVALID." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Invalid, expired or revoked credentials." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "EMAIL_VERIFICATION_REQUIRED includes email and resend_after seconds." + }, "422": { "content": { "application/json": { @@ -10252,6 +10981,26 @@ } }, "description": "Validation Error" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "RATE_LIMIT_EXCEEDED with Retry-After and details.retry_after seconds." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "VERIFICATION_UNAVAILABLE with Retry-After: 60. Retry sign-in or resend after an uncertain registration outcome." } }, "summary": "Register a new user account", @@ -10279,12 +11028,42 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/MessageResponse" + "$ref": "#/components/schemas/ResendVerificationResponse" } } }, "description": "Successful Response" }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Invalid request or VERIFICATION_TOKEN_INVALID." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Invalid, expired or revoked credentials." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "EMAIL_VERIFICATION_REQUIRED includes email and resend_after seconds." + }, "422": { "content": { "application/json": { @@ -10294,6 +11073,26 @@ } }, "description": "Validation Error" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "RATE_LIMIT_EXCEEDED with Retry-After and details.retry_after seconds." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "VERIFICATION_UNAVAILABLE with Retry-After: 60. Retry sign-in or resend after an uncertain registration outcome." } }, "summary": "Resend verification email", @@ -10327,6 +11126,36 @@ }, "description": "Successful Response" }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Invalid request or VERIFICATION_TOKEN_INVALID." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Invalid, expired or revoked credentials." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "EMAIL_VERIFICATION_REQUIRED includes email and resend_after seconds." + }, "422": { "content": { "application/json": { @@ -10336,6 +11165,26 @@ } }, "description": "Validation Error" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "RATE_LIMIT_EXCEEDED with Retry-After and details.retry_after seconds." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "VERIFICATION_UNAVAILABLE with Retry-After: 60. Retry sign-in or resend after an uncertain registration outcome." } }, "summary": "Reset password with token", @@ -10369,6 +11218,36 @@ }, "description": "Successful Response" }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Invalid request or VERIFICATION_TOKEN_INVALID." + }, + "401": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "Invalid, expired or revoked credentials." + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "EMAIL_VERIFICATION_REQUIRED includes email and resend_after seconds." + }, "422": { "content": { "application/json": { @@ -10378,6 +11257,26 @@ } }, "description": "Validation Error" + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "RATE_LIMIT_EXCEEDED with Retry-After and details.retry_after seconds." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + }, + "description": "VERIFICATION_UNAVAILABLE with Retry-After: 60. Retry sign-in or resend after an uncertain registration outcome." } }, "summary": "Verify email address", diff --git a/design/server-architecture.rst b/design/server-architecture.rst index e1bf0e5..e739402 100644 --- a/design/server-architecture.rst +++ b/design/server-architecture.rst @@ -42,6 +42,18 @@ The current library mutation handler discards client-supplied ``updated_at``, applies supplied fields, and assigns a server update time. Tombstones protect deleted entities. JSON payloads are not recursively merged. Owner serialization, atomic batches, and history validation remain part of the server contract. +Reading history is an immutable ledger: corrections append reversals, and progress +is projected from eligible time intervals and document coverage. Tracking writes +are staged locally until the server advertises the current schema contract. + +Timers use versioned transitions under the same owner lock. The first accepted +branch wins; stale branches are acknowledged without applying their effects. Saving +a timer, appending its activities and updating book progress form one transaction. +Conflicting saves discard the whole batch. Terminal rows prevent delayed offline +writes from reviving completed timers. Native notification actions are journaled +on the device and replayed through the client repository; they do not write to +PowerSync independently. + These mechanisms need acceptance coverage across the full set of mutable fields before the whole requirement can be marked verified. @@ -72,9 +84,7 @@ against the configured server. External provider photo URLs remain supported, but are fetched without Papyrus credentials. Downloads are private and marked ``no-store``. Replacing a photo removes the previous file after commit, and permanent account deletion removes the entire owner media directory, including -photos. Failed writes retain the previous reference and file. This increment -does not change database schemas or PowerSync projections. Deploy the updated -server before clients that offer photo uploads. +photos. Failed writes retain the previous reference and file. Account deletion and recovery ----------------------------- @@ -95,11 +105,22 @@ failures, with row locks coordinating multiple workers. Local device libraries and external provider files remain outside this cleanup. Previously issued PowerSync tokens remain usable until expiry and cannot be renewed. -Planned contracts ------------------ +Verification before sign-in +---------------------------- + +Registration creates a pending account and queues verification mail without +issuing an application session. Login, refresh and authenticated API access require +verification of the account's current primary email. Verification consumes a +single-use email-bound token; the client then signs in separately. Google sign-in +uses provider authority for eligible Gmail/Workspace identities and Papyrus email +verification for other addresses. Guest data stays separate throughout these flows. + +The generated :doc:`/api/index` defines the wire schemas. Auth services and their +regression tests own eligibility, token consumption and delivery behavior. + +Planned capabilities +-------------------- -Email verification before sign-in, recoverable account deletion followed by -permanent cleanup, and full-library content search are requirements with remaining -implementation work. They are not capabilities established by the architecture -diagram above. Additional storage providers remain committed targets, but -automatic failover is outside scope. +Full-library content search and additional storage providers remain product +targets. Their presence in requirements or diagrams does not establish implemented +behavior. Automatic storage failover is outside scope. diff --git a/requirements/functional.rst b/requirements/functional.rst index 5b1fc74..fe3de91 100644 --- a/requirements/functional.rst +++ b/requirements/functional.rst @@ -25,9 +25,9 @@ These are product commitments, not a list of released capabilities. See - Verification links are single-use, expire after 24 hours, and can be resent with rate limiting - Guest use remains available without verification and keeps its own separate library - **Implementation:** Registration and verification services exist, but - registration currently creates an authenticated session. Requiring verification - first needs coordinated changes to the server and the client registration flow. + **Implementation:** The server returns pending-verification details without + session tokens. The client shows verification guidance and keeps the guest + library separate. After verifying the email address, the user signs in. Email ownership is required because the address identifies the account and supports recovery. See `OWASP authentication guidance @@ -50,8 +50,9 @@ These are product commitments, not a list of released capabilities. See - Successful login creates a secure session token - User is redirected to their library after login - **Implementation:** Email/password login exists, but the server does not - currently enforce email verification before issuing a session. + **Implementation:** The server requires verification of the current primary + email before issuing or refreshing a session. The client routes unverified + users to verification guidance without installing an authenticated session. .. fr:: OAuth login (Google) :id: FR-1_3