@almadar/orb 16.9.1 → 17.1.0

package/shells/almadar-shell/packages/server/src/app.ts

@@ -4,21 +4,39 @@
 
 import express, { type Express } from 'express';
 import cors from 'cors';
+import helmet from 'helmet';
+import rateLimit from 'express-rate-limit';
 import {
   env,
   logger,
   errorHandler,
   notFoundHandler,
   debugEventsRouter,
+  personasRouter,
+  pushRouter,
+  pushServiceWorkerHandler,
+  PUSH_SERVICE_WORKER_PATH,
+  reportsRouter,
+  createHooksRouter,
 } from '@almadar/server';
+import { hookProviders } from './hooks-providers.js';
+import { broadcastBusEvent } from './sse.js';
 import { registerRoutes } from './routes.js';
 
 export const app: Express = express();
 
 // Middleware
-app.use(cors({ origin: true, credentials: true }));
-app.use(express.json());
-app.use(express.urlencoded({ extended: true }));
+app.use(helmet());
+// CORS: env-driven allowlist (CORS_ORIGIN) — never reflect arbitrary origins with credentials.
+app.use(cors({ origin: env.CORS_ORIGIN, credentials: true }));
+app.use(express.json({ limit: '1mb' }));
+app.use(express.urlencoded({ extended: true, limit: '1mb' }));
+// Rate limiting protects deployed apps; verification walkers and local dev
+// fire hundreds of bridge events per minute and must not be throttled —
+// ORB_DISABLE_RATE_LIMIT=1 (set by the verify harness) bypasses it.
+if (process.env.ORB_DISABLE_RATE_LIMIT !== '1') {
+  app.use('/api', rateLimit({ windowMs: 15 * 60 * 1000, max: 300, standardHeaders: true, legacyHeaders: false }));
+}
 
 // Health check
 app.get('/health', (_req, res) => {
@@ -28,9 +46,46 @@ app.get('/health', (_req, res) => {
 // Debug event bus endpoints (dev-only, no-op in production)
 app.use('/api/debug', debugEventsRouter());
 
+// Web Push surface (browser/push-subscribe): public VAPID key + the shared
+// service worker (root-scoped — a SW's max scope is its own directory).
+app.use('/api/push', pushRouter);
+app.get(PUSH_SERVICE_WORKER_PATH, pushServiceWorkerHandler);
+
+// Inbound webhook ingress (I-19 decision): mounted BEFORE the authenticated
+// /api routes — hook senders (Google Calendar watch channels, e-sign status,
+// banking callbacks) cannot present a Firebase token, so each provider
+// VERIFIES its own signature/channel token and unverified requests get 400.
+// Providers are DERIVED from this app's invoked services (generated
+// hooks-providers.ts, I-26). Dispatch = SSE bus broadcast to every connected
+// client, so client circuits' `listens` fire; cron pull stays the backstop.
+app.use(
+  '/api/hooks',
+  createHooksRouter({
+    providers: hookProviders(),
+    dispatch: (event, payload) => {
+      broadcastBusEvent(undefined, {
+        type: 'bus',
+        event,
+        payload,
+        source: { orbital: 'webhook', trait: 'ingress' },
+        timestamp: Date.now(),
+      });
+    },
+  }),
+);
+
+// Dev persona roster (no-op unless ALLOW_DEV_AUTH_BYPASS). Mounted BEFORE
+// registerRoutes, which applies authenticateFirebase to /api — a pre-login
+// persona picker cannot present a token it does not have yet.
+app.use('/api', personasRouter());
+
 // Register generated routes
 registerRoutes(app);
 
+// Server-side report export (Excel/PDF/CSV). Mounted AFTER registerRoutes so
+// the /api auth middleware it registers covers this route too.
+app.use('/api/reports', reportsRouter);
+
 // Error handling
 app.use(notFoundHandler);
 app.use(errorHandler);

package/shells/almadar-shell/packages/server/src/hooks-providers.ts

@@ -0,0 +1,11 @@
+/**
+ * Hook Providers
+ *
+ * Checked-in stub so the template builds standalone in CI; the compiler
+ * overwrites it with the provider map derived from the app's invoked
+ * services × the registry's hook declarations (I-26).
+ */
+
+export function hookProviders() {
+  return {};
+}

package/shells/almadar-shell/packages/server/src/index.ts

@@ -4,14 +4,53 @@
 
 import { initializeFirebase, env, logger } from '@almadar/server';
 
-// Initialize Firebase before anything else uses it
-initializeFirebase();
+// Initialize Firebase before anything else uses it. When no credentials
+// are configured (local dev without FIREBASE_*/FIRESTORE_EMULATOR_HOST),
+// boot anyway — a purely client-side app must still serve.
+try {
+  initializeFirebase();
+} catch (e) {
+  const message = e instanceof Error ? e.message : String(e);
+  // In production the real data source IS Firebase (env.ts refuses to boot with
+  // USE_MOCK_DATA=true there), so swallowing this leaves a server that starts
+  // cleanly and then throws on the first request. Fail at boot instead.
+  if (env.NODE_ENV === 'production') {
+    logger.error(`Firebase is required when NODE_ENV=production — refusing to start: ${message}`);
+    throw e;
+  }
+  logger.warn(`Firebase not configured — auth/db routes disabled: ${message}`);
+}
 
+import { validateIntegrationEnv, FirestoreCredentialPersistence } from '@almadar/server';
 import { app } from './app.js';
+import { invokedServices, installTenantCredentialStore } from './services/clients.js';
+
+// Fail fast in production when a required integration credential is missing
+// (see SECRETS.md); registers the invoked services for /health reporting.
+validateIntegrationEnv(invokedServices);
 
 const PORT = env.PORT || 3030;
 
 async function start(): Promise<void> {
+  // W4 tenant credential store: with a master key configured, stored
+  // credentials (Firestore rows, AES-256-GCM) layer over the env —
+  // store → env → unconfigured — and go live on change without restart.
+  if (process.env.ALMADAR_CREDENTIAL_MASTER_KEY) {
+    try {
+      await installTenantCredentialStore(new FirestoreCredentialPersistence());
+      logger.info('Tenant credential store installed');
+    } catch (e) {
+      const message = e instanceof Error ? e.message : String(e);
+      // A configured master key IS the deployment's statement that the store
+      // is in use — failing to serve it in production is a boot failure.
+      if (env.NODE_ENV === 'production') {
+        logger.error(`Tenant credential store failed to initialize — refusing to start: ${message}`);
+        throw e;
+      }
+      logger.warn(`Tenant credential store unavailable — falling back to env credentials: ${message}`);
+    }
+  }
+
   // Seed mock data when USE_MOCK_DATA is enabled
   if (env.USE_MOCK_DATA) {
     try {

package/shells/almadar-shell/packages/server/src/services/clients.ts

@@ -0,0 +1,17 @@
+/**
+ * Service Clients — placeholder
+ *
+ * Compiler generates the real service clients here (delegating to
+ * @almadar/integrations; see orbital-shell-typescript codegen/service.rs).
+ * This stub only lets the template build standalone; an emitted app
+ * overwrites it wholesale.
+ */
+
+export const declaredServices = [] as const;
+
+export const invokedServices = [] as const;
+
+/** Overwritten at emit time with the RuntimeIntegrationManager-backed store install. */
+export async function installTenantCredentialStore(_adapter: object): Promise<void> {
+  // {{GENERATED_SERVICE_CLIENTS}}
+}

package/shells/almadar-shell/packages/server/src/sse.ts

@@ -0,0 +1,20 @@
+/**
+ * Live-push SSE channel — placeholder
+ *
+ * Compiler generates the real SSE module here (connection registry +
+ * cross-client broadcast; see orbital-shell-typescript backend/server/sse.rs).
+ * This stub only lets the template build standalone; an emitted app
+ * overwrites it wholesale.
+ */
+
+export interface BusBroadcastItem {
+  type: 'bus';
+  event: string;
+  payload?: object;
+  source: { orbital: string; trait: string };
+  timestamp: number;
+}
+
+export function broadcastBusEvent(_originClientId: string | undefined, _item: BusBroadcastItem): void {
+  // {{GENERATED_SSE_BROADCAST}}
+}

package/shells/almadar-shell/packages/server/src/types/express.d.ts

@@ -1,15 +1,9 @@
-import type { EventPayloadValue } from '@almadar/core';
+import type { RawUserClaims } from '@almadar/core';
 
 declare global {
   namespace Express {
     interface Request {
-      firebaseUser?: {
-        uid: string;
-        email?: string;
-        name?: string;
-        picture?: string;
-        [key: string]: EventPayloadValue;
-      };
+      firebaseUser?: RawUserClaims & { uid: string };
     }
   }
 }

package/shells/almadar-shell/packages/server/tsconfig.json

@@ -5,7 +5,6 @@
     "moduleResolution": "bundler",
     "outDir": "./dist",
     "strict": true,
-    "strictNullChecks": false,
     "esModuleInterop": true,
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true,

package/shells/almadar-shell/packages/shared/package.json

@@ -5,7 +5,7 @@
   "main": "src/index.ts",
   "types": "src/index.ts",
   "dependencies": {
-    "@almadar/core": "^7.14.3",
+    "@almadar/core": "^10.102.0",
     "zod": "^3.22.0"
   }
 }