@reclaimprotocol/attestor-core 3.0.1

package/lib/types/claims.d.ts

@@ -0,0 +1,64 @@
+import type { ProviderClaimData } from 'src/proto/api';
+import type { IAttestorClient } from 'src/types/client';
+import type { CompleteTLSPacket, Logger } from 'src/types/general';
+import type { ProofGenerationStep, ProviderName, ProviderParams, ProviderSecretParams } from 'src/types/providers';
+import { Transcript } from 'src/types/tunnel';
+import type { PrepareZKProofsBaseOpts } from 'src/types/zk';
+/**
+ * Uniquely identifies a claim.
+ * Hash of claim info.
+ * Utilise `getIdentifierFromClaimInfo` to obtain this.
+ */
+export type ClaimID = ProviderClaimData['identifier'];
+export type ClaimInfo = Pick<ProviderClaimData, 'context' | 'provider' | 'parameters'>;
+export type AnyClaimInfo = ClaimInfo | {
+    identifier: ClaimID;
+};
+export type CompleteClaimData = Pick<ProviderClaimData, 'owner' | 'timestampS' | 'epoch'> & AnyClaimInfo;
+export type CreateClaimOnAttestorOpts<N extends ProviderName> = {
+    /** name of the provider to generate signed receipt for */
+    name: N;
+    /**
+     * secrets that are used to make the API request;
+     * not included in the receipt & cannot be viewed by anyone
+     * outside this client
+     */
+    secretParams: ProviderSecretParams<N>;
+    params: ProviderParams<N>;
+    /**
+     * Some metadata context to be included in the claim
+     */
+    context?: {
+        [key: string]: any;
+    };
+    onStep?(step: ProofGenerationStep): void;
+    /**
+     * Private key in hex format,
+     * prefixed with '0x'
+     */
+    ownerPrivateKey: string;
+    /**
+     * Provide either the client or the URL
+     * to the server -- so a client can be created internally.
+     *
+     * The created client will go into the global client pool.
+     */
+    client: IAttestorClient | {
+        url: string | URL;
+    };
+    /**
+     * Optionally set the timestamp of the claim
+     * in unix seconds. If not provided, the current
+     * time will be used.
+     */
+    timestampS?: number;
+    logger?: Logger;
+    /**
+     * Optionally update the provider parameters
+     * based on the transcript
+     */
+    updateProviderParams?(transcript: Transcript<CompleteTLSPacket>, tlsVersion: string): Promise<{
+        params: Partial<ProviderParams<N>>;
+        secretParams: Partial<ProviderSecretParams<N>>;
+    }>;
+} & PrepareZKProofsBaseOpts;

package/lib/types/claims.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhaW1zLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL3R5cGVzL2NsYWltcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiIn0=

package/lib/types/client.d.ts

