walnut.js/README.md

walnut
======

Small, light, and secure iot application framework.

```bash
curl https://git.daplie.com/Daplie/daplie-snippets/raw/master/install.sh | bash

daplie-install-cloud
```

Features
------

* Works with Goldilocks for secure, Let's Encrypt maneged, https-only serving

* IOT Application server written in [Node.js](https://nodejs.org)
* Small memory footprint (for a node app)
* Secure
  * Uses JWT, not Cookies\*
  * HTTPS-only (checks for X-Forwarded-For)
  * AES, RSA, and ECDSA encryption and signing
  * Safe against CSRF, XSS, and SQL injection
  * Safe against Compression attacks
* Multi-Tentated Application Management
* Built-in OAuth2 & OAuth3 support

\*Cookies are used only for GETs and only where using a token would be less secure
such as images which would otherwise require the token to be passed into the img src.
They are also scoped such that CSRF attacks are not possible.

In Progress
-----------

* HTTPS Key Pinning
* Heroku (pending completion of PostgreSQL support)
* [GunDB](https://gundb.io) Support
* OpenID support

Structure
=====

Currently being tested with Ubuntu, Raspbian, and Debian on Digital Ocean, Raspberry Pi, and Heroku.

```
/srv/walnut/
├── setup.sh (in-progress)
├── core
│   ├── bin
│   ├── boot
│   ├── holepunch
│   └── lib
├── node_modules
├── packages
│   ├── apis
│   ├── pages
│   └── services
└── var
```

* `core` contains all walnut code
* `node_modules` is a flat installation of all dependencies
* `certs` is a directory for Let's Encrypt (or custom) certificates
* `var` is a directory for database files and such
* `packages` contains 3 types of packages

Will install to
---------------

```
/srv/walnut/core/
/etc/walnut
/opt/walnut
/var/log/walnut
/etc/systemd/system/walnut.service
/etc/tmpfiles.d/walnut.conf
```

Implementation details
----------------

Initialization
--------------

needs to know its primary domain

```
POST https://api.<domain.tld>/api/com.daplie.walnut.init

{ "domain": "<domain.tld>" }
```

Resetting the Initialization
----------------------------

Once you run the app the initialization files will appear in these locations

```
/srv/walnut/var/com.daplie.walnut.config.sqlite3
/srv/walnut/config/<domain.tld>.json
```

Deleting those files will rese

Accessing static apps
---------------------

Static apps are stored in `packages/pages`

```
# App ID as files with a list of packages they should load
/srv/walnut/packages/pages/<domain.tld#path>       # https://domain.tld/path
/srv/walnut/packages/pages/<domain.tld>            # https://domain.tld and https://domain.tld/foo match

# packages are directories with reverse dns name   # used for debugging
/srv/walnut/packages/pages/<tld.domain.package>    # matches apps.<domain.tld>/<package-name> and <domain.tld>/apps/<package-name>
```