[core] 2026.7.1

[core] Up dashboard
[core] Up WEBJS
2026-07-15 20:04:29 +07:00 · 2026-07-15 20:04:29 +07:00 · 2026-07-15 20:04:29 +07:00 · 2026-07-15 20:04:29 +07:00 · 2026-07-15 20:04:29 +07:00 · 2026-07-15 20:04:29 +07:00
34 changed files with 1559 additions and 152 deletions
@@ -1,15 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(yarn build:*)",
-      "Bash(cat:*)",
-      "Bash(node:*)",
-      "Bash(npm show:*)",
-      "Bash(python3:*)",
-      "Bash(yarn test:unit:*)",
-      "Bash(npx tsc:*)",
-      "Bash(pre-commit run:*)",
-      "Bash(yarn test:*)"
-    ]
-  }
-}
@@ -44,8 +44,8 @@ up-webjs:
 	yarn up whatsapp-web.js@github:devlikeapro/whatsapp-web.js#fork-main-2026-06-26

 up-wpp:
-	yarn up @wppconnect-team/wppconnect
-	yarn up @wppconnect/wa-js
+	yarn up @wppconnect-team/wppconnect@github:wppconnect-team/wppconnect#master
+	yarn up @wppconnect/wa-js@github:wppconnect-team/wa-js#main

 up-rust-bridge:
 	yarn up -R whatsapp-rust-bridge
@@ -5,12 +5,12 @@
    "plugins": ["@nestjs/swagger"],
    "watchPathIgnorePatterns": ["node_modules", "src/dashboard", "dist"],
    "assets": [
-      "dashboard/**",
-      "core/engines/webjs/*",
-      "plus/engines/webjs/*",
-      "apps/chatwoot/i18n/locales/*.yaml",
-      "apps/chatwoot/i18n/locales/*.yml"
+      { "include": "dashboard/**", "watchAssets": false },
+      { "include": "core/engines/webjs/*", "watchAssets": true },
+      { "include": "plus/engines/webjs/*", "watchAssets": true },
+      { "include": "apps/chatwoot/i18n/locales/*.yaml", "watchAssets": true },
+      { "include": "apps/chatwoot/i18n/locales/*.yml", "watchAssets": true }
    ],
-    "watchAssets": true
+    "watchAssets": false
  }
 }
@@ -60,8 +60,8 @@
    "@types/passport": "^1.0.17",
    "@types/sqlite3": "^5.1.0",
    "@types/ws": "^8.5.4",
-    "@wppconnect-team/wppconnect": "^2.2.1",
-    "@wppconnect/wa-js": "^4.3.1",
+    "@wppconnect-team/wppconnect": "github:wppconnect-team/wppconnect#master",
+    "@wppconnect/wa-js": "github:wppconnect-team/wa-js#main",
    "adm-zip": "0.5.10",
    "agentkeepalive": "^4.5.0",
    "async-lock": "^1.4.1",
@@ -12,12 +12,16 @@ import {
 import { ApiOperation, ApiSecurity, ApiTags } from '@nestjs/swagger';
 import { SessionManager } from '@waha/core/abc/manager.abc';
 import { Action } from '@waha/core/auth/casl.types';
-import { CanServer } from '@waha/core/auth/policies';
+import { CanServer, CanSession, FromBody } from '@waha/core/auth/policies';
 import { CheckPolicies } from '@waha/core/auth/policies.decorator';
 import { PoliciesGuard } from '@waha/core/auth/policies.guard';
 import { ApiKeyService } from '@waha/core/services/ApiKeyService';
 import { WAHAValidationPipe } from '@waha/nestjs/pipes/WAHAValidationPipe';
-import { ApiKeyDTO, ApiKeyRequest } from '@waha/structures/apikeys.dto';
+import {
+  ApiKeyDTO,
+  ApiKeyRequest,
+  ScopedApiKeyRequest,
+} from '@waha/structures/apikeys.dto';

@ApiSecurity('api_key')
@Controller('api/keys')
@@ -44,6 +48,26 @@ export class ApiKeysController {
    return this.service.list();
  }

+  @Post('/media')
+  @ApiOperation({
+    summary: 'Create or get a media-download-only API key for a session',
+  })
+  @CheckPolicies(CanSession(Action.Read, FromBody('session')))
+  @UsePipes(new WAHAValidationPipe())
+  async media(@Body() body: ScopedApiKeyRequest): Promise<ApiKeyDTO> {
+    return this.service.createOrGetMediaKey(body.session);
+  }
+
+  @Post('/control')
+  @ApiOperation({
+    summary: 'Create or get a control-only API key for a session',
+  })
+  @CheckPolicies(CanSession(Action.Control, FromBody('session')))
+  @UsePipes(new WAHAValidationPipe())
+  async control(@Body() body: ScopedApiKeyRequest): Promise<ApiKeyDTO> {
+    return this.service.createOrGetControlKey(body.session);
+  }
+
  @Put('/:id')
  @ApiOperation({ summary: 'Update an API key' })
  @UsePipes(new WAHAValidationPipe())
@@ -7,7 +7,12 @@ import {
  UseInterceptors,
  UseGuards,
 } from '@nestjs/common';
-import { ApiOperation, ApiSecurity, ApiTags } from '@nestjs/swagger';
+import {
+  ApiOkResponse,
+  ApiOperation,
+  ApiSecurity,
+  ApiTags,
+} from '@nestjs/swagger';
 import { ApiFileAcceptHeader } from '@waha/nestjs/ApiFileAcceptHeader';
 import {
  QRCodeSessionParam,
@@ -19,6 +24,9 @@ import { SessionManager } from '../core/abc/manager.abc';
 import { WhatsappSession } from '../core/abc/session.abc';
 import { BufferResponseInterceptor } from '../nestjs/BufferResponseInterceptor';
 import {
+  PasskeyAssertionRequest,
+  PasskeyChallenge,
+  PasskeyConfirmationResponse,
  QRCodeFormat,
  QRCodeQuery,
  QRCodeValue,
@@ -68,6 +76,54 @@ class AuthController {
  ) {
    return session.requestCode(request.phoneNumber, request.method, request);
  }
+
+  @Get('passkey/challenge')
+  @SessionApiParam
+  @ApiOperation({
+    summary: 'Get the pending passkey (WebAuthn) challenge.',
+    description:
+      'Available while the session is in PASSKEY_REQUIRED status. ' +
+      'Pass the challenge to navigator.credentials.get({ publicKey: challenge }) ' +
+      'on the https://web.whatsapp.com origin.',
+  })
+  @ApiOkResponse({ type: PasskeyChallenge })
+  getPasskeyChallenge(@SessionParam session: WhatsappSession) {
+    return session.getPasskeyChallenge();
+  }
+
+  @Post('passkey')
+  @SessionApiParam
+  @ApiOperation({
+    summary: 'Submit a WebAuthn passkey assertion to finish pairing.',
+  })
+  submitPasskey(
+    @SessionParam session: WhatsappSession,
+    @Body() request: PasskeyAssertionRequest,
+  ) {
+    return session.sendPasskeyResponse(JSON.stringify(request));
+  }
+
+  @Get('passkey/confirmation')
+  @SessionApiParam
+  @ApiOperation({
+    summary: 'Get the pending passkey confirmation code.',
+    description:
+      'Available while the session is in PASSKEY_CONFIRMATION_REQUIRED status. ' +
+      'Most pairings skip this step - WhatsApp confirms them right after the assertion.',
+  })
+  @ApiOkResponse({ type: PasskeyConfirmationResponse })
+  getPasskeyConfirmation(@SessionParam session: WhatsappSession) {
+    return session.getPasskeyConfirmation();
+  }
+
+  @Post('passkey/confirm')
+  @SessionApiParam
+  @ApiOperation({
+    summary: 'Confirm passkey pairing (only needed for the manual code case).',
+  })
+  confirmPasskey(@SessionParam session: WhatsappSession) {
+    return session.confirmPasskey();
+  }
 }

 export { AuthController };
@@ -31,4 +31,28 @@ export class McpController {
    });
    return ImageMcpResponse(Buffer.from(response.data));
  }
+
+  protected async scopedApiKey(
+    url: string,
+    session: string,
+  ): Promise<string | null> {
+    const response = await this.request({
+      method: 'POST',
+      url: url,
+      data: { session: session },
+    });
+    if (response.status >= 200 && response.status < 300) {
+      return response.data?.key ?? null;
+    }
+    // e.g. 403 (caller lacks the scope) or 422 (session missing) → fall back
+    return null;
+  }
+
+  protected async mediaApiKey(session: string): Promise<string | null> {
+    return this.scopedApiKey('/api/keys/media', session);
+  }
+
+  protected async controlApiKey(session: string): Promise<string | null> {
+    return this.scopedApiKey('/api/keys/control', session);
+  }
 }
@@ -19,6 +19,7 @@ import { PresenceTools } from '@waha/apps/mcp/tools/presence.tools';
 import { ProfileTools } from '@waha/apps/mcp/tools/profile.tools';
 import { StatusTools } from '@waha/apps/mcp/tools/status.tools';
 import { ServerTools } from '@waha/apps/mcp/tools/server.tools';
+import { KeysTools } from '@waha/apps/mcp/tools/keys.tools';

@Injectable()
 export class McpService {
@@ -42,6 +43,7 @@ export class McpService {
      new ProfileTools(api),
      new StatusTools(api),
      new ServerTools(api),
+      new KeysTools(api),
    ]);
    const transport = new StreamableHTTPServerTransport({
      sessionIdGenerator: undefined, // stateless
@@ -3,17 +3,24 @@ import { WAHASelf } from '@waha/apps/app_sdk/waha/WAHASelf';
 import { McpController } from '@waha/apps/mcp/decorators/controller';
 import { Tool } from '@waha/apps/mcp/decorators/tool';
 import {
+  AuthPasskeyChallengeInput,
+  AuthPasskeyConfirmationInput,
+  AuthPasskeyConfirmInput,
+  AuthPasskeySubmitInput,
  AuthQRInput,
  AuthRequestCodeInput,
  ScreenshotInput,
 } from '@waha/apps/mcp/tools/auth.zod';

-function AuthContent(key: string): any {
+function AuthContent(key: string | null): any {
+  const open = key
+    ? `add "?x-api-key=${key}" to the query params (this is a control-only key scoped to this session)`
+    : `append "?x-api-key=YOUR_API_KEY" to the query params, using the key you already have`;
  return {
    type: 'text' as const,
    text: `
 You can either ask the user to scan a QR code or provide a phone number and call auth-request-code. auth-request-code is preferable, so ask for the phone number and pass it in international format without +.
-If the user wants to open the QR code or screenshot in a browser, add "?x-api-key=${key}" to the query params.
+If the user wants to open the QR code or screenshot in a browser, ${open}.
 `,
  };
 }
@@ -39,7 +46,8 @@ export class AuthTools extends McpController {
  })
  async authQR({ session }: z.infer<typeof AuthQRInput>) {
    const result = await this.imageRequest(`/api/${session}/auth/qr`);
-    result.content.push(AuthContent(this.api.key));
+    const key = await this.controlApiKey(session);
+    result.content.push(AuthContent(key));
    return result;
  }

@@ -58,7 +66,8 @@ export class AuthTools extends McpController {
    const result = await this.imageRequest(
      `/api/screenshot?session=${session}`,
    );
-    result.content.push(AuthContent(this.api.key));
+    const key = await this.controlApiKey(session);
+    result.content.push(AuthContent(key));
    return result;
  }

@@ -94,4 +103,95 @@ export class AuthTools extends McpController {
    });
    return result;
  }
