Evidence — Derinlemesine başvuru

Bir bakışta

Bu sayfa, NextPDF\Enterprise\Evidence modülü için derinlemesine başvurudur. Modül, doğrulama bulgularını değişmez bir EvidencePackage içine mühürler, bunu kararlı bir SHA-256 özetiyle belirlenimci JSON olarak dışa aktarır, takılabilir bir depo sözleşmesi aracılığıyla kalıcılaştırır ve çalıştırmalar arasındaki regresyonları ContinuousMonitor ile izler. Modül, Validation ve Compliance yüzeyleri tarafından üretilen bulguları tüketir; kendisi hiçbir uygunluk denetimi gerçekleştirmez. İş akışı rehberliği için önce Evidence yetenek sayfasını okuyun.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Enterprise (nextpdf/enterprise) ile gelir ve bir Enterprise katmanı lisans zarfıyla etkinleşir. Bu hakka sahip olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Sürümleri karşılaştırın ve bir lisans edinin.

Yüzey, enterprise.compliance.evidence yeteneği tarafından lisanslanır; reddedilen bir hak, özelliği reddeder. Core ve Pro, bulgular ve raporlar üretir; bulguları değişmez, belirlenimci, isteğe bağlı zaman damgalı ve regresyon izlemeli bir pakete mühürlemenin hiçbir Core katmanı veya Pro katmanı eşdeğeri yoktur.

Genel API yüzeyi

composer require nextpdf/enterprise:^3

