@caido/sdk-backend 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Caido
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,29 @@
+<div align="center">
+  <img width="1000" alt="image" src="https://user-images.githubusercontent.com/6225588/211916659-567751d1-0225-402b-9141-4145c18b0834.png">
+
+  <br />
+  <br />
+  <a href="https://caido.io/">Website</a>
+  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+  <a href="https://dashboard.caido.io/">Dashboard</a>
+  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+  <a href="https://docs.caido.io/" target="_blank">Docs</a>
+  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+  <a href="https://links.caido.io/roadmap">Roadmap</a>
+  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+  <a href="https://github.com/caido/caido/tree/main/brand">Branding</a>
+  <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
+  <a href="https://links.caido.io/www-discord" target="_blank">Discord</a>
+  <br />
+  <hr />
+</div>
+
+## 👋 Backend SDK
+
+[![NPM Version](https://img.shields.io/npm/v/@caido/sdk-backend?style=for-the-badge)](https://www.npmjs.com/package/@caido/sdk-backend)
+
+This is repository for the Caido backend SDK. Head over to the [starter kit](https://github.com/caido/starterkit-plugin) to view it in action.
+
+## 💚 Community
+
+Come join our [Discord](https://links.caido.io/www-discord) community and connect with other Caido users! We'd love to have you as part of the conversation and help with any questions you may have.

package/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@caido/sdk-backend",
+  "version": "0.1.0",
+  "description": "Typing for the Caido Backend SDK",
+  "author": "Caido Labs Inc. <dev@caido.io>",
+  "license": "MIT",
+  "types": "./src/index.d.ts",
+  "files": [
+    "src/*"
+  ]
+}

package/src/index.d.ts

@@ -0,0 +1,3 @@
+/// <reference path="types/typing.d.ts" />
+/// <reference path="types/common.d.ts" />
+/// <reference path="types/runtime.d.ts" />

package/src/types/common.d.ts

@@ -0,0 +1,196 @@
+declare module "caido:common" {
+  /**
+   * 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.
+   *
+   * To modify, use `toSpec` to get a `FindingSpec` object.
+   */
+  export type Finding = {
+    getId(): ID;
+    getTitle(): string;
+    getDescription(): string | undefined;
+    getReporter(): string;
+  };
+
+  /**
+   * A mutable Finding not yet created.
+   */
+  export type FindingSpec = {
+    title: string;
+    description?: string | undefined;
+    reporter: string;
+    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",
+     *   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/runtime.d.ts

@@ -0,0 +1,147 @@
+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;
+  };
+
+  /**
+   * 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,47 @@
+import { MaybePromise, FindingsSDK, RequestsSDK } from "caido:common";
+
+declare module "@caido/sdk-backend" {
+  export * from "caido:common";
+
+  /**
+   * The SDK for the API RPC service.
+   */
+  export type APISDK = {
+    /**
+     * Registers a new backend function for the RPC.
+     *
+     * @example
+     * sdk.api.register("multiply", (a: number, b: number) => {
+     *    return a * b;
+     * });
+     */
+    register(
+      name: string,
+      callback: (...args: unknown[]) => MaybePromise<unknown>,
+    ): void;
+  };
+
+  /**
+   * 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;
+    /**
+     * The SDK for the API RPC service.
+     */
+    api: APISDK;
+  };
+}