~iany/

Power of Monoid, Beauty of Simplicity

me@iany.me (Ian Yang) — Fri, 20 Feb 2026 00:00:00 +0800

A monoid is one of the smallest useful abstractions in algebra: a set closed under an associative binary operation, with an identity element. That simplicity is exactly why it shows up everywhere—from summing numbers and concatenating strings to powering divide-and-conquer algorithms and elegant data structures like finger trees. This post walks through what monoids are, why they give you “compute power” for free when you can phrase a problem in terms of them, and how to think about choosing the right monoid and predicate when you do.

What is a monoid?

A monoid is a set $S$ equipped with a binary operator $\bullet$ and an identity element $e$ (Wikipedia).

The operator is closed on $S$ . For all $a, b \in S$ , the result $a \bullet b$ is also in $S$ .
The operator is associative: For all $a,b,c \in S$ , $(a \bullet b) \bullet c = a \bullet (b \bullet c)$
The identity element $e$ satisfies $e \bullet a = a \bullet e = a$ for all $a \in S$ .

For example, The integer numbers with the operator addition (+) is a monoid, where the identity element is 0. The integer numbers with the operator multiplication (x) is also a monoid with the identity element 1.

The set of finite lists with the operator concatenation is a monoid since:

The operator is closed because concatenation of two finite lists is also a finite list.
The operator is associative, because both $(a \bullet b) \bullet c$ and $a \bullet (b \bullet c)$ result in a new list by placing elements of $a, b, c$ consecutively.
The identity element is the empty list.

The integer numbers with the operator max is a counterexample. The operator is closed and associative, but there is no identity element. Given any integer $e$ , there’s always a smaller integer $a$ such that $e \bullet a = e \ne a$ . However, max on the integer set with a lower bound is a monoid, such as the non-negative integers where the identity element is the lower bound 0.

Divide and conquer: why associativity matters

At first glance, associativity may seem too trivial to be useful in programming. However, associativity is what enables powerful divide-and-conquer strategies, where problems can be split into parts, solved independently, and then safely recombined.

Exponentiation by Squaring

Let’s begin with a simple application: repeatedly applying the binary operator to the same element.

 $\underbrace{a \bullet a \bullet \cdots \bullet a}_{a \text{ appears } n \text{ times}}$

Instead of applying the binary operator $n-1$ times sequentially, we exploit associativity to group every two instances of $a$ together recursively. This gives us a smaller problem when n is even:

 $\underbrace{(a \bullet a) \bullet \cdots \bullet (a \bullet a)}_{(a \bullet a) \text{ appears } \frac{n}{2} \text{ times}}$

When n is odd:

 $a \bullet \underbrace{(a \bullet a) \bullet \cdots \bullet (a \bullet a)}_{(a \bullet a) \text{ appears } \frac{n-1}{2} \text{ times}}$

We only need to compute $a \bullet a$ once to turn the problem of size $n$ to size $n/2$ . Repeating the process on $(a \bullet a)$ gives the Exponentiation by Squaring algorithm, which requires at most $\displaystyle 2 \lfloor \log _{2}n\rfloor$ computations that is more efficient than $n-1$ when $n$ is greater than 4.

For integers or real numbers under multiplication (×), exponentiation by squaring is an efficient algorithm to compute positive integer powers. Since the set of elliptic curve points under point addition forms a monoid, this same method can also be used to compute Elliptic Curve Scalar Multiplication.

General Divide-and-Conquer Search Algorithm

We can generalize the divide-and-conquer method to search an element in a sequence based solely on associativity.

The result of applying the monoid operator to a sequence from left to right serves as a summary of that sequence. If a predicate can determine whether a given element is in the sequence based solely on this summary, we can devise a general divide-and-conquer search algorithm.

Let’s say we want to search for a target element in the sequence $t_1, \ldots, t_n$ , where each $t_i$ belongs to a monoid $(S, \bullet, e)$ . Here, $S$ is the underlying set, $\bullet$ is the binary operation, and $e$ is the identity element.

We don’t know which kind of predicates works for the search algorithm. Let’s give a best guess that the predicate $p$ is a function of the monoid “summary” that $p(t_1 \bullet \cdots \bullet t_n)$ is true if and only if $t$ is in the sequence $t_1, \dots, t_n$ .

Assume that $p(t_1 \bullet \cdots \bullet t_n)$ is true, thus the target element $t$ is in the sequence. We divide the sequence into two halves: $t_1,\ldots,t_k$ and $t_{k+1},\ldots,t_n$ , where $1 \le k \le n$ . We then evaluate $p(t_1 \bullet \cdots \bullet t_k)$ to determine whether the target element lies in the first or second half, and continue the search.

Based on this observation, we can deduce the following property of the predicate: there exists an index $x$ such that

 $p(t_1 \bullet \cdots \bullet t_k) := \begin{cases} \text{false} & \text{if } k < x, \\ \text{true} & \text{if } k \ge x. \end{cases}$

$t_x$ is the target element if such $x$ exists; otherwise, the target element does not exist in the sequence.

Intuitively, the target element is the turning point at which the predicate on the running summary changes from false to true.

Note that $p$ makes sense only on the summary of any prefix of the sequence. If we need to continue the search in the second half, we must remember the summary of the scanned prefix.

Now we can define the search algorithm $\mathrm{Search}(p, s, \{t_i,\ldots,t_j\})$ where

$s$ is the summary of scanned prefix $t_1 \bullet \cdots \bullet t_{i-1}$ when $i > 1$ or the identity element $e$ otherwise.
$t_i, \ldots, t_j$ is the sub-range to search next.
$p$ is the predicate as defined above

The algorithm proceeds as follows:

If $p(s \bullet t_i \bullet \cdots \bullet t_j$ ) is false, the target element does not exist. The algorithm aborts with an error.
Otherwise, if there’s only one element ( $i = j$ ), $t_i$ is the target element. The algorithm aborts with the found result.
Otherwise, choose a pivot index $i \le m \lt j$ to split the sequence into two nonempty halves: $t_i, \ldots, t_m$ and $t_{m+1},\ldots,t_j$ . Test $p(s \bullet t_i \bullet \cdots \bullet t_m)$ that
- If it is true, continue the search in the first half: $\mathrm{Search}(p, s, \{t_i,\ldots,t_m\})$
- Otherwise, continue the search in the second half: $\mathrm{Search}(p, s \bullet (t_i \bullet \cdots \bullet t_m),\{t_{m+1},\ldots,t_j\})$

The algorithm starts with $\mathrm{Search}(p, e, \{t_1, \ldots, t_k\})$ .

Application: Random-Access Sequence

An application of the search algorithm is accessing the nth element in the sequence.

We initialize the sequence to all 1s and use the monoid of non-negative integers with addition $(\mathbb{N},+,0)$ :

 $\underbrace{1, \ldots, 1}_{n \text{ times}}$

The predicate to find the i-th (starting from 0) element is:

 $\[ p_i(s) := s > i \]$

It may seem silly to search for the i-th 1 in a sequence of 1s, but we can store any data in the sequence and attach the monoid values as annotations to guide the search algorithm.

Application: Max-Priority Queue

Another application is finding the element with the max priority.

We use the monoid of non-negative integers with operator max $(\mathbb{N},\mathrm{max},0)$ and assume that the maximum value has the maximum priority.

The predicate to find the element with the max priority is

 $\[ p(s) := s = m \]$

Where $m$ is the monoid summary of the entire sequence—that is, the maximum value in the sequence. The predicate checks whether the summary equals to $m$ .

Annotated Search Tree

A natural way to support the divide-and-conquer search is an annotated binary tree. Store the sequence elements at the leaves, and at each node store the monoid summary of the subtree—e.g. the sum of lengths or the maximum priority in that subtree. The predicate can then be evaluated on the left subtree’s annotation to decide whether to descend left or right, and the prefix summary is updated when going right by combining it with the left subtree’s summary.

A plain binary tree can degenerate to a list in the worst case, so operations may become linear. A more advanced structure, the finger tree¹, keeps the tree balanced and supports efficient access at both ends and in the middle; each node carries a monoidal “measure” of its subtree, and the same search strategy applies. In Haskell, Data.Sequence from the containers library implements sequences as finger trees with size (length) as the measure, giving $O(\log n)$ indexing, splitting, and concatenation.

Utility of the Identity Element

The general divide-and-conquer algorithm does not require a monoid—only a semigroup. A semigroup is a fancy word for a set equipped with a closed, associative binary operator but lacking an identity element. The presence of an identity element makes monoids convenient to work with.

The identity element serves as a natural default value or starting point for algorithms. For instance, in the search algorithm, the summary of the scanned prefix is initialized to $e$ . Without an identity element, we need an additional flag to indicate whether any prefix has been scanned, and the algorithm would have to branch conditionally based on that flag.

The art of choosing monoid and predicate

In the random-access example we used $(\mathbb{N}, +, 0)$ and annotated each position with $1$ —the summary of a segment is its length, and the predicate $s > i$ tells us whether the $i$ -th element lies in the prefix we have so far. In the max-priority queue we used $(\mathbb{N}, \max, 0)$ (or a bounded variant): the summary is the maximum value in the segment, and the predicate $s = m$ identifies the segment that contains the global maximum. In both cases, the monoid was chosen so that the combined summary over a range is exactly what the predicate needs to decide where to go next.

