@fedify/fedify/types/sig/key.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, type Multikey } from "../vocab/vocab.js";
/**
 * Checks if the given key is valid and supported.  No-op if the key is valid,
 * otherwise throws an error.
 * @param key The key to check.
 * @param type Which type of key to check.  If not specified, the key can be
 *             either public or private.
 * @throws {TypeError} If the key is invalid or unsupported.
 */
export declare function validateCryptoKey(key: dntShim.CryptoKey, type?: "public" | "private"): void;
/**
 * Generates a key pair which is appropriate for Fedify.
 * @param algorithm The algorithm to use.  Currently only RSASSA-PKCS1-v1_5 and
 *                  Ed25519 are supported.
 * @returns The generated key pair.
 * @throws {TypeError} If the algorithm is unsupported.
 */
export declare function generateCryptoKeyPair(algorithm?: "RSASSA-PKCS1-v1_5" | "Ed25519"): Promise<dntShim.CryptoKeyPair>;
/**
 * Exports a key in JWK format.
 * @param key The key to export.  Either public or private key.
 * @returns The exported key in JWK format.  The key is suitable for
 *          serialization and storage.
 * @throws {TypeError} If the key is invalid or unsupported.
 */
export declare function exportJwk(key: dntShim.CryptoKey): Promise<dntShim.JsonWebKey>;
/**
 * Imports a key from JWK format.
 * @param jwk The key in JWK format.
 * @param type Which type of key to import, either `"public"` or `"private"`.
 * @returns The imported key.
 * @throws {TypeError} If the key is invalid or unsupported.
 */
export declare function importJwk(jwk: dntShim.JsonWebKey, type: "public" | "private"): Promise<dntShim.CryptoKey>;
/**
 * Options for {@link fetchKey}.
 * @since 1.3.0
 */
export interface FetchKeyOptions {
    /**
     * The document loader for loading remote JSON-LD documents.
     */
    documentLoader?: DocumentLoader;
    /**
     * The context loader for loading remote JSON-LD contexts.
     */
    contextLoader?: DocumentLoader;
    /**
     * The key cache to use for caching public keys.
     * @since 0.12.0
     */
    keyCache?: KeyCache;
    /**
     * The OpenTelemetry tracer provider to use for tracing.  If omitted,
     * the global tracer provider is used.
     * @since 1.3.0
     */
    tracerProvider?: TracerProvider;
}
/**
 * The result of {@link fetchKey}.
 * @since 1.3.0
 */
export interface FetchKeyResult<T extends CryptographicKey | Multikey> {
    /**
     * The fetched (or cached) key.
     */
    readonly key: T & {
        publicKey: dntShim.CryptoKey;
    } | null;
    /**
     * Whether the key is fetched from the cache.
     */
    readonly cached: boolean;
}
/**
 * Fetches a {@link CryptographicKey} or {@link Multikey} from the given URL.
 * If the given URL contains an {@link Actor} object, it tries to find
 * the corresponding key in the `publicKey` or `assertionMethod` property.
 * @typeParam T The type of the key to fetch.  Either {@link CryptographicKey}
 *              or {@link Multikey}.
 * @param keyId The URL of the key.
 * @param cls The class of the key to fetch.  Either {@link CryptographicKey}
 *            or {@link Multikey}.
 * @param options Options for fetching the key.  See {@link FetchKeyOptions}.
 * @returns The fetched key or `null` if the key is not found.
 * @since 1.3.0
 */
export declare function fetchKey<T extends CryptographicKey | Multikey>(keyId: URL | string, cls: (new (...args: any[]) => T) & {
    fromJsonLd(jsonLd: unknown, options: {
        documentLoader?: DocumentLoader;
        contextLoader?: DocumentLoader;
        tracerProvider?: TracerProvider;
    }): Promise<T>;
}, options?: FetchKeyOptions): Promise<FetchKeyResult<T>>;
/**
 * A cache for storing cryptographic keys.
 * @since 0.12.0
 */
export interface KeyCache {
    /**
     * Gets a key from the cache.
     * @param keyId The key ID.
     * @returns The key if found, `null` if the key is not available (e.g.,
     *          fetching the key was tried but failed), or `undefined`
     *          if the cache is not available.
     */
    get(keyId: URL): Promise<CryptographicKey | Multikey | null | undefined>;
    /**
     * Sets a key to the cache.
     *
     * Note that this caches unavailable keys (i.e., `null`) as well,
     * and it is recommended to make unavailable keys expire after a short period.
     * @param keyId The key ID.
     * @param key The key to cache.  `null` means the key is not available
     *            (e.g., fetching the key was tried but failed).
     */
    set(keyId: URL, key: CryptographicKey | Multikey | null): Promise<void>;
}
//# sourceMappingURL=key.d.ts.map