@opengeni/api-router 0.30.3 → 1.0.0

package/src/auth/managed-email.ts

@@ -0,0 +1,174 @@
+import type { Settings } from "@opengeni/config";
+import type {
+  ManagedEmailDeliveryResult,
+  ManagedEmailMessage,
+  ManagedEmailTransport,
+} from "@opengeni/core";
+import { createHmac } from "node:crypto";
+import { Resend } from "resend";
+
+const CAPTURE_MAX_MESSAGES = 250;
+const CAPTURE_TTL_MS = 15 * 60 * 1000;
+
+export type CapturedManagedEmail = ManagedEmailMessage & {
+  capturedAt: string;
+};
+
+/**
+ * Process-local test/development transport. Captures are count/TTL bounded and
+ * one-time readable; there is deliberately no route, disk, database, or log
+ * projection for message bodies or setup bearers.
+ */
+export class InMemoryManagedEmailTransport implements ManagedEmailTransport {
+  private readonly messages: CapturedManagedEmail[] = [];
+  readonly sender: string;
+  readonly idempotency: ManagedEmailTransport["idempotency"];
+
+  constructor(
+    private readonly options: {
+      maxMessages?: number;
+      ttlMs?: number;
+      now?: () => number;
+      sender?: string;
+      idempotency?: ManagedEmailTransport["idempotency"];
+    } = {},
+  ) {
+    this.sender = options.sender ?? "Opengeni <auth@mail.opengeni.ai>";
+    this.idempotency = options.idempotency ?? {
+      scope: "opengeni-in-memory-v1",
+      retentionSeconds: 86_400,
+    };
+  }
+
+  async send(message: ManagedEmailMessage): Promise<ManagedEmailDeliveryResult> {
+    this.prune();
+    const maxMessages = this.options.maxMessages ?? CAPTURE_MAX_MESSAGES;
+    if (this.messages.length >= maxMessages) this.messages.splice(0, 1);
+    this.messages.push({
+      ...message,
+      capturedAt: new Date(this.now()).toISOString(),
+    });
+    return { status: "sent", providerMessageId: null };
+  }
+
+  take(predicate: (message: CapturedManagedEmail) => boolean): CapturedManagedEmail | null {
+    this.prune();
+    const index = this.messages.findIndex(predicate);
+    if (index < 0) return null;
+    return this.messages.splice(index, 1)[0] ?? null;
+  }
+
+  size(): number {
+    this.prune();
+    return this.messages.length;
+  }
+
+  private prune(): void {
+    const cutoff = this.now() - (this.options.ttlMs ?? CAPTURE_TTL_MS);
+    while (this.messages[0] && Date.parse(this.messages[0].capturedAt) <= cutoff) {
+      this.messages.shift();
+    }
+  }
+
+  private now(): number {
+    return this.options.now?.() ?? Date.now();
+  }
+}
+
+class UnconfiguredManagedEmailTransport implements ManagedEmailTransport {
+  readonly idempotency = {
+    scope: "opengeni-unconfigured-v1",
+    retentionSeconds: 0,
+  } as const;
+
+  constructor(readonly sender: string) {}
+
+  async send(): Promise<ManagedEmailDeliveryResult> {
+    return { status: "failed", errorClass: "provider_not_configured" };
+  }
+}
+
+class ResendManagedEmailTransport implements ManagedEmailTransport {
+  private readonly client: Resend;
+  readonly idempotency: ManagedEmailTransport["idempotency"];
+
+  constructor(
+    apiKey: string,
+    readonly sender: string,
+    scopeSecret: string,
+  ) {
+    this.client = new Resend(apiKey);
+    this.idempotency = {
+      // The keyed digest binds this delivery to the Resend account without
+      // persisting an API-key derivative that can be tested offline.
+      scope: `resend-v1-24h:${createHmac("sha256", scopeSecret).update(apiKey).digest("hex")}`,
+      retentionSeconds: 86_400,
+    };
+  }
+
+  async send(message: ManagedEmailMessage): Promise<ManagedEmailDeliveryResult> {
+    if (message.from !== this.sender) {
+      return { status: "failed", errorClass: "sender_changed" };
+    }
+    try {
+      const result = await this.client.emails.send(
+        {
+          from: message.from,
+          to: message.to,
+          subject: message.subject,
+          text: message.text,
+          html: message.html,
+        },
+        message.idempotencyKey ? { idempotencyKey: message.idempotencyKey } : undefined,
+      );
+      if (!result.error) {
+        return { status: "sent", providerMessageId: result.data?.id ?? null };
+      }
+      const statusCode = "statusCode" in result.error ? Number(result.error.statusCode) : NaN;
+      return clearProviderRefusal(statusCode)
+        ? { status: "failed", errorClass: boundedErrorClass(result.error.name, "provider_refused") }
+        : {
+            status: "outcome_unknown",
+            errorClass: boundedErrorClass(result.error.name, "provider_ambiguous"),
+          };
+    } catch (error) {
+      return {
+        status: "outcome_unknown",
+        errorClass: boundedErrorClass(
+          error instanceof Error ? error.name : "transport_error",
+          "transport_error",
+        ),
+      };
+    }
+  }
+}
+
+export function createManagedEmailTransport(settings: Settings): ManagedEmailTransport {
+  if (settings.resendApiKey) {
+    if (!settings.betterAuthSecret) {
+      throw new Error("OPENGENI_BETTER_AUTH_SECRET is required for managed email delivery");
+    }
+    return new ResendManagedEmailTransport(
+      settings.resendApiKey,
+      settings.emailFrom,
+      settings.betterAuthSecret,
+    );
+  }
+  if (settings.environment === "local" || settings.environment === "test") {
+    return new InMemoryManagedEmailTransport({ sender: settings.emailFrom });
+  }
+  return new UnconfiguredManagedEmailTransport(settings.emailFrom);
+}
+
+function clearProviderRefusal(statusCode: number): boolean {
+  return statusCode >= 400 && statusCode < 500 && ![408, 409, 425, 429].includes(statusCode);
+}
+
+function boundedErrorClass(value: string, fallback: string): string {
+  const normalized = value
+    .trim()
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9_-]+/g, "_")
+    .slice(0, 64);
+  return normalized || fallback;
+}

