@caido/sdk-workflow 0.38.0 → 0.39.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caido/sdk-workflow",
-  "version": "0.38.0",
+  "version": "0.39.0",
   "description": "Typing for the Caido Workflow SDK",
   "author": "Caido Labs Inc. <dev@caido.io>",
   "license": "MIT",

package/src/index.d.ts

@@ -1 +1,4 @@
-export * from "./typing";
+///<reference path="types/common.d.ts" />
+///<reference path="types/global.d.ts" />
+///<reference path="types/runtime.d.ts" />
+///<reference path="types/typing.d.ts" />

package/src/types/common.d.ts

@@ -0,0 +1,225 @@
+declare module "caido:utils" {
+  /**
+   * The body of a Request or Response.
+   *
+   * Calling `to<FORMAT>` will try to convert the body to the desired format.
+   */
+  export class Body {
+    constructor(data: string | Array<number> | Uint8Array);
+    /**
+     * Parse the body as a string.
+     *
+     * Unprintable characters will be replaced with `�`.
+     */
+    toText(): string;
+    /**
+     * Try to parse the body as JSON.
+     *
+     * @throws {SyntaxError} If the body is not valid JSON.
+     */
+    toJson(): any;
+    /**
+     * Get the raw body as an array of bytes.
+     */
+    toRaw(): Uint8Array;
+  }
+
+  /**
+   * A saved immutable Request.
+   *
+   * To modify, use `toSpec` to get a `RequestSpec` object.
+   */
+  export type Request = {
+    getId(): ID;
+    getHost(): string;
+    getPort(): number;
+    getTls(): boolean;
+    getMethod(): string;
+    getPath(): string;
+    getQuery(): string;
+    getHeaders(): Record<string, Array<string>>;
+    getHeader(name: string): Array<string> | undefined;
+    getBody(): Body | undefined;
+    toSpec(): RequestSpec;
+    toSpecRaw(): RequestSpecRaw;
+  };
+
+  export type SetBodyOptions = {
+    /**
+     * Should update the Content-export type header.
+     *
+     * @default true
+     */
+    updateContentLength: boolean;
+  };
+
+  /**
+   * A mutable Request not yet sent.
+   */
+  export class RequestSpec {
+    constructor(url: string);
+    getHost(): string;
+    setHost(host: string): void;
+    getPort(): number;
+    setPort(port: number): void;
+    getTls(): boolean;
+    setTls(tls: boolean): void;
+    getMethod(): string;
+    setMethod(method: string): void;
+    getPath(): string;
+    setPath(path: string): void;
+    getQuery(): string;
+    setQuery(query: string): void;
+    getHeaders(): Record<string, Array<string>>;
+    getHeader(name: string): Array<string> | undefined;
+    setHeader(name: string, value: string): void;
+    removeHeader(name: string): void;
+    getBody(): Body | undefined;
+    setBody(body: Body | Bytes, options?: SetBodyOptions): void;
+    setRaw(raw: Bytes): RequestSpecRaw;
+  }
+
+  /**
+   * A mutable raw Request not yet sent.
+   */
+  export class RequestSpecRaw {
+    constructor(url: string);
+    getHost(): string;
+    setHost(host: string): void;
+    getPort(): number;
+    setPort(port: number): void;
+    getTls(): boolean;
+    setTls(tls: boolean): void;
+    getRaw(): Uint8Array;
+    setRaw(raw: Bytes): void;
+  }
+
+  /**
+   * An immutable saved Response.
+   */
+  export type Response = {
+    getId(): ID;
+    getCode(): number;
+    getHeaders(): Record<string, Array<string>>;
+    getHeader(name: string): Array<string> | undefined;
+    getBody(): Body | undefined;
+  };
+
+  /**
+   * An immutable saved Request and Response pair.
+   */
+  export type RequestResponse = {
+    request: Request;
+    response: Response;
+  };
+
+  /**
+   * The SDK for the Requests service.
+   */
+  export type RequestsSDK = {
+    /**
+     * Sends a request.
+     *
+     * This respects the upstream proxy settings.
+     *
+     * @throws {Error} If the request cannot be sent.
+     *
+     * @example
+     * const spec = new RequestSpec("https://example.com");
+     * sdk.requests.send(request)
+     *   .then((res) => {
+     *     console.log(res.request.getId());
+     *     console.log(res.response.getCode());
+     *   })
+     *   .catch((err) => {
+     *     console.error(err);
+     *   });
+     */
+    send(request: RequestSpec | RequestSpecRaw): Promise<RequestResponse>;
+
+    /**
+     * Checks if a request is in scope.
+     *
+     * @example
+     * if (sdk.requests.inScope(request)) {
+     *  console.log("In scope");
+     * }
+     */
+    inScope(request: Request | RequestSpec): boolean;
+  };
+
+  /**
+   * A saved immutable Finding.
+   */
+  export type Finding = {
+    /**
+     * The unique Caido {@link ID} of the finding.
+     */
+    getId(): ID;
+    /**
+     * The title of the finding.
+     */
+    getTitle(): string;
+    /**
+     * The description of the finding.
+     */
+    getDescription(): string | undefined;
+    /**
+     * The name of the reporter.
+     */
+    getReporter(): string;
+  };
+
+  /**
+   * A mutable Finding not yet created.
+   */
+  export type FindingSpec = {
+    /**
+     * The title of the finding.
+     */
+    title: string;
+    /**
+     * The description of the finding.
+     */
+    description?: string | undefined;
+    /**
+     * The name of the reporter.
+     * It will be used to group findings.
+     */
+    reporter: string;
+    /**
+     * Deduplication key for findings.
+     * If a finding with the same dedupe key already exists, it will not be created.
+     */
+    dedupeKey?: string | undefined;
+    /**
+     * The associated {@link Request}.
+     */
+    request: Request;
+  };
+
+  /**
+   * The SDK for the Findings service.
+   */
+  export type FindingsSDK = {
+    /**
+     * Creates a new Finding.
+     *
+     * @throws {Error} If the request cannot be saved.
+     *
+     * @example
+     * sdk.findings.create({
+     *   title: "Title",
+     *   description: "Description",
+     *   reporter: "Reporter",
+     *   dedupe: `${request.getHost()}-${request.getPath()}`,
+     *   request,
+     * });
+     */
+    create(spec: FindingSpec): Promise<Finding>;
+  };
+
+  export type ID = string;
+  export type Bytes = string | Array<number> | Uint8Array;
+  export type MaybePromise<T> = T | Promise<T>;
+}

