alepha 0.22.0 → 0.23.0

package/src/react/sitemap/primitives/$sitemap.ts

@@ -0,0 +1,196 @@
+import { $inject, createPrimitive, KIND, Primitive } from "alepha";
+import { DateTimeProvider } from "alepha/datetime";
+import { type ServerRequest, ServerRouterProvider } from "alepha/server";
+
+/**
+ * Expose a `sitemap.xml` generated from the application's `$page` primitives.
+ *
+ * Registers a `GET /sitemap.xml` route that reads every registered page at
+ * request time and emits a standard XML sitemap. Marked `static` by default, so
+ * the build prerenders it to `dist/public/sitemap.xml` for static deployments —
+ * while SSR runtimes also serve it live.
+ *
+ * The hostname comes from `options.hostname`, falling back to `PUBLIC_URL`, then
+ * to `""` (relative URLs).
+ *
+ * @example
+ * ```ts
+ * import { $sitemap } from "alepha/react/sitemap";
+ *
+ * class AppRouter {
+ *   sitemap = $sitemap();
+ * }
+ * ```
+ */
+export const $sitemap = (
+  options: SitemapPrimitiveOptions = {},
+): SitemapPrimitive => {
+  return createPrimitive(SitemapPrimitive, options);
+};
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export interface SitemapPrimitiveOptions {
+  /**
+   * Absolute base URL used to build `<loc>` entries (e.g. "https://alepha.dev").
+   *
+   * Defaults to `PUBLIC_URL`, then to `""` (relative URLs).
+   */
+  hostname?: string;
+
+  /**
+   * Route path the sitemap is served at.
+   *
+   * @default "/sitemap.xml"
+   */
+  path?: string;
+
+  /**
+   * Prerender the sitemap to a static file at build time.
+   *
+   * @default true
+   */
+  static?: boolean;
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+
+export class SitemapPrimitive extends Primitive<SitemapPrimitiveOptions> {
+  protected readonly router = $inject(ServerRouterProvider);
+  protected readonly dateTime = $inject(DateTimeProvider);
+
+  protected onInit() {
+    this.router.createRoute({
+      method: "GET",
+      path: this.options.path ?? "/sitemap.xml",
+      static: this.options.static ?? true,
+      silent: true,
+      handler: (request: ServerRequest) => {
+        request.reply.setHeader("content-type", "application/xml");
+        return this.buildSitemap();
+      },
+    });
+  }
+
+  /**
+   * Render the sitemap to its path and body. Used by the build to snapshot the
+   * sitemap to a static file.
+   */
+  public prerender(): { path: string; body: string } {
+    return {
+      path: this.options.path ?? "/sitemap.xml",
+      body: this.buildSitemap(),
+    };
+  }
+
+  /**
+   * Build the sitemap XML from the application's page primitives.
+   */
+  protected buildSitemap(): string {
+    const hostname =
+      this.options.hostname ?? String(this.alepha.env.PUBLIC_URL ?? "");
+    const pages = this.getSitemapPages();
+    return this.generateSitemapFromPages(pages, hostname);
+  }
+
+  /**
+   * Select the pages that should appear in the sitemap.
+   *
+   * Excludes layout pages (with `children`), wildcard paths, and `/404`.
+   * Parameterized pages are included only when they declare `static.entries`.
+   */
+  protected getSitemapPages(): any[] {
+    const pages = this.alepha.primitives("page") as any[];
+    return pages.filter((page) => {
+      const options = page.options;
+      const path: string = options.path ?? "";
+      if (options.children) {
+        return false;
+      }
+      if (path.includes("*")) {
+        return false;
+      }
+      if (path === "/404") {
+        return false;
+      }
+      if (!options.schema?.params) {
+        return true;
+      }
+      if (
+        options.static &&
+        typeof options.static === "object" &&
+        options.static.entries
+      ) {
+        return true;
+      }
+      return false;
+    });
+  }
+
+  protected generateSitemapFromPages(pages: any[], baseUrl: string): string {
+    const urls: string[] = [];
+    const normalizedBaseUrl = baseUrl.replace(/\/$/, "");
+
+    for (const page of pages) {
+      const options = page.options;
+
+      if (!options.schema?.params) {
+        const path = options.path || "";
+        const url = `${normalizedBaseUrl}${path === "" ? "/" : path}`;
+        urls.push(url);
+      } else if (
+        options.static &&
+        typeof options.static === "object" &&
+        options.static.entries
+      ) {
+        for (const entry of options.static.entries) {
+          const path = this.buildPathFromParams(
+            options.path || "",
+            entry.params || {},
+          );
+          const url = `${normalizedBaseUrl}${path}`;
+          urls.push(url);
+        }
+      }
+    }
+
+    return this.buildSitemapXml(urls);
+  }
+
+  protected buildPathFromParams(
+    pathPattern: string,
+    params: Record<string, any>,
+  ): string {
+    let path = pathPattern;
+    for (const [key, value] of Object.entries(params)) {
+      path = path.replace(`:${key}`, String(value));
+    }
+    return path || "/";
+  }
+
+  protected buildSitemapXml(urls: string[]): string {
+    const lastMod = this.dateTime.now().format("YYYY-MM-DD");
+    const urlEntries = urls
+      .map(
+        (url) =>
+          `  <url>\n    <loc>${this.escapeXml(url)}</loc>\n    <lastmod>${lastMod}</lastmod>\n  </url>`,
+      )
+      .join("\n");
+
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${urlEntries}
+</urlset>`;
+  }
+
+  protected escapeXml(str: string): string {
+    return str
+      .replace(/&/g, "&amp;")
+      .replace(/</g, "&lt;")
+      .replace(/>/g, "&gt;")
+      .replace(/"/g, "&quot;")
+      .replace(/'/g, "&#39;");
+  }
+}
+
+$sitemap[KIND] = SitemapPrimitive;

package/src/server/auth/__tests__/appleClientSecret.spec.ts

@@ -0,0 +1,34 @@
+import {
+  decodeJwt,
+  decodeProtectedHeader,
+  exportPKCS8,
+  generateKeyPair,
+} from "jose";
+import { describe, expect, it } from "vitest";
+import { signAppleClientSecret } from "../helpers/appleClientSecret.ts";
+
+describe("apple client secret", () => {
+  it("signs an ES256 JWT with the Apple-required claims + kid header", async () => {
+    const { privateKey } = await generateKeyPair("ES256", {
+      crv: "P-256",
+      extractable: true,
+    });
+    const pem = await exportPKCS8(privateKey);
+    const secret = await signAppleClientSecret({
+      privateKeyPem: pem,
+      teamId: "TEAM123456",
+      serviceId: "club.alepha.signin",
+      keyId: "KEY1234567",
+    });
+    const claims = decodeJwt(secret);
+    expect(claims.iss).toBe("TEAM123456");
+    expect(claims.sub).toBe("club.alepha.signin");
+    expect(claims.aud).toBe("https://appleid.apple.com");
+    expect(typeof claims.exp).toBe("number");
+
+    // Apple requires ES256 + the Key ID in the protected header.
+    const header = decodeProtectedHeader(secret);
+    expect(header.alg).toBe("ES256");
+    expect(header.kid).toBe("KEY1234567");
+  });
+});

package/src/server/auth/__tests__/authFederationClient.spec.ts

@@ -0,0 +1,40 @@
+import { exportPKCS8, exportSPKI, generateKeyPair } from "jose";
+import { describe, expect, it } from "vitest";
+import { signFederationAssertion } from "../helpers/federationAssertion.ts";
+import { assertionToProfile } from "../primitives/$authFederationClient.ts";
+
+describe("federation client mapping", () => {
+  it("maps a verified assertion to a LinkAccountOptions profile", async () => {
+    const { privateKey, publicKey } = await generateKeyPair("EdDSA", {
+      crv: "Ed25519",
+      extractable: true,
+    });
+    const priv = await exportPKCS8(privateKey);
+    const pub = await exportSPKI(publicKey);
+    const token = await signFederationAssertion(
+      {
+        provider: "google",
+        sub: "g-1",
+        email: "x@y.z",
+        email_verified: true,
+        name: "X Y",
+      },
+      {
+        privateKeyPem: priv,
+        issuer: "https://alepha.club",
+        audience: "https://b14.alepha.club",
+      },
+    );
+    const { provider, link } = await assertionToProfile(token, {
+      publicKeyPem: pub,
+      issuer: "https://alepha.club",
+      audience: "https://b14.alepha.club",
+    });
+    expect(provider).toBe("google");
+    expect(link.user).toMatchObject({
+      sub: "g-1",
+      email: "x@y.z",
+      email_verified: true,
+    });
+  });
+});

package/src/server/auth/__tests__/federationAssertion.spec.ts

@@ -0,0 +1,146 @@
+import {
+  exportPKCS8,
+  exportSPKI,
+  generateKeyPair,
+  importPKCS8,
+  SignJWT,
+} from "jose";
+import { describe, expect, it } from "vitest";
+import {
+  type FederationProfile,
+  signFederationAssertion,
+  verifyFederationAssertion,
+} from "../helpers/federationAssertion.ts";
+
+const profile: FederationProfile = {
+  provider: "google",
+  sub: "google-123",
+  email: "p@example.com",
+  email_verified: true,
+  name: "Pat Player",
+};
+
+const keys = async () => {
+  const { privateKey, publicKey } = await generateKeyPair("EdDSA", {
+    crv: "Ed25519",
+    extractable: true,
+  });
+  return {
+    priv: await exportPKCS8(privateKey),
+    pub: await exportSPKI(publicKey),
+  };
+};
+
+describe("federation assertion", () => {
+  it("round-trips a signed assertion for the right audience", async () => {
+    const { priv, pub } = await keys();
+    const token = await signFederationAssertion(profile, {
+      privateKeyPem: priv,
+      issuer: "https://alepha.club",
+      audience: "https://b14.alepha.club",
+    });
+    const out = await verifyFederationAssertion(token, {
+      publicKeyPem: pub,
+      issuer: "https://alepha.club",
+      audience: "https://b14.alepha.club",
+    });
+    expect(out.profile).toMatchObject({
+      provider: "google",
+      sub: "google-123",
+      email: "p@example.com",
+    });
+    expect(out.jti).toBeTruthy();
+  });
+
+  it("rejects a wrong audience (tenant mismatch)", async () => {
+    const { priv, pub } = await keys();
+    const token = await signFederationAssertion(profile, {
+      privateKeyPem: priv,
+      issuer: "https://alepha.club",
+      audience: "https://b14.alepha.club",
+    });
+    await expect(
+      verifyFederationAssertion(token, {
+        publicKeyPem: pub,
+        issuer: "https://alepha.club",
+        audience: "https://other.alepha.club",
+      }),
+    ).rejects.toThrow();
+  });
+
+  it("rejects an expired assertion", async () => {
+    const { priv, pub } = await keys();
+    const token = await signFederationAssertion(profile, {
+      privateKeyPem: priv,
+      issuer: "https://alepha.club",
+      audience: "https://b14.alepha.club",
+      ttlSeconds: -1,
+    });
+    await expect(
+      verifyFederationAssertion(token, {
+        publicKeyPem: pub,
+        issuer: "https://alepha.club",
+        audience: "https://b14.alepha.club",
+      }),
+    ).rejects.toThrow();
+  });
+
+  it("rejects a tampered signature (verified by a different key)", async () => {
+    const { priv } = await keys();
+    const { pub: otherPub } = await keys();
+    const token = await signFederationAssertion(profile, {
+      privateKeyPem: priv,
+      issuer: "https://alepha.club",
+      audience: "https://b14.alepha.club",
+    });
+    await expect(
+      verifyFederationAssertion(token, {
+        publicKeyPem: otherPub,
+        issuer: "https://alepha.club",
+        audience: "https://b14.alepha.club",
+      }),
+    ).rejects.toThrow();
+  });
+
+  it("rejects an algorithm-confusion token (non-EdDSA alg)", async () => {
+    // Sign with HS256 using the SPKI bytes as a symmetric secret — the classic
+    // alg-confusion attack. The EdDSA pin must reject it.
+    const { pub } = await keys();
+    const forged = await new SignJWT({
+      profile,
+    })
+      .setProtectedHeader({ alg: "HS256", typ: "JWT" })
+      .setIssuer("https://alepha.club")
+      .setAudience("https://b14.alepha.club")
+      .setJti("forged")
+      .setIssuedAt()
+      .setExpirationTime("60s")
+      .sign(new TextEncoder().encode(pub));
+    await expect(
+      verifyFederationAssertion(forged, {
+        publicKeyPem: pub,
+        issuer: "https://alepha.club",
+        audience: "https://b14.alepha.club",
+      }),
+    ).rejects.toThrow();
+  });
+
+  it("rejects an assertion missing jti", async () => {
+    const { priv, pub } = await keys();
+    const key = await importPKCS8(priv, "EdDSA");
+    const noJti = await new SignJWT({ profile })
+      .setProtectedHeader({ alg: "EdDSA", typ: "JWT" })
+      .setIssuer("https://alepha.club")
+      .setAudience("https://b14.alepha.club")
+      .setIssuedAt()
+      .setExpirationTime("60s")
+      .sign(key);
+    await expect(
+      verifyFederationAssertion(noJti, {
+        publicKeyPem: pub,
+        issuer: "https://alepha.club",
+        audience: "https://b14.alepha.club",
+      }),
+    ).rejects.toThrow();
+  });
+});

package/src/server/auth/__tests__/federationRedirectReplay.spec.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from "vitest";
+import { JtiReplayGuard } from "../helpers/jtiReplayGuard.ts";
+import { safeRedirectPath } from "../helpers/safeRedirectPath.ts";
+
+describe("safeRedirectPath", () => {
+  it("keeps a simple absolute path", () => {
+    expect(safeRedirectPath("/me")).toBe("/me");
+    expect(safeRedirectPath("/admin/pages?x=1")).toBe("/admin/pages?x=1");
+  });
+
+  it("rejects protocol-relative, absolute, backslash, and empty → fallback", () => {
+    expect(safeRedirectPath("//evil.com")).toBe("/");
+    expect(safeRedirectPath("https://evil.com")).toBe("/");
+    expect(safeRedirectPath("/\\evil.com")).toBe("/");
+    expect(safeRedirectPath("evil")).toBe("/");
+    expect(safeRedirectPath(undefined)).toBe("/");
+    expect(safeRedirectPath(undefined, "/home")).toBe("/home");
+  });
+});
+
+describe("JtiReplayGuard", () => {
+  it("accepts a jti once, rejects the replay", () => {
+    const g = new JtiReplayGuard();
+    expect(g.check("a")).toBe(true);
+    expect(g.check("a")).toBe(false);
+    expect(g.check("b")).toBe(true);
+  });
+
+  it("accepts the same jti again once its TTL has elapsed", () => {
+    const g = new JtiReplayGuard(100); // 100ms TTL
+    expect(g.check("a", 1_000)).toBe(true);
+    expect(g.check("a", 1_050)).toBe(false); // still within TTL
+    expect(g.check("a", 2_000)).toBe(true); // expired → fresh again
+  });
+
+  it("stays bounded under churn (hard cap evicts oldest)", () => {
+    const g = new JtiReplayGuard(60_000, 5) as unknown as {
+      check: (j: string, n?: number) => boolean;
+      seen: Map<string, number>;
+    };
+    for (let i = 0; i < 50; i++) g.check(`j${i}`, 1_000);
+    expect(g.seen.size).toBeLessThanOrEqual(5);
+  });
+});

package/src/server/auth/helpers/appleClientSecret.ts

@@ -0,0 +1,24 @@
+import { importPKCS8, SignJWT } from "jose";
+
+export interface AppleClientSecretOptions {
+  privateKeyPem: string; // ES256 .p8 contents (PKCS#8 PEM)
+  teamId: string; // Apple Team ID  -> iss
+  serviceId: string; // Apple Service ID -> sub (the OAuth client_id)
+  keyId: string; // Apple Key ID -> header kid
+  ttlSeconds?: number; // default 300 (5 min)
+}
+
+/** Signs Apple's short-lived ES256 client_secret JWT on demand (no rotation job). */
+export async function signAppleClientSecret(
+  opts: AppleClientSecretOptions,
+): Promise<string> {
+  const key = await importPKCS8(opts.privateKeyPem, "ES256");
+  return new SignJWT({})
+    .setProtectedHeader({ alg: "ES256", kid: opts.keyId, typ: "JWT" })
+    .setIssuer(opts.teamId)
+    .setSubject(opts.serviceId)
+    .setAudience("https://appleid.apple.com")
+    .setIssuedAt()
+    .setExpirationTime(`${opts.ttlSeconds ?? 300}s`)
+    .sign(key);
+}

package/src/server/auth/helpers/federationAssertion.ts

@@ -0,0 +1,74 @@
+import { importPKCS8, importSPKI, jwtVerify, SignJWT } from "jose";
+
+const ALG = "EdDSA";
+
+export interface FederationProfile {
+  provider: "google" | "apple";
+  sub: string;
+  email?: string;
+  email_verified?: boolean;
+  name?: string;
+  given_name?: string;
+  family_name?: string;
+  picture?: string;
+  is_private_email?: boolean;
+}
+
+export interface SignAssertionOptions {
+  privateKeyPem: string; // EdDSA PKCS#8 PEM
+  issuer: string;
+  audience: string; // exact tenant origin
+  ttlSeconds?: number; // default 60
+  jti?: string; // default random
+}
+
+export interface VerifyAssertionOptions {
+  publicKeyPem: string; // EdDSA SPKI PEM
+  issuer: string;
+  audience: string;
+}
+
+export interface VerifiedAssertion {
+  profile: FederationProfile;
+  jti: string;
+}
+
+export async function signFederationAssertion(
+  profile: FederationProfile,
+  opts: SignAssertionOptions,
+): Promise<string> {
+  const key = await importPKCS8(opts.privateKeyPem, ALG);
+  const jti = opts.jti ?? crypto.randomUUID();
+  const ttl = opts.ttlSeconds ?? 60;
+  return new SignJWT({ profile })
+    .setProtectedHeader({ alg: ALG, typ: "JWT" })
+    .setIssuer(opts.issuer)
+    .setAudience(opts.audience)
+    .setJti(jti)
+    .setIssuedAt()
+    .setExpirationTime(`${ttl}s`)
+    .sign(key);
+}
+
+export async function verifyFederationAssertion(
+  token: string,
+  opts: VerifyAssertionOptions,
+): Promise<VerifiedAssertion> {
+  const key = await importSPKI(opts.publicKeyPem, ALG);
+  const { payload } = await jwtVerify(token, key, {
+    issuer: opts.issuer,
+    audience: opts.audience,
+    algorithms: [ALG],
+    // Defense-in-depth: reject a (signature-valid) token that omits any of
+    // these, so it can't slip an unbounded lifetime or an unreplayable id.
+    requiredClaims: ["exp", "iat", "jti"],
+  });
+  const profile = payload.profile as FederationProfile | undefined;
+  if (!profile?.sub || !profile.provider) {
+    throw new Error("Federation assertion missing profile.sub/provider");
+  }
+  if (!payload.jti) {
+    throw new Error("Federation assertion missing jti");
+  }
+  return { profile, jti: String(payload.jti) };
+}

package/src/server/auth/helpers/jtiReplayGuard.ts

@@ -0,0 +1,41 @@
+/**
+ * Single-use guard for short-lived assertion `jti`s. Bounded + self-pruning so
+ * it can't grow without limit in a long-lived process. Best-effort per-instance
+ * (assertions are also `aud`-bound + ~60s TTL, so a cross-isolate replay window
+ * is tiny); use a shared store if you need a hard cross-instance guarantee.
+ */
+export class JtiReplayGuard {
+  protected readonly seen = new Map<string, number>(); // jti -> expiry epoch ms
+
+  constructor(
+    protected readonly ttlMs = 120_000,
+    protected readonly maxEntries = 10_000,
+  ) {}
+
+  /** Records `jti` and returns true if fresh; false if already used (replay). */
+  check(jti: string, now: number = Date.now()): boolean {
+    this.prune(now);
+    if (this.seen.has(jti)) {
+      return false;
+    }
+    this.seen.set(jti, now + this.ttlMs);
+    return true;
+  }
+
+  protected prune(now: number): void {
+    for (const [k, exp] of this.seen) {
+      if (exp <= now) {
+        this.seen.delete(k);
+      }
+    }
+    // Hard cap: if still over budget after dropping expired, evict oldest-first
+    // (Map preserves insertion order).
+    while (this.seen.size >= this.maxEntries) {
+      const oldest = this.seen.keys().next().value;
+      if (oldest === undefined) {
+        break;
+      }
+      this.seen.delete(oldest);
+    }
+  }
+}

package/src/server/auth/helpers/safeRedirectPath.ts

@@ -0,0 +1,19 @@
+/**
+ * Returns a safe in-app redirect target: a single absolute path on the current
+ * origin. Rejects protocol-relative (`//host`), absolute URLs, and backslash
+ * tricks so a crafted `redirect` query can't become a post-auth open redirect.
+ */
+export function safeRedirectPath(
+  redirect: string | undefined,
+  fallback = "/",
+): string {
+  if (
+    typeof redirect === "string" &&
+    redirect.startsWith("/") &&
+    !redirect.startsWith("//") &&
+    !redirect.includes("\\")
+  ) {
+    return redirect;
+  }
+  return fallback;
+}

package/src/server/auth/index.ts

@@ -5,11 +5,15 @@ import { ServerAuthProvider } from "./providers/ServerAuthProvider.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 
+export * from "./helpers/appleClientSecret.ts";
+export * from "./helpers/federationAssertion.ts";
 export * from "./index.shared.ts";
 export * from "./primitives/$auth.ts";
 export * from "./primitives/$authApple.ts";
 export * from "./primitives/$authCredentials.ts";
 export * from "./primitives/$authFacebook.ts";
+export * from "./primitives/$authFederationBroker.ts";
+export * from "./primitives/$authFederationClient.ts";
 export * from "./primitives/$authFranceConnect.ts";
 export * from "./primitives/$authGithub.ts";
 export * from "./primitives/$authGoogle.ts";