+
+  @Tool('auth-passkey-challenge', {
+    title: 'Get passkey challenge',
+    description:
+      'Get the pending passkey (WebAuthn) challenge for a session in PASSKEY_REQUIRED status. ' +
+      'Fails with 422 when nothing is pending. ' +
+      'You cannot sign the challenge yourself - the assertion has to be produced by an authenticator ' +
+      'on the https://web.whatsapp.com origin (the WAHA browser extension, or the DevTools fallback). ' +
+      'Hand the challenge to the user, then submit the result with auth-passkey-submit.',
+    inputSchema: AuthPasskeyChallengeInput,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+    },
+  })
+  async passkeyChallenge({
+    session,
+  }: z.infer<typeof AuthPasskeyChallengeInput>) {
+    return this.textRequest({
+      method: 'GET',
+      url: `/api/${session}/auth/passkey/challenge`,
+    });
+  }
+
+  @Tool('auth-passkey-submit', {
+    title: 'Submit passkey assertion',
+    description:
+      'Submit the WebAuthn assertion produced by navigator.credentials.get() to finish passkey pairing. ' +
+      'Get the challenge from auth-passkey-challenge first. ' +
+      'After this the session usually goes straight to WORKING; ' +
+      'if it goes to PASSKEY_CONFIRMATION_REQUIRED instead, follow up with auth-passkey-confirmation.',
+    inputSchema: AuthPasskeySubmitInput,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+    },
+  })
+  async passkeySubmit({
+    session,
+    ...body
+  }: z.infer<typeof AuthPasskeySubmitInput>) {
+    return this.textRequest({
+      method: 'POST',
+      url: `/api/${session}/auth/passkey`,
+      data: body,
+    });
+  }
+
+  @Tool('auth-passkey-confirmation', {
+    title: 'Get passkey confirmation code',
+    description:
+      'Get the pending passkey confirmation code for a session in PASSKEY_CONFIRMATION_REQUIRED status. ' +
+      'Fails with 422 when nothing is pending. ' +
+      'Show the code to the user, ask them to check it matches the one on their phone, ' +
+      'then call auth-passkey-confirm.',
+    inputSchema: AuthPasskeyConfirmationInput,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+    },
+  })
+  async passkeyConfirmation({
+    session,
+  }: z.infer<typeof AuthPasskeyConfirmationInput>) {
+    return this.textRequest({
+      method: 'GET',
+      url: `/api/${session}/auth/passkey/confirmation`,
+    });
+  }
+
+  @Tool('auth-passkey-confirm', {
+    title: 'Confirm passkey pairing',
+    description:
+      'Finish passkey pairing after the user confirmed the code matches the one shown on their phone. ' +
+      'Only call it once the user has verified the code from auth-passkey-confirmation.',
+    inputSchema: AuthPasskeyConfirmInput,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+    },
+  })
+  async passkeyConfirm({ session }: z.infer<typeof AuthPasskeyConfirmInput>) {
+    return this.textRequest({
+      method: 'POST',
+      url: `/api/${session}/auth/passkey/confirm`,
+    });
+  }
 }
@@ -1,6 +1,9 @@
 import { z } from 'zod';
 import { DtoToZod } from '@waha/apps/mcp/schemas/DtoToZod';