package/src/types/global.d.ts

@@ -0,0 +1,55 @@
+import {
+  Body as _Body,
+  Bytes as _Bytes,
+  Finding as _Finding,
+  FindingSpec as _FindingSpec,
+  FindingsSDK as _FindingsSDK,
+  ID as _ID,
+  MaybePromise as _MaybePromise,
+  Request as _Request,
+  RequestResponse as _RequestResponse,
+  RequestSpec as _RequestSpec,
+  RequestSpecRaw as _RequestSpecRaw,
+  RequestsSDK as _RequestsSDK,
+  Response as _Response,
+} from "caido:utils";
+
+import {
+  HttpInput as _HttpInput,
+  PassiveInput as _PassiveInput,
+  BytesInput as _BytesInput,
+  ConvertInput as _ConvertInput,
+  Data as _Data,
+  Decision as _Decision,
+  SDK as _SDK,
+} from "caido:workflow";
+
+declare global {
+  //@ts-ignore TS2666
+  export {
+    _Body as Body,
+    _Request as Request,
+    _RequestSpec as RequestSpec,
+    _RequestSpecRaw as RequestSpecRaw,
+    _Response as Response,
+    _RequestResponse as RequestResponse,
+    _Finding as Finding,
+    _FindingSpec as FindingSpec,
+    _ID as ID,
+    _Bytes as Bytes,
+    _MaybePromise as MaybePromise,
+    _RequestsSDK as RequestsSDK,
+    _FindingsSDK as FindingsSDK,
+  };
+
+  //@ts-ignore TS2666
+  export {
+    _HttpInput as HttpInput,
+    _PassiveInput as PassiveInput,
+    _BytesInput as BytesInput,
+    _ConvertInput as ConvertInput,
+    _Data as Data,
+    _Decision as Decision,
+    _SDK as SDK,
+  };
+}

package/src/types/runtime.d.ts

