Streams

Overview

Every stream has its own address, ending in a 64-character id:

https://streams.relf.cloud/kern/3f9c…64 hexadecimal characters…a1d0

• Streams belong to a space. That's your personal space or a workspace in Kern Cloud. Whatever a stream creates syncs to everyone in that space within moments, like any other change.
• Owners and admins manage them. Streams add work from outside, so members and viewers can't see or change them.
• Settings are enforced by Kern Cloud. Authentication, origins, rate limits, spam checks and validation all happen on the server before anything is created, so they work even when nobody has Kern open.
• Everything is logged. Each submission that reaches a stream leaves an entry in its delivery log, which you can inspect, redeliver, or use to block a sender.

Open Streams from the space menu at the top of Kern's sidebar (Streams…) or with Ctrl+K → Open streams. You'll need Kern Cloud turned on, with the space open.

Quick start

1. In Kern, open the space the work should go to, then choose Streams… → New stream.
2. Pick a starting point. Bug report form sets up summary, description, steps, severity, email, page and browser fields, and maps severity to task priority.
3. Under Destination, choose a project and board column. Under Security, add your website's address to Allowed websites.
4. Copy the ready-made snippet from Overview → Send to it into your site. It's generated from your settings. Then use Try it to preview and send a test.

A plain HTML form needs no JavaScript at all:

<form action="https://streams.relf.cloud/kern/your-stream-id" method="POST">
  <input name="title" required maxlength="200" placeholder="What went wrong?">
  <textarea name="description" required></textarea>
  <select name="severity">
    <option>low</option><option>medium</option><option>high</option><option>critical</option>
  </select>
  <!-- Leave empty: bots fill this in and are ignored. -->
  <input name="_hp" tabindex="-1" autocomplete="off" aria-hidden="true" style="position:absolute;left:-9999px">
  <button type="submit">Send</button>
</form>

After a form post, people see a short thank-you page, or go to your own page if you set Responses → After a form post, go to. For a modal that stays on the page, see the bug report modal example.

Sending submissions

Send a POST request to the stream's address. The body can be:

Form bodies can be turned off with Security → Accept HTML form posts. These request headers have a meaning:

Browsers ask permission first (a CORS preflight OPTIONS request) before sending JSON. The stream answers it for the websites you allow, so no extra setup is needed.

Responses and errors

Responses are JSON. A delivered submission answers 201:

{
  "ok": true,
  "id": 1042,                         // delivery log entry
  "status": "delivered",              // or "partial"
  "message": "Thanks! We've received it."
}

Token and signature streams with Responses → Return ids on also get taskId and issue ({"number", "url"}), and any warnings. Public streams never reveal ids. Every response carries a Kern-Event header with the log entry id.

Refusals look like this, with a link back here:

{ "ok": false, "code": "invalid_fields", "message": "Summary is required.",
  "fields": { "title": "Summary is required" }, "docs": "https://kern.chrisrelf.xyz/docs/streams.html" }

Spam is answered like success. A filled-in honeypot or a blocked sender gets an ordinary 201, so bots learn nothing. The log records it as spam.

HTML form posts

When a plain form posts (form-encoded, with Accept: text/html), the stream answers with a page instead of JSON. If you set a redirect address, people go there with ?kern=ok, or ?kern=error&code=… when something was wrong.

Authentication

Choose one mode per stream under Security → Authentication.

Public

For forms and modals in web pages. There's no secret, because anything in a web page is readable by its visitors. Protection comes from allowed websites, rate limits, the honeypot, optional Turnstile and validation. Use public streams only for things you'd accept from anyone.

Secret token

For your own servers and scripts. Send the stream secret as a bearer token:

curl -X POST "https://streams.relf.cloud/kern/id" \
  -H "Authorization: Bearer $KERN_STREAM_SECRET" \
  -H "Content-Type: application/json" \
  --data '{"title":"Disk almost full","description":"/var is at 93%"}'

Signed requests

The strongest mode, and the one to use from CI. The secret never travels with the request. Each request carries an HMAC-SHA256 of its body and the current time, so it can't be altered, and it can't be replayed:

Kern-Signature: t=unix seconds,v1=hex HMAC-SHA256(secret, "<t>.<raw body>")

• Sign the exact bytes you send. Re-serialising JSON changes the bytes and breaks the signature.
• t must be within the stream's clock tolerance (5 minutes by default, 30 seconds to an hour).
• Each signature is accepted once. Sign every request afresh, including retries.
• During a rotation you may include two v1= values, one per secret.

Node.js:

import { createHmac, randomUUID } from "node:crypto";

const body = JSON.stringify({ title: "Nightly build failed", description: "See run 4821" });
const t = Math.floor(Date.now() / 1000);
const v1 = createHmac("sha256", process.env.KERN_STREAM_SECRET).update(`${t}.${body}`).digest("hex");

const res = await fetch("https://streams.relf.cloud/kern/id", {
  method: "POST",
  headers: { "Content-Type": "application/json", "Kern-Signature": `t=${t},v1=${v1}`, "Idempotency-Key": randomUUID() },
  body,
});

