@terreno/api 0.7.2 → 0.8.0

package/src/consentApp.ts

@@ -0,0 +1,463 @@
+/**
+ * ConsentApp plugin for @terreno/api.
+ *
+ * Registers consent form management and user consent response routes as a TerrenoPlugin.
+ * Provides admin CRUD for consent forms, read-only access to responses, and user-facing
+ * endpoints for fetching pending consents and submitting responses.
+ */
+
+import type express from "express";
+import {DateTime} from "luxon";
+import {asyncHandler, modelRouter} from "./api";
+import type {User} from "./auth";
+import {authenticateMiddleware} from "./auth";
+import {APIError} from "./errors";
+import {logger} from "./logger";
+import {ConsentForm} from "./models/consentForm";
+import {ConsentResponse} from "./models/consentResponse";
+import {Permissions} from "./permissions";
+import type {TerrenoPlugin} from "./terrenoPlugin";
+import type {ConsentFormDocument} from "./types/consentForm";
+
+export interface ConsentAppOptions {
+  auditTrail?: boolean;
+  aiConfig?: {
+    generateContent: (params: {
+      type: string;
+      description: string;
+      locale: string;
+    }) => Promise<string>;
+    translateContent: (params: {
+      content: string;
+      fromLocale: string;
+      toLocale: string;
+    }) => Promise<string>;
+  };
+  resolveConsentForms?: (
+    user: User,
+    forms: ConsentFormDocument[]
+  ) => ConsentFormDocument[] | Promise<ConsentFormDocument[]>;
+  supportedLocales?: string[];
+}
+
+export class ConsentApp implements TerrenoPlugin {
+  private options: ConsentAppOptions;
+
+  constructor(options: ConsentAppOptions = {}) {
+    this.options = options;
+  }
+
+  register(app: express.Application): void {
+    const {auditTrail, resolveConsentForms, aiConfig} = this.options;
+
+    // Admin CRUD for consent forms
+    app.use(
+      "/consent-forms",
+      modelRouter(ConsentForm, {
+        endpoints: (router) => {
+          if (aiConfig) {
+            // POST /consent-forms/generate - generate consent form content with AI
+            router.post(
+              "/generate",
+              authenticateMiddleware(),
+              asyncHandler(async (req, res) => {
+                const user = req.user as User | undefined;
+                if (!user?.admin) {
+                  throw new APIError({status: 403, title: "Admin access required"});
+                }
+
+                const {type, description, locale = "en"} = req.body;
+                if (!type) {
+                  throw new APIError({status: 400, title: "type is required"});
+                }
+                if (!description) {
+                  throw new APIError({status: 400, title: "description is required"});
+                }
+
+                const content = await aiConfig.generateContent({description, locale, type});
+
+                logger.info("ConsentForm content generated", {locale, type});
+
+                return res.json({data: {content}});
+              })
+            );
+
+            // POST /consent-forms/translate - translate consent form content with AI
+            router.post(
+              "/translate",
+              authenticateMiddleware(),
+              asyncHandler(async (req, res) => {
+                const user = req.user as User | undefined;
+                if (!user?.admin) {
+                  throw new APIError({status: 403, title: "Admin access required"});
+                }
+
+                const {content, fromLocale, toLocale} = req.body;
+                if (!content) {
+                  throw new APIError({status: 400, title: "content is required"});
+                }
+                if (!fromLocale) {
+                  throw new APIError({status: 400, title: "fromLocale is required"});
+                }
+                if (!toLocale) {
+                  throw new APIError({status: 400, title: "toLocale is required"});
+                }
+
+                const translated = await aiConfig.translateContent({content, fromLocale, toLocale});
+
+                logger.info("ConsentForm content translated", {fromLocale, toLocale});
+
+                return res.json({data: {content: translated}});
+              })
+            );
+          }
+
+          // POST /consent-forms/:id/publish - clone form with incremented version and activate
+          router.post(
+            "/:id/publish",
+            authenticateMiddleware(),
+            asyncHandler(async (req, res) => {
+              const user = req.user as User | undefined;
+              if (!user?.admin) {
+                throw new APIError({status: 403, title: "Admin access required"});
+              }
+
+              const form = await ConsentForm.findExactlyOne({_id: req.params.id});
+
+              const newFormData = {
+                active: true,
+                agreeButtonText: form.agreeButtonText,
+                allowDecline: form.allowDecline,
+                captureSignature: form.captureSignature,
+                checkboxes: form.checkboxes,
+                content: form.content,
+                declineButtonText: form.declineButtonText,
+                defaultLocale: form.defaultLocale,
+                order: form.order,
+                required: form.required,
+                requireScrollToBottom: form.requireScrollToBottom,
+                slug: form.slug,
+                title: form.title,
+                type: form.type,
+                version: form.version + 1,
+              };
+
+              const newForm = await ConsentForm.create(newFormData);
+
+              // Deactivate all other versions of the same slug
+              await ConsentForm.updateMany(
+                {_id: {$ne: newForm._id}, slug: form.slug},
+                {active: false}
+              );
+
+              logger.info("ConsentForm published", {
+                newVersion: newForm.version,
+                slug: newForm.slug,
+              });
+
+              return res.json({data: newForm});
+            })
+          );
+        },
+        permissions: {
+          create: [Permissions.IsAdmin],
+          delete: [Permissions.IsAdmin],
+          list: [Permissions.IsAdmin],
+          read: [Permissions.IsAdmin],
+          update: [Permissions.IsAdmin],
+        },
+        queryFields: ["slug", "type", "active", "version"],
+        sort: "order",
+      })
+    );
+
+    // Admin read-only access to consent responses
+    app.use(
+      "/consent-responses",
+      modelRouter(ConsentResponse, {
+        permissions: {
+          create: [],
+          delete: [],
+          list: [Permissions.IsAdmin],
+          read: [Permissions.IsAdmin],
+          update: [],
+        },
+        populatePaths: [
+          {
+            fields: ["title", "slug", "version", "type"],
+            path: "consentFormId",
+          },
+        ],
+      })
+    );
+
+    // User-facing consent endpoints
+    const router = require("express").Router() as express.Router;
+
+    // GET /consents/pending - fetch pending consent forms for the current user
+    router.get(
+      "/pending",
+      authenticateMiddleware(),
+      asyncHandler(async (req, res) => {
+        const user = req.user as User | undefined;
+        if (!user) {
+          throw new APIError({status: 401, title: "Authentication required"});
+        }
+
+        logger.debug("Fetching pending consent forms", {userId: user.id});
+
+        const activeForms = await ConsentForm.find({active: true}).sort({order: 1});
+
+        let resolvedForms: ConsentFormDocument[];
+        if (resolveConsentForms) {
+          resolvedForms = await resolveConsentForms(user, activeForms);
+          logger.debug("resolveConsentForms applied", {
+            activeFormCount: activeForms.length,
+            resolvedFormCount: resolvedForms.length,
+            userAdmin: Boolean(user.admin),
+            userId: user.id,
+          });
+        } else {
+          resolvedForms = activeForms;
+        }
+
+        const existingResponses = await ConsentResponse.find({userId: user.id});
+
+        const respondedFormVersions = new Map<string, number>();
+        for (const response of existingResponses) {
+          const formId = response.consentFormId.toString();
+          respondedFormVersions.set(formId, response.formVersionSnapshot ?? 0);
+        }
+
+        // Fetch the forms corresponding to existing responses to check version matches
+        const respondedFormIds = existingResponses.map((r) => r.consentFormId);
+        const respondedForms = await ConsentForm.find({_id: {$in: respondedFormIds}});
+        const formVersionByFormId = new Map<string, number>();
+        for (const form of respondedForms) {
+          formVersionByFormId.set(form._id.toString(), form.version);
+        }
+
+        // Filter out forms where the user already has a response matching the current version
+        const pendingForms = resolvedForms.filter((form) => {
+          const formId = form._id.toString();
+          // Find responses for this form
+          const matchingResponses = existingResponses.filter(
+            (r) => r.consentFormId.toString() === formId
+          );
+          if (matchingResponses.length === 0) {
+            return true;
+          }
+          // Check if any response matches the current form version
+          return !matchingResponses.some((r) => r.formVersionSnapshot === form.version);
+        });
+
+        const filteredOutByResolverCount = Math.max(activeForms.length - resolvedForms.length, 0);
+        const filteredOutByResponsesCount = Math.max(resolvedForms.length - pendingForms.length, 0);
+
+        logger.info("Pending consent forms fetched", {
+          activeFormCount: activeForms.length,
+          filteredOutByResolverCount,
+          filteredOutByResponsesCount,
+          pendingFormCount: pendingForms.length,
+          resolvedFormCount: resolvedForms.length,
+          responseCount: existingResponses.length,
+          userAdmin: Boolean(user.admin),
+          userId: user.id,
+        });
+
+        return res.json({data: pendingForms});
+      })
+    );
+
+    // POST /consents/respond - submit a consent response
+    router.post(
+      "/respond",
+      authenticateMiddleware(),
+      asyncHandler(async (req, res) => {
+        const user = req.user as User | undefined;
+        if (!user) {
+          throw new APIError({status: 401, title: "Authentication required"});
+        }
+
+        const {agreed, checkboxValues, consentFormId, locale, signature} = req.body;
+
+        if (!consentFormId) {
+          throw new APIError({status: 400, title: "consentFormId is required"});
+        }
+        if (agreed === undefined || agreed === null) {
+          throw new APIError({status: 400, title: "agreed field is required"});
+        }
+        if (!locale) {
+          throw new APIError({status: 400, title: "locale is required"});
+        }
+
+        const form = await ConsentForm.findExactlyOne(
+          {_id: consentFormId},
+          {status: 404, title: "Consent form not found"}
+        );
+
+        if (!form.active) {
+          throw new APIError({status: 400, title: "Consent form is not active"});
+        }
+
+        // Validate signature requirement
+        if (form.captureSignature && agreed && !signature) {
+          throw new APIError({
+            status: 400,
+            title: "Signature is required for this consent form",
+          });
+        }
+
+        // Validate required checkboxes
+        if (agreed && form.checkboxes.length > 0) {
+          const values = checkboxValues ?? {};
+          for (let i = 0; i < form.checkboxes.length; i++) {
+            const checkbox = form.checkboxes[i];
+            if (checkbox.required && !values[i.toString()]) {
+              throw new APIError({
+                status: 400,
+                title: `Required checkbox "${checkbox.label}" must be checked`,
+              });
+            }
+          }
+        }
+
+        const responseData: Record<string, unknown> = {
+          agreed,
+          agreedAt: DateTime.now().toJSDate(),
+          consentFormId: form._id,
+          locale,
+          userId: user.id,
+        };
+
+        if (checkboxValues !== undefined) {
+          responseData.checkboxValues = checkboxValues;
+        }
+
+        if (signature) {
+          responseData.signature = signature;
+          responseData.signedAt = DateTime.now().toJSDate();
+        }
+
+        if (auditTrail) {
+          responseData.ipAddress = req.ip;
+          responseData.userAgent = req.headers["user-agent"];
+          responseData.contentSnapshot =
+            form.content.get(locale) ?? form.content.get(form.defaultLocale);
+          responseData.formVersionSnapshot = form.version;
+        } else {
+          responseData.formVersionSnapshot = form.version;
+        }
+
+        const response = await ConsentResponse.create(responseData);
+
+        logger.info("Consent response recorded", {
+          agreed,
+          consentFormId: form._id.toString(),
+          locale,
+          userId: user.id,
+        });
+
+        return res.json({data: response});
+      })
+    );
+
+    // GET /consents/my - fetch the current user's consent responses with form data
+    router.get(
+      "/my",
+      authenticateMiddleware(),
+      asyncHandler(async (req, res) => {
+        const user = req.user as User | undefined;
+        if (!user) {
+          throw new APIError({status: 401, title: "Authentication required"});
+        }
+
+        const responses = await ConsentResponse.find({userId: user.id}).sort({agreedAt: -1});
+
+        const formIds = responses.map((r) => r.consentFormId);
+        const forms = await ConsentForm.find({_id: {$in: formIds}});
+        const formMap = new Map(forms.map((f) => [f._id.toString(), f]));
+
+        const data = responses.map((response) => {
+          const form = formMap.get(response.consentFormId.toString());
+          return {
+            _id: response._id,
+            agreed: response.agreed,
+            agreedAt: response.agreedAt,
+            checkboxValues: response.checkboxValues,
+            contentSnapshot: response.contentSnapshot,
+            form: form
+              ? {
+                  captureSignature: form.captureSignature,
+                  checkboxes: form.checkboxes,
+                  slug: form.slug,
+                  title: form.title,
+                  type: form.type,
+                  version: form.version,
+                }
+              : null,
+            formVersionSnapshot: response.formVersionSnapshot,
+            ipAddress: response.ipAddress,
+            locale: response.locale,
+            signature: response.signature,
+            signedAt: response.signedAt,
+            userAgent: response.userAgent,
+          };
+        });
+
+        return res.json({data});
+      })
+    );
+
+    // GET /consents/audit/:userId - admin audit trail for a specific user
+    if (auditTrail) {
+      router.get(
+        "/audit/:userId",
+        authenticateMiddleware(),
+        asyncHandler(async (req, res) => {
+          const user = req.user as User | undefined;
+          if (!user?.admin) {
+            throw new APIError({status: 403, title: "Admin access required"});
+          }
+
+          const responses = await ConsentResponse.find({userId: req.params.userId}).sort({
+            agreedAt: -1,
+          });
+
+          const formIds = responses.map((r) => r.consentFormId);
+          const forms = await ConsentForm.find({_id: {$in: formIds}});
+          const formMap = new Map(forms.map((f) => [f._id.toString(), f]));
+
+          const auditEntries = responses.map((response) => {
+            const form = formMap.get(response.consentFormId.toString());
+            return {
+              agreed: response.agreed,
+              agreedAt: response.agreedAt,
+              contentSnapshot: response.contentSnapshot,
+              form: form
+                ? {
+                    slug: form.slug,
+                    title: form.title,
+                    type: form.type,
+                    version: form.version,
+                  }
+                : null,
+              formVersionSnapshot: response.formVersionSnapshot,
+              ipAddress: response.ipAddress,
+              locale: response.locale,
+              responseId: response._id,
+              signedAt: response.signedAt,
+              userAgent: response.userAgent,
+            };
+          });
+
+          return res.json({data: auditEntries});
+        })
+      );
+    }
+
+    app.use("/consents", router);
+
+    logger.info("ConsentApp registered", {auditTrail: Boolean(auditTrail)});
+  }
+}