@@ -0,0 +1,148 @@
+declare global {
+  /**
+   * Console interface for logging.
+   *
+   * Currently logs are only available in the backend logs.
+   * See https://docs.caido.io/report_bug.html#1-backend-logs
+   */
+  type Console = {
+    debug(message: any): void;
+    log(message: any): void;
+    warn(message: any): void;
+    error(message: any): void;
+  };
+  var console: Console;
+
+  /**
+   * The URLSearchParams interface defines utility methods to work with the query string of a URL.
+   */
+  class URLSearchParams implements Iterable<[string, string]> {
+    constructor(
+      init?:
+        | URLSearchParams
+        | string
+        | { readonly [name: string]: string }
+        | Iterable<readonly [name: string, value: string]>
+        | ReadonlyArray<readonly [name: string, value: string]>,
+    );
+    /**
+     * Append a new name-value pair to the query string.
+     */
+    append(name: string, value: string): void;
+    /**
+     * If `value` is provided, removes all name-value pairs
+     * where name is `name` and value is `value`.
+     *
+     * If `value` is not provided, removes all name-value pairs whose name is `name`.
+     */
+    delete(name: string, value?: string): void;
+    /**
+     * Returns an ES6 `Iterator` over each of the name-value pairs in the query.
+     * Each item of the iterator is a JavaScript `Array`. The first item of the `Array` is the `name`, the second item of the `Array` is the `value`.
+     *
+     * Alias for `urlSearchParams[@@iterator]()`.
+     */
+    entries(): IterableIterator<[string, string]>;
+    /**
+     * Iterates over each name-value pair in the query and invokes the given function.
+     *
+     * ```js
+     * const myURL = new URL('https://example.org/?a=b&#x26;c=d');
+     * myURL.searchParams.forEach((value, name) => {
+     *   console.log(name, value);
+     * });
+     * // Prints:
+     * //   a b
+     * //   c d
+     * ```
+     * @param fn Invoked for each name-value pair in the query
+     */
+    forEach(fn: (value: string, name: string) => void): void;
+    /**
+     * Returns the value of the first name-value pair whose name is `name`. If there
+     * are no such pairs, `null` is returned.
+     * @return or `null` if there is no name-value pair with the given `name`.
+     */
+    get(name: string): string | null;
+    /**
+     * Returns the values of all name-value pairs whose name is `name`. If there are
+     * no such pairs, an empty array is returned.
+     */
+    getAll(name: string): string[];
+    /**
+     * Checks if the `URLSearchParams` object contains key-value pair(s) based on `name` and an optional `value` argument.
+     *
+     * If `value` is provided, returns `true` when name-value pair with
+     * same `name` and `value` exists.
+     *
+     * If `value` is not provided, returns `true` if there is at least one name-value
+     * pair whose name is `name`.
+     */
+    has(name: string, value?: string): boolean;
+    /**
+     * Returns an ES6 `Iterator` over the names of each name-value pair.
+     *
+     * ```js
+     * const params = new URLSearchParams('foo=bar&#x26;foo=baz');
+     * for (const name of params.keys()) {
+     *   console.log(name);
+     * }
+     * // Prints:
+     * //   foo
+     * //   foo
+     * ```
+     */
+    keys(): IterableIterator<string>;
+    /**
+     * Sets the value in the `URLSearchParams` object associated with `name` to `value`. If there are any pre-existing name-value pairs whose names are `name`,
+     * set the first such pair's value to `value` and remove all others. If not,
+     * append the name-value pair to the query string.
+     *
+     * ```js
+     * const params = new URLSearchParams();
+     * params.append('foo', 'bar');
+     * params.append('foo', 'baz');
+     * params.append('abc', 'def');
+     * console.log(params.toString());
+     * // Prints foo=bar&#x26;foo=baz&#x26;abc=def
+     *
+     * params.set('foo', 'def');
+     * params.set('xyz', 'opq');
+     * console.log(params.toString());
+     * // Prints foo=def&#x26;abc=def&#x26;xyz=opq
+     * ```
+     */
+    set(name: string, value: string): void;
+    /**
+     * The total number of parameter entries.
+     */
+    readonly size: number;
+    /**
+     * Sort all existing name-value pairs in-place by their names. Sorting is done
+     * with a [stable sorting algorithm](https://en.wikipedia.org/wiki/Sorting_algorithm#Stability), so relative order between name-value pairs
+     * with the same name is preserved.
+     *
+     * This method can be used, in particular, to increase cache hits.
+     *
+     * ```js
+     * const params = new URLSearchParams('query[]=abc&#x26;type=search&#x26;query[]=123');
+     * params.sort();
+     * console.log(params.toString());
+     * // Prints query%5B%5D=abc&#x26;query%5B%5D=123&#x26;type=search
+     * ```
+     */
+    sort(): void;
+    /**
+     * Returns the search parameters serialized as a string, with characters
+     * percent-encoded where necessary.
+     */
+    toString(): string;
+    /**
+     * Returns an ES6 `Iterator` over the values of each name-value pair.
+     */
+    values(): IterableIterator<string>;
+    [Symbol.iterator](): IterableIterator<[string, string]>;
+  }
+}
+
+export {};

