Auth for Val Town

I've developed a collection of vals that lets you sign into HTTP vals who use its middleware

(help me name this?)

Example Projects

You have an HTTP val that is just for you, because it accesses your sqlite or blob storage or any other sensitive function. Install the @postpostscript/authMiddleware.authMiddlewareCookie middleware for zero-config authentication that makes executing the endpoint exclusive to you. Example: @postpostscript/authIdExampleCookiePrivate
You have an HTTP val and you want to gate a feature behind a login form while letting anyone access the site. Use that same middleware but disable the token issuer (iss) requirement and set the optional option to true. Example: @postpostscript/authIdExampleComments
You have an API and you want to lock it down, with specific scopes giving you access to specific endpoints. Use the authMiddlewareToken middleware with the additional middleware @postpostscript/pathAsScope. Example: @postpostscript/apiProxy
@postpostscript/sqliteExplorerApp: a fork of @nbbaier/sqliteExplorerApp gated behind authMiddlewareCookie

Make a cool project with this? Let me know and I'll add it to the list!

How it Works

Every user who wants to use this system is required to set up a JWKS endpoint at @handle/jwks (Instructions: @postpostscript/jwks). This is the foundation for trusted communication between code executed by different Val Town accounts, and is what enables this system

Anyone who wants to sign in must fork the @postpostscript/authId val which provides the sign in mechanism just for you. You can modify this to your liking as long as it provides the same outputs (redirecting back to the Client with token and clientToken query string params) with the same inputs (a Client Token)

If I want to require authentication for my HTTP val, I need to use middleware to protect the endpoint(s). The simplest of that is @postpostscript/authMiddleware.authMiddlewareCookie, which will provide a login form for the endpoint and pass through the request once a trusted token is stored in the AUTH_ID_TOKEN cookie. By default, the val's owner is the only one who can sign into it. Here's an example JWT Payload that provides access to @example/exampleApp:

{
  "jti": "c63a41c9-13d0-4424-b5b4-4a8ec6002610",
  "aud": [
    "@example/exampleApp",
    "@postpostscript/authId"
  ],
  "scope": "@postpostscript/authId/id",
  "iss": "@postpostscript/authId",
  "sub": "@postpostscript/authId",
  "clientTokenId": "12abb6d0-6c88-4d2f-bb56-88f79a2b4503",
  "iat": 1709694976,
  "exp": 1709698576
}

This, once the token is verified against the @postpostscript/jwks endpoint, says:

I received this auth token from @postpostscript (iss: @postpostscript/authId)
I have been given permission to act as them (scope: @postpostscript/authId/id)
I was authenticated at the request of a trusted client (clientTokenId: 12abb6d0-6c88-4d2f-bb56-88f79a2b4503)
@example/exampleApp is the only val that should accept this token (aud: @example/exampleApp)
I have 1 hour to use this token, after that it will not work (iat and exp)

Here's how I got to this token

I navigated to https://example-exampleapp.web.val.run/
I entered my Val Town username (@postpostscript)
I clicked "Go to Your Sign In Page" and was redirected to https://postpostscript-authid.web.val.run/?clientToken=[...]
Since I hadn't verified my identity on my sign in page in an hour, I needed to do that by clicking "Send Sign In Link to My Email" and clicking the link in that email. Now the @postpostscript/authId endpoint knew I was @postpostscript!
Next I reviewed the list of scopes @example/exampleApp was requesting. In this case, it was only the required scope of @postpostscript/authId/id, the one proving I am me. In other apps, I may see other scopes that the apps have requested that I can optionally accept
I clicked Provide Access to @example/exampleApp and was redirected to https://example-exampleapp.web.val.run/?token=[...]&clientToken[...]. If the app is happy with those tokens, I am now authenticated. If it were locked down to only be available to @example, I'd see an error here

Next Steps

Try it out, give me feedback, and help out with improvements if you'd like! Right now @handle/authId is the only trusted sign-in provider but that's just for simplicity, there could be @handle/authIdV2 or @handle/iamme or @handle/whatever, as long as the outputs are the same

I have started working on a permissioned callback system (run someone else's code as you without needing to fork anything) that uses this, but I'm not 100% sure yet how to guarantee that code you have whitelisted has not changed. Either way, that should be coming in the near future! Let me know if you have any ideas for that or anything else!

Glossary

Scope

A permission that has been granted to a token, for example @example/blog/deleteComment or @example/apiProxy/request/v1/*:GET. Vals can self-describe their scopes like this:

Create val
export const SCOPES = {
  deleteComment: "lets you delete a comment",
  "request/v1/*": "makes an API request as you",
}

Client Token

A token @postpostscript/authMiddleware.authMiddlewareCookie generates to represent a sign-in request. It is passed to a user's sign-in page and then passed back afterwards to ensure both parties trust each other

Out of the box, @postpostscript/jwks.verify enforces the maximum number of times a token can be validated when the field maxUses is present in its payload. Client Tokens use this to ensure that 1 sign-in request = 1 sign-in attempt, successful or not

JWT (JSON Web Token)

A key giving permission to the token-holder to do an action

JWKS (JSON Web Key Sets)

A standard for the public verification of JWTs

blogAuth