@mgarnier11/freebox
v2.0.0
Published
Simple authentification and secure requests to your Freebox OS server
Downloads
5
Maintainers
Readme
Freebox for Node.js
Simple authentication and secure requests to your Freebox OS server
Why ?
From Freebox OS API documentation (https://dev.freebox.fr/sdk/os), register and authentication processes are quite difficult to set up. This little library simplify and automate all the hard authentication stuff to being able to request your Freebox from anywhere using HTTPS protocol.
Install
$ npm install freebox
Usage
Official Freebox OS API Documentation: https://dev.freebox.fr/sdk/os
Tested on:
- Freebox Revolution V6
If you tested on your Freebox and the device model is not in this list, please open an issue and I will add it in the list.
Register your app
Register only once your app ! You must be connected to your Freebox local network to register an app. To test if are on your Freebox local network, visit this page: https://mafreebox.freebox.fr. If it's working, you are on your Freebox local network.
Note: You can not register an app using a remote HTTPS freebox server domain like https://r42bhm9p.fbxos.fr
.
const { FreeboxRegister } = require("freebox");
async function main() {
const freeboxRegister = new FreeboxRegister({
app_id: "fbx.my_amazing_app",
app_name: "My Amazing App",
app_version: "1.0.0",
device_name: "My cool PC",
});
// Obtaining an app_token & everything you need
// following the guide at https://dev.freebox.fr/sdk/os/login/
const access = await freeboxRegister.register();
}
main().catch((err) => console.error(err));
/*
Please check your Freebox Server LCD screen and authorize application access to register your app.
Your app has been granted access !
Save safely those following informations secret to connect to your Freebox API:
{ app_token:
'etCEF2aytGPLWm1KZM0vIW/ziZOU58v/0qv9jUiJcedjadjaRZ/bflWSKy6HODORGUo6',
app_id: 'fbx.my_amazing_app',
api_domain: 'r42bhm9p.fbxos.fr',
https_port: 35023,
api_base_url: '/api/',
api_version: '6.0' }
*/
Login & request your Freebox server
const { Freebox } = require("freebox");
async function main() {
const freebox = new Freebox({
app_token:
"etCEF2aytGPLWm1KZM0vIW/ziZOU58v/0qv9jUiJcedjadjaRZ/bflWSKy6HODORGUo6",
app_id: "fbx.my_amazing_app",
api_domain: "r42bhm9p.fbxos.fr",
https_port: 35023,
api_base_url: "/api/",
api_version: "6.0",
});
// Open a session
// https://dev.freebox.fr/sdk/os/login/
await freebox.login();
// Get the current Wi-Fi global configuration
// https://dev.freebox.fr/sdk/os/wifi
const response = await freebox.request({
method: "GET",
url: "wifi/config",
});
// Close the current session
// https://dev.freebox.fr/sdk/os/login/#closing-the-current-session
await freebox.logout();
}
main().catch((err) => console.error(err));
API: FreeboxRegister
Each application identified with an app_name must gain access to Freebox API before being able to use the api. This procedure can only be initiated from the local network, and the user must have access to the Freebox front panel to grant access to the app.
Once the user authorize the app, the app will be provided with a unique app_token associated with a set of default permissions.
This app_token must be store securely by the app, and will not be exchanged in clear text for the following requests.
Note that the user can revoke the app_token, or edit its permissions afterwards. For instance if the user resets the admin password, app permissions will be reset.
FreeboxRegister([appIdentity])
Returns a new instance.
appIdentity
Type: Object
app_id
Type: String
Default: "fbx.nodejs_app_{generatedId}"
A unique app_id
string.
app_name
Type: String
Default: "nodejs_app_{generatedId}"
A descriptive application name (will be displayed on lcd).
app_version
Type: String
Default: "1.0.0"
Your app version.
device_name
Type: String
Default: "NodeJS"
The name of the device on which the app will be used.
Instance
.register()
Register your app to the Freebox. It requires a manual input on Freebox LCD screen.
Returns an Object
with all the informations needed to login and request your Freebox.
.discovery()
Returns an Object
(AxiosResponse) containing the API information of the Freebox.
API: Freebox
The app need to open a session to get an auth_token. The app will then be authenticated by adding this session_token in HTTP headers of the following requests. The validity of the auth_token is limited in time and the app will have to renew this auth_token once in a while.
Freebox([appRegistered])
Returns a new instance.
appRegistered
Type: Object
app_id
Type: String
Same app_id
used in TokenRequest to get the app_token
.
app_token
Type: String
Unique app_token
provided after authorizing the app via FreeboxRegister
class.
This token has been associated with a set of default permissions.
api_domain
Type: String
Default: "https://mafreebox.freebox.fr"
The domain to use in place of hardcoded Freebox IP.
https_port
Type: Number
Port to use for remote https access to the Freebox API.
api_base_url
Type: String
The API root path on the HTTP server.
api_version
Type: String
The current API version on the Freebox.
app_version
Type: String
Optional
Same app_version
used in TokenRequest (using FreeboxRegister
class) to get the app_token
.
Instance
.login()
Login to a Freebox by opening a session.
.logout()
Close the current session.
.request(object)
Requests the Freebox by passing an object AxiosRequestConfig
(https://github.com/axios/axios#request-config).
Returns an Object
(AxiosResponse).
License
MIT License Copyright (c) 2019 Mathieu Schimmerling.
Crafted with ❤️