@myronsi/messenger-api 2.0.0-alpha.8 → 2.1.0-alpha.1

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 Contract changes only. The backend changelog is `CHANGELOG.md` in the repository root. Rules: `docs/api-compatibility.md`.
 
+## 2.1.0-alpha.1
+
+- Registration returns a one-time recovery_key. GET /me adds recovery_setup_required.
+- Adds GET/POST /me/recovery-key, POST /auth/recover/key and GET /me/security-events.
+- Adds the security_notice WebSocket event for a recovery password reset.
+- Recovery requires 2FA when enabled, rotates its key and sessions, and delays recovery-method changes for 24 hours. Legacy Shamir recovery remains unavailable.
+
 ## 2.0.0-alpha.8
 
 Found by validating every response of the backend's HTTP tests against this contract:

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-/* Generated from api/openapi.yaml 2.0.0-alpha.8. Do not edit. */
-export declare const API_VERSION: "2.0.0-alpha.8";
+/* Generated from api/openapi.yaml 2.1.0-alpha.1. Do not edit. */
+export declare const API_VERSION: "2.1.0-alpha.1";
 export type { paths, components, operations } from "./schema.js";
 export * from "./ws-events.js";

package/dist/index.js

@@ -1 +1 @@
-export const API_VERSION = "2.0.0-alpha.8";
+export const API_VERSION = "2.1.0-alpha.1";

package/dist/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: Messenger API
-  version: 2.0.0-alpha.8
+  version: 2.1.0-alpha.1
   summary: REST contract of the Messenger backend (v2).
   description: |
     Contract for the Go backend. The WebSocket protocol is described in `websocket/` and
@@ -202,6 +202,97 @@ paths:
           headers:
             Set-Cookie: { $ref: "#/components/headers/RefreshCookie" }
         "401": { $ref: "#/components/responses/Unauthorized" }
