settld 0.1.0

package/src/api/http.js

@@ -0,0 +1,124 @@
+export class RequestBodyError extends Error {
+  constructor(statusCode, message, { cause } = {}) {
+    super(message);
+    this.name = "RequestBodyError";
+    this.statusCode = statusCode;
+    if (cause) this.cause = cause;
+  }
+}
+
+function inferReasonCode({ statusCode, message, details }) {
+  const msg = typeof message === "string" ? message.trim() : "";
+  const lower = msg.toLowerCase();
+  const detailsMessage =
+    details && typeof details === "object" && !Array.isArray(details) && typeof details.message === "string" ? details.message : null;
+
+  if (statusCode === 429 || lower === "rate limit exceeded") return "RATE_LIMITED";
+  if (statusCode === 403 && lower === "forbidden") return "FORBIDDEN";
+  if (statusCode === 404 && (lower === "not found" || lower.endsWith(" not found"))) return "NOT_FOUND";
+  if (statusCode === 409 && lower.startsWith("idempotency key conflict")) return "IDEMPOTENCY_CONFLICT";
+  if (lower === "request body too large") return "BODY_TOO_LARGE";
+  if (lower === "invalid json body") return "SCHEMA_INVALID";
+  if (lower === "json body is required") return "SCHEMA_INVALID";
+  if (lower.startsWith("invalid ") || lower.endsWith(" is required") || lower.includes(" are required") || lower.startsWith("missing required")) {
+    return "SCHEMA_INVALID";
+  }
+  if (lower === "event.at is too far in the future") return "FUTURE_TIMESTAMP";
+  if (lower === "too many events in request") return "INGEST_MAX_EVENTS_EXCEEDED";
+  if (lower === "missing precondition") return "MISSING_PRECONDITION";
+
+  if ((lower === "invalid payload" || lower === "event rejected") && typeof detailsMessage === "string") {
+    const m = detailsMessage.match(/\((URL_[A-Z0-9_]+)\)/);
+    if (m && m[1]) return m[1];
+  }
+
+  if (lower === "event chain verification failed") {
+    const err =
+      details && typeof details === "object" && !Array.isArray(details) ? (details.error ?? details.message ?? null) : details;
+    const text = typeof err === "string" ? err.toLowerCase() : "";
+    if (text.includes("signature invalid")) return "SIG_INVALID";
+    if (text.includes("unknown signerkeyid")) return "SIGNER_UNKNOWN";
+    if (text.includes("prevchainhash mismatch") || text.includes("payloadhash mismatch") || text.includes("chainhash mismatch")) {
+      return "CHAIN_BREAK";
+    }
+    return "CHAIN_BREAK";
+  }
+
+  if (lower === "signature policy rejected") {
+    const text = typeof detailsMessage === "string" ? detailsMessage.toLowerCase() : "";
+    if (text.includes("unknown signer key")) return "SIGNER_UNKNOWN";
+    if (text.includes("signer key is not active") || text.includes("revoked")) return "SIGNER_REVOKED";
+    if (text.includes("purpose mismatch")) return "SIGNER_PURPOSE_MISMATCH";
+    return "SIGNATURE_POLICY";
+  }
+
+  if (lower === "job transition rejected") return "TRANSITION_ILLEGAL";
+  if (lower === "invalid event envelope" || lower === "invalid actor" || lower === "invalid payload") return "SCHEMA_INVALID";
+  if (lower === "event rejected") return "EVENT_REJECTED";
+
+  return "UNKNOWN";
+}
+
+function defaultMaxBodyBytes() {
+  const raw = typeof process !== "undefined" ? process.env.PROXY_MAX_BODY_BYTES : null;
+  if (!raw || String(raw).trim() === "") return 1_000_000;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed <= 0) throw new TypeError("PROXY_MAX_BODY_BYTES must be a positive number");
+  return Math.floor(parsed);
+}
+
+export async function readJsonBody(req, { maxBytes = defaultMaxBodyBytes() } = {}) {
+  const contentType = req.headers["content-type"] ?? "";
+  const isJson = contentType.includes("application/json") || contentType.includes("+json");
+  if (!isJson) return null;
+
+  const rawBody = await readRawBody(req, { maxBytes });
+  const raw = String(rawBody ?? "").trim();
+  if (!raw) return null;
+
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new RequestBodyError(400, "invalid JSON body", { cause: err });
+  }
+}
+
+export async function readRawBody(req, { maxBytes = defaultMaxBodyBytes() } = {}) {
+  if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0) throw new TypeError("maxBytes must be a positive safe integer");
+
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    size += buf.length;
+    if (size > maxBytes) {
+      throw new RequestBodyError(413, "request body too large");
+    }
+    chunks.push(buf);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+export function sendJson(res, statusCode, body) {
+  const payload = body === undefined ? "" : JSON.stringify(body, null, 2);
+  res.statusCode = statusCode;
+  res.setHeader("content-type", "application/json; charset=utf-8");
+  res.end(payload);
+}
+
+export function sendText(res, statusCode, body, { contentType = "text/plain; charset=utf-8" } = {}) {
+  res.statusCode = statusCode;
+  res.setHeader("content-type", contentType);
+  res.end(body ?? "");
+}
+
+export function sendError(res, statusCode, message, details, { code = null } = {}) {
+  const reasonCode = code ?? inferReasonCode({ statusCode, message, details });
+  try {
+    res.__settldErrorCode = reasonCode;
+    res.__settldErrorMessage = message;
+  } catch {
+    // ignore
+  }
+  sendJson(res, statusCode, { error: message, code: reasonCode, details });
+}

