SPHINX-X11(1)

💖 NAME 💖

sphinx-x11 — the cutest little script interpreter for gluing your password manager to X11, no cap 🦋

---

✨ DESCRIPTION ✨

okay so. sphinx-x11(1) is a simple "script" language interpreter — yes bestie, a whole tiny language — whose entire job is integrating the SPHINX CLI with X11. it types stuff into your windows for you so you don't have to. it's giving personal assistant energy fr fr 💅

---

🎀 SPHINX-SCRIPT PARAMETERS 🎀

every sphinx-x11(1) script expects two things, in this order:

1. a username as the first parameter
2. a hostname as the second parameter

that's the vibe check. first and second parameter respectively, periodt.

---

🌸 VOCABULARY 🌸

here's every token your script can speak. these are the words, the whole lexicon, the main character glossary 👑

• type "text..." — types the given text... right into whichever X11 window has focus rn
• wait-for-click — just chills until you click anywhere. whenever. no rush 🫶
• user — types the username (usually the first parameter handed to the sphinx script) into the currently focused X11 window
• host — types the hostname (usually the second script parameter) into the currently focused X11 window
• pwd — grabs a password via getpwd(1) and sphinx(1), then types it into the currently focused X11 window
• otp — calculates the current Time-based One-Time Password (TOTP) pin code using an OTP secret that lives in sphinx(1) (fetched via getpwd(1)), then types it into the currently focused X11 window
• tab — types a tab character into the currently focused X11 window, which usually hops you between form fields
• enter — sends an Enter key press into the focused X11 window, which usually submits a form
• gethost — waits for a left mouse click on a browser window, copies the URL out of the address bar, extracts the hostname, and stashes it in the internal $host variable so host or pwd (defined above) can use it
• getuser — runs sphinx list $host. if it finds multiple users, it shows them off in a dmenu widget. if/when one user is found and/or selected, that becomes the internal $user variable, which user or pwd (defined above) can then use

any lines that aren't made of these tokens? literally just ignored. not read. not acknowledged. ghosted 💀

---

🔥 OTP SUPPORT 🔥

in this implementation, a TOTP value gets stored with a username prefixed by otp:// — that way a regular username can co-exist with its TOTP secret in SPHINX. two icons, one name, slay ✨

for example, in a common two-factor authentication (2FA) login, the first pwd operation might use joe as the username, and the TOTP value would be retrieved with otp://joe as the username. which allows for seamless 2FA login, bestie. seamless. 💅

---

🌈 DEFAULT SCRIPTS 🌈

sphinx-x11(1) ships with five default scripts. on Debian-based systems, these use a sx11- prefix instead of the .sphinx extension. iykyk.

• pass.sphinx — gets a password using sphinx(1), types it, and submits it.
• user-pass.sphinx — gets a password using sphinx(1), types the username, and then submits it.
• user-pass-otp.sphinx — gets a password, and a TOTP pin code using sphinx(1), types the username, the password, then submits the form, and finally enters the TOTP pin and submits again.
• otp.sphinx — gets a TOTP pin using sphinx(1) and types and submits it.
• getacc-user-pass.sphinx — waits for a click on a browser window, from which it gets the target host. it uses this together with sphinx list to list users associated with the host. then it waits for another click in the username input field of a login form, gets a password using sphinx(1), types the username, password, and submits.

🚨 okay so about getacc-user-pass.sphinx: this script is convenient but it carries phishing risks if a malicious site manipulates the clipboard. use this script very carefully. at the moment, this security problem is not fixed, since there is no simple way to get the current tab's URL from a browser securely via a web extension. don't be the main character of a cautionary tale, bestie 😭

all of these scripts wait for user interaction before retrieving passwords (and/or TOTP tokens) and entering them, navigating with tab and enter. you are welcome to contribute adapted sphinx scripts for websites that have other login semantics 🫶

---

⭐ EXAMPLE ⭐

this example shows off the user-pass-otp.sphinx script:

#!sphinx-x11

wait-for-click
user
tab
pwd
tab
enter
wait-for-click
otp
enter

explanation, line by line, because we don't gatekeep 🎀

• Line 1: specifies sphinx-x11(1) as the script interpreter.
• Line 3: waits for the user to click.
• Line 4: types the username (first script parameter).
• Line 5: sends a tab key to move to the next form field.
• Line 6: retrieves and types the password for the specified user and host (second script parameter).
• Line 7: sends another tab key to move focus.
• Line 8: presses enter to submit the form.
• Line 9: waits for the user to click in the TOTP input field of the next form.
• Line 10: retrieves the TOTP value via pwdsphinx/getpwd and types it.
• Line 11: presses enter to submit the TOTP form.

---

🙈 REPORTING BUGS 🙈

found a bug? spill, babe:

https://github.com/stef/pwdsphinx/issues/

---

🧚 AUTHOR 🧚

Written by Stefan Marsiske.

---

👑 COPYRIGHT 👑

Copyright © 2023 Stefan Marsiske. License GPLv3+: GNU GPL version 3 or later https://gnu.org/licenses/gpl.html. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. (fr fr, no warranty, take it or leave it 💀)

---

💜 SEE ALSO 💜

sphinx(1), type-pwd(1), exec-on-click(1), getpwd(1)

---

and that's the whole page bestie — sp...1(1), section 1 of the manual, served fresh 💖 go forth and automate your logins, you gorgeous genius. slay 🦋✨