Python:

import hashlib, hmac, json, os, time, urllib.request

body = json.dumps({"title": "Nightly build failed", "description": "See run 4821"}).encode()
t = str(int(time.time()))
v1 = hmac.new(os.environ["KERN_STREAM_SECRET"].encode(), t.encode() + b"." + body, hashlib.sha256).hexdigest()
req = urllib.request.Request("https://streams.relf.cloud/kern/id", data=body, method="POST",
    headers={"Content-Type": "application/json", "Kern-Signature": f"t={t},v1={v1}"})
urllib.request.urlopen(req)

Shell (bash and OpenSSL):

BODY='{"title":"Deploy failed","description":"Job 7 on main"}'
T=$(date +%s)
SIG=$(printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac "$KERN_STREAM_SECRET" -hex | sed 's/^.* //')
curl -X POST "https://streams.relf.cloud/kern/id" \
  -H "Content-Type: application/json" -H "Kern-Signature: t=$T,v1=$SIG" --data "$BODY"

Secrets and rotation

• Secrets look like kss_ followed by 43 characters (256 random bits). Kern shows one when a stream is created.
• Rotate issues a new secret. The old one keeps working for a grace period you choose (up to 7 days), so you can update senders without dropping submissions. Stop accepting it ends the grace period early.
• Owners and admins can reveal the current secret again. Each reveal is recorded in the workspace's activity log.
• Secrets are stored encrypted (AES-256-GCM). Never put a secret in a web page; that's what public streams are for.

Security and spam

Allowed websites

A list of origins: https://example.com, https://*.example.com (any subdomain, not the bare domain), or http://localhost:3000 while developing. When the list isn't empty, requests whose Origin isn't on it are refused, and browsers on other sites aren't allowed to send at all (CORS). Public streams also refuse requests with no Origin header by default (Only from web pages), which stops simple scripts. Origins can be faked outside browsers, so treat this as a filter, not a lock.

Allowed IP addresses

Addresses or CIDR ranges (203.0.113.0/24, 2001:db8::/32). When set, everything else is refused. This works well for CI runners and servers with fixed addresses.

Honeypot

A hidden field (named _hp unless you change it) that people never see and bots fill in. Submissions with it filled in are dropped quietly. Keep the field in your form, hidden with CSS rather than type="hidden", which bots skip. Clear the name to turn it off.

Cloudflare Turnstile

1. Create a Turnstile widget in the Cloudflare dashboard for your site's domain.
2. In Security, turn on Turnstile, paste the site key, and save the secret key. It's stored encrypted and never shown again.
3. Add the widget to your form. The generated HTML snippet includes it. The widget adds a cf-turnstile-response field; JavaScript senders can pass the token in that field or the Kern-Turnstile header.

Turnstile applies to public streams only.

Blocked senders

Kern Cloud never stores sender IP addresses, only a keyed, one-way hash (16 characters) that identifies a repeat sender. Use Block sender on any log entry. Their future submissions look accepted but are dropped. Unblock them under Security.

Rate limits

Per sender (5 a minute and 30 an hour by default) and for the whole stream (200 an hour). Over the limit, senders get 429 with Retry-After. Requests refused before authentication, such as rate limits, bad origins and bad secrets, aren't logged, so nobody can fill your log from outside.

Repeats and retries

• Ignore repeats: an identical submission within 10 minutes (adjustable, 0 turns it off) is recorded once and answered as a duplicate. This catches double-clicks.
• Idempotency-Key: send a unique key per logical submission, and retries with the same key return the original result.

Safe content

