@fedify/fedify/types/sig/ld.d.ts

An ActivityPub server framework

import * as dntShim from "../_dnt.shims.js";
import { type TracerProvider } from "@opentelemetry/api";
import { type DocumentLoader } from "../runtime/docloader.js";
import { CryptographicKey } from "../vocab/vocab.js";
import { type KeyCache } from "./key.js";
/**
 * A signature of a JSON-LD document.
 * @since 1.0.0
 */
export interface Signature {
    "@context"?: "https://w3id.org/identity/v1";
    type: "RsaSignature2017";
    id?: string;
    creator: string;
    created: string;
    signatureValue: string;
}
/**
 * Attaches a LD signature to the given JSON-LD document.
 * @param jsonLd The JSON-LD document to attach the signature to.  It is not
 *               modified.
 * @param signature The signature to attach.
 * @returns The JSON-LD document with the attached signature.
 * @throws {TypeError} If the input document is not a valid JSON-LD document.
 * @since 1.0.0
 */
export declare function attachSignature(jsonLd: unknown, signature: Signature): {
    signature: Signature;
};
/**
 * Options for creating Linked Data Signatures.
 * @since 1.0.0
 */
export interface CreateSignatureOptions {
    /**
     * The context loader for loading remote JSON-LD contexts.
     */
    contextLoader?: DocumentLoader;
    /**
     * The time when the signature was created.  If not specified, the current
     * time will be used.
     */
    created?: dntShim.Temporal.Instant;
}
/**
 * Creates a LD signature for the given JSON-LD document.
 * @param jsonLd The JSON-LD document to sign.
 * @param privateKey The private key to sign the document.
 * @param keyId The ID of the public key that corresponds to the private key.
 * @param options Additional options for creating the signature.
 *                See also {@link CreateSignatureOptions}.
 * @return The created signature.
 * @throws {TypeError} If the private key is invalid or unsupported.
 * @since 1.0.0
 */
export declare function createSignature(jsonLd: unknown, privateKey: dntShim.CryptoKey, keyId: URL, { contextLoader, created }?: CreateSignatureOptions): Promise<Signature>;
/**
 * Options for signing JSON-LD documents.
 * @since 1.0.0
 */
export interface SignJsonLdOptions extends CreateSignatureOptions {
    /**
     * The OpenTelemetry tracer provider for tracing the signing process.
     * If omitted, the global tracer provider is used.
     * @since 1.3.0
     */
    tracerProvider?: TracerProvider;
}
/**
 * Signs the given JSON-LD document with the private key and returns the signed
 * JSON-LD document.
 * @param jsonLd The JSON-LD document to sign.
 * @param privateKey The private key to sign the document.
 * @param keyId The key ID to use in the signature.  It will be used by the
 *              verifier to fetch the corresponding public key.
 * @param options Additional options for signing the document.
 *                See also {@link SignJsonLdOptions}.
 * @returns The signed JSON-LD document.
 * @throws {TypeError} If the private key is invalid or unsupported.
 * @since 1.0.0
 */
export declare function signJsonLd(jsonLd: unknown, privateKey: dntShim.CryptoKey, keyId: URL, options: SignJsonLdOptions): Promise<{
    signature: Signature;
}>;
interface SignedJsonLd {
    signature: Signature;
}
/**
 * Checks if the given JSON-LD document has a Linked Data Signature.
 * @param jsonLd The JSON-LD document to check.
 * @returns `true` if the document has a signature; `false` otherwise.
 * @since 1.0.0
 */
export declare function hasSignature(jsonLd: unknown): jsonLd is SignedJsonLd;
/**
 * Detaches Linked Data Signatures from the given JSON-LD document.
 * @param jsonLd The JSON-LD document to modify.
 * @returns The modified JSON-LD document.  If the input document does not
 *          contain a signature, the original document is returned.
 * @since 1.0.0
 */
export declare function detachSignature(jsonLd: unknown): unknown;
/**
 * Options for verifying Linked Data Signatures.
 * @since 1.0.0
 */
export interface VerifySignatureOptions {
    /**
     * The document loader to use for fetching the public key.
     */
    documentLoader?: DocumentLoader;
    /**
     * The context loader to use for JSON-LD context retrieval.
     */
    contextLoader?: DocumentLoader;
    /**
     * The key cache to use for caching public keys.
     */
    keyCache?: KeyCache;
    /**
     * The OpenTelemetry tracer provider for tracing the verification process.
     * If omitted, the global tracer provider is used.
     * @since 1.3.0
     */
    tracerProvider?: TracerProvider;
}
/**
 * Verifies Linked Data Signatures of the given JSON-LD document.
 * @param jsonLd The JSON-LD document to verify.
 * @param options Options for verifying the signature.
 * @returns The public key that signed the document or `null` if the signature
 *          is invalid or the key is not found.
 * @since 1.0.0
 */
export declare function verifySignature(jsonLd: unknown, options?: VerifySignatureOptions): Promise<CryptographicKey | null>;
/**
 * Options for verifying JSON-LD documents.
 */
export interface VerifyJsonLdOptions extends VerifySignatureOptions {
}
/**
 * Verify the authenticity of the given JSON-LD document using Linked Data
 * Signatures.  If the document is signed, this function verifies the signature
 * and checks if the document is attributed to the owner of the public key.
 * If the document is not signed, this function returns `false`.
 * @param jsonLd The JSON-LD document to verify.
 * @param options Options for verifying the document.
 * @returns `true` if the document is authentic; `false` otherwise.
 */
export declare function verifyJsonLd(jsonLd: unknown, options?: VerifyJsonLdOptions): Promise<boolean>;
export {};
//# sourceMappingURL=ld.d.ts.map