feat: expand opt-in capability coverage with versioned consent

backend/src/middleware/productUsage.js

@@ -3,6 +3,7 @@
 // identifiers, paths, timing, or counts are retained or sent.
 const service = require('../services/productUsageService');
 const logger = require('../utils/logger');
+const { capabilityKeys } = require('../usage/capabilityRules');
 // Mirrors emailWebhookTransport: the webhook is in play only when both are
 // set, which is when adminEmail routes the test send through it.
 const webhookTransportConfigured = () =>
@@ -59,13 +60,28 @@ function productUsage(req, res, next) {
       /^\/(?:photos|events)\/[^/]+\/upload(?:\/|$)/.test(pathname)
     )
       features.push('s3_storage');
-    if (features.length)
+    const expanded = [...new Set([
+      ...capabilityKeys(req.method, pathname),
+      ...(res.locals.productUsageFeatures || [])
+    ])];
+    if (features.length || expanded.length)
       service
-        .markUsed(features, {
+        .markUsed(expanded, {
+          legacyFeatures: features,
           destinationBackup: DESTINATION_BACKUP.test(pathname)
         })
         .catch(() => logger.warn('Product usage marker could not be recorded'));
   });
   next();
 }
-module.exports = { productUsage, RULES, DESTINATION_BACKUP };
+// Integration calls can record one general capability, but never trigger the
+// daily sender. Public/customer/gallery routes do not mount this middleware.
+function productUsageApi(req, res, next) {
+  res.once('finish', () => {
+    if (!req.admin?.id || !req.apiToken || res.statusCode < 200 || res.statusCode >= 300) return;
+    service.markUsed(['api_integration'], { legacyFeatures: [] })
+      .catch(() => logger.warn('Product usage API marker could not be recorded'));
+  });
+  next();
+}
+module.exports = { productUsage, productUsageApi, RULES, DESTINATION_BACKUP };

backend/src/routes/adminBackup.js

@@ -795,6 +795,8 @@ router.post('/s3/test-upload', adminAuth, requirePermission('backup.create'), as
     
     // Test deletion
     await s3Adapter.delete(testKey);
+
+    if (contentMatch) require('../usage/capabilityEvidence').capabilityEvidence(res, 's3_storage', 's3_backups');
     
     res.json({
       success: true,

backend/src/routes/adminEmail.js

@@ -1,4 +1,5 @@
 const express = require('express');
+const { capabilityEvidence } = require('../usage/capabilityEvidence');
 const nodemailer = require('nodemailer');
 const { body, query, validationResult } = require('express-validator');
 const { db, logActivity } = require('../database/db');
@@ -221,6 +222,7 @@ router.post('/incoming-config/test', adminAuth, requirePermission('email.view'),
     if (result && result.ok === false) {
       return res.status(400).json({ error: 'Incoming mail is not configured yet — enter host, username and password first.' });
     }
+    if (result?.ok) capabilityEvidence(res, 'incoming_mail');
     res.json(result);
   } catch (error) {
     logger.error('IMAP connection test error:', error);
@@ -234,7 +236,10 @@ router.post('/incoming-config/roundtrip', adminAuth, requirePermission('email.se
   try {
     const emailIntakeService = require('../services/emailIntakeService');
     const result = await emailIntakeService.roundTripTest();
-    if (result.ok) return res.json(result);
+    if (result.ok) {
+      capabilityEvidence(res, 'incoming_mail', 'smtp');
+      return res.json(result);
+    }
     const map = {
       smtp_unconfigured: 'Configure and save the outgoing SMTP settings first.',
       imap_unconfigured: 'Configure and save the incoming IMAP settings first.',
@@ -257,6 +262,7 @@ router.post('/incoming-config/poll', adminAuth, requirePermission('email.view'),
   try {
     const emailIntakeService = require('../services/emailIntakeService');
     const result = await emailIntakeService.pollOnce();
+    if (result && !result.skipped) capabilityEvidence(res, 'incoming_mail');
     res.json(result); // { processed } or { skipped: 'disabled'|'unconfigured'|'busy' }
   } catch (error) {
     logger.error('Manual poll error:', error);
@@ -456,6 +462,7 @@ router.post('/accounts/test', adminAuth, messagingGate, requirePermission('email
       host: b.imap_host, port: b.imap_port, secure: b.imap_secure,
       user: b.imap_user, pass, folder: b.imap_folder || 'INBOX',
     });
+    if (result?.ok) capabilityEvidence(res, 'incoming_mail');
     res.json(result);
   } catch (error) {
     res.status(422).json({ ok: false, error: `Mailbox test failed (${error.message}).` });
@@ -511,6 +518,7 @@ router.post('/test', adminAuth, requirePermission('email.send'), async (req, res
           details: webhookError.message,
         });
       }
+      capabilityEvidence(res, 'email_webhook');
       return res.json({ message: 'Test email sent successfully' });
     }
 
@@ -587,6 +595,7 @@ router.post('/test', adminAuth, requirePermission('email.send'), async (req, res
         + await buildSignatureTextFor('en')
     });
 
+    capabilityEvidence(res, 'smtp');
     res.json({ message: 'Test email sent successfully' });
   } catch (error) {
     logger.error('Test email error:', error);
@@ -847,6 +856,8 @@ router.post('/send', adminAuth, messagingGate, requirePermission('email.send'),
 
     const emailProcessor = require('../services/emailProcessor');
     const result = await emailProcessor.sendRawEmail({ to, cc, subject, html, accountKey });
+    if (result.transport === 'webhook') capabilityEvidence(res, 'email_webhook');
+    if (result.transport === 'smtp') capabilityEvidence(res, 'smtp');
 
     await db('email_queue').insert({
       recipient_email: to,
@@ -1259,4 +1270,4 @@ router.post('/templates/:key/preview', adminAuth, requirePermission('email.view'
   }
 });
 
-module.exports = router;
+module.exports = router;

backend/src/routes/adminPhotos.js

@@ -7,6 +7,7 @@ const { adminAuth } = require('../middleware/auth');
 const { requirePermission } = require('../middleware/permissions');
 const { ensureThumbnail } = require('../services/imageProcessor');
 const { isVideoMimeType } = require('../services/videoProcessor');
+const { acceptedUpload } = require('../usage/capabilityEvidence');
 const { generatePhotoFilename, buildContentDisposition } = require('../utils/filenameSanitizer');
 const {
   getUseOriginalFilenames,
@@ -357,6 +358,11 @@ router.post('/:eventId/upload', adminAuth, requirePermission('photos.upload'), r
             event,
           });
           if (result.success) {
+            acceptedUpload(res, {
+              video: isVideoMimeType(file.mimetype),
+              raw: path.extname(file.originalname).toLowerCase() === '.dng',
+              s3: process.env.STORAGE_BACKEND === 's3'
+            });
             replacedPhotos.push({
               id: result.photo.id,
               filename: result.photo.filename,
@@ -471,6 +477,8 @@ router.post('/:eventId/upload', adminAuth, requirePermission('photos.upload'), r
           .returning('id');
         const photoId = inserted[0]?.id || inserted[0];
 
+        acceptedUpload(res, { video: isVideo, raw: extension.toLowerCase() === '.dng', s3: process.env.STORAGE_BACKEND === 's3' });
+
         uploadedPhotos.push({
           id: photoId,
           filename: newFilename,
@@ -1720,6 +1728,11 @@ router.post('/:eventId/chunked-upload/:uploadId/complete', adminAuth, requirePer
       'admin',
       category_id || null
     );
+    if (uploadedPhotos.length) acceptedUpload(res, {
+      video: isVideoMimeType(fileObj.mimetype),
+      raw: path.extname(fileObj.originalname).toLowerCase() === '.dng',
+      s3: process.env.STORAGE_BACKEND === 's3'
+    });
 
     // Clean up temp directory
     try {

backend/src/routes/adminUsage.js

@@ -54,6 +54,14 @@ router.post(
     res.json(await service.enable(req.body.consent_version))
   )
 );
+router.post(
+  '/consent',
+  wrap(async (req, res) => {
+    if (!req.body || Object.keys(req.body).length !== 1 || req.body.consent_version !== 'usage-consent.v2')
+      throw new ValidationError('Explicit usage v2 consent is required');
+    res.json(await service.command('consent', { consent_version: 'usage-consent.v2' }));
+  })
+);
 router.post(
   '/disable',
   wrap(async (_req, res) => res.json(await service.disable()))

backend/src/routes/adminWhatsapp.js

@@ -176,6 +176,7 @@ router.post('/test', adminAuth, requirePermission('whatsapp.manage'), async (req
     };
     const testComponents = buildComponents(testData, language, params);
     const result = await sendWhatsAppMessage(phone, config, language, testComponents);
+    require('../usage/capabilityEvidence').capabilityEvidence(res, 'whatsapp');
     res.json({ success: true, messageId: result.messageId });
   } catch (error) {
     logger.error('WhatsApp test send error:', error);

backend/src/services/emailProcessor.js

@@ -1091,7 +1091,7 @@ async function sendRawEmail({ to, cc, subject, html, text, attachments, accountK
     ? await emailWebhookTransport.send(mail)
     : await tx.sendMail(mail);
   logger.info(`Manual email sent: ${info.messageId}`);
-  return { messageId: info.messageId, html };
+  return { messageId: info.messageId, html, transport: viaWebhook ? 'webhook' : 'smtp' };
 }
 
 /**

backend/src/usage/UsageService.js

@@ -17,6 +17,12 @@ const {
   digest,
   canonical,
   FEATURE_KEYS,
+  LEGACY_FEATURE_KEYS,
+  CATALOG,
+  CURRENT_SCHEMA_VERSION,
+  CURRENT_CONSENT_VERSION,
+  featureKeysFor,
+  observesUse,
   LAYOUTS
 } = require('./protocol.cjs');
 
@@ -100,6 +106,10 @@ const parse = (value) => {
 };
 
 class UsageService {
+  schemaVersion(state) {
+    return state?.consent_version === CURRENT_CONSENT_VERSION
+      ? CURRENT_SCHEMA_VERSION : 'usage.v1';
+  }
   constructor(db, options = {}) {
     this.db = db;
     this.fetch = options.fetch || global.fetch;
@@ -232,7 +242,10 @@ class UsageService {
       installation_id: state.installation_id,
       collector_url: collectorUrl,
       collector_error: collectorError,
-      schema_version: 'usage.v1',
+      schema_version: this.schemaVersion(state),
+      available_schema_version: CURRENT_SCHEMA_VERSION,
+      consent_version: state.consent_version || 'usage-consent.v1',
+      consent_update_available: state.status === 'active' && this.schemaVersion(state) !== CURRENT_SCHEMA_VERSION,
       last_report_date: state.last_report_date,
       last_error: state.last_error,
       pending_action: state.pending_packet
@@ -272,7 +285,7 @@ class UsageService {
     return this.status();
   }
   async enable(consent) {
-    if (consent !== 'usage-consent.v1')
+    if (!['usage-consent.v1', CURRENT_CONSENT_VERSION].includes(consent))
       throw new ValidationError('Explicit usage consent is required');
     // Read BEFORE the lease, deliberately. locked() claims the lease and then
     // reads the row in a second statement; a /disable completing between
@@ -293,7 +306,7 @@ class UsageService {
       const identity = generateIdentity();
       const pending = makePacket(identity, 'register', 0, {
         consent_version: consent
-      });
+      }, this.schemaVersion({ consent_version: consent }));
       // Identity generation and the binding file are the slow part, and the
       // row still reads `disabled` throughout — which is why /disable could
       // not see an activation in flight and its conditional update matched
@@ -308,6 +321,7 @@ class UsageService {
         .where({ id: 1, status: 'disabled', cancel_seq: cancelSeq })
         .update({
           status: 'activation_pending',
+          consent_version: consent,
           notice_dismissed: formatBoolean(true),
           installation_id: identity.installation_id,
           public_key: identity.public_key,
@@ -513,7 +527,18 @@ class UsageService {
         } else {
           ack.whereNot({ status: 'deletion_pending' });
         }
-        await ack.update(update);
+        if (packet.action === 'consent') {
+          // Upgrade and reset the observation period atomically. A late receipt
+          // must never re-enable collection after an intervening opt-out.
+          await this.db.transaction(async (tx) => {
+            const upgraded = await tx('product_usage_state')
+              .where({ id: 1, status: 'active', installation_id: packet.installation_id })
+              .update({ ...update, consent_version: CURRENT_CONSENT_VERSION });
+            if (upgraded) await tx('product_usage_markers').delete();
+          });
+        } else {
+          await ack.update(update);
+        }
         await this.db('product_usage_state')
           .where({ id: 1, status: 'deletion_pending' })
           .update({ sequence: packet.sequence, pending_packet: null });
@@ -563,7 +588,7 @@ class UsageService {
     await this.locked(async (state) => {
       if (state.status === 'disabled') return;
       if (state.status === 'deletion_pending') {
-        const packet = makePacket(state, 'delete', Number(state.sequence), {});
+        const packet = makePacket(state, 'delete', Number(state.sequence), {}, this.schemaVersion(state));
         state.pending_packet = JSON.stringify(packet);
         await this.db('product_usage_state')
           .where({ id: 1 })
@@ -582,12 +607,13 @@ class UsageService {
         new Date(this.now()).toISOString().slice(0, 10)
       )
         return;
-      const payload = await this.snapshot();
+      const payload = await this.snapshot(this.schemaVersion(state));
       const packet = makePacket(
         state,
         'report',
         Number(state.sequence) + 1,
-        payload
+        payload,
+        this.schemaVersion(state)
       );
       state.pending_packet = JSON.stringify(packet);
       // Only while still active. /disable clears pending_packet and moves the
@@ -604,8 +630,8 @@ class UsageService {
     return this.status();
   }
 
-  async markUsed(features, { destinationBackup = false } = {}) {
-    const allowed = [...new Set(features)].filter((f) =>
+  async markUsed(features, { destinationBackup = false, legacyFeatures } = {}) {
+    let allowed = [...new Set([...features, ...(legacyFeatures || [])])].filter((f) =>
       FEATURE_KEYS.includes(f)
     );
     if (!allowed.length) return;
@@ -615,6 +641,10 @@ class UsageService {
       if (this.db.client.config.client === 'pg') query.forUpdate();
       const state = await query.first();
       if (!state || state.status !== 'active') return;
+      const version = this.schemaVersion(state);
+      if (legacyFeatures) allowed = version === 'usage.v1' ? legacyFeatures : features;
+      allowed = allowed.filter((feature) => featureKeysFor(version).includes(feature) && observesUse(feature, version));
+      if (!allowed.length) return;
       // Only when the operation actually writes to the configured backup
       // destination. Deriving this from "a backup ran while S3 is configured"
       // marked S3 as USED for a local database backup or a .picpeak export,
@@ -624,17 +654,20 @@ class UsageService {
         const destination = await tx('app_settings')
           .where({ setting_key: 'backup_destination_type' })
           .first();
-        if (destination && parse(destination.setting_value) === 's3')
+        if (destination && parse(destination.setting_value) === 's3') {
           allowed.push('s3_storage');
+          if (version === CURRENT_SCHEMA_VERSION) allowed.push('s3_backups');
+        }
       }
       await tx('product_usage_markers')
-        .insert(allowed.map((feature) => ({ feature })))
+        .insert([...new Set(allowed)].map((feature) => ({ feature })))
         .onConflict('feature')
         .ignore();
     });
   }
 
-  async snapshot() {
+  async snapshot(version) {
+    version = version || this.schemaVersion(await this.state());
     const rows = await this.db('app_settings')
       .whereIn('setting_key', SETTING_KEYS)
       .select('setting_key', 'setting_value');
@@ -642,7 +675,9 @@ class UsageService {
       rows.map((r) => [r.setting_key, parse(r.setting_value)])
     );
     const flagRows = await this.db('feature_flags')
-      .whereIn('key', Object.values(FLAG_MAP))
+      .whereIn('key', version === CURRENT_SCHEMA_VERSION
+        ? [...new Set([...Object.values(FLAG_MAP), 'incomingMail', ...Object.values(CATALOG.features).map((f) => f.flag).filter(Boolean)])]
+        : Object.values(FLAG_MAP))
       .select('key', 'value');
     const flags = Object.fromEntries(
       flagRows.map((r) => [r.key, truth(r.value)])
@@ -651,7 +686,7 @@ class UsageService {
       await this.db('product_usage_markers').pluck('feature')
     );
     const features = Object.fromEntries(
-      FEATURE_KEYS.map((key) => [
+      LEGACY_FEATURE_KEYS.map((key) => [
         key,
         { configured: Boolean(flags[FLAG_MAP[key]]), used: used.has(key) }
       ])
@@ -746,11 +781,14 @@ class UsageService {
       features.custom_css.used = true;
     }
     const now = new Date(this.now()).toISOString();
+    const expanded = version === CURRENT_SCHEMA_VERSION
+      ? await require('./expandedSnapshot').expandSnapshot(this.db, { features, flags, used, now: this.now() })
+      : features;
     return {
       picpeak_version: this.version,
       report_date: now.slice(0, 10),
       generated_at: now,
-      features,
+      features: expanded,
       gallery_layouts: [...layouts].sort()
     };
   }
@@ -768,13 +806,16 @@ class UsageService {
         throw new ConflictError('Usage participation is not active');
       if (state.pending_packet)
         throw new ConflictError('Retry the pending usage operation first');
-      if (!['feedback', 'vote', 'session'].includes(action))
+      if (!['feedback', 'vote', 'session', 'consent'].includes(action))
         throw new ValidationError('Invalid usage action');
+      if (action === 'consent' && state.consent_version === CURRENT_CONSENT_VERSION)
+        throw new ConflictError('Usage consent is already current');
       const packet = makePacket(
         state,
         action,
         Number(state.sequence) + 1,
-        payload
+        payload,
+        action === 'consent' ? CURRENT_SCHEMA_VERSION : this.schemaVersion(state)
       );
       // Validate the complete packet before storing an un-sendable operation.
       verifyEnvelope(

backend/src/usage/capabilityEvidence.js

@@ -0,0 +1,19 @@
+'use strict';
+const { FEATURE_KEYS, observesUse } = require('./schema.cjs');
+
+// Trusted route handlers call this AFTER their business operation succeeds.
+// Only fixed, allowlisted keys reach finish middleware. It still requires an
+// authenticated admin, a 2xx response and active consent before persisting.
+function capabilityEvidence(res, ...keys) {
+  res.locals.productUsageFeatures = [...new Set([
+    ...(res.locals.productUsageFeatures || []),
+    ...keys.filter((key) => FEATURE_KEYS.includes(key) && observesUse(key))
+  ])];
+}
+function acceptedUpload(res, { video = false, raw = false, s3 = false } = {}) {
+  capabilityEvidence(res, 'photo_management',
+    ...(video ? ['video_uploads'] : []),
+    ...(raw ? ['camera_raw_uploads'] : []),
+    ...(s3 ? ['s3_storage', 's3_photo_storage'] : []));
+}
+module.exports = { capabilityEvidence, acceptedUpload };

backend/src/usage/capabilityRules.js

@@ -0,0 +1,79 @@
+'use strict';
+
+// A fixed capability allowlist, not a route/click log. Only the resulting keys
+// survive the request. No request body, query, path, IDs or response values are
+// passed to the usage service. Read-only status/health/options polls are absent.
+const WRITE = ['POST', 'PUT', 'PATCH', 'DELETE'];
+const RULES_V2 = [
+  [WRITE, /^\/customers(?:\/|$)/, ['crm']],
+  [WRITE, /^\/quotes(?:\/|$)/, ['crm', 'crm_quotes']],
+  [WRITE, /^\/invoices(?:\/|$)/, ['crm', 'crm_invoices']],
+  [WRITE, /^\/contracts(?:\/|$)/, ['crm', 'crm_contracts']],
+  [WRITE, /^\/projects(?:\/|$)/, ['crm', 'crm_projects']],
+  [['GET'], /^\/calendar\/items\/?$/, ['crm', 'crm_calendar']],
+  [WRITE, /^\/customers\/[^/]+\/(?:hour-entries|bill-combined|trigger-monthly-bill)(?:\/|$)/, ['crm', 'crm_hours']],
+  [['POST'], /^\/customers\/(?:invite|[^/]+\/send-invite)\/?$/, ['customer_portal']],
+  [WRITE, /^\/deals\/[^/]+\/installment-plan\/?$/, ['crm', 'crm_installments']],
+  [WRITE, /^\/(?:quotes\/presets|contracts\/blocks)(?:\/|$)/, ['document_templates']],
+  [WRITE, /^\/expenses\/inbound(?:\/|$)/, ['accounting', 'accounting_incoming_invoices']],
+  [WRITE, /^\/expenses(?:\/(?!inbound(?:\/|$))|$)/, ['accounting', 'accounting_expenses']],
+  [WRITE, /^\/ledger(?:\/|$)/, ['accounting', 'accounting_ledger']],
+  [['GET'], /^\/ledger\/export\/?$/, ['accounting', 'accounting_ledger']],
+  [['GET'], /^\/tax-report(?:\/(?:pdf|csv))?\/?$/, ['accounting', 'accounting_tax_report']],
+  [WRITE, /^\/workflows(?:\/|$)/, ['workflows']],
+  [WRITE, /^\/newsletters(?:\/[^/]+)?\/?$/, ['newsletters']],
+  [['POST'], /^\/newsletters\/[^/]+\/(?:test|queue|cancel)\/?$/, ['newsletters']],
+  [WRITE, /^\/events\/[^/]+\/(?:faces|people)(?:\/|$)/, ['face_recognition']],
+  [WRITE, /^\/events\/faces\/auto-categories\/?$/, ['face_recognition']],
+  [['POST'], /^\/external-media\/events\/[^/]+\/import-external\/?$/, ['share_mounts']],
+  [['POST'], /^\/events\/?$/, ['galleries']],
+  [['PUT', 'DELETE'], /^\/events\/[^/]+\/?$/, ['galleries']],
+  [['POST'], /^\/events\/[^/]+\/(?:publish|duplicate|toggle-status|extend|rename|reveal|reset-password)\/?$/, ['galleries']],
+  [['POST'], /^\/events\/(?:bulk-archive|bulk-delete)\/?$/, ['galleries', 'archive_management']],
+  [['POST'], /^\/events\/[^/]+\/archive\/?$/, ['archive_management']],
+  [['POST'], /^\/archives\/[^/]+\/restore\/?$/, ['archive_management']],
+  [['DELETE'], /^\/archives\/[^/]+\/?$/, ['archive_management']],
+  [['GET'], /^\/archives\/[^/]+\/download\/?$/, ['archive_management', 'photo_exports']],
+  [WRITE, /^\/(?:events|photos)\/[^/]+\/photos(?:\/|$)/, ['photo_management']],
+  [['POST'], /^\/photos\/photos\/[^/]+\/retry\/?$/, ['photo_processing']],
+  [['POST'], /^\/photos\/repair-(?:dimensions|capture-dates|orientation)\/?$/, ['photo_processing']],
+  [['POST', 'PUT'], /^\/thumbnails\/(?:settings|regenerate|regenerate-previews)\/?$/, ['photo_processing']],
+  [['POST'], /^\/photo-export\/[^/]+\/export\/?$/, ['photo_exports']],
+  [['GET'], /^\/(?:events|photos)\/[^/]+\/photos\/[^/]+\/download\/?$/, ['photo_exports']],
+  [['GET'], /^\/events\/[^/]+\/(?:qr|qr-print)\/?$/, ['gallery_sharing']],
+  [['POST'], /^\/events\/[^/]+\/(?:send-gallery-email|resend-email)\/?$/, ['gallery_sharing']],
+  [['POST'], /^\/events\/[^/]+\/short-urls\/?$/, ['gallery_sharing', 'short_links']],
+  [['DELETE'], /^\/short-urls\/[^/]+\/?$/, ['short_links']],
+  [WRITE, /^\/categories(?:\/|$)/, ['gallery_categories']],
+  [WRITE, /^\/event-types(?:\/|$)/, ['event_types']],
+  [WRITE, /^\/events\/[^/]+\/slideshow(?:\/|$)/, ['slideshow']],
+  [['PUT'], /^\/settings\/slideshow\/?$/, ['slideshow']],
+  [WRITE, /^\/transfers(?:\/|$)/, ['transfers']],
+  [['GET'], /^\/transfers\/[^/]+\/(?:download|extra-files\/[^/]+\/download|uploads\/[^/]+\/download)\/?$/, ['transfers']],
+  [['POST'], /^\/email\/send\/?$/, ['messaging']],
+  [WRITE, /^\/email\/(?:accounts|item\/[^/]+\/[^/]+(?:\/state)?)\/?$/, ['messaging']],
+  [WRITE, /^\/email\/templates(?:\/|$)/, ['email_templates']],
+  [['PUT'], /^\/settings\/theme\/?$/, ['branding']],
+  [WRITE, /^\/settings\/(?:branding|logo|favicon)(?:\/|$)/, ['branding']],
+  [WRITE, /^\/events\/[^/]+\/logo\/?$/, ['branding']],
+  [['PUT'], /^\/settings\/seo\/?$/, ['seo_customization']],
+  [WRITE, /^\/cms\/pages(?:\/|$)/, ['cms']],
+  [['POST'], /^\/webhooks\/[^/]+\/(?:test|deliveries\/[^/]+\/replay)\/?$/, ['webhooks']],
+  [WRITE, /^\/users(?:\/(?![^/]+\/reset-password(?:\/|$))|$)/, ['admin_management']],
+  [WRITE, /^\/roles(?:\/|$)/, ['admin_management']],
+  [['POST'], /^\/restore\/start\/?$/, ['restore']],
+  [['GET'], /^\/backup\/picpeak\/export\/?$/, ['backup', 'portable_backup']],
+  [['POST'], /^\/backup\/picpeak\/import\/?$/, ['restore', 'portable_backup']],
+  [['POST'], /^\/backup\/run\/?$/, ['backup']],
+  [['POST'], /^\/database-backup\/backup\/?$/, ['backup', 'database_backup']],
+  [['GET'], /^\/dashboard\/analytics\/?$/, ['analytics_dashboard']],
+  [WRITE, /^\/feedback\/(?:feedback|word-filters)(?:\/|$)/, ['feedback_moderation']],
+  [WRITE, /^\/events\/[^/]+\/guests(?:\/|$)/, ['guest_management']],
+  [['GET'], /^\/events\/[^/]+\/guests\/(?:export-all|[^/]+\/export)\/?$/, ['guest_management']],
+];
+
+function capabilityKeys(method, pathname) {
+  return [...new Set(RULES_V2.filter(([methods, pattern]) => methods.includes(method) && pattern.test(pathname))
+    .flatMap(([, , keys]) => keys))];
+}
+module.exports = { RULES_V2, capabilityKeys };

backend/src/usage/expandedSnapshot.js

@@ -0,0 +1,109 @@
+'use strict';
+const { CATALOG, emptyFeatures } = require('./schema.cjs');
+const { formatBoolean } = require('../utils/dbCompat');
+
+const truth = (value) => value === true || value === 1 || value === '1';
+const parse = (value) => {
+  for (let i = 0; i < 3 && typeof value === 'string'; i++) {
+    try { const decoded = JSON.parse(value); if (decoded === value) break; value = decoded; }
+    catch { break; }
+  }
+  return value;
+};
+
+// Technical configuration only. Never read photos, feedback contents, guest /
+// customer / admin profiles, messages, audit logs, delivery logs or counts.
+// Presence queries return a literal 1, not even a row's identifying primary key.
+async function expandSnapshot(db, { features, flags, used, now }) {
+  const result = { ...emptyFeatures('usage.v2'), ...features };
+  const effective = { analytics: true, userManagement: true, ...flags };
+  if (!effective.quotes) effective.bills = false;
+  if (effective.bills) effective.accounting = true;
+  if (!effective.accounting) {
+    effective.incomingInvoices = false;
+    effective.expenses = false;
+    effective.taxReport = false;
+  }
+  effective.clients = ['customerPortal', 'quotes', 'bills', 'contracts', 'projects', 'calendar', 'hoursLogging', 'newsletters']
+    .some((flag) => effective[flag]);
+  if (['1', 'true', 'yes'].includes(String(process.env.PICPEAK_SINGLE_CONTAINER || '').toLowerCase())) effective.faces = false;
+  for (const [key, definition] of Object.entries(CATALOG.features)) {
+    if (definition.configuration === 'builtin') result[key].configured = true;
+    if (definition.flag) result[key].configured = Boolean(effective[definition.flag]);
+    if (definition.used && key !== 'custom_css') result[key].used = used.has(key);
+    if (!definition.used) delete result[key].used;
+  }
+  // Applied custom CSS is detected locally without any visitor observation.
+  result.custom_css.used = features.custom_css.used;
+
+  const has = async (table, columns) => {
+    if (!(await db.schema.hasTable(table))) return false;
+    for (const column of columns) if (!(await db.schema.hasColumn(table, column))) return false;
+    return true;
+  };
+  const exists = async (table, columns, filter) => {
+    if (!(await has(table, columns))) return false;
+    const query = db(table);
+    filter(query);
+    return Boolean(await query.select(db.raw('1 as present')).first());
+  };
+  const enabled = (table, column, filter = () => {}) => exists(table, [column], (query) => {
+    query.where(column, formatBoolean(true)); filter(query);
+  });
+  const settingKeys = [
+    'general_allowed_file_types', 'general_public_site_enabled',
+    'download_resolution_picker_enabled', 'branding_watermark_enabled',
+    'database_backup_enabled', 'backup_destination_type', 'backup_s3_bucket',
+    'default_protection_level', 'enable_devtools_protection', 'enable_canvas_rendering'
+  ];
+  const settings = Object.fromEntries((await db('app_settings')
+    .whereIn('setting_key', settingKeys).select('setting_key', 'setting_value'))
+    .map((row) => [row.setting_key, parse(row.setting_value)]));
+  const extensions = new Set(String(settings.general_allowed_file_types || 'jpg,jpeg,png,webp')
+    .toLowerCase().split(',').map((s) => s.trim().replace(/^\./, '')));
+  result.video_uploads.configured = ['mp4', 'm4v', 'webm', 'mov', 'avi'].some((extension) => extensions.has(extension));
+  result.camera_raw_uploads.configured = extensions.has('dng');
+  result.public_site.configured = truth(settings.general_public_site_enabled);
+  result.database_backup.configured = truth(settings.database_backup_enabled);
+  result.email_webhook.configured = Boolean((process.env.EMAIL_WEBHOOK_URL || '').trim() && (process.env.EMAIL_WEBHOOK_SECRET || '').trim());
+  result.s3_photo_storage.configured = process.env.STORAGE_BACKEND === 's3' &&
+    Boolean(process.env.STORAGE_S3_BUCKET && process.env.STORAGE_S3_ACCESS_KEY && process.env.STORAGE_S3_SECRET_KEY);
+  result.s3_backups.configured = settings.backup_destination_type === 's3' && Boolean(settings.backup_s3_bucket);
+  result.crm_installments.configured = Boolean(effective.quotes || effective.bills);
+  result.document_templates.configured = Boolean(effective.quotes || effective.contracts);
+  const imapColumns = ['imap_host', 'imap_user', 'imap_pass'];
+  const imapPresent = (query) => { for (const column of imapColumns) query.whereNotNull(column).whereNot(column, ''); };
+  result.incoming_mail.configured = Boolean(effective.incomingMail) && (
+    await exists('email_configs', imapColumns, imapPresent) ||
+    await exists('mail_accounts', [...imapColumns, 'enabled'], (query) => { imapPresent(query); query.where('enabled', formatBoolean(true)); })
+  );
+  result.api_integration.configured = await exists('api_tokens', ['revoked_at', 'expires_at'], (query) => {
+    query.whereNull('revoked_at').where((q) => q.whereNull('expires_at').orWhere('expires_at', '>', new Date(now).toISOString()));
+  });
+  result.webhooks.configured = await enabled('webhooks', 'active');
+  for (const [key, column] of Object.entries({
+    gallery_guest_uploads: 'allow_user_uploads', gallery_downloads: 'allow_downloads',
+    gallery_client_access: 'client_access_enabled', gallery_watermarks: 'watermark_downloads'
+  })) result[key].configured = await enabled('events', column);
+  result.gallery_watermarks.configured ||= truth(settings.branding_watermark_enabled);
+  result.gallery_reveal.configured = await exists('events', ['allow_user_uploads', 'reveal_mode'], (query) =>
+    query.where({ allow_user_uploads: formatBoolean(true), reveal_mode: formatBoolean(true) }));
+  result.gallery_expiration.configured = await exists('events', ['expires_at'], (query) => query.whereNotNull('expires_at'));
+  result.download_resolution_picker.configured = truth(settings.download_resolution_picker_enabled) ||
+    await enabled('events', 'download_resolution_picker_enabled');
+  result.gallery_image_protection.configured = ['standard', 'enhanced', 'maximum'].includes(settings.default_protection_level) ||
+    truth(settings.enable_devtools_protection) || truth(settings.enable_canvas_rendering);
+  for (const column of ['disable_right_click', 'enable_devtools_protection', 'use_canvas_rendering'])
+    result.gallery_image_protection.configured ||= await enabled('events', column);
+  result.gallery_image_protection.configured ||= await exists('events', ['protection_level'], (query) =>
+    query.whereIn('protection_level', ['standard', 'enhanced', 'maximum']));
+  for (const [suffix, column] of Object.entries({
+    likes: 'allow_likes', ratings: 'allow_ratings', comments: 'allow_comments',
+    favorites: 'allow_favorites', reactions: 'allow_reactions', color_labels: 'allow_color_labels'
+  })) result['gallery_feedback_' + suffix].configured = await exists('event_feedback_settings', ['feedback_enabled', column], (query) =>
+    query.where({ feedback_enabled: formatBoolean(true), [column]: formatBoolean(true) }));
+  result.gallery_guest_accounts.configured = await exists('event_feedback_settings', ['feedback_enabled', 'identity_mode'], (query) =>
+    query.where('feedback_enabled', formatBoolean(true)).whereIn('identity_mode', ['guest', 'shared']));
+  return result;
+}
+module.exports = { expandSnapshot };

backend/src/usage/protocol.cjs

@@ -3,13 +3,18 @@ const crypto = require("node:crypto");
 const Ajv = require("ajv");
 const {
   envelopeSchema,
+  envelopeSchemas,
+  CURRENT_SCHEMA_VERSION,
   FEATURE_KEYS,
   LAYOUTS,
   payloads,
 } = require("./schema.cjs");
-const validate = new Ajv({ allErrors: false, strict: true }).compile(
-  envelopeSchema,
-);
+const ajv = new Ajv({ allErrors: false, strict: true });
+const validators = new Map(Object.entries(envelopeSchemas).map(
+  ([version, schema]) => [version, ajv.compile(schema)],
+));
+const validate = (envelope) =>
+  Boolean(validators.get(envelope?.packet?.schema_version)?.(envelope));
 const MAX_BYTES = 16384;
 const MAX_AGE_MS = 5 * 60 * 1000;
 
@@ -56,9 +61,9 @@ function generateIdentity() {
     private_key: keys.privateKey.export({ format: "pem", type: "pkcs8" }),
   };
 }
-function makePacket(identity, action, sequence, payload) {
+function makePacket(identity, action, sequence, payload, schemaVersion = CURRENT_SCHEMA_VERSION) {
   return {
-    schema_version: "usage.v1",
+    schema_version: schemaVersion,
     installation_id: identity.installation_id,
     packet_id: crypto.randomUUID(),
     action,
@@ -139,6 +144,7 @@ function verifyEnvelope(envelope, now = Date.now()) {
   return envelope.packet;
 }
 module.exports = {
+  ...require("./schema.cjs"),
   canonical,
   digest,
   generateIdentity,

backend/src/usage/schema.cjs

@@ -1,138 +1,79 @@
 "use strict";
 
-// Vendored unchanged in PicPeak. Changing the wire contract requires a new
-// schema version and matching conformance tests in both repositories.
-const FEATURE_KEYS = [
-  "crm",
-  "crm_quotes",
-  "crm_invoices",
-  "crm_contracts",
-  "crm_projects",
-  "crm_calendar",
-  "crm_hours",
-  "customer_portal",
-  "accounting",
-  "workflows",
-  "newsletters",
-  "face_recognition",
-  "custom_css",
-  "oauth",
-  "smtp",
-  "whatsapp",
-  "backup",
-  "s3_storage",
-  "share_mounts",
-];
-const LAYOUTS = [
-  "grid",
-  "masonry",
-  "carousel",
-  "timeline",
-  "mosaic",
-  "gallery-premium",
-  "gallery-story",
-  "other",
+// Vendored byte-identical in PicPeak. v1 stays immutable; a larger allowlist
+// has a new wire version and requires explicit, signed v2 consent.
+const CATALOG = require("./features.v2.json");
+const CURRENT_SCHEMA_VERSION = "usage.v2";
+const CURRENT_CONSENT_VERSION = "usage-consent.v2";
+const LEGACY_FEATURE_KEYS = [
+  "crm", "crm_quotes", "crm_invoices", "crm_contracts", "crm_projects",
+  "crm_calendar", "crm_hours", "customer_portal", "accounting", "workflows",
+  "newsletters", "face_recognition", "custom_css", "oauth", "smtp",
+  "whatsapp", "backup", "s3_storage", "share_mounts",
 ];
+const FEATURE_KEYS = Object.keys(CATALOG.features);
+const LAYOUTS = ["grid", "masonry", "carousel", "timeline", "mosaic", "gallery-premium", "gallery-story", "other"];
 const object = (properties, required = Object.keys(properties)) => ({
-  type: "object",
-  additionalProperties: false,
-  properties,
-  required,
+  type: "object", additionalProperties: false, properties, required,
 });
-const uuid = {
-  type: "string",
-  pattern:
-    "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$",
-};
+const uuid = { type: "string", pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" };
 const hash = { type: "string", pattern: "^[0-9a-f]{64}$" };
-const timestamp = {
-  type: "string",
-  pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$",
-};
-const text = (maxLength, minLength = 1) => ({
-  type: "string",
-  minLength,
-  maxLength,
-});
+const timestamp = { type: "string", pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" };
+const text = (maxLength, minLength = 1) => ({ type: "string", minLength, maxLength });
 const boolean = { type: "boolean" };
-const features = object(
-  Object.fromEntries(
-    FEATURE_KEYS.map((key) => [
-      key,
-      object({ configured: boolean, used: boolean }),
-    ]),
-  ),
+const featureKeysFor = (version = CURRENT_SCHEMA_VERSION) =>
+  version === "usage.v1" ? LEGACY_FEATURE_KEYS : version === "usage.v2" ? FEATURE_KEYS : [];
+const observesUse = (key, version = CURRENT_SCHEMA_VERSION) =>
+  version === "usage.v1" || CATALOG.features[key]?.measurement === "configuration_and_use";
+const emptyFeatures = (version = CURRENT_SCHEMA_VERSION) => Object.fromEntries(
+  featureKeysFor(version).map(key => [key, {
+    configured: false, ...(observesUse(key, version) ? { used: false } : {})
+  }])
 );
-const report = object({
-  picpeak_version: {
-    type: "string",
-    maxLength: 48,
-    pattern: "^\\d+\\.\\d+\\.\\d+(?:-(?:alpha|beta|rc)\\.\\d+)?$",
-  },
+const report = (version) => object({
+  picpeak_version: { type: "string", maxLength: 48, pattern: "^\\d+\\.\\d+\\.\\d+(?:-(?:alpha|beta|rc)\\.\\d+)?$" },
   report_date: { type: "string", pattern: "^\\d{4}-\\d{2}-\\d{2}$" },
   generated_at: timestamp,
-  features,
-  gallery_layouts: {
-    type: "array",
-    uniqueItems: true,
-    maxItems: LAYOUTS.length,
-    items: { enum: LAYOUTS },
-  },
+  features: object(Object.fromEntries(featureKeysFor(version).map(key => [
+    key, object({ configured: boolean, ...(observesUse(key, version) ? { used: boolean } : {}) })
+  ]))),
+  gallery_layouts: { type: "array", uniqueItems: true, maxItems: LAYOUTS.length, items: { enum: LAYOUTS } },
 });
 const feedback = object({
-  feedback_id: uuid,
-  kind: { enum: ["feedback", "feature_request", "testimonial"] },
-  title: text(120),
-  body: text(4000),
-  name: text(80, 0),
-  allow_public: boolean,
-  allow_marketing: boolean,
+  feedback_id: uuid, kind: { enum: ["feedback", "feature_request", "testimonial"] },
+  title: text(120), body: text(4000), name: text(80, 0),
+  allow_public: boolean, allow_marketing: boolean,
 });
-const payloads = {
-  register: object({ consent_version: { const: "usage-consent.v1" } }),
-  report,
-  delete: object({}),
-  feedback,
+const makePayloads = (version) => ({
+  register: object({ consent_version: { const: version === "usage.v1" ? "usage-consent.v1" : CURRENT_CONSENT_VERSION } }),
+  report: report(version),
+  delete: object({}), feedback,
   vote: object({ feedback_id: uuid, voted: boolean }),
   session: object({}),
-};
-const packetBase = {
-  schema_version: { const: "usage.v1" },
-  installation_id: hash,
-  packet_id: uuid,
-  sequence: { type: "integer", minimum: 0, maximum: Number.MAX_SAFE_INTEGER },
-};
-const packetSchema = {
-  oneOf: Object.entries(payloads).map(([action, payload]) =>
-    object({
-      ...packetBase,
-      action: { const: action },
-      payload,
-    }),
-  ),
-};
-const envelopeSchema = {
+  ...(version === "usage.v2" ? { consent: object({ consent_version: { const: CURRENT_CONSENT_VERSION } }) } : {}),
+});
+const payloadsByVersion = Object.fromEntries(["usage.v1", "usage.v2"].map(version => [version, makePayloads(version)]));
+const envelopeSchemas = Object.fromEntries(Object.entries(payloadsByVersion).map(([version, actions]) => [version, {
   $schema: "http://json-schema.org/draft-07/schema#",
-  $id: "https://usage.picpeak.app/schema/usage.v1.json",
-  title: "PicPeak usage.v1 signed envelope",
-  description:
-    "Only report.payload is automatic feature telemetry. Other actions are explicit participant operations. See /transparency for field semantics and retention.",
+  $id: `https://usage.picpeak.app/schema/${version}.json`,
+  title: `PicPeak ${version} signed envelope`,
+  description: "Only report.payload is automatic feature telemetry. Other actions are explicit participant operations. See /transparency for field semantics and retention.",
   ...object({
-    packet: packetSchema,
-    public_key: {
-      type: "string",
-      minLength: 59,
-      maxLength: 59,
-      pattern: "^[A-Za-z0-9_-]+$",
-    },
-    issued_at: timestamp,
-    nonce: uuid,
-    signature: {
-      type: "string",
-      minLength: 86,
-      maxLength: 86,
-      pattern: "^[A-Za-z0-9_-]+$",
-    },
+    packet: { oneOf: Object.entries(actions).map(([action, payload]) => object({
+      schema_version: { const: version },
+      installation_id: hash, packet_id: uuid,
+      sequence: { type: "integer", minimum: 0, maximum: Number.MAX_SAFE_INTEGER },
+      action: { const: action }, payload,
+    })) },
+    public_key: { type: "string", minLength: 59, maxLength: 59, pattern: "^[A-Za-z0-9_-]+$" },
+    issued_at: timestamp, nonce: uuid,
+    signature: { type: "string", minLength: 86, maxLength: 86, pattern: "^[A-Za-z0-9_-]+$" },
   }),
+}]));
+const envelopeSchema = envelopeSchemas[CURRENT_SCHEMA_VERSION];
+const payloads = payloadsByVersion[CURRENT_SCHEMA_VERSION];
+module.exports = {
+  FEATURE_KEYS, LEGACY_FEATURE_KEYS, LAYOUTS, CATALOG, CURRENT_SCHEMA_VERSION,
+  CURRENT_CONSENT_VERSION, featureKeysFor, observesUse, emptyFeatures,
+  envelopeSchema, envelopeSchemas, payloads, payloadsByVersion,
 };
-module.exports = { FEATURE_KEYS, LAYOUTS, envelopeSchema, payloads };