@reclaimprotocol/attestor-core 4.0.3 → 5.0.1-beta.10

package/lib/browser/types/providers.gen.d.ts

@@ -0,0 +1,443 @@
+type BinaryData = Uint8Array | string;
+export interface HttpProviderParameters {
+    /**
+     * which URL does the request have to be made to Has to be a valid https URL for eg. https://amazon.in/orders?q=abcd
+     */
+    url: string;
+    method: "GET" | "POST" | "PUT" | "PATCH";
+    /**
+     * Specify the geographical location from where to proxy the request. 2-letter ISO country code or parameter (public or secret)
+     */
+    geoLocation?: string;
+    /**
+     * Specify the unique session id for allowing use of same proxy ip across multiple requests. Can be a smallcase alphanumeric string of length 8-14 characters. eg. "mystring12345", "something1234".
+     */
+    proxySessionId?: string;
+    /**
+     * Any additional headers to be sent with the request Note: these will be revealed to the attestor & won't be redacted from the transcript. To add hidden headers, use 'secretParams.headers' instead
+     */
+    headers?: {
+        [k: string]: string;
+    };
+    /**
+     * Body of the HTTP request
+     */
+    body?: BinaryData;
+    /**
+     * If the API doesn't perform well with the "key-update" method of redaction, you can switch to "zk" mode by setting this to "zk"
+     */
+    writeRedactionMode?: "zk" | "key-update";
+    /**
+     * Apply TLS configuration when creating the tunnel to the attestor.
+     */
+    additionalClientOptions?: {
+        /**
+         * @minItems 1
+         */
+        supportedProtocolVersions?: ("TLS1_2" | "TLS1_3")[];
+    };
+    /**
+     * The attestor will use this list to check that the redacted response does indeed match all the provided strings/regexes
+     *
+     * @minItems 1
+     */
+    responseMatches: {
+        /**
+         * "regex": the response must match the regex "contains": the response must contain the provided
+         *  string exactly
+         */
+        value: string;
+        /**
+         * The string/regex to match against
+         */
+        type: "regex" | "contains";
+        /**
+         * Inverses the matching logic. Fail when match is found and proceed otherwise
+         */
+        invert?: boolean;
+    }[];
+    /**
+     * which portions to select from a response. These are selected in order, xpath => jsonPath => regex * These redactions are done client side and only the selected portions are sent to the attestor. The attestor will only be able to see the selected portions alongside the first line of the HTTP response (i.e. "HTTP/1.1 200 OK") * To disable any redactions, pass an empty array
+     */
+    responseRedactions?: {
+        /**
+         * expect an HTML response, and to contain a certain xpath for eg. "/html/body/div.a1/div.a2/span.a5"
+         */
+        xPath?: string;
+        /**
+         * expect a JSON response, retrieve the item at this path using dot notation for e.g. 'email.addresses.0'
+         */
+        jsonPath?: string;
+        /**
+         * select a regex match from the response
+         */
+        regex?: string;
+        /**
+         * If provided, the value inside will be hashed instead of being redacted. Useful for cases where the data inside is an identifiying piece of information that you don't want to reveal to the attestor, eg. an email address.
+         * If the hash function produces more bytes than the original value, the hash will be truncated.
+         * Eg. if hash is enabled, the original value is "hello", and hashed is "a1b2c", then the attestor will only see "a1b2c".
+         * Note: if a regex with named groups is provided, only the named groups will be hashed.
+         */
+        hash?: "oprf" | "oprf-mpc" | "oprf-raw";
+    }[];
+    /**
+     * A map of parameter values which are user in form of {{param}} in URL, responseMatches, responseRedactions, body, geolocation. Those in URL, responseMatches & geo will be put into context and signed This value will NOT be included in provider hash
+     */
+    paramValues?: {
+        [k: string]: string;
+    };
+}
+export declare const HttpProviderParametersJson: {
+    title: string;
+    type: string;
+    required: string[];
+    properties: {
+        url: {
+            type: string;
+            format: string;
+            description: string;
+        };
+        method: {
+            type: string;
+            enum: string[];
+        };
+        geoLocation: {
+            type: string;
+            nullable: boolean;
+            description: string;
+        };
+        proxySessionId: {
+            type: string;
+            nullable: boolean;
+            description: string;
+        };
+        headers: {
+            type: string;
+            description: string;
+            additionalProperties: {
+                type: string;
+            };
+        };
+        body: {
+            description: string;
+            oneOf: ({
+                type: string;
+                format: string;
+            } | {
+                type: string;
+                format?: undefined;
+            })[];
+        };
+        writeRedactionMode: {
+            type: string;
+            description: string;
+            enum: string[];
+        };
+        additionalClientOptions: {
+            type: string;
+            description: string;
+            nullable: boolean;
+            properties: {
+                supportedProtocolVersions: {
+                    type: string;
+                    minItems: number;
+                    uniqueItems: boolean;
+                    items: {
+                        type: string;
+                        enum: string[];
+                    };
+                };
+            };
+        };
+        responseMatches: {
+            type: string;
+            minItems: number;
+            uniqueItems: boolean;
+            description: string;
+            items: {
+                type: string;
+                required: string[];
+                properties: {
+                    value: {
+                        type: string;
+                        description: string;
+                    };
+                    type: {
+                        type: string;
+                        description: string;
+                        enum: string[];
+                    };
+                    invert: {
+                        type: string;
+                        description: string;
+                    };
+                };
+                additionalProperties: boolean;
+            };
+        };
+        responseRedactions: {
+            type: string;
+            uniqueItems: boolean;
+            description: string;
+            items: {
+                type: string;
+                properties: {
+                    xPath: {
+                        type: string;
+                        nullable: boolean;
+                        description: string;
+                    };
+                    jsonPath: {
+                        type: string;
+                        nullable: boolean;
+                        description: string;
+                    };
+                    regex: {
+                        type: string;
+                        nullable: boolean;
+                        description: string;
+                    };
+                    hash: {
+                        type: string;
+                        description: string;
+                        enum: string[];
+                    };
+                };
+                additionalProperties: boolean;
+            };
+        };
+        paramValues: {
+            type: string;
+            description: string;
+            additionalProperties: {
+                type: string;
+            };
+        };
+    };
+    additionalProperties: boolean;
+};
+/**
+ * Secret parameters to be used with HTTP provider. None of the values in this object will be shown to the attestor
+ */
+export interface HttpProviderSecretParameters {
+    /**
+     * cookie string for authorisation.
+     */
+    cookieStr?: string;
+    /**
+     * authorisation header value
+     */
+    authorisationHeader?: string;
+    /**
+     * Headers that need to be hidden from the attestor
+     */
+    headers?: {
+        [k: string]: string;
+    };
+    /**
+     * A map of parameter values which are user in form of {{param}} in body these parameters will NOT be shown to attestor and extracted
+     */
+    paramValues?: {
+        [k: string]: string;
+    };
+}
+export declare const HttpProviderSecretParametersJson: {
+    title: string;
+    type: string;
+    description: string;
+    properties: {
+        cookieStr: {
+            type: string;
+            description: string;
+        };
+        authorisationHeader: {
+            type: string;
+            description: string;
+        };
+        headers: {
+            type: string;
+            description: string;
+            additionalProperties: {
+                type: string;
+            };
+        };
+        paramValues: {
+            type: string;
+            description: string;
+            additionalProperties: {
+                type: string;
+            };
+        };
+    };
+    additionalProperties: boolean;
+};
+export interface ProvidersConfig {
+    http: {
+        parameters: HttpProviderParameters;
+        secretParameters: HttpProviderSecretParameters;
+    };
+}
+export declare const PROVIDER_SCHEMAS: {
+    http: {
+        parameters: {
+            title: string;
+            type: string;
+            required: string[];
+            properties: {
+                url: {
+                    type: string;
+                    format: string;
+                    description: string;
+                };
+                method: {
+                    type: string;
+                    enum: string[];
+                };
+                geoLocation: {
+                    type: string;
+                    nullable: boolean;
+                    description: string;
+                };
+                proxySessionId: {
+                    type: string;
+                    nullable: boolean;
+                    description: string;
+                };
+                headers: {
+                    type: string;
+                    description: string;
+                    additionalProperties: {
+                        type: string;
+                    };
+                };
+                body: {
+                    description: string;
+                    oneOf: ({
+                        type: string;
+                        format: string;
+                    } | {
+                        type: string;
+                        format?: undefined;
+                    })[];
+                };
+                writeRedactionMode: {
+                    type: string;
+                    description: string;
+                    enum: string[];
+                };
+                additionalClientOptions: {
+                    type: string;
+                    description: string;
+                    nullable: boolean;
+                    properties: {
+                        supportedProtocolVersions: {
+                            type: string;
+                            minItems: number;
+                            uniqueItems: boolean;
+                            items: {
+                                type: string;
+                                enum: string[];
+                            };
+                        };
+                    };
+                };
+                responseMatches: {
+                    type: string;
+                    minItems: number;
+                    uniqueItems: boolean;
+                    description: string;
+                    items: {
+                        type: string;
+                        required: string[];
+                        properties: {
+                            value: {
+                                type: string;
+                                description: string;
+                            };
+                            type: {
+                                type: string;
+                                description: string;
+                                enum: string[];
+                            };
+                            invert: {
+                                type: string;
+                                description: string;
+                            };
+                        };
+                        additionalProperties: boolean;
+                    };
+                };
+                responseRedactions: {
+                    type: string;
+                    uniqueItems: boolean;
+                    description: string;
+                    items: {
+                        type: string;
+                        properties: {
+                            xPath: {
+                                type: string;
+                                nullable: boolean;
+                                description: string;
+                            };
+                            jsonPath: {
+                                type: string;
+                                nullable: boolean;
+                                description: string;
+                            };
+                            regex: {
+                                type: string;
+                                nullable: boolean;
+                                description: string;
+                            };
+                            hash: {
+                                type: string;
+                                description: string;
+                                enum: string[];
+                            };
+                        };
+                        additionalProperties: boolean;
+                    };
+                };
+                paramValues: {
+                    type: string;
+                    description: string;
+                    additionalProperties: {
+                        type: string;
+                    };
+                };
+            };
+            additionalProperties: boolean;
+        };
+        secretParameters: {
+            title: string;
+            type: string;
+            description: string;
+            properties: {
+                cookieStr: {
+                    type: string;
+                    description: string;
+                };
+                authorisationHeader: {
+                    type: string;
+                    description: string;
+                };
+                headers: {
+                    type: string;
+                    description: string;
+                    additionalProperties: {
+                        type: string;
+                    };
+                };
+                paramValues: {
+                    type: string;
+                    description: string;
+                    additionalProperties: {
+                        type: string;
+                    };
+                };
+            };
+            additionalProperties: boolean;
+        };
+    };
+};
+export {};

