steam-session
Advanced tools
This module enables you to negotiate Steam tokens by authenticating with the Steam login server. This is for use with your own accounts. This is not to be used to authenticate other Steam users or to gain access to their accounts. For that use-case, please use the Steam OpenID service (you may want to consider using steam-signin) and the many available WebAPIs.
Node.js v12.22.0 or later is required to use this module.
Logging into Steam is a two-step process.
startWithCredentials to start a login session using your account credentialsstartWithQR to start a QR login sessionSee the examples directory on GitHub for example code.
When using CommonJS (require()), steam-session exports an object. When using ES6 modules (import), steam-session does
not offer a default export and you will need to import specific things.
The majority of steam-session consumers will only care about enums, and the LoginSession
and potentially LoginApprover classes.
const {EAuthSessionSecurityHistory} = require('steam-session');
import {EAuthSessionSecurityHistory} from 'steam-session';
const {EAuthSessionGuardType} = require('steam-session');
import {EAuthSessionGuardType} from 'steam-session';
Contains the possible auth session guards.
const {EAuthTokenPlatformType} = require('steam-session');
import {EAuthTokenPlatformType} from 'steam-session';
Contains the different platform types that can be authenticated for. You should specify the correct platform type when
you instantiate a LoginSession object.
Audiences present in tokens issued for the different platform types:
SteamClient - ['web', 'client']WebBrowser - ['web']MobileApp - ['web', 'mobile']const {EResult} = require('steam-session');
import {EResult} from 'steam-session';
Contains possible result codes. This is a very large enum that used throughout Steam, so most values in this enum will not be relevant when authenticating.
const {ESessionPersistence} = require('steam-session');
import {ESessionPersistence} from 'steam-session';
Contains possible persistence levels for auth sessions.
It's possible to define a custom transport to be used when interacting with the Steam login server. The default transport
used to interact with the Steam login server is chosen depending on your provided EAuthTokenPlatformType.
For the SteamClient platform type, a WebSocketCMTransport will be used to communicate with a CM server using a WebSocket.
For other platform types, a WebApiTransport will be used to interact with the Steam login server using api.steampowered.com.
It is very likely that you won't need to mess with this.
Everything in this category is TypeScript interfaces, so even if you're implementing a custom transport, you don't need these unless you're using TypeScript.
const {ITransport, ApiRequest, ApiResponse} = require('steam-session');
import {ITransport, ApiRequest, ApiResponse} from 'steam-session';
const {LoginSession} = require('steam-session');
import {LoginSession} from 'steam-session';
The LoginSession class is the primary way to interact with steam-session.
Read-only. A SteamID instance containing the SteamID for the
currently-authenticated account. Populated immediately after startWithCredentials
resolves, or immediately after accessToken or refreshToken are set (meaning that
this is always populated when authenticated fires).
A number specifying the time, in milliseconds, before a login attempt will timeout. The timer begins
after polling begins.
If you attempt to set this property after polling has already been emitted, an Error will be thrown since
setting this property after that point has no effect.
Read-only. A string containing your account name. This is populated just before the authenticated
event is fired.
A string containing your access token. As of 2023-09-12, Steam does not return an access token in response to
successful authentication, so this won't be set when the authenticated event is fired. This will be set
after you call refreshAccessToken() or renewRefreshToken().
Also, since getWebCookies() calls refreshAccessToken() internally for EAuthTokenPlatformType
SteamClient or MobileApp, this will also be set after calling getWebCookies() for those platform types.
You can also assign an access token to this property if you already have one, although at present that wouldn't do anything useful.
Setting this property will throw an Error if:
startWithCredentials and you set it to a token that doesn't belong to the same account, orrefreshToken and you set this to a token that doesn't belong to the same account as the refresh tokenAccess tokens can't be used for much. You can use them with a few undocumented WebAPIs like IFriendsListService/GetFriendsList by passing the access token as an access_token query string parameter. For example:
https://api.steampowered.com/IFriendsListService/GetFriendsList/v1/?access_token=eyAidHlwIjogIkpXVCIsICJhbGciOiAiRWREU0EiIH0.eyJpc3MiOiJ...
As of time of writing (2023-04-24), it appears that you can also use access tokens with regular published API methods, for example:
https://api.steampowered.com/ISteamUserStats/GetNumberOfCurrentPlayers/v1/?appid=440&access_token=eyAidHlwIjogIkpXVCIsICJhbGciOiAiRWREU0EiIH0.eyJpc3MiOiJ...
A string containing your refresh token. This is populated just before the authenticated event is
fired. You can also assign a refresh token to this property if you already have one.
Setting this property will throw an Error if:
startWithCredentials and you set it to a token that doesn't belong to the same account, oraccessToken and you set this to a token that doesn't belong to the same account as the access tokenRead-only. A string containing your Steam Guard machine token. This is populated when you pass a steamGuardMachineToken to
startWithCredentials, or just before the steamGuardMachineToken
event is emitted.
platformType - A value from EAuthTokenPlatformType. You should set this to the
appropriate platform type for your desired usage.options - An object with zero or more of these properties:
userAgent - Pass a user-agent string if you want to override the default user-agent.
This is only effective when using EAuthTokenPlatformType.WebBrowser.transport - An ITransport instance, if you need to specify a custom transport.
If omitted, defaults to a WebSocketCMTransport instance for SteamClient platform types, and a
WebApiTransport instance for all other platform types. In all likelihood, you don't need to use this.localAddress - A string containing the local IP address you want to use. For example, 11.22.33.44httpProxy - A string containing a URI for an HTTP proxy. For example, http://user:pass@1.2.3.4:80socksProxy - A string containing a URI for a SOCKS proxy. For example, socks5://user:pass@1.2.3.4:1080agent - An https.Agent instance to use for requests. If omitted, a new https.Agent will be created internally.machineId - Only applicable when using EAuthTokenPlatformType.SteamClient. Pass a Buffer containing a valid
Steam machine ID. Pass true to have steam-session internally generate a machine ID using the same format that
steam-user uses. Pass false, null, or omit
this property to not send a machine ID (not sending a machine ID may cause problems in the future).machineFriendlyName - Only applicable when using EAuthTokenPlatformType.SteamClient. Pass a string containing
the machine name that you want to report to Steam when logging on. If omitted, a machine name will automatically
be generated in the format DESKTOP-ABCDEFG. Auto-generated machine IDs are always the same on the same machine
(it's based on the hash of your actual machine's hostname)You can only use one of localAddress, httpProxy, socksProxy or agent at the same time. If you try to use more
than one of them, an Error will be thrown.
If you specify a custom transport, then you are responsible for handling proxy or agent usage in your transport.
Constructs a new LoginSession instance. Example usage:
import {LoginSession, EAuthTokenPlatformType} from 'steam-session';
let session = new LoginSession(EAuthTokenPlatformType.WebBrowser);
details - An object with these properties:
accountName - Your account's login name, as a stringpassword - Your account's password, as a stringpersistence - Optional. A value from ESessionPersistence. Defaults to Persistent.steamGuardMachineToken - Optional. If you have a valid Steam Guard machine token, supplying it here will allow
you to bypass email code verification.steamGuardCode - Optional. If you have a valid Steam Guard code (either email or TOTP), supplying it here will
attempt to use it during login.Starts a new login attempt using your account credentials. Returns a Promise.
If you're logging in with EAuthTokenPlatformType.SteamClient, you can supply a Buffer containing the SHA-1 hash of
your sentry file for steamGuardMachineToken. For example:
import {createHash} from 'crypto';
import {readFileSync} from 'fs';
import {LoginSession, EAuthTokenPlatformType} from 'steam-session';
let hash = createHash('sha1');
hash.update(readFileSync('ssfn1234567890'));
let buffer = hash.digest(); // buffer contains a Buffer
let session = new LoginSession(EAuthTokenPlatformType.SteamClient);
session.startWithCredentials({
accountName: 'johndoe',
password: 'h3ll0wor1d',
steamGuardMachineToken: buffer
});
If you supply a steamGuardCode here and you're using email-based Steam Guard, Steam will send you a new Steam Guard
email if you're using EAuthTokenPlatformType = SteamClient or MobileApp. You would ideally keep your LoginSession active
that generated your first email, and pass the code using submitSteamGuardCode instead
of creating a new LoginSession and supplying the code to startWithCredentials.
On failure, the Promise will be rejected with its message being equal to the string representation of an EResult
value. There will also be an eresult property on the Error object equal to the numeric representation of the relevant
EResult value. For example:
Error: InvalidPassword
eresult: 5
On success, the Promise will be resolved with an object containing these properties:
actionRequired - A boolean indicating whether action is required from you to continue this login attempt.
If false, you should expect for authenticated to be emitted shortly.validActions - If actionRequired is true, this is an array of objects indicating which actions you could take to
continue this login attempt. Each object has these properties:
type - A value from EAuthSessionGuardTypedetail - An optional string containing more details about this guard option. Right now, the only known use for
this is that it contains your email address' domain for EAuthSessionGuardType.EmailCode.Here's a list of which guard types might be present in this method's response, and how you should proceed:
EmailCode: An email was sent to you containing a code (detail contains your email address' domain, e.g. gmail.com).
You should get that code and either call submitSteamGuardCode, or create a new
LoginSession and supply that code to the steamGuardCode property when calling startWithCredentials.DeviceCode: You need to supply a TOTP code from your mobile authenticator (or by using steam-totp).
Get that code and either call submitSteamGuardCode, or create a new LoginSession
and supply that code to the steamGuardCode property when calling startWithCredentials.DeviceConfirmation: You need to approve the confirmation prompt in your Steam mobile app. If this guard type is
present, polling will start and loginTimeout will be in effect.EmailConfirmation: You need to approve the confirmation email sent to you. If this guard type is
present, polling will start and loginTimeout will be in effect.Note that multiple guard types might be available; for example both DeviceCode and DeviceConfirmation can be
available at the same time.
When this method resolves, steamID will be populated.
Starts a new QR login attempt. Returns a Promise.
On failure, the Promise will be rejected with its message being equal to the string representation of an EResult
value. There will also be an eresult property on the Error object equal to the numeric representation of the relevant
EResult value. Realistically, failures should never happen unless Steam is having problems or you're having network issues.
On success, the Promise will be resolved with an object containing these properties:
actionRequired - Always true.validActions - Same as validActions for startWithCredentials. DeviceConfirmation
should always be present. DeviceCode has also been observed, even though at this point Steam doesn't even know what
account you intend to log into.qrChallengeUrl - A string containing the URL that should be encoded into a QR code and then scanned with the Steam
mobile app.steamID will not be populated when this method resolves, since at this point we don't know which account
we're going to log into. It will be populated after you successfully authenticate.
Immediately after this resolves, LoginSession will start polling to determine when authentication has succeeded.
authCode - Your Steam Guard code, as a stringIf a Steam Guard code is needed, you can supply it using this method. Returns a Promise.
On failure, the Promise will be rejected with its message being equal to the string representation of an EResult
value. There will also be an eresult property on the Error object equal to the numeric representation of the relevant
EResult value. For example:
Error: TwoFactorCodeMismatch
eresult: 88
Note that an incorrect email code will fail with EResult value InvalidLoginAuthCode (65), and an incorrect TOTP code will fail with EResult value TwoFactorCodeMismatch (88).
On success, the Promise will be resolved with no value. In this case, you should expect for authenticated
to be emitted shortly.
Forces an immediate polling attempt. This will throw an Error if you call it before the polling event is
emitted, after authenticated is emitted, or after you call cancelLoginAttempt.
Cancels polling for an ongoing login attempt. Once canceled, you should no longer interact with this
LoginSession object, and you should create a new one if you want to start a new attempt.
Once successfully authenticated, you can call this method to get cookies for use on the Steam websites.
You can also manually set refreshToken and then call this method without going through another login
attempt if you already have a valid refresh token. Returns a Promise.
On failure, the Promise will be rejected. Depending on the nature of the failure, an EResult may or may not be available.
On success, the Promise will be resolved with an array of strings. Each string contains a cookie, e.g.
steamLoginSecure=blahblahblahblah
or
steamLoginSecure=blahblahblahblah; Path=/; Secure; HttpOnly; SameSite=None; Domain=steamcommunity.com
Here's an example of how you can get new web cookies when you already have a valid refresh token:
import {LoginSession, EAuthTokenPlatformType} from 'steam-session';
let session = new LoginSession(EAuthTokenPlatformType.WebBrowser);
session.refreshToken = 'eyAidHlwIjogIkpXVCIsICJhbGciOiAiRWREU0EiIH0.eyJpc3MiOiJ...';
let cookies = await session.getWebCookies();
As long as a refreshToken is set, you can call this method to obtain a new access token.
Returns a Promise.
On failure, the Promise will be rejected. An EResult will be available under the eresult property of the Error object.
On success, the Promise will be resolved with no value. You can then read the access token from the LoginSession's accessToken property.
import {LoginSession, EAuthTokenPlatformType} from 'steam-session';
let session = new LoginSession(EAuthTokenPlatformType.SteamClient);
session.refreshToken = 'eyAidHlwIjogIkpXVCIsICJhbGciOiAiRWREU0EiIH0.eyJpc3MiOiJ...';
await session.refreshAccessToken();
console.log(`New access token: ${session.accessToken}`);
As of 2023-04-24, this method works for EAuthTokenPlatformType MobileApp and SteamClient, but using WebBrowser will fail
with response AccessDenied.
Does the same thing as refreshAccessToken(), while also attempting to renew your refresh token.
Whether a new refresh token will actually be issued is at the discretion of the Steam backend. This method will
return true if a new refresh token was issued (which can be accessed using the refreshToken property), or
false if no new refresh token was issued. Regardless of the return value, the accessToken property is
always updated with a fresh access token (unless there was an error).
Important: If a refresh token is successfully renewed (e.g. this method returns true), the old refresh token will become invalid, even if it is not yet expired.
import {LoginSession, EAuthTokenPlatformType} from 'steam-session';
let session = new LoginSession(EAuthTokenPlatformType.SteamClient);
session.refreshToken = 'eyAidHlwIjogIkpXVCIsICJhbGciOiAiRWREU0EiIH0.eyJpc3MiOiJ...';
let renewed = await session.renewRefreshToken();
console.log(`New access token: ${session.accessToken}`);
if (renewed) {
console.log(`New refresh token: ${session.refreshToken}`);
} else {
console.log('No new refresh token was issued');
}
As of 2023-04-24, this method works for EAuthTokenPlatformType MobileApp and SteamClient, but using WebBrowser will fail
with response AccessDenied.
This event is emitted once we start polling Steam to periodically check if the login attempt has succeeded or not. Polling starts when any of these conditions are met:
steamGuardCode*steamGuardMachineToken*submitSteamGuardCode*DeviceConfirmation or EmailConfirmation are among the valid guards
* = in these cases, we expect to only have to poll once before login succeeds.
After this event is emitted, if your loginTimeout elapses and the login attempt has not yet succeeded,
timeout is emitted and the login attempt is abandoned. You would then need to start a new login attempt
using a fresh LoginSession object.
This event is emitted when the time specified by loginTimeout elapses after polling begins,
and the login attempt has not yet succeeded. When timeout is emitted, cancelLoginAttempt is
called internally.
This event is emitted when Steam reports a "remote interaction" via polling. This is observed to happen
when the approval prompt is viewed in the Steam mobile app for the DeviceConfirmation guard. For a QR login,
this would be after you scan the code, but before you tap approve or deny.
This event is emitted when Steam sends us a new Steam Guard machine token. Machine tokens are only relevant when logging into an account that has email-based Steam Guard enabled. Thus, this will only be emitted after successfully logging into such an account.
At this time, this event is only emitted when logging in using EAuthTokenPlatformType = SteamClient. It's not presently possible to get a machine token for the WebBrowser platform (and MobileApp platform doesn't support machine tokens at all).
When this event is emitted, the steamGuardMachineToken property contains your new machine
token.
This event is emitted when we successfully authenticate with Steam. At this point, accountName
and refreshToken are populated. If the EAuthTokenPlatformType
passed to the constructor is appropriate, you can now safely call getWebCookies.
This event is emitted if we encounter an error while polling. The first argument to the event handler is an Error object. If this happens, the login attempt has failed and will need to be retried.
Node.js will crash if this event is emitted and not handled.
const {LoginApprover} = require('steam-session');
import {LoginApprover} from 'steam-session';
This class can be used to approve a login attempt that was started with a QR code. See the approve-qr example.
Read-only. A SteamID instance containing the SteamID for the
account to which the provided accessToken belongs. Populated immediately after accessToken
is set.
A string containing your access token. This is automatically set by the constructor, but you can also manually assign
it if you need to set a new access token.
An Error will be thrown when you set this property if you set it to a value that isn't a well-formed JWT, if you set it
to a refresh token rather than an access token, or if you set it to an access token that was not generated using
EAuthTokenPlatformType.MobileApp.
A string or Buffer containing your shared secret. This is automatically set by the constructor, but you can also
manually assign it if you need to set a new shared secret.
If this is a string, it must be either hex- or base64-encoded.
accessToken - A string containing a valid access token for the account you want to approve logins for. This
access token (not refresh token) must have been created using the MobileApp platform type.sharedSecret - A string or Buffer containing your account's TOTP shared secret. If this is a string, it must be
hex- or base64-encoded.options - An object with zero or more of these properties:
transport - An ITransport instance, if you need to specify a custom transport.
If omitted, defaults to a WebApiTransport instance. In all likelihood, you don't need to use this.localAddress - A string containing the local IP address you want to use. For example, 11.22.33.44httpProxy - A string containing a URI for an HTTP proxy. For example, http://user:pass@1.2.3.4:80socksProxy A string containing a URI for a SOCKS proxy. For example, socks5://user:pass@1.2.3.4:1080agent - An https.Agent instance to use for requests. If omitted, a new https.Agent will be created internally.You can only use one of localAddress, httpProxy, socksProxy or agent at the same time. If you try to use more
than one of them, an Error will be thrown.
If you specify a custom transport, then you are responsible for handling proxy or agent usage in your transport.
Constructs a new LoginApprover instance. Example usage:
import {LoginApprover} from 'steam-session';
let approver = new LoginApprover('eyAid...', 'oTVMfZJ9uHXo3m9MwTD9IOEWQaw=');
An Error will be thrown if your accessToken isn't a well-formed JWT, if it's a refresh token rather than an access
token, or if it's an access token that was not generated using EAuthTokenPlatformType.MobileApp.
qrChallengeUrl - A string containing the QR challenge URL from a startWithQR callReturns a Promise which resolves to an object with these properties:
ip - The origin IP address of the QR login attempt, as a stringlocation - An object
geoloc - A string containing geo coordinatescity - Stringstate - StringplatformType - The EAuthTokenPlatformType provided for the QR codedeviceFriendlyName - The device name provided when the QR code was generated (likely a browser user-agent)version - A number containing the version from the QR code, probably not useful to youloginHistory - EAuthSessionSecurityHistorylocationMismatch - A boolean indicating whether the location you requested the auth session info from doesn't match
the location where the QR code was generatedhighUsageLogin - A boolean indicating "whether this login has seen high usage recently"requestedPersistence - The ESessionPersistence requested for this logindetails - An object with these properties:
qrChallengeUrl - A string containing the QR challenge URL from a startWithQR callapprove - true to approve the login or false to denypersistence - An option value from ESessionPersistenceApproves or denies an auth session from a QR URL. If you pass true for approve, then the next poll from the
LoginSession will return access tokens. If you pass false, then the LoginSession will emit an error
event with EResult FileNotFound (9).
Returns a Promise which resolves with no value. Once this Promise resolves, you could call forcePoll,
and the LoginSession should then immediately emit authenticated.
FAQs
Enables authenticating with Steam
We found that steam-session demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.
Security News
Research
A supply chain attack on Rspack's npm packages injected cryptomining malware, potentially impacting thousands of developers.
Research
Security News
Socket researchers discovered a malware campaign on npm delivering the Skuld infostealer via typosquatted packages, exposing sensitive data.