• Escape Markdown (on by default) stops submitted text from adding links, images, HTML or formatting to tasks and issues. Your templates still format normally.
• Neutralise mentions (on by default) stops submissions from notifying GitHub users or teams (@name) or cross-referencing other issues (#12).
• Control characters and bidirectional-override characters are removed from all submitted text.
• Kern never renders raw HTML from task descriptions, and doesn't load remote images.

What submissions become

For tasks you can set:

• Project and board column: new tasks go to the bottom of the column and take its status. If the column or project is deleted later, tasks fall back to the project or the Inbox, and the log says so.
• Status (when there's no column) and priority.
• Priority from a field: map submitted values to priorities, for example low → Low and critical → Urgent. Values 0–4 work without a mapping.
• Labels from the space, and a due date a number of days after submission (in the workspace's time zone).

GitHub issues

1. Create a fine-grained personal access token. Choose Only select repositories with just the target repository, grant Issues: Read and write and nothing else, and set an expiry.
2. In the stream's GitHub section, enter the repository as owner/name, save, then paste the token. Kern Cloud checks the token can reach the repository before storing it.
3. Choose GitHub issue or Task + GitHub issue under Destination.

The token is encrypted at rest (AES-256-GCM), used only to open issues for this stream, and can't be read back by anyone. Remove it any time, and revoke it on GitHub if you stop using the stream. Optional issue labels and assignees are sent along; if GitHub refuses them, the issue is opened without them and the log notes it.

With Link to the task on and the task's project connected to the same repository (Project → Code), the task and issue start linked, exactly as if you'd linked them in Kern. Title, description, state and labels then sync both ways, and Kern won't import the issue a second time.

Fields and validation

Declare the fields a stream expects. Each has a key (dots for nesting, like user.email), a label, a type, and optional rules. Submissions that fail are refused with 422 and listed in the log as rejected; nothing is created.

• Required fields must be present and not blank. Optional blank fields are dropped.
• Hidden fields are validated and usable in templates, but left out of {{_fields}}.
• Other fields: Keep accepts undeclared fields and lists them after the declared ones; Reject refuses submissions that contain them.
• The honeypot field and cf-turnstile-response are removed before validation.

Templates

The title and body are templates. {{key}} inserts a submitted value ({{user.email}} for nested ones). The body is Markdown. If the title renders empty, the fallback title is used.

Filters follow a bar: {{severity | upper}}, lower, trim, json, and {{name | default:"Anonymous"}}. For example:

Title:  [{{severity | upper | default:"BUG"}}] {{title}}
Body:   Reported by {{email | default:"someone anonymous"}} on {{page}}

        {{_fields}}

A footer with where and when the submission arrived is added by default (Add a footer), and the raw submission can be attached too. Titles are cut at 200 characters and bodies at 60,000.

Delivery log

Everything that passed authentication is logged with one of these outcomes:

• Open an entry to see the submitted data, the website, the anonymised sender, the client and how long delivery took.
• Redeliver runs a logged submission through the stream again, with its current settings.
• Entries are kept 30 days by default (1 to 90). Turn off Keep submitted data to keep only outcomes; you then can't redeliver.
• Notifications: people with the space open see each delivery in Kern (each person can turn this off in Settings → Cloud). Email can go to the stream's creator or all admins for every submission or only problems, at most one a minute per stream.

Limits

Examples

A bug report modal

Using the Bug report form starting point, with your site in Allowed websites:

<dialog id="bug">
  <form id="bug-form">
    <h2>Report a bug</h2>
    <input name="title" required maxlength="200" placeholder="Summary">
    <textarea name="description" required placeholder="What happened?"></textarea>
    <textarea name="steps" placeholder="Steps to reproduce (optional)"></textarea>
    <select name="severity"><option>low</option><option selected>medium</option><option>high</option><option>critical</option></select>
    <input name="email" type="email" placeholder="Email, if we may follow up">
    <input name="_hp" tabindex="-1" autocomplete="off" aria-hidden="true" style="position:absolute;left:-9999px">
    <p id="bug-status" role="status"></p>
    <button>Send</button>
  </form>
</dialog>

<script>
  const STREAM = "https://streams.relf.cloud/kern/your-stream-id";
  const form = document.getElementById("bug-form");
  const status = document.getElementById("bug-status");

  form.addEventListener("submit", async (event) => {
    event.preventDefault();
    const data = Object.fromEntries(new FormData(form));
    status.textContent = "Sending…";
    try {
      const res = await fetch(STREAM, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ ...data, page: location.href, browser: navigator.userAgent }),
      });
      const out = await res.json();
      if (!out.ok) {
        status.textContent = res.status === 429 ? `Please wait ${out.retryAfter} seconds and try again.` : out.message;
        return;
      }
      status.textContent = out.message;
      form.reset();
      setTimeout(() => document.getElementById("bug").close(), 1500);
    } catch {
      status.textContent = "Couldn't send. Check your connection and try again.";
    }
  });
</script>

GitHub Actions: open an issue when a workflow fails

A signed stream set to Task + GitHub issue, with the secret saved as the repository secret KERN_STREAM_SECRET:

- name: Report failure to Kern
  if: failure()
  env:
    KERN_STREAM_SECRET: ${{ secrets.KERN_STREAM_SECRET }}
    KERN_STREAM_URL: https://streams.relf.cloud/kern/your-stream-id
  run: |
    BODY=$(jq -nc --arg t "CI failed on ${GITHUB_REF_NAME}" \
      --arg b "Run: ${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}" \
      '{title: $t, body: $b}')
    T=$(date +%s)
    SIG=$(printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac "$KERN_STREAM_SECRET" -hex | sed 's/^.* //')
    curl -fsS -X POST "$KERN_STREAM_URL" \
      -H "Content-Type: application/json" \
      -H "Kern-Signature: t=$T,v1=$SIG" \
      -H "Idempotency-Key: ${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}" \
      --data "$BODY"

Forward from your own backend

If you'd rather not expose the stream to browsers at all, post from your server with a token or signature. Your server can add details only it knows, such as the signed-in user's id.

// e.g. an Express route behind your own authentication
app.post("/api/feedback", async (req, res) => {
  const r = await fetch(process.env.KERN_STREAM_URL, {
    method: "POST",
    headers: { "Content-Type": "application/json", Authorization: `Bearer ${process.env.KERN_STREAM_SECRET}` },
    body: JSON.stringify({ title: req.body.title, message: req.body.message, account: req.user.id }),
  });
  res.status(r.ok ? 204 : 502).end();
});

Troubleshooting