package/lib/browser/types/providers.gen.js

@@ -0,0 +1,16 @@
+const HttpProviderParametersJson = { "title": "HttpProviderParameters", "type": "object", "required": ["url", "method", "responseMatches"], "properties": { "url": { "type": "string", "format": "url", "description": "which URL does the request have to be made to Has to be a valid https URL for eg. https://amazon.in/orders?q=abcd" }, "method": { "type": "string", "enum": ["GET", "POST", "PUT", "PATCH"] }, "geoLocation": { "type": "string", "nullable": true, "description": "Specify the geographical location from where to proxy the request. 2-letter ISO country code or parameter (public or secret)" }, "proxySessionId": { "type": "string", "nullable": true, "description": 'Specify the unique session id for allowing use of same proxy ip across multiple requests. Can be a smallcase alphanumeric string of length 8-14 characters. eg. "mystring12345", "something1234".' }, "headers": { "type": "object", "description": "Any additional headers to be sent with the request Note: these will be revealed to the attestor & won't be redacted from the transcript. To add hidden headers, use 'secretParams.headers' instead", "additionalProperties": { "type": "string" } }, "body": { "description": "Body of the HTTP request", "oneOf": [{ "type": "string", "format": "binary" }, { "type": "string" }] }, "writeRedactionMode": { "type": "string", "description": `If the API doesn't perform well with the "key-update" method of redaction, you can switch to "zk" mode by setting this to "zk"`, "enum": ["zk", "key-update"] }, "additionalClientOptions": { "type": "object", "description": "Apply TLS configuration when creating the tunnel to the attestor.", "nullable": true, "properties": { "supportedProtocolVersions": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "enum": ["TLS1_2", "TLS1_3"] } } } }, "responseMatches": { "type": "array", "minItems": 1, "uniqueItems": true, "description": "The attestor will use this list to check that the redacted response does indeed match all the provided strings/regexes", "items": { "type": "object", "required": ["value", "type"], "properties": { "value": { "type": "string", "description": '"regex": the response must match the regex "contains": the response must contain the provided\n string exactly' }, "type": { "type": "string", "description": "The string/regex to match against", "enum": ["regex", "contains"] }, "invert": { "type": "boolean", "description": "Inverses the matching logic. Fail when match is found and proceed otherwise" } }, "additionalProperties": false } }, "responseRedactions": { "type": "array", "uniqueItems": true, "description": 'which portions to select from a response. These are selected in order, xpath => jsonPath => regex * These redactions are done client side and only the selected portions are sent to the attestor. The attestor will only be able to see the selected portions alongside the first line of the HTTP response (i.e. "HTTP/1.1 200 OK") * To disable any redactions, pass an empty array', "items": { "type": "object", "properties": { "xPath": { "type": "string", "nullable": true, "description": 'expect an HTML response, and to contain a certain xpath for eg. "/html/body/div.a1/div.a2/span.a5"' }, "jsonPath": { "type": "string", "nullable": true, "description": "expect a JSON response, retrieve the item at this path using dot notation for e.g. 'email.addresses.0'" }, "regex": { "type": "string", "nullable": true, "description": "select a regex match from the response" }, "hash": { "type": "string", "description": `If provided, the value inside will be hashed instead of being redacted. Useful for cases where the data inside is an identifiying piece of information that you don't want to reveal to the attestor, eg. an email address.
+If the hash function produces more bytes than the original value, the hash will be truncated.
+Eg. if hash is enabled, the original value is "hello", and hashed is "a1b2c", then the attestor will only see "a1b2c".
+Note: if a regex with named groups is provided, only the named groups will be hashed.`, "enum": ["oprf", "oprf-mpc", "oprf-raw"] } }, "additionalProperties": false } }, "paramValues": { "type": "object", "description": "A map of parameter values which are user in form of {{param}} in URL, responseMatches, responseRedactions, body, geolocation. Those in URL, responseMatches & geo will be put into context and signed This value will NOT be included in provider hash", "additionalProperties": { "type": "string" } } }, "additionalProperties": false };
+const HttpProviderSecretParametersJson = { "title": "HttpProviderSecretParameters", "type": "object", "description": "Secret parameters to be used with HTTP provider. None of the values in this object will be shown to the attestor", "properties": { "cookieStr": { "type": "string", "description": "cookie string for authorisation." }, "authorisationHeader": { "type": "string", "description": "authorisation header value" }, "headers": { "type": "object", "description": "Headers that need to be hidden from the attestor", "additionalProperties": { "type": "string" } }, "paramValues": { "type": "object", "description": "A map of parameter values which are user in form of {{param}} in body these parameters will NOT be shown to attestor and extracted", "additionalProperties": { "type": "string" } } }, "additionalProperties": false };
+const PROVIDER_SCHEMAS = {
+  http: {
+    parameters: HttpProviderParametersJson,
+    secretParameters: HttpProviderSecretParametersJson
+  }
+};
+export {
+  HttpProviderParametersJson,
+  HttpProviderSecretParametersJson,
+  PROVIDER_SCHEMAS
+};

