alepha 0.22.0 → 0.23.0

package/src/server/auth/primitives/$authFederationBroker.ts

@@ -0,0 +1,273 @@
+import { AlephaError, t } from "alepha";
+import { SecurityError } from "alepha/security";
+import { $route, BadRequestError } from "alepha/server";
+import { $cookie } from "alepha/server/cookies";
+import {
+  authorizationCodeGrant,
+  buildAuthorizationUrl,
+  type Configuration,
+  calculatePKCECodeChallenge,
+  discovery,
+  randomPKCECodeVerifier,
+  randomState,
+} from "openid-client";
+import { signAppleClientSecret } from "../helpers/appleClientSecret.ts";
+import {
+  type FederationProfile,
+  signFederationAssertion,
+} from "../helpers/federationAssertion.ts";
+import { safeRedirectPath } from "../helpers/safeRedirectPath.ts";
+
+export interface FederationBrokerProviders {
+  google?: { clientId: string; clientSecret: string };
+  apple?: {
+    serviceId: string;
+    teamId: string;
+    keyId: string;
+    privateKeyPem: string;
+  };
+}
+
+export interface FederationBrokerOptions {
+  /** Broker public origin, e.g. https://alepha.club — becomes the assertion `iss`. */
+  issuer: string;
+  /** EdDSA PKCS#8 PEM — signs assertions. */
+  signingKeyPem: string;
+  providers: FederationBrokerProviders;
+  /** Validate the requested tenant and return its exact origin (or null to reject). */
+  resolveTenant: (tenant: string) => Promise<string | null>;
+  assertionTtlSeconds?: number;
+}
+
+const ISSUERS = {
+  google: "https://accounts.google.com",
+  apple: "https://appleid.apple.com",
+} as const;
+
+export const $authFederationBroker = (options: FederationBrokerOptions) => {
+  const callbackPath = "/auth/federated/callback";
+
+  if (!options.signingKeyPem) {
+    throw new AlephaError("$authFederationBroker requires signingKeyPem");
+  }
+
+  // Per-flow cookie: carries the tenant + PKCE/state across the redirect.
+  const flow = $cookie({
+    name: "federationFlow",
+    ttl: [15, "minutes"],
+    httpOnly: true,
+    encrypt: true,
+    schema: t.object({
+      provider: t.text(),
+      tenantOrigin: t.text({ size: "long" }),
+      redirectPath: t.text({ size: "long" }),
+      codeVerifier: t.optional(t.text({ size: "long" })),
+      state: t.optional(t.text()),
+      nonce: t.optional(t.text()),
+    }),
+  });
+
+  const callbackUri = `${options.issuer}${callbackPath}`;
+
+  // Build an openid-client Configuration for a provider. Apple's client_secret
+  // is signed fresh on every call (~5min) — no static secret, no rotation.
+  const getConfig = async (
+    provider: "google" | "apple",
+  ): Promise<Configuration> => {
+    if (provider === "google") {
+      const g = options.providers.google;
+      if (!g) {
+        throw new SecurityError("google federation not configured");
+      }
+      return discovery(new URL(ISSUERS.google), g.clientId, g.clientSecret);
+    }
+    const a = options.providers.apple;
+    if (!a) {
+      throw new SecurityError("apple federation not configured");
+    }
+    const clientSecret = await signAppleClientSecret({
+      privateKeyPem: a.privateKeyPem,
+      teamId: a.teamId,
+      serviceId: a.serviceId,
+      keyId: a.keyId,
+    });
+    return discovery(new URL(ISSUERS.apple), a.serviceId, clientSecret);
+  };
+
+  const scopeFor = (provider: string) =>
+    provider === "apple" ? "name email" : "openid email profile";
+
+  const start = $route({
+    path: "/auth/federated/start",
+    schema: {
+      query: t.object({
+        provider: t.text(),
+        tenant: t.text(),
+        redirect: t.optional(t.text({ size: "long" })),
+      }),
+    },
+    handler: async ({ query, reply, cookies }) => {
+      if (query.provider !== "google" && query.provider !== "apple") {
+        throw new BadRequestError(`Unsupported provider '${query.provider}'`);
+      }
+      const tenantOrigin = await options.resolveTenant(query.tenant);
+      if (!tenantOrigin) {
+        throw new BadRequestError("Unknown or inactive tenant");
+      }
+
+      const config = await getConfig(query.provider);
+      const codeVerifier = randomPKCECodeVerifier();
+      const codeChallenge = await calculatePKCECodeChallenge(codeVerifier);
+      const parameters: Record<string, string> = {
+        redirect_uri: callbackUri,
+        scope: scopeFor(query.provider),
+        code_challenge: codeChallenge,
+        code_challenge_method: "S256",
+      };
+      // Apple needs response_mode=form_post when requesting name/email scopes.
+      if (query.provider === "apple") {
+        parameters.response_mode = "form_post";
+      }
+
+      const usePkce = config.serverMetadata().supportsPKCE();
+      let state: string | undefined;
+      let nonce: string | undefined;
+      if (!usePkce) {
+        state = randomState();
+        nonce = randomState();
+        parameters.state = state;
+        parameters.nonce = nonce;
+        delete parameters.code_challenge;
+        delete parameters.code_challenge_method;
+      }
+
+      flow.set(
+        {
+          provider: query.provider,
+          tenantOrigin,
+          redirectPath: safeRedirectPath(query.redirect),
+          codeVerifier: usePkce ? codeVerifier : undefined,
+          state,
+          nonce,
+        },
+        { cookies },
+      );
+      reply.redirect(buildAuthorizationUrl(config, parameters).toString(), 302);
+    },
+  });
+
+  const handle = async (
+    urlOrReq: URL | Request,
+    cookies: any,
+    reply: any,
+    rawProfile?: Record<string, unknown>,
+  ) => {
+    const ctx = flow.get({ cookies });
+    if (!ctx) {
+      throw new BadRequestError("Missing federation flow");
+    }
+    flow.del({ cookies });
+
+    const provider = ctx.provider as "google" | "apple";
+
+    let profile: FederationProfile;
+    try {
+      const config = await getConfig(provider);
+      const tokens = await authorizationCodeGrant(config, urlOrReq, {
+        pkceCodeVerifier: ctx.codeVerifier,
+        expectedState: ctx.state,
+        expectedNonce: ctx.nonce,
+      });
+
+      // Verified claims come from the id_token; merge Apple's one-time form_post name.
+      const claims = (tokens.claims?.() ?? {}) as Record<string, unknown>;
+      const merged = { ...rawProfile, ...claims } as Record<string, unknown>;
+      profile = {
+        provider,
+        sub: String(merged.sub),
+        email: merged.email as string | undefined,
+        email_verified:
+          typeof merged.email_verified === "string"
+            ? merged.email_verified === "true"
+            : (merged.email_verified as boolean | undefined),
+        name: merged.name as string | undefined,
+        given_name: merged.given_name as string | undefined,
+        family_name: merged.family_name as string | undefined,
+        picture: merged.picture as string | undefined,
+        is_private_email:
+          typeof merged.is_private_email === "string"
+            ? merged.is_private_email === "true"
+            : (merged.is_private_email as boolean | undefined),
+      };
+    } catch {
+      // Upstream auth failed or the user denied consent — bounce back to the
+      // tenant with an error rather than surfacing a raw 500.
+      const fail = new URL(`${ctx.tenantOrigin}${ctx.redirectPath}`);
+      fail.searchParams.set("error", "federation_failed");
+      reply.redirect(fail.toString(), 302);
+      return;
+    }
+
+    const assertion = await signFederationAssertion(profile, {
+      privateKeyPem: options.signingKeyPem,
+      issuer: options.issuer,
+      audience: ctx.tenantOrigin,
+      ttlSeconds: options.assertionTtlSeconds,
+    });
+
+    const dest = new URL(`${ctx.tenantOrigin}/auth/federated/callback`);
+    dest.searchParams.set("token", assertion);
+    dest.searchParams.set("redirect", ctx.redirectPath);
+    reply.redirect(dest.toString(), 302);
+  };
+
+  const callback = $route({
+    path: callbackPath,
+    handler: async ({ url, reply, cookies }) => handle(url, cookies, reply),
+  });
+
+  // Apple posts the result (form_post). Extract its one-time `user` (name/email)
+  // before openid-client consumes the body.
+  const callbackPost = $route({
+    path: callbackPath,
+    method: "POST",
+    handler: async ({ reply, cookies, raw }) => {
+      let rawProfile: Record<string, unknown> | undefined;
+      let req: Request | URL = raw?.web?.req as Request;
+      if (raw?.web?.req) {
+        const cloned = raw.web.req.clone();
+        req = raw.web.req;
+        try {
+          const form = await cloned.formData();
+          const userField = form.get("user");
+          if (typeof userField === "string") {
+            const parsed = JSON.parse(userField) as {
+              name?: { firstName?: string; lastName?: string };
+              email?: string;
+            };
+            rawProfile = {};
+            if (parsed.name?.firstName) {
+              rawProfile.given_name = parsed.name.firstName;
+            }
+            if (parsed.name?.lastName) {
+              rawProfile.family_name = parsed.name.lastName;
+            }
+            if (parsed.name?.firstName || parsed.name?.lastName) {
+              rawProfile.name = [parsed.name?.firstName, parsed.name?.lastName]
+                .filter(Boolean)
+                .join(" ");
+            }
+            if (parsed.email) {
+              rawProfile.email = parsed.email;
+            }
+          }
+        } catch {
+          // ignore — name is optional on repeat logins
+        }
+      }
+      await handle(req, cookies, reply, rawProfile);
+    },
+  });
+
+  return { start, callback, callbackPost };
+};

