@wtfalch/auth 0.1.0 → 0.2.1

package/README.md

@@ -0,0 +1,90 @@
+# @wtfalch/auth
+
+Sign in against [auth.wtfalch.dev](https://auth.wtfalch.dev) from a Next.js app.
+
+A thin OIDC client for one self-hosted ZITADEL instance, plus a client for the
+sign-in service that sits in front of it. Apps host their own sign-in pages: a
+browser never renders a page on the identity service.
+
+Built for the wtfalch estate, published because valet consumes it from a
+container and a `file:` path does not survive a Docker build.
+
+```
+pnpm add @wtfalch/auth
+```
+
+Node 22 or later. `next` is a peer dependency and only the `/next` entry point
+needs it.
+
+## Using it
+
+```ts
+// src/lib/auth.ts
+import { nextAuth } from '@wtfalch/auth/next';
+
+export const { handlers, proxy, getUser, requireUser, signIn } = nextAuth({
+  appUrl: process.env.APP_URL,
+  clientId: process.env.AUTH_CLIENT_ID,
+  organizationId: process.env.AUTH_ORGANIZATION_ID,
+  cookieSecret: process.env.AUTH_COOKIE_SECRET,
+  appKey: process.env.AUTH_APP_KEY,
+  afterLogin: '/portal',
+});
+```
+
+Mount `handlers` at `app/auth/[...auth]/route.ts`, call `proxy` from your
+middleware for the paths that need a session, and read the person with
+`getUser()` in a server component.
+
+`createAuth` from `@wtfalch/auth` is the same thing without the framework, for
+a CLI or a worker that has no router to import.
+
+## Configuration
+
+| | |
+| --- | --- |
+| `appUrl` | This app's origin. Every URL the SDK builds starts here, never from the request's `Host`. |
+| `clientId` | The OIDC client for this origin. Each URL an app runs at is its own client, because the issuer holds one login URL per application. |
+| `organizationId` | Scopes every sign-in, and is checked on every token. |
+| `cookieSecret` | 32 bytes, `openssl rand -base64 32`. One per app. |
+| `appKey` | This app's key for the sign-in service. Needed for anything that checks or creates a credential. |
+
+Values are read on first use rather than at import, so `next build` needs none
+of them, and a missing one fails by name rather than mysteriously.
+
+**A cookie secret is needed where cookies are, and nowhere else.** An app that
+never seals a session, such as a CLI that sends an invitation, can leave it
+unset: the error waits until something actually reaches for the key. A secret
+that is *supplied and wrong* still throws at startup, because that is a typo
+rather than a deployment that does not need one.
+
+## What the app key can do
+
+It reaches the sign-in service, which holds ZITADEL's login client. Scoped to
+one organisation and to this app's clients, it can create people in that
+organisation, send mail to an address, and try passwords.
+
+It cannot sign in as somebody without their password or their mailbox, cannot
+reach another app, and cannot change anything on the instance. Treat it as a
+secret; it is not a skeleton key.
+
+## The session
+
+The cookie is the session. There is no session table and no token store, so
+there is nothing to expire, revoke or clean up on the app's side, and
+authority is whatever the app reads for itself on each request. The cookie is
+encrypted with `cookieSecret`, carries `__Host-` and `Secure` on an `https://`
+app URL, and refreshes itself when the id token is close to expiring.
+
+`ORG_CLAIM` is enforced on every token: a token from another organisation is
+refused even when the issuer and the signature are good.
+
+## Documentation
+
+`docs/adopting.md` in [wtfalch/auth](https://github.com/wtfalch/auth) covers a
+full adoption: the files to add, the email flows, invitations, refresh, and the
+checks to run against a real issuer.
+
+## Licence
+
+Private to the wtfalch estate.

package/dist/auth.d.ts

@@ -37,9 +37,9 @@ export type Gate = {
     cookies: SetCookie[];
 };
 export type Intent = 'login' | 'register';
-export type SignInError = 'invalid_credentials' | 'request' | 'unavailable';
+export type SignInError = 'invalid_credentials' | 'too_many' | 'request' | 'unavailable';
 export type ResetError = 'invalid_code' | 'invalid_password' | 'unavailable';
-export type SignUpError = 'email_taken' | 'invalid' | 'request' | 'unavailable';
+export type SignUpError = 'registration_closed' | 'email_taken' | 'username_taken' | 'username_invalid' | 'invalid' | 'request' | 'unavailable';
 export type SignInResult = {
     ok: true;
     redirectTo: string;

package/dist/auth.js

@@ -265,6 +265,16 @@ export function createAuth(input) {
             if (error instanceof BrokerError && error.error === 'email_taken') {
                 return { ok: false, error: 'email_taken', message: error.detail ?? error.error };
             }
+            if (error instanceof BrokerError && error.error === 'registration_closed') {
+                return { ok: false, error: 'registration_closed', message: error.detail ?? error.error };
+            }
+            // Both carry a sentence about the name, for the form to show as it is.
+            if (error instanceof BrokerError && error.error === 'username_taken') {
+                return { ok: false, error: 'username_taken', message: error.detail ?? error.error };
+            }
+            if (error instanceof BrokerError && error.error === 'username_invalid') {
+                return { ok: false, error: 'username_invalid', message: error.detail ?? error.error };
+            }
             if (error instanceof BrokerError && error.error === 'request') {
                 return { ok: false, error: 'request', message: error.detail ?? error.error };
             }
@@ -390,6 +400,9 @@ function signInError(error) {
     // A key the service will not take is the app's problem, not the visitor's.
     if (error instanceof BrokerError && error.error === 'unauthorized')
         return 'unavailable';
+    // The sign-in service's brute-force backstop tripped; ask them to wait.
+    if (error instanceof BrokerError && error.error === 'too_many')
+        return 'too_many';
     if (error instanceof BrokerError && error.status < 500)
         return 'invalid_credentials';
     return 'unavailable';

package/dist/broker.d.ts

@@ -9,6 +9,12 @@ export interface NewUser {
     password: string;
     givenName: string;
     familyName: string;
+    /**
+     * A login name they chose, where the app asks for one. Three to thirty of
+     * letters, digits, `.`, `_` and `-`; the service refuses reserved names
+     * and words it will not have. Without it the email is the login name.
+     */
+    username?: string;
 }
 export declare class BrokerError extends Error {
     readonly status: number;

package/dist/config.d.ts

@@ -5,8 +5,15 @@ export interface AuthOptions {
     clientId: string | undefined;
     /** From scripts/provisioned.json. Sent as a scope and checked on every token. */
     organizationId: string | undefined;
-    /** 32 bytes, base64 or hex: `openssl rand -base64 32`. One per app. */
-    cookieSecret: string | undefined;
+    /**
+     * 32 bytes, base64 or hex: `openssl rand -base64 32`. One per app.
+     *
+     * Optional in the type as well as at runtime, because a caller that never
+     * seals a cookie should not have to mention it at all. Supplied and wrong is
+     * still a startup error; absent is only an error when something reaches for
+     * the key.
+     */
+    cookieSecret?: string | undefined;
     /** Default https://auth.wtfalch.dev. */
     issuer?: string;
     /** Where the routes are mounted. Default /auth. */
@@ -33,7 +40,19 @@ export interface ResolvedOptions {
     appUrl: URL;
     clientId: string;
     organizationId: string;
-    cookieKey: Uint8Array;
+    /**
+     * Decoded on first access, not at resolve time.
+     *
+     * Only `cookies.ts` touches it, to seal or open a session. An app that never
+     * does either has no use for the secret, and a CLI that sends an invitation
+     * is exactly that: it calls the broker, which needs `appKey` and `clientId`
+     * and nothing else. Requiring a cookie-signing key to send an email meant
+     * putting that secret in a second container to make one command run.
+     *
+     * A secret that was SUPPLIED is still decoded eagerly, so a typo is a startup
+     * error. Only the absence is deferred.
+     */
+    readonly cookieKey: Uint8Array;
     issuer: string;
     basePath: string;
     afterLogin: string;

package/dist/config.js

@@ -7,11 +7,28 @@ export function resolveOptions(options) {
     if (!basePath.startsWith('/') || basePath.endsWith('/')) {
         throw new Error(`@wtfalch/auth: basePath must start with "/" and not end with one, got "${basePath}"`);
     }
+    /*
+      Checked NOW when one was supplied, and only then.
+  
+      The two failures are different and deserve different timing. A secret that
+      is the wrong length is a typo, and a typo should be found when the app
+      starts rather than by the first person who tries to sign in. A secret that
+      is ABSENT may simply be an app that never seals a cookie -- a CLI sending an
+      invitation -- and refusing to start is how that ends up carrying a
+      cookie-signing key it never uses.
+    */
+    if (options.cookieSecret !== undefined)
+        decodeKey(options.cookieSecret);
+    // Held here so the key is decoded at most once however often it is read.
+    let cookieKey;
     return {
         appUrl,
         clientId: options.clientId,
         organizationId: options.organizationId,
-        cookieKey: decodeKey(options.cookieSecret),
+        get cookieKey() {
+            cookieKey ??= decodeKey(options.cookieSecret);
+            return cookieKey;
+        },
         issuer: (options.issuer ?? ISSUER).replace(/\/$/, ''),
         basePath,
         afterLogin: options.afterLogin ?? '/',

package/dist/redirect.js

@@ -12,5 +12,12 @@ export function safeNextPath(next, fallback) {
     }
     if (url.origin !== 'https://app.invalid')
         return fallback;
-    return `${url.pathname}${url.search}`;
+    const path = `${url.pathname}${url.search}`;
+    // The URL parser can normalise an input like "/..//evil" into a
+    // protocol-relative "//evil", which a caller resolving it against an origin
+    // would send to another host. Guard the OUTPUT, not just the input.
+    if (!path.startsWith('/') || path.startsWith('//') || path.startsWith('/\\')) {
+        return fallback;
+    }
+    return path;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/auth",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Sign in against auth.wtfalch.dev from a Next.js app.",
   "repository": {
     "type": "git",
@@ -8,7 +8,9 @@
     "directory": "packages/auth"
   },
   "type": "module",
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -23,12 +25,6 @@
   "engines": {
     "node": ">=22.0.0"
   },
-  "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json",
-    "prepack": "pnpm build",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run"
-  },
   "dependencies": {
     "jose": "^6.2.10",
     "openid-client": "6.8.7"
@@ -44,11 +40,16 @@
   "devDependencies": {
     "@types/node": "^22",
     "@types/react": "^19",
-    "@wtfalch/auth-broker": "workspace:*",
     "next": "^16",
     "playwright-core": "^1.62.1",
     "react": "^19",
     "typescript": "^5.9.0",
-    "vitest": "^4.1.6"
+    "vitest": "^4.1.6",
+    "@wtfalch/auth-broker": "0.1.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
   }
-}
+}