qarpeo 0.0.0-alpha.10

package/dist/runtime/server/utils/impersonation.mjs

@@ -0,0 +1,298 @@
+import { useNitroApp } from "nitro/app";
+import { createError } from "nuxt/server";
+import { getD1Binding } from "../../db.mjs";
+import { ensureAuthTables } from "./auth.mjs";
+import { hashSessionToken, getAuthSession, setAuthSession } from "./session.mjs";
+function getD1(event) {
+  const bindingName = globalThis.process?.env?.QARPEO_DEFAULT_DB_BINDING || "DB";
+  return getD1Binding(bindingName, event);
+}
+const TOKEN_PREFIX = "qp_live_";
+export async function startImpersonation(event, targetUserId) {
+  const session = await getAuthSession(event);
+  const adminUser = session?.user;
+  if (!adminUser?.id) {
+    throw createError({ statusCode: 401, statusMessage: "Unauthorized" });
+  }
+  if (adminUser.role !== "admin" && adminUser.role !== "super_admin") {
+    throw createError({
+      statusCode: 403,
+      statusMessage: "Forbidden",
+      message: "Only admins can impersonate users"
+    });
+  }
+  if (session?.impersonator) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: "Bad Request",
+      message: "Already in an impersonation session. Stop the current session first."
+    });
+  }
+  if (targetUserId === adminUser.id) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: "Bad Request",
+      message: "Cannot impersonate yourself"
+    });
+  }
+  const d1 = getD1(event);
+  await ensureAuthTables(d1);
+  const dbTarget = await d1.prepare(
+    "SELECT id, email, name, avatar_url, role, email_verified FROM _qarpeo_users WHERE id = ? LIMIT 1"
+  ).bind(targetUserId).first();
+  if (!dbTarget) {
+    throw createError({
+      statusCode: 404,
+      statusMessage: "Not Found",
+      message: "Target user not found"
+    });
+  }
+  if (dbTarget.role === "admin" || dbTarget.role === "super_admin") {
+    throw createError({
+      statusCode: 403,
+      statusMessage: "Forbidden",
+      message: "Cannot impersonate another admin"
+    });
+  }
+  const targetUser = {
+    id: dbTarget.id,
+    email: dbTarget.email,
+    name: dbTarget.name,
+    avatarUrl: dbTarget.avatar_url,
+    role: dbTarget.role,
+    emailVerified: Boolean(dbTarget.email_verified)
+  };
+  await setAuthSession(event, {
+    ...session,
+    user: targetUser,
+    impersonator: adminUser,
+    // Strip org context when impersonating
+    currentOrganizationId: null,
+    currentOrganization: null,
+    currentRole: null
+  });
+  const timestamp = Date.now();
+  try {
+    const nitroApp = useNitroApp();
+    await nitroApp.hooks?.callHook("qarpeo:auth:impersonation:start", {
+      adminId: adminUser.id,
+      targetUserId,
+      timestamp
+    });
+  } catch (hookErr) {
+    console.warn(
+      "[qarpeo:auth] Error calling qarpeo:auth:impersonation:start hook:",
+      hookErr?.message || hookErr
+    );
+  }
+  console.log(
+    `[qarpeo:audit] impersonation:start admin=${adminUser.id} target=${targetUserId} at=${timestamp}`
+  );
+  return { success: true, user: targetUser };
+}
+export async function stopImpersonation(event) {
+  const session = await getAuthSession(event);
+  const impersonator = session?.impersonator;
+  if (!impersonator) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: "Bad Request",
+      message: "No active impersonation session"
+    });
+  }
+  const targetUserId = session?.user?.id || "";
+  const adminId = impersonator.id;
+  await setAuthSession(event, {
+    ...session,
+    user: impersonator,
+    impersonator: null,
+    currentOrganizationId: null,
+    currentOrganization: null,
+    currentRole: null
+  });
+  const timestamp = Date.now();
+  try {
+    const nitroApp = useNitroApp();
+    await nitroApp.hooks?.callHook("qarpeo:auth:impersonation:stop", {
+      adminId,
+      targetUserId,
+      timestamp
+    });
+  } catch (hookErr) {
+    console.warn(
+      "[qarpeo:auth] Error calling qarpeo:auth:impersonation:stop hook:",
+      hookErr?.message || hookErr
+    );
+  }
+  console.log(
+    `[qarpeo:audit] impersonation:stop admin=${adminId} target=${targetUserId} at=${timestamp}`
+  );
+  return { success: true, user: impersonator };
+}
+export async function createApiToken(event, input) {
+  const session = await getAuthSession(event);
+  const user = session?.user;
+  if (!user?.id) {
+    throw createError({ statusCode: 401, statusMessage: "Unauthorized" });
+  }
+  const name = input.name?.trim();
+  if (!name) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: "Bad Request",
+      message: "Token name is required"
+    });
+  }
+  const d1 = getD1(event);
+  await ensureAuthTables(d1);
+  const randomBytes = new Uint8Array(32);
+  crypto.getRandomValues(randomBytes);
+  const rawSecret = Array.from(randomBytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+  const rawToken = `${TOKEN_PREFIX}${rawSecret}`;
+  const tokenHash = await hashSessionToken(rawToken);
+  const scopes = input.scopes && input.scopes.length > 0 ? input.scopes : ["*"];
+  const now = Date.now();
+  const expiresAt = input.expiresInDays ? now + input.expiresInDays * 24 * 60 * 60 * 1e3 : null;
+  const id = crypto.randomUUID();
+  await d1.prepare(`
+      INSERT INTO _qarpeo_api_tokens (id, user_id, name, token_hash, scopes, expires_at, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).bind(id, user.id, name, tokenHash, JSON.stringify(scopes), expiresAt, now).run();
+  return { id, token: rawToken, name, scopes, expiresAt, createdAt: now };
+}
+export async function listApiTokens(event) {
+  const session = await getAuthSession(event);
+  const user = session?.user;
+  if (!user?.id) {
+    throw createError({ statusCode: 401, statusMessage: "Unauthorized" });
+  }
+  const d1 = getD1(event);
+  await ensureAuthTables(d1);
+  const results = await d1.prepare(`
+      SELECT id, name, scopes, last_used_at as lastUsedAt, expires_at as expiresAt, created_at as createdAt
+      FROM _qarpeo_api_tokens
+      WHERE user_id = ?
+      ORDER BY created_at DESC
+    `).bind(user.id).all();
+  return (results.results || []).map((row) => ({
+    id: row.id,
+    name: row.name,
+    scopes: row.scopes ? JSON.parse(row.scopes) : ["*"],
+    lastUsedAt: row.lastUsedAt || null,
+    expiresAt: row.expiresAt || null,
+    createdAt: row.createdAt
+  }));
+}
+export async function revokeApiToken(event, tokenId) {
+  const session = await getAuthSession(event);
+  const user = session?.user;
+  if (!user?.id) {
+    throw createError({ statusCode: 401, statusMessage: "Unauthorized" });
+  }
+  const d1 = getD1(event);
+  await ensureAuthTables(d1);
+  const existing = await d1.prepare("SELECT user_id FROM _qarpeo_api_tokens WHERE id = ? LIMIT 1").bind(tokenId).first();
+  if (!existing) {
+    throw createError({ statusCode: 404, statusMessage: "Not Found", message: "Token not found" });
+  }
+  const isOwner = existing.user_id === user.id;
+  const isAdmin = user.role === "admin" || user.role === "super_admin";
+  if (!isOwner && !isAdmin) {
+    throw createError({ statusCode: 403, statusMessage: "Forbidden", message: "Permission denied" });
+  }
+  await d1.prepare("DELETE FROM _qarpeo_api_tokens WHERE id = ?").bind(tokenId).run();
+  return { success: true };
+}
+export async function verifyApiToken(event, rawToken) {
+  if (!rawToken.startsWith(TOKEN_PREFIX)) {
+    throw createError({
+      statusCode: 401,
+      statusMessage: "Unauthorized",
+      message: "Invalid token format"
+    });
+  }
+  let d1;
+  try {
+    d1 = getD1(event);
+  } catch {
+    throw createError({
+      statusCode: 500,
+      statusMessage: "Internal Server Error",
+      message: "Database unavailable"
+    });
+  }
+  const tokenHash = await hashSessionToken(rawToken);
+  const tokenRecord = await d1.prepare(
+    "SELECT id, user_id, scopes, expires_at FROM _qarpeo_api_tokens WHERE token_hash = ? LIMIT 1"
+  ).bind(tokenHash).first();
+  if (!tokenRecord) {
+    throw createError({
+      statusCode: 401,
+      statusMessage: "Unauthorized",
+      message: "Invalid or revoked token"
+    });
+  }
+  if (tokenRecord.expires_at && Date.now() > tokenRecord.expires_at) {
+    await d1.prepare("DELETE FROM _qarpeo_api_tokens WHERE id = ?").bind(tokenRecord.id).run();
+    throw createError({
+      statusCode: 401,
+      statusMessage: "Unauthorized",
+      message: "Token has expired"
+    });
+  }
+  try {
+    const ctx = event.context?.cloudflare?.ctx;
+    if (ctx?.waitUntil) {
+      ctx.waitUntil(
+        d1.prepare("UPDATE _qarpeo_api_tokens SET last_used_at = ? WHERE id = ?").bind(Date.now(), tokenRecord.id).run()
+      );
+    } else {
+      await d1.prepare("UPDATE _qarpeo_api_tokens SET last_used_at = ? WHERE id = ?").bind(Date.now(), tokenRecord.id).run();
+    }
+  } catch {
+  }
+  const dbUser = await d1.prepare(
+    "SELECT id, email, name, avatar_url, role, email_verified FROM _qarpeo_users WHERE id = ? LIMIT 1"
+  ).bind(tokenRecord.user_id).first();
+  if (!dbUser) {
+    throw createError({
+      statusCode: 401,
+      statusMessage: "Unauthorized",
+      message: "Token user not found"
+    });
+  }
+  const user = {
+    id: dbUser.id,
+    email: dbUser.email,
+    name: dbUser.name,
+    avatarUrl: dbUser.avatar_url,
+    role: dbUser.role,
+    emailVerified: Boolean(dbUser.email_verified)
+  };
+  const scopes = tokenRecord.scopes ? JSON.parse(tokenRecord.scopes) : ["*"];
+  return { user, tokenId: tokenRecord.id, scopes, userId: tokenRecord.user_id };
+}
+export function hasApiTokenScope(scopes, required) {
+  if (scopes.includes("*")) return true;
+  return scopes.includes(required);
+}
+export async function requireApiToken(event, options = {}) {
+  const authHeader = event.headers?.get?.("authorization") || "";
+  const raw = authHeader.startsWith("Bearer ") ? authHeader.slice(7).trim() : "";
+  if (!raw) {
+    throw createError({
+      statusCode: 401,
+      statusMessage: "Unauthorized",
+      message: "Authorization: Bearer <token> header is required"
+    });
+  }
+  const context = await verifyApiToken(event, raw);
+  if (options.scope && !hasApiTokenScope(context.scopes, options.scope)) {
+    throw createError({
+      statusCode: 403,
+      statusMessage: "Forbidden",
+      message: `Token does not have required scope: ${options.scope}`
+    });
+  }
+  return context;
+}

package/dist/runtime/server/utils/jobs.d.ts

@@ -0,0 +1,70 @@
+import type { CFEvent } from "../../types/index";
+export interface JobContext {
+    /** Unique message/job ID */
+    id: string;
+    /** Timestamp when the job was dispatched */
+    timestamp: Date;
+    /** Delivery attempt count (starts at 1) */
+    attempts: number;
+    /** Name of the job being executed */
+    jobName: string;
+    /** Manually request a retry for this message */
+    retry: () => void;
+    /** Manually acknowledge this message */
+    ack: () => void;
+}
+export type JobHandler<T = any> = (data: T, context: JobContext) => Promise<void> | void;
+export interface JobDefinitionOptions {
+    /**
+     * Cloudflare Queue binding name override.
+     *
+     * @default "QUEUE"
+     */
+    binding?: string;
+    /**
+     * Maximum retry attempts before discarding or dead-lettering.
+     *
+     * @default 3
+     */
+    maxRetries?: number;
+}
+export interface JobDefinition<T = any> {
+    name: string;
+    handler: JobHandler<T>;
+    options?: JobDefinitionOptions;
+}
+export interface JobEnvelope<T = any> {
+    __jobName: string;
+    data: T;
+    id: string;
+    timestamp: number;
+}
+/**
+ * Define a typed background job handler.
+ *
+ * @example
+ *   // server/jobs/send-welcome-email.ts
+ *   export default defineJob("send-welcome-email", async (data: { userId: string }, ctx) => {
+ *     // Background work here...
+ *   })
+ */
+export declare function defineJob<T = any>(nameOrHandler: string | JobHandler<T>, handlerOrOptions?: JobHandler<T> | JobDefinitionOptions, options?: JobDefinitionOptions): JobDefinition<T>;
+/**
+ * Dispatch a background job for asynchronous processing on Cloudflare Queues.
+ *
+ * @example
+ *   await dispatchJob("send-welcome-email", { userId: "user_123" })
+ */
+export declare function dispatchJob<T = any>(name: string, data: T, options?: {
+    binding?: string;
+    delaySeconds?: number;
+    event?: CFEvent;
+}): Promise<void>;
+/**
+ * Dispatches an incoming Cloudflare Queue batch to registered job handlers. Used internally by the
+ * Qarpeo queue consumer plugin.
+ */
+export declare function runJobsBatch(batch: any, jobModules: Record<string, any>, options?: {
+    customQueueHandler?: any;
+    maxRetries?: number;
+}): Promise<void>;

package/dist/runtime/server/utils/jobs.mjs

@@ -0,0 +1,125 @@
+import { useQueue } from "../../queue.mjs";
+export function defineJob(nameOrHandler, handlerOrOptions, options) {
+  if (typeof nameOrHandler === "string") {
+    const handler2 = typeof handlerOrOptions === "function" ? handlerOrOptions : () => {
+    };
+    const opts2 = typeof handlerOrOptions === "object" ? handlerOrOptions : options;
+    return {
+      name: nameOrHandler,
+      handler: handler2,
+      options: opts2
+    };
+  }
+  const handler = nameOrHandler;
+  const opts = typeof handlerOrOptions === "object" ? handlerOrOptions : options;
+  return {
+    name: "",
+    handler,
+    options: opts
+  };
+}
+export async function dispatchJob(name, data, options) {
+  const bindingName = options?.binding || (typeof process !== "undefined" ? process.env.QARPEO_DEFAULT_QUEUE_BINDING : void 0) || "QUEUE";
+  const queueClient = useQueue(bindingName, options?.event);
+  const id = typeof crypto !== "undefined" && typeof crypto.randomUUID === "function" ? crypto.randomUUID() : `job_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+  const payload = {
+    __jobName: name,
+    data,
+    id,
+    timestamp: Date.now()
+  };
+  await queueClient.send(payload, {
+    delaySeconds: options?.delaySeconds
+  });
+}
+export async function runJobsBatch(batch, jobModules, options) {
+  if (!batch || !Array.isArray(batch.messages)) return;
+  const defaultMaxRetries = options?.maxRetries ?? 3;
+  const nonJobMessages = [];
+  for (const msg of batch.messages) {
+    const body = msg.body;
+    if (!body || typeof body !== "object" || !body.__jobName) {
+      nonJobMessages.push(msg);
+      continue;
+    }
+    const jobName = body.__jobName;
+    const rawExport = jobModules[jobName];
+    let jobDef = rawExport?.default || rawExport;
+    if (!jobDef) {
+      for (const key of Object.keys(jobModules)) {
+        const mod = jobModules[key]?.default || jobModules[key];
+        if (mod && (mod.name === jobName || key === jobName)) {
+          jobDef = mod;
+          break;
+        }
+      }
+    }
+    const handler = typeof jobDef === "function" ? jobDef : typeof jobDef?.handler === "function" ? jobDef.handler : null;
+    if (!handler) {
+      console.warn(
+        `[qarpeo:jobs] No handler registered for job "${jobName}". Discarding message ID: ${msg.id}`
+      );
+      try {
+        msg.ack?.();
+      } catch {
+      }
+      continue;
+    }
+    const maxRetries = jobDef?.options?.maxRetries ?? defaultMaxRetries;
+    const attempts = msg.attempts || 1;
+    let acknowledged = false;
+    let retried = false;
+    const context = {
+      id: msg.id || body.id || `msg_${Date.now()}`,
+      timestamp: msg.timestamp ? new Date(msg.timestamp) : new Date(body.timestamp || Date.now()),
+      attempts,
+      jobName,
+      retry: () => {
+        retried = true;
+        msg.retry?.();
+      },
+      ack: () => {
+        acknowledged = true;
+        msg.ack?.();
+      }
+    };
+    try {
+      await handler(body.data, context);
+      if (!acknowledged && !retried) {
+        msg.ack?.();
+      }
+    } catch (err) {
+      console.error(
+        `[qarpeo:jobs] Error processing job "${jobName}" (attempt ${attempts}/${maxRetries}):`,
+        err
+      );
+      if (!acknowledged && !retried) {
+        if (attempts < maxRetries) {
+          msg.retry?.();
+        } else {
+          console.error(
+            `[qarpeo:jobs] Job "${jobName}" failed after ${attempts} attempts. Discarding.`
+          );
+          msg.ack?.();
+        }
+      }
+    }
+  }
+  if (nonJobMessages.length > 0 && typeof options?.customQueueHandler === "function") {
+    try {
+      const subBatch = {
+        ...batch,
+        messages: nonJobMessages
+      };
+      await options.customQueueHandler(subBatch);
+    } catch (err) {
+      console.error("[qarpeo:queue] Error in custom queueHandler:", err);
+      for (const msg of nonJobMessages) {
+        try {
+          msg.retry?.();
+        } catch {
+        }
+      }
+    }
+  }
+}

package/dist/runtime/server/utils/kv-store.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shared in-memory KV store for local development and preview mode. Attached to globalThis to
+ * ensure cross-chunk persistence in Nitro/Vite.
+ */
+export interface DevMockKvEntry {
+    value: string;
+    expiration?: number;
+}
+export declare function getDevMockKvStore(): Map<string, DevMockKvEntry>;

package/dist/runtime/server/utils/kv-store.mjs

@@ -0,0 +1,32 @@
+const GLOBAL_KV_KEY = "__qarpeo_dev_mock_kv__";
+export function getDevMockKvStore() {
+  const g = globalThis;
+  if (!g[GLOBAL_KV_KEY]) {
+    g[GLOBAL_KV_KEY] = /* @__PURE__ */ new Map([
+      [
+        "session:sess_usr_9921",
+        {
+          value: JSON.stringify({ userId: "usr_1", role: "admin" }),
+          expiration: Math.floor(Date.now() / 1e3) + 86400
+        }
+      ],
+      [
+        "cache:swr:navigation",
+        {
+          value: JSON.stringify({ items: ["/docs", "/blog", "/pricing"] }),
+          expiration: Math.floor(Date.now() / 1e3) + 3600
+        }
+      ],
+      ["ratelimit:ip:127.0.0.1", { value: "14", expiration: Math.floor(Date.now() / 1e3) + 42 }],
+      [
+        "domain:acme.qarpeo.dev",
+        { value: "tenant_acme_corp", expiration: Math.floor(Date.now() / 1e3) + 86400 * 7 }
+      ],
+      [
+        "domain:portal.example.com",
+        { value: "tenant_acme_corp", expiration: Math.floor(Date.now() / 1e3) + 86400 * 7 }
+      ]
+    ]);
+  }
+  return g[GLOBAL_KV_KEY];
+}

package/dist/runtime/server/utils/mail-suppression.d.ts

@@ -0,0 +1,62 @@
+import type { MailSuppressionReason, MailSuppressionRecord, MailSuppressionType, MailUnsubscribeOptions } from "../../../types";
+export declare function ensureMailSuppressionsTable(db: any): Promise<void>;
+/**
+ * Generates an HMAC-signed one-click unsubscribe token.
+ */
+export declare function generateUnsubscribeToken(email: string, secret?: string): Promise<string>;
+/**
+ * Verifies an HMAC-signed unsubscribe token and extracts the email address.
+ */
+export declare function verifyUnsubscribeToken(token: string, secret?: string): Promise<string | null>;
+/**
+ * Builds RFC 2369 and RFC 8058 compliant `List-Unsubscribe` headers.
+ */
+export declare function buildListUnsubscribeHeaders(options: {
+    to: string;
+    baseUrl: string;
+    config?: MailUnsubscribeOptions;
+    secret?: string;
+}): Promise<Record<string, string>>;
+/**
+ * Adds an email address to the suppression list.
+ */
+export declare function suppressEmail(event: any, options: {
+    email: string;
+    reason?: MailSuppressionReason;
+    type?: MailSuppressionType;
+    source?: string;
+    metadata?: Record<string, any>;
+}): Promise<MailSuppressionRecord>;
+/**
+ * Checks whether an email address is suppressed.
+ */
+export declare function isEmailSuppressed(event: any, email: string): Promise<{
+    suppressed: boolean;
+    reason?: MailSuppressionReason;
+    type?: MailSuppressionType;
+    record?: MailSuppressionRecord;
+}>;
+/**
+ * Removes an email address from the suppression list.
+ */
+export declare function unsuppressEmail(event: any, email: string): Promise<boolean>;
+/**
+ * Lists suppressed emails with pagination and optional search filter.
+ */
+export declare function listSuppressedEmails(event: any, options?: {
+    limit?: number;
+    offset?: number;
+    search?: string;
+    type?: string;
+    reason?: string;
+}): Promise<{
+    items: MailSuppressionRecord[];
+    total: number;
+}>;
+/**
+ * Tracks soft bounces and promotes to suppression if threshold is reached.
+ */
+export declare function recordSoftBounce(event: any, email: string, threshold?: number): Promise<{
+    suppressed: boolean;
+    count: number;
+}>;