package/src/server/auth/primitives/$authFederationClient.ts

@@ -0,0 +1,89 @@
+import { $context, t } from "alepha";
+import type { IssuerPrimitive } from "alepha/security";
+import { $route, BadRequestError } from "alepha/server";
+import {
+  type VerifyAssertionOptions,
+  verifyFederationAssertion,
+} from "../helpers/federationAssertion.ts";
+import { JtiReplayGuard } from "../helpers/jtiReplayGuard.ts";
+import { safeRedirectPath } from "../helpers/safeRedirectPath.ts";
+import { ServerAuthProvider } from "../providers/ServerAuthProvider.ts";
+import type { LinkAccountOptions, WithLinkFn } from "./$auth.ts";
+
+export async function assertionToProfile(
+  token: string,
+  opts: VerifyAssertionOptions,
+): Promise<{ provider: string; jti: string; link: LinkAccountOptions }> {
+  const { profile, jti } = await verifyFederationAssertion(token, opts);
+  return {
+    provider: profile.provider,
+    jti,
+    link: {
+      access_token: "", // federated: no upstream token retained
+      user: {
+        sub: profile.sub,
+        email: profile.email,
+        email_verified: profile.email_verified,
+        name: profile.name,
+        given_name: profile.given_name,
+        family_name: profile.family_name,
+        picture: profile.picture,
+      },
+    },
+  };
+}
+
+export interface FederationClientOptions {
+  realm: IssuerPrimitive & WithLinkFn;
+  brokerUrl: string; // assertion issuer
+  publicKeyPem: string;
+  selfOrigin?: string; // optional override; otherwise derived from the request host
+}
+
+export const $authFederationClient = (options: FederationClientOptions) => {
+  const { alepha } = $context();
+  const replay = new JtiReplayGuard(); // single-use, bounded (assertions ~60s)
+
+  const callback = $route({
+    path: "/auth/federated/callback",
+    schema: {
+      query: t.object({
+        token: t.text({ size: "rich" }),
+        redirect: t.optional(t.text({ size: "long" })),
+      }),
+    },
+    handler: async ({ query, url, reply, cookies }) => {
+      const serverAuth = alepha.inject(ServerAuthProvider);
+      const audience = options.selfOrigin ?? `${url.protocol}//${url.host}`;
+      try {
+        const { provider, jti, link } = await assertionToProfile(query.token, {
+          publicKeyPem: options.publicKeyPem,
+          issuer: options.brokerUrl,
+          audience,
+        });
+        if (!replay.check(jti)) {
+          throw new BadRequestError("Assertion already used");
+        }
+        if (!options.realm.link) {
+          throw new BadRequestError("Realm has no link function");
+        }
+        const user = await options.realm.link(provider)(link);
+        await serverAuth.establishSession(
+          user,
+          options.realm,
+          provider,
+          cookies,
+        );
+      } catch {
+        // Invalid / expired / replayed / tampered assertion (or a link
+        // refusal, e.g. unverified email) is an expected failure mode — bounce
+        // to login with an error rather than surfacing a raw 500.
+        reply.redirect("/auth/login?error=federation_failed", 302);
+        return;
+      }
+      reply.redirect(safeRedirectPath(query.redirect), 302);
+    },
+  });
+
+  return { callback };
+};