package/lib/browser/types/rpc.d.ts

@@ -0,0 +1,35 @@
+import type { RPCMessage, TunnelDisconnectEvent, TunnelMessage } from '#src/proto/api.ts';
+import type { AttestorError } from '#src/utils/error.ts';
+type ExtractPrefix<T, S extends string> = T extends `${infer _}${S}` ? _ : never;
+export type RPCType = ExtractPrefix<keyof RPCMessage, 'Request'>;
+type RPCRequestType<T extends RPCType> = `${T}Request`;
+type RPCResponseType<T extends RPCType> = `${T}Response`;
+export type RPCRequestData<T extends RPCType> = Exclude<RPCMessage[RPCRequestType<T>], undefined>;
+export type RPCResponseData<T extends RPCType> = Exclude<RPCMessage[RPCResponseType<T>], undefined>;
+export type RPCRequest<T extends RPCType> = {
+    requestId: RPCMessage['id'];
+    type: T;
+    data: RPCRequestData<T>;
+    respond(res: RPCResponseData<T> | AttestorError): void;
+};
+export type RPCResponse<T extends RPCType> = {
+    id: RPCMessage['id'];
+    type: T;
+    data: RPCResponseData<T>;
+} | {
+    id: RPCMessage['id'];
+    error: AttestorError;
+};
+export type RPCEventMap = {
+    'connection-terminated': AttestorError;
+    'tunnel-message': TunnelMessage;
+    'tunnel-disconnect-event': TunnelDisconnectEvent;
+    'rpc-request': RPCRequest<RPCType>;
+    'rpc-response': RPCResponse<RPCType>;
+};
+export type RPCEventType = keyof RPCEventMap;
+export interface RPCEvent<T extends RPCEventType> extends Event {
+    type: T;
+    data: RPCEventMap[T];
+}
+export {};

