@originator-profile/verify 0.4.0-beta.1

package/dist/index.d.mts

@@ -0,0 +1,532 @@
+import { JwtVcDecodingResult, JwtVcVerificationResult, UnverifiedJwtVc, VerifiedJwtVc, VcValidator } from '@originator-profile/securing-mechanism';
+import { ContentAttestation, Target, ContentAttestationSet, JwtOpPayload, JwtDpPayload, Op, Dp, OpVc, Jwk, CoreProfile, Certificate as Certificate$1, WebMediaProfile, WebsiteProfile, ArticleCA, JapaneseExistenceCertificate, OriginatorProfileSet, SiteProfile, CertificationSystem, AllowedOrigin } from '@originator-profile/model';
+import { Keys } from '@originator-profile/cryptography';
+import { DigestSriContent, ContentFetcher, ElementSelector } from '@originator-profile/sign';
+import { ErrorObject } from 'ajv';
+import { JWTVerifyResult, ResolvedKey, JWTPayload } from 'jose';
+import { JOSEError } from 'jose/errors';
+
+/** Content Attestation 復号失敗 */
+type CaDecodingFailure = JwtVcDecodingResult<ContentAttestation>;
+/** 復号済み Content Attestation */
+type DecodedCa = UnverifiedJwtVc<ContentAttestation>;
+/** Content Attestation 復号結果 */
+type CaDecodingResult = DecodedCa | CaInvalid;
+/** Content Attestation 検証失敗 */
+type CaVerificationFailure = JwtVcVerificationResult<ContentAttestation>;
+/** 検証済み Content Attestation */
+type VerifiedCa<T extends ContentAttestation = ContentAttestation> = VerifiedJwtVc<T>;
+/** Content Attestation 検証結果 */
+type CaVerificationResult<T extends ContentAttestation = ContentAttestation> = VerifiedCa<T> | CaInvalid | CaVerifyFailed;
+
+/**
+ * Content Attestation 無効
+ *
+ * Content Attestation が無効な形式です。詳細は result プロパティに格納される CaInvalid クラスインスタンスのメッセージを確認してください。
+ */
+declare class CaInvalid extends Error {
+    result: CaDecodingFailure;
+    static get code(): string;
+    readonly code: string;
+    constructor(message: string, result: CaDecodingFailure);
+}
+/**
+ * Content Attestation 検証失敗
+ *
+ * Content Attestation の検証に失敗しました。詳細は result プロパティに格納される CaVerifyFailed クラスインスタンスのメッセージを確認してください。
+ **/
+declare class CaVerifyFailed extends Error {
+    result: CaVerificationFailure;
+    static get code(): string;
+    readonly code: string;
+    constructor(message: string, result: CaVerificationFailure);
+}
+
+/**
+ * `digestSRI` の検証
+ * @see {@link https://www.w3.org/TR/SRI/#the-integrity-attribute}
+ * @example
+ * ```ts
+ * const content: DigestSriContent = {
+ *   id: "<URL>",
+ *   digestSRI: "sha256-...",
+ * };
+ *
+ * await verifyDigestSri(content); // true or false
+ * ```
+ */
+declare function verifyDigestSri(content: DigestSriContent, fetcher?: typeof fetch): Promise<boolean>;
+
+type IntegrityVerifyResult = {
+    valid: boolean;
+    failedIntegrities: ReadonlyArray<string>;
+};
+/** Target Integrity のコンテンツ取得・要素位置特定アルゴリズム */
+declare const TargetIntegrityAlgorithm: {
+    HtmlTargetIntegrity: {
+        contentFetcher: ContentFetcher;
+        elementSelector: ElementSelector;
+    };
+    TextTargetIntegrity: {
+        contentFetcher: ContentFetcher;
+        elementSelector: ElementSelector;
+    };
+    VisibleTextTargetIntegrity: {
+        contentFetcher: ContentFetcher;
+        elementSelector: ElementSelector;
+    };
+    ExternalResourceTargetIntegrity: {
+        contentFetcher: ContentFetcher;
+        elementSelector: ElementSelector;
+    };
+};
+/**
+ * Target Integrity の検証
+ * @see {@link https://docs.originator-profile.org/opb/content-integrity-descriptor/}
+ * @example
+ * ```ts
+ * const content = {
+ *   type: "HtmlTargetIntegrity", // or ***TargetIntegrity
+ *   cssSelector: "<CSS セレクター>",
+ *   integrity: "sha256-...",
+ * };
+ *
+ * await verifyIntegrity(content); // true or false
+ * ```
+ */
+declare function verifyIntegrity(content: Target, doc?: Document, fetcher?: typeof fetch): Promise<IntegrityVerifyResult>;
+type VerifyIntegrity = typeof verifyIntegrity;
+
+/**
+ * Content Attestation 検証機の作成
+ * @param ca Content Attestation
+ * @param keys Content Attestation の発行者の検証鍵
+ * @param issuer Content Attestation の発行者
+ * @param url 検証対象のURL
+ * @param verifyIntegrity Target Integrity の検証器
+ * @param validator バリデーター
+ * @returns 検証機
+ */
+declare function CaVerifier<T extends ContentAttestation>(ca: string, keys: Keys, issuer: string, url: URL, verifyIntegrity?: VerifyIntegrity, validator?: VcValidator<VerifiedCa<T>>): () => Promise<CaVerificationResult<T>>;
+
+/** COntent Attestation Set 要素 */
+type CasItem<Ca> = {
+    main: boolean;
+    attestation: Ca;
+};
+/** 検証済み Content Attestation Set */
+type VerifiedCas<Ca extends ContentAttestation = ContentAttestation> = Array<CasItem<VerifiedCa<Ca>>>;
+/** Content Attestation Set 検証失敗 */
+type CasVerificationFailure = Exclude<CasItem<CaVerificationResult>, CaVerificationResult>[];
+/** Content Attestation Set 検証結果 */
+type CasVerificationResult<T extends ContentAttestation = ContentAttestation> = VerifiedCas<T> | CasVerifyFailed;
+
+/**
+ * Content Attestation Set 検証失敗
+ *
+ * Content Attestation Set の検証に失敗しました。詳細は result プロパティに格納される CaVerifyFailed クラスインスタンスのメッセージを確認してください。
+ **/
+declare class CasVerifyFailed extends Error {
+    result: CasVerificationFailure;
+    static get code(): string;
+    readonly code: string;
+    constructor(message: string, result: CasVerificationFailure);
+}
+
+/**
+ * Content Attestation Set 要素の正規化
+ *
+ * @example
+ * ```ts
+ * const cas = ["eyJ...", { main: true, attestation: "eyJ..." }];
+ * const normalized = normalizeCasItem(cas);
+ * normalized; // [{ main: false, attestation: "eyJ..." }, { main: true, attestation: "eyJ..." }]
+ * ```
+ * */
+declare function normalizeCasItem<Ca>(ca: Ca | CasItem<Ca>): CasItem<Ca>;
+
+/**
+ * Content Attestation Set の検証
+ * @param cas Content Attestation Set
+ * @param verifiedOps 検証済み Originator Profile Set
+ * @param url 検証対象のURL
+ * @param verifyIntegrity Target Integrity の検証器
+ * @param validator バリデーター
+ * @returns CAS 検証結果
+ *
+ * @example
+ * ```ts
+ * import { verifyIntegirty } from "@originator-profile/verify";
+ *
+ * const cas = ["eyJ...", { main: true, attestation: "eyJ..." }];
+ * const verifiedOps; // VerifiedOps
+ * const url = location.href;
+ * const verified = await verifyCas(cas, verifiedOps, url, verifyIntegrity);
+ * if (verified instanceof Error) {
+ *   verified; // CasVerifyFailed
+ *   process.exit(1);
+ * }
+ * verified; // VerifiedCas
+ * ```
+ */
+declare function verifyCas<T extends ContentAttestation = ContentAttestation>(cas: ContentAttestationSet, verifiedOps: VerifiedOps, url: string, verifyIntegrity: VerifyIntegrity, validator?: typeof VcValidator): Promise<CasVerificationResult<T>>;
+
+interface ProfilePair {
+    op: {
+        iss: string;
+        sub: string;
+        profile: string;
+    };
+    dp: {
+        sub: string;
+        profile: string;
+    };
+}
+interface WebsiteProfilePair {
+    "@context": string;
+    website: ProfilePair;
+}
+interface AdProfilePair {
+    "@context": string;
+    ad: ProfilePair;
+}
+/** Profile の Token の復号結果 */
+type DecodeResult = {
+    op: true;
+    payload: JwtOpPayload;
+    jwt: string;
+} | {
+    dp: true;
+    payload: JwtDpPayload;
+    jwt: string;
+} | ProfileClaimsValidationFailed;
+/** Profile の Token の検証結果 */
+type VerifyTokenResult = (JWTVerifyResult & ResolvedKey & ({
+    op: Op;
+    jwt: string;
+} | {
+    dp: Dp;
+    jwt: string;
+})) | ProfileClaimsValidationFailed | ProfileTokenVerifyFailed;
+/** Profile Set */
+type Profiles = {
+    profile: string[];
+    ad?: ProfilePair[];
+};
+/** Profile の検証結果 */
+type VerifyResult = VerifyTokenResult | ProfilesResolveFailed | ProfilesVerifyFailed;
+/** Profile Set の検証結果 */
+type VerifyResults = VerifyResult[];
+
+declare class ProfileGenericError extends Error {
+    static get code(): string;
+    readonly code: string;
+}
+declare class ProfileClaimsValidationFailed extends ProfileGenericError {
+    static get code(): "ERR_PROFILE_CLAIMS_VALIDATION_FAILED";
+    readonly code: "ERR_PROFILE_CLAIMS_VALIDATION_FAILED";
+    /** 復号結果 */
+    result: {
+        error?: JOSEError;
+        errors?: ErrorObject[];
+        payload?: JWTPayload;
+        jwt: string;
+    };
+    constructor(message: string, result: ProfileClaimsValidationFailed["result"]);
+}
+declare class ProfileTokenVerifyFailed extends ProfileGenericError {
+    static get code(): "ERR_PROFILE_TOKEN_VERIFY_FAILED";
+    readonly code: "ERR_PROFILE_TOKEN_VERIFY_FAILED";
+    /** 検証結果 */
+    result: Exclude<DecodeResult, ProfileGenericError> & {
+        error?: JOSEError;
+    };
+    constructor(message: string, result: ProfileTokenVerifyFailed["result"]);
+}
+declare class ProfileBodyExtractFailed extends ProfileGenericError {
+    static get code(): "ERR_PROFILE_BODY_EXTRACT_FAILED";
+    readonly code: "ERR_PROFILE_BODY_EXTRACT_FAILED";
+}
+declare class ProfileBodyVerifyFailed extends ProfileGenericError {
+    static get code(): "ERR_PROFILE_BODY_VERIFY_FAILED";
+    readonly code: "ERR_PROFILE_BODY_VERIFY_FAILED";
+    /** 検証結果 */
+    result: {
+        error?: JOSEError;
+        body: string;
+    };
+    constructor(message: string, result: ProfileBodyVerifyFailed["result"]);
+}
+declare class ProfilesResolveFailed extends ProfileGenericError {
+    static get code(): "ERR_PROFILES_RESOLVE_FAILED";
+    readonly code: "ERR_PROFILES_RESOLVE_FAILED";
+    /** 検証結果 */
+    result: Exclude<DecodeResult, ProfileGenericError>;
+    constructor(message: string, result: ProfilesResolveFailed["result"]);
+}
+declare class ProfilesVerifyFailed extends ProfileGenericError {
+    static get code(): "ERR_PROFILES_VERIFY_FAILED";
+    readonly code: "ERR_PROFILES_VERIFY_FAILED";
+    /** 検証結果 */
+    result: Exclude<DecodeResult | VerifyTokenResult, ProfileGenericError>;
+    constructor(message: string, result: ProfilesVerifyFailed["result"]);
+}
+declare class CertificationSystemValidationFailed extends ProfileGenericError {
+    static get code(): "ERR_CERTIFICATION_SYSTEM_VALIDATION_FAILED";
+    readonly code: "ERR_CERTIFICATION_SYSTEM_VALIDATION_FAILED";
+    /** 検証結果 */
+    result: {
+        payload?: unknown;
+    };
+    constructor(message: string, result: CertificationSystemValidationFailed["result"]);
+}
+
+// Definitions by: Eddie Atkinson <https://github.com/eddie-atkinson>
+
+type Operation = "add" | "replace" | "remove" | "move";
+
+type DiffOps = Array<{
+  op: Operation;
+  path: Array<string | number>;
+  value?: any;
+}>;
+type PathConverter = (path: string) => string[];
+
+declare function diffApply<T extends object>(
+  obj: T,
+  diff: DiffOps,
+  pathConverter?: PathConverter
+): T;
+
+/**
+ * JSON Patch を適用する関数
+ *
+ * @link https://jsonpatch.com/
+ */
+declare const patch: <T extends object>(...args: Parameters<typeof diffApply<T>>) => T;
+/**
+ * VerifyResult ファクトリー
+ *
+ * @link https://reference.originator-profile.org/ts/types/_originator-profile_securing-mechanism.UnverifiedJwtVc
+ * @link https://reference.originator-profile.org/ts/types/_originator-profile_securing-mechanism.VerifiedJwtVc
+ */
+declare const VerifyResultFactory: (issuedAt: Date, expiredAt: Date) => {
+    create: (vc: OpVc, jwt: string, verificationKey?: Jwk, validated?: boolean) => UnverifiedJwtVc<OpVc> | VerifiedJwtVc<OpVc>;
+};
+/** OP ID Constants */
+declare const opId: {
+    /** CP 発行者 */
+    authority: "dns:cp-issuer.example.org";
+    /** PA 発行者 */
+    certifier: "dns:pa-issuer.example.org";
+    /** CA 発行者 */
+    originator: "dns:originator.example.org";
+    /** 無効な第三者 */
+    invalid: "dns:invalid.example.org";
+};
+/** Core Profile */
+declare const cp: CoreProfile;
+/** Certificate  */
+declare const certificate: Certificate$1;
+/** Web Media Profile */
+declare const wmp: WebMediaProfile;
+/** Website Profile */
+declare const wsp: WebsiteProfile;
+/** CA ID */
+declare const caId = "urn:uuid:78550fa7-f846-4e0f-ad5c-8d34461cb95b";
+/** CA URL */
+declare const caUrl: URL;
+/** Article CA */
+declare const article: ArticleCA;
+
+/**
+ * Originator Profile Set 無効
+ *
+ * Originator Profile Set が無効な形式です。詳細は result プロパティに格納される OpInvalid クラスインスタンスのメッセージを確認してください。
+ */
+declare class OpsInvalid extends Error {
+    result: OpsDecodingFailure;
+    static get code(): string;
+    readonly code: string;
+    constructor(message: string, result: OpsDecodingFailure);
+}
+/**
+ * Originator Profile 無効
+ *
+ * Originator Profile が無効な形式です。次の原因で使用されます。
+ *
+ *  - Core Profile の復号に失敗した
+ *  - Profile Annotation の復号に失敗した
+ *  - Web Media Profile の復号に失敗した
+ *  - Core Profile と Profile Annotation の `credentialSubject.id` が不一致
+ *  - Core Profile と Web Media Profile の `credentialSubject.id` が不一致
+ */
+declare class OpInvalid extends Error {
+    result: OpDecodingFailure;
+    static get code(): string;
+    readonly code: string;
+    constructor(message: string, result: OpDecodingFailure);
+}
+/**
+ * Core Profile 未発見
+ *
+ * Core Profile が見つかりませんでした。次の原因で使用されます。
+ *
+ * - Core Profile が Originator Profile Set に含まれていない
+ * - Core Profile の検証結果が見つからなかった
+ */
+declare class CoreProfileNotFound<T extends OpVc> extends Error {
+    result: UnverifiedJwtVc<T>;
+    static get code(): string;
+    readonly code: string;
+    constructor(message: string, result: UnverifiedJwtVc<T>);
+}
+/**
+ * Originator Profile Set 検証失敗
+ *
+ * Originator Profile Set の検証に失敗しました。詳細は result プロパティに格納される OpVerifyFailed クラスインスタンスのメッセージを確認してください。
+ **/
+declare class OpsVerifyFailed extends Error {
+    result: OpsVerificationFailure;
+    static get code(): string;
+    readonly code: string;
+    constructor(message: string, result: OpsVerificationFailure);
+}
+/**
+ * Originator Profile 検証失敗
+ *
+ * Originator Profile の検証に失敗しました。次の原因で使用されます。
+ *
+ * - Core Profile の検証に失敗した
+ * - Profile Annotation の検証に失敗した
+ * - Web Media Profile の検証に失敗した
+ *
+ * ここでの検証の失敗とは、次の原因を含みます。
+ *
+ * - 復号に失敗した
+ * - Core Profile の検証結果が見つからなかった
+ * - Profile Annotation 発行者の Core Profile が見つからなかった
+ * - Web Media Profile 発行者の Core Profile が見つからなかった
+ * - 署名の検証に失敗した
+ **/
+declare class OpVerifyFailed extends Error {
+    result: OpVerificationFailure;
+    static get code(): string;
+    readonly code: string;
+    constructor(message: string, result: OpVerificationFailure);
+}
+
+type Certificate = Certificate$1 | JapaneseExistenceCertificate;
+/** Originator Profile 復号失敗 */
+type OpDecodingFailure = {
+    core: JwtVcDecodingResult<CoreProfile>;
+    annotations?: JwtVcDecodingResult<Certificate>[];
+    media?: JwtVcDecodingResult<WebMediaProfile>;
+};
+/** 復号済み Originator Profile */
+type DecodedOp = {
+    core: UnverifiedJwtVc<CoreProfile>;
+    annotations?: UnverifiedJwtVc<Certificate>[];
+    media: UnverifiedJwtVc<WebMediaProfile>;
+};
+/** Originator Profile 復号結果 */
+type OpDecodingResult = DecodedOp | OpInvalid;
+/** Originator Profile Set 復号失敗 */
+type OpsDecodingFailure = OpDecodingResult[];
+/** 復号済み Originator Profile Set */
+type DecodedOps = DecodedOp[];
+/** Originator Profile Set 復号結果 */
+type OpsDecodingResult = DecodedOps | OpsInvalid;
+/** Originator Profile 検証失敗 */
+type OpVerificationFailure = {
+    core: JwtVcVerificationResult<CoreProfile> | CoreProfileNotFound<CoreProfile>;
+    annotations?: (JwtVcVerificationResult<Certificate> | CoreProfileNotFound<Certificate>)[];
+    media?: JwtVcVerificationResult<WebMediaProfile> | CoreProfileNotFound<WebMediaProfile>;
+};
+/** 検証済み Originator Profile */
+type VerifiedOp = {
+    core: VerifiedJwtVc<CoreProfile>;
+    annotations?: VerifiedJwtVc<Certificate>[];
+    media?: VerifiedJwtVc<WebMediaProfile>;
+};
+/** Originator Profile 検証結果 */
+type OpVerificationResult = VerifiedOp | OpVerifyFailed;
+/** Originator Profile Set 検証失敗 */
+type OpsVerificationFailure = OpVerificationResult[];
+/** 検証済み Originator Profile Set */
+type VerifiedOps = VerifiedOp[];
+/** Originator Profile Set 検証結果 */
+type OpsVerificationResult = VerifiedOps | OpsInvalid | OpsVerifyFailed;
+
+/**
+ * Originator Profile Set の復号
+ * @param ops Originator Profile Set
+ * @returns 復号結果
+ */
+declare function decodeOps(ops: OriginatorProfileSet): OpsDecodingResult;
+
+/**
+ * Originator Profile Set の検証者の作成
+ * @param ops Originator Profile Set
+ * @param keys Core Profile の発行者の検証鍵
+ * @param issuer Core Profile の発行者
+ * @param validator バリデーター
+ * @returns 検証者
+ */
+declare function OpsVerifier(ops: OriginatorProfileSet, keys: Keys, issuer: string | string[], validator?: typeof VcValidator): () => Promise<OpsVerificationResult>;
+
+declare class SiteProfileInvalid extends Error {
+    result: SpVerificationFailure;
+    static get code(): "ERR_SITE_PROFILE_INVALID";
+    readonly code: "ERR_SITE_PROFILE_INVALID";
+    constructor(message: string, result: SpVerificationFailure);
+}
+declare class SiteProfileVerifyFailed extends Error {
+    result: SpVerificationFailure;
+    static get code(): "ERR_SITE_PROFILE_VERIFY_FAILED";
+    readonly code: "ERR_SITE_PROFILE_VERIFY_FAILED";
+    constructor(message: string, result: SpVerificationFailure);
+}
+
+/** Site Profile 検証失敗 */
+type SpVerificationFailure = {
+    originators: OpsVerificationResult;
+    credential?: JwtVcVerificationResult<WebsiteProfile> | JwtVcDecodingResult<WebsiteProfile> | CoreProfileNotFound<WebsiteProfile>;
+};
+type VerifiedSp = {
+    originators: VerifiedOps;
+    credential: VerifiedJwtVc<WebsiteProfile>;
+};
+type SpVerificationResult = VerifiedSp | SiteProfileInvalid | SiteProfileVerifyFailed;
+
+/**
+ * Site Profile の検証者の作成
+ * @param sp Site Profile
+ * @param keys Core Profile の発行者の検証鍵
+ * @param issuer Core Profile の発行者
+ * @param origin 提示するWebサイトを識別するための RFC 6454 オリジン
+ * @param verifyOrigin WSPが提示されたWebサイトのorigin引数との一致性検証の可否 (デフォルト: 有効)
+ * @param validator バリデーター
+ * @returns 検証者
+ */
+declare function SpVerifier(sp: SiteProfile, keys: Keys, issuer: string | string[], origin: URL["origin"], verifyOrigin?: boolean, validator?: typeof VcValidator): () => Promise<SpVerificationResult>;
+
+/** 認証制度ペイロードの確認のためのバリデーター */
+declare function CertificationSystemValidator(): (payload: unknown) => true | CertificationSystemValidationFailed;
+type CertificationSystemValidator = ReturnType<typeof CertificationSystemValidator>;
+/**
+ * 認証制度の検証
+ * @param payload ペイロード
+ * @return 検証結果
+ */
+declare function validateCertificationSystem(payload: unknown): CertificationSystem | CertificationSystemValidationFailed;
+
+/**
+ * URLオリジンが対象のオリジンの中に含まれているのか検証する
+ * @param origin 対象とするオリジン
+ * @param allowedOrigins 情報の対象となるオリジン
+ * @returns 検証結果: allowedOriginsの中にoriginが含まれていればtrue, それ以外ならfalse
+ */
+declare function verifyAllowedOrigin(origin: URL["origin"], allowedOrigins: AllowedOrigin): boolean;
+
+export { type AdProfilePair, type CaDecodingFailure, type CaDecodingResult, CaInvalid, type CaVerificationFailure, type CaVerificationResult, CaVerifier, CaVerifyFailed, type CasItem, type CasVerificationFailure, type CasVerificationResult, CasVerifyFailed, type Certificate, CertificationSystemValidationFailed, CertificationSystemValidator, CoreProfileNotFound, type DecodeResult, type DecodedCa, type DecodedOp, type DecodedOps, type IntegrityVerifyResult, type OpDecodingFailure, type OpDecodingResult, OpInvalid, type OpVerificationFailure, type OpVerificationResult, OpVerifyFailed, type OpsDecodingFailure, type OpsDecodingResult, OpsInvalid, type OpsVerificationFailure, type OpsVerificationResult, OpsVerifier, OpsVerifyFailed, ProfileBodyExtractFailed, ProfileBodyVerifyFailed, ProfileClaimsValidationFailed, ProfileGenericError, type ProfilePair, ProfileTokenVerifyFailed, type Profiles, ProfilesResolveFailed, ProfilesVerifyFailed, SiteProfileInvalid, SiteProfileVerifyFailed, type SpVerificationFailure, type SpVerificationResult, SpVerifier, TargetIntegrityAlgorithm, type VerifiedCa, type VerifiedCas, type VerifiedOp, type VerifiedOps, type VerifiedSp, type VerifyIntegrity, type VerifyResult, VerifyResultFactory, type VerifyResults, type VerifyTokenResult, type WebsiteProfilePair, article, caId, caUrl, certificate, cp, decodeOps, normalizeCasItem, opId, patch, validateCertificationSystem, verifyAllowedOrigin, verifyCas, verifyDigestSri, verifyIntegrity, wmp, wsp };