@myronsi/messenger-api 2.0.0-alpha.1.next.29 → 2.0.0-alpha.2

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 Contract changes only. The backend changelog is `CHANGELOG.md` in the repository root. Rules: `docs/api-compatibility.md`.
 
+## 2.0.0-alpha.2
+
+Authentication details found while implementing the Go backend:
+
+- Session IDs (`Session.id`, `session_id` path parameter) are UUIDs (`format: uuid`) instead of decimal IDs.
+- `code` of `POST /auth/login/2fa` and `POST /me/2fa/disable` accepts an authenticator code or a recovery code.
+- `POST /me/2fa/confirm` answers `200` with `recovery_codes` (shown once) instead of `204`.
+- `POST /me/password` can answer `403` (wrong current password); `POST /me/2fa/confirm` and `/me/2fa/disable` can answer `409`.
+- The refresh cookie is scoped to `/api/v2/auth/refresh`.
+
 ## 2.0.0-alpha.1
 
 First draft of API contract v2 for the Go backend (`/api/v2`), published as `@myronsi/messenger-api@2.0.0-alpha.1`:

package/README.md

@@ -15,7 +15,7 @@ api/
    ├─ ws-events.d.ts     WebSocket event types (from the JSON Schemas)
    ├─ ws-events.schema.json  bundled JSON Schemas (used by the breaking-change check)
    ├─ ws-docs.json       websocket.md and the examples (used by the PATCH check)
-   └─ index.js           export const API_VERSION = "2.0.0-alpha.1"
+   └─ index.js           export const API_VERSION = "2.0.0-alpha.2"
 ```
 
 ## Use in the frontend
@@ -45,14 +45,13 @@ Change the contract first, in the same PR as the code that implements it. Bump `
 
 ## Go server
 
