alepha 0.23.0 → 0.24.0

package/src/api/notifications/schemas/notificationDetailResourceSchema.ts

@@ -1,19 +1,17 @@
-import { type Static, t } from "alepha";
+import { type Static, z } from "alepha";
 import { logEntrySchema } from "alepha/logger";
 import { notificationResourceSchema } from "./notificationResourceSchema.ts";
 
-export const notificationDetailResourceSchema = t.extend(
-  notificationResourceSchema,
-  {
-    variables: t.optional(t.record(t.text(), t.any())),
-    rendered: t.optional(t.record(t.text(), t.any())),
-    logs: t.optional(t.array(logEntrySchema)),
-  },
-  {
+export const notificationDetailResourceSchema = notificationResourceSchema
+  .extend({
+    variables: z.record(z.text(), z.any()).optional(),
+    rendered: z.record(z.text(), z.any()).optional(),
+    logs: z.array(logEntrySchema).optional(),
+  })
+  .meta({
     title: "NotificationDetailResource",
     description: "A notification resource with rendered content and logs.",
-  },
-);
+  });
 
 export type NotificationDetailResource = Static<
   typeof notificationDetailResourceSchema

package/src/api/notifications/schemas/notificationPayloadSchema.ts

@@ -1,13 +1,15 @@
-import { type Static, t } from "alepha";
+import { type Static, z } from "alepha";
 
