add officer-invoiceshelf sidecar

owns the invoiceshelf contract: instance url, sanctum token and the company
header that scopes every request. the platform side is the usual thin
auth+forward proxy at /api/invoiceshelf and holds no credentials.

built against the live 2.4.2 instance rather than the 3.0.0-alpha.1 checkout
in _references — the route allow-list came from artisan route:list on the
running container. they differ: 2.4.2 has estimates/{id}/convert-to-invoice
but no invoices/{id}/convert-to-estimate.

three upstream quirks absorbed here:
- accept: application/json is mandatory, or an unauthenticated request 302s
  to an html login instead of returning 401
- origin/referer must never be sent, or statefulapi() switches to session+csrf
  and every request 419s. the proxy forwards neither.
- a wrong company header does not error, it silently returns another company's
  data. the pinned company is explicit and logged.

document pdfs are repaired: 2.4.2 prefixes them with a literal serialised http
response (201 bytes) inside a body already typed application/pdf. we slice to
the %PDF- magic. the report routes don't have the bug.

resources are an allow-list. backups, disks, modules, update/*, installation/*,
mail config, settings writes and ownership transfer stay unreachable, and the
per-resource action list keeps `send` — which really emails the customer —
from being reachable by accident.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

src/servers/sidecar/invoiceshelf/index.ts

@@ -0,0 +1,141 @@
+import type { SidecarCommand, SidecarEvent } from '../protocol';
+import { createSidecarConnector } from '../connect';
+import { handleOfficerRoute } from './routes';
+import { callUpstream, getConfig, resolveCompanyId } from './upstream';
+
+// The officer-invoiceshelf sidecar. Owns the whole InvoiceShelf contract for Officer: the instance URL, the
+// Sanctum API token, and the `company` header that scopes every request. The platform API is a thin
+// auth-gated forwarder (src/servers/api/invoiceshelf/router.ts) holding no InvoiceShelf credentials.
+//
+// Built and verified against the LIVE instance, which runs 2.4.2 — NOT against the 3.0.0-alpha.1 checkout in
+// _references/InvoiceShelf. The two differ in ways that matter (2.4.2 has no invoices/{id}/convert-to-estimate
+// and no installation/is-installed). The route allow-list in routes.ts came from `artisan route:list` on the
+// running container.
+//
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+// HTTP CONTRACT — the platform strips its /api/invoiceshelf mount prefix before forwarding.
+//
+//   GET  /_health                          ours. Confirms the token is live and reports the pinned company.
+//   GET  /_officer/summary                 me + current company + dashboard totals, one call
+//   GET  /_officer/lookups                 customers/items/units/tax-types/categories/payment-methods/currencies
+//   GET  /_officer/bootstrap               the upstream's own bootstrap blob
+//   GET  /_officer/next-number?key=invoice the number the next document would take
+//   GET  /_officer/search?search=          cross-entity search
+//   GET  /_officer/reports/:kind           sales-customers|sales-items|tax-summary|profit-loss|expenses → PDF
+//
+//   GET|POST        /_officer/:resource            list / create
+//   GET|PUT|DELETE  /_officer/:resource/:id        read / update / delete
+//   POST            /_officer/:resource/delete     bulk delete {ids:[…]}
+//   GET             /_officer/:resource/templates  invoices|estimates only
+//   GET             /_officer/:resource/:id/pdf    invoices|estimates|payments — magic-byte repaired
+//   GET             /_officer/:resource/:id/preview   rendered email HTML, sends nothing.
+//                                                     Requires ?subject=&body=&from=&to= — the controller
+//                                                     validates them and 422s otherwise.
+//   GET             /_officer/customers/:id/stats
+//   POST            /_officer/:resource/:id/:action   status|clone|send|convert-to-invoice|duplicate
+//   anything else                                     404
+//
+// `:resource` is an allow-list (routes.ts). The administrative half of the API — backups, disks, modules,
+// update/*, installation/*, mail config, settings writes, ownership transfer — is deliberately unreachable.
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+
+const API_URL = process.env.API_URL ?? `ws://127.0.0.1:${process.env.PORT ?? '5000'}`;
+
+/** Grab an ephemeral free port by briefly binding one and releasing it. */
+function getFreePort(): number {
+  const probeServer = Bun.serve({ port: 0, hostname: '127.0.0.1', fetch: () => new Response('') });
+  const p = probeServer.port;
+  probeServer.stop(true);
+  if (p == null) throw new Error('failed to acquire a free port');
+  return p;
+}
+
+const port = getFreePort();
+
+const server = Bun.serve({
+  port,
+  hostname: '127.0.0.1',
+  // Expense receipts and company logos are uploaded as multipart bodies through this proxy.
+  maxRequestBodySize: 64 * 1024 * 1024,
+  async fetch(req) {
+    const url = new URL(req.url);
+    const cfg = getConfig();
+
+    if (url.pathname === '/_health') {
+      if (!cfg) return Response.json({ ok: false, error: 'INVOICESHELF_URL/TOKEN not configured' }, { status: 503 });
+      const started = Date.now();
+      try {
+        const [versionRes, company] = await Promise.all([
+          callUpstream(cfg, { path: '/api/v1/app/version', withCompany: false }),
+          resolveCompanyId(cfg),
+        ]);
+        if (!versionRes.ok) {
+          return Response.json({ ok: false, error: `upstream returned ${versionRes.status}` }, { status: 502 });
+        }
+        const version = (await versionRes.json()) as { version?: string };
+        return Response.json({ ok: true, version: version.version ?? null, company, ms: Date.now() - started });
+      } catch (err) {
+        return Response.json({ ok: false, error: String(err), ms: Date.now() - started }, { status: 502 });
+      }
+    }
+
+    if (url.pathname.startsWith('/_officer/')) {
+      if (!cfg) return Response.json({ error: 'invoiceshelf not configured' }, { status: 503 });
+      try {
+        const res = await handleOfficerRoute(cfg, req, url);
+        if (res) return res;
+        return Response.json({ error: 'not found' }, { status: 404 });
+      } catch (err) {
+        console.error(`[invoiceshelf] ${req.method} ${url.pathname} failed`, err);
+        return Response.json({ error: 'internal error' }, { status: 500 });
+      }
+    }
+
+    return Response.json({ error: 'not found' }, { status: 404 });
+  },
+});
+
+console.log(`[invoiceshelf] listening on 127.0.0.1:${port} -> ${getConfig()?.base ?? '(INVOICESHELF_URL unset)'}`);
+
+type ReplyFn = (msg: SidecarEvent) => void;
+
+function handleCommand(cmd: SidecarCommand, reply: ReplyFn) {
+  switch (cmd.type) {
+    case 'ping':
+      reply({ type: 'pong', id: cmd.id });
+      break;
+    default:
+      reply({
+        type: 'error',
+        id: (cmd as SidecarCommand).id,
+        error: `Unknown command type: ${(cmd as Record<string, unknown>).type}`,
+      });
+  }
+}
+
+const connection = createSidecarConnector({
+  apiUrl: `${API_URL}/api/sidecar/register`,
+  name: 'invoiceshelf',
+  capabilities: ['invoiceshelf'],
+  onCommand(cmd, reply) {
+    handleCommand(cmd as SidecarCommand, reply as ReplyFn);
+  },
+  onConnected() {
+    connection.send({ type: 'invoiceshelf:server', port });
+    console.log(`[invoiceshelf] reported server port ${port} to API`);
+  },
+});
+
+function shutdown(signal: string) {
+  console.log(`[invoiceshelf] ${signal} received, shutting down...`);
+  try {
+    server.stop(true);
+  } catch {
+    /* already stopped */
+  }
+  connection.destroy();
+  process.exit(0);
+}
+
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+process.on('SIGINT', () => shutdown('SIGINT'));