package/src/index.ts

@@ -5,11 +5,14 @@ export * from "./betterAuthApp";
 export * from "./betterAuthSetup";
 export * from "./configurationApp";
 export * from "./configurationPlugin";
+export * from "./consentApp";
 export * from "./errors";
 export * from "./expressServer";
 export * from "./githubAuth";
 export * from "./logger";
 export * from "./middleware";
+export * from "./models/consentForm";
+export * from "./models/consentResponse";
 export * from "./models/versionConfig";
 export * from "./notifiers";
 export * from "./openApiBuilder";
@@ -21,8 +24,11 @@ export * from "./plugins";
 export * from "./populate";
 export * from "./scriptRunner";
 export * from "./secretProviders";
+export * from "./syncConsents";
 export * from "./terrenoApp";
 export * from "./terrenoPlugin";
 export * from "./transformers";
+export * from "./types/consentForm";
+export * from "./types/consentResponse";
 export * from "./utils";
 export * from "./versionCheckPlugin";

package/src/models/consentForm.ts

@@ -0,0 +1,123 @@
+import mongoose from "mongoose";
+import {createdUpdatedPlugin, findExactlyOne, findOneOrNone, isDeletedPlugin} from "../plugins";
+import type {ConsentFormDocument, ConsentFormModel} from "../types/consentForm";
+
+const consentFormSchema = new mongoose.Schema<ConsentFormDocument, ConsentFormModel>(
+  {
+    active: {
+      default: false,
+      description: "Whether this consent form is currently active and available to users",
+      type: Boolean,
+    },
+    agreeButtonText: {
+      default: "I Agree",
+      description: "Label text for the agreement button",
+      type: String,
+    },
+    allowDecline: {
+      default: false,
+      description: "Whether users are allowed to decline the consent form",
+      type: Boolean,
+    },
+    captureSignature: {
+      default: false,
+      description: "Whether to require a drawn or typed signature when the user agrees",
+      type: Boolean,
+    },
+    checkboxes: {
+      default: [],
+      description: "List of checkboxes the user must interact with before agreeing",
+      type: [
+        {
+          confirmationPrompt: {
+            description: "Optional prompt shown when the user checks this checkbox",
+            type: String,
+          },
+          label: {
+            description: "Display label for the checkbox",
+            required: true,
+            type: String,
+          },
+          required: {
+            default: false,
+            description: "Whether this checkbox must be checked before the user can agree",
+            type: Boolean,
+          },
+        },
+      ],
+    },
+    content: {
+      description:
+        'Locale-keyed map of Markdown content for this form (e.g. {"en": "# Terms\\n..."})',
+      of: String,
+      required: true,
+      type: Map,
+    },
+    declineButtonText: {
+      default: "Decline",
+      description: "Label text for the decline button (only shown when allowDecline is true)",
+      type: String,
+    },
+    defaultLocale: {
+      default: "en",
+      description: "Default locale to use when the requested locale is not available",
+      type: String,
+    },
+    order: {
+      default: 0,
+      description: "Display order relative to other consent forms (lower numbers appear first)",
+      required: true,
+      type: Number,
+    },
+    required: {
+      default: true,
+      description: "Whether users must complete this form before accessing the application",
+      type: Boolean,
+    },
+    requireScrollToBottom: {
+      default: false,
+      description: "Whether users must scroll to the bottom of the form content before agreeing",
+      type: Boolean,
+    },
+    slug: {
+      description:
+        "URL-safe identifier for this form, combined with version to uniquely identify a form",
+      index: true,
+      required: true,
+      trim: true,
+      type: String,
+    },
+    title: {
+      description: "Human-readable title of the consent form",
+      required: true,
+      trim: true,
+      type: String,
+    },
+    type: {
+      description: "Category of consent form",
+      enum: ["agreement", "privacy", "hipaa", "research", "terms", "custom"],
+      required: true,
+      type: String,
+    },
+    version: {
+      default: 1,
+      description:
+        "Version number of this form. Incrementing the version requires users to re-consent",
+      required: true,
+      type: Number,
+    },
+  },
+  {strict: "throw", toJSON: {virtuals: true}, toObject: {virtuals: true}}
+);
+
+consentFormSchema.index({slug: 1, version: 1}, {unique: true});
+
+consentFormSchema.plugin(createdUpdatedPlugin);
+consentFormSchema.plugin(isDeletedPlugin);
+consentFormSchema.plugin(findOneOrNone);
+consentFormSchema.plugin(findExactlyOne);
+
+export const ConsentForm = mongoose.model<ConsentFormDocument, ConsentFormModel>(
+  "ConsentForm",
+  consentFormSchema
+);