-export const notificationPayloadSchema = t.object({
-  type: t.enum(["email", "sms"]),
-  template: t.text(),
-  contact: t.text(),
-  variables: t.optional(t.record(t.text(), t.any())),
-  category: t.optional(t.text()),
-  critical: t.optional(t.boolean()),
-  sensitive: t.optional(t.boolean()),
+export const notificationPayloadSchema = z.object({
+  type: z.enum(["email", "sms"]),
+  template: z.text(),
+  contact: z.text(),
+  variables: z.record(z.text(), z.any()).optional(),
+  category: z.text().optional(),
+  critical: z.boolean().optional(),
+  sensitive: z.boolean().optional(),
+  /** Recipient language (e.g. "fr" or "fr-FR") used to pick `translations`. */
+  lang: z.text().optional(),
 });
 
 export type NotificationPayload = Static<typeof notificationPayloadSchema>;

package/src/api/notifications/schemas/notificationQuerySchema.ts

@@ -1,9 +1,9 @@
-import { type Static, t } from "alepha";
+import { type Static, z } from "alepha";
 import { pageQuerySchema } from "alepha/orm";
 
-export const notificationQuerySchema = t.extend(pageQuerySchema, {
-  status: t.optional(
-    t.enum([
+export const notificationQuerySchema = pageQuerySchema.extend({
+  status: z
+    .enum([
       "pending",
       "scheduled",
       "retrying",
@@ -11,8 +11,8 @@ export const notificationQuerySchema = t.extend(pageQuerySchema, {
       "completed",
       "dead",
       "cancelled",
-    ]),
-  ),
+    ])
+    .optional(),
 });
 
 export type NotificationQuery = Static<typeof notificationQuerySchema>;

package/src/api/notifications/schemas/notificationResourceSchema.ts

@@ -1,18 +1,18 @@
-import { type Static, t } from "alepha";
+import { type Static, z } from "alepha";
 
-export const notificationResourceSchema = t.object({
-  id: t.uuid(),
-  createdAt: t.datetime(),
-  status: t.text(),
-  template: t.optional(t.text()),
-  type: t.optional(t.text()),
-  contact: t.optional(t.text()),
-  category: t.optional(t.text()),
-  critical: t.optional(t.boolean()),
-  sensitive: t.optional(t.boolean()),
-  startedAt: t.optional(t.datetime()),
-  completedAt: t.optional(t.datetime()),
-  error: t.optional(t.text()),
+export const notificationResourceSchema = z.object({
+  id: z.uuid(),
+  createdAt: z.datetime(),
+  status: z.text(),
+  template: z.text().optional(),
+  type: z.text().optional(),
+  contact: z.text().optional(),
+  category: z.text().optional(),
+  critical: z.boolean().optional(),
+  sensitive: z.boolean().optional(),
+  startedAt: z.datetime().optional(),
+  completedAt: z.datetime().optional(),
+  error: z.text().optional(),
 });
 
 export type NotificationResource = Static<typeof notificationResourceSchema>;

package/src/api/notifications/services/NotificationSenderService.ts

@@ -5,6 +5,14 @@ import { SmsProvider } from "alepha/sms";
 import { $notification } from "../primitives/$notification.ts";
 import type { NotificationPayload } from "../schemas/notificationPayloadSchema.ts";
 
+type NotificationMessageEmail = {
+  subject: string;
+  body: string | ((variables: any) => string);
+};
+type NotificationMessageSms = {
+  message: string | ((variables: any) => string);
+};
+
 export class NotificationSenderService {
   protected readonly alepha = $inject(Alepha);
   protected readonly log = $logger();
@@ -51,7 +59,9 @@ export class NotificationSenderService {
   public renderSms(payload: NotificationPayload) {
     const { variables, contact, template } = this.load(payload);
 
-    const sms = template.options.sms;
+    const sms =
+      this.translation(template.options, payload.lang)?.sms ??
+      template.options.sms;
     if (!sms) {
       throw new AlephaError(
         `Notification template ${payload.template} has no sms defined`,
@@ -69,7 +79,9 @@ export class NotificationSenderService {
   public renderEmail(payload: NotificationPayload) {
     const { variables, contact, template } = this.load(payload);
 
-    const email = template.options.email;
+    const email =
+      this.translation(template.options, payload.lang)?.email ??
+      template.options.email;
     if (!email) {
       throw new AlephaError(
         `Notification template ${payload.template} has no email defined`,
@@ -85,6 +97,30 @@ export class NotificationSenderService {
     return { to: contact, subject, body };
   }
 
+  /**
+   * Pick the template's `translations` entry for the payload language:
+   * exact match ("fr-FR") first, then the base language ("fr"). Returns
+   * undefined when there is no match — callers fall back to the default
+   * (template-level) message.
+   */
+  protected translation(
+    options: {
+      translations?: Record<
+        string,
+        { email?: unknown; sms?: unknown } | undefined
+      >;
+    },
+    lang?: string,
+  ):
+    | { email?: NotificationMessageEmail; sms?: NotificationMessageSms }
+    | undefined {
+    if (!lang || !options.translations) return undefined;
+    const exact = options.translations[lang];
+    if (exact) return exact as any;
+    const base = lang.split("-")[0]?.toLowerCase();
+    return base ? (options.translations[base] as any) : undefined;
+  }
+
   protected load(payload: NotificationPayload) {
     const variables = payload.variables || {};
     const contact = payload.contact;

package/src/api/oauth/__tests__/OAuthClientService.spec.ts

@@ -55,6 +55,48 @@ describe("OAuthClientService.register", () => {
   });
 });
 
+describe("OAuthClientService.intersectScopes", () => {
+  const setup = async () => {
+    const alepha = Alepha.create().with(AlephaOrmPostgres);
+    const service = alepha.inject(OAuthClientService);
+    await alepha.start();
+    return service;
+  };
+
+  it("drops requested scopes the client is not registered for", async ({
+    expect,
+  }) => {
+    const service = await setup();
+    // Client registered for ["mcp"] but asks for admin → admin is stripped.
+    expect(service.intersectScopes(["mcp", "admin"], ["mcp"])).toEqual(["mcp"]);
+  });
+
+  it("falls back to the client's registered scopes when none requested", async ({
+    expect,
+  }) => {
+    const service = await setup();
+    expect(service.intersectScopes(undefined, ["mcp", "openid"])).toEqual([
+      "mcp",
+      "openid",
+    ]);
+    expect(service.intersectScopes([], ["mcp"])).toEqual(["mcp"]);
+  });
+
+  it("preserves requested order and de-duplicates", async ({ expect }) => {
+    const service = await setup();
+    expect(
+      service.intersectScopes(["openid", "mcp", "openid"], ["mcp", "openid"]),
+    ).toEqual(["openid", "mcp"]);
+  });
+
+  it("returns nothing when no requested scope is allowed", async ({
+    expect,
+  }) => {
+    const service = await setup();
+    expect(service.intersectScopes(["admin"], ["mcp"])).toEqual([]);
+  });
+});
+
 describe("OAuthClientService authorization code", () => {
   it("mints and verifies a single-use auth code bound to PKCE", async ({
     expect,

package/src/api/oauth/__tests__/OAuthController.spec.ts

@@ -231,3 +231,131 @@ describe("OAuthController authorize + token", () => {
     expect(body.error).toBe("unsupported_grant_type");
   });
 });
+
+describe("OAuthController refresh_token grant", () => {
+  /**
+   * Boot a server with a **session-backed** issuer (like the platform IdP
+   * realm, which wires `onCreateSession`/`onRefreshSession` via
+   * `alepha/api/users`). Token-only issuers can't refresh through the endpoint
+   * (the old access token isn't carried), so a session store is required to
+   * exercise the refresh grant end-to-end.
+   */
+  const boot = async () => {
+    const sessions = new Map<string, string>(); // refresh_token -> userId
+
+    class App {
+      issuer = $issuer({
+        name: "users",
+        secret: "test-secret",
+        settings: {
+          onCreateSession: async (user) => {
+            const refreshToken = randomUUID();
+            sessions.set(refreshToken, user.id);
+            return { refreshToken, sessionId: randomUUID() };
+          },
+          onRefreshSession: async (refreshToken) => {
+            const userId = sessions.get(refreshToken);
+            if (!userId) throw new Error("unknown refresh token");
+            return {
+              user: { id: userId, roles: [] } as UserAccount,
+              expiresIn: 3600,
+            };
+          },
+        },
+      });
+    }
+
+    const alepha = Alepha.create()
+      .with(AlephaServer)
+      .with(AlephaOrmPostgres)
+      .with(AlephaOAuth);
+    alepha.set(oauthOptions, {
+      realm: "users",
+      resource: "/mcp",
+      loginPath: "/login",
+    });
+
+    const app = alepha.inject(App);
+    await alepha.start();
+
+    const service = alepha.inject(OAuthClientService);
+    service.registerIssuer(
+      "users",
+      app.issuer,
+      async (id) => ({ id, roles: [] }) as UserAccount,
+    );
+
+    const { hostname } = alepha.inject(ServerProvider);
+    return { hostname, service };
+  };
+
+  const registerClient = async (
+    hostname: string,
+    redirectUri: string,
+  ): Promise<string> => {
+    const resp = await fetch(`${hostname}/oauth/register`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        client_name: "Test Client",
+        redirect_uris: [redirectUri],
+      }),
+    });
+    const body = (await resp.json()) as Record<string, string>;
+    return body.client_id;
+  };
+
+  it("re-mints an id_token on the refresh grant for openid clients", async ({
+    expect,
+  }) => {
+    const { hostname, service } = await boot();
+    const redirectUri = "https://claude.ai/api/mcp/auth_callback";
+    const clientId = await registerClient(hostname, redirectUri);
+
+    const verifier = "the-code-verifier-value-1234567890";
+    const challenge = createHash("sha256").update(verifier).digest("base64url");
+    const userId = randomUUID();
+
+    // 1) authorization_code exchange → access + refresh + id token.
+    const code = await service.createAuthorizationCode("users", {
+      userId,
+      clientId,
+      redirectUri,
+      codeChallenge: challenge,
+      scopes: ["openid"],
+    });
+    const tokenResp = await fetch(`${hostname}/oauth/token`, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        grant_type: "authorization_code",
+        code,
+        client_id: clientId,
+        redirect_uri: redirectUri,
+        code_verifier: verifier,
+      }).toString(),
+    });
+    expect(tokenResp.status).toBe(200);
+    const tokenBody = (await tokenResp.json()) as Record<string, string>;
+    expect(typeof tokenBody.refresh_token).toBe("string");
+    expect(typeof tokenBody.id_token).toBe("string");
+
+    // 2) refresh_token grant — MUST return a fresh id_token so an id_token-based
+    //    relying party (the stateless Club RP forwards the id_token as Bearer)
+    //    actually renews its identity, not just the access token.
+    const refreshResp = await fetch(`${hostname}/oauth/token`, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        grant_type: "refresh_token",
+        refresh_token: tokenBody.refresh_token,
+        client_id: clientId,
+      }).toString(),
+    });
+    expect(refreshResp.status).toBe(200);
+    const refreshBody = (await refreshResp.json()) as Record<string, string>;
+    expect(typeof refreshBody.access_token).toBe("string");
+    expect(refreshBody.token_type).toBe("Bearer");
+    expect(typeof refreshBody.id_token).toBe("string");
+  });
+});

package/src/api/oauth/controllers/OAuthController.ts

@@ -1,11 +1,13 @@
-import { $atom, $inject, $state, t } from "alepha";
+import { $atom, $inject, $state, z } from "alepha";
 import { $logger } from "alepha/logger";
+import { JwtProvider } from "alepha/security";
 import { $route } from "alepha/server";
 import { renderConsentPage } from "../helpers/consentPage.ts";
 import {
   buildAuthorizationServerMetadata,
   buildProtectedResourceMetadata,
 } from "../helpers/oauthMetadata.ts";
+import { buildOpenIdConfiguration } from "../helpers/oidcMetadata.ts";
 import { authorizeDecisionBodySchema } from "../schemas/authorizeDecisionBodySchema.ts";
 import { authorizeQuerySchema } from "../schemas/authorizeQuerySchema.ts";
 import { registerClientBodySchema } from "../schemas/registerClientBodySchema.ts";
@@ -22,10 +24,10 @@ import { OAuthClientService } from "../services/OAuthClientService.ts";
 export const oauthOptions = $atom({
   name: "alepha.api.oauth.options",
   description: "Configuration for the OAuth authorization server.",
-  schema: t.object({
-    realm: t.text({ default: "users" }),
-    resource: t.text({ default: "/mcp" }),
-    loginPath: t.text({ default: "/login" }),
+  schema: z.object({
+    realm: z.text({ default: "users" }),
+    resource: z.text({ default: "/mcp" }),
+    loginPath: z.text({ default: "/login" }),
   }),
   default: { realm: "users", resource: "/mcp", loginPath: "/login" },
 });
@@ -39,6 +41,7 @@ export class OAuthController {
   protected readonly log = $logger();
   protected readonly options = $state(oauthOptions);
   protected readonly clients = $inject(OAuthClientService);
+  protected readonly jwt = $inject(JwtProvider);
 
   /**
    * Absolute origin of the current request, e.g. https://app.com.
@@ -70,6 +73,24 @@ export class OAuthController {
     },
   });
 
+  openidConfiguration = $route({
+    method: "GET",
+    path: "/.well-known/openid-configuration",
+    handler: ({ url, reply }) => {
+      reply.headers["content-type"] = "application/json";
+      reply.body = JSON.stringify(buildOpenIdConfiguration(this.baseUrl(url)));
+    },
+  });
+
+  jwks = $route({
+    method: "GET",
+    path: "/oauth/jwks",
+    handler: async ({ reply }) => {
+      reply.headers["content-type"] = "application/json";
+      reply.body = JSON.stringify(await this.jwt.getJwks(this.options.realm));
+    },
+  });
+
   register = $route({
     method: "POST",
     path: "/oauth/register",
@@ -129,7 +150,22 @@ export class OAuthController {
         reply.body = "redirect_uri not registered";
         return;
       }
+      const silent = query.prompt === "none";
+      // Skip the consent screen for `prompt=none` (silent SSO) AND for trusted
+      // first-party clients (the AS's own product — consent is for third-party
+      // apps). A non-silent trusted client still sends an unauthenticated user
+      // through login first; it just never shows the "wants to connect" page.
+      const skipConsent = silent || client.trusted === true;
+
       if (!user) {
+        if (silent) {
+          // Silent SSO with no IdP session → OIDC `login_required`.
+          const redirect = new URL(query.redirect_uri);
+          redirect.searchParams.set("error", "login_required");
+          if (query.state) redirect.searchParams.set("state", query.state);
+          reply.redirect(redirect.toString(), 302);
+          return;
+        }
         const returnTo = encodeURIComponent(url.pathname + url.search);
         reply.redirect(
           `${this.options.loginPath}?redirect_uri=${returnTo}`,
@@ -137,11 +173,42 @@ export class OAuthController {
         );
         return;
       }
+
+      if (skipConsent) {
+        // Authenticated + (prompt=none OR trusted client) → skip consent and
+        // mint the code directly (silent SSO + first-party login).
+        const code = await this.clients.createAuthorizationCode(
+          this.options.realm,
+          {
+            userId: user.id,
+            clientId: query.client_id,
+            redirectUri: query.redirect_uri,
+            codeChallenge: query.code_challenge,
+            scopes: this.clients.intersectScopes(
+              query.scope?.split(" "),
+              client.scopes,
+            ),
+            resource: query.resource || undefined,
+            nonce: query.nonce,
+          },
+        );
+        const redirect = new URL(query.redirect_uri);
+        redirect.searchParams.set("code", code);
+        if (query.state) redirect.searchParams.set("state", query.state);
+        reply.redirect(redirect.toString(), 302);
+        return;
+      }
+
       reply.headers["content-type"] = "text/html; charset=utf-8";
       reply.body = renderConsentPage({
         clientName: client.clientName,
         userName: user.name ?? user.email ?? "your account",
-        scopes: query.scope ? query.scope.split(" ") : client.scopes,
+        // Show the user the scopes they will actually grant, not the raw
+        // (possibly over-broad) request.
+        scopes: this.clients.intersectScopes(
+          query.scope?.split(" "),
+          client.scopes,
+        ),
         hidden: {
           response_type: query.response_type,
           client_id: query.client_id,
@@ -151,6 +218,7 @@ export class OAuthController {
           scope: query.scope ?? "",
           state: query.state ?? "",
           resource: query.resource ?? "",
+          nonce: query.nonce ?? "",
         },
       });
     },
@@ -201,8 +269,12 @@ export class OAuthController {
           clientId: body.client_id,
           redirectUri: body.redirect_uri,
           codeChallenge: body.code_challenge,
-          scopes: body.scope ? body.scope.split(" ") : client.scopes,
+          scopes: this.clients.intersectScopes(
+            body.scope?.split(" "),
+            client.scopes,
+          ),
           resource: body.resource || undefined,
+          nonce: body.nonce,
         },
       );
       redirect.searchParams.set("code", code);
@@ -222,10 +294,29 @@ export class OAuthController {
     path: "/oauth/token",
     schema: { body: tokenRequestBodySchema },
     use: [],
-    handler: async ({ body, reply }) => {
+    handler: async ({ body, url, reply }) => {
       reply.headers["content-type"] = "application/json";
       try {
         if (body.grant_type === "authorization_code") {
+          const client = await this.clients.findByClientId(
+            body.client_id ?? "",
+          );
+          if (!client || client.revokedAt) {
+            reply.status = 400;
+            reply.body = JSON.stringify({ error: "invalid_client" });
+            return;
+          }
+          if (client.type === "confidential") {
+            const ok = await this.clients.verifySecret(
+              client.clientId,
+              body.client_secret ?? "",
+            );
+            if (!ok) {
+              reply.status = 401;
+              reply.body = JSON.stringify({ error: "invalid_client" });
+              return;
+            }
+          }
           const grant = await this.clients.consumeAuthorizationCode(
             this.options.realm,
             body.code ?? "",
@@ -239,13 +330,25 @@ export class OAuthController {
             this.options.realm,
             { ...grant, clientId: body.client_id ?? "" },
           );
-          reply.body = JSON.stringify({
+          const response: Record<string, unknown> = {
             access_token: tokens.access_token,
             token_type: "Bearer",
             expires_in: tokens.expires_in,
             refresh_token: tokens.refresh_token,
             scope: grant.scopes.join(" "),
-          });
+          };
+          if (grant.scopes.includes("openid")) {
+            response.id_token = await this.clients.issueIdToken(
+              this.options.realm,
+              {
+                userId: grant.userId,
+                clientId: body.client_id ?? "",
+                issuer: this.baseUrl(url),
+                nonce: grant.nonce,
+              },
+            );
+          }
+          reply.body = JSON.stringify(response);
           return;
         }
 
@@ -254,12 +357,29 @@ export class OAuthController {
             this.options.realm,
             body.refresh_token ?? "",
           );
-          reply.body = JSON.stringify({
+          const response: Record<string, unknown> = {
             access_token: tokens.access_token,
             token_type: "Bearer",
             expires_in: tokens.expires_in,
             refresh_token: tokens.refresh_token,
-          });
+          };
+          // Re-mint an OIDC `id_token` so id_token-based relying parties (e.g. a
+          // stateless OIDC RP that forwards the id_token as the request Bearer)
+          // actually renew their identity on refresh — without it the RP keeps
+          // forwarding the now-expired id_token and every call 401s. Per OIDC
+          // Core §12.2 the refreshed id_token carries no `nonce`; `sub` is
+          // unchanged. Requires `client_id` to set the `aud`.
+          if (body.client_id) {
+            response.id_token = await this.clients.issueIdToken(
+              this.options.realm,
+              {
+                userId: tokens.userId,
+                clientId: body.client_id,
+                issuer: this.baseUrl(url),
+              },
+            );
+          }
+          reply.body = JSON.stringify(response);
           return;
         }
 

package/src/api/oauth/entities/oauthClientEntity.ts

@@ -1,4 +1,4 @@
-import { type Static, t } from "alepha";
+import { type Static, z } from "alepha";
 import { $entity, db } from "alepha/orm";
 
 /**
@@ -11,19 +11,36 @@ import { $entity, db } from "alepha/orm";
  */
 export const oauthClientEntity = $entity({
   name: "oauth_clients",
-  schema: t.object({
-    id: db.primaryKey(t.uuid()),
+  schema: z.object({
+    id: db.primaryKey(z.uuid()),
     createdAt: db.createdAt(),
     updatedAt: db.updatedAt(),
-    clientId: t.text({ maxLength: 64 }),
-    clientName: t.text({ maxLength: 200 }),
-    redirectUris: db.default(t.array(t.text({ maxLength: 2048 })), []),
-    scopes: db.default(t.array(t.text({ maxLength: 64 })), []),
-    realm: t.text({ maxLength: 100 }),
-    source: db.default(t.text({ maxLength: 16 }), "dcr"),
-    createdByUserId: t.optional(t.uuid()),
-    lastUsedAt: t.optional(t.datetime()),
-    revokedAt: t.optional(t.datetime()),
+    clientId: z.text({ maxLength: 64 }),
+    clientName: z.text({ maxLength: 200 }),
+    redirectUris: db.default(z.array(z.text({ maxLength: 2048 })), []),
+    scopes: db.default(z.array(z.text({ maxLength: 64 })), []),
+    realm: z.text({ maxLength: 100 }),
+    /**
+     * OAuth client type. `confidential` clients authenticate at the token
+     * endpoint with a secret; `public` clients rely on PKCE only.
+     */
+    type: db.default(z.enum(["public", "confidential"]), "public"),
+    /**
+     * First-party client: skip the consent screen. Consent exists to protect a
+     * user from THIRD-party apps requesting their data; a trusted client is the
+     * authorization server's own product (same vendor), so an authenticated
+     * user is sent straight back with a code — no "App X wants to connect" page.
+     */
+    trusted: db.default(z.boolean(), false),
+    /**
+     * Scrypt hash of the client secret (confidential clients only). Null for
+     * public clients. Verified via `OAuthClientService.verifySecret`.
+     */
+    clientSecretHash: z.text({ maxLength: 256 }).optional(),
+    source: db.default(z.text({ maxLength: 16 }), "dcr"),
+    createdByUserId: z.uuid().optional(),
+    lastUsedAt: z.datetime().optional(),
+    revokedAt: z.datetime().optional(),
   }),
   indexes: [{ columns: ["clientId"], unique: true }],
 });

package/src/api/oauth/helpers/oauthMetadata.ts

@@ -7,6 +7,7 @@ export const buildAuthorizationServerMetadata = (baseUrl: string) => ({
   authorization_endpoint: `${baseUrl}/oauth/authorize`,
   token_endpoint: `${baseUrl}/oauth/token`,
   registration_endpoint: `${baseUrl}/oauth/register`,
+  jwks_uri: `${baseUrl}/oauth/jwks`,
   response_types_supported: ["code"],
   grant_types_supported: ["authorization_code", "refresh_token"],
   code_challenge_methods_supported: ["S256"],