@enbox/api/dist/types/web5.d.ts

SDK for accessing the features and capabilities of Web5

/**
 * NOTE: Added reference types here to avoid a `pnpm` bug during build.
 * https://github.com/TBD54566975/web5-js/pull/507
 */
import type { DwnDataEncodedRecordsWriteMessage, DwnProtocolDefinition, HdIdentityVault, Permission, WalletConnectOptions, Web5Agent } from '@enbox/agent';
import { DidApi } from './did-api.js';
import { DwnApi } from './dwn-api.js';
import { VcApi } from './vc-api.js';
/** Override defaults configured during the technical preview phase. */
export type TechPreviewOptions = {
    /** Override default dwnEndpoints provided for technical preview. */
    dwnEndpoints?: string[];
};
/** Override defaults for DID creation. */
export type DidCreateOptions = {
    /** Override default dwnEndpoints provided during DID creation. */
    dwnEndpoints?: string[];
};
/**
 * Represents a permission request for a protocol definition.
 */
export type ConnectPermissionRequest = {
    /**
     * The protocol definition for the protocol being requested.
     */
    protocolDefinition: DwnProtocolDefinition;
    /**
     * The permissions being requested for the protocol. If none are provided, the default is to request all permissions.
     */
    permissions?: Permission[];
};
/**
 * Options for connecting to a Web5 agent. This includes the ability to connect to an external wallet.
 *
 * NOTE: the returned `ConnectPermissionRequest` type is different to the `ConnectPermissionRequest` type in the `@enbox/agent` package.
 */
export type ConnectOptions = Omit<WalletConnectOptions, 'permissionRequests'> & {
    /** The user friendly name of the client/app to be displayed when prompting end-user with permission requests. */
    displayName: string;
    /**
     * The permissions that are being requested for the connected DID.
     * This is used to create the {@link ConnectPermissionRequest} for the wallet connect flow.
     */
    permissionRequests: ConnectPermissionRequest[];
};
/** Optional overrides that can be provided when calling {@link Web5.connect}. */
export type Web5ConnectOptions = {
    /**
     * When specified, external wallet connect flow is triggered.
     * This param currently will not work in apps that are currently connected.
     * It must only be invoked at registration with a reset and empty DWN and agent.
     */
    walletConnectOptions?: ConnectOptions;
    /**
     * Provide a {@link Web5Agent} implementation. Defaults to creating a local
     * {@link Web5UserAgent} if one isn't provided
     **/
    agent?: Web5Agent;
    /**
     * Provide an instance of a {@link HdIdentityVault} implementation. Defaults to
     * a LevelDB-backed store with an insecure, static unlock password if one
     * isn't provided. To allow the app user to enter a secure password of
     * their choosing, provide an initialized {@link HdIdentityVault} instance.
     **/
    agentVault?: HdIdentityVault;
    /** Specify an existing DID to connect to. */
    connectedDid?: string;
    /**
     * The Web5 app `password` is used to protect data on the device the application is running on.
     *
     * Only the end user should know this password: it should not be stored on the device or
     * transmitted over the network.
     *
     * This password is crucial for the security of an identity vault that stores the local Agent's
     * cryptographic keys and decentralized identifier (DID). The vault's content is encrypted using
     * the password, making it accessible only to those who know the password.
     *
     * App users should be advised to use a strong, unique passphrase that is not shared across
     * different services or applications. The password should be kept confidential and not be
     * exposed to unauthorized entities. Losing the password may result in irreversible loss of
     * access to the vault's contents.
     */
    password?: string;
    /**
     * The `recoveryPhrase` is a unique, secure key for recovering the identity vault.
     *
     * This phrase is a series of 12 words generated securely and known only to the user. It plays a
     * critical role in the security of the identity vault by enabling the recovery of the vault's
     * contents, including cryptographic keys and the Agent's decentralized identifier (DID), across
     * different devices or if the original device is compromised or lost.
     *
     * The recovery phrase is akin to a master key, as anyone with access to this phrase can restore
     * and access the vault's contents. It’s combined with the app `password` to encrypt the vault's
     * content.
     *
     * Unlike a password, the recovery phrase is not intended for regular use but as a secure backup
     * method for vault recovery. Losing this phrase can result in permanent loss of access to the
     * vault's contents, as it cannot be reset or retrieved if forgotten.
     *
     * Users should treat the recovery phrase with the highest level of security, ensuring it is
     * never shared, stored online, or exposed to potential threats. It is the user's responsibility
     * to keep this phrase safe to maintain the integrity and accessibility of their secured data. It
     * is recommended to write it down and store it in a secure location, separate from the device and
     * digital backups.
     */
    recoveryPhrase?: string;
    /**
     * Enable synchronization of DWN records between local and remote DWNs.
     * Sync defaults to running every 2 minutes and can be set to any value accepted by `ms()`.
     * To disable sync set to 'off'.
     */
    sync?: string;
    /**
     * Override defaults configured during the technical preview phase.
     * See {@link TechPreviewOptions} for available options.
     */
    techPreview?: TechPreviewOptions;
    /**
     * Override defaults configured options for creating a DID during connect.
     * See {@link DidCreateOptions} for available options.
     */
    didCreateOptions?: DidCreateOptions;
    /**
     * If the `registration` option is provided, the agent DID and the connected DID will be registered with the DWN endpoints provided by `techPreview` or `didCreateOptions`.
     *
     * If registration fails, the `onFailure` callback will be called with the error.
     * If registration is successful, the `onSuccess` callback will be called.
     */
    registration?: {
        /** Called when all of the DWN registrations are successful */
        onSuccess: () => void;
        /** Called when any of the DWN registrations fail */
        onFailure: (error: any) => void;
    };
};
/**
 * Represents the result of the Web5 connection process, including the Web5 instance,
 * the connected decentralized identifier (DID), and optionally the recovery phrase used
 * during the agent's initialization.
 */