Sembol	Parametreler	Varsayılan davranış	Döndürür	Şununla fırlatır veya başarısız olur	Notlar
EvidencePortal::__construct	EvidenceStoreInterface $store, EvidenceExporter $exporter	Depoyu ve dışa aktarıcıyı bağlar	EvidencePortal	Hiçbir şey bildirilmez	Her iki işbirlikçi de enjekte edilebilir
EvidencePortal::generateEvidence	string $documentHash, list<EvidenceRecord> $records, ?string $tsaTimestamp = null	Geçti/kaldı sayar, taze bir UUID kimliği ve duvar saati generatedAt ile bir paketi mühürler, kalıcılaştırır	EvidencePackage	Hiçbir şey bildirilmez	persistImmutable() değil, store() aracılığıyla kalıcılaştırır
EvidencePortal::getEvidence	string $documentHash	Karma için saklanan en son paket	?EvidencePackage	Hiçbir şey bildirilmez	Hiçbiri saklanmadığında null
EvidencePortal::getHistory	string $documentHash	Tam geçmiş, en yeni önce	list<EvidencePackage>	Hiçbir şey bildirilmez	Sıralama depo tarafından sağlanır
EvidencePortal::exportAsJson	EvidencePackage $package	Dışa aktarıcıya devreder	non-empty-string	JsonException	EvidenceExporter::toJson ile aynı baytlar
EvidencePackage::__construct	sekiz adlandırılmış parametre, çite bakın	Değişmez değer nesnesi	EvidencePackage	Hiçbir şey bildirilmez	Sayılar $records karşısında doğrulanmaz
EvidencePackage::allPassed	yok	failedCount === 0	bool	Hiçbir şey bildirilmez	Boş bir paket için true; totalFindings üzerinden kapılayın
EvidencePackage::passRate	yok	passedCount / totalFindings	float	Hiçbir şey bildirilmez	totalFindings === 0 olduğunda 0.0
EvidenceRecord::__construct	string $policyName, bool $passed, string $details, string $validatorVersion, DateTimeImmutable $timestamp	Değişmez tek politika denetimi sonucu	EvidenceRecord	Hiçbir şey bildirilmez	Tüm özellikler public readonly
EvidenceExporter::toJson	EvidencePackage $package	Sabit anahtar sıralı JSON; kaçışsız eğik çizgiler ve Unicode	non-empty-string	JsonException	Anahtar sırası taşıyıcıdır
EvidenceExporter::exportHash	EvidencePackage $package	toJson() baytları üzerinde SHA-256	non-empty-string (64 onaltılık)	JsonException	Paket başına kararlı
EvidenceStoreInterface::store	EvidencePackage $package	Ekler; belge karması başına geçmişe izin verilir	void	Uygulama tanımlı	Yalnızca ekleme semantiği gereklidir
EvidenceStoreInterface::persistImmutable	EvidencePackage $package	Arka ucun desteklediği yerde WORM yazımı	void	Uygulama tanımlı	WORM olmayan arka uçlar store() gibi davranır
EvidenceStoreInterface::findByDocumentHash	string $documentHash	Karma için en son paket	?EvidencePackage	Uygulama tanımlı
EvidenceStoreInterface::findAllByDocumentHash	string $documentHash	Karma için tüm paketler, en yeni önce	list<EvidencePackage>	Uygulama tanımlı
EvidenceStoreInterface::count	yok	Saklanan paketlerin toplam sayısı	int<0, max>	Uygulama tanımlı
InMemoryEvidenceStore	sınıf	Testler ve geliştirme için dizi destekli depo	n/a	n/a	Dayanıklı değil; WORM semantiği yok
ContinuousMonitor::__construct	EvidenceStoreInterface $store	Depoyu bağlar	ContinuousMonitor	Hiçbir şey bildirilmez
ContinuousMonitor::check	EvidencePackage $currentEvidence, string $documentHash	Başarısız politika adlarını saklanan en son paketle karşılaştırır	MonitorResult	Hiçbir şey bildirilmez	İlk denetim, her geçerli başarısızlığı yeni olarak ele alır
ContinuousMonitor::isDue	string $documentHash, MonitorSchedule $schedule	Önceki kanıt yokken, aralık geçtiğinde veya saklanan kanıt gelecek tarihli olduğunda zamanı gelmiştir	bool	Hiçbir şey bildirilmez	Saat kaymasında güvenli-başarısızlık
MonitorResult::__construct	sekiz adlandırılmış parametre, çite bakın	Değişmez fark sonucu	MonitorResult	Hiçbir şey bildirilmez	Her iki paketi ve checkedAt değerini içerir
MonitorSchedule::__construct	MonitorFrequency $frequency, int $retentionDays = 90, bool $alertOnNewIssues = true	Yapılandırma değer nesnesi	MonitorSchedule	Hiçbir şey bildirilmez	Saklama ve uyarı ana makine tarafından zorlanır
MonitorFrequency	dize destekli enum	Daily, Weekly, Monthly durumları	n/a	n/a	Destek değerleri daily, weekly, monthly
MonitorFrequency::intervalSeconds	yok	Durum başına aralık: 86400, 604800, 2592000	positive-int	Hiçbir şey bildirilmez	Monthly sabit 30 gündür

Giriş noktası imzaları

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
}

Davranış sözleşmesi

EvidencePortal::generateEvidence(string $documentHash, list<EvidenceRecord> $records, ?string $tsaTimestamp = null): EvidencePackage, mühürleme giriş noktasıdır. Dışarıdan gözlemlenebilen kurallar:

