@metamask/snaps-utils/dist/snaps.d.mts

A collection of utilities for MetaMask Snaps

import type { SubjectPermissions, PermissionConstraint } from "@metamask/permission-controller";
import type { BlockReason } from "@metamask/snaps-registry";
import { type SnapId, type Snap as TruncatedSnap } from "@metamask/snaps-sdk";
import type { Struct } from "@metamask/superstruct";
import type { LocalizationFile } from "./localization.mjs";
import type { InitialConnections, SnapManifest, SnapPermissions } from "./manifest/validation.mjs";
import type { FetchedSnapFiles, SnapsPermissionRequest } from "./types.mjs";
import { SnapIdPrefixes } from "./types.mjs";
export declare const PROPOSED_NAME_REGEX: RegExp;
export declare enum SnapStatus {
    Installing = "installing",
    Updating = "updating",
    Running = "running",
    Stopped = "stopped",
    Crashed = "crashed"
}
export declare enum SnapStatusEvents {
    Start = "START",
    Stop = "STOP",
    Crash = "CRASH",
    Update = "UPDATE"
}
export type StatusContext = {
    snapId: SnapId;
};
export type StatusEvents = {
    type: SnapStatusEvents;
};
export type StatusStates = {
    value: SnapStatus;
    context: StatusContext;
};
export type Status = StatusStates['value'];
export type VersionHistory = {
    origin: string;
    version: string;
    date: number;
};
export type SnapAuxilaryFile = {
    path: string;
    value: string;
};
export type PersistedSnap = Snap;
/**
 * A Snap as it exists in {@link SnapController} state.
 */
export type Snap = TruncatedSnap & {
    /**
     * The initial connections of the Snap, optional, requested on installation.
     */
    initialConnections?: InitialConnections;
    /**
     * The initial permissions of the Snap, which will be requested when it is
     * installed.
     */
    initialPermissions: SnapPermissions;
    /**
     * The source code of the Snap.
     */
    sourceCode: string;
    /**
     * The Snap's manifest file.
     */
    manifest: SnapManifest;
    /**
     * Information detailing why the snap is blocked.
     */
    blockInformation?: BlockReason;
    /**
     * The current status of the Snap, e.g. whether it's running or stopped.
     */
    status: Status;
    /**
     * The version history of the Snap.
     * Can be used to derive when the Snap was installed, when it was updated to a certain version and who requested the change.
     */
    versionHistory: VersionHistory[];
    /**
     * Static auxiliary files that can be loaded at runtime.
     */
    auxiliaryFiles?: SnapAuxilaryFile[];
    /**
     * Localization files which are used to translate the manifest.
     */
    localizationFiles?: LocalizationFile[];
    /**
     * Flag to signal whether this snap was preinstalled or not.
     *
     * A lack of specifying this option will be deemed as not preinstalled.
     */
    preinstalled?: boolean;
    /**
     * Flag to signal whether this snap is removable or not.
     *
     * A lack of specifying this option will be deemed as removable.
     */
    removable?: boolean;
    /**
     * Flag to signal whether this snap should be hidden from the user or not.
     */
    hidden?: boolean;
    /**
     * Flag to signal whether this snap should hide the Snap branding like header or avatar in the UI or not.
     */
    hideSnapBranding?: boolean;
};
export type TruncatedSnapFields = 'id' | 'initialPermissions' | 'version' | 'enabled' | 'blocked';
/**
 * Calculates the Base64-encoded SHA-256 digest of all required Snap files.
 *
 * @param files - All required Snap files to be included in the checksum.
 * @returns The Base64-encoded SHA-256 digest of the source code.
 */
export declare function getSnapChecksum(files: FetchedSnapFiles): Promise<string>;
/**
 * Checks whether the `source.shasum` property of a Snap manifest matches the
 * shasum of the snap.
 *
 * @param files - All required Snap files to be included in the checksum.
 * @param errorMessage - The error message to throw if validation fails.
 */
export declare function validateSnapShasum(files: FetchedSnapFiles, errorMessage?: string): Promise<void>;
export declare const LOCALHOST_HOSTNAMES: readonly ["localhost", "127.0.0.1", "[::1]"];
export declare const BaseSnapIdStruct: Struct<string, null>;
export declare const LocalSnapIdStruct: Struct<string, null>;
export declare const NpmSnapIdStruct: Struct<string, null>;
export declare const HttpSnapIdStruct: Struct<string, null>;
export declare const SnapIdPrefixStruct: Struct<string, null>;
export declare const SnapIdStruct: Struct<string, null>;
/**
 * Extracts the snap prefix from a snap ID.
 *
 * @param snapId - The snap ID to extract the prefix from.
 * @returns The snap prefix from a snap id, e.g. `npm:`.
 */
export declare function getSnapPrefix(snapId: string): SnapIdPrefixes;
/**
 * Strips snap prefix from a full snap ID.
 *
 * @param snapId - The snap ID to strip.
 * @returns The stripped snap ID.
 */
export declare function stripSnapPrefix(snapId: string): string;
/**
 * Check if the given value is a valid snap ID. This function is a type guard,
 * and will narrow the type of the value to `SnapId` if it returns `true`.
 *
 * @param value - The value to check.
 * @returns `true` if the value is a valid snap ID, and `false` otherwise.
 */
export declare function isSnapId(value: unknown): value is SnapId;
/**
 * Assert that the given value is a valid snap ID.
 *
 * @param value - The value to check.
 * @throws If the value is not a valid snap ID.
 */
export declare function assertIsValidSnapId(value: unknown): asserts value is SnapId;
/**
 * Utility function to check if an origin has permission (and caveat) for a particular snap.
 *
 * @param permissions - An origin's permissions object.
 * @param snapId - The id of the snap.
 * @returns A boolean based on if an origin has the specified snap.
 */
export declare function isSnapPermitted(permissions: SubjectPermissions<PermissionConstraint>, snapId: SnapId): boolean;
/**
 * Checks whether the passed in requestedPermissions is a valid
 * permission request for a `wallet_snap` permission.
 *
 * @param requestedPermissions - The requested permissions.
 * @throws If the criteria is not met.
 */
export declare function verifyRequestedSnapPermissions(requestedPermissions: unknown): asserts requestedPermissions is SnapsPermissionRequest;
export type { Snap as TruncatedSnap } from "@metamask/snaps-sdk";
//# sourceMappingURL=snaps.d.mts.map