package/src/types/typing.d.ts

@@ -0,0 +1,52 @@
+declare module "caido:workflow" {
+  import {
+    Bytes,
+    FindingsSDK,
+    RequestsSDK,
+    Request,
+    Response,
+  } from "caido:utils";
+
+  export type HttpInput = {
+    request: Request | undefined;
+    response: Response | undefined;
+  };
+  /**
+   * @deprecated Use HttpInput instead.
+   */
+  export type PassiveInput = HttpInput;
+  export type BytesInput = Array<number>;
+  /**
+   * @deprecated Use BytesInput instead.
+   */
+  export type ConvertInput = BytesInput;
+
+  export type Data = Bytes;
+  export type Decision = boolean;
+
+  /**
+   * The SDK object available to all scripts.
+   */
+  export type SDK = {
+    /**
+     * The console.
+     *
+     * This is currently the same as the global `console`.
+     */
+    console: Console;
+    /**
+     * The SDK for the Findings service.
+     */
+    findings: FindingsSDK;
+    /**
+     * The SDK for the Requests services
+     */
+    requests: RequestsSDK;
+    /**
+     * Converts bytes to a string.
+     *
+     * Unprintable characters will be replaced with `�`.
+     */
+    asString(array: Bytes): string;
+  };
+}

package/src/typing.d.ts