The flip side is that finding both the right monoid and the right predicate can be tricky. At each step the search has access only to the monoid summary of the prefix (or segment) seen so far, so the predicate must be decided from that summary alone. The monoid must be rich enough to supply the information the predicate needs. Sometimes the natural summary (e.g. sum or max) suggests the predicate (e.g. $s > i$ or $s = m$ ). Sometimes you must try a different carrier or operation, or encode extra information into the monoid (e.g. pairs or custom types), so that the predicate can be expressed. There is no universal recipe—it is a matter of design and experimentation. Reframe the problem as: “What do I need to know about a segment to decide the next step?” Then choose a monoid that can represent that knowledge and a predicate that uses it.

Hinze, R., & Paterson, R. (2006). Finger trees: A simple general-purpose data structure. Journal of Functional Programming, 16(2), 197–217. Cambridge University Press. https://www.cs.ox.ac.uk/ralf.hinze/publications/FingerTrees.pdf

Use Bun for Shell Scripts

me@iany.me (Ian Yang) — Sat, 07 Feb 2026 00:00:00 +0800

I’ve moved most of my small scripts to Bun. It sidesteps Windows’ lack of shebang support and the Git-for-Windows/WSL bash dance, and gives you one runtime for both ad-hoc shell-style commands and full scripts.

Problems Bun solves

Windows doesn’t execute #!/usr/bin/env python3 or #!/bin/bash, so scripts written for Linux or macOS usually need a separate PowerShell version. Bun compiles JavaScript to native executables, so a single script can run cross-platform without shebangs.

Mise file tasks have started to support shebangs on Windows in the latest release, but they rely on system bash.exe, which often points at WSL. Bun does not. You run bun ./script.js and embed shell commands via Bun.$; the script uses Bun’s bundled bash environment.

Why Bun for shell scripts

The command bun build ./script.ts --compile --outfile script produces a single binary, so no shebang or interpreter is needed on Windows. The Bun.build API is available too; I use a build.js script to walk a directory and compile all executables. Pre-built binaries start quickly—Bun’s docs cite ~5ms vs Node’s ~25ms for a simple script, which helps for small, frequently run scripts.

Bun has strong support for shell-style scripting. Bun Shell runs bash commands; the main entry point is Bun.$, which constructs shell commands from template literals for safe interpolation, similar to google/zx. On Windows, Bun ships with MSYS, so you get a consistent bash environment and common Linux CLI tools without extra setup.

Other useful features:

Bun.secrets—Securely store and retrieve secrets using the OS keystore (Windows Credential Manager, macOS Keychain, Linux libsecret). Secrets - Bun
Built-in support for glob patterns, YAML parsing, ANSI colors, and more. Bun Runtime

Short example

import { $ } from "bun";
const out = await $`echo hello`.text();
console.log(out); // hello

Run it with bun run script.js or bun ./script.js.

Obsidian Notes

JavaScript Shell Scripting

Use tmux for PowerShell in Windows Terminal

me@iany.me (Ian Yang) — Thu, 29 Jan 2026 23:30:42 +0800

You can get tmux session persistence and multiplexing in Windows Terminal by running tmux inside WSL and setting the default shell to PowerShell. New panes and windows will then start pwsh.exe instead of a Linux shell. Here’s a minimal setup using small wrappers and the tmux -C attach trick to configure new sessions.

Why tmux under WSL with PowerShell?

Since tmux does not run natively on Windows, the standard approach is to use it through WSL. However, if you launch wsl tmux from Windows Terminal, all panes will default to your WSL shell. When working in a Windows directory, I prefer to use native PowerShell within the Windows environment.

To ensure every tmux pane runs PowerShell, configure tmux to use pwsh.exe as its default command. When you launch pwsh.exe from WSL within a Windows directory, it brings us back to the Windows environment.

Wrappers so you can call tmux from PowerShell

Put these in a directory on your PATH (e.g. ~/Documents/PowerShell/bin).

PowerShell — tmux.ps1:

wsl tmux $args

Cmd — tmux.cmd:

@echo off
wsl tmux %*

From PowerShell or Cmd you can then run tmux new, tmux attach, etc., and they all go to WSL’s tmux.

Creating PowerShell Sessions

The next piece is a script that creates a new session whose default command is pwsh.exe, or attaches if that session already exists. Example usage: tmux-pwsh dev or tmux-pwsh work.

The script sets the default command only for sessions it creates; it does not affect sessions started with a standard tmux new-session.

tmux-pwsh.ps1:

param(
[Parameter(Mandatory=$true)]
[string]$SessionName
)
$pwshCommand = "exec pwsh.exe -nologo"
# Check if session exists using exact name match
wsl tmux has-session -t "\=$SessionName" 2>$null
if ($LASTEXITCODE -ne 0) {
wsl tmux new-session -d -s $SessionName $pwshCommand
echo "set-option default-command `"$pwshCommand`"" | `
wsl tmux -C attach -t "\=$SessionName" >$null
}
wsl tmux attach -t "\=$SessionName"

Note:

The = prefix does an exact session name match and must be escaped when sending the command from PowerShell to WSL.
The new session specifies command pwsh.exe via the command argument.
Running wsl tmux set-option immediately after creating the session does not work because there’s a brief window where the session is not available for setting options. Instead, sending set-option via tmux -C attach reliably applies the setting.

After this, splitting panes and creating new windows in that session will all start pwsh.exe -nologo in Windows Terminal.

Summary

Use WSL for tmux and PowerShell as the default command by setting tmux’s default command to exec pwsh.exe -nologo.
tmux.ps1 / tmux.cmd — thin wrappers so tmux from Windows means wsl tmux.
tmux-pwsh.ps1 <name> — create (or attach to) a named session that uses PowerShell as the default command.

Once these are on your PATH, run e.g. tmux-pwsh dev from Windows Terminal to get a tmux session where every pane is PowerShell.

Backup Ignored Files with Git Remote Branch

me@iany.me (Ian Yang) — Fri, 12 Dec 2025 03:22:58 +0800

When working with Git repositories, there are often files that need to be backed up but shouldn’t be committed to the main branch. These might include local development settings, IDE configuration files, personal notes, or development scripts that are specific to your workflow. The challenge is finding a way to back up these ignored files without polluting the main repository history.

The Original Solution

My original approach was to use a separate repository to store backup files for all repositories and create symbolic links. This worked, but had several drawbacks:

Backup files were disconnected from their source repositories, making it harder to track what belongs where
Backing up new files required moving them to the backup repository and then creating symbolic links

A Better Approach: Remote Branch

Instead of using a separate repository, we can use a remote branch within the same repository. This approach offers several advantages:

Everything stays in one repository
When you clone the repository, the backup branch comes with it
Backup files are stored in a separate branch, keeping the main branch clean
Full Git history for backup files, just like any other branch

The Script

With AI assistance, I developed git-store-file, a tool for managing ignored files by storing them in a remote branch (default: origin/_store). This keeps backup files separate from your working branch without interfering with regular development. The script is available in Python.

Installation

Download the script and make it executable:

curl -o ~/bin/git-store-file https://raw.githubusercontent.com/doitian/dotfiles-public/master/default/bin/git-store-file
chmod +x ~/bin/git-store-file

Usage

The script has four main commands: store, status, restore, and ls.

Store Files

Store one or more files to the remote branch, including files that are ignored by Git:

# Store a single file
git-store-file config.local.json
# Store multiple files
git-store-file config.local.json secrets.env
# Use a custom branch name
git-store-file --branch backup config.local.json
# Use a custom remote
git-store-file --remote upstream config.local.json

When you run the store command, the script will:

Create a temporary Git index to avoid conflicts with your working directory
Load the target branch’s current state into the temporary index
Add the specified files using git add -f to include ignored files
Create a commit with the changes
Display commit statistics and prompt for confirmation
Push the commit to the remote branch

Check Status

Check which files stored in the remote branch have been modified in your local working directory:

# Check status
git-store-file status
# Show diff for modified files
git-store-file status --diff

Restore Files

Restore files from the remote branch to your working directory:

# Restore a specific file
git-store-file restore config.local.json
# Restore all files from the branch
git-store-file restore

List Files

List all files stored in the remote branch:

git-store-file ls

Options

-b, --branch BRANCH: Specify the branch name (default: _store)
-r, --remote REMOTE: Specify the remote name (default: origin)
-h, --help: Show help message

Examples

# Store local configuration
git-store-file .env.local
# Check what's changed
git-store-file status -d
# Restore after cloning
git-store-file restore .env.local
# List all backed up files
git-store-file ls

How It Works

The script uses Git’s low-level plumbing commands to manipulate the repository without affecting your working directory:

Temporary Index: Uses the GIT_INDEX_FILE environment variable to create a temporary index, completely isolated from your working directory
Read Tree: Loads the target branch’s tree structure into the temporary index
Force Add: Uses git add -f to add files even if they’re listed in .gitignore
Commit Tree: Creates a commit object directly using git commit-tree, bypassing the normal commit workflow
Direct Push: Pushes the commit hash directly to the remote branch reference

