lib.data-exchange-server

@lssm-tech/lib.data-exchange-server

Website: https://contractspec.io

Server-side adapters, execution services, and workflow templates for SchemaModel-first data interchange.

What It Provides

• File, HTTP, SQL, and storage adapter families.
• SQL adapters that preserve portable database endpoint metadata while delegating execution to injected clients/provider boundaries.
• Dry-run, validation, preview, execute, retry, and audit services.
• WorkflowSpec templates for interchange orchestration.
• A fail-closed governed projection gateway, revocation reconciliation, and privacy-status projection for ecosystem data sharing.
• A host-injected SecretProvider envelope sealer that canonicalizes the exact authorization as AES-256-GCM AAD and returns ciphertext-only product envelopes.
• A bounded HTTPS materialization port that delivers one encrypted dispatch to an exact product ingress without ambient credentials or redirect following.

Usage

Import the root entrypoint from @lssm-tech/lib.data-exchange-server, or use ./adapters, ./governed, ./services, and ./workflow.

Template-Aware Imports

Server dry-runs and executions accept the same import templates as core. This lets users upload partner-specific CSV/JSON/XML layouts while the server previews normalized records before writing them.

import { defineDataExchangeTemplate } from "@lssm-tech/lib.data-exchange-core";
import { dryRunImport, executeImport } from "@lssm-tech/lib.data-exchange-server";

const template = defineDataExchangeTemplate({
	key: "invoices.import",
	version: "1.0.0",
	columns: [
		{
			key: "id",
			label: "Invoice ID",
			targetField: "id",
			required: true,
			sourceAliases: ["Invoice Number", "No facture"],
		},
		{
			key: "amount",
			label: "Amount",
			targetField: "amount",
			format: {
				kind: "number",
				decimalSeparator: ",",
				thousandsSeparator: ".",
			},
		},
	],
});

const preview = await dryRunImport({
	source: {
		kind: "file",
		path: "partner.csv",
		format: "csv",
		codecOptions: { csv: { delimiter: ";", skipRows: 1 } },
	},
	target: { kind: "memory", format: "json" },
	schema: InvoiceImportSchema,
	template,
});

if (preview.issues.every((issue) => issue.severity !== "error")) {
	await executeImport({
		source: {
			kind: "file",
			path: "partner.csv",
			format: "csv",
			codecOptions: { csv: { delimiter: ";", skipRows: 1 } },
		},
		target: { kind: "memory", format: "json" },
		schema: InvoiceImportSchema,
		template,
	});
}

Execution audit entries record whether mappings came from explicit mappings, template resolution, or inference.

Governed projection gateway

@lssm-tech/lib.data-exchange-server/governed evaluates catalog, grant, subject, tenant, audience, purpose, field, time, residency, revision, and revocation-watermark authority before calling the injected source port. A denial is recorded without a payload or field disclosure; an allowed response returns only the exact requested field allowlist.

Revocation reconciliation suspends a share when a required consumer is missing, stale, or reports a failed acknowledgement. Hosts own durable stores, encryption, transport, deletion/export jobs, and operator workflows. The package never assumes that products share a database or that a managed runtime owns customer keys.

The delivery worker accepts provider-neutral consumer and rights-processor ports. Only an explicit applied/complete result advances a terminal success; exceptions are indeterminate and fail closed. Missing bindings are retryable, attempts are leased and bounded, and expired leases can be reclaimed without claiming that an unknown downstream side effect succeeded.

createSecretProviderGovernedEnvelopeSealer resolves a product-owned key reference through an injected binding and SecretProvider. It accepts only a 32-byte AES-256 key, requires payload fields to equal the authorized field allowlist, uses canonical authorization bytes as AAD, appends the GCM tag to the encoded ciphertext, hashes the randomized ciphertext rather than low-entropy plaintext, requires an exact configured key version when one is pinned, and rejects oversized payloads before encryption. It clears its local key copy after sealing. Provider errors are replaced with a redacted failure. The sealer never owns, rotates, serializes, or logs key material.

createGovernedRecoveryIngress is the product-side HTTP trust boundary. It requires a strong server-only bearer, exact application binding, matching idempotency header, bounded strict dispatch body, and schema-valid product evidence. Authentication or binding failures never invoke the product port; product exceptions become a generic 503 without leaking diagnostics.

createGovernedMaterializationIngressRegistry is the independent encrypted-copy boundary. It selects one ingress from the exact source application path and a distinct 32-character-or-longer source-to-receiver bearer. The strict dispatch must match receiver application and region, exact purpose, lawful-basis and consent evidence, fields, grant/revision/watermark, expiry and retention, receiver encryption algorithm/key reference, and idempotency key. Unknown sources, stale authority, plaintext, source subjects, central identity, and forged receipts fail before persistence. Hosts may bind recovery without materialization; materialization requires both an explicit receiver region and at least one source binding.

createGovernedMaterializationHttpPort is the matching source-side transport. It accepts one exact HTTPS origin, source application, strong server-only bearer, and optional injected fetch implementation. Requests carry the delivery ID as their idempotency key, omit ambient credentials, refuse redirects, and use a bounded timeout. Only a 200 application/json receipt under 64 KiB is parsed; the receipt must bind the exact delivery, materialization, and consumer. Network, status, media-type, body-size, parsing, and receipt failures collapse to one redacted unavailable error. The port never decrypts or logs product data.

createGovernedRecoveryHttpPort applies the same exact-origin, strong-bearer, idempotency, no-credentials, no-redirect, bounded-timeout, JSON media-type, and streaming response limits to projection revocation and privacy-rights work. It removes worker lease metadata before transport, rejects application substitution before network I/O, returns a bounded retry result for an explicit downstream status, and collapses network or invalid-receipt outcomes to one redacted error.