Session Traversal Utilities for NAT (STUN) server. Implements RFC5389 with partial support RFC5766, RFC5245, RFC5780.
npm i stun
const stun = require('stun')
const { STUN_BINDING_REQUEST, STUN_ATTR_XOR_MAPPED_ADDRESS } = stun.constants
const server = stun.createServer()
const request = stun.createMessage(STUN_BINDING_REQUEST)
server.once('bindingResponse', stunMsg => {
console.log('your ip:', stunMsg.getAttribute(STUN_ATTR_XOR_MAPPED_ADDRESS).value.address)
server.close()
})
server.send(request, 19302, 'stun.l.google.com')
createMessage(type): StunMessagecreateServer([socket: dgram.Socket]): StunServervalidateFingerprint(message: StunMessage): boolvalidateMessageIntegrity(message: StunMessage, key: string): boolclass StunMessage
static from(message: Buffer): StunMessageget typeget transactionIdsetType(type)setTransactionID(transaction: Buffer): boolisLegacy(): booladdAttribute(type, address: string, port: number)addAttribute(type, value: String|Buffer[, encoding: string = 'utf8'])addAttribute(type, value: number)addAttribute(type, value: array<number>)addAttribute(type, code: number, reason: string)getAttribute(type): StunAttributeremoveAttribute(type): boolget count: numberaddMessageIntegrity(key: string)addFingerprint()toBuffer(): Bufferclass StunServer
class StunAttribute
constants: objectcreateMessage(type): StunMessageCreates an StunMessage object of the specified type with random transaction field. The type argument is a number that should be a message type. See constants below.
createServer([socket: dgram.Socket]): StunServerCreates a StunServer object. An optional socket argument should be instance of dgram.Socket. If socket is not specifed, the dgram.Socket will be created with udp4 type and will bound to the "all interfaces" address on a random port.
validateFingerprint(message: StunMessage): boolCheck a FINGERPRINT attribute if it is specifed.
validateMessageIntegrity(message: StunMessage, key: string): boolCheck a MESSAGE_INTEGRITY attribute if it is specifed.
stunServer.on('bindingResponse', (stunMsg) => {
if (!stun.validateFingerprint(stunMsg)) {
// do stuff...
}
if (!stun.validateMessageIntegrity(stunMsg, icePassword)) {
// do stuff...
}
})
class StunMessageThe StunMessage class is an utility that encapsulates the STUN protocol.
Instances of the StunMessage class can be created using the stun.createMessage() function or the StunMessage.from method.
from(message: Buffer): StunMessageCreates a StunMessage object from a message Buffer.
typetransactionIdReturns the type and transactionId fields from the current message.
setType(type)Set the type of the message. The type argument is a number that should be a message type. See constants below.
setTransactionID(transaction: Buffer): boolSet the transaction id of the message. The transaction argument should be a Buffer and have length 12 bytes.
isLegacy(): boolReturns true if the message confirms to RFC3489 rather than RFC5389.
addAttribute(type, address: string, port: number)Adds a type attribute to the current message. The type argument should be one of:
STUN_ATTR_MAPPED_ADDRESSSTUN_ATTR_ALTERNATE_SERVERSTUN_ATTR_XOR_MAPPED_ADDRESSSTUN_ATTR_RESPONSE_ORIGINSTUN_ATTR_OTHER_ADDRESSSTUN_ATTR_XOR_PEER_ADDRESSSTUN_ATTR_XOR_RELAYED_ADDRESS.stunMsg.addAttribute(STUN_ATTR_XOR_MAPPED_ADDRESS, '8.8.8.8', 19302)
addAttribute(type, value: String|Buffer[, encoding: string = 'utf8'])Adds a type attribute to the current message. The type argument should be one of:
STUN_ATTR_USERNAMESTUN_ATTR_REALMSTUN_ATTR_NONCESTUN_ATTR_SOFTWARESTUN_ATTR_ORIGINSTUN_ATTR_USE_CANDIDATESTUN_ATTR_ICE_CONTROLLEDSTUN_ATTR_ICE_CONTROLLINGSTUN_ATTR_DATASTUN_ATTR_EVEN_PORTSTUN_ATTR_RESERVATION_TOKENSTUN_ATTR_DONT_FRAGMENTSTUN_ATTR_PADDING.stunMsg.addAttribute(STUN_ATTR_SOFTWARE, 'node/8.2.0 stun/1.0.0')
addAttribute(type, value: number)Adds a type attribute to the current message. The type argument should be one of:
STUN_ATTR_RETRANSMIT_COUNTSTUN_ATTR_PRIORITYSTUN_ATTR_NETWORK_INFOSTUN_ATTR_NOMINATIONSTUN_ATTR_CHANNEL_NUMBERSTUN_ATTR_LIFETIMESTUN_ATTR_REQUESTED_TRANSPORTSTUN_ATTR_CHANGE_REQUESTSTUN_ATTR_RESPONSE_PORT.stunMsg.addAttribute(STUN_ATTR_PRIORITY, 123)
addAttribute(type, value: array<number>)Adds a type attribute to the current message. The type argument should be STUN_ATTR_UNKNOWN_ATTRIBUTES.
stunMsg.addAttribute(STUN_ATTR_UNKNOWN_ATTRIBUTES, [2, 3, 4])
addAttribute(type, code: number, reason: string)Adds a type attribute to the current message. The type argument should be STUN_ATTR_ERROR_CODE.
stunMsg.addAttribute(STUN_ATTR_ERROR_CODE, STUN_CODE_UNAUTHORIZED, STUN_REASON_UNAUTHORIZED)
getAttribute(type): StunAttributeReturns the StunAttribute attribute of the specified type. The type argument is a number that should be an attribute type. See constants below.
removeAttribute(type): boolRemove a type attribute from the current message. Returns true if an attribute was removed. The type argument is a number that should be an attribute type. See constants below.
count: numberReturns the number of an attributes in the current message.
addMessageIntegrity(key: string)Adds a MESSAGE-INTEGRITY attribute that is valid for the current message. The key is the HMAC key used to generate the cryptographic HMAC hash.
addFingerprint()Adds a FINGERPRINT attribute that is valid for the current message.
toBuffer(): BufferConverts a StunMessage object to the buffer.
class StunServerThe StunServer class is an EventEmitter that encapsulates a STUN server.
new StunServer(socket: dgram.Socket)Creates a new StunServer object. The socket argument should be an instance of dgram.Socket. The incoming message is silently ignored when it is not a stun one.
send(message: StunMessage, port: number, address: string[, cb: function])Sends the StunMessage message on the socket. The destination port and address must be specified. An optional callback function will be called when the message has been sent.
close()Stops the processing of the incoming messages and emits close event.
bindingRequestEmitted when the STUN_BINDING_REQUEST message is available on a socket.
bindingIndicationEmitted when the STUN_BINDING_INDICATION message is available on a socket.
bindingResponseEmitted when the STUN_BINDING_RESPONSE message is available on a socket.
bindingErrorEmitted when the STUN_BINDING_ERROR_RESPONSE message is available on a socket.
closeEmitted when the server closes.
errorEmitted when the server got an invalid message.
class StunAttributeThe StunAttribute class is an utility for adding an attributes to the StunMessage message.
typeReturns the attribute type. See constants below.
valueReturns the value of the attribute. It depends on the value type of the attribute.
stunMsg.getAttribute(STUN_ATTR_USERNAME).value // string
stunMsg.getAttribute(STUN_ATTR_PRIORITY).value // number
stunMsg.getAttribute(STUN_ATTR_MAPPED_ADDRESS).value // object
constants: objectThese are the types of STUN messages defined in RFC5389:
STUN_BINDING_REQUESTSTUN_BINDING_INDICATIONSTUN_BINDING_RESPONSESTUN_BINDING_ERROR_RESPONSEThese are the event names for STUN messages above:
STUN_EVENT_BINDING_REQUESTSTUN_EVENT_BINDING_INDICATIONSTUN_EVENT_BINDING_RESPONSESTUN_EVENT_BINDING_ERROR_RESPONSEThese are the types of STUN messages defined in RFC5766:
STUN_ALLOCATE_REQUESTSTUN_ALLOCATE_RESPONSESTUN_ALLOCATE_ERROR_RESPONSESTUN_REFRESH_REQUESTSTUN_REFRESH_RESPONSESTUN_REFRESH_ERROR_RESPONSESTUN_SEND_INDICATIONSTUN_DATA_INDICATIONSTUN_CREATE_PERMISSION_REQUESTSTUN_CREATE_PERMISSION_RESPONSESTUN_CREATE_PERMISSION_ERROR_RESPONSESTUN_CHANNEL_BIND_REQUESTSTUN_CHANNEL_BIND_RESPONSESTUN_CHANNEL_BIND_ERROR_RESPONSEThsese are all known STUN attributes, defined in RFC5389 and elsewhere:
STUN_ATTR_MAPPED_ADDRESSSTUN_ATTR_USERNAMESTUN_ATTR_MESSAGE_INTEGRITYSTUN_ATTR_ERROR_CODESTUN_ATTR_UNKNOWN_ATTRIBUTESSTUN_ATTR_REALMSTUN_ATTR_NONCESTUN_ATTR_XOR_MAPPED_ADDRESSSTUN_ATTR_SOFTWARESTUN_ATTR_ALTERNATE_SERVERSTUN_ATTR_FINGERPRINTSTUN_ATTR_ORIGINSTUN_ATTR_RETRANSMIT_COUNTSTUN_ATTR_PRIORITYSTUN_ATTR_USE_CANDIDATESTUN_ATTR_ICE_CONTROLLEDSTUN_ATTR_ICE_CONTROLLINGSTUN_ATTR_NOMINATIONSTUN_ATTR_NETWORK_INFOSTUN_ATTR_CHANNEL_NUMBERSTUN_ATTR_LIFETIMESTUN_ATTR_XOR_PEER_ADDRESSSTUN_ATTR_DATASTUN_ATTR_XOR_RELAYED_ADDRESSSTUN_ATTR_EVEN_PORTSTUN_ATTR_REQUESTED_TRANSPORTSTUN_ATTR_DONT_FRAGMENTSTUN_ATTR_RESERVATION_TOKENSTUN_ATTR_CHANGE_REQUESTSTUN_ATTR_PADDINGSTUN_ATTR_RESPONSE_PORTSTUN_ATTR_RESPONSE_ORIGINSTUN_ATTR_OTHER_ADDRESSThese are the types of STUN error codes defined in RFC5389 and elsewhere:
STUN_CODE_TRY_ALTERNATESTUN_CODE_BAD_REQUESTSTUN_CODE_UNAUTHORIZEDSTUN_CODE_UNKNOWN_ATTRIBUTESTUN_CODE_STALE_CREDENTIALSSTUN_CODE_STALE_NONCESTUN_CODE_SERVER_ERRORSTUN_CODE_GLOBAL_FAILURESTUN_CODE_ROLE_CONFLICTSTUN_CODE_FORBIDDENSTUN_CODE_ALLOCATION_MISMATCHSTUN_CODE_WRONG_CREDENTIALSSTUN_CODE_UNSUPPORTED_PROTOCOLSTUN_CODE_ALLOCATION_QUOTASTUN_CODE_INSUFFICIENT_CAPACITYThese are the strings for the error codes above:
STUN_REASON_TRY_ALTERNATESTUN_REASON_BAD_REQUESTSTUN_REASON_UNAUTHORIZEDSTUN_REASON_UNKNOWN_ATTRIBUTESTUN_REASON_STALE_CREDENTIALSSTUN_REASON_STALE_NONCESTUN_REASON_SERVER_ERRORSTUN_REASON_ROLE_CONFLICTSTUN_REASON_FORBIDDENSTUN_REASON_ALLOCATION_MISMATCHSTUN_REASON_WRONG_CREDENTIALSSTUN_REASON_UNSUPPORTED_PROTOCOLSTUN_REASON_ALLOCATION_QUOTASTUN_REASON_INSUFFICIENT_CAPACITYMIT, 2017 (c) Dmitriy Tsvettsikh
FAQs
Session Traversal Utilities for NAT (STUN) client and server.
The npm package stun receives a total of 773 weekly downloads. As such, stun popularity was classified as not popular.
We found that stun demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 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.
Company News
Socket won two 2026 Reppy Awards from RepVue, ranking in the top 5% of all sales orgs. AE Alexandra Lister shares what it's like to grow a sales career here.
Security News
NIST will stop enriching most CVEs under a new risk-based model, narrowing the NVD's scope as vulnerability submissions continue to surge.
Company News
/Security News
Socket is an initial recipient of OpenAI's Cybersecurity Grant Program, which commits $10M in API credits to defenders securing open source software.