@@ -0,0 +1,136 @@
+import type { InitRequest, RPCMessage, RPCMessages, ServiceSignatureType, TunnelMessage } from 'src/proto/api';
+import type { Logger } from 'src/types/general';
+import type { RPCEvent, RPCEventMap, RPCEventType, RPCRequestData, RPCResponseData, RPCType } from 'src/types/rpc';
+import type { TCPSocketProperties, Tunnel } from 'src/types/tunnel';
+import type { WebSocket as WSWebSocket } from 'ws';
+/**
+ * Any WebSocket implementation -- either the native
+ * WebSocket or the WebSocket from the `ws` package.
+ */
+export type AnyWebSocket = WebSocket | WSWebSocket;
+export type AnyWebSocketConstructor = new (url: string | URL) => AnyWebSocket;
+export type IAttestorClientCreateOpts = {
+    /**
+     * Attestor WS URL
+     */
+    url: string | URL;
+    signatureType?: ServiceSignatureType;
+    logger?: Logger;
+    /**
+     * Initial messages to send to the server
+     * in the query parameter used to establish
+     * the connection.
+     */
+    initMessages?: Partial<RPCMessage>[];
+    /**
+     * Provide a custom WebSocket implementation,
+     * will use the native WebSocket if not provided.
+     */
+    Websocket?: AnyWebSocketConstructor;
+};
+/**
+ * Base layer for the WebSocket connection on
+ * the client and server.
+ */
+export declare class IAttestorSocket {
+    metadata: InitRequest;
+    logger: Logger;
+    /**
+     * Is the WebSocket connection open?
+     */
+    isOpen: boolean;
+    /**
+     * Has the WebSocket connection been closed
+     */
+    isClosed: boolean;
+    /**
+     * Whether the WebSocket has been initialised
+     * by receiving an "init-response" message.
+     */
+    isInitialised: boolean;
+    /**
+     * Sends RPC messages to the server in a single packet.
+     * If the ID is not provided, it will be generated.
+     *
+     * Promisify the `send` method if using the `ws` package's
+     * WebSocket implementation.
+     */
+    sendMessage(...msgs: Partial<RPCMessage>[]): Promise<RPCMessages>;
+    /**
+     * Sends a "terminateConnectionAlert" message to the server
+     * with the specified error (if any), if the connection is
+     * still open and then closes the connection.
+     */
+    terminateConnection(err?: Error): Promise<void>;
+    /**
+     * Use this to listen to events on the WebSocket.
+     */
+    addEventListener<K extends RPCEventType>(type: K, listener: (data: RPCEvent<K>) => void): void;
+    removeEventListener<K extends RPCEventType>(type: K, listener: (data: RPCEvent<K>) => void): void;
+    /**
+     * Syntactic sugar for emitting events on the WebSocket.
+     * Wraps the `makeRpcEvent` call internally
+     */
+    dispatchRPCEvent<K extends RPCEventType>(type: K, data: RPCEventMap[K]): void;
+    /**
+     * Starts processing RPC messages from the WebSocket
+     * & emits events for each message type. These can be
+     * captured by the `addEventListener` method.
+     *
+     * Will also listen to "error" & "close" events on the WebSocket
+     * and emit a "attestor-error" event with the error.
+     * So, you only need to listen to the "attestor-error"
+     * event to capture anything you're interested in.
+     */
+    constructor(ws: WebSocket, metadata: InitRequest, logger: Logger);
+}
+export declare class IAttestorServerSocket extends IAttestorSocket {
+    /**
+     * Unique identifier for this WebSocket connection
+     */
+    sessionId: number;
+    /**
+     * Set of tunnels this client created. Only available
+     * when WS is created by the server
+     */
+    tunnels: {
+        [id: TunnelMessage['tunnelId']]: Tunnel<TCPSocketProperties>;
+    };
+    /**
+     * Fetches a tunnel by its ID.
+     * If the tunnel does not exist, it will throw an error.
+     */
+    getTunnel(tunnelId: TunnelMessage['tunnelId']): Tunnel<TCPSocketProperties>;
+}
+export declare class IAttestorClient extends IAttestorSocket {
+    constructor(opts: IAttestorClientCreateOpts);
+    /**
+     * Waits for a particular message to come in.
+     * If the connection is closed before the message is received,
+     * the promise will reject.
+     */
+    waitForResponse<T extends RPCType>(id: number): Promise<RPCResponseData<T>>;
+    /**
+     * Make an RPC request to the other end of the WebSocket.
+     */
+    rpc<T extends RPCType>(type: T, request: Partial<RPCRequestData<T>>): Promise<RPCResponseData<T>>;
+    /**
+     * Waits for the "init" request to be responded to
+     */
+    waitForInit(): Promise<void>;
+}
+interface WebSocketWithServerSocket {
+    /**
+     * Our RPC socket instance
+     */
+    serverSocket?: IAttestorServerSocket;
+}
+declare module 'ws' {
+    namespace WebSocket {
+        interface WebSocket extends WebSocketWithServerSocket {
+        }
+    }
+    interface WebSocket extends WebSocketWithServerSocket {
+    }
+}
+export {};

package/lib/types/client.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xpZW50LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL3R5cGVzL2NsaWVudC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiIn0=

package/lib/types/general.d.ts

