search

Apollon77 / alexa-cookie

Library to generate a cookie including a csrf for alexa remote
MIT License
36 stars 13 forks source link

readme

alexa-cookie

NPM version Downloads Test and Release

Library to generate/retrieve a cookie including a csrf for alexa remote

Disclaimer

All product and company names or logos are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them or any associated subsidiaries! This personal project is maintained in spare time and has no business goal. ALEXA is a trademark of AMAZON TECHNOLOGIES, INC.

Description

This library can be used to get the cookies needed to access Amazon Alexa services from outside. It authenticates with Amazon and gathers all needed details. These details are returned in the callback. If the automatic authentication fails (which is more common case in the meantime because of security checks from amazon like a needed Captcha or because you enabled two factor authentication) the library can also setup a proxy server to allow the manual login and will catch the cookie by itself. Using this proxy you can enter needed 2FA codes or solve captchas and still do not need to trick around to get the cookie.

Starting with version 2.0 of this library the proxy approach was changed to be more "as the Amazon mobile Apps" which registers a device at Amazon and uses OAuth tokens to handle the automatic refresh of the cookies afterwards. This should work seamless. A cookie is valid for 14 days, so it is preferred to refresh the cookie after 5-13 days (please report if it should be shorter).

Troubleshooting for getting the cookie and tokens initially

If you still use the E-Mail or SMS based 2FA flow then this might not work. Please update the 2FA/OTP method in the amazon settings to the current process.

If you open the Proxy URL from a mobile device where also the Alexa App is installed on it might be that it do not work because Amazon might open the Alexa App. So please use a device or PC where the Alexa App is not installed

If you see a page that tells you that "alexa.amazon.xx is deprecated" and you should use the alexa app and with a QR code on it when you enter the Proxy URL" then this means that you call the proxy URL with a different IP/Domainname then the one you entered in the "proxy own IP" settings or you adjusted the IP shown in the Adapter configuration. The "proxy own IP" setting needs to match the IP/Domainname you use to call the proxy URL!

Example:

See example folder!

Usage

Special note for callback return for parameter result:

When automatic cookie retrieval worked (uncommon)

If the library was able to automatically log you in and get the cookie (which is the more uncommon case in the meantime) the object returned will contain keys "cookie" and "csrf" to use.

When proxy was used (preferred and more common case)

If the Proxy was used (or especially when "proxyOnly" was set in options) then result is a object with much more data.

Important for the further interaction with alexa are the keys "localCookie" (same as "cookie" above) and pot. "crsf". I decided for different keys to make sure the next lines are understood by the developer ...

Please store the returned object and provide this object in all subsequent calls to the library in the options object in key "formerRegistrationData" as shown in the example!

If you not do this a new device is created each time the proxy is used which can end up in having many unused devices (such a device is like a mobile phone where you use the Alexa App with).

Please use the new method "refreshAlexaCookie" to refresh the cookie data. It takes the same options object as the other method and requires the key "formerRegistrationData". It returns an updated object will all data as above. Please also store this and provide for subsequent calls!

Since 4.0.0 of this library a new key called "macDms" is also returned when cookies are generated or refreshed. This is (right now Oct 2021) needed to use the Push Connection (alexa-remote library). Better strt also persisting this field, might be needed more later on.

Thanks:

A big thanks go to soef for the initial version of this library and to many other community users to support in finding out what Amazon changes here and there.

Partly based on Amazon Alexa Remote Control (PLAIN shell) and alexa-remote-control and the the Proxy idea from OpenHab-Addon. Also the new way to refresh cookie and all needed changes were developed in close cooperation with @mgeramb Thank you for that work.

Changelog:

5.0.2 (2023-11-25)

5.0.1 (2023-11-24)

5.0.0 (2023-09-08)

4.2.0 (2023-08-08)

4.1.3 (2022-08-03)

4.1.2 (2022-07-19)

4.1.1 (2022-07-18)

4.1.0 (2022-07-18)

4.0.3 (2022-07-06)

4.0.2 (2022-06-30)

4.0.1 (2021-10-11)

4.0.0 (2021-10-11)

3.4.3 (2021-04-18)

3.4.2 (2020-11-23)

3.4.1 (2020-07-24)

3.4.0 (2020-07-19)

3.3.3 (2020-07-16)

3.3.2 (2020-07-15)

3.3.1 (2020-07-15)

3.3.0 (2020-07-13)

3.2.1 (2020-06-17)

3.2.0 (2020-06-15)

3.0.3 (2020.03.16)

3.0.2 (2019.12.27)

3.0.1 (2019.12.24)

3.0.0

2.1.0

2.0.1

2.0.0

1.0.3

1.0.2

1.0.1

1.0.0

0.2.x

0.1.x

0.0.x