@wtfalch/auth 0.1.0 → 0.1.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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/auth",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Sign in against auth.wtfalch.dev from a Next.js app.",
   "repository": {
     "type": "git",