index.html 21 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316
  1. <!doctype html>
  2. <html lang="en-nz">
  3. <head>
  4. <meta charset="utf-8">
  5. <meta name="viewport" content="width=device-width, initial-scale=1">
  6. <title>Spry — Astrologue Developer</title>
  7. <meta name="description" content="Spry is the authentication and user-management layer for Statum applications — the signed auth slot, authoritative guards, subclassable actions, the spry_users schema — plus the spry CLI that scaffolds, keys and deploys an application. Free software, LGPL-3.0-or-later.">
  8. <meta name="color-scheme" content="light dark">
  9. <meta name="theme-color" content="#f2ebda" media="(prefers-color-scheme: light)">
  10. <meta name="theme-color" content="#0a0a12" media="(prefers-color-scheme: dark)">
  11. <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'%3E%3Ccircle cx='32' cy='32' r='27' fill='none' stroke='%23a8801f' stroke-width='4'/%3E%3Cpath d='M32 8l6 18 18 6-18 6-6 18-6-18-18-6 18-6z' fill='%23a8801f'/%3E%3Ccircle cx='32' cy='32' r='4' fill='%23003078'/%3E%3C/svg%3E">
  12. <meta property="og:title" content="Spry — Astrologue Developer">
  13. <meta property="og:description" content="Reusable authentication and user-management services for Statum — the signed auth slot, guards and subclassable actions — plus the spry CLI that scaffolds, keys and deploys an application.">
  14. <meta property="og:type" content="website">
  15. <link rel="stylesheet" href="../../assets/css/style.css">
  16. </head>
  17. <body>
  18. <a class="skip-link" href="#main">Skip to content</a>
  19. <header class="masthead">
  20. <div class="container masthead__inner">
  21. <a class="brand" href="../../">
  22. <img class="brand__logo brand__logo--light" src="../../assets/img/astrologue-light.png" width="392" height="89" alt="Astrologue">
  23. <img class="brand__logo brand__logo--dark" src="../../assets/img/astrologue-dark.png" width="392" height="89" alt="Astrologue">
  24. </a>
  25. <nav class="site-nav" aria-label="Primary">
  26. <ul class="site-nav__list">
  27. <li><a href="../../">Home</a></li>
  28. <li><a href="../../#news">News</a></li>
  29. <li><a href="../../#download">Download</a></li>
  30. <li><a href="../" aria-current="page">Developer</a></li>
  31. <li><a class="nav-cta" href="../../#download">Get Astrologue</a></li>
  32. </ul>
  33. </nav>
  34. </div>
  35. </header>
  36. <main id="main">
  37. <nav class="breadcrumb" aria-label="Breadcrumb">
  38. <div class="container">
  39. <ol>
  40. <li><a href="../../">Astrologue</a></li>
  41. <li><a href="../">Developer</a></li>
  42. <li aria-current="page">Spry</li>
  43. </ol>
  44. </div>
  45. </nav>
  46. <section class="docs-header">
  47. <div class="container">
  48. <p class="kicker"><span>Web stack · Users at the door</span></p>
  49. <h1>Spry</h1>
  50. <p class="lede">Authentication and user management for Statum applications. Identity is a signed Statum slot — no cookies, no bearer tokens — with user ids sealed in encrypted private data, guards that re-validate against the store on every request, and a set of ready-made actions built for subclassing. The spry CLI scaffolds an application, maintains its keys and ships it as a container image.</p>
  51. <dl class="docs-facts">
  52. <div><dt>Version</dt> <dd><code>0.2</code></dd></div>
  53. <div><dt>Licence</dt> <dd>LGPL-3.0-or-later</dd></div>
  54. <div><dt>Package</dt> <dd><code>usm&nbsp;install&nbsp;spry</code></dd></div>
  55. <div><dt>Language</dt> <dd>Vala</dd></div>
  56. </dl>
  57. </div>
  58. </section>
  59. <section class="band band--plain" id="docs">
  60. <div class="container docs-layout">
  61. <nav class="docs-toc" aria-label="On this page">
  62. <h2>On this page</h2>
  63. <ul>
  64. <li><a href="#overview">Overview</a></li>
  65. <li><a href="#features">Features</a></li>
  66. <li><a href="#installation">Installation</a></li>
  67. <li><a href="#usage">Usage &amp; documentation</a></li>
  68. <li><a href="#package">Package &amp; source</a></li>
  69. </ul>
  70. </nav>
  71. <div class="docs-prose">
  72. <header class="section-head" id="overview">
  73. <p class="kicker"><span>Overview</span></p>
  74. <h2>Who is asking?</h2>
  75. </header>
  76. <p>Spry answers the first question every application with users must answer, and it answers with the machinery <a href="../statum/">Statum</a> already provides rather than adding a parallel one. It renders nothing itself — pages, layouts and resources are Statum's job, and the auth UI arrives as app-owned templates generated by the CLI. Its place in the stack:</p>
  77. <figure class="code-plate">
  78. <pre><code>astralis HTTP request handling
  79. └─ Statum pages, slots/state, directives, client JS
  80. └─ Spry THIS LIBRARY: users, auth slot, actions, guards
  81. ├─ Invercargill-Sql spry_users / spry_user_permissions schema
  82. └─ Inversion module + service wiring</code></pre>
  83. <figcaption>The stack, from Spry's README.</figcaption>
  84. </figure>
  85. <p>Adding it to an application is one module; seeding an administrator at startup is idempotent, so the same code runs on every boot:</p>
  86. <figure class="code-plate">
  87. <pre><code>application.add_module&lt;StatumModule&gt;();
  88. application.add_module&lt;SpryModule&gt;(); // UserService + schema + migrations
  89. var statum = application.configure_with&lt;StatumConfigurator&gt;();
  90. SpryAuth.register_actions(statum); // or hand-pick with statum.action&lt;T&gt;()
  91. var scope = application.container.create_scope();
  92. yield SpryAuth.ensure_admin(scope.resolve&lt;UserService&gt;(),
  93. "admin", "admin@example.com", "change-me");</code></pre>
  94. <figcaption>From Spry's README — <code>SpryModule</code> registers no endpoints; it wires the migration, entity mappings and the scoped <code>UserService</code>.</figcaption>
  95. </figure>
  96. <header class="section-head" id="features">
  97. <p class="kicker"><span>Features</span></p>
  98. <h2>What it hands you</h2>
  99. </header>
  100. <ul class="docs-features">
  101. <li><strong>The signed auth slot.</strong> Identity as a SESSION slot of type name <code>"auth"</code> — no cookies, no bearer tokens — written once at login and read on every request.</li>
  102. <li><strong>Encrypted user ids.</strong> The authoritative <code>user_id</code> lives in the slot's encrypted private data and never reaches the browser; a stolen public copy cannot impersonate anyone.</li>
  103. <li><strong>Authoritative guards.</strong> <code>SpryAuth.require_login</code> and <code>require_permission</code> re-validate against the store on every guarded request — disabling, deleting or revoking takes effect immediately, and a store failure fails closed.</li>
  104. <li><strong>Subclassable actions.</strong> Nine shipped actions — login, register, logout, password change, enable, grant, revoke, alter, delete — whose redirect URIs and notification messages are <code>protected virtual</code> properties.</li>
  105. <li><strong>Sealed row actions.</strong> User-management actions read their target id from encrypted private data authored per row, so management buttons cannot be aimed at another account.</li>
  106. <li><strong>A user store.</strong> <code>UserService</code> with idempotent permission grants, targeted revokes, and an authenticate path with no account-enumeration side channel.</li>
  107. <li><strong>The spry CLI.</strong> <code>spry new</code> scaffolds a packaged application, <code>spry add</code> grows it, <code>spry keys</code> maintains key material, <code>spry dev</code> is the watch loop, <code>spry deploy</code> builds the container image.</li>
  108. </ul>
  109. <header class="section-head" id="installation">
  110. <p class="kicker"><span>Installation</span></p>
  111. <h2>Getting the library</h2>
  112. </header>
  113. <p>With USM on your machine, one command acquires, builds and installs the library, the spry CLI, the C header, Vala binding and introspection:</p>
  114. <figure class="code-plate">
  115. <pre><code>usm install spry</code></pre>
  116. <figcaption>Installs from the Astrologue package repository.</figcaption>
  117. </figure>
  118. <p>From source, the build lives at the repository root:</p>
  119. <figure class="code-plate">
  120. <pre><code>git clone &lt;the Spry repository&gt;
  121. cd Spry
  122. meson setup . build
  123. ninja -C build
  124. ninja -C build install</code></pre>
  125. <figcaption>The same meson invocation the package's own build script uses.</figcaption>
  126. </figure>
  127. <p>Then compile against it with Vala's usual package mechanism:</p>
  128. <figure class="code-plate">
  129. <pre><code>valac --pkg spry-0.2 my-app.vala</code></pre>
  130. <figcaption>The installed <code>spry-0.2.deps</code> resolves the Statum, Astralis, Invercargill-Sql and Inversion bindings for you.</figcaption>
  131. </figure>
  132. <header class="section-head" id="usage">
  133. <p class="kicker"><span>Usage &amp; documentation</span></p>
  134. <h2>Identity, guards, actions</h2>
  135. </header>
  136. <p>Spry's README is its documentation, and it is a thorough one — the stack diagram, every action's form fields and guards, the user store's contract, and the CLI's full command surface. These idioms are lifted from it.</p>
  137. <h3>The auth slot</h3>
  138. <p>The slot's public fields are signed and browser-visible — bind them for navigation and guards. The private field is signed and encrypted, and never reaches the browser:</p>
  139. <figure class="code-plate">
  140. <pre><code>username public signed login name; bind for nav/guards
  141. display_name public signed forename + surname, falling back to username
  142. permissions public signed string[] patterns: admin/* match everything
  143. logout public signed embedded ActionDto for logout buttons
  144. user_id private signed + authoritative spry_users.id — never
  145. encrypted reaches the browser</code></pre>
  146. <figcaption>The <code>auth</code> slot, field by field, from Spry's README.</figcaption>
  147. </figure>
  148. <p>Because the whole slot is signed under static keys in <code>web-config.json</code>, a session survives a server restart; because <code>user_id</code> is sealed, editing a browser-side copy gains nothing.</p>
  149. <h3>Reading identity, guarding handlers</h3>
  150. <figure class="code-plate">
  151. <pre><code>public class ProfileEntrypoint : StatumEntrypoint {
  152. protected UserService users = inject&lt;UserService&gt;();
  153. public override async DirectiveBuilder handle() throws GLib.Error {
  154. var guard = yield SpryAuth.require_login(directives(), request, users);
  155. if (guard != null) {
  156. return (!)guard; // navigate("/login")
  157. }
  158. var me = SpryAuth.current(request);
  159. if (!me.has_permission("reports.read")) { // admin / users.* wildcards work
  160. ...
  161. }
  162. ...
  163. }
  164. }</code></pre>
  165. <figcaption>From Spry's README — the guard takes the caller's builder and the caller's <code>UserService</code>.</figcaption>
  166. </figure>
  167. <p><code>SpryAuth.current</code> returns the cheap display identity — the signed snapshot minted at login, anonymous when no slot is held — while the guards are authoritative: <code>require_login</code> answers <code>null</code> only when the held slot's user id still maps to a live, enabled account, and <code>require_permission</code> additionally re-derives the permission set from the store. Permission patterns keep their exact older semantics: <code>admin</code> and <code>*</code> match everything, <code>prefix*</code> matches any permission with that prefix, everything else is exact.</p>
  168. <h3>The shipped actions</h3>
  169. <p>Nine actions cover the standard account surface. Each is a <code>StatumAction</code> subclass designed for subclassing — a different landing page or friendlier message is one override away:</p>
  170. <figure class="code-plate">
  171. <pre><code>public class LoginAction : StatumAction {
  172. private UserService users = inject&lt;UserService&gt;();
  173. /** URI navigated to after a successful login. */
  174. protected virtual string landing_uri { get { return "/"; } }
  175. /** Notification shown when the credentials do not match an account. */
  176. protected virtual string invalid_credentials_message {
  177. get { return "Invalid username or password"; }
  178. }
  179. public override async DirectiveBuilder handle() throws GLib.Error {
  180. ...
  181. var user = yield users.authenticate_user(username, password);
  182. if (user == null) {
  183. return directives().notify("error", invalid_credentials_message);
  184. }
  185. return SpryAuth.login(directives(), (!)user, action_registry)
  186. .navigate(landing_uri);
  187. }
  188. }</code></pre>
  189. <figcaption>From <code>src/Actions/LoginAction.vala</code> — unknown usernames and wrong passwords answer the same generic notify, so the response leaks no account existence.</figcaption>
  190. </figure>
  191. <p>The full set: <code>LoginAction</code>, <code>RegisterAction</code>, <code>LogoutAction</code>, <code>ChangePasswordAction</code> (logged-in), and — guarded by <code>require_permission</code>, default <code>admin</code> — <code>SetUserEnabledAction</code>, <code>GrantPermissionAction</code>, <code>RevokePermissionAction</code>, <code>AlterUserAction</code> (refuses self-alter) and <code>DeleteUserAction</code> (refuses self-delete). The five management actions read their target from sealed private data:</p>
  192. <figure class="code-plate">
  193. <pre><code>var target = new Spry.Actions.UserActionPrivate();
  194. target.user_id = row_user.id;
  195. row.grant = action_registry
  196. .author_private&lt;Spry.Actions.GrantPermissionAction,
  197. Spry.Actions.UserActionPrivate&gt;(target);</code></pre>
  198. <figcaption>From Spry's README — the id travels in an encrypted blob sealed under the action's own namespace.</figcaption>
  199. </figure>
  200. <p>Register and Alter share one validator — username length, email shape, required names, and a strict YYYY-MM-DD date-of-birth parse that rejects impossible calendar dates by round-tripping the parsed date. Both map uniqueness failures to the same friendly duplicate messages, so raw database errors never reach the client.</p>
  201. <h3>The user store</h3>
  202. <p><code>UserService</code> is injected per request, every method <code>async</code> and <code>throws Error</code>. Its authenticate path returns <code>null</code> for an unknown username, a wrong password or a disabled account — the same generic failure each time, with a dummy hash check burned for unknown usernames so both paths take comparable time. Permission grants are idempotent (no duplicate row when already held); revocation is a single targeted delete of the matching rows; and stale ids raise <code>UserServiceError.USER_NOT_FOUND</code> instead of crashing.</p>
  203. <h3>The spry CLI</h3>
  204. <figure class="code-plate">
  205. <pre><code>spry new my-app # scaffold an application, packaged for USM
  206. spry add page # grow it inside marker blocks
  207. spry add action
  208. spry add resource
  209. spry add login # auth UI bound to Spry.Actions
  210. spry add register
  211. spry add user-management
  212. spry keys # maintain the static key pairs
  213. spry dev # build, run, watch — a failed build keeps the old process
  214. spry deploy # build the USM container image</code></pre>
  215. <figcaption>The command surface, from Spry's README — <code>spry --help</code> lists it in full.</figcaption>
  216. </figure>
  217. <p><code>spry new</code> includes the USM packaging — <code>MANIFEST.usm</code>, <code>usm-scripts/</code>, <code>.usmignore</code> — so a generated application is installable from birth. <code>spry deploy</code> delegates to <code>usm manifest deploy</code>: the application's manifest drives an in-container install where the system package manager resolves the platform libraries and USM repositories resolve the Web-Stack, and the image is saved as <code>&lt;app&gt;-&lt;version&gt;.image.tar.xz</code> for <code>podman load -i</code>. Target systems include Fedora, Debian, Ubuntu, Alpine and Gentoo. Keys are never packaged — <code>.usmignore</code> excludes <code>web-config.json</code> — so an image serves plain pages with ephemeral keys, or full authentication when the config is bind-mounted read-only.</p>
  218. <header class="section-head" id="package">
  219. <p class="kicker"><span>Package &amp; source</span></p>
  220. <h2>The ledger</h2>
  221. </header>
  222. <dl class="docs-package">
  223. <div><dt>Version</dt><dd><code>0.2</code> (from <code>MANIFEST.usm</code>)</dd></div>
  224. <div><dt>Licence</dt><dd>LGPL-3.0-or-later — free to run, study, share and improve; the LGPL keeps it free to link from any program.</dd></div>
  225. <div><dt>Package</dt><dd><code>usm install spry</code></dd></div>
  226. <div><dt>Provides</dt><dd><code>libspry-0.2.so</code>, <code>spry</code> (the CLI), <code>spry-0.2.h</code>, <code>spry-0.2.vapi</code> + <code>.deps</code>, <code>spry-0.2.gir</code>, <code>spry-0.2.pc</code></dd></div>
  227. <div><dt>Needs at runtime</dt><dd>GLib and GObject, json-glib, libsodium, plus the stack beneath: <code>libinvercargill-1.so</code>, <code>libinversion-0.1.so</code>, <code>libastralis-0.1.so</code>, <code>libstatum-0.1.so</code>, <code>libinvercargill-sql.so</code> and <code>libinvercargill-sql-inversion.so</code>.</dd></div>
  228. <div><dt>Source</dt><dd>The repository <code>Tilo15/Spry</code> on the Astrologue forge (git over ssh, port 222). Free software: the licence guarantees your right to the source.</dd></div>
  229. </dl>
  230. <p>One honest gap: the package ships a GIR but no typelib. Spry's migration classes derive from a class in a nested namespace of Invercargill-Sql, and the Vala 0.56 GIR writer drops the intermediate namespace segment when naming a parent from another library — so <code>g-ir-compiler</code> cannot resolve the parent type and the typelib cannot be built. The GIR is installed, and the packaging records the blocker; Vala and C consumers are unaffected.</p>
  231. <nav class="docs-siblings" aria-label="Neighbours in the catalogue">
  232. <p>Its neighbours:</p>
  233. <ul>
  234. <li><a href="../statum/">Statum</a> — the framework it extends</li>
  235. <li><a href="../invercargill-sql/">Invercargill-Sql</a> and <a href="../invercargill-sql-inversion/">Invercargill-Sql-Inversion</a> — its schema and wiring</li>
  236. <li><a href="../locksmith/">Locksmith</a> — the stack's cryptography, next in the catalogue</li>
  237. </ul>
  238. </nav>
  239. <nav class="docs-pager" aria-label="Project pages">
  240. <a class="docs-pager__link docs-pager__link--prev" href="../statum/">
  241. <span>Previous</span>
  242. <strong>Statum</strong>
  243. </a>
  244. <p class="docs-pager__up"><a href="../">All eleven</a></p>
  245. <a class="docs-pager__link docs-pager__link--next" href="../locksmith/">
  246. <span>Next in the catalogue</span>
  247. <strong>Locksmith</strong>
  248. </a>
  249. </nav>
  250. </div>
  251. </div>
  252. </section>
  253. </main>
  254. <footer class="site-footer">
  255. <div class="container">
  256. <div class="footer-grid">
  257. <div class="foot-brand">
  258. <img class="brand__logo brand__logo--dark" src="../../assets/img/astrologue-dark.png" width="392" height="89" alt="Astrologue">
  259. <p>An operating system for change — kept for self sufficiency, resilience, and software freedom, so regular people can hold the power of general purpose computers in their own hands.</p>
  260. </div>
  261. <nav aria-label="The four freedoms">
  262. <p class="foot-title">The Four Freedoms</p>
  263. <ol class="freedoms">
  264. <li><strong>Run</strong> the software as you wish, for any purpose.</li>
  265. <li><strong>Study</strong> the source and change it to do your computing as you wish.</li>
  266. <li><strong>Share</strong> copies so you can help others.</li>
  267. <li><strong>Modify</strong> and publish your versions so everyone benefits.</li>
  268. </ol>
  269. </nav>
  270. <nav aria-label="Site">
  271. <p class="foot-title">Site</p>
  272. <ul class="foot-list">
  273. <li><a href="../../">Home</a></li>
  274. <li><a href="../../#news">News</a></li>
  275. <li><a href="../../#download">Download</a></li>
  276. <li><a href="../">Developer</a></li>
  277. </ul>
  278. </nav>
  279. </div>
  280. <p class="colophon">Set in Cinzel and EB Garamond (SIL Open Font License). Astrologue is free software, licensed GPL-3.0-or-later: take it, tend it, pass it on. The libraries are LGPL-3.0-or-later, so they remain free to link.</p>
  281. </div>
  282. </footer>
  283. </body>
  284. </html>