@bongos/core 1.25.21 → 1.25.22

package/src/bongos/folder-upload.js

@@ -0,0 +1,243 @@
+// src/bongos/folder-upload.js — create a project from a folder: check an uploaded folder
+// (papers, artwork, scaffolding) and commit it into the new private repository, so a
+// person with no repository never touches git (task 1005282).
+//
+// Two halves:
+//   checkFolderUpload(files) — PURE. Decides, before anything exists, whether the upload
+//     can become a repository: the size limits, the refused file types, and path safety.
+//     A refusal names each file and the plain reason, so the page can say it.
+//   pushFolderToRepo(...)    — writes the checked files to a temp dir, makes ONE commit and
+//     pushes it to `main` of the empty repo the route just created, acting as the person's
+//     OWN GitHub token. One git push, not one API call per file: GitHub's content-creation
+//     rate limits (about 80 writes a minute) would stall a few hundred files otherwise.
+//
+// Nothing here reads the files' meaning and nothing is sent to an AI service: the platform
+// does not read people's files on its own AI bill. The bytes go from the request to the
+// repository and the temp copy is deleted in `finally`.
+//
+// The credential never sits in argv or a remote: it rides one push as an http.extraHeader
+// set through GIT_CONFIG_* environment variables, and any error text is scrubbed.
+
+const { execFile } = require('node:child_process');
+const fsp = require('node:fs/promises');
+const os = require('node:os');
+const path = require('node:path');
+const { promisify } = require('node:util');
+
+const execFileP = promisify(execFile);
+
+const MB = 1024 * 1024;
+
+// The limits, and why (stated in the task's ship notes too):
+//   • 25 MB a file — GitHub's own "upload files" page takes 25 MB a file, and git pushes
+//     warn at 50 MB and refuse at 100 MB, so this keeps every file well clear of both.
+//   • 50 MB and 1,000 files an upload — the whole folder passes through our small server's
+//     memory once (about 67 MB as it travels), and cost discipline says the hub box is not
+//     a file store. A bigger project can be put on GitHub directly and picked as
+//     "A repo I already have".
+const UPLOAD_LIMITS = Object.freeze({
+  fileBytes: 25 * MB,
+  totalBytes: 50 * MB,
+  files: 1000,
+  pathChars: 300,
+  depth: 32,
+});
+
+// The request body is base64 inside JSON: 4/3 of the bytes, plus names and brackets.
+const UPLOAD_BODY_LIMIT = `${Math.ceil((UPLOAD_LIMITS.totalBytes * 4) / 3 / MB) + 4}mb`;
+
+// File types refused by extension (lower-cased, without the dot), each with its reason.
+const PROGRAM_EXT = ['exe', 'dll', 'msi', 'msix', 'appx', 'scr', 'com', 'pif', 'cpl', 'sys', 'dmg', 'pkg', 'apk', 'aab', 'ipa', 'deb', 'rpm', 'iso', 'img', 'vhd', 'vhdx', 'vmdk'];
+const ARCHIVE_EXT = ['zip', 'rar', '7z', 'tar', 'gz', 'tgz', 'bz2', 'xz'];
+const SECRET_EXT = ['pem', 'p12', 'pfx', 'jks', 'keystore'];
+const SECRET_NAMES = ['id_rsa', 'id_dsa', 'id_ecdsa', 'id_ed25519', '.netrc', '.pgpass'];
+// .env.example and friends are documentation, not secrets
+const ENV_DOC_RE = /^\.env\.(example|sample|template|dist)$/i;
+
+const REASONS = Object.freeze({
+  program: 'Programs, installers and disk images can’t go in. They can’t be read as project material and can carry harm.',
+  archive: 'Zipped files can’t go in. Unzip it on your computer and choose the folder instead, so its files can be seen.',
+  secret: 'This looks like a password or key file. Keep secrets out of the project; nothing was uploaded.',
+  file_too_big: `Each file can be at most ${UPLOAD_LIMITS.fileBytes / MB} MB. Make it smaller or split it, or leave it out and add it on GitHub later.`,
+  unsafe_path: 'This file’s name or folder isn’t allowed: it points outside the folder, or uses a name or characters a project can’t hold. Rename it with plain letters, numbers, spaces and dashes.',
+  git_internal: 'Git’s own internal files can’t be uploaded. Choose the folder without its .git folder.',
+  workflow: 'Files in .github/workflows would start automatic jobs on GitHub, so they can’t be uploaded this way. Leave that folder out; you can add it on GitHub later.',
+  platform_file: 'The platform writes this file itself when it sets your project up. Rename or remove yours so neither is lost.',
+  duplicate: 'Two files have this same name (apart from capital letters). Rename one.',
+  bad_content: 'This file didn’t arrive whole. Choose the folder again.',
+});
+
+// Paths the platform's own setup layer writes (scripts/bongos/adopt-preflight.js
+// INCOMING_PATHS). The setup never overwrites a file already in the repo, so an uploaded
+// copy here would silently replace the platform's: refuse it and say so instead.
+const PLATFORM_FILES = ['config/branding.json', 'config/modules.json', 'config/hierarchy.json'];
+const PLATFORM_DIRS = ['.claude/'];
+
+// Left out quietly and reported as skipped: OS clutter and installed packages (rebuilt
+// from package.json; never part of anyone's papers).
+const SKIP_NAMES = ['.ds_store', 'thumbs.db', 'desktop.ini', 'ehthumbs.db'];
+const SKIP_DIRS = ['node_modules', '__macosx'];
+
+// eslint-disable-next-line no-control-regex
+const CONTROL_RE = /[\u0000-\u001f\u007f]/;
+// Windows device names (CON, NUL, COM1…), with or without an extension: a clone on Windows
+// cannot hold them, and on a Windows host the temp copy would write to the device.
+const WIN_RESERVED_RE = /^(con|prn|aux|nul|com[0-9]|lpt[0-9])(\.|$)/i;
+const BASE64_RE = /^[A-Za-z0-9+/]*={0,2}$/;
+
+function extOf(name) {
+  const i = name.lastIndexOf('.');
+  return i > 0 ? name.slice(i + 1).toLowerCase() : '';
+}
+
+// Why this one path is unsafe, or null. Paths are relative, '/'-separated, and stay
+// inside the folder: no leading slash, drive letter, backslash, '.', '..', or empty part.
+function unsafePathReason(p) {
+  if (typeof p !== 'string' || !p || p.length > UPLOAD_LIMITS.pathChars) return 'unsafe_path';
+  if (CONTROL_RE.test(p) || p.includes('\\') || p.startsWith('/') || /^[A-Za-z]:/.test(p)) return 'unsafe_path';
+  const parts = p.split('/');
+  if (parts.length > UPLOAD_LIMITS.depth) return 'unsafe_path';
+  for (const part of parts) {
+    if (!part || part === '.' || part === '..' || part.length > 255) return 'unsafe_path';
+    if (/[ .]$/.test(part)) return 'unsafe_path';   // Windows drops these silently: two names could become one
+    if (WIN_RESERVED_RE.test(part)) return 'unsafe_path';
+  }
+  return null;
+}
+
+// The rule a safe path breaks, or null: git internals, workflows, platform-owned files,
+// and refused file types.
+function pathRuleReason(p) {
+  const lower = p.toLowerCase();
+  const parts = lower.split('/');
+  const name = parts[parts.length - 1];
+  if (parts.includes('.git') || name === '.gitmodules') return 'git_internal';
+  if (lower.startsWith('.github/workflows/')) return 'workflow';
+  if (PLATFORM_FILES.includes(lower) || PLATFORM_DIRS.some((d) => lower.startsWith(d))) return 'platform_file';
+  if (name === '.env' || (name.startsWith('.env.') && !ENV_DOC_RE.test(name)) || SECRET_NAMES.includes(name)) return 'secret';
+  const ext = extOf(name);
+  if (SECRET_EXT.includes(ext)) return 'secret';
+  if (PROGRAM_EXT.includes(ext)) return 'program';
+  if (ARCHIVE_EXT.includes(ext)) return 'archive';
+  return null;
+}
+
+function isSkipped(p) {
+  const parts = p.toLowerCase().split('/');
+  return SKIP_NAMES.includes(parts[parts.length - 1]) || parts.slice(0, -1).some((d) => SKIP_DIRS.includes(d));
+}
+
+// Decoded size of a base64 string without decoding it.
+function base64Bytes(s) {
+  const pad = s.endsWith('==') ? 2 : s.endsWith('=') ? 1 : 0;
+  return Math.floor((s.length * 3) / 4) - pad;
+}
+
+// The whole upload, checked. `files` is [{ path, data }] with data as base64.
+// Returns { ok, files: [{ path, data }], skipped: [path], problems: [{ path, code, reason }],
+//           totals: { files, bytes }, code, message } — `code`/`message` name the headline
+// refusal when !ok. Nothing is decoded or written; this only decides.
+function checkFolderUpload(files) {
+  const problems = [];
+  const kept = [];
+  const skipped = [];
+  const seen = new Map();
+  let bytes = 0;
+  const refuse = (p, code) => problems.push({ path: typeof p === 'string' ? p.slice(0, UPLOAD_LIMITS.pathChars) : '', code, reason: REASONS[code] });
+
+  if (!Array.isArray(files) || files.length === 0) {
+    return { ok: false, files: [], skipped, problems, totals: { files: 0, bytes: 0 }, code: 'upload_empty', message: 'The folder had no files in it. Choose a folder with at least one file.' };
+  }
+  for (const f of files) {
+    const p = f && f.path;
+    const data = f && f.data;
+    const unsafe = unsafePathReason(p);
+    if (unsafe) { refuse(p, unsafe); continue; }
+    if (isSkipped(p)) { skipped.push(p); continue; }
+    if (typeof data !== 'string' || !BASE64_RE.test(data) || data.length % 4 !== 0) { refuse(p, 'bad_content'); continue; }
+    const rule = pathRuleReason(p);
+    if (rule) { refuse(p, rule); continue; }
+    const size = base64Bytes(data);
+    if (size > UPLOAD_LIMITS.fileBytes) { refuse(p, 'file_too_big'); continue; }
+    const key = p.toLowerCase();
+    if (seen.has(key)) { refuse(p, 'duplicate'); continue; }
+    seen.set(key, true);
+    bytes += size;
+    kept.push({ path: p, data });
+  }
+  const totals = { files: kept.length, bytes };
+  if (problems.length) {
+    const n = problems.length;
+    return { ok: false, files: [], skipped, problems, totals, code: 'upload_refused', message: n === 1 ? 'One file can’t go in, so nothing was created. Remove or fix it, then try again.' : `${n} files can’t go in, so nothing was created. Remove or fix them, then try again.` };
+  }
+  if (kept.length > UPLOAD_LIMITS.files) {
+    return { ok: false, files: [], skipped, problems, totals, code: 'upload_too_many', message: `The folder has ${kept.length} files; the most a folder can have is ${UPLOAD_LIMITS.files}. Nothing was created.` };
+  }
+  if (bytes > UPLOAD_LIMITS.totalBytes) {
+    return { ok: false, files: [], skipped, problems, totals, code: 'upload_too_big', message: `The folder is ${(bytes / MB).toFixed(1)} MB; the most a folder can be is ${UPLOAD_LIMITS.totalBytes / MB} MB. Nothing was created.` };
+  }
+  if (!kept.length) {
+    return { ok: false, files: [], skipped, problems, totals, code: 'upload_empty', message: 'Nothing in the folder could go in (only system clutter or installed packages). Choose a folder with your own files.' };
+  }
+  return { ok: true, files: kept, skipped, problems, totals, code: null, message: null };
+}
+
+// Hide any token in text that may be logged or returned.
+function scrub(s) {
+  return String(s || '')
+    .replace(/(ghs_|ghp_|gho_|ghu_|github_pat_)[A-Za-z0-9_]+/g, '$1***')
+    .replace(/(authorization:\s*basic\s+)[A-Za-z0-9+/=]+/gi, '$1***');
+}
+
+// Default git seam: execFile arg-array, shell:false (the injection discipline used by
+// modules/lifecycle/github-push.js). Tests inject their own.
+async function defaultExec(args, opts = {}) {
+  try {
+    const { stdout } = await execFileP('git', args, { encoding: 'utf8', timeout: 120000, maxBuffer: 16 * MB, ...opts, shell: false });
+    return stdout;
+  } catch (e) {
+    const out = new Error('git failed');
+    out.code = 'GIT_FAILED';
+    out.stderr = scrub(e && (e.stderr || e.message)).slice(-2000);
+    throw out;
+  }
+}
+
+// Commit the checked files into the EMPTY repo owner/repo as one commit on `main`, and
+// push it with the person's token. `remoteUrl` and `exec` are the test seams (a test pushes
+// to a local bare repo). The temp copy is always removed.
+async function pushFolderToRepo({ token, owner, repo, files, author, exec = defaultExec, remoteUrl } = {}) {
+  // async throughout: this runs inside a request, and a sync write of up to 50 MB would
+  // stall every other request on the one Node process
+  const dir = await fsp.mkdtemp(path.join(os.tmpdir(), 'bongos-folder-'));
+  try {
+    const work = path.join(dir, 'w');
+    // the paths were checked by checkFolderUpload; resolve once more so nothing can land
+    // outside the work dir whatever slipped past — all of them, before anything is written
+    const dests = files.map((f) => {
+      const dest = path.resolve(work, ...f.path.split('/'));
+      if (!dest.startsWith(work + path.sep)) throw Object.assign(new Error('unsafe path'), { code: 'UNSAFE_PATH' });
+      return dest;
+    });
+    // each folder once, not once per file
+    for (const d of new Set([work, ...dests.map((d) => path.dirname(d))])) await fsp.mkdir(d, { recursive: true });
+    for (let i = 0; i < files.length; i++) await fsp.writeFile(dests[i], Buffer.from(files[i].data, 'base64'));
+    const who = author && author.name ? author : { name: 'Cloud Bongos upload', email: 'upload@users.noreply.github.com' };
+    const url = remoteUrl || `https://github.com/${owner}/${repo}.git`;
+    const env = { ...process.env, GIT_TERMINAL_PROMPT: '0' };
+    if (token && !remoteUrl) {
+      const basic = Buffer.from(`x-access-token:${token}`).toString('base64');
+      Object.assign(env, { GIT_CONFIG_COUNT: '1', GIT_CONFIG_KEY_0: 'http.https://github.com/.extraheader', GIT_CONFIG_VALUE_0: `AUTHORIZATION: basic ${basic}` });
+    }
+    const opts = { cwd: work, env };
+    await exec(['init', '-q', '-b', 'main'], opts);
+    await exec(['-c', `user.name=${who.name}`, '-c', `user.email=${who.email}`, '-c', 'core.autocrlf=false', 'add', '-A'], opts);
+    await exec(['-c', `user.name=${who.name}`, '-c', `user.email=${who.email}`, 'commit', '-q', '-m', 'Add the uploaded folder'], opts);
+    await exec(['push', '-q', url, 'HEAD:refs/heads/main'], opts);
+    return { files: files.length };
+  } finally {
+    await fsp.rm(dir, { recursive: true, force: true });
+  }
+}
+
+module.exports = { UPLOAD_LIMITS, UPLOAD_BODY_LIMIT, checkFolderUpload, pushFolderToRepo, scrub };

package/src/bongos/routes/github.js

@@ -26,6 +26,7 @@ const { listUserRepos, createUserRepo, listUserOrgs, getOrgAccess, createOrgRepo
 const githubRepos = require('../github-repos');
 const repoInfo = require('../repo-info'); // namespace, so a test can stub loadRepoInfo
 const { validateOrRespond } = require('./_helpers');
+const { UPLOAD_LIMITS, UPLOAD_BODY_LIMIT, checkFolderUpload, pushFolderToRepo, scrub } = require('../folder-upload'); // create a project from an uploaded folder (task 1005282)
 const prelaunch = require('../prelaunch-gate');
 const log = require('../logger').logger.child({ src: 'github' });
 
@@ -66,6 +67,30 @@ async function repoInviteFailure(req, res, err, where) {
   return res.fail('github_error', { status: 502, message: 'GitHub could not be reached. Try again in a moment.' });
 }
 
+// GitHub's refusals to create a repo, each in the owner's words: shared by the plain create
+// and the create-from-a-folder route. Never a 403 for an org refusal (the page reads a 403
+// as "sign in again").
+async function createRepoFailure(req, res, err, org) {
+  if (err && err.code === 'name_taken') {
+    return res.fail('name_taken', { status: 409, message: org
+      ? `${org} already has a repository with that name. Pick another, or adopt the existing one.`
+      : 'You already have a repository with that name. Pick another, or adopt the existing one.' });
+  }
+  if (org && err && err.code === 'org_app_restricted') {
+    return res.fail('org_app_restricted', { status: 409, message: `${org} only lets apps its owners have approved act for it. An owner can approve this platform in the organisation's settings (Third-party access), or create the repo yourself.` });
+  }
+  if (org && err && err.code === 'org_forbidden') {
+    return res.fail('org_forbidden', { status: 409, message: `GitHub didn't let your account create a repository in ${org}. Ask one of its owners, or put the project on your own account.` });
+  }
+  if (org && err && err.code === 'org_not_found') return orgNotFound(res, org);
+  if (err && err.status === 401) {
+    await db.deleteGithubToken({ builderId: req.builder.id }).catch(() => {});
+    return res.fail('repo_scope_required', { status: 403, message: 'Your GitHub authorization expired. Reconnect to create the repo.' });
+  }
+  console.error('[gds] POST /github/repos', err && err.message);
+  return res.fail('github_error', { status: 502, message: 'GitHub could not create the repo. Try again, or create it manually.' });
+}
+
 // Parse + validate the owner/name ref, or send a 400 and return null.
 function parseRepoRef(raw, res) {
   const ref = String(raw || '').trim();
@@ -124,12 +149,28 @@ function parseInviteLogin(raw, res) {
   return login;
 }
 
+// The folder upload's process-local state (task 1005282): how many uploads are being
+// held in memory at once (each can be ~70 MB, and the hub box is small), and the repo a
+// builder's failed upload left behind, which a retry may fill and nothing else.
+// Process-local ON PURPOSE: the hub runs as one Node process on one box (docs/
+// architecture.md), so a retry reaches the process that made the repo. On a restart the
+// map is empty and a retry is refused plainly ("start again with a new name"), never
+// pointed anywhere else. Entries past the window are swept on every write.
+const MAX_UPLOADS_IN_FLIGHT = 2;
+const RETRY_WINDOW_MS = 60 * 60 * 1000;
+let uploadsInFlight = 0;
+const madeForUpload = new Map();
+function rememberUploadRepo(builderId, repo, now = Date.now()) {
+  for (const [id, r] of madeForUpload) if (now - r.at > RETRY_WINDOW_MS) madeForUpload.delete(id);
+  madeForUpload.set(builderId, { full_name: repo.full_name, html_url: repo.html_url, at: now });
+}
+
 // `deps` is the test seam for the two repo-invite helpers: they are imported directly
 // (so the dead-code check sees them used) and a test hands in stand-ins here, because a
 // destructured import cannot be stubbed on the module object the way the older
 // namespace-called helpers below are.
 module.exports = function buildGithubRouter(overrides = {}) {
-  const deps = { inviteRepoCollaborator, repoInviteState, ...overrides };
+  const deps = { inviteRepoCollaborator, repoInviteState, pushFolderToRepo: pushFolderToRepo, ...overrides };
   const router = express.Router();
 
   // rank: archon (permission access_request.review, the same gate as a hall invite) —
@@ -261,24 +302,76 @@ module.exports = function buildGithubRouter(overrides = {}) {
       const repo = org ? await createOrgRepo(token, { org, name }) : await createUserRepo(token, { name });
       res.status(201).json({ repo });
     } catch (err) {
-      if (err && err.code === 'name_taken') {
-        return res.fail('name_taken', { status: 409, message: org
-          ? `${org} already has a repository with that name. Pick another, or adopt the existing one.`
-          : 'You already have a repository with that name. Pick another, or adopt the existing one.' });
-      }
-      if (org && err && err.code === 'org_app_restricted') {
-        return res.fail('org_app_restricted', { status: 409, message: `${org} only lets apps its owners have approved act for it. An owner can approve this platform in the organisation's settings (Third-party access), or create the repo yourself.` });
+      return createRepoFailure(req, res, err, org);
+    }
+  });
+
+  // rank: any-builder — create a project's repository FROM A FOLDER the person uploaded
+  // (task 1005282): papers, artwork or scaffolding, for someone with no repository. The
+  // whole upload is checked first (folder-upload.js: sizes, refused types, path safety),
+  // and a refusal comes back with each file's plain reason BEFORE the repo exists. Then the
+  // private repo is made exactly as POST /github/repos makes it, and the files go in as one
+  // commit on main, pushed with the caller's OWN token. The files are never read for
+  // meaning and never sent to an AI service. If the push fails after the repo was made,
+  // the same builder may retry into THAT repo (`into`), and no other.
+  router.post('/github/repos/upload', express.json({ limit: UPLOAD_BODY_LIMIT }), auth.requireBuilder, async (req, res) => {
+    if (validateOrRespond(req, res, {
+      name: { type: 'string', maxLength: 100 },
+      org: { type: 'string', maxLength: 39 },
+      into: { type: 'string', maxLength: 140 },
+      files: { type: 'array' },   // each entry checked by checkFolderUpload, with its own reason
+    })) return;
+    const body = req.body || {};
+    const into = body.into != null ? String(body.into).trim() : '';
+    const name = String(body.name || '').trim();
+    const org = body.org != null ? String(body.org).trim() : '';
+    if (!into && !REPO_NAME_RE.test(name)) {
+      return res.fail('bad_repo_name', { status: 400, message: 'Repository names use letters, numbers, and . _ - (1–100 chars).' });
+    }
+    if (org && !validGithubLogin(org)) return badOrg(res);
+    const checked = checkFolderUpload(body.files);
+    if (!checked.ok) {
+      return res.fail(checked.code, { status: 400, message: checked.message, details: {
+        problems: checked.problems.slice(0, 50), problem_count: checked.problems.length,
+        skipped: checked.skipped.length, totals: checked.totals, limits: UPLOAD_LIMITS,
+      } });
+    }
+    let retry = null;
+    if (into) {
+      retry = madeForUpload.get(req.builder.id);
+      if (!retry || retry.full_name !== into || Date.now() - retry.at > RETRY_WINDOW_MS) {
+        return res.fail('upload_retry_refused', { status: 409, message: 'Your files can only be retried into the repository this page just made. Start again with a new name.' });
       }
-      if (org && err && err.code === 'org_forbidden') {
-        return res.fail('org_forbidden', { status: 409, message: `GitHub didn't let your account create a repository in ${org}. Ask one of its owners, or put the project on your own account.` });
+    }
+    if (uploadsInFlight >= MAX_UPLOADS_IN_FLIGHT) {
+      return res.fail('upload_busy', { status: 503, message: 'Too many folders are being uploaded right now. Nothing was created. Try again in a minute.' });
+    }
+    const token = await resolveRepoToken(req, res);
+    if (!token) return;
+    uploadsInFlight++;
+    try {
+      let repo = retry ? { full_name: retry.full_name, html_url: retry.html_url } : null;
+      if (!repo) {
+        try {
+          repo = org ? await createOrgRepo(token, { org, name }) : await createUserRepo(token, { name });
+        } catch (err) {
+          return createRepoFailure(req, res, err, org);
+        }
+        rememberUploadRepo(req.builder.id, repo);
       }
-      if (org && err && err.code === 'org_not_found') return orgNotFound(res, org);
-      if (err && err.status === 401) {
-        await db.deleteGithubToken({ builderId: req.builder.id }).catch(() => {});
-        return res.fail('repo_scope_required', { status: 403, message: 'Your GitHub authorization expired. Reconnect to create the repo.' });
+      const [owner, repoName] = String(repo.full_name).split('/');
+      const login = req.builder.github_login;
+      const author = login && validGithubLogin(login) ? { name: login, email: `${login}@users.noreply.github.com` } : null;
+      try {
+        await deps.pushFolderToRepo({ token, owner, repo: repoName, files: checked.files, author });
+      } catch (err) {
+        log.error('[gds] POST /github/repos/upload push', scrub(err && (err.stderr || err.message)));
+        return res.fail('upload_failed', { status: 502, message: `Your repository ${repo.full_name} was made, but your files didn’t reach it. Try again: they go into the same repository.`, details: { repo } });
       }
-      console.error('[gds] POST /github/repos', err && err.message);
-      res.fail('github_error', { status: 502, message: 'GitHub could not create the repo. Try again, or create it manually.' });
+      madeForUpload.delete(req.builder.id);
+      res.status(201).json({ repo, uploaded: { files: checked.totals.files, bytes: checked.totals.bytes, skipped: checked.skipped } });
+    } finally {
+      uploadsInFlight--;
     }
   });
 

package/src/bongos/routes.js

@@ -131,6 +131,9 @@ function buildGdsRouter() {
       // task 1004421: a project's logo — up to 256 KB decoded, ~342 KB as base64.
       // modules/provisioning/routes/look.js mounts its own 400 KB parser.
       /^\/provisioning\/instances\/\d+\/logo$/.test(req.path) ||
+      // task 1005282: a project made from an uploaded folder — up to 50 MB of files,
+      // ~67 MB as base64. routes/github.js mounts its own parser (folder-upload.js limit).
+      req.path === '/github/repos/upload' ||
       // task 1004496: a reference image on a page feedback doc — up to 4 MB decoded,
       // ~5.3 MB as base64. modules/page-notes/routes/page-notes.js mounts its own 8 MB parser.
       /^\/page-notes\/\d+\/images$/.test(req.path) ||

package/src/branding.js

@@ -116,6 +116,10 @@ const ENV_OVERRIDES = [
   // JSON { scope, markdown }, empty when the founder never used the guide. modules/onboarding/guide-handoff.js
   // writes it once: the scope answers as carried over, and the hand-off file. SERVER-ONLY, like the birth.
   ['GUIDE_HANDOFF', ['founding', 'guideHandoff']],
+  // The project's own facts from the startup flow (task 1005129, modules/provisioning/project-facts.js):
+  // base64url JSON { facts, rules }, empty when none were answered. modules/onboarding/project-facts.js
+  // copies them once into the project's editable setting. SERVER-ONLY, like the birth.
+  ['PROJECT_FACTS', ['founding', 'projectFacts']],
 ];
 
 const isObj = (v) => v && typeof v === 'object' && !Array.isArray(v);

package/src/module-api.js

@@ -81,7 +81,7 @@ const { sleep } = require('./sleep');
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.25.21'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.25.22'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');

package/src/sandbox/gate.js

@@ -0,0 +1,164 @@
+'use strict';
+// src/sandbox/gate.js — the sandbox's OUTBOUND GATE: reads to a known provider go out,
+// sends, charges and writes are refused and logged (task 1005291; ADR 0406 §5).
+//
+// WHY. A project's sandbox runs the same app as its live site. It starts with no provider
+// keys of its own (the sandbox service is created with only BONGOS_SANDBOX=1 and its own
+// DATABASE_URL), so by default nothing it does can reach a real customer. When the owner
+// LENDS a real key so the sandbox can show real data, this gate is what keeps it to
+// reading: per known provider, a read passes and anything that would send a message, take
+// a payment or change a record is refused, logged, and kept for the owner to see.
+//
+// WHAT IT CANNOT DO, said plainly (ADR 0406 §5): it sees only calls made through Node's
+// own `fetch`, `http` and `https` in the process it was installed in. Code that bypasses
+// those (a native binary, a child process, another language), or a provider not in the
+// table below, is NOT caught. That is why the owner should lend a read-only or restricted
+// key where the provider offers one: the key is the floor, the gate is the second wall.
+//
+// `decide()` is pure and is the whole policy; `wrapFetch` / `wrapHttp` only apply it.
+
+// Each provider: how to recognise its host, and which calls are reads. Everything that
+// is not a read is refused, named by what it would have done.
+const PROVIDERS = [
+  { name: 'Stripe', host: /(^|\.)stripe\.com$/i, kind: 'charge',
+    // A test-mode key cannot move real money, so the gate stays out of its way.
+    testKey: /^(sk|rk)_test_/ },
+  { name: 'SendGrid', host: /(^|\.)sendgrid\.com$/i, kind: 'send' },
+  { name: 'Mailgun', host: /(^|\.)mailgun\.net$/i, kind: 'send' },
+  { name: 'Postmark', host: /(^|\.)postmarkapp\.com$/i, kind: 'send' },
+  { name: 'Resend', host: /(^|\.)resend\.com$/i, kind: 'send' },
+  { name: 'Amazon SES', host: /^email(-smtp)?\.[a-z0-9-]+\.amazonaws\.com$/i, kind: 'send' },
+  { name: 'Twilio', host: /(^|\.)twilio\.com$/i, kind: 'send' },
+  { name: 'Slack', host: /(^|\.)slack\.com$/i, kind: 'send' },
+  { name: 'Discord', host: /(^|\.)discord(app)?\.com$/i, kind: 'send' },
+  { name: 'PayPal', host: /(^|\.)paypal\.com$/i, kind: 'charge' },
+  { name: 'Square', host: /(^|\.)squareup\.com$/i, kind: 'charge' },
+  { name: 'Shopify', host: /\.myshopify\.com$/i, kind: 'write' },
+  { name: 'GitHub', host: /^api\.github\.com$/i, kind: 'write' },
+  { name: 'Airtable', host: /^api\.airtable\.com$/i, kind: 'write' },
+  // Notion and HubSpot answer some READS by POST (a query, a search), so those paths
+  // are named as reads; any other write is refused.
+  { name: 'Notion', host: /^api\.notion\.com$/i, kind: 'write', postReads: [/^\/v1\/databases\/[^/]+\/query$/, /^\/v1\/search$/] },
+  { name: 'HubSpot', host: /^api\.hubapi\.com$/i, kind: 'write', postReads: [/\/search$/] },
+];
+
+const READ_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+
+const WHAT = { send: 'send a message', charge: 'take or move a payment', write: 'change a record' };
+
+/** The bearer token or basic user on a request, if any (to spot a test-mode key). */
+function credentialOf(headers) {
+  const h = headers || {};
+  const raw = typeof h.get === 'function' ? h.get('authorization') : (h.authorization || h.Authorization || '');
+  const v = String(raw || '').trim();
+  if (/^bearer\s+/i.test(v)) return v.replace(/^bearer\s+/i, '');
+  if (/^basic\s+/i.test(v)) { try { return Buffer.from(v.replace(/^basic\s+/i, ''), 'base64').toString('utf8').split(':')[0]; } catch (_) { return ''; } }
+  return '';
+}
+
+/**
+ * The gate's whole policy. `{ method, host, path, headers }` → `{ allow: true }` or
+ * `{ allow: false, provider, kind, reason }`. A host in no provider's row passes: the
+ * gate covers the providers it knows, and says so.
+ */
+function decide({ method, host, path, headers }) {
+  const m = String(method || 'GET').toUpperCase();
+  const h = String(host || '').toLowerCase().replace(/:\d+$/, '');
+  const p = PROVIDERS.find((x) => x.host.test(h));
+  if (!p) return { allow: true };
+  if (READ_METHODS.has(m)) return { allow: true, provider: p.name };
+  const pathOnly = String(path || '/').split('?')[0];
+  if (m === 'POST' && (p.postReads || []).some((re) => re.test(pathOnly))) return { allow: true, provider: p.name };
+  if (p.testKey && p.testKey.test(credentialOf(headers))) return { allow: true, provider: p.name, testMode: true };
+  return {
+    allow: false, provider: p.name, kind: p.kind,
+    reason: `Refused by the sandbox: this ${m} to ${p.name} would ${WHAT[p.kind]} for real.`,
+  };
+}
+
+/** A small in-memory record of refusals, newest first, shown on the sandbox's own page. */
+// Each refusal is one line on stderr, which Render shows in the sandbox's own log.
+function makeLog({ limit = 100, write = (line) => process.stderr.write(`${line}\n`) } = {}) {
+  const items = [];
+  return {
+    items,
+    add(r) {
+      const entry = { at: new Date().toISOString(), provider: r.provider, kind: r.kind, method: r.method, target: `${r.host}${r.path.split('?')[0]}` };
+      items.unshift(entry);
+      if (items.length > limit) items.length = limit;
+      write(`[bongos-sandbox] refused ${entry.kind} to ${entry.provider}: ${entry.method} ${entry.target}`);
+      return entry;
+    },
+  };
+}
+
+class SandboxRefused extends Error {
+  constructor(d) { super(d.reason); this.name = 'SandboxRefused'; this.code = 'BONGOS_SANDBOX_REFUSED'; this.provider = d.provider; this.kind = d.kind; }
+}
+
+/** Wrap a fetch: a refused call answers 403 with a body that says why, and never leaves. */
+function wrapFetch(fetchImpl, log) {
+  if (!fetchImpl || fetchImpl.__bongosSandbox) return fetchImpl;
+  const wrapped = async function sandboxFetch(input, init = {}) {
+    const url = new URL(typeof input === 'string' || input instanceof URL ? String(input) : input.url);
+    const method = (init.method || (input && input.method) || 'GET');
+    const headers = init.headers || (input && input.headers) || {};
+    const d = decide({ method, host: url.host, path: url.pathname + url.search, headers: typeof headers.get === 'function' ? headers : lower(headers) });
+    if (d.allow) return fetchImpl(input, init);
+    log.add({ ...d, method: String(method).toUpperCase(), host: url.host, path: url.pathname });
+    return new Response(JSON.stringify({ error: { type: 'bongos_sandbox_refused', provider: d.provider, kind: d.kind, message: d.reason } }),
+      { status: 403, headers: { 'content-type': 'application/json', 'x-bongos-sandbox': 'refused' } });
+  };
+  wrapped.__bongosSandbox = true;
+  return wrapped;
+}
+
+const lower = (o) => Object.fromEntries(Object.entries(o || {}).map(([k, v]) => [String(k).toLowerCase(), v]));
+
+// What a request made through http(s).request is aimed at, from any of its call shapes.
+function targetOf(args) {
+  let url = null, opts = {};
+  if (typeof args[0] === 'string' || args[0] instanceof URL) { url = new URL(String(args[0])); if (args[1] && typeof args[1] === 'object') opts = args[1]; }
+  else if (args[0] && typeof args[0] === 'object') opts = args[0];
+  const host = opts.hostname || opts.host || (url && url.hostname) || 'localhost';
+  const path = opts.path || (url ? url.pathname + url.search : '/');
+  return { method: opts.method || 'GET', host, path, headers: lower(opts.headers) };
+}
+
+/** A request object that never connects and fails with the refusal, as a refused socket would. */
+function refusedRequest(d, cb) {
+  const { EventEmitter } = require('node:events');
+  const req = new EventEmitter();
+  let fired = false;
+  const fire = () => { if (fired) return; fired = true; process.nextTick(() => req.emit('error', new SandboxRefused(d))); };
+  Object.assign(req, {
+    write: () => true, setHeader() {}, getHeader() {}, removeHeader() {}, setTimeout() { return req; }, setNoDelay() {}, setSocketKeepAlive() {},
+    end() { fire(); return req; }, abort() { fired = true; }, destroy() { fired = true; return req; }, flushHeaders() {},
+  });
+  void cb;
+  return req;
+}
+
+/** Patch a node `http` / `https` module's request + get through the gate. */
+function wrapHttp(mod, log) {
+  if (!mod || mod.request.__bongosSandbox) return;
+  const realRequest = mod.request;
+  const realGet = mod.get;
+  const guarded = (real, isGet) => {
+    const fn = function sandboxRequest(...args) {
+      const t = targetOf(args);
+      const d = decide(t);
+      if (d.allow) return real.apply(mod, args);
+      log.add({ ...d, method: String(t.method).toUpperCase(), host: t.host, path: t.path });
+      const req = refusedRequest(d, args[args.length - 1]);
+      if (isGet) req.end();
+      return req;
+    };
+    fn.__bongosSandbox = true;
+    return fn;
+  };
+  mod.request = guarded(realRequest, false);
+  mod.get = guarded(realGet, true);
+}
+
+module.exports = { decide, makeLog, wrapFetch, wrapHttp };