@wtfalch/auth 0.3.1 → 0.4.1

package/README.md

@@ -60,6 +60,45 @@ Auth-request lookup failures lead to the configured error page with
 `auth_error=request` or `auth_error=unavailable`. That page should show a
 retry link; it must not automatically restart authorization.
 
+## In a browser app
+
+`@wtfalch/auth/browser` is the other half: a public PKCE client for an app that
+runs in the browser rather than on a server, and **silent single sign-on
+across the estate's subdomains**.
+
+```ts
+import { createBrowserAuth } from '@wtfalch/auth/browser';
+
+const auth = createBrowserAuth({
+  issuer: 'https://auth.wtfalch.dev',
+  clientId: '…',              // this app's client id at the issuer
+  callbackPath: '/signed-in', // when `/auth/callback` is not yours to host
+});
+
+// On load, with no token: ask the issuer without interacting. Either it
+// answers with a code — a flash and the app is signed in — or it says
+// `login_required` and the app shows its own button.
+if (!auth.currentSession()) await auth.trySilentSignIn();
+```
+
+**Why not one cookie for `.<apex>`.** The server session above is a `__Host-`
+cookie, which by specification carries no `Domain`: host-only, and that is what
+stops one subdomain writing a session the next one trusts. Single sign-on comes
+from the **issuer's** session instead — each origin takes its own token from
+it, and the person is asked for credentials once.
+
+`silentSignInAvailable()` is what a caller draws from: with no session it
+cannot otherwise tell *about to leave for the issuer* from *asked already, and
+here we are*, and the first case paints a sign-in screen at somebody on their
+way to being signed in.
+
+**Every silent attempt happens at most once per tab**, because an issuer
+answering `login_required` returns the person to a page whose load would ask
+again. `forget()` sets the same mark, so a sign-out does not undo itself.
+
+`completeSignIn()` at the callback returns `signed-in`, `silent-refused` — the
+answer to a silent attempt, not a failure — or `error`.
+
 ## Configuration
 
 | | |

package/dist/browser.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Signing in from a browser app, and being *already* signed in when another
+ * subdomain did it.
+ *
+ * The rest of this package is for a server: it holds a session in a cookie and
+ * the person never sees a token. A browser app cannot do that — whatever it
+ * holds, the person holding the browser holds too — so this is a public client
+ * using PKCE, the flow designed for exactly that.
+ *
+ * **Why a session cannot simply be shared across subdomains.** The server
+ * side's cookie is `__Host-` prefixed, and that prefix is defined as `Secure`,
+ * `Path=/` and *no* `Domain` attribute: host-only, by specification. It is
+ * what stops one subdomain writing a session cookie the next one would trust.
+ * Widening it to `.<apex>` to get single sign-on would trade that away, so the
+ * shared thing is not a cookie: it is the **session at the issuer**. Every
+ * origin gets its own token from it, and the person is asked for credentials
+ * once.
+ *
+ * **`prompt=none` is what makes that invisible.** On load, an app with no token
+ * asks the issuer to authorise without interacting. Either a code comes back —
+ * a redirect out and in, a flash, and the app is signed in — or the issuer
+ * answers `login_required`, and the app shows its own sign-in affordance
+ * having lost nothing. `trySilentSignIn` is that attempt, `completeSignIn`
+ * tells the two apart, and `SilentRefused` is the outcome to draw a button for
+ * rather than an error.
+ *
+ * **A top-level redirect, not a hidden iframe.** The classic silent-auth trick
+ * loads the issuer in an iframe, which needs the issuer's cookie in a
+ * third-party context — blocked by default in Safari and increasingly
+ * elsewhere. It fails *silently* and intermittently, which is the worst
+ * failure mode available. A redirect always works and costs a flash.
+ *
+ * **Every silent attempt is made at most once per tab.** Without that, an
+ * issuer answering `login_required` sends the app back to a page whose load
+ * asks again, forever, and the loop is invisible: the address bar settles and
+ * the tab spins. `forget()` sets the same mark, so pressing sign out does not
+ * bounce somebody straight back in — a sign-out that undoes itself is not one.
+ */
+export interface BrowserAuthOptions {
+    /** The issuer, e.g. `https://auth.wtfalch.dev`. */
+    issuer: string;
+    /** This app's client id at the issuer. */
+    clientId: string;
+    /**
+     * This app's origin. Read from the browser by default, so one build serves
+     * every project's subdomain without being told which it answers on.
+     */
+    origin?: string;
+    /**
+     * Where the issuer sends the person back. `/auth/callback` is the estate's
+     * default, and an app that cannot host it there says so — on a Stalwart
+     * origin `/auth` belongs to Stalwart and never reaches the app.
+     */
+    callbackPath?: string;
+    /** Scopes to ask for. `openid` is required; the rest is the app's business. */
+    scope?: string;
+}
+export interface BrowserSession {
+    accessToken: string;
+    /** Epoch milliseconds. */
+    expiresAt: number;
+}
+/** What `completeSignIn` found at the callback. */
+export type SignInOutcome = {
+    kind: 'signed-in';
+    session: BrowserSession;
+    returnTo: string;
+}
+/**
+ * The issuer has no session for this person, so a silent attempt could not
+ * be honoured. Not an error: it is the answer, and the app should show its
+ * sign-in affordance.
+ */
+ | {
+    kind: 'silent-refused';
+} | {
+    kind: 'error';
+    error: string;
+};
+export interface BrowserAuth {
+    /** The session this tab holds, or null. Expiry is checked with a minute of
+     *  slack: a token that dies mid-request is worse than one renewed early. */
+    currentSession(): BrowserSession | null;
+    /**
+     * Whether a silent attempt is still available in this tab: no session held,
+     * and none tried.
+     *
+     * A caller needs this to know what to *draw*. "No session" alone cannot
+     * tell "about to leave for the issuer" from "asked already, and here we
+     * are" -- and drawing a sign-in screen in the first case shows somebody a
+     * screen saying they are not signed in, for as long as the redirect takes,
+     * on their way to being let in. It was a third of a second on the estate's
+     * mail client, and it was the thing people noticed.
+     */
+    silentSignInAvailable(): boolean;
+    /**
+     * Ask the issuer to authorise without interacting, if it has not been asked
+     * in this tab already. Returns false when there was nothing to try — a
+     * session is held, or the attempt has been made — and otherwise does not
+     * return, because the browser leaves.
+     */
+    trySilentSignIn(returnTo?: string): Promise<boolean>;
+    /** Leave for the issuer, expecting to be asked for credentials. Does not
+     *  return. */
+    signIn(returnTo?: string): Promise<void>;
+    /** Finish the flow at the callback path. */
+    completeSignIn(search?: string): Promise<SignInOutcome>;
+    /** Drop the session, and do not silently take another in this tab. */
+    forget(): void;
+}
+export declare function createBrowserAuth(options: BrowserAuthOptions): BrowserAuth;