@@ -0,0 +1,39 @@
+import type { Logger as TLSLogger, TLSPacketContext, TLSProtocolVersion } from '@reclaimprotocol/tls';
+/**
+ * Represents a slice of any array or string
+ */
+export type ArraySlice = {
+    fromIndex: number;
+    toIndex: number;
+};
+export type Logger = TLSLogger & {
+    child: (opts: {
+        [_: string]: any;
+    }) => Logger;
+};
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'trace' | 'fatal';
+export type ZKRevealInfo = {
+    type: 'zk';
+    redactedPlaintext: Uint8Array;
+};
+export type MessageRevealInfo = {
+    type: 'complete';
+} | ZKRevealInfo;
+export type CompleteTLSPacket = TLSPacketContext & {
+    /**
+     * Full data that was sent/recv across the wire
+     */
+    data: Uint8Array;
+};
+export type IDecryptedTranscriptMessage = {
+    sender: 'client' | 'server';
+    redacted: boolean;
+    message: Uint8Array;
+    plaintextLength: number;
+    recordHeader: Uint8Array;
+};
+export type IDecryptedTranscript = {
+    transcript: IDecryptedTranscriptMessage[];
+    tlsVersion: TLSProtocolVersion;
+    hostname: string;
+};

package/lib/types/general.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZ2VuZXJhbC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy90eXBlcy9nZW5lcmFsLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiIifQ==

package/lib/types/handlers.d.ts

@@ -0,0 +1,10 @@
+import { Transaction } from 'elastic-apm-node';
+import { IAttestorServerSocket } from 'src/types/client';
+import { Logger } from 'src/types/general';
+import { RPCRequestData, RPCResponseData, RPCType } from 'src/types/rpc';
+export type RPCHandlerMetadata = {
+    logger: Logger;
+    tx?: Transaction;
+    client: IAttestorServerSocket;
+};
+export type RPCHandler<R extends RPCType> = (data: RPCRequestData<R>, ctx: RPCHandlerMetadata) => Promise<RPCResponseData<R>>;

package/lib/types/handlers.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaGFuZGxlcnMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvdHlwZXMvaGFuZGxlcnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IiJ9

package/lib/types/index.d.ts

@@ -0,0 +1,9 @@
+export * from './providers';
+export * from './general';
+export * from './signatures';
+export * from './claims';
+export * from './zk';
+export * from './client';
+export * from './rpc';
+export * from './tunnel';
+export * from './handlers';

package/lib/types/index.js

@@ -0,0 +1,26 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./providers"), exports);
+__exportStar(require("./general"), exports);
+__exportStar(require("./signatures"), exports);
+__exportStar(require("./claims"), exports);
+__exportStar(require("./zk"), exports);
+__exportStar(require("./client"), exports);
+__exportStar(require("./rpc"), exports);
+__exportStar(require("./tunnel"), exports);
+__exportStar(require("./handlers"), exports);
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvdHlwZXMvaW5kZXgudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7Ozs7Ozs7Ozs7OztBQUFBLDhDQUEyQjtBQUMzQiw0Q0FBeUI7QUFDekIsK0NBQTRCO0FBQzVCLDJDQUF3QjtBQUN4Qix1Q0FBb0I7QUFDcEIsMkNBQXdCO0FBQ3hCLHdDQUFxQjtBQUNyQiwyQ0FBd0I7QUFDeEIsNkNBQTBCIn0=

package/lib/types/providers.d.ts