package/lib/browser/types/signatures.d.ts

@@ -0,0 +1,28 @@
+export type PrivateKey = string;
+type Awaitable<T> = T | Promise<T>;
+export type ServiceSignatureProvider = {
+    /**
+     * Returns public key in compressed (compact) format used in Reclaim RPC calls
+     * @param privateKey corresponding private key in raw o hex form
+     */
+    getPublicKey(privateKey: PrivateKey): Uint8Array;
+    /**
+     * Returns address corresponding to the provided public key
+     * @param publicKey raw o hex form, compressed or uncompressed
+     */
+    getAddress(publicKey: Uint8Array): string;
+    /**
+     * Signs data with the provided private key
+     * @param data raw data to be signed
+     * @param privateKey private key in raw or hex format
+     */
+    sign(data: Uint8Array, privateKey: PrivateKey): Awaitable<Uint8Array>;
+    /**
+     * Verifies signature against provided data and an address
+     * @param data raw data to be verified. Must be same as used in sign() call
+     * @param signature signature bytes or string
+     * @param addressBytes address corresponding to a public key
+     */
+    verify(data: Uint8Array, signature: Uint8Array | string, addressBytes: Uint8Array | string): Awaitable<boolean>;
+};
+export {};

package/lib/browser/types/tunnel.d.ts

