@reclaimprotocol/attestor-core 5.0.1-beta.2 → 5.0.1-beta.3

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

@@ -0,0 +1,77 @@
+import type { Logger as TLSLogger, TLSPacketContext, TLSProtocolVersion } from '@reclaimprotocol/tls';
+import type { OPRFRawMarker, TOPRFProofParams } from '#src/types/zk.ts';
+/**
+ * Represents a slice of any array or string
+ */
+export type ArraySlice = {
+    fromIndex: number;
+    toIndex: number;
+};
+export type RedactedOrHashedArraySlice = {
+    fromIndex: number;
+    toIndex: number;
+    /**
+     * By default, the data is redacted. Instead if you'd like
+     * a deterministic hash, set this to:
+     * - 'oprf' for client-side TOPRF with ZK proof
+     * - 'oprf-mpc' for TEE-to-TEE MPC OPRF
+     * - 'oprf-raw' for server-side OPRF (data revealed to attestor)
+     * @default undefined
+     */
+    hash?: 'oprf' | 'oprf-mpc' | 'oprf-raw';
+};
+export type Logger = TLSLogger & {
+    fatal: (...args: any[]) => void;
+    child: (opts: {
+        [_: string]: any;
+    }) => Logger;
+};
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'trace' | 'fatal';
+export type ZKRevealInfo = {
+    type: 'zk';
+    redactedPlaintext: Uint8Array;
+    toprfs?: TOPRFProofParams[];
+    oprfRawMarkers?: OPRFRawMarker[];
+    overshotToprfFromPrevBlock?: {
+        length: number;
+    };
+    /**
+     * If an oprf-raw marker from the previous block overshot into this block.
+     * The server will collect plaintext from this block to complete the OPRF.
+     */
+    overshotOprfRawFromPrevBlock?: {
+        length: number;
+    };
+};
+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;
+    /**
+     * oprf-raw replacements: original plaintext -> nullifier mappings
+     * for server-side parameter replacement
+     */
+    oprfRawReplacements?: OPRFRawReplacement[];
+};
+export type OPRFRawReplacement = {
+    /** Original plaintext that was OPRF'd */
+    originalText: string;
+    /** OPRF nullifier string to replace with */
+    nullifierText: string;
+};

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

@@ -0,0 +1,10 @@
+import type { Transaction } from 'elastic-apm-node';
+import type { IAttestorServerSocket } from '#src/types/client.ts';
+import type { Logger } from '#src/types/general.ts';
+import type { RPCRequestData, RPCResponseData, RPCType } from '#src/types/rpc.ts';
+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/browser/types/index.d.ts

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

package/lib/browser/types/index.js

@@ -0,0 +1,10 @@
+export * from "./providers.js";
+export * from "./general.js";
+export * from "./signatures.js";
+export * from "./claims.js";
+export * from "./zk.js";
+export * from "./client.js";
+export * from "./rpc.js";
+export * from "./tunnel.js";
+export * from "./handlers.js";
+export * from "./bgp.js";

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

@@ -0,0 +1,161 @@
+import type { TLSConnectionOptions } from '@reclaimprotocol/tls';
+import type { AttestorVersion, ProviderClaimData } from '#src/proto/api.ts';
+import type { ArraySlice, Logger, RedactedOrHashedArraySlice } from '#src/types/general.ts';
+import type { ProvidersConfig } from '#src/types/providers.gen.ts';
+import type { Transcript } from '#src/types/tunnel.ts';
+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, SecretParams, T> = T | ((params: Params, secretParams?: SecretParams) => T);
+export type ProviderCtx = {
+    version: AttestorVersion;
+};
+type GetResponseRedactionsOpts<P> = {
+    response: Uint8Array;
+    params: P;
+    logger: Logger;
+    ctx: ProviderCtx;
+};
+type AssertValidProviderReceipt<P> = {
+    receipt: Transcript<Uint8Array>;
+    params: P;
+    logger: Logger;
+    ctx: ProviderCtx;
+};
+/**
+ * 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, SecretParams, 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, SecretParams, string | undefined>;
+    /**
+     * Session identifier for proxy IP persistence.
+     *
+     * When provided, ensures all requests within the same session
+     * are routed through the same proxy IP address. Useful for
+     * maintaining IP consistency across multiple requests.
+     *
+     * Can be a smallcase alphanumeric string of length 8-14 characters.
+     * @example "mystring12345", "something1234"
+     */
+    proxySessionId?: ProviderField<Params, SecretParams, string | undefined>;
+    /** extra options to pass to the client like root CA certificates */
+    additionalClientOptions?: ProviderField<Params, SecretParams, 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, SecretParams, RedactionMode | undefined>;
+    /** generate the raw request to be sent to through the TLS receipt */
+    createRequest(secretParams: SecretParams, params: Params, logger: Logger): 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?(opts: GetResponseRedactionsOpts<Params>): RedactedOrHashedArraySlice[];
+    /**
+     * 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(opts: AssertValidProviderReceipt<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 {};