Harden lab API review follow-ups

Author: alpha912

.env.docker.example

@@ -53,3 +53,7 @@ WORKER_ENABLED=false
 
 # Payments
 PAYMENTS_ENABLED=false
+
+# Backup automation (used by deploy/backup.sh or the backup systemd unit)
+# BACKUP_ROOT=/opt/localloop-backend/backups
+# RETENTION_DAYS=14

CHANGELOG.md

@@ -5,6 +5,8 @@
 - GET endpoints for all five Loop entity types: `GET /api/v1/material/:id`,
   `/material`, `/product/:id`, `/product`, `/offer/:id`, `/offer`,
   `/match/:id`, `/match`, `/transfer/:id`, `/transfer`.
+- Minimal lab `GET /api/v1/node/info` endpoint for local node metadata.
+- Backup automation artifacts: `deploy/backup.sh`, systemd backup service, and timer.
 - `category` and `status` query filters on list endpoints.
 - Migration `010_loop_indexes.sql`: performance indexes on all loop_* tables
   (category, status, city columns, FK columns, created_at DESC).
@@ -18,6 +20,9 @@
 ### Changed
 - `DB_POOL_SIZE` default raised from 10 to 20.
 - `.env.docker.example` documents new pool/timeout vars.
+- Federation handshake responses now default to the preferred v0.2.0 context/version.
+- Relay validation now restricts relayed event/entity combinations to supported lab event families.
+- `deploy/setup.sh` now provisions `.env.docker` for Docker-based operations.
 
 ### Security
 - Rotated all `.env.docker` secrets (postgres, minio, better-auth).

README.md

@@ -41,6 +41,7 @@ bun test                      # run all tests
 | `POST` | `/api/v1/material` | Register a MaterialDNA record |
 | `GET` | `/api/v1/material/:id` | Retrieve a material by ID |
 | `GET` | `/api/v1/material` | List materials (`limit`, `category`) |
+| `GET` | `/api/v1/node/info` | Return local node metadata for the lab backend |
 | `POST` | `/api/v1/product` | Register a ProductDNA record |
 | `GET` | `/api/v1/product/:id` | Retrieve a product by ID |
 | `GET` | `/api/v1/product` | List products (`limit`, `category`) |
@@ -56,13 +57,13 @@ bun test                      # run all tests
 | `POST` | `/api/v1/material-status` | Record a material status update |
 | `GET` | `/api/v1/events` | List loop events (`limit`) |
 | `GET` | `/api/v1/stream` | SSE stream for loop events |
-| `POST` | `/api/v1/relay` | Relay a loop event from another node |
+| `POST` | `/api/v1/relay` | Relay a supported lab loop event from another node |
 
 ### Federation
 | Method | Path | Description |
 | --- | --- | --- |
 | `GET` | `/api/v1/federation/nodes` | List known federation nodes |
-| `POST` | `/api/v1/federation/handshake` | Register a federation node |
+| `POST` | `/api/v1/federation/handshake` | Register a federation node (lab-only handshake) |
 
 ### Cities
 | Method | Path | Description |
@@ -80,6 +81,8 @@ bun test                      # run all tests
 | `GET` | `/docs` | Redoc UI |
 
 LOOP write routes accept both `application/json` and `application/ld+json`.
+The backend also serves `GET /api/v1/node/info` as a minimal lab-only node metadata endpoint.
+Spec endpoints that remain unimplemented in this repo are `/api/v1/material/search`, `/api/v1/signals`, `/api/v1/transaction`, `/api/v1/federate/announce`, and `/api/v1/federate/offer`.
 
 ## Environment variables
 

deploy/backup.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+PROJECT_DIR="${PROJECT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
+COMPOSE_FILE="${COMPOSE_FILE:-$PROJECT_DIR/docker-compose.yml}"
+BACKUP_ROOT="${BACKUP_ROOT:-$PROJECT_DIR/backups}"
+RETENTION_DAYS="${RETENTION_DAYS:-14}"
+STAMP="$(date -u +%Y%m%dT%H%M%SZ)"
+RUN_DIR="$BACKUP_ROOT/$STAMP"
+
+require_command() {
+  if ! command -v "$1" >/dev/null 2>&1; then
+    echo "Missing required command: $1" >&2
+    exit 1
+  fi
+}
+
+require_file() {
+  if [[ ! -f "$1" ]]; then
+    echo "Required file not found: $1" >&2
+    exit 1
+  fi
+}
+
+require_command docker
+require_file "$COMPOSE_FILE"
+
+mkdir -p "$RUN_DIR/postgres" "$RUN_DIR/redis" "$RUN_DIR/minio" "$RUN_DIR/manifests"
+
+echo "Creating backup at $RUN_DIR"
+
+cd "$PROJECT_DIR"
+
+docker compose -f "$COMPOSE_FILE" exec -T postgres sh -lc \
+  'PGPASSWORD="$POSTGRES_PASSWORD" pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc' \
+  > "$RUN_DIR/postgres/localloop.dump"
+
+docker compose -f "$COMPOSE_FILE" exec -T redis redis-cli SAVE >/dev/null
+cp "$PROJECT_DIR/data/redis/dump.rdb" "$RUN_DIR/redis/dump.rdb"
+
+tar -czf "$RUN_DIR/minio/minio-data.tar.gz" -C "$PROJECT_DIR" data/minio
+
+printf '%s\n' \
+  "timestamp=$STAMP" \
+  "project_dir=$PROJECT_DIR" \
+  "compose_file=$COMPOSE_FILE" \
+  "retention_days=$RETENTION_DAYS" \
+  > "$RUN_DIR/manifests/backup.env"
+
+ln -sfn "$RUN_DIR" "$BACKUP_ROOT/latest"
+
+find "$BACKUP_ROOT" -mindepth 1 -maxdepth 1 -type d ! -name "$STAMP" -mtime +"$RETENTION_DAYS" -exec rm -rf {} +
+
+echo "Backup complete: $RUN_DIR"

deploy/localloop-backend-backup.service

@@ -0,0 +1,17 @@
+[Unit]
+Description=localLOOP Backend Backup
+After=docker.service network.target
+Requires=docker.service
+
+[Service]
+Type=oneshot
+WorkingDirectory=/opt/localloop-backend
+EnvironmentFile=-/opt/localloop-backend/.env
+ExecStart=/opt/localloop-backend/deploy/backup.sh
+User=root
+Group=root
+NoNewPrivileges=yes
+ProtectSystem=strict
+ProtectHome=yes
+PrivateTmp=yes
+ReadWritePaths=/opt/localloop-backend/backups /opt/localloop-backend/data

deploy/localloop-backend-backup.timer

@@ -0,0 +1,10 @@
+[Unit]
+Description=Nightly localLOOP backend backup
+
+[Timer]
+OnCalendar=*-*-* 02:30:00
+Persistent=true
+Unit=localloop-backend-backup.service
+
+[Install]
+WantedBy=timers.target

deploy/setup.sh

@@ -32,11 +32,12 @@ fi
 echo "Setting up installation directory..."
 mkdir -p "$INSTALL_DIR"
 mkdir -p "$INSTALL_DIR/data"
+mkdir -p "$INSTALL_DIR/backups"
 
 # Copy application files (if running from source directory)
 if [[ -f "src/index.ts" ]]; then
     echo "Copying application files..."
-    cp -r src package.json bun.lock prisma prisma.config.ts "$INSTALL_DIR/"
+    cp -r src deploy package.json bun.lock prisma prisma.config.ts docker-compose.yml .env.example .env.docker.example "$INSTALL_DIR/"
 
     # Copy .env.example if .env doesn't exist
     if [[ ! -f "$INSTALL_DIR/.env" ]]; then
@@ -45,6 +46,13 @@ if [[ -f "src/index.ts" ]]; then
         echo "IMPORTANT: Edit $INSTALL_DIR/.env with your production configuration!"
         echo "Required: DATABASE_URL, MINIO_SECRET_KEY, BETTER_AUTH_SECRET (if auth enabled)"
     fi
+
+    if [[ ! -f "$INSTALL_DIR/.env.docker" ]]; then
+        cp .env.docker.example "$INSTALL_DIR/.env.docker"
+        echo ""
+        echo "IMPORTANT: Edit $INSTALL_DIR/.env.docker before enabling Docker-based operations!"
+        echo "Required: POSTGRES_PASSWORD, MINIO_ROOT_PASSWORD, MINIO_SECRET_KEY, DATABASE_URL"
+    fi
 fi
 
 # Set ownership
@@ -55,9 +63,12 @@ chown -R "$SERVICE_USER:$SERVICE_GROUP" "$INSTALL_DIR"
 if [[ -f "deploy/localloop-backend.service" ]]; then
     echo "Installing systemd service..."
     cp deploy/localloop-backend.service /etc/systemd/system/localloop-backend.service
+    cp deploy/localloop-backend-backup.service /etc/systemd/system/localloop-backend-backup.service
+    cp deploy/localloop-backend-backup.timer /etc/systemd/system/localloop-backend-backup.timer
     systemctl daemon-reload
     echo "Service installed. Enable with: systemctl enable localloop-backend"
     echo "Start with: systemctl start localloop-backend"
+    echo "Enable backups with: systemctl enable --now localloop-backend-backup.timer"
 fi
 
 # Verify bun is installed
@@ -75,3 +86,4 @@ echo "1. Edit $INSTALL_DIR/.env with production credentials"
 echo "2. Run 'cd $INSTALL_DIR && bun install' as $SERVICE_USER"
 echo "3. Run 'systemctl enable --now localloop-backend'"
 echo "4. Check status with 'systemctl status localloop-backend'"
+echo "5. Enable nightly backups with 'systemctl enable --now localloop-backend-backup.timer'"

src/federation/registry.ts

@@ -10,11 +10,16 @@ export type NodeRecord = {
   lab_only: true;
 };
 
+export function resolveNodeApiEndpoint(publicBaseUrl: string) {
+  const trimmed = publicBaseUrl.replace(/\/+$/, '');
+  return trimmed.endsWith('/api/v1') ? trimmed : `${trimmed}/api/v1`;
+}
+
 export function getLocalNode(): NodeRecord {
   return {
     node_id: config.node.id,
     name: config.node.name,
-    endpoint: config.publicBaseUrl,
+    endpoint: resolveNodeApiEndpoint(config.publicBaseUrl),
     capabilities: config.node.capabilities,
     last_seen: new Date().toISOString(),
     lab_only: true,

src/routes/federation.ts

@@ -1,10 +1,11 @@
 import type { FastifyInstance } from 'fastify';
 import { config } from '../config';
 import { incrementMetric } from '../metrics';
-import { getLocalNode, listNodes, upsertNode, type NodeRecord } from '../federation/registry';
+import { getLocalNode, listNodes, resolveNodeApiEndpoint, upsertNode, type NodeRecord } from '../federation/registry';
 import { requireApiKey } from '../security/apiKey';
 import { federationSchemaIds, registerFederationSchemas } from '../schemas/federationSchemas';
 import { loopContentType } from '../protocol';
+import packageInfo from '../../package.json';
 
 const listResponseSchema = {
   type: 'object',
@@ -28,6 +29,21 @@ const listResponseSchema = {
   },
 };
 
+const nodeInfoResponseSchema = {
+  type: 'object',
+  required: ['@context', '@type', 'id', 'name', 'version', 'endpoint', 'capabilities', 'lab_only'],
+  properties: {
+    '@context': { type: 'string' },
+    '@type': { type: 'string', const: 'NodeInfo' },
+    id: { type: 'string' },
+    name: { type: 'string' },
+    version: { type: 'string' },
+    endpoint: { type: 'string' },
+    capabilities: { type: 'array', items: { type: 'string' } },
+    lab_only: { type: 'boolean', const: true },
+  },
+};
+
 const apiKeySecurity = [{ ApiKeyAuth: [] }];
 
 const writeRateLimit = {
@@ -50,6 +66,26 @@ const defaultDeps: FederationDeps = {
 export async function registerFederationRoutes(app: FastifyInstance, deps: FederationDeps = defaultDeps) {
   registerFederationSchemas(app);
 
+  app.get('/api/v1/node/info', {
+    schema: {
+      response: {
+        200: nodeInfoResponseSchema,
+      },
+    },
+  }, async () => {
+    const local = deps.getLocalNode();
+    return {
+      '@context': 'https://local-loop-io.github.io/projects/loop-protocol/contexts/loop-v0.2.0.jsonld',
+      '@type': 'NodeInfo',
+      id: local.node_id,
+      name: local.name,
+      version: packageInfo.version,
+      endpoint: resolveNodeApiEndpoint(config.publicBaseUrl),
+      capabilities: local.capabilities,
+      lab_only: true,
+    };
+  });
+
   app.get('/api/v1/federation/nodes', {
     schema: {
       response: {
@@ -99,7 +135,7 @@ export async function registerFederationRoutes(app: FastifyInstance, deps: Feder
     reply.code(202).send({
       '@context': 'https://local-loop-io.github.io/projects/loop-protocol/contexts/loop-v0.2.0.jsonld',
       '@type': 'NodeHandshakeResponse',
-      schema_version: '0.1.1',
+      schema_version: '0.2.0',
       status: 'accepted',
       peer_id: local.node_id,
       capabilities: local.capabilities,

src/routes/loop.ts

@@ -96,6 +96,14 @@ const writeRateLimit = {
   timeWindow: config.rateLimitWriteWindow,
 };
 
+const allowedRelayEvents: Record<string, readonly string[]> = {
+  material: ['material.created', 'material.status_updated'],
+  product: ['product.created'],
+  offer: ['offer.created'],
+  match: ['match.created'],
+  transfer: ['transfer.created'],
+};
+
 type DbLikeError = Error & {
   code?: string;
 };
@@ -178,6 +186,14 @@ function sendWriteConflict(error: unknown, reply: FastifyReply) {
   return false;
 }
 
+function isAllowedRelayEvent(entityType: string, eventType: string) {
+  if (!Object.hasOwn(allowedRelayEvents, entityType)) {
+    return false;
+  }
+
+  return allowedRelayEvents[entityType]?.includes(eventType) ?? false;
+}
+
 export async function registerLoopRoutes(app: FastifyInstance, deps: LoopDeps = defaultDeps) {
   app.post('/api/v1/material', {
     config: { rateLimit: writeRateLimit },
@@ -652,6 +668,11 @@ export async function registerLoopRoutes(app: FastifyInstance, deps: LoopDeps =
       source_node?: string;
     };
 
+    if (!isAllowedRelayEvent(payload.entity_type, payload.event_type)) {
+      reply.code(400).send({ error: 'Unsupported relay event_type for entity_type' });
+      return;
+    }
+
     const eventPayload = {
       ...payload.payload,
       source_node: payload.source_node ?? 'remote',