RFC: Improve server API

[garronej]

To support DPoP, we need to update oidc-spa/backend and introduce a breaking change.
If we're going to do that, let's redisign the API to make it's usage less boilerplaty and try avoid having to export specific adapters for express, Hono, NestJS, tRCP, socket.io ect.

We also want to have a mock mode like in the client side API.

Here is an aspirational API example with Hono:

// src/auth.ts

import { oidcStart } from "oidc-start/server";
import { z } from "zod";
import { HTTPException } from "hono/http-exception";
import type { HonoRequest } from "hono";

export const { bootstrapAuth, requireAuth, isAnonymous } = oidcStart
    .withExpectedDecodedAccessTokenShape({
        decodedAccessTokenSchema: z.object({
            sub: z.string(),
            realm_access: z.object({
                roles: z.array(z.string())
            })
        })
    })
    // Depending if the user is using vanilla express, hono, trpc, they will be able to 
    // integrate.
    .withFrameworkIntegration<HonoRequest>({
        getRequestHeader: ({ req, headerName })=> req.header(headerName),
        createHttp401Exception: ({ cause }) => new HTTPException(401, cause)
    })
    // Let user declare custom logic for authorization
    .withAuthorizationCheck<{ requiredRole?: "realm-admin" | "support-staff" }>({
        checkAuthorization: ({ 
            requiredRole, 
            // Inherit the type declared in withExpectedDecodedAccessTokenShape
            decodedAccessToken 
        })=> {
            if( !requiredRole ){
                return;
            }
            if( !decodedAccessToken.realm_access.roles.includes(requiredRole)){
                throw new HTTPException(403, `Missing role ${requiredRole}`);
            }
        }
    })
    .createUtils();

bootstrapAuth(
    process.env.AUTH_USE_MOCK ? 
    {
        implementation: "mock",
        // Option 1: No token verification, trust payload
        mockBehavior: "unsafe decode only",
        
        // Option 2: Pretend every request bears a static identity
        /*
        mockBehavior: "use static identity",
        decodedAccessToken_mock: {
            sub: "123",
            ream_access: {
                roles: ["realm-admin"]
            }
        }
        */
    }:
    {
        implementation: "real",
        issuerUri: "https://auth.my-company.com/realms/myrealm",
        expectedAudience: "account",
        requireDPoP: true
    }
);

// ====================================
// src/main.ts

import { requireAuth, isAnonymous } from "@/auth";

//...

app.openapi(route, async c => {
    const { decodedAccessToken } = await requireAuth({ 
        req: c.req,  
        requiredRole: "realm-admin"
    });

    const todos = await getUserTodoStore(decodedAccessToken.sub).getAll();

    return c.json(todos);
});

// With middleware

app.middleware(async (c, next) => {
    let userId: string | undefined = undefined;

    if (!isAnonymous(c.req)) {
        const { decodedAccessToken } = await requireAuth({ req: c.req });

        userId = decodedAccessToken.sub;
    }

    return next(c, { userId });
});

app.openapi(route, async ({ req, userId }) => {
    if (userId === undefined) {
        // Process the request as anonymous
    }

    const todos = await getUserTodoStore(userId).getAll();

    return c.json(todos);
});