alepha 0.22.0 → 0.24.0

package/src/security/atoms/currentTenantAtom.ts

@@ -1,4 +1,4 @@
-import { $atom, t } from "alepha";
+import { $atom, z } from "alepha";
 
 /**
  * Atom storing the active tenant for the current request.
@@ -24,11 +24,11 @@ import { $atom, t } from "alepha";
  */
 export const currentTenantAtom = $atom({
   name: "alepha.security.tenant",
-  schema: t.optional(
-    t.object({
-      id: t.text({
+  schema: z
+    .object({
+      id: z.text({
         description: "Tenant identifier (slug, UUID, or composite).",
       }),
-    }),
-  ),
+    })
+    .optional(),
 });

package/src/security/atoms/currentUserAtom.ts

@@ -1,4 +1,4 @@
-import { $atom, t } from "alepha";
+import { $atom } from "alepha";
 import { userAccountInfoSchema } from "../schemas/userAccountInfoSchema.ts";
 
 /**
@@ -9,5 +9,5 @@ import { userAccountInfoSchema } from "../schemas/userAccountInfoSchema.ts";
  */
 export const currentUserAtom = $atom({
   name: "alepha.security.user",
-  schema: t.optional(userAccountInfoSchema),
+  schema: userAccountInfoSchema.optional(),
 });

package/src/security/primitives/$issuer.ts

@@ -17,7 +17,7 @@ import type { JSONWebKeySet, JWTPayload } from "jose";
 import { currentTenantAtom } from "../atoms/currentTenantAtom.ts";
 import { SecurityError } from "../errors/SecurityError.ts";
 import type { IssuerResolver } from "../interfaces/IssuerResolver.ts";
-import { JwtProvider } from "../providers/JwtProvider.ts";
+import { JwtProvider, type SigningConfig } from "../providers/JwtProvider.ts";
 import { SecurityProvider } from "../providers/SecurityProvider.ts";
 import type { Role } from "../schemas/roleSchema.ts";
 import type { UserAccount } from "../schemas/userAccountInfoSchema.ts";
@@ -65,6 +65,13 @@ export type IssuerPrimitiveOptions = {
    * Custom resolvers (in addition to default JWT resolver).
    */
   resolvers?: IssuerResolver[];
+
+  /**
+   * Asymmetric signing config. When set, this issuer's tokens are signed with
+   * the given alg + kid and its public keys are published via JWKS. When
+   * omitted, the HS256 `secret` path is used (default, backward compatible).
+   */
+  signing?: SigningConfig;
 } & (IssuerInternal | IssuerExternal);
 
 export interface IssuerSettings {
@@ -173,6 +180,7 @@ export class IssuerPrimitive extends Primitive<IssuerPrimitiveOptions> {
       name: this.name,
       profile: this.options.profile,
       secret: "jwks" in this.options ? this.options.jwks : this.options.secret,
+      signing: this.options.signing,
       roles,
       resolvers: [],
     });
@@ -331,6 +339,18 @@ export class IssuerPrimitive extends Primitive<IssuerPrimitiveOptions> {
     // `viska.club.alepha.dev` even when the user belongs to both.
     const tenant = this.alepha.store.get(currentTenantAtom)?.id;
 
+    // Resilient display name: compose from first/last when the caller didn't
+    // provide one (credentials users register with first+last but no `name`),
+    // and carry the OIDC given/family claims so consumers can re-derive it —
+    // otherwise such users surface as "Anonymous User".
+    const composedName =
+      user.name ??
+      ([user.firstName, user.lastName]
+        .filter((s): s is string => !!s?.trim())
+        .join(" ")
+        .trim() ||
+        undefined);
+
     const access_token = await this.jwt.create(
       {
         // jwt
@@ -340,7 +360,9 @@ export class IssuerPrimitive extends Primitive<IssuerPrimitiveOptions> {
         aud: this.name,
         sid, // session id, if available
         // oidc
-        name: user.name,
+        name: composedName,
+        given_name: user.firstName,
+        family_name: user.lastName,
         email: user.email,
         preferred_username: user.username,
         picture: user.picture,

package/src/security/providers/JwtProvider.ts

@@ -6,8 +6,12 @@ import {
   type CryptoKey,
   createLocalJWKSet,
   createRemoteJWKSet,
+  exportJWK,
   type FlattenedJWSInput,
+  generateKeyPair,
+  importPKCS8,
   type JSONWebKeySet,
+  type JWK,
   type JWSHeaderParameters,
   type JWTHeaderParameters,
   type JWTPayload,
@@ -26,6 +30,7 @@ import { SecurityError } from "../errors/SecurityError.ts";
 export class JwtProvider {
   protected readonly log = $logger();
   protected readonly keystore: KeyLoaderHolder[] = [];
+  protected readonly signers = new Map<string, SignerHolder>();
   protected readonly dateTimeProvider = $inject(DateTimeProvider);
   protected readonly encoder = new TextEncoder();
 
@@ -61,6 +66,65 @@ export class JwtProvider {
     }
   }
 
+  /**
+   * Configure an asymmetric signing key for a realm/issuer. Tokens minted for
+   * `name` are then signed with `alg` + `kid`, and a local verify loader is
+   * registered so this process can verify its own tokens (refresh tokens,
+   * authorization codes, id_tokens). Public keys are published via `getJwks`.
+   *
+   * `privateKey` is a PKCS#8 PEM (from env). When it is empty/undefined an
+   * **ephemeral per-process keypair** is generated so dev/test work with no env
+   * key configured — the published JWKS still resolves; tokens just don't
+   * survive a restart. Additive: realms without a signing key keep the HS256
+   * path untouched.
+   */
+  public async setSigningKey(
+    name: string,
+    signing: SigningConfig,
+  ): Promise<void> {
+    const key = signing.privateKey
+      ? await importPKCS8(signing.privateKey, signing.alg, {
+          extractable: true,
+        })
+      : (await generateKeyPair(signing.alg, { extractable: true })).privateKey;
+    const exported = await exportJWK(key);
+    // Strip every private member so the published JWK is public-only.
+    const { d, p, q, dp, dq, qi, ...pub } = exported as Record<string, unknown>;
+    const publicJwk: JWK = {
+      ...(pub as JWK),
+      kid: signing.kid,
+      use: "sig",
+      alg: signing.alg,
+    };
+
+    this.signers.set(name, {
+      alg: signing.alg,
+      kid: signing.kid,
+      key,
+      publicJwk,
+    });
+
+    this.log.debug(`will sign + verify JWTs for '${name}'`, {
+      alg: signing.alg,
+      kid: signing.kid,
+    });
+
+    // Register a local verify loader so tokens we sign can be verified.
+    this.keystore.push({
+      name,
+      keyLoader: createLocalJWKSet({ keys: [publicJwk] }),
+    });
+  }
+
+  /**
+   * Public JWK Set for a realm/issuer configured with an asymmetric signing
+   * key. Returns an empty set for HS256 / external (URL-based) realms.
+   */
+  public async getJwks(name: string): Promise<JSONWebKeySet> {
+    const signer = this.signers.get(name);
+    return { keys: signer ? [signer.publicJwk] : [] };
+  }
+
   /**
    * Retrieves the payload from a JSON Web Token (JWT).
    *
@@ -133,6 +197,21 @@ export class JwtProvider {
     keyName?: string,
     signOptions?: JwtSignOptions,
   ): Promise<string> {
+    // Asymmetric path: when a signing key is configured for this realm, sign
+    // with its alg + kid so the token verifies against the published JWKS.
+    const signerName = keyName ?? this.keystore[0]?.name;
+    const signer = signerName ? this.signers.get(signerName) : undefined;
+    if (signer) {
+      const signJwt = new SignJWT(payload);
+      signJwt.setProtectedHeader({
+        alg: signer.alg,
+        kid: signer.kid,
+        ...signOptions?.header,
+      });
+      return await signJwt.sign(signer.key);
+    }
+
+    // HS256 path (unchanged default).
     const secretKey = keyName
       ? this.keystore.find((it) => it.name === keyName)?.secretKey
       : this.keystore[0]?.secretKey;
@@ -173,6 +252,27 @@ export interface KeyLoaderHolder {
   secretKey?: string;
 }
 
+export interface SignerHolder {
+  alg: string;
+  kid: string;
+  key: CryptoKey | KeyObject;
+  publicJwk: JWK;
+}
+
+/**
+ * Asymmetric signing config for a realm/issuer. `privateKey` is a PKCS#8 PEM
+ * (typically injected from env). EdDSA preferred; RS256 acceptable.
+ */
+export interface SigningConfig {
+  alg: "EdDSA" | "RS256";
+  /**
+   * PKCS#8 PEM private key. Empty/undefined → an ephemeral per-process keypair
+   * is generated (dev/test convenience; tokens don't survive a restart).
+   */
+  privateKey?: string;
+  kid: string;
+}
+
 export interface JwtSignOptions {
   header?: Partial<JWTHeaderParameters>;
 }

package/src/security/providers/SecurityProvider.ts

@@ -24,7 +24,7 @@ import {
   type UserAccount,
   userAccountInfoSchema,
 } from "../schemas/userAccountInfoSchema.ts";
-import { JwtProvider } from "./JwtProvider.ts";
+import { JwtProvider, type SigningConfig } from "./JwtProvider.ts";
 
 export class SecurityProvider {
   protected readonly UNKNOWN_USER_NAME = "Anonymous User";
@@ -72,7 +72,9 @@ export class SecurityProvider {
     on: "start",
     handler: async () => {
       for (const realm of this.realms) {
-        if (realm.secret) {
+        if (realm.signing) {
+          await this.jwt.setSigningKey(realm.name, realm.signing);
+        } else if (realm.secret) {
           const secret =
             typeof realm.secret === "function" ? realm.secret() : realm.secret;
           this.jwt.setKeyLoader(realm.name, secret);
@@ -313,6 +315,10 @@ export class SecurityProvider {
     const username = this.getUsernameFromPayload(payload);
     const picture = this.getPictureFromPayload(payload);
     const name = this.getNameFromPayload(payload);
+    const firstName =
+      typeof payload.given_name === "string" ? payload.given_name : undefined;
+    const lastName =
+      typeof payload.family_name === "string" ? payload.family_name : undefined;
     const organization = this.getOrganizationFromPayload(payload);
     const rolesFromSystem = this.getRoles(realmName);
     const roles = rolesFromPayload
@@ -332,6 +338,8 @@ export class SecurityProvider {
       id,
       roles,
       name,
+      firstName,
+      lastName,
       email,
       username,
       picture,
@@ -703,6 +711,32 @@ export class SecurityProvider {
     return this.realms;
   }
 
+  /**
+   * Resolve the realm an authenticated admin action is allowed to operate on.
+   *
+   * Admin endpoints accept a client-supplied target realm (e.g. a
+   * `userRealmName` query param). Without scoping, a realm-A admin could act on
+   * realm-B resources by simply naming realm B — a cross-tenant escalation
+   * whenever realms are used as tenant boundaries. This binds the target realm
+   * to the caller's own realm: omitting the target means "my realm"; naming a
+   * *different* realm than the caller's is refused.
+   *
+   * Returns the effective realm to use (may be `undefined` in single-realm apps
+   * where neither the caller nor the request carries a realm).
+   */
+  public assertRealmScope(
+    user: { realm?: string } | undefined,
+    requestedRealm: string | undefined,
+  ): string | undefined {
+    const callerRealm = user?.realm;
+    if (requestedRealm && callerRealm && requestedRealm !== callerRealm) {
+      throw new ForbiddenError(
+        `Cross-realm access denied: authenticated in realm '${callerRealm}', requested realm '${requestedRealm}'.`,
+      );
+    }
+    return requestedRealm ?? callerRealm;
+  }
+
   /**
    * Retrieves the user account from the provided user ID.
    *
@@ -983,6 +1017,13 @@ export interface Realm {
    */
   secret?: string | JSONWebKeySet | (() => string);
 
+  /**
+   * Asymmetric signing config. When set, this realm signs its tokens with an
+   * asymmetric key and publishes the public keys via JWKS (see
+   * `JwtProvider.getJwks`). Takes precedence over `secret`.
+   */
+  signing?: SigningConfig;
+
   /**
    * Create the user account info based on the raw JWT payload.
    * By default, SecurityProvider has his own implementation, but this method allow to override it.

package/src/security/schemas/permissionSchema.ts

@@ -1,36 +1,36 @@
 import type { Static } from "alepha";
-import { t } from "alepha";
+import { z } from "alepha";
 
-export const permissionSchema = t.object({
-  name: t.text({
+export const permissionSchema = z.object({
+  name: z.text({
     description: "Name of the permission.",
   }),
 
-  group: t.optional(
-    t.text({
+  group: z
+    .text({
       description: "Group of the permission.",
-    }),
-  ),
+    })
+    .optional(),
 
-  description: t.optional(
-    t.text({
+  description: z
+    .text({
       description: "Describe the permission.",
-    }),
-  ),
+    })
+    .optional(),
 
   // HTTP Only
 
-  method: t.optional(
-    t.text({
+  method: z
+    .text({
       description: "HTTP method of the permission. When available.",
-    }),
-  ),
+    })
+    .optional(),
 
-  path: t.optional(
-    t.text({
+  path: z
+    .text({
       description: "Pathname of the permission. When available.",
-    }),
-  ),
+    })
+    .optional(),
 });
 
 export type Permission = Static<typeof permissionSchema>;

package/src/security/schemas/roleSchema.ts

@@ -1,41 +1,35 @@
 import type { Static } from "alepha";
-import { t } from "alepha";
+import { z } from "alepha";
 
-export const roleSchema = t.object({
-  name: t.text({
+export const roleSchema = z.object({
+  name: z.text({
     description: "Name of the role.",
   }),
 
-  description: t.optional(
-    t.text({
+  description: z
+    .text({
       description: "Describe the role.",
-    }),
-  ),
+    })
+    .optional(),
 
-  default: t.optional(
-    t.boolean({
-      description:
-        "If true, this role will be assigned to all users by default.",
-    }),
-  ),
+  default: z
+    .boolean()
+    .describe("If true, this role will be assigned to all users by default.")
+    .optional(),
 
-  permissions: t.array(
-    t.object({
-      name: t.text({
+  permissions: z.array(
+    z.object({
+      name: z.text({
         description: "Name of the permission.",
       }),
-      ownership: t.optional(
-        t.boolean({
-          description:
-            "If true, user will only have access to it's own resources.",
-        }),
-      ),
-      exclude: t.optional(
-        t.array(t.text(), {
-          description:
-            "Exclude some permissions. Useful when 'name' is a wildcard.",
-        }),
-      ),
+      ownership: z
+        .boolean()
+        .describe("If true, user will only have access to it's own resources.")
+        .optional(),
+      exclude: z
+        .array(z.text())
+        .describe("Exclude some permissions. Useful when 'name' is a wildcard.")
+        .optional(),
     }),
   ),
 });

package/src/security/schemas/userAccountInfoSchema.ts

@@ -1,61 +1,71 @@
 import type { Static } from "alepha";
-import { t } from "alepha";
+import { z } from "alepha";
 
-export const userAccountInfoSchema = t.object({
-  id: t.text({
+export const userAccountInfoSchema = z.object({
+  id: z.text({
     description: "Unique identifier for the user.",
   }),
 
-  name: t.optional(
-    t.text({
+  name: z
+    .text({
       description: "Full name of the user.",
-    }),
-  ),
+    })
+    .optional(),
 
-  email: t.optional(
-    t.text({
+  firstName: z
+    .text({
+      description: "Given name of the user (OIDC `given_name`).",
+    })
+    .optional(),
+
+  lastName: z
+    .text({
+      description: "Family name of the user (OIDC `family_name`).",
+    })
+    .optional(),
+
+  email: z
+    .text({
       description: "Email address of the user.",
       format: "email",
-    }),
-  ),
+    })
+    .optional(),
 
-  username: t.optional(
-    t.text({
+  username: z
+    .text({
       description: "Preferred username of the user.",
-    }),
-  ),
+    })
+    .optional(),
 
-  picture: t.optional(
-    t.text({
+  picture: z
+    .text({
       description: "URL to the user's profile picture.",
-    }),
-  ),
+    })
+    .optional(),
 
-  sessionId: t.optional(
-    t.text({
+  sessionId: z
+    .text({
       description: "Session identifier for the user, if applicable.",
-    }),
-  ),
+    })
+    .optional(),
 
   // -------------------------------------------------------------------------------------------------------------------
 
-  organization: t.optional(
-    t.uuid({
-      description: "Organization the user belongs to.",
-    }),
-  ),
+  organization: z
+    .uuid()
+    .describe("Organization the user belongs to.")
+    .optional(),
 
-  roles: t.optional(
-    t.array(t.text(), {
-      description: "List of roles assigned to the user.",
-    }),
-  ),
+  roles: z
+    .array(z.text())
+    .describe("List of roles assigned to the user.")
+    .optional(),
 
-  realm: t.optional(
-    t.text({
+  realm: z
+    .text({
       description: "The realm (issuer) the user was authenticated from.",
-    }),
-  ),
+    })
+    .optional(),
 });
 
 export type UserAccount = Static<typeof userAccountInfoSchema>;

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__/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);
+}