/** * @license * Copyright 2022-2026 Matter.js Authors * SPDX-License-Identifier: Apache-2.0 */ import { Bytes, Construction, Duration, Environment } from "@matter/general"; import { DclClient } from "./DclClient.js"; import { DclConfig, DclGithubConfig } from "./DclConfig.js"; import type { CertSeedEntry, SeedSource } from "./SeedTypes.js"; /** * Implements a service to manage DCL root certificates as a singleton in the environment and so will be shared by * multiple nodes of relevant. It is mainly relevant for controller use cases. * The service supports fetching certificates from teh CSA production and test DCL instances, as well * as from a GitHub repository for development certificates. */ export declare class DclCertificateService { #private; constructor(environment: Environment, options?: DclCertificateService.Options); get construction(): Construction; /** Whether the service runs {@link DclCertificateService.Options.offline}. */ get offline(): boolean; /** * Get certificate metadata by subject key identifier. Returns undefined if not found or if the * entry is filtered by the effective trust policy. */ getCertificate(subjectKeyId: Bytes | string, options?: DclCertificateService.GetCertificateOptions): DclCertificateService.CertificateMetadata | undefined; /** * Get all certificate metadata entries (raw enumeration, unaffected by the * `fetchTestCertificates` filter so management commands can still inspect cached test certs). */ get certificates(): DclCertificateService.CertificateMetadata[]; /** * Whether the service trusts test (non-production) certificates as valid trust anchors. * * Independent of {@link Options.fetchTestCertificates} (which only governs whether test certs are * downloaded). Defaults to {@link Options.acceptTestCertificates}, falling back to * `fetchTestCertificates` when the trust policy is not set explicitly. */ get acceptsTestCertificates(): boolean; /** * Get certificate as PEM string. * @throws {MatterDclError} if certificate not found or filtered by trust policy */ getCertificateAsPem(subjectKeyId: Bytes | string, options?: DclCertificateService.GetCertificateOptions): Promise; /** * Get certificate as DER bytes. * * Self-heals a corrupted local cache: if the stored certificate no longer parses (e.g. a * truncated or mangled storage entry), make one best-effort re-fetch from DCL so a broken cache * entry cannot permanently break attestation for an otherwise-valid trust anchor. If recovery * fails the original bytes are returned unchanged, leaving the caller's normal validation to * surface the parse failure rather than masking it with a different error here. * * @throws {MatterDclError} if certificate not found or filtered by trust policy */ getCertificateAsDer(subjectKeyId: Bytes | string, options?: DclCertificateService.GetCertificateOptions): Promise; /** * Install revocation information that did not come from the DCL. * * The DCL is the authority on revocation: it publishes distribution points, and {@link isRevoked} * downloads and validates the CRL behind one the first time an authority is asked about. A set * installed here is trusted as it stands — no signer chain, no CRL signature — because it is * already the validated product of that process rather than an input to it. So this is for a * deployment that cannot reach the DCL, and for certification against a PKI the DCL does not * publish. Ordinary commissioning needs none of it. * * The entries live in memory for the life of this service and are never stored. A serial listed * here is revoked; every other serial still goes to the DCL, so an installed set can only add * revocations, never hide one. Installing the same set twice changes nothing. * * An entry that names no issuer is matched on its key identifier alone, which the specification's * composite key does not license and chip's own reading refuses. A key identifier is a hash of the * issuer's public key, so the widening is small, and it errs toward refusing a device rather than * admitting one. * * @see {@link MatterSpecification.v161.Core} § 6.2.4.1 */ installRevocations(entries: DclCertificateService.RevocationSetEntry[]): void; /** * Revocation information installed from outside the DCL, by the key identifier it was stated for. * * A copy: what this service holds can only be added to, through {@link installRevocations}. */ get installedRevocations(): ReadonlyMap; /** * Check if a certificate is revoked by looking up its serial number in the revocation set * for the given authority key identifier. * * Lazily fetches revocation data from DCL on first access per AKID, then caches for 1 hour. * Per spec Section 6.2.6.2, the revocation set is indexed by (AuthorityKeyIdentifier, IssuerDN). * * Returns true if the certificate is revoked, false otherwise. * If revocation data is not available for the given authority, returns false. * * @throws {ClosedError} if the service is closing or closed */ isRevoked(authorityKeyIdentifier: Bytes | string, serialNumber: Bytes | string, issuerDnDerHex?: string): Promise; /** * Get certificate metadata by subject key identifier, fetching from DCL if not in local storage and the service * is not {@link DclCertificateService.Options.offline}. Returns undefined if not found or if the entry is filtered * by the effective trust policy. */ getOrFetchCertificate(subjectKeyId: Bytes | string, options?: DclClient.Options & { isProduction?: boolean; } & DclCertificateService.GetCertificateOptions): Promise; /** * Delete a certificate from storage and index. */ deleteCertificate(subjectKeyId: Bytes | string): Promise; /** * Inject a certificate (PAA or CD signer) into the trust store. * * Returns `true` if the certificate was newly added, `false` if a certificate with the same * SubjectKeyIdentifier already exists (in which case the store is unchanged). * * @param derBytes DER-encoded X.509 certificate * @param kind "PAA" (self-signed root) or "CDSigner" (CMS Certification Declaration signer) * @param options.isProduction mark as production-trust; defaults to `false` */ addCertificate(derBytes: Bytes, kind: DclCertificateService.CertificateKind, options?: { isProduction?: boolean; }): Promise; /** * Look up a CD signer certificate by its SubjectKeyIdentifier. * * Checks the local trust store first. On miss, queries the production DCL * (`/dcl/pki/all-certificates?subjectKeyId=`) and caches the result as a * CDSigner entry with `isProduction: true`. * * Returns `undefined` if no matching CD signer can be found either locally or on DCL. */ getOrFetchCdSigner(subjectKeyId: Bytes | string): Promise<{ publicKey: Bytes; isProduction: boolean; } | undefined>; /** * Close the service and stop all timers. */ close(): Promise; /** * Update certificates from DCL and GitHub. Returns true if update succeeded, false if it failed. */ update(force?: boolean): Promise; /** * Read a revocation set: the per-issuer list of revoked serial numbers that the CHIP SDK's * `generate_revocation_set.py` writes by walking the DCL's revocation distribution points and the * CRLs behind them. It is that tool's own format, not a DCL wire format. Fields beyond the ones * {@link installRevocations} needs are ignored. */ static parseRevocationSet(json: string): DclCertificateService.RevocationSetEntry[]; /** Result of parsing a CRL. */ static parseCrl(crlDer: Bytes, authorityName?: Bytes): DclCertificateService.CrlParseResult; /** Convenience wrapper that returns only the revoked serial numbers from a CRL. */ static parseCrlRevokedSerials(crlDer: Bytes): Set; } export declare namespace DclCertificateService { /** Per-call options for certificate retrieval. */ interface GetCertificateOptions { /** * Whether the lookup should also return test (non-production) certificates. * Defaults to the service-wide `fetchTestCertificates` flag passed at construction. */ considerTestCertificates?: boolean; } interface Options { /** Whether to fetch test certificates in addition to production ones. Default is false. */ fetchTestCertificates?: boolean; /** * Whether to trust test (non-production) certificates as valid trust anchors. Controls whether a * matched test PAA is accepted during device attestation or flagged via a * `TrustedAsTestCertificate` finding. Independent of `fetchTestCertificates`. Defaults to the value * of `fetchTestCertificates` when not set. */ acceptTestCertificates?: boolean; /** Whether to fetch development certificates from GitHub. Default is true (when fetchTestCertificates is true). */ fetchGithubCertificates?: boolean; /** * Interval for periodic certificate updates. Default is 1 day. Set to null to disable automatic certificate * updates */ updateInterval?: Duration | null; /** Timeout for DCL requests. Default is 5s. */ timeout?: Duration; /** DCL config for production endpoint. Defaults to DclConfig.production. */ dclConfig?: DclConfig; /** DCL config for test endpoint. Defaults to DclConfig.test. */ testDclConfig?: DclConfig; /** GitHub config for development certificates. Programmatic override only. Defaults to DclGithubConfig.defaults. */ githubConfig?: DclGithubConfig; /** * Pre-populate storage from snapshot before the initial network update, which still runs after unless * `offline`. */ seed?: { paaRoots?: SeedSource; cdSigners?: SeedSource; }; /** Revocation information from outside the DCL — see {@link DclCertificateService.installRevocations}. */ revocations?: RevocationSetEntry[]; /** * Reaches no network at all: no update, no CRL, no certificate fetched on demand and no re-fetch of one that * would not parse. The trust store is whatever storage from earlier runs and `seed` carried, revocation is * whatever {@link DclCertificateService.installRevocations} was given, and a certificate neither of those holds * reads as absent. * * For a deployment with no route to the ledger, and for a test that must judge attestation * against a stated PKI rather than against whatever the ledger holds today. */ offline?: boolean; } /** One authority's revoked serial numbers, as a DCL revocation set states them. */ interface RevocationSetEntry { /** Subject key identifier of the certificate that issued the revoked ones, as hex. */ issuerSubjectKeyId: string; /** * Base64 of the DER-encoded issuer Name. With the key identifier this forms the composite key * revocation is indexed by; an entry without one matches on the key identifier alone. */ issuerName?: string; /** The revoked serial numbers, as hex. */ revokedSerialNumbers: string[]; } /** Kind of certificate stored in the trust store. */ type CertificateKind = "PAA" | "CDSigner"; /** * Metadata for a stored certificate. */ type CertificateMetadata = { subject?: string; subjectAsText?: string; subjectKeyId: string; serialNumber: string; vid: number; isRoot: boolean; isProduction: boolean; /** Kind of certificate. Defaults to "PAA" when absent (backward compat). */ kind?: CertificateKind; /** Epoch timestamp (ms) when this certificate was first fetched and added to the local trust store. */ fetchedAt?: number; }; /** Revocation information installed from outside the DCL, as {@link installedRevocations} reports it. */ interface InstalledRevocation { readonly serials: ReadonlySet; readonly issuerDnDerHex?: string; } /** Cached revocation data for a single AKID. */ interface RevocationEntry { serials: Set; issuerDnDerHex?: string; } /** Result of parsing a DER-encoded CRL. */ interface CrlParseResult { /** Revoked serial numbers (uppercase hex). */ serials: Set; /** Hex of the DER-encoded issuer Name, for composite revocation key matching. */ issuerDnDerHex?: string; /** CRL Authority Key Identifier extension value (uppercase hex). */ authorityKeyId?: string; /** Raw DER bytes of tbsCertList for signature verification. */ tbsDer?: Bytes; /** * DER of the CRL's signature AlgorithmIdentifier; absent if it differs from the one inside tbsCertList. */ signatureAlgorithm?: Bytes; /** Raw signature value bytes from the CRL; absent unless it is a BIT STRING without unused bits. */ signatureValue?: Bytes; /** * The single URI of a critical Issuing Distribution Point extension; absent if the extension is missing, not * critical, or names anything but exactly one URI. */ issuingDistributionPointUri?: string; /** * OID (hex) of a critical CRL or CRL entry extension the parser does not support, such as a delta CRL * indicator, or of a certificateIssuer entry extension that is not critical or not a single directoryName; * RFC 5280 §6.3.3 forbids using such a CRL. */ unsupportedCriticalExtension?: string; /** Unix epoch ms of the CRL's nextUpdate field, if present. */ nextUpdateMs?: number; } } //# sourceMappingURL=DclCertificateService.d.ts.map