diff --git a/CHANGELOG.md b/CHANGELOG.md index 70470f658..4107b1048 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,8 @@ All notable HyperMeow changes are documented here. HyperMeow uses commit pseudo- ### Added +- Add call-link guest registration and login with one-call in-memory Signal stores. + - Opt-in concurrent WebSocket connections through `SocketConfig.RaceURLs`, with asynchronous loser cleanup and support for native and JS/WASM builds. See [connection options](README.md#connection-options). - `Client.DisablePostConnectPassiveIQ` to skip the post-connect passive/active IQ when the login payload already declares an active connection. - Persist hosted (coexistence) pairing as `store.Device.IsHosted` and report it on `events.PairSuccess.IsHosted`. SQL-backed stores upgrade to schema version 20, which adds `whatsmeow_device.is_hosted` (default `false`). @@ -20,6 +22,16 @@ All notable HyperMeow changes are documented here. HyperMeow uses commit pseudo- ### Fixed +- Keep provider response text out of displayed guest registration errors while retaining explicit diagnostics. + +- Bound guest Signal identities, sessions and sender keys before retaining peer data. + +- Redact malformed call-link and registration URLs from returned errors, including reflected redirect locations. + +- Reject guest registration redirects and bound guest prekey uploads and retained keys. + +- Preserve guest identity-reader trust and deletion fences during identity verification. + - Migrate an established hosted PN session when the peer starts sending from its hosted LID. SQL-backed migration uses literal address-prefix ranges so hosted underscores cannot select or delete another account's keys. - Use one Signal address for a hosted device 99 when decrypting its messages, sending to it and answering its retry receipts: `:99@hosted.lid` when the account's LID is known, otherwise `:99@hosted`. Hosted sessions no longer collide with a regular device 99, and sessions stored under the PN hosted address move to the LID hosted address. `MessageInfo.Sender` still reports hosted senders on the regular servers. - Redact shared-device and root secrets from app-state mutations in trace logs. diff --git a/README.md b/README.md index e5a0ef861..3f3332fa5 100644 --- a/README.md +++ b/README.md @@ -264,3 +264,52 @@ Disconnect and wait for owned work to settle before accepting replacement connection authority. `FrameSocket.SetOnDisconnect` replaces the callback under the socket lock; assign the legacy field only before connecting. These additions are unreleased until their reviewed main commit is adopted. + +## Call-link guests + +The `guest` package registers a one-time guest identity for a WhatsApp call +link and logs it in without pairing a phone. The identity lives only in +memory and only for one call: + +```go +import "github.com/polymorfa/hypermeow/guest" + +device := guest.NewDevice(nil) // fresh keys, in-memory stores +reg, err := guest.Register(ctx, device, guest.Request{ + InviteCode: "https://call.whatsapp.com/voice/TOKEN", + Name: "Ada", +}) +if err != nil { + return err +} +client, err := guest.NewClient(device, reg, nil) +if err != nil { + return err +} +err = client.Connect() +``` + +`NewClient` applies the guest identity before creating the client, sets the +guest login payload, turns off the post-connect passive IQ and uses the +registered browser's User-Agent. `Request.BaseURL` points registration at +another host, such as a simulator. A guest can only join the +call link it registered for. Messaging, groups and app state don't apply. + +Guest registration never follows HTTP redirects, including with a supplied +HTTP client. Point `BaseURL` directly at the intended registration service. +The in-memory guest store retains at most 1024 unconsumed prekeys, including +at most 64 retry keys. Upload attempts are at least one second apart; new +upload batches are generated at most once per minute. A failed upload can +retry its pending keys after the shorter interval. These local resource limits +return an error when reached and never evict an unconsumed key. + +Signal identities, sessions and sender keys share a limit of 1024 entries and +16 MiB of stored key/value data, in addition to the prekey limit. Each address +is limited to 512 bytes. Writes beyond those limits return an error without +evicting trusted identities. Replacing existing state or deleting identities +and sessions releases the corresponding capacity. These are local policies +for one-call guests, not WhatsApp server limits. + +Registration error strings omit provider response text. Typed `guest.Error` +fields and unwrapped causes remain available for explicit diagnostics and may +contain reflected request data; avoid logging them without redaction. diff --git a/guest/guest_test.go b/guest/guest_test.go new file mode 100644 index 000000000..9b70115c6 --- /dev/null +++ b/guest/guest_test.go @@ -0,0 +1,1027 @@ +// Copyright (c) 2026 Rajeh Taher +// +// Licensed under the MIT License. See LICENSE-MIT for details. + +package guest + +import ( + "bytes" + "context" + "encoding/base64" + "encoding/json" + "errors" + "fmt" + "math" + "net/http" + "net/http/httptest" + "net/url" + "strconv" + "strings" + "sync" + "sync/atomic" + "testing" + "time" + + "github.com/polymorfa/libsignal-protocol-go/ecc" + "github.com/polymorfa/libsignal-protocol-go/keys/identity" + "github.com/polymorfa/libsignal-protocol-go/keys/prekey" + "github.com/polymorfa/libsignal-protocol-go/protocol" + "github.com/polymorfa/libsignal-protocol-go/session" + "github.com/polymorfa/libsignal-protocol-go/util/optional" + + "github.com/polymorfa/hypermeow/proto/waWa6" + "github.com/polymorfa/hypermeow/store" + "github.com/polymorfa/hypermeow/types" +) + +func guestSignalUsage(t *testing.T, m *memoryStore) (int, int64) { + t.Helper() + m.mu.Lock() + defer m.mu.Unlock() + var size int64 + for address := range m.identities { + size += int64(len(address) + 32) + } + for address, value := range m.sessions { + size += int64(len(address)) + int64(len(value)) + } + for address, value := range m.senderKeys { + size += int64(len(address)) + int64(len(value)) + } + if size != m.signalBytes { + t.Fatalf("Signal byte accounting mismatch: tracked=%d stored=%d", m.signalBytes, size) + } + return len(m.identities) + len(m.sessions) + len(m.senderKeys), size +} + +func TestGuestSignalStoreRejectsOversizedAddresses(t *testing.T) { + ctx := context.Background() + address := strings.Repeat("1", maxGuestSignalAddressBytes+1) + for _, write := range []func(*memoryStore) error{ + func(m *memoryStore) error { return m.PutIdentity(ctx, address, [32]byte{1}) }, + func(m *memoryStore) error { _, err := m.EnsureIdentity(ctx, address, [32]byte{1}, 0); return err }, + func(m *memoryStore) error { _, err := m.IsTrustedIdentity(ctx, address, [32]byte{1}); return err }, + func(m *memoryStore) error { return m.PutSession(ctx, address, []byte{1}) }, + func(m *memoryStore) error { return m.PutManySessions(ctx, map[string][]byte{address: {1}}) }, + func(m *memoryStore) error { return m.PutSenderKey(ctx, address, "1:0", []byte{1}) }, + func(m *memoryStore) error { return m.PutSenderKey(ctx, "call", address, []byte{1}) }, + } { + m := newMemoryStore() + if err := write(m); !errors.Is(err, errGuestSignalLimit) { + t.Fatal("oversized Signal address was accepted") + } + if entries, size := guestSignalUsage(t, m); entries != 0 || size != 0 { + t.Fatal("rejected Signal address was retained") + } + } +} + +func TestGuestSignalStoreSharesEntryBudget(t *testing.T) { + m := newMemoryStore() + ctx := context.Background() + for i := range maxGuestSignalEntries - 2 { + if err := m.PutSession(ctx, strconv.Itoa(i)+":0", []byte{1}); err != nil { + t.Fatal(err) + } + } + if err := m.PutIdentity(ctx, "identity:0", [32]byte{1}); err != nil { + t.Fatal(err) + } + if err := m.PutSenderKey(ctx, "call", "sender:0", []byte{1}); err != nil { + t.Fatal(err) + } + if err := m.PutIdentity(ctx, "new:0", [32]byte{2}); !errors.Is(err, errGuestSignalLimit) { + t.Fatal("identity write bypassed the shared entry budget") + } + if _, err := m.EnsureIdentity(ctx, "new:1", [32]byte{2}, 0); !errors.Is(err, errGuestSignalLimit) { + t.Fatal("identity reader bypassed the shared entry budget") + } + if err := m.PutSession(ctx, "0:0", []byte{2}); err != nil { + t.Fatal("existing session could not update at the entry limit") + } + if err := m.PutIdentity(ctx, "identity:0", [32]byte{1}); err != nil { + t.Fatal("existing identity could not update at the entry limit") + } + if err := m.DeleteSession(ctx, "0:0"); err != nil { + t.Fatal(err) + } + if err := m.PutIdentity(ctx, "new:0", [32]byte{2}); err != nil { + t.Fatal("session deletion did not free shared capacity") + } + if err := m.DeleteIdentity(ctx, "new:0"); err != nil { + t.Fatal(err) + } + if err := m.PutSession(ctx, "replacement:0", []byte{3}); err != nil { + t.Fatal("identity deletion did not free shared capacity") + } + if entries, size := guestSignalUsage(t, m); entries != maxGuestSignalEntries || size > maxGuestSignalBytes { + t.Fatal("Signal store exceeded its shared budget") + } +} + +func TestGuestSignalStoreByteBudgetAndAtomicBatches(t *testing.T) { + m := newMemoryStore() + ctx := context.Background() + if err := m.PutSession(ctx, "1:0", make([]byte, maxGuestSignalBytes-len("1:0"))); err != nil { + t.Fatal(err) + } + if err := m.PutSenderKey(ctx, "call", "2:0", []byte{1}); !errors.Is(err, errGuestSignalLimit) { + t.Fatal("sender-key write bypassed the shared byte budget") + } + if err := m.PutSession(ctx, "1:0", make([]byte, maxGuestSignalBytes)); !errors.Is(err, errGuestSignalLimit) { + t.Fatal("oversized replacement was accepted") + } + if err := m.PutManySessions(ctx, map[string][]byte{"1:0": {1}, "2:0": make([]byte, maxGuestSignalBytes)}); !errors.Is(err, errGuestSignalLimit) { + t.Fatal("oversized batch was accepted") + } + if entries, size := guestSignalUsage(t, m); entries != 1 || size != maxGuestSignalBytes { + t.Fatal("rejected batch or replacement changed the store") + } + if err := m.PutManySessions(ctx, map[string][]byte{"1:0": {1}, "2:0": {2}}); err != nil { + t.Fatal("atomic shrink-and-add batch could not use freed capacity") + } + if err := m.DeleteAllSessions(ctx, "1"); err != nil { + t.Fatal(err) + } + if entries, size := guestSignalUsage(t, m); entries != 1 || size != 4 { + t.Fatal("session deletion retained byte usage") + } +} + +func TestGuestSignalStoreDeletionFreesIdentityBudget(t *testing.T) { + m := newMemoryStore() + ctx := context.Background() + for _, address := range []string{"123:0", "123:1", "1234:0"} { + if err := m.PutIdentity(ctx, address, [32]byte{1}); err != nil { + t.Fatal(err) + } + } + stored, generation, err := m.GetManyIdentities(ctx, []string{"123:0", "123:1"}) + if err != nil || len(stored) != 2 { + t.Fatal("stored identities were not available before deletion") + } + if err = m.DeleteAllIdentities(ctx, "123"); err != nil { + t.Fatal(err) + } + if trusted, err := m.EnsureIdentity(ctx, "123:0", [32]byte{2}, generation); err != nil || trusted { + t.Fatal("stale identity generation was accepted") + } + if entries, size := guestSignalUsage(t, m); entries != 1 || size != int64(len("1234:0")+32) { + t.Fatal("identity deletion retained budget or removed another user") + } + if err = m.DeleteIdentity(ctx, "1234:0"); err != nil { + t.Fatal(err) + } + if err = m.DeleteIdentity(ctx, "1234:0"); err != nil { + t.Fatal(err) + } + if entries, size := guestSignalUsage(t, m); entries != 0 || size != 0 { + t.Fatal("repeated identity deletion corrupted the budget") + } + if err = m.PutIdentity(ctx, strings.Repeat("1", maxGuestSignalAddressBytes), [32]byte{1}); err != nil { + t.Fatal("address at the permitted boundary was rejected") + } + guestSignalUsage(t, m) +} + +func TestGuestSignalStoreConcurrentWritesRespectBudget(t *testing.T) { + m := newMemoryStore() + ctx := context.Background() + var workers sync.WaitGroup + for worker := range 64 { + workers.Go(func() { + for offset := range 32 { + address := strconv.Itoa(worker*32+offset) + ":0" + var err error + switch offset % 3 { + case 0: + err = m.PutIdentity(ctx, address, [32]byte{1}) + case 1: + err = m.PutSession(ctx, address, []byte{1}) + case 2: + err = m.PutSenderKey(ctx, "call", address, []byte{1}) + } + if err != nil && !errors.Is(err, errGuestSignalLimit) { + t.Error("unexpected concurrent store error") + } + } + }) + } + workers.Wait() + if entries, size := guestSignalUsage(t, m); entries != maxGuestSignalEntries || size > maxGuestSignalBytes { + t.Fatal("concurrent stores exceeded their shared budget") + } +} + +func newGuestSignalExchange(t *testing.T) (*store.Device, *session.Cipher, uint32) { + t.Helper() + receiver, sender := NewDevice(nil), NewDevice(nil) + key, err := receiver.PreKeys.GenOnePreKey(context.Background()) + if err != nil { + t.Fatal(err) + } + bundle := prekey.NewBundle(receiver.RegistrationID, 0, optional.NewOptionalUint32(key.KeyID), + receiver.SignedPreKey.KeyID, ecc.NewDjbECPublicKey(*key.Pub), ecc.NewDjbECPublicKey(*receiver.SignedPreKey.Pub), + *receiver.SignedPreKey.Signature, identity.NewKey(ecc.NewDjbECPublicKey(*receiver.IdentityKey.Pub))) + address := protocol.NewSignalAddress("200", 0) + builder := session.NewBuilderFromSignal(sender, address, store.SignalProtobufSerializer) + if err = builder.ProcessBundle(context.Background(), bundle); err != nil { + t.Fatal("could not establish the synthetic Signal sender") + } + return receiver, session.NewCipher(builder, address), key.KeyID +} + +func TestGuestSignalBadMACCannotGrowIdentityStore(t *testing.T) { + for _, large := range []bool{false, true} { + t.Run("large="+strconv.FormatBool(large), func(t *testing.T) { + device, sender, preKeyID := newGuestSignalExchange(t) + serializer := store.SignalProtobufSerializer + message, err := sender.Encrypt(context.Background(), []byte("synthetic fixture")) + if err != nil { + t.Fatal("could not encrypt the synthetic prekey message") + } + outer, err := serializer.PreKeySignalMessage.Deserialize(message.Serialize()) + if err != nil { + t.Fatal("could not parse the synthetic prekey message") + } + inner, err := serializer.SignalMessage.Deserialize(outer.Message) + if err != nil || len(inner.Mac) == 0 { + t.Fatal("synthetic Signal message has no MAC") + } + inner.Mac[0] ^= 1 + outer.Message = serializer.SignalMessage.Serialize(inner) + bad, err := protocol.NewPreKeySignalMessageFromStruct(outer, serializer.PreKeySignalMessage, serializer.SignalMessage) + if err != nil { + t.Fatal("could not construct the bad-MAC fixture") + } + count := maxGuestSignalEntries + 8 + if large { + count = 4 + } + for i := range count { + name := strconv.Itoa(i + 1000) + if large { + name = strings.Repeat("1", 1<<20) + name + } + address := protocol.NewSignalAddress(name, 0) + builder := session.NewBuilderFromSignal(device, address, serializer) + if _, err = session.NewCipher(builder, address).DecryptMessage(context.Background(), bad); err == nil { + t.Fatal("bad-MAC message was accepted") + } + } + m := device.Identities.(*memoryStore) + entries, size := guestSignalUsage(t, m) + if entries > maxGuestSignalEntries || size > maxGuestSignalBytes || (large && entries != 0) { + t.Fatalf("bad-MAC messages retained excessive state: entries=%d bytes=%d", entries, size) + } + if len(m.sessions) != 0 { + t.Fatal("failed decrypt stored a Signal session") + } + if key, _ := device.PreKeys.GetPreKey(context.Background(), preKeyID); key == nil { + t.Fatal("failed decrypt consumed the prekey") + } + }) + } +} + +func TestGuestSignalValidExchangeStillWorks(t *testing.T) { + device, sender, preKeyID := newGuestSignalExchange(t) + serializer := store.SignalProtobufSerializer + address := protocol.NewSignalAddress("100", 0) + builder := session.NewBuilderFromSignal(device, address, serializer) + receiver := session.NewCipher(builder, address) + first, err := sender.Encrypt(context.Background(), []byte("first fixture")) + if err != nil { + t.Fatal("synthetic sender failed to encrypt") + } + plain, err := receiver.DecryptMessage(context.Background(), first.(*protocol.PreKeySignalMessage)) + if err != nil || !bytes.Equal(plain, []byte("first fixture")) { + t.Fatal("valid prekey message failed") + } + if key, _ := device.PreKeys.GetPreKey(context.Background(), preKeyID); key != nil { + t.Fatal("successful prekey decrypt did not consume the prekey") + } + reply, err := receiver.Encrypt(context.Background(), []byte("reply fixture")) + if err != nil { + t.Fatal("synthetic receiver failed to reply") + } + if _, err = sender.Decrypt(context.Background(), reply.(*protocol.SignalMessage)); err != nil { + t.Fatal("synthetic sender failed to decrypt the reply") + } + next, err := sender.Encrypt(context.Background(), []byte("next fixture")) + if err != nil { + t.Fatal("synthetic sender failed to encrypt the next message") + } + plain, err = receiver.Decrypt(context.Background(), next.(*protocol.SignalMessage)) + if err != nil || !bytes.Equal(plain, []byte("next fixture")) { + t.Fatal("established Signal session failed") + } +} + +// newTestDevice is a NewDevice with fixed registration and prekey IDs, so the +// key encodings can be checked byte for byte. +func newTestDevice() *store.Device { + device := NewDevice(nil) + device.RegistrationID = 0x01020304 + device.SignedPreKey = device.IdentityKey.CreateSignedPreKey(7) + return device +} + +func decodeKey(t *testing.T, value string) []byte { + t.Helper() + raw, err := base64.StdEncoding.DecodeString(strings.NewReplacer("-", "+", "_", "/").Replace(value)) + if err != nil { + t.Fatalf("decode %q: %v", value, err) + } + return raw +} + +func TestRegisterSendsKeysAndParsesLID(t *testing.T) { + device := newTestDevice() + var rawQuery string + var header http.Header + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.URL.Path != "/v2/guest_reg" || r.Method != http.MethodGet { + http.NotFound(w, r) + return + } + rawQuery, header = r.URL.RawQuery, r.Header.Clone() + _, _ = w.Write([]byte(`{"status":"ok","lid":"123456789","ent_access_token":"T","ent_canonical_fbid":"F"}`)) + })) + defer server.Close() + + reg, err := Register(context.Background(), device, Request{ + InviteCode: "https://call.whatsapp.com/voice/AbC123", Name: "Ada Lovelace", + BaseURL: server.URL + "/v2", HTTPClient: server.Client(), Language: "pt", PrivateInviteCode: "PRIV", + }) + if err != nil { + t.Fatalf("Register: %v", err) + } + if reg.LID != types.NewJID("123456789", types.HiddenUserServer) || reg.Name != "Ada Lovelace" || + reg.EntAccessToken != "T" || reg.EntCanonicalFBID != "F" { + t.Fatalf("registration = %+v", reg) + } + + if !strings.Contains(rawQuery, "guest_name=Ada%20Lovelace") { + t.Fatalf("guest_name must use %%20 for spaces: %s", rawQuery) + } + query, err := url.ParseQuery(rawQuery) + if err != nil { + t.Fatalf("parse query: %v", err) + } + if query.Get("lg") != "PT" || query.Get("lc") != "US" || query.Get("private_invite_code") != "PRIV" || + query.Get("mcc") != "310" || query.Get("mnc") != "999" || query.Get("tos_version") != "1" { + t.Fatalf("defaults and options = %v", query) + } + if query.Get("invite_code") != "AbC123" || query.Get("guest_type") != "guest_calling" { + t.Fatalf("invite = %q type = %q", query.Get("invite_code"), query.Get("guest_type")) + } + if got := decodeKey(t, query.Get("authkey")); string(got) != string(device.NoiseKey.Pub[:]) { + t.Fatal("authkey is not the noise public key") + } + if got := decodeKey(t, query.Get("e_ident")); string(got) != string(device.IdentityKey.Pub[:]) { + t.Fatal("e_ident is not the identity public key") + } + if got := decodeKey(t, query.Get("e_regid")); string(got) != "\x01\x02\x03\x04" { + t.Fatalf("e_regid = %x", got) + } + if got := decodeKey(t, query.Get("e_skey_id")); string(got) != "\x00\x00\x07" { + t.Fatalf("e_skey_id = %x", got) + } + if got := decodeKey(t, query.Get("e_keytype")); string(got) != "\x05" { + t.Fatalf("e_keytype = %x", got) + } + if got := decodeKey(t, query.Get("e_skey_sig")); string(got) != string(device.SignedPreKey.Signature[:]) { + t.Fatal("e_skey_sig is not the signed prekey signature") + } + if len(query.Get("id")) != 20 || query.Get("id") != query.Get("backup_token") { + t.Fatalf("id and backup_token must be the same 20 raw bytes") + } + if header.Get("User-Agent") != DefaultBrowser.UserAgent || header.Get("Origin") != DefaultOrigin || + header.Get("Referer") != DefaultOrigin+"/" { + t.Fatalf("headers = %v", header) + } +} + +func TestRegisterReportsRejections(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.WriteHeader(http.StatusForbidden) + _, _ = w.Write([]byte(`{"status":"fail","reason":"blocked","param":"invite_code","retry_after":30}`)) + })) + defer server.Close() + _, err := Register(context.Background(), newTestDevice(), Request{ + InviteCode: "TOKEN", Name: "Guest", BaseURL: server.URL, HTTPClient: server.Client(), + }) + var regErr *Error + if !errors.As(err, ®Err) || regErr.HTTPStatus != http.StatusForbidden || regErr.Reason != "blocked" || + regErr.Param != "invite_code" || regErr.RetryAfter != "30" { + t.Fatalf("error = %v", err) + } +} + +func TestRegisterResponseErrorsDoNotLogProviderText(t *testing.T) { + for _, kind := range []string{"status", "reason", "lid", "http"} { + t.Run(kind, func(t *testing.T) { + sent := make(chan string, 1) + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) { + echo := req.URL.RawQuery + select { + case sent <- echo: + default: + } + if kind == "http" { + conn, buffer, err := w.(http.Hijacker).Hijack() + if err != nil { + t.Error("could not prepare malformed HTTP response") + return + } + defer conn.Close() + _, _ = buffer.WriteString("REFLECTED " + echo + "\r\n\r\n") + _ = buffer.Flush() + return + } + body := map[string]string{"status": "fail", "reason": "blocked"} + switch kind { + case "status": + body["status"], body["reason"] = echo, "" + case "reason": + body["reason"] = echo + case "lid": + body["status"], body["lid"] = "ok", echo + } + _ = json.NewEncoder(w).Encode(body) + })) + defer server.Close() + _, err := Register(context.Background(), NewDevice(nil), Request{ + InviteCode: "PRIVATE_CALL_INVITE_TOKEN", Name: "Private Guest", BaseURL: server.URL, + }) + if err == nil { + t.Fatal("reflected failure response was accepted") + } + for _, displayed := range []string{err.Error(), fmt.Sprintf("%v", err), fmt.Sprintf("%+v", err), fmt.Errorf("registration attempt: %w", err).Error()} { + for _, sensitive := range []string{"PRIVATE_CALL_INVITE_TOKEN", "Private%20Guest", "authkey=", "invite_code=", "guest_name="} { + if strings.Contains(displayed, sensitive) { + t.Fatal("displayed registration error exposed provider text") + } + } + } + echo := <-sent + if kind == "status" || kind == "reason" { + var details *Error + if !errors.As(err, &details) || (kind == "status" && details.Status != echo) || (kind == "reason" && details.Reason != echo) { + t.Fatal("typed provider diagnostics were not retained") + } + } + }) + } +} + +func TestRegisterRejectsBadInput(t *testing.T) { + if _, err := Register(context.Background(), &store.Device{}, Request{InviteCode: "T", Name: "G"}); !errors.Is(err, ErrMissingKeys) { + t.Fatalf("missing keys error = %v", err) + } + if _, err := Register(context.Background(), newTestDevice(), Request{InviteCode: "T", Name: " "}); err == nil { + t.Fatal("a blank name must be rejected") + } + if _, err := ParseInviteCode("https://call.whatsapp.com/"); err == nil { + t.Fatal("a link without a token must be rejected") + } +} + +func TestRegisterRejectsMalformedLID(t *testing.T) { + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + _, _ = w.Write([]byte(`{"status":"ok","lid":"not-a-number"}`)) + })) + defer server.Close() + if _, err := Register(context.Background(), newTestDevice(), Request{ + InviteCode: "T", Name: "G", BaseURL: server.URL, HTTPClient: server.Client(), + }); err == nil { + t.Fatal("a malformed lid must be rejected") + } +} + +func TestNewDeviceHasWorkingMemoryStores(t *testing.T) { + device := NewDevice(nil) + if device.ID != nil || !device.Initialized || device.PreKeys == nil || device.Sessions == nil || + device.Identities == nil || device.PrivacyTokens == nil || device.LIDs == nil || device.Container == nil { + t.Fatalf("device stores = %+v", device) + } + ctx := context.Background() + if err := device.Save(ctx); err != nil { + t.Fatalf("Save must be a no-op: %v", err) + } + if err := device.Sessions.PutSession(ctx, "1.0", []byte("s")); err != nil { + t.Fatal(err) + } + if got, _ := device.Sessions.GetSession(ctx, "1.0"); string(got) != "s" { + t.Fatalf("session = %q", got) + } + preKeys, err := device.PreKeys.GetOrGenPreKeys(ctx, 3) + if err != nil || len(preKeys) != 3 { + t.Fatalf("prekeys = %v, %v", preKeys, err) + } + if count, _ := device.PreKeys.UploadedPreKeyCount(ctx); count != 0 { + t.Fatalf("unuploaded prekeys counted: %d", count) + } + if err = device.PreKeys.MarkPreKeysAsUploaded(ctx, preKeys[2].KeyID); err != nil { + t.Fatal(err) + } + if count, _ := device.PreKeys.UploadedPreKeyCount(ctx); count != 3 { + t.Fatalf("uploaded prekeys = %d", count) + } + if trusted, _ := device.Identities.IsTrustedIdentity(ctx, "1.0", [32]byte{1}); !trusted { + t.Fatal("an unknown identity must be trusted on first use") + } + _ = device.Identities.PutIdentity(ctx, "1.0", [32]byte{1}) + if trusted, _ := device.Identities.IsTrustedIdentity(ctx, "1.0", [32]byte{2}); trusted { + t.Fatal("a changed identity must not be trusted") + } +} + +func TestNewClientStartsAuthenticatedWithGuestPayload(t *testing.T) { + device := NewDevice(nil) + reg := &Registration{ + LID: types.NewJID("123456789", types.HiddenUserServer), Name: "Ada", Browser: DefaultBrowser, + } + cli, err := NewClient(device, reg, nil) + if err != nil { + t.Fatalf("NewClient: %v", err) + } + if device.ID == nil || *device.ID != reg.LID || device.LID != reg.LID || device.PushName != "Ada" { + t.Fatalf("device identity = %v / %v / %q", device.ID, device.LID, device.PushName) + } + if !cli.DisablePostConnectPassiveIQ || cli.UserAgent != DefaultBrowser.UserAgent || cli.GetClientPayload == nil { + t.Fatal("client was not configured for a guest login") + } + payload := cli.GetClientPayload() + if payload.GetUsername() != 123456789 || payload.GetDevice() != 0 || + payload.GetProduct() != waWa6.ClientPayload_WHATSAPP_LID || + payload.GetAccountType() != waWa6.ClientPayload_GUEST || + payload.GetPassive() || !payload.GetPull() || payload.GetPushName() != "Ada" || + payload.GetDevicePairingData() != nil { + t.Fatalf("payload = %v", payload) + } + if store.BaseClientPayload.AccountType != nil || store.BaseClientPayload.Product != nil { + t.Fatal("LoginPayload must not modify the shared base payload") + } + if _, err = NewClient(&store.Device{}, reg, nil); err == nil { + t.Fatal("a device without stores must be rejected") + } +} + +func TestRegisterRejectsPairedDeviceAndRedactsURL(t *testing.T) { + paired := NewDevice(nil) + id := types.NewJID("1", types.DefaultUserServer) + paired.ID = &id + if _, err := Register(context.Background(), paired, Request{InviteCode: "T", Name: "G"}); err == nil { + t.Fatal("a paired device must be rejected") + } + // Nothing listens on this port, so the request fails with a *url.Error. + _, err := Register(context.Background(), NewDevice(nil), Request{ + InviteCode: "SECRETTOKEN", Name: "Secret Name", BaseURL: "http://127.0.0.1:1", + }) + if err == nil || strings.Contains(err.Error(), "SECRETTOKEN") || strings.Contains(err.Error(), "Secret") { + t.Fatalf("error must not carry the request URL: %v", err) + } +} + +func TestRegisterRedactsMalformedRequestURLs(t *testing.T) { + for _, base := range []string{ + "http://127.0.0.1/%zz", + "http://127.0.0.1/\n", + "http://127.0.0.1:bad", + } { + t.Run(strconv.Quote(base), func(t *testing.T) { + _, err := Register(context.Background(), NewDevice(nil), Request{ + InviteCode: "PRIVATE_INVITE", Name: "Private Guest", BaseURL: base, + }) + if err == nil { + t.Fatal("malformed registration URL was accepted") + } + for _, sensitive := range []string{ + "PRIVATE_INVITE", "Private Guest", "Private%20Guest", "invite_code=", "guest_name=", "authkey=", "e_ident=", "e_skey_val=", + } { + if strings.Contains(err.Error(), sensitive) { + t.Fatal("request-construction error exposed registration data") + } + } + var urlErr *url.Error + if errors.As(err, &urlErr) { + t.Fatal("request-construction error retained the request URL") + } + }) + } +} + +func TestParseInviteCodeRedactsMalformedURL(t *testing.T) { + _, err := ParseInviteCode("https://call.whatsapp.com/voice/%zz/PRIVATE_INVITE") + if err == nil { + t.Fatal("malformed call link was accepted") + } + var escapeErr url.EscapeError + if !errors.As(err, &escapeErr) { + t.Fatal("call-link parse error lost its underlying cause") + } + if strings.Contains(err.Error(), "PRIVATE_INVITE") || strings.Contains(err.Error(), "call.whatsapp.com") { + t.Fatal("call-link parse error exposed the invite URL") + } +} + +type registrationErrorTransport struct{ err error } + +func (tr registrationErrorTransport) RoundTrip(*http.Request) (*http.Response, error) { + return nil, tr.err +} + +func TestRegisterRedactsNestedURLErrorsAndPreservesCause(t *testing.T) { + cause := &url.Error{Op: "parse", URL: "https://invalid/PRIVATE_INVITE", Err: context.Canceled} + client := &http.Client{Transport: registrationErrorTransport{err: cause}} + _, err := Register(context.Background(), NewDevice(nil), Request{ + InviteCode: "PRIVATE_INVITE", Name: "Private Guest", HTTPClient: client, + }) + if !errors.Is(err, context.Canceled) { + t.Fatal("registration error lost its underlying cause") + } + var urlErr *url.Error + if errors.As(err, &urlErr) || strings.Contains(err.Error(), "PRIVATE_INVITE") { + t.Fatal("registration error exposed a nested request URL") + } +} + +func TestGuestStoreReadsDoNotExposeMutableSessionState(t *testing.T) { + ctx := context.Background() + device := NewDevice(nil) + _ = device.Sessions.PutSession(ctx, "1.0", []byte("session")) + first, _ := device.Sessions.GetSession(ctx, "1.0") + first[0] = 'X' + many, _ := device.Sessions.GetManySessions(ctx, []string{"1.0", "missing"}) + many["1.0"][0] = 'Y' + again, _ := device.Sessions.GetSession(ctx, "1.0") + if string(again) != "session" { + t.Fatal("session changed through returned slice") + } + if _, exists := many["missing"]; exists { + t.Fatal("missing session returned as an existing key") + } + _ = device.SenderKeys.PutSenderKey(ctx, "g", "1.0", []byte("sender")) + sender, _ := device.SenderKeys.GetSenderKey(ctx, "g", "1.0") + sender[0] = 'X' + again, _ = device.SenderKeys.GetSenderKey(ctx, "g", "1.0") + if string(again) != "sender" { + t.Fatal("sender key changed through returned slice") + } +} +func TestGuestIdentityCannotReplaceAnAccount(t *testing.T) { + for _, jid := range []types.JID{types.NewJID("", types.HiddenUserServer), types.NewJID("0", types.HiddenUserServer), types.NewJID("invalid", types.HiddenUserServer), types.NewJID("123", types.DefaultUserServer)} { + if err := Apply(NewDevice(nil), &Registration{LID: jid}); err == nil { + t.Fatal("invalid guest identity accepted") + } + } + device := NewDevice(nil) + account := types.NewJID("123", types.DefaultUserServer) + device.ID = &account + if err := Apply(device, &Registration{LID: types.NewJID("456", types.HiddenUserServer)}); err == nil || *device.ID != account { + t.Fatal("existing account replaced") + } +} + +type redirectCountingTransport struct { + base http.RoundTripper + hits atomic.Int32 +} + +func (tr *redirectCountingTransport) RoundTrip(req *http.Request) (*http.Response, error) { + tr.hits.Add(1) + return tr.base.RoundTrip(req) +} + +func TestRegisterRejectsRedirects(t *testing.T) { + for _, status := range []int{301, 302, 303, 307, 308} { + for _, custom := range []bool{false, true} { + for _, relative := range []bool{false, true} { + t.Run(strconv.Itoa(status)+"/custom="+strconv.FormatBool(custom)+"/relative="+strconv.FormatBool(relative), func(t *testing.T) { + var targetHits atomic.Int32 + target := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + targetHits.Add(1) + _, _ = w.Write([]byte(`{"status":"ok","lid":"123456"}`)) + })) + defer target.Close() + origin := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) { + if req.URL.Path == "/internal-control" { + targetHits.Add(1) + _, _ = w.Write([]byte(`{"status":"ok","lid":"123456"}`)) + return + } + location := target.URL + "/internal-control" + if relative { + location = "/internal-control" + } + http.Redirect(w, req, location, status) + })) + defer origin.Close() + var client *http.Client + var transport *redirectCountingTransport + var callerPolicyCalled bool + if custom { + transport = &redirectCountingTransport{base: http.DefaultTransport} + client = &http.Client{Transport: transport, CheckRedirect: func(*http.Request, []*http.Request) error { + callerPolicyCalled = true + return nil + }} + } + _, err := Register(context.Background(), NewDevice(nil), Request{ + InviteCode: "PRIVATE_INVITE", Name: "Guest", BaseURL: origin.URL, HTTPClient: client, + }) + if err == nil || targetHits.Load() != 0 { + t.Fatalf("redirect accepted: err=%v, target hits=%d", err, targetHits.Load()) + } + for _, secret := range []string{"PRIVATE_INVITE", origin.URL, target.URL, "internal-control"} { + if strings.Contains(err.Error(), secret) { + t.Fatal("redirect error exposed a request URL or invite") + } + } + if custom { + if transport.hits.Load() != 1 || callerPolicyCalled { + t.Fatal("registration did not preserve the transport and enforce its own redirect policy") + } + _ = client.CheckRedirect(nil, nil) + if !callerPolicyCalled { + t.Fatal("Register mutated the caller's HTTP client") + } + } + }) + } + } + } +} + +func TestRegisterRejectsMalformedRedirectWithoutExposingLocation(t *testing.T) { + for _, status := range []int{301, 302, 303, 307, 308} { + t.Run(strconv.Itoa(status), func(t *testing.T) { + var hits atomic.Int32 + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, req *http.Request) { + hits.Add(1) + w.Header().Set("Location", "http://%zz/"+req.URL.RawQuery) + w.WriteHeader(status) + })) + defer server.Close() + _, err := Register(context.Background(), NewDevice(nil), Request{ + InviteCode: "PRIVATE_INVITE", Name: "Private Guest", BaseURL: server.URL, + }) + if err == nil || hits.Load() != 1 { + t.Fatal("malformed redirect was not rejected after one request") + } + for _, sensitive := range []string{"PRIVATE_INVITE", "Private%20Guest", "authkey=", "invite_code=", "guest_name="} { + if strings.Contains(err.Error(), sensitive) { + t.Fatal("malformed redirect error exposed registration data") + } + } + var regErr *Error + if !errors.As(err, ®Err) || regErr.HTTPStatus != status { + t.Fatal("redirect refusal lost the HTTP status") + } + }) + } +} + +func TestGuestPreKeyRetentionCannotExceedLimit(t *testing.T) { + m := newMemoryStore() + for i := 0; i < 1100; i++ { + if _, err := m.GenOnePreKey(context.Background()); err != nil { + break + } + } + if len(m.preKeys) != 64 { + t.Fatalf("retained %d unconsumed prekeys", len(m.preKeys)) + } +} + +func TestGuestPreKeyUploadRateLimitAfterAcknowledgement(t *testing.T) { + m := newMemoryStore() + ctx := context.Background() + batch, err := m.GetOrGenPreKeys(ctx, 50) + if err != nil { + t.Fatal(err) + } + if err = m.MarkPreKeysAsUploaded(ctx, batch[len(batch)-1].KeyID); err != nil { + t.Fatal(err) + } + if _, err = m.GetOrGenPreKeys(ctx, 50); err == nil { + t.Fatal("acknowledgement bypassed the local upload rate limit") + } + for _, key := range batch { + _ = m.RemovePreKey(ctx, key.KeyID) + } + if _, err = m.GetOrGenPreKeys(ctx, 50); err == nil { + t.Fatal("consumption bypassed the local upload rate limit") + } +} + +func TestGuestPreKeyRejectsOversizedBatch(t *testing.T) { + m := newMemoryStore() + for _, count := range []uint32{2048, math.MaxUint32} { + if _, err := m.GetOrGenPreKeys(context.Background(), count); err == nil || len(m.preKeys) != 0 { + t.Fatalf("oversized request allocated keys: err=%v, retained=%d", err, len(m.preKeys)) + } + } +} + +func TestGuestRetryPreKeyDoesNotMarkPendingKeysUploaded(t *testing.T) { + m := newMemoryStore() + ctx := context.Background() + if _, err := m.GetOrGenPreKeys(ctx, 3); err != nil { + t.Fatal(err) + } + if _, err := m.GenOnePreKey(ctx); err != nil { + t.Fatal(err) + } + if count, err := m.UploadedPreKeyCount(ctx); err != nil || count != 1 { + t.Fatalf("retry key changed pending upload state: count=%d, err=%v", count, err) + } +} + +func TestGuestPreKeysInitialBatchAndConsumedCapacity(t *testing.T) { + m := newMemoryStore() + now := time.Unix(1000, 0) + m.now = func() time.Time { return now } + ctx := context.Background() + initial, err := m.GetOrGenPreKeys(ctx, 812) + if err != nil || len(initial) != 812 { + t.Fatalf("initial batch: count=%d, err=%v", len(initial), err) + } + if err = m.MarkPreKeysAsUploaded(ctx, initial[len(initial)-1].KeyID); err != nil { + t.Fatal(err) + } + for range 4 { + now = now.Add(time.Minute) + batch, batchErr := m.GetOrGenPreKeys(ctx, 50) + if batchErr != nil || len(batch) != 50 { + t.Fatalf("normal batch: count=%d, err=%v", len(batch), batchErr) + } + if err = m.MarkPreKeysAsUploaded(ctx, batch[len(batch)-1].KeyID); err != nil { + t.Fatal(err) + } + } + now = now.Add(time.Minute) + if _, err = m.GetOrGenPreKeys(ctx, 50); err == nil || len(m.preKeys) != 1012 { + t.Fatalf("full store allocated a partial batch: count=%d, err=%v", len(m.preKeys), err) + } + // Consumed keys free capacity; unconsumed keys are never evicted. + for _, key := range initial[:50] { + if err = m.RemovePreKey(ctx, key.KeyID); err != nil { + t.Fatal(err) + } + } + if batch, batchErr := m.GetOrGenPreKeys(ctx, 50); batchErr != nil || len(batch) != 50 { + t.Fatalf("consumed capacity was not reusable: count=%d, err=%v", len(batch), batchErr) + } + if key, _ := m.GetPreKey(ctx, initial[50].KeyID); key != initial[50] { + t.Fatal("unconsumed prekey changed") + } + if key, _ := m.GetPreKey(ctx, initial[0].KeyID); key != nil { + t.Fatal("consumed prekey was retained") + } +} + +func TestGuestPreKeysRetryPreservesPendingBatch(t *testing.T) { + m := newMemoryStore() + now := time.Unix(1000, 0) + m.now = func() time.Time { return now } + ctx := context.Background() + pending, err := m.GetOrGenPreKeys(ctx, 3) + if err != nil { + t.Fatal(err) + } + if _, err = m.GenOnePreKey(ctx); err != nil { + t.Fatal(err) + } + for _, delta := range []time.Duration{-time.Second, 500 * time.Millisecond} { + now = time.Unix(1000, 0).Add(delta) + if _, err = m.GetOrGenPreKeys(ctx, 3); err == nil { + t.Fatal("early retry or clock rollback bypassed the rate limit") + } + } + now = time.Unix(1000, 0).Add(time.Second) + retry, err := m.GetOrGenPreKeys(ctx, 3) + if err != nil || len(retry) != len(pending) || len(m.preKeys) != 4 { + t.Fatalf("retry allocated another batch: err=%v, retained=%d", err, len(m.preKeys)) + } + for i := range pending { + if pending[i] != retry[i] { + t.Fatal("retry changed an unacknowledged key") + } + } + _ = m.MarkPreKeysAsUploaded(ctx, pending[2].KeyID) + _ = m.MarkPreKeysAsUploaded(ctx, pending[0].KeyID) + if count, _ := m.UploadedPreKeyCount(ctx); count != 4 { + t.Fatalf("older acknowledgement reversed upload state: %d", count) + } +} + +func TestGuestPreKeysConcurrentGeneratorsStayBounded(t *testing.T) { + m := newMemoryStore() + ctx := context.Background() + if _, err := m.GetOrGenPreKeys(ctx, 1010); err != nil { + t.Fatal(err) + } + var wg sync.WaitGroup + for range 64 { + wg.Add(1) + go func() { + defer wg.Done() + _, _ = m.GenOnePreKey(ctx) + }() + } + wg.Wait() + if len(m.preKeys) != 1024 { + t.Fatalf("concurrent generators retained %d keys", len(m.preKeys)) + } +} + +func TestGuestPreKeysDoNotWrapWireIDs(t *testing.T) { + m := newMemoryStore() + m.nextPreKey = 0xffffff + ctx := context.Background() + last, err := m.GenOnePreKey(ctx) + if err != nil || last.KeyID != 0xffffff { + t.Fatalf("last key: %v, %v", last, err) + } + if _, err = m.GenOnePreKey(ctx); err == nil || len(m.preKeys) != 1 { + t.Fatal("single-key generator wrapped the three-byte ID") + } + if _, err = m.GetOrGenPreKeys(ctx, 1); err == nil || len(m.preKeys) != 1 { + t.Fatal("batch generator wrapped the three-byte ID") + } +} + +func TestGuestRetryKeysCannotStarveNormalPreKeyUploads(t *testing.T) { + m := newMemoryStore() + now := time.Unix(1000, 0) + m.now = func() time.Time { return now } + ctx := context.Background() + initial, err := m.GetOrGenPreKeys(ctx, 812) + if err != nil { + t.Fatal(err) + } + _ = m.MarkPreKeysAsUploaded(ctx, initial[len(initial)-1].KeyID) + for range 212 { + _, _ = m.GenOnePreKey(ctx) + } + now = now.Add(time.Minute) + if batch, batchErr := m.GetOrGenPreKeys(ctx, 50); batchErr != nil || len(batch) != 50 { + t.Fatalf("retry-key exhaustion blocked a normal upload: count=%d, err=%v", len(batch), batchErr) + } +} + +func TestGuestFailedInitialUploadCanRetryPendingKeys(t *testing.T) { + m := newMemoryStore() + now := time.Unix(1000, 0) + m.now = func() time.Time { return now } + ctx := context.Background() + initial, err := m.GetOrGenPreKeys(ctx, 812) + if err != nil { + t.Fatal(err) + } + // No ACK: retry the same keys after a transient failure, not a new batch. + now = now.Add(30 * time.Second) + retry, err := m.GetOrGenPreKeys(ctx, 812) + if err != nil || len(retry) != len(initial) || len(m.preKeys) != 812 { + t.Fatalf("failed initial upload cannot retry safely: err=%v, count=%d", err, len(retry)) + } + for i := range initial { + if initial[i] != retry[i] { + t.Fatal("failed upload retry changed pending key material") + } + } +} + +func TestGuestPreKeyUploadAttemptsAreSerializedAndThrottled(t *testing.T) { + m := newMemoryStore() + now := time.Unix(1000, 0) + m.now = func() time.Time { return now } + ctx := context.Background() + var wg sync.WaitGroup + var success atomic.Int32 + for range 32 { + wg.Add(1) + go func() { + defer wg.Done() + if _, err := m.GetOrGenPreKeys(ctx, 50); err == nil { + success.Add(1) + } + }() + } + wg.Wait() + if success.Load() != 1 || len(m.preKeys) != 50 { + t.Fatalf("concurrent upload attempts escaped the gate: success=%d, keys=%d", success.Load(), len(m.preKeys)) + } + for range 10 { + now = now.Add(time.Second) + if pending, err := m.GetOrGenPreKeys(ctx, 50); err != nil || len(pending) != 50 || len(m.preKeys) != 50 { + t.Fatalf("pending retry grew state: err=%v, keys=%d", err, len(m.preKeys)) + } + if _, err := m.GetOrGenPreKeys(ctx, 50); err == nil { + t.Fatal("pending retry bypassed the unconditional upload interval") + } + } +} diff --git a/guest/login.go b/guest/login.go new file mode 100644 index 000000000..f5e741719 --- /dev/null +++ b/guest/login.go @@ -0,0 +1,94 @@ +// Copyright (c) 2026 Rajeh Taher +// +// Licensed under the MIT License. See LICENSE-MIT for details. + +package guest + +import ( + "errors" + "strconv" + + "google.golang.org/protobuf/proto" + + whatsmeow "github.com/polymorfa/hypermeow" + "github.com/polymorfa/hypermeow/proto/waWa6" + "github.com/polymorfa/hypermeow/store" + "github.com/polymorfa/hypermeow/types" + waLog "github.com/polymorfa/hypermeow/util/log" +) + +// Apply records the registered identity on the device: its ID and LID become +// the guest LID (device 0) and its push name the guest's display name. +func Apply(device *store.Device, reg *Registration) error { + if device == nil || reg == nil || reg.LID.Server != types.HiddenUserServer || reg.LID.Device != 0 { + return errors.New("guest: device and registration are required") + } + if value, err := strconv.ParseUint(reg.LID.User, 10, 64); err != nil || value == 0 { + return errors.New("guest: registration has no valid guest identity") + } + if device.ID != nil && *device.ID != reg.LID { + return errors.New("guest: device already belongs to another identity") + } + id := types.JID{User: reg.LID.User, Server: types.HiddenUserServer} + device.ID = &id + device.LID = id + device.PushName = reg.Name + return nil +} + +// LoginPayload builds the guest login ClientPayload for a device that Apply +// has prepared. +// +// It matches the WhatsApp Web guest bootstrap override (username = LID, +// device 0, product = WHATSAPP_LID, accountType = GUEST, pushName; +// WAWebGuestCoreBackendBootstrap.js:7-14 in public guest build 1053925913) +// and the active login it is merged into (passive false, pull true; +// WAWebGuestCoreBackendConsts.js:22-24, WAWebGetClientPayloadForLogin.js:14-17). +func LoginPayload(device *store.Device) (*waWa6.ClientPayload, error) { + if device == nil || device.ID == nil || device.ID.Server != types.HiddenUserServer || device.ID.Device != 0 { + return nil, errors.New("guest: device has no guest identity; call Apply first") + } + if value, err := strconv.ParseUint(device.ID.User, 10, 64); err != nil || value == 0 { + return nil, errors.New("guest: device has no valid guest identity") + } + payload := proto.Clone(store.BaseClientPayload).(*waWa6.ClientPayload) + payload.Username = proto.Uint64(device.ID.UserInt()) + payload.Device = proto.Uint32(uint32(device.ID.Device)) + payload.Product = waWa6.ClientPayload_WHATSAPP_LID.Enum() + payload.AccountType = waWa6.ClientPayload_GUEST.Enum() + payload.Passive = proto.Bool(false) + payload.Pull = proto.Bool(true) + payload.LidDbMigrated = proto.Bool(true) + payload.Lc = proto.Int32(1) + if device.PushName != "" { + payload.PushName = proto.String(device.PushName) + } + return payload, nil +} + +// NewClient returns a client that logs in as the registered guest. It applies +// reg to device first, so the client starts out authenticated, then sends the +// guest login payload, skips the post-connect passive IQ (the payload already +// says passive false, as WhatsApp Web does) and uses the registered browser's +// User-Agent for the WebSocket. Use a device from NewDevice. +func NewClient(device *store.Device, reg *Registration, log waLog.Logger) (*whatsmeow.Client, error) { + if device == nil || !device.Initialized || device.PreKeys == nil { + return nil, errors.New("guest: device has no stores; use guest.NewDevice") + } + if err := Apply(device, reg); err != nil { + return nil, err + } + if _, err := LoginPayload(device); err != nil { + return nil, err + } + cli := whatsmeow.NewClient(device, log) + cli.GetClientPayload = func() *waWa6.ClientPayload { + payload, _ := LoginPayload(device) + return payload + } + cli.DisablePostConnectPassiveIQ = true + if reg.Browser.UserAgent != "" { + cli.UserAgent = reg.Browser.UserAgent + } + return cli, nil +} diff --git a/guest/memory.go b/guest/memory.go new file mode 100644 index 000000000..e5f21f8af --- /dev/null +++ b/guest/memory.go @@ -0,0 +1,461 @@ +// Copyright (c) 2026 Rajeh Taher +// +// Licensed under the MIT License. See LICENSE-MIT for details. + +package guest + +import ( + "context" + "crypto/rand" + "encoding/binary" + "errors" + "sort" + "strings" + "sync" + "time" + + "github.com/polymorfa/hypermeow/store" + "github.com/polymorfa/hypermeow/types" + "github.com/polymorfa/hypermeow/util/keys" + waLog "github.com/polymorfa/hypermeow/util/log" +) + +// NewDevice returns a fresh, unpaired device for one guest session. Its keys +// are new and everything it stores lives in memory: Signal identities, +// sessions, prekeys and sender keys work normally, other state (app state, +// contacts, chat settings) is discarded, and saving the device does nothing. +// Nothing survives the process, which is what a one-time guest identity needs. +// The store retains at most 1024 unconsumed prekeys, including at most 64 retry +// keys. Upload attempts are at least one second apart, and new upload batches +// are generated at most once per minute. Signal identities, sessions and sender +// keys share a 1024-entry and 16 MiB key/value-data budget. Each address is at +// most 512 bytes. Excess writes fail without evicting existing state. These +// are local guest resource policies. +func NewDevice(log waLog.Logger) *store.Device { + if log == nil { + log = waLog.Noop + } + mem := newMemoryStore() + device := &store.Device{ + Log: log, + NoiseKey: keys.NewKeyPair(), + IdentityKey: keys.NewKeyPair(), + RegistrationID: randomRegistrationID(), + AdvSecretKey: randomBytes(32), + } + device.SignedPreKey = device.IdentityKey.CreateSignedPreKey(1) + device.SetAllStores(mem) + device.LIDs = mem + device.Container = mem + device.Initialized = true + return device +} + +func randomRegistrationID() uint32 { + var b [4]byte + _, _ = rand.Read(b[:]) + // Signal registration IDs are 14-bit and non-zero. + id := binary.BigEndian.Uint32(b[:]) & 0x3fff + if id == 0 { + id = 1 + } + return id +} + +func randomBytes(n int) []byte { + b := make([]byte, n) + _, _ = rand.Read(b) + return b +} + +// memoryStore keeps Signal state in memory and accepts everything else as a +// no-op through the embedded NoopStore (whose nil Error means success). +const ( + maxGuestPreKeys = 1024 + maxGuestRetryPreKeys = 64 + guestPreKeyUploadPeriod = time.Second + guestPreKeyGenerationPeriod = time.Minute + maxGuestPreKeyID = 0xffffff + maxGuestSignalAddressBytes = 512 + maxGuestSignalEntries = 1024 + maxGuestSignalBytes = 16 << 20 +) + +var ( + errGuestPreKeyLimit = errors.New("guest: prekey retention or ID limit reached") + errGuestPreKeyRate = errors.New("guest: prekey upload rate limit reached") + errGuestSignalLimit = errors.New("guest: Signal store resource limit reached") +) + +type memoryPreKey struct { + key *keys.PreKey + uploaded bool + retry bool +} + +type memoryStore struct { + *store.NoopStore + + mu sync.Mutex + signalBytes int64 + identities map[string][32]byte + identityDeleteGen uint64 + sessions map[string][]byte + preKeys map[uint32]memoryPreKey + nextPreKey uint32 + lastPreKeyUpload time.Time + lastPreKeyGeneration time.Time + now func() time.Time + senderKeys map[string][]byte +} + +var _ store.AllStores = (*memoryStore)(nil) +var _ store.DeviceContainer = (*memoryStore)(nil) + +func newMemoryStore() *memoryStore { + return &memoryStore{ + NoopStore: &store.NoopStore{}, + identities: make(map[string][32]byte), + sessions: make(map[string][]byte), + preKeys: make(map[uint32]memoryPreKey), + nextPreKey: 1, + now: time.Now, + senderKeys: make(map[string][]byte), + } +} + +func addressUser(address string) string { + user, _, _ := strings.Cut(address, ".") + user, _, _ = strings.Cut(user, ":") + return user +} + +func (m *memoryStore) reserveSignalLocked(entries int, size int64) error { + if entries > maxGuestSignalEntries-len(m.identities)-len(m.sessions)-len(m.senderKeys) || + size > maxGuestSignalBytes-m.signalBytes { + return errGuestSignalLimit + } + m.signalBytes += size + return nil +} + +func (m *memoryStore) putIdentityLocked(address string, key [32]byte) error { + if len(address) > maxGuestSignalAddressBytes { + return errGuestSignalLimit + } + if _, exists := m.identities[address]; !exists { + if err := m.reserveSignalLocked(1, int64(len(address)+len(key))); err != nil { + return err + } + } + m.identities[strings.Clone(address)] = key + return nil +} + +// IdentityStore + +func (m *memoryStore) PutIdentity(_ context.Context, address string, key [32]byte) error { + m.mu.Lock() + defer m.mu.Unlock() + return m.putIdentityLocked(address, key) +} + +func (m *memoryStore) DeleteAllIdentities(_ context.Context, phone string) error { + m.mu.Lock() + defer m.mu.Unlock() + m.identityDeleteGen++ + for address := range m.identities { + if addressUser(address) == phone { + m.signalBytes -= int64(len(address) + 32) + delete(m.identities, address) + } + } + return nil +} + +func (m *memoryStore) DeleteIdentity(_ context.Context, address string) error { + m.mu.Lock() + defer m.mu.Unlock() + m.identityDeleteGen++ + if _, exists := m.identities[address]; exists { + m.signalBytes -= int64(len(address) + 32) + } + delete(m.identities, address) + return nil +} + +func (m *memoryStore) IsTrustedIdentity(_ context.Context, address string, key [32]byte) (bool, error) { + if len(address) > maxGuestSignalAddressBytes { + return false, errGuestSignalLimit + } + m.mu.Lock() + defer m.mu.Unlock() + known, ok := m.identities[address] + return !ok || known == key, nil +} + +func (m *memoryStore) GetManyIdentities(_ context.Context, addresses []string) (map[string][32]byte, uint64, error) { + m.mu.Lock() + defer m.mu.Unlock() + out := make(map[string][32]byte, min(len(addresses), len(m.identities))) + for _, address := range addresses { + if key, ok := m.identities[address]; ok { + out[address] = key + } + } + return out, m.identityDeleteGen, nil +} + +func (m *memoryStore) EnsureIdentity(_ context.Context, address string, key [32]byte, deleteGeneration uint64) (bool, error) { + m.mu.Lock() + defer m.mu.Unlock() + if deleteGeneration != m.identityDeleteGen { + return false, nil + } + if len(address) > maxGuestSignalAddressBytes { + return false, errGuestSignalLimit + } + if known, ok := m.identities[address]; ok { + return known == key, nil + } + if err := m.putIdentityLocked(address, key); err != nil { + return false, err + } + return true, nil +} + +// SessionStore + +func (m *memoryStore) GetSession(_ context.Context, address string) ([]byte, error) { + m.mu.Lock() + defer m.mu.Unlock() + return append([]byte(nil), m.sessions[address]...), nil +} + +func (m *memoryStore) HasSession(_ context.Context, address string) (bool, error) { + m.mu.Lock() + defer m.mu.Unlock() + _, ok := m.sessions[address] + return ok, nil +} + +func (m *memoryStore) GetManySessions(_ context.Context, addresses []string) (map[string][]byte, error) { + m.mu.Lock() + defer m.mu.Unlock() + out := make(map[string][]byte, min(len(addresses), len(m.sessions))) + for _, address := range addresses { + if session, ok := m.sessions[address]; ok { + out[address] = append([]byte(nil), session...) + } + } + return out, nil +} + +func (m *memoryStore) PutSession(_ context.Context, address string, session []byte) error { + if len(address) > maxGuestSignalAddressBytes || len(session) > maxGuestSignalBytes { + return errGuestSignalLimit + } + m.mu.Lock() + defer m.mu.Unlock() + previous, exists := m.sessions[address] + entries, size := 0, int64(len(session))-int64(len(previous)) + if !exists { + entries, size = 1, size+int64(len(address)) + } + if err := m.reserveSignalLocked(entries, size); err != nil { + return err + } + m.sessions[strings.Clone(address)] = append([]byte(nil), session...) + return nil +} + +func (m *memoryStore) PutManySessions(_ context.Context, sessions map[string][]byte) error { + if len(sessions) > maxGuestSignalEntries { + return errGuestSignalLimit + } + m.mu.Lock() + defer m.mu.Unlock() + entries, size := 0, int64(0) + for address, session := range sessions { + if len(address) > maxGuestSignalAddressBytes || len(session) > maxGuestSignalBytes { + return errGuestSignalLimit + } + previous, exists := m.sessions[address] + size += int64(len(session)) - int64(len(previous)) + if !exists { + entries++ + size += int64(len(address)) + } + } + if err := m.reserveSignalLocked(entries, size); err != nil { + return err + } + for address, session := range sessions { + m.sessions[strings.Clone(address)] = append([]byte(nil), session...) + } + return nil +} + +func (m *memoryStore) DeleteAllSessions(_ context.Context, phone string) error { + m.mu.Lock() + defer m.mu.Unlock() + for address, session := range m.sessions { + if addressUser(address) == phone { + m.signalBytes -= int64(len(address)) + int64(len(session)) + delete(m.sessions, address) + } + } + return nil +} + +func (m *memoryStore) DeleteSession(_ context.Context, address string) error { + m.mu.Lock() + defer m.mu.Unlock() + if previous, exists := m.sessions[address]; exists { + m.signalBytes -= int64(len(address)) + int64(len(previous)) + } + delete(m.sessions, address) + return nil +} + +func (m *memoryStore) MigratePNToLID(context.Context, types.JID, types.JID) error { + return nil +} + +// PreKeyStore + +func (m *memoryStore) GetOrGenPreKeys(_ context.Context, count uint32) ([]*keys.PreKey, error) { + m.mu.Lock() + defer m.mu.Unlock() + if count == 0 { + return []*keys.PreKey{}, nil + } + if count > maxGuestPreKeys { + return nil, errGuestPreKeyLimit + } + now := m.now() + if !m.lastPreKeyUpload.IsZero() && now.Before(m.lastPreKeyUpload.Add(guestPreKeyUploadPeriod)) { + return nil, errGuestPreKeyRate + } + pending := make([]*keys.PreKey, 0, len(m.preKeys)) + for _, entry := range m.preKeys { + if !entry.uploaded { + pending = append(pending, entry.key) + } + } + sort.Slice(pending, func(i, j int) bool { return pending[i].KeyID < pending[j].KeyID }) + if len(pending) > int(count) { + pending = pending[:count] + } + needed := int(count) - len(pending) + if needed > 0 && !m.lastPreKeyGeneration.IsZero() && now.Before(m.lastPreKeyGeneration.Add(guestPreKeyGenerationPeriod)) { + return nil, errGuestPreKeyRate + } + if needed > maxGuestPreKeys-len(m.preKeys) || uint64(m.nextPreKey)+uint64(needed) > maxGuestPreKeyID+1 { + return nil, errGuestPreKeyLimit + } + m.lastPreKeyUpload = now + out := pending + for len(out) < int(count) { + key, err := m.newPreKeyLocked(false) + if err != nil { + return nil, err + } + out = append(out, key) + } + if needed > 0 { + m.lastPreKeyGeneration = now + } + return out, nil +} + +func (m *memoryStore) GenOnePreKey(_ context.Context) (*keys.PreKey, error) { + m.mu.Lock() + defer m.mu.Unlock() + return m.newPreKeyLocked(true) +} + +func (m *memoryStore) newPreKeyLocked(retry bool) (*keys.PreKey, error) { + if len(m.preKeys) >= maxGuestPreKeys || m.nextPreKey > maxGuestPreKeyID { + return nil, errGuestPreKeyLimit + } + if retry { + count := 0 + for _, entry := range m.preKeys { + if entry.retry { + count++ + } + } + if count >= maxGuestRetryPreKeys { + return nil, errGuestPreKeyLimit + } + } + key := keys.NewPreKey(m.nextPreKey) + m.preKeys[key.KeyID] = memoryPreKey{key: key, uploaded: retry, retry: retry} + m.nextPreKey++ + return key, nil +} + +func (m *memoryStore) GetPreKey(_ context.Context, id uint32) (*keys.PreKey, error) { + m.mu.Lock() + defer m.mu.Unlock() + return m.preKeys[id].key, nil +} + +func (m *memoryStore) RemovePreKey(_ context.Context, id uint32) error { + m.mu.Lock() + defer m.mu.Unlock() + delete(m.preKeys, id) + return nil +} + +func (m *memoryStore) MarkPreKeysAsUploaded(_ context.Context, upToID uint32) error { + m.mu.Lock() + defer m.mu.Unlock() + for id, entry := range m.preKeys { + if id <= upToID { + entry.uploaded = true + m.preKeys[id] = entry + } + } + return nil +} + +func (m *memoryStore) UploadedPreKeyCount(_ context.Context) (int, error) { + m.mu.Lock() + defer m.mu.Unlock() + count := 0 + for _, entry := range m.preKeys { + if entry.uploaded { + count++ + } + } + return count, nil +} + +// SenderKeyStore + +func (m *memoryStore) PutSenderKey(_ context.Context, group, user string, session []byte) error { + if len(group) > maxGuestSignalAddressBytes || len(user) > maxGuestSignalAddressBytes || len(session) > maxGuestSignalBytes { + return errGuestSignalLimit + } + m.mu.Lock() + defer m.mu.Unlock() + address := group + "\x00" + user + previous, exists := m.senderKeys[address] + entries, size := 0, int64(len(session))-int64(len(previous)) + if !exists { + entries, size = 1, size+int64(len(address)) + } + if err := m.reserveSignalLocked(entries, size); err != nil { + return err + } + m.senderKeys[address] = append([]byte(nil), session...) + return nil +} + +func (m *memoryStore) GetSenderKey(_ context.Context, group, user string) ([]byte, error) { + m.mu.Lock() + defer m.mu.Unlock() + return append([]byte(nil), m.senderKeys[group+"\x00"+user]...), nil +} diff --git a/guest/memory_identity_test.go b/guest/memory_identity_test.go new file mode 100644 index 000000000..fcc279f5f --- /dev/null +++ b/guest/memory_identity_test.go @@ -0,0 +1,125 @@ +// Copyright (c) 2026 Rajeh Taher +// +// Licensed under the MIT License. See LICENSE-MIT for details. + +package guest + +import ( + "context" + "testing" + + "github.com/polymorfa/hypermeow/store" +) + +func TestMemoryIdentityReaderPreservesTrustedKey(t *testing.T) { + ctx := context.Background() + device := NewDevice(nil) + reader := device.Identities.(store.IdentityKeyReader) + const address = "123:0" + _, generation, err := reader.GetManyIdentities(ctx, []string{address}) + if err != nil { + t.Fatal(err) + } + for _, test := range []struct { + name string + key [32]byte + trusted bool + }{ + {"first use", [32]byte{1}, true}, + {"matching identity", [32]byte{1}, true}, + {"conflicting identity", [32]byte{2}, false}, + {"original identity retained", [32]byte{1}, true}, + } { + t.Run(test.name, func(t *testing.T) { + trusted, ensureErr := reader.EnsureIdentity(ctx, address, test.key, generation) + if ensureErr != nil || trusted != test.trusted { + t.Fatalf("EnsureIdentity trusted=%v, error=%v, want %v", trusted, ensureErr, test.trusted) + } + }) + } + stored, _, err := reader.GetManyIdentities(ctx, []string{address}) + if err != nil || stored[address] != ([32]byte{1}) { + t.Fatalf("conflict replaced original identity: %v, %v", stored, err) + } +} + +func TestMemoryIdentityReaderRejectsFetchAfterDeletion(t *testing.T) { + for _, all := range []bool{false, true} { + name := "one identity" + if all { + name = "all identities" + } + t.Run(name, func(t *testing.T) { + ctx := context.Background() + device := NewDevice(nil) + reader := device.Identities.(store.IdentityKeyReader) + const address = "123:0" + _, generation, err := reader.GetManyIdentities(ctx, []string{address}) + if err != nil { + t.Fatal(err) + } + if all { + err = device.Identities.DeleteAllIdentities(ctx, "123") + } else { + err = device.Identities.DeleteIdentity(ctx, address) + } + if err != nil { + t.Fatal(err) + } + trusted, err := reader.EnsureIdentity(ctx, address, [32]byte{1}, generation) + if err != nil || trusted { + t.Fatalf("stale fetch trusted=%v, error=%v", trusted, err) + } + stored, freshGeneration, err := reader.GetManyIdentities(ctx, []string{address}) + if err != nil || len(stored) != 0 || freshGeneration == generation { + t.Fatalf("deleted identity restored: %v, generation=%d, error=%v", stored, freshGeneration, err) + } + trusted, err = reader.EnsureIdentity(ctx, address, [32]byte{2}, freshGeneration) + if err != nil || !trusted { + t.Fatalf("fresh fetch trusted=%v, error=%v", trusted, err) + } + }) + } +} + +func TestMemoryIdentityReaderConcurrentFetchesKeepOneKey(t *testing.T) { + ctx := context.Background() + device := NewDevice(nil) + reader := device.Identities.(store.IdentityKeyReader) + const address = "123:0" + _, generation, err := reader.GetManyIdentities(ctx, []string{address}) + if err != nil { + t.Fatal(err) + } + type result struct { + key [32]byte + trusted bool + err error + } + results := make(chan result, 2) + start := make(chan struct{}) + for _, key := range [][32]byte{{1}, {2}} { + go func() { + <-start + trusted, ensureErr := reader.EnsureIdentity(ctx, address, key, generation) + results <- result{key, trusted, ensureErr} + }() + } + close(start) + var winner [32]byte + accepted := 0 + for range 2 { + result := <-results + if result.err != nil { + t.Fatal(result.err) + } + if result.trusted { + accepted++ + winner = result.key + } + } + stored, _, err := reader.GetManyIdentities(ctx, []string{address}) + if err != nil || accepted != 1 || stored[address] != winner { + t.Fatalf("concurrent identities: accepted=%d, stored=%v, error=%v", accepted, stored, err) + } +} diff --git a/guest/register.go b/guest/register.go new file mode 100644 index 000000000..35ebde325 --- /dev/null +++ b/guest/register.go @@ -0,0 +1,404 @@ +// Copyright (c) 2026 Rajeh Taher +// +// Licensed under the MIT License. See LICENSE-MIT for details. + +// Package guest registers a one-time WhatsApp guest identity for a call link +// and logs it in without pairing a phone. +// +// A guest is what WhatsApp creates when someone opens a call link in a browser +// without an account. The identity is scoped to one call link and is not meant +// to be persisted or reused. +// +// Evidence status. The request and response follow the public WhatsApp Web +// guest bundle, build 1053925913 (observed 2026-11-10): +// WAWebGuestCoreBackendConsts.js:2-26 (endpoint and defaults), +// WAWebGuestCoreRegistrationNetworkRequest.js:3-50 (fields and encodings; the +// call-link form is register_with_link_token_and_push_name, invite_code plus +// guest_name) and WAWebGuestCoreRegistrationAction.js:18-48 (response fields +// and failure reason/param/retry_after). The login payload follows +// WAWebGuestCoreBackendBootstrap.js:7-14. The guest_type value guest_calling +// is from a captured call guest session; the calling caller is not in that +// bundle. None of this has been exercised against the server. +package guest + +import ( + "context" + "crypto/rand" + "encoding/base64" + "encoding/binary" + "encoding/json" + "errors" + "fmt" + "io" + "net/http" + "net/url" + "strconv" + "strings" + + "github.com/google/uuid" + + "github.com/polymorfa/hypermeow/store" + "github.com/polymorfa/hypermeow/types" +) + +// DefaultBaseURL is the registration host a browser guest uses. +const DefaultBaseURL = "https://v.whatsapp.net/v2" + +// DefaultOrigin is the page origin a browser guest registers from. +const DefaultOrigin = "https://web.whatsapp.com" + +// Browser describes the browser a guest registers and connects as. Keep it +// consistent with the WebSocket User-Agent; NewClient applies UserAgent to the +// client for that reason. +type Browser struct { + OSName string + OSVersion string + Name string + Version string + UserAgent string + AcceptLanguage string +} + +// DefaultBrowser is a current desktop Chrome on macOS. +var DefaultBrowser = Browser{ + OSName: "Mac OS", + OSVersion: "10.15.7", + Name: "Chrome", + Version: "142.0.0.0", + UserAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/142.0.0.0 Safari/537.36", + AcceptLanguage: "en-US,en;q=0.9", +} + +// Request is one guest registration for one call link. +type Request struct { + // InviteCode is the call-link token (not the full URL; see ParseInviteCode). + InviteCode string + // Name is the display name other participants see. + Name string + + // BaseURL overrides DefaultBaseURL, for example to point at a simulator. + BaseURL string + // Origin overrides DefaultOrigin for the Origin and Referer headers. + Origin string + // Browser overrides DefaultBrowser. + Browser *Browser + // Country and Language are the lc and lg parameters. Defaults: "US", "EN". + // Language is sent uppercased, as WhatsApp Web does. + Country string + Language string + // PrivateInviteCode is the optional private_invite_code parameter (the + // page's ic query value). + PrivateInviteCode string + // AccessSessionID groups this registration with the rest of the guest + // session. A random UUID is used when empty. + AccessSessionID string + // HTTPClient supplies the transport, timeout and cookie jar, with + // http.DefaultClient used when nil. Registration never follows redirects; + // the caller's client is not mutated. + HTTPClient *http.Client +} + +// Registration is a successful guest registration. +type Registration struct { + // LID is the guest's own identity, assigned at registration. + LID types.JID + // Name is the display name the guest registered with. + Name string + // EntAccessToken and EntCanonicalFBID are returned by the server and kept + // for callers that need them; nothing in this package uses them. + EntAccessToken string + EntCanonicalFBID string + // Browser is the browser the guest registered as. + Browser Browser +} + +// Error is a non-successful registration response. Provider fields are retained +// for explicit inspection and may contain sensitive request data. Error prints +// only the HTTP status. +type Error struct { + HTTPStatus int + Status string + Reason string + // Param names the request field the server objected to, when given. + Param string + // RetryAfter is the server's retry_after value as sent, when given. + RetryAfter string + Body string +} + +func (e *Error) Error() string { + return fmt.Sprintf("guest: registration failed: HTTP %d", e.HTTPStatus) +} + +// ErrMissingKeys is returned when the device has no registration key material. +var ErrMissingKeys = errors.New("guest: device is missing noise, identity or signed prekey material") + +// ParseInviteCode accepts a call-link token or a full call.whatsapp.com URL +// and returns the token. +func ParseInviteCode(tokenOrURL string) (string, error) { + value := strings.TrimSpace(tokenOrURL) + if value == "" { + return "", errors.New("guest: invite code is required") + } + if !strings.Contains(value, "/") { + return value, nil + } + parsed, err := url.Parse(value) + if err != nil { + return "", registrationFailure("parse call link", err) + } + segments := strings.Split(strings.Trim(parsed.Path, "/"), "/") + token := segments[len(segments)-1] + if token == "" { + return "", errors.New("guest: call link has no token") + } + return token, nil +} + +// Register registers device as a guest for one call link. Use a fresh device +// from NewDevice, then pass the result to NewClient. +func Register(ctx context.Context, device *store.Device, req Request) (*Registration, error) { + if device == nil || device.NoiseKey == nil || device.IdentityKey == nil || device.SignedPreKey == nil { + return nil, ErrMissingKeys + } + if device.ID != nil { + return nil, errors.New("guest: device is already paired; use a fresh device") + } + inviteCode, err := ParseInviteCode(req.InviteCode) + if err != nil { + return nil, err + } + name := strings.TrimSpace(req.Name) + if name == "" { + return nil, errors.New("guest: display name is required") + } + browser := DefaultBrowser + if req.Browser != nil { + browser = *req.Browser + } + endpoint, err := registrationURL(device, req, inviteCode, name, browser) + if err != nil { + return nil, err + } + httpReq, err := http.NewRequestWithContext(ctx, http.MethodGet, endpoint, nil) + if err != nil { + return nil, registrationFailure("build registration request", err) + } + origin := req.Origin + if origin == "" { + origin = DefaultOrigin + } + httpReq.Header.Set("User-Agent", browser.UserAgent) + httpReq.Header.Set("Accept", "*/*") + httpReq.Header.Set("Accept-Language", browser.AcceptLanguage) + httpReq.Header.Set("Origin", origin) + httpReq.Header.Set("Referer", origin+"/") + httpReq.Header.Set("Sec-Fetch-Site", "same-site") + httpReq.Header.Set("Sec-Fetch-Mode", "cors") + httpReq.Header.Set("Sec-Fetch-Dest", "empty") + client := req.HTTPClient + if client == nil { + client = http.DefaultClient + } + registrationClient := *client + transport := client.Transport + if transport == nil { + transport = http.DefaultTransport + } + registrationClient.Transport = registrationTransport{base: transport} + registrationClient.CheckRedirect = func(*http.Request, []*http.Request) error { + return errors.New("guest: registration redirects are not allowed") + } + resp, err := registrationClient.Do(httpReq) + if err != nil { + return nil, registrationFailure("send registration", err) + } + defer resp.Body.Close() + body, err := io.ReadAll(io.LimitReader(resp.Body, 64<<10)) + if err != nil { + return nil, registrationFailure("read registration response", err) + } + return parseRegistration(resp.StatusCode, body, name, browser) +} + +type registrationTransport struct{ base http.RoundTripper } + +func (tr registrationTransport) RoundTrip(req *http.Request) (*http.Response, error) { + if tr.base == nil { + return nil, errors.New("guest: registration transport is unavailable") + } + resp, err := tr.base.RoundTrip(req) + if err != nil || resp == nil { + return resp, err + } + // Client.Do parses Location before CheckRedirect, so reject at the transport. + switch resp.StatusCode { + case http.StatusMovedPermanently, http.StatusFound, http.StatusSeeOther, http.StatusTemporaryRedirect, http.StatusPermanentRedirect: + if resp.Body != nil { + _ = resp.Body.Close() + } + return nil, &Error{HTTPStatus: resp.StatusCode} + } + return resp, nil +} + +func (tr registrationTransport) CancelRequest(req *http.Request) { + if canceler, ok := tr.base.(interface{ CancelRequest(*http.Request) }); ok { + canceler.CancelRequest(req) + } +} + +func redactURLError(err error) error { + for { + var urlErr *url.Error + if !errors.As(err, &urlErr) { + return err + } + err = urlErr.Err + } +} + +type registrationFailureError struct { + operation string + cause error +} + +func (e *registrationFailureError) Error() string { return "guest: " + e.operation + " failed" } +func (e *registrationFailureError) Unwrap() error { return e.cause } + +func registrationFailure(operation string, cause error) error { + return ®istrationFailureError{operation: operation, cause: redactURLError(cause)} +} + +func registrationURL(device *store.Device, req Request, inviteCode, name string, browser Browser) (string, error) { + base := req.BaseURL + if base == "" { + base = DefaultBaseURL + } + country, language := req.Country, req.Language + if country == "" { + country = "US" + } + if language == "" { + language = "EN" + } + language = strings.ToUpper(language) + sessionID := req.AccessSessionID + if sessionID == "" { + sessionID = uuid.NewString() + } + deviceID := make([]byte, 20) + if _, err := rand.Read(deviceID); err != nil { + return "", fmt.Errorf("guest: generate device id: %w", err) + } + regID := make([]byte, 4) + binary.BigEndian.PutUint32(regID, device.RegistrationID) + keyID := make([]byte, 4) + binary.BigEndian.PutUint32(keyID, device.SignedPreKey.KeyID) + version := store.GetWAVersion() + + query := []string{ + param("mcc", "310"), + param("mnc", "999"), + param("lc", country), + param("lg", language), + param("tos_version", "1"), + param("device_id", uuid.NewString()), + param("access_session_id", sessionID), + param("authkey", encodeKey(device.NoiseKey.Pub[:])), + param("e_regid", encodeKey(regID)), + param("e_keytype", encodeKey([]byte{5})), + param("e_ident", encodeKey(device.IdentityKey.Pub[:])), + param("e_skey_id", encodeKey(keyID[1:])), + param("e_skey_val", encodeKey(device.SignedPreKey.Pub[:])), + param("e_skey_sig", encodeKey(device.SignedPreKey.Signature[:])), + param("os_name", browser.OSName), + param("os_version", browser.OSVersion), + param("browser", browser.Name), + param("browser_version", browser.Version), + param("web_build_version", "2."+strconv.FormatUint(uint64(version[1]), 10)+"."+strconv.FormatUint(uint64(version[2]), 10)), + param("guest_type", "guest_calling"), + param("invite_code", inviteCode), + param("guest_name", name), + } + if req.PrivateInviteCode != "" { + query = append(query, param("private_invite_code", req.PrivateInviteCode)) + } + query = append(query, + "id="+percentEncodeBytes(deviceID), + "backup_token="+percentEncodeBytes(deviceID), + ) + return strings.TrimRight(base, "/") + "/guest_reg?" + strings.Join(query, "&"), nil +} + +// param encodes like the browser's encodeURIComponent: spaces become %20, not +// "+". QueryEscape already escapes a literal "+" as %2B, so the swap is safe. +func param(key, value string) string { + return key + "=" + strings.ReplaceAll(url.QueryEscape(value), "+", "%20") +} + +// encodeKey is standard base64 with the URL-safe alphabet and padding kept, +// then query-escaped (the padding becomes %3D). +func encodeKey(value []byte) string { + return strings.NewReplacer("+", "-", "/", "_").Replace(base64.StdEncoding.EncodeToString(value)) +} + +// percentEncodeBytes escapes every byte outside RFC 3986's unreserved set as +// %XX, one byte at a time, so bytes >= 0x80 stay single bytes. +func percentEncodeBytes(value []byte) string { + const hex = "0123456789ABCDEF" + var out strings.Builder + for _, b := range value { + if ('a' <= b && b <= 'z') || ('A' <= b && b <= 'Z') || ('0' <= b && b <= '9') || + b == '-' || b == '_' || b == '.' || b == '~' { + out.WriteByte(b) + continue + } + out.WriteByte('%') + out.WriteByte(hex[b>>4]) + out.WriteByte(hex[b&0x0f]) + } + return out.String() +} + +type registrationResponse struct { + Status string `json:"status"` + Reason string `json:"reason"` + Param string `json:"param"` + RetryAfter json.RawMessage `json:"retry_after"` + LID string `json:"lid"` + EntAccessToken string `json:"ent_access_token"` + EntCanonicalFBID string `json:"ent_canonical_fbid"` +} + +func parseRegistration(httpStatus int, body []byte, name string, browser Browser) (*Registration, error) { + var parsed registrationResponse + jsonErr := json.Unmarshal(body, &parsed) + if httpStatus != http.StatusOK || jsonErr != nil || parsed.Status != "ok" { + return nil, &Error{ + HTTPStatus: httpStatus, Status: parsed.Status, Reason: parsed.Reason, + Param: parsed.Param, RetryAfter: strings.Trim(string(parsed.RetryAfter), `"`), + Body: truncate(string(body), 512), + } + } + user := strings.TrimSpace(parsed.LID) + if at := strings.IndexByte(user, '@'); at >= 0 { + user = user[:at] + } + if _, err := strconv.ParseUint(user, 10, 64); err != nil { + return nil, errors.New("guest: registration returned an invalid lid") + } + return &Registration{ + LID: types.NewJID(user, types.HiddenUserServer), + Name: name, + EntAccessToken: parsed.EntAccessToken, EntCanonicalFBID: parsed.EntCanonicalFBID, + Browser: browser, + }, nil +} + +func truncate(value string, limit int) string { + if len(value) <= limit { + return value + } + return value[:limit] +} diff --git a/preassigned_identity_test.go b/preassigned_identity_test.go new file mode 100644 index 000000000..a56e5dd53 --- /dev/null +++ b/preassigned_identity_test.go @@ -0,0 +1,57 @@ +// Copyright (c) 2026 Rajeh Taher +// +// Licensed under the MIT License. See LICENSE-MIT for details. + +package whatsmeow + +import ( + "context" + "testing" + "time" + + waBinary "github.com/polymorfa/hypermeow/binary" + "github.com/polymorfa/hypermeow/store" + "github.com/polymorfa/hypermeow/types" + "github.com/polymorfa/hypermeow/types/events" + "github.com/polymorfa/hypermeow/util/keys" +) + +// A device whose identity is assigned before NewClient, with working stores +// and no ADV account (the guest package's shape), must authenticate on +// connect success and dispatch Connected without touching a missing store. +func TestConnectSuccessForPreassignedIdentity(t *testing.T) { + lid := types.NewJID("123456789", types.HiddenUserServer) + device := &store.Device{ + NoiseKey: keys.NewKeyPair(), IdentityKey: keys.NewKeyPair(), RegistrationID: 1, + ID: &lid, LID: lid, + } + device.SignedPreKey = device.IdentityKey.CreateSignedPreKey(1) + noop := &store.NoopStore{} + device.SetAllStores(noop) + device.LIDs = noop + device.Container = noop + device.Initialized = true + + cli := NewClient(device, nil) + cli.DisablePostConnectPassiveIQ = true + connected := make(chan struct{}, 1) + cli.AddEventHandler(func(evt any) { + if _, ok := evt.(*events.Connected); ok { + select { + case connected <- struct{}{}: + default: + } + } + }) + cli.handleConnectSuccess(context.Background(), &waBinary.Node{ + Tag: "success", Attrs: waBinary.Attrs{"lid": lid, "t": "1700000000"}, + }) + if !cli.IsLoggedIn() { + t.Fatal("client with a preassigned identity ignored connect success") + } + select { + case <-connected: + case <-time.After(5 * time.Second): + t.Fatal("Connected was not dispatched") + } +}