@php-wasm/web 1.0.4 → 1.0.6

package/lib/index.d.ts

@@ -7,3 +7,5 @@ export { setupPostMessageRelay } from './setup-post-message-relay';
 export { spawnPHPWorkerThread } from './worker-thread/spawn-php-worker-thread';
 export { createDirectoryHandleMountHandler } from './directory-handle-mount';
 export type { MountDevice, MountOptions, SyncProgress, SyncProgressCallback, } from './directory-handle-mount';
+export * from './tls/certificates';
+export type { TCPOverFetchOptions } from './tcp-over-fetch-websocket';

package/lib/load-runtime.d.ts

@@ -1,8 +1,8 @@
 import { EmscriptenOptions, PHPLoaderModule, SupportedPHPVersion } from '@php-wasm/universal';
+import { TCPOverFetchOptions } from './tcp-over-fetch-websocket';
 export interface LoaderOptions {
     emscriptenOptions?: EmscriptenOptions;
     onPhpLoaderModuleLoaded?: (module: PHPLoaderModule) => void;
-    /** @deprecated To be replaced with `extensions` in the future */
-    loadAllExtensions?: boolean;
+    tcpOverFetch?: TCPOverFetchOptions;
 }
 export declare function loadWebRuntime(phpVersion: SupportedPHPVersion, options?: LoaderOptions): Promise<number>;

package/lib/tcp-over-fetch-websocket.d.ts

@@ -0,0 +1,108 @@
+import { GeneratedCertificate } from './tls/certificates';
+export type TCPOverFetchOptions = {
+    CAroot: GeneratedCertificate;
+};
+/**
+ * Sets up a WebSocket that analyzes the received bytes and, if they look like
+ * TLS or HTTP, handles the network transmission using fetch().
+ */
+export declare const tcpOverFetchWebsocket: (tcpOptions: TCPOverFetchOptions) => {
+    websocket: {
+        url: (_: any, host: string, port: string) => string;
+        subprotocol: string;
+        decorator: () => {
+            new (url: string, wsOptions: string[]): {
+                CONNECTING: number;
+                OPEN: number;
+                CLOSING: number;
+                CLOSED: number;
+                readyState: number;
+                binaryType: string;
+                bufferedAmount: number;
+                extensions: string;
+                protocol: string;
+                host: string;
+                port: number;
+                listeners: Map<string, any>;
+                CAroot?: GeneratedCertificate | undefined;
+                clientUpstream: TransformStream<any, any>;
+                clientUpstreamWriter: WritableStreamDefaultWriter<any>;
+                clientDownstream: TransformStream<any, any>;
+                fetchInitiated: boolean;
+                bufferedBytesFromClient: Uint8Array;
+                url: string;
+                options: string[];
+                on(eventName: string, callback: (e: any) => void): void;
+                once(eventName: string, callback: (e: any) => void): void;
+                addEventListener(eventName: string, callback: (e: any) => void): void;
+                removeListener(eventName: string, callback: (e: any) => void): void;
+                removeEventListener(eventName: string, callback: (e: any) => void): void;
+                emit(eventName: string, data?: any): void;
+                onclose(data: any): void;
+                onerror(data: any): void;
+                onmessage(data: any): void;
+                onopen(data: any): void;
+                /**
+                 * Emscripten calls this method whenever the WASM module
+                 * writes bytes to the TCP socket.
+                 */
+                send(data: ArrayBuffer): void;
+                fetchOverTLS(): Promise<void>;
+                fetchOverHTTP(): Promise<void>;
+                close(): void;
+            };
+        };
+    };
+};
+export interface TCPOverFetchWebsocketOptions {
+    CAroot?: GeneratedCertificate;
+    /**
+     * If true, the WebSocket will emit 'message' events with the received bytes
+     * and the 'close' event when the WebSocket is closed.
+     *
+     * If false, the consumer will be responsible for reading the bytes from the
+     * clientDownstream stream and tracking the closure of that stream.
+     */
+    outputType?: 'messages' | 'stream';
+}
+export declare class TCPOverFetchWebsocket {
+    url: string;
+    options: string[];
+    CONNECTING: number;
+    OPEN: number;
+    CLOSING: number;
+    CLOSED: number;
+    readyState: number;
+    binaryType: string;
+    bufferedAmount: number;
+    extensions: string;
+    protocol: string;
+    host: string;
+    port: number;
+    listeners: Map<string, any>;
+    CAroot?: GeneratedCertificate;
+    clientUpstream: TransformStream<any, any>;
+    clientUpstreamWriter: WritableStreamDefaultWriter<any>;
+    clientDownstream: TransformStream<any, any>;
+    fetchInitiated: boolean;
+    bufferedBytesFromClient: Uint8Array;
+    constructor(url: string, options: string[], { CAroot, outputType }?: TCPOverFetchWebsocketOptions);
+    on(eventName: string, callback: (e: any) => void): void;
+    once(eventName: string, callback: (e: any) => void): void;
+    addEventListener(eventName: string, callback: (e: any) => void): void;
+    removeListener(eventName: string, callback: (e: any) => void): void;
+    removeEventListener(eventName: string, callback: (e: any) => void): void;
+    emit(eventName: string, data?: any): void;
+    onclose(data: any): void;
+    onerror(data: any): void;
+    onmessage(data: any): void;
+    onopen(data: any): void;
+    /**
+     * Emscripten calls this method whenever the WASM module
+     * writes bytes to the TCP socket.
+     */
+    send(data: ArrayBuffer): void;
+    fetchOverTLS(): Promise<void>;
+    fetchOverHTTP(): Promise<void>;
+    close(): void;
+}