package/dist/browser.js

@@ -0,0 +1,202 @@
+/**
+ * Signing in from a browser app, and being *already* signed in when another
+ * subdomain did it.
+ *
+ * The rest of this package is for a server: it holds a session in a cookie and
+ * the person never sees a token. A browser app cannot do that — whatever it
+ * holds, the person holding the browser holds too — so this is a public client
+ * using PKCE, the flow designed for exactly that.
+ *
+ * **Why a session cannot simply be shared across subdomains.** The server
+ * side's cookie is `__Host-` prefixed, and that prefix is defined as `Secure`,
+ * `Path=/` and *no* `Domain` attribute: host-only, by specification. It is
+ * what stops one subdomain writing a session cookie the next one would trust.
+ * Widening it to `.<apex>` to get single sign-on would trade that away, so the
+ * shared thing is not a cookie: it is the **session at the issuer**. Every
+ * origin gets its own token from it, and the person is asked for credentials
+ * once.
+ *
+ * **`prompt=none` is what makes that invisible.** On load, an app with no token
+ * asks the issuer to authorise without interacting. Either a code comes back —
+ * a redirect out and in, a flash, and the app is signed in — or the issuer
+ * answers `login_required`, and the app shows its own sign-in affordance
+ * having lost nothing. `trySilentSignIn` is that attempt, `completeSignIn`
+ * tells the two apart, and `SilentRefused` is the outcome to draw a button for
+ * rather than an error.
+ *
+ * **A top-level redirect, not a hidden iframe.** The classic silent-auth trick
+ * loads the issuer in an iframe, which needs the issuer's cookie in a
+ * third-party context — blocked by default in Safari and increasingly
+ * elsewhere. It fails *silently* and intermittently, which is the worst
+ * failure mode available. A redirect always works and costs a flash.
+ *
+ * **Every silent attempt is made at most once per tab.** Without that, an
+ * issuer answering `login_required` sends the app back to a page whose load
+ * asks again, forever, and the loop is invisible: the address bar settles and
+ * the tab spins. `forget()` sets the same mark, so pressing sign out does not
+ * bounce somebody straight back in — a sign-out that undoes itself is not one.
+ */
+const TOKEN = 'wtfalch.auth.token';
+const VERIFIER = 'wtfalch.auth.verifier';
+const RETURN = 'wtfalch.auth.return';
+/** Set before a silent attempt leaves, so a refusal cannot become a loop. */
+const TRIED = 'wtfalch.auth.silent-tried';
+/** Storage that never throws. A browser refusing it signs in every visit,
+ *  which is worse than the alternative but not broken. */
+const store = {
+    get(key) {
+        try {
+            return sessionStorage.getItem(key);
+        }
+        catch {
+            return null;
+        }
+    },
+    set(key, value) {
+        try {
+            sessionStorage.setItem(key, value);
+        }
+        catch {
+            /* ignored, deliberately: see above */
+        }
+    },
+    drop(key) {
+        try {
+            sessionStorage.removeItem(key);
+        }
+        catch {
+            /* ignored, deliberately */
+        }
+    },
+};
+function base64url(bytes) {
+    return btoa(String.fromCharCode(...new Uint8Array(bytes)))
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_')
+        .replace(/=+$/, '');
+}
+async function challengeFor(verifier) {
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier));
+    return base64url(digest);
+}
+function verifier() {
+    // 32 bytes is RFC 7636's recommendation; base64url of it is 43 characters,
+    // inside the 43..128 the spec allows.
+    return base64url(crypto.getRandomValues(new Uint8Array(32)).buffer);
+}
+export function createBrowserAuth(options) {
+    const origin = options.origin ?? window.location.origin;
+    const callbackPath = options.callbackPath ?? '/auth/callback';
+    const scope = options.scope ?? 'openid email profile offline_access';
+    const redirectUri = `${origin}${callbackPath}`;
+    const authorize = async (prompt, returnTo) => {
+        const proof = verifier();
+        store.set(VERIFIER, proof);
+        store.set(RETURN, returnTo);
+        const url = new URL(`${options.issuer}/oauth/v2/authorize`);
+        url.searchParams.set('client_id', options.clientId);
+        url.searchParams.set('redirect_uri', redirectUri);
+        url.searchParams.set('response_type', 'code');
+        url.searchParams.set('scope', scope);
+        url.searchParams.set('code_challenge', await challengeFor(proof));
+        url.searchParams.set('code_challenge_method', 'S256');
+        if (prompt)
+            url.searchParams.set('prompt', prompt);
+        window.location.assign(url.toString());
+    };
+    const currentSession = () => {
+        const raw = store.get(TOKEN);
+        if (!raw)
+            return null;
+        try {
+            const session = JSON.parse(raw);
+            return session.expiresAt - 60_000 > Date.now() ? session : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    const silentSignInAvailable = () => !currentSession() && !store.get(TRIED);
+    return {
+        currentSession,
+        silentSignInAvailable,
+        async trySilentSignIn(returnTo = window.location.pathname) {
+            if (!silentSignInAvailable())
+                return false;
+            store.set(TRIED, '1');
+            await authorize('none', returnTo);
+            return true;
+        },
+        async signIn(returnTo = window.location.pathname) {
+            // A deliberate sign-in clears the mark: whatever the issuer said before,
+            // the person is asking now.
+            store.drop(TRIED);
+            await authorize(undefined, returnTo);
+        },
+        async completeSignIn(search = window.location.search) {
+            const params = new URLSearchParams(search);
+            const proof = store.get(VERIFIER);
+            const returnTo = store.get(RETURN) ?? '/';
+            // Removed whatever happens: a code that failed to exchange must not be
+            // retried against the same proof, and a stale verifier is what makes the
+            // *next* sign-in fail confusingly.
+            store.drop(VERIFIER);
+            store.drop(RETURN);
+            const issuerError = params.get('error');
+            if (issuerError) {
+                // The three the spec gives for "I would have had to ask them
+                // something". Any of them answers a silent attempt rather than
+                // failing it.
+                if (['login_required', 'interaction_required', 'consent_required'].includes(issuerError)) {
+                    return { kind: 'silent-refused' };
+                }
+                return { kind: 'error', error: params.get('error_description') ?? issuerError };
+            }
+            const code = params.get('code');
+            if (!code)
+                return { kind: 'error', error: 'the issuer sent no code' };
+            if (!proof) {
+                return {
+                    kind: 'error',
+                    error: 'this tab has no record of starting a sign-in — start again from the app',
+                };
+            }
+            const response = await fetch(`${options.issuer}/oauth/v2/token`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/x-www-form-urlencoded' },
+                body: new URLSearchParams({
+                    grant_type: 'authorization_code',
+                    client_id: options.clientId,
+                    redirect_uri: redirectUri,
+                    code,
+                    code_verifier: proof,
+                }),
+            });
+            if (!response.ok) {
+                const body = await response.text();
+                return {
+                    kind: 'error',
+                    error: `the issuer refused the code (${response.status}): ${body.slice(0, 200)}`,
+                };
+            }
+            const token = (await response.json());
+            if (!token.access_token)
+                return { kind: 'error', error: 'the issuer returned no access token' };
+            const session = {
+                accessToken: token.access_token,
+                expiresAt: Date.now() + (token.expires_in ?? 3600) * 1000,
+            };
+            store.set(TOKEN, JSON.stringify(session));
+            // Signed in: a later silent attempt in this tab is allowed again, which
+            // matters when the token expires and the page reloads.
+            store.drop(TRIED);
+            return { kind: 'signed-in', session, returnTo };
+        },
+        forget() {
+            store.drop(TOKEN);
+            // The mark stays set: a sign-out that silently signs you back in is not
+            // a sign-out.
+            store.set(TRIED, '1');
+        },
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wtfalch/auth",
-  "version": "0.3.1",
-  "description": "Sign in against auth.wtfalch.dev from a Next.js app.",
+  "version": "0.4.1",
+  "description": "Sign in against auth.wtfalch.dev: a server session for a Next.js app, and a browser client with silent single sign-on across subdomains.",
   "repository": {
     "type": "git",
     "url": "https://github.com/wtfalch/auth",
@@ -17,6 +17,10 @@
     "./next": {
       "types": "./dist/next.d.ts",
       "default": "./dist/next.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "default": "./dist/browser.js"
     }
   },
   "sideEffects": false,