@@ -1,249 +0,0 @@
-/**
- * Console interface for logging.
- *
- * Currently logs are only available in the backend logs.
- * See https://docs.caido.io/report_bug.html#1-backend-logs
- */
-export declare type Console = {
-  debug(message: any): void;
-  log(message: any): void;
-  warn(message: any): void;
-  error(message: any): void;
-};
-
-/**
- * The body of a Request or Response.
- *
- * Calling `to<FORMAT>` will try to convert the body to the desired format.
- */
-export declare class Body {
-  constructor(data: string | Array<number> | Uint8Array);
-  /**
-   * Parse the body as a string.
-   *
-   * Unprintable characters will be replaced with `�`.
-   */
-  toText(): string;
-  /**
-   * Try to parse the body as JSON.
-   *
-   * @throws {SyntaxError} If the body is not valid JSON.
-   */
-  toJson(): any;
-  /**
-   * Get the raw body as an array of bytes.
-   */
-  toRaw(): Uint8Array;
-}
-
-/**
- * A saved immutable Request.
- *
- * To modify, use `toSpec` to get a `RequestSpec` object.
- */
-export declare type Request = {
-  getId(): ID;
-  getHost(): string;
-  getPort(): number;
-  getTls(): boolean;
-  getMethod(): string;
-  getPath(): string;
-  getQuery(): string;
-  getHeaders(): Record<string, Array<string>>;
-  getHeader(name: string): Array<string> | undefined;
-  getBody(): Body | undefined;
-  toSpec(): RequestSpec;
-  toSpecRaw(): RequestSpecRaw;
-};
-
-type SetBodyOptions = {
-  /**
-   * Should update the Content-Type header.
-   *
-   * @default true
-   */
-  updateContentLength: boolean;
-};
-
-/**
- * A mutable Request not yet sent.
- */
-export declare class RequestSpec {
-  constructor(url: string);
-  getHost(): string;
-  setHost(host: string): void;
-  getPort(): number;
-  setPort(port: number): void;
-  getTls(): boolean;
-  setTls(tls: boolean): void;
-  getMethod(): string;
-  setMethod(method: string): void;
-  getPath(): string;
-  setPath(path: string): void;
-  getQuery(): string;
-  setQuery(query: string): void;
-  getHeaders(): Record<string, Array<string>>;
-  getHeader(name: string): Array<string> | undefined;
-  setHeader(name: string, value: string): void;
-  removeHeader(name: string): void;
-  getBody(): Body | undefined;
-  setBody(body: Body | Bytes, options?: SetBodyOptions): void;
-  setRaw(raw: Bytes): RequestSpecRaw;
-}
-
-/**
- * A mutable raw Request not yet sent.
- */
-export declare class RequestSpecRaw {
-  constructor(url: string);
-  getHost(): string;
-  setHost(host: string): void;
-  getPort(): number;
-  setPort(port: number): void;
-  getTls(): boolean;
-  setTls(tls: boolean): void;
-  getRaw(): Uint8Array;
-  setRaw(raw: Bytes): void;
-}
-
-/**
- * An immutable saved Response.
- */
-export declare type Response = {
-  getId(): ID;
-  getCode(): number;
-  getHeaders(): Record<string, Array<string>>;
-  getHeader(name: string): Array<string> | undefined;
-  getBody(): Body | undefined;
-};
-
-/**
- * An immutable saved Request and Response pair.
- */
-export declare type RequestResponse = {
-  request: Request;
-  response: Response;
-};
-
-/**
- * The SDK for the Requests service.
- */
-export declare type RequestsSDK = {
-  /**
-   * Sends a request.
-   *
-   * This respects the upstream proxy settings.
-   *
-   * @throws {Error} If the request cannot be sent.
-   *
-   * @example
-   * const spec = new RequestSpec("https://example.com");
-   * sdk.requests.send(request)
-   *   .then((res) => {
-   *     console.log(res.request.getId());
-   *     console.log(res.response.getCode());
-   *   })
-   *   .catch((err) => {
-   *     console.error(err);
-   *   });
-   */
-  send(request: RequestSpec | RequestSpecRaw): Promise<RequestResponse>;
-
-  /**
-   * Checks if a request is in scope.
-   *
-   * @example
-   * if (sdk.requests.inScope(request)) {
-   *  console.log("In scope");
-   * }
-   */
-  inScope(request: Request | RequestSpec): boolean;
-};
-
-/**
- * A saved immutable Finding.
- *
- * To modify, use `toSpec` to get a `FindingSpec` object.
- */
-export declare type Finding = {
-  getId(): ID;
-  getTitle(): string;
-  getDescription(): string | undefined;
-  getReporter(): string;
-};
-
-/**
- * A mutable Finding not yet created.
- */
-export declare type FindingSpec = {
-  title: string;
-  description?: string | undefined;
-  reporter: string;
-  request: Request;
-};
-
-/**
- * The SDK for the Findings service.
- */
-export declare type FindingsSDK = {
-  /**
-   * Creates a new Finding.
-   *
-   * @throws {Error} If the request cannot be saved.
-   *
-   * @example
-   * sdk.findings.create({
-   *   title: "Title",
-   *   description: "Description",
-   *   reporter: "Reporter",
-   *   request,
-   * });
-   */
-  create(spec: FindingSpec): Promise<Finding>;
-};
-
-export declare type HttpInput = {
-  request: Request | undefined;
-  response: Response | undefined;
-};
-/**
- * @deprecated Use HttpInput instead.
- */
-export declare type PassiveInput = HttpInput;
-export declare type BytesInput = Array<number>;
-/**
- * @deprecated Use BytesInput instead.
- */
-export declare type ConvertInput = BytesInput;
-
-export declare type ID = string;
-export declare type Data = Bytes;
-export declare type Decision = boolean;
-export declare type Bytes = string | Array<number> | Uint8Array;
-export declare type MaybePromise<T> = T | Promise<T>;
-
-/**
- * The SDK object available to all scripts.
- */
-export declare type SDK = {
-  /**
-   * The console.
-   *
-   * This is currently the same as the global `console`.
-   */
-  console: Console;
-  /**
-   * The SDK for the Findings service.
-   */
-  findings: FindingsSDK;
-  /**
-   * The SDK for the Requests services
-   */
-  requests: RequestsSDK;
-  /**
-   * Converts bytes to a string.
-   *
-   * Unprintable characters will be replaced with `�`.
-   */
-  asString(array: Bytes): string;
-};