minauth/dist/plugin/plugintype.d.ts

A TypeScript library for building authentication systems on top of the Mina blockchain and other zero-knowledge proofs solutions.

import { Router } from 'express';
import { JsonProof } from 'o1js';
import { InterfaceKind, WithInterfaceTag, RetType, TsInterfaceType, FpInterfaceType } from './interfacekind.js';
import { Decoder, EncodeDecoder } from './encodedecoder.js';
import { Logger } from './logger.js';
import { VerificationKey } from '../common/verificationkey.js';
/**
 * Information about the validity of a proof.
 * In the future there could be more information that plugin wants to return.
 */
export type OutputValidity = {
    isValid: true;
} | {
    isValid: false;
    reason: string;
};
export declare const outputValid: OutputValidity;
export declare const outputInvalid: (reason: string) => OutputValidity;
/**
 * MinAuth plugins must implement this interface.
 * The interface type is parameterized by an interface kind:
 * - `TsInterfaceType` for idiomatic typescript interface
 * - `FpInterfaceType` for functional style interface
 * that is used by the library to provide safety and composability.
 * A plugin author is free to implement the plugin using any interface,
 * the library will convert it to the functional style interface.
 * A plugin is a server-side component that can be used to verify a proof.
 * It may defined custom routes and handlers that are necessary for the
 * client counterpart to generate a proof.
 * The two remainng arguments `Input` and `Output` parametrize
 * the plugin's input and output.
 * `Input` will usually contain a zk-proof and auxiliary data
 * required to establish public data against which the proof was made.
 * and `Output` will wrap the output of the proof.
 */
export interface IMinAuthPlugin<InterfaceType extends InterfaceKind, Input, Output> extends WithInterfaceTag<InterfaceType> {
    /**
     * This is meant to build the public inputs for the proof and verify
     * the proof using compiled verifier zk-circuit.
     * The input will usually contain a zk-proof and auxiliary data
     * required to establish public data against which the proof was made.
     */
    verifyAndGetOutput(input: Input): RetType<InterfaceType, Output>;
    /**
     * Plugins should be able to confirm the validity produced outputs.
     * Most outputs along with underlying proofs can get outdated by
     * changes to the data that the proof is based on.
     *
     * This function shouldn't error out unless an internal error occurred during
     * validation.
     */
    checkOutputValidity(output: Output): RetType<InterfaceType, OutputValidity>;
    /** Custom routes and handlers. Will be installed under `/plugins/<plugin name>` */
    readonly customRoutes: Router;
}
/** Type parameter extraction (inference) helpers. */
type ExtractPluginInputType<T> = T extends IMinAuthPlugin<infer _1, infer Input, infer _2> ? Input : never;
/** Type parameter extraction (inference) helpers. */
type ExtractPluginOutputType<T> = T extends IMinAuthPlugin<infer _1, infer _2, infer Output> ? Output : never;
/**
 * A plugin factory is responsible for initializing a plugin given the configuration.
 * A module defining a plugin must export a value of this type as `default`.
 * For the explanation of the interface type parameter, see `IMinAuthPlugin`.
 */
export interface IMinAuthPluginFactory<InterfaceType extends InterfaceKind, PluginType extends IMinAuthPlugin<InterfaceType, Input, Output>, Configuration, Input = ExtractPluginInputType<PluginType>, Output = ExtractPluginOutputType<PluginType>> extends WithInterfaceTag<InterfaceType> {
    /**
     * Initialize the plugin given the configuration.
     * The underlying zk program is typically compiled here.
     * @param cfg The plugin configuration
     * @param outputValidityUpdate: a callback that the plugin can use to notify about
     * the validity of outputs it has generated.
     */
    initialize(cfg: Configuration, logger: Logger): RetType<InterfaceType, PluginType>;
    /** Decoder for the plugin configuration. */
    readonly configurationDec: Decoder<InterfaceType, Configuration>;
    /** The decoder for the plugin inputs. */
    readonly inputDecoder: Decoder<InterfaceType, Input>;
    /** Encoder/Decoder for the plugins outputs. */
    readonly outputEncDec: EncodeDecoder<InterfaceType, Output>;
}
/**
 * IMinAuthProver defines the part of MinAuth plugin that is used by the client
 * - the party that wants to present a proof qualifying for access to a resource.
 * The interface type is parameterized by an interface kind:
 * - `TsInterfaceType` for idiomatic typescript interface
 * - `FpInterfaceType` for functional style interface
 * that is usd by the library to provide safety and composability.
 * A plugin author is free to implement the prover using any interface,
 * the library will convert it to the functional style interface for internal use.
 *
 * @param InterfaceType - the interface kind
 * @param PublicInputArgs - used to parameterize the way in which public inputs
 * are prepared for the proof.
 * @param PublicInput - the type of public input needed to produce a proof.
 * @param PrivateInput - the type of private input needed to produce a proof.
 */
export interface IMinAuthProver<InterfaceType extends InterfaceKind, PublicInputArgs, PublicInput, PrivateInput> extends WithInterfaceTag<InterfaceType> {
    prove(publicInput: PublicInput, secretInput: PrivateInput): RetType<InterfaceType, JsonProof>;
    fetchPublicInputs(args: PublicInputArgs): RetType<InterfaceType, PublicInput>;
}
type ExtractProverPublicInputArgsType<T> = T extends IMinAuthProver<infer _1, infer PublicInputArgs, infer _2, infer _3> ? PublicInputArgs : never;
type ExtractProverPublicInputType<T> = T extends IMinAuthProver<infer _1, infer _2, infer PublicInput, infer _3> ? PublicInput : never;
type ExtractProverPrivateInputType<T> = T extends IMinAuthProver<infer _1, infer _2, infer _3, infer PrivateInput> ? PrivateInput : never;
/**
 * IMinAuthProverFactory encapsulates the logic of creating a prover.
 * The meaning of its type parameters can be looked up in the documentation
 * of `IMinAuthProver`.
 *
 * @param cfg The plugin configuration
 * @param compile: whether to compile the underlying zk circuit
 * @returns a prover
 */
export interface IMinAuthProverFactory<InterfaceType extends InterfaceKind, ProverType extends IMinAuthProver<InterfaceType, PublicInputArgs, PublicInput, PrivateInput>, Configuration, PublicInputArgs = ExtractProverPublicInputArgsType<ProverType>, PublicInput = ExtractProverPublicInputType<ProverType>, PrivateInput = ExtractProverPrivateInputType<ProverType>> extends WithInterfaceTag<InterfaceType> {
    initialize(cfg: Configuration, { compile }: {
        compile: boolean;
    }): RetType<InterfaceType, ProverType>;
    compile(): RetType<InterfaceType, {
        verificationKey: VerificationKey;
    }>;
}
/**
 * Convert a plugin factory from the idiomatic typescript interface to the functional style
 */
export declare const tsToFpMinAuthPlugin: <PublicInputArgs, Output>(i: IMinAuthPlugin<"ts", PublicInputArgs, Output>) => IMinAuthPlugin<"fp", PublicInputArgs, Output>;
/**
 * Convert a plugin factory from the idiomatic typescript interface to the functional style
 */
export declare const tsToFpMinAuthPluginFactory: <Configuration, Input, Output>(i: IMinAuthPluginFactory<"ts", IMinAuthPlugin<"ts", Input, Output>, Configuration, Input, Output>) => IMinAuthPluginFactory<"fp", IMinAuthPlugin<"fp", Input, Output>, Configuration, Input, Output>;
export {};