This low-level approach ensures that:

Your working directory remains unchanged
The main branch is never affected
Ignored files can be stored without modifying .gitignore
The backup branch maintains full Git history

Conclusion

The git-store-file script solves the problem of backing up ignored files in a clean, Git-native way. By leveraging a remote branch, it keeps everything in one repository while maintaining clear separation between your main codebase and backup files. Whether you’re managing local configurations, IDE settings, or personal development scripts, this tool provides a simple and reliable backup solution that integrates seamlessly with your existing Git workflow.

How to Activate mise for Cursor When It Runs Shell Commands

me@iany.me (Ian Yang) — Wed, 26 Nov 2025 11:31:37 +0800

When using mise with Cursor, you may notice that the mise environment is not activated when Cursor executes shell commands. This occurs because Cursor launches a non-login shell, which initializes differently than an interactive login shell and therefore does not automatically source your usual mise setup.

The Problem

Cursor runs commands in a non-login shell, which means:

For zsh: Only .zshenv is loaded (not .zshrc)
For bash: Only .bash_profile is loaded (not .bashrc)

If you’ve configured mise activation in .zshrc or .zprofile, it won’t be available when Cursor executes commands.

The Solution

The solution is to activate mise in .zshenv (for zsh) or .bash_profile (for bash) when the file is loaded by Cursor. You can detect Cursor by checking for the CURSOR_AGENT environment variable.

Add this to your ~/.zshenv or ~/.bash_profile:

# Activate mise when running in Cursor
if [[ -n "$CURSOR_AGENT" ]]; then
eval "$(mise activate)"
fi

Why This Works

.zshenv (or .bash_profile) is always sourced for non-login shells
The CURSOR_AGENT environment variable is set when Cursor runs commands
By conditionally activating mise only when CURSOR_AGENT is present, you avoid potential conflicts or slowdowns in other non-login shell contexts
This ensures mise and all its configured tools are available when Cursor executes terminal commands

After adding this configuration, rerun Cursor chats, and mise should be available in all Cursor shell commands.

Temporary Vi Mode in PowerShell

me@iany.me (Ian Yang) — Sat, 22 Nov 2025 23:17:05 +0800

I miss the feature in readline (Bash/Zsh) where Ctrl+x, Ctrl+v switches to Vi command mode temporarily. In that workflow, entering Insert mode switches back to Emacs mode. PSReadLine has a command ViCommandMode, but binding it directly in Emacs mode will report errors on every key input.

The solution requires handling the mode change event to toggle the global EditMode between Emacs and Vi.

When entering “Insert” mode (the default for Emacs users), we force the mode to Emacs and set up the trigger for the temporary Vi mode. When that trigger (Ctrl+x, Ctrl+v) is fired, we switch the edit mode to Vi and jump to command mode.

Here is the configuration for your $PROFILE:

function OnViModeChange {
if ($args[0] -eq 'Insert') {
Set-PSReadLineOption -EditMode Emacs
Set-PSReadlineKeyHandler -Chord "Ctrl+x,Ctrl+v" -ScriptBlock {
Set-PSReadLineOption -EditMode Vi
[Microsoft.PowerShell.PSConsoleReadLine]::ViCommandMode()
}
# Add other Emacs key bindings here.
# Switching `EditMode` resets key bindings to their defaults.
# Remember to reconfigure them.
# Set-PSReadlineKeyHandler -Chord "Ctrl+w" -Function BackwardKillWord
}
}
Set-PSReadLineOption -ViModeIndicator Script
Set-PSReadLineOption -ViModeChangeHandler $Function:OnViModeChange
Set-PSReadLineOption -EditMode Emacs
# Reuse the function to start Emacs mode
OnViModeChange Insert

Switching EditMode resets key bindings to their defaults. Remember to reconfigure them.

Study on Quotient Spaces

me@iany.me (Ian Yang) — Tue, 18 Nov 2025 21:23:25 +0800

I’m reading Linear Algebra Done Right by Axler and found the section on quotient spaces difficult to understand, so I researched and took these notes.

Definitions

3.95 notion: $v + U$

Suppose $v \in V$ and $U \subseteq V$ . Then $v + U$ is the subset of $V$ defined by

 $v + U = \{v + u : u \in U\}.$

Also called a translate. Attention that a translate is a set.

3.97 definition: translate

Suppose $v \in V$ and $U \subseteq V$ , the set $v + U$ is said to be a translate of $U$ .

Quotient space is a set of all translates (set of sets):

3.99 definition: quotient space, $V/U$

Suppose $U$ is a subspace of $V$ . Then the quotient space $V/U$ is the set of all translates of $U$ . Thus

 $V/U = \{v + U : v \in V\}.$

Quotient space is a set of sets. There are duplicates for each $v \in V$ because for some $v_1, v_2 \in V$ , $v_1 + U$ and $v_2 + U$ can be identical set.

A quotient space $V/U$ is formed by “collapsing” a subspace $U$ to zero within a larger vector space $V$ . This construction is based on an equivalence relation where two vectors $x, y \in V$ are considered equivalent if their difference lies in $U$ —that is, $x \sim y$ if and only if $x - y \in U$ . wikipedia

Lemmas

3.101 two translates of a subspace are equal or disjoint

Suppose $U$ is a subspace of $V$ and $v, w \in V$ . Then

 $v - w \in U \iff v + U = w + U \iff (v + U) \cap (w + U) \neq \emptyset$

If two translates are not disjoint (the union set is not empty), they must be equal. So they are equal or disjoint.

All distinct translates of a subspace are disjoint. Given any $v \in V$ , it belongs to only one translate.

Since the quotient space $V/U$ is a set of translates of a subspace, it is like a disjoint partition of values in $V$ . By using the definition of quotient map

3.104 definition: quotient map, $\pi$

Suppose $U$ is a subspace of $V$ . The quotient map $\pi : V \to V/U$ is the linear map defined by

 $\pi(v) = v + U$

for each $v \in V$ .

We can write that

 $\pi(v_1) = \pi(v_2) \iff v_1 - v_2 \in U$

The quotient map has two essential properties:

The null space of $\pi$ is exactly the subspace $U$ , because $v+U=0+U \iff v-0 \in U \iff v \in U$
The range of $\pi$ is the entire quotient space $V/U$

Quotient Space Is a Vector Space

First define the addition and scalar multiplication operations:

3.102 definition: addition and scalar multiplication on $V/U$

Suppose $U$ is a subspace of $V$ . Then addition and scalar multiplication are defined on $V/U$ by

 $\begin{align*} (v + U) + (w + U) &= (v + w) + U \\ \lambda(v + U) &= (\lambda v) + U \end{align*}$

for all $v, w \in V$ and $\lambda \in \mathbf{F}$ .

$v+U$ is not the unique way to represent a member in $V/U$ , because there may exist $v'\ne v$ that $u + U = v' + U$ . The operations make sense only when the choice of $v$ to represent a translate makes no differences.

Specifically, suppose $v_1, v_2, w_1, w_2 \in V$ such that

 $v_1 + U = v_2 + U \quad\textrm{and}\quad w_1 + U = w_2 + U$

From the addition definition:

 $\begin{align*} (v_1+U) + (w_1+U) &= (v_1 + w_1) + U \\ (v_2+U) + (w_2+U) &= (v_2 + w_2) + U \end{align*}$

The left side of the two equations indeed are the different representation of the same equation, so we must show that the right side equal: $(v_1 + w_1)+U=(v2+w2)+U$ .

This applies to scalar multiplication as well:

 $\begin{align*} \lambda(v_1 + U) &= (\lambda v_1) + U \\ \lambda(v_2 + U) &= (\lambda v_2) + U \end{align*}$

We must show that $(\lambda v_1) + U = (\lambda v_2) + U$ .

Dimension

The dimension of the quotient space is given by a simple subtraction, relating the dimension of $V/U$ to the “lost” dimension of $U$ :

3.105 dimension of quotient space

Suppose $V$ is finite-dimensional and $U$ is a subspace of V. Then

 $\text{dim } V/U = \text{dim }V - \text{dim }U.$

Linear Map from V/(null T) to W

3.106 notation: $\widetilde{T}$

Suppose $T \in \mathcal{L}(V, W)$ . Define $\widetilde{T}: V/(\text{null } T) \to W$ by

 $\widetilde{T}(v + \text{null } T) = Tv.$

Think of merging inputs having the same output. These inputs will be the same input in the quotient space $V/(\text{null } T)$ .

For any $v_1, v_2 \in V$ that $Tv_1 = Tv_2$ , $v_1 + \mathrm{null}\, T$ and $v_2 + \mathrm{null}\, T$ are the same value in $V/(\mathrm{null}\, T)$ . This makes $\widetilde{T}$ injective. Because $\mathrm{range}\,\widetilde{T}=\mathrm{range}\, T$ , $\widetilde{T}$ is also surjective on to $\mathrm{range}\, T$ .

3.63 invertibility $\iff$ injectivity and surjectivity

A linear map is invertible if and only if it is injective and surjective.

3.63 shows us that $\widetilde{T}$ is invertible, and according to the definition of isomorphic, $V/(\mathrm{null}\, T)$ and $\mathrm{range}\,T$ are isomorphic vector spaces and $\widetilde{T}$ is their isomorphism.