@@ -0,0 +1,18 @@
+import type { CreateTunnelRequest } from '#src/proto/api.ts';
+export type MakeTunnelBaseOpts<O> = O & {
+    onClose?(err?: Error): void;
+    onMessage?(data: Uint8Array): void;
+};
+export type Tunnel<E> = E & {
+    write(data: Uint8Array): void | Promise<void>;
+    close(err?: Error): void | Promise<void>;
+};
+export type MakeTunnelFn<O, E = {}> = (opts: MakeTunnelBaseOpts<O>) => (Tunnel<E> | Promise<Tunnel<E>>);
+export type Transcript<T> = {
+    sender: 'client' | 'server';
+    message: T;
+}[];
+export type TCPSocketProperties = {
+    transcript: Transcript<Uint8Array>;
+    createRequest: Pick<CreateTunnelRequest, 'host' | 'port' | 'geoLocation' | 'proxySessionId'>;
+};

package/lib/browser/types/zk.d.ts

@@ -0,0 +1,38 @@
+import type { EncryptionAlgorithm, OPRFOperator, ZKEngine, ZKOperator } from '@reclaimprotocol/zk-symmetric-crypto';
+import type { TOPRFPayload } from '#src/proto/api.ts';
+export type ZKOperators = {
+    [E in EncryptionAlgorithm]?: ZKOperator;
+};
+export type OPRFOperators = {
+    [E in EncryptionAlgorithm]?: OPRFOperator;
+};
+export type PrepareZKProofsBaseOpts = {
+    /** get ZK operator for specified algorithm */
+    zkOperators?: ZKOperators;
+    oprfOperators?: OPRFOperators;
+    /**
+     * max number of ZK proofs to generate concurrently
+     * @default 10
+     */
+    zkProofConcurrency?: number;
+    zkEngine?: ZKEngine;
+};
+export type TOPRFProofParams = TOPRFPayload & {
+    mask: Uint8Array;
+    plaintext: Uint8Array;
+    overshoot?: {
+        ciphertext: Uint8Array;
+        iv: Uint8Array;
+        recordNumber: number;
+    };
+};
+/**
+ * Marker for server-side OPRF computation (oprf-raw mode).
+ * Data is revealed to attestor who computes OPRF directly.
+ */
+export type OPRFRawMarker = {
+    dataLocation: {
+        fromIndex: number;
+        length: number;
+    };
+};