package/src/server/auth/providers/ServerAuthProvider.ts

@@ -3,6 +3,7 @@ import { DateTimeProvider } from "alepha/datetime";
 import { $logger } from "alepha/logger";
 import {
   InvalidCredentialsError,
+  type IssuerPrimitive,
   SecurityError,
   type UserAccount,
 } from "alepha/security";
@@ -547,18 +548,31 @@ export class ServerAuthProvider {
       return;
     }
 
-    const tokens = await issuer.createToken(user);
+    await this.establishSession(user, issuer, provider.name, cookies);
+
+    reply.redirect(redirectUri, 302);
+  }
 
+  /**
+   * Establish a local session for an already-resolved user: mint realm tokens
+   * and write the `tokens` cookie. Used by the OAuth callback and by federated
+   * (broker) login. `issuer` is the realm issuer (provider.issuer / realm).
+   */
+  public async establishSession(
+    user: UserAccount,
+    issuer: IssuerPrimitive,
+    providerName: string,
+    cookies: Cookies,
+  ): Promise<void> {
+    const tokens = await issuer.createToken(user);
     this.setTokens(
       {
         ...tokens,
         issued_at: this.dateTimeProvider.now().unix(),
-        provider: provider.name,
+        provider: providerName,
       },
       cookies,
     );
-
-    reply.redirect(redirectUri, 302);
   }
 
   /**

package/src/server/cookies/__tests__/ServerCookiesProvider.spec.ts

@@ -232,6 +232,76 @@ describe("ServerCookiesProvider", () => {
     // Secure flag is not added in tests unless protocol is https, which is handled by the provider
   });
 
+  describe("APP_NAME namespacing", () => {
+    class TokenApp {
+      tokens = $cookie({
+        name: "tokens",
+        schema: t.object({ value: t.text() }),
+      });
+      set = $action({
+        handler: () => {
+          this.tokens.set({ value: "from-app" });
+        },
+      });
+      read = $action({
+        schema: {
+          response: t.object({ value: t.optional(t.text()) }),
+        },
+        handler: ({ cookies }) => {
+          return { value: this.tokens.get({ cookies })?.value };
+        },
+      });
+    }
+
+    const makeApp = (appName: string) =>
+      Alepha.create({
+        env: { COOKIE_SECRET: TEST_COOKIE_SECRET, APP_NAME: appName },
+      })
+        .with(AlephaServer)
+        .with(AlephaServerCookies)
+        .with(TokenApp);
+
+    test("prefixes the cookie name with the lowercased APP_NAME", async () => {
+      const appA = makeApp("AppA");
+      await appA.start();
+
+      const response = await appA.inject(TokenApp).set.fetch();
+      const setCookieHeader = response.headers.get("set-cookie");
+
+      // Cookie is written under the namespaced name, not the bare "tokens".
+      expect(setCookieHeader).toContain("appa.tokens=");
+      expect(setCookieHeader).not.toMatch(/(^|; )tokens=/);
+    });
+
+    test("two apps sharing a cookie jar do not collide", async () => {
+      const appA = makeApp("AppA");
+      const appB = makeApp("AppB");
+      await appA.start();
+      await appB.start();
+
+      // App A writes its cookie.
+      const responseA = await appA.inject(TokenApp).set.fetch();
+      const cookieA = responseA.headers
+        .get("set-cookie")!
+        .match(/appa\.tokens=([^;]*)/)![1];
+
+      // App A reads its own cookie back from the shared jar — works.
+      const incoming = `appa.tokens=${cookieA}`;
+      const readA = await appA
+        .inject(TokenApp)
+        .read.fetch({}, { request: { headers: { cookie: incoming } } });
+      expect(readA.data.value).toBe("from-app");
+
+      // App B sees the SAME jar (same host:localhost), but reads under
+      // "appb.tokens" — so App A's cookie is invisible to it. No collision,
+      // no failed-decrypt-then-delete logout.
+      const readB = await appB
+        .inject(TokenApp)
+        .read.fetch({}, { request: { headers: { cookie: incoming } } });
+      expect(readB.data.value).toBeUndefined();
+    });
+  });
+
   // test("should throw if secret is missing for secure cookies", async () => {
   // 	class AppWithMissingSecret {
   // 		badCookie = $cookie({

package/src/server/cookies/providers/ServerCookiesProvider.ts

@@ -88,13 +88,33 @@ export class ServerCookiesProvider {
     );
   }
 
+  /**
+   * Namespaces a cookie name with the app's `APP_NAME` (lowercased) so that
+   * two Alepha apps sharing a cookie jar do not collide.
+   *
+   * Cookies are scoped by host + path only — never by port — so two apps on
+   * `localhost:3000` and `localhost:4000` would otherwise both read/write a
+   * cookie literally named `tokens` and silently clobber each other (and,
+   * because each encrypts with its own `APP_SECRET`, the foreign cookie fails
+   * to decrypt and gets deleted, logging the user out).
+   *
+   * When `APP_NAME` is unset the name is returned unchanged, so existing
+   * single-app deployments keep their current cookie names. Same convention as
+   * the `APP_NAME` prefix used by R2 storage and server-timing.
+   */
+  protected prefixName(name: string): string {
+    const app = this.alepha.env.APP_NAME;
+    if (!app) return name;
+    return `${String(app).toLowerCase()}.${name}`;
+  }
+
   public getCookie<T extends TSchema>(
     name: string,
     options: CookiePrimitiveOptions<T>,
     contextCookies?: Cookies,
   ): Static<T> | undefined {
     const cookies = this.getCookiesFromContext(contextCookies);
-    let rawValue = cookies.req[name];
+    let rawValue = cookies.req[this.prefixName(name)];
 
     if (!rawValue) return undefined;
 
@@ -174,7 +194,7 @@ export class ServerCookiesProvider {
       cookie.maxAge = this.dateTimeProvider.duration(options.ttl).as("seconds");
     }
 
-    cookies.res[name] = cookie;
+    cookies.res[this.prefixName(name)] = cookie;
   }
 
   public deleteCookie<T extends TSchema>(
@@ -182,7 +202,7 @@ export class ServerCookiesProvider {
     contextCookies?: Cookies,
   ): void {
     const cookies = this.getCookiesFromContext(contextCookies);
-    cookies.res[name] = null;
+    cookies.res[this.prefixName(name)] = null;
   }
 
   // --- Crypto & Parsing ---

package/src/server/core/interfaces/ServerRequest.ts

@@ -188,6 +188,14 @@ export interface ServerRoute<
    * @see ServerLoggerProvider
    */
   silent?: boolean;
+
+  /**
+   * Mark this `GET` route as prerenderable. When `true`, the build invokes the
+   * handler in-process and writes its body verbatim to `dist/public/{path}`,
+   * so the route is served as a static file (e.g. `sitemap.xml`, `robots.txt`).
+   * The route still serves live at request time for runtimes that have a server.
+   */
+  static?: boolean;
 }
 
 /**

package/src/server/core/primitives/$route.ts

@@ -5,9 +5,11 @@ import {
   PipelinePrimitive,
   type PipelinePrimitiveOptions,
 } from "alepha";
+import { ServerReply } from "../helpers/ServerReply.ts";
 import type {
   RequestConfigSchema,
   ServerHandler,
+  ServerRequest,
   ServerRoute,
 } from "../interfaces/ServerRequest.ts";
 import { ServerRouterProvider } from "../providers/ServerRouterProvider.ts";
@@ -46,6 +48,31 @@ export class RoutePrimitive<
       handler: this.handler,
     } as ServerRoute<TConfig>);
   }
+
+  /**
+   * Invoke this route's handler in-process (no HTTP server) and return its path
+   * and body. Used by the build to snapshot `static` routes to files.
+   *
+   * Only meaningful for self-contained `GET` handlers that return a string or
+   * Buffer (e.g. `sitemap.xml`, `robots.txt`).
+   */
+  public async prerender(): Promise<{ path: string; body: string | Buffer }> {
+    const reply = new ServerReply();
+    const request = {
+      method: this.options.method ?? "GET",
+      url: new URL(`http://localhost${this.options.path}`),
+      params: {},
+      query: {},
+      headers: {},
+      body: undefined,
+      metadata: {},
+      reply,
+    } as unknown as ServerRequest<TConfig>;
+
+    const result = await this.handler.run(request);
+    const body = (result ?? reply.body) as string | Buffer;
+    return { path: this.options.path, body };
+  }
 }
 
 $route[KIND] = RoutePrimitive;