export type Web5ConnectResult = {
    /** The Web5 instance, providing access to the agent, DID, DWN, and VC APIs. */
    web5: Web5;
    /** The DID that has been connected or created during the connection process. */
    did: string;
    /**
     * The first time a Web5 agent is initialized, the recovery phrase that was used to generate the
     * agent's DID and keys is returned. This phrase can be used to recover the agent's vault contents
     * and should be stored securely by the user.
     */
    recoveryPhrase?: string;
    /**
     * The resulting did of a successful wallet connect. Only returned on success if
     * {@link WalletConnectOptions} was provided.
     */
    delegateDid?: string;
};
/**
 * Parameters that are passed to Web5 constructor.
 *
 * @see {@link Web5ConnectOptions}
 */
export type Web5Params = {
    /**
     * A {@link Web5Agent} instance that handles DIDs, DWNs and VCs requests. The agent manages the
     * user keys and identities, and is responsible to sign and verify messages.
     */
    agent: Web5Agent;
    /** The DID of the tenant under which all DID, DWN, and VC requests are being performed. */
    connectedDid: string;
    /** The DID that will be signing Web5 messages using grants from the connectedDid */
    delegateDid?: string;
};
/**
 * The main Web5 API interface. It manages the creation of a DID if needed, the connection to the
 * local DWN and all the web5 main foundational APIs such as VC, syncing, etc.
 */
export declare class Web5 {
    /**
     * A {@link Web5Agent} instance that handles DIDs, DWNs and VCs requests. The agent manages the
     * user keys and identities, and is responsible to sign and verify messages.
     */
    agent: Web5Agent;
    /** Exposed instance to the DID APIs, allow users to create and resolve DIDs  */
    did: DidApi;
    /** Exposed instance to the DWN APIs, allow users to read/write records */
    dwn: DwnApi;
    /** Exposed instance to the VC APIs, allow users to issue, present and verify VCs */
    vc: VcApi;
    constructor({ agent, connectedDid, delegateDid }: Web5Params);
    /**
     * Connects to a {@link Web5Agent}. Defaults to creating a local {@link Web5UserAgent} if one
     * isn't provided.
     *
     * If `walletConnectOptions` are provided, a WalletConnect flow will be initiated to import a delegated DID from an external wallet.
     * If there is a failure at any point during connecting and processing grants, all created DIDs and Identities as well as the provided grants
     * will be cleaned up and an error thrown. This allows for subsequent Connect attempts to be made without any errors.
     *
     * @param options - Optional overrides that can be provided when calling {@link Web5.connect}.
     * @returns A promise that resolves to a {@link Web5} instance and the connected DID.
     */
    static connect({ agent, agentVault, connectedDid, password, recoveryPhrase, sync, techPreview, didCreateOptions, registration, walletConnectOptions, }?: Web5ConnectOptions): Promise<Web5ConnectResult>;
    /**
     * Cleans up the DID, Keys and Identity. Primarily used by a failed WalletConnect import.
     * Does not throw on error, but logs to console.
     */
    private static cleanUpIdentity;
    /**
     * A static method to process connected grants for a delegate DID.
     *
     * This will store the grants as the DWN owner to be used later when impersonating the connected DID.
     */
    static processConnectedGrants({ grants, agent, delegateDid }: {
        grants: DwnDataEncodedRecordsWriteMessage[];
        agent: Web5Agent;
        delegateDid: string;
    }): Promise<string[]>;
}
//# sourceMappingURL=web5.d.ts.map