package/lib/browser/utils/auth.d.ts

@@ -0,0 +1,8 @@
+import type { AuthenticationRequest, ServiceSignatureType } from '#src/proto/api.ts';
+import { AuthenticatedUserData } from '#src/proto/api.ts';
+export declare function assertValidAuthRequest(request: AuthenticationRequest | undefined, signatureType: ServiceSignatureType): Promise<void>;
+/**
+ * Create an authentication request with the given data and private key,
+ * which can then be used to authenticate with the service.
+ */
+export declare function createAuthRequest(_data: Partial<AuthenticatedUserData>, privateKey: string): Promise<AuthenticationRequest>;

package/lib/browser/utils/auth.js

@@ -0,0 +1,71 @@
+import { getBytes } from "ethers";
+import { DEFAULT_AUTH_EXPIRY_S } from "../config/index.js";
+import { AuthenticatedUserData } from "../proto/api.js";
+import { getEnvVariable } from "../utils/env.js";
+import { AttestorError } from "../utils/error.js";
+import { unixTimestampSeconds } from "../utils/generics.js";
+import { SelectedServiceSignature, SIGNATURES } from "../utils/signatures/index.js";
+async function assertValidAuthRequest(request, signatureType) {
+  const publicKey = getEnvVariable("AUTHENTICATION_PUBLIC_KEY");
+  if (!request) {
+    if (publicKey) {
+      throw new AttestorError(
+        "ERROR_AUTHENTICATION_FAILED",
+        "User must be authenticated"
+      );
+    }
+    return;
+  }
+  if (!publicKey) {
+    throw new AttestorError(
+      "ERROR_BAD_REQUEST",
+      "The attestor is not configured for authentication"
+    );
+  }
+  const { signature, data } = request;
+  if (!data) {
+    throw new AttestorError(
+      "ERROR_AUTHENTICATION_FAILED",
+      "Missing data in auth request"
+    );
+  }
+  if (data.expiresAt < unixTimestampSeconds()) {
+    throw new AttestorError(
+      "ERROR_AUTHENTICATION_FAILED",
+      "Authentication request has expired"
+    );
+  }
+  const proto = AuthenticatedUserData.encode(data).finish();
+  const signatureAlg = SIGNATURES[signatureType];
+  const address = signatureAlg.getAddress(
+    getBytes(publicKey)
+  );
+  const verified = await signatureAlg.verify(proto, signature, address);
+  if (!verified) {
+    throw new AttestorError(
+      "ERROR_AUTHENTICATION_FAILED",
+      "Signature verification failed"
+    );
+  }
+}
+async function createAuthRequest(_data, privateKey) {
+  const createdAt = unixTimestampSeconds();
+  const data = {
+    createdAt,
+    expiresAt: createdAt + DEFAULT_AUTH_EXPIRY_S,
+    id: "",
+    hostWhitelist: [],
+    ..._data
+  };
+  const proto = AuthenticatedUserData.encode(data).finish();
+  const signature = await SelectedServiceSignature.sign(proto, privateKey);
+  const request = {
+    data,
+    signature
+  };
+  return request;
+}
+export {
+  assertValidAuthRequest,
+  createAuthRequest
+};