Configuration releases

Configuration releases turn tenant setup into a reviewable artifact. The signed package covers tenant policy, applicant branding, current verification workflows, Country Assurance Pack definitions, provider metadata and exact workflow-to-BPMN bindings.

The release plane requires an administrator or compliance operator session. Tenant API keys cannot export or promote configuration.

Safety contract

Control	Behaviour
Integrity	Every package is canonicalized, SHA-256 hashed and signed with Ed25519. Stored packages are verified again before validation or promotion.
Secrets	Password, token, API-key, private-key and credential fields are rejected. Provider credentials remain in the target environment's secret store.
Tenant boundary	A signed package can only be imported by the tenant named in its payload.
Sandbox	One administrator or compliance approval applies the release.
Live	Two distinct administrator/compliance users must approve. The requester cannot approve their own promotion.
Country assurance	Imported Country Assurance Packs are created as drafts. Legal, data-licence and evidence approval must occur separately.
Rollback	Rollback is another two-person release. History is never overwritten or deleted.

1. Export the current baseline

POST /v1/configuration/packages/export
Authorization: Bearer <operator-session>
Idempotency-Key: 6575853b-3746-4a04-b8a4-1f61387d533f
Content-Type: application/json

{}

The response is a portable envelope:

{
  "package": {
    "payload": {
      "schema": "proofline.configuration.v1",
      "packageId": "cfg_…",
      "tenantId": "ten_…",
      "sourceEnvironment": "sandbox",
      "exportedAt": "2026-07-22T12:00:00.000Z",
      "configuration": {
        "settings": {},
        "branding": {},
        "workflows": [],
        "countryPacks": [],
        "providers": [],
        "processBindings": []
      }
    },
    "payloadSha256": "…",
    "signatureAlgorithm": "Ed25519",
    "signatureBase64": "…",
    "publicKeyBase64": "…",
    "keyId": "ed25519:…"
  }
}

Commit the editable source to a protected repository, not the signed envelope. An editable source contains only sourceEnvironment and configuration.

2. Validate and seal edited source

import { Assayra } from "@assayra/sdk-web";
import source from "./proofline.configuration.json" with { type: "json" };

const assayra = new Assayra({
  baseUrl: process.env.ASSAYRA_BASE_URL!,
  token: process.env.ASSAYRA_OPERATOR_SESSION!,
});

const sealed = await assayra.configuration.seal(source);
console.log(sealed.package.payload.packageId, sealed.package.payloadSha256);

POST /v1/configuration/packages validates the complete typed source, confirms required commercial modules and orchestration dependencies, rejects secret-bearing fields and signs the result. A sealed package is immutable; create another package for further changes.

3. Inspect the target diff

const candidate = sealed.package.payload.packageId;
const review = await assayra.configuration.validate(candidate, "live");

if (!review.validation.valid) {
  console.table(review.validation.errors);
  throw new Error("Configuration is not eligible for live promotion");
}

for (const change of review.diff) {
  console.log(change.path, change.before, change.after);
}

Diff entries use stable JSON paths such as configuration.branding.productName. Validation is repeated immediately before the second approval, so stale prerequisites fail closed.

4. Request and approve live promotion

const requested = await assayra.configuration.promote(candidate, "live");
console.log(requested.promotion.status); // pending

A different logged-in administrator or compliance officer completes the release:

await checker.configuration.approve(requested.promotion.id);

The database transaction applies tenant settings and branding, creates immutable successor workflow versions, preserves applications pinned to older versions, creates changed Country Assurance Packs as drafts, updates only non-secret provider metadata and resolves process bindings to their exact deployed BPMN definition.

5. Roll back safely

const rollback = await checker.configuration.rollback(requested.promotion.id);
// A different approver completes the rollback.
await administrator.configuration.approve(rollback.promotion.id);

Rollback re-applies the captured prior configuration as a new governed release. It does not delete the failed release, erase approvals or rewrite application evidence.

Import a signed package

Use import when moving an Assayra-signed envelope between isolated deployments that share the same tenant identity and trusted release authority:

const imported = await assayra.configuration.import(envelope);
if (!imported.verification.valid) throw new Error("Package did not verify");

An altered hash, signature, signing key or tenant ID is rejected before the package enters the release ledger.

Error codes

Code	Meaning
configuration_contains_secret	A prohibited secret-bearing field or URL parameter was found.
configuration_signature_invalid	Imported payload hash or Ed25519 signature failed.
configuration_package_integrity_failed	A stored package no longer verifies against the active release authority.
configuration_validation_failed	Workflow, entitlement, process or live-policy validation failed.
configuration_distinct_approver_required	The requester attempted to provide the second approval.
configuration_not_rollbackable	The release is not applied, was already rolled back or already has a pending rollback.