index.ts

import {Readable} from "node:stream"

export * from "./util";
export {WeakValueMap} from "./WeakValueMap";
import {BreakPoints} from "./BreakPoints";
export * from "./hybridstreams";

export const _testForRaceCondition_breakPoints = new BreakPoints();

export type UploadFile = {
    createReadStream: () => Readable
}

export type CSRFProtectionMode = "preflight" | "corsReadToken" | "csrfToken"

export type SecurityPropertiesOfHttpRequest = {
    httpMethod: string,
    /**
     * Computed origin
     * @see getOrigin
     */
    origin?: string,
    /**
     * Computed destination
     * @see getDestination
     */
    destination?: string,

    /**
     * Computed result from Util.js/browserMightHaveSecurityIssuseWithCrossOriginRequests function
     */
    browserMightHaveSecurityIssuseWithCrossOriginRequests: Boolean;

    csrfProtectionMode?: CSRFProtectionMode
    corsReadToken?: string,
    csrfToken?: string,

    /**
     * We are sure that the client proved to make a successful http read and present the result while the call had these security properties.
     * Used for socket connection.
     */
    readWasProven?: boolean

    /**
     * Computed result from couldBeSimpleRequest function
     */
    couldBeSimpleRequest?: boolean
};

/**
 * The info that's needed  to set up a socket connection
 */
export type WelcomeInfo = {
    classId: string,
    /**
     * Undefined, if the server does not support engine.io
     */
    engineIoPath?: string
};

export interface IServerSession {
    /**
     * The client needs to know some things, before creating the socket connection
     */
    getWelcomeInfo(): WelcomeInfo;

    getCookieSession(encryptedQuestion: ServerPrivateBox<GetCookieSession_question>): {state: CookieSessionState, token: ServerPrivateBox<GetCookieSessionAnswerToken>};
    getHttpSecurityProperties(encryptedQuestion: ServerPrivateBox<GetHttpSecurityProperties_question>): ServerPrivateBox<GetHttpSecurityProperties_answer>;
    getCorsReadToken(): string
    updateCookieSession(encryptedCookieSessionUpdate: ServerPrivateBox<CookieSessionUpdate>, alsoReturnNewSession: ServerPrivateBox<GetCookieSession_question>) : Promise<{state: CookieSessionState, token: ServerPrivateBox<GetCookieSessionAnswerToken>}>;
}

export interface CookieSession extends Record<string, unknown> {
    /**
     * Security: This may be readable from inside the browser.
     */
    id: string
    version: number

    /**
     * Branch protection salt. We safe and check this also in the SessionValidator
     * Because the commit to the SessionValidator does not happen at instant but before the next call, an attacker could use 2 socket connections and create 2 (/multiple) branches of CookieSessions with different content but (each time) the same version number.
     * <p>
     * More detail: To create such branching, one would have 2 socket connections, call a session-changing method, get the returned CookieSessionUpdate token and http-call the updateCookieSession() method with it **simultaneously**
     * Should be possible in a browser (cross-site attacking scenario, when allowed for a subset of ServerSessions) and no problem with a non-browser client.
     * </p>
     */
    bpSalt?: string

    /**
     * To allow for a more stupid SessionValidator that just stores [id]_[version]_[bpSalt] entry strings
     */
    previousBpSalt?: string

    commandDestruction?:boolean
}

/**
 * Sent as a public cookie and header for change-indication / detection by the socket clients.
 * See tests/session-playground
 */
export type CookieSessionState = Pick<CookieSession, "id" | "version"> | undefined; // undefined means as always: no cookie set / session not created; Do we need the bpSalt ? or is that too much bloat ?

export type Socket_Client2ServerMessage = {
    /**
     * Incremented on every call (by the client) to help put things in the proper timely order and prevent race condition bugs.
     */
    sequenceNumber: number
    type: "methodCall" | "getVersion" | "updateHttpSecurityProperties" | "setCookieSession" | "methodDownCallResult" | "channelItemNotUsedAnymore" | "streamDataRequest" | "streamData";
    payload: Socket_MethodCall | Socket_ChannelItemNotUsedAnymore | Socket_StreamDataRequest | Socket_StreamData | unknown
}

export type Socket_MethodCall = {
    /**
     * Generated by the client
     */
    callId: number

    serverSessionClassId?: string

    methodName: string,
    args: unknown[]
}

export type Socket_Server2ClientMessage = {
    /**
     * Incremented on every call (by the client) to help put things in the proper timely order and prevent race condition bugs.
     */
    sequenceNumber: number
    type: "init" | "methodCallResult" | "getVersion" | "downCall" | "channelItemNotUsedAnymore" | "streamDataRequest" | "streamData"
    payload: Socket_Server2ClientInit | Socket_MethodUpCallResult | Socket_DownCall | Socket_StreamDataRequest | Socket_StreamData | Socket_ChannelItemNotUsedAnymore
}

/**
 * Result of a client->server call
 */
