In Swift, property wrappers are simply types that are decorated with a special attribute and contain a wrappedValue member. While property wrappers by themselves can be useful, where they really shine is when combined with the tools SwiftUI provides for plumbing them into SwiftUI’s data model.

Composing Property Wrappers

The first step to building useful custom property wrappers is knowing that, like Views, property wrappers can themselves contain more property wrappers.

@propertyWrapper
struct Uppercasing: DynamicProperty {
    @Environment(\.myString) var myString: String

    var wrappedValue: String {
        myString.uppercased()
    }
}

The DynamicProperty protocol serves as a marker for SwiftUI that a conforming type may contain property wrappers which need to be plumbed into SwiftUI’s data model (similar to View itself). The example above works exactly like you’d expect.

The protocol also provides an update method which the documentation says is called “before rendering a view’s body to ensure the view has the most recent value.” This method serves as a useful point for ensuring that both the data you’re vending to the view is up-to-date and that any method for observing external changes is set up.

@propertyWrapper
struct MyObserver: DynamicProperty {
    var index: Int

    @State var wrappedValue: String
    @State private var observer: AnyCancellable?

    init(index: Int) {
        self.wrappedValue = MyManager.shared.values[index]
    }

    func update() {
        observer = MyManager.shared.addObserver(index) {
            wrappedValue = $0
        }
    }
}

The Escape Hatch

You can get pretty far by using the framework’s built-in property wrappers to actually observe data and trigger view updates. But there are plenty of scenarios where you may have some external change that you want to result in a view update too. What you need is some escape hatch to manually say to SwiftUI, “hey, my data has changed and my containing view should be updated.”

The way I most often reach for is by having, within my custom property wrapper, a @StateObject with an “observer” type that encapsulates the observation logic for the property wrapper. Having a single reference type to store state is useful in itself¹, but making it an ObservableObject means that you can trigger a view update just by calling objectWillChange.send().

Another way you can do this without involving Combine is by giving your property wrapper its own @State value that contains some unused data whose only purpose is to be modified when the view needs to be updated. This approach is shown in this blog post by Saagar Jha.

Examples

Finally, here are some examples of actual custom property wrappers I use, both in Tusker and in other projects, in hopes that they can provide some inspiration for ways custom property wrappers can be useful.

@OptionalObservedObject

This one is pretty self-explanatory. SwiftUI’s @ObservedObject property wrapper doesn’t work with optional types. Mine functions exactly like you’d expect: it takes an optional value of a type that implements ObservableObject and, when it has a value, triggers a SwiftUI view update whenever the wrapped object changes.

The need for this one is largely obviated if you can exclusively target OS versions since the advent of @Observable, but it’s still useful if you can’t.

@ProgressObserving

This is a nice simple one. It uses key-value observing to watch a Progress’ fractionCompleted property and update a SwiftUI view whenever it changes. It also takes care of dispatching to the main thread if necessary (since a progress tree may be updated from multiple threads).

@PreferenceObserving

A while back, I spent a bunch of time over-engineering a system for storing Tusker’s user preferences. The details of how it works aren’t germane (perhaps another time), but one important consideration is that all the preferences end up in a big ObservableObject. This means that, while watching the entire preferences object from SwiftUI is trivial, watching only a single preference key is somewhat awkward. This property wrapper encapsulates all that awkwardness, allowing a view to read the current value of a user preference and be updated whenever it changes (but not when irrelevant preferences change). The property wrapper is used by providing a KeyPath from the type of the preferences container object to the preference itself:

struct SomeView: View {
    @PreferenceObserving(\.$statusContentMode) var statusContentMode
    var body: some View { /* ... */ }
}

@EnvironmentOrLocal

SwiftUI’s environment is great for dependency injection, but sometimes you need to override an environment value for just part of a view hierarchy, and trying to get the .environment modifier in the right place would be awkward. This is a cute one for a few reasons:

1. The property wrapper is, itself, an enum. This works because SwiftUI correctly discovers and wires up the Environment associated value in one of the cases.
2. There’s an .environment static member, so that you don’t have to spell out the whole Environment initializer when the type can be inferred (e.g., in a view initializer’s default parameter).
3. Because of the magic of @Observable, nothing needs to be done to make SwiftUI’s dependency tracking work.

@propertyWrapper
enum EnvironmentOrLocal<T: AnyObject & Observable>: DynamicProperty {
    case environment(Environment<T>)
    case local(T)

    static var environment: Self {
        .environment(Environment(T.self))
    }

    var wrappedValue: T {
        get {
            switch self {
            case .environment(let env):
                env.wrappedValue
            case .local(let v):
                v
            }
        }
    }
}

@DraftObserving

This is one of the more complex property wrappers that I’ve written for Tusker. In the app’s Compose screen, in-progress drafts are modeled with a CoreData object. In addition to the draft object itself, there are also several related objects, such as DraftAttachments. Since NSManagedObject conforms to ObservableObject, it’s fairly straightforward to observe a single one. But there are a few places where I need to observe not only the draft, but also the various related objects². This property wrapper takes care of observing all of them and updating a SwiftUI whenever any changes. I won’t get into all the (slightly gnarly) details, but the key idea is that the property wrapper observes the Draft itself and, whenever the draft changes, checks whether any of the related objects have changed, attaching observers to them as well if needed.

@ThreadObserving

Tusker allows composing an entire thread of posts at once and, like there are parts of the UI that may change whenever any aspect of a single draft changes, there are parts that may change whenever any aspect of any draft in the thread changes. This property wrapper is a fairly straightforward composition of many of the observer object that @DraftObserving uses, aggregating their effects together.

@FocusedInputAutocompleteState

This one extends the focused input system I mentioned in my last post, about FocusedValues. One of the focused values used in Tusker’s Compose screen is a representation of the focused text input view itself (i.e., a UITextView). The actual protocol provides a number of properties, including a Combine publisher representing the state of the current autocomplete session (e.g., “inactive” or “mention starting with @sh”). It’s a publisher since its value changes over time and other parts of the UI need to be able to react to it, but the fact that it is makes observing it a little cumbersome.

This property wrapper uses @FocusedValue to get the current autocomplete state publisher and then attaches a subscriber to it. Then, whenever either the focused input changes or the autocomplete state of the current input changes, it triggers a SwiftUI view update.

Here’s the one sentence explainer: the FocusedValues system is like preferences but where the reducer function is “whichever values originates from a focused view wins.”

And if that doesn’t sell you, here’s the pitch for people familiar with AppKit or UIKit: a useful way of thinking about the FocusedValues system is as a strongly typed, generalized version of the responder chain.

Focused values are declared much like environment values. With a key type and a computed property, or the @Entry macro:

extension FocusedValues {
    @Entry var myValue: Int?
}

The main caveat they have is that the property’s type needs to be optional and its default value is always nil.

An actual value for a key is attached to a view using the .focusedValue modifier:

TextField("Username", text: $username)
	.focusedValue(\.myValue, 42)

Whenever the TextField has focus, the value 42 will be written for the myValue key. This doesn’t just apply at the leaf nodes, though: you could attach the .focusedValue modifier to, say, a VStack, and that value would be written whenever any child of the VStack (or any child of their children, etc.) has focus.

Finally, reading a focused value takes place using the @FocusedValue property wrapper:

struct MyView: View {
    @FocusedValue(\.myValue) var myValue: Int?
    var body: some View {
        // some view that contains the TextField above
        let _ = print(myValue) // => Optional(42)
	}
}

As is (hopefully) clear, the API for focused values is fairly straightforward. Next, let’s look at a few ways of using them effectively.

Validate Menu Items

Suppose you have menu commands which are defined at the scene level but whose enabled/disabled state depends on data from the currently edited object in your UI. You could try to hoist all the necessary state up to level where the menu command is added, or you could move into a view model or some other such object to make it easier to share. But better would be to define a focused value representing whether the command is enabled and read that from the commands content.

struct MyCommands: Commands {
    @FocusedValue(\.myCommandEnabled) var myCommandEnabled: Bool?
    var body: some Commands {
        CommandMenu("Editor") {
            Button("Do Something") {
                // ...
            }
            .disabled(myCommandEnabled != true)
        }
    }
}

Literally Like the Responder Chain

Take it one step beyond validating, and put the action itself into a focused value. The type of your focused value doesn’t have to be plain-old-data, it can be more complex. Your focused value could literally be the closure that’s used as the action for a menu item or a button elsewhere in your UI. By doing this, you’re effectively using the focused values system exactly as you would the responder chain.

struct MyCommands: Commands {
    @FocusedValue(\.myAction) var myAction: (() -> Void)?
    var body: some Commands {
        CommandMenu("Editor") {
            Button("Do Something") {
                myAction?()
            }
            .disabled(myAction == nil)
		}
    }
}

Sneakily Access a Platform View

This one’s a little more niche, but I still find it useful. In Tusker’s Compose screen, there are multiple fields in which you can use custom emoji (using :shortcodes:), including the body of the post of course, but also the content warning, as well as any poll options. The Tusker UI includes a button to show the custom emoji picker, for when you can’t remember the shortcode. Implementing this is tricky since it relies on the state of the underlying UIKit text editing controls—namely, the cursor position (that being where a custom emoji should be inserted).

The way I tackle this is by using a focused value which holds a reference to the UITextField/UITextView itself. This requires a little bit of ceremony, but it means that, elsewhere, the UI has access to all the information it needs to make custom emoji autocomplete work smoothly.

The common thread among all of these suggestions is that, as with preferences, you’re using the structure of the graph that SwiftUI manages for you to carry information. The .focusedValue modifier tells you when something inside of it has focus, so take advantage of that rather than trying to convey the same information up the view hierarchy yourself.

