/** * @license * Copyright 2022-2026 Matter.js Authors * SPDX-License-Identifier: Apache-2.0 */ import { Bytes, Crypto, MaybePromise, PublicKey } from "@matter/general"; import { VendorId } from "@matter/types"; import { DclCertificateService } from "../dcl/DclCertificateService.js"; import { CommissioningError } from "../peer/CommissioningError.js"; /** Reasons a device attestation validation can fail or produce warnings. */ export declare enum DeviceAttestationCheck { PaaNotTrusted = "PaaNotTrusted", CertificateChainInvalid = "CertificateChainInvalid", CertificateExpired = "CertificateExpired", VendorIdMismatch = "VendorIdMismatch", AttestationSignatureInvalid = "AttestationSignatureInvalid", AttestationNonceMismatch = "AttestationNonceMismatch", CertificationDeclarationSignatureInvalid = "CertificationDeclarationSignatureInvalid", CertificationDeclarationFieldMismatch = "CertificationDeclarationFieldMismatch", CertificateRevoked = "CertificateRevoked", FirmwareInfoMismatch = "FirmwareInfoMismatch", CertificationTypeProvisional = "CertificationTypeProvisional", CertificationTypeTest = "CertificationTypeTest", CertificateIdNotVerified = "CertificateIdNotVerified", CertificateUnparseable = "CertificateUnparseable", AttestationElementsUnparseable = "AttestationElementsUnparseable", CertificationDeclarationUnparseable = "CertificationDeclarationUnparseable", CdSignerVerificationSkipped = "CdSignerVerificationSkipped", PaaTrustStoreTimeMismatch = "PaaTrustStoreTimeMismatch", DclServiceUnavailable = "DclServiceUnavailable", TrustedAsTestCertificate = "TrustedAsTestCertificate", /** An unexpected error during validation (e.g. an unrecoverably corrupt trust-store certificate). */ ValidationError = "ValidationError" } /** A single finding from the attestation validation process. */ export interface AttestationFinding { /** Severity. "error" aborts validation unless the check is recoverable (collected instead). */ level: "error" | "warning" | "info"; /** The specific check that produced this finding. */ type: DeviceAttestationCheck; /** Human-readable description. */ message: string; } /** Error thrown when device attestation validation encounters a hard failure. */ export declare class DeviceAttestationError extends CommissioningError { readonly failure: DeviceAttestationCheck; constructor(failure: DeviceAttestationCheck, message: string, options?: ErrorOptions); } export declare namespace DeviceAttestationValidator { interface Context { crypto: Crypto; attestationChallenge: Bytes; /** * DclCertificateService for PAA trust store, chain validation, revocation checks, and * CD signer lookup. When absent, DCL-dependent checks are skipped (PAA lookup, chain * verification, revocation, CD signature) but local checks still run (nonce, signature, * VendorID, CD fields). */ dclCertificateService?: DclCertificateService; } interface DeviceAttestationData { dac: Bytes; pai: Bytes; attestationElements: Bytes; attestationSignature: Bytes; attestationNonce: Bytes; vendorId: VendorId; productId: number; } /** Result of a successful validation, including any non-fatal findings. */ interface ValidationResult { dacPublicKey: ReturnType; findings: AttestationFinding[]; } /** * Controls behavior when attestation findings occur. * - `true`: always proceed (warnings/info logged) * - `false`: reject on any finding * - `undefined`: backward-compatible accept with logging * - function: receives all findings; may * - return `true` to proceed * - return `false` to reject with the underlying error (the original * {@link DeviceAttestationError} on hard-failure findings, or a fresh * {@link CommissioningError} on collected-finding rejection) * - return a `string` to reject with a new {@link CommissioningError} whose message is * that string and whose `cause` is the underlying error * - throw any error to reject by rethrowing that error verbatim (no wrapping) */ type OnAttestationFailure = boolean | ((findings: AttestationFinding[]) => MaybePromise); /** * Validates device attestation per Matter spec Section 6.2.3.1. * * Local checks (nonce, signature, VendorID, CD fields) always run. DCL-dependent checks * (PAA trust store, chain verification, revocation) only run when dclCertificateService * is provided. * * Most error-level failures throw immediately via {@link DeviceAttestationError}. A small * set of recoverable error cases (currently {@link DeviceAttestationCheck.TrustedAsTestCertificate}) * are collected in `findings` so the caller can decide via `onFailure` whether to proceed. * Warning and info findings are always collected. */ function validate(context: Context, data: DeviceAttestationData): Promise; } //# sourceMappingURL=DeviceAttestationValidator.d.ts.map