-The Go server code is generated from `openapi.yaml` with [oapi-codegen](https://github.com/oapi-codegen/oapi-codegen) (strict server) in the same PR as a contract change. The configuration is `oapi-codegen.yaml`; the generator was verified with oapi-codegen v2.8.0 (Go 1.25) against this document. Add this directive to the Go module and commit the generated file:
+The Go server code is generated from `openapi.yaml` with [oapi-codegen](https://github.com/oapi-codegen/oapi-codegen) (strict server) in the same PR as a contract change. The configuration is `oapi-codegen.yaml`, the output is `internal/httpapi/api.gen.go`, and the `go:generate` directive lives in `internal/httpapi/generate.go`:
 
-```go
-//go:generate go run github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@v2.8.0 -config api/oapi-codegen.yaml api/openapi.yaml
+```sh
+make generate   # go generate ./...
 ```
 
-As soon as the repository has a `go.mod`, CI runs `go generate ./... && git diff --exit-code`.
-
+When an operation is added to the contract, the build fails until it is added to `internal/httpapi/unimplemented.go` (which answers 501) or to a real implementation. CI runs `go generate ./... && git diff --exit-code`, so a stale generated file fails the build.
 ## Publishing
 
 See `docs/releasing.md`: `next` on every merge to `master` that changes `api/`, the stable version after a backend release when `info.version` is not on npm yet. Both use `npm publish` with Trusted Publishing, which also attaches provenance.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-/* Generated from api/openapi.yaml 2.0.0-alpha.1. Do not edit. */
-export declare const API_VERSION: "2.0.0-alpha.1";
+/* Generated from api/openapi.yaml 2.0.0-alpha.2. Do not edit. */
+export declare const API_VERSION: "2.0.0-alpha.2";
 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.1";
+export const API_VERSION = "2.0.0-alpha.2";

package/dist/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: Messenger API
-  version: 2.0.0-alpha.1
+  version: 2.0.0-alpha.2
   summary: REST contract of the Messenger backend (v2).
   description: |
     Contract for the Go backend. The WebSocket protocol is described in `websocket/` and
@@ -356,7 +356,7 @@ paths:
       tags: [me]
       operationId: changePassword
       summary: Change the password
-      description: Revokes all other sessions.
+      description: "Revokes all other sessions. A wrong current password answers `403` with `code: invalid_credentials`."
       requestBody:
         required: true
         content:
@@ -368,6 +368,7 @@ paths:
           description: Password changed
         "400": { $ref: "#/components/responses/BadRequest" }
         "401": { $ref: "#/components/responses/Unauthorized" }
+        "403": { $ref: "#/components/responses/Forbidden" }
         "422": { $ref: "#/components/responses/ValidationFailed" }
         "429": { $ref: "#/components/responses/TooManyRequests" }
   /me/security:
@@ -463,7 +464,7 @@ paths:
       tags: [me]
       operationId: setupTwoFactor
       summary: Start two-factor setup
-      description: Returns the secret and an `otpauth://` URI; two-factor stays off until confirmed.
+      description: "Returns the secret and an `otpauth://` URI; two-factor stays off until confirmed. A wrong password answers `403` with `code: invalid_credentials`; `409` when two-factor is already on."
       requestBody:
         required: true
         content:
@@ -488,6 +489,7 @@ paths:
       tags: [me]
       operationId: confirmTwoFactor
       summary: Turn two-factor on with a code
+      description: "Returns the recovery codes. They are shown only once, so store them safely."
       requestBody:
         required: true
         content:
@@ -495,10 +497,14 @@ paths:
             schema: { $ref: "#/components/schemas/TwoFactorCode" }
       responses:
         "426": { $ref: "#/components/responses/ClientOutdated" }
-        "204":
+        "200":
           description: Two-factor authentication enabled
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/TwoFactorRecoveryCodes" }
         "400": { $ref: "#/components/responses/BadRequest" }
         "401": { $ref: "#/components/responses/Unauthorized" }
+        "409": { $ref: "#/components/responses/Conflict" }
         "429": { $ref: "#/components/responses/TooManyRequests" }
   /me/2fa/disable:
     parameters:
@@ -508,6 +514,7 @@ paths:
       tags: [me]
       operationId: disableTwoFactor
       summary: Turn two-factor off
+      description: "A wrong password or code answers `403` (`invalid_credentials` or `invalid_two_factor_code`); `409` when two-factor is off."
       requestBody:
         required: true
         content:
@@ -520,6 +527,7 @@ paths:
         "400": { $ref: "#/components/responses/BadRequest" }
         "401": { $ref: "#/components/responses/Unauthorized" }
         "403": { $ref: "#/components/responses/Forbidden" }
+        "409": { $ref: "#/components/responses/Conflict" }
         "429": { $ref: "#/components/responses/TooManyRequests" }
   /me/privacy:
     parameters:
@@ -1512,7 +1520,7 @@ components:
 
   headers:
     RefreshCookie:
-      description: HttpOnly, Secure, SameSite refresh cookie scoped to `/api/v2/auth`. Login and refresh set it; logout clears it (expired cookie).
+      description: HttpOnly, Secure, SameSite refresh cookie scoped to `/api/v2/auth/refresh`, so the browser sends it only to the refresh endpoint. Login and refresh set it; logout clears it (expired cookie).
       schema: { type: string }
 
   parameters:
@@ -1555,7 +1563,7 @@ components:
       name: session_id
       in: path
       required: true
-      schema: { $ref: "#/components/schemas/Id" }
+      schema: { type: string, format: uuid }
 
     ClientVersion:
       name: X-Client-Version
@@ -1734,7 +1742,10 @@ components:
       required: [login_challenge, code]
       properties:
         login_challenge: { type: string }
-        code: { type: string, pattern: "^[0-9]{6}$" }
+        code:
+          type: string
+          pattern: "^([0-9]{6}|[0-9A-Fa-f]{8}-[0-9A-Fa-f]{8})$"
+          description: A code of the authenticator app, or an unused recovery code.
     TokenResponse:
       type: object
       required: [access_token, token_type, expires_in]
@@ -1829,7 +1840,7 @@ components:
       type: object
       required: [id, created_at, last_used_at, is_current]
       properties:
-        id: { $ref: "#/components/schemas/Id" }
+        id: { type: string, format: uuid }
         device:
           type: [string, "null"]
           description: Sanitised user agent
@@ -1848,12 +1859,23 @@ components:
       required: [code]
       properties:
         code: { type: string, pattern: "^[0-9]{6}$" }
+    TwoFactorRecoveryCodes:
+      type: object
+      required: [recovery_codes]
+      properties:
+        recovery_codes:
+          type: array
+          items: { type: string }
+          description: One-time codes for signing in without the authenticator app. Shown only once.
     DisableTwoFactorRequest:
       type: object
       required: [password, code]
       properties:
         password: { type: string, maxLength: 128, writeOnly: true }
-        code: { type: string, pattern: "^[0-9]{6}$" }
+        code:
+          type: string
+          pattern: "^([0-9]{6}|[0-9A-Fa-f]{8}-[0-9A-Fa-f]{8})$"
+          description: A code of the authenticator app, or an unused recovery code.
     Visibility:
       type: string
       description: Who may see the item. `*_except` scopes use the exception lists.

package/dist/schema.d.ts

@@ -1,4 +1,4 @@
-/* Generated from api/openapi.yaml 2.0.0-alpha.1. Do not edit. */
+/* Generated from api/openapi.yaml 2.0.0-alpha.2. Do not edit. */
 export interface paths {
     "/meta": {
         parameters: {
@@ -276,7 +276,7 @@ export interface paths {
         get?: never;
         /**
          * Change the password
-         * @description Revokes all other sessions.
+         * @description Revokes all other sessions. A wrong current password answers `403` with `code: invalid_credentials`.
          */
         put: operations["changePassword"];
         post?: never;
@@ -372,7 +372,7 @@ export interface paths {
         put?: never;
         /**
          * Start two-factor setup
-         * @description Returns the secret and an `otpauth://` URI; two-factor stays off until confirmed.
+         * @description Returns the secret and an `otpauth://` URI; two-factor stays off until confirmed. A wrong password answers `403` with `code: invalid_credentials`; `409` when two-factor is already on.
          */
         post: operations["setupTwoFactor"];
         delete?: never;
@@ -395,7 +395,10 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /** Turn two-factor on with a code */
+        /**
+         * Turn two-factor on with a code
+         * @description Returns the recovery codes. They are shown only once, so store them safely.
+         */
         post: operations["confirmTwoFactor"];
         delete?: never;
         options?: never;
@@ -417,7 +420,10 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /** Turn two-factor off */
+        /**
+         * Turn two-factor off
+         * @description A wrong password or code answers `403` (`invalid_credentials` or `invalid_two_factor_code`); `409` when two-factor is off.
+         */
         post: operations["disableTwoFactor"];
         delete?: never;
         options?: never;
@@ -1286,6 +1292,7 @@ export interface components {
         };
         TwoFactorLoginRequest: {
             login_challenge: string;
+            /** @description A code of the authenticator app, or an unused recovery code. */
             code: string;
         };
         TokenResponse: {
@@ -1344,7 +1351,8 @@ export interface components {
             session_duration_days: number;
         };
         Session: {
-            id: components["schemas"]["Id"];
+            /** Format: uuid */
+            id: string;
             /** @description Sanitised user agent */
             device?: string | null;
             created_at: components["schemas"]["Timestamp"];
@@ -1359,8 +1367,13 @@ export interface components {
         TwoFactorCode: {
             code: string;
         };
+        TwoFactorRecoveryCodes: {
+            /** @description One-time codes for signing in without the authenticator app. Shown only once. */
+            recovery_codes: string[];
+        };
         DisableTwoFactorRequest: {
             password: string;
+            /** @description A code of the authenticator app, or an unused recovery code. */
             code: string;
         };
         /**
@@ -1717,7 +1730,7 @@ export interface components {
         UserId: components["schemas"]["Id"];
         RequestId: components["schemas"]["Id"];
         AttachmentId: components["schemas"]["Id"];
-        SessionId: components["schemas"]["Id"];
+        SessionId: string;
         /** @description Version of the client app, for logs and the per-client metric. */
         ClientVersion: string;
         /** @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`). */
@@ -1725,7 +1738,7 @@ export interface components {
     };
     requestBodies: never;
     headers: {
-        /** @description HttpOnly, Secure, SameSite refresh cookie scoped to `/api/v2/auth`. Login and refresh set it; logout clears it (expired cookie). */
+        /** @description HttpOnly, Secure, SameSite refresh cookie scoped to `/api/v2/auth/refresh`, so the browser sends it only to the refresh endpoint. Login and refresh set it; logout clears it (expired cookie). */
         RefreshCookie: string;
     };
     pathItems: never;
@@ -2161,6 +2174,7 @@ export interface operations {
             };
             400: components["responses"]["BadRequest"];
             401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
             422: components["responses"]["ValidationFailed"];
             426: components["responses"]["ClientOutdated"];
             429: components["responses"]["TooManyRequests"];
@@ -2365,14 +2379,17 @@ export interface operations {
         };
         responses: {
             /** @description Two-factor authentication enabled */
-            204: {
+            200: {
                 headers: {
                     [name: string]: unknown;
                 };
-                content?: never;
+                content: {
+                    "application/json": components["schemas"]["TwoFactorRecoveryCodes"];
+                };
             };
             400: components["responses"]["BadRequest"];
             401: components["responses"]["Unauthorized"];
+            409: components["responses"]["Conflict"];
             426: components["responses"]["ClientOutdated"];
             429: components["responses"]["TooManyRequests"];
         };
@@ -2405,6 +2422,7 @@ export interface operations {
             400: components["responses"]["BadRequest"];
             401: components["responses"]["Unauthorized"];
             403: components["responses"]["Forbidden"];
+            409: components["responses"]["Conflict"];
             426: components["responses"]["ClientOutdated"];
             429: components["responses"]["TooManyRequests"];
         };

package/dist/ws-docs.json

@@ -334,7 +334,7 @@
       "event_id": "7217400317439950009",
       "chat_id": null,
       "data": {
-        "api_version": "2.0.0-alpha.1",
+        "api_version": "2.0.0-alpha.2",
         "min_client_api_version": "2.0.0-alpha.1",
         "user_id": "1001"
       }

package/dist/ws-events.d.ts

@@ -1,4 +1,4 @@
-/* Generated from api/openapi.yaml 2.0.0-alpha.1. Do not edit. */
+/* Generated from api/openapi.yaml 2.0.0-alpha.2. Do not edit. */
 
 /**
  * Any WebSocket event, in either direction.

package/dist/ws-events.schema.json

@@ -214,7 +214,8 @@
         },
         "code": {
           "type": "string",
-          "pattern": "^[0-9]{6}$"
+          "pattern": "^([0-9]{6}|[0-9A-Fa-f]{8}-[0-9A-Fa-f]{8})$",
+          "description": "A code of the authenticator app, or an unused recovery code."
         }
       }
     },
@@ -450,7 +451,8 @@
       ],
       "properties": {
         "id": {
-          "$ref": "#/$defs/Id"
+          "type": "string",
+          "format": "uuid"
         },
         "device": {
           "type": [
@@ -500,6 +502,21 @@
         }
       }
     },
+    "TwoFactorRecoveryCodes": {
+      "type": "object",
+      "required": [
+        "recovery_codes"
+      ],
+      "properties": {
+        "recovery_codes": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "One-time codes for signing in without the authenticator app. Shown only once."
+        }
+      }
+    },
     "DisableTwoFactorRequest": {
       "type": "object",
       "required": [
@@ -514,7 +531,8 @@
         },
         "code": {
           "type": "string",
-          "pattern": "^[0-9]{6}$"
+          "pattern": "^([0-9]{6}|[0-9A-Fa-f]{8}-[0-9A-Fa-f]{8})$",
+          "description": "A code of the authenticator app, or an unused recovery code."
         }
       }
     },

package/package.json

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