alepha 0.22.0 → 0.24.0

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

@@ -0,0 +1,19 @@
+/**
+ * OpenID Connect Discovery 1.0 — provider metadata document
+ * (`/.well-known/openid-configuration`). `baseUrl` is the absolute origin of
+ * the OIDC provider (e.g. https://alepha.club).
+ */
+export const buildOpenIdConfiguration = (baseUrl: string) => ({
+  issuer: baseUrl,
+  authorization_endpoint: `${baseUrl}/oauth/authorize`,
+  token_endpoint: `${baseUrl}/oauth/token`,
+  jwks_uri: `${baseUrl}/oauth/jwks`,
+  registration_endpoint: `${baseUrl}/oauth/register`,
+  response_types_supported: ["code"],
+  grant_types_supported: ["authorization_code", "refresh_token"],
+  subject_types_supported: ["public"],
+  id_token_signing_alg_values_supported: ["EdDSA", "RS256"],
+  code_challenge_methods_supported: ["S256"],
+  token_endpoint_auth_methods_supported: ["none", "client_secret_post"],
+  scopes_supported: ["openid", "email", "profile"],
+});

package/src/api/oauth/index.ts

@@ -8,6 +8,7 @@ export {
 } from "./controllers/OAuthController.ts";
 export type { OAuthClientEntity } from "./entities/oauthClientEntity.ts";
 export { oauthClientEntity } from "./entities/oauthClientEntity.ts";
+export { buildOpenIdConfiguration } from "./helpers/oidcMetadata.ts";
 export type { RegisterClientOptions } from "./services/OAuthClientService.ts";
 export { OAuthClientService } from "./services/OAuthClientService.ts";
 

package/src/api/oauth/schemas/authorizeDecisionBodySchema.ts

@@ -1,18 +1,19 @@
-import { t } from "alepha";
+import { z } from "alepha";
 
 /**
  * Body posted by the consent screen. All authorization-request parameters
  * are round-tripped through hidden form fields so the POST handler can
  * re-validate them without server-side session state.
  */
-export const authorizeDecisionBodySchema = t.object({
-  decision: t.text(),
-  response_type: t.text(),
-  client_id: t.text(),
-  redirect_uri: t.text({ maxLength: 2048 }),
-  code_challenge: t.text(),
-  code_challenge_method: t.text(),
-  scope: t.optional(t.text({ maxLength: 1024 })),
-  state: t.optional(t.text({ maxLength: 512 })),
-  resource: t.optional(t.text({ maxLength: 2048 })),
+export const authorizeDecisionBodySchema = z.object({
+  decision: z.text(),
+  response_type: z.text(),
+  client_id: z.text(),
+  redirect_uri: z.text({ maxLength: 2048 }),
+  code_challenge: z.text(),
+  code_challenge_method: z.text(),
+  scope: z.text({ maxLength: 1024 }).optional(),
+  state: z.text({ maxLength: 512 }).optional(),
+  resource: z.text({ maxLength: 2048 }).optional(),
+  nonce: z.text({ maxLength: 512 }).optional(),
 });

package/src/api/oauth/schemas/authorizeQuerySchema.ts

@@ -1,15 +1,17 @@
-import { t } from "alepha";
+import { z } from "alepha";
 
 /**
  * OAuth 2.1 authorization request query parameters (GET /oauth/authorize).
  */
-export const authorizeQuerySchema = t.object({
-  response_type: t.text(),
-  client_id: t.text(),
-  redirect_uri: t.text({ maxLength: 2048 }),
-  code_challenge: t.text(),
-  code_challenge_method: t.text(),
-  scope: t.optional(t.text({ maxLength: 1024 })),
-  state: t.optional(t.text({ maxLength: 512 })),
-  resource: t.optional(t.text({ maxLength: 2048 })),
+export const authorizeQuerySchema = z.object({
+  response_type: z.text(),
+  client_id: z.text(),
+  redirect_uri: z.text({ maxLength: 2048 }),
+  code_challenge: z.text(),
+  code_challenge_method: z.text(),
+  scope: z.text({ maxLength: 1024 }).optional(),
+  state: z.text({ maxLength: 512 }).optional(),
+  resource: z.text({ maxLength: 2048 }).optional(),
+  prompt: z.text({ maxLength: 64 }).optional(),
+  nonce: z.text({ maxLength: 512 }).optional(),
 });

package/src/api/oauth/schemas/registerClientBodySchema.ts

@@ -1,16 +1,15 @@
-import { t } from "alepha";
+import { z } from "alepha";
 
 /**
  * RFC 7591 Dynamic Client Registration request body.
  * Only the fields Alepha consumes are typed; unknown fields are ignored.
  */
-export const registerClientBodySchema = t.object(
-  {
-    client_name: t.optional(t.text({ maxLength: 200 })),
-    redirect_uris: t.array(t.text({ maxLength: 2048 }), { minItems: 1 }),
-    scope: t.optional(t.text({ maxLength: 1024 })),
-    grant_types: t.optional(t.array(t.text())),
-    token_endpoint_auth_method: t.optional(t.text()),
-  },
-  { additionalProperties: true },
-);
+export const registerClientBodySchema = z
+  .object({
+    client_name: z.text({ maxLength: 200 }).optional(),
+    redirect_uris: z.array(z.text({ maxLength: 2048 })).min(1),
+    scope: z.text({ maxLength: 1024 }).optional(),
+    grant_types: z.array(z.text()).optional(),
+    token_endpoint_auth_method: z.text().optional(),
+  })
+  .meta({ additionalProperties: true });

package/src/api/oauth/schemas/tokenRequestBodySchema.ts

@@ -1,4 +1,4 @@
-import { t } from "alepha";
+import { z } from "alepha";
 
 /**
  * Body of a POST /oauth/token request. OAuth 2.1 mandates
@@ -6,11 +6,12 @@ import { t } from "alepha";
  * optional at the schema level; the handler enforces the grant-specific
  * requirements and returns the appropriate OAuth error responses.
  */
-export const tokenRequestBodySchema = t.object({
-  grant_type: t.optional(t.text()),
-  code: t.optional(t.text({ maxLength: 4096 })),
-  client_id: t.optional(t.text()),
-  redirect_uri: t.optional(t.text({ maxLength: 2048 })),
-  code_verifier: t.optional(t.text({ maxLength: 256 })),
-  refresh_token: t.optional(t.text({ maxLength: 4096 })),
+export const tokenRequestBodySchema = z.object({
+  grant_type: z.text().optional(),
+  code: z.text({ maxLength: 4096 }).optional(),
+  client_id: z.text().optional(),
+  redirect_uri: z.text({ maxLength: 2048 }).optional(),
+  code_verifier: z.text({ maxLength: 256 }).optional(),
+  refresh_token: z.text({ maxLength: 4096 }).optional(),
+  client_secret: z.text({ maxLength: 512 }).optional(),
 });

package/src/api/oauth/services/OAuthClientService.ts

@@ -1,5 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import { $inject, Alepha, AlephaError } from "alepha";
+import { CryptoProvider } from "alepha/crypto";
 import { DateTimeProvider } from "alepha/datetime";
 import { $logger } from "alepha/logger";
 import { $repository } from "alepha/orm";
@@ -13,11 +14,34 @@ import {
   oauthClientEntity,
 } from "../entities/oauthClientEntity.ts";
 
+/**
+ * The user projection a realm's `loadUser` hands to the OAuth module —
+ * a `UserAccount` plus the OIDC profile extras the id_token mints
+ * (`email_verified`; `firstName`/`lastName` map to `given_name`/`family_name`).
+ */
+export interface OidcIssuerUser extends UserAccount {
+  emailVerified?: boolean;
+}
+
 export interface RegisterClientOptions {
   realm: string;
-  clientName: string;
+  /**
+   * Explicit client id (OIDC clients registered by Platform). When omitted,
+   * a `mcp_<uuid>` id is generated (Dynamic Client Registration).
+   */
+  clientId?: string;
+  clientName?: string;
   redirectUris: string[];
-  scopes: string[];
+  scopes?: string[];
+  /**
+   * `confidential` clients require a `secret` (stored hashed) and authenticate
+   * at the token endpoint. Defaults to `public` (PKCE only).
+   */
+  type?: "public" | "confidential";
+  /** First-party client — skip the consent screen (see the entity field). */
+  trusted?: boolean;
+  /** Raw secret for a confidential client; stored as a scrypt hash. */
+  secret?: string;
   source?: "dcr" | "user" | "admin";
   createdByUserId?: string;
 }
@@ -40,6 +64,7 @@ export class OAuthClientService {
   protected readonly log = $logger();
   protected readonly repo = $repository(oauthClientEntity);
   protected readonly jwt = $inject(JwtProvider);
+  protected readonly crypto = $inject(CryptoProvider);
 
   /**
    * Codes already redeemed in this process. Single-use enforcement only
@@ -58,7 +83,7 @@ export class OAuthClientService {
     string,
     {
       issuer: IssuerPrimitive;
-      loadUser: (userId: string) => Promise<UserAccount>;
+      loadUser: (userId: string) => Promise<OidcIssuerUser>;
     }
   >();
 
@@ -69,7 +94,7 @@ export class OAuthClientService {
   public registerIssuer(
     realm: string,
     issuer: IssuerPrimitive,
-    loadUser: (userId: string) => Promise<UserAccount>,
+    loadUser: (userId: string) => Promise<OidcIssuerUser>,
   ): void {
     this.issuers.set(realm, { issuer, loadUser });
   }
@@ -108,6 +133,52 @@ export class OAuthClientService {
     };
   }
 
+  /**
+   * Mint an OIDC `id_token` for a consumed grant, signed by the realm's issuer
+   * key (asymmetric when configured). Claims: iss, sub, aud (client_id), exp,
+   * iat, nonce (when present), plus the standard profile claims the loader
+   * provides: email, email_verified, name, given_name, family_name,
+   * preferred_username, picture.
+   */
+  public async issueIdToken(
+    realm: string,
+    params: {
+      userId: string;
+      clientId: string;
+      issuer: string;
+      nonce?: string;
+    },
+  ): Promise<string> {
+    const entry = this.issuers.get(realm);
+    if (!entry) {
+      throw new AlephaError(`No issuer registered for realm '${realm}'`);
+    }
+    const user = await entry.loadUser(params.userId);
+    const iat = this.dateTime.now().unix();
+    const exp = iat + entry.issuer.accessTokenExpiration.asSeconds();
+    return this.jwt.create(
+      {
+        iss: params.issuer,
+        sub: user.id,
+        aud: params.clientId,
+        exp,
+        iat,
+        ...(params.nonce ? { nonce: params.nonce } : {}),
+        ...(user.email ? { email: user.email } : {}),
+        ...(user.emailVerified !== undefined
+          ? { email_verified: user.emailVerified }
+          : {}),
+        ...(user.name ? { name: user.name } : {}),
+        ...(user.firstName ? { given_name: user.firstName } : {}),
+        ...(user.lastName ? { family_name: user.lastName } : {}),
+        ...(user.username ? { preferred_username: user.username } : {}),
+        ...(user.picture ? { picture: user.picture } : {}),
+      },
+      realm,
+      { header: { typ: "JWT" } },
+    );
+  }
+
   /**
    * Exchange a refresh token for a fresh access token (OAuth 2.1
    * `refresh_token` grant), using the issuer registered for `realm`. Lets an
@@ -122,16 +193,20 @@ export class OAuthClientService {
     access_token: string;
     expires_in?: number;
     refresh_token?: string;
+    /** Subject of the refreshed session — lets the token endpoint re-mint an
+     * OIDC `id_token` for relying parties that forward it as the Bearer. */
+    userId: string;
   }> {
     const entry = this.issuers.get(realm);
     if (!entry) {
       throw new AlephaError(`No issuer registered for realm '${realm}'`);
     }
-    const { tokens } = await entry.issuer.refreshToken(refreshToken);
+    const { tokens, user } = await entry.issuer.refreshToken(refreshToken);
     return {
       access_token: tokens.access_token,
       expires_in: tokens.expires_in,
       refresh_token: tokens.refresh_token,
+      userId: user.id,
     };
   }
 
@@ -146,29 +221,118 @@ export class OAuthClientService {
       throw new AlephaError("At least one redirect_uri is required");
     }
     for (const uri of options.redirectUris) {
-      if (!uri.startsWith("https://") && !uri.startsWith("http://localhost")) {
-        throw new AlephaError(`Invalid redirect_uri: ${uri}`);
-      }
+      this.assertValidRedirectUri(uri);
     }
 
-    const clientId = `mcp_${randomUUID().replace(/-/g, "")}`;
+    const type = options.type ?? "public";
+    if (type === "confidential" && !options.secret) {
+      throw new AlephaError("A confidential client requires a secret");
+    }
+
+    const clientId =
+      options.clientId ?? `mcp_${randomUUID().replace(/-/g, "")}`;
+    const clientSecretHash = options.secret
+      ? await this.crypto.hashPassword(options.secret)
+      : undefined;
+
     const client = await this.repo.create({
       clientId,
-      clientName: options.clientName || "MCP Client",
+      clientName: options.clientName || "OAuth Client",
       redirectUris: options.redirectUris,
-      scopes: options.scopes,
+      scopes: options.scopes ?? ["openid"],
       realm: options.realm,
+      type,
+      trusted: options.trusted ?? false,
+      clientSecretHash,
       source: options.source ?? "dcr",
       createdByUserId: options.createdByUserId,
     });
 
     this.log.info("OAuth client registered", {
       clientId,
+      type,
       source: client.source,
     });
     return client;
   }
 
+  /**
+   * Idempotently align a registered client's redirect_uri allowlist with the
+   * given list. No-op when the client is unknown or the list already matches —
+   * safe to call from post-deploy seeders (allowlist changes ship as code, and
+   * `register` alone would leave existing rows stale).
+   */
+  public async updateRedirectUris(
+    clientId: string,
+    redirectUris: string[],
+  ): Promise<void> {
+    if (redirectUris.length === 0) {
+      throw new AlephaError("At least one redirect_uri is required");
+    }
+    for (const uri of redirectUris) {
+      this.assertValidRedirectUri(uri);
+    }
+    const client = await this.findByClientId(clientId);
+    if (!client) {
+      return;
+    }
+    if (
+      client.redirectUris.length === redirectUris.length &&
+      client.redirectUris.every((uri, i) => uri === redirectUris[i])
+    ) {
+      return;
+    }
+    await this.repo.updateById(client.id, { redirectUris });
+    this.log.info("OAuth client redirect_uris updated", {
+      clientId,
+      redirectUris,
+    });
+  }
+
+  /**
+   * Verify a confidential client's secret against its stored scrypt hash.
+   * Returns false for unknown/revoked/public (no-hash) clients.
+   */
+  public async verifySecret(
+    clientId: string,
+    secret: string,
+  ): Promise<boolean> {
+    const client = await this.findByClientId(clientId);
+    if (!client || client.revokedAt || !client.clientSecretHash) {
+      return false;
+    }
+    return this.crypto.verifyPassword(secret, client.clientSecretHash);
+  }
+
+  /**
+   * Validate a registered redirect_uri. https (or http://localhost) only, and
+   * at most a single `*` which must live inside the host (see
+   * `redirectUriMatches` for the matching rule).
+   */
+  protected assertValidRedirectUri(uri: string): void {
+    const stars = (uri.match(/\*/g) ?? []).length;
+    if (stars > 1) {
+      throw new AlephaError(
+        `At most one '*' wildcard is allowed in redirect_uri: ${uri}`,
+      );
+    }
+    const probe = uri.replace("*", "wildcard");
+    if (
+      !probe.startsWith("https://") &&
+      !probe.startsWith("http://localhost")
+    ) {
+      throw new AlephaError(`Invalid redirect_uri: ${uri}`);
+    }
+    if (stars === 1) {
+      const host = uri.slice(uri.indexOf("://") + 3).split("/")[0] ?? "";
+      if (!host.includes("*")) {
+        throw new AlephaError(
+          `Wildcard '*' is only allowed in the host: ${uri}`,
+        );
+      }
+    }
+  }
+
   /**
    * Look up a client by its public `clientId`. Returns null if unknown.
    */
@@ -182,14 +346,55 @@ export class OAuthClientService {
   }
 
   /**
-   * Exact-match redirect_uri check. OAuth 2.1 forbids substring/prefix
-   * matching — the value must equal a registered URI byte-for-byte.
+   * Narrow the scopes a client asks for to those it is actually registered
+   * for. The requested scope string is attacker-controlled, so it must never
+   * be trusted verbatim — a client registered for `["mcp"]` that asks for
+   * `mcp admin` must only be granted `mcp`. When nothing (usable) is
+   * requested, the client's full registered set is the default grant.
+   * Requested order is preserved and duplicates are dropped.
+   */
+  public intersectScopes(
+    requested: string[] | undefined,
+    allowed: string[],
+  ): string[] {
+    if (!requested || requested.length === 0) {
+      return allowed;
+    }
+    const allowedSet = new Set(allowed);
+    const granted: string[] = [];
+    for (const scope of requested) {
+      if (allowedSet.has(scope) && !granted.includes(scope)) {
+        granted.push(scope);
+      }
+    }
+    return granted;
+  }
+
+  /**
+   * Redirect_uri check. A registered pattern is matched byte-exact unless it
+   * contains a single `*`, which matches exactly ONE host label (no dots).
+   * E.g. `https://*.alepha.club/auth/callback` matches
+   * `https://b14.alepha.club/auth/callback` but NOT `https://alepha.club/...`
+   * nor `https://a.b.alepha.club/...`.
    */
   public isRedirectUriAllowed(
     client: OAuthClientEntity,
     redirectUri: string,
   ): boolean {
-    return client.redirectUris.includes(redirectUri);
+    return client.redirectUris.some((pattern) =>
+      this.redirectUriMatches(pattern, redirectUri),
+    );
+  }
+
+  protected redirectUriMatches(pattern: string, candidate: string): boolean {
+    if (!pattern.includes("*")) {
+      return pattern === candidate;
+    }
+    // Escape every regex metachar (incl. the `*` and the dots), then turn the
+    // single escaped `*` into a one-label match (`[^.]+` — no dots).
+    const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const rx = new RegExp(`^${escaped.replace("\\*", "[^.]+")}$`);
+    return rx.test(candidate);
   }
 
   /**
@@ -205,6 +410,7 @@ export class OAuthClientService {
       codeChallenge: string;
       scopes: string[];
       resource?: string;
+      nonce?: string;
     },
   ): Promise<string> {
     const iat = this.dateTime.now().unix();
@@ -216,6 +422,7 @@ export class OAuthClientService {
         code_challenge: grant.codeChallenge,
         scopes: grant.scopes,
         resource: grant.resource,
+        nonce: grant.nonce,
         iat,
         exp: iat + 60,
         jti: randomUUID(),
@@ -233,7 +440,12 @@ export class OAuthClientService {
     realm: string,
     code: string,
     check: { clientId: string; redirectUri: string; codeVerifier: string },
-  ): Promise<{ userId: string; scopes: string[]; resource?: string }> {
+  ): Promise<{
+    userId: string;
+    scopes: string[];
+    resource?: string;
+    nonce?: string;
+  }> {
     const { result } = await this.jwt.parse(code, realm, {
       typ: "oauth_code",
     });
@@ -262,6 +474,7 @@ export class OAuthClientService {
       userId: payload.sub as string,
       scopes: (payload.scopes as string[]) ?? [],
       resource: payload.resource as string | undefined,
+      nonce: payload.nonce as string | undefined,
     };
   }
 }

package/src/api/organizations/controllers/AdminOrganizationController.ts

@@ -1,4 +1,4 @@
-import { $inject, t } from "alepha";
+import { $inject, z } from "alepha";
 import { $secure } from "alepha/security";
 import { $action, okSchema } from "alepha/server";
 import { createOrganizationSchema } from "../schemas/createOrganizationSchema.ts";
@@ -22,7 +22,7 @@ export class AdminOrganizationController {
     description: "Find organizations with pagination and filtering",
     schema: {
       query: organizationQuerySchema,
-      response: t.page(organizationResourceSchema),
+      response: z.page(organizationResourceSchema),
     },
     handler: ({ query }) => this.organizationService.find(query),
   });
@@ -36,8 +36,8 @@ export class AdminOrganizationController {
     use: [$secure({ permissions: ["admin:organization:read"] })],
     description: "Get an organization by ID",
     schema: {
-      params: t.object({
-        id: t.uuid(),
+      params: z.object({
+        id: z.uuid(),
       }),
       response: organizationResourceSchema,
     },
@@ -70,8 +70,8 @@ export class AdminOrganizationController {
     use: [$secure({ permissions: ["admin:organization:update"] })],
     description: "Update an organization",
     schema: {
-      params: t.object({
-        id: t.uuid(),
+      params: z.object({
+        id: z.uuid(),
       }),
       body: updateOrganizationSchema,
       response: organizationResourceSchema,
@@ -90,8 +90,8 @@ export class AdminOrganizationController {
     use: [$secure({ permissions: ["admin:organization:delete"] })],
     description: "Delete an organization",
     schema: {
-      params: t.object({
-        id: t.uuid(),
+      params: z.object({
+        id: z.uuid(),
       }),
       response: okSchema,
     },

package/src/api/organizations/entities/organizations.ts

@@ -1,18 +1,18 @@
 import type { Static } from "alepha";
-import { t } from "alepha";
+import { z } from "alepha";
 import { $entity, db } from "alepha/orm";
 
 export const organizations = $entity({
   name: "organizations",
-  schema: t.object({
-    id: db.primaryKey(t.uuid()),
+  schema: z.object({
+    id: db.primaryKey(z.uuid()),
     version: db.version(),
     createdAt: db.createdAt(),
     updatedAt: db.updatedAt(),
 
-    name: t.text(),
-    slug: t.text({ minLength: 2, maxLength: 100 }),
-    enabled: db.default(t.boolean(), true),
+    name: z.text(),
+    slug: z.text({ minLength: 2, maxLength: 100 }),
+    enabled: db.default(z.boolean(), true),
   }),
   indexes: [{ columns: ["slug"], unique: true }],
 });

package/src/api/organizations/schemas/createOrganizationSchema.ts

@@ -1,10 +1,10 @@
 import type { Static } from "alepha";
-import { t } from "alepha";
+import { z } from "alepha";
 
-export const createOrganizationSchema = t.object({
-  name: t.text(),
-  slug: t.text({ minLength: 2, maxLength: 100 }),
-  enabled: t.optional(t.boolean()),
+export const createOrganizationSchema = z.object({
+  name: z.text(),
+  slug: z.text({ minLength: 2, maxLength: 100 }),
+  enabled: z.boolean().optional(),
 });
 
 export type CreateOrganization = Static<typeof createOrganizationSchema>;

package/src/api/organizations/schemas/organizationQuerySchema.ts

@@ -1,10 +1,10 @@
 import type { Static } from "alepha";
-import { t } from "alepha";
+import { z } from "alepha";
 import { pageQuerySchema } from "alepha/orm";
 
-export const organizationQuerySchema = t.extend(pageQuerySchema, {
-  name: t.optional(t.text({ description: "Filter by name (partial match)" })),
-  enabled: t.optional(t.boolean({ description: "Filter by enabled status" })),
+export const organizationQuerySchema = pageQuerySchema.extend({
+  name: z.text({ description: "Filter by name (partial match)" }).optional(),
+  enabled: z.boolean().describe("Filter by enabled status").optional(),
 });
 
 export type OrganizationQuery = Static<typeof organizationQuerySchema>;

package/src/api/organizations/schemas/updateOrganizationSchema.ts

@@ -1,7 +1,6 @@
 import type { Static } from "alepha";
-import { t } from "alepha";
 import { createOrganizationSchema } from "./createOrganizationSchema.ts";
 
-export const updateOrganizationSchema = t.partial(createOrganizationSchema);
+export const updateOrganizationSchema = createOrganizationSchema.partial();
 
 export type UpdateOrganization = Static<typeof updateOrganizationSchema>;