| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316 |
- <!doctype html>
- <html lang="en-nz">
- <head>
- <meta charset="utf-8">
- <meta name="viewport" content="width=device-width, initial-scale=1">
- <title>Spry — Astrologue Developer</title>
- <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.">
- <meta name="color-scheme" content="light dark">
- <meta name="theme-color" content="#f2ebda" media="(prefers-color-scheme: light)">
- <meta name="theme-color" content="#0a0a12" media="(prefers-color-scheme: dark)">
- <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">
- <meta property="og:title" content="Spry — Astrologue Developer">
- <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.">
- <meta property="og:type" content="website">
- <link rel="stylesheet" href="../../assets/css/style.css">
- </head>
- <body>
- <a class="skip-link" href="#main">Skip to content</a>
- <header class="masthead">
- <div class="container masthead__inner">
- <a class="brand" href="../../">
- <img class="brand__logo brand__logo--light" src="../../assets/img/astrologue-light.png" width="392" height="89" alt="Astrologue">
- <img class="brand__logo brand__logo--dark" src="../../assets/img/astrologue-dark.png" width="392" height="89" alt="Astrologue">
- </a>
- <nav class="site-nav" aria-label="Primary">
- <ul class="site-nav__list">
- <li><a href="../../">Home</a></li>
- <li><a href="../../#news">News</a></li>
- <li><a href="../../#download">Download</a></li>
- <li><a href="../" aria-current="page">Developer</a></li>
- <li><a class="nav-cta" href="../../#download">Get Astrologue</a></li>
- </ul>
- </nav>
- </div>
- </header>
- <main id="main">
- <nav class="breadcrumb" aria-label="Breadcrumb">
- <div class="container">
- <ol>
- <li><a href="../../">Astrologue</a></li>
- <li><a href="../">Developer</a></li>
- <li aria-current="page">Spry</li>
- </ol>
- </div>
- </nav>
- <section class="docs-header">
- <div class="container">
- <p class="kicker"><span>Web stack · Users at the door</span></p>
- <h1>Spry</h1>
- <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>
- <dl class="docs-facts">
- <div><dt>Version</dt> <dd><code>0.2</code></dd></div>
- <div><dt>Licence</dt> <dd>LGPL-3.0-or-later</dd></div>
- <div><dt>Package</dt> <dd><code>usm install spry</code></dd></div>
- <div><dt>Language</dt> <dd>Vala</dd></div>
- </dl>
- </div>
- </section>
- <section class="band band--plain" id="docs">
- <div class="container docs-layout">
- <nav class="docs-toc" aria-label="On this page">
- <h2>On this page</h2>
- <ul>
- <li><a href="#overview">Overview</a></li>
- <li><a href="#features">Features</a></li>
- <li><a href="#installation">Installation</a></li>
- <li><a href="#usage">Usage & documentation</a></li>
- <li><a href="#package">Package & source</a></li>
- </ul>
- </nav>
- <div class="docs-prose">
- <header class="section-head" id="overview">
- <p class="kicker"><span>Overview</span></p>
- <h2>Who is asking?</h2>
- </header>
- <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>
- <figure class="code-plate">
- <pre><code>astralis HTTP request handling
- └─ Statum pages, slots/state, directives, client JS
- └─ Spry THIS LIBRARY: users, auth slot, actions, guards
- ├─ Invercargill-Sql spry_users / spry_user_permissions schema
- └─ Inversion module + service wiring</code></pre>
- <figcaption>The stack, from Spry's README.</figcaption>
- </figure>
- <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>
- <figure class="code-plate">
- <pre><code>application.add_module<StatumModule>();
- application.add_module<SpryModule>(); // UserService + schema + migrations
- var statum = application.configure_with<StatumConfigurator>();
- SpryAuth.register_actions(statum); // or hand-pick with statum.action<T>()
- var scope = application.container.create_scope();
- yield SpryAuth.ensure_admin(scope.resolve<UserService>(),
- "admin", "admin@example.com", "change-me");</code></pre>
- <figcaption>From Spry's README — <code>SpryModule</code> registers no endpoints; it wires the migration, entity mappings and the scoped <code>UserService</code>.</figcaption>
- </figure>
- <header class="section-head" id="features">
- <p class="kicker"><span>Features</span></p>
- <h2>What it hands you</h2>
- </header>
- <ul class="docs-features">
- <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>
- <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>
- <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>
- <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>
- <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>
- <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>
- <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>
- </ul>
- <header class="section-head" id="installation">
- <p class="kicker"><span>Installation</span></p>
- <h2>Getting the library</h2>
- </header>
- <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>
- <figure class="code-plate">
- <pre><code>usm install spry</code></pre>
- <figcaption>Installs from the Astrologue package repository.</figcaption>
- </figure>
- <p>From source, the build lives at the repository root:</p>
- <figure class="code-plate">
- <pre><code>git clone <the Spry repository>
- cd Spry
- meson setup . build
- ninja -C build
- ninja -C build install</code></pre>
- <figcaption>The same meson invocation the package's own build script uses.</figcaption>
- </figure>
- <p>Then compile against it with Vala's usual package mechanism:</p>
- <figure class="code-plate">
- <pre><code>valac --pkg spry-0.2 my-app.vala</code></pre>
- <figcaption>The installed <code>spry-0.2.deps</code> resolves the Statum, Astralis, Invercargill-Sql and Inversion bindings for you.</figcaption>
- </figure>
- <header class="section-head" id="usage">
- <p class="kicker"><span>Usage & documentation</span></p>
- <h2>Identity, guards, actions</h2>
- </header>
- <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>
- <h3>The auth slot</h3>
- <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>
- <figure class="code-plate">
- <pre><code>username public signed login name; bind for nav/guards
- display_name public signed forename + surname, falling back to username
- permissions public signed string[] patterns: admin/* match everything
- logout public signed embedded ActionDto for logout buttons
- user_id private signed + authoritative spry_users.id — never
- encrypted reaches the browser</code></pre>
- <figcaption>The <code>auth</code> slot, field by field, from Spry's README.</figcaption>
- </figure>
- <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>
- <h3>Reading identity, guarding handlers</h3>
- <figure class="code-plate">
- <pre><code>public class ProfileEntrypoint : StatumEntrypoint {
- protected UserService users = inject<UserService>();
- public override async DirectiveBuilder handle() throws GLib.Error {
- var guard = yield SpryAuth.require_login(directives(), request, users);
- if (guard != null) {
- return (!)guard; // navigate("/login")
- }
- var me = SpryAuth.current(request);
- if (!me.has_permission("reports.read")) { // admin / users.* wildcards work
- ...
- }
- ...
- }
- }</code></pre>
- <figcaption>From Spry's README — the guard takes the caller's builder and the caller's <code>UserService</code>.</figcaption>
- </figure>
- <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>
- <h3>The shipped actions</h3>
- <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>
- <figure class="code-plate">
- <pre><code>public class LoginAction : StatumAction {
- private UserService users = inject<UserService>();
- /** URI navigated to after a successful login. */
- protected virtual string landing_uri { get { return "/"; } }
- /** Notification shown when the credentials do not match an account. */
- protected virtual string invalid_credentials_message {
- get { return "Invalid username or password"; }
- }
- public override async DirectiveBuilder handle() throws GLib.Error {
- ...
- var user = yield users.authenticate_user(username, password);
- if (user == null) {
- return directives().notify("error", invalid_credentials_message);
- }
- return SpryAuth.login(directives(), (!)user, action_registry)
- .navigate(landing_uri);
- }
- }</code></pre>
- <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>
- </figure>
- <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>
- <figure class="code-plate">
- <pre><code>var target = new Spry.Actions.UserActionPrivate();
- target.user_id = row_user.id;
- row.grant = action_registry
- .author_private<Spry.Actions.GrantPermissionAction,
- Spry.Actions.UserActionPrivate>(target);</code></pre>
- <figcaption>From Spry's README — the id travels in an encrypted blob sealed under the action's own namespace.</figcaption>
- </figure>
- <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>
- <h3>The user store</h3>
- <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>
- <h3>The spry CLI</h3>
- <figure class="code-plate">
- <pre><code>spry new my-app # scaffold an application, packaged for USM
- spry add page # grow it inside marker blocks
- spry add action
- spry add resource
- spry add login # auth UI bound to Spry.Actions
- spry add register
- spry add user-management
- spry keys # maintain the static key pairs
- spry dev # build, run, watch — a failed build keeps the old process
- spry deploy # build the USM container image</code></pre>
- <figcaption>The command surface, from Spry's README — <code>spry --help</code> lists it in full.</figcaption>
- </figure>
- <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><app>-<version>.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>
- <header class="section-head" id="package">
- <p class="kicker"><span>Package & source</span></p>
- <h2>The ledger</h2>
- </header>
- <dl class="docs-package">
- <div><dt>Version</dt><dd><code>0.2</code> (from <code>MANIFEST.usm</code>)</dd></div>
- <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>
- <div><dt>Package</dt><dd><code>usm install spry</code></dd></div>
- <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>
- <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>
- <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>
- </dl>
- <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>
- <nav class="docs-siblings" aria-label="Neighbours in the catalogue">
- <p>Its neighbours:</p>
- <ul>
- <li><a href="../statum/">Statum</a> — the framework it extends</li>
- <li><a href="../invercargill-sql/">Invercargill-Sql</a> and <a href="../invercargill-sql-inversion/">Invercargill-Sql-Inversion</a> — its schema and wiring</li>
- <li><a href="../locksmith/">Locksmith</a> — the stack's cryptography, next in the catalogue</li>
- </ul>
- </nav>
- <nav class="docs-pager" aria-label="Project pages">
- <a class="docs-pager__link docs-pager__link--prev" href="../statum/">
- <span>Previous</span>
- <strong>Statum</strong>
- </a>
- <p class="docs-pager__up"><a href="../">All eleven</a></p>
- <a class="docs-pager__link docs-pager__link--next" href="../locksmith/">
- <span>Next in the catalogue</span>
- <strong>Locksmith</strong>
- </a>
- </nav>
- </div>
- </div>
- </section>
- </main>
- <footer class="site-footer">
- <div class="container">
- <div class="footer-grid">
- <div class="foot-brand">
- <img class="brand__logo brand__logo--dark" src="../../assets/img/astrologue-dark.png" width="392" height="89" alt="Astrologue">
- <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>
- </div>
- <nav aria-label="The four freedoms">
- <p class="foot-title">The Four Freedoms</p>
- <ol class="freedoms">
- <li><strong>Run</strong> the software as you wish, for any purpose.</li>
- <li><strong>Study</strong> the source and change it to do your computing as you wish.</li>
- <li><strong>Share</strong> copies so you can help others.</li>
- <li><strong>Modify</strong> and publish your versions so everyone benefits.</li>
- </ol>
- </nav>
- <nav aria-label="Site">
- <p class="foot-title">Site</p>
- <ul class="foot-list">
- <li><a href="../../">Home</a></li>
- <li><a href="../../#news">News</a></li>
- <li><a href="../../#download">Download</a></li>
- <li><a href="../">Developer</a></li>
- </ul>
- </nav>
- </div>
- <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>
- </div>
- </footer>
- </body>
- </html>
|