+  /auth/recover/key:
+    parameters:
+      - $ref: "#/components/parameters/ClientVersion"
+      - $ref: "#/components/parameters/ClientApiVersion"
+    post:
+      tags: [auth]
+      operationId: recoverWithKey
+      summary: Reset password with a single-use recovery key
+      security: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/RecoverWithKeyRequest" }
+      responses:
+        "200":
+          description: Success
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/RegisterResponse" }
+        "400": { $ref: "#/components/responses/BadRequest" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+        "403": { $ref: "#/components/responses/Forbidden" }
+        "409": { $ref: "#/components/responses/Conflict" }
+        "422": { $ref: "#/components/responses/ValidationFailed" }
+        "426": { $ref: "#/components/responses/ClientOutdated" }
+        "429": { $ref: "#/components/responses/TooManyRequests" }
+  /me/recovery-key:
+    parameters:
+      - $ref: "#/components/parameters/ClientVersion"
+      - $ref: "#/components/parameters/ClientApiVersion"
+    get:
+      tags: [auth]
+      operationId: getRecoveryKey
+      summary: Get recovery-key status without revealing its hash
+      responses:
+        "200":
+          description: Success
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/RecoveryKeyStatus" }
+        "400": { $ref: "#/components/responses/BadRequest" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+        "403": { $ref: "#/components/responses/Forbidden" }
+        "409": { $ref: "#/components/responses/Conflict" }
+        "422": { $ref: "#/components/responses/ValidationFailed" }
+        "426": { $ref: "#/components/responses/ClientOutdated" }
+        "429": { $ref: "#/components/responses/TooManyRequests" }
+    post:
+      tags: [auth]
+      operationId: replaceRecoveryKey
+      summary: Create or regenerate a recovery key after password and second-factor confirmation
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/ReplaceRecoveryKeyRequest" }
+      responses:
+        "200":
+          description: Success
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/RecoveryKeyResult" }
+        "400": { $ref: "#/components/responses/BadRequest" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+        "403": { $ref: "#/components/responses/Forbidden" }
+        "409": { $ref: "#/components/responses/Conflict" }
+        "422": { $ref: "#/components/responses/ValidationFailed" }
+        "426": { $ref: "#/components/responses/ClientOutdated" }
+        "429": { $ref: "#/components/responses/TooManyRequests" }
+  /me/security-events:
+    parameters:
+      - $ref: "#/components/parameters/ClientVersion"
+      - $ref: "#/components/parameters/ClientApiVersion"
+    get:
+      tags: [auth]
+      operationId: listSecurityEvents
+      summary: List the last 50 security events of this account
+      responses:
+        "200":
+          description: Success
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/SecurityEventPage" }
+        "400": { $ref: "#/components/responses/BadRequest" }
+        "401": { $ref: "#/components/responses/Unauthorized" }
+        "403": { $ref: "#/components/responses/Forbidden" }
+        "409": { $ref: "#/components/responses/Conflict" }
+        "422": { $ref: "#/components/responses/ValidationFailed" }
+        "426": { $ref: "#/components/responses/ClientOutdated" }
+        "429": { $ref: "#/components/responses/TooManyRequests" }
   /auth/recover:
     parameters:
       - $ref: "#/components/parameters/ClientVersion"
@@ -1880,12 +1971,52 @@ components:
           type: integer
           minimum: 1
           description: Seconds until the access token expires
+    RecoverWithKeyRequest:
+      type: object
+      required: [username, recovery_key, new_password]
+      properties:
+        username: { type: string, maxLength: 64 }
+        recovery_key: { type: string, maxLength: 128 }
+        new_password: { type: string, minLength: 8, maxLength: 128 }
+        code: { type: string, maxLength: 128 }
+    ReplaceRecoveryKeyRequest:
+      type: object
+      required: [password]
+      properties:
+        password: { type: string, maxLength: 128 }
+        code: { type: string, maxLength: 128 }
+    RecoveryKeyResult:
+      type: object
+      required: [recovery_key]
+      properties:
+        recovery_key: { type: string }
+    RecoveryKeyStatus:
+      type: object
+      required: [exists, created_at, locked_until]
+      properties:
+        exists: { type: boolean }
+        created_at: { type: [string, 'null'], format: date-time }
+        locked_until: { type: [string, 'null'], format: date-time }
+    SecurityEventPage:
+      type: object
+      required: [items]
+      properties:
+        items:
+          type: array
+          items:
+            type: object
+            required: [id, type, created_at]
+            properties:
+              id: { $ref: "#/components/schemas/Id" }
+              type: { type: string }
+              created_at: { type: string, format: date-time }
     RegisterResponse:
       allOf:
         - $ref: "#/components/schemas/TokenResponse"
         - type: object
           description: Recovery parts of the temporary recovery flow (redesigned in release 1.1).
           properties:
+            recovery_key: { type: string, description: Shown once; only a keyed hash is stored }
             device_part: { type: string }
             qr_part: { type: string }
     TwoFactorChallenge:
@@ -2095,6 +2226,7 @@ components:
           required: [created_at]
           properties:
             created_at: { $ref: "#/components/schemas/Timestamp" }
+            recovery_setup_required: { type: boolean }
     UserPage:
       type: object
       required: [items, next_cursor]

package/dist/schema.d.ts

@@ -1,4 +1,4 @@
-/* Generated from api/openapi.yaml 2.0.0-alpha.8. Do not edit. */
+/* Generated from api/openapi.yaml 2.1.0-alpha.1. Do not edit. */
 export interface paths {
     "/meta": {
         parameters: {
@@ -136,6 +136,73 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/auth/recover/key": {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description Version of the client app, for logs and the per-client metric. */
+                "X-Client-Version"?: components["parameters"]["ClientVersion"];
+                /** @description Contract version the client was built with (`API_VERSION` of `@myronsi/messenger-api`). A different MAJOR or a version below `min_client_api_version` is answered with `426`; a malformed value with `400` (`invalid_client_version`). */
+                "X-Client-Api-Version"?: components["parameters"]["ClientApiVersion"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Reset password with a single-use recovery key */
+        post: operations["recoverWithKey"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/me/recovery-key": {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description Version of the client app, for logs and the per-client metric. */
+                "X-Client-Version"?: components["parameters"]["ClientVersion"];
+                /** @description Contract version the client was built with (`API_VERSION` of `@myronsi/messenger-api`). A different MAJOR or a version below `min_client_api_version` is answered with `426`; a malformed value with `400` (`invalid_client_version`). */
+                "X-Client-Api-Version"?: components["parameters"]["ClientApiVersion"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        /** Get recovery-key status without revealing its hash */
+        get: operations["getRecoveryKey"];
+        put?: never;
+        /** Create or regenerate a recovery key after password and second-factor confirmation */
+        post: operations["replaceRecoveryKey"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/me/security-events": {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description Version of the client app, for logs and the per-client metric. */
+                "X-Client-Version"?: components["parameters"]["ClientVersion"];
+                /** @description Contract version the client was built with (`API_VERSION` of `@myronsi/messenger-api`). A different MAJOR or a version below `min_client_api_version` is answered with `426`; a malformed value with `400` (`invalid_client_version`). */
+                "X-Client-Api-Version"?: components["parameters"]["ClientApiVersion"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        /** List the last 50 security events of this account */
+        get: operations["listSecurityEvents"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/auth/recover": {
         parameters: {
             query?: never;
@@ -1358,7 +1425,37 @@ export interface components {
             /** @description Seconds until the access token expires */
             expires_in: number;
         };
+        RecoverWithKeyRequest: {
+            username: string;
+            recovery_key: string;
+            new_password: string;
+            code?: string;
+        };
+        ReplaceRecoveryKeyRequest: {
+            password: string;
+            code?: string;
+        };
+        RecoveryKeyResult: {
+            recovery_key: string;
+        };
+        RecoveryKeyStatus: {
+            exists: boolean;
+            /** Format: date-time */
+            created_at: string | null;
+            /** Format: date-time */
+            locked_until: string | null;
+        };
+        SecurityEventPage: {
+            items: {
+                id: components["schemas"]["Id"];
+                type: string;
+                /** Format: date-time */
+                created_at: string;
+            }[];
+        };
         RegisterResponse: components["schemas"]["TokenResponse"] & {
+            /** @description Shown once; only a keyed hash is stored */
+            recovery_key?: string;
             device_part?: string;
             qr_part?: string;
         };
@@ -1488,6 +1585,7 @@ export interface components {
         };
         Me: components["schemas"]["User"] & {
             created_at: components["schemas"]["Timestamp"];
+            recovery_setup_required?: boolean;
         };
         UserPage: {
             items: components["schemas"]["User"][];
@@ -1989,6 +2087,142 @@ export interface operations {
             426: components["responses"]["ClientOutdated"];
         };
     };
+    recoverWithKey: {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description Version of the client app, for logs and the per-client metric. */
+                "X-Client-Version"?: components["parameters"]["ClientVersion"];
+                /** @description Contract version the client was built with (`API_VERSION` of `@myronsi/messenger-api`). A different MAJOR or a version below `min_client_api_version` is answered with `426`; a malformed value with `400` (`invalid_client_version`). */
+                "X-Client-Api-Version"?: components["parameters"]["ClientApiVersion"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["RecoverWithKeyRequest"];
+            };
+        };
+        responses: {
+            /** @description Success */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["RegisterResponse"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            409: components["responses"]["Conflict"];
+            422: components["responses"]["ValidationFailed"];
+            426: components["responses"]["ClientOutdated"];
+            429: components["responses"]["TooManyRequests"];
+        };
+    };
+    getRecoveryKey: {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description Version of the client app, for logs and the per-client metric. */
+                "X-Client-Version"?: components["parameters"]["ClientVersion"];
+                /** @description Contract version the client was built with (`API_VERSION` of `@myronsi/messenger-api`). A different MAJOR or a version below `min_client_api_version` is answered with `426`; a malformed value with `400` (`invalid_client_version`). */
+                "X-Client-Api-Version"?: components["parameters"]["ClientApiVersion"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Success */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["RecoveryKeyStatus"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            409: components["responses"]["Conflict"];
+            422: components["responses"]["ValidationFailed"];
+            426: components["responses"]["ClientOutdated"];
+            429: components["responses"]["TooManyRequests"];
+        };
+    };
+    replaceRecoveryKey: {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description Version of the client app, for logs and the per-client metric. */
+                "X-Client-Version"?: components["parameters"]["ClientVersion"];
+                /** @description Contract version the client was built with (`API_VERSION` of `@myronsi/messenger-api`). A different MAJOR or a version below `min_client_api_version` is answered with `426`; a malformed value with `400` (`invalid_client_version`). */
+                "X-Client-Api-Version"?: components["parameters"]["ClientApiVersion"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ReplaceRecoveryKeyRequest"];
+            };
+        };
+        responses: {
+            /** @description Success */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["RecoveryKeyResult"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            409: components["responses"]["Conflict"];
+            422: components["responses"]["ValidationFailed"];
+            426: components["responses"]["ClientOutdated"];
+            429: components["responses"]["TooManyRequests"];
+        };
+    };
+    listSecurityEvents: {
+        parameters: {
+            query?: never;
+            header?: {
+                /** @description Version of the client app, for logs and the per-client metric. */
+                "X-Client-Version"?: components["parameters"]["ClientVersion"];
+                /** @description Contract version the client was built with (`API_VERSION` of `@myronsi/messenger-api`). A different MAJOR or a version below `min_client_api_version` is answered with `426`; a malformed value with `400` (`invalid_client_version`). */
+                "X-Client-Api-Version"?: components["parameters"]["ClientApiVersion"];
+            };
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Success */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["SecurityEventPage"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            409: components["responses"]["Conflict"];
+            422: components["responses"]["ValidationFailed"];
+            426: components["responses"]["ClientOutdated"];
+            429: components["responses"]["TooManyRequests"];
+        };
+    };
     startRecovery: {
         parameters: {
             query?: never;

package/dist/ws-docs.json

@@ -415,6 +415,14 @@
         "read_at": "2026-10-04T12:00:00Z"
       }
     },
+    "server/security_notice.json": {
+      "type": "security_notice",
+      "event_id": "7217400317439950009",
+      "chat_id": null,
+      "data": {
+        "type": "password_reset"
+      }
+    },
     "server/typing.json": {
       "type": "typing",
       "event_id": "7217400317439950009",

package/dist/ws-events.d.ts

@@ -1,4 +1,4 @@
-/* Generated from api/openapi.yaml 2.0.0-alpha.8. Do not edit. */
+/* Generated from api/openapi.yaml 2.1.0-alpha.1. Do not edit. */
 
 /**
  * Any WebSocket event, in either direction.
@@ -48,6 +48,7 @@ export type ServerEvent =
   | ServerReactionAddEvent
   | ServerReactionRemoveEvent
   | ServerReadEvent
+  | ServerSecurityNoticeEvent
   | ServerTypingEvent;
 export type Timestamp = string;
 export type ApprovalRequestType = "direct_message" | "group_invite";
@@ -516,6 +517,14 @@ export interface ServerReadEvent {
     read_at: Timestamp;
   };
 }
+export interface ServerSecurityNoticeEvent {
+  type: "security_notice";
+  event_id: Id;
+  chat_id: null;
+  data: {
+    type: "password_reset";
+  };
+}
 /**
  * A user started or stopped typing.
  */

package/dist/ws-events.schema.json

@@ -249,6 +249,118 @@
         }
       }
     },
+    "RecoverWithKeyRequest": {
+      "type": "object",
+      "required": [
+        "username",
+        "recovery_key",
+        "new_password"
+      ],
+      "properties": {
+        "username": {
+          "type": "string",
+          "maxLength": 64
+        },
+        "recovery_key": {
+          "type": "string",
+          "maxLength": 128
+        },
+        "new_password": {
+          "type": "string",
+          "minLength": 8,
+          "maxLength": 128
+        },
+        "code": {
+          "type": "string",
+          "maxLength": 128
+        }
+      }
+    },
+    "ReplaceRecoveryKeyRequest": {
+      "type": "object",
+      "required": [
+        "password"
+      ],
+      "properties": {
+        "password": {
+          "type": "string",
+          "maxLength": 128
+        },
+        "code": {
+          "type": "string",
+          "maxLength": 128
+        }
+      }
+    },
+    "RecoveryKeyResult": {
+      "type": "object",
+      "required": [
+        "recovery_key"
+      ],
+      "properties": {
+        "recovery_key": {
+          "type": "string"
+        }
+      }
+    },
+    "RecoveryKeyStatus": {
+      "type": "object",
+      "required": [
+        "exists",
+        "created_at",
+        "locked_until"
+      ],
+      "properties": {
+        "exists": {
+          "type": "boolean"
+        },
+        "created_at": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "format": "date-time"
+        },
+        "locked_until": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "format": "date-time"
+        }
+      }
+    },
+    "SecurityEventPage": {
+      "type": "object",
+      "required": [
+        "items"
+      ],
+      "properties": {
+        "items": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "id",
+              "type",
+              "created_at"
+            ],
+            "properties": {
+              "id": {
+                "$ref": "#/$defs/Id"
+              },
+              "type": {
+                "type": "string"
+              },
+              "created_at": {
+                "type": "string",
+                "format": "date-time"
+              }
+            }
+          }
+        }
+      }
+    },
     "RegisterResponse": {
       "allOf": [
         {
@@ -258,6 +370,10 @@
           "type": "object",
           "description": "Recovery parts of the temporary recovery flow (redesigned in release 1.1).",
           "properties": {
+            "recovery_key": {
+              "type": "string",
+              "description": "Shown once; only a keyed hash is stored"
+            },
             "device_part": {
               "type": "string"
             },
@@ -761,6 +877,9 @@
           "properties": {
             "created_at": {
               "$ref": "#/$defs/Timestamp"
+            },
+            "recovery_setup_required": {
+              "type": "boolean"
             }
           }
         }
@@ -2637,6 +2756,38 @@
         "data"
       ]
     },
+    "ServerSecurityNoticeEvent": {
+      "title": "ServerSecurityNoticeEvent",
+      "type": "object",
+      "required": [
+        "type",
+        "event_id",
+        "chat_id",
+        "data"
+      ],
+      "properties": {
+        "type": {
+          "const": "security_notice"
+        },
+        "event_id": {
+          "$ref": "#/$defs/Id"
+        },
+        "chat_id": {
+          "type": "null"
+        },
+        "data": {
+          "type": "object",
+          "required": [
+            "type"
+          ],
+          "properties": {
+            "type": {
+              "const": "password_reset"
+            }
+          }
+        }
+      }
+    },
     "ServerTypingEvent": {
       "title": "ServerTypingEvent",
       "description": "A user started or stopped typing.",
@@ -2756,6 +2907,9 @@
         {
           "$ref": "#/$defs/ServerReadEvent"
         },
+        {
+          "$ref": "#/$defs/ServerSecurityNoticeEvent"
+        },
         {
           "$ref": "#/$defs/ServerTypingEvent"
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myronsi/messenger-api",
-  "version": "2.0.0-alpha.8",
+  "version": "2.1.0-alpha.1",
   "description": "API contract of the Messenger backend: OpenAPI document, WebSocket event schemas and generated TypeScript types",
   "license": "MIT",
   "repository": {