wissel.net Usability - Productivity - Business - The web - Singapore and Twins

JWT for machine to machine communication

Stephan H. Wissel — 20 September 2026

There are plenty of IdP available that provide OIDC flows for your users, including Domino, even if some can't read RFC 6749) properly (I'm looking at you Okta and Ping)*

When it comes to machine identity the situation becomes murkier. Machines might or might not be in your directory, directory admins might be reluctant to add machines etc. etc. So some utility needs to help out here

Generating access_token

I wrote about about generating JWT before, but in needs more context. So lets have a look what is actually needed:

a means to identify the machine
the shape of the access token required
the trusted key pair to sign and validate the key

How we trained Lotus Notes

Stephan H. Wissel — 12 September 2026

A recent post on vowe.net pointing to Lotus Notes and the dangers of starting from scratch sent me down the memory lane into the 1990ties.

Collaboration training

Companies would send regular employees in groups of 10 -20 to a full day training to learn about that new thing "collaboration" (which gave the word collaborator a less perilous meaning). This is how it would go down in four modules:

In the first module the Notes discussion database gets introduced. Participants would learn about topics, responses and response-to-responses. Without seeding lively discussions would emerge.

The second module would focus on eMail, inbox, signature, encryption, richtext and - everybody's favorite - permanent pen.

Followed by the lunch break

The trainer would have prepared individual emails to all participants. Most of them with harmless request like "What's your favorite color" or "Ask your colleague about the last holiday". Two emails however had loaded requests: "Stand up and put your one hand on your head" and "stand up and sing or hum the national anthem (considered unproblematic in Switzerland)"

Unsurprisingly hardly any of the recipients of such a message complied. The trainer would then ask a random participant to join in front to face the class, followed by the explanation: "You can't expect email to transport requests that a better issued in person (paraphrasing here)".

Time for a coffee break with gipfeli.

The trainer then introduced module four "Imagine you are all distributed in regional offices, so you can't show paper documents to each other, solve the problem I'll hand out". I then would hand out sheets of paper with the sentence "Every capital letter is part of the solution". The sheets were all different with different letters capitalized, so the task was to collect the capital letters and form the solution LOTUS NOTES. This wasn't explained to the participants though.