@@ -0,0 +1,135 @@
+import type { TLSConnectionOptions } from '@reclaimprotocol/tls';
+import type { ProviderClaimData } from 'src/proto/api';
+import type { ArraySlice } from 'src/types/general';
+import type { ProvidersConfig } from 'src/types/providers.gen';
+import type { Transcript } from 'src/types/tunnel';
+export type AttestorData = {
+    id: string;
+    url: string;
+};
+type CreateRequestResult = {
+    /**
+     * Raw request to be sent
+     * If a string, it is assumed to be an
+     * ASCII encoded string. If it contains
+     * non-ASCII characters, the redactions
+     * may not work as expected
+     */
+    data: Uint8Array | string;
+    redactions: ArraySlice[];
+};
+export type ProviderName = keyof ProvidersConfig;
+export type ProviderParams<T extends ProviderName> = ProvidersConfig[T]['parameters'];
+export type ProviderSecretParams<T extends ProviderName> = ProvidersConfig[T]['secretParameters'];
+export type RedactionMode = 'key-update' | 'zk';
+export type ProviderField<Params, T> = T | ((params: Params) => T);
+/**
+ * Generic interface for a provider that can be used to verify
+ * claims on a TLS receipt
+ *
+ * @notice "Params" are the parameters you want to claim against.
+ * These would typically be found in the response body
+ *
+ * @notice "SecretParams" are the parameters that are used to make the API request.
+ * These must be redacted in the request construction in "createRequest" & cannot be viewed by anyone
+ */
+export interface Provider<N extends ProviderName, Params = ProviderParams<N>, SecretParams = ProviderSecretParams<N>> {
+    /**
+     * host:port to connect to for this provider;
+     * the protocol establishes a connection to the first one
+     * when a request is received from a user.
+     *
+     * Run on attestor side when creating a new session
+     *
+     * Eg. "www.google.com:443", (p) => p.url.host
+     * */
+    hostPort: ProviderField<Params, string>;
+    /**
+     * Which geo location to send the request from
+     * Provide 2 letter country code, or a function
+     * that returns the country code
+     * @example "US", "IN"
+     */
+    geoLocation?: ProviderField<Params, string | undefined>;
+    /** extra options to pass to the client like root CA certificates */
+    additionalClientOptions?: ProviderField<Params, TLSConnectionOptions | undefined>;
+    /**
+     * default redaction mode to use. If not specified,
+     * the default is 'key-update'.
+     *
+     * It's switched to 'zk' for TLS1.2 requests as TLS1.2
+     * don't support key updates
+     *
+     * @default 'key-update'
+     */
+    writeRedactionMode?: ProviderField<Params, RedactionMode | undefined>;
+    /** generate the raw request to be sent to through the TLS receipt */
+    createRequest(secretParams: SecretParams, params: Params): CreateRequestResult;
+    /**
+     * Return the slices of the response to redact
+     * Eg. if the response is "hello my secret is xyz",
+     * and you want to redact "xyz", you would return
+     * [{start: 17, end: 20}]
+     *
+     * This is run on the client side, to selct which portions of
+     * the server response to send to the attestor
+     * */
+    getResponseRedactions?(response: Uint8Array, params: Params): ArraySlice[];
+    /**
+     * verify a generated TLS receipt against given parameters
+     * to ensure the receipt does contain the claims the
+     * user is claiming to have
+     *
+     * This is run on the attestor side.
+     * @param receipt application data messages exchanged in the TLS session
+     * @param params the parameters to verify the receipt against.
+     *  Eg. `{"email": "abcd@gmail.com"}`
+     * @returns sucessful verification or throws an error message.
+       *  Optionally return parameters extracted from the receipt
+       *  that will then be included in the claim context
+     * */
+    assertValidProviderReceipt(receipt: Transcript<Uint8Array>, params: Params): void | Promise<void> | {
+        extractedParameters: {
+            [key: string]: string;
+        };
+    };
+}
+export type ProofGenerationStep = {
+    name: 'connecting';
+} | {
+    name: 'sending-request-data';
+} | {
+    name: 'waiting-for-response';
+} | {
+    name: 'generating-zk-proofs';
+    proofsDone: number;
+    proofsTotal: number;
+    /**
+     * approximate time left in seconds.
+     * Only computed after the first block
+     * is done
+     * */
+    approxTimeLeftS?: number;
+} | {
+    name: 'waiting-for-verification';
+};
+type StepData = {
+    timestampS: number;
+    epoch: number;
+    attestors: AttestorData[];
+};
+export type CreateStep = ({
+    name: 'creating';
+} & StepData) | ({
+    name: 'attestor-progress';
+    currentAttestor: AttestorData;
+    step: ProofGenerationStep;
+} & StepData) | {
+    name: 'attestor-done';
+    timestampS: number;
+    epoch: number;
+    attestorsLeft: AttestorData[];
+    claimData: ProviderClaimData;
+    signaturesDone: string[];
+};
+export {};