@k2b/cloud 0.6.0-rc.0

package/src/services/notifications/user.ts

@@ -0,0 +1,248 @@
+import { sql } from "bun";
+import {
+  isSafeNotificationTargetHref,
+  type NotificationDefinitionPresentationCatalog,
+  resolveNotificationDefinitionPresentation,
+} from "../../contracts/notification-types";
+import type { MutationResult } from "../../contracts/shared";
+import type {
+  NotificationDeliveryStatus,
+  UserNotificationHistoryResponse,
+  UserNotificationPreference,
+  UserNotificationPreferencesResponse,
+} from "../../contracts/user-notifications";
+import { normalizeLocale } from "../../shared/locale";
+import { toPgTextArray } from "../postgres";
+import { listNotificationChannels } from "./channels";
+
+type PreferenceRow = {
+  id: string;
+  app_id: string;
+  kind: string;
+  label: string;
+  description: string;
+  presentation: NotificationDefinitionPresentationCatalog | null;
+  recommended_channels: string[];
+  required_channels: string[];
+  channels: string[] | null;
+  customized: boolean;
+};
+
+type HistoryRow = {
+  id: string;
+  event_id: string;
+  definition_id: string;
+  app_id: string;
+  label: string;
+  description: string;
+  presentation: NotificationDefinitionPresentationCatalog | null;
+  title: string;
+  target_href: string | null;
+  channel: string;
+  destination_label: string;
+  required: boolean;
+  status: NotificationDeliveryStatus;
+  attempt_count: number;
+  error_code: string | null;
+  created_at: Date;
+  delivered_at: Date | null;
+};
+
+const unique = (values: readonly string[]): string[] => [...new Set(values)];
+
+const definitionPresentation = (
+  row: Pick<PreferenceRow, "label" | "description" | "presentation">,
+  locale?: string,
+): { label: string; description: string } => resolveNotificationDefinitionPresentation(row, locale);
+
+const mapPreference = (row: PreferenceRow, locale?: string): UserNotificationPreference => {
+  const requiredChannels = unique(row.required_channels);
+  const required = new Set(requiredChannels);
+  const selectedChannels = unique(row.customized ? (row.channels ?? []) : row.recommended_channels).filter(
+    (channel) => !required.has(channel),
+  );
+  const presentation = definitionPresentation(row, locale);
+  return {
+    id: row.id,
+    appId: row.app_id,
+    kind: row.kind,
+    label: presentation.label,
+    description: presentation.description,
+    recommendedChannels: unique(row.recommended_channels),
+    requiredChannels,
+    selectedChannels,
+    effectiveChannels: unique([...requiredChannels, ...selectedChannels]),
+    customized: row.customized,
+  };
+};
+
+const listPreferences = async (userId: string, locale?: string): Promise<UserNotificationPreferencesResponse> => {
+  const rows = await sql<PreferenceRow[]>`
+    SELECT d.id, d.app_id, d.kind, d.label, d.description, d.presentation,
+           d.recommended_channels, d.required_channels, p.channels,
+           (p.user_id IS NOT NULL) AS customized
+    FROM notifications.definitions d
+    LEFT JOIN notifications.preferences p
+      ON p.definition_id = d.id AND p.user_id = ${userId}::uuid
+    WHERE d.active = true AND d.recipient_kind = 'user'
+    ORDER BY d.app_id, d.id
+  `;
+  const definitions = rows
+    .map((row) => mapPreference(row, locale))
+    .sort(
+      (left, right) =>
+        left.appId.localeCompare(right.appId) ||
+        left.label.localeCompare(right.label, normalizeLocale(locale)) ||
+        left.id.localeCompare(right.id),
+    );
+  return { availableChannels: listNotificationChannels(), definitions };
+};
+
+const findPreference = async (userId: string, definitionId: string, locale?: string): Promise<UserNotificationPreference | null> => {
+  const result = await listPreferences(userId, locale);
+  return result.definitions.find((definition) => definition.id === definitionId) ?? null;
+};
+
+const setPreference = async (config: {
+  userId: string;
+  definitionId: string;
+  channels: string[];
+  locale?: string;
+}): Promise<MutationResult<UserNotificationPreference>> => {
+  const rows = await sql<{ required_channels: string[] }[]>`
+    SELECT required_channels
+    FROM notifications.definitions
+    WHERE id = ${config.definitionId} AND active = true AND recipient_kind = 'user'
+    LIMIT 1
+  `;
+  const definition = rows[0];
+  if (!definition) return { ok: false, error: "Notification preference not found", status: 404 };
+
+  const required = new Set(definition.required_channels);
+  const channels = unique(config.channels.map((channel) => channel.trim()).filter(Boolean)).filter((channel) => !required.has(channel));
+  const available = new Set(listNotificationChannels());
+  const unavailable = channels.filter((channel) => !available.has(channel));
+  if (unavailable.length > 0) {
+    return { ok: false, error: `Unavailable notification channel: ${unavailable.join(", ")}`, status: 400 };
+  }
+
+  await sql`
+    INSERT INTO notifications.preferences (user_id, definition_id, channels, updated_at)
+    VALUES (${config.userId}::uuid, ${config.definitionId}, ${toPgTextArray(channels)}::text[], now())
+    ON CONFLICT (user_id, definition_id) DO UPDATE
+    SET channels = EXCLUDED.channels, updated_at = now()
+  `;
+  const preference = await findPreference(config.userId, config.definitionId, config.locale);
+  if (!preference) return { ok: false, error: "Notification preference not found", status: 404 };
+  return { ok: true, data: preference };
+};
+
+const resetPreference = async (config: {
+  userId: string;
+  definitionId: string;
+  locale?: string;
+}): Promise<MutationResult<UserNotificationPreference>> => {
+  const existing = await findPreference(config.userId, config.definitionId, config.locale);
+  if (!existing) return { ok: false, error: "Notification preference not found", status: 404 };
+  await sql`
+    DELETE FROM notifications.preferences
+    WHERE user_id = ${config.userId}::uuid AND definition_id = ${config.definitionId}
+  `;
+  const preference = await findPreference(config.userId, config.definitionId, config.locale);
+  if (!preference) return { ok: false, error: "Notification preference not found", status: 404 };
+  return { ok: true, data: preference };
+};
+
+const publicDeliveryError = (code: string | null, status: NotificationDeliveryStatus): { code: string | null; message: string | null } => {
+  if (!code) return { code: null, message: null };
+  switch (code) {
+    case "disabled_by_user":
+      return { code, message: "Delivery is disabled in your notification preferences." };
+    case "no_preferred_channel":
+      return { code, message: "No preferred delivery channel is configured." };
+    case "channel_unavailable":
+      return { code, message: "This delivery channel is currently unavailable." };
+    case "no_endpoint":
+      return { code, message: "No registered destination is available for this channel." };
+    case "fallback_not_needed":
+      return { code, message: "Another preferred channel delivered this notification." };
+    case "lease_recovered":
+      return { code, message: "Delivery resumed after an interrupted attempt." };
+    default:
+      return {
+        code: "provider_error",
+        message:
+          status === "pending" || status === "sending"
+            ? "The provider reported an error; delivery will retry."
+            : "The provider could not deliver this notification.",
+      };
+  }
+};
+
+const listHistory = async (config: {
+  userId: string;
+  page: number;
+  perPage: number;
+  status?: NotificationDeliveryStatus;
+  locale?: string;
+}): Promise<UserNotificationHistoryResponse> => {
+  const page = Math.max(1, config.page);
+  const perPage = Math.min(100, Math.max(1, config.perPage));
+  const offset = (page - 1) * perPage;
+  const status = config.status ?? null;
+  const [countRows, rows] = await Promise.all([
+    sql<{ count: number }[]>`
+      SELECT COUNT(*)::int AS count
+      FROM notifications.deliveries d
+      JOIN notifications.events e ON e.id = d.event_id
+      WHERE e.recipient_user_id = ${config.userId}::uuid
+        AND (${status}::text IS NULL OR d.status = ${status})
+    `,
+    sql<HistoryRow[]>`
+      SELECT d.id, d.event_id, e.definition_id, n.app_id, n.label, n.description, n.presentation, e.title, e.target_href,
+             d.channel, d.destination_label, d.required, d.status, d.attempt_count,
+             d.error_code, d.created_at, d.delivered_at
+      FROM notifications.deliveries d
+      JOIN notifications.events e ON e.id = d.event_id
+      JOIN notifications.definitions n ON n.id = e.definition_id
+      WHERE e.recipient_user_id = ${config.userId}::uuid
+        AND (${status}::text IS NULL OR d.status = ${status})
+      ORDER BY e.created_at DESC, d.required DESC, d.route_priority NULLS FIRST, d.created_at, d.id
+      LIMIT ${perPage} OFFSET ${offset}
+    `,
+  ]);
+  const total = Number(countRows[0]?.count ?? 0);
+  return {
+    items: rows.map((row) => {
+      const error = publicDeliveryError(row.error_code, row.status);
+      const presentation = definitionPresentation(row, config.locale);
+      return {
+        id: row.id,
+        eventId: row.event_id,
+        definitionId: row.definition_id,
+        appId: row.app_id,
+        label: presentation.label,
+        title: row.title,
+        targetHref: row.target_href && isSafeNotificationTargetHref(row.target_href) ? row.target_href : null,
+        channel: row.channel,
+        destinationLabel: row.destination_label,
+        required: row.required,
+        status: row.status,
+        attemptCount: row.attempt_count,
+        errorCode: error.code,
+        errorMessage: error.message,
+        createdAt: row.created_at.toISOString(),
+        deliveredAt: row.delivered_at?.toISOString() ?? null,
+      };
+    }),
+    total,
+    page,
+    perPage,
+    totalPages: total === 0 ? 0 : Math.ceil(total / perPage),
+  };
+};
+
+export const userNotifications = {
+  preferences: { list: listPreferences, set: setPreference, reset: resetPreference },
+  history: { list: listHistory },
+} as const;