package/src/models/consentResponse.ts

@@ -0,0 +1,78 @@
+import mongoose from "mongoose";
+import {createdUpdatedPlugin, findExactlyOne, findOneOrNone, isDeletedPlugin} from "../plugins";
+import type {ConsentResponseDocument, ConsentResponseModel} from "../types/consentResponse";
+
+const consentResponseSchema = new mongoose.Schema<ConsentResponseDocument, ConsentResponseModel>(
+  {
+    agreed: {
+      description: "Whether the user agreed (true) or declined (false) the consent form",
+      required: true,
+      type: Boolean,
+    },
+    agreedAt: {
+      description: "Timestamp when the user submitted their agreement or declination",
+      required: true,
+      type: Date,
+    },
+    checkboxValues: {
+      description: "Map of checkbox index to boolean indicating whether each checkbox was checked",
+      of: Boolean,
+      type: Map,
+    },
+    consentFormId: {
+      description: "Reference to the ConsentForm that was responded to",
+      ref: "ConsentForm",
+      required: true,
+      type: mongoose.Schema.Types.ObjectId,
+    },
+    contentSnapshot: {
+      description: "Snapshot of the form content in the user's locale at the time of response",
+      type: String,
+    },
+    formVersionSnapshot: {
+      description: "Version number of the form at the time the user responded",
+      type: Number,
+    },
+    ipAddress: {
+      description: "IP address of the user at the time of response, captured for audit purposes",
+      type: String,
+    },
+    locale: {
+      description: "Locale code of the content version the user viewed when responding",
+      required: true,
+      type: String,
+    },
+    signature: {
+      description: "Base64-encoded signature image or typed signature text, if captured",
+      type: String,
+    },
+    signedAt: {
+      description: "Timestamp when the user provided their signature",
+      type: Date,
+    },
+    userAgent: {
+      description: "User-agent string of the browser or app used to submit the response",
+      type: String,
+    },
+    userId: {
+      description: "Reference to the User who submitted this response",
+      index: true,
+      ref: "User",
+      required: true,
+      type: mongoose.Schema.Types.ObjectId,
+    },
+  },
+  {strict: "throw", toJSON: {virtuals: true}, toObject: {virtuals: true}}
+);
+
+consentResponseSchema.index({consentFormId: 1, userId: 1});
+
+consentResponseSchema.plugin(createdUpdatedPlugin);
+consentResponseSchema.plugin(isDeletedPlugin);
+consentResponseSchema.plugin(findOneOrNone);
+consentResponseSchema.plugin(findExactlyOne);
+
+export const ConsentResponse = mongoose.model<ConsentResponseDocument, ConsentResponseModel>(
+  "ConsentResponse",
+  consentResponseSchema
+);

package/src/models/versionConfig.ts

@@ -1,6 +1,6 @@
 import mongoose, {type Document} from "mongoose";
 
-import {type APIErrorConstructor} from "../errors";
+import type {APIErrorConstructor} from "../errors";
 import {createdUpdatedPlugin, findOneOrNone} from "../plugins";
 
 export interface VersionConfigDocument extends mongoose.Document {