Blog 3

[motdotla]

No description provided.

[charliecreates]

Global Rouge styling is a good direction, but placing a large highlight/CSS block in _includes/layouts/meta.html increases cross-page coupling and makes future overrides harder. The new blog post has a real correctness issue (json = {...} without declaration) and a likely reader-confusion issue around .well-known key discovery depending on whether req.agentUid is set. There’s also potential API confusion in the tutorial due to switching between vestauth.primitives.verify and vestauth.tool.verify without explanation.

Summary of changes

Summary

This PR introduces Rouge-based syntax highlighting across the site and adds a new blog post.

Key updates

• Jekyll config: switches from no highlighter to rouge via kramdown.syntax_highlighter and highlighter.
• Global code styling: adds a sizable block of CSS in _includes/layouts/meta.html to style inline code and Rouge highlight output (div.highlighter-rouge, figure.highlight, token colors) with light/dark scheme support.
• Blog layout cleanup: removes blog-specific code block styles in _layouts/blog.html (presumably replaced by the global Rouge styles) and removes text-transform: lowercase.
• Homepage snippets: replaces inline <pre><code> blocks with Liquid {% highlight %} blocks for shell/JS examples.
• Content: adds a new post blog/_posts/2026-02-22-run-your-own-vestauth-infrastructure.md and an associated image assets/img/blog/blog-3.png.

[charliecreates]

The inline-code selector main :not(pre) > code will also style code inside other containers you likely don’t want treated as “inline” (e.g., figure.highlight code can still match depending on Rouge’s structure, nested wrappers, or future markup changes). It’s safer to explicitly exclude Rouge/highlight containers so you don’t end up double-styling or fighting specificity later.

Suggestion

Tighten the selector to target only inline code while explicitly excluding Rouge blocks. For example:

main :not(pre):not(.highlight):not(.highlighter-rouge) > code {
  /* inline code styles */
}

/* Or, more explicit: */
main p > code,
main li > code,
main td > code {
  /* inline code styles */
}

This reduces unintended styling collisions with Rouge-generated markup. Reply with "@CharlieHelps yes please" if you’d like me to add a commit with this change.

[charliecreates]

All Rouge/highlighting styles are being injected into a shared meta.html include. This is a large, domain-specific styling block that will apply to every page and increases the cost of future style changes (and makes CSS harder to discover/override). If the site grows, this becomes a maintainability pain point and can cause unexpected cross-page regressions.

Suggestion

Move these code/highlight styles into a dedicated CSS file (e.g., assets/css/highlight.css) and include it via <link> so it’s cacheable and logically separated.

If you want to keep it inline for now, at least wrap with a comment header and scope to a class on layouts that need it (e.g., .has-code-blocks main ...). Reply with "@CharlieHelps yes please" if you’d like me to add a commit moving this into an asset and wiring it up.

[charliecreates]

The .well-known endpoint example filters keys by req.agentUid, but req.agentUid is only set for *.localhost hosts in the later middleware. If you hit http://localhost:3000/.well-known/... directly, req.agentUid will be undefined and this will always return an empty key set, which can confuse readers when they test the endpoint during the tutorial.

Suggestion

Adjust the example to handle the non-subdomain case explicitly (and explain it). For example:

app.get('/.well-known/http-message-signatures-directory', (req, res) => {
  if (!req.agentUid) {
    return res.status(400).json({
      error: 'Missing agent subdomain. Use http://<agent-uid>.localhost:3000/…'
    })
  }

  const keys = PUBLIC_JWKS
    .filter(jwk => jwk.agent_uid === req.agentUid)
    .map(jwk => jwk.value)

  res.json({ keys })
})

Reply with "@CharlieHelps yes please" if you’d like me to add a commit updating the post with this clarification and snippet.

[charliecreates]

In the /register example, json = { ... } assigns to an undeclared variable. In Node this can create a global (or throw in strict mode), and it’s a bad pattern to show in docs since readers will copy/paste it.

Suggestion

Declare the response object with const (or let) in the example:

const json = {
  uid: agent.uid,
  kid: publicJwk.kid,
  public_jwk: verified.public_jwk,
  is_new: true
}

res.json(json)

Reply with "@CharlieHelps yes please" if you’d like me to add a commit fixing this in the post.

[charliecreates]

The post alternates between vestauth.primitives.verify(...) and vestauth.tool.verify(...) (later in /whoami). If that’s intentional, it needs a quick explanation; otherwise it reads like a mistake and will lead to copy/paste confusion when readers implement both endpoints.

Suggestion

Either standardize on one verification API in the tutorial or add a short callout explaining the difference (e.g., tool.verify convenience wrapper vs lower-level primitives.verify). If you want to standardize, consider using the same function signature for both endpoints.

Reply with "@CharlieHelps yes please" if you’d like me to add a commit that updates the post for consistency/clarity.

[charliecreates]

The snippet uses vestauth.primitives.verify(req.method, url, req.headers, req.body.public_jwk) when handling /register. If the request body is {} (as shown in the earlier curl test) req.body.public_jwk is undefined, which can produce a confusing error relative to what you’re trying to demonstrate (missing signature headers).

Because this is a guide, it’s better to either: (a) keep the earlier verbose call where the 4th arg is clearly the public key and add a short note that it’s expected to be present for successful registration, or (b) add a guard that returns 400 when public_jwk is missing so readers get a clear, intentional failure mode.

Suggestion

Add an explicit early check in the snippet to improve the tutorial’s copy/paste experience:

if (!req.body?.public_jwk) {
  return res.status(400).json({
    error: { status: 400, code: 'MISSING_PUBLIC_JWK', message: 'Missing `public_jwk` in request body.' },
  })
}

Reply with "@CharlieHelps yes please" if you’d like me to add a commit updating the snippet accordingly.

[charliecreates]

Switching kramdown.syntax_highlighter and highlighter to rouge is fine, but it changes generated HTML structure and class names for code blocks across the site. You already updated index.md to use {% highlight %}, but any existing posts/pages that relied on prior <pre> styling may render differently.

Given you also removed .blog-content pre styles, you should verify at least one older post/page with fenced code blocks still looks acceptable (light + dark).

Suggestion

Do a quick audit of existing markdown posts/pages that contain fenced code blocks (```), verify the generated HTML uses Rouge wrappers, and ensure the new CSS covers them. If gaps exist, add a small compatibility selector (e.g. for bare pre > code) or update the markdown to use {% highlight %} consistently.

Reply with "@CharlieHelps yes please" if you’d like me to add a commit that adds minimal compatibility CSS for non-Rouge code blocks.