package/src/services/notifications/web-push-transport.ts

@@ -0,0 +1,135 @@
+import type { ClientRequest, IncomingMessage } from "node:http";
+import { type RequestOptions as HttpsRequestOptions, request as httpsRequest } from "node:https";
+import webpush, { type RequestDetails as WebPushRequestDetails, type RequestOptions as WebPushRequestOptions } from "web-push";
+import { type BrowserPushSubscription, BrowserPushSubscriptionSchema } from "../../contracts/user-notifications";
+import { normalizeNetworkHostname } from "../../shared/network-address";
+import { type PublicNetworkAddress, resolvePublicNetworkAddresses } from "../network-security";
+
+const RESPONSE_LIMIT_BYTES = 64 * 1_024;
+const REQUEST_TIMEOUT_MS = 15_000;
+const MAX_ADDRESS_ATTEMPTS = 4;
+
+type RequestFactory = (options: HttpsRequestOptions, callback: (response: IncomingMessage) => void) => ClientRequest;
+type RequestDetailsFactory = (
+  subscription: BrowserPushSubscription,
+  payload: string,
+  options: WebPushRequestOptions,
+) => WebPushRequestDetails;
+
+type WebPushTransportDeps = {
+  generateRequestDetails?: RequestDetailsFactory;
+  request?: RequestFactory;
+  resolve?: (hostname: string) => Promise<PublicNetworkAddress[]>;
+};
+
+export const buildPinnedWebPushRequests = async (
+  subscription: BrowserPushSubscription,
+  payload: string,
+  options: WebPushRequestOptions,
+  deps: WebPushTransportDeps = {},
+): Promise<{ body: Buffer | null; endpoint: string; attempts: HttpsRequestOptions[] }> => {
+  const validatedSubscription = BrowserPushSubscriptionSchema.parse(subscription);
+  const endpoint = new URL(validatedSubscription.endpoint);
+  const hostname = normalizeNetworkHostname(endpoint.hostname);
+  const resolvedAddresses = await (deps.resolve ?? resolvePublicNetworkAddresses)(hostname);
+  const uniqueAddresses = resolvedAddresses.filter(
+    (target, index) => resolvedAddresses.findIndex((candidate) => candidate.address === target.address) === index,
+  );
+  const firstFamily = uniqueAddresses[0]?.family ?? 4;
+  const primary = uniqueAddresses.filter((target) => target.family === firstFamily);
+  const secondary = uniqueAddresses.filter((target) => target.family !== firstFamily);
+  const addresses: PublicNetworkAddress[] = [];
+  for (let index = 0; addresses.length < MAX_ADDRESS_ATTEMPTS && (index < primary.length || index < secondary.length); index++) {
+    const primaryTarget = primary[index];
+    const secondaryTarget = secondary[index];
+    if (primaryTarget) addresses.push(primaryTarget);
+    if (secondaryTarget && addresses.length < MAX_ADDRESS_ATTEMPTS) addresses.push(secondaryTarget);
+  }
+  if (addresses.length === 0) throw new Error("Push endpoint has no public network address");
+
+  const details = (deps.generateRequestDetails ?? webpush.generateRequestDetails)(validatedSubscription, payload, options);
+  if (details.endpoint !== validatedSubscription.endpoint) throw new Error("Web Push request endpoint changed during preparation");
+  return {
+    body: details.body,
+    endpoint: validatedSubscription.endpoint,
+    attempts: addresses.map((target) => ({
+      protocol: "https:",
+      hostname: target.address,
+      port: endpoint.port ? Number(endpoint.port) : 443,
+      path: `${endpoint.pathname}${endpoint.search}`,
+      method: details.method,
+      headers: { ...details.headers, host: endpoint.host },
+      servername: hostname,
+      rejectUnauthorized: true,
+      timeout: REQUEST_TIMEOUT_MS,
+    })),
+  };
+};
+
+const sendPreparedWebPushRequest = async (request: RequestFactory, options: HttpsRequestOptions, body: Buffer | null): Promise<void> =>
+  new Promise<void>((resolve, reject) => {
+    let settled = false;
+    let responseReceived = false;
+    const finish = (result: { error?: Error }) => {
+      if (settled) return;
+      settled = true;
+      if (result.error) {
+        reject(responseReceived ? Object.assign(result.error, { providerResponse: true }) : result.error);
+      } else {
+        resolve();
+      }
+    };
+    const outgoing = request(options, (response) => {
+      responseReceived = true;
+      let responseBody = "";
+      let bytes = 0;
+      response.on("data", (chunk: Buffer | string) => {
+        bytes += Buffer.byteLength(chunk);
+        if (bytes > RESPONSE_LIMIT_BYTES) {
+          response.destroy();
+          finish({ error: new Error("Web Push provider response is too large") });
+          return;
+        }
+        responseBody += chunk.toString();
+      });
+      response.on("end", () => {
+        const statusCode = response.statusCode ?? 0;
+        if (statusCode >= 200 && statusCode <= 299) {
+          finish({});
+          return;
+        }
+        finish({
+          error: Object.assign(new Error("Web Push provider returned an unexpected response"), {
+            statusCode,
+            responseBody,
+          }),
+        });
+      });
+      response.on("error", (error) => finish({ error }));
+    });
+    outgoing.on("timeout", () => outgoing.destroy(new Error("Web Push provider request timed out")));
+    outgoing.on("error", (error) => finish({ error }));
+    if (body) outgoing.write(body);
+    outgoing.end();
+  });
+
+export const sendPinnedWebPush = async (
+  subscription: BrowserPushSubscription,
+  payload: string,
+  options: WebPushRequestOptions,
+  deps: WebPushTransportDeps = {},
+): Promise<void> => {
+  const request = deps.request ?? httpsRequest;
+  const prepared = await buildPinnedWebPushRequests(subscription, payload, options, deps);
+  let lastError: unknown;
+  for (const attempt of prepared.attempts) {
+    try {
+      await sendPreparedWebPushRequest(request, attempt, prepared.body);
+      return;
+    } catch (error) {
+      if (error && typeof error === "object" && "providerResponse" in error) throw error;
+      lastError = error;
+    }
+  }
+  throw lastError instanceof Error ? lastError : new Error("Web Push provider request failed");
+};

package/src/services/oauth-tokens.ts

@@ -0,0 +1,209 @@
+import { sql } from "bun";
+import { createRemoteJWKSet, decodeProtectedHeader, errors, type JWTPayload, type JWTVerifyGetKey, jwtVerify } from "jose";
+import type { User } from "../contracts/shared";
+import { isAccountCategoryAllowed } from "./account-category-policy";
+import { isAccountExpired } from "./account-model";
+import { IDENTITY_JWKS_MAX_AGE_SECONDS } from "./identity/constants";
+import { getIdentityRuntimeConfig } from "./identity/runtime-config";
+import type { ServiceAccount } from "./service-accounts";
+import { buildProjectedUser, userProjectionSql } from "./session/user";
+
+type ServiceAccountActorRow = Record<string, unknown> & {
+  service_account_id: string;
+  service_account_name: string;
+  service_account_kind: ServiceAccount["kind"];
+  service_account_status: ServiceAccount["status"];
+  delegated_user_id: string | null;
+  app_id: string | null;
+  resource_type: string | null;
+  resource_id: string | null;
+  service_account_created_by: string | null;
+  service_account_created_at: Date | string;
+};
+
+type RemoteSetState = { key: JWTVerifyGetKey; lastForcedRefreshAt: number };
+const remoteSets = new Map<string, RemoteSetState>();
+
+const createRemoteSet = (url: URL): JWTVerifyGetKey =>
+  createRemoteJWKSet(url, {
+    cacheMaxAge: IDENTITY_JWKS_MAX_AGE_SECONDS * 1_000,
+    cooldownDuration: 30_000,
+    timeoutDuration: 5_000,
+  });
+
+const remoteSet = (url: URL): RemoteSetState => {
+  const existing = remoteSets.get(url.href);
+  if (existing) return existing;
+  const created = { key: createRemoteSet(url), lastForcedRefreshAt: 0 };
+  remoteSets.set(url.href, created);
+  return created;
+};
+
+const parseScopeClaim = (payload: JWTPayload): string[] => {
+  const value = payload.scope;
+  if (typeof value !== "string") return [];
+  return value
+    .split(/\s+/)
+    .map((scope) => scope.trim())
+    .filter(Boolean);
+};
+
+export type AuthenticatedOAuthToken =
+  | {
+      kind: "user";
+      payload: JWTPayload;
+      user: User;
+      scopes: string[];
+    }
+  | {
+      kind: "service_account";
+      payload: JWTPayload;
+      serviceAccount: ServiceAccount;
+      delegatedUser: User | null;
+      scopes: string[];
+    };
+
+const getStringClaim = (payload: JWTPayload, key: string): string | null => {
+  const value = payload[key];
+  return typeof value === "string" && value.length > 0 ? value : null;
+};
+
+const uuidClaim = (payload: JWTPayload, key: string): string | null => {
+  const value = getStringClaim(payload, key);
+  return value && /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value) ? value : null;
+};
+
+const mapServiceAccount = (row: ServiceAccountActorRow): ServiceAccount => ({
+  id: row.service_account_id,
+  name: row.service_account_name,
+  kind: row.service_account_kind,
+  status: row.service_account_status,
+  delegatedUserId: row.delegated_user_id,
+  appId: row.app_id,
+  resourceType: row.resource_type,
+  resourceId: row.resource_id,
+  createdBy: row.service_account_created_by,
+  createdAt: new Date(row.service_account_created_at).toISOString(),
+});
+
+/** Resolve the live OAuth client/principal, then check current account-category policy. */
+export const resolveOAuthTokenActor = async (
+  payload: JWTPayload,
+  groupsAdmin: string[],
+  query: typeof sql = sql,
+): Promise<AuthenticatedOAuthToken | null> => {
+  const clientId = getStringClaim(payload, "client_id");
+  if (!clientId) return null;
+  const scopes = parseScopeClaim(payload);
+  const rawServiceAccountId = getStringClaim(payload, "service_account_id");
+
+  if (rawServiceAccountId) {
+    const serviceAccountId = uuidClaim(payload, "service_account_id");
+    if (!serviceAccountId) return null;
+    const rows = await query<ServiceAccountActorRow[]>`
+      SELECT
+        sa.id AS service_account_id,
+        sa.name AS service_account_name,
+        sa.kind AS service_account_kind,
+        sa.status AS service_account_status,
+        sa.delegated_user_id,
+        sa.app_id,
+        sa.resource_type,
+        sa.resource_id,
+        sa.created_by AS service_account_created_by,
+        sa.created_at AS service_account_created_at,
+        ${userProjectionSql(groupsAdmin)}
+      FROM oauth.clients c
+      JOIN auth.service_accounts sa ON sa.id = ${serviceAccountId}::uuid AND sa.status = 'active'
+      LEFT JOIN auth.users u ON u.id = sa.delegated_user_id
+      LEFT JOIN auth.user_ipa_data ui ON ui.user_id = u.id
+      WHERE c.client_id = ${clientId}
+    `;
+    const row = rows[0];
+    if (!row) return null;
+    const serviceAccount = mapServiceAccount(row);
+    const delegatedUser = serviceAccount.delegatedUserId ? buildProjectedUser(row) : null;
+    if (serviceAccount.kind === "user_delegated" && !delegatedUser) return null;
+    if (delegatedUser && isAccountExpired(delegatedUser.accountExpires)) return null;
+    if (delegatedUser && !(await isAccountCategoryAllowed(delegatedUser, query))) return null;
+    return { kind: "service_account", payload, serviceAccount, delegatedUser, scopes };
+  }
+
+  const rawUserId = getStringClaim(payload, "id");
+  const userId = rawUserId ? uuidClaim(payload, "id") : null;
+  if (rawUserId && !userId) return null;
+  const uid = getStringClaim(payload, "uid") ?? (typeof payload.sub === "string" ? payload.sub : null);
+  if (!userId && !uid) return null;
+  const predicate = userId ? sql`u.id = ${userId}::uuid` : sql`u.uid = ${uid}`;
+  const rows = await query<Record<string, unknown>[]>`
+    SELECT ${userProjectionSql(groupsAdmin)}
+    FROM oauth.clients c
+    JOIN auth.users u ON ${predicate}
+    LEFT JOIN auth.user_ipa_data ui ON ui.user_id = u.id
+    WHERE c.client_id = ${clientId}
+  `;
+  const user = rows[0] ? buildProjectedUser(rows[0]) : null;
+  if (!user || isAccountExpired(user.accountExpires)) return null;
+  if (!(await isAccountCategoryAllowed(user, query))) return null;
+  return { kind: "user", payload, user, scopes };
+};
+
+export const verifyAccessToken = async (
+  token: string,
+  expectedAudience: string | string[] = "cloud",
+  options: {
+    issuer?: string;
+    key?: JWTVerifyGetKey;
+    jwksUrl?: URL;
+    groupsAdmin?: string[];
+    query?: typeof sql;
+  } = {},
+): Promise<AuthenticatedOAuthToken | null> => {
+  let remote: { url: URL; state: RemoteSetState } | null = null;
+  try {
+    const header = decodeProtectedHeader(token);
+    if (header.alg !== "RS256" || typeof header.kid !== "string" || header.kid.length === 0 || header.kid.length > 200) return null;
+
+    const completeOverride = Boolean(options.issuer && (options.key || options.jwksUrl) && options.groupsAdmin);
+    const runtime = completeOverride ? null : await getIdentityRuntimeConfig();
+    const issuer = options.issuer ?? runtime!.issuer;
+    const jwksUrl = options.jwksUrl ?? runtime?.oauthJwksUrl;
+    const groupsAdmin = options.groupsAdmin ?? runtime!.groupsAdmin;
+    const state = options.key || !jwksUrl ? null : remoteSet(jwksUrl);
+    if (state && jwksUrl) remote = { url: jwksUrl, state };
+    let key = options.key ?? state?.key;
+    if (!key) return null;
+
+    const verify = (candidate: JWTVerifyGetKey) =>
+      jwtVerify(token, candidate, {
+        algorithms: ["RS256"],
+        issuer,
+        audience: expectedAudience,
+      });
+    let verified: Awaited<ReturnType<typeof verify>>;
+    try {
+      verified = await verify(key);
+    } catch (error) {
+      if (!(error instanceof errors.JWKSNoMatchingKey) || !remote) throw error;
+      const now = Date.now();
+      if (now - remote.state.lastForcedRefreshAt < 30_000) throw error;
+      remote.state.lastForcedRefreshAt = now;
+      key = createRemoteSet(remote.url);
+      remote.state.key = key;
+      verified = await verify(key);
+    }
+
+    if (verified.payload.token_use !== "access") return null;
+    return resolveOAuthTokenActor(verified.payload, groupsAdmin, options.query);
+  } catch {
+    return null;
+  }
+};
+
+export const clearOAuthVerifierCachesForTest = (): void => {
+  remoteSets.clear();
+};
+
+export const oauthTokens = {
+  verifyAccessToken,
+};