Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Pages of your own

gonk’s pages answer the questions every deployment has: what is open, what one item says, what the Dashboard counts. Your team will have questions of its own. How far along is this epic? What lands next? Who is sitting on an expired lease? A face is a page you write to answer one of them, and gonk serves it from its own origin.

This part has three chapters. This one shows what a face is, what gonk refuses it, and builds a first one that lists open items. A board for an epic and Plans, projects and who has what then read the starter’s four samples.

What a face is, and is not

A face is a directory of static files: an index.html, its scripts and its styles. gonk serves them, and they run in the viewer’s browser. Everything a face shows, it reads from gonk’s existing JSON routes, the same ones curl reads in The ledger in a browser, under the viewer’s own session.

A face isA face is not
files you write, in a directory you namea plugin: gonk runs none of its code
served by gonk, read-only, from that directory alonea way to change gonk’s own pages or their theme
a reader of gonk’s routes, as the person viewing ita new authority: it can read only what that person can

A face can also read a mounted peer through the HTTP door. For a peer mounted at urn:metrics:, fetch('/metrics/today', {headers: {Accept: 'application/json'}}) reads urn:metrics:today as the signed-in viewer. Use the mechanical route, not /resolution/iri/, which renders pages. That viewer’s grants must hold the peer’s read token and urn:cap:net:<the peer's host> (localhost for a socket); the face itself adds no authority.

So a face shows nothing its viewer could not read by hand. It can change nothing that gonk did not already let that viewer change. The starter’s faces only read.

What you need

ikigai-gonk and ikigai, as Which gonk installs them, plus git and curl. The gonk this book pins serves faces (introduced in ikigai-gonk PR 295). A browser is what a face is for. To check one from a shell, as this chapter does, you also need Deno 2, which runs the same JavaScript modules the browser loads.

Get the template

The gonk starter carries a template and four sample faces in faces/. In a new empty directory, clone it at the revision this book checks:

$ git clone --quiet https://github.com/ikigai-rs/ikigai-gonk-starter starter
$ git -C starter checkout --quiet 2a5f08cdeec2535d0addb03fcb5b6b62bb870e4a
$ LC_ALL=C ls starter/faces starter/faces/template
starter/faces:
README.md
board
claims
flight
project
template

starter/faces/template:
README.md
app.css
app.js
index.html
kit.js

template/ is the smallest face that works: a form that asks for an item and shows it. kit.js holds what every face needs (an element builder that never parses markup, a same-origin JSON read, gonk’s paths), and every sample carries its own copy. Copy the template to a face of your own, called open:

$ mkdir faces
$ cp -R starter/faces/template faces/open

The one config line

gonk learns about a face from one line in its config home: a name and a directory.

gonk.face = "open /path/to/faces/open"

The name becomes the face’s address, so gonk is strict about it. A line that names no directory, a name with a capital letter, or a line with no directory at all stops gonk at the start, before it opens anything:

$ mkdir refused
$ printf 'gonk.face = "open %s/faces/nowhere"\n' "$PWD" > refused/config.toml
$ ikigai-gonk --config-home "$PWD/refused" --data-home "$PWD/.ikigai" --port 1070 --no-quic --no-backup
ikigai-gonk: gonk.face: face `open`: …/faces/nowhere is not a directory. Create it, or remove the line
  (config read from …/refused/config.toml)
$ printf 'gonk.face = "Open %s/faces/open"\n' "$PWD" > refused/config.toml
$ ikigai-gonk --config-home "$PWD/refused" --data-home "$PWD/.ikigai" --port 1070 --no-quic --no-backup
ikigai-gonk: gonk.face: `Open` is not a face name: lowercase letters, digits and `-`, starting with a letter or digit
  (config read from …/refused/config.toml)
$ printf 'gonk.face = "open"\n' > refused/config.toml
$ ikigai-gonk --config-home "$PWD/refused" --data-home "$PWD/.ikigai" --port 1070 --no-quic --no-backup
ikigai-gonk: gonk.face = "open" is not `<name> <directory>` or `<name> <directory> library` (for example `gonk.face = "ops ~/ops-face"`, or `gonk.face = "graph ~/graph-face library"` for a face that only holds code other faces import)
  (config read from …/refused/config.toml)

The second form, with the word library third, is a face that only holds code other faces import; Code two faces share below uses one. The third word must be exactly library, and a fourth word is refused too, each with the same message quoting the line:

$ mkdir -p faces/shared
$ printf 'gonk.face = "shared %s/faces/shared librray"\n' "$PWD" > refused/config.toml
$ ikigai-gonk --config-home "$PWD/refused" --data-home "$PWD/.ikigai" --port 1070 --no-quic --no-backup
ikigai-gonk: gonk.face = "shared …/faces/shared librray" is not `<name> <directory>` or `<name> <directory> library` (for example `gonk.face = "ops ~/ops-face"`, or `gonk.face = "graph ~/graph-face library"` for a face that only holds code other faces import)
  (config read from …/refused/config.toml)

Now write the real lines, one per face. gonk reads them when it starts, so this writes all three this chapter uses: open, the face built below, and shared and tally, the library and the face that imports from it, which Code two faces share fills in. Each directory must exist before gonk starts, a library’s included.

$ mkdir -p .config/ikigai faces/tally
$ printf 'gonk.face = "open %s/faces/open"\ngonk.face = "shared %s/faces/shared library"\ngonk.face = "tally %s/faces/tally"\n' "$PWD" "$PWD" "$PWD" > .config/ikigai/config.toml

Start gonk, and file something

If the gonk and the model-stub from A query from a sentence are still running, stop them first, since this gonk takes the same port (A gonk per chapter).

$ ikigai-gonk --config-home "$PWD/.config/ikigai" --data-home "$PWD/.ikigai" --port 1070 --no-quic --no-backup
ikigai-gonk 0.1.1 — holding the store at …/.ikigai/store
…

Over the owner’s socket, file two items in default and one in a ledger called notes. The anonymous caller at the HTTP door reads default and not notes, which matters below.

$ ikigai --mount "urn:gk:=$PWD/.ikigai/gonk.sock" -c 'sink urn:gk:iki:ledger:append labels=book Write the faces chapters'
#1 urn:iki:ledger:default:item:…
[uncacheable]
$ ikigai --mount "urn:gk:=$PWD/.ikigai/gonk.sock" -c 'sink urn:gk:iki:ledger:append priority=1 labels=book,pin Move the gonk pin'
#2 urn:iki:ledger:default:item:…
[uncacheable]
$ ikigai --mount "urn:gk:=$PWD/.ikigai/gonk.sock" -c 'sink urn:gk:iki:ledger:notes:append A private note'
notes#1 urn:iki:ledger:notes:item:…
[uncacheable]

Where a face lives

Each face gets a link in the Add-ons row of every gonk page, named by its name. A library face gets none, so shared is not in the row:

$ curl -s http://localhost:1070/ | grep -o "href='/face/name/[^']*'"
href='/face/name/open/'
href='/face/name/tally/'

/face/name/open/ serves the directory’s index.html, and /face/name/open/app.js serves app.js. Every other file is under the same prefix.

A face’s address ends in /, so the template’s relative app.css and app.js resolve inside that face’s directory. The header link includes the slash. A request without it redirects to that address:

$ curl -s -o /dev/null -w '%{http_code}\n' http://localhost:1070/face/name/open/
200
$ curl -s -o /dev/null -w '%{http_code}\n' http://localhost:1070/face/name/open
308
$ open http://localhost:1070/face/name/open/

The template asks for an item. Give it 2 and it shows “Move the gonk pin”, its state and its labels, with a link to gonk’s own page for the item.

What the jail refuses

gonk reads the face’s files through a file endpoint jailed to the directory. It serves only names inside the directory, only a fixed list of file types, and nothing hidden. To see it, put a secret beside the face, a hidden file and a shell script inside it, and a link that points out:

$ echo 'not for the web' > faces/secret.txt
$ echo 'TOKEN=not-for-the-web' > faces/open/.env
$ echo 'echo hi' > faces/open/run.sh
$ ln -s ../secret.txt faces/open/secret.txt

None of them is served. A .. is refused whether it is written plainly or percent-encoded. curl’s --path-as-is sends the path as typed, as an attacker would; without it, some curl versions remove the .. before sending:

$ curl -s --path-as-is -w ' [%{http_code}]\n' http://localhost:1070/face/name/open/../secret.txt
not found: urn:face:name:open:..:secret.txt: a face serves no hidden name [404]
$ curl -s --path-as-is -w ' [%{http_code}]\n' http://localhost:1070/face/name/open/%2E%2E/secret.txt
not found: urn:face:name:open:..:secret.txt: a face serves no hidden name [404]
$ curl -s -w ' [%{http_code}]\n' http://localhost:1070/face/name/open/.env
not found: urn:face:name:open:.env: a face serves no hidden name [404]
$ curl -s -w ' [%{http_code}]\n' http://localhost:1070/face/name/open/secret.txt
invalid argument `path`: `secret.txt` is a symbolic link; this endpoint never follows links [400]
$ curl -s -w ' [%{http_code}]\n' http://localhost:1070/face/name/open/run.sh
not found: urn:face:name:open:run.sh: a face serves only .html, .css, .js, .mjs, .json, .jsonld, .ttl, .txt, .svg, .png, .jpg, .webp, .ico, .woff2 [404]