3.69 definition: isomorphism, isomorphic

An isomorphism is an invertible linear map.
Two vector spaces are called isomorphic if there is an isomorphism from one vector space onto the other one.

One of the key uses of $\widetilde{T}$ is demonstrating a canonical isomorphism. For any linear map $T \in \mathcal{L}(V, W)$ , the quotient space $V/(\text{null } T)$ is isomorphic to the image space $\text{range } T$ . This shows that the quotient space $V/(\text{null } T)$ serves as a way to “mod out” the non-injective part of $T$ .

Hosting Static Site on Cloudflare R2

me@iany.me (Ian Yang) — Wed, 22 Oct 2025 18:46:38 +0800

This post explains how to set up a static site on Cloudflare R2.

I recently migrated my blog to Cloudflare R2, and the process went smoothly until I encountered R2’s lack of native support for rewriting URLs to index.html files. This post explains how I resolved this issue.

Setting Up

Create the bucket.
Add the custom domain blog.iany.me. To redirect iany.me and www.iany.me to the blog, add these as custom domains as well. Since I host the domain in Cloudflare, the DNS record is automatically configured.

Publishing

I use rclone to deploy the site to R2. Below is the GitHub workflow I employ. Noting that the fetch-depth option for actions/checkout retrieves the complete repository history. This works with Hugo’s --enableGitInfo flag to accurately determine article creation dates.

name: Deploy Hugo Site to Cloudflare R2
on:
push:
branches:
- master
workflow_dispatch:
jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Install latest Hugo
run: |
TAG=$(curl -s https://api.github.com/repos/gohugoio/hugo/releases/latest \
| grep '"tag_name":' \
| head -1 \
| sed -E 's/.*"([^"]+)".*/\1/')
curl -L "https://github.com/gohugoio/hugo/releases/download/${TAG}/hugo_${TAG#v}_Linux-64bit.tar.gz" \
-o hugo.tar.gz
tar -xzf hugo.tar.gz hugo
sudo mv hugo /usr/local/bin/
hugo version
- name: Install rclone
run: |
curl https://rclone.org/install.sh | sudo bash
- name: Build site with Hugo
run: hugo --minify --enableGitInfo
- name: Configure rclone for Cloudflare R2
env:
R2_ACCESS_KEY_ID: ${{ secrets.R2_ACCESS_KEY_ID }}
R2_SECRET_ACCESS_KEY: ${{ secrets.R2_SECRET_ACCESS_KEY }}
R2_ENDPOINT: ${{ secrets.R2_ENDPOINT }}
run: |
rclone config create r2 s3 \
provider Cloudflare \
access_key_id "${R2_ACCESS_KEY_ID}" \
secret_access_key "${R2_SECRET_ACCESS_KEY}" \
endpoint "${R2_ENDPOINT}" \
--quiet
- name: Deploy to Cloudflare R2
env:
R2_BUCKET: ${{ secrets.R2_BUCKET }}
run: |
rclone copy public/ r2:"${R2_BUCKET}" \
--checksum \
--no-traverse \
--verbose

Rules

Go to the dashboard of the domain iany.me and go to the section Rules.

Redirect Rules

I have added 3 redirect rules:

When incoming requests have a hostname iany.me or www.iany.me, redirect to concat("https://blog.iany.me", http.request.uri.path).
Redirect https://blog.iany.me/*/index.html to https://blog.iany.me/${1}/.
Redirect http://* to https://${1}

Although the Redirect Rules manual says if multiple rules make the same modification, the last executed rule wins, I have to put rule 2 before 3.

URL Rewrite Rules

I added 2 rewrite rules for index.html:

When the request URL is https://blog.iany.me or https://blog.iany.me/, rewrite the URL path to /index.html.
When the request URL matches https://blog.iany.me/*/, rewrite the path to ${1}/index.html

Cache Rules

I added 2 cache rules for images and static content:

Set cache TTL to 1 month for png, jpg, jpeg, and svg files.
Set cache TTL to 1 year for files in /js, /fonts, /css, and /uploads.

Explain Atomic Cross-Chain Swaps by Herlihy

me@iany.me (Ian Yang) — Fri, 19 Sep 2025 22:26:46 +0800

This article explains the paper [Herlihy, 2018]¹ in simple words. In the paper, Herlihy has introduced an effective atomic cross-chain swap protocol in order to exchange assets across multiple blockchains among multiple parties.

Model

A swap can be modeled using a directed graph $(V, A)$ . $V$ is a set of involved users, and $A$ is a set of payments. Each payment is annotated as $(u, v)$ where $u$ is the payer and $v$ is the payee. The Atomic Swap Protocol ensures that when all users follow the protocol, if one payment succeeds, all other payments must succeed.

For example, following model represents a swap that Alice sends a payment to Bob, and Bob sends a payment to Carol.

 $\begin{array}{rl} V &= \{\mathrm{Alice}, \mathrm{Bob}, \mathrm{Carol}\} \\ A &= \{(\mathrm{Alice},\mathrm{Bob}), (\mathrm{Bob}, \mathrm{Carol})\} \end{array}$

Simple Protocol

When all payments can be connected into a path, like the example above, the protocol is simple and is similar to the payment hops in lightning network.

A path is annotated as $(u_1, \ldots, u_l)$ , which is consisted of $l-1$ payments: $(u_1, u_2),(u_2, u_3),\ldots,(u_{l-1}, u_l)$ .

The final payee $u_l$ generates a secret $s$ and sends its hash $H(s)$ to the payer $u_1$ . The payer $u_1$ creates a Hash Time Locked Contract $(H(s), 2(l-1)\Delta)$ that either $u_2$ can get the fund by providing the secret $s$ , or $u_1$ can get the refund when time has elapsed $2(l-1)\Delta$ units. The users $u_i$ from $u_2$ to $u_{l-2}$ creates a Hash Time Locked Contract $(H(s), 2(l-i)\Delta)$ when they confirm that they have received the inbound contract. The payee $u_l$ can settle the deal by providing the secret $s$ to $u_{l-1}$ , and each user uses the received secret $s$ to settle their inbound contract.

The simple protocol also works when payee and payer are the same user ( $u_1 = u_l$ ). From engineering points, it should work for most scenarios.

Arbitrary Connected Directed Graph

The paper also extends the swap protocol to arbitrary connected directed graph. A connected directed graph means for any two user $u, v$ , there are a payment path from $u$ to $v$ , and a payment path from $v$ to $u$ . Such directed graphs contain loops, as in the example below:

 $\begin{array}{rl} V = \{&A, B, C, D, E, F\} \\ A = \{ \\ &(A, B), (B, C), (C, A), \\ &(C, D), (D, B), \\ &(D, E), (E, F), (F, D) \\ \} \\ \end{array}$

Leaders Selection

The protocol must select a Feedback Vertex Set of the directed graph as leaders. A feedback vertex set is a subset of $V$ that once removed from the graph, there will be no loops in the graph. For example, $(B, D)$ is a feedback vertex set of the example above. When there are multiple candidates, choose an arbitrary set.

The leaders generate secrets and publish their hashes. If $(B, D)$ are selected, they should publish $(H(s_B), H(s_D))$ .

The protocol then move forward in two phases.

Phase One

In the first phase, users offer outbound contracts to counterparty for each payment.

Leaders must offer contracts first:

Publish a contract on every outbound payments, then
wait until all inbound contracts have been published.

Followers must confirm inbound contracts first:

Wait until correct inbound contracts have been published, then
publish a contract on every outbound payments.

The contracts are Hash Time Locked Contracts $(h, t)$ that payee can get the fund using the proof to unlock $h$ , or the payer gets the refund after timeout $t$ .

For a payment $(u, v)$ , the proof of $h$ is a triple $(s, p, \sigma)$ where

$p$ is any payment path $(u_0, \ldots, u_k)$ starting from the payee $v$ ( $u_0 = v$ ) to a leader $u_k$ . The path $p$ can have a length of 0 if $v$ itself is a leader.
$s$ is the secret generated by the ending leader of the path $p$ , and $h = H(s)$ .
$\sigma$ is a nested signatures of $s$ signed by users in the path $p$ .
- The innest signature is $\mathrm{sig}_k = \mathit{sig}(s, u_k)$
- For user $u_i$ ( $0 \leq i \leq k - 1$ ), the signature is $\mathrm{sig}_i = \mathit{sig}(\mathrm{sig}_{i+1}, u_i)$
- $\sigma = \mathrm{sig}_0$

The hash lock $h$ can be set to $H(s)$ for the shortest $p$ , or just the hashes of all secrets to all unlocking using arbitrary ending leader of the path $p$ .

The time lock $t$ is $(\mathit{diam}(\mathcal{D}) + |p|)\Delta$ , where

$\mathit{diam}(\mathcal{D})$ is the longest length of a payment path without duplicated users in the directed graph.
$|p|$ is the length of the path $p$ in the hash lock.
$\Delta$ is a configured time unit constant for the time out.

Let’s see two examples.

The first example is the payment from a leader: $(B, C)$ .

There are three candidate path $p$ from the payee $C$ to a leader either $B$ or $D$ :

$(C, A, B)$
$(C, D)$
$(C, D, B)$

$B$ can choose any one, but the shortest one is recommended. Let’s use $(C, D)$ . $B$ can publish the contract because he/she is the leader.

The hash lock for $(B, C)$ is $H(s_D)$ .
The time lock is $6\Delta$ , because the length of the longest path $(A, B, C, D, E, F)$ is 5, and the length of $(C, D)$ is 1.

The second example is the payment from a follower: $(C, A)$ .

$C$ can choose the path $(A, B)$ and publish the contract:

The hash lock is $H(s_B)$ .
The time lock is $6\Delta$

Phase Two

In phase two, leaders can unlock the inbound contracts because they know all secrets. For example, the leader $B$ can unlock the inbound payment $(A, B)$ by offering:

The path $p = (B)$
The secret $s_B$
The signature $sig(s_B, B)$

Followers must trace outbound contracts unlocking events. For example, $A$ can unlock the contract for $(C, A)$ after receiving the unlocking event above:

The path $p = (A, B)$
The secret $s_B$ since B has published it when unlocking $(A, B)$ .
The signature $sig(sig(s_B, B), A)$

Herlihy, M. (2018). Atomic Cross-Chain Swaps (No. arXiv:1801.09515). arXiv. https://doi.org/10.48550/arXiv.1801.09515

Envrc Alternative for PowerShell in Windows

me@iany.me (Ian Yang) — Sat, 06 Apr 2024 08:55:34 +0800

This post introduces a solution for automatically setting up and tearing down shell environments for PowerShell in Windows. It is proposed as a potential alternative to the bash-based tool direnv, which, while effective at loading .envrc files in the current or nearest ancestor directory, has limited compatibility with PowerShell in Windows.

.envrc.ps1

The basic idea is creating a file .envrc.ps1 with two entries: setup and teardown. The setup entry is responsible for setting up the environment up entering the directory, and the teardown entry is used when leaving it.

PowerShell allows code to be executed from a file using the dot command. This means that the entire file can be used as the setup entry. For the teardown entry, a function can be defined within the same file, and I use the function name down.

The layout of the file .envrc.ps1 looks like:

# setup
$env:GH_TOKEN = "secret"
# teardown
function global:down {
$env:GH_TOKEN = ""
}

The global: scope before the function name is necessary when this file is loaded in the hook, as I will do later.

The corresponding commands for setup and teardown entries:

Setup: . .envrc.ps1
Teardown: down

Hook

To hook the setup and teardown entries, I reference this example.

using namespace System;
using namespace System.Management.Automation;
$hook = [EventHandler[LocationChangedEventArgs]] {
param([object] $source, [LocationChangedEventArgs] $eventArgs)
end {
# 1. `down` for $eventArgs.OldPath
# 2. `. .envrc.ps1` for $eventArgs.NewPath
}
};
$currentAction = $ExecutionContext.SessionState.InvokeCommand.LocationChangedAction;
if ($currentAction) {
$ExecutionContext.SessionState.InvokeCommand.LocationChangedAction = [Delegate]::Combine($currentAction, $hook);
} else {
$ExecutionContext.SessionState.InvokeCommand.LocationChangedAction = $hook;
};

To run the code snippet, PowerShell 7 or later is required. You can install it from the repository.

Here is the algorithm for identifying setup and teardown entries:

Find the nearest .envrc.ps1 for the old path.
Find the nearest .envrc.ps1 for the new path.
If the two paths are the same, skip the next step.
If they differ, invoke the down function and remove it if it exists. Then, if found, load the .envrc.ps1 file for the new path.

The full code example to be added into PowerShell $PROFILE file.

using namespace System;
using namespace System.Management.Automation;
# existing PowerShell profile contents
# skip when version is less than 7
if ($PSVersionTable.PSVersion.Major -lt 7) {
return
}
# find the .envrc.ps1 in the currenct directory or the nearest ancestor directory.
function Find-NearestEnvrc {
param (
[Parameter(Mandatory=$true)]
[string]$StartDir
)
$currentDir = Resolve-Path $StartDir
while ($currentDir -ne "") {
$envrcPath = Join-Path $currentDir ".envrc.ps1"
if (Test-Path $envrcPath) {
return $envrcPath
}
$currentDir = Split-Path $currentDir -Parent
}
return ""
}
# hook the setup and teardown entries
$hook = [EventHandler[LocationChangedEventArgs]] {
param([object] $source, [LocationChangedEventArgs] $eventArgs)
end {
$oldEnvrc = Find-NearestEnvrc $eventArgs.OldPath
$newEnvrc = Find-NearestEnvrc $eventArgs.NewPath
if ($oldEnvrc -ne $newEnvrc) {
Get-Command down -ErrorAction SilentlyContinu
if (Get-Command down -ErrorAction SilentlyContinu) {
down
Remove-Item Function:down
}
if ($newEnvrc -ne "") {
. $newEnvrc
}
}
}
};
$currentAction = $ExecutionContext.SessionState.InvokeCommand.LocationChangedAction;
if ($currentAction) {
$ExecutionContext.SessionState.InvokeCommand.LocationChangedAction = [Delegate]::Combine($currentAction, $hook);
} else {
$ExecutionContext.SessionState.InvokeCommand.LocationChangedAction = $hook;
};

Example Usage

# setup
# set environment variable
$env:GH_TOKEN = "secret"
# load python virtual env
. .venv\Scripts\Activate.ps1
# add a helper function
function global:build {
cargo build
}
# teardown
function global:down {
# unset environment variable
$env:GH_TOKEN = ""
# unload python virtual env
deactivate
# remove the helper function
Remove-Item Function:build
}

How to Verify JoyID WebAuthn Signature

me@iany.me (Ian Yang) — Sun, 17 Dec 2023 17:35:33 +0800

JoyID is a multichain, cross-platform, passwordless and mnemonic-free wallet solution based on FIDO WebAuthn protocol and Nervos CKB.

This post shows how to verify the signature from the method signChallenge of the @joyid/ckb package. The method reference page has a demo. I use the demo to obtain an example response then verify the response using the OpenSSL command line and the Python library PyCryptodome.

The JoyID follows the WebAuthn specification and employs secp256r1 for signing. Although the guide references section 6.3.3 of the WebAuthn specification, titled “The authenticatorGetAssertion Operation”, I discovered that the example in this repository provided me much more helps.

The Response Parsing

This is the example I obtained from the demo.

{
"signature": "MEUCICF25qdO6nLreEoBHnyaw-9R6XFHbIu-NwsAI53t016qAiEAgmhlwTEMxoWxKj79R1rUkB_6nrhJfws82DqHkY_HnqQ",
"message": "K4sF4fAwPvuJj-TW3mARmMenuGSrvmohxzsueH4YfFIFAAAAAHsidHlwZSI6IndlYmF1dGhuLmdldCIsImNoYWxsZW5nZSI6IlUybG5iaUIwYUdseklHWnZjaUJ0WlEiLCJvcmlnaW4iOiJodHRwczovL3Rlc3RuZXQuam95aWQuZGV2IiwiY3Jvc3NPcmlnaW4iOmZhbHNlLCJvdGhlcl9rZXlzX2Nhbl9iZV9hZGRlZF9oZXJlIjoiZG8gbm90IGNvbXBhcmUgY2xpZW50RGF0YUpTT04gYWdhaW5zdCBhIHRlbXBsYXRlLiBTZWUgaHR0cHM6Ly9nb28uZ2wveWFiUGV4In0",
"challenge": "Sign this for me",
"alg": -7,
"pubkey": "3538dfd53ad93d2e0a6e7f470295dcd71057d825e1f87229e5afe2a906aa7cfc099fdfa04442dac33548b6988af8af58d2052529088f7b73ef00800f7fbcddb3",
"keyType": "main_key"
}

pubkey

The pubkey field represents the uncompressed public key concatenating two 32-byte integers in hex. PyCryptodome can import the key by prepending the flag 0x04. OpenSSL uses PEM to encode keys, and PyCryptodome can help here to export the key in PEM format.

from Crypto.PublicKey import ECC
pubkey_raw_hex = "3538dfd53ad93d2e0a6e7f470295dcd71057d825e1f87229e5afe2a906aa7cfc099fdfa04442dac33548b6988af8af58d2052529088f7b73ef00800f7fbcddb3"
pubkey = ECC.import_key(bytes.fromhex("04" + pubkey_raw_hex), curve_name="secp256r1")
with open("pubkey.pem", "wt") as pemfile:
pemfile.write(pubkey.export_key(format="PEM"))

Double check the key using OpenSSL:

$ openssl ec -text -inform PEM -in pubkey.pem -pubin
...
Public-Key: (256 bit)
pub:
04:35:38:df:d5:3a:d9:3d:2e:0a:6e:7f:47:02:95:
dc:d7:10:57:d8:25:e1:f8:72:29:e5:af:e2:a9:06:
aa:7c:fc:09:9f:df:a0:44:42:da:c3:35:48:b6:98:
8a:f8:af:58:d2:05:25:29:08:8f:7b:73:ef:00:80:
0f:7f:bc:dd:b3
ASN1 OID: prime256v1
NIST CURVE: P-256
...

message

The message is a binary encoded by base64 RFC 4648 §5 without the equal sign (=) paddings. Many base64 tools and libraries require padding equal sign (=) in the end of the string to make the length multiple of 4. The message in the example response has a length 351, which requires one = padding. A trick is always padding two equals at the end of the string before decoding.

The first 37 bytes in message are authenticator data, and the following bytes are client data in JSON.

The section section 6.1 in the WebAuthn specification defines the layout of the authenticator data.

rpIdHash, 32 bytes: the sha256 checksum of the text testnet.joyid.dev
flags, 1 byte: 0x05 in JoyID
signCount, 4 bytes: all zeros

base64 -d <<<'
K4sF4fAwPvuJj-TW3mARmMenuGSrvmohxzsueH4YfFIFAAAAAHsidHlwZSI6Indl
YmF1dGhuLmdldCIsImNoYWxsZW5nZSI6IlUybG5iaUIwYUdseklHWnZjaUJ0WlEi
LCJvcmlnaW4iOiJodHRwczovL3Rlc3RuZXQuam95aWQuZGV2IiwiY3Jvc3NPcmln
aW4iOmZhbHNlLCJvdGhlcl9rZXlzX2Nhbl9iZV9hZGRlZF9oZXJlIjoiZG8gbm90
IGNvbXBhcmUgY2xpZW50RGF0YUpTT04gYWdhaW5zdCBhIHRlbXBsYXRlLiBTZWUg
aHR0cHM6Ly9nb28uZ2wveWFiUGV4In0=' |
dd bs=1 count=37 2>/dev/null |
xxd
#=> 00000000: 2b8b 05e1 f030 3efb 898f e4d6 de60 1198
#=> 00000010: c7a7 b864 abbe 6a21 c73b 2e78 7e18 7c52
#=> 00000020: 0500 0000 00

Check the first two lines with the sha256 checksum:

echo -n 'testnet.joyid.dev' | sha256sum
#=> 2b8b05e1f0303efb898fe4d6de601198c7a7b864abbe6a21c73b2e787e187c52 -

The client data JSON looks like this:

base64 -d <<<'
K4sF4fAwPvuJj-TW3mARmMenuGSrvmohxzsueH4YfFIFAAAAAHsidHlwZSI6Indl
YmF1dGhuLmdldCIsImNoYWxsZW5nZSI6IlUybG5iaUIwYUdseklHWnZjaUJ0WlEi
LCJvcmlnaW4iOiJodHRwczovL3Rlc3RuZXQuam95aWQuZGV2IiwiY3Jvc3NPcmln
aW4iOmZhbHNlLCJvdGhlcl9rZXlzX2Nhbl9iZV9hZGRlZF9oZXJlIjoiZG8gbm90
IGNvbXBhcmUgY2xpZW50RGF0YUpTT04gYWdhaW5zdCBhIHRlbXBsYXRlLiBTZWUg
aHR0cHM6Ly9nb28uZ2wveWFiUGV4In0=' |
dd bs=1 skip=37 2>/dev/null |
jq
{
"type": "webauthn.get",
"challenge": "U2lnbiB0aGlzIGZvciBtZQ",
"origin": "https://testnet.joyid.dev",
"crossOrigin": false,
...
}

Notice the challenge field. It is the parameter passed to signChallenge, in base64.

base64 -d <<<'U2lnbiB0aGlzIGZvciBtZQ=='
#=> Sign this for me

Attention that message is not the binary to be signed. According to the Figure 4, Generating an assertion signature, in the WebAuthn specification, the binary to be signed is a concatenation of the authenticator data and the sha256 checksum of the client data JSON.

The following code shows how to prepare the message to sign and save it into the file message.bin. Attention that base64 must use the alternative keys - and _ to replace + and / respectively.

Attention

To decode base64 “RFC 4648 §5” in python, use either base64.b64decode(s, altchars="-_") or binascii.urlsafe_b64decode(s).

import base64
from Crypto.Hash import SHA256
message_bin = base64.urlsafe_b64decode(
"K4sF4fAwPvuJj-TW3mARmMenuGSrvmohxzsueH4YfFIFAAAAAHsidHlwZSI6Indl"
"YmF1dGhuLmdldCIsImNoYWxsZW5nZSI6IlUybG5iaUIwYUdseklHWnZjaUJ0WlEi"
"LCJvcmlnaW4iOiJodHRwczovL3Rlc3RuZXQuam95aWQuZGV2IiwiY3Jvc3NPcmln"
"aW4iOmZhbHNlLCJvdGhlcl9rZXlzX2Nhbl9iZV9hZGRlZF9oZXJlIjoiZG8gbm90"
"IGNvbXBhcmUgY2xpZW50RGF0YUpTT04gYWdhaW5zdCBhIHRlbXBsYXRlLiBTZWUg"
"aHR0cHM6Ly9nb28uZ2wveWFiUGV4In0==",
)
authenticator_data = message_bin[:37]
client_data = message_bin[37:]
message_to_sign = authenticator_data + SHA256.new(client_data).digest()
with open("message.bin", "wb") as fout:
fout.write(message_to_sign)

Attention

The message in the response is not the binary to be signed. Instead, the binary to be signed is a concatenation of the authenticator data and the sha256 checksum of the client data JSON.

signature

The field signature are two 32-byte integers first encoded in DER, then base64 RFC 4648 §5 without the equal sign (=) paddings.

Many base64 tools and libraries require padding equal sign (=) in the end of the string to make the length multiple of 4. The signature in the example response has a length 95, which requires one = padding.

OpenSSL also stores signature in DER, let’s save one in the file signature.der:

base64 -d <<<"MEUCICF25qdO6nLreEoBHnyaw-9R6XFHbIu-NwsAI53t016qAiEAgmhlwTEMxoWxKj79R1rUkB_6nrhJfws82DqHkY_HnqQ=" > signature.der

The command openssl asn1parse can parse the file signature.der in the DER format.

openssl asn1parse -dump -inform DER -in signature.der
# Output =>
# 0:d=0 hl=2 l= 69 cons: SEQUENCE
# 2:d=1 hl=2 l= 32 prim: INTEGER :2176E6A74EEA72EB784A011E7C9AC3EF51E971476C8BBE370B00239DEDD35EAA
# 36:d=1 hl=2 l= 33 prim: INTEGER :826865C1310CC685B12A3EFD475AD4901FFA9EB8497F0B3CD83A87918FC79EA4

PyCryptodome expects the signature of 64 bytes for two 32-byte integers. Following code uses the asn1 module to extract the raw signature from the DER binary.

import base64
from Crypto.Util.asn1 import DerSequence
signature_der = base64.urlsafe_b64decode(
"MEUCICF25qdO6nLreEoBHnyaw-9R6XFHbIu-NwsAI53t016qAiEAgmhlwTEMxoWx"
"Kj79R1rUkB_6nrhJfws82DqHkY_HnqQ=",
)
signature_seq = DerSequence()
signature_seq.decode(signature_der)
print(signature_seq[0].to_bytes(32).hex())
# => 2176e6a74eea72eb784a011e7c9ac3ef51e971476c8bbe370b00239dedd35eaa
print(signature_seq[1].to_bytes(32).hex())
# => 826865c1310cc685b12a3efd475ad4901ffa9eb8497f0b3cd83a87918fc79ea4

Verifying

PyCryptodome:

from Crypto.Hash import SHA256
from Crypto.Signature import DSS
DSS.new(pubkey, "fips-186-3").verify(SHA256.new(message_to_sign), signature)
print("Verified OK")

OpenSSL:

openssl dgst -sha256 -verify pubkey.pem -signature signature.der message.bin

Full Python code (Gist)

import base64
from Crypto.Hash import SHA256
from Crypto.PublicKey import ECC
from Crypto.Signature import DSS
from Crypto.Util.asn1 import DerSequence
response = {
"signature": "MEUCICF25qdO6nLreEoBHnyaw-9R6XFHbIu-NwsAI53t016qAiEAgmhlwTEMxoWx"
"Kj79R1rUkB_6nrhJfws82DqHkY_HnqQ",
"message": "K4sF4fAwPvuJj-TW3mARmMenuGSrvmohxzsueH4YfFIFAAAAAHsidHlwZSI6IndlYmF1dGhuLmdldCIsImNoYWxsZW5nZSI6IlUybG5iaUIwYUdseklHWnZjaUJ0WlEiLCJvcmlnaW4iOiJodHRwczovL3Rlc3RuZXQuam95aWQuZGV2IiwiY3Jvc3NPcmlnaW4iOmZhbHNlLCJvdGhlcl9rZXlzX2Nhbl9iZV9hZGRlZF9oZXJlIjoiZG8gbm90IGNvbXBhcmUgY2xpZW50RGF0YUpTT04gYWdhaW5zdCBhIHRlbXBsYXRlLiBTZWUgaHR0cHM6Ly9nb28uZ2wveWFiUGV4In0",
"challenge": "Sign this for me",
"alg": -7,
"pubkey": "3538dfd53ad93d2e0a6e7f470295dcd71057d825e1f87229e5afe2a906aa7cfc099fdfa04442dac33548b6988af8af58d2052529088f7b73ef00800f7fbcddb3",
"keyType": "main_key",
}
pubkey = ECC.import_key(
bytes.fromhex("04" + response["pubkey"]),
curve_name="secp256r1",
)
with open("pubkey.pem", "wt") as fout:
fout.write(pubkey.export_key(format="PEM"))
message_bin = base64.urlsafe_b64decode(response["message"] + "==")
authenticator_data = message_bin[:37]
client_data = message_bin[37:]
# https://github.com/duo-labs/py_webauthn/blob/master/webauthn/authentication/verify_authentication_response.py
message_to_sign = authenticator_data + SHA256.new(client_data).digest()
with open("message.bin", "wb") as fout:
fout.write(message_to_sign)
signature_der = base64.urlsafe_b64decode(response["signature"] + "==")
with open("signature.der", "wb") as fout:
fout.write(signature_der)
signature_seq = DerSequence()
signature_seq.decode(signature_der)
signature = signature_seq[0].to_bytes(32) + signature_seq[1].to_bytes(32)
DSS.new(pubkey, "fips-186-3").verify(SHA256.new(message_to_sign), signature)
print("Verified OK")

Renaming Browser Tab Names

me@iany.me (Ian Yang) — Fri, 21 Jul 2023 20:31:59 +0800

Renaming browser tab names may seem like a simple task, but it can actually be quite challenging.

Most browsers sync the tab name with the web page title. Therefore, it seems simple to set tab name by setting document.title:

document.title = "Custom Tab Name";

However, many web pages use JavaScript to alter the page title, which would override the custom name. While Object.defineProperty in JavaScript can override the property setter function, it’s not possible to access the original setter function for document.title. Fortunately, browsers sync page titles with the first <title> tag, so setting its content acts as a workaround to set the page title.

Here is the bookmark for renaming a tab. I also add %t as the token for the original page tab title. This is handy such as adding a custom prefix with Work: %t, or restoring the original title without reloading the page by using %t.

// Rename the document title using a bookmarklet.
//
// As a user,
// - Once I have renamed the tab, it should not be overwritten.
// - I can include the token %t as placeholder for the real title.
// - To restore, I can rename the tab to %t
//
// Install: Copy the code to
//
// https://caiorss.github.io/bookmarklet-maker/
//
// and generate the bookmarklet.
// Init only once
if (!("_renameTitle" in document)) {
// Force creating the title tag.
document.title = document.title || "";
const titleEl = document.getElementsByTagName("title")[0];
const titleTokenRegex = /%t/g;
// Remembers the real title
let titleWithoutRenaming = document.title;
// User set title
let titleWithRenaming = "";
// Rename the document title to v.
// If v contains the token %t, replace all occurences to the
// real title.
document._renameTitle = (v) => {
titleWithRenaming = v;
titleEl.innerText = v.replace(titleTokenRegex, titleWithoutRenaming);
};
Object.defineProperty(document, "title", {
// Other code will use document.title setter to change the title.
//
// Remember the new value as the real title but still use the
// title set by user.
set: (v) => {
titleWithoutRenaming = v;
// Once document has defined the title property, its value is
// not synchronized to the tab name.
//
// Here uses a workaround to set the title tag content.
titleEl.innerText = titleWithRenaming.replace(titleTokenRegex, v);
},
get: () => titleEl.innerText,
});
}
const title = prompt(
"Rename tab (Use token %t for original title)",
document.title
);
// title is null when user cancel the dialog.
if (title !== null) {
document._renameTitle(title);
}

Transforming Markdown to Attractive PDFs: A Guide to Using Pandoc with Xelatex

me@iany.me (Ian Yang) — Sat, 29 Apr 2023 21:43:02 +0800

I used to read lengthy and complex articles in the PDF format. Despite the abundance of PDF exporting options, the resulting files often appear unappealing. However, there is a solution. With the pandoc tool and the xelatex backend, you can transform Markdown files into aesthetically pleasing PDFs. In this tutorial, I will guide you through the steps of using pandoc with xelatex and share the lessons I’ve learned.

Installation

Ubuntu users can install the package texlive-xetex and pandoc, In macOS, I recommend a minimal installation:

brew install librsvg pandoc
brew install --cask basictex
sudo tlmgr update --self
sudo tlmgr update --all
for pkg in texliveonfly xelatex adjustbox tcolorbox collectbox ucs environ \
trimspaces titling enumitem rsfs xecjk fvextra svg transparent; do
sudo tlmgr install $pkg
done

The library librsvg is required to support SVG images.

Verify the installation by converting a simple markdown file.

echo "# Hello World" > test.md
pandoc --pdf-engine=xelatex -i test.md -o test.pdf

Tips

In LaTeX, the document class serves as the template for the basic page styles.

I’m a fan of koma-script, and I will choose between scrreprt and scrbook depending whether the file to create is more like a report or a book. I recommend try them and the standard classes like report and book, then choose the one that best suites your preferences.

To customize the document class in pandoc, simply set the variable documentclass. Other variables are available for controlling the LaTeX style. I use some of them to define my default style.

DOCUMENTCLASS="${DOCUMENTCLASS:-scrreprt}"
MAINFONT="${MAINFONT:-Helvetica}"
MONOFONT="${MONOFONT:-Cartograph CF}"
pandoc --pdf-engine=xelatex \
--variable fontsize=12pt \
--variable linestretch=1.5 \
--variable geometry=a4paper \
--variable documentclass="${DOCUMENTCLASS}" \
--variable mainfont="${MAINFONT}" \
--variable monofont="${MONOFONT}" \
-i test.md -o test.pdf

Gotchas

CJK

CJK is a collective term for the Chinese, Japanese, and Korean languages. When CJKmainfont is set, pandoc handles CJK characters with the xecjk package.

pandoc --variable CJKmainfont="Noto Serif CJK SC" ...

My recommendation is to only set CJKmainfont when needed to avoid messing up the quotation marks display. Where the article contains a mixture of English and Asian characters resulting in strange looking quotation marks '"“”‘’, consider trying the following solution.

Create a file cjk.latex to force English quotation marks.

% cjk.tex
\AtBeginDocument{%
\XeTeXcharclass`^^^^2019=0
}

Include this file via the pandoc argument -H such as pandoc -H cjk.tex.

The figure below shows the results from the same markdown file on my MacBook. However, when I test this in Ubuntu, it seems there are no such issues.

Fix CJK Quotation Marks

This is the input markdown file used in the example.

English's "straight quotations" and this’s “curly quotations”.
中文的"直引号"和“弯引号”。

Code Block Syntax Highlight

Pandoc does not wrap lines in code blocks by default. It truncated the lines which are too long to fit on the page.

To solve the problem mentioned above, I followed a solution on GitHub suggested by jannick0. It involves the creation of a file that contains the LaTeX snippets below. These snippets can then be included by using the pandoc argument -H highlighting.tex. Additionally, I added a border around the code block.

highlighting.tex

% use this file via pandoc -H highlighting.tex
\usepackage{fvextra}
\DefineVerbatimEnvironment{Highlighting}{Verbatim}{breaklines,breaknonspaceingroup,breakanywhere,frame=single,framesep=8pt,rulecolor=\color[HTML]{aaaaaa},commandchars=\\\{\}}

As I replied in the thread, this solution does not work for code blocks without setting a language. I use a Lua filter to set the language of these code blocks to “text”. To run the filter, save it in a file, say highlighting.lua, and invoke pandoc with --lua-filter=highlighting.lua

highlighting.lua

function CodeBlock(el)
if #el.classes == 0 then
el.classes[1] = 'text'
end
return el
end
return {{CodeBlock = CodeBlock}}

Disable Figures Floating

The last issue to address is the floating of figures in LaTeX, which moves the images to avoid large blank space in pages. While LaTeX attempts to place figures in appropriate locations, authors may refer to them as “above” or “below” in the markdown files. This can be confusing for readers who may find that the referenced chart or diagram is actually on the following page in the PDF file.

To solve the issue, simply disable floating figures. Create a file disable-floating.tex and invoke pandoc with arguments -H disable-floating.tex.

disable-floating.tex

% https://stackoverflow.com/a/58840456/667158
\usepackage{float}
\let\origfigure\figure
\let\endorigfigure\endfigure
\renewenvironment{figure}[1][2] {
\expandafter\origfigure\expandafter[H]
} {
\endorigfigure
}

Putting It All Together

See the repo doitian/pandoc-ide.

The Ultimate Guide to Customizing Obsidian Vim Mode via QuickAdd

me@iany.me (Ian Yang) — Thu, 27 Apr 2023 21:22:30 +0800

Obsidian is my go-to note-taking app because of its availability on all desktop and mobile platforms with the bonus of Vim mode. In this guide, I’ll show you how I customize the Vim mode in Obsidian to maximize my note-taking efficiency.

Setup User Launch Scripts via QuickAdd

To customize the Vim mode in Obsidian, JavaScript is the only solution. Obsidian allows running user scripts by implementing an plugin. I use an easy alternative to run a JavaScript file on launch via QuickAdd.

First, let’s create the JavaScript file in the vault. Save the skeleton below as the file vimrc.js in any folder in the vault. Keep in mind that Obsidian does not support editing JavaScript files, so use an external editor.

vimrc.js

function notice(text) {
new Notice(text);
return text;
}
module.exports = async function (context) {
const vim = window.CodeMirrorAdapter?.Vim;
if (vim === undefined) {
new Notice(`🔴error: vim mode is disabled`);
return;
}
// Add customizations here.
console.log(`🔵info: vimrc loaded`);
};

Then, install QuickAdd by browsing the community plugins in Settings and follow the instructions on the Obsidian help page Community Plugins.

Finally, include the script in a QuickAdd macro and activate the option to execute the macro upon the plugin load.

Open the tab QuickAdd in Settings.
Click the button “Manage Macros”. In the pop-up dialog, fill in the macro name “vimrc” and click the button “Add macro“ to add a new macro vimrc.
Toggle the option “Run on plugin load” on under the newly created macro.
Configure the macro vimrc. Find the script file vimrc in the “User Scripts” section and add the script as the only step in the macro.

Attention that the script runs once on launch or reload. Running “Reload app without saving” via Command Palette will reload the file after changes,

Vim Mode Customization Techniques

For the best tutorial on customizing Vim mode and what methods the vim object provides, refer to how CodeMirror establishes the Vim mode. I will only introduce the methods that I use in my own customizations.

`vim.defineEx`

The defineEx method enables users to execute a new ex command in Vim by typing : in normal mode. For instance, the ex command :w saves the file.

I introduce defineEx first because I need an ex command to run any Obsidian command so that I can use it to add key bindings later. I name this command obr, which is the abbreviation of OBsidian Run. The command requires the Obsidian command identifier as the argument, for example, :obr app:open-settings will open the Settings dialog.

vim.defineEx("obr", "", function (cm, params) {
if (params?.args?.length !== 1) {
throw new Error(notice("🔴error: obr requires exactly 1 parameter"));
}
const command = params.args[0];
context.app.commands.executeCommandById(command);
});

To find the command identifier, I add another ex command :obl to display a list of identifiers and copy the selected one. It accepts an argument to filter the result. For example, obl open will list identifiers that contain the word “open”.

vim.defineEx("obl", "", async function (cm, params) {
let commands = Object.keys(context.app.commands.commands);
for (const keyword of params?.args ?? []) {
commands = commands.filter((command) => command.includes(keyword));
}
const choice = await context.quickAddApi.suggester(commands, commands);
if (choice !== null) {
await context.quickAddApi.utility.setClipboard(choice);
new Notice(`🔵info: copied ${choice} to the clipboard`);
}
});

`vim.map`

The vim.map method takes two arguments, lhs and rhs, which can both be either a key sequence or an ex command. The meaning of the method varies depending on the arguments passed.

When both lhs and rhs are key sequence, it maps the key sequence lhs to rhs. For example, vim.map('D', 'dd') will redefine D to delete the whole line.
When both lhs and rhs are ex commands, it creates a new ex command alias. For example, vim.map(':Reload', ':obr app:reload') adds the alias :Reload to run the Obsidian command app:reload.
When lhs is a key sequence, and rhs is an ex command, it maps the key sequence to run the ex command. For example vim.map('ZZ', ':obr app:reload') allows reloading Obsidian by typing ZZ.
When lhs is an ex command, and rhs is a key sequence, executing the ex command has the same effect as typing the key sequence.

I have a bunch of mappings from key sequences to :obr, for example, the z-family to operate on folds:

vim.map("zo", ":obr editor:toggle-fold");
vim.map("zc", ":obr editor:toggle-fold");
vim.map("za", ":obr editor:toggle-fold");
vim.map("zR", ":obr editor:unfold-all");
vim.map("zM", ":obr editor:fold-all");

To use the space key as a key mapping prefix, it must first be unmapped.

vim.unmap("<Space>");
vim.map("<Space><Space>", ":obr switcher:open");
vim.map("<Space>n", ":nohl");

`vim.defineAction` and `vim.defineOperator`

We can use both action and operator in vim.mapCommand. The difference is that an operator performs upon text objects. See how CodeMirror defines the built-in actions and operators.

I have an action swapLine to move lines around. It’s not perfect, since undo will reverse one step only.

vim.defineAction("swapLine", function(_cm, { repeat, down }) {
const command = down ? "editor:swap-line-down" : "editor:swap-line-up";
for (let i = 0; i < repeat; i++) {
context.app.commands.executeCommandById(command);
}
});
// undo after 5]e will only swap one line up.
vim.mapCommand("]e", "action", "swapLine", { down: true });
vim.mapCommand("[e", "action", "swapLine", { down: false });

The example for vim.defineOperator is titleCase, which formats the text in the APA Title Case Capitalization. For instance, gzap formats the current paragraph in the title case.

function titleCase(str, options) {
// See https://github.com/words/ap-style-title-case/blob/master/index.js how to format str to apa title case
}
// Following helper funnctions are borrowed from https://codemirror.net/5/keymap/vim.js
function cursorIsBefore(cur1, cur2) {
if (cur1.line < cur2.line) {
return true;
}
if (cur1.line == cur2.line && cur1.ch < cur2.ch) {
return true;
}
return false;
}
function cursorMin(cur1, cur2) {
return cursorIsBefore(cur1, cur2) ? cur1 : cur2;
}
function findFirstNonWhiteSpaceCharacter(text) {
if (!text) {
return 0;
}
var firstNonWS = text.search(/\S/);
return firstNonWS == -1 ? text.length : firstNonWS;
}
vim.defineOperator("titleCase", function(cm, args, ranges, oldAnchor, newHead) {
const selections = cm.getSelections();
const newSelections = selections.map((s) =>
titleCase(s, { keepSpaces: true })
);
cm.replaceSelections(newSelections);
if (args.shouldMoveCursor) {
return newHead;
} else if (
!cm.state.vim.visualMode &&
args.linewise &&
ranges[0].anchor.line + 1 == ranges[0].head.line
) {
return {
line: oldAnchor.line,
ch: findFirstNonWhiteSpaceCharacter(cm.getLine(oldAnchor.line)),
};
} else if (args.linewise) {
return oldAnchor;
} else {
return cursorMin(ranges[0].anchor, ranges[0].head);
}
return newHead;
});
vim.mapCommand("gz", "operator", "titleCase");

Practice Autofocus Method in Todoist

me@iany.me (Ian Yang) — Mon, 03 Oct 2022 19:26:38 +0800

I read the article Autofocus: The Productivity System That Treats Your to-Do List Like a River¹ recently. I used to fill the time slots with tasks daily, but I rarely completed all the planned tasks. Even for the completed ones, I often missed the scheduled time slot. I felt stressed and guilty. So I decide to give the Autofocus Method a try.

The River Filter

I will continue using Todoist. I created a filter named River. The tasks are sorted by added date. I added the filter to the sidebar and set it as my home view for easy access.

The filter has three sections:

Overdue tasks: overdue
Tasks I am doing: today | @now💧
Tasks in River: !##⏰ Events & !overdue & !today & !@now💧 & !@someday🪨

Todoist supports filter sections by separating queries with comma (,). So here is the final filter query:

overdue, today | @now💧, !##⏰ Events & !overdue & !today & !@now💧 & !@someday🪨

Section 1: Overdue Tasks

This section allows me to re-schedule the overdue tasks.

I decided to not totally abandon the due dates. However, I use them with great moderation. I set a due date if I must complete the task on that date, and before the day comes, I can forget the task.

I add such tasks to the project ⏰ Events. They will appear in the River filter when they are due or overdue.

Section 2: Tasks I Am Doing

This section lists tasks that I am doing now.

There are two kinds of such tasks.

The first is the scheduled tasks that are due today.

The second is the selected tasks from the river. I add the tag @now💧 to the task if I feel like doing it.

Section 3: Tasks in River

This section contains the tasks in the river. It excludes tasks from the project ⏰ Events, and the dismissed tasks. I tag dismissed tasks with @someday🪨 .

The Workflow

I add new tasks to the inbox without triaging the projects, tags, due dates, and priorities. Since the filter

When I have time to do something, I open the River filter and scan the tasks from top to bottom without scrolling down.

First, I re-schedule the overdue tasks.

Then, I do a quick scan on the second section—the tasks that I planned before. If I feel like doing a task in the list, I start working on it.

If I failed to find a task to work on in the previous step, I continue the scan to the last section—the tasks in the river. I add tag @now💧 to pop the task to the top of the list.

If there are no items stands out for me, I have three choices to remove tasks from the first screen:

Defer the scheduled tasks into future.
Remove the tag @now💧 from the task.
Dismiss a task by adding the tag @someday🪨.

The Autofocus Method suggests to cross the item off the list and re-enter it at the end of the list if I haven’t finished it yet. In Todoist, I duplicate the task and cross the original item off.

Here is my setup to practice the Autofocus Method in Todoist. I’m still experimenting to see whether it can improve my productivity.

References

McKay, B., & McKay, K. (2022, September 20). Autofocus: The Productivity System That Treats Your To-Do List Like a River. The Art of Manliness. https://www.artofmanliness.com/character/behavior/autofocus-the-productivity-system-that-treats-your-to-do-list-like-a-river/