Mental model

request ─> session cookie ─> from the application? ─> verifySession ─> principal(session) ─> answered as User
              none                   no                    │                  refused
               │                     │                     └ ended: 401       └ 401
            visitor                 401

A request is one of three things: a visitor (Option.none()), someone (Option.some(user)), or refused (RemoteUnauthenticated, a 401 the client decodes). A cookie rides along with any request to the site, so one is used only from a request that shows it came from the application, by the rule Yielded applies to its own mutations: an Origin it trusts and its CSRF header (x-effect-auth-csrf: 1), or, for what a browser sends on the page's behalf, the Origin alone (below). From any other request it is refused, never quietly ignored: a page elsewhere borrows no one's session, and a client of the application's own that forgot the header learns so on its first call.

Install#

pnpm add effect @yielded/auth foldkit-remote foldkit-remote-server foldkit-auth

@yielded/auth is a peer, pinned exactly while Yielded is in beta. Yielded needs effect 4.0.3 or later, while foldkit declares exactly 4.0.0, so until Foldkit widens its peer an application allows it in its package.json:

{
  "pnpm": {
    "peerDependencyRules": { "allowedVersions": { "foldkit>effect": "4.0.4" } },
    "overrides": { "foldkit>@effect/platform-browser": "4.0.4" }
  }
}