settld 0.1.0

package/src/core/evidence-store.js

@@ -0,0 +1,286 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { presignS3Url } from "./s3-presign.js";
+import { normalizeTenantId } from "./tenancy.js";
+
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+function assertPlainObject(value, name) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${name} must be an object`);
+  if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+    throw new TypeError(`${name} must be a plain object`);
+  }
+}
+
+export function parseObjEvidenceRef(evidenceRef) {
+  assertNonEmptyString(evidenceRef, "evidenceRef");
+  if (!evidenceRef.startsWith("obj://")) throw new TypeError("evidenceRef must start with obj://");
+  const raw = evidenceRef.slice("obj://".length);
+  if (!raw || raw.trim() === "") throw new TypeError("evidenceRef path is required");
+  if (raw.includes("\0")) throw new TypeError("evidenceRef must not contain NUL");
+
+  const normalized = raw.replaceAll("\\", "/");
+  const parts = normalized.split("/").filter(Boolean);
+  for (const part of parts) {
+    if (part === "." || part === "..") throw new TypeError("evidenceRef must not contain path traversal");
+  }
+  return parts.join("/");
+}
+
+export function buildEvidenceDownloadUrl({ basePath = "/evidence/download", tenantId, jobId, evidenceId, evidenceRef, expiresAt, secret }) {
+  assertNonEmptyString(basePath, "basePath");
+  tenantId = normalizeTenantId(tenantId);
+  assertNonEmptyString(jobId, "jobId");
+  assertNonEmptyString(evidenceId, "evidenceId");
+  assertNonEmptyString(evidenceRef, "evidenceRef");
+  assertNonEmptyString(expiresAt, "expiresAt");
+  assertNonEmptyString(secret, "secret");
+
+  const sig = signEvidenceDownload({ secret, tenantId, jobId, evidenceId, evidenceRef, expiresAt });
+  const qs = new URLSearchParams({
+    tenantId,
+    jobId,
+    evidenceId,
+    evidenceRef,
+    expiresAt,
+    sig
+  });
+  return `${basePath}?${qs.toString()}`;
+}
+
+export function signEvidenceDownload({ secret, tenantId, jobId, evidenceId, evidenceRef, expiresAt }) {
+  assertNonEmptyString(secret, "secret");
+  tenantId = normalizeTenantId(tenantId);
+  assertNonEmptyString(jobId, "jobId");
+  assertNonEmptyString(evidenceId, "evidenceId");
+  assertNonEmptyString(evidenceRef, "evidenceRef");
+  assertNonEmptyString(expiresAt, "expiresAt");
+
+  const data = `${tenantId}\n${jobId}\n${evidenceId}\n${evidenceRef}\n${expiresAt}`;
+  return crypto.createHmac("sha256", secret).update(data, "utf8").digest("hex");
+}
+
+export function verifyEvidenceDownload({ secret, tenantId, jobId, evidenceId, evidenceRef, expiresAt, sig, nowMs = Date.now() }) {
+  assertNonEmptyString(secret, "secret");
+  assertNonEmptyString(sig, "sig");
+  tenantId = normalizeTenantId(tenantId);
+  assertNonEmptyString(jobId, "jobId");
+  assertNonEmptyString(evidenceId, "evidenceId");
+  assertNonEmptyString(evidenceRef, "evidenceRef");
+  assertNonEmptyString(expiresAt, "expiresAt");
+  if (!Number.isFinite(nowMs)) throw new TypeError("nowMs must be a finite number");
+
+  const expMs = Date.parse(expiresAt);
+  if (!Number.isFinite(expMs)) return { ok: false, error: "invalid expiresAt" };
+  if (nowMs > expMs) return { ok: false, error: "expired" };
+
+  const expected = signEvidenceDownload({ secret, tenantId, jobId, evidenceId, evidenceRef, expiresAt });
+  const ok = crypto.timingSafeEqual(Buffer.from(expected, "utf8"), Buffer.from(sig, "utf8"));
+  return ok ? { ok: true } : { ok: false, error: "bad signature" };
+}
+
+export function createFsEvidenceStore({ rootDir }) {
+  assertNonEmptyString(rootDir, "rootDir");
+
+  async function ensureRoot(tenantId) {
+    tenantId = normalizeTenantId(tenantId);
+    await fs.mkdir(path.join(rootDir, tenantId), { recursive: true });
+  }
+
+  function resolvePath({ tenantId, evidenceRef }) {
+    tenantId = normalizeTenantId(tenantId);
+    const rel = parseObjEvidenceRef(evidenceRef);
+    return path.join(rootDir, tenantId, rel);
+  }
+
+  async function putEvidence({ tenantId, evidenceRef, data }) {
+    assertNonEmptyString(evidenceRef, "evidenceRef");
+    if (!(data instanceof Uint8Array)) throw new TypeError("data must be a Uint8Array");
+    await ensureRoot(tenantId);
+    const fp = resolvePath({ tenantId, evidenceRef });
+    await fs.mkdir(path.dirname(fp), { recursive: true });
+    await fs.writeFile(fp, data);
+    return { evidenceRef };
+  }
+
+  async function readEvidence({ tenantId, evidenceRef }) {
+    const fp = resolvePath({ tenantId, evidenceRef });
+    const data = await fs.readFile(fp);
+    return { data };
+  }
+
+  async function deleteEvidence({ tenantId, evidenceRef }) {
+    const fp = resolvePath({ tenantId, evidenceRef });
+    try {
+      await fs.unlink(fp);
+      return true;
+    } catch (err) {
+      if (err?.code === "ENOENT") return false;
+      throw err;
+    }
+  }
+
+  return {
+    kind: "fs",
+    rootDir,
+    resolvePath,
+    putEvidence,
+    readEvidence,
+    deleteEvidence
+  };
+}
+
+export function createInMemoryEvidenceStore() {
+  const byTenant = new Map(); // tenantId -> Map<evidenceRef, Uint8Array>
+
+  function getTenantMap(tenantId) {
+    tenantId = normalizeTenantId(tenantId);
+    let m = byTenant.get(tenantId);
+    if (!m) {
+      m = new Map();
+      byTenant.set(tenantId, m);
+    }
+    return m;
+  }
+
+  return {
+    kind: "memory",
+    async putEvidence({ tenantId, evidenceRef, data }) {
+      assertNonEmptyString(evidenceRef, "evidenceRef");
+      if (!(data instanceof Uint8Array)) throw new TypeError("data must be a Uint8Array");
+      const m = getTenantMap(tenantId);
+      m.set(evidenceRef, data);
+      return { evidenceRef };
+    },
+    async readEvidence({ tenantId, evidenceRef }) {
+      assertNonEmptyString(evidenceRef, "evidenceRef");
+      const m = getTenantMap(tenantId);
+      const data = m.get(evidenceRef);
+      if (!data) {
+        const err = new Error("not found");
+        err.code = "ENOENT";
+        throw err;
+      }
+      return { data };
+    },
+    async deleteEvidence({ tenantId, evidenceRef }) {
+      assertNonEmptyString(evidenceRef, "evidenceRef");
+      const m = getTenantMap(tenantId);
+      return m.delete(evidenceRef);
+    }
+  };
+}
+
+export function createS3EvidenceStore({ endpoint, region, bucket, accessKeyId, secretAccessKey, forcePathStyle = true } = {}) {
+  assertNonEmptyString(endpoint, "endpoint");
+  assertNonEmptyString(region, "region");
+  assertNonEmptyString(bucket, "bucket");
+  assertNonEmptyString(accessKeyId, "accessKeyId");
+  assertNonEmptyString(secretAccessKey, "secretAccessKey");
+
+  function keyFor({ tenantId, evidenceRef }) {
+    tenantId = normalizeTenantId(tenantId);
+    const rel = parseObjEvidenceRef(evidenceRef);
+    return `${tenantId}/${rel}`;
+  }
+
+  async function putEvidence({ tenantId, evidenceRef, data }) {
+    assertNonEmptyString(evidenceRef, "evidenceRef");
+    if (!(data instanceof Uint8Array)) throw new TypeError("data must be a Uint8Array");
+    const key = keyFor({ tenantId, evidenceRef });
+    const url = presignS3Url({
+      endpoint,
+      region,
+      bucket,
+      key,
+      method: "PUT",
+      accessKeyId,
+      secretAccessKey,
+      forcePathStyle,
+      expiresInSeconds: 300
+    });
+    const resp = await fetch(url, { method: "PUT", body: data });
+    if (!resp.ok) throw new Error(`S3 put failed (${resp.status})`);
+    return { evidenceRef };
+  }
+
+  async function readEvidence({ tenantId, evidenceRef }) {
+    assertNonEmptyString(evidenceRef, "evidenceRef");
+    const key = keyFor({ tenantId, evidenceRef });
+    const url = presignS3Url({
+      endpoint,
+      region,
+      bucket,
+      key,
+      method: "GET",
+      accessKeyId,
+      secretAccessKey,
+      forcePathStyle,
+      expiresInSeconds: 300
+    });
+    const resp = await fetch(url, { method: "GET" });
+    if (resp.status === 404) {
+      const err = new Error("not found");
+      err.code = "ENOENT";
+      throw err;
+    }
+    if (!resp.ok) throw new Error(`S3 get failed (${resp.status})`);
+    const ab = await resp.arrayBuffer();
+    return { data: new Uint8Array(ab) };
+  }
+
+  async function deleteEvidence({ tenantId, evidenceRef }) {
+    assertNonEmptyString(evidenceRef, "evidenceRef");
+    const key = keyFor({ tenantId, evidenceRef });
+    const url = presignS3Url({
+      endpoint,
+      region,
+      bucket,
+      key,
+      method: "DELETE",
+      accessKeyId,
+      secretAccessKey,
+      forcePathStyle,
+      expiresInSeconds: 300
+    });
+    const resp = await fetch(url, { method: "DELETE" });
+    if (!resp.ok && resp.status !== 404) throw new Error(`S3 delete failed (${resp.status})`);
+    return resp.ok;
+  }
+
+  async function getPresignedDownloadUrl({ tenantId, evidenceRef, expiresInSeconds }) {
+    assertNonEmptyString(evidenceRef, "evidenceRef");
+    if (!Number.isSafeInteger(expiresInSeconds) || expiresInSeconds <= 0) {
+      throw new TypeError("expiresInSeconds must be a positive integer");
+    }
+    const key = keyFor({ tenantId, evidenceRef });
+    return presignS3Url({
+      endpoint,
+      region,
+      bucket,
+      key,
+      method: "GET",
+      accessKeyId,
+      secretAccessKey,
+      forcePathStyle,
+      expiresInSeconds
+    });
+  }
+
+  return {
+    kind: "s3",
+    endpoint,
+    region,
+    bucket,
+    forcePathStyle: Boolean(forcePathStyle),
+    keyFor,
+    putEvidence,
+    readEvidence,
+    deleteEvidence,
+    getPresignedDownloadUrl
+  };
+}

package/src/core/evidence.js

@@ -0,0 +1,119 @@
+import { checkUrlSafetySync } from "./url-safety.js";
+
+export const EVIDENCE_KIND = Object.freeze({
+  VIDEO_CLIP: "VIDEO_CLIP",
+  STILL_IMAGE: "STILL_IMAGE",
+  SENSOR_SNAPSHOT: "SENSOR_SNAPSHOT"
+});
+
+const EVIDENCE_KINDS = new Set(Object.values(EVIDENCE_KIND));
+const REDACTION_STATES = new Set(["NONE", "REQUESTED", "APPLIED"]);
+
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+function assertPlainObject(value, name) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${name} must be an object`);
+  if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+    throw new TypeError(`${name} must be a plain object`);
+  }
+}
+
+function assertSafePositiveInt(value, name) {
+  if (!Number.isSafeInteger(value) || value <= 0) throw new TypeError(`${name} must be a positive safe integer`);
+}
+
+function assertEvidenceRef(ref) {
+  assertNonEmptyString(ref, "payload.evidenceRef");
+  if (ref.length > 2048) throw new TypeError("payload.evidenceRef is too long");
+  if (ref.startsWith("data:")) throw new TypeError("payload.evidenceRef must not be a data: URI");
+  if (ref.includes("base64")) throw new TypeError("payload.evidenceRef must not include base64 data");
+  const safety = checkUrlSafetySync(ref, { allowPrivate: false, allowLoopback: false });
+  if (!safety.ok) {
+    throw new TypeError(`payload.evidenceRef is unsafe (${safety.code})`);
+  }
+}
+
+export function validateEvidenceCapturedPayload(payload) {
+  assertPlainObject(payload, "payload");
+  const allowed = new Set([
+    "jobId",
+    "incidentId",
+    "evidenceId",
+    "evidenceRef",
+    "kind",
+    "durationSeconds",
+    "sizeBytes",
+    "contentType",
+    "redaction"
+  ]);
+  for (const key of Object.keys(payload)) {
+    if (!allowed.has(key)) throw new TypeError(`payload contains unknown field: ${key}`);
+  }
+
+  assertNonEmptyString(payload.jobId, "payload.jobId");
+  assertNonEmptyString(payload.incidentId, "payload.incidentId");
+  assertNonEmptyString(payload.evidenceId, "payload.evidenceId");
+  assertEvidenceRef(payload.evidenceRef);
+  assertNonEmptyString(payload.kind, "payload.kind");
+  if (!EVIDENCE_KINDS.has(payload.kind)) throw new TypeError("payload.kind is not supported");
+
+  if (payload.durationSeconds !== undefined) assertSafePositiveInt(payload.durationSeconds, "payload.durationSeconds");
+  if (payload.sizeBytes !== undefined) assertSafePositiveInt(payload.sizeBytes, "payload.sizeBytes");
+  if (payload.contentType !== undefined) assertNonEmptyString(payload.contentType, "payload.contentType");
+
+  if (payload.redaction !== undefined) {
+    assertPlainObject(payload.redaction, "payload.redaction");
+    const redactionAllowed = new Set(["state", "notes"]);
+    for (const key of Object.keys(payload.redaction)) {
+      if (!redactionAllowed.has(key)) throw new TypeError(`payload.redaction contains unknown field: ${key}`);
+    }
+    assertNonEmptyString(payload.redaction.state, "payload.redaction.state");
+    if (!REDACTION_STATES.has(payload.redaction.state)) throw new TypeError("payload.redaction.state is not supported");
+    if (payload.redaction.notes !== undefined) assertNonEmptyString(payload.redaction.notes, "payload.redaction.notes");
+  }
+
+  return payload;
+}
+
+export function validateEvidenceViewedPayload(payload) {
+  assertPlainObject(payload, "payload");
+  const allowed = new Set(["jobId", "evidenceId", "evidenceRef", "viewedAt"]);
+  for (const key of Object.keys(payload)) {
+    if (!allowed.has(key)) throw new TypeError(`payload contains unknown field: ${key}`);
+  }
+
+  assertNonEmptyString(payload.jobId, "payload.jobId");
+  assertNonEmptyString(payload.evidenceId, "payload.evidenceId");
+  assertEvidenceRef(payload.evidenceRef);
+  assertNonEmptyString(payload.viewedAt, "payload.viewedAt");
+  const t = Date.parse(payload.viewedAt);
+  if (!Number.isFinite(t)) throw new TypeError("payload.viewedAt must be an ISO date string");
+  return payload;
+}
+
+export function validateEvidenceExpiredPayload(payload) {
+  assertPlainObject(payload, "payload");
+  const allowed = new Set(["jobId", "evidenceId", "evidenceRef", "expiredAt", "retentionDays", "policyHash"]);
+  for (const key of Object.keys(payload)) {
+    if (!allowed.has(key)) throw new TypeError(`payload contains unknown field: ${key}`);
+  }
+
+  assertNonEmptyString(payload.jobId, "payload.jobId");
+  assertNonEmptyString(payload.evidenceId, "payload.evidenceId");
+  assertEvidenceRef(payload.evidenceRef);
+  assertNonEmptyString(payload.expiredAt, "payload.expiredAt");
+  const t = Date.parse(payload.expiredAt);
+  if (!Number.isFinite(t)) throw new TypeError("payload.expiredAt must be an ISO date string");
+
+  if (!Number.isSafeInteger(payload.retentionDays) || payload.retentionDays < 0) {
+    throw new TypeError("payload.retentionDays must be a non-negative safe integer");
+  }
+
+  if (payload.policyHash !== undefined && payload.policyHash !== null) {
+    assertNonEmptyString(payload.policyHash, "payload.policyHash");
+  }
+
+  return payload;
+}

