Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 7 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ The public page at https://live.setkernel.com: a Cloudflare Worker with static a
Durable Object. sk-obs01 pushes filtered, delayed events to it; visitors watch over a WebSocket.
It also holds `workers/meter`, sk-meter, the Cloudflare billing guard (an hourly cron, no route;
`workers/meter/README.md`), moved here on 2026-11-09 (setkernel/hq#1449).
`workers/status` is sk-status's code (the `/status` read model on ctl.setkernel.net), moved the same
day; it has never been deployed and nothing here deploys it (`workers/status/README.md`).
Public repo: everything here is visible to anyone.

## Commands
Expand All @@ -24,8 +26,9 @@ Public repo: everything here is visible to anyone.
# and repo names against GitHub's public list, live)
# worker: npm run test:worker (vitest in workerd: the real Worker and Hub, see test/worker/)
# meter: npm run test:meter (node --test: sk-meter's guard, usage queries, alert, baseline)
# status: npm run test:status (node --test: sk-status's board, views, Access check, routes)
# lint: npm run check (node --check on every script)
# validate: npm run validate (check + test + test:worker + test:meter + a wrangler deploy --dry-run
# validate: npm run validate (check + test + test:worker + test:meter + test:status + a wrangler deploy --dry-run
# of each Worker; what CI runs)
```

Expand Down Expand Up @@ -102,6 +105,9 @@ or nothing live to roll back to, gives the issue `owner` too.
- `workers/meter/`: sk-meter, its own Worker (`wrangler.toml`, not `wrangler.jsonc`): `src/` the hourly
run and the guard flags, `allowances.json`, `tools/` the baseline and the offline drill, `test/` its
`node --test` suites. Its settings come from the Infisical -> Workers sync (`keep_vars = true`).
- `workers/status/`: sk-status (`wrangler.toml`): `src/` the routes, the `Board` Durable Object and the
views, `public/status/fonts/`, `test/` (its `setup.js` resolves `cloudflare:workers` to a stand-in).
Not deployed; its writer, the control Worker, is being retired.
- `test/`: `node --test` suites for the pure modules and the page (`day.test.mjs` for Day).
- `test/worker/`: vitest suites run in workerd by `@cloudflare/vitest-plugin` (`vitest.config.mjs`
reads `wrangler.jsonc`). They fake Access's certs with a throwaway key and drive every route
Expand Down
5 changes: 3 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,9 @@
"test": "node --test test/*.test.mjs",
"test:worker": "vitest run",
"test:meter": "node --test workers/meter/test/*.test.js",
"check": "for f in src/*.js public/*.js public/lib/*.js public/usage/*.js scripts/*.mjs workers/meter/src/*.js workers/meter/tools/*.mjs; do node --check \"$f\" || exit 1; done",
"validate": "npm run check && npm test && npm run test:worker && npm run test:meter && wrangler deploy --dry-run --outdir .wrangler/dry-run && wrangler deploy --dry-run --config workers/meter/wrangler.toml --outdir .wrangler/dry-run-meter"
"test:status": "node --import ./workers/status/test/setup.js --test workers/status/test/*.test.js",
"check": "for f in src/*.js public/*.js public/lib/*.js public/usage/*.js scripts/*.mjs workers/meter/src/*.js workers/meter/tools/*.mjs workers/status/src/*.js; do node --check \"$f\" || exit 1; done",
"validate": "npm run check && npm test && npm run test:worker && npm run test:meter && npm run test:status && wrangler deploy --dry-run --outdir .wrangler/dry-run && wrangler deploy --dry-run --config workers/meter/wrangler.toml --outdir .wrangler/dry-run-meter && wrangler deploy --dry-run --config workers/status/wrangler.toml --outdir .wrangler/dry-run-status"
},
"dependencies": {
"@noble/secp256k1": "3.2.0"
Expand Down
70 changes: 70 additions & 0 deletions workers/status/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
# sk-status: the read model of the org

A page for Raghav, the internal wall and the showcase's publisher: sk-meter's guard flags and
the last 24 hours of merges and failures, on `ctl.setkernel.net/status` behind Access.

It moved here from a private repository on 2026-11-09 (setkernel/hq#1449, plan v6 F3). Its
history up to then is that repository's `status/` at commit `c1e3253`.

**It has never been deployed, and nothing deploys it from here.** Its only writer was the
control Worker, which publishes over a service binding (the `Feed` entrypoint) and is
being retired in hq#1449. Without it the board stays empty and the page shows only the guard.
Deploying it is Raghav's call ("The first deploy", below); until then this is code and tests
only, checked by `npm run validate`.

## How it works
- `src/board.js` `Board`: one SQLite Durable Object (`BOARD`, name `org`). Each writer publishes
its own view here after it changes, and `/status` reads this one object.
- An item applies only with a higher `rev` than the board holds. Reaching `merged` or `failed`
adds one row to `events`; `closed` and `new` take an item off the board without one.
- Each publish prunes ended items and events older than 24 hours. No alarms, no WebSockets.
- `src/model.js`: checks a published batch against the state list (`STATES`) and builds the two
views. One bad entry is rejected with its index and reason; the rest of the batch applies.
- `src/index.js`: the routes, the Access check, the guard, and the `Feed` entrypoint.
- `src/access.js`: who may read (`STATUS_CLIENTS` scopes) and the Access token check.
- `src/html.js`: the phone page, no script. Manrope is self-hosted under `public/status/fonts/`
with its licence; the last fallback is `sans-serif`.
- It imports one module from outside this folder: `../../meter/src/flags.js` (the guard).

## Routes
All on `ctl.setkernel.net`, behind an Access app for `ctl.setkernel.net/status` and
`ctl.setkernel.net/status/*` (not in setkernel-cloudflare tofu yet). The Worker routes are the
same two patterns.

| Route | Who | What |
|---|---|---|
| `GET /status` | a person | HTML when the browser asks for it, JSON otherwise |
| `GET /status/internal.json` | a person, or an `internal` service token | `{ generated_at, snapshot_at, guard, last_24h }` |
| `GET /status/public.json` | anyone let in, including a `public` token | `{ generated_at, last_24h: { merged, failed } }`, built field by field |
| `/status/fonts/*` | (static assets) | the two font files and `OFL-Manrope.txt` |

The Worker verifies `Cf-Access-Jwt-Assertion` itself (RS256, setkernel's team, audience
`STATUS_ACCESS_AUD`). A token with an `email` is a person and sees everything. A service token
gets in only if `STATUS_CLIENTS` lists its client id as `internal` or `public`; a `public` token
gets a 403 on anything but `/status/public.json`. With `STATUS_ACCESS_AUD` unset, every request
is a 401.

## The guard
`/status` reads sk-meter's flags at most once a minute per isolate. Under `guard:degrade`
snapshots are reused longer (person 60 s, service token 600 s; normally 15 s and 120 s). Under
`guard:refuse`, `/status/public.json` answers 503 with `retry-after`; people still see the page.

## What it costs
Estimated with two pollers at one a minute: about 176,000 Workers requests (1.8% of the
included 10M) and up to 190,000 Durable Object requests (19% of 1M at worst) a month
(https://developers.cloudflare.com/workers/platform/pricing/,
https://developers.cloudflare.com/durable-objects/platform/pricing/).

## Commands
```sh
npm run test:status # node --test, with cloudflare:workers resolved to test/cloudflare-workers.js
```

## The first deploy (Raghav, only if the page is wanted)
1. setkernel-cloudflare: the Access app for the two paths (allow Raghav; two service tokens for
the wall and the publisher), `setkernel.net` in `deploy_tokens["setkernel-live"].zones`, and
`workers_admin` for one deploy (Workers Editor can't create a Worker).
2. Infisical `sk-ctl-workers/prod`, folder `/sk-status`: `STATUS_ACCESS_AUD` and `STATUS_CLIENTS`
from tofu outputs, and a Workers sync from that folder (never `/`) to the Worker `sk-status`.
3. A deploy job here, like `meter` in `.github/workflows/deploy.yml`.
4. Remove `workers_admin` again.
93 changes: 93 additions & 0 deletions workers/status/public/status/fonts/OFL-Manrope.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
Copyright 2019 The Manrope Project Authors (https://github.com/sharanda/manrope)

This Font Software is licensed under the SIL Open Font License, Version 1.1.
This license is copied below, and is also available with a FAQ at:
http://scripts.sil.org/OFL


-----------------------------------------------------------
SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
-----------------------------------------------------------

PREAMBLE
The goals of the Open Font License (OFL) are to stimulate worldwide
development of collaborative font projects, to support the font creation
efforts of academic and linguistic communities, and to provide a free and
open framework in which fonts may be shared and improved in partnership
with others.

The OFL allows the licensed fonts to be used, studied, modified and
redistributed freely as long as they are not sold by themselves. The
fonts, including any derivative works, can be bundled, embedded,
redistributed and/or sold with any software provided that any reserved
names are not used by derivative works. The fonts and derivatives,
however, cannot be released under any other type of license. The
requirement for fonts to remain under this license does not apply
to any document created using the fonts or their derivatives.

DEFINITIONS
"Font Software" refers to the set of files released by the Copyright
Holder(s) under this license and clearly marked as such. This may
include source files, build scripts and documentation.

"Reserved Font Name" refers to any names specified as such after the
copyright statement(s).

"Original Version" refers to the collection of Font Software components as
distributed by the Copyright Holder(s).

"Modified Version" refers to any derivative made by adding to, deleting,
or substituting -- in part or in whole -- any of the components of the
Original Version, by changing formats or by porting the Font Software to a
new environment.

"Author" refers to any designer, engineer, programmer, technical
writer or other person who contributed to the Font Software.

PERMISSION & CONDITIONS
Permission is hereby granted, free of charge, to any person obtaining
a copy of the Font Software, to use, study, copy, merge, embed, modify,
redistribute, and sell modified and unmodified copies of the Font
Software, subject to the following conditions:

1) Neither the Font Software nor any of its individual components,
in Original or Modified Versions, may be sold by itself.

2) Original or Modified Versions of the Font Software may be bundled,
redistributed and/or sold with any software, provided that each copy
contains the above copyright notice and this license. These can be
included either as stand-alone text files, human-readable headers or
in the appropriate machine-readable metadata fields within text or
binary files as long as those fields can be easily viewed by the user.

3) No Modified Version of the Font Software may use the Reserved Font
Name(s) unless explicit written permission is granted by the corresponding
Copyright Holder. This restriction only applies to the primary font name as
presented to the users.

4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
Software shall not be used to promote, endorse or advertise any
Modified Version, except to acknowledge the contribution(s) of the
Copyright Holder(s) and the Author(s) or with their explicit written
permission.

5) The Font Software, modified or unmodified, in part or in whole,
must be distributed entirely under this license, and must not be
distributed under any other license. The requirement for fonts to
remain under this license does not apply to any document created
using the Font Software.

TERMINATION
This license becomes null and void if any of the above conditions are
not met.

DISCLAIMER
THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
OTHER DEALINGS IN THE FONT SOFTWARE.
Binary file not shown.
Binary file not shown.
85 changes: 85 additions & 0 deletions workers/status/src/access.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
// Who may read /status. Access admits only its policy's people and service tokens at the edge
// (setkernel-cloudflare, access stack); index.js checks the token again with verifyAccessJwt
// below, so a mistake in the Access config still can't open the page. This file verifies the
// token and maps the verified claims to a viewer and a scope. jwksFetcher and verifyAccessJwt
// began as a copy of the control Worker's access.js (setkernel-live's before it); status keeps its own.

export const ISSUER = "https://setkernel.cloudflareaccess.com";
export const CERTS = `${ISSUER}/cdn-cgi/access/certs`;

function b64urlBytes(s) {
const b64 = s.replace(/-/g, "+").replace(/_/g, "/") + "===".slice((s.length + 3) % 4);
return Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
}
const b64urlJson = (s) => JSON.parse(new TextDecoder().decode(b64urlBytes(s)));

// Access's signing keys, cached for an hour (they rotate rarely). An unknown kid refetches, but
// not more than once every minRefetchMs, so junk tokens can't turn every request into a fetch.
export function jwksFetcher(url = CERTS, ttlMs = 3600_000, fetchFn = (u) => fetch(u), minRefetchMs = 60_000) {
let keys = null;
let at = 0;
return async (kid) => {
const age = Date.now() - at;
const unknown = kid && keys && !keys.some((k) => k.kid === kid);
if (!keys || age >= ttlMs || (unknown && age >= minRefetchMs)) {
const r = await fetchFn(url);
if (!r.ok) throw new Error(`certs: HTTP ${r.status}`);
keys = (await r.json()).keys ?? [];
at = Date.now();
}
return keys;
};
}

// The claims of an unexpired RS256 token from setkernel's Access, for this app (aud), signed by
// one of Access's current keys; null for anything else.
export async function verifyAccessJwt(token, { aud, getKeys, issuer = ISSUER, now = Date.now() }) {
try {
const parts = (token || "").split(".");
if (parts.length !== 3 || !aud) return null;
const header = b64urlJson(parts[0]);
const claims = b64urlJson(parts[1]);
if (header.alg !== "RS256" || claims.iss !== issuer) return null;
const auds = Array.isArray(claims.aud) ? claims.aud : [claims.aud];
if (!auds.includes(aud)) return null;
if (!Number.isFinite(claims.exp) || claims.exp * 1000 <= now) return null;
if (Number.isFinite(claims.nbf) && claims.nbf * 1000 > now + 60_000) return null;
const jwk = (await getKeys(header.kid)).find((k) => k.kid === header.kid);
if (!jwk) return null;
const key = await crypto.subtle.importKey("jwk", jwk, { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" }, false, ["verify"]);
const ok = await crypto.subtle.verify("RSASSA-PKCS1-v1_5", key, b64urlBytes(parts[2]), new TextEncoder().encode(`${parts[0]}.${parts[1]}`));
return ok ? claims : null;
} catch {
return null;
}
}


export const SCOPES = ["internal", "public"];

// STATUS_CLIENTS: { "<service token client id>": "internal" | "public" }. The wall's token gets
// internal; the showcase publisher's gets public, so it can only ever read the sanitized view.
// Answers a Map; an unset or malformed variable is an empty one (no service token is let in).
export function clientScopes(raw) {
try {
const parsed = typeof raw === "string" ? JSON.parse(raw) : null;
if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return new Map();
const entries = Object.entries(parsed);
if (entries.some(([id, scope]) => !id || !SCOPES.includes(scope))) return new Map();
return new Map(entries);
} catch {
return new Map();
}
}

// Verified claims -> who is asking: { who: "person", email } for someone who signed in through
// Access, { who: "service", scope } for a listed service token, or null. A service token's
// claims carry common_name (its client id) and no email.
export function viewer(claims, scopes) {
if (!claims) return null;
if (typeof claims.common_name === "string" && claims.common_name) {
const scope = scopes.get(claims.common_name);
return scope ? { who: "service", scope } : null;
}
return typeof claims.email === "string" && claims.email ? { who: "person", email: claims.email } : null;
}
Loading
Loading