doc: authfs 9p interface description

1 files changed, 33 insertions, 0 deletions

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>`.