@ads-repo/meta-creative-buckets 1.0.0

package/scripts/config.cjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+
+/**
+ * Shared configuration for the creative-buckets dashboard.
+ *
+ * Everything client-specific lives here, so the same scripts run against any Meta ad
+ * account without editing code. Resolution order, first match wins:
+ *
+ *   1. CLI flag        --client acme
+ *   2. Environment     BUCKETS_CLIENT=acme
+ *   3. buckets.config.json in the project root
+ *   4. Defaults below
+ *
+ * The client slug does two jobs: it names the output folder (data/meta-ads/<slug>/) and,
+ * when the per-client env convention is used, it picks the credentials. Both token forms
+ * are accepted so a single-account setup does not need a suffix:
+ *
+ *   META_ACCESS_TOKEN_ACME  +  META_AD_ACCOUNT_ID_ACME     (per-client, slug upper-cased)
+ *   META_ACCESS_TOKEN       +  META_AD_ACCOUNT_ID          (plain fallback)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// .env loading, dependency-free. `dotenv` is used when the project already has it; otherwise
+// a small parser covers the same ground, so the skill drops into any repo without an install.
+// Real environment variables always win over the file, and .env.local shadows .env.
+(function loadEnv() {
+  try {
+    require('dotenv').config();
+  } catch (e) {
+    for (const file of ['.env', '.env.local']) {
+      const p = path.join(process.cwd(), file);
+      if (!fs.existsSync(p)) continue;
+      for (const raw of fs.readFileSync(p, 'utf-8').split('\n')) {
+        const line = raw.trim();
+        if (!line || line.startsWith('#')) continue;
+        const eq = line.indexOf('=');
+        if (eq === -1) continue;
+        const key = line.slice(0, eq).trim().replace(/^export\s+/, '');
+        if (!key || process.env[key] !== undefined) continue;
+        let val = line.slice(eq + 1).trim();
+        // strip matching surrounding quotes, keeping any inside the value
+        if (val.length > 1 && (val[0] === '"' || val[0] === "'") && val[val.length - 1] === val[0]) {
+          val = val.slice(1, -1);
+        }
+        process.env[key] = val;
+      }
+    }
+  }
+})();
+
+const DEFAULTS = {
+  client: 'default',
+  accountName: null,        // shown in the dashboard header; falls back to the account id
+  logo: null,               // path to a client logo (png/jpg/svg), relative to project root
+  agencyLogo: null,         // second logo, drawn to the right of the first
+};
+
+function readFlag(name) {
+  const i = process.argv.indexOf(`--${name}`);
+  if (i !== -1 && process.argv[i + 1] && !process.argv[i + 1].startsWith('--')) {
+    return process.argv[i + 1];
+  }
+  const inline = process.argv.find(a => a.startsWith(`--${name}=`));
+  return inline ? inline.slice(name.length + 3) : null;
+}
+
+function readConfigFile() {
+  const p = path.join(process.cwd(), 'buckets.config.json');
+  if (!fs.existsSync(p)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf-8'));
+  } catch (e) {
+    console.warn(`  ⚠ buckets.config.json is not valid JSON (${e.message}) — using defaults`);
+    return {};
+  }
+}
+
+const fileCfg = readConfigFile();
+
+const client = readFlag('client') || process.env.BUCKETS_CLIENT || fileCfg.client || DEFAULTS.client;
+
+// Slug -> ENV suffix. "acme-cz" becomes ACME_CZ, matching the per-client token convention.
+const SUFFIX = client.toUpperCase().replace(/[^A-Z0-9]+/g, '_').replace(/^_|_$/g, '');
+
+function credentials() {
+  const token = process.env[`META_ACCESS_TOKEN_${SUFFIX}`] || process.env.META_ACCESS_TOKEN;
+  let accountId = process.env[`META_AD_ACCOUNT_ID_${SUFFIX}`] || process.env.META_AD_ACCOUNT_ID;
+  if (accountId && !String(accountId).startsWith('act_')) accountId = 'act_' + accountId;
+  return { token, accountId };
+}
+
+// A single place to fail, so every script gives the same actionable message.
+function requireCredentials() {
+  const { token, accountId } = credentials();
+  if (!token || !accountId) {
+    // On the default client the plain form is the one to show; a named client means the
+    // user is juggling accounts, so lead with the suffixed pair that keeps them apart.
+    const named = client !== DEFAULTS.client;
+    console.error(
+      `\nError: Meta credentials missing${named ? ` for client "${client}"` : ''}.\n\n` +
+      `Add these to .env in your project root (see env.example in the skill folder):\n` +
+      (named
+        ? `  META_ACCESS_TOKEN_${SUFFIX}=your-access-token\n` +
+          `  META_AD_ACCOUNT_ID_${SUFFIX}=act_1234567890\n`
+        : `  META_ACCESS_TOKEN=your-access-token\n` +
+          `  META_AD_ACCOUNT_ID=act_1234567890\n\n` +
+          `Reading several accounts? Suffix each pair with the client slug\n` +
+          `(META_ACCESS_TOKEN_ACME_CZ=…) and pass --client acme-cz.\n`)
+    );
+    process.exit(1);
+  }
+  return { token, accountId };
+}
+
+const dataDir = path.join(process.cwd(), 'data', 'meta-ads', client);
+
+module.exports = {
+  client,
+  envSuffix: SUFFIX,
+  accountName: fileCfg.accountName || DEFAULTS.accountName,
+  logo: fileCfg.logo || DEFAULTS.logo,
+  agencyLogo: fileCfg.agencyLogo || DEFAULTS.agencyLogo,
+  dataDir,
+  historyDir: path.join(dataDir, 'history'),
+  latestFile: path.join(dataDir, 'buckets-latest.json'),
+  credentials,
+  requireCredentials,
+  apiVersion: process.env.META_API_VERSION || 'v25.0',
+  pageSize: parseInt(process.env.META_API_PAGE_SIZE) || 500,
+  rateLimitDelay: parseInt(process.env.META_API_RATE_LIMIT_DELAY) || 400,
+};

package/scripts/encrypt-dashboard.cjs

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+
+/**
+ * Wrap the built dashboard in a password gate, for hosting on a Vercel Hobby plan where
+ * Vercel's own Password Protection is not available.
+ *
+ * The whole page is encrypted with AES-256-GCM under a key derived from the password with
+ * PBKDF2-SHA256 (600k iterations). The output is a small login page that decrypts the real
+ * dashboard in the browser via Web Crypto and writes it into the document. No library, no
+ * server, no build step — it stays a single static file.
+ *
+ *   buckets-matrix.html  ->  buckets-matrix-locked.html
+ *
+ * READ THIS BEFORE RELYING ON IT
+ * ------------------------------
+ * This is a fence, not a vault. The ciphertext ships to anyone who loads the page, so an
+ * attacker can brute-force the password offline at their own pace. 600k PBKDF2 iterations
+ * make that slow but not impossible — a weak password will fall. It stops casual visitors,
+ * search engines and link-forwarding; it does not stop a determined one. For real protection
+ * use Vercel Pro's Password Protection or Cloudflare Access.
+ *
+ * The source file is never modified: this reads it and writes a NEW file alongside.
+ *
+ * Thumbnails: by default the referenced thumbs/ images are inlined into the encrypted
+ * payload, so they cannot be fetched directly from the host. That is the point of the
+ * exercise — leaving them as loose files would expose every creative to anyone guessing
+ * the URL, defeating the gate. It makes the file much larger (~14 MB here). Pass
+ * --keep-thumbs to skip inlining and accept that exposure.
+ *
+ * Usage:
+ *   node encrypt-dashboard.cjs <password> [--in <file>] [--out <file>] [--keep-thumbs]
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const cfg = require('./config.cjs');
+
+// Label for the unlock screen. The dashboard JSON knows the real account name; fall back to
+// the client slug when it has not been fetched yet.
+function accountLabel() {
+  if (cfg.accountName) return cfg.accountName;
+  try {
+    return JSON.parse(fs.readFileSync(cfg.latestFile, 'utf-8')).accountName || cfg.client;
+  } catch (e) {
+    return cfg.client;
+  }
+}
+const LABEL = accountLabel();
+const escHtml = (s) => String(s == null ? '' : s)
+  .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+  .replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+
+const args = process.argv.slice(2);
+const flag = (name) => {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : null;
+};
+const has = (name) => args.includes(name);
+
+const password = args.find((a) => !a.startsWith('--') && args[args.indexOf(a) - 1] !== '--in' && args[args.indexOf(a) - 1] !== '--out');
+
+if (!password) {
+  console.error('Usage: node encrypt-dashboard.cjs <password> [--in <file>] [--out <file>] [--keep-thumbs]');
+  process.exit(1);
+}
+if (password.length < 6) {
+  console.error(`Error: password is ${password.length} characters — too short to be worth encrypting at all.`);
+  process.exit(1);
+}
+// Warn but proceed: the length floor is the caller's call, not this script's.
+// Measured on an M-series Mac at 600k iterations: ~10 guesses/s locally, so a GPU rig lands
+// around 3k/s. A brand-name-plus-year password sits in the first few thousand guesses.
+if (password.length < 12 || /^[A-Za-z]+\d{0,4}$/.test(password)) {
+  console.warn(`\n  ⚠ Weak password (${password.length} chars). A brand-name-plus-year pattern falls to an\n` +
+               `    offline guess in seconds, because the ciphertext is public. This will stop a passer-by\n` +
+               `    following a shared link, and nothing more. Do not treat the page as confidential.`);
+}
+
+const IN = path.resolve(flag('--in') || path.join(cfg.dataDir, 'buckets-matrix.html'));
+const OUT = path.resolve(flag('--out') || IN.replace(/\.html$/, '-locked.html'));
+const KEEP_THUMBS = has('--keep-thumbs');
+
+if (!fs.existsSync(IN)) {
+  console.error(`Error: ${IN} not found — build the dashboard first.`);
+  process.exit(1);
+}
+if (path.resolve(IN) === path.resolve(OUT)) {
+  console.error('Error: --out must differ from --in. This script never overwrites its source.');
+  process.exit(1);
+}
+
+let html = fs.readFileSync(IN, 'utf-8');
+const originalBytes = Buffer.byteLength(html);
+
+// ---------------------------------------------------------------------------
+// Inline the thumbnails, so the gate actually covers the creatives too.
+// ---------------------------------------------------------------------------
+let inlined = 0, missingThumbs = 0;
+if (!KEEP_THUMBS) {
+  const baseDir = path.dirname(IN);
+  const cache = new Map();
+  const toDataUri = (rel) => {
+    if (cache.has(rel)) return cache.get(rel);
+    const p = path.join(baseDir, rel);
+    let uri = null;
+    if (fs.existsSync(p)) {
+      uri = `data:image/jpeg;base64,${fs.readFileSync(p).toString('base64')}`;
+      inlined++;
+    } else {
+      missingThumbs++;
+    }
+    cache.set(rel, uri);
+    return uri;
+  };
+
+  // The page references thumbs/<id>.jpg in the ADS array, and derives thumbs/<id>@full.jpg
+  // from it at runtime. Replace both with data URIs, and neutralise the runtime derivation
+  // by mapping ad id -> full-size data URI in a lookup the page prefers when present.
+  const fullMap = {};
+  html = html.replace(/"thumbs\/([^"]+?)\.jpg"/g, (m, id) => {
+    const small = toDataUri(`thumbs/${id}.jpg`);
+    const full = toDataUri(`thumbs/${id}@full.jpg`);
+    if (full) fullMap[id] = full;
+    return small ? JSON.stringify(small) : m;
+  });
+
+  // fullSrc() turns a thumb path into its @full variant by string replace; with data URIs
+  // that no longer works, so give it an explicit lookup keyed by ad id.
+  const lookup = `\nconst FULL_BY_ID = ${JSON.stringify(fullMap)};\n`;
+  html = html.replace(
+    /function fullSrc\(a\)\{[^\n]*\n/,
+    `${lookup}function fullSrc(a){ return FULL_BY_ID[a.id] || a.thumb || ''; }\n`
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Encrypt: PBKDF2-SHA256 -> AES-256-GCM
+// ---------------------------------------------------------------------------
+const ITER = 600000;
+const salt = crypto.randomBytes(16);
+const iv = crypto.randomBytes(12);
+const key = crypto.pbkdf2Sync(password, salt, ITER, 32, 'sha256');
+const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+const ct = Buffer.concat([cipher.update(Buffer.from(html, 'utf-8')), cipher.final()]);
+const tag = cipher.getAuthTag();
+// Web Crypto expects the auth tag appended to the ciphertext
+const payload = Buffer.concat([ct, tag]).toString('base64');
+
+const page = `<!DOCTYPE html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Creative Matrix - ${escHtml(LABEL)}</title>
+<meta name="robots" content="noindex,nofollow">
+<link href="https://fonts.googleapis.com/css2?family=Raleway:wght@400;500;600;700&display=swap" rel="stylesheet">
+<style>
+*{box-sizing:border-box}
+body{margin:0;min-height:100vh;display:flex;align-items:center;justify-content:center;
+  font-family:'Raleway',-apple-system,sans-serif;background:#F3F4F6;color:#111;padding:24px}
+.box{background:#fff;border:1px solid #E5E7EB;border-radius:12px;padding:32px;width:100%;max-width:380px;
+  box-shadow:0 8px 28px rgba(16,24,40,.08);text-align:center}
+h1{margin:0 0 6px;font-size:19px;font-weight:600}
+.sub{color:#6b7280;font-size:13px;margin-bottom:22px}
+input{width:100%;font-family:inherit;font-size:15px;padding:11px 14px;border:1px solid #E5E7EB;
+  border-radius:8px;outline:none;text-align:center}
+input:focus{border-color:#ff5722}
+button{width:100%;margin-top:10px;font-family:inherit;font-size:14px;font-weight:600;padding:11px;
+  border:none;border-radius:8px;background:#ff5722;color:#fff;cursor:pointer}
+button:hover{filter:brightness(1.05)}
+button:disabled{opacity:.6;cursor:default}
+.err{color:#dc2626;font-size:12.5px;font-weight:600;margin-top:12px;min-height:18px}
+.foot{color:#9ca3af;font-size:11px;margin-top:18px;line-height:1.5}
+</style></head>
+<body>
+<div class="box" id="box">
+  <h1>Creative Matrix</h1>
+  <div class="sub">${escHtml(LABEL)}</div>
+  <form id="f">
+    <input type="password" id="pw" placeholder="Password" autocomplete="current-password" autofocus>
+    <button type="submit" id="go">Unlock</button>
+  </form>
+  <div class="err" id="err"></div>
+  <div class="foot">This page is access-limited, not secured.<br>Do not share the link outside the client.</div>
+</div>
+<script>
+const DATA={salt:"${salt.toString('base64')}",iv:"${iv.toString('base64')}",ct:"${payload}",iter:${ITER}};
+const b64=s=>Uint8Array.from(atob(s),c=>c.charCodeAt(0));
+const KEY='creativeBucketsPw';
+
+async function unlock(pw,quiet){
+  const err=document.getElementById('err'), go=document.getElementById('go');
+  if(!quiet){ go.disabled=true; go.textContent='Decrypting…'; err.textContent=''; }
+  try{
+    const base=await crypto.subtle.importKey('raw',new TextEncoder().encode(pw),'PBKDF2',false,['deriveKey']);
+    const key=await crypto.subtle.deriveKey(
+      {name:'PBKDF2',salt:b64(DATA.salt),iterations:DATA.iter,hash:'SHA-256'},
+      base,{name:'AES-GCM',length:256},false,['decrypt']);
+    const plain=await crypto.subtle.decrypt({name:'AES-GCM',iv:b64(DATA.iv)},key,b64(DATA.ct));
+    // remember the password so a reload does not ask again (sessionStorage = this tab only)
+    try{ sessionStorage.setItem(KEY,pw); }catch(e){}
+    const doc=new TextDecoder().decode(plain);
+    document.open(); document.write(doc); document.close();
+    return true;
+  }catch(e){
+    if(!quiet){
+      err.textContent='Wrong password';
+      go.disabled=false; go.textContent='Unlock';
+      document.getElementById('pw').select();
+    }
+    try{ sessionStorage.removeItem(KEY); }catch(e2){}
+    return false;
+  }
+}
+
+document.getElementById('f').addEventListener('submit',e=>{
+  e.preventDefault();
+  unlock(document.getElementById('pw').value,false);
+});
+
+// already unlocked in this tab? go straight in
+(async()=>{
+  let saved=null;
+  try{ saved=sessionStorage.getItem(KEY); }catch(e){}
+  if(saved) await unlock(saved,true);
+})();
+</script>
+</body></html>`;
+
+fs.writeFileSync(OUT, page);
+
+const outBytes = Buffer.byteLength(page);
+console.log(`\nPassword-gated dashboard`);
+console.log(`  in  : ${path.relative(process.cwd(), IN)}  (${(originalBytes / 1024).toFixed(0)} kB, unchanged)`);
+console.log(`  out : ${path.relative(process.cwd(), OUT)}  (${(outBytes / 1024 / 1024).toFixed(1)} MB)`);
+if (!KEEP_THUMBS) {
+  console.log(`  thumbnails inlined : ${inlined}${missingThumbs ? ` (${missingThumbs} missing)` : ''}`);
+} else {
+  console.log(`  thumbnails NOT inlined — they stay fetchable by direct URL`);
+}
+console.log(`  PBKDF2 iterations  : ${ITER.toLocaleString()}`);
+console.log(`\n  Reminder: the ciphertext is public, so this resists casual access, not a determined`);
+console.log(`  attacker. Use a long password and do not reuse one that protects anything else.`);