That last line is the whole list of file types a face may have at this pin. The starter’s faces/README.md also lists .md, which this gonk does not serve. And a face is read-only: nobody, the owner included, can write into it through gonk.

$ curl -s -X PUT --data 'alert(1)' -w ' [%{http_code}]\n' http://localhost:1070/face/name/open/app.js
method not allowed [405]
$ rm faces/secret.txt faces/open/.env faces/open/run.sh faces/open/secret.txt

What the CSP refuses

A face is served under the HTTP door’s default Content Security Policy, the same one gonk’s own pages carry, and it sets none of its own:

$ curl -sI http://localhost:1070/face/name/open/ | grep -i '^content-security-policy'
Content-Security-Policy: default-src 'self'; script-src 'self'; style-src 'self'; object-src 'none'; base-uri 'none'; frame-ancestors 'none'; form-action 'self'

script-src 'self' means a script must be a file from gonk’s own origin. A <script> element with code inside it, or an onclick= attribute, does not run. style-src 'self' does the same for a <style> element and a style= attribute. Write a page that tries it:

<!doctype html>
<html lang="en">
<head><meta charset="utf-8"><title>Inline</title></head>
<body>
  <main>
    <h1>Inline</h1>
    <p id="said">The inline script did not run.</p>
    <script>document.getElementById("said").textContent = "The inline script ran.";</script>
  </main>
</body>
</html>

gonk serves the file as written; the jail reads files, not HTML. The header that comes with it is what makes the browser refuse the script:

$ curl -s -o /dev/null -w '%{http_code} %{content_type}\n' http://localhost:1070/face/name/open/inline.html
200 text/html
$ curl -sI http://localhost:1070/face/name/open/inline.html | grep -io "script-src 'self'"
script-src 'self'
$ open http://localhost:1070/face/name/open/inline.html

The page says “The inline script did not run.”, and the browser’s developer console reports the refused script as a Content Security Policy violation. This is why the starter’s faces keep every script in a file, attach handlers with addEventListener, and style only through classes in app.css. Its kit.js throws if a face asks it for a style or on… attribute, rather than letting the browser drop it silently. Remove the page:

$ rm faces/open/inline.html

Why it lives on gonk’s origin

