Evidence — Referensi Mendalam

Sekilas

Halaman ini adalah referensi mendalam untuk modul NextPDF\Enterprise\Evidence. Modul ini menyegel temuan validasi ke dalam EvidencePackage yang immutable, mengekspornya sebagai JSON deterministik dengan digest SHA-256 yang stabil, mempersistensikannya melalui kontrak store yang dapat dipasang, dan melacak regresi antar-run dengan ContinuousMonitor. Modul ini mengonsumsi temuan yang dihasilkan oleh permukaan Validation dan Compliance; ia tidak melakukan pemeriksaan konformansi apa pun sendiri. Untuk panduan alur kerja, baca halaman kapabilitas Evidence terlebih dahulu.

Ketersediaan & lisensi

Kapabilitas ini hadir dalam NextPDF Enterprise (nextpdf/enterprise) dan diaktifkan dengan envelope lisensi tingkat Enterprise. Deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Permukaan ini dilisensikan oleh kapabilitas enterprise.compliance.evidence; entitlement yang ditolak menolak fitur ini. Core dan Pro menghasilkan temuan dan laporan; menyegel temuan ke dalam paket yang immutable, deterministik, dan opsional ber-timestamp dengan pelacakan regresi tidak memiliki padanan pada tingkat Core maupun Pro.

Permukaan API publik

composer require nextpdf/enterprise:^3

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
EvidencePortal::__construct	EvidenceStoreInterface $store, EvidenceExporter $exporter	Merangkai store dan exporter	EvidencePortal	Tidak ada yang dideklarasikan	Kedua kolaborator dapat diinjeksikan
EvidencePortal::generateEvidence	string $documentHash, list<EvidenceRecord> $records, ?string $tsaTimestamp = null	Menghitung pass/fail, menyegel paket dengan id UUID baru dan generatedAt waktu dinding, mempersistensikannya	EvidencePackage	Tidak ada yang dideklarasikan	Mempersistensi melalui store(), bukan persistImmutable()
EvidencePortal::getEvidence	string $documentHash	Paket tersimpan terbaru untuk hash tersebut	?EvidencePackage	Tidak ada yang dideklarasikan	null ketika tidak ada yang tersimpan
EvidencePortal::getHistory	string $documentHash	Riwayat lengkap, terbaru dahulu	list<EvidencePackage>	Tidak ada yang dideklarasikan	Pengurutan disediakan oleh store
EvidencePortal::exportAsJson	EvidencePackage $package	Mendelegasikan ke exporter	non-empty-string	JsonException	Byte yang sama dengan EvidenceExporter::toJson
EvidencePackage::__construct	delapan parameter bernama, lihat fence	Value object immutable	EvidencePackage	Tidak ada yang dideklarasikan	Count tidak divalidasi terhadap $records
EvidencePackage::allPassed	tidak ada	failedCount === 0	bool	Tidak ada yang dideklarasikan	true untuk paket kosong; gate pada totalFindings
EvidencePackage::passRate	tidak ada	passedCount / totalFindings	float	Tidak ada yang dideklarasikan	0.0 ketika totalFindings === 0
EvidenceRecord::__construct	string $policyName, bool $passed, string $details, string $validatorVersion, DateTimeImmutable $timestamp	Hasil pemeriksaan policy tunggal yang immutable	EvidenceRecord	Tidak ada yang dideklarasikan	Semua properti adalah public readonly
EvidenceExporter::toJson	EvidencePackage $package	JSON dengan urutan kunci tetap; slash dan Unicode tak ter-escape	non-empty-string	JsonException	Urutan kunci bersifat load-bearing
EvidenceExporter::exportHash	EvidencePackage $package	SHA-256 atas byte toJson()	non-empty-string (64 hex)	JsonException	Stabil per paket
EvidenceStoreInterface::store	EvidencePackage $package	Menambahkan; riwayat per document hash diperbolehkan	void	Ditentukan oleh implementasi	Semantik append-only diwajibkan
EvidenceStoreInterface::persistImmutable	EvidencePackage $package	Penulisan WORM jika backend mendukungnya	void	Ditentukan oleh implementasi	Backend non-WORM berperilaku seperti store()
EvidenceStoreInterface::findByDocumentHash	string $documentHash	Paket terbaru untuk hash tersebut	?EvidencePackage	Ditentukan oleh implementasi
EvidenceStoreInterface::findAllByDocumentHash	string $documentHash	Semua paket untuk hash tersebut, terbaru dahulu	list<EvidencePackage>	Ditentukan oleh implementasi
EvidenceStoreInterface::count	tidak ada	Jumlah total paket tersimpan	int<0, max>	Ditentukan oleh implementasi
InMemoryEvidenceStore	class	Store berbasis array untuk pengujian dan pengembangan	n/a	n/a	Tidak durable; tanpa semantik WORM
ContinuousMonitor::__construct	EvidenceStoreInterface $store	Merangkai store	ContinuousMonitor	Tidak ada yang dideklarasikan
ContinuousMonitor::check	EvidencePackage $currentEvidence, string $documentHash	Membandingkan nama policy yang gagal terhadap paket terbaru tersimpan	MonitorResult	Tidak ada yang dideklarasikan	Check pertama memperlakukan setiap kegagalan saat ini sebagai baru
ContinuousMonitor::isDue	string $documentHash, MonitorSchedule $schedule	Due ketika tidak ada evidence sebelumnya, interval telah berlalu, atau evidence tersimpan bertanggal masa depan	bool	Tidak ada yang dideklarasikan	Fail-safe terhadap clock skew
MonitorResult::__construct	delapan parameter bernama, lihat fence	Hasil diff yang immutable	MonitorResult	Tidak ada yang dideklarasikan	Menyertakan kedua paket dan checkedAt
MonitorSchedule::__construct	MonitorFrequency $frequency, int $retentionDays = 90, bool $alertOnNewIssues = true	Value object konfigurasi	MonitorSchedule	Tidak ada yang dideklarasikan	Retensi dan alerting ditegakkan oleh host
MonitorFrequency	enum berbasis string	Case Daily, Weekly, Monthly	n/a	n/a	Nilai backing daily, weekly, monthly
MonitorFrequency::intervalSeconds	tidak ada	Interval per case: 86400, 604800, 2592000	positive-int	Tidak ada yang dideklarasikan	Monthly adalah tetap 30 hari

Tanda tangan entry-point

final class EvidencePortal
{
    public function __construct(
        private readonly EvidenceStoreInterface $store,
        private readonly EvidenceExporter $exporter,
    )

    public function generateEvidence(string $documentHash, array $records, ?string $tsaTimestamp = null): EvidencePackage

    public function getEvidence(string $documentHash): ?EvidencePackage

    public function getHistory(string $documentHash): array

    public function exportAsJson(EvidencePackage $package): string
}

final readonly class EvidencePackage
{
    public function __construct(
        public string $packageId,
        public string $documentHash,
        public array $records,
        public int $totalFindings,
        public int $passedCount,
        public int $failedCount,
        public DateTimeImmutable $generatedAt,
        public ?string $tsaTimestamp = null,
    )

    public function allPassed(): bool

    public function passRate(): float
}

final readonly class EvidenceRecord
{
    public function __construct(
        public string $policyName,
        public bool $passed,
        public string $details,
        public string $validatorVersion,
        public DateTimeImmutable $timestamp,
    )
}

final readonly class EvidenceExporter
{
    public function toJson(EvidencePackage $package): string

    public function exportHash(EvidencePackage $package): string
}

interface EvidenceStoreInterface
{
    public function store(EvidencePackage $package): void;

    public function persistImmutable(EvidencePackage $package): void;

    public function findByDocumentHash(string $documentHash): ?EvidencePackage;

    public function findAllByDocumentHash(string $documentHash): array;

    public function count(): int;
}

final class ContinuousMonitor
{
    public function __construct(
        private readonly EvidenceStoreInterface $store,
    )

    public function check(EvidencePackage $currentEvidence, string $documentHash): MonitorResult

    public function isDue(string $documentHash, MonitorSchedule $schedule): bool
}

final readonly class MonitorSchedule
{
    public function __construct(
        public MonitorFrequency $frequency,
        public int $retentionDays = 90,
        public bool $alertOnNewIssues = true,
    )
}

enum MonitorFrequency: string
{
    case Daily = 'daily';
    case Weekly = 'weekly';
    case Monthly = 'monthly';

    public function intervalSeconds(): int
}

Kontrak perilaku

EvidencePortal::generateEvidence(string $documentHash, list<EvidenceRecord> $records, ?string $tsaTimestamp = null): EvidencePackage adalah titik masuk penyegelan. Aturan yang dapat diamati secara eksternal:

1. Perakitan. generateEvidence menghitung record yang passed dan failed serta menetapkan totalFindings ke jumlahnya. Ia menetapkan packageId UUID versi-4 yang baru, menstempel generatedAt dengan waktu dinding, mempersistensikan paket melalui EvidenceStoreInterface::store, dan mengembalikannya. Daftar record ditanamkan dalam urutan yang diberikan, tanpa modifikasi.
2. Immutabilitas. EvidencePackage adalah final readonly dan tidak pernah dimutasi setelah konstruksi; ia cocok untuk penyimpanan WORM. allPassed() adalah failedCount === 0. passRate() adalah passedCount / totalFindings, dan 0.0 ketika totalFindings === 0.
3. Ekspor deterministik. EvidenceExporter::toJson memancarkan envelope dan setiap record dengan urutan kunci tetap yang ditulis tangan; urutan record mengikuti paket. Encoding bersifat ketat dan melempar pada kegagalan, dengan slash dan Unicode dibiarkan tak ter-escape (JSON_UNESCAPED_SLASHES). Timestamp diserialisasi dengan DateTimeInterface::RFC3339_EXTENDED, bentuk RFC 3339 extended dengan pecahan detik. exportHash mengembalikan digest hex SHA-256 sepanjang 64 karakter atas byte-byte tersebut secara persis. Paket yang sama selalu menghasilkan digest yang sama, di host mana pun, kapan pun. Menghasilkan ulang evidence untuk dokumen yang sama menghasilkan packageId dan generatedAt yang baru, sehingga digest baru: determinisme bersifat per paket, bukan per dokumen.
4. Timestamp adalah bukti waktu, bukan verdict. Sebuah paket dapat membawa token RFC 3161 opsional yang disuplai pemanggil (ter-encode base64). Token mengikat datum paket ke sebuah nilai waktu. Modul menanamkannya sebagai string opak; ia tidak mengambil, mem-parse, atau memverifikasi token, dan ia tidak menjamin TSA. Verifikasi token adalah milik modul Signature dan Security.
5. Pelacakan regresi. ContinuousMonitor::check memuat paket terbaru tersimpan untuk document hash dan membandingkan nama policy gagal yang unik. Isu dikategorikan sebagai newIssues (gagal sekarang, tidak sebelumnya), resolvedIssues (gagal sebelumnya, tidak sekarang), dan unchangedIssues (gagal pada keduanya). hasChanges bernilai true hanya ketika terdapat isu baru atau terselesaikan; kegagalan yang tidak berubah saja melaporkan false. Pada check pertama, setiap kegagalan saat ini adalah baru.
6. Penjadwalan. ContinuousMonitor::isDue mengembalikan true ketika tidak ada evidence untuk hash tersebut, ketika waktu yang berlalu sejak generatedAt tersimpan mencapai interval frekuensi schedule, atau ketika evidence tersimpan bertanggal masa depan relatif terhadap host polling. Kasus bertanggal masa depan bersifat fail-safe: paling buruk satu check ulang ekstra, tidak pernah yang terlewat.
7. Kontrak store. Implementasi EvidenceStoreInterface harus mendukung semantik append-only; beberapa paket per document hash membentuk riwayat, terbaru dahulu. persistImmutable menargetkan backend yang mampu WORM; implementasi non-WORM harus berperilaku persis seperti store.

Kasus tepi & mode kegagalan

• Paket kosong melaporkan allPassed() true dan passRate() 0.0. Gate pada totalFindings > 0 sebelum memperlakukan sebuah paket sebagai pass.
• Konstruksi EvidencePackage langsung tidak memvalidasi count terhadap $records. Gunakan portal, atau jaga sendiri konsistensi count.
• generateEvidence mempersistensi sebelum mengembalikan. Jalankan ContinuousMonitor::check dengan paket baru sebelum mempersistensikannya; check setelah persistensi membandingkan paket terhadap dirinya sendiri dan melaporkan tidak ada perubahan.
• exportHash mencakup byte toJson secara persis. Digest yang dihitung ulang oleh serializer, urutan kunci, atau kebijakan escaping lain tidak akan cocok.
• MonitorFrequency::Monthly adalah jendela tetap 30 hari, bukan bulan kalender.
• MonitorSchedule::$retentionDays dan $alertOnNewIssues adalah konfigurasi yang dibawa untuk scheduler host. Modul tidak pernah menghapus evidence dan tidak pernah mengirim alert.
• InMemoryEvidenceStore adalah untuk pengujian dan pengembangan. Paket hilang saat proses keluar, dan persistImmutable-nya tidak memiliki semantik WORM.
• String details record diekspor apa adanya; exporter tidak meredaksi. Jauhkan rahasia dan data pribadi teregulasi dari details. Residensi, retensi, dan kontrol akses mengikuti implementasi store operator.
• Argumen tsaTimestamp diterima sebagai string opak. Token yang malformed ditanamkan tanpa perubahan dan hanya muncul pada verifikasi hilir.

Perilaku mode FIPS

Modul ini menghitung digest SHA-256 dan menanamkan token RFC 3161 yang disuplai pemanggil. Ia tidak melakukan penandatanganan maupun kustodi kunci. Perilaku mode FIPS diatur oleh modul Security dan Signature.

Konformansi

Claim	Standard	Clause
Sebuah token time-stamp menunjukkan bahwa sebuah datum sudah ada pada suatu titik waktu tertentu.	IETF RFC 3161	§2
Timestamp yang diekspor menggunakan profil tanggal/waktu Internet dari ISO 8601, dengan pecahan detik.	IETF RFC 3339	§5.6
Material validasi yang ditanamkan di dalam PDF termasuk dalam Document Security Store; permukaan tersebut adalah milik modul Signature, bukan modul ini.	ISO 32000-2:2020	§12.8.4

Semua klausa diparafrasakan; NextPDF tidak mereproduksi teks normatif. NextPDF tidak membuat klaim sertifikasi. Penangkapan evidence mendukung alur kerja audit; ia bukan atestasi legal dan bukan sertifikasi audit. Sebuah token timestamp adalah bukti waktu saja, dan modul ini tidak menyatakan bahwa konten apa pun compliant. Validitas dan konformansi tetap merupakan properti dari file final ditambah sebuah validator. Referensi ini bukan opini legal; konsultasikan dengan penasihat kepatuhan dan legal Anda sendiri.

Catatan pengembangan

• Sumber modul membawa @since 2.2.0; referensi ini mendokumentasikan permukaan sebagaimana dikirim dalam nextpdf/enterprise 3.1.0.
• Segalanya berjalan dalam proses di host Anda. Modul tidak melakukan I/O jaringan dan tidak pernah menghubungi TSA sendiri.
• Urutan kunci literal-array exporter bersifat load-bearing secara desain. Menyusun ulangnya akan mengubah exportHash dan membatalkan digest yang sebelumnya tersimpan; sumber melarangnya.
• packageId adalah UUID versi-4 yang dirakit dari keluaran \random_bytes(16); identifier bersifat unik tetapi tidak reproducible.
• Persistensi durable disediakan oleh host. Penegakan WORM dan kontrol akses adalah tanggung jawab operator; store in-memory adalah satu-satunya implementasi yang dibundel.
• MonitorResult adalah value object final readonly; delapan propertinya bersifat public, termasuk checkedAt, waktu dinding dari check tersebut.

Batas publikasi

Halaman ini mendokumentasikan hanya perilaku yang dapat diamati secara eksternal dan permukaan API publik yang didukung. Jalur namespace internal, kelas helper, tabel mekanisme, nama file runbook, dan prefiks tiket berada di luar cakupan.

Lihat juga

• Evidence — halaman kapabilitas dengan panduan alur kerja.
• Validation — Referensi Mendalam
• Compliance — Referensi Mendalam
• AST audit trail — Referensi Mendalam
• Specifications: PAdES