-import { RequestCodeRequest } from '@waha/structures/auth.dto';
+import {
+  PasskeyAssertionRequest,
+  RequestCodeRequest,
+} from '@waha/structures/auth.dto';

 export const AuthQRInput = z.object({
  session: z.string(),
@@ -13,3 +16,19 @@ export const ScreenshotInput = z.object({
 export const AuthRequestCodeInput = DtoToZod(RequestCodeRequest).extend({
  session: z.string(),
 });
+
+export const AuthPasskeyChallengeInput = z.object({
+  session: z.string(),
+});
+
+export const AuthPasskeyConfirmationInput = z.object({
+  session: z.string(),
+});
+
+export const AuthPasskeySubmitInput = DtoToZod(PasskeyAssertionRequest).extend({
+  session: z.string(),
+});
+
+export const AuthPasskeyConfirmInput = z.object({
+  session: z.string(),
+});
@@ -18,10 +18,22 @@ import {
  UnpinMessageInput,
 } from '@waha/apps/mcp/tools/chats.zod';

-function FetchMediaUsingApiKeyContent(key: string) {
+function FetchMediaContent(key: string | null) {
+  if (key) {
+    return {
+      type: 'text' as const,
+      text:
+        `To fetch media use "X-Api-Key: ${key}" HTTP header. ` +
+        `To open it in a browser add "?x-api-key=${key}" to the query params. ` +
+        `This is a media-only API key: it can ONLY download files for this session — ` +
+        `it cannot read messages, send, or control the session.`,
+    };
+  }
  return {
    type: 'text' as const,
-    text: `To fetch media use "X-Api-Key: ${key}" HTTP header. If the user wants to open it - add "?x-api-key=${key}" to query params`,
+    text:
+      `To fetch media, use your existing WAHA API key in the "X-Api-Key" HTTP header ` +
+      `(or append "?x-api-key=YOUR_API_KEY" to open it in a browser).`,
  };
 }

@@ -170,7 +182,8 @@ export class ChatTools extends McpController {
      JSON.stringify({ status: response.status, response: responseText }),
    );
    if (query.downloadMedia) {
-      result.content.push(FetchMediaUsingApiKeyContent(this.api.key));
+      const mediaKey = await this.mediaApiKey(session);
+      result.content.push(FetchMediaContent(mediaKey));
    }
    return result;
  }
@@ -219,7 +232,8 @@ export class ChatTools extends McpController {
      params: query,
    });
    if (query.downloadMedia) {
-      result.content.push(FetchMediaUsingApiKeyContent(this.api.key));
+      const mediaKey = await this.mediaApiKey(session);
+      result.content.push(FetchMediaContent(mediaKey));
    }
    return result;
  }
@@ -0,0 +1,44 @@
+import { z } from 'zod';
+import { WAHASelf } from '@waha/apps/app_sdk/waha/WAHASelf';
+import { McpController } from '@waha/apps/mcp/decorators/controller';
+import { Tool } from '@waha/apps/mcp/decorators/tool';
+import { TextMcpResponse } from '@waha/apps/mcp/responses';
+import { ScopedKeyInput } from '@waha/apps/mcp/tools/keys.zod';
+
+export class KeysTools extends McpController {
+  constructor(api: WAHASelf) {
+    super(api);
+  }
+
+  @Tool('keys-get-scoped-key', {
+    title: 'Get a scoped API key',
+    description:
+      'Create or get a minimal, scoped API key for a session. ' +
+      'Use "media" scope for a download-only key to fetch media files, ' +
+      'or "control" scope for a control-only key to open the QR code / screenshot in a browser. ' +
+      'The returned key is far weaker than your own key and is safe to hand to the user for that single purpose.',
+    inputSchema: ScopedKeyInput,
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+    },
+  })
+  async getScopedKey({ session, scope }: z.infer<typeof ScopedKeyInput>) {
+    let key: string | null = null;
+    if (scope === 'media') {
+      key = await this.mediaApiKey(session);
+    } else {
+      key = await this.controlApiKey(session);
+    }
+    if (!key) {
+      return TextMcpResponse(
+        JSON.stringify({
+          error:
+            'Could not mint a scoped API key. Check that the session exists and that your key has access to it.',
+        }),
+      );
+    }
+    return TextMcpResponse(JSON.stringify({ scope: scope, key: key }));
+  }
+}
@@ -0,0 +1,14 @@
+import { z } from 'zod';
+
+const SessionField = z.string().describe('Session name');
+
+export const ScopedKeyInput = z.object({
+  session: SessionField,
+  scope: z
+    .enum(['media', 'control'])
+    .describe(
+      'Scope of the key. ' +
+        '"media" — download-only key for fetching media files of the session. ' +
+        '"control" — control-only key to open QR code / screenshot in a browser.',
+    ),
+});
@@ -63,6 +63,10 @@ import {
 import { distinctUntilChanged, map } from 'rxjs/operators';
 import { MessageId } from 'whatsapp-web.js';

+import {
+  PasskeyChallenge,
+  PasskeyConfirmationResponse,
+} from '../../structures/auth.dto';
 import {
  ChatRequest,
  CheckNumberStatusQuery,
@@ -163,6 +167,19 @@ export interface SessionParams {
  ignore: IgnoreJidConfig;
 }

+/**
+ * A status change, along with the extra info that belongs to that status
+ * (if any) - like the passkey challenge for PASSKEY_REQUIRED.
+ */
+interface SessionStatusUpdate {
+  status: WAHASessionStatus;
+  data: any;
+}
+
+interface SessionStatusUpdatePoint extends SessionStatusUpdate {
+  timestamp: number;
+}
+
 export abstract class WhatsappSession {
  public engine: WAHAEngine;

@@ -178,6 +195,7 @@ export abstract class WhatsappSession {
  protected jids: JidFilter;

  private _status: WAHASessionStatus;
+  private _statusData: any = null;
  private _presence:
    | WAHAPresenceStatus.ONLINE
    | WAHAPresenceStatus.OFFLINE
@@ -190,7 +208,7 @@ export abstract class WhatsappSession {

  private shouldPrintQR: boolean;
  protected events2: DefaultMap<WAHAEvents, SwitchObservable<any>>;
-  private status$: Subject<WAHASessionStatus>;
+  private status$: Subject<SessionStatusUpdate>;
  protected profilePictures: NodeCache = new NodeCache({
    stdTTL: 24 * 60 * 60, // 1 day
  });
@@ -217,7 +235,7 @@ export abstract class WhatsappSession {
    ignore,
  }: SessionParams) {
    this._status = WAHASessionStatus.STOPPED;
-    this.status$ = new Subject<WAHASessionStatus>();
+    this.status$ = new Subject<SessionStatusUpdate>();

    this.name = name;
    this.proxyConfig = proxyConfig;
@@ -252,46 +270,55 @@ export abstract class WhatsappSession {
        // Wait for WORKING status to get all the info
        // https://github.com/devlikeapro/waha/issues/409
        .pipe(
-          switchMap((status: WAHASessionStatus) => {
+          switchMap((update: SessionStatusUpdate) => {
            const me = this.getSessionMeInfo();
            const hasMe = !!me?.pushName && !!me?.id;
            // Delay WORKING by 1 second if condition is met
            // Usually we get WORKING with all the info after
-            if (status === WAHASessionStatus.WORKING && !hasMe) {
-              return of(status).pipe(delay(2000));
+            if (update.status === WAHASessionStatus.WORKING && !hasMe) {
+              return of(update).pipe(delay(2000));
            }
-            return of(status);
+            return of(update);
          }),
          // Remove consecutive duplicate WORKING statuses
          distinctUntilChanged(
-            (prev, curr) => prev === curr && curr === WAHASessionStatus.WORKING,
+            (prev, curr) =>
+              prev.status === curr.status &&
+              curr.status === WAHASessionStatus.WORKING,
          ),
          // attach current time (ms)
          timestamp(),
          map(
            ({ value, timestamp }) =>
              ({
-                status: value,
+                status: value.status,
                timestamp: timestamp,
-              }) as SessionStatusPoint,
+                data: value.data,
+              }) as SessionStatusUpdatePoint,
          ),
          // keep the last 3 entries
-          scan<SessionStatusPoint, SessionStatusPoint[]>(
-            (statuses, status: SessionStatusPoint) => {
-              const next = [...statuses, status];
+          scan<SessionStatusUpdatePoint, SessionStatusUpdatePoint[]>(
+            (points, point: SessionStatusUpdatePoint) => {
+              const next = [...points, point];
              return next.length > 3 ? next.slice(-3) : next;
            },
            [],
          ),
          // shape final payload
-          map(
-            (statuses) =>
-              ({
-                name: this.name,
-                status: statuses.at(-1)?.status, // current
-                statuses: statuses,
-              }) as WASessionStatusBody,
-          ),
+          map((points) => {
+            const current = points.at(-1); // current
+            return {
+              name: this.name,
+              status: current?.status,
+              statuses: points.map(
+                (point): SessionStatusPoint => ({
+                  status: point.status,
+                  timestamp: point.timestamp,
+                }),
+              ),
+              data: current?.data ?? null,
+            } as WASessionStatusBody;
+          }),
        ),
    );

@@ -311,20 +338,34 @@ export abstract class WhatsappSession {
    return this.events2.get(event);
  }

-  public set status(value: WAHASessionStatus) {
-    if (this.unpairing && value !== WAHASessionStatus.STOPPED) {
+  /**
+   * Set the status along with the extra info that belongs to it.
+   * Plain 'status = value' assignments go through here without data,
+   * so the data is dropped as soon as the session moves on.
+   */
+  protected setStatus(status: WAHASessionStatus, data: any = null) {
+    if (this.unpairing && status !== WAHASessionStatus.STOPPED) {
      // In case of unpairing
      // wait for STOPPED event, ignore the rest
      return;
    }
-    this._status = value;
-    this.status$.next(value);
+    this._status = status;
+    this._statusData = data;
+    this.status$.next({ status: status, data: data });
+  }
+
+  public set status(value: WAHASessionStatus) {
+    this.setStatus(value);
  }

  public get status() {
    return this._status;
  }

+  public get statusData() {
+    return this._statusData;
+  }
+
  protected set presence(value: WAHAPresenceStatus) {
    switch (value) {
      case null:
@@ -450,6 +491,22 @@ export abstract class WhatsappSession {
    throw new NotImplementedByEngineError();
  }

+  public getPasskeyChallenge(): PasskeyChallenge {
+    throw new NotImplementedByEngineError();
+  }
+
+  public async sendPasskeyResponse(responseJson: string): Promise<void> {
+    throw new NotImplementedByEngineError();
+  }
+
+  public async confirmPasskey(): Promise<void> {
+    throw new NotImplementedByEngineError();
+  }
+
+  public getPasskeyConfirmation(): PasskeyConfirmationResponse {
+    throw new NotImplementedByEngineError();
+  }
+
  abstract getScreenshot(): Promise<Buffer>;

  public getSessionMeInfo(): MeInfo | null {
@@ -0,0 +1,167 @@
+import * as grpc from '@grpc/grpc-js';
+import {
+  GowsEventStreamObservable,
+  GowsStreamEndedError,
+} from '@waha/core/engines/gows/GowsEventStreamObservable';
+import { EventEmitter } from 'events';
+import { merge, Subject } from 'rxjs';
+import { retry } from 'rxjs/operators';
+
+/**
+ * Mimics grpc.ClientReadableStream.
+ * The important part is failWithStatus - it reproduces what grpc-js does in
+ * client.js makeServerStreamRequest.onReceiveStatus on a non OK status:
+ * push(null) schedules 'end' on the next tick, then 'error' is emitted
+ * synchronously in the current tick.
+ */
+class FakeStream extends EventEmitter {
+  public cancelled = false;
+
+  cancel() {
+    this.cancelled = true;
+  }
+
+  failWithStatus(err: any) {
+    process.nextTick(() => this.emit('end'));
+    this.emit('error', err);
+  }
+
+  endCleanly() {
+    process.nextTick(() => this.emit('end'));
+  }
+}
+
+class FakeClient {
+  public closed = false;
+
+  close() {
+    this.closed = true;
+  }
+}
+
+function buildLogger(): any {
+  function noop() {
+    return undefined;
+  }
+  return {
+    debug: noop,
+    info: noop,
+    warn: noop,
+    error: noop,
+    setBindings: noop,
+  };
+}
+
+function drainTicks(): Promise<void> {
+  return new Promise((resolve) => setImmediate(resolve));
+}
+
+function observe(stream: FakeStream, client: FakeClient) {
+  const observable = new GowsEventStreamObservable(buildLogger(), () => ({
+    client: client as any,
+    stream: stream as any,
+  }));
+  // Do not wait a real second for the client to close
+  observable.CLIENT_CLOSE_TIMEOUT = 0;
+
+  const next = jest.fn();
+  const error = jest.fn();
+  const complete = jest.fn();
+  const subscription = observable.subscribe({
+    next: next,
+    error: error,
+    complete: complete,
+  });
+  return {
+    next: next,
+    error: error,
+    complete: complete,
+    subscription: subscription,
+  };
+}
+
+describe('GowsEventStreamObservable', () => {
+  it('errors (not completes) when the stream fails with a non OK status', async () => {
+    const stream = new FakeStream();
+    const client = new FakeClient();
+    const { error, complete } = observe(stream, client);
+
+    const err = { code: grpc.status.UNAVAILABLE, message: 'unavailable' };
+    stream.failWithStatus(err);
+    await drainTicks();
+
+    expect(error).toHaveBeenCalledTimes(1);
+    expect(error).toHaveBeenCalledWith(err);
+    expect(complete).not.toHaveBeenCalled();
+    expect(stream.cancelled).toBe(true);
+    expect(client.closed).toBe(true);
+  });
+
+  it('errors (not completes) when the stream ends cleanly', async () => {
+    const stream = new FakeStream();
+    const client = new FakeClient();
+    const { error, complete } = observe(stream, client);
+
+    stream.endCleanly();
+    await drainTicks();
+
+    expect(error).toHaveBeenCalledTimes(1);
+    expect(error.mock.calls[0][0]).toBeInstanceOf(GowsStreamEndedError);
+    expect(complete).not.toHaveBeenCalled();
+  });
+
+  it('does not error when we cancel the stream ourselves', async () => {
+    const stream = new FakeStream();
+    const client = new FakeClient();
+    const { error, complete, subscription } = observe(stream, client);
+
+    subscription.unsubscribe();
+    stream.emit('error', { code: grpc.status.CANCELLED });
+    stream.emit('end');
+    await drainTicks();
+
+    expect(error).not.toHaveBeenCalled();
+    expect(complete).not.toHaveBeenCalled();
+    expect(stream.cancelled).toBe(true);
+    expect(client.closed).toBe(true);
+  });
+
+  it('reconnects via retry() when merged with a never ending subject', async () => {
+    const streams = [new FakeStream(), new FakeStream()];
+    const clients = [new FakeClient(), new FakeClient()];
+    let attempt = 0;
+
+    const observable = new GowsEventStreamObservable(buildLogger(), () => {
+      const index = attempt;
+      attempt += 1;
+      return { client: clients[index] as any, stream: streams[index] as any };
+    });
+    observable.CLIENT_CLOSE_TIMEOUT = 0;
+
+    const local$ = new Subject<any>();
+    const next = jest.fn();
+    const error = jest.fn();
+    const subscription = merge(observable, local$)
+      .pipe(retry({ delay: 1 }))
+      .subscribe({ next: next, error: error });
+
+    streams[0].failWithStatus({ code: grpc.status.INTERNAL });
+    await drainTicks();
+    await new Promise((resolve) => setTimeout(resolve, 20));
+
+    expect(attempt).toBe(2);
+    expect(error).not.toHaveBeenCalled();
+
+    streams[1].emit('data', {
+      toObject: () => ({ event: 'Message', data: '{"id":"1"}' }),
+    });
+    await drainTicks();
+
+    expect(next).toHaveBeenCalledTimes(1);
+    expect(next.mock.calls[0][0]).toEqual({
+      event: 'Message',
+      data: { id: '1' },
+    });
+    subscription.unsubscribe();
+  });
+});
@@ -1,14 +1,29 @@
 import * as grpc from '@grpc/grpc-js';
+import { rand } from '@waha/core/auth/config';
 import { messages } from '@waha/core/engines/gows/grpc/gows';
 import { EnginePayload } from '@waha/structures/webhooks.dto';
 import { sleep } from '@waha/utils/promiseTimeout';
 import { Logger } from 'pino';
 import { Observable } from 'rxjs';
-import { rand } from '@waha/core/auth/config';
+
+/**
+ * Raised when the gRPC stream ends without an error.
+ * The engine event stream is expected to live as long as the session,
+ * so a clean end still means we lost the events and have to reconnect.
+ */
+export class GowsStreamEndedError extends Error {
+  constructor() {
+    super('gRPC event stream ended');
+    this.name = 'GowsStreamEndedError';
+  }
+}

 /**
 * Observable that listens to a gRPC stream and emits EnginePayload objects.
 * Pass a factory function that returns a client and a stream.
+ *
+ * The observable always terminates with an error, never with a completion,
+ * so that an upstream retry() reconnects the stream.
 */
 export class GowsEventStreamObservable extends Observable<EnginePayload> {
  _client: grpc.Client;
@@ -26,63 +41,79 @@ export class GowsEventStreamObservable extends Observable<EnginePayload> {
      logger.setBindings({ id: rand() });
      const { client, stream } = factory();
      this._client = client;
+      const closeTimeout = this.CLIENT_CLOSE_TIMEOUT;

      let closed = false;
-      const cleanup = async (reason: string) => {
+      let terminated = false;
+      let tearingDown = false;
+
+      async function cleanup(reason: string) {
        if (closed) {
          return;
        }
        closed = true;

-        logger.debug({ reason }, 'Cancelling gRPC stream...');
+        logger.debug({ reason: reason }, 'Cancelling gRPC stream...');
        try {
          stream.cancel();
        } catch (err) {
-          logger.warn({ err }, 'Failed to cancel gRPC stream');
+          logger.warn({ err: err }, 'Failed to cancel gRPC stream');
        }

-        logger.debug({ reason }, 'Closing gRPC client...');
+        logger.debug({ reason: reason }, 'Closing gRPC client...');
        try {
          client.close();
        } catch (err) {
-          logger.warn({ err }, 'Failed to close gRPC client');
+          logger.warn({ err: err }, 'Failed to close gRPC client');
        }

-        await sleep(this.CLIENT_CLOSE_TIMEOUT);
-      };
+        await sleep(closeTimeout);
+      }
+
+      // Must run synchronously from the stream handlers.
+      // grpc-js calls stream.push(null) - which schedules 'end' on the next tick -
+      // and only then emits 'error' in the same tick. Erroring the subscriber
+      // right away wins that race, otherwise 'end' completes the observable
+      // and the upstream retry() never reconnects.
+      function terminate(err: Error) {
+        if (terminated) {
+          return;
+        }
+        terminated = true;
+        // Erroring the subscriber runs the teardown below, which cleans up.
+        subscriber.error(err);
+      }

      stream.on('data', (raw) => {
        setImmediate(() => {
          const obj = raw.toObject();
          obj.data = JSON.parse(obj.data);
-          subscriber?.next(obj);
+          subscriber.next(obj);
        });
      });

-      stream.on('end', (...args) => {
-        logger.debug('Stream ended', args);
-        subscriber?.complete();
-        subscriber = null;
-        void cleanup('end');
-      });
-
-      stream.on('error', async (err: any) => {
-        const CLIENT_CANCELLED_CODE = grpc.status.CANCELLED;
-        if (err.code === CLIENT_CANCELLED_CODE) {
-          logger.debug('Stream cancelled by client');
-          await cleanup('cancelled');
+      stream.on('end', () => {
+        if (tearingDown || terminated) {
+          logger.debug('Stream ended');
          return;
        }
-        logger.error(err, 'Stream error');
-        await cleanup('error');
-        // Give some time to node event loop to process the error
-        await sleep(100);
-        subscriber?.error(err);
-        subscriber = null;
+        logger.error('Stream ended unexpectedly, reconnecting...');
+        terminate(new GowsStreamEndedError());
      });

-      return async () => {
-        await cleanup('teardown');
+      stream.on('error', (err: any) => {
+        if (tearingDown || terminated) {
+          // We cancelled the stream ourselves, no need to reconnect
+          logger.debug({ err: err }, 'Stream cancelled by client');
+          return;
+        }
+        logger.error(err, 'Stream error, reconnecting...');
+        terminate(err);
+      });
+
+      return () => {
+        tearingDown = true;
+        void cleanup('teardown');
      };
    });
  }
@@ -18,5 +18,9 @@ export function BuildEventStreamClient(
  return new messages.EventStreamClient(address, credentials, {
    'grpc.max_send_message_length': 128 * 1024 * 1024,
    'grpc.max_receive_message_length': 128 * 1024 * 1024,
+    // Detect a hung server, so the stream errors out and we reconnect
+    'grpc.keepalive_time_ms': 30_000,
+    'grpc.keepalive_timeout_ms': 10_000,
+    'grpc.keepalive_permit_without_calls': 1,
  });
 }
@@ -1132,6 +1132,99 @@ export namespace messages {
            return PairCodeResponse.deserialize(bytes);
        }
    }
+    export class PasskeyResponseRequest extends pb_1.Message {
+        #one_of_decls: number[][] = [];
+        constructor(data?: any[] | {
+            session?: Session;
+            response_json?: string;
+        }) {
+            super();
+            pb_1.Message.initialize(this, Array.isArray(data) ? data : [], 0, -1, [], this.#one_of_decls);
+            if (!Array.isArray(data) && typeof data == "object") {
+                if ("session" in data && data.session != undefined) {
+                    this.session = data.session;
+                }
+                if ("response_json" in data && data.response_json != undefined) {
+                    this.response_json = data.response_json;
+                }
+            }
+        }
+        get session() {
+            return pb_1.Message.getWrapperField(this, Session, 1) as Session;
+        }
+        set session(value: Session) {
+            pb_1.Message.setWrapperField(this, 1, value);
+        }
+        get has_session() {
+            return pb_1.Message.getField(this, 1) != null;
+        }
+        get response_json() {
+            return pb_1.Message.getFieldWithDefault(this, 2, "") as string;
+        }
+        set response_json(value: string) {
+            pb_1.Message.setField(this, 2, value);
+        }
+        static fromObject(data: {
+            session?: ReturnType<typeof Session.prototype.toObject>;
+            response_json?: string;
+        }): PasskeyResponseRequest {
+            const message = new PasskeyResponseRequest({});
+            if (data.session != null) {
+                message.session = Session.fromObject(data.session);
+            }
+            if (data.response_json != null) {
+                message.response_json = data.response_json;
+            }
+            return message;
+        }
+        toObject() {
+            const data: {
+                session?: ReturnType<typeof Session.prototype.toObject>;
+                response_json?: string;
+            } = {};
+            if (this.session != null) {
+                data.session = this.session.toObject();
+            }
+            if (this.response_json != null) {
+                data.response_json = this.response_json;
+            }
+            return data;
+        }
+        serialize(): Uint8Array;
+        serialize(w: pb_1.BinaryWriter): void;
+        serialize(w?: pb_1.BinaryWriter): Uint8Array | void {
+            const writer = w || new pb_1.BinaryWriter();
+            if (this.has_session)
+                writer.writeMessage(1, this.session, () => this.session.serialize(writer));
+            if (this.response_json.length)
+                writer.writeString(2, this.response_json);
+            if (!w)
+                return writer.getResultBuffer();
+        }
+        static deserialize(bytes: Uint8Array | pb_1.BinaryReader): PasskeyResponseRequest {
+            const reader = bytes instanceof pb_1.BinaryReader ? bytes : new pb_1.BinaryReader(bytes), message = new PasskeyResponseRequest();
+            while (reader.nextField()) {
+                if (reader.isEndGroup())
+                    break;
+                switch (reader.getFieldNumber()) {
+                    case 1:
+                        reader.readMessage(message.session, () => message.session = Session.deserialize(reader));
+                        break;
+                    case 2:
+                        message.response_json = reader.readString();
+                        break;
+                    default: reader.skipField();
+                }
+            }
+            return message;
+        }
+        serializeBinary(): Uint8Array {
+            return this.serialize();
+        }
+        static deserializeBinary(bytes: Uint8Array): PasskeyResponseRequest {
+            return PasskeyResponseRequest.deserialize(bytes);
+        }
+    }
    export class Empty extends pb_1.Message {
        #one_of_decls: number[][] = [];
        constructor(data?: any[] | {}) {
@@ -11053,6 +11146,24 @@ export namespace messages {
                responseSerialize: (message: PairCodeResponse) => Buffer.from(message.serialize()),
                responseDeserialize: (bytes: Buffer) => PairCodeResponse.deserialize(new Uint8Array(bytes))
            },
+            SubmitPasskeyResponse: {
+                path: "/messages.MessageService/SubmitPasskeyResponse",
+                requestStream: false,
+                responseStream: false,
+                requestSerialize: (message: PasskeyResponseRequest) => Buffer.from(message.serialize()),
+                requestDeserialize: (bytes: Buffer) => PasskeyResponseRequest.deserialize(new Uint8Array(bytes)),
+                responseSerialize: (message: Empty) => Buffer.from(message.serialize()),
+                responseDeserialize: (bytes: Buffer) => Empty.deserialize(new Uint8Array(bytes))
+            },
+            ConfirmPasskey: {
+                path: "/messages.MessageService/ConfirmPasskey",
+                requestStream: false,
+                responseStream: false,
+                requestSerialize: (message: Session) => Buffer.from(message.serialize()),
+                requestDeserialize: (bytes: Buffer) => Session.deserialize(new Uint8Array(bytes)),
+                responseSerialize: (message: Empty) => Buffer.from(message.serialize()),
+                responseDeserialize: (bytes: Buffer) => Empty.deserialize(new Uint8Array(bytes))
+            },
            Logout: {
                path: "/messages.MessageService/Logout",
                requestStream: false,
@@ -11599,6 +11710,8 @@ export namespace messages {
        abstract StopSession(call: grpc_1.ServerUnaryCall<Session, Empty>, callback: grpc_1.sendUnaryData<Empty>): void;
        abstract GetSessionState(call: grpc_1.ServerUnaryCall<Session, SessionStateResponse>, callback: grpc_1.sendUnaryData<SessionStateResponse>): void;
        abstract RequestCode(call: grpc_1.ServerUnaryCall<PairCodeRequest, PairCodeResponse>, callback: grpc_1.sendUnaryData<PairCodeResponse>): void;
+        abstract SubmitPasskeyResponse(call: grpc_1.ServerUnaryCall<PasskeyResponseRequest, Empty>, callback: grpc_1.sendUnaryData<Empty>): void;
+        abstract ConfirmPasskey(call: grpc_1.ServerUnaryCall<Session, Empty>, callback: grpc_1.sendUnaryData<Empty>): void;
        abstract Logout(call: grpc_1.ServerUnaryCall<Session, Empty>, callback: grpc_1.sendUnaryData<Empty>): void;
        abstract SetProfileName(call: grpc_1.ServerUnaryCall<ProfileNameRequest, Empty>, callback: grpc_1.sendUnaryData<Empty>): void;
        abstract SetProfileStatus(call: grpc_1.ServerUnaryCall<ProfileStatusRequest, Empty>, callback: grpc_1.sendUnaryData<Empty>): void;
@@ -11676,6 +11789,12 @@ export namespace messages {
        RequestCode: GrpcUnaryServiceInterface<PairCodeRequest, PairCodeResponse> = (message: PairCodeRequest, metadata: grpc_1.Metadata | grpc_1.CallOptions | grpc_1.requestCallback<PairCodeResponse>, options?: grpc_1.CallOptions | grpc_1.requestCallback<PairCodeResponse>, callback?: grpc_1.requestCallback<PairCodeResponse>): grpc_1.ClientUnaryCall => {
            return super.RequestCode(message, metadata, options, callback);
        };
+        SubmitPasskeyResponse: GrpcUnaryServiceInterface<PasskeyResponseRequest, Empty> = (message: PasskeyResponseRequest, metadata: grpc_1.Metadata | grpc_1.CallOptions | grpc_1.requestCallback<Empty>, options?: grpc_1.CallOptions | grpc_1.requestCallback<Empty>, callback?: grpc_1.requestCallback<Empty>): grpc_1.ClientUnaryCall => {
+            return super.SubmitPasskeyResponse(message, metadata, options, callback);
+        };
+        ConfirmPasskey: GrpcUnaryServiceInterface<Session, Empty> = (message: Session, metadata: grpc_1.Metadata | grpc_1.CallOptions | grpc_1.requestCallback<Empty>, options?: grpc_1.CallOptions | grpc_1.requestCallback<Empty>, callback?: grpc_1.requestCallback<Empty>): grpc_1.ClientUnaryCall => {
+            return super.ConfirmPasskey(message, metadata, options, callback);
+        };
        Logout: GrpcUnaryServiceInterface<Session, Empty> = (message: Session, metadata: grpc_1.Metadata | grpc_1.CallOptions | grpc_1.requestCallback<Empty>, options?: grpc_1.CallOptions | grpc_1.requestCallback<Empty>, callback?: grpc_1.requestCallback<Empty>): grpc_1.ClientUnaryCall => {
            return super.Logout(message, metadata, options, callback);
        };
@@ -488,6 +488,17 @@ function deserialize_messages_PairCodeResponse(buffer_arg) {
  return gows_pb.PairCodeResponse.deserializeBinary(new Uint8Array(buffer_arg));
 }

+function serialize_messages_PasskeyResponseRequest(arg) {
+  if (!(arg instanceof gows_pb.PasskeyResponseRequest)) {
+    throw new Error('Expected argument of type messages.PasskeyResponseRequest');
+  }
+  return Buffer.from(arg.serializeBinary());
+}
+
+function deserialize_messages_PasskeyResponseRequest(buffer_arg) {
+  return gows_pb.PasskeyResponseRequest.deserializeBinary(new Uint8Array(buffer_arg));
+}
+
 function serialize_messages_PresenceRequest(arg) {
  if (!(arg instanceof gows_pb.PresenceRequest)) {
    throw new Error('Expected argument of type messages.PresenceRequest');
@@ -764,6 +775,28 @@ startSession: {
    responseSerialize: serialize_messages_PairCodeResponse,
    responseDeserialize: deserialize_messages_PairCodeResponse,
  },
+  submitPasskeyResponse: {
+    path: '/messages.MessageService/SubmitPasskeyResponse',
+    requestStream: false,
+    responseStream: false,
+    requestType: gows_pb.PasskeyResponseRequest,
+    responseType: gows_pb.Empty,
+    requestSerialize: serialize_messages_PasskeyResponseRequest,
+    requestDeserialize: deserialize_messages_PasskeyResponseRequest,
+    responseSerialize: serialize_messages_Empty,
+    responseDeserialize: deserialize_messages_Empty,
+  },
+  confirmPasskey: {
+    path: '/messages.MessageService/ConfirmPasskey',
+    requestStream: false,
+    responseStream: false,
+    requestType: gows_pb.Session,
+    responseType: gows_pb.Empty,
+    requestSerialize: serialize_messages_Session,
+    requestDeserialize: deserialize_messages_Session,
+    responseSerialize: serialize_messages_Empty,
+    responseDeserialize: deserialize_messages_Empty,
+  },
  logout: {
    path: '/messages.MessageService/Logout',
    requestStream: false,
@@ -84,6 +84,7 @@ goog.exportSymbol('proto.messages.Pagination', null, global);
 goog.exportSymbol('proto.messages.PairCodeRequest', null, global);
 goog.exportSymbol('proto.messages.PairCodeResponse', null, global);
 goog.exportSymbol('proto.messages.ParticipantAction', null, global);
+goog.exportSymbol('proto.messages.PasskeyResponseRequest', null, global);
 goog.exportSymbol('proto.messages.PhoneInfo', null, global);
 goog.exportSymbol('proto.messages.PollMessage', null, global);
 goog.exportSymbol('proto.messages.PollVoteMessage', null, global);
@@ -395,6 +396,27 @@ if (goog.DEBUG && !COMPILED) {
   */
  proto.messages.PairCodeResponse.displayName = 'proto.messages.PairCodeResponse';
 }
+/**
+ * Generated by JsPbCodeGenerator.
+ * @param {Array=} opt_data Optional initial data array, typically from a
+ * server response, or constructed directly in Javascript. The array is used
+ * in place and becomes part of the constructed object. It is not cloned.
+ * If no data is provided, the constructed object will be empty, but still
+ * valid.
+ * @extends {jspb.Message}
+ * @constructor
+ */
+proto.messages.PasskeyResponseRequest = function(opt_data) {
+  jspb.Message.initialize(this, opt_data, 0, -1, null, null);
+};
+goog.inherits(proto.messages.PasskeyResponseRequest, jspb.Message);
+if (goog.DEBUG && !COMPILED) {
+  /**
+   * @public
+   * @override
+   */
+  proto.messages.PasskeyResponseRequest.displayName = 'proto.messages.PasskeyResponseRequest';
+}
 /**
 * Generated by JsPbCodeGenerator.
 * @param {Array=} opt_data Optional initial data array, typically from a
@@ -4190,6 +4212,187 @@ proto.messages.PairCodeResponse.prototype.setCode = function(value) {



+if (jspb.Message.GENERATE_TO_OBJECT) {
+/**
+ * Creates an object representation of this proto.
+ * Field names that are reserved in JavaScript and will be renamed to pb_name.
+ * Optional fields that are not set will be set to undefined.
+ * To access a reserved field use, foo.pb_<name>, eg, foo.pb_default.
+ * For the list of reserved names please see:
+ *     net/proto2/compiler/js/internal/generator.cc#kKeyword.
+ * @param {boolean=} opt_includeInstance Deprecated. whether to include the
+ *     JSPB instance for transitional soy proto support:
+ *     http://goto/soy-param-migration
+ * @return {!Object}
+ */
+proto.messages.PasskeyResponseRequest.prototype.toObject = function(opt_includeInstance) {
+  return proto.messages.PasskeyResponseRequest.toObject(opt_includeInstance, this);
+};
+
+
+/**
+ * Static version of the {@see toObject} method.
+ * @param {boolean|undefined} includeInstance Deprecated. Whether to include
+ *     the JSPB instance for transitional soy proto support:
+ *     http://goto/soy-param-migration
+ * @param {!proto.messages.PasskeyResponseRequest} msg The msg instance to transform.
+ * @return {!Object}
+ * @suppress {unusedLocalVariables} f is only used for nested messages
+ */
+proto.messages.PasskeyResponseRequest.toObject = function(includeInstance, msg) {
+  var f, obj = {
+    session: (f = msg.getSession()) && proto.messages.Session.toObject(includeInstance, f),
+    responseJson: jspb.Message.getFieldWithDefault(msg, 2, "")
+  };
+
+  if (includeInstance) {
+    obj.$jspbMessageInstance = msg;
+  }
+  return obj;
+};
+}
+
+
+/**
+ * Deserializes binary data (in protobuf wire format).
+ * @param {jspb.ByteSource} bytes The bytes to deserialize.
+ * @return {!proto.messages.PasskeyResponseRequest}
+ */
+proto.messages.PasskeyResponseRequest.deserializeBinary = function(bytes) {
+  var reader = new jspb.BinaryReader(bytes);
+  var msg = new proto.messages.PasskeyResponseRequest;
+  return proto.messages.PasskeyResponseRequest.deserializeBinaryFromReader(msg, reader);
+};
+
+
+/**
+ * Deserializes binary data (in protobuf wire format) from the
+ * given reader into the given message object.
+ * @param {!proto.messages.PasskeyResponseRequest} msg The message object to deserialize into.
+ * @param {!jspb.BinaryReader} reader The BinaryReader to use.
+ * @return {!proto.messages.PasskeyResponseRequest}
+ */
+proto.messages.PasskeyResponseRequest.deserializeBinaryFromReader = function(msg, reader) {
+  while (reader.nextField()) {
+    if (reader.isEndGroup()) {
+      break;
+    }
+    var field = reader.getFieldNumber();
+    switch (field) {
+    case 1:
+      var value = new proto.messages.Session;
+      reader.readMessage(value,proto.messages.Session.deserializeBinaryFromReader);
+      msg.setSession(value);
+      break;
+    case 2:
+      var value = /** @type {string} */ (reader.readString());
+      msg.setResponseJson(value);
+      break;
+    default:
+      reader.skipField();
+      break;
+    }
+  }
+  return msg;
+};
+
+
+/**
+ * Serializes the message to binary data (in protobuf wire format).
+ * @return {!Uint8Array}
+ */
+proto.messages.PasskeyResponseRequest.prototype.serializeBinary = function() {
+  var writer = new jspb.BinaryWriter();
+  proto.messages.PasskeyResponseRequest.serializeBinaryToWriter(this, writer);
+  return writer.getResultBuffer();
+};
+
+
+/**
+ * Serializes the given message to binary data (in protobuf wire
+ * format), writing to the given BinaryWriter.
+ * @param {!proto.messages.PasskeyResponseRequest} message
+ * @param {!jspb.BinaryWriter} writer
+ * @suppress {unusedLocalVariables} f is only used for nested messages
+ */
+proto.messages.PasskeyResponseRequest.serializeBinaryToWriter = function(message, writer) {
+  var f = undefined;
+  f = message.getSession();
+  if (f != null) {
+    writer.writeMessage(
+      1,
+      f,
+      proto.messages.Session.serializeBinaryToWriter
+    );
+  }
+  f = message.getResponseJson();
+  if (f.length > 0) {
+    writer.writeString(
+      2,
+      f
+    );
+  }
+};
+
+
+/**
+ * optional Session session = 1;
+ * @return {?proto.messages.Session}
+ */
+proto.messages.PasskeyResponseRequest.prototype.getSession = function() {
+  return /** @type{?proto.messages.Session} */ (
+    jspb.Message.getWrapperField(this, proto.messages.Session, 1));
+};
+
+
+/**
+ * @param {?proto.messages.Session|undefined} value
+ * @return {!proto.messages.PasskeyResponseRequest} returns this
+*/
+proto.messages.PasskeyResponseRequest.prototype.setSession = function(value) {
+  return jspb.Message.setWrapperField(this, 1, value);
+};
+
+
+/**
+ * Clears the message field making it undefined.
+ * @return {!proto.messages.PasskeyResponseRequest} returns this
+ */
+proto.messages.PasskeyResponseRequest.prototype.clearSession = function() {
+  return this.setSession(undefined);
+};
+
+
+/**
+ * Returns whether this field is set.
+ * @return {boolean}
+ */
+proto.messages.PasskeyResponseRequest.prototype.hasSession = function() {
+  return jspb.Message.getField(this, 1) != null;
+};
+
+
+/**
+ * optional string response_json = 2;
+ * @return {string}
+ */
+proto.messages.PasskeyResponseRequest.prototype.getResponseJson = function() {
+  return /** @type {string} */ (jspb.Message.getFieldWithDefault(this, 2, ""));
+};
+
+
+/**
+ * @param {string} value
+ * @return {!proto.messages.PasskeyResponseRequest} returns this
+ */
+proto.messages.PasskeyResponseRequest.prototype.setResponseJson = function(value) {
+  return jspb.Message.setProto3StringField(this, 2, value);
+};
+
+
+
+
+
 if (jspb.Message.GENERATE_TO_OBJECT) {
 /**
 * Creates an object representation of this proto.
@@ -48,6 +48,10 @@ import {
  toCusFormat,
  toJID,
 } from '@waha/core/utils/jids';
+import {
+  PasskeyChallenge,
+  PasskeyConfirmationResponse,
+} from '@waha/structures/auth.dto';
 import {
  Channel,
  ChannelListResult,
@@ -419,6 +423,25 @@ export class WhatsappSessionGoWSCore extends WhatsappSession {
      if (data.Event == 'success') {
        return;
      }
+      if (data.Event == 'passkey-request') {
+        // WhatsApp requires a passkey (WebAuthn) to finish pairing this account.
+        const challenge = data.PasskeyRequest?.PublicKey ?? null;
+        this.logger.info('Passkey required to finish pairing');
+        this.setStatus(WAHASessionStatus.PASSKEY_REQUIRED, challenge);
+        return;
+      }
+      if (data.Event == 'passkey-confirmation') {
+        // Only the manual case reaches us - when WhatsApp allows skipping the
+        // handoff UX, whatsmeow confirms on its own and emits nothing.
+        // The operator must see the code, verify it matches the one shown on
+        // their phone, then confirm via POST .../auth/passkey/confirm.
+        const code = data.PasskeyConfirmation?.Code ?? null;
+        this.logger.info({ code: code }, 'Passkey confirmation code');
+        this.setStatus(WAHASessionStatus.PASSKEY_CONFIRMATION_REQUIRED, {
+          code: code,
+        });
+        return;
+      }
      if (data.Event != 'code') {
        this.logger.warn(data, 'Failed QR item event');
        this.status = WAHASessionStatus.FAILED;
@@ -430,6 +453,17 @@ export class WhatsappSessionGoWSCore extends WhatsappSession {
      }
      this.qr.save(qr);
      this.printQR(this.qr);
+      if (
+        this.status === WAHASessionStatus.PASSKEY_REQUIRED ||
+        this.status === WAHASessionStatus.PASSKEY_CONFIRMATION_REQUIRED
+      ) {
+        // The underlying whatsmeow QR rotation keeps emitting fresh codes in
+        // parallel while the passkey challenge is pending (it doesn't know
+        // about the passkey step). Don't let that bounce the session back to
+        // SCAN_QR_CODE mid-flow — the operator is busy signing the passkey.
+        // It'd also wipe the passkey data off the status.
+        return;
+      }
      this.status = WAHASessionStatus.SCAN_QR_CODE;
    });
    events.on(WhatsMeowEvent.PUSH_NAME_SETTING, (data) => {
@@ -849,6 +883,36 @@ export class WhatsappSessionGoWSCore extends WhatsappSession {
    return { code: code };
  }

+  public async sendPasskeyResponse(responseJson: string): Promise<void> {
+    const request = new messages.PasskeyResponseRequest({
+      session: this.session,
+      response_json: responseJson,
+    });
+    await promisify(this.client.SubmitPasskeyResponse)(request);
+  }
+
+  public async confirmPasskey(): Promise<void> {
+    await promisify(this.client.ConfirmPasskey)(this.session);
+  }
+
+  public getPasskeyChallenge(): PasskeyChallenge {
+    if (this.status !== WAHASessionStatus.PASSKEY_REQUIRED) {
+      throw new UnprocessableEntityException(
+        'No passkey challenge is pending for the session',
+      );
+    }
+    return this.statusData;
+  }
+
+  public getPasskeyConfirmation(): PasskeyConfirmationResponse {
+    if (this.status !== WAHASessionStatus.PASSKEY_CONFIRMATION_REQUIRED) {
+      throw new UnprocessableEntityException(
+        'No passkey confirmation is pending for the session',
+      );
+    }
+    return { code: this.statusData?.code };
+  }
+
  async unpair() {
    await promisify(this.client.Logout)(this.session);
  }
@@ -1,4 +1,5 @@
 import { WebJSPresence } from '@waha/core/engines/webjs/types';
+import { GetSerialized } from '@waha/core/utils/serialized';
 import { GetChatMessagesFilter } from '@waha/structures/chats.dto';
 import { Label } from '@waha/structures/labels.dto';
 import { LidToPhoneNumber } from '@waha/structures/lids.dto';
@@ -75,7 +76,7 @@ function extractReactionsByMessageKey(
 ): Map<string, ChannelMessageReaction[]> {
  const reactions = new Map();
  for (const reaction of newsletterReactions) {
-    const key = reaction.parentMsgKey._serialized;
+    const key = GetSerialized(reaction.parentMsgKey);
    const emojiCountMap = reaction.emojiCountMap;
    const reactionList: ChannelMessageReaction[] = [];
    for (const emoji in emojiCountMap) {
@@ -266,7 +267,8 @@ export class WebjsClientCore extends Client {
        // Filter chats by IDs if filter is provided
        if (filter && filter.ids && filter.ids.length > 0) {
          chats = chats.filter((chat) =>
-            filter.ids.includes(chat.id._serialized),
+            // @ts-ignore
+            filter.ids.includes(window.WWebJS.GetSerialized(chat.id)),
          );
        }

@@ -382,7 +384,10 @@ export class WebjsClientCore extends Client {
          // Construct the initial anchor the same way wa-js does:
          // serialize to string then reconstruct via MsgKey.fromString so the
          // object has the exact shape msgFindByDirection expects.
-          const lastReceivedSerialized = chat.lastReceivedKey?._serialized;
+          // @ts-ignore
+          const lastReceivedSerialized = window.WWebJS.GetSerialized(
+            chat.lastReceivedKey,
+          );
          if (!lastReceivedSerialized) return [];
          let currentAnchorKey = window
            .require('WAWebMsgKey')
@@ -406,7 +411,8 @@ export class WebjsClientCore extends Client {
          // @ts-ignore
          const toModel = (m) => {
            if (m && typeof m.serialize === 'function') return m;
-            const serializedId = m?.id?._serialized;
+            // @ts-ignore
+            const serializedId = window.WWebJS.GetSerialized(m?.id);
            const Msg = window.require('WAWebCollections').Msg;
            if (serializedId) {
              const stored = Msg.get(serializedId);
@@ -437,7 +443,8 @@ export class WebjsClientCore extends Client {
            // appear in multiple batches when anchors overlap
            const seenIds = new Set();
            msgs = msgs.filter((m) => {
-              const sid = m?.id?._serialized;
+              // @ts-ignore
+              const sid = window.WWebJS.GetSerialized(m?.id);
              if (!sid || seenIds.has(sid)) return false;
              seenIds.add(sid);
              return true;
@@ -463,7 +470,10 @@ export class WebjsClientCore extends Client {
            // the oldest message in this batch — use it as the next anchor to
            // walk further back in history without overlap
            const oldestInBatch = batchModels[batchModels.length - 1];
-            const oldestSerialized = oldestInBatch?.id?._serialized;
+            // @ts-ignore
+            const oldestSerialized = window.WWebJS.GetSerialized(
+              oldestInBatch?.id,
+            );
            if (!oldestSerialized) break;
            currentAnchorKey = window
              .require('WAWebMsgKey')
@@ -532,9 +542,9 @@ export class WebjsClientCore extends Client {
        const result = values.map((map) => {
          return {
            // @ts-ignore
-            lid: map.lid._serialized,
+            lid: window.WWebJS.GetSerialized(map.lid),
            // @ts-ignore
-            pn: map.phoneNumber._serialized,
+            pn: window.WWebJS.GetSerialized(map.phoneNumber),
          };
        });
        // @ts-ignore
@@ -565,7 +575,8 @@ export class WebjsClientCore extends Client {

      const wid = WAWebWidFactory.createWid(lid);
      const result = WAWebApiContact.getPhoneNumber(wid);
-      return result ? result._serialized : null;
+      // @ts-ignore
+      return window.WWebJS.GetSerialized(result);
    }, lid);
    return pn;
  }
@@ -577,7 +588,8 @@ export class WebjsClientCore extends Client {

      const wid = WAWebWidFactory.createWid(pn);
      const result = WAWebApiContact.getCurrentLid(wid);
-      return result ? result._serialized : null;
+      // @ts-ignore
+      return window.WWebJS.GetSerialized(result);
    }, phoneNumber)) as any;
    return lid;
  }
@@ -617,7 +629,8 @@ export class WebjsClientCore extends Client {
      }
      return chatstates.map((chatstate) => {
        return {
-          participant: chatstate.id._serialized,
+          // @ts-ignore
+          participant: window.WWebJS.GetSerialized(chatstate.id),
          lastSeen: chatstate.t,
          state: chatstate.type,
        };
@@ -681,7 +694,7 @@ export class WebjsClientCore extends Client {
    const messages: WebjsChannelMessage[] = messageInstances.map((msg) => {
      return {
        message: msg,
-        reactions: reactions.get(msg.id._serialized) || [],
+        reactions: reactions.get(GetSerialized(msg.id)) || [],
        viewCount: msg.rawData.viewCount,
      };
    });
@@ -19,6 +19,7 @@ import {
  GroupParticipant as WEBJSGroupParticipant,
 } from 'whatsapp-web.js';
 import { isPnUser } from '@waha/core/utils/jids';
+import { GetSerialized } from '@waha/core/utils/serialized';

 function ToGroupInfo(
  group: GroupChat,
@@ -29,7 +30,7 @@ function ToGroupInfo(
  const groupMetadata = group.groupMetadata;
  const info: GroupInfo = {
    // @ts-ignore
-    id: group.id._serialized,
+    id: GetSerialized(group.id),
    subject: group.name,
    description: group.description,
    invite: invite,
@@ -72,11 +73,10 @@ export function getParticipants(
      role = GroupParticipantRole.ADMIN;
    }

+    const participantId = GetSerialized(participant.id);
    return {
-      id: participant.id._serialized,
-      pn: isPnUser(participant.id._serialized)
-        ? participant.id._serialized
-        : null,
+      id: participantId,
+      pn: isPnUser(participantId) ? participantId : null,
      role: role,
    };
  });
@@ -182,6 +182,7 @@ import {
  Message as MessageInstance,
  Call as CallInstance,
 } from 'whatsapp-web.js/src/structures';
+import { GetSerialized } from '@waha/core/utils/serialized';

 import { WAJSPresenceChatStateType, WebJSPresence } from './types';
 import { WebJSAuthFactory } from './WebJSAuthFactory';
@@ -531,7 +532,8 @@ export class WhatsappSessionWebJSCore extends WhatsappSession {
    }
    const wid = clientInfo.wid;
    return {
-      id: wid?._serialized,
+      id: GetSerialized(wid),
+      lid: GetSerialized(clientInfo.lid),
      pushName: clientInfo?.pushname,
    };
  }
@@ -738,7 +740,7 @@ export class WhatsappSessionWebJSCore extends WhatsappSession {
    }
    return {
      numberExists: true,
-      chatId: result._serialized,
+      chatId: GetSerialized(result),
    };
  }

@@ -1135,14 +1137,14 @@ export class WhatsappSessionWebJSCore extends WhatsappSession {

  protected async fetchChatSummary(chat: Chat): Promise<ChatSummary> {
    const picture = await this.getContactProfilePicture(
-      chat.id._serialized,
+      GetSerialized(chat.id),
      false,
    );
    const lastMessage = chat.lastMessage
      ? this.toWAMessage(chat.lastMessage)
      : null;
    return {
-      id: chat.id._serialized,
+      id: GetSerialized(chat.id),
      name: chat.name || null,
      picture: picture,
      lastMessage: lastMessage,
@@ -1248,7 +1250,7 @@ export class WhatsappSessionWebJSCore extends WhatsappSession {
      // @ts-ignore
      message.rawData.receipts = await message.getInfo().catch((error) => {
        this.logger.error(
-          { error: error, msg: message.id._serialized },
+          { error: error, msg: GetSerialized(message.id) },
          'Failed to get receipts',
        );
        return null;
@@ -1713,7 +1715,7 @@ export class WhatsappSessionWebJSCore extends WhatsappSession {
      role = ChannelRole.GUEST;
    }
    return {
-      id: chat.id._serialized,
+      id: GetSerialized(chat.id),
      name: chat.name,
      description: chat.description,
      invite: getChannelInviteLink(metadata.inviteCode),
@@ -2212,10 +2214,10 @@ export class WhatsappSessionWebJSCore extends WhatsappSession {
      },
    );
    const chatsArchived$ = chatArchived$.pipe(
-      filter((event: any) => this.jids.include(event?.chat?.id?._serialized)),
+      filter((event: any) => this.jids.include(GetSerialized(event?.chat?.id))),
      map((event) => {
        return {
-          id: event.chat.id._serialized,
+          id: GetSerialized(event.chat.id),
          archived: event.archived,
          timestamp: event.chat.timestamp,
        };
@@ -2302,7 +2304,7 @@ export class WhatsappSessionWebJSCore extends WhatsappSession {

    const source = this.getMessageSource(reaction.id.id);
    return {
-      id: reaction.id._serialized,
+      id: GetSerialized(reaction.id),
      from: normalizeJid(reaction.senderId),
      fromMe: reaction.id.fromMe,
      source: source,
@@ -2311,13 +2313,13 @@ export class WhatsappSessionWebJSCore extends WhatsappSession {
      timestamp: reaction.timestamp,
      reaction: {
        text: reaction.reaction,
-        messageId: reaction.msgId._serialized,
+        messageId: GetSerialized(reaction.msgId),
      },
    };
  }

  private toPollVotePayload(vote: WebjsPollVote): PollVotePayload | null {
-    const pollMessageId = vote?.parentMessage?.id?._serialized;
+    const pollMessageId = GetSerialized(vote?.parentMessage?.id);
    if (!pollMessageId) {
      return null;
    }
@@ -2397,10 +2399,10 @@ export class WhatsappSessionWebJSCore extends WhatsappSession {
  protected toWAMessage(message: Message): WAMessage {
    const replyTo = this.extractReplyTo(message);
    const source = this.getMessageSource(message.id.id);
-    const key = parseMessageIdSerialized(message.id._serialized);
+    const key = parseMessageIdSerialized(GetSerialized(message.id));
    // @ts-ignore
    return {
-      id: message.id._serialized,
+      id: GetSerialized(message.id),
      timestamp: message.timestamp,
      from: message.from,
      fromMe: message.fromMe,
@@ -2474,7 +2476,7 @@ export class WhatsappSessionWebJSCore extends WhatsappSession {

  protected toWAContact(contact: Contact) {
    // @ts-ignore
-    contact.id = contact.id._serialized;
+    contact.id = GetSerialized(contact.id);
    return contact;
  }

@@ -2552,7 +2554,7 @@ export class WEBJSEngineMediaProcessor
  }

  getMessageId(message: Message): string {
-    return message.id._serialized;
+    return GetSerialized(message.id);
  }

  getMimetype(message: Message): string {
@@ -3,6 +3,7 @@ import {
  UnprocessableEntityException,
 } from '@nestjs/common';
 import { SessionManager } from '@waha/core/abc/manager.abc';
+import { SessionActions } from '@waha/core/auth/casl.types';
 import {
  ApiKey,
  IApiKeyRepository,
@@ -10,6 +11,24 @@ import {
 import { ApiKeyDTO, ApiKeyRequest } from '@waha/structures/apikeys.dto';
 import { generatePrefixedId, generateSecret } from '@waha/utils/ids';

+const MEDIA_KEY_ACTIONS: SessionActions = {
+  read: false,
+  send: false,
+  control: false,
+  setting: false,
+  app: false,
+  delete: false,
+};
+
+const CONTROL_KEY_ACTIONS: SessionActions = {
+  read: false,
+  send: false,
+  control: true,
+  setting: false,
+  app: false,
+  delete: false,
+};
+
 function CheckInvariant(
  apiKey: Pick<ApiKey, 'isAdmin' | 'session' | 'actions'>,
 ): void {
@@ -78,6 +97,46 @@ export class ApiKeyService {
    return this.toDTO(apikey);
  }

+  private async createOrGetScopedKey(
+    session: string,
+    variant: string,
+    actions: SessionActions,
+  ): Promise<ApiKeyDTO> {
+    const exists = await this.manager.exists(session);
+    if (!exists) {
+      throw new UnprocessableEntityException(
+        `Session "${session}" does not exist`,
+      );
+    }
+    // Deterministic id keeps this idempotent: repeated calls reuse the same
+    // stored secret instead of minting a new key every time.
+    const id = `key_id_${variant}_${session}`;
+    const existing = await this.repository.getById(id);
+    if (existing) {
+      return this.toDTO(existing);
+    }
+    const apikey: ApiKey = {
+      id: id,
+      key: `key_${generateSecret(32)}`,
+      isActive: true,
+      isAdmin: false,
+      session: session,
+      actions: actions,
+      app_id: null,
+    };
+    CheckInvariant(apikey);
+    await this.repository.upsert(apikey);
+    return this.toDTO(apikey);
+  }
+
+  async createOrGetMediaKey(session: string): Promise<ApiKeyDTO> {
+    return this.createOrGetScopedKey(session, 'media', MEDIA_KEY_ACTIONS);
+  }
+
+  async createOrGetControlKey(session: string): Promise<ApiKeyDTO> {
+    return this.createOrGetScopedKey(session, 'control', CONTROL_KEY_ACTIONS);
+  }
+
  async list(): Promise<ApiKeyDTO[]> {
    const keys = await this.repository.list();
    return keys.map((key) => this.toDTO(key));
@@ -0,0 +1,131 @@
+import {
+  GetSerialized,
+  GetSerializedMsgKey,
+  GetSerializedWid,
+} from './serialized';
+
+describe('serialized helpers', () => {
+  describe('GetSerializedWid', () => {
+    it('returns strings and nullish values as-is', () => {
+      expect(GetSerializedWid('123@c.us')).toBe('123@c.us');
+      expect(GetSerializedWid(null)).toBeNull();
+      expect(GetSerializedWid(undefined)).toBeUndefined();
+    });
+
+    it('uses existing _serialized', () => {
+      expect(GetSerializedWid({ _serialized: '123@c.us' })).toBe('123@c.us');
+    });
+
+    it('ignores the minified $1 property and reconstructs from keys', () => {
+      const wid: any = { $1: 'ignored', user: '123', server: 'c.us' };
+      expect(GetSerializedWid(wid)).toBe('123@c.us');
+      expect(wid._serialized).toBe('123@c.us');
+    });
+
+    it('reconstructs from user/server and caches', () => {
+      const wid: any = { user: '123', server: 'c.us' };
+      expect(GetSerializedWid(wid)).toBe('123@c.us');
+      expect(wid._serialized).toBe('123@c.us');
+    });
+
+    it('reconstructs a group wid', () => {
+      expect(GetSerializedWid({ user: '123-456', server: 'g.us' })).toBe(
+        '123-456@g.us',
+      );
+    });
+
+    it('appends the device when present and truthy', () => {
+      expect(GetSerializedWid({ user: '123', server: 'c.us', device: 7 })).toBe(
+        '123:7@c.us',
+      );
+      expect(GetSerializedWid({ user: '123', server: 'c.us', device: 0 })).toBe(
+        '123@c.us',
+      );
+    });
+
+    it('handles the special "call" wid', () => {
+      expect(GetSerializedWid({ user: 'call', server: 'call' })).toBe('call');
+    });
+
+    it('returns null when it cannot reconstruct (no keys, only $1)', () => {
+      expect(GetSerializedWid({ foo: 'bar' })).toBeNull();
+      expect(GetSerializedWid({ $1: '123@c.us' })).toBeNull();
+    });
+  });
+
+  describe('GetSerializedMsgKey', () => {
+    it('reconstructs fromMe_remote_id and caches', () => {
+      const key: any = {
+        fromMe: true,
+        remote: { _serialized: '123@c.us' },
+        id: 'AAA',
+      };
+      expect(GetSerializedMsgKey(key)).toBe('true_123@c.us_AAA');
+      expect(key._serialized).toBe('true_123@c.us_AAA');
+    });
+
+    it('reconstructs a remote wid that only has component keys', () => {
+      const key: any = {
+        fromMe: false,
+        remote: { user: '123', server: 'c.us' },
+        id: 'AAA',
+      };
+      expect(GetSerializedMsgKey(key)).toBe('false_123@c.us_AAA');
+    });
+
+    it('appends the participant', () => {
+      const key: any = {
+        fromMe: false,
+        remote: { _serialized: '123-456@g.us' },
+        id: 'AAA',
+        participant: { _serialized: '789@c.us' },
+      };
+      expect(GetSerializedMsgKey(key)).toBe('false_123-456@g.us_AAA_789@c.us');
+    });
+
+    it('appends self before participant', () => {
+      const key: any = {
+        fromMe: true,
+        remote: { _serialized: '123@c.us' },
+        id: 'AAA',
+        self: 'out',
+        participant: { _serialized: '789@c.us' },
+      };
+      expect(GetSerializedMsgKey(key)).toBe('true_123@c.us_AAA_out_789@c.us');
+    });
+
+    it('ignores $1 and reconstructs from keys', () => {
+      const key: any = {
+        $1: 'ignored',
+        fromMe: true,
+        remote: { _serialized: '999@c.us' },
+        id: 'BBB',
+      };
+      expect(GetSerializedMsgKey(key)).toBe('true_999@c.us_BBB');
+    });
+  });
+
+  describe('GetSerialized (dispatcher)', () => {
+    it('dispatches wid shapes', () => {
+      expect(GetSerialized({ user: '123', server: 'c.us' })).toBe('123@c.us');
+    });
+
+    it('dispatches msgkey shapes', () => {
+      expect(
+        GetSerialized({
+          fromMe: true,
+          remote: { user: '123', server: 'c.us' },
+          id: 'AAA',
+        }),
+      ).toBe('true_123@c.us_AAA');
+    });
+
+    it('honours existing _serialized before dispatching', () => {
+      expect(GetSerialized({ _serialized: 'x@c.us' })).toBe('x@c.us');
+    });
+
+    it('returns null for unknown shapes', () => {
+      expect(GetSerialized({ foo: 'bar' })).toBeNull();
+    });
+  });
+});
@@ -0,0 +1,103 @@
+/**
+ * Serialized-ID helpers for the WEBJS engine.
+ *
+ * COPIED from whatsapp-web.js `src/util/Serialized.js` (fork: ../whatsapp-web.js).
+ * Keep this file in sync with that upstream version whenever it changes.
+ *
+ * WhatsApp Web renamed the `_serialized` property on its ID objects (Wid /
+ * MsgKey) to a minified name (`$1`) in the 2026-07 update. Rather than depend on
+ * that unstable minified name, each helper reconstructs the serialized string
+ * deterministically from the object's own component keys - existing
+ * `_serialized` -> reconstruct from keys - and caches it back onto the object as
+ * `_serialized` so later reads keep working.
+ */
+
+interface CacheHit {
+  done: boolean;
+  value: string | null;
+}
+
+function cached(id: any): CacheHit {
+  if (id == null) {
+    return { done: true, value: id };
+  }
+  if (typeof id === 'string') {
+    return { done: true, value: id };
+  }
+  if (typeof id._serialized === 'string' && id._serialized !== '') {
+    return { done: true, value: id._serialized };
+  }
+  return { done: false, value: null };
+}
+
+/**
+ * Serializes a Wid (WhatsApp ID): `user[:device]@server`.
+ */
+export function GetSerializedWid(id: any): string | null {
+  const hit = cached(id);
+  if (hit.done) {
+    return hit.value;
+  }
+
+  let value: string | null;
+  if (id.user != null && id.server != null) {
+    value =
+      id.user === 'call'
+        ? 'call'
+        : `${id.user}${id.device ? `:${id.device}` : ''}@${id.server}`;
+  } else {
+    value = null;
+  }
+
+  if (value != null) {
+    id._serialized = value;
+  }
+  return value;
+}
+
+/**
+ * Serializes a MsgKey (message ID): `fromMe_remote_id[_self][_participant]`.
+ */
+export function GetSerializedMsgKey(id: any): string | null {
+  const hit = cached(id);
+  if (hit.done) {
+    return hit.value;
+  }
+
+  let value: string | null;
+  if (id.remote != null && id.id != null) {
+    const remote = GetSerializedWid(id.remote);
+    const participant =
+      id.participant != null ? GetSerializedWid(id.participant) : null;
+    value =
+      `${id.fromMe ? 'true' : 'false'}_${remote}_${id.id}` +
+      (id.self ? `_${id.self}` : '') +
+      (participant ? `_${participant}` : '');
+  } else {
+    value = null;
+  }
+
+  if (value != null) {
+    id._serialized = value;
+  }
+  return value;
+}
+
+/**
+ * Generic entry point: resolves `_serialized`/`$1` then dispatches to the Wid
+ * or MsgKey helper based on the object's shape. Use the specific helpers when
+ * the id type is known.
+ */
+export function GetSerialized(id: any): string | null {
+  const hit = cached(id);
+  if (hit.done) {
+    return hit.value;
+  }
+  if (id.remote != null && id.id != null) {
+    return GetSerializedMsgKey(id);
+  }
+  if (id.user != null && id.server != null) {
+    return GetSerializedWid(id);
+  }
+  return null;
+}
@@ -76,6 +76,12 @@ export class ApiKeyDTO {
  actions: SessionActions | null;
 }

+export class ScopedApiKeyRequest {
+  @ApiProperty({ example: 'default' })
+  @SessionName()
+  session: string;
+}
+
 export class ApiKeyRequest {
  @ApiProperty({ example: false })
  @IsBoolean()
@@ -38,3 +38,115 @@ export class RequestCodeRequest {
 export class PairingCodeResponse {
  code: string;
 }
+
+export class PasskeyAssertionResponseData {
+  @ApiProperty({
+    description: 'Base64url-encoded clientDataJSON from the authenticator.',
+  })
+  clientDataJSON: string;
+
+  @ApiProperty({
+    description: 'Base64url-encoded authenticatorData from the authenticator.',
+  })
+  authenticatorData: string;
+
+  @ApiProperty({
+    description: 'Base64url-encoded signature from the authenticator.',
+  })
+  signature: string;
+
+  @ApiProperty({
+    description:
+      'Base64url-encoded user handle, if returned by the authenticator.',
+    required: false,
+  })
+  userHandle?: string;
+}
+
+export class PasskeyAssertionRequest {
+  @ApiProperty({
+    description:
+      'Credential ID, as returned by navigator.credentials.get().toJSON().',
+  })
+  id: string;
+
+  @ApiProperty({
+    description: 'Base64url-encoded raw credential ID.',
+  })
+  rawId: string;
+
+  @ApiProperty({
+    description: 'Always "public-key".',
+    example: 'public-key',
+  })
+  type: string;
+
+  @ApiProperty({ type: PasskeyAssertionResponseData })
+  response: PasskeyAssertionResponseData;
+}
+
+export class PasskeyAllowedCredential {
+  @ApiProperty({
+    description: 'Base64url-encoded credential ID.',
+  })
+  id: string;
+
+  @ApiProperty({
+    description: 'Always "public-key".',
+    example: 'public-key',
+  })
+  type: string;
+
+  @ApiProperty({
+    description: 'Authenticator transports the credential supports.',
+    example: ['internal', 'hybrid'],
+    required: false,
+  })
+  transports?: string[];
+}
+
+/**
+ * WebAuthn request options - pass it to navigator.credentials.get({ publicKey })
+ * on the https://web.whatsapp.com origin.
+ */
+export class PasskeyChallenge {
+  @ApiProperty({
+    description: 'Base64url-encoded challenge to sign.',
+  })
+  challenge: string;
+
+  @ApiProperty({
+    description: 'How long the challenge is valid for, in milliseconds.',
+    example: 60000,
+  })
+  timeout: number;
+
+  @ApiProperty({
+    description: 'Relying party ID.',
+    example: 'web.whatsapp.com',
+  })
+  rpId: string;
+
+  @ApiProperty({ type: [PasskeyAllowedCredential] })
+  allowCredentials: PasskeyAllowedCredential[];
+
+  @ApiProperty({
+    example: 'required',
+  })
+  userVerification: string;
+
+  @ApiProperty({
+    description: 'WebAuthn extensions requested by WhatsApp.',
+    required: false,
+  })
+  extensions?: Record<string, any>;
+}
+
+export class PasskeyConfirmationResponse {
+  @ApiProperty({
+    description:
+      'The code the user must verify against the one shown on their phone.',
+    example: '1234',
+  })
+  code: string;
+}
@@ -45,6 +45,8 @@ export enum WAHASessionStatus {
  STOPPED = 'STOPPED',
  STARTING = 'STARTING',
  SCAN_QR_CODE = 'SCAN_QR_CODE',
+  PASSKEY_REQUIRED = 'PASSKEY_REQUIRED',
+  PASSKEY_CONFIRMATION_REQUIRED = 'PASSKEY_CONFIRMATION_REQUIRED',
  WORKING = 'WORKING',
  FAILED = 'FAILED',
 }
@@ -125,6 +125,18 @@ export class WASessionStatusBody {
  status: WAHASessionStatus;

  statuses: SessionStatusPoint[];
+
+  @ApiProperty({
+    required: false,
+    nullable: true,
+    description:
+      'Extra info that belongs to the current status, null for most of them.\n' +
+      'PASSKEY_REQUIRED - the WebAuthn challenge, ' +
+      'pass it to navigator.credentials.get({ publicKey: data }).\n' +
+      'PASSKEY_CONFIRMATION_REQUIRED - { code } - the code to verify against the phone.',
+    example: null,
+  })
+  data?: any;
 }

 export class WAHAWebhook<Payload = any> {
@@ -48,7 +48,7 @@ function getPlatform() {
 }

 export const VERSION: WAHAEnvironment = {
-  version: '2026.6.2',
+  version: '2026.7.1',
  engine: getEngineName(),
  tier: getWAHAVersion(),
  browser: getBrowser(),
@@ -2,11 +2,11 @@
  "waha": {
    "gows": {
      "repo": "devlikeapro/gows-plus",
-      "ref": "v1.0.42"
+      "ref": "v1.0.43"
    },
    "dashboard": {
      "repo": "devlikeapro/dashboard",
-      "ref": "47244c7d9202e0f4c1b23d12d45d5c208cd1184f"
+      "ref": "68a2e06035beed6ba04bd5dede49399d5478096d"
    }
  }
 }
@@ -7,7 +7,7 @@ __metadata:

 "@adiwajshing/baileys@github:devlikeapro/Baileys#fork-master-2026-04-28":
  version: 7.0.0-rc13
-  resolution: "@adiwajshing/baileys@https://github.com/devlikeapro/Baileys.git#commit=e45231f4a2b289ef739d5c4f74f51ca284f17069"
+  resolution: "@adiwajshing/baileys@https://github.com/devlikeapro/Baileys.git#commit=942ba050bab32436384e267ec2d8122ca434fba6"
  dependencies:
    "@cacheable/node-cache": "npm:^1.4.0"
    "@hapi/boom": "npm:^9.1.3"
@@ -32,7 +32,7 @@ __metadata:
      optional: true
    link-preview-js:
      optional: true
-  checksum: 10/b0c7dee01e1b39db8bd1e745fa77aa1e2b3a288fb88ebbe81eb2079e63dfd5d1fa8503b2d28f0eb063d1e6782fd7b97567311a33c6444a7129a86cc4c6ab2d3d
+  checksum: 10/44194fa66bd9b6f3ca1cac9aa2e0edc88a5c2537b6bf366c70f9ebcb4560888785af8c5f4f2f18851d5fd9f55f7421a319a0157c0c6ed8d72734e3c9a0946c0c
  languageName: node
  linkType: hard

@@ -1596,13 +1596,20 @@ __metadata:
  languageName: node
  linkType: hard

-"@img/sharp-win32-x64@npm:0.34.5, @img/sharp-win32-x64@npm:^0.34.5":
+"@img/sharp-win32-x64@npm:0.34.5":
  version: 0.34.5
  resolution: "@img/sharp-win32-x64@npm:0.34.5"
  conditions: os=win32 & cpu=x64
  languageName: node
  linkType: hard

+"@img/sharp-win32-x64@npm:^0.35.3":
+  version: 0.35.3
+  resolution: "@img/sharp-win32-x64@npm:0.35.3"
+  conditions: os=win32 & cpu=x64
+  languageName: node
+  linkType: hard
+
 "@inquirer/checkbox@npm:^4.1.2, @inquirer/checkbox@npm:^4.1.5":
  version: 4.1.8
  resolution: "@inquirer/checkbox@npm:4.1.8"
@@ -4617,15 +4624,15 @@ __metadata:
  languageName: node
  linkType: hard

-"@wppconnect-team/wppconnect@npm:^2.2.1":
-  version: 2.2.1
-  resolution: "@wppconnect-team/wppconnect@npm:2.2.1"
+"@wppconnect-team/wppconnect@github:wppconnect-team/wppconnect#master":
+  version: 2.2.3
+  resolution: "@wppconnect-team/wppconnect@https://github.com/wppconnect-team/wppconnect.git#commit=b467df8a5e0b00bbd794b5afc40c7fb1836e70a0"
  dependencies:
-    "@img/sharp-win32-x64": "npm:^0.34.5"
-    "@wppconnect/wa-js": "npm:^4.3.0"
+    "@img/sharp-win32-x64": "npm:^0.35.3"
+    "@wppconnect/wa-js": "npm:^4.4.1"
    "@wppconnect/wa-version": "npm:^1.5.3941"
    atob: "npm:^2.1.2"
-    axios: "npm:^1.16.1"
+    axios: "npm:^1.18.1"
    boxen: "npm:^5.1.2"
    catch-exit: "npm:^2.0.0"
    chalk: "npm:~4.1.2"
@@ -4648,7 +4655,7 @@ __metadata:
    rimraf: "npm:^3.0.2"
    sanitize-filename: "npm:^1.6.4"
    sharp: "npm:0.34.5"
-    tmp: "npm:^0.2.5"
+    tmp: "npm:^0.2.7"
    tree-kill: "npm:^1.2.2"
    winston: "npm:^3.19.0"
    ws: "npm:^8.21.0"
@@ -4657,21 +4664,21 @@ __metadata:
      optional: true
    fsevents:
      optional: true
-  checksum: 10/d7940928c2874ddd0e2412b0628d2750c2457bf9b08a8840e79de24e8666f792e2e7a78c0bc16c13c4ab870e7d37683ad1b08522fb9ea7da90f695e5b21cc044
+  checksum: 10/73baacfc22b9cbc40cbec4d010591b6614e28e7e5d95be0d8cbd378d8160f886cd2683c12a0ad8bbe8e073d8bbbc5d0cb785e316320e60e6e0178c36af779a99
  languageName: node
  linkType: hard

-"@wppconnect/wa-js@npm:^4.3.0":
-  version: 4.3.0
-  resolution: "@wppconnect/wa-js@npm:4.3.0"
-  checksum: 10/844e63b58b62d4057ab51f114b3f9b12e13637a026b6df50c5f53801181a3800065342c0f79478db10d43dfe96a6ec60bf9d8fab7840caaf94970a774572279d
+"@wppconnect/wa-js@github:wppconnect-team/wa-js#main":
+  version: 4.4.1
+  resolution: "@wppconnect/wa-js@https://github.com/wppconnect-team/wa-js.git#commit=1f7cc7e12e2cf9246a65bb8de4348055016f374e"
+  checksum: 10/8c6a370cfa6d4ec516664b71fd1b0e4300f3dc28433925cace8df7954c6b1781913c9993d573cb39cb78d363b3edf2f4d23255655d4cdd053296ffe4534c1170
  languageName: node
  linkType: hard

-"@wppconnect/wa-js@npm:^4.3.1":
-  version: 4.3.1
-  resolution: "@wppconnect/wa-js@npm:4.3.1"
-  checksum: 10/5515e347fadeb9221b02ac92bd00e42f5dd31ad4236a0ca812b34060d993c5384e30e1dabf8bac85016f49075a5374ea87b7e5eb345cfdeabaabd6eb7a0b9ba2
+"@wppconnect/wa-js@npm:^4.4.1":
+  version: 4.4.1
+  resolution: "@wppconnect/wa-js@npm:4.4.1"
+  checksum: 10/8c6a370cfa6d4ec516664b71fd1b0e4300f3dc28433925cace8df7954c6b1781913c9993d573cb39cb78d363b3edf2f4d23255655d4cdd053296ffe4534c1170
  languageName: node
  linkType: hard

@@ -13333,10 +13340,10 @@ __metadata:
  languageName: node
  linkType: hard

-"tmp@npm:^0.2.5":
-  version: 0.2.5
-  resolution: "tmp@npm:0.2.5"
-  checksum: 10/dd4b78b32385eab4899d3ae296007b34482b035b6d73e1201c4a9aede40860e90997a1452c65a2d21aee73d53e93cd167d741c3db4015d90e63b6d568a93d7ec
+"tmp@npm:^0.2.7":
+  version: 0.2.7
+  resolution: "tmp@npm:0.2.7"
+  checksum: 10/0a3bc90beb0c6275273c3475fb57e466eaab1c9c4a101d029ff62b18146ce136e7f75d09de34863d9f2c2a492751402508f9e028bc98eb34a1416195d4b15619
  languageName: node
  linkType: hard

@@ -13958,8 +13965,8 @@ __metadata:
    "@types/supertest": "npm:^2.0.8"
    "@types/user-agents": "npm:^1"
    "@types/ws": "npm:^8.5.4"
-    "@wppconnect-team/wppconnect": "npm:^2.2.1"
-    "@wppconnect/wa-js": "npm:^4.3.1"
+    "@wppconnect-team/wppconnect": "github:wppconnect-team/wppconnect#master"
+    "@wppconnect/wa-js": "github:wppconnect-team/wa-js#main"
    adm-zip: "npm:0.5.10"
    agentkeepalive: "npm:^4.5.0"
    async-lock: "npm:^1.4.1"
@@ -14141,7 +14148,7 @@ __metadata:

 "whatsapp-web.js@github:devlikeapro/whatsapp-web.js#fork-main-2026-06-26":
  version: 1.34.7
-  resolution: "whatsapp-web.js@https://github.com/devlikeapro/whatsapp-web.js.git#commit=c304d30169c739acedfbd770c5b206d91bb18c67"
+  resolution: "whatsapp-web.js@https://github.com/devlikeapro/whatsapp-web.js.git#commit=2daac8c8f83ddd7d92983bff8803dde970002a79"
  dependencies:
    archiver: "npm:7.0.1"
    fluent-ffmpeg: "npm:2.1.3"
@@ -14158,7 +14165,7 @@ __metadata:
      optional: true
    unzipper:
      optional: true
-  checksum: 10/f241c03ae23cb9021b40a94f1a2a74dec35ca834c8c9496faa69b6891da3be5c8fe3256793aa2449dff64db382d6891d2162dbd020426ff588613a05c55d88fc
+  checksum: 10/358d9c3e9da5f04d2db26706ba2cbf2a675efed47905d1b47319096b7739dd34e3ded8526ae5985da6b6fce9e9b931bc142a612db4af46b520bd9d55ad5ef6c9
  languageName: node
  linkType: hard
Author	SHA1	Message	Date
devlikepro	7e719d8894	[core] 2026.7.1 Release / WEBJS - chrome - amd64 - chrome (push) Waiting to run Details Release / WEBJS - chromium - amd64 - latest (push) Waiting to run Details Release / WEBJS - chromium - linux/arm64 - arm (push) Waiting to run Details Release / GOWS - none - amd64 - gows (push) Waiting to run Details Release / GOWS - none - linux/arm64 - gows-arm (push) Waiting to run Details Release / NOWEB - none - amd64 - noweb (push) Waiting to run Details Release / NOWEB - none - linux/arm64 - noweb-arm (push) Waiting to run Details	2026-07-15 20:04:29 +07:00
devlikepro	8faa3ca5a4	[core] Up dashboard	2026-07-15 20:04:29 +07:00
devlikepro	5dd8bf140d	[core] Up WEBJS	2026-07-15 20:04:29 +07:00
devlikepro	0501c37500	[core] WEBJS - add lid to /me	2026-07-15 20:04:29 +07:00
devlikepro	1496274a99	[core] Up WEBJS - fix _serialized id rename fix #2157 fix #2158 fix #2159 fix #2160 fix #2162	2026-07-15 20:04:29 +07:00
devlikepro	b6ba3951da	[core] Up NOWEB	2026-07-15 20:04:29 +07:00
devlikepro	a4a3dc93ad	[core] Up WPP - fix _serialized issues	2026-07-15 20:04:28 +07:00
devlikepro	57eb0e14ca	[core] Up dashboard - fix image emoji	2026-07-15 20:04:28 +07:00
devlikepro	d8970326be	[core] GOWS - fix "Session silently stops sending webhook events after <stream:error> (media ack)" - fix #2151	2026-07-15 20:04:28 +07:00
devlikepro	06412c2c1e	[core] Up WEBJS - fix sending image with "msg.avParams is not a function" fix #2149	2026-07-15 20:04:28 +07:00
devlikepro	0b39645c50	[core] Update Dashboard - passkey flow driven by session.status Picks up the UI side of the passkey rework: no more passkey.* events, PASSKEY_CONFIRMATION_REQUIRED handled, GET /auth/passkey/challenge.	2026-07-15 20:04:28 +07:00
devlikepro	76f8cc6f53	[core] Don't watch src/dashboard assets - fixes ENOSPC inotify limit on start:dev	2026-07-15 20:04:28 +07:00
devlikepro	ea79b1d886	[core] Passkey - collapse events into session.status, add GET /auth/passkey/challenge - Remove 'passkey.required' and 'passkey.confirmation.required' events. Passkey pairing is a session state, so it rides on 'session.status' instead - one new status value per pairing step WhatsApp adds, not one new event. - Add PASSKEY_CONFIRMATION_REQUIRED session status. - Add 'data' to the session.status payload - the extra info that belongs to the current status. PASSKEY_REQUIRED carries the WebAuthn challenge, PASSKEY_CONFIRMATION_REQUIRED carries { code }, null otherwise. - Base session gets setStatus(status, data); the plain 'status = value' setter delegates to it with no data, so the data clears itself as soon as the session moves on (WORKING, STOPPED, ...) with no extra bookkeeping. - REST: GET /auth/passkey/challenge (was GET /auth/passkey) returns the challenge object, GET /auth/passkey/confirmation returns { code }. Both throw 422 when nothing is pending. - MCP: auth-passkey-challenge, auth-passkey-submit, auth-passkey-confirmation, auth-passkey-confirm. - Drop the SkipHandoffUX auto-confirm branch - it was dead code. whatsmeow confirms on its own in that case and only emits passkey-confirmation for the manual one (qrchan.go). - Keep QR rotation from bouncing PASSKEY_CONFIRMATION_REQUIRED back to SCAN_QR_CODE, same as PASSKEY_REQUIRED.	2026-07-15 20:04:27 +07:00
devlikepro	e54604eb97	[core] rm settings.local.json	2026-07-15 20:04:27 +07:00
Berg Pinheiro	d267a29e87	[core] Update Dashboard - adds Passkey UI (extension-assisted + manual DevTools fallback)	2026-07-15 20:04:27 +07:00
Berg Pinheiro	d4625359e6	[core] Up GOWS - v1.0.43, adds SubmitPasskeyResponse/ConfirmPasskey RPCs	2026-07-15 20:04:27 +07:00
Berg Pinheiro	3618b92c3e	feat(passkey): Add Passkey (WebAuthn) session pairing - New engine step: gows emits passkey-request/passkey-confirmation, session status PASSKEY_REQUIRED, challenge stored and exposed via getPasskeyChallenge(). - REST: GET/POST /api/:session/auth/passkey, GET /api/:session/auth/passkey/confirmation, POST /api/:session/auth/passkey/confirm. - Webhooks: passkey.required (challenge) and passkey.confirmation.required (manual code case; most pairings auto-confirm server-side right after the assertion). - QR rotation no longer bounces PASSKEY_REQUIRED back to SCAN_QR_CODE.	2026-07-15 20:04:27 +07:00
devlikepro	982092cf2b	[core] MCP - do no share real api key for media and auth - qr or screenshot - fix #2146	2026-07-15 20:04:27 +07:00
devlikepro	6a452cd66e	[core] Up WPP. Use 'main' branch versions for wa-js and wppconnect	2026-07-15 20:04:27 +07:00
devlikepro	19625e38e9	[core] Up NOWEB. Fix chat history ordering fix #2139 .	2026-07-15 20:04:27 +07:00