Brain Laravel Package

Technical Evaluation

Architecture fit

• This is a security-hardening release for a Laravel workflow package (brain), not a feature release. Its primary value is closing #[Sensitive] redaction leaks, which previously exposed declared sensitive values through: earlier/skipped/cancelled workflow events, validation errors, nested workflow boundaries, exception messages in failure events, brain:run console output, previews/result tables/run history, and VarDumper dumps.
• The new model is materially better aligned with typical enterprise expectations: redaction keys now apply workflow-wide rather than per-action, and nested workflows inherit their parent's keys. That is the correct semantic for a PII/credential boundary.
• A second architectural change is queued-payload encryption: #[Sensitive] values are now encrypted with APP_KEY at queue time. This moves the package from "redacted at the edges" to "protected at rest in the queue," which is a meaningful defense-in-depth improvement but introduces a new hard dependency on key management.
• Internal quality signals are strong: Workflow/Process/brain:show split into smaller methods, pre-commit gates on cyclomatic complexity (max 10) and CRAP (max 30), and 100% test coverage required. For a package handling sensitive data, enforced quality gates reduce long-term maintenance risk.

Integration feasibility

• Low integration effort for a version bump: the release is additive for consumers. Jobs queued before 4.1.4 still run, and SensitiveValue payloads queued before encryption remain readable, so there is no queue-drain requirement before upgrading.
• The only mandatory operational step is key management: if APP_KEY is rotated after upgrading, the old key must remain in APP_PREVIOUS_KEYS until all jobs queued under it are processed. Teams that rotate keys on a schedule, or that share a single APP_KEY across services, need to confirm their rotation runbook supports this.
• Documentation coverage is adequate for onboarding: #[Sensitive] behavior, #[OnQueue], and brain:migrate are documented in the README, docs site, and Boost guidelines.
• Residual unknowns: no evidence in the notes of a formal security advisory (CVE/GHSA), no stated upgrade-path caveats beyond the key note, and no explicit statement of whether pre-4.1.4 versions should be treated as compromised for teams that stored sensitive values in logs.

Technical risk

• Highest risk is retrospective exposure, not upgrade risk. If prior versions leaked sensitive values into logs, failure events, or run history, those artifacts may still exist in log aggregators, exception trackers (Sentry/Bugsnag), and brain:run history. Upgrading stops new leaks but does not remediate existing ones. This requires a separate log-hygiene review and possible purge/rotation of any credentials that were exposed.
• Key-rotation coupling is a new failure mode. A rotated APP_KEY without APP_PREVIOUS_KEYS populated will render queued sensitive payloads undecryptable, and jobs will fail at processing time — potentially after a delay, and potentially in a batch. This is a self-inflicted outage vector for teams with automated rotation.
• Behavioral change in redaction scope. Redaction previously keyed per action; now a key declared by any action applies workflow-wide. This is stricter and safer, but it can change what appears in existing dashboards, run histories, and support workflows. Anyone who relied on seeing a value in a non-sensitive action's output will lose that visibility.
• rules() now validates real values. Validation semantics change: rules are applied to the decrypted value rather than a redacted placeholder. This is correct, but it may surface previously-passing payloads as failing, and it changes the shape of validation errors.
• Inheritance and dot notation (#[Sensitive] inherited from parent classes, user.password) broaden coverage; the risk here is over-redaction of fields teams expected to inspect, not under-redaction.
• Framework currency risk is low but real: the test suite was fixed for Laravel 13.34, Rector 2.6.7, and Testbench 11.5, implying the package tracks recent framework/tooling versions. Confirm your pinned Laravel version is inside the tested matrix.

Key questions

1. Do we have a written definition of what data our workflows mark #[Sensitive], and does the new workflow-wide scoping over-redact anything our support or on-call teams depend on?
2. What sensitive data has already been written to logs, exception trackers, or brain:run history by pre-4.1.4 versions, and what is our remediation plan (purge, credential rotation, retention policy change)?
3. Does our APP_KEY rotation policy include APP_PREVIOUS_KEYS, and how long do we retain old keys relative to our maximum queue latency?
4. Is there a published security advisory for the redaction leaks, and if so, what is the vendor's recommended action for consumers of prior versions?
5. Who owns the #[Sensitive] annotation review as a recurring control, so that new workflow actions are annotated at authoring time rather than after a leak?
6. Do any workflows rely on validation behavior that changes now that rules() sees real values?
7. What is our rollback story if the upgrade surfaces over-redaction or decryption failures in production — can we revert without losing queued encrypted payloads?

Integration Approach

Stack fit

• Fits cleanly into an existing Laravel service already using brain: no new infrastructure, no new service dependency. The encryption path uses APP_KEY, which the application already manages, so there is no new secret store to stand up.
• Queue-worker topology is unchanged. Encryption happens at enqueue time and decryption at processing time, entirely inside the existing job lifecycle.
• Teams not currently using #[Sensitive] get little immediate benefit but also no cost; teams using it get substantial benefit. Gauge value by counting #[Sensitive] declarations in the codebase.

Migration path

• Treat as a drop-in patch upgrade (4.1.3 → 4.1.4): no code changes required, backward compatible for in-flight jobs and pre-encryption payloads.
• Do the key-management prerequisite before deploying: verify APP_PREVIOUS_KEYS is wired into the runtime config and document the retention window. If APP_PREVIOUS_KEYS is not currently configured, add it in the same change set as the version bump.
• Follow with an annotation audit: confirm #[Sensitive] is applied at the level where inheritance and dot notation actually cover the fields you intend (user.password rather than a broad user), and verify nested workflows inherit as expected.

Compatibility

• Backward compatible in both directions of concern: pre-4.1.4 queued jobs still execute, and pre-encryption SensitiveValue payloads remain readable. No queue drain required.
• Forward-compatibility caveat: once jobs are queued encrypted, rollback to a pre-4.1.4 version may not be able to read them. Confirm the rollback window against the deploy sequence before shipping.
• Tooling compatibility is asserted for Laravel 13.34, Rector 2.6.7, and Testbench 11.5. Verify against the versions actually pinned in composer.json and CI.

Sequencing

1. Pre-work: configure APP_PREVIOUS_KEYS and confirm the key-retention policy; inventory #[Sensitive] usage across workflows.
2. Exposure review: scan log aggregators, error trackers, and brain:run history for sensitive values emitted by earlier versions; scope remediation.
3. Upgrade in a non-production environment: run the existing workflow test suite, plus a targeted test that queues a #[Sensitive] payload, rotates the key, and processes the job with the old key present.
4. Production deploy: low-risk window, but stage the queue workers after the web/app tier so that new encrypted payloads are only produced once consumers can read them.
5. Post-deploy validation: confirm redaction in earlier/skipped/cancelled events, validation errors, failure-event exception messages, nested workflows, and brain:run console output. Check that rules() validation still passes on real values.
6. Remediate exposure: purge or rotate anything identified in step 2.
7. Codify: add a CI/lint check or PR template prompt for #[Sensitive] on new workflow action inputs, so coverage does not regress.

Operational Impact

Maintenance

• Low steady-state maintenance: enforced complexity and CRAP ceilings plus a 100% coverage requirement mean the codebase should stay tractable and refactors remain safe. This is a favorable signal versus packages with no quality gates.
• New recurring maintenance obligation: APP_PREVIOUS_KEYS must be curated. Old keys should be removed only after the longest possible queue latency plus retry/backoff has elapsed. This is a small but permanent runbook entry.
• Annotation hygiene is now a maintenance surface: #[Sensitive] must be maintained as workflows evolve, and inheritance/dot-notation rules must be understood by whoever edits workflow definitions.

Support

• Support and on-call visibility will change. Redaction now covers more of the workflow lifecycle and brain:run masks values in previews, result tables, and run history. Expect some "I can't see the value anymore" tickets in the first weeks; set expectations before deploy.
• Sensitive prompts in brain:run now use hidden input, which changes interactive operator behavior — worth a short internal note for anyone who runs commands manually in production.
• Decryption failures will present as job failures with redacted exception messages. Support staff will have less diagnostic detail by design, so teams should establish a non-sensitive correlation ID (workflow ID, job ID) as the standard troubleshooting handle.
• No vendor support relationship is described; support is community/open-source. Escalation depends on the maintainer and issue tracker responsiveness.

Scaling

• Encryption/decryption cost per queued sensitive payload is negligible relative to typical job work, and it occurs at enqueue/dequeue boundaries rather than in hot request paths.
• Payload size grows modestly for encrypted fields; only relevant if you queue very large sensitive blobs or approach queue message-size limits (e.g., SQS 256 KB). Audit any workflow that puts large documents under #[Sensitive].
• No change to worker concurrency, throughput, or horizontal scaling characteristics.
• Workflow-wide redaction scoping has a minor performance implication (more fields processed per event) that is very unlikely to be material.

Failure modes

• Key rotation without APP_PREVIOUS_KEYS: queued sensitive values become undecryptable; jobs fail at processing time, possibly hours after enqueue and potentially across a whole batch. Highest-severity new failure mode.
• Rollback after encrypted jobs are queued: older versions may not read encrypted payloads. Define the rollback boundary explicitly.
• Over-redaction of operational data: on-call loses access to a field they previously relied on for diagnosis, extending incident resolution time. Mitigate with correlation IDs and clear logging guidance.
• Validation behavior change: rules() now sees real values, so previously-tolerated payloads may begin failing validation; failures are redacted, so diagnosis requires the workflow/job ID.
• Residual exposure from prior versions: logs and error trackers written before the upgrade remain a standing data-handling issue until purged. This is a failure mode that no upgrade fixes by itself.
• Under-annotation: the guarantees only apply to fields actually declared sensitive. A missed annotation is silent and persists until a leak is discovered — the internal quality gates do not cover application-level annotation correctness.

Ramp-up

• For a team already using the package: low. The release is a patch upgrade requiring one config prerequisite (APP_PREVIOUS_KEYS) and one documentation pass; estimate one to two days for a small team including the exposure review, and add time if log remediation is in scope.
• For a team new to the package: moderate. The learning surface is the #[Sensitive] model (workflow-wide scoping, inheritance, dot notation), #[OnQueue] behavior, and brain:migrate. The newly expanded README, docs site, and Boost guidelines materially reduce this — onboarding a new engineer to authoring workflows is now realistic in a few days, though truly safe usage still requires the team to agree on what counts as sensitive.
• The highest-value ramp-up investment is not the package API but a short internal standard: which fields are always #[Sensitive], how APP_PREVIOUS_KEYS is managed, and how to troubleshoot redacted failures via correlation IDs. That document is roughly a half-day of effort and prevents the most likely operational failures.