A face could be any static site. It lives on gonk’s origin because of who is asking. A person signed in to gonk with a passkey holds a session cookie for that origin, and only for it. A page on gonk’s origin reads gonk’s routes with that session, so it sees what that person may see. A page on another origin cannot borrow the session, and gonk refuses a read that another site’s page loads (gonk PR 100, ledger #880), as The ledger in a browser showed with an image.

A browser says which kind of read it is making, in its Sec-Fetch-* headers. Here are the face’s read and the same read from another site’s page:

$ curl -s -o /dev/null -w '%{http_code}\n' -H 'Accept: application/json' -H 'Sec-Fetch-Site: same-origin' -H 'Sec-Fetch-Mode: cors' -H 'Sec-Fetch-Dest: empty' http://localhost:1070/iki/ledger/items
200
$ curl -s -o /dev/null -w '%{http_code}\n' -H 'Accept: application/json' -H 'Sec-Fetch-Site: cross-site' -H 'Sec-Fetch-Mode: cors' -H 'Sec-Fetch-Dest: empty' http://localhost:1070/iki/ledger/items
403

The face itself holds nothing. Its files are added to the anonymous loopback caller’s grant, as the toolbox’s are, so anyone who can open gonk’s pages on this machine can load the face. What the face then reads is judged under the viewer’s own grant. The anonymous viewer here cannot read notes, so the face cannot either:

$ curl -s -H 'Accept: application/json' http://localhost:1070/iki/ledger/notes/items | cut -d. -f1
denied: this capability does not hold `urn:cap:ledger:read:notes`

A viewer reaching gonk from another machine loads the face only if their passkey grant includes reading its directory (urn:cap:fs:read:{dir}). The socket and QUIC doors serve no faces at all.

A first page: the open items

Now turn the template into a page that answers one question: what is open in this ledger? Build it in four steps.

1. Read the route the page will read

A face reads what curl reads. A ledger’s listing is /iki/ledger/items for default and /iki/ledger/{name}/items for any other, and Accept: application/json asks for its JSON face. It answers open items, with a total to page by:

$ curl -s -H 'Accept: application/json' 'http://localhost:1070/iki/ledger/items?status=open' | jq -c '{total, items: [.items[] | {number, title, priority, labels, claim, awaiting}]}'
{"total":2,"items":[{"number":2,"title":"Move the gonk pin","priority":1,"labels":["book","pin"],"claim":null,"awaiting":null},{"number":1,"title":"Write the faces chapters","priority":null,"labels":["book"],"claim":null,"awaiting":null}]}

kit.js already knows this route: listAll(ledger, params) reads every page of a listing, and stateOf(item) turns status, claim and awaiting into words (open, claimed, expired, awaiting, done).

2. Put the question in a module of its own

Keep the question apart from the page, in a module that touches no DOM. A browser and a shell can then both run it. Save this as faces/open/open.js:

// The open face's question, apart from the page: a ledger's open items, most urgent first.
// No DOM here, so a shell can run it as well as a browser.
import { listAll, paths, stateOf } from "./kit.js";

// Lower priority number first, no priority last, then the item number.
function rank(a, b) {
  return (a.priority ?? Infinity) - (b.priority ?? Infinity) || a.number - b.number;
}

// One row per open item: what the page shows, and where its link goes.
export async function openItems(ledger, now = Date.now()) {
  const items = await listAll(ledger, { status: "open" });
  return items.sort(rank).map((it) => ({
    label: `${ledger}#${it.number}`,
    title: it.title || "",
    state: stateOf(it, now),
    labels: it.labels || [],
    href: paths.itemPage(ledger, it.number),
  }));
}

3. Draw it

Replace the template’s app.js with one that asks open.js and draws a list. Every element is made by el, so a title holding <script> stays text, and the result is announced in the page’s one role="status" region:

// The open face: a ledger's open items, each linked to gonk's own page for it.
import { el, announce, query, setQuery } from "./kit.js";
import { openItems } from "./open.js";

const form = document.getElementById("pick");
const out = document.getElementById("out");

function row(r) {
  const note = r.labels.length ? `${r.state}; ${r.labels.join(", ")}` : r.state;
  return el("li", {}, el("a", { href: r.href }, r.label), ` ${r.title} `, el("span", { class: "muted" }, `(${note})`));
}

async function show(ledger) {
  announce(`Reading ${ledger}…`);
  out.replaceChildren(el("h2", { id: "out-h" }, "Open items"));
  try {
    const rows = await openItems(ledger);
    out.append(rows.length ? el("ul", { class: "items" }, rows.map(row)) : el("p", { class: "muted" }, "Nothing is open."));
    announce(`${rows.length} open items in ${ledger}.`);
  } catch (error) {
    out.append(el("p", { class: "warn" }, `Could not read it: ${error.message}`));
    announce(`Could not read ${ledger}.`);
  }
}

form.addEventListener("submit", (event) => {
  event.preventDefault();
  const ledger = form.ledger.value.trim() || "default";
  setQuery({ ledger });
  show(ledger);
});

form.ledger.value = query().get("ledger") || "default";
show(form.ledger.value);

And replace index.html, so the form asks for a ledger alone. The page loads its one stylesheet and its one module as files, which is all the CSP allows:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Open items</title>
  <link rel="stylesheet" href="app.css">
  <script type="module" src="app.js"></script>
</head>
<body>
  <main>
    <h1>Open items</h1>
    <p class="muted">A ledger's open items, most urgent first, each linked to gonk's own page.</p>
    <form id="pick">
      <label>Ledger <input name="ledger" value="default" autocomplete="off"></label>
      <button type="submit">Show</button>
    </form>
    <p role="status" aria-live="polite"></p>
    <section id="out" aria-labelledby="out-h">
      <h2 id="out-h">Open items</h2>
    </section>
  </main>
</body>
</html>

gonk serves the new files at once, with no restart:

$ curl -s http://localhost:1070/face/name/open/ | grep -o '<h1>[^<]*</h1>'
<h1>Open items</h1>
$ curl -s -o /dev/null -w '%{http_code} %{content_type}\n' http://localhost:1070/face/name/open/open.js
200 text/javascript

4. Check it, from a shell and in a browser

Deno runs the same module the browser loads. --location gives it the face’s address, so kit.js reads gonk’s origin as the page does, and --allow-net lets it reach that origin and nothing else. DENO_DIR keeps Deno’s cache in this directory, as --data-home does for gonk. Save the check as show.js:

// What the open face shows, printed: the face's own module, run as the anonymous viewer.
import { openItems } from "./faces/open/open.js";

const ledger = Deno.args[0] || "default";
try {
  for (const r of await openItems(ledger)) console.log(`${r.label} ${r.title} (${r.state}) ${r.href}`);
} catch (error) {
  console.log(`Could not read it: ${error.message}`);
}
$ DENO_DIR="$PWD/.deno" deno run --location http://localhost:1070/face/name/open/ --allow-net=localhost:1070 show.js
default#2 Move the gonk pin (open) /l/default/item/2
default#1 Write the faces chapters (open) /l/default/item/1
$ DENO_DIR="$PWD/.deno" deno run --location http://localhost:1070/face/name/open/ --allow-net=localhost:1070 show.js notes
Could not read it: /iki/ledger/notes/items: 403 Forbidden

The second run is the anonymous viewer asking for notes: the face says what failed, in words, and shows nothing. Each link goes to gonk’s own page for the item:

$ curl -s -o /dev/null -w '%{http_code}\n' http://localhost:1070/l/default/item/2
200
$ open 'http://localhost:1070/face/name/open/?ledger=default'

In the browser, check what the shell cannot. The starter’s faces/README.md lists these checks, and none of them has been run by this book’s checks:

  • what the page shows matches gonk’s own ledger page;
  • the developer console reports no CSP violation;
  • Tab reaches the field, the button and every link, in reading order, with a visible focus ring;
  • at 320 px wide nothing scrolls sideways;
  • it reads in both light and dark mode;
  • an accessibility audit (axe, or the browser’s own) finds nothing.

A face’s markup is yours, and so is its accessibility. gonk’s checks cover gonk’s pages and the header link, not what a deployment serves.

Code two faces share: a library face

Two faces that need the same helper can each carry a copy, as the starter’s samples carry kit.js. A library face holds one copy instead: a directory of modules, configured with the word library third, that other faces import by its address. gonk serves it exactly as it serves any face (the same jail, file types, read grant and CSP), but lists it in no Add-ons row, since there is nothing in it to visit. The shared line above is one. Put a module in it:

// Shared by every face that imports it: a count in words.
export function count(n, one, many) {
  return `${n} ${n === 1 ? one : many}`;
}

Then tally, a second face, imports it by its absolute path on gonk’s origin. script-src 'self' allows that, because the library is a file from the same origin:

// The tally face: how many items are open, in words, with the library's helper.
import { count } from "/face/name/shared/words.js";

const said = document.getElementById("said");
const answer = await fetch("/iki/ledger/items?status=open", { headers: { Accept: "application/json" } });
said.textContent = answer.ok
  ? `${count((await answer.json()).total, "open item", "open items")} in default.`
  : `Could not read it: ${answer.status}`;
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Tally</title>
  <script type="module" src="app.js"></script>
</head>
<body>
  <main>
    <h1>Tally</h1>
    <p id="said" role="status" aria-live="polite">Counting…</p>
  </main>
</body>
</html>

The library’s file is served at its address, and the face’s script names that address:

$ curl -s -o /dev/null -w '%{http_code} %{content_type}\n' http://localhost:1070/face/name/shared/words.js
200 text/javascript
$ curl -s http://localhost:1070/face/name/tally/app.js | grep -o 'from "/face/name/shared/[^"]*"'
from "/face/name/shared/words.js"

A library has no front page unless it carries an index.html, so its own address is a 404. An HTML page it does carry is framed like any face’s:

$ curl -s -o /dev/null -w '%{http_code}\n' http://localhost:1070/face/name/shared/
404

Neither gonk’s row nor the bar gonk writes into a face’s pages lists the library: here is tally’s page, whose Add-ons links are the two listed faces:

$ curl -s http://localhost:1070/face/name/tally/ | grep -o "href=.\?/face/name/[a-z-]*/" | sort -u
href="/face/name/open/
href="/face/name/tally/

If every face were a library, the frame would leave out the Add-ons entry altogether.

$ open http://localhost:1070/face/name/tally/

The page says “2 open items in default.”, counted by the library’s count.

What you have

A face is a directory and one line. gonk serves it read-only and jailed, under a CSP that runs only its files, and every read it makes is the viewer’s own. A library face is the same, minus the Add-ons link, for code more than one face imports. Next, A board for an epic reads the starter’s first sample: an item’s children, their blocks links, and a column for each.