Typically a barrage of emails would follow with different levels of speculation, curiosity, acceptance or ridicule. After 20-30 minutes the task would have been figured out at the "cost" of 100+ emails. The winning team (we informally tracked completion time) however took less that three minutes: One participant created a discussion entry "Please share all capital letters on your sheets" and sent a doc link (hyper link in today's lingo) to the rest. 10 response documents later they were done.

Participant reported a better understanding of "Zusammenarbeit (collaboration)" and "Benachrichtigung (notification)" which made them appreciate the shiny new tool.

I loved this sessions since the showed not only how to use the tools, but why and when and when not.

HCL opensources CouchCompanion

Stephan H. Wissel — 09 September 2026

I'm a big fan of Apache CouchDB, so I was very pleased when I got the permission to opensource (is that even a verb) a R&D project we were working on for a while, meet CouchCompanion

Fauxton as role model

We were asking us, how would CouchDB's admin ui Fauxton look like when you rebuild today, what would be the tech stack and new or enhanced features. This is what we can up with:

build with webcomponents, namely Webawesome and Lit, no big framework like react or angular
Native fetch()
All JSON and JS Code editable with the Monaco editor (the one used in VSCode)
Support to build Mango queries and indici
Sync with version control (Github for the moment, fighting with CORS and CSP)
dark/lght mode
UI to configure OIDC IdP

... and more. There is a capability walkthrough available. But to really get a feel, just run the container:

docker run -d --name couch-companion -p 5984:5984 \
  -e COUCHDB_USER=admin -e COUCHDB_PASSWORD=<choose one> \
  -v couchdb_data:/opt/couchdb/data \
  ghcr.io/hcl-tech-software/couch-companion:latest

The container is based on the official CouchDB image with Fauxton swapped out for CouchCompanion. Give it a spin!

Using age in Github actions

Stephan H. Wissel — 24 August 2026

In the last article I introduced age and a working setup for macOS. Now let's look at Github actions integration

TL/DR

In a nutshell: create an age key just for GitHub actions, commit it to secrets, add the public key to recipients.txt and add it to your github job.

Harden your developer setup with age and direnv

Stephan H. Wissel — 21 August 2026

Credential stealing is rampant, so some diligence in guarding API keys, passphrases and secrets is warranted.

Stop wondering if it could happen to you, but prepare for when it might happen. Here is one arrow in your defense portfolio.

Limit the blast radius

When an attacker sneaks by your 2FA using e.g a supply chain attack your next line of defense is "How much can they see?"

For starters no key (other than public ones), token or credential shall live on disk unencrypted.
Loaded evn variables should be limited to their projects, when in ~/Code/someproject there must not be any env variable from ~/Code/otherproject be loaded.
The day-2-day use must be easy and convenient

Three components

To make this work we need three components:

macOS keychain: holds the AGE key(s), (Other operating systems is another story for another time).
age "Actually good encryption": to encrypt your secrets and .env variables.
direnv: Loads and unloads environment variables depending on the current directory.

Use tmux to automate your developer setup

Stephan H. Wissel — 12 August 2026

For my development setup I typically rely on Development Containers which works very UI centric. Your Ide discovers the .devcontainer folder and boots an edit container and starts whatever you have defined in your docker-compose.yml file. This is great for sharing, I wrote about it, read for a refresher.

In a terminal centric world this is a heavy approach and I want options

Multiplex your terminal

My goal: with a single script start quarkus dev, twice npm run dev and a database (Apache CouchDB, glad you asked). They all need to run in the foreground, so I can keep an eye on them. This precludes simply using & to run them in the background.

Enter tmux. The wiki describes it: "tmux is a terminal multiplexer. It lets you switch easily between several programs in one terminal, detach them (they keep running in the background) and reattach them to a different terminal." Claude described it like this (might contain emscripten):

Claude's take on tmux

Old habits die hard: you open a terminal, start a long running task, your SSH (Secure Shell) connection drops and your task dies with it. Enter tmux, the terminal multiplexer. It sits between your terminal and your shell sessions, so the sessions live on the server (or your machine), not in the window you happen to be looking at. Close the laptop, reconnect from the coffee shop, run tmux attach and everything is exactly where you left it.
Multiplexing is the second trick: one terminal window hosts multiple sessions, each with multiple windows (think tabs), each split into panes. API server on the left, logs on the right, a shell at the bottom — all navigated by keyboard, no mouse gymnastics required. Everything hangs off a prefix key, Ctrl-b by default, which the seasoned crowd promptly remaps to Ctrl-a (a habit inherited from GNU screen, tmux's venerable predecessor).
The price of admission is a modest set of keyboard shortcuts and, optionally, a ~/.tmux.conf to bend it to your will. The payoff: sessions that survive disconnects, scripted development environments that launch your entire workspace with one command, and even pair programming by attaching two people to the same session. As usual YMMV.

Signing your git commits

Stephan H. Wissel — 06 August 2026

Code pedigree is more important than ever with the ever increasing rate of supply chain attacks. Setting up code signing are a few steps, recorded here for reference.

Choice of key formats

While you could pick an ssh or x509 key, I shall stick to gpg and the Ed25519 algorythm.

Act 1 - get macOS ready

When you followed earlier advice you are good to go. If not, install Homebrew and dependencies

brew install gh gpg pinentry-mac

# setup pinentry
mkdir -p ~/.gnupg
chmod 700 ~/.gnupg
echo "pinentry-program $(brew --prefix)/bin/pinentry-mac" >> ~/.gnupg/gpg-agent.conf
gpgconf --kill gpg-agent

Act 2 - create the key

This creates a signing key that lasts for 2 years. Make sure to get the eMail right. After creation we extract the key id.

gpg --batch --quick-generate-key "John Doe <john.doe@example.com>" ed25519 sign
TARGET_EMAIL="john.doe@example.com"
GPG_KEY_ID=$(gpg --list-secret-keys --with-colons "$TARGET_EMAIL" 2>/dev/null \
             | awk -F: '$1=="sec" {print $5; exit}')
echo Your key id is $GPG_KEY_ID

You also can do that manually running gpg --list-secret-keys --keyid-format=long and look for the string after the / in the line starting with sec.

Act 3 - configure your local git

Make sure to get the eMail right

git config --global user.name "John Doe"
git config --global user.email "$TARGET_EMAIL"
git config --global user.signingkey "$GPG_KEY_ID"
git config --global commit.gpgsign true
git config --global tag.gpgsign true
git config --global pull.rebase true

Act 4 - Let github know

Display the public key:

gpg --armor --export $GPG_KEY_ID

Go to your Github key settings, click on "New GPG key" and paste it

Act 5 - overwrite for individual repos (optional)

git config user.name "John Doe"
git config user.email "$TARGET_EMAIL"
git config user.signingkey "$GPG_KEY_ID"
git config commit.gpgsign true
git config tag.gpgsign true
git config pull.rebase true

For adventurous souls there is a setup script available to automate this. Use at your own risk.

As usual YMMV

welcome http query

Stephan H. Wissel — 17 July 2026

In 2026, after a 16 years pause, HTTP gained a new keyword QUERY. Much has been said and said about the GET with a body. But why did it take so long?

Agreement not implementation

I'll share a secret: QUERY has been supported by HTTP for a long time. So has HTTP UNIVERSE or HTTP TANGO The protocol doesn't care for the keyword. Your client an server care. HTTP GET can't contain a body - nonsense. Of course it can. And you can expect, unless you control both sides, that it will fail in one way or another.

So the IETF standards are the etiquette of interaction, not the laws. They are the gentlemen agreement stating "If we both follow the RFC, we can have the reasonable expectation that this exchange of information could work".

Hammering out agreements that don't break previous ones it time consuming and tedious, especially in venerable, foundational standards like http. just see how time tested the standards surrounding http are:

Standards

Method	Standardized	Document
GET	1991	HTTP/0.9
GET, HEAD, POST	1996	RFC 1945
OPTIONS, PUT, DELETE, TRACE, CONNECT	1997	RFC 2068
	refined 1999	(HTTP/1.1) RFC 2616
PATCH	2010	RFC 5789
Summarized HTTP semantics	2022	RFC 9110
QUERY	2026	RFC 10008

Extensions

Extension	Since	Document	Methods added
WebDAV (core)	1999	RFC 2518	PROPFIND, PROPPATCH, MKCOL, COPY, MOVE, LOCK, UNLOCK
	revised 2007	RFC 4918
DeltaV (versioning)	2002	RFC 3253	CHECKOUT, CHECKIN, VERSION-CONTROL, REPORT, MERGE, …
Ordered Collections	2003	RFC 3648	ORDERPATCH
ACL (Access Control List)	2004	RFC 3744	ACL
CalDAV (calendaring)	2007	RFC 4791	MKCALENDAR
SEARCH	2008	RFC 5323	SEARCH
BIND (bindings)	2010	RFC 5842	BIND, UNBIND, REBIND
CardDAV (contacts)	2011	RFC 6352	(reuses WebDAV methods)

The WebDAV SEARCH method (2008) was the early inspiration for QUERY — drafts even used the name SEARCH before the working group settled on QUERY to avoid the WebDAV baggage and map cleanly onto the URI query component.

HTTP anything

Don't believe HTTP TANGO would work? Just clone my little fun project, run it and open the developer tools to watch the network.
Works, since it controls both ends.

Tooling needs to catch up

Now QUERY is a standard, tooling needs to catch up. Enums need extension and adjacent standards updated. E.g OpenAPI 3.x has no provision for new HTTP syntax, while Bruno and curl do just fine.

As usual YMMV

sharing vs routing

Stephan H. Wissel — 01 July 2026

Common to all collaboration platforms is the ability to define what items (files, emails, chats, videos) get shared with whom and how (read-only, read-write, comment). What is missing is sharing the intend or purpose. There is what, who, how but not why.

Formal workflow systems on the other hand, while rigid in the way they operate, thrive on intend: "for review", "for approval", "for risk analysis" and so on.

Finding the middle ground

Capturing the purpose or intend allows to uncover actual (soft) workflows. The challenge to solve is to make it worthwhile to the regular users to declare their intend (which by itself is hilarious: how to declare the intend "cover-my-backside" in office compatible lingo?)

A few ideas how to implement this:

make it easy, the dialogue defining the share includes a field for intend. Most sharing dialogues allow notifications, so it is half way there
adjust the language in the UX: add a "route to" capability
integrate it into a task management system (I'd favour GTD)
add a fancy dashboard to visualize flows
find promoters who are keen to try that way of work
use machine learning to predict the routing (been there, done that)

Is this a good idea, what do you think?

My AI coding workflow

Stephan H. Wissel — 08 May 2026

There are infinite opinions available how to use AI in software development. I haven't formed one, so I'm documenting what, so far has worked for me. I distinguish between the ideation phase, which's output is a set of specs, issues, tickets, whatever you call it and the implementation phase, which's output is working code.

The two phases run in sequence (doh), but not exclusive. E.g. while feature one and two run through implementation, feature three and four csn be in ideation. This post is about the implementation phase.

Chinese whispers (AI edition)

Based on the ideation phase I start with a set of github issues. They tend to be more than single sentence descriptions of an desired outcome. I launch multiple instances of Claude using claude -w, to enable the git worktree support. The exact number depends on your willingness to endure frequent context switching, I'm old so I stick to 2-4.

In each instance I follow the same prompt: "Plan and implement issue #42, share your assumptions, ask clarifying questions, outline options and seek approvals"

AI goes through a round of questions and challenges until we reach consensus and it implements the task at hand. Once done it creates a pull request. The creation of the pull request triggers code reviews. Currently that's GitHub Copilot review and CodeRabbit AI (disclaimer: the link is a referral link). Both agents review the code, come to conclusions and share them in conversations in the pull request. What's interesting is that they both highlight different issues with limited overlap. I'm particularly fond of CodeRabbit's "nitpick" level of feedback.

Once their review is completed, I let the PR merge, most of the time more that one from the various work trees. To close the feedback loop I then prompt: "Visit all pull requests [timeframe] and look for unresolved conversations. Assess each claim for merit and decide if it is still valid. When no longer valid, post your justification as comment. When still valid, create a new issue with detailed explanation and options, so any developer can understand and act on it, then add a comment linking to the issue. In both cases, mark the conversation as resolved."

This approach strikes a balance between "let the agent do its thing" and "keep the development transparent". If your source of truth for development tasks isn't GitHub issues, you need to adjust my approach.

All of this gets supported by CLAUDE.md, MCP, Skills, Tools etc, but that's another story for another time.

As usual YMMV