@msimerson/stun
Advanced tools
Session Traversal Utilities for NAT (STUN) server. Implements RFC5389 with partial support RFC5766, RFC5245, RFC5780.
npm i stun
const stun = require('stun');
stun.request('stun.l.google.com:19302', (err, res) => {
if (err) {
console.error(err);
} else {
const { address } = res.getXorAddress();
console.log('your ip', address);
}
});
// or with promise
const res = await stun.request('stun.l.google.com:19302');
console.log('your ip', res.getXorAddress().address);
$ npm i -g stun
$ stun # started on udp/0.0.0.0:3478
createMessage(type: number [, transaction: Buffer]): StunRequestcreateTransaction(): BuffercreateServer(options: Object): StunServervalidateFingerprint(message: StunMessage): boolvalidateMessageIntegrity(message: StunMessage, key: string): boolrequest(url: string, [options: RequestOptions], callback: function): voidencode(message: StunMessage): Bufferdecode(message: Buffer): StunResponseclass StunRequest
setType(type)setTransactionId(transaction: Buffer): 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)addAddress(ip: string, port: number): StunAddressAttributeaddAlternateServer(ip: string, port: number): StunAddressAttributeaddXorAddress(ip: string, port: number): StunXorAddressAttributeaddUsername(username: string): StunByteStringAttributeaddRealm(realm: string): StunByteStringAttributeaddNonce(nonce: string): StunByteStringAttributeaddSoftware(software: string): StunByteStringAttributeaddUnknownAttributes(attributes: number[]): StunUInt16ListAttributeaddError(code: number, reason: string): StunErrorCodeAttributeaddPriority(priority: number): StunUInt32AttributeaddUseCandidate(): StunByteStringAttributeaddIceControlled(tiebreaker: Buffer): StunByteStringAttributeaddIceControlling(tiebreaker: Buffer): StunByteStringAttributeremoveAttribute(type): booladdMessageIntegrity(key: string)addFingerprint()toBuffer(): Bufferclass StunResponse
getAddress(): ObjectgetXorAddress(): ObjectgetAlternateServer(): ObjectgetUsername(): stringgetError(): ObjectgetRealm(): stringgetNonce(): stringgetSoftware(): stringgetUnknownAttributes(): number[]getMessageIntegrity(): BuffergetFingerprint(): numbergetPriority(): numbergetIceControlled(): BuffergetIceControlling(): Bufferclass StunMessage
class StunServer
new StunServer(socket: dgram.Socket)send(message: StunMessage, port: number, address: string[, cb: function])close()listen(port: number, [address: string], [callback: function()])Event: bindingRequestEvent: bindingIndicationEvent: bindingResponseEvent: bindingErrorEvent: closeEvent: errorEvent: listeningclass StunAttribute
constants: Objectclass StunErrorclass StunMessageErrorclass StunResponseErrorcreateMessage(type: number [, transaction: Buffer]): StunRequestCreates an StunRequest object of the specified type with random transaction field. The type argument is a number that should be a message type. See constants below.
createTransaction(): BufferCreate transaction id for STUN message. Follow RFC5389.
createServer(options: Object): StunServeroptions.type: stringThe type of socket. Must be 'udp4' or 'udp6'. Required.
options.socket: dgram.SocketCreates a StunServer object of the specified type. The type argument should be 'udp' at the moment. An optional socket argument should be instance of dgram.Socket. If socket is not specified, 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 specified.
validateMessageIntegrity(message: StunMessage, key: string): boolCheck a MESSAGE_INTEGRITY attribute if it is specified.
stunServer.on('bindingResponse', (msg) => {
if (!stun.validateFingerprint(msg)) {
// do stuff..
}
if (!stun.validateMessageIntegrity(msg, icePassword)) {
// do stuff...
}
});
request(url: string, [options: RequestOptions], callback: function): voidrequest(url: string, [options: RequestOptions]): PromiseCreate a request STUN_BINDING_REQUEST to stun server, follow RFC5389. The first argument may be a host (stun.example.com), host with port (stun.example.com:1234) or host with port and protocol (stun://stun.example.com:1234). By default, port is 3478.
All options described below are optional.
options.server: StunServer - A stun server to receive responses.options.socket: dgram.Socket - A UDP socket over which the message will be send.options.message: StunMessage - A STUN_BINDING_REQUEST message to send.options.timeout: number - Initial retransmission timeout (RTO) in ms, default is 500ms.options.maxTimeout: number- Maximal RTO, default is infinity.options.retries: number - Maximal the number of retries, default is 6The last argument is a function with 2 arguments err and res. It's follow nodejs callback style. The second argument is instance of StunMessage.
encode(message: StunMessage): BufferEncode StunRequest or StunResponse into the Buffer.
decode(message: Buffer): StunResponseDecode the Buffer into a StunResponse.
const socket = dgram.createSocket({ type: 'udp4' });
socket.on('message', (message) => {
const response = stun.decode(message);
// do stuff ...
});
class StunMessageThe StunMessage class is an utility that encapsulates the STUN protocol. This is a base class for StunRequest and StunResponse.
typetransactionIdReturns the type and transactionId fields from the current message.
isLegacy(): boolReturns true if the message confirms to RFC3489 rather than RFC5389.
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. Return undefined if attribute is not exist.
N.B. This method return only first matched attribute. If you want to get another one, try this:
const attributes = Array.from(stunMessage).filter(
(attribute) => attribute.type === STUN_ATTR_MAPPED_ADDRESS
);
count: numberReturns the number of an attributes in the current message.
class StunRequestThe StunRequest encapsulates outgoing messages of the STUN protocol. Instances of the StunRequest can be created using the createMessage().
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.
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);
addAddress(ip: string, port: number): StunAddressAttributeAdds a MAPPED-ADDRESS attribute to the message.
addAlternateServer(ip: string, port: number): StunAddressAttributeAdds a ALTERNATE-SERVER attribute to the message.
addXorAddress(ip: string, port: number): StunXorAddressAttributeAdds a XOR-MAPPED-ADDRESS attribute to the message.
addUsername(username: string): StunByteStringAttributeAdds a USERNAME attribute to the message.
addRealm(realm: string): StunByteStringAttributeAdds a REALM attribute to the message.
addNonce(nonce: string): StunByteStringAttributeAdds a NONCE attribute to the message.
addSoftware(software: string): StunByteStringAttributeAdds a SOFTWARE attribute to the message.
addUnknownAttributes(attributes: number[]): StunUInt16ListAttributeAdds a UNKNOWN-ATTRIBUTES attribute to the message.
addError(code: number, reason: string): StunErrorCodeAttributeAdds a ERROR-CODE attribute to the message.
addPriority(priority: number): StunUInt32AttributeAdds a PRIORITY attribute to the message.
addUseCandidate(): StunByteStringAttributeAdds a USE-CANDIDATE attribute to the message.
addIceControlled(tiebreaker: Buffer): StunByteStringAttributeAdds a ICE-CONTROLLED attribute to the message.
addIceControlling(tiebreaker: Buffer): StunByteStringAttributeAdds a ICE-CONTROLLING attribute to the message.
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.
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.
listen(port: number, [address: string], [callback: function()])Attempt to listen for messages on a named port and optional address. For UDP servers calls socket.bind under the hood.
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.
listeningThe 'listening' event is emitted whenever a socket begins listening for messages.
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_CAPACITYclass StunErrorBase class for all generated errors.
packet: Buffer|StunMessageReceived data.
sender: objectFor UDP, this is an rinfo attribute.
class StunMessageErrorThe STUN server may receive invalid messages. This error class represent ones. Inherits from StunError.
packet: BufferSee above.
class StunResponseErrorThis class represent protocol level errors, for messages with class type ERROR. Inherits from StunError.
packet: StunMessageSee above.
MIT, 2017-2019 (c) Dmitriy Tsvettsikh
FAQs
Session Traversal Utilities for NAT (STUN) client and server.
The npm package @msimerson/stun receives a total of 1,324 weekly downloads. As such, @msimerson/stun popularity was classified as popular.
We found that @msimerson/stun demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer 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.