Sintesi esecutiva
| Preoccupazione principale | I dati di lavoro protetti e la compatibilità storica non potevano essere accettati per assunzione. Dovevamo provare i confini attuali, migrare la deriva sicura e mantenere guardrail dove i dati reali richiedono ancora compatibilità. |
| Bug principali trovati | Un calcolo biweekly dei periodi paga sensibile al DST poteva non avanzare correttamente; percorsi di compatibilità obsoleti tenevano vivi concetti vecchi; gli indici Redis avevano drift; e alcuni finding di sicurezza dovevano essere chiusi. |
| Correzioni principali | Le letture di lavoro protetto passano ora da un gate di accesso canonico; shims e alias obsoleti sono stati rimossi; la deriva Redis è stata riparata; sono stati aggiunti audit crypto/plaintext; la navigazione DST dei periodi paga è stata corretta; i finding di sicurezza sono stati chiusi; e i controlli settings sono stati ricostruiti con test. |
| Verifica | La suite PHPUnit privata completa è passata con 2.318 test e 19.222 assertion. Il quick gate pubblico è passato con 1.311 test e 7.698 assertion. I gate PHPStan livello 9 privati e pubblici erano puliti. |
Perché abbiamo indagato
The work began with the protected business work-data lifecycle: identity, membership, consent, access, encrypted envelope state, exports, revocation, caching, and audit evidence all had to line up. The investigation widened because old compatibility paths, route shims, skipped tests, and Redis migration artifacts made it harder to prove the current product model.
The rule was simple: old compatibility should either be proven necessary and guarded, or proven unused and removed. For sensitive work data, assumptions were not enough.
Bug DST dei periodi paga
One real product bug found during the cleanup was in biweekly pay-period navigation. The old calculation converted timestamp seconds into days by dividing by 86400. Across a spring daylight-saving transition, that can miscount calendar days and cause the next period to resolve incorrectly.
- Fixed
PayPeriods::biweeklyStart()to use calendar-day differences instead of timestamp seconds divided by 86,400. - Added
PayPeriodsTest::testBiweeklyNavigationAdvancesAcrossSpringDstBoundary, which verifies America/Edmonton navigation from 2024-02-26 to 2024-03-11 and then 2024-03-25. - Re-enabled
EarningsCalendarParityIntegrationTest::testRenderSectionsLazyDoesNotFatalWhenEncryptedWorkRowOmitsGross, which had exposed the period-navigation stall. - Kept
PayPeriodGeneratorTestin the remediation verification set so adjacent generation behavior remains covered.
Dati di lavoro protetti
- Added and enforced
BusinessProtectedDataAccessfor actor authority, target membership, consent, wrap state, envelope metadata, and business site visibility. - Routed member reports, financial summaries, workspace warmers, team earnings, daily member JSON, and member XLSX/PDF exports through the protected gate.
- Locked generic PDF/XLSX endpoints to personal current-user payloads and added negative tests for forged business/member payloads.
- Moved protected business XLSX/PDF export to server-side rebuilds from authorized rows.
- Expanded audit events for requested, denied, started, completed, and failed protected read/export outcomes.
- Added revocation tests proving stale reports, exports, summaries, team earnings, and caches are denied or purged after access changes.
Alias, percorsi, redirect, metodi e classi
- Removed
/earnings/compatibility route and smoke references; personal earnings and reports use/reports/. - Removed
/profile/compatibility route and profile-page references; account profile settings now live under settings/account. - Removed
/js/businesses/asset shim after canonical asset references were verified. - Removed settings legacy hash redirect map, JSON payload, and browser redirect logic.
- Removed
/blog/article/?slug=...redirect entrypoint from active routing and accessibility inventory references. - Replaced
/api/v1/profile/update/andprofile/settingsroute declarations with account-scoped profile routes. - Removed unused
BusinessDiscoverymethod aliases,ShadowTalon::init(), old Settings account route aliases, and an internalEmailVerificationrate-limit wrapper. - Removed runtime bare
work.writeorganization mutation compatibility; runtime grants now require explicit self/org scope or manager authority. - Removed generated
TODO: Document...comments and unusedFPDF.phpplaceholder class so source scans and inventories reflect active work.
Redis e deriva dei dati
- Created a Redis checkpoint before mutation:
paycal-redis-20260619-091729.rdb, SHA-256baff0c94361b57ef67a153b242669c537165a9b576a1cfb4953b10e95fa41215. - Migrated old relationship/metaphor Redis keys and values: 4,288 key migrations and 599 value updates, with 0 conflicts and 0 errors.
- Repaired connection index drift across 1,698 connections and 1,447 businesses. The fixer repaired 378 drifted records and verified post-run drift at 0.
- Extended
scripts/connections-audit.phpso report-only mode identifies barework.writedrift and--fixmigrates records to explicitwork.scope.self. - Replaced the stale SQL-era Redis field migration helper with a Redis-native dry-run/execute/verify flow for
text_sizing -> textanddensity -> spacing. - Removed absent compatibility paths for no-colon email index keys,
theme_mode, and legacy fixed-TTL lock-boundary keys after audit verification. - Marked 98 seeded
@paycal.appfake personas so plaintext work-entry audits can ignore them by default while still reporting them with--include-ignored.
Work entry crypto e plaintext
- Added
CryptoCompatibilityTelemetryfor unwrap source selection and outcomes. - Added
scripts/paycal crypto:compat:audit --jsonto report wrapper and fallback usage. - Added
scripts/paycal work:plaintext:audit --jsonto report plaintext-only rows, invalid encrypted blobs, fake-user rows, and rows requiring user-session rewrite. - Retired the old plaintext migration execution path so it cannot strip intentional work-entry snapshot fields.
- Backfilled earnings snapshot fields across 64,447 work entries, including 859 missing gross values, and verified final missing gross and wage counts at 0.
- Kept plaintext/non-encrypted read compatibility because real-user rows still require user-session encrypted rewrite.
- Kept work-entry short-alias read compatibility because encrypted blobs and fixtures can still contain historical alias-shaped payloads, even though active Redis hash fields showed zero short aliases.
Finding di sicurezza chiusi
- Active request-IP call paths now use trusted-proxy-aware client IP resolution.
- Invite code and audit-chain hash comparisons use constant-time comparison.
- CORS validation evaluates request origins against an explicit allowlist.
- The development security-disable flag is ignored outside approved dev-like environments.
- Rate-limit IP key derivation uses SHA-256 instead of MD5.
- The admin test runner returns summarized output by default instead of raw PHPUnit details.
Remediation di impostazioni e aspetto
- Added a persisted sidebar Trigger preference with a 400 ms default, 200 ms minimum, 3,000 ms maximum, and 200 ms step size.
- Cancelled delayed sidebar timers on pointer exit, document leave, and window blur.
- Grouped sidebar navigation into Personal, Business, and bottom Utility actions, with Settings, Help, and Sign Out anchored together.
- Replaced the Accent dropdown with 16 spectrum swatches, hover popovers, shared accent tokens, and a live preview window.
- Renamed Accent color to Accent, Density preset to Density, and Variant to Mode.
- Rebuilt notification position selection as a spatial grid using canonical top/bottom values.
- Fixed settings nav hover, active, and focus states after a global link hover rule produced a poor white hover block in the dark settings header.
Guardrail per il futuro
- Protected business work rows must originate from the canonical protected access gate before any report, export, cache, warmer, or audit path can use them.
- Old compatibility paths must be classified as required, migrated, or removed. PayCal will not keep old behavior alive only because it is convenient.
- Data migrations require report-only audit, checkpoint, fix, report-only verification, and regression tests.
- Compatibility that protects real user data stays until telemetry and audits prove removal is safe.
- Pay-period and earnings code must use calendar-aware date math across timezone and DST boundaries.
- Skipped tests must have a clear environment reason; deterministic product regressions should run in the normal gate.
- Settings controls must be visibly connected to the preference they configure, bounded by persisted defaults, and protected by rendered-contract tests.