@dfinity/agent
Version:
JavaScript and TypeScript library to interact with the Internet Computer
228 lines • 8.39 kB
TypeScript
import { Principal } from '@dfinity/principal';
import type { Agent } from './agent/api.ts';
export interface Cert {
tree: HashTree;
signature: Uint8Array;
delegation?: Delegation;
}
export declare enum NodeType {
Empty = 0,
Fork = 1,
Labeled = 2,
Leaf = 3,
Pruned = 4
}
export type NodePath = Array<Uint8Array | string>;
export type NodeLabel = Uint8Array & {
__nodeLabel__: void;
};
export type NodeValue = Uint8Array & {
__nodeValue__: void;
};
export type NodeHash = Uint8Array & {
__nodeHash__: void;
};
export type EmptyHashTree = [NodeType.Empty];
export type ForkHashTree = [NodeType.Fork, HashTree, HashTree];
export type LabeledHashTree = [NodeType.Labeled, NodeLabel, HashTree];
export type LeafHashTree = [NodeType.Leaf, NodeValue];
export type PrunedHashTree = [NodeType.Pruned, NodeHash];
export type HashTree = EmptyHashTree | ForkHashTree | LabeledHashTree | LeafHashTree | PrunedHashTree;
/**
* Make a human readable string out of a hash tree.
* @param tree The hash tree to convert to a string
*/
export declare function hashTreeToString(tree: HashTree): string;
interface Delegation extends Record<string, unknown> {
subnet_id: Uint8Array;
certificate: Uint8Array;
}
type VerifyFunc = (pk: Uint8Array, sig: Uint8Array, msg: Uint8Array) => Promise<boolean> | boolean;
export interface CreateCertificateOptions {
/**
* The bytes encoding the certificate to be verified
*/
certificate: Uint8Array;
/**
* The root key against which to verify the certificate
* (normally, the root key of the IC main network)
*/
rootKey: Uint8Array;
/**
* The effective canister ID of the request when verifying a response, or
* the signing canister ID when verifying a certified variable.
*/
canisterId: Principal;
/**
* BLS Verification strategy. Default strategy uses bls12_381 from @noble/curves
*/
blsVerify?: VerifyFunc;
/**
* The maximum age of the certificate in minutes. Default is 5 minutes.
* This is used to verify the time the certificate was signed, particularly for validating Delegation certificates, which can live for longer than the default window of +/- 5 minutes. If the certificate is
* older than the specified age, it will fail verification.
* @default 5
*/
maxAgeInMinutes?: number;
/**
* Overrides the maxAgeInMinutes setting and skips comparing the client's time against the certificate. Used for scenarios where the machine's clock is known to be out of sync, or for inspecting expired certificates.
* @default false
*/
disableTimeVerification?: boolean;
/**
* The agent used to sync time with the IC network, if the certificate fails the freshness check.
* If the agent does not implement the {@link HttpAgent.getTimeDiffMsecs}, {@link HttpAgent.hasSyncedTime} and {@link HttpAgent.syncTime} methods,
* time will not be synced in case of a freshness check failure.
* @default undefined
*/
agent?: Agent;
}
export declare class Certificate {
#private;
private _rootKey;
private _canisterId;
private _blsVerify;
private _maxAgeInMinutes;
cert: Cert;
/**
* Create a new instance of a certificate, automatically verifying it.
* @param {CreateCertificateOptions} options {@link CreateCertificateOptions}
* @throws if the verification of the certificate fails
*/
static create(options: CreateCertificateOptions): Promise<Certificate>;
private static createUnverified;
private constructor();
/**
* Lookup a path in the certificate tree, using {@link lookup_path}.
* @param path The path to lookup.
* @returns The result of the lookup.
*/
lookup_path(path: NodePath): LookupResult;
/**
* Lookup a subtree in the certificate tree, using {@link lookup_subtree}.
* @param path The path to lookup.
* @returns The result of the lookup.
*/
lookup_subtree(path: NodePath): SubtreeLookupResult;
private verify;
private _checkDelegationAndGetKey;
}
/**
* Utility function to constrain the type of a lookup result
* @param result the result of a lookup
* @returns {Uint8Array | undefined} the value if the lookup was found, `undefined` otherwise
*/
export declare function lookupResultToBuffer(result: LookupResult): Uint8Array | undefined;
/**
* @param t The hash tree to reconstruct
*/
export declare function reconstruct(t: HashTree): Promise<Uint8Array>;
/**
* Creates a domain separator for hashing by encoding the input string
* with its length as a prefix.
* @param s - The input string to encode.
* @returns A Uint8Array containing the encoded domain separator.
*/
export declare function domain_sep(s: string): Uint8Array;
export declare enum LookupPathStatus {
Unknown = "Unknown",
Absent = "Absent",
Found = "Found",
Error = "Error"
}
export interface LookupPathResultAbsent {
status: LookupPathStatus.Absent;
}
export interface LookupPathResultUnknown {
status: LookupPathStatus.Unknown;
}
export interface LookupPathResultFound {
status: LookupPathStatus.Found;
value: Uint8Array;
}
export interface LookupPathResultError {
status: LookupPathStatus.Error;
}
export type LookupResult = LookupPathResultAbsent | LookupPathResultUnknown | LookupPathResultFound | LookupPathResultError;
export declare enum LookupSubtreeStatus {
Absent = "Absent",
Unknown = "Unknown",
Found = "Found"
}
export interface LookupSubtreeResultAbsent {
status: LookupSubtreeStatus.Absent;
}
export interface LookupSubtreeResultUnknown {
status: LookupSubtreeStatus.Unknown;
}
export interface LookupSubtreeResultFound {
status: LookupSubtreeStatus.Found;
value: HashTree;
}
export type SubtreeLookupResult = LookupSubtreeResultAbsent | LookupSubtreeResultUnknown | LookupSubtreeResultFound;
export declare enum LookupLabelStatus {
Absent = "Absent",
Unknown = "Unknown",
Found = "Found",
Less = "Less",
Greater = "Greater"
}
export interface LookupLabelResultAbsent {
status: LookupLabelStatus.Absent;
}
export interface LookupLabelResultUnknown {
status: LookupLabelStatus.Unknown;
}
export interface LookupLabelResultFound {
status: LookupLabelStatus.Found;
value: HashTree;
}
export interface LookupLabelResultGreater {
status: LookupLabelStatus.Greater;
}
export interface LookupLabelResultLess {
status: LookupLabelStatus.Less;
}
export type LabelLookupResult = LookupLabelResultAbsent | LookupLabelResultUnknown | LookupLabelResultFound | LookupLabelResultGreater | LookupLabelResultLess;
/**
* Lookup a path in a tree. If the path is a subtree, use {@link lookup_subtree} instead.
* @param path the path to look up
* @param tree the tree to search
* @returns {LookupResult} the result of the lookup
*/
export declare function lookup_path(path: NodePath, tree: HashTree): LookupResult;
/**
* Lookup a subtree in a tree.
* @param path the path to look up
* @param tree the tree to search
* @returns {SubtreeLookupResult} the result of the lookup
*/
export declare function lookup_subtree(path: NodePath, tree: HashTree): SubtreeLookupResult;
/**
* If the tree is a fork, flatten it into an array of trees
* @param {HashTree} t the tree to flatten
* @returns {HashTree[]} the flattened tree
*/
export declare function flatten_forks(t: HashTree): Array<LabeledHashTree | LeafHashTree | PrunedHashTree>;
/**
* Find a label in a tree
* @param label the label to find
* @param tree the tree to search
* @returns {LabelLookupResult} the result of the label lookup
*/
export declare function find_label(label: NodeLabel, tree: HashTree): LabelLookupResult;
/**
* Check if a canister ID falls within the canister ranges of a given subnet
* @param params the parameters with which to check the canister ranges
* @param params.canisterId the canister ID to check
* @param params.subnetId the subnet ID from which to check the canister ranges
* @param params.tree the hash tree in which to lookup the subnet's canister ranges
* @returns {boolean} `true` if the canister is in the range, `false` otherwise
*/
export declare function check_canister_ranges(params: {
canisterId: Principal;
subnetId: Principal;
tree: HashTree;
}): boolean;
export {};
//# sourceMappingURL=certificate.d.ts.map