@assembly-js/app-foundation 0.0.41 → 0.0.43

package/bin/check-proxy-csrf.mjs

@@ -0,0 +1,387 @@
+#!/usr/bin/env node
+// Fails the build when the app's proxy does not behave like the sign-in proxy:
+// it must reject a state-changing request that lacks the CSRF header, forward
+// one that carries it without the proxy ever adding the header itself, leave
+// the re-exchange route reachable, and accept the cookieless (Safari) bearer.
+// A text check cannot tell a gate from a bypass — an update turn once satisfied
+// "proxy.ts contains APP_CSRF_HEADER" by stamping the header on every request —
+// so this loads the app's real proxy and sends it requests.
+//
+// Runs under node like the other checks, then re-executes itself under bun,
+// which can import the app's TypeScript proxy directly. In that child
+// `server-only` and the node SDK are stubbed and fetch is disabled: no probe
+// carries a session token, so nothing here needs the network.
+//
+// Like check-crons, a broken proxy fails the build only when the current turn
+// changed it (or with --strict, which the update acceptance passes); otherwise
+// the findings are warnings, since there is no agent to act on them. An app
+// still on the pre-bearer foundation only ever warns outside --strict: the
+// platform security update is what fixes it, not an ordinary turn.
+import { existsSync, readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const ROOT = process.cwd();
+const STRICT = process.argv.includes('--strict');
+const PROXY_FILES = ['proxy.ts', 'middleware.ts'];
+const REEXCHANGE_ROUTE = 'app/api/assembly-reexchange/route.ts';
+const REEXCHANGE_PATH = '/api/assembly-reexchange';
+const PRE_BEARER_MARKER = 'lib/assembly.ts';
+const VENDORED_BEARER_MARKER = 'lib/mint-bearer.ts';
+const RESULT_PREFIX = 'check-proxy-csrf-result ';
+const CHILD_TIMEOUT_MS = 60_000;
+
+const TURN_BASELINE_ENV = 'ASSEMBLY_TURN_BASELINE_SHA';
+const PROXY_WIRING_PATHS = [...PROXY_FILES, 'app/api/assembly-reexchange/'];
+
+// Each finding id is a fixed string with a fixed explanation; the request that
+// produced it travels as JSON detail, so reports group by id.
+const FINDINGS = {
+  proxy_missing: 'no proxy.ts at the app root',
+  proxy_unloadable: 'the proxy module could not be loaded',
+  proxy_threw: 'the proxy threw while handling a request',
+  proxy_skips_path: 'the proxy matcher leaves a path that serves app requests unprotected',
+  csrf_gate_missing: 'a state-changing request without the CSRF header was forwarded',
+  csrf_header_stamped: 'the proxy added the CSRF header to a request that did not carry it',
+  csrf_request_blocked: 'a state-changing request carrying the CSRF header was not forwarded',
+  csrf_header_stripped: 'the proxy removed the CSRF header from a forwarded request',
+  server_action_blocked: 'a Next server action was not forwarded',
+  reexchange_not_excluded: 'the proxy matcher does not exclude the re-exchange route',
+  reexchange_blocked_by_proxy: 'the proxy does not pass a re-exchange request through with its CSRF header',
+  reexchange_route_missing: `${REEXCHANGE_ROUTE} is missing`,
+  reexchange_csrf_missing: 'the re-exchange route accepts a request without the CSRF header',
+  reexchange_always_forbidden: 'the re-exchange route rejects a request that carries the CSRF header',
+  cookieless_fallback_missing: 'a bearer sent in the client-bearer header was not forwarded to the render',
+};
+
+if (process.env.ASSEMBLY_PROXY_CHECK_CHILD === '1') {
+  await runProbes();
+} else {
+  runCheck();
+}
+
+// --- parent (node) ---------------------------------------------------------
+
+function runCheck() {
+  const proxyFile = PROXY_FILES.find((f) => existsSync(join(ROOT, f)));
+  // An app still on the pre-bearer foundation (lib/assembly.ts without
+  // lib/mint-bearer.ts, the same markers check-token-usage reads, and no
+  // package proxy) cannot pass this check by an ordinary turn's edits: the platform
+  // security update is what moves it. Its findings stay warnings that say so,
+  // unless --strict (the update's own acceptance) asks for a verdict.
+  const usesPackageProxy =
+    Boolean(proxyFile) && /createAssemblyProxy\s*\(/.test(readFileSync(join(ROOT, proxyFile), 'utf8'));
+  const preBearer =
+    existsSync(join(ROOT, PRE_BEARER_MARKER)) &&
+    !existsSync(join(ROOT, VENDORED_BEARER_MARKER)) &&
+    !usesPackageProxy;
+  const fatal = STRICT || (!preBearer && proxyChangedThisTurn());
+  const report = (findings) => reportFindings(findings, fatal, preBearer);
+  if (!proxyFile) {
+    report([{ id: 'proxy_missing', detail: {} }]);
+    return;
+  }
+
+  const bun = findBun();
+  const child = spawnSync(bun, [fileURLToPath(import.meta.url), ...process.argv.slice(2)], {
+    cwd: ROOT,
+    encoding: 'utf8',
+    timeout: CHILD_TIMEOUT_MS,
+    env: {
+      ...process.env,
+      ASSEMBLY_PROXY_CHECK_CHILD: '1',
+      ASSEMBLY_PROXY_CHECK_FILE: proxyFile,
+      // The gate is dormant while the exchange is off, so probe it switched on.
+      ENABLE_APP_SESSION_TOKEN_EXCHANGE: 'true',
+      ASSEMBLY_API_KEY: '',
+    },
+  });
+  if (child.error) {
+    // No bun to load TypeScript with (e.g. a deploy builder): nothing to prove
+    // here, and the turn that wrote the proxy already ran this in the sandbox.
+    const line = `check-proxy-csrf: skipped, bun is not available (${child.error.code ?? 'spawn error'})`;
+    if (fatal) {
+      console.error(line);
+      process.exit(1);
+    }
+    console.warn(line);
+    return;
+  }
+  const resultLine = (child.stdout ?? '')
+    .split('\n')
+    .reverse()
+    .find((l) => l.startsWith(RESULT_PREFIX));
+  if (!resultLine) {
+    const stderrTail = (child.stderr ?? '').trim().split('\n').slice(-8).join('\n');
+    report([{ id: 'proxy_unloadable', detail: { file: proxyFile, stderr: stderrTail } }]);
+    return;
+  }
+  const { findings } = JSON.parse(resultLine.slice(RESULT_PREFIX.length));
+  if (findings.length > 0) report(findings);
+}
+
+function reportFindings(findings, fatal, preBearer) {
+  const out = fatal ? console.error : console.warn;
+  out('');
+  out(
+    fatal
+      ? 'check-proxy-csrf: the app proxy does not enforce the sign-in CSRF gate:'
+      : 'check-proxy-csrf: the app proxy does not enforce the sign-in CSRF gate (pre-existing; this build is not failed for it):',
+  );
+  out('');
+  for (const { id, detail } of findings) {
+    out(`  - ${id}: ${FINDINGS[id] ?? id} ${JSON.stringify(detail)}`);
+  }
+  out('');
+  if (preBearer && !fatal) {
+    out('This app predates the platform sign-in proxy. The platform security update moves it onto that');
+    out('proxy; do not rewrite proxy.ts in this turn to satisfy this check.');
+    return;
+  }
+  out('proxy.ts is the platform sign-in proxy. It must be exactly this, plus the app\'s own additions in onForward:');
+  out('');
+  out("  import { createAssemblyProxy } from '@assembly-js/app-foundation/server';");
+  out('');
+  out('  export const proxy = createAssemblyProxy({');
+  out('    // optional: onForward({ request, headers, session }) { headers.set(...) },');
+  out('  });');
+  out('');
+  out('  export const config = {');
+  out('    matcher: [');
+  out("      '/((?!_next/static(?:/|$)|_next/image(?:/|$)|api/assembly-reexchange(?:/|$)).*)',");
+  out('    ],');
+  out('  };');
+  out('');
+  out('Never set or delete the CSRF header in the proxy, and never write your own gate.');
+  if (fatal) process.exit(1);
+}
+
+function findBun() {
+  const execPath = process.env.npm_execpath ?? '';
+  if (/\bbun(\.exe)?$/.test(execPath)) return execPath;
+  const installed = join(process.env.BUN_INSTALL ?? join(homedir(), '.bun'), 'bin', 'bun');
+  return existsSync(installed) ? installed : 'bun';
+}
+
+function proxyChangedThisTurn() {
+  const baseline = (process.env[TURN_BASELINE_ENV] ?? '').trim();
+  if (!baseline) return false;
+  const listings = [
+    { args: ['diff', '--name-only', `${baseline}..HEAD`], parse: (line) => line },
+    // Porcelain rows are "XY path", or "XY old -> new" for a rename.
+    { args: ['status', '--porcelain', '--untracked-files=all'], parse: (line) => line.slice(3).split(' -> ').pop() },
+  ];
+  for (const { args, parse } of listings) {
+    const result = spawnSync('git', args, { cwd: ROOT, encoding: 'utf8' });
+    if (result.status !== 0) return true;
+    const changed = result.stdout.split('\n').map((line) => parse(line).trim()).filter(Boolean);
+    if (changed.some((file) => PROXY_WIRING_PATHS.some((p) => (p.endsWith('/') ? file.startsWith(p) : file === p)))) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// --- child (bun) -----------------------------------------------------------
+
+async function runProbes() {
+  const findings = [];
+  const add = (id, detail) => findings.push({ id, detail });
+  const finish = () => {
+    console.log(RESULT_PREFIX + JSON.stringify({ findings }));
+    process.exit(0);
+  };
+
+  stubServerModules();
+  // Next's server runtime installs this global before any app module loads;
+  // its request-scoped helpers (after, headers) throw at import without it.
+  globalThis.AsyncLocalStorage ??= (await import('node:async_hooks')).AsyncLocalStorage;
+  globalThis.fetch = () => Promise.reject(new Error('network is disabled in check-proxy-csrf'));
+
+  const appRequire = createRequire(join(ROOT, 'package.json'));
+  const { NextRequest } = await import(appRequire.resolve('next/server'));
+  const { APP_CSRF_HEADER, BEARER_HEADER_NAME, CLIENT_BEARER_HEADER } = await import(
+    appRequire.resolve('@assembly-js/app-foundation/client')
+  );
+  const proxyFile = process.env.ASSEMBLY_PROXY_CHECK_FILE;
+  const mod = await import(pathToFileURL(join(ROOT, proxyFile)).href);
+  const handler = mod.proxy ?? mod.middleware ?? mod.default;
+  if (typeof handler !== 'function') {
+    add('proxy_unloadable', { file: proxyFile, reason: 'no proxy export' });
+    finish();
+  }
+
+  const origin = 'http://localhost:3000';
+  const send = async (fn, probe, method, path, headers = {}) => {
+    const request = new NextRequest(new URL(path, origin), { method, headers });
+    try {
+      return describeOutcome(await fn(request), headers);
+    } catch (err) {
+      add('proxy_threw', { probe, method, path, error: String(err?.message ?? err) });
+      return null;
+    }
+  };
+  const apiPath = '/api/proxy-check';
+  // CSRF rides on ambient credentials, so the forged-write probes carry a
+  // cookie; a cookieless write (an inbound webhook) is allowed through.
+  const AMBIENT_COOKIE = 'assembly-proxy-check=1';
+  const CROSS_SITE_FORM = {
+    cookie: AMBIENT_COOKIE,
+    origin: 'https://attacker.example',
+    'sec-fetch-site': 'cross-site',
+    'content-type': 'application/x-www-form-urlencoded',
+  };
+  // Next only runs the proxy where config.matcher says, so a probe on any other
+  // path would pass against a gate no real request reaches.
+  const skipped = new Set();
+  for (const path of [apiPath, '/']) {
+    if (!(await proxyRunsOn(appRequire, mod.config, path))) {
+      skipped.add(path);
+      add('proxy_skips_path', { path });
+    }
+  }
+  const proxy = async (probe, method, path, headers) =>
+    skipped.has(path) ? null : send(handler, probe, method, path, headers);
+
+  for (const [method, path] of [
+    ['POST', apiPath],
+    ['PUT', apiPath],
+    ['PATCH', apiPath],
+    ['DELETE', apiPath],
+    ['POST', '/'],
+  ]) {
+    const out = await proxy('no_csrf_header', method, path, { cookie: AMBIENT_COOKIE });
+    if (out && !out.rejected) add('csrf_gate_missing', { method, path, status: out.status, variant: 'cookie' });
+  }
+  // What a cross-site form post actually sends: a gate keyed on any of these
+  // (e.g. trusting a request because it has an Origin) must still reject it.
+  for (const path of [apiPath, '/']) {
+    const out = await proxy('cross_site_form', 'POST', path, CROSS_SITE_FORM);
+    if (out && !out.rejected) add('csrf_gate_missing', { method: 'POST', path, status: out.status, variant: 'cross_site_form' });
+  }
+
+  const read = await proxy('get_without_header', 'GET', apiPath);
+  if (read?.forwarded && read.forwardedHeader(APP_CSRF_HEADER) !== null) {
+    add('csrf_header_stamped', { method: 'GET', path: apiPath });
+  }
+
+  // Legitimate writes come from a signed-in browser, so they carry its cookies too.
+  const write = await proxy('with_csrf_header', 'POST', apiPath, { cookie: AMBIENT_COOKIE, [APP_CSRF_HEADER]: '1' });
+  if (write && !write.forwarded) {
+    add('csrf_request_blocked', { method: 'POST', path: apiPath, status: write.status });
+  } else if (write && write.forwardedHeader(APP_CSRF_HEADER) === null) {
+    add('csrf_header_stripped', { method: 'POST', path: apiPath });
+  }
+
+  const action = await proxy('server_action', 'POST', '/', { cookie: AMBIENT_COOKIE, 'next-action': 'proxy-check' });
+  if (action && !action.forwarded) add('server_action_blocked', { status: action.status });
+
+  // The route enforces CSRF itself; the proxy must either not run on it or
+  // pass it through untouched, else silent renewal is dead after the bearer's
+  // first hour.
+  if (await proxyRunsOn(appRequire, mod.config, REEXCHANGE_PATH)) {
+    add('reexchange_not_excluded', { path: REEXCHANGE_PATH });
+    const out = await proxy('reexchange', 'POST', REEXCHANGE_PATH, { [APP_CSRF_HEADER]: '1' });
+    if (out && (!out.forwarded || out.forwardedHeader(APP_CSRF_HEADER) === null)) {
+      add('reexchange_blocked_by_proxy', { status: out.status });
+    }
+  }
+  if (!existsSync(join(ROOT, REEXCHANGE_ROUTE))) {
+    add('reexchange_route_missing', {});
+  } else {
+    const route = await import(pathToFileURL(join(ROOT, REEXCHANGE_ROUTE)).href);
+    if (typeof route.POST !== 'function') {
+      add('reexchange_route_missing', { reason: 'no POST export' });
+    } else {
+      const bare = await send(route.POST, 'reexchange_route', 'POST', REEXCHANGE_PATH);
+      if (bare && bare.status !== 403) add('reexchange_csrf_missing', { status: bare.status });
+      const headed = await send(route.POST, 'reexchange_route', 'POST', REEXCHANGE_PATH, {
+        [APP_CSRF_HEADER]: '1',
+      });
+      if (headed && headed.status === 403) add('reexchange_always_forbidden', { status: headed.status });
+    }
+  }
+
+  // Browsers that refuse the partitioned cookie (Safari) hold the bearer in
+  // memory and send it as a header; the proxy must hand it to the render.
+  const bearer = unsignedBearer({ workspace_id: 'proxy-check', exp: Math.floor(Date.now() / 1000) + 3600 });
+  const cookieless = await proxy('cookieless_bearer', 'GET', '/', { [CLIENT_BEARER_HEADER]: bearer });
+  if (cookieless && (!cookieless.forwarded || cookieless.forwardedHeader(BEARER_HEADER_NAME) !== bearer)) {
+    add('cookieless_fallback_missing', { status: cookieless.status });
+  }
+
+  finish();
+}
+
+// What the proxy did with a request: forwarded (NextResponse.next / rewrite, or
+// no response at all) or answered itself, and for a forward, the headers the
+// render would see. NextResponse.next({ request: { headers } }) lists every
+// forwarded header in x-middleware-override-headers; without that header the
+// inbound request passes through unchanged.
+function describeOutcome(response, inbound) {
+  if (!response) {
+    return { forwarded: true, rejected: false, status: 200, forwardedHeader: (n) => inbound[n] ?? null };
+  }
+  const forwarded =
+    response.headers.get('x-middleware-next') === '1' || response.headers.has('x-middleware-rewrite');
+  const override = response.headers.get('x-middleware-override-headers');
+  const forwardedHeader = (name) => {
+    if (override === null) return inbound[name] ?? null;
+    return override.split(',').map((h) => h.trim()).includes(name)
+      ? response.headers.get(`x-middleware-request-${name}`)
+      : null;
+  };
+  return {
+    forwarded,
+    rejected: !forwarded && response.status >= 400 && response.status < 500,
+    status: response.status,
+    forwardedHeader,
+  };
+}
+
+async function proxyRunsOn(appRequire, config, path) {
+  if (!config?.matcher) return true;
+  try {
+    const { unstable_doesMiddlewareMatch } = await import(
+      appRequire.resolve('next/experimental/testing/server')
+    );
+    return unstable_doesMiddlewareMatch({ config, url: path });
+  } catch {
+    // No matcher helper in this Next version: assume the proxy runs there.
+    return true;
+  }
+}
+
+function unsignedBearer(claims) {
+  const b64 = (o) => Buffer.from(JSON.stringify(o)).toString('base64url');
+  return `${b64({ alg: 'none', typ: 'JWT' })}.${b64(claims)}.proxy-check`;
+}
+
+// `server-only` throws outside a React Server Component bundle, and the SDK
+// would reach the network; neither has anything to do with the CSRF gate. Bun
+// runtime plugins intercept by resolved file path, not by specifier.
+function stubServerModules() {
+  const stub = (dir, contents) => ({
+    filter: new RegExp(`node_modules[\\\\/]${dir}[\\\\/].*\\.[cm]?js$`),
+    contents,
+  });
+  const stubs = [
+    stub('server-only', 'export {};'),
+    stub(
+      '@assembly-js[\\\\/]node-sdk',
+      "export const OpenAPI = { BASE: 'http://127.0.0.1:9' };\n" +
+        "export async function assemblyApi() { throw new Error('network is disabled in check-proxy-csrf'); }\n",
+    ),
+  ];
+  Bun.plugin({
+    name: 'check-proxy-csrf-stubs',
+    setup(build) {
+      for (const { filter, contents } of stubs) {
+        build.onLoad({ filter }, () => ({ contents, loader: 'js' }));
+      }
+    },
+  });
+}

package/dist/proxy.d.ts

@@ -0,0 +1,11 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { type ExchangedSession } from './session-exchange.js';
+export interface AssemblyProxyForwardContext {
+    request: NextRequest;
+    headers: Headers;
+    session: ExchangedSession | null;
+}
+export interface AssemblyProxyOptions {
+    onForward?: (context: AssemblyProxyForwardContext) => void | Promise<void>;
+}
+export declare function createAssemblyProxy(options?: AssemblyProxyOptions): (request: NextRequest) => Promise<NextResponse | Response>;