firebase / firebase/firebase-admin-node

Misleading error message for THIRD_PARTY_AUTH_ERROR: raw "OAuth 2 access token" text surfaced instead of the APNs-specific message

Đang mở
#3,215 0 bình luận 0 reaction 0 người được giao Xem trên GitHub
api: messaging
Ngôn ngữ chính
TypeScript
Star
1.7k
Fork
419
Merge trung bình
3 ngày 10 giờ
Pull request đã merge (30 ngày)
16

Mô tả

## Summary

When FCM rejects an iOS send with `UNAUTHENTICATED`, the SDK surfaces the raw
gateway message ("...Expected OAuth 2 access token...") instead of its own
APNs-specific message, even though the error is classified as
`messaging/third-party-auth-error`. This sends developers down the wrong path
(debugging their own service-account / OAuth setup) when the real cause is a
downstream APNs credential problem.

## What happened

Sending to iOS device tokens, some tokens fail with:

```json
HTTP 401
{
"error": {
"code": 401,
"status": "UNAUTHENTICATED",
"message": "Request is missing required authentication credential. Expected OAuth 2 access token, login cookie or other valid authentication credential. ...",
"details": [{ "@type": "...FcmError", "errorCode": "THIRD_PARTY_AUTH_ERROR" }]
}
}
```

`error.code` is correctly `messaging/third-party-auth-error`, but `error.message`
is the raw *"Expected OAuth 2 access token"* text. That message strongly implies
a problem with the caller's own authentication (service account / access token),
so it's natural to spend several debugging cycles verifying OAuth, the service
account, token refresh, etc. — all of which are fine. The actual cause is on the
APNs side (e.g. an APNs auth key/certificate that doesn't cover the environment a
given token was minted in). The misleading message cost us multiple debugging
rounds before we inspected `details[].errorCode`.

## Root cause in the SDK

In `src/messaging/error.ts` on current `main`:

- `UNAUTHENTICATED` is mapped to `THIRD_PARTY_AUTH_ERROR` (line ~201), and there is
a clear canonical message for it (lines ~133–137):

> "A message targeted to an iOS device could not be sent because the required
> APNs SSL certificate was not uploaded or has expired. Check the validity of
> your development and production certificates."

- But the error message is assigned as (line ~260):

```ts
error.message = message || error.message;
```

Since the raw server `message` is truthy, it always wins, so the SDK's own
clearer, APNs-specific message is never shown for this code — the misleading
"OAuth 2 access token" text is surfaced instead.

## A second, smaller issue: the canonical message is dated

Even when shown, the canonical message only mentions an *"APNs SSL certificate"*
and *"development and production certificates"* — i.e. the `.p12` model. Modern
setups use `.p8` **APNs auth keys** (token-based auth), and Web Push uses VAPID
keys. For those, "certificate ... has expired / check your certificates" is
itself misleading, because there is no certificate involved.

## Suggested fix

1. For `third-party-auth-error`, prefer (or prepend) the SDK's canonical message
rather than the raw `UNAUTHENTICATED` gateway text, since that raw text
systematically points debugging in the wrong direction. The raw text can be
kept as "Raw server response: ..." (the SDK already appends that in some
paths).
2. Update the canonical message to cover APNs **auth keys (`.p8`)** and **Web Push
(VAPID)**, not just SSL certificates.

## Environment

- Verified against current `main`, `src/messaging/error.ts`.
- Reproduced on a real send to an affected iOS token (401 / UNAUTHENTICATED /
`details[].errorCode = THIRD_PARTY_AUTH_ERROR`).

Happy to open a PR along the lines of the suggested fix if this direction sounds right.

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Hướng nghiên cứu

Start in src/messaging/error.ts by reading the THIRD_PARTY_AUTH_ERROR mapping and the later error.message assignment. Confirm how the canonical APNs message is selected when the raw UNAUTHENTICATED response is present, then update the behavior and wording so APNs auth keys and Web Push VAPID credentials are covered. Done means the third-party-auth-error no longer surfaces the misleading raw OAuth guidance as its primary message.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Đánh giá

Công nghệ
typescript
Lĩnh vực
api, backend
Loại issue
Lỗi
Độ khó
3/5
Thời gian dự kiến
1-2 ngày
Mức độ hoạt động
Ít trao đổi
Độ rõ ràng
Khá rõ ràng
Mức phù hợp với người mới
70/100

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.