agora-token 2.0.4 → 2.0.6

package/src/AccessToken2.js

@@ -1,42 +1,55 @@
 var crypto = require('crypto')
 const zlib = require('zlib')
 const VERSION_LENGTH = 3
-const APP_ID_LENGTH = 32
 
+// Returns the Token007 version prefix.
 const getVersion = () => {
     return '007'
 }
 
+// Returns whether a value is a 32-character hexadecimal identifier.
+const isUuid = value => {
+    return value !== null && typeof value !== 'undefined' && /^[0-9a-fA-F]{32}$/.test(value.toString())
+}
+
+// Represents the common service type and privilege payload.
 class Service {
+    // Creates a service with the specified numeric type.
     constructor(service_type) {
         this.__type = service_type
         this.__privileges = {}
     }
 
+    // Serializes the numeric service type.
     __pack_type() {
         let buf = new ByteBuf()
         buf.putUint16(this.__type)
         return buf.pack()
     }
 
+    // Serializes the service privilege map.
     __pack_privileges() {
         let buf = new ByteBuf()
         buf.putTreeMapUInt32(this.__privileges)
         return buf.pack()
     }
 
+    // Returns the numeric service type.
     service_type() {
         return this.__type
     }
 
+    // Adds or updates a service privilege expiration timestamp.
     add_privilege(privilege, expire) {
         this.__privileges[privilege] = expire
     }
 
+    // Serializes the service type and privileges.
     pack() {
         return Buffer.concat([this.__pack_type(), this.__pack_privileges()])
     }
 
+    // Deserializes service privileges after the type has been consumed.
     unpack(buffer) {
         let bufReader = new ReadByteBuf(buffer)
         this.__privileges = bufReader.getTreeMapUInt32()
@@ -46,19 +59,23 @@ class Service {
 
 const kRtcServiceType = 1
 
+// Represents an RTC service payload.
 class ServiceRtc extends Service {
+    // Creates an RTC service for a channel and user ID.
     constructor(channel_name, uid) {
         super(kRtcServiceType)
         this.__channel_name = channel_name
         this.__uid = uid === 0 ? '' : `${uid}`
     }
 
+    // Serializes the RTC service payload.
     pack() {
         let buffer = new ByteBuf()
         buffer.putString(this.__channel_name).putString(this.__uid)
         return Buffer.concat([super.pack(), buffer.pack()])
     }
 
+    // Deserializes the RTC service payload.
     unpack(buffer) {
         let bufReader = super.unpack(buffer)
         this.__channel_name = bufReader.getString()
@@ -74,18 +91,22 @@ ServiceRtc.kPrivilegePublishDataStream = 4
 
 const kRtmServiceType = 2
 
+// Represents an RTM service payload.
 class ServiceRtm extends Service {
+    // Creates an RTM service for a user ID.
     constructor(user_id) {
         super(kRtmServiceType)
         this.__user_id = user_id || ''
     }
 
+    // Serializes the RTM service payload.
     pack() {
         let buffer = new ByteBuf()
         buffer.putString(this.__user_id)
         return Buffer.concat([super.pack(), buffer.pack()])
     }
 
+    // Deserializes the RTM service payload.
     unpack(buffer) {
         let bufReader = super.unpack(buffer)
         this.__user_id = bufReader.getString()
@@ -95,17 +116,50 @@ class ServiceRtm extends Service {
 
 ServiceRtm.kPrivilegeLogin = 1
 
+const kStreamingServiceType = 3
+
+// Represents a Streaming service payload.
+class ServiceStreaming extends Service {
+    // Creates a Streaming service for a channel and numeric user ID or string account.
+    constructor(channelName = '', account = '') {
+        super(kStreamingServiceType)
+        this.__channel_name = channelName
+        this.__account = account === 0 ? '' : `${account}`
+    }
+
+    // Serializes the Streaming service payload.
+    pack() {
+        const buffer = new ByteBuf().putString(this.__channel_name).putString(this.__account)
+        return Buffer.concat([super.pack(), buffer.pack()])
+    }
+
+    // Deserializes the Streaming service payload.
+    unpack(buffer) {
+        const reader = super.unpack(buffer)
+        this.__channel_name = reader.getString()
+        this.__account = reader.getString()
+        return reader
+    }
+}
+
+ServiceStreaming.kPrivilegePublishMixStream = 1
+ServiceStreaming.kPrivilegePublishRawStream = 2
+
 const kFpaServiceType = 4
 
+// Represents an FPA service payload.
 class ServiceFpa extends Service {
+    // Creates an FPA service.
     constructor() {
         super(kFpaServiceType)
     }
 
+    // Serializes the FPA service payload.
     pack() {
         return super.pack()
     }
 
+    // Deserializes the FPA service payload.
     unpack(buffer) {
         let bufReader = super.unpack(buffer)
         return bufReader
@@ -114,20 +168,64 @@ class ServiceFpa extends Service {
 
 ServiceFpa.kPrivilegeLogin = 1
 
+const kConvoAIServiceType = 9
+
+// Represents a ConvoAI service payload.
+class ServiceConvoAI extends Service {
+    // Creates a ConvoAI service.
+    constructor() {
+        super(kConvoAIServiceType)
+    }
+
+    // Serializes the ConvoAI service payload.
+    pack() {
+        return super.pack()
+    }
+
+    // Deserializes the ConvoAI service payload.
+    unpack(buffer) {
+        return super.unpack(buffer)
+    }
+}
+
+const kSttServiceType = 10
+
+// Represents an STT service payload.
+class ServiceStt extends Service {
+    // Creates an STT service.
+    constructor() {
+        super(kSttServiceType)
+    }
+
+    // Serializes the STT service payload.
+    pack() {
+        return super.pack()
+    }
+
+    // Deserializes the STT service payload.
+    unpack(buffer) {
+        return super.unpack(buffer)
+    }
+}
+
 const kChatServiceType = 5
 
+// Represents a Chat service payload.
 class ServiceChat extends Service {
+    // Creates a Chat service for a user ID.
     constructor(user_id) {
         super(kChatServiceType)
         this.__user_id = user_id || ''
     }
 
+    // Serializes the Chat service payload.
     pack() {
         let buffer = new ByteBuf()
         buffer.putString(this.__user_id)
         return Buffer.concat([super.pack(), buffer.pack()])
     }
 
+    // Deserializes the Chat service payload.
     unpack(buffer) {
         let bufReader = super.unpack(buffer)
         this.__user_id = bufReader.getString()
@@ -138,9 +236,40 @@ class ServiceChat extends Service {
 ServiceChat.kPrivilegeUser = 1
 ServiceChat.kPrivilegeApp = 2
 
+const kFCdnServiceType = 6
+
+// Represents an FCDN service payload.
+class ServiceFCdn extends Service {
+    // Creates an FCDN service for a channel and numeric user ID or string account.
+    constructor(channelName = '', account = '') {
+        super(kFCdnServiceType)
+        this.__channel_name = channelName
+        this.__account = account === 0 ? '' : `${account}`
+    }
+
+    // Serializes the FCDN service payload.
+    pack() {
+        const buffer = new ByteBuf().putString(this.__channel_name).putString(this.__account)
+        return Buffer.concat([super.pack(), buffer.pack()])
+    }
+
+    // Deserializes the FCDN service payload.
+    unpack(buffer) {
+        const reader = super.unpack(buffer)
+        this.__channel_name = reader.getString()
+        this.__account = reader.getString()
+        return reader
+    }
+}
+
+ServiceFCdn.kPrivilegePublish = 1
+ServiceFCdn.kPrivilegePlay = 2
+
 const kApaasServiceType = 7
 
+// Represents an APaaS service payload.
 class ServiceApaas extends Service {
+    // Creates an APaaS service for a room, user, and role.
     constructor(roomUuid, userUuid, role) {
         super(kApaasServiceType)
         this.__room_uuid = roomUuid || ''
@@ -148,6 +277,7 @@ class ServiceApaas extends Service {
         this.__role = role || -1
     }
 
+    // Serializes the APaaS service payload.
     pack() {
         let buffer = new ByteBuf()
         buffer.putString(this.__room_uuid)
@@ -156,6 +286,7 @@ class ServiceApaas extends Service {
         return Buffer.concat([super.pack(), buffer.pack()])
     }
 
+    // Deserializes the APaaS service payload.
     unpack(buffer) {
         let bufReader = super.unpack(buffer)
         this.__room_uuid = bufReader.getString()
@@ -169,7 +300,87 @@ ServiceApaas.PRIVILEGE_ROOM_USER = 1
 ServiceApaas.PRIVILEGE_USER = 2
 ServiceApaas.PRIVILEGE_APP = 3
 
+// Stores RTM2 resource-level permissions.
+class Rtm2Permissions {
+    // Creates an empty RTM2 permission set.
+    constructor() {
+        this.details = {}
+    }
+
+    // Adds or replaces resources for a resource and permission type.
+    add(resourceType, permissionType, resources) {
+        if (!this.details[resourceType]) {
+            this.details[resourceType] = {}
+        }
+        this.details[resourceType][permissionType] = Array.from(resources)
+    }
+}
+
+Rtm2Permissions.kMessageChannels = 0
+Rtm2Permissions.kStreamChannels = 1
+Rtm2Permissions.kGroupChannels = 2
+Rtm2Permissions.kServerGroups = 3
+Rtm2Permissions.kUsers = 4
+Rtm2Permissions.kRead = 0
+Rtm2Permissions.kWrite = 1
+
+const kRtm2ServiceType = 8
+
+// Represents an RTM2 service payload.
+class ServiceRtm2 extends Service {
+    // Creates an RTM2 service for a user and permission set.
+    constructor(userId, permissions) {
+        super(kRtm2ServiceType)
+        this.__user_id = userId === 0 || userId == null ? '' : String(userId)
+        this.__permissions = permissions || new Rtm2Permissions()
+    }
+
+    // Serializes the RTM2 service payload.
+    pack() {
+        const buffer = new ByteBuf().putString(this.__user_id)
+        const resourceTypes = Object.keys(this.__permissions.details).map(Number).sort((left, right) => left - right)
+        buffer.putUint16(resourceTypes.length)
+        resourceTypes.forEach(resourceType => {
+            const permissionMap = this.__permissions.details[resourceType]
+            const permissionTypes = Object.keys(permissionMap).map(Number).sort((left, right) => left - right)
+            buffer.putUint16(resourceType).putUint16(permissionTypes.length)
+            permissionTypes.forEach(permissionType => {
+                const resources = permissionMap[permissionType]
+                buffer.putUint16(permissionType).putUint16(resources.length)
+                resources.forEach(resource => buffer.putString(resource))
+            })
+        })
+        return Buffer.concat([super.pack(), buffer.pack()])
+    }
+
+    // Deserializes the RTM2 service payload.
+    unpack(buffer) {
+        const reader = super.unpack(buffer)
+        this.__user_id = reader.getString()
+        this.__permissions = new Rtm2Permissions()
+        const resourceTypeCount = reader.getUint16()
+        for (let i = 0; i < resourceTypeCount; i++) {
+            const resourceType = reader.getUint16()
+            const permissionCount = reader.getUint16()
+            for (let j = 0; j < permissionCount; j++) {
+                const permissionType = reader.getUint16()
+                const resourceCount = reader.getUint16()
+                const resources = []
+                for (let k = 0; k < resourceCount; k++) {
+                    resources.push(reader.getString().toString())
+                }
+                this.__permissions.add(resourceType, permissionType, resources)
+            }
+        }
+        return reader
+    }
+}
+
+ServiceRtm2.kPrivilegeLogin = 1
+
+// Builds, parses, and verifies Token007 tokens containing one or more services.
 class AccessToken2 {
+    // Creates a token builder or an empty token parser.
     constructor(appId, appCertificate, issueTs, expire) {
         this.appId = appId
         this.appCertificate = appCertificate
@@ -177,53 +388,69 @@ class AccessToken2 {
         this.expire = expire
         // salt ranges in (1, 99999999)
         this.salt = Math.floor(Math.random() * 99999999) + 1
-        this.services = {}
+        this.services = []
+        this.__signature = Buffer.alloc(0)
+        this.__signing_info = Buffer.alloc(0)
+        this.__parsed = false
     }
 
-    __signing() {
-        let signing = encodeHMac(new ByteBuf().putUint32(this.issueTs).pack(), this.appCertificate)
+    // Derives the signing key with the stored or supplied App Certificate.
+    __signing(appCertificate = this.appCertificate) {
+        let signing = encodeHMac(new ByteBuf().putUint32(this.issueTs).pack(), appCertificate)
         signing = encodeHMac(new ByteBuf().putUint32(this.salt).pack(), signing)
         return signing
     }
 
+    // Validates the fields required to build a token.
     __build_check() {
-        let is_uuid = data => {
-            if (data.length !== APP_ID_LENGTH) {
-                return false
-            }
-            let buf = Buffer.from(data, 'hex')
-            return !!buf
-        }
-
         const { appId, appCertificate, services } = this
-        if (!is_uuid(appId) || !is_uuid(appCertificate)) {
+        if (!isUuid(appId) || !isUuid(appCertificate)) {
             return false
         }
 
-        if (Object.keys(services).length === 0) {
+        if (services.length === 0) {
             return false
         }
         return true
     }
 
+    // Returns services in stable type order while preserving duplicate insertion order.
+    __services_for_packing() {
+        return this.services
+            .map((service, index) => ({ service, index }))
+            .sort((left, right) => {
+                const typeDifference = left.service.service_type() - right.service.service_type()
+                return typeDifference || left.index - right.index
+            })
+            .map(entry => entry.service)
+    }
+
+    // Adds a service without replacing services of the same type.
     add_service(service) {
-        this.services[service.service_type()] = service
+        this.services.push(service)
+    }
+
+    // Returns all services of the requested type in insertion or token order.
+    getServices(serviceType) {
+        return this.services.filter(service => service.service_type() === serviceType)
     }
 
+    // Builds a Token007 token containing all added services.
     build() {
         if (!this.__build_check()) {
             return ''
         }
 
         let signing = this.__signing()
+        const services = this.__services_for_packing()
         let signing_info = new ByteBuf()
             .putString(this.appId)
             .putUint32(this.issueTs)
             .putUint32(this.expire)
             .putUint32(this.salt)
-            .putUint16(Object.keys(this.services).length)
+            .putUint16(services.length)
             .pack()
-        Object.values(this.services).forEach(service => {
+        services.forEach(service => {
             signing_info = Buffer.concat([signing_info, service.pack()])
         })
 
@@ -233,38 +460,82 @@ class AccessToken2 {
         return `${getVersion()}${Buffer.from(compressed).toString('base64')}`
     }
 
+    // Parses known services and retains the original bytes for signature verification.
     from_string(origin_token) {
-        let origin_version = origin_token.substring(0, VERSION_LENGTH)
+        // Clear the previous token state so a failed parse cannot reuse its signature or services.
+        this.appId = ''
+        this.issueTs = 0
+        this.expire = 0
+        this.salt = 0
+        this.services = []
+        this.__signature = Buffer.alloc(0)
+        this.__signing_info = Buffer.alloc(0)
+        this.__parsed = false
+
+        if (typeof origin_token !== 'string' || origin_token.length < VERSION_LENGTH) {
+            return false
+        }
+
+        const origin_version = origin_token.substring(0, VERSION_LENGTH)
         if (origin_version !== getVersion()) {
             return false
         }
 
-        let origin_content = origin_token.substring(VERSION_LENGTH, origin_token.length)
-        let buffer = zlib.inflateSync(new Buffer(origin_content, 'base64'))
-        let bufferReader = new ReadByteBuf(buffer)
-
-        let signature = bufferReader.getString()
-        this.appId = bufferReader.getString()
-        this.issueTs = bufferReader.getUint32()
-        this.expire = bufferReader.getUint32()
-        this.salt = bufferReader.getUint32()
-        let service_count = bufferReader.getUint16()
-
-        let remainBuf = bufferReader.pack()
-        for (let i = 0; i < service_count; i++) {
-            let bufferReaderService = new ReadByteBuf(remainBuf)
-            let service_type = bufferReaderService.getUint16()
-            let service = new AccessToken2.kServices[service_type]()
-            remainBuf = service.unpack(bufferReaderService.pack()).pack()
-            this.services[service_type] = service
+        try {
+            const origin_content = origin_token.substring(VERSION_LENGTH)
+            const buffer = zlib.inflateSync(Buffer.from(origin_content, 'base64'))
+            const bufferReader = new ReadByteBuf(buffer)
+
+            this.__signature = Buffer.from(bufferReader.getString())
+            this.__signing_info = Buffer.from(bufferReader.pack())
+            this.services = []
+            this.appId = bufferReader.getString()
+            this.issueTs = bufferReader.getUint32()
+            this.expire = bufferReader.getUint32()
+            this.salt = bufferReader.getUint32()
+            const service_count = bufferReader.getUint16()
+
+            let remainBuf = bufferReader.pack()
+            for (let i = 0; i < service_count; i++) {
+                const bufferReaderService = new ReadByteBuf(remainBuf)
+                const service_type = bufferReaderService.getUint16()
+                const ServiceClass = AccessToken2.kServices[service_type]
+                if (!ServiceClass) {
+                    this.__parsed = true
+                    return true
+                }
+
+                const service = new ServiceClass()
+                remainBuf = service.unpack(bufferReaderService.pack()).pack()
+                this.add_service(service)
+            }
+        } catch (error) {
+            return false
+        }
+
+        this.__parsed = true
+        return true
+    }
+
+    // Verifies the signature of a successfully parsed token.
+    verifySignature(appCertificate) {
+        if (!this.__parsed || this.__signature.length === 0 || this.__signing_info.length === 0
+            || !isUuid(this.appId) || !isUuid(appCertificate)) {
+            return false
         }
+
+        const signature = encodeHMac(this.__signing(appCertificate), this.__signing_info)
+        return this.__signature.length === signature.length
+            && crypto.timingSafeEqual(this.__signature, signature)
     }
 }
 
+// Returns a SHA-256 HMAC digest.
 var encodeHMac = function (key, message) {
     return crypto.createHmac('sha256', key).update(message).digest()
 }
 
+// Creates a little-endian token buffer writer.
 var ByteBuf = function () {
     var that = {
         buffer: Buffer.alloc(1024),
@@ -273,46 +544,76 @@ var ByteBuf = function () {
 
     that.buffer.fill(0)
 
+    // Grows the backing buffer when the next value does not fit.
+    var ensureCapacity = function (additionalLength) {
+        const requiredLength = that.position + additionalLength
+        if (requiredLength <= that.buffer.length) {
+            return
+        }
+
+        let capacity = that.buffer.length
+        while (capacity < requiredLength) {
+            capacity *= 2
+        }
+
+        const expanded = Buffer.alloc(capacity)
+        that.buffer.copy(expanded, 0, 0, that.position)
+        that.buffer = expanded
+    }
+
+    // Returns the bytes written to the buffer.
     that.pack = function () {
         var out = Buffer.alloc(that.position)
         that.buffer.copy(out, 0, 0, out.length)
         return out
     }
 
+    // Appends an unsigned 16-bit integer.
     that.putUint16 = function (v) {
+        ensureCapacity(2)
         that.buffer.writeUInt16LE(v, that.position)
         that.position += 2
         return that
     }
 
+    // Appends an unsigned 32-bit integer.
     that.putUint32 = function (v) {
+        ensureCapacity(4)
         that.buffer.writeUInt32LE(v, that.position)
         that.position += 4
         return that
     }
+    // Appends a signed 32-bit integer.
     that.putInt32 = function (v) {
+        ensureCapacity(4)
         that.buffer.writeInt32LE(v, that.position)
         that.position += 4
         return that
     }
 
+    // Appends a signed 16-bit integer.
     that.putInt16 = function (v) {
+        ensureCapacity(2)
         that.buffer.writeInt16LE(v, that.position)
         that.position += 2
         return that
     }
 
+    // Appends length-prefixed bytes.
     that.putBytes = function (bytes) {
         that.putUint16(bytes.length)
+        ensureCapacity(bytes.length)
         bytes.copy(that.buffer, that.position)
         that.position += bytes.length
         return that
     }
 
+    // Appends a length-prefixed string.
     that.putString = function (str) {
         return that.putBytes(Buffer.from(str))
     }
 
+    // Appends a string map in numeric key order.
     that.putTreeMap = function (map) {
         if (!map) {
             that.putUint16(0)
@@ -328,6 +629,7 @@ var ByteBuf = function () {
         return that
     }
 
+    // Appends an unsigned 32-bit value map in numeric key order.
     that.putTreeMapUInt32 = function (map) {
         if (!map) {
             that.putUint16(0)
@@ -346,30 +648,35 @@ var ByteBuf = function () {
     return that
 }
 
+// Creates a little-endian token buffer reader.
 var ReadByteBuf = function (bytes) {
     var that = {
         buffer: bytes,
         position: 0
     }
 
+    // Reads an unsigned 16-bit integer.
     that.getUint16 = function () {
         var ret = that.buffer.readUInt16LE(that.position)
         that.position += 2
         return ret
     }
 
+    // Reads an unsigned 32-bit integer.
     that.getUint32 = function () {
         var ret = that.buffer.readUInt32LE(that.position)
         that.position += 4
         return ret
     }
 
+    // Reads a signed 16-bit integer.
     that.getInt16 = function () {
         var ret = that.buffer.readUInt16LE(that.position)
         that.position += 2
         return ret
     }
 
+    // Reads length-prefixed bytes.
     that.getString = function () {
         var len = that.getUint16()
 
@@ -379,6 +686,7 @@ var ReadByteBuf = function (bytes) {
         return out
     }
 
+    // Reads an unsigned 32-bit value map.
     that.getTreeMapUInt32 = function () {
         var map = {}
         var len = that.getUint16()
@@ -390,10 +698,11 @@ var ReadByteBuf = function (bytes) {
         return map
     }
 
+    // Returns unread bytes from the buffer.
     that.pack = function () {
-        let length = that.buffer.length
-        var out = Buffer.alloc(length)
-        that.buffer.copy(out, 0, that.position, length)
+        const length = that.buffer.length - that.position
+        const out = Buffer.alloc(length)
+        that.buffer.copy(out, 0, that.position)
         return out
     }
 
@@ -403,20 +712,37 @@ var ReadByteBuf = function (bytes) {
 AccessToken2.kServices = {}
 AccessToken2.kServices[kApaasServiceType] = ServiceApaas
 AccessToken2.kServices[kChatServiceType] = ServiceChat
+AccessToken2.kServices[kFCdnServiceType] = ServiceFCdn
 AccessToken2.kServices[kFpaServiceType] = ServiceFpa
 AccessToken2.kServices[kRtcServiceType] = ServiceRtc
 AccessToken2.kServices[kRtmServiceType] = ServiceRtm
+AccessToken2.kServices[kRtm2ServiceType] = ServiceRtm2
+AccessToken2.kServices[kStreamingServiceType] = ServiceStreaming
+AccessToken2.kServices[kConvoAIServiceType] = ServiceConvoAI
+AccessToken2.kServices[kSttServiceType] = ServiceStt
 
 module.exports = {
     AccessToken2,
     kApaasServiceType,
     kChatServiceType,
+    kConvoAIServiceType,
+    kFCdnServiceType,
     kFpaServiceType,
     kRtcServiceType,
     kRtmServiceType,
+    kRtm2ServiceType,
+    kSttServiceType,
+    kStreamingServiceType,
+    Rtm2Permissions,
+    Service,
     ServiceApaas,
     ServiceChat,
+    ServiceConvoAI,
+    ServiceFCdn,
     ServiceFpa,
     ServiceRtc,
-    ServiceRtm
+    ServiceRtm,
+    ServiceRtm2,
+    ServiceStt,
+    ServiceStreaming
 }