package/src/auth/managed-sign-in-notifications.ts

@@ -0,0 +1,81 @@
+import type { ManagedEmailTransport } from "@opengeni/core";
+import type { Database } from "@opengeni/db";
+import { sql } from "drizzle-orm";
+import { z } from "zod";
+
+const Claim = z.object({
+  operationId: z.string().uuid(),
+  leaseId: z.string().uuid(),
+  email: z.string().email(),
+  provider: z.enum(["password", "google", "github"]),
+  sender: z.string(),
+});
+const started = new WeakSet<object>();
+
+export async function deliverManagedSignInNotification(
+  db: Database,
+  transport: ManagedEmailTransport,
+  operationId: string | null = null,
+): Promise<"sent" | "failed" | "outcome_unknown"> {
+  try {
+    const result = await db.execute(
+      sql`select claim_managed_sign_in_notification(${operationId}::uuid,${transport.sender},${transport.idempotency.scope},${transport.idempotency.retentionSeconds}::integer) as claim`,
+    );
+    const row = (Array.isArray(result) ? result : result.rows)[0] as { claim: unknown } | undefined;
+    if (!row?.claim) return "outcome_unknown";
+    const claim = Claim.parse(row.claim);
+    let status: "sent" | "failed" | "outcome_unknown" = "outcome_unknown";
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    try {
+      const response = await Promise.race([
+        transport.send({
+          kind: "sign_in_method_changed",
+          from: claim.sender,
+          to: claim.email,
+          idempotencyKey: `sign-in-method:${claim.operationId}`,
+          subject: "Your Opengeni sign-in methods changed",
+          text: `Your Opengeni ${claim.provider} sign-in method changed. If this was not you, reset your password and contact your administrator.`,
+          html: `<p>Your Opengeni ${claim.provider} sign-in method changed. If this was not you, reset your password and contact your administrator.</p>`,
+        }),
+        new Promise<{ status: "outcome_unknown" }>((resolve) => {
+          timer = setTimeout(() => resolve({ status: "outcome_unknown" }), 5_000);
+        }),
+      ]);
+      status = response.status;
+    } catch {
+      /* Retain the durable unknown claim for idempotent retry. */
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+    await db.execute(
+      sql`select settle_managed_sign_in_notification(${claim.operationId}::uuid,${claim.leaseId}::uuid,${status})`,
+    );
+    return status;
+  } catch {
+    // Security state is already committed. A failed claim/ack must never be
+    // reported as a failed method change; its durable obligation remains live.
+    return "outcome_unknown";
+  }
+}
+
+export function startManagedSignInNotificationDelivery(
+  db: Database,
+  transport: ManagedEmailTransport,
+): void {
+  if (started.has(db as object)) return;
+  started.add(db as object);
+  let active = false;
+  const drain = async () => {
+    if (active) return;
+    active = true;
+    try {
+      for (let count = 0; count < 10; count++)
+        if ((await deliverManagedSignInNotification(db, transport)) === "outcome_unknown") break;
+    } finally {
+      active = false;
+    }
+  };
+  const timer = setInterval(() => void drain(), 60_000);
+  (timer as ReturnType<typeof setInterval> & { unref?: () => void }).unref?.();
+  void drain();
+}

package/src/auth/new-signups-gate.ts

@@ -0,0 +1,49 @@
+import type { Settings } from "@opengeni/config";
+import { readManagedAuthNewSignupsSwitch, type Database } from "@opengeni/db";
+import type { Observability } from "@opengeni/observability";
+
+/**
+ * Decides whether a new managed account may be created right now.
+ *
+ * `OPENGENI_MANAGED_AUTH_NEW_SIGNUPS_ENABLED` is the deployment ceiling (read at
+ * startup). While it allows sign-ups, the newest revision of the operator
+ * runtime switch (migration 0585) decides, read on every call so a flip
+ * applies to the next request on every API replica without a restart.
+ *
+ * Fail-safe: if the read fails, the last value this process observed wins;
+ * before any successful read, the deployment ceiling wins. A missing revision
+ * (pre-0585 schema) also follows the ceiling.
+ */
+export type ManagedAuthNewSignupsGate = {
+  signupsOpen(): Promise<boolean>;
+};
+
+export function createManagedAuthNewSignupsGate(input: {
+  db: Database;
+  settings: Pick<Settings, "managedAuthNewSignupsEnabled">;
+  observability?: Pick<Observability, "warn"> | undefined;
+}): ManagedAuthNewSignupsGate {
+  const ceiling = input.settings.managedAuthNewSignupsEnabled !== false;
+  let lastKnown: boolean | null = null;
+  return {
+    async signupsOpen() {
+      if (!ceiling) return false;
+      try {
+        const current = await readManagedAuthNewSignupsSwitch(input.db);
+        lastKnown = current ? current.signupsEnabled : true;
+        return lastKnown;
+      } catch (error) {
+        try {
+          input.observability?.warn("Managed auth new signups switch read failed", {
+            dependency: "managed_auth_new_signups_switch",
+            fallback: lastKnown === null ? "deployment_ceiling" : "last_known",
+            errorClass: error instanceof Error ? error.name : "UnknownError",
+          });
+        } catch {
+          // An observer failure must not decide a sign-up.
+        }
+        return lastKnown ?? ceiling;
+      }
+    },
+  };
+}

package/src/auth/organization-user-setup.ts

@@ -0,0 +1,307 @@
+import type { Settings } from "@opengeni/config";
+import type { ManagedEmailTransport } from "@opengeni/core";
+
+const encoder = new TextEncoder();
+export type OrganizationUserSetupEmailTokenTransport = "fragment" | "query";
+
+/**
+ * Prove that the stable invited-user setup bearer can be constructed before an
+ * invitation commits. Provider availability is intentionally outside this
+ * precondition: the durable delivery journal records a failed or ambiguous
+ * transport outcome after the invitation exists.
+ */
+export function assertOrganizationUserSetupDeliveryConfigured(
+  settings: Settings,
+  transport: ManagedEmailTransport,
+): void {
+  assertOrganizationUserSetupQueryTransportConfigured(settings);
+  requiredSetupSecret(settings);
+  requiredPublicBaseUrl(settings);
+  assertManagedEmailTransportMetadata(transport);
+}
+
+/** Enforce the query-bearing edge proof for env and embedded settings alike. */
+export function assertOrganizationUserSetupQueryTransportConfigured(
+  settings: Pick<
+    Settings,
+    | "organizationUserSetupEmailTokenTransport"
+    | "organizationUserSetupQueryEdgeSanitizationConfirmed"
+  >,
+): void {
+  if (
+    settings.organizationUserSetupEmailTokenTransport === "query" &&
+    !settings.organizationUserSetupQueryEdgeSanitizationConfirmed
+  ) {
+    throw new Error(
+      "OPENGENI_ORGANIZATION_USER_SETUP_QUERY_EDGE_SANITIZATION_CONFIRMED=true is required when OPENGENI_ORGANIZATION_USER_SETUP_EMAIL_TOKEN_TRANSPORT=query",
+    );
+  }
+}
+
+/** Reject an invalid embedded-provider contract before any durable boundary. */
+export function assertManagedEmailTransportMetadata(transport: ManagedEmailTransport): void {
+  if (
+    transport.sender.trim() !== transport.sender ||
+    encoder.encode(transport.sender).byteLength < 3 ||
+    encoder.encode(transport.sender).byteLength > 320
+  ) {
+    throw new Error("Managed email sender is invalid");
+  }
+  const { scope, retentionSeconds } = transport.idempotency;
+  if (
+    scope.trim() !== scope ||
+    !/^[a-z0-9][a-z0-9:._-]*$/.test(scope) ||
+    encoder.encode(scope).byteLength > 200 ||
+    !Number.isInteger(retentionSeconds) ||
+    retentionSeconds < 0 ||
+    retentionSeconds > 31_536_000
+  ) {
+    throw new Error("Managed email idempotency contract is invalid");
+  }
+}
+
+export async function deriveOrganizationUserSetupToken(
+  settings: Settings,
+  input: {
+    invitationId: string;
+    deliveryId: string;
+    transport?: OrganizationUserSetupEmailTokenTransport;
+  },
+): Promise<{ token: string; digest: string; url: string }> {
+  const secret = requiredSetupSecret(settings);
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const signature = await crypto.subtle.sign(
+    "HMAC",
+    key,
+    encoder.encode(
+      `opengeni:organization-user-setup-delivery:v1:${input.deliveryId}:${input.invitationId}`,
+    ),
+  );
+  const token = base64Url(new Uint8Array(signature));
+  const digest = await sha256Hex(token);
+  const url = new URL("/setup-account", requiredPublicBaseUrl(settings));
+  if ((input.transport ?? settings.organizationUserSetupEmailTokenTransport) === "query") {
+    // Email security gateways routinely wrap links and may discard URL
+    // fragments. Enable this only after the compatibility web rollout; the
+    // browser's first executable head bootstrap scrubs query authority without
+    // redirecting or allowing a query-bearing subresource Referer.
+    url.searchParams.set("token", token);
+  } else {
+    url.hash = new URLSearchParams({ token }).toString();
+  }
+  return { token, digest, url: url.toString() };
+}
+
+export type OrganizationUserSetupEmailSnapshot = {
+  senderEmail: string;
+  recipientEmail: string;
+  recipientName: string | null;
+  organizationName: string;
+  organizationRole: "owner" | "admin" | "member";
+  sharedWorkspaceAccess: Array<{
+    workspaceId: string;
+    workspaceName: string;
+    role: "viewer" | "member" | "admin";
+  }>;
+  setupUrl: string;
+};
+
+export function renderOrganizationUserSetupEmail(input: OrganizationUserSetupEmailSnapshot): {
+  from: string;
+  to: string;
+  subject: string;
+  text: string;
+  html: string;
+} {
+  const greeting = input.recipientName ? `Hi ${input.recipientName},` : "Hello,";
+  const role = titleCase(input.organizationRole);
+  const workspaceSummary =
+    input.sharedWorkspaceAccess.length === 0
+      ? "No shared workspaces are assigned yet."
+      : `Shared workspace access:\n${input.sharedWorkspaceAccess
+          .map((workspace) => `- ${workspace.workspaceName}: ${titleCase(workspace.role)}`)
+          .join("\n")}`;
+  const workspaceHtml =
+    input.sharedWorkspaceAccess.length === 0
+      ? "<p>No shared workspaces are assigned yet.</p>"
+      : `<p>Shared workspace access:</p><ul>${input.sharedWorkspaceAccess
+          .map(
+            (workspace) =>
+              `<li>${escapeHtml(workspace.workspaceName)}: ${escapeHtml(titleCase(workspace.role))}</li>`,
+          )
+          .join("")}</ul>`;
+  return {
+    from: input.senderEmail,
+    to: input.recipientEmail,
+    subject: `You're invited to join ${input.organizationName} on Opengeni`,
+    text: `${greeting}\n\nYou've been invited to join ${input.organizationName} on Opengeni as ${role}.\n\n${workspaceSummary}\n\nThis invitation grants only the organization role and shared workspace access listed above. It never shares anyone's Personal workspace.\n\nAccept invitation to ${input.organizationName}: ${input.setupUrl}\n\nYou'll sign in or create an account before joining. Already use Opengeni? Open this invitation and choose Sign in as ${input.recipientEmail}. Opengeni will show the invitation immediately after you sign in.`,
+    html: `<p>${escapeHtml(greeting)}</p><p>You've been invited to join <strong>${escapeHtml(input.organizationName)}</strong> on Opengeni as ${escapeHtml(role)}.</p>${workspaceHtml}<p>This invitation grants only the organization role and shared workspace access listed above. It never shares anyone's Personal workspace.</p><p><a href="${escapeHtml(input.setupUrl)}">Accept invitation to ${escapeHtml(input.organizationName)}</a></p><p>You'll sign in or create an account before joining. Already use Opengeni? Open this invitation and choose <strong>Sign in as ${escapeHtml(input.recipientEmail)}</strong>. Opengeni will show the invitation immediately after you sign in.</p>`,
+  };
+}
+
+export async function organizationUserSetupPayloadDigest(input: {
+  from: string;
+  to: string;
+  subject: string;
+  text: string;
+  html: string;
+  providerIdempotencyScope: string;
+}): Promise<string> {
+  return await sha256Hex(
+    JSON.stringify({
+      version: 2,
+      providerIdempotencyScope: input.providerIdempotencyScope,
+      from: input.from,
+      to: input.to,
+      subject: input.subject,
+      text: input.text,
+      html: input.html,
+    }),
+  );
+}
+
+export async function resolveOrganizationUserSetupDeliveryEmail(
+  settings: Settings,
+  input: {
+    invitationId: string;
+    deliveryId: string;
+    senderEmail: string;
+    recipientEmail: string;
+    recipientName: string | null;
+    organizationName: string;
+    organizationRole: "owner" | "admin" | "member";
+    sharedWorkspaceAccess: OrganizationUserSetupEmailSnapshot["sharedWorkspaceAccess"];
+    providerIdempotencyScope: string;
+    frozenTransport: OrganizationUserSetupEmailTokenTransport | null;
+    frozenPayloadDigest: string | null;
+  },
+): Promise<{
+  transport: OrganizationUserSetupEmailTokenTransport;
+  token: string;
+  tokenDigest: string;
+  payloadDigest: string;
+  message: ReturnType<typeof renderOrganizationUserSetupEmail>;
+}> {
+  const candidates: OrganizationUserSetupEmailTokenTransport[] = input.frozenTransport
+    ? [input.frozenTransport]
+    : input.frozenPayloadDigest
+      ? ["fragment", "query"]
+      : [settings.organizationUserSetupEmailTokenTransport];
+  for (const transport of candidates) {
+    const setup = await deriveOrganizationUserSetupToken(settings, {
+      invitationId: input.invitationId,
+      deliveryId: input.deliveryId,
+      transport,
+    });
+    const message = renderOrganizationUserSetupEmail({
+      senderEmail: input.senderEmail,
+      recipientEmail: input.recipientEmail,
+      recipientName: input.recipientName,
+      organizationName: input.organizationName,
+      organizationRole: input.organizationRole,
+      sharedWorkspaceAccess: input.sharedWorkspaceAccess,
+      setupUrl: setup.url,
+    });
+    const payloadDigest = await organizationUserSetupPayloadDigest({
+      ...message,
+      providerIdempotencyScope: input.providerIdempotencyScope,
+    });
+    if (input.frozenPayloadDigest && payloadDigest !== input.frozenPayloadDigest) continue;
+    return {
+      transport,
+      token: setup.token,
+      tokenDigest: setup.digest,
+      payloadDigest,
+      message,
+    };
+  }
+  throw new Error("Organization setup delivery transport does not match its frozen payload");
+}
+
+export async function organizationUserSetupRequestFingerprint(
+  settings: Settings,
+  input: { tokenDigest: string; name: string; password: string },
+): Promise<string> {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(requiredSetupSecret(settings)),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const signature = await crypto.subtle.sign(
+    "HMAC",
+    key,
+    encoder.encode(
+      JSON.stringify({
+        tokenDigest: input.tokenDigest,
+        name: input.name,
+        password: input.password,
+      }),
+    ),
+  );
+  return hex(new Uint8Array(signature));
+}
+
+export async function selfServiceOrganizationSetupRequestFingerprint(input: {
+  authUserId: string;
+  organizationName: string;
+}): Promise<string> {
+  const actorSubjectId = `user:${input.authUserId}`;
+  const organizationNameBytes = encoder.encode(input.organizationName);
+  return await sha256Hex(
+    `opengeni:self-service-organization:v1:${actorSubjectId}:${organizationNameBytes.byteLength}:${input.organizationName}`,
+  );
+}
+
+export async function organizationUserSetupTokenDigest(token: string): Promise<string> {
+  return await sha256Hex(token);
+}
+
+function requiredSetupSecret(settings: Settings): string {
+  if (!settings.betterAuthSecret) {
+    throw new Error("OPENGENI_BETTER_AUTH_SECRET is required for organization user setup");
+  }
+  return settings.betterAuthSecret;
+}
+
+function requiredPublicBaseUrl(settings: Settings): string {
+  if (!settings.publicBaseUrl) {
+    throw new Error("OPENGENI_PUBLIC_BASE_URL is required for organization user setup");
+  }
+  return settings.publicBaseUrl;
+}
+
+async function sha256Hex(value: string): Promise<string> {
+  const digest = await crypto.subtle.digest("SHA-256", encoder.encode(value));
+  return hex(new Uint8Array(digest));
+}
+
+function hex(bytes: Uint8Array): string {
+  return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+function base64Url(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+
+function titleCase(value: string): string {
+  return `${value.slice(0, 1).toUpperCase()}${value.slice(1)}`;
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#039;");
+}