package/src/api/maintenance.js

@@ -0,0 +1,174 @@
+import { createApi } from "./app.js";
+import { createPgStore } from "../db/store-pg.js";
+import { logger } from "../core/log.js";
+import { configForLog, loadConfig } from "../core/config.js";
+import { makeOpsAuditRecord } from "../core/ops-audit.js";
+import { DEFAULT_TENANT_ID } from "../core/tenancy.js";
+
+const cfg = loadConfig({ mode: "maintenance" });
+logger.info("config.effective", { config: configForLog(cfg) });
+
+const intervalSeconds = cfg.maintenance.intervalSeconds;
+const batchSize = cfg.maintenance.retentionCleanup.batchSize;
+const maxMillis = cfg.maintenance.retentionCleanup.maxMillis;
+const dryRun = cfg.maintenance.retentionCleanup.dryRun;
+
+const store = await createPgStore({ databaseUrl: cfg.store.databaseUrl, schema: cfg.store.pgSchema, migrateOnStartup: cfg.store.migrateOnStartup });
+const api = createApi({ store });
+
+let stopped = false;
+
+async function shutdown(signal) {
+  if (stopped) return;
+  stopped = true;
+  logger.info("maintenance.shutdown", { signal });
+  try {
+    await store?.close?.();
+  } finally {
+    process.exit(0);
+  }
+}
+
+process.on("SIGINT", () => shutdown("SIGINT"));
+process.on("SIGTERM", () => shutdown("SIGTERM"));
+
+logger.info("maintenance.start", { intervalSeconds, batchSize, maxMillis, dryRun, storeMode: "pg", pgSchema: cfg.store.pgSchema });
+
+while (!stopped) {
+  const loopStartedMs = Date.now();
+  try {
+    const retention = await api.tickRetentionCleanup({ tenantId: null, maxRows: batchSize, maxMillis, dryRun, requireLock: true });
+    const retentionOutcome = retention?.ok ? "ok" : retention?.code === "MAINTENANCE_ALREADY_RUNNING" ? "already_running" : "error";
+    try {
+      if (typeof store.appendOpsAudit === "function") {
+        await store.appendOpsAudit({
+          tenantId: DEFAULT_TENANT_ID,
+          audit: makeOpsAuditRecord({
+            tenantId: DEFAULT_TENANT_ID,
+            actorKeyId: null,
+            actorPrincipalId: "maintenance_runner",
+            requestId: null,
+            action: "MAINTENANCE_RETENTION_RUN",
+            targetType: "maintenance",
+            targetId: "retention",
+            at: new Date().toISOString(),
+            details: {
+              origin: "maintenance_runner",
+              outcome: retentionOutcome,
+              scope: retention?.scope ?? "global",
+              dryRun: Boolean(retention?.dryRun),
+              maxRows: Number(retention?.maxRows ?? batchSize),
+              maxMillis: Number(retention?.maxMillis ?? maxMillis),
+              runtimeMs: retention?.runtimeMs ?? null,
+              timedOut: retention?.timedOut === true,
+              purged: retention?.purged ?? null,
+              code: retention?.code ?? null
+            }
+          })
+        });
+      }
+    } catch (err) {
+      logger.error("maintenance.audit_failed", { err });
+    }
+
+    if (!retention?.ok && retention?.code !== "MAINTENANCE_ALREADY_RUNNING") {
+      throw new Error(`retention cleanup failed: ${String(retention?.code ?? "UNKNOWN")}`);
+    }
+
+    const financeReconcile = await api.tickFinanceReconciliation({
+      tenantId: null,
+      period: null,
+      force: true,
+      requireLock: true
+    });
+    const financeOutcome = financeReconcile?.ok ? "ok" : financeReconcile?.code === "MAINTENANCE_ALREADY_RUNNING" ? "already_running" : "error";
+    try {
+      if (typeof store.appendOpsAudit === "function") {
+        await store.appendOpsAudit({
+          tenantId: DEFAULT_TENANT_ID,
+          audit: makeOpsAuditRecord({
+            tenantId: DEFAULT_TENANT_ID,
+            actorKeyId: null,
+            actorPrincipalId: "maintenance_runner",
+            requestId: null,
+            action: "MAINTENANCE_FINANCE_RECONCILE_RUN",
+            targetType: "maintenance",
+            targetId: "finance_reconcile",
+            at: new Date().toISOString(),
+            details: {
+              origin: "maintenance_runner",
+              outcome: financeOutcome,
+              scope: financeReconcile?.scope ?? "global",
+              period: financeReconcile?.period ?? null,
+              force: financeReconcile?.force === true,
+              maxTenants: financeReconcile?.maxTenants ?? null,
+              maxPeriodsPerTenant: financeReconcile?.maxPeriodsPerTenant ?? null,
+              runtimeMs: financeReconcile?.runtimeMs ?? null,
+              summary: financeReconcile?.summary ?? null,
+              code: financeReconcile?.code ?? null
+            }
+          })
+        });
+      }
+    } catch (err) {
+      logger.error("maintenance.audit_failed", { err });
+    }
+
+    if (!financeReconcile?.ok && financeReconcile?.code !== "MAINTENANCE_ALREADY_RUNNING") {
+      throw new Error(`finance reconcile failed: ${String(financeReconcile?.code ?? "UNKNOWN")}`);
+    }
+  } catch (err) {
+    logger.error("maintenance.failed", { err });
+    try {
+      if (typeof store.appendOpsAudit === "function") {
+        await store.appendOpsAudit({
+          tenantId: DEFAULT_TENANT_ID,
+          audit: makeOpsAuditRecord({
+            tenantId: DEFAULT_TENANT_ID,
+            actorKeyId: null,
+            actorPrincipalId: "maintenance_runner",
+            requestId: null,
+            action: "MAINTENANCE_RETENTION_RUN",
+            targetType: "maintenance",
+            targetId: "retention",
+            at: new Date().toISOString(),
+            details: { origin: "maintenance_runner", outcome: "error", dryRun: Boolean(dryRun), maxRows: batchSize, maxMillis, error: err?.message ?? String(err) }
+          })
+        });
+        await store.appendOpsAudit({
+          tenantId: DEFAULT_TENANT_ID,
+          audit: makeOpsAuditRecord({
+            tenantId: DEFAULT_TENANT_ID,
+            actorKeyId: null,
+            actorPrincipalId: "maintenance_runner",
+            requestId: null,
+            action: "MAINTENANCE_FINANCE_RECONCILE_RUN",
+            targetType: "maintenance",
+            targetId: "finance_reconcile",
+            at: new Date().toISOString(),
+            details: {
+              origin: "maintenance_runner",
+              outcome: "error",
+              period: null,
+              force: true,
+              maxTenants: null,
+              maxPeriodsPerTenant: null,
+              error: err?.message ?? String(err)
+            }
+          })
+        });
+      }
+    } catch {}
+    try {
+      await store?.close?.();
+    } finally {
+      process.exit(1);
+    }
+  }
+
+  const elapsedMs = Date.now() - loopStartedMs;
+  const sleepMs = Math.max(0, intervalSeconds * 1000 - elapsedMs);
+  if (sleepMs > 0) {
+    await new Promise((resolve) => setTimeout(resolve, sleepMs));
+  }
+}

package/src/api/middleware/auth.js

@@ -0,0 +1,105 @@
+import { hasScope, parseApiKeyToken, parseBearerAuthorizationHeader, verifyAuthKeySecret } from "../../core/auth.js";
+import { DEFAULT_TENANT_ID, normalizeTenantId } from "../../core/tenancy.js";
+
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+function parseHeader(req, name) {
+  if (!req?.headers) return null;
+  const lower = String(name).toLowerCase();
+  const v = req.headers[lower] ?? req.headers[name] ?? null;
+  return v === null || v === undefined ? null : String(v);
+}
+
+export function requireScope(scopes, scope) {
+  return hasScope(scopes, scope);
+}
+
+export async function authenticateRequest({
+  req,
+  store,
+  tenantId = DEFAULT_TENANT_ID,
+  legacyTokenScopes = new Map(),
+  nowIso = () => new Date().toISOString(),
+  touchMinSeconds = null
+} = {}) {
+  if (!req) throw new TypeError("req is required");
+  if (!store) throw new TypeError("store is required");
+  tenantId = normalizeTenantId(tenantId ?? DEFAULT_TENANT_ID);
+
+  const authz = parseHeader(req, "authorization");
+  const bearer = parseBearerAuthorizationHeader(authz);
+  const apiKeyHeader = parseHeader(req, "x-proxy-api-key");
+
+  const token = apiKeyHeader ? String(apiKeyHeader).trim() : bearer ? String(bearer).trim() : null;
+  if (token) {
+    const parsed = parseApiKeyToken(token);
+    if (parsed) {
+      const { keyId, secret } = parsed;
+      assertNonEmptyString(keyId, "keyId");
+      assertNonEmptyString(secret, "secret");
+
+      const record =
+        typeof store.getAuthKey === "function"
+          ? await store.getAuthKey({ tenantId, keyId })
+          : store.authKeys?.get?.(`${tenantId}\n${keyId}`) ?? null;
+
+      if (!record) return { ok: false, reason: "unknown_key" };
+      if (record.status && record.status !== "active") return { ok: false, reason: "key_inactive" };
+
+      const expiresAt = record.expiresAt ?? null;
+      if (expiresAt) {
+        const expMs = Date.parse(String(expiresAt));
+        const nowMs = Date.parse(nowIso());
+        if (Number.isFinite(expMs) && Number.isFinite(nowMs) && nowMs >= expMs) {
+          return { ok: false, reason: "expired" };
+        }
+      }
+
+      const storedHash = record.secretHash ?? null;
+      const verify = verifyAuthKeySecret({ secret, secretHash: storedHash });
+      if (!verify.ok) {
+        return { ok: false, reason: "bad_secret" };
+      }
+
+      try {
+        if (typeof store.touchAuthKey === "function") {
+          const minSecondsRaw =
+            touchMinSeconds !== null && touchMinSeconds !== undefined
+              ? Number(touchMinSeconds)
+              : typeof process !== "undefined"
+                ? Number(process.env.PROXY_AUTH_KEY_TOUCH_MIN_SECONDS ?? 60)
+                : 60;
+          const minSeconds = Number.isFinite(minSecondsRaw) && minSecondsRaw >= 0 ? minSecondsRaw : 60;
+          const lastMs = record.lastUsedAt ? Date.parse(String(record.lastUsedAt)) : NaN;
+          const nowAt = nowIso();
+          const nowMs = Date.parse(nowAt);
+          const shouldTouch =
+            !Number.isFinite(lastMs) || !Number.isFinite(nowMs) || minSeconds === 0 ? true : nowMs - lastMs >= minSeconds * 1000;
+          if (shouldTouch) {
+            await store.touchAuthKey({ tenantId, keyId, at: nowAt });
+          }
+        }
+      } catch {
+        // Best-effort; auth should not fail hard on last_used_at updates.
+      }
+
+      const scopes = new Set(Array.isArray(record.scopes) ? record.scopes : []);
+      return { ok: true, tenantId, principalId: `auth:${keyId}`, scopes, method: "api_key", keyId };
+    }
+
+    // Legacy ops token (pre-hardening). Accepted only if configured explicitly.
+    const legacy = legacyTokenScopes.get(token);
+    if (legacy) return { ok: true, tenantId, principalId: `legacy_ops:${token}`, scopes: legacy, method: "legacy_ops_token" };
+  }
+
+  const legacyHeader = parseHeader(req, "x-proxy-ops-token");
+  if (legacyHeader && legacyTokenScopes.size) {
+    const legacyToken = String(legacyHeader).trim();
+    const legacy = legacyTokenScopes.get(legacyToken);
+    if (legacy) return { ok: true, tenantId, principalId: `legacy_ops:${legacyToken}`, scopes: legacy, method: "legacy_ops_token" };
+  }
+
+  return { ok: false, reason: "missing" };
+}

package/src/api/middleware/authz.js

@@ -0,0 +1,19 @@
+import { hasScope } from "../../core/auth.js";
+
+export function authorize({ scopes, requiredScopes, mode = "any" } = {}) {
+  const required = Array.isArray(requiredScopes) ? requiredScopes.filter(Boolean) : [];
+  if (!required.length) return false;
+
+  if (mode === "all") {
+    for (const s of required) {
+      if (!hasScope(scopes, s)) return false;
+    }
+    return true;
+  }
+
+  for (const s of required) {
+    if (hasScope(scopes, s)) return true;
+  }
+  return false;
+}
+