fix(form-builder): canonicalize JSON for byte-stable storage (WS-6)

MySQL 8.0 JSON columns may reorder associative-array keys on
round-trip. For audit-immutable values (schema snapshots, webhook
payloads, activity log diffs), this is corrupting: re-emits produce
different byte sequences for the same logical content.

Introduced JsonCanonicalizer (recursive ksort on associative arrays;
numeric-indexed lists preserve order) and applied at every writer
site that produces byte-stable JSON:

- FormSubmissionService: canonicalize the schema_snapshot array
  before storage (audit-immutable per ARCH §4.3, RFC-WS-6 v1.1).
- FormField::logFieldChange / FormSchema::logSchemaChange: canonicalize
  activity-log properties before withProperties() so old/new diffs
  read back byte-stable.
- BindingActivityLogger: canonicalize both the pass-level and
  per-binding activity properties.
- FormWebhookDispatcher: canonicalize payload_snapshot before
  storage (delivery-time HMAC re-encodes the same canonical bytes).
- DeliverFormWebhookJob: switched json_encode to
  JsonCanonicalizer::encode for the HMAC-signed body, so the
  signature is byte-stable across re-deliveries and reproducible by
  receivers from the same logical payload.

Sites NOT canonicalized (deliberate):
- form_schemas.settings — opaque UI config; key order has no
  semantic meaning, no byte-stability requirement.
- form_schemas.translations / form_fields.translations — read by
  display layer; key order doesn't matter.
- form_templates.schema_snapshot — user-supplied input via store/
  update; user is the source of truth, not audit-immutable in the
  same way as form_submissions.schema_snapshot.

Reverted the 7 assertEquals workarounds from session 2.6:
- ConditionalLogicActivityLogPayloadTest
- ConditionalLogicBackfillTest::test_rollback_reconstructs_canonical_json
- FormFieldBindingMigrationTest::test_rollback_reconstructs_json_and_drops_table
- FormFieldOptionServiceAndScopeTest::test_replace_options_emits_activity_log_on_field_only
- FormFieldOptionsActivityLogTest::test_field_updated_payload_contains_options_diff_when_options_change
- FormFieldOptionsBackfillTest::test_forward_migration_backfills_rows_strips_translations_and_rewrites_snapshot
- FormFieldOptionsSnapshotAndStrictRequestTest::test_submission_snapshot_embeds_rich_shape_options

Each now uses assertSame on JsonCanonicalizer::encode of both sides —
byte-stable comparison meaningful regardless of MySQL JSON storage
behavior.

New regression test SchemaSnapshotByteStableAcrossReemitsTest
exercises the contract end-to-end: complex schema with bindings,
validation rules, options, conditional logic, submitted; reads
schema_snapshot via three roads (Eloquent cast, fresh model, raw
bytes) and asserts the canonical encode is identical.

ARCH-FORM-BUILDER.md §4.6.1 gets a "Byte-stability" sub-section
explaining what's canonicalized and why.

Test count: 1388 → 1400 (+11 JsonCanonicalizer unit, +1 snapshot
regression). Larastan clean. Rector dry-run unchanged at 355.

Refs: WS-6 session 2.6 deviation #4 cleanup, RFC-WS-6 v1.1

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-04-28 13:51:38 +02:00
parent 0afbd36bf7
commit a791a276fa
17 changed files with 488 additions and 82 deletions

View File

@@ -19,9 +19,9 @@ use App\Models\FormBuilder\FormSubmission;
use App\Models\FormBuilder\FormSubmissionDelegation;
use App\Models\FormBuilder\FormValue;
use App\Models\User;
use App\Support\Json\JsonCanonicalizer;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Str;
/**
* Submission lifecycle: draft submitted reviewed per ARCH §4.3, §15.
@@ -103,7 +103,7 @@ final class FormSubmissionService
{
$this->assertWritable($submission);
$result = DB::transaction(function () use ($submission, $actor): FormSubmission {
$result = DB::transaction(function () use ($submission): FormSubmission {
$schema = $submission->schema;
$submission->status = FormSubmissionStatus::SUBMITTED->value;
@@ -111,7 +111,12 @@ final class FormSubmissionService
$submission->schema_version_at_submit = $schema->version;
if ($schema->snapshot_mode !== FormSchemaSnapshotMode::NEVER) {
$submission->schema_snapshot = $this->buildSnapshot($schema);
// RFC-WS-6 session 2.7: schema_snapshot is audit-immutable;
// canonicalize before storage so MySQL JSON-column round-trip
// can never corrupt audit-replay diffs or webhook signing.
$submission->schema_snapshot = JsonCanonicalizer::canonicalize(
$this->buildSnapshot($schema),
);
}
if ($submission->opened_at !== null) {
@@ -272,7 +277,6 @@ final class FormSubmissionService
* any residual options key defensively (commit 2 backfill should
* already have done so on existing rows).
*
* @param mixed $translations
* @return array<string, mixed>|null
*/
private function stripOptionsFromTranslations(mixed $translations): ?array

View File

@@ -9,6 +9,7 @@ use App\Jobs\FormBuilder\DeliverFormWebhookJob;
use App\Models\FormBuilder\FormSchemaWebhook;
use App\Models\FormBuilder\FormSubmission;
use App\Models\FormBuilder\FormWebhookDelivery;
use App\Support\Json\JsonCanonicalizer;
/**
* Finds active webhooks for a submission's schema + trigger and queues a
@@ -36,7 +37,12 @@ final class FormWebhookDispatcher
'trigger_event' => $triggerEvent,
'status' => FormWebhookDeliveryStatus::PENDING->value,
'attempts' => 0,
'payload_snapshot' => $this->buildPayload($submission, $triggerEvent),
// RFC-WS-6 session 2.7 — canonicalize before storage; the
// delivery job HMAC-signs the same canonical bytes after
// re-encode, so signature is reproducible.
'payload_snapshot' => JsonCanonicalizer::canonicalize(
$this->buildPayload($submission, $triggerEvent),
),
]);
DeliverFormWebhookJob::dispatch($delivery->id)->onConnection('webhooks')->onQueue('webhooks');