package/lib/tls/1_2/connection.d.ts

@@ -0,0 +1,194 @@
+/**
+ * This isomorphic class implements the server end of
+ * the client <-> server TLS 1.2 connection. It has two ends:
+ *
+ * * Client end, that emits and accepts TLS encrypted data.
+ * * Server end, that emits and accepts unencrypted data.
+ *
+ * The API consumer is responsible for connecting both ends
+ * to the appropriate handlers.
+ *
+ * See https://datatracker.ietf.org/doc/html/rfc5246.
+ *
+ * ## Warning
+ *
+ * **WARNING** NEVER USE THIS CODE AS A SERVER-SIDE TLS HANDLER.
+ *
+ * This code is not secure. It is a minimal subset required
+ * to decrypt the TLS traffic from a PHP-wasm worker. Yes,
+ * it can speak TLS. No, it won't protect your data.
+ *
+ * ## Rationale
+ *
+ * This is useful for running PHP.wasm in web browsers.
+ * Function calls such as `file_get_contents("https://w.org")`
+ * emit encrypted TLS traffic. With this class, you
+ * can decrypt it, serve the requested data, and encrypt
+ * the response before passing it back to the PHP.wasm
+ * module.
+ *
+ * ## Implementation details
+ *
+ * TLS_1_2_Connection implements the minimal subset of TLS 1.2
+ * required to exchange encrypted data with PHP.wasm:
+ *
+ * * TLS Handshake
+ * * All TLS 1.2 record types, including messages spanning multiple
+ *   records and empty records.
+ * * Encryption and decryption of application data.
+ * * Auto-chunking long data blobs before encrypting them to
+ *   respect the AES-GCM record size limit.
+ *
+ * The logic is based on numerous RFCs:
+ *
+ * * RFC 5246: The TLS Protocol Version 1.2
+ * * RFC 8446: TLS 1.3
+ * * RFC 6066: TLS Extensions
+ * * RFC 4492: Elliptic Curve Cryptography (ECC) Cipher Suites for TLS
+ * * RFC 5288: AES Galois Counter Mode (GCM) Cipher Suites for TLS
+ * * RFC 6070: PKCS #5: Password-Based Key Derivation Function 2 (PBKDF2) Test Vectors
+ *
+ * ... and a few others.
+ *
+ * ## Limitations
+ *
+ * * Multiple ChangeCipherSpec messages are not supported.
+ * * Only uncompressed mode (compression method 0) is supported.
+ * * Only the TLS1_CK_ECDHE_RSA_WITH_AES_128_GCM_SHA256 cipher suite is
+ *   supported, primarily because `crypto.subtle` supports AES-GCM.
+ *   For AES-GCM details, see https://datatracker.ietf.org/doc/html/rfc5288.
+ */
+export declare class TLS_1_2_Connection {
+    /**
+     * Sequence number of the last received TLS  record.
+     *
+     * AES-GCM requires transmitting the sequence number
+     * in the clear in the additional data to prevent a
+     * potential attacker from re-transmitting the same
+     * TLS record in a different context.
+     */
+    private receivedRecordSequenceNumber;
+    /**
+     * Sequence number of the last sent TLS record.
+     *
+     * AES-GCM requires transmitting the sequence number
+     * in the clear in the additional data to prevent a
+     * potential attacker from re-transmitting the same
+     * TLS record in a different context.
+     */
+    private sentRecordSequenceNumber;
+    /**
+     * Encryption keys for this connection derived during
+     * the TLS handshake.
+     */
+    private sessionKeys;
+    /**
+     * Whether this connection have been closed.
+     */
+    private closed;
+    /**
+     * Bytes received from the client but not yet parsed
+     * as TLS records.
+     */
+    private receivedBytesBuffer;
+    /**
+     * TLS records received from the client but not yet
+     * parsed as TLS messages.
+     */
+    private receivedTLSRecords;
+    /**
+     * TLS messages can span multiple TLS records. This
+     * map holds partial TLS messages that are still incomplete
+     * after parsing one or more TLS records.
+     */
+    private partialTLSMessages;
+    /**
+     * A log of all the exchanged TLS handshake messages.
+     * This is required to build the Finished message and
+     * verify the integrity of the handshake.
+     */
+    private handshakeMessages;
+    /**
+     * Maximum chunk size supported by the cipher suite used
+     * in this TLS implementation.
+     */
+    private MAX_CHUNK_SIZE;
+    /**
+     * The client end of the TLS connection.
+     * This is where the WASM module can write and read the
+     * encrypted data.
+     */
+    clientEnd: {
+        upstream: TransformStream<Uint8Array, Uint8Array>;
+        downstream: TransformStream<Uint8Array, Uint8Array>;
+    };
+    private clientDownstreamWriter;
+    private clientUpstreamReader;
+    /**
+     * The server end of the TLS connection.
+     * This is where the JavaScript handler can write and read the
+     * unencrypted data.
+     */
+    serverEnd: {
+        upstream: TransformStream<Uint8Array, Uint8Array>;
+        /**
+         * Chunk the data before encrypting it. The
+         * TLS1_CK_ECDHE_RSA_WITH_AES_128_GCM_SHA256 cipher suite
+         * only supports up to 16KB of data per record.
+         *
+         * This will spread some messages across multiple records,
+         * but TLS supports it so that's fine.
+         */
+        downstream: TransformStream<any, any>;
+    };
+    private serverUpstreamWriter;
+    constructor();
+    /**
+     * Marks this connections as closed and closes all the associated
+     * streams.
+     */
+    close(): Promise<void>;
+    /**
+     * TLS handshake as per RFC 5246.
+     *
+     * https://datatracker.ietf.org/doc/html/rfc5246#section-7.4
+     */
+    TLSHandshake(certificatePrivateKey: CryptoKey, certificatesDER: Uint8Array[]): Promise<void>;
+    /**
+     * Derives the session keys from the random values and the
+     * pre-master secret – as per RFC 5246.
+     */
+    private deriveSessionKeys;
+    private readNextHandshakeMessage;
+    private readNextMessage;
+    private readNextTLSRecord;
+    /**
+     * Returns the requested number of bytes from the client.
+     * Waits for the bytes to arrive if necessary.
+     */
+    private pollBytes;
+    /**
+     * Listens for all incoming messages and passes them to the
+     * server handler.
+     */
+    private pollForClientMessages;
+    /**
+     * Decrypts data in a TLS 1.2-compliant manner using
+     * the AES-GCM algorithm.
+     */
+    private decryptData;
+    private accumulateUntilMessageIsComplete;
+    /**
+     * Passes a TLS record to the client.
+     *
+     * Accepts unencrypted data and ensures it gets encrypted
+     * if needed before sending it to the client. The encryption
+     * only kicks in after the handshake is complete.
+     */
+    private writeTLSRecord;
+    /**
+     * Encrypts data in a TLS 1.2-compliant manner using
+     * the AES-GCM algorithm.
+     */
+    private encryptData;
+}

