NodeApp API

How NodeApps work

• A node's owner installs your signed .JawApp package. The node runs your script in a sandbox: plain JavaScript, no files, no timers, no modules, network only to the hosts its manifest lists, and limits on time and memory for every action.
• Someone opens your app: the node calls onOpen and sends back the screen it returns. They press a button: the node calls onAction with the button and the values of the inputs next to it, and sends the next screen. Typing stays on their device until they press a button.
• Screens are data, not code: a tree of predefined elements (text, tables, buttons, text boxes…). Jaw decides how everything looks, inside a border labelled with your app's name, so an app can't imitate Jaw or run anything on a person's device.
• Listed apps are reached through forwarders: nobody on the way learns both who asked and which app, and your app never learns who anyone is or which node they use. It sees a separate stranger per person (or one session for a room).

Get jaw-app

jaw-app is the NodeApp SDK: it makes an app from a template, runs it on your machine in the same sandbox nodes use, with a preview drawn by the Jaw app's own screen component, checks it, and signs it. It comes in the Jaw API package, next to the bot SDK.

You need the .NET 10 SDK (dot.net). Unzip the package, then from its folder:

dotnet tool install --global Jaw.AppKit --add-source ./packages --version 0.0.23

From the Jaw repository instead: dotnet run --project tools/Jaw.AppKit -- <command>.

Quick start

jaw-app new counter my-app
jaw-app run my-app

That makes a folder with two files. manifest.json:

{ "name": "Counter", "description": "Counts your presses, and everyone's", "version": "1.0.0",
  "main": "main.js", "modes": ["individual"], "storageBytes": 1024 }

main.js:

function onOpen(session) { return view(session); }

function onAction(session, action) {
  if (action.button === "add") {
    session.state.count = (session.state.count || 0) + action.values.step;
    storage.set("total", String(Number(storage.get("total") || 0) + action.values.step));
  }
  return view(session);
}

function view(session) {
  return { title: "Counter", body: [
    { type: "text", text: "You: " + (session.state.count || 0) + " · everyone: " + (storage.get("total") || 0) },
    { type: "group", title: "Add", children: [
      { type: "number", id: "step", value: 1, min: 1, max: 10 },
      { type: "button", id: "add", text: "Add", style: "primary" } ] } ] };
}

Change the text, save, and the preview reloads. When it works: jaw-app check my-app, then jaw-app pack my-app, and give the .JawApp to a node's owner (Publishing).

The manifest

The node's owner sees what the manifest asks for and approves it when installing. People using the app never see it (an app could lie in it); they see the name, description, AppID and who signed it.

The script

Define two functions; both return a screen:

• onOpen(session): optional, for the first screen;
• onAction(session, action): required. action is { button, values: { id: value } } (or null when opened, if there's no onOpen).

session is { id, mode, state, member }:

Each action gets a fresh sandbox: keep nothing in global variables. A script that runs too long, uses too much memory, recurses too deep, throws, or returns something that isn't a valid screen fails that action only: the person sees why, and nothing it changed is kept.

Reaching the web

An app can fetch data, a weather forecast for example, from the hosts its manifest lists under network, or from any website with ["any"]. The node makes the requests, never anyone's device, so the website sees the node, not the person. Make onOpen/onAction async and await http:

async function onOpen(session) {
  const data = await http.getJson("https://api.open-meteo.com/v1/forecast?latitude=59.9&longitude=10.7&current=temperature_2m");
  return { title: "Oslo", body: [ { type: "text", text: data.current.temperature_2m + " °C" } ] };
}

Fixed rules, whatever the manifest says:

• https on the usual port only; GET and POST; redirects aren't followed; no cookies.
• Only public addresses: never the node's own machine or local network, checked on the address actually reached.
• Headers: accept, accept-language, authorization, content-type and x-….
• At most 4 requests per action and 60 a minute per app; 64 KB sent and 256 KB read per request; 5 seconds each (15 through Tor). An action may wait that long for each request on top of its runMilliseconds.
• On a node that is reachable only as an onion service, every request goes through Tor, so websites never learn the node's address. If Tor isn't working, the request fails; it's never sent directly.

The owner sees what the app reaches when installing it (installing is the consent), and can turn one app's network off later in Settings → Apps on this node. A refused or failed request rejects with the reason; catch it to show something useful.

Sessions and modes

Room sessions follow the room. When someone is removed, the room's session moves to a new key they don't have, and your app keeps its state; you don't see this happen. An app channel and each message that embeds your app are separate sessions. In jaw-app run, Alice, Bob and Carol are three people in the same room.

Screens

Return { title, body }, where body is a list of elements shown top to bottom:

{ title: "Weather",
  body: [
    { type: "heading", text: "London" },
    { type: "text", text: [ "Now ", { text: "14°C", style: "bold" }, " and dry." ] },
    { type: "group", title: "Another city", children: [
      { type: "textbox", id: "city", label: "City", maxLength: 40 },
      { type: "button", id: "show", text: "Show", style: "primary" } ] } ] }

Elements

Ids (inputs and buttons): 1-64 letters, digits, -, _ or ., unique within the screen. There is no styling beyond this: Jaw decides how everything looks.

Actions

When someone presses a button, the action holds its id and, for every input in the same group (or, for a button outside any group, every input outside a group): text boxes and choices as text, checkboxes and toggles as true or false, numbers as whole numbers. Inputs nobody touched send the value the screen gave them.

The node checks every action against the screen it answers before your script sees it, so an action can't name a button or input the screen didn't have, or a value it doesn't allow (too long, out of range, not an option).

Storage

storage.get(key) and storage.set(key, value) (strings; null removes) reach the app's own store on the node, shared by every session, within storageBytes. set returns false when the store is full. Use session.state for what belongs to one session.

Limits

Publishing: install, list, AppIDs

1. jaw-app pack my-app writes my-app/Name-version.JawApp, signed by your author key. Owners see it as "by account …" with your key's fingerprint; sign every later version with the same key.
2. A node's owner installs it in the Jaw app: Settings → Apps on this node. The node's own people can open it from there.
3. To offer it to everyone, the owner presses List in Apps and gives it an AppID, a network-wide name like nodeapp://counter. AppIDs are claimed like handles: a little proof-of-work, backed by witness nodes, fixed after 6 hours, renewed monthly by the node. App names never use up handles.
4. The app then appears in everyone's Apps tab. Its advert names no node: it's published through a forwarder, and requests reach the app through three forwarders.

The same app on five nodes is five apps, with five keys and five AppIDs.

In rooms: app channels and embeds

• App channels: someone with the ManageApps permission adds a channel of kind App (Room settings → Add channel), naming your AppID and a mode (room or room-pseudonyms). Everyone who can read the channel shares the session.
• Embeds: a message containing nodeapp://counter shows your app under it, optionally nodeapp://poll?mode=pseudonyms or ?mode=room. Each embed is its own session for everyone who reads the message. Channels can turn embeds off (EmbedApps).
• Every app is grayed out behind a warning until a person chooses to open it (or to always trust it).

What apps learn (and don't)

People are warned that an app and its node can see and keep everything they send it. In return, your app never learns who they are: in individual mode it sees a separate stranger per person (and per app), in rooms only the room's session and, if you asked for pseudonyms, a name per person that means nothing outside your session. It doesn't see the room's members or messages. Ask for no more than you need.

NodeApps or bots?

Troubleshooting