@keetanetwork/keetanet-client 0.14.13 → 0.16.0

package/lib/p2p.d.ts

@@ -6,6 +6,7 @@ import type { JSONSerializable, JSONSerializableObject } from './utils/conversio
 import type { DistributiveOmit } from './utils/helper';
 import type { KVStorageProvider } from './kv';
 import type { Representative } from '../config';
+import { VoteStaple } from './vote';
 /**
  * Peer to Peer connection configuration
  */
@@ -95,7 +96,7 @@ interface P2PPeerRepBase extends P2PPeerBase {
 /**
  * Peering information for a Representative
  */
-type P2PPeerRep = P2PPeerRepBase & ({
+export type P2PPeerRep = P2PPeerRepBase & ({
     /**
      * Certificate from this peer which confirms its endpoints
      */
@@ -327,9 +328,12 @@ export declare class P2PSwitch {
      */
     sendMessage(to: P2PConnection | Account | P2PPeer | null, id: string, type: string, data: any, ttl?: number, exclude?: (string | P2PConnection)[], skipConnectToPeers?: boolean): Promise<boolean>;
     /**
+     * Check if any registered filter matches the VoteStaple's touched accounts.
+     * Uses the VoteStaple's touchedAccounts getter which may be pre-computed via trustedValues.
+     *
      * TODO - make this private after refactoring websockets to handle higher load
      * https://github.com/KeetaNetwork/node/issues/785
      */
-    haveAnyFilter(data: any): Promise<boolean>;
+    haveAnyFilter(voteStaple: VoteStaple): Promise<boolean>;
 }
 export default P2PSwitch;

package/lib/utils/buffer.d.ts

@@ -3,13 +3,15 @@ import zlib from 'zlib';
 /**
  * RFC 4648 Base32 Decoder
  */
-export declare function DecodeBase32(data: string, length: number): ArrayBuffer;
+export declare function DecodeBase32(data: string, length?: number): ArrayBuffer;
 /**
  * RFC 4648 Base32 Encoder
  */
 export declare function EncodeBase32(data: ArrayBuffer): string;
 export declare function DecodeBase64(data: string): ArrayBuffer;
+export declare function DecodeBase64URL(data: string): ArrayBuffer;
 export declare function EncodeBase64(data: ArrayBuffer): string;
+export declare function EncodeBase64URL(data: ArrayBuffer): string;
 export declare function ZlibInflate(data: ArrayBuffer, options?: zlib.ZlibOptions): ArrayBuffer;
 export declare function ZlibDeflate(data: ArrayBuffer, options?: zlib.ZlibOptions): ArrayBuffer;
 export declare function ZlibInflateAsync(data: ArrayBuffer, options?: zlib.ZlibOptions): Promise<ArrayBuffer>;
@@ -18,11 +20,15 @@ export declare class BufferStorage {
     #private;
     readonly storageKind: string;
     static isInstance: (obj: any, strict?: boolean) => obj is BufferStorage;
-    constructor(key: bigint | ArrayBuffer | string, length: number);
+    static decodeKey(key: ArrayBuffer | Buffer | string, length?: number): ArrayBuffer;
+    static decodeKey(key: bigint, length: number): ArrayBuffer;
+    static decodeKey(key: bigint | ArrayBuffer | Buffer | string, length?: number): ArrayBuffer;
+    constructor(key: bigint | ArrayBuffer | Buffer | string, length: number);
     get(): ArrayBuffer;
     get length(): number;
     getBuffer(): Buffer;
     toString(encoding?: 'hex' | 'base32' | 'base64'): string;
+    toJSON(): string;
     toBigInt(): bigint;
     compare(compareWith: typeof this | undefined | null): boolean;
     compareHexString(compareWith: BufferStorage | string | undefined | null): boolean;

package/lib/utils/certificate.d.ts

@@ -1,8 +1,8 @@
 import * as ASN1 from './asn1';
-import Account, { AccountKeyAlgorithm } from '../account';
+import Account from '../account';
 import * as HashLib from './hash';
 import { BufferStorage } from './buffer';
-import type { ToJSONSerializableOptions, ToJSONSerializable } from './conversion';
+import { type ToJSONSerializableOptions } from './conversion';
 /**
  * De-normalized mapped Certificate Schema, for use in type annotations since
  * we do not want to expose such a complex type
@@ -147,6 +147,10 @@ export declare class CertificateBuilder {
      * Convert a KeetaNet Account to a Key ID (for Subject Key Identifier)
      */
     private accountToKeyId;
+    /**
+     * Set the CA path length
+     */
+    protected setCAPathLen(pathLen: bigint | undefined): void;
     /**
      * Produce the extensions to include in this certificate
      */
@@ -211,10 +215,11 @@ export declare class CertificateHash extends BufferStorage {
     toJSON(): CertificateHashString;
     toString(): CertificateHashString;
 }
+export type CertificateBundleJSONOutput = ReturnType<CertificateBundle['toJSON']>;
 export declare class CertificateBundle {
     #private;
     static isInstance: (obj: any, strict?: boolean) => obj is CertificateBundle;
-    constructor(input: CertificateBundle | Certificate[] | ArrayBuffer | Buffer | string | (ConstructorParameters<typeof Certificate>[0])[] | Set<Certificate>);
+    constructor(input: CertificateBundle | Certificate[] | ArrayBuffer | Buffer | string | CertificateBundleJSONOutput | (ConstructorParameters<typeof Certificate>[0])[] | Set<Certificate>);
     get bundleSize(): number;
     getDER(): ArrayBuffer;
     getDERBuffer(): Buffer;
@@ -223,7 +228,12 @@ export declare class CertificateBundle {
         certificates: string[];
     };
 }
-export type CertificateJSONOutput = ToJSONSerializable<ReturnType<Certificate['toJSON']>>;
+declare const keyUsageBits: readonly ["digitalSignature", "nonRepudiation", "keyEncipherment", "dataEncipherment", "keyAgreement", "keyCertSign", "cRLSign", "encipherOnly", "decipherOnly"];
+type KeyUsageBits = typeof keyUsageBits[number];
+type KeyUsage = {
+    [P in KeyUsageBits]?: boolean;
+};
+export type CertificateJSONOutput = ReturnType<Certificate['toJSON']>;
 export declare class Certificate {
     #private;
     /**
@@ -296,6 +306,10 @@ export declare class Certificate {
             ca: boolean,
             pathLenConstraint?: bigint
         ];
+        /**
+         * Defines the purpose of the key
+         */
+        keyUsage?: KeyUsage;
         /**
          * Subject Key Identifier
          */
@@ -325,7 +339,7 @@ export declare class Certificate {
      * Is a certificate object?
      */
     static isCertificate(value: unknown): value is Certificate;
-    constructor(input: Certificate | ArrayBuffer | Buffer | string, options?: CertificateOptions);
+    constructor(input: Certificate | CertificateJSONOutput | ArrayBuffer | Buffer | string, options?: CertificateOptions);
     /**
      * Finalize construction of the certificate -- if this method is
      * replaced in a subclass, remember to call it at the end of the
@@ -352,6 +366,15 @@ export declare class Certificate {
      * Verifies that the certificate is was signed by the given account or certificate
      */
     verify(account: Account | Certificate): boolean;
+    /**
+     * Verify that a given chain meets the depth requirements
+     */
+    protected static verifyChainDepth(chain: Certificate[]): {
+        valid: true;
+    } | {
+        valid: false;
+        reason: string;
+    };
     /**
      * Asserts provided certificates can construct a valid graph with no loops or orphans, and that all provided certificates can reach the root, or current certificate
      * @param certificates Additional intermediate certificates to verify
@@ -360,6 +383,7 @@ export declare class Certificate {
     /**
      * Verify against a given certificate store
      */
+    verifyChain(store: NonNullable<CertificateOptions['store']>): Certificate[] | null;
     verifyChain(store: NonNullable<CertificateOptions['store']>, _ignore_seenCerts?: Set<Certificate>): Certificate[] | null;
     /**
      * Check if the certificate is valid at a given moment
@@ -438,31 +462,23 @@ export declare class Certificate {
      * Get a JSON representation of the certificate
      */
     toJSON(options?: ToJSONSerializableOptions, includeChain?: boolean): {
-        $binary?: string;
-        $chain?: unknown;
-        serial: bigint;
-        notBefore: Date;
-        notAfter: Date;
+        $binary?: string | undefined;
+        $chain?: undefined;
+        serial: string;
+        notBefore: string;
+        notAfter: string;
         subject: string;
         issuer: string;
-        subjectPublicKey: Account<AccountKeyAlgorithm.ECDSA_SECP256K1 | AccountKeyAlgorithm.ED25519 | AccountKeyAlgorithm.ECDSA_SECP256R1>;
+        subjectPublicKey: import("../account").Secp256K1PublicKeyString | import("../account").Secp256R1PublicKeyString | import("../account").ED25519PublicKeyString;
         baseExtensions: {
-            /**
-             * Basic Constraints
-             */
-            basicConstraints?: [ca: boolean, pathLenConstraint?: bigint];
-            /**
-             * Subject Key Identifier
-             */
-            subjectKeyIdentifier?: Buffer;
-            /**
-             * Authority Key Identifier
-             */
+            basicConstraints?: [ca: boolean, pathLenConstraint?: string | undefined] | undefined;
+            keyUsage?: KeyUsage | undefined;
+            subjectKeyIdentifier?: string | undefined;
             authorityKeyIdentifier?: {
                 type: "context";
                 value: 0;
-                contains: Buffer;
-            };
+                contains: string;
+            } | undefined;
         } | undefined;
         subjectDN: {
             name: string;
@@ -472,7 +488,7 @@ export declare class Certificate {
             name: string;
             value: string;
         }[];
-        $hash: CertificateHash;
+        $hash: CertificateHashString;
     };
 }
 export {};

package/lib/utils/conversion.d.ts

@@ -13,12 +13,16 @@ type AddBinaryIfIncluded<I> = I extends {
 } ? Omit<I, '$binary'> & {
     '$binary': NonNullable<BinaryType>;
 } : I;
-export type ToJSONSerializable<T, Options extends ToJSONSerializableOptions = ToJSONSerializableOptions> = T extends JSONSerializable ? T : T extends undefined ? undefined : T extends bigint ? string : T extends Date ? string : T extends Buffer | ArrayBuffer ? string : T extends {
+type IsTuple<T> = T extends readonly any[] ? number extends T['length'] ? false : true : false;
+type JSONDepthLimit = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+export type ToJSONSerializable<T, Options extends ToJSONSerializableOptions = ToJSONSerializableOptions, Depth extends number = 10> = T extends never ? never : Depth extends never ? never : T extends JSONSerializable ? T : T extends undefined ? undefined : T extends bigint ? string : T extends Date ? string : T extends Buffer | ArrayBuffer ? string : T extends {
     toJSON(): infer U;
-} ? Options['addBinary'] extends true ? ToJSONSerializable<AddBinaryIfIncluded<U>, Options> : ToJSONSerializable<U, Options> : T extends object ? {
-    [K in keyof T]: ToJSONSerializable<T[K], Options>;
+} ? Options['addBinary'] extends true ? ToJSONSerializable<AddBinaryIfIncluded<U>, Options, JSONDepthLimit[Depth]> : ToJSONSerializable<U, Options, JSONDepthLimit[Depth]> : IsTuple<T> extends true ? {
+    [K in keyof T]: ToJSONSerializable<T[K], Options, JSONDepthLimit[Depth]>;
+} : T extends readonly (infer U)[] ? ToJSONSerializable<U, Options, JSONDepthLimit[Depth]>[] : T extends object ? {
+    [K in keyof T]: ToJSONSerializable<T[K], Options, JSONDepthLimit[Depth]>;
 } : never;
-export declare function toJSONSerializable<Value, Options extends ToJSONSerializableOptions>(data: Value, opts?: Options): ToJSONSerializable<Value, Options>;
+export declare function toJSONSerializable<Value = never, Options extends ToJSONSerializableOptions = ToJSONSerializableOptions>(data: Value, opts?: Options): ToJSONSerializable<Value, Options>;
 export declare function objectToBuffer(data: any, opts?: ToJSONSerializableOptions): Buffer;
 export declare function parseHexBigIntString(input: string): bigint;
 export {};

package/lib/utils/external-keys/passkey-prf.d.ts

@@ -0,0 +1,156 @@
+/**
+ * ExternalKeyPair for the Keeta Network which uses the PRF (Pseudo-Random
+ * Function) extension of the WebAuthn API to generate a key pair that can be
+ * used for signing and verifying messages. The PRF extension allows for the
+ * generation of a key pair that is derived from a secret value, which can be
+ * used for authentication and encryption purposes. This implementation uses
+ * the WebAuthn API to create a new credential with the PRF extension and then
+ * extracts the public key from the generated credential.
+ */
+import type * as KeetaNet from '../../../client';
+import type { AccountKeyAlgorithm } from '../../../lib/account';
+type KeetaPasskeyPRFKeyPairPackages = {
+    KeetaNet: {
+        lib: {
+            Account: typeof KeetaNet.lib.Account;
+            Utils: {
+                Helper: typeof KeetaNet.lib.Utils.Helper;
+                Buffer: typeof KeetaNet.lib.Utils.Buffer;
+            };
+        };
+    };
+    navigator: {
+        credentials: Pick<Navigator['credentials'], 'create' | 'get'>;
+    };
+    bip39: {
+        entropyToMnemonic: (entropy: Uint8Array) => string;
+    };
+};
+type KeetaPasskeyPRFKeyPairOptions = {
+    /**
+     * Key type to generate from the PRF output.  This is optional and
+     * defaults to ECDSA_SECP256K1, but can be set to any supported key
+     * type
+     */
+    keyType?: AccountKeyAlgorithm;
+    /**
+     * The index to use for the generated key pair.  This is optional and
+     * defaults to 0, but can be set to any non-negative integer.  The
+     * index is used to allow for multiple key pairs to be generated from
+     * a single Passkey credential
+     */
+    index?: number;
+    /**
+     * The salt to use for the PRF extension.  This is optional and
+     * defaults to a fixed value, but can be set to any value.  The salt
+     * is used to derive the keying material from the passkey.
+     *
+     * The default salt is the SHA2-256 hash of the UTF-8 bytes of the
+     * string "keeta.com/wallet/seed/v1" and should generally be used.
+     */
+    salt?: Uint8Array;
+};
+/**
+ * Options for looking up an existing Passkey PRF key pair.  You can look up
+ * a key pair by its key ID, or by its public key string (not supported yet),
+ * or you can just look up any key pair (the user will be prompted to select a
+ * credential.
+ */
+type KeetaPasskeyPRFKeyPairLookupOptions = KeetaPasskeyPRFKeyPairOptions & ({
+    /**
+     * Look up by a key ID
+     */
+    keyID: string;
+} | {
+    /**
+     * Look up by a Keeta public key string
+     *
+     * XXX:TODO
+     */
+    publicKeyString: string;
+} | object);
+type KeetaPasskeyPRFKeyPairGenerateOptions = KeetaPasskeyPRFKeyPairOptions & {
+    /**
+     * "Relying Party" information from WebAuthn, which is used to
+     * identify the context in which the credential is being created.
+     */
+    rp: {
+        /**
+         * The name of the relying party, which is a human-readable
+         * identifier for the entity that is requesting the credential.
+         *
+         * This field is optional and defaults to 'Keeta Network' if
+         * not provided.
+         */
+        name?: string;
+        /**
+         * The ID of the relying party, which is a unique identifier
+         * for the entity that is requesting the credential.  This
+         * should be a domain name (e.g. "example.com") that
+         * identifies the relying party.
+         */
+        id: string;
+    };
+    /**
+     * "User" information from WebAuthn, which is used to identify the
+     * user for whom the credential is being created.
+     */
+    user: {
+        /**
+         * The display name of the user, which is a human-readable
+         * identifier for the Passkey credential.
+         */
+        displayName: string;
+        /**
+         * The name of the user, which is a unique identifier for the
+         * Passkey credential.  This should be a string that uniquely
+         * identifies the user.
+         */
+        name: string;
+        /**
+         * The user ID, which is a unique identifier for the Passkey
+         * credential on this Relying Party.  This should be a byte
+         * array that uniquely identifies the user, and is used by the
+         * authenticator to associate the credential with the user.
+         *
+         * This field is optional and will be generated randomly if
+         * not provided.
+         *
+         * Generating a new Passkey with the same user ID will result
+         * in the old credential being overwritten, so if you want to
+         * have multiple Passkeys for the same user you should not
+         * use a duplicate user ID.
+         */
+        id?: Uint8Array;
+    };
+};
+interface KeetaPasskeyPRFKeyPair extends InstanceType<typeof KeetaNet.lib.Account.ExternalKeyPair> {
+    /**
+     * The key ID is a unique identifier for the key pair, which can be
+     * used to lookup the key pair without having to search through all
+     * existing key or have the user select the credential (and potentially
+     * pick the "wrong" credential if they have multiple credentials).
+     *
+     * The key ID is generated by the authenticator so we cannot control
+     * what it is.
+     */
+    readonly keyID: string;
+    /**
+     * Export the private key material for the key pair.  This should only
+     * be called if you want to export the private key material for backup
+     * purposes, and should not be used for regular signing operations.
+     *
+     * **SECURITY WARNING** This method will expose the private key
+     *                      material for the key pair, which can be used to
+     *                      compromise the security of the key pair.
+     */
+    exportPassphrase: () => Promise<string>;
+}
+interface KeetaPasskeyPRFKeyPairClass {
+    lookup: (options?: KeetaPasskeyPRFKeyPairLookupOptions) => Promise<KeetaPasskeyPRFKeyPair>;
+    generate: (options: KeetaPasskeyPRFKeyPairGenerateOptions) => Promise<KeetaPasskeyPRFKeyPair>;
+}
+export declare function KeetaPasskeyPRFKeyPairFactory(packages: KeetaPasskeyPRFKeyPairPackages, includeTesting: true): Required<KeetaPasskeyPRFKeyPairClass>;
+export declare function KeetaPasskeyPRFKeyPairFactory(packages: KeetaPasskeyPRFKeyPairPackages, includeTesting?: false): Omit<KeetaPasskeyPRFKeyPairClass, '_Testing'>;
+export declare function KeetaPasskeyPRFKeyPairFactory(packages: KeetaPasskeyPRFKeyPairPackages, includeTesting?: boolean): KeetaPasskeyPRFKeyPairClass;
+export {};