package/src/core/failpoints.js

@@ -0,0 +1,30 @@
+function enabled() {
+  if (typeof process === "undefined") return false;
+  if (process.env.NODE_ENV !== "test") return false;
+  if (process.env.PROXY_ENABLE_FAILPOINTS !== "1") return false;
+  return typeof process.env.PROXY_FAILPOINTS === "string" && process.env.PROXY_FAILPOINTS.trim() !== "";
+}
+
+function parseFailpoints(raw) {
+  if (typeof raw !== "string" || raw.trim() === "") return new Set();
+  return new Set(
+    raw
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean)
+  );
+}
+
+const ACTIVE_FAILPOINTS = enabled() ? parseFailpoints(process.env.PROXY_FAILPOINTS) : new Set();
+
+export function failpoint(name) {
+  if (!ACTIVE_FAILPOINTS.size) return;
+  if (typeof name !== "string" || name.trim() === "") throw new TypeError("failpoint name must be a non-empty string");
+  if (!ACTIVE_FAILPOINTS.has(name)) return;
+  process.kill(process.pid, "SIGKILL");
+}
+
+export function listFailpoints() {
+  return Array.from(ACTIVE_FAILPOINTS).sort();
+}
+

package/src/core/finance-account-map.js

@@ -0,0 +1,59 @@
+import { canonicalJsonStringify } from "./canonical-json.js";
+import { sha256Hex } from "./crypto.js";
+
+function isPlainObject(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value) && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null));
+}
+
+export const FINANCE_ACCOUNT_MAP_SCHEMA_VERSION_V1 = "FinanceAccountMap.v1";
+
+export function computeFinanceAccountMapHash(map) {
+  if (!isPlainObject(map)) throw new TypeError("finance account map must be an object");
+  return sha256Hex(canonicalJsonStringify(map));
+}
+
+export function validateFinanceAccountMapV1(map) {
+  if (!isPlainObject(map)) throw new TypeError("finance account map must be an object");
+  if (map.schemaVersion !== FINANCE_ACCOUNT_MAP_SCHEMA_VERSION_V1) {
+    throw new TypeError(`finance account map schemaVersion must be ${FINANCE_ACCOUNT_MAP_SCHEMA_VERSION_V1}`);
+  }
+
+  const accounts = map.accounts ?? null;
+  if (!isPlainObject(accounts)) throw new TypeError("finance account map accounts must be an object");
+  for (const [k, v] of Object.entries(accounts)) {
+    if (typeof k !== "string" || !k.trim()) throw new TypeError("finance account map accounts keys must be non-empty strings");
+    if (typeof v !== "string" || !v.trim()) throw new TypeError(`finance account map accounts.${k} must be a non-empty string`);
+  }
+
+  const exportPolicy = map.exportPolicy ?? null;
+  if (exportPolicy !== null && exportPolicy !== undefined) {
+    if (!isPlainObject(exportPolicy)) throw new TypeError("finance account map exportPolicy must be an object when provided");
+    const gateMode = exportPolicy.gateMode ?? null;
+    if (gateMode !== null && gateMode !== undefined) {
+      const text = String(gateMode);
+      if (text !== "warn" && text !== "strict") throw new TypeError("finance account map exportPolicy.gateMode must be warn or strict");
+    }
+  }
+
+  const dimensions = map.dimensions ?? null;
+  if (dimensions !== null && dimensions !== undefined && !isPlainObject(dimensions)) {
+    throw new TypeError("finance account map dimensions must be an object when provided");
+  }
+
+  return true;
+}
+
+export function resolveExternalAccountFor({ map, accountId }) {
+  if (!isPlainObject(map)) throw new TypeError("map is required");
+  if (typeof accountId !== "string" || !accountId.trim()) throw new TypeError("accountId is required");
+  const accounts = map.accounts ?? null;
+  if (!isPlainObject(accounts)) throw new TypeError("map.accounts must be an object");
+  const external = accounts[accountId] ?? null;
+  if (typeof external !== "string" || !external.trim()) {
+    const err = new Error(`missing account mapping for ${accountId}`);
+    err.code = "FINANCE_ACCOUNT_MAP_MISSING";
+    err.accountId = accountId;
+    throw err;
+  }
+  return String(external);
+}