export type Socket_MethodUpCallResult = {
    /**
     * Generated by the client
     */
    callId: number

    result?: unknown

    /**
     * Behaves as close as possible to the http api
     */
    status: 200 | 500 | 550 | "needsHttpSecurityProperties" | "needsCookieSession" | "doCookieSessionUpdate" | "dropped_CookieSessionIsOutdated"

    /**
     * If a CommunicationError was thrown, then that code
     */
    httpStatusCode?: number

    /**
     * If an error occurred
     */
    error?: object

    /**
     * If this is needed to proceed the call
     */
    needsHttpSecurityProperties?: {
        question: ServerPrivateBox<GetHttpSecurityProperties_question>
        /**
         * Hint for the client: The ServerSessionClass id or the security group id for which the answer is valid.
         */
        syncKey: string
    }

    /**
     * Request the cookie-session from the server by http
     */
    needsInitializedCookieSession?: ServerPrivateBox<GetCookieSession_question>

    /**
     * Commands to update the cookieSession via http (so it really gets stored in the cookie)
     */
    doCookieSessionUpdate?: ServerPrivateBox<CookieSessionUpdate>


}

export type Socket_Server2ClientInit = {
    cookieSessionRequest: ServerPrivateBox<GetCookieSession_question>
}


/**
 * Question from the websocket connection
 */
export type GetHttpSecurityProperties_question = {
    serverSocketConnectionId: string
    serverSessionClassId: string,
}

export type GetHttpSecurityProperties_answer = {
    question: GetHttpSecurityProperties_question,
    result: SecurityPropertiesOfHttpRequest
}

/**
 * Question from the websocket connection
 */
export type GetCookieSession_question = {
    serverSocketConnectionId: string
    forceInitialize: boolean;
}

export type GetCookieSessionAnswerToken = {
    question: GetCookieSession_question,
    /**
     * Can be undefined, if no session was started yet
     */
    cookieSession?: CookieSession
}

/**
 * Update the cookie session on the http side
 */
export type CookieSessionUpdate = {
    /**
     * Where did this come from ?
     */
    serverSessionClassId: string,

    newSession: CookieSession
}

/**
 * The content is encrypted and can only be read by this server, or another server that shares {@link Server#secret}
 * <p>
 * Encrypted (+MAC'ed) value in a box that points to the correct secret key that should be used to decrypt it.
 * </p>
 * - The box was encrypted by the server and it's authenticity can be trusted. It's meant to be decrypted by the server again / the client can't see the content.
 * - It stores a content type to prevent spoofing with a token on stock with a different types
 *
 */
export type ServerPrivateBox<Content> = {
    /**
     * Base64 encoded.
     * <p>
     *     <i>NOTE: Is a nonce really needed or could we save us these 24 bytes here? It won't prevent replay attacks, if handed to the client (restfuncs is aware of replay and takse other measures against these).
     *     Also data variety is enough by the current use cases (i.e. there's the ServerSocketConnection id included) and the information that 2 tokens have the same value does not hurt.
     *     But for cryptographic cleanliness we leave it in.
     *     </i>
     * </p>
     */
    nonce: string

    /**
     * Encrypted content, base64 encoded
     */
    content: string;

    /**
     * Fake property. To make ServerPrivateBox typesafe, we must reference 'Content' somewhere. Will never be set
     */
    _contentType?: Content
}

export type ChannelItemDTO = {
    _dtoType: "ClientCallback" | "UploadFile" | "Readable"
    /**
     * Chosen by the sender (usually the client)
     */
    id: number;
}

export type ClientCallbackDTO = ChannelItemDTO & {
    _dtoType: "ClientCallback",
}

/**
 * The server calls down a callback function
 */
export type Socket_DownCall = {
    id: number;
    /**
     * Client's id
     */
    callbackFnId: number

    args: unknown[]

    serverAwaitsAnswer: boolean;

    /**
     * Whether the callback function was declared as non-void
     */
    diagnosis_resultWasDeclared: boolean;
}

export type Socket_ChannelItemNotUsedAnymore = {
    id: number;

    /**
     * Include lastSequenceNumberFromClient
     */
    time: number;
}

export type Socket_StreamDataRequest = {
    /**
     * Id of the channel item (the Readable)
     */
    id: number;

    /**
     * Like in Readable._read
     */
    size: number;
}

export type Socket_StreamData = {
    /**
     * Id of the channel item (the Readable / Writable)
     */
    id: number;

    /**
     * String or base64 encoded string from buffer, or null when the end of the stream is reached / stream is closed
     * TODO: Implement better binary protocol
     */
    data: string | null;

    /**
     * When set to "buffer", then data is a buffer, encoded as base64 string
     */
    encoding: BufferEncoding | string

    /**
     * If the stream errored
     */
    error?: object
}

/**
 * Result of a server->client callback function call
 */
export type Socket_DownCallResult = {
    /**
     * Generated by the server
     */
    callId: number

    result?: unknown


    /**
     * If an error occurred
     */
    error?: object
}