@myronsi/messenger-api 2.1.0-alpha.15 → 2.1.0-alpha.16.next.89

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 Contract changes only. The backend changelog is `CHANGELOG.md` in the repository root. Rules: `docs/api-compatibility.md`.
 
+## 2.1.0-alpha.16
+
+- Trusted-device recovery no longer needs the current password. `DeviceRecoveryApproval.password` is no longer
+  required, is deprecated and ignored. New optional `passkey` (`PasskeyVerification`).
+- `POST /auth/recovery-requests/{requestId}/approve/options` (`DeviceRecoveryApprovalOptions`: `method` `passkey`
+  with `challenge_id` and `public_key`, or `session` with `approvable_from` while the session is too new).
+- New error codes `user_verification_required` (account has passkeys, no assertion sent) and `session_too_new`
+  (no passkeys and the session is younger than the minimum session age), both `403` on the approval.
+
 ## 2.1.0-alpha.15
 
 - End-to-end encrypted audio calls in direct chats and groups (tag `calls`, see `docs/calls.md` and

package/dist/index.d.ts

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

package/dist/index.js

@@ -1 +1 @@
-export const API_VERSION = "2.1.0-alpha.15";
+export const API_VERSION = "2.1.0-alpha.16";

package/dist/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: Messenger API
-  version: 2.1.0-alpha.15
+  version: 2.1.0-alpha.16
   summary: REST contract of the Messenger backend (v2).
   description: |
     Contract for the Go backend. The WebSocket protocol is described in `websocket/` and
@@ -2172,7 +2172,22 @@ paths:
       tags:
         - auth
       operationId: approveDeviceRecovery
-      summary: Approve a recovery request using number matching, the password and the second factor
+      summary: Approve a recovery request using number matching, user verification and the second factor
+      description: |
+        Approval does not need the current password, which the user may have forgotten. The checks run in this
+        order: the request must belong to the caller and `match_number` must match (a wrong number denies the
+        request), then user verification, then the second factor.
+
+        User verification follows `POST /auth/recovery-requests/{requestId}/approve/options`. When the account
+        has passkeys, `passkey` must carry an assertion with user verification for the challenge from that call
+        (`403 user_verification_required` without it, `403 invalid_credentials` for a failed assertion,
+        `400 invalid_request` for an unknown, used or expired challenge). A missing `code` answers
+        `401 two_factor_required` before the challenge is used, so the request can be repeated with the same
+        assertion and the code. A wrong code is checked after the passkey and uses up the challenge.
+        Without passkeys the approving session must be at least as old as the minimum session age
+        (`RECOVERY_APPROVAL_MIN_SESSION_AGE`, 72 hours by default), otherwise `403 session_too_new`.
+
+        `password` is ignored and only accepted so that older clients keep working.
       requestBody:
         required: true
         content:
@@ -2201,6 +2216,41 @@ paths:
           $ref: "#/components/responses/ClientOutdated"
         "429":
           $ref: "#/components/responses/TooManyRequests"
+  /auth/recovery-requests/{requestId}/approve/options:
+    parameters:
+      - *a1
+      - *a2
+      - *a4
+    post:
+      tags:
+        - auth
+      operationId: deviceRecoveryApprovalOptions
+      summary: Tell the approving device how to verify its user
+      description: |
+        `method: passkey` when the account has passkeys: `challenge_id` and `public_key` (WebAuthn request
+        options with `userVerification: required`) are for `navigator.credentials.get`, and the result goes to
+        the approval as `passkey`. The challenge is bound to this session and request, is single use and expires
+        after 5 minutes or with the request. `method: session` otherwise; `approvable_from` is set while the
+        session is younger than the minimum session age and tells when it may approve.
+      responses:
+        "200":
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DeviceRecoveryApprovalOptions"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "426":
+          $ref: "#/components/responses/ClientOutdated"
+        "429":
+          $ref: "#/components/responses/TooManyRequests"
   /auth/recovery-requests/{requestId}/deny:
     parameters:
       - *a1
@@ -4020,6 +4070,8 @@ components:
         - invalid_client_version
         - blocked_by_user
         - approval_required
+        - user_verification_required
+        - session_too_new
         - calls_unavailable
         - calls_not_allowed
         - call_identity_required
@@ -4933,18 +4985,42 @@ components:
       type: object
       required:
         - match_number
-        - password
       properties:
         match_number:
           type: integer
           minimum: 10
           maximum: 99
+        passkey:
+          $ref: "#/components/schemas/PasskeyVerification"
+        code:
+          type: string
+          maxLength: 128
         password:
           type: string
           maxLength: 1024
-        code:
+          deprecated: true
+          description: Ignored. Older clients still send it.
+    DeviceRecoveryApprovalOptions:
+      type: object
+      required:
+        - method
+      properties:
+        method:
+          type: string
+          enum: [passkey, session]
+        challenge_id:
           type: string
+          minLength: 32
           maxLength: 128
+          description: "Present with `method: passkey`."
+        public_key:
+          type: object
+          additionalProperties: true
+          description: "WebAuthn request options, present with `method: passkey`."
+        approvable_from:
+          type: string
+          format: date-time
+          description: "Present with `method: session` while the session is too new to approve."
     DeviceRecoveryComplete:
       type: object
       required:

package/dist/schema.d.ts

@@ -1,4 +1,4 @@
-/* Generated from api/openapi.yaml 2.1.0-alpha.15. Do not edit. */
+/* Generated from api/openapi.yaml 2.1.0-alpha.16. Do not edit. */
 export interface paths {
     "/meta": {
         parameters: {
@@ -1687,7 +1687,23 @@ export interface paths {
         };
         get?: never;
         put?: never;
-        /** Approve a recovery request using number matching, the password and the second factor */
+        /**
+         * Approve a recovery request using number matching, user verification and the second factor
+         * @description Approval does not need the current password, which the user may have forgotten. The checks run in this
+         *     order: the request must belong to the caller and `match_number` must match (a wrong number denies the
+         *     request), then user verification, then the second factor.
+         *
+         *     User verification follows `POST /auth/recovery-requests/{requestId}/approve/options`. When the account
+         *     has passkeys, `passkey` must carry an assertion with user verification for the challenge from that call
+         *     (`403 user_verification_required` without it, `403 invalid_credentials` for a failed assertion,
+         *     `400 invalid_request` for an unknown, used or expired challenge). A missing `code` answers
+         *     `401 two_factor_required` before the challenge is used, so the request can be repeated with the same
+         *     assertion and the code. A wrong code is checked after the passkey and uses up the challenge.
+         *     Without passkeys the approving session must be at least as old as the minimum session age
+         *     (`RECOVERY_APPROVAL_MIN_SESSION_AGE`, 72 hours by default), otherwise `403 session_too_new`.
+         *
+         *     `password` is ignored and only accepted so that older clients keep working.
+         */
         post: operations["approveDeviceRecovery"];
         delete?: never;
         options?: never;
@@ -1695,6 +1711,38 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/auth/recovery-requests/{requestId}/approve/options": {
+        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: {
+                /** @description Approval handle from the recovery_request event. It is different from the requester's capability and cannot poll or complete the request. */
+                requestId: string;
+            };
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Tell the approving device how to verify its user
+         * @description `method: passkey` when the account has passkeys: `challenge_id` and `public_key` (WebAuthn request
+         *     options with `userVerification: required`) are for `navigator.credentials.get`, and the result goes to
+         *     the approval as `passkey`. The challenge is bound to this session and request, is single use and expires
+         *     after 5 minutes or with the request. `method: session` otherwise; `approvable_from` is set while the
+         *     session is younger than the minimum session age and tells when it may approve.
+         */
+        post: operations["deviceRecoveryApprovalOptions"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/auth/recovery-requests/{requestId}/deny": {
         parameters: {
             query?: never;
@@ -2549,7 +2597,7 @@ export interface components {
          *     codes must be treated like `internal_error`.
          * @enum {string}
          */
-        ErrorCode: "invalid_request" | "validation_failed" | "unauthenticated" | "invalid_credentials" | "two_factor_required" | "invalid_two_factor_code" | "token_expired" | "forbidden" | "not_found" | "conflict" | "already_exists" | "payload_too_large" | "unsupported_media_type" | "rate_limited" | "client_outdated" | "invalid_client_version" | "blocked_by_user" | "approval_required" | "calls_unavailable" | "calls_not_allowed" | "call_identity_required" | "call_full" | "call_ended" | "already_in_call" | "stale_epoch" | "internal_error";
+        ErrorCode: "invalid_request" | "validation_failed" | "unauthenticated" | "invalid_credentials" | "two_factor_required" | "invalid_two_factor_code" | "token_expired" | "forbidden" | "not_found" | "conflict" | "already_exists" | "payload_too_large" | "unsupported_media_type" | "rate_limited" | "client_outdated" | "invalid_client_version" | "blocked_by_user" | "approval_required" | "user_verification_required" | "session_too_new" | "calls_unavailable" | "calls_not_allowed" | "call_identity_required" | "call_full" | "call_ended" | "already_in_call" | "stale_epoch" | "internal_error";
         /** @description RFC 9457 problem details. `426 Upgrade Required` (`client_outdated`) uses the same format. */
         Problem: {
             /**
@@ -3064,8 +3112,28 @@ export interface components {
         };
         DeviceRecoveryApproval: {
             match_number: number;
-            password: string;
+            passkey?: components["schemas"]["PasskeyVerification"];
             code?: string;
+            /**
+             * @deprecated
+             * @description Ignored. Older clients still send it.
+             */
+            password?: string;
+        };
+        DeviceRecoveryApprovalOptions: {
+            /** @enum {string} */
+            method: "passkey" | "session";
+            /** @description Present with `method: passkey`. */
+            challenge_id?: string;
+            /** @description WebAuthn request options, present with `method: passkey`. */
+            public_key?: {
+                [key: string]: unknown;
+            };
+            /**
+             * Format: date-time
+             * @description Present with `method: session` while the session is too new to approve.
+             */
+            approvable_from?: string;
         };
         DeviceRecoveryComplete: {
             new_password: string;
@@ -6365,6 +6433,40 @@ export interface operations {
             429: components["responses"]["TooManyRequests"];
         };
     };
+    deviceRecoveryApprovalOptions: {
+        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: {
+                /** @description Approval handle from the recovery_request event. It is different from the requester's capability and cannot poll or complete the request. */
+                requestId: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Success */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["DeviceRecoveryApprovalOptions"];
+                };
+            };
+            400: components["responses"]["BadRequest"];
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            426: components["responses"]["ClientOutdated"];
+            429: components["responses"]["TooManyRequests"];
+        };
+    };
     denyDeviceRecovery: {
         parameters: {
             query?: never;

package/dist/ws-events.d.ts

@@ -1,4 +1,4 @@
-/* Generated from api/openapi.yaml 2.1.0-alpha.15. Do not edit. */
+/* Generated from api/openapi.yaml 2.1.0-alpha.16. Do not edit. */
 
 /**
  * Any WebSocket event, in either direction.
@@ -111,6 +111,8 @@ export type ErrorCode =
   | "invalid_client_version"
   | "blocked_by_user"
   | "approval_required"
+  | "user_verification_required"
+  | "session_too_new"
   | "calls_unavailable"
   | "calls_not_allowed"
   | "call_identity_required"

package/dist/ws-events.schema.json

@@ -202,6 +202,8 @@
         "invalid_client_version",
         "blocked_by_user",
         "approval_required",
+        "user_verification_required",
+        "session_too_new",
         "calls_unavailable",
         "calls_not_allowed",
         "call_identity_required",
@@ -2299,8 +2301,7 @@
     "DeviceRecoveryApproval": {
       "type": "object",
       "required": [
-        "match_number",
-        "password"
+        "match_number"
       ],
       "properties": {
         "match_number": {
@@ -2308,13 +2309,49 @@
           "minimum": 10,
           "maximum": 99
         },
-        "password": {
-          "type": "string",
-          "maxLength": 1024
+        "passkey": {
+          "$ref": "#/$defs/PasskeyVerification"
         },
         "code": {
           "type": "string",
           "maxLength": 128
+        },
+        "password": {
+          "type": "string",
+          "maxLength": 1024,
+          "deprecated": true,
+          "description": "Ignored. Older clients still send it."
+        }
+      }
+    },
+    "DeviceRecoveryApprovalOptions": {
+      "type": "object",
+      "required": [
+        "method"
+      ],
+      "properties": {
+        "method": {
+          "type": "string",
+          "enum": [
+            "passkey",
+            "session"
+          ]
+        },
+        "challenge_id": {
+          "type": "string",
+          "minLength": 32,
+          "maxLength": 128,
+          "description": "Present with `method: passkey`."
+        },
+        "public_key": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "WebAuthn request options, present with `method: passkey`."
+        },
+        "approvable_from": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Present with `method: session` while the session is too new to approve."
         }
       }
     },

package/package.json

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