package/lib/tls/1_2/prf.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Implements the TLS 1.2 PRF using HMAC-SHA256.
+ *
+ * See https://datatracker.ietf.org/doc/html/rfc5246#section-5
+ */
+export declare function tls12Prf(secret: ArrayBuffer, label: ArrayBuffer, seed: ArrayBuffer, outputLength: number): Promise<ArrayBuffer>;
+export declare function hmacSha256(key: CryptoKey, data: ArrayBuffer): Promise<ArrayBuffer>;

package/lib/tls/1_2/types.d.ts

@@ -0,0 +1,223 @@
+/**
+ * TLS 1.2 Record layer types defined after the structs
+ * from the TLS 1.2 RFC.
+ * https://datatracker.ietf.org/doc/html/rfc5246#section-6.2
+ */
+import { ParsedExtension } from '../extensions/parse-extensions';
+export declare const enum CompressionMethod {
+    Null = 0,
+    Deflate = 1
+}
+/**
+ * TLS 1.2 Record layer types defined after the structs
+ * from the TLS 1.2 RFC.
+ * https://datatracker.ietf.org/doc/html/rfc5246#section-6.2.1
+ */
+export interface TLSRecord {
+    type: ContentType;
+    version: ProtocolVersion;
+    length: number;
+    fragment: Uint8Array;
+}
+export interface ProtocolVersion {
+    major: number;
+    minor: number;
+}
+export interface GenericStreamCipher {
+    content: Uint8Array;
+    MAC: Uint8Array;
+}
+export interface GenericBlockCipher {
+    IV: Uint8Array;
+    block_ciphered: BlockCiphered;
+}
+export interface BlockCiphered {
+    content: Uint8Array;
+    MAC: Uint8Array;
+    padding: Uint8Array;
+    padding_length: number;
+}
+export interface GenericAEADCipher {
+    nonce_explicit: Uint8Array;
+    aead_encrypted: Uint8Array;
+}
+/**
+ * TLS 1.2 Handshake types defined after the structs
+ * from the TLS 1.2 RFC.
+ * https://datatracker.ietf.org/doc/html/rfc5246#section-7.4
+ */
+export type TLSMessage = AlertMessage | HandshakeMessage<any> | ChangeCipherSpecMessage | ApplicationDataMessage;
+export interface AlertMessage {
+    type: typeof ContentTypes.Alert;
+    level: AlertLevel;
+    description: AlertDescription;
+}
+export declare const AlertLevels: {
+    readonly Warning: 1;
+    readonly Fatal: 2;
+};
+export type AlertLevel = (typeof AlertLevels)[keyof typeof AlertLevels];
+export declare const AlertLevelNames: any;
+export declare const AlertDescriptions: {
+    readonly CloseNotify: 0;
+    readonly UnexpectedMessage: 10;
+    readonly BadRecordMac: 20;
+    readonly DecryptionFailed: 21;
+    readonly RecordOverflow: 22;
+    readonly DecompressionFailure: 30;
+    readonly HandshakeFailure: 40;
+    readonly NoCertificate: 41;
+    readonly BadCertificate: 42;
+    readonly UnsupportedCertificate: 43;
+    readonly CertificateRevoked: 44;
+    readonly CertificateExpired: 45;
+    readonly CertificateUnknown: 46;
+    readonly IllegalParameter: 47;
+    readonly UnknownCa: 48;
+    readonly AccessDenied: 49;
+    readonly DecodeError: 50;
+    readonly DecryptError: 51;
+    readonly ExportRestriction: 60;
+    readonly ProtocolVersion: 70;
+    readonly InsufficientSecurity: 71;
+    readonly InternalError: 80;
+    readonly UserCanceled: 90;
+    readonly NoRenegotiation: 100;
+    readonly UnsupportedExtension: 110;
+};
+export type AlertDescription = (typeof AlertDescriptions)[keyof typeof AlertDescriptions];
+export declare const AlertDescriptionNames: any;
+export interface ChangeCipherSpecMessage {
+    type: typeof ContentTypes.ChangeCipherSpec;
+    body: Uint8Array;
+}
+export interface ApplicationDataMessage {
+    type: typeof ContentTypes.ApplicationData;
+    body: Uint8Array;
+}
+export declare const ContentTypes: {
+    readonly ChangeCipherSpec: 20;
+    readonly Alert: 21;
+    readonly Handshake: 22;
+    readonly ApplicationData: 23;
+};
+export type ContentType = (typeof ContentTypes)[keyof typeof ContentTypes];
+export declare const enum HandshakeType {
+    HelloRequest = 0,
+    ClientHello = 1,
+    ServerHello = 2,
+    Certificate = 11,
+    ServerKeyExchange = 12,
+    CertificateRequest = 13,
+    ServerHelloDone = 14,
+    CertificateVerify = 15,
+    ClientKeyExchange = 16,
+    Finished = 20
+}
+export type HandshakeMessageBody = HelloRequest | ClientHello | ServerHello | Certificate | ServerKeyExchange | CertificateRequest | ServerHelloDone | CertificateVerify | ClientKeyExchange | Finished;
+export interface HandshakeMessage<Body extends HandshakeMessageBody> {
+    type: typeof ContentTypes.Handshake;
+    msg_type: HandshakeType;
+    length: number;
+    body: Body;
+}
+export interface HelloRequest {
+}
+/**
+ * 1 byte
+ */
+export type SessionId = Uint8Array;
+export interface ClientHello {
+    client_version: Uint8Array;
+    random: Uint8Array;
+    session_id: SessionId;
+    cipher_suites: string[];
+    compression_methods: Uint8Array;
+    extensions: ParsedExtension[];
+}
+export interface ServerHello {
+    server_version: Uint8Array;
+    random: Uint8Array;
+    session_id: Uint8Array;
+    cipher_suite: Uint8Array;
+    compression_method: number;
+    extensions?: Uint8Array;
+}
+export interface Certificate {
+    certificate_list: Uint8Array[];
+}
+export interface ServerKeyExchange {
+    params: Uint8Array;
+    signed_params: Uint8Array;
+}
+/**
+ * ECCurveType from
+ * https://datatracker.ietf.org/doc/html/rfc4492#section-5.4
+ */
+export declare const ECCurveTypes: {
+    /**
+     * Indicates the elliptic curve domain parameters are
+     * conveyed verbosely, and the underlying finite field is a prime
+     * field.
+     */
+    ExplicitPrime: number;
+    /**
+     * Indicates the elliptic curve domain parameters are
+     * conveyed verbosely, and the underlying finite field is a
+     * characteristic-2 field.
+     */
+    ExplicitChar2: number;
+    /**
+     * Indicates that a named curve is used.  This option
+     * SHOULD be used when applicable.
+     */
+    NamedCurve: number;
+};
+/**
+ * Named elliptic curves from
+ * https://datatracker.ietf.org/doc/html/rfc4492#section-5.1.1
+ */
+export declare const ECNamedCurves: {
+    sect163k1: number;
+    sect163r1: number;
+    sect163r2: number;
+    sect193r1: number;
+    sect193r2: number;
+    sect233k1: number;
+    sect233r1: number;
+    sect239k1: number;
+    sect283k1: number;
+    sect283r1: number;
+    sect409k1: number;
+    sect409r1: number;
+    secp256k1: number;
+    secp256r1: number;
+    secp384r1: number;
+    secp521r1: number;
+    arbitrary_explicit_prime_curves: number;
+    arbitrary_explicit_char2_curves: number;
+};
+export interface CertificateRequest {
+    certificate_types: Uint8Array;
+    supported_signature_algorithms: Uint8Array;
+    certificate_authorities: Uint8Array;
+}
+export interface ServerHelloDone {
+}
+export interface CertificateVerify {
+    algorithm: Uint8Array;
+    signature: Uint8Array;
+}
+export interface ClientKeyExchange {
+    exchange_keys: Uint8Array;
+}
+export interface Finished {
+    verify_data: Uint8Array;
+}
+export type SessionKeys = {
+    masterSecret: Uint8Array;
+    clientWriteKey: CryptoKey;
+    serverWriteKey: CryptoKey;
+    clientIV: Uint8Array;
+    serverIV: Uint8Array;
+};