From 36381d86c6a690a7870ce360dad63be333361447 Mon Sep 17 00:00:00 2001
From: Sam Anthony <sam@samanthony.xyz>
Date: Fri, 6 Mar 2026 17:34:57 -0500
Subject: doc: authfs 9p interface description

---
 doc/authfs.md | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)
 create mode 100644 doc/authfs.md

diff --git a/doc/authfs.md b/doc/authfs.md
new file mode 100644
index 0000000..0f3ee6f
--- /dev/null
+++ b/doc/authfs.md
@@ -0,0 +1,33 @@
+# 9P files served by the `authfs` daemon
+
+`users/`
+	`<username>/`
+		`passwd`
+		`passwdhash`
+		`login`
+`sessions/`
+	`<id>/`
+		`user`
+
+`/users/<username>/` (d)
+To add a user, create the `<username>` subdirectory. Authfs
+automatically creates the `passwd`, `passwd`, and `login` files
+inside.
+
+`/users/<username>/passwd` (w)
+Writing a (cleartext) password changes the user's password.
+
+`/users/<username>/passwdhash` (r)
+Read returns an Argon2id hash of the user's password (see
+github.com/alexedwards/argon2id).
+
+`/users/<username>/login` (rw)
+To log in and obtain a session, write the user's password to `login`
+(in cleartext). Then read from `login`. If the password was correct,
+the read will return a session `<id>` corresponding to a directory
+under `/sessions/`. Otherwise if the password was incorrect, the read
+returns `Rerror`.
+
+`/sessions/<id>/user` (r)
+Read returns the `<username>` of the user who owns the session
+identified by `<id>`.
-- 
cgit v1.2.3