hereos-frontend v1.3.1

HereOS-Frontend

Frontend SDK for HereOS.

This only makes sense with the HereOS backend.

Contents

1. Install
2. Data class
3. Functions
4. Modules
5. More help

Install

npm install hereos-frontend

Usage Example

//import
import * as HereOS from "hereos-frontend";

//INITIATE
//create websocket etc
await HereOS.Init();

//OR create own websocket
HereOS.Data.ws = createMyCustomWebSocket();
//example handler
HereOS.Data.ws.on("message", (message) => {
	HereOS.Modules.parse(message);
}

//SIGN IN
//sign in using password (username, password)
let authenticated: boolean = await HereOS.UsePswd("john-doe", "mypassword");
//stay signed in securely
let token = await HereOS.Exec("createtoken");
//store token
localStorage.setItem("token", token);
//sign in using token (username, token)
let authenticated = await HereOS.UseToken("john-doe", localStorage.getItem("token"));

//EXECUTE SHELL COMMANDS
//using current credentials
let user_directory_contents = await HereOS.Exec("ls /users/john-doe");

//using other credentials
//you can also provide token and pin instead
let user_directory_contents = await HereOS.Exec("ls /users/jeff", {
	username: "jeff",
	password: "mynameisjeff",
});

//DATA
//access 
let {
	ws,
	username,
	cwd,
	//...
} = HereOS.Data;
//you could also change them manually
HereOS.Data.username = "patrick";

//MESSAGES
//listen for any message
HereOS.Data.messageHandlers.set("my-handler", (channel: string, body: string, msgid: string) => {
	console.log(body);	
});

//MODULES
//send bare message
HereOS.Modules.send("Hello");

//modify modules
HereOS.Modules.send = (message: string) => {
	console.log("trying to send message " + message);
	//...
}

Security Notice

NEVER store password or pin persistently.\n ALWAYS sign in using the token immediately. This will prevent sending password or pin with every command. If a command requires full authentication, prefix it with "auth", (e.g. "auth removeself").

Data

BASIC

cwd: string (default: "/");

Path to execute commands in

ws: WebSocket | any

Websocket created by the Init() function.\n Used my the Modules.send() method to send messages.

AUTHENTICATION

card-token: string | undefined

Token used together with a pin.

password: string | undefined

Password used together with the username.

pin: string | undefined

Pin used to execute commands.

token: string | undefined

Token used together with username and IP address. This will not authenticate all actions for security reasons.

username: string | undefined

Username used to execute commands.

HANDLERS

messageHandlers: Map<string, ((channel: string, body: string, msgid: string) => void)>

Map of all message Handlers. Handlers will be run when the WebSocket receives a message.

Functions

Exec(command: string, config?: CommandConfig) => Promise\<string>

1. Creates a message id
2. Sends the command using either config or the HereOS variables
3. Listens incoming messages until one message has the same id
4. Extracts output and cwd from response
5. Updates cwd
6. Returns output

Init(url: string) => Promise\<void>

Most likely only works in browsers. 1. Creates websocket 2. Waits for websocket to open 3. Resolves the promise 4. Listens for messages

UseCard(card_token: string, pin: string) => Promise\<boolean>

1. Stores token and pin as variable
2. Clears username & password variable
3. Runs the "testauth" command to check the credentials
4. Returns command output

UsePswd(username: string, password: string) => Promise\<boolean>

1. Stores username and password as variable
2. Clears token & pin variables
3. Runs the "testauth" command to check the credentials
4. Returns command output

UseToken(username: string, token: string) => Promise\<boolean>

1. Stores username and token as variable
2. Runs the "testauth" command to check the credentials
3. Returns command output

Modules

Modules.send(message: string) => void

Used by the Exec() function. Sends the message to the websocket.\n Modify this method if you are not using a standard WebSocket.

Modules.parse(message: string) => void

Implemented by the Init() function. Extracts data from the message and triggers all handlers. Use this method if you skipped the Init() function and initiated your own WebSocket.

Other

CommandConfig:

interface CommandConfig {
	username?: string,
	password?: string,
	card_token?: string,
	token?: string,
	pin?: string,
	cwd?: string,
}

More Help

Please check out the HereOS documentation if you don't know what is going on here.