A preference is defined by two things: a default value, which is the value used when nothing writes an explicit value, and a reducer function, which defines how multiple values for the same preference at the same level of the view hierarchy are combined. The default value is fairly straightforward, and really depends on what, conceptually, the preference represents, so I won’t spend much time on it here. The reducer, however, is where the nuance lies.

The Reducer Function

When defining a PreferenceKey, one of the requirements of the protocol is the reduce method. Unfortunately, the documentation for the method isn’t great, and there’s one requirement in particular it has that’s not explicitly stated:

It is incorrect to write value = nextValue() as your reducer.

struct BadStringPref: PreferenceKey {
    static var defaultValue: String { "default" }
    static func reduce(value: inout String, nextValue: () -> String) {
        // This is wrong!
        value = nextValue()
    }
}

The reason for this is that, when the reduce method is called, either the current or next value may be the preference’s default value. That means that just naively overwriting the current value with the next one may replace a non-default preference value with the default one. What’s more, the reduce method may be called by SwiftUI even if there is only one explicitly-written preference in your view tree.

Here’s a simple example of a view hierarchy which can produce that result:

Color.red
    .preference(key: BadStringPref.self, value: "non-default")
    .overlay {
        if true {
            Color.green
        }
    }
	.onPreferenceChange(BadStringPref.self) {
        print($0) // => "default"
    }

The presence of the dynamic content (i.e., the if statement) inside the overlay¹ results in the preference’s reduce method being called with a nextValue of the preference’s default. This can also happen with other modifiers, such as toolbar:

Color.red
    .preference(key: BadStringPref.self, value: "non-default")
    .toolbar {
        // Doesn't even need content!
    }
	.onPreferenceChange(BadStringPref.self) {
        print($0) // => "default"
    }

So, how should this be fixed? Well, the reduce method needs to be modified to not return the default value if either the current or next values are non-default.²

More concretely, it depends on the type of the preference value. Optionals are probably the simplest case: the intuitive answer of “use the ?? operator” is correct. If you use value = value ?? nextValue(), then the only way the reduced value can be nil is if both current and next were nil to begin with. For booleans, you can use the logical OR or AND operators depending on whether the default value is false or true, respectively. Beyond that, it’s hard to make prescriptive recommendations since it depends on what the preference conceptually represents. The important part is that you need to take into consideration the current value, rather than always accepting the next value.

Stated more simply: while it’s more obviously wrong to always ignore the next value, it’s also incorrect to always ignore the current value.

Reduce Order

One more note about the reduce method: the docs say that it “receives its values in view-tree order.” But, observationally, this is not always the case³. I think it would be more accurate for the docs to say that the method receives its values in “graph-order” (that is, the order in which the graph nodes representing the individual views are added), which often, but not necessarily always, matches the view-tree order. In any event, it seems prudent to avoid depending heavily on the order in which reduce sees preference values.

Using Preferences Effectively

SwiftUI models your user interface as a graph, with each view and modifier being represented as a node in the graph. The way to get the most out of preferences is, in my experience, by using them to let the graph do work for you. In particular, this means that, instead of trying to build separate mechanisms that pass data up the hierarchy, just use preferences.

ViewThatFits

Suppose you have a design where you want to display two pieces of UI (information, controls, whatever) in one place if they both fit. If they don’t, however, you want to display only one piece of UI there, and move the other control elsewhere (e.g., into a menu). You could accomplish this by using GeometryReader and choosing a breakpoint. But you would have to lift the GeometryReader all the way up the hierarchy to the lowest common ancestor of the primary and secondary locations, which can have other implications for the layout.

Instead, you can use ViewThatFits to decide whether or not to display the secondary control, and use preferences to let the graph do the work of getting the information about which view was chosen to the alternate location for the secondary control.

One caveat with this approach lies in the way that ViewThatFits seems to work—at least as of iOS 18. ViewThatFits tries its children in the order that you specify them. But, while preferences of views after the one that’s selected are not written, the preferences of the views before the one selected (i.e., that are too big to fit) are written. This means that, to get the intended result of knowing which view is actually being displayed, you need to explicitly write a preference value (even if it’s the default value) for each view in the ViewThatFits:

ViewThatFits {
    Color.red
    	.frame(width: 200)
    	.preference(key: IsWide.self, value: true)

    Color.blue
    	.preference(key: IsWide.self, value: false)
}

Notably, in the circumstances where, in the example above, the blue view is shown, the preference key’s reduce method is not invoked. This suggests to me that SwiftUI is taking into account the preferences written by ViewThatFits children to some degree, since the reducer would be called if two views were inside a different container.⁴

Data Validation

Here’s a more concrete example. In Tusker, the Compose screen lets you author a thread of multiple posts together, before posting them all at once. Managing the state of this UI is a little complicated, because a thread can consist of an arbitrary number of draft posts, any one of which the user may be editing. While there are parts of the UI that only rely on the state of an individual draft, there are other parts (such as the “Post” button) that need to track the state of the entire thread. You might see where I’m going with this.

The view that’s responsible for editing an individual draft writes a preference whose value is whether or not that particular draft is valid (not exceeding the character limit, etc.)⁵. The preference’s reducer function is the logical AND operator, and so when views higher in the hierarchy read the preference, SwiftUI has taken care of combining the individual drafts’ validities into a single value representing the state of the thread as a whole.

If you want to take a look at how this actually works in practice (it’s simpler than you might expect), the code is public.⁶

This approach has the useful result that views that care about the validity of the entire thread do not need to somehow observe the state of a bunch of separate objects. The view layer’s observation of the model layer takes place at the natural granularity that emerges from the structure of the data. This is the crux of what I mean about letting SwiftUI’s graph do work for you. Primitives like ForEach influence the shape of the graph, which is something you can take advantage of.

I don’t think what you dislike about programming for a living is necessarily that you spend all day touching computers. I’ve seen burnout described as being a result of a disconnect between what you’re actually doing—day to day, hour to hour—and the aspect of your job that you feel is important and that you want to be doing. If you’re building a coffee table with your own two hands it’s harder to be disconnected from your work than if you’re spending all day developing a headache trying to explain why introducing a second, parallel onboarding flow for a small subset of users will only precipitate further headaches down the road.

I’ve also spent a lot of time thinking about “AI” lately. Not so much because I want to, but because its looming presence casts a pall over the entire field of programming. Certain segments of the industry are so bent on making fetch happen that thinking about it is simply inescapable.

Predictions about how AI will impact software development run the gamut from, at one extreme, “in five years, literally nobody will be writing code” to “LLMs will be treated as any other tool, like autocomplete” and, at the other extreme, “the software industry will have given up the pretense that AI-assisted software development provides any value.”

For my part, I land somewhere in the middle: while I have yet to have a truly positive experience with LLM-aided programming (admittedly, that’s mostly for a lack of trying—the reasons for which I’ll get to later), the technology does seem like it could produce useful results.

But, that said, I think we need to be clear that there are actually two separate axes here: how capital treats “AI” and what it actually is. I would like to live in a world where we don’t have to worry about the distinction. Unfortunately, this is not that world.

The way large language models are currently pitched is, fundamentally, a form of labor arbitrage. LLM tools are force multipliers. Everyone can be a 10× engineer with help from AI. A solo founder can crank out an entire MVP in a weekend. You have a new superpower. Go at it alone. Pay no attention to the unfathomable extent of the uncompensated-for labor behind the single most comprehensive work that humankind has ever produced. Substitute mere access to capital for the sum total of human effort required to produce Everything.

To a first approximation, all of the furniture bought and sold these days is mass-produced. It doesn’t need to be particularly fancy or especially well-made. Being mass-produced and therefore widely available without being exorbitantly expensive is enough to succeed. I make no value judgement about that, it’s just the fact of the matter. Just as LLM maximalists want access to capital to displace knowledge work, access to capital (in the form of economies of scale) has killed the furniture trade.

Or has it? Like I said, I’ve been watching a lot of woodworking YouTube lately.

The artisinal furniture craft is still… alive. It would probably be an overstatement to say it still thrives. But it does live, on the efforts of people who pay more for furniture because they care about it, on the efforts of people who work slower and with more deliberation at the expense of greater profits. It lives, fundamentally, because of people who care about the craft.

I said that I haven’t really made an effort to use LLM-based tools. There are two kinds of programming I do—work and not-work—and that is the case for both.

For work, I am in the fortunate position to not be in the sort of environment where output is valued above all else. I can work in the way that, well, works for me. And the way that works for me does not involve such tools. That’s not to say that using those kinds of tools couldn’t also work for me. But, right now, it doesn’t need to, and I have no particular desire to find out whether it does. There are things to be said about tying your career to your passions, but, for better or for worse, that’s where I am. I don’t need to use LLM tools to get my work done, and I care about how I get my work done, so I don’t use them. For not-work, it’s even simpler. I enjoy programming, and I don’t want to use tools that take that away from me.

I’m sorry to be the sort of person who’s going to make everything about class. But it only takes the slightest bit of class consciousness to see what’s happening, and where the industry is headed. To feel the glee with which the petite bourgeoisie imagine firing 90% of their workforce. To hear the loathing for labor dripping from Sam Altman’s voice when he speaks of impending job losses. To see the zeal with which technology giants impose layoffs and simultaneously bloviate about how AI will massively increase worker productivity.

So, after all of that, here is where I land:

I believe that people will continue to have the skills that capital claims AI will subsume. That I will continue to have those skills. That both of those will continue to be the case even as the labor market for software engineers contracts. I have to believe—I have to hope—because there is no other option. To be a pessimist is to cede your agency. I will not. The world is what we make of it and the world I want to make is one in which human labor is not entirely displaced by capital.

Even beyond that, I know that I care about building software and about making it good and about sweating the details. If there is no one left in the world programming for the sake of programming, it will be because I am dead. I will continue to care about the craft. Capital cannot take that away from me.

Redesign

I don’t really know what my design process is. This time, I spent ages trawling through hundreds of other people’s personal blogs and websites trying to find anything that I liked, hoping that something cohesive would eventually emerge. It ultimately did, though I have no idea wherefrom.

Typography

The body text is set in Valkyrie by Matthew Butterick, and the code is set in MD IO by Mass Driver. Valkyrie is a font that I’ve had my eye on for a while, since reading Butterick’s Practical Typography. In the old design, I deliberately chose to use a system font (Charter) to avoid the (over-the-wire byte) cost of shipping an entire font. This time, though, I put quite a lot of work into the backend static-site-generator in part so that I could ship subset fonts without a lot of manual work.

It took me a while to settle on MD IO since it’s not one of my usual monospace fonts. But I’m quite happy with it ultimately. It looks nice with Valkyrie when used inline, and looks good in bigger blocks of code. It also has a nice italic style, which is important to me since comments in syntax-highlighted code blocks are italicized. I’m very pleased with how the font choices turned out, I think they both look great—especially on high-DPI displays¹.

Markdown Decorations

One of the more notable touches from the old design was the use of CSS pseudo-elements to render inline Markdown decorations (i.e., underscores around italicized text, making links appear like [hello](example.com), etc.). I still quite like that touch, but after five and a half years, it’s time to move on. No more Markdown decorations—but maybe they’ll come back in a future redesign.

Sidenotes

One of the side effects of having the content be width-constrained and left-aligned is that I have this big column of empty space on the right to play with. The previous design already used floating asides on wide enough screens, and I wanted to extend that to footnotes as well. I’m the type of person who reads all the footnotes, and having to jump to the end back is somewhat jarring—even if there are backlinks, I often visually lose my place just from the viewport changing. So, sidenotes it is.

I embarked on an exhaustive survey of someone else’s exhaustive survey of existing web libraries for creating sidenotes. Unfortunately, just about all of the options either had limitations that I wasn’t willing to accept (e.g., not supporting sidenotes that are numbered like footnotes) or were entirely reliant on JavaScript.

The solution that I arrived at is a custom combination of some backend processing in the static site generator and a bunch of CSS. When footnotes in Markdown are being converted to HTML, the reference to and the contents of every footnote is output twice: first immediately following the footnote reference in an inline <span> element, and then again in the footnotes section at the end. Having the sidenote definition inline immediately after the reference lets me do two things with CSS alone:

1. Align the sidenote to exactly where it’s referenced in the content.
2. Highlight the sidenote when the corresponding reference is hovered.

The second set of definitions are at the end, and are only shown when the screen is viewport is narrow enough for the sidenotes not to fit. Lastly, the two sets of references exist because—although the text of the links is the same—the destinations are different: one jumps to the footnotes section at the end of the page, the other to the sidenote. Which reference is shown is also swapped out using CSS, this time producing a purely functional change since they’re visually identical.

Color Schemes

For a couple reasons, there’s no longer a dark theme. What you see now is what there is. The first reason is that I’ve never particularly enjoyed light text on a dark background for reading—I always preferred the light theme of my old design. The second is that, since the page background is now a nice off-white, I found no satisfying way of incorporating that into a dark theme.

The Graph

The impetus for rewriting the backend of my blog can be summed up in one word: graph. Specifically, a dependency graph.

I should back up first. When building the backends for the last couple versions of my blog, I’ve done things pretty much the same way: write a bunch of code that reads files and outputs more files. Less a cohesive piece of software, and more of a script. No real consideration was made for incremental compilation or watching files for changes. At various times, this was handled by separate tools and by just watching the entire content directory for changes and rebuilding the whole site. This did work, but it was less than ideal—both because it bothers the perfectionist in me and because regeneration gets inexorably slower as the blog grows.

So, the path I went down was building the entire static site generator around a giant directed, acyclic graph. Each node in the grah is a unit of computation that produces an output value from the values of some input nodes (or inputs external to the graph, like the filesystem). Powering this monstrosity elegant architecture is a Rust crate I wrote called compute_graph which abstracts away dealing with the actual graph and lets you just write code for each of the nodes.

Actually generating the site, then, is effectively just (“just”) topologically sorting the graph and evaluating each node in order. From there, it’s not terribly complicated to track which files are read during the process and, when the filesystem watcher detects a change, invalidate just the nodes that read that file and let the graph evaluation take care of the rest. Because the graph also prevents invalidations from propagating downstream when a node’s value doesn’t change, partial updates can be much more efficient than just regenerating things willy-nilly (e.g., editing the excerpt of a blog post will regenerate both the post page and the homepage, but editing not-the-excerpt won’t regenerate the homepage).

One of the more interesting details of the graph abstraction is that the output value of a node can, itself, be more graph nodes. This means that part of the process of graph evaluation is going back, making sure all the edges are established, then redoing the topological sort and starting the evaluation again.

And, for fun, here’s a diagram of the entire dependency graph—all 977 nodes—of the website as of writing this (you really do want to be in a browser for this, it likely won’t work in your RSS reader):

Font Subsetting

Font subsetting is one of the big features that the whole graph abstraction enables. Subsetting is the process of creating a new font that contains only a subset of the characters/glyphs that the original font has. The simplest way to do this would be do determine what character set you’re interested in based on the language the content is written in, and generate a subset font for that.

If the entire site is typeset in just one style of one font, that process would work fine. But are you also using all of those characters in the bold style of the font? The bold italic one? The monospace bold italic one²? Probably not.

So here’s where the big dependency graph comes in: every node that writes an HTML file to disk also outputs the HTML as a string that’s used by further nodes to extract the set of distinct characters used from each font style. This process involves parsing the HTML, walking the tree while keeping track of the current font state (to handle nesting), and accumulating the set of characters. The character sets from each file are merged and then those are inputs to the node responsible for actually subsetting the font. Subsetting is performed by pyftsubset from the fontTools project³ which is run directly from Rust using PyO3. Finally, the subset fonts are Base 64 encoded and embedded in the compiled CSS.

The graph is very useful for this whole thing because it means that everything that needs to be regenerated is whenever necessary, and only when necessary (i.e., editing content in a way that doesn’t add new characters to the fonts doesn’t re-subset them), without having to write a bunch of code to explicitly keep track of all that information.

ActivityPub

One of the major features of version 5 was making my blog a first-class ActivityPub citizen. This meant you could follow my blog from Mastodon (& co.) and leave comments by replying. This was a cool feature, but I’ve made the decision to leave it behind this time. It was too great of a code/maintenance burden for too few users. While it didn’t break too often, it accounted for the majority of the code in v6 and made deployment somewhat more complicated, since it wasn’t just a static site—which now it is.

I haven’t entirely abandoned fediverse integration though: now you can comment on blog posts by replying via ActivityPub to a post from my personal account. I think this is a good middle ground: it’s effectively delegating all the ActivityPub responsibility to Akkoma, which is actually built for that purpose first and foremost—rather than my hodgepodge—and simply fetching them from the client side. I was also already posting links to blog posts, and almost all of the responses I’d get are directly to that.

We are too eager to look for a way out of a hard situation, too eager to just do the easy thing, too happy to cast out of our minds what does not directly affect us (or what we want to believe will not directly affect us).

See, for example:

1. The Fourth Estate rolling over when faced with a protection racket.
2. Hospitals abandoning caring for trans and pregnant patients.
3. Too much of legal academia being willing to carry water for abhorrent positions (e.g., the birth and slow mainstreaming of the atextual and ahistorical opposition to birthright citizenship).
4. The Harris campaign being unwilling to shift from Biden on any major issues.
5. Merrick Garland preserving norms at the Justice Department.
6. Democrats in general continuing to try and do politics as normal.

This is not an exhaustive list; you could surely add more.

Take just one of those, for example. If you were to get in a room with the executives at Paramount contemplating settling Trump’s 60 Minutes lawsuit, and wave a magic wand to get them to bare their souls—or if some alien could examine their innermost thoughts—I think that they would profess their belief that a free and independent press is integral to a well-functioning society. It is such a core part of the American mythos that there is little doubt in my mind that those Paramount executives do not think they believe it is the case.

But, I would posit that to believe something is to act in accordance with it. A professed belief with which you do not act in accordance is not something you actually believe.

The Electric Monk was a labour-saving device, like a dishwasher or a video recorder. Dishwashers washed tedious dishes for you, thus saving you the bother of washing them yourself, video recorders watched tedious television for you, thus saving you the bother of looking at it yourself; Electric Monks believed things for you, thus saving you what was becoming an increasingly onerous task, that of believing all the things the world expected you to believe.

— Douglas Adams, Dirk Gently’s Holistic Detective Agency

I believe that there are right things and that there are wrong things. And I fervently believe it is incumbent upon each of us to do what we believe is right, even when (or, perhaps, especially when) doing so comes at a personal cost. I only wish that I knew how to instill those values into a culture.

Inextricably bound up in all this is the notion that conservatives are unreachable because “I don’t know how to explain to you that you should care about other people”. Caring about what happens to other people has the necessary condition of believing that there are right things and wrong things. If you do not believe that, then all that matters—and all that can matter—is whether something that happens is good for you or bad for you.

For example: conservatives not caring about abortion until someone close to them needs one. If you do not believe that there are right things and wrong things—if you do not believe that pregnant women dying of sepsis in hospital parking lots is a wrong thing, then until the pregnant woman dying of sepsis in a hospital parking lot is your wife or your daughter, it simply does not matter.

Furthermore, if belief lies in the acts, then the hostility towards and dismantling of the social safety net is a deliberate to make it harder to act in accordance with your beliefs and to make it harder to believe.

Nonetheless, I need you to believe that there are right things and that there are wrong things.

More precisely, what I mean by the title of this post is that the lifetime of a struct that conforms to View is unmoored from that of the conceptual thing representing a piece of your user interface.

This comes up on social media with some regularity. Every few months there’ll be questions about (either directly, or in the form of questions that boil down to) why some view’s initializer is being called more than expected. One particularly common case is people migrating from Combine/ObservableObject to the iOS 17+ @Observable.

If you were not paying attention to SwiftUI in the early days, or have only started learning it more recently, there are some important details about the nature of the framework you might have missed. One of the things the SwiftUI engineers emphasized when it was announced was that the body property can be called at any time by the framework and may be called as often as the framework likes. What follows from this—that’s not entirely obvious or always explicitly stated—is that View initializers run with the same frequency. Consider the minimal possible case:

struct MyParentView: View {
    var body: some View {
        MyChildView()
    }
}

Evaluating MyParentView’s body necessarily means running the initializer for MyChildView. SwiftUI does a lot of work to make things feel magical, but, at the end of the day, the code that you’re writing is ultimately actually running. So, the initializer runs.

After that happens, SwiftUI can compare the new and old values of MyChildView to decide whether it’s changed and, in turn, whether to read its body. But, by the time the framework is making that decision, the initializer has already been run.

An Autoclosure Corollary

It follows, I argue, from the reasons given above that it is a poor API design choice for SwiftUI property wrappers to use @autoclosure parameters in the wrapped value initializer.

An entirely reasonable principle of API design is that you should hide unnecessary complexity from consumers of your API. There is, however, a very fine line between hiding unnecessary complexity and obscuring necessary complexity—or worse, being actively misleading about what’s happening. I think @StateObject and its autoclosure initializer tread too close to that line.

The use of an autoclosure hides the fact that the property wrapper itself is getting initialized frequently—just like the view that contains it (initializing the view necessarily means initializing all of its properties—i.e., the property wrappers themselves). If your API design is such that you can very easily write two pieces code that, on the surface, look almost identical but have dramatically different performance characteristics, then it hinders (especially inexperienced) developers’ understanding.

@StateObject var model = MyViewModel()
// vs.
@State var model = MyViewModel()

That the name StateObject conflates the behavior with State certainly doesn’t help either.

Some Recommendations

Not realizing that view initializers—not just the body property—are in the hot path can quickly get you into hot water, particularly if you’re doing any expensive work or are trying to use RAII¹ with a value in a view property. So, what follows are some general recommendations for avoiding those issues that are as close to universally correct as I’m willing to claim in writing.

No Expensive Work in Inits

This is a simple one. As discussed earlier, this is equivalent to doing that same expensive work in a view’s body property. But SwiftUI calls both of those at arbitrary times with arbitrary frequency. Doing expensive work in either place will quickly cause performance issues.

Ignore View Lifetimes

Even more generally, you should ignore the lifetime of your View structs altogether. “When is my view initialized? Who knows, I don’t care!” Even if, at some point during development, you find that a particular view’s initializer is called at a useful time, avoid depending on that, even if the work you need to do is cheap. While, right now, you might have a good handle on a particular View’s lifetime, it’s very easy to inadvertently change that in the future, either by introducing additional dependencies in the view’s parent, due to changes to the view’s identity, or due to entirely framework-internal changes.

Note that this is a particularly important idea and is worth hammering home: a View’s initializer is called as part of its parent’s body. This is particularly prone to action at a distance: seemingly-unrelated changes at the callsite where a view is used (or beyond) can dramatically change how often that view is initialized.

Use Lifecycle Modifiers

The @State docs call this out with regard to Observable, but it’s true in general. Rather than putting expensive objects as the wrapped value of a @State property wrapper, use SwiftUI’s lifecycle modifiers like .onAppear or .task to construct them.

What’s more, if you need to do any one-time setup work—even inexpensive—related to a particular instance of a conceptual view, the lifecycle modifiers are the way to go. They abstract you away from the particularities of the lifetime of the struct instance itself.

The root of all this complexity is the fact that I’m essentially trying to replicate a portion of the CSS layout algorithm using only the information provided by the HTML tokenization process (that is, the text that is emitted and the start/end tags) while flattening into a single string all the structure used to achieve those results.

The previous version of this—which did correctly handle the initial test cases that I threw at it, but not what cropped up in the wild—worked by trying to keep track of when you had just finished one block element and then, before starting a new one, emitting line breaks to approximate the spacing between them that would otherwise be specified by CSS. Here are an assortment of issues that arise when using this strategy with real input:

Blocks can start after a closing non-block element

<span>a</span><p>b</p>

This should render equivalent to two blocks, the first containing “a” and the second containing “b”.

Blocks can start immediately after a character

a<p>b</p>

This should render the same as the example above.

Whitespace between blocks should be ignored

That is, this:

<p>a</p><p>b</p>

should render equivalent to this:

<p>a</p>
<p>b</p>

which in turn should render equivalent to this:

<p>a</p>



<p>b</p>

So you need to keep track of the whitespace that was emitted between two block elements, and not emit any extra—or possibly remove some.

Whitespace within blocks should not be ignored

But you can’t ignore whitespace (or even just newlines) altogether, because there is content that expects newlines to be preserved. And, moreover, people will do things like writing code—where they expect whitespace to be preserved—outside of a <pre> context.

Empty block elements shouldn’t take up space

<p>a</p>
<p></p>
<p>b</p>

This should render equivalently to the examples above with two <div>s, since the emtpy tag shouldn’t consume any space. Additionally, other empty elements inside that middle <div> shouldn’t cause it to start consuming space either.

A line break tag at the end of a block should be ignored

So while this example should appear to have three line breaks between “a” and “b”:

<p>a</p>
<p><br>b</p>

this next example should only appear to have two:

<p>a<br></p>
<p>b</p>

But a line break tag at the beginning of a block should take up space

This example should have about three lines worth of space between “a” and “b”. One for the space between “a” and the middle paragraph, one for the <br> content of the middle paragraph, and one for the space between the middle paragraph and “b”.

<p>a</p>
<p><br></p>
<p>b</p>

Actual newline characters should be ignored at the beginning and end of blocks

So all three of these paragraphs are equivalent:

<p>a</p>
<p>a
</p>
<p>
a</p>

Leading whitespace in <pre> is ignored

Presumably because, when authoring HTML, you’re expected to write the opening tag on one line and then start your content on the next.

Observationally, this also appears to be the case for whitespace preceding </pre>, but the HTML spec is silent on the matter.

List items are like blocks but with only one linebreak

In this case, there should be no blank lines between “a” and “b”:

<ul>
    <li>a</li>
    <li>b</li>
</ul>

Blocks in <li> should not produce line breaks at the beginning/end of the list item

It’s perfectly okay to have block elements inside list items, but the following should render the same as the previous example:

<ul>
    <li><p>a</p></li>
    <li><p>b</p></li>
</ul>

But two blocks within the same <li> should have a blank line separating them

<ul>
    <li><p>a</p><p>b</p></li>
</ul>

Okay, I’m going insane. How do you fix it?

After trying to make my initial approach work for some time, while slowly discovering more and more of these edge cases, I gave up. Armed with the intuition that this feels like the sort of problem that should be tractable with a sufficiently complicated state machine, I spent a number of days drawing, abandoning, and redrawing diagrams in Freeform trying to cover all the inputs and properties I needed.

In addition to everything described above, the final version also covers a couple additional things such as nested <pre> tags (because why not) and removing (or preventing from being generated) leading/trailing whitespace from the output string.

With the diagram converted to code (and several intervening iterations of noticing issues and revising the diagram), I am left with a gnarly 600 lines of Swift consisting of 7 giant switch statements, each of which matches over the 20 distinct states of the machine.

The code by itself is nigh-impossible to reason about, which is why it bears the warning “This is not a place of honor. No highly esteeme—” er. I mean, which is why it bears the exhortation:

// DO NOT TOUCH THE CODE WITHOUT CHECKING/UPDATING THE DIAGRAM.

Speaking of the diagram: in an effort to preserve the sanity of future-me, I turned my chicken-scratch drawing into a GraphViz file that I could stick in version control. Here’s the rendered graph, in all its splendor (please write in with suggestions about how to make this not look like GraphViz is questioning its life choices):

Conclusion

In writing this blog post I ran into 1 2 more edge cases that I had not handled correctly.

While I don’t regret rewriting the HTML parsing/conversion code I had before, it does feel rather like having opened Pandora’s box.

And back to what I alluded to at the beginning, all this extra bookkeeping means the end-to-end HTML → attributed string conversion performance is now merely 2.3× faster than the old SwiftSoup-based implemention (as opposed to 2.7× faster before this whole state machine adventure).

And while that technique worked perfectly well, there were a number of downsides that I wasn’t entirely satisfied with. First: SwiftSoup alone is a big dependency, at around ten thousand lines of code. Since it’s shipping in my app, I take the view that I’m responsible for making sure it doesn’t break—and that’s a lot of surface area to cover (moreover, since it was ported from a Java library, the code is extremely un-Swift-y). Second: it’s not especially fast. Partly because of its aforementioned nature as a Java port (everything is a class, lots of unnecessary copies), but primarily because it’s just doing more than I need it to (the first rule of optimization is do less work): it was parsing a string into a tree and then I was flattening that tree back into a string.

The last time I needed to do something similar, I used lol-html, Cloudflare’s streaming HTML rewriter. But, while that worked (and is still in use for my RSS reader app), it’s written in Rust, and I didn’t want to introduce significant additional complexity to the build process for Tusker. So, writing a new HTML parser in Swift seemed like a great idea.

The Architecture

Parsing HTML is no small task, and the spec stands at some 42 thousand words. Fortunately, I get to ignore about half of that. Parsing HTML is divided into two primary stages: tokenizing and tree construction. The tokenization stage takes the character stream as input and produces a stream of tokens (text characters, comments, start/end tags, etc.). The tree construction stages then uses the token stream to build up the actual DOM tree. The main way I’m improving over SwiftSoup in terms of not doing unnecessary work is by skipping tree construction altogether.

This is based on lol-html’s architecture, which usually uses a simulated tree construction stage (because the tokenizer gets feedback from the tree constructor and may have its state altered based on the current position in the tree) and only switches to the slower, real one when necessary. In my case, though, I don’t even simulate tree construction, since everything I want from the output can be generated directly from the token stream.

This does mean that in certain circumstances the output of the tokenizer could be incorrect, but that’s not a problem for my use case. For Tusker, I’m only ever going to use it to parse fragments—not whole documents—and the Mastodon backend sanitizes incoming HTML. What’s more, from what I can tell of lol-html’s simulator, most of the cases where (without the tree construction stage) ambiguity arises or feedback is needed aren’t going to come up in my use case. They involve other tag namespaces (SVG, MathML), or things like <template> tags—both of which I’m comfortable with handling incorrectly.

Tokenizing

The tokenizer is the single biggest component of this project, weighing in at about 1500 lines of code. Fortunately though, the spec is quite clear. It describes in exacting detail the state machine that a spec-compliant tokenizer needs to mimic. To make things simple, all of my code is an almost one-for-one translation of the spec into Swift. There are a few places where I diverged, mostly in the name of performance, but where I didn’t, the code is quite easy to follow.

Attributed Strings

Converting the token stream to an NSAttributedString is somewhat more complicated, but not terribly so. The gist of it is that the converter tracks what the style of the string should be at the current point in the token stream. Then, when a text character arrives from the tokenizer, it’s added to a buffer representing characters for which the current styles apply (called a “run”). When an open/close tag token is emitted, the current style is adjusted. After the current styles change, the current run is finished and an attributed string is built for the current text and styles and is appended to the overall string.

Optimization

Named Character References

The spec requires HTML tokenizers to have some special handling for named character references (things like &) which aren’t well-formed (e.g., missing the trailing semicolon). Because I was sticking very closely to the spec, this was originally implemented rather inefficiently: when a named character reference began, it would consume further characters one by one while there were any named character references beginning with the accumulated characters. I was just using a regular Swift dictionary to store all of the valid character references, so this was effectively an O(n) operation for each character in the reference.

That is, to put it mildly, ridiculously inefficient. Instead, the new approach just consumes as many alphanumeric characters as possible until it hits a semicolon. Then, if there’s no valid character reference, it backs up character by character until it finds a valid reference. This optimizes for the common case of a properly-formed reference, but (as far as I can tell) preserves the error-handling behavior that the spec requires.

Static Dispatch

The way I implemented the tokenizer, there’s a separate method that follows the procedure for each state, each of which returns the next token. The tokenizer itself is also an Iterator that yields tokens. The Iterator.next implementation just switches over the current state and dispatches to the correct method.

It’s fairly common for the procedure for tokenizing to involve switching to a different state. Originally, I did this by changing the state and then calling next(). One small optimization I made relatively early was, in instances where the new state is constant, replacing the next() call with a direct call to the appropriate method for the new state—effectively statically dispatching whenever the state changes.

state = .tagName
return next()
// vs.
state = .tagName
return tokenizeTagName()

UI/NSFont Caching

A number of the tags handled by the attributed string converter alter the current font. Originally, I implemented this by looking at the currently-applied styles and using them to assemble a SymbolicTraits that could be passed to UIFontDescriptor.withSymbolicTraits on the base font descriptor. When profiling, though, I found a non-trivial amount of time was being spent inside withSymbolicTraits to look up the actual font that should be used. So, the converter instead caches the known styles and their corresponding font objects.

Using Swift.Array

One of the first optimizations I’d implemented was a type called InlineArray3 which was a collection type that stored up to three elements inline. Growing beyond that would cause it to switch to a regular Swift array, the storage for which is out of line. The motivation for this was the fact that the vast majority of the HTML tags that the parser sees will have very few attributes, so you might be able to gain a little bit of performance by storing them inline.

After implementing a simple performance testing harness (discussed later), I went back and tested this, and it turned out that just using Array was a fair bit faster. Just goes to show that you shouldn’t try to optimize things without having concrete data.

Looping in Hot Recursive Functions

For a number of states in the tokenizer (such as while tokenizing a tag name), the state machines stays in the same state for multiple iterations before emitting a token. Initially, I implemented this just by having the tokenization function recursively call itself. One small but measurable performance improvement I got came from turning hot recursive paths into loops. So, rather than the function calling itself recursively, the entire function body would be wrapped in an infinite loop and the “recursive call” would simply continue on to the next loop iteration.

This was one of the more surprising optimizations I made, since I’d expected this to make no difference. Given tail-call optimization, I’d think both approaches would generate basically identical code. And indeed, looking at the disassembly before and after this change seems to confirm that. There are differences, and though they seem very minor, I guess they’re enough to make a difference (though a very, very small one—only about 5ms over 10k iterations).

Avoiding Enums with Associated Values

Lots of states of the tokenizer involve building up the current token until it’s ready to emit. This means the parser needs to store the in-progress token. My Token data type is a Swift enum with a handful of different cases. So, the natural way of representing the current token was as an instance variable of an optional Token. Modifying the current token means, then, pattern matching against a Token and then constructing the updated Token and assigning it back.

Unfortunately, this does not permit in-place modification, meaning that all of the enum’s associated values need to be copied. For primitive types, this might not be a problem. But for more complex types, like arrays and strings, this results in a bunch of extra copies. So, rather than having a single currentToken property, there are separate properties representing the data for each possible token—each of which can be modified in-place:

private var currentToken: Token?
// vs.
private var currentStartTag: (String, selfClosing: Bool, attributes: [Attribute])?
private var currentEndTag: String?
// etc.

Using Unicode.Scalar instead of Character

My tokenizer originally operated on a stream of Swift Characters, which represent extended grapheme clusters. The tokenizer, however, only cares about individual Unicode code points—and indeed is specified to operate on code points. So, I changed the tokenizer to operate on the Unicode.Scalar type. This resulted in a significant speed-up, since the there was no longer any time being spent on the grapheme breaking algorithm.

Grouping Character Tokens

When emitting the document text, the tokenizer is specified to emit individual characters. As an optimization, though, I introduced an additional token type which emits a whole string of characters in one go. Since long, uninterrupted runs of characters that don’t require further parsing are quite common in actual HTML documents, this eliminates a bunch of the overhead associated with handling a token that comes from switching back and forth between the tokenizer and whatever’s consuming the tokens (that overhead is amortized over the sequence of character tokens).

Conclusion

To both test the final performance of the new end-to-end HTML to NSAttributedString conversion process as well as guide most of the optimizations I described above, I wrote a small benchmarking harness that converts the HTML from the last ten thousand posts on my timeline to attributed strings using the old and new methods. This is basically the exact use case I have for this project, so I’m confident that the benchmarking results are fairly representative.

All told, the new process is about 2.7× faster when both are built in release mode, and a whopping 8× faster in debug (not terribly important, but nice for me since a debug build is often what’s on my phone).

I’m very happy with how this project turned out. I greatly enjoyed overengineering/optimizing something fairly self-contained, and the end result meets all of the goals/requirements I had for my use case. If you’re curious to see how it works in more detail, check out the source code.

This work is heavily based on this article by Adam Langley, which provides a great deal of information about implementing passkeys. My goal here is to fill in some more of the details, and provide some Elixir-specific information. As with Adam’s article, I’m not going to use any WebAuthn libraries (even though that may be advisable from a security/maintenance perspective) since I think it’s interesting and helpful to understand how things actually work.

Providing an exhaustive, production-ready implementation is a non-goal of this post. I’m going to make some slightly odd decisions for pedagogical reasons, and leave some things incomplete. That said, I’ll try to note when I’m doing so.

To start, I’m using the default Phoenix template app (less Tailwind) in which I’ve also generated the default, controller-based authentication system. Some parts of the password-specific stuff have been stripped out altogether, others will get changed to fit with the passkey authentication setup we’re going to build.

Database schema

The first thing we’ll need is a backend schema for passkeys. The only data we need to store for a particular passkey is a unique identifier, and the public key itself. We also want users to be able to have multiple passkeys associated with their account (since they may want to login from multiple platforms that don’t cross-sync passkeys), so the users schema will have a one-to-many relationship with the passkeys.

The actual model I’ll call UserCredential, since that’s closer to what the WebAuthn spec calls them. Here’s the schema, it’s pretty simple:

defmodule PhoenixPasskeys.Accounts.UserCredential do
  use Ecto.Schema
  import Ecto.Changeset

  @primary_key {:id, :binary, []}

  schema "users_credentials" do
    # DER-encoded Subject Public Key Info: https://datatracker.ietf.org/doc/html/rfc5280#section-4.1.2.7
    field :public_key_spki, :binary
    belongs_to :user, PhoenixPasskeys.Accounts.User
    timestamps()
  end

  def changeset(credential, attrs) do
    credential
    |> cast(attrs, [:id, :public_key_spki, :user_id])
  end
end

There are a couple things to note here:

1. First, we’re explicitly specifying that the primary key is a binary, since that’s what the WebAuthn API provides as the credential ID.
2. The public_key_spki field contains the data for the public key itself and the algorithm being used. We don’t care about the specific format, though, since we don’t have to parse it ourselves.

To the generated User schema, I also added the has_many side of the relationship. There’s also a migration to create the credentials table. I won’t show it here, since it’s exactly what you’d expect—just make sure the id column is a binary.

Registration JavaScript

WebAuthn, being a modern web API, is a JavaScript API. This is a distinct disadvantage, if your users expect to be able to login from JavaScript-less browsers. Nonetheless, we proceed with the JS. Here’s the first bit:

document.addEventListener("DOMContentLoaded", () => {
    const registrationForm = document.getElementById("registration-form");
    if (registrationForm) {
        registrationForm.addEventListener("submit", (event) => {
            event.preventDefault();
            registerWebAuthnAccount(registrationForm);
        });
    }
});

If we find the registration <form> element (note that I’ve added an ID (and also removed the password field)), we add a submit listener to it which prevents the form submission and instead calls the registerWebAuthnAccount function we’ll create next.

Before we get there, we’ll also write a brief helper function to check whether passkeys are actually available:

async function supportsPasskeys() {
    if (!window.PublicKeyCredential || !PublicKeyCredential.isConditionalMediationAvailable) {
		return false;
	}
	const [conditional, userVerifiying] = await Promise.all([
		PublicKeyCredential.isConditionalMediationAvailable(),
		PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable(),
	]);
	return conditional && userVerifiying;
}

The conditional mediation check establishes that WebAuthn conditional UI is available. This is what we’ll use for login, and is part of what makes using passkeys a nice, slick experience. Conditional UI will let us start a request for a passkey that doesn’t present anything until the user interacts with the browser’s passkey autofill UI.

The user-verifying platform authenticator check establishes that, well, there is a user-verifying platform authenticator. The platform authenticator part means an authenticator that’s part of the user’s device, not removable, and the user-verifying part means that the authenticator verifies the presence of the user (such as via biometrics).

In the registerWebAuthnAccount function, the first thing we need to do is check that both these conditions are met and passkeys are supported by the browser. If not, we’ll just bail out and registration won’t be possible.

async function registerWebAuthnAccount(form) {
    if (!(await supportsPasskeys())) {
        return;
    }
}

Next, we’ll setup a big ol’ options object that we’ll pass to the WebAuthn API to specify what sort of credential we want. There’s going to be a whole lot of stuff here, so lets take it one piece at a time.

async function registerWebAuthnAccount(form) {
    // ...
    const createOptions = {
        publicKey: {
			rp: {
				id: "localhost",
				name: "Phoenix Passkeys",
			},
        },
    };
}

The RP is the Relying Party—that is, us, the party which relies on the credentials for authentication. The ID is the domain of the RP—just localhost for this example, though in reality you’d need to use your actual domain in production. The name is just a user-facing name for the RP.

async function registerWebAuthnAccount(form) {
    // ...
    const createOptions = {
        publicKey: {
            // ...
            user: {
                id: generateUserID(),
                name: form["user[email]"].value,
                displayName: "",
            },
        },
    };
}

Next up is some info about the user who the credential is for. The user’s “name” will just be the email that they entered in the form. The displayName value is required, per the spec, but we don’t have any other information so we just leave it blank and let the browser display the name only. The ID is where this gets a little weird, since we’re just generating a random 64-byte value:

function generateUserID() {
	const userID = new Uint8Array(64);
	crypto.getRandomValues(userID);
	return userID;
}

If you were adding a passkey to an existing user account, you could use a server-specified value for the user ID and the browser would replace any existing credentials with the same user ID and RP ID. But, since the user is registering a new account at this point, we assume they don’t want to do that (and, moreover, we don’t have any ID we can use yet). The user ID will also be returned upon a successful login, which would let us look up the user that’s logging in. However, since we’re only going to allow a credential to belong to a single user, we can use the credential’s ID to uniquely determine the user.

Next up, we specify the types of public keys that we’ll accept. We’re going to support Ed25519, ES256, and RS256, since those are recommended by the WebAuthn spec:

async function registerWebAuthnAccount(form) {
    // ...
    const createOptions = {
        publicKey: {
            // ...
            pubKeyCredParams: [
                {type: "public-key", alg: -8}, // Ed25519
                {type: "public-key", alg: -7}, // ES256
                {type: "public-key", alg: -257}, // RS256
            ],
        },
    };
}

During the login process, the server will generate a challenge value that the client will sign and the server will verify was signed with the user’s private key. The spec also requires that we provide a challenge when creating a credential, but we’re not going to use it for anything (since the user is just now creating the credential, we have nothing trusted that we can verify the initial challenge against), so we just provide an empty value:

async function registerWebAuthnAccount(form) {
    // ...
    const createOptions = {
        publicKey: {
            // ...
            challenge: new Uint8Array(),
        },
    };
}

Lastly, we give our requirements for authenticators that we want to use:

async function registerWebAuthnAccount(form) {
    // ...
    const createOptions = {
        publicKey: {
            // ...
            authenticatorSelection: {
                authenticatorAttachment: "platform",
                requireResidentKey: true,
            },
        },
    };
}

We want only the platform authenticator, not anything else, like removable security keys. We also specify that we want a resident key. This usage of “resident” is deprecated terminology that’s enshrined in the API. Really it means we want a discoverable credential, so that the authenticator will surface it during the login process without us having to request the credential by ID. This is important to note, since it’s what prevents needing a separate username entry step.

Now that we (finally) have all the configuration options in place, we can actually proceed with the credential creation. We pass the options to navigator.credentials.create to actually create the WebAuthn credential. If that fails, we’ll just take the easy way out and alert to inform the user (in an actual service, you’d probably want better error handling).

async function registerWebAuthnAccount(form) {
    // ...
    const credential = await navigator.credentials.create(createOptions);
    if (!credential) {
        alert("Could not create credential");
        return
    }
}

From the credential we get back, we need a few pieces of information. First is the decoded client data, which is an object that contains information about the credential creation request that occurred.

async function registerWebAuthnAccount(form) {
    // ...
    const clientDataJSON = new TextDecoder().decode(credential.response.clientDataJSON);
    const clientData = JSON.parse(clientDataJSON);
}

The clientDataJSON field of the response object contains the JSON-serialized object in an ArrayBuffer, so we decode that to text and then parse the JSON. With the decoded object, we do a consistency check with a couple pieces of data: the type of the request, whether or not it was cross-origin, and the actual origin being used.

async function registerWebAuthnAccount(form) {
    // ...
    if (clientData.type !== "webauthn.create" || (("crossOrigin" in clientData) && clientData.crossOrigin) || clientData.origin !== "http://localhost:4000") {
        alert("Invalid credential");
        return;
    }
}

If it was not a creation request, the request was cross-origin, or the origin doesn’t match, we bail out. Note that in production, the origin should be checked against the actual production origin, not localhost. And again, in reality you’d want better error handling than just an alert.

Next, we need to get the authenticator data which is encoded in a binary format and pull a few pieces of data out of it. You can see the full format of the authenticator data in the spec, but the parts we’re interested in are the backed-up state and the credential ID, which is part of the attested credential data.

async function registerWebAuthnAccount(form) {
    // ...
    const authenticatorData = new Uint8Array(credential.response.getAuthenticatorData());
    const backedUp = (authenticatorData[32] >> 4) & 1;
    const idLength = (authenticatorData[53] << 8) | authenticatorData[54];
    const id = authenticatorData.slice(55, 55 + idLength);
}

We get the backed-up bit from the flags byte at offset 32. Then we get the length of the credential ID, which is encoded as a big-endian, 16-bit integer at bytes 53 and 54. The ID itself immediately follows the length, thus starting at byte 55.

Before proceeding, we check that the backed-up bit is set, indicating that the credential is backed-up and safe from the user losing the current device. If it’s not, we won’t let the user register with this passkey. I choose to do this since it’s recommended by Adam Langley’s blog post, but whether it’s actually necessary may depend on your specific circumstances.

async function registerWebAuthnAccount(form) {
    // ...
    if (backedUp !== 1) {
        alert("Can't register with non backed-up credential");
        return;
    }
}

The last piece of data we need out of the credential is the actual public key:

async function registerWebAuthnAccount(form) {
    // ...
    const publicKey = credential.response.getPublicKey();
}

And with all that in place, we can actually initiate the registration. We’ll assemble a form data payload with all of the requisite values:

async function registerWebAuthnAccount(form) {
    // ...
    const body = new FormData();
    body.append("_csrf_token", form._csrf_token.value);
    body.append("email", form["user[email]"].value);
    body.append("credential_id", arrayBufferToBase64(id));
    body.append("public_key_spki", arrayBufferToBase64(publicKey));
}

We’ll use the body in a POST request to the registration endpoint. The response we get back will contain a status value to indicate whether the request was successful or not. If it was successful, the backend will have set the session cookie, and we can redirect to the home page and the new user will be logged in. If registration failed, we’ll alert the user.

async function registerWebAuthnAccount(form) {
    // ...
    const resp = await fetch(form.action, {
        method: "POST",
        body,
    });
    const respJSON = await resp.json();
    if (respJSON.status === "ok") {
        window.location = "/";
    } else {
        alert("Registration failed");
    }
}

And with that, we’re done with JavaScript (for now) and can move on to the backend part of registering an account.

Creating a user

In the UserRegistrationController module that comes with the Phoenix auth template, we’ll change the create function. By default, it registers the user using the parameters from the signup form and then redirects to the homepage. Instead, we’re going to register using the passkey we created on the client and then respond with the JSON that our JavaScript is expecting.

The first thing we need to do is extract the values that were sent by the frontend and decode the base 64-encoded ones.

defmodule PhoenixPasskeysWeb.UserRegistrationController do
  def create(conn, %{
        "email" => email,
        "credential_id" => credential_id,
        "public_key_spki" => public_key_spki
      }) do
    credential_id = Base.decode64!(credential_id)
    public_key_spki = Base.decode64!(public_key_spki)
  end
end

Those get passed to the Accounts.register_user function, which we’ll update shortly to handle. If account creation succeeded, we’ll still send the confirmation email as the existing code did. After that, instead of redirecting, we’ll log the user in by setting the session cookie and then respond with the “ok” status for the frontend. If account creation fails, we’ll just respond with the “error” status so the frontend can alert the user.

defmodule PhoenixPasskeysWeb.UserRegistrationController do
  def create(...) do
    # ...
    case Accounts.register_user(email, credential_id, public_key_spki) do
      {:ok, user} ->
        # Send confirmation email...

        conn
        |> UserAuth.log_in_user_without_redirect(user)
        |> json(%{status: :ok})

      {:error, _changeset} ->
        json(conn, %{status: :error})
    end
  end
end

Let’s update the register_user function. Instead of just creating a changeset for the user and then inserting it, we need to also create the authenticator. To avoid potentially leaving things in a broken state, we wrap both of these in a database transaction.

defmodule PhoenixPasskeys.Accounts do
  def register_user(email, credential_id, public_key_spki) do
    Repo.transaction(fn ->
      user =
        %User{}
        |> User.registration_changeset(%{email: email})
        |> Repo.insert()
        |> case do
          {:ok, user} -> user
          {:error, changeset} -> Repo.rollback(changeset)
        end
    end)
  end
end

First, we create a user with the given email. If the user creation fails, we abort and rollback the transaction. Then, we can create a credential belonging to the new user with the credential ID and public key we received from the client. As with the user, if creating the credential fails, we rollback the transaction.

defmodule PhoenixPasskeys.Accounts do
  def register_user(email, credential_id, public_key_spki) do
    Repo.transaction(fn ->
      # ...
      %UserCredential{}
      |> UserCredential.changeset(%{
        id: credential_id,
        public_key_spki: public_key_spki,
        user_id: user.id
      })
      |> Repo.insert()
      |> case do
        {:ok, _credential} -> nil
        {:error, changeset} -> Repo.rollback(changeset)
      end
    end)
  end
end

We don’t need to do anything with the newly created credential, so we can just ignore it once it’s been created.

And finally, from the transaction function, we return the user:

defmodule PhoenixPasskeys.Accounts do
  def register_user(email, credential_id, public_key_spki) do
    Repo.transaction(fn ->
      # ...
      user
    end)
  end
end

The last thing we need to to complete the registration flow is to set the new user’s session cookie so that they’re logged in immediately. The UserAuth module that’s generated as part of the Phoenix auth template has a log_in_user function that does exactly this. But it also redirects the connection to another endpoint. We don’t want to do that, since we’re sending a JSON response, so I’ve split the function into two: one that only sets the session, and the existing function that sets the session and then redirects.

defmodule PhoenixPasskeysWeb.UserAuth do
  def log_in_user(conn, user, params \\ %{}) do
    user_return_to = get_session(conn, :user_return_to)
    conn
    |> log_in_user_without_redirect(user, params)
    |> redirect(to: user_return_to || signed_in_path(conn))
  end

  def log_in_user_without_redirect(conn, user, params \\ %{}) do
    token = Accounts.generate_user_session_token(user)
    conn
    |> renew_session()
    |> put_token_in_session(token)
    |> maybe_write_remember_me_cookie(token, params)
  end
end

And with that, everything is in place and you can now create an account with a passkey!

Login form

Now that the user’s got an account, they need to be able to login with it. That means once again interacting with the WebAuthn API and writing a bunch of JavaScript. But before we get there, we need some slight changes to the backend.

In the HTML for the login page, we’ll add an ID to the <form> element so that we can find it from JS. We’ll also remove the password field, which is obviously no longer necessary. Lastly, but certainly not least, we need to send a challenge to the client.

The challenge is a value that the user’s device will cryptographically sign with their private key. The result will get sent back to the server, and we’ll verify it against the public key we have stored thus authenticating them. We’ll send the challenge just in a hidden form field:

<input type="hidden" id="challenge" value={@webauthn_challenge} />

In the session controller, we’ll need to generate and assign the challenge to the connection.

defmodule PhoenixPasskeysWeb.UserSessionController do
  def new(conn, _params) do
    conn
    |> put_webauthn_challenge()
    |> render(:new, error_message: nil)
  end
end

WebAuthn expects the challenge to be a value up to 64 bytes long, so we’ll use the Erlang crypto module to generate one of that length. The value is encoded as URL-safe base 64 (the same as normal base 64, but with dash and underscore rather than plus and slash) without padding. We encode it this way since that’s the format in which it will later be returned as part of the clientDataJSON, so when we extract that value we can directly compare it to the challenge value we generated.

defmodule PhoenixPasskeysWeb.UserSessionController do
  defp put_webauthn_challenge(conn) do
    challenge =
      :crypto.strong_rand_bytes(64)
      |> Base.url_encode64(padding: false)

    conn
    |> put_session(:webauthn_challenge, challenge)
    |> assign(:webauthn_challenge, challenge)
  end
end

Note that the challenge string is also stored in the session, so that we can later check that the challenge that the client signed matches the challenge we generated. It’s safe to store this in the session, even though it’s sent to the client, because the cookie is encrypted and signed so the client can’t tamper with it.

Login JavaScript

With the first part of the backend changes taken care of, it’s time for more JavaScript, baby!

We’ll follow a similar outline to the registration setup (and the same caveat applies about error handling).

document.addEventListener("DOMContentLoaded", () => {
    // ...
    const loginForm = document.getElementById("login-form");
	if (loginForm) {
        loginWebAuthnAccount(loginForm);
    }
});

async function loginWebAuthnAccount(loginForm) {
    if (!(await supportsPasskeys())) {
        return;
    }
}

The first thing we need to do is grab the challenge from the hidden form field, then we can construct the options object for getting the credential (which is, thankfully, much simpler than for creation).

async function loginWebAuthnAccount(loginForm) {
    // ...
    const challenge = loginForm.challenge.value;
    const getOptions = {
        mediation: "conditional",
        publicKey: {
            challenge: base64URLToArrayBuffer(challenge),
            rpId: "localhost",
        },
    };
}

In the options, we specify that we want conditional mediation. As noted before, this means that the browser won’t display any UI, except for autofill, for this credential request until the user accepts the autofill suggestion. In the public key options, we also give the decoded challenge value and specify the our Relying Party ID (again, this would need to be the actual domain in production).

Now, we can actually make the credential request and then, if we get a credential back, encode and send all the values to the backend. We need to send the ID of the credential, so that the backend can find its public key and the corresponding user. We also need the client data JSON, which we send as text decoded from the ArrayBuffer it’s returned as. We also need to send the authenticator data as well as the signature itself.

async function loginWebAuthnAccount(loginForm) {
    // ...
    const credential = await navigator.credentials.get(getOptions);
    if (!credential) {
        alert("Could not get credential");
        return;
    }

    const clientDataJSON = new TextDecoder().decode(credential.response.clientDataJSON);

    const body = new FormData();
    body.append("_csrf_token", loginForm._csrf_token.value);
    body.append("raw_id", arrayBufferToBase64(credential.rawId));
    body.append("client_data_json", clientDataJSON);
    body.append("authenticator_data", arrayBufferToBase64(credential.response.authenticatorData));
    body.append("signature", arrayBufferToBase64(credential.response.signature));
}

We can then send a request to the login endpoint. If the backend request fails (or if we failed to get the credential) we just alert the user (again, you’d probably want something better in reality). If the login attempt was successful, the server will have set the session cookie, and so we can just redirect to the homepage and the user will be logged in.

async function loginWebAuthnAccount(loginForm) {
    // ...
    const resp = await fetch("/users/log_in", {
        method: "POST",
        body,
    });
    const respJSON = await resp.json();
    if (respJSON?.status === "ok") {
        window.location = "/";
    } else {
        alert("Login failed");
    }
}

With that in place, let’s move on to the backend half of the login request.

Validating a login attempt

As with signup, we’ll modify the existing log in endpoint to actually validate the WebAuthn login attempt.

The first step is extracting all of the information the frontend provides in the params and decoding it:

defmodule PhoenixPasskeysWeb.UserSessionController do
  def create(conn, params) do
    id = params |> Map.get("raw_id") |> Base.decode64!()
    authenticator_data = params |> Map.get("authenticator_data") |> Base.decode64!()
    client_data_json_str = params |> Map.get("client_data_json")
    signature = params |> Map.get("signature") |> Base.decode64!()
  end
end

Next, we’re going to validate all of the information we got from the client. Before we get to that, there are a handful of helper functions we’ll use. First, looking up a credential by its ID:

defmodule PhoenixPasskeys.Accounts do
  def get_credential(id) do
    Repo.get(UserCredential, id)
    |> Repo.preload(:user)
  end
end

Next, a function in the controller that verifies the signature against the provided data:

defmodule PhoenixPasskeysWeb.UserSessionController do
  defp verify_signature(credential, client_data_json_str, authenticator_data, signature) do
    with {:ok, pubkey} <- X509.PublicKey.from_der(credential.public_key_spki),
         client_data_json_hash <- :crypto.hash(:sha256, client_data_json_str),
         signed_message <- authenticator_data <> client_data_json_hash,
         true <- :public_key.verify(signed_message, :sha256, signature, pubkey) do
      true
    else
      _ ->
        false
    end
  end
end

X509 comes from the x509 package, which is the only third-party piece of code we’re using. It’s a fairly thin wrapper around the Erlang public_key and crypto modules, and mostly serves to save me from having to deal with Erlang records in my code. Its from_der helper function is used to parse the public key from the encoded format.

Next, we hash the client data JSON and append that hash to the authenticator data from the client. This value is what should match the signature using the public key we’ve got, so finally we check that. If all these steps succeeded, we return true, and false otherwise.

The last helper function will receive the decoded client data make sure it’s got all of the values that we expect. If the crossOrigin value is present and is not false, the client data is invalid and the login attempt will be rejected.

defmodule PhoenixPasskeysWeb.UserSessionController do
  defp check_client_data_json(%{"crossOrigin" => crossOrigin}) when crossOrigin != false do
    false
  end
end

Otherwise, we check that the data has the expected type and origin, and we extract the challenge value (note that we’re checking the origin again here, and this would need to change in production):

defmodule PhoenixPasskeysWeb.UserSessionController do
  defp check_client_data_json(%{
         "type" => "webauthn.get",
         "challenge" => challenge,
         "origin" => "http://localhost:4000"
       }) do
    {:ok, challenge}
  end
end

And lastly, if neither of the previous patterns matched, the client data fails validation:

defmodule PhoenixPasskeysWeb.UserSessionController do
  defp check_client_data_json(_), do: false
end

Now, let’s put all those parts together and validate the login attempt.

defmodule PhoenixPasskeysWeb.UserSessionController do
  def create(conn, params) do
    # ...
    with credential when not is_nil(credential) <- Accounts.get_credential(id),
         true <- verify_signature(credential, client_data_json_str, authenticator_data, signature),
         {:ok, client_data_json} <- Jason.decode(client_data_json_str),
         {:ok, challenge} <- check_client_data_json(client_data_json),
         true <- challenge == get_session(conn, :webauthn_challenge),
         true <- :binary.part(authenticator_data, 0, 32) == :crypto.hash(:sha256, "localhost"),
         true <- (:binary.at(authenticator_data, 32) &&& 1) == 1 do
      conn
      |> delete_session(:webauthn_challenge)
      |> UserAuth.log_in_user_without_redirect(credential.user)
      |> json(%{status: :ok})
    else
      _ ->
        json(conn, %{status: :error})
    end
  end
end

Here’s everything that we’re doing:

1. Lookup the credential with the given ID.
2. Use the public key we had stored to verify the signature on the authenticator data and client data JSON.
3. Decode the client data JSON.
4. Check that all the values in the client data are what we expect, and extract the challenge that was signed.
5. Ensure the challenge that the user signed matches what we previously generated.
6. Extract the hash of the origin from the authenticator data and ensure it matches our origin (this would not be localhost in production).
7. Check that the authenticator data has the user presence bit set (indicating that a person was actually present on the client’s end).

If all of those steps succeeded, we remove the old challenge value from the session (since it’s no longer needed), actually log the user in, and then respond with the “ok” status that the JavaScript is expecting. If any step failed, we’ll respond with the “error” status and the frontend will alert the user.

Since there’s a lot going on here, it’s worth being clear about what exactly in this process lets us authenticate and prove that the user is who they claim to be. Since the signature verification step is using the public key that we stored during the registration process, we know that anyone that can produce a valid signature using that public key must be the user (or at any rate, have their private key). The value that they’re signing is, essentially, the challenge: a securely generated random value. The user isn’t directly signing the challenge, but this is still safe, since the challenge value is included in the client data JSON, that hash of which is included in the signed message.

So: the challenge value that was signed by the user must be in the client data, and the challenge value in the client data must be the one we generated. Given that, we know that the user whose key was used to sign the message is the one trying to log in now. That we’re verifying with the stored public key prevents an attacker from using an arbitrary key to sign the login attempt. And that the signed challenge matches the challenge the server generated means an attacker can’t reuse a previous response to login (a replay attack).

At long last, we finally have the ability to log in to our application using a passkey. Only a few minor things to go, so let’s forge ahead.

Handling login if the user enters an email

Although we’re presenting the conditional UI, there’s nothing preventing the user from typing their email into the field and then clicking “Sign in,” so we should probably handle that to. This can be done fairly simply by reusing our existing code for conditional login.

We’ll change the loginWebAuthnAccount to take an additional parameter, conditional, which will be a boolean indicating whether this login attempt is to setup the conditional UI or triggered by submitting the login form.

If it’s false, we won’t request conditional mediation and instead we’ll look up the credentials corresponding to the email the user entered and ask WebAuthn for one of those:

async function loginWebAuthnAccount(loginForm, conditional) {
    // ...
    let allowCredentials = [];
    if (!conditional) {
		const email = loginForm["user[email]"].value;
		const resp = await fetch(`/users/log_in/credentials?email=${email}`);
		const respJSON = await resp.json();
		allowCredentials = respJSON.map((id) => {
			return {
				type: "public-key",
				id: base64ToArrayBuffer(id),
			};
		});
    }

    const getOptions = {
		mediation: conditional ? "conditional" : "optional",
		publicKey: {
			challenge: base64URLToArrayBuffer(challenge),
			rpId: "localhost",
			allowCredentials,
		}
    };
    // ...
}

The “optional” value for the mediation option means that the authenticator isn’t required to display UI, but will do so if its policies dictate that. The allowCredentials array contains objects describing all of the credentials that we want to accept—specifically, their binary IDs as ArrayBuffers.

We look up the user’s credentials so that the one we actually request from the authenticator matches the account that the user is trying to log in with. To handle this, we’ll also wire up an additional route on the backend that returns the base 64-encoded IDs of all the credentials belonging to the user with a given email.

defmodule PhoenixPasskeysWeb.UserSessionController do
  def credentials(conn, %{"email" => email}) do
    ids =
      Accounts.get_credentials_by_email(email)
      |> Enum.map(fn cred -> Base.encode64(cred.id) end)

    json(conn, ids)
  end
end

The get_credentials_by_email function is quite simple. It just looks up a user by email, preloading any credentials they have and then returning them:

defmodule PhoenixPasskeys.Accounts do
  def get_credentials_by_email(email) do
    Repo.one(from u in User, where: u.email == ^email, preload: :credentials)
    |> case do
      %{credentials: credentials} -> credentials
      nil -> []
    end
  end
end

Back in the JS, we can tweak the setup code to pass true for the conditional parameter in the initial request and also register a submit handler on the login form that will invoke it with false:

document.addEventListener("DOMContentLoaded", () => {
    // ...
	const loginForm = document.getElementById("login-form");
	if (loginForm) {
		loginWebAuthnAccount(loginForm, true);
		loginForm.addEventListener("submit", (event) => {
			event.preventDefault();
			loginWebAuthnAccount(loginForm, false);
		});
	}
});

And so we’ve handled the case where the user ignores the conditional UI and still types in their email to log in.

Passkey reset

A not-infrequent argument against passkeys is that if your phone falls into a lake, you lose access to all of your passkey-backed accounts. One could argue that this isn’t true because the definition of passkeys means that they’re backed up and thus protected from this sort of event (and indeed, earlier we only permitted registering with backed-up credentials). I think the argument isn’t particularly interesting, however, because you can still have a “Forgot my passkey” option that works just like it does now with passwords.

This is less secure than a passkey implementation that has no “Forgot” option. But it’s no less secure than current password-based systems, and I think the UX/security tradeoff here falls on the UX side—people will, inevitably, lose access to their passkeys while retaining access to their email.

Implementing isn’t too complicated, fortunately, since we can reuse much of the registration code. First, the JavaScript. The only change necessary is attaching the registration function to the reset form as well.

document.addEventListener("DOMContentLoaded", () => {
    // ...
	const resetForm = document.getElementById("reset-passkey-form");
	if (resetForm) {
		resetForm.addEventListener("submit", (event) => {
			event.preventDefault();
			registerWebAuthnAccount(resetForm);
		});
	}
});

In the HTML for the reset form, we we need to include the email in the same form field as the registration form (and also add an ID to the <form> element):

<input type="hidden" name="user[email]" value={@user.email} />

In the function for the reset route (which is changed to POST from PUT, to match the signup route), we take the credential ID and public key and use them to update the user’s credentials:

defmodule PhoenixPasskeysWeb.UserResetPasswordController do
  def update(conn, %{
        "credential_id" => credential_id,
        "public_key_spki" => public_key_spki
      }) do
    credential_id = Base.decode64!(credential_id)
    public_key_spki = Base.decode64!(public_key_spki)
    case Accounts.reset_user_credentials(conn.assigns.user, credential_id, public_key_spki) do
      :ok ->
        conn
        |> put_flash(:info, "Passkey reset successfully.")
        |> UserAuth.log_in_user_without_redirect(conn.assigns.user)
        |> json(%{status: :ok})

      {:error, _} ->
        conn
        |> put_flash(:error, "Error resetting passkey")
        |> json(%{status: :error})
    end
  end
end

After updating, we log the user in if applicable and return JSON with the appropriate status.

The reset_user_credentials function works very similarly to the original reset password function that was part of the template: it deletes all the user’s existing sessions, and then removes their existing credentials and creates a new one:

defmodule PhoenixPasskeys.Accounts do
  def reset_user_credentials(user, credential_id, public_key_spki) do
    Ecto.Multi.new()
    |> Ecto.Multi.delete_all(
      :old_credentials,
      from(a in UserCredential, where: a.user_id == ^user.id)
    )
    |> Ecto.Multi.insert(
      :new_credential,
      UserCredential.changeset(%UserCredential{}, %{
        id: credential_id,
        public_key_spki: public_key_spki,
        user_id: user.id
      })
    )
    |> Ecto.Multi.delete_all(:tokens, UserToken.user_and_contexts_query(user, :all))
    |> Repo.transaction()
    |> case do
      {:ok, _} -> :ok
      {:error, _, changeset, _} -> {:error, changeset}
    end
  end
end

It’s worth noting that this does have slightly weaker security properties than the phx.gen.auth reset password implementation. With that approach, leaking a password reset token does not necessarily result in an account takeover, since whoever obtained the leaked token may not know the target user’s email address. Since the auth template forces the user to re-login after a reset, this prevents someone without the email address from gaining access even if they change the password.

But since logging in with a passkey is functionally a single factor, resetting it means gaining access to the account. So, a leaked reset token gives the bearer control over the account. This is an argument against having a reset option, but whether this is a concern in practice depends on your specific circumstances.

Conclusion

As noted, this is not a complete implementation. There are a handful of places where I’ve left things unfinished since this isn’t meant to be production-level code. There are also a few places where there are security decisions that need to be made on a more contextual basis, that I’ve tried to note. And, of course, you wouldn’t really want to only permit signing in with passkeys and wholesale drop the passwords column from your database.

Nonetheless, I hope this has been a helpful look at how to implement passkeys in an Elixir/Phoenix application. You can find the complete repo here, and it may also be useful to look at the specific commit where passkey support was added.