1. Bir araya getirme. generateEvidence, geçen ve kalan kayıtları sayar ve totalFindings değerini bunların toplamına ayarlar. Taze bir sürüm-4 UUID packageId atar, generatedAt değerini duvar saatiyle damgalar, paketi EvidenceStoreInterface::store aracılığıyla kalıcılaştırır ve döndürür. Kayıt listesi verilen sırada, değiştirilmeden gömülür.
2. Değişmezlik. EvidencePackage, final readonly olup oluşturulduktan sonra hiçbir zaman değiştirilmez; WORM depolaması için uygundur. allPassed(), failedCount === 0 demektir. passRate(), passedCount / totalFindings değeridir ve totalFindings === 0 olduğunda 0.0 olur.
3. Belirlenimci dışa aktarma. EvidenceExporter::toJson, zarfı ve her kaydı sabit, elle yazılmış bir anahtar sırasıyla yayar; kayıt dizisi paketi izler. Kodlama katıdır ve başarısızlıkta fırlatır; eğik çizgiler ve Unicode kaçışsız bırakılır (JSON_UNESCAPED_SLASHES). Zaman damgaları DateTimeInterface::RFC3339_EXTENDED ile, yani kesirli saniyeler içeren RFC 3339 genişletilmiş biçimiyle serileştirilir. exportHash, tam olarak bu baytlar üzerinde 64 karakterli SHA-256 onaltılık özetini döndürür. Aynı paket, herhangi bir ana makinede, herhangi bir zamanda her zaman aynı özeti verir. Aynı belge için kanıtı yeniden oluşturmak yeni bir packageId ve generatedAt, dolayısıyla yeni bir özet verir: belirlenim paket başınadır, belge başına değil.
4. Zaman damgası, bir karar değil, zamanın kanıtıdır. Bir paket, çağıranın sağladığı isteğe bağlı bir RFC 3161 jetonu (base64 kodlu) taşıyabilir. Jeton, paket verisini bir zaman değerine bağlar. Modül bunu opak bir dize olarak gömer; jetonları getirmez, ayrıştırmaz veya doğrulamaz ve TSA için kefil olmaz. Jeton doğrulama, Signature ve Security modüllerine aittir.
5. Regresyon izleme. ContinuousMonitor::check, belge karması için saklanan en son paketi yükler ve benzersiz başarısız politika adlarını karşılaştırır. Sorunlar newIssues (şimdi başarısız, önce değil), resolvedIssues (önce başarısız, şimdi değil) ve unchangedIssues (her ikisinde de başarısız) olarak sınıflandırılır. hasChanges, yalnızca yeni veya çözülmüş sorunlar mevcut olduğunda true olur; yalnızca değişmeyen başarısızlıklar false bildirir. İlk denetimde, her geçerli başarısızlık yenidir.
6. Zamanlama. ContinuousMonitor::isDue, karma için hiçbir kanıt bulunmadığında, saklanan generatedAt değerinden bu yana geçen süre zamanlama sıklığı aralığına ulaştığında veya saklanan kanıt yoklama yapan ana makineye göre gelecek tarihli olduğunda true döndürür. Gelecek tarihli durum güvenli-başarısızlıktır: en kötü ihtimalle fazladan bir yeniden denetim, asla kaçırılan bir denetim değil.
7. Depo sözleşmesi. EvidenceStoreInterface uygulamaları yalnızca ekleme semantiğini desteklemelidir; belge karması başına birden çok paket geçmişi oluşturur, en yeni önce. persistImmutable, WORM yetenekli arka uçları hedefler; WORM olmayan uygulamalar tam olarak store gibi davranmalıdır.

Uç durumlar ve başarısızlık modları

• Boş bir paket allPassed() için true ve passRate() için 0.0 bildirir. Bir paketi geçiş olarak ele almadan önce totalFindings > 0 üzerinden kapılayın.
• Doğrudan EvidencePackage oluşturma, sayıları $records karşısında doğrulamaz. Portalı kullanın veya sayıları kendiniz tutarlı tutun.
• generateEvidence, döndürmeden önce kalıcılaştırır. Yeni paketle ContinuousMonitor::check işlemini onu kalıcılaştırmadan önce çalıştırın; kalıcılaştırmadan sonra yapılan bir denetim, paketi kendisiyle karşılaştırır ve hiçbir değişiklik bildirmez.
• exportHash, tam olarak toJson baytlarını kapsar. Başka herhangi bir serileştirici, anahtar sırası veya kaçış politikasıyla yeniden hesaplanan bir özet eşleşmez.
• MonitorFrequency::Monthly, takvim ayı değil, sabit 30 günlük bir penceredir.
• MonitorSchedule::$retentionDays ve $alertOnNewIssues, ana makine zamanlayıcıları için taşınan yapılandırmalardır. Modül hiçbir zaman kanıt silmez ve hiçbir zaman uyarı göndermez.
• InMemoryEvidenceStore, testler ve geliştirme içindir. Paketler süreç çıkışında kaybolur ve persistImmutable işlevinin hiçbir WORM semantiği yoktur.
• Kayıt details dizeleri birebir dışa aktarılır; dışa aktarıcı redakte etmez. Sırları ve düzenlemeye tabi kişisel verileri details dışında tutun. Yerleşim, saklama ve erişim denetimi, operatörün depo uygulamasını izler.
• tsaTimestamp argümanı opak bir dize olarak kabul edilir. Hatalı biçimli bir jeton değiştirilmeden gömülür ve yalnızca akış aşağısı doğrulamada ortaya çıkar.

FIPS modu davranışı

Bu modül, SHA-256 özetleri hesaplar ve çağıranın sağladığı bir RFC 3161 jetonu gömer. Hiçbir imzalama ve hiçbir anahtar muhafazası gerçekleştirmez. FIPS modu davranışı, Security ve Signature modülleri tarafından yönetilir.

Uygunluk

İddia	Standart	Madde
Bir zaman damgası jetonu, bir verinin belirli bir zaman noktasında var olduğunu gösterir.	IETF RFC 3161	§2
Dışa aktarılan zaman damgaları, kesirli saniyelerle birlikte ISO 8601’in İnternet tarih/saat profilini kullanır.	IETF RFC 3339	§5.6
Bir PDF içine gömülü doğrulama materyali, Document Security Store’a aittir; o yüzey bu modülün değil, Signature modülünündür.	ISO 32000-2:2020	§12.8.4

Tüm maddeler açımlanmıştır; NextPDF normatif metni yeniden üretmez. NextPDF hiçbir sertifikasyon iddiasında bulunmaz. Kanıt yakalama, denetim iş akışlarını destekler; bir hukuki tasdik ve bir denetim sertifikasyonu değildir. Bir zaman damgası jetonu yalnızca zamanın kanıtıdır ve bu modül herhangi bir içeriğin uyumlu olduğunu öne sürmez. Geçerlilik ve uygunluk, son dosya ile bir doğrulayıcının özellikleri olmaya devam eder. Bu başvuru bir hukuki görüş değildir; kendi uyumluluk ve hukuk danışmanlarınıza başvurun.

Geliştirme notları

• Modül kaynağı @since 2.2.0 taşır; bu başvuru, nextpdf/enterprise 3.1.0 sürümünde gönderilen yüzeyi belgeler.
• Her şey, ana makinenizde süreç içinde çalışır. Modül hiçbir ağ G/Ç’si gerçekleştirmez ve kendisi asla bir TSA ile iletişim kurmaz.
• Dışa aktarıcının dizi-değişmez anahtar sırası, tasarım gereği taşıyıcıdır. Yeniden sıralamak exportHash değerini değiştirir ve önceden saklanan özetleri geçersiz kılar; kaynak bunu yasaklar.
• packageId, \random_bytes(16) çıktısından oluşturulan bir sürüm-4 UUID’dir; tanımlayıcılar benzersizdir ancak yeniden üretilebilir değildir.
• Dayanıklı kalıcılık, ana makine tarafından sağlanır. WORM zorunluluğu ve erişim denetimi operatörün sorumluluğundadır; bellek içi depo, birlikte gelen tek uygulamadır.
• MonitorResult, final readonly bir değer nesnesidir; sekiz özelliği public’tir, denetimin duvar saati zamanı olan checkedAt dahil.

Yayımlama sınırı

Bu sayfa yalnızca dışarıdan gözlemlenebilen davranışı ve desteklenen genel API yüzeyini belgeler. İç ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, runbook dosya adları ve bilet önekleri kapsam dışıdır.

Ayrıca bkz.

• Evidence — iş akışı rehberliği içeren yetenek sayfası.
• Validation — Derinlemesine başvuru
• Compliance — Derinlemesine başvuru
• AST denetim izi — Derinlemesine başvuru
• Belirtimler: PAdES