@zero-server/grpc 0.9.0 → 0.9.2

package/lib/grpc/credentials.js

@@ -0,0 +1,398 @@
+/**
+ * @module grpc/credentials
+ * @description Channel credentials for gRPC connections.
+ *              Provides factory functions for creating insecure, SSL/TLS,
+ *              and metadata-based credentials. Supports certificate rotation
+ *              and credential composition.
+ *
+ *              Uses only Node.js built-in `tls` and `fs` — no external packages.
+ *
+ * @example | Insecure (plaintext)
+ *   const { ChannelCredentials, GrpcClient } = require('@zero-server/sdk');
+ *   const creds = ChannelCredentials.createInsecure();
+ *   const client = new GrpcClient({ address: 'http://localhost:50051', credentials: creds }, schema, 'Greeter');
+ *
+ * @example | Server-only TLS
+ *   const creds = ChannelCredentials.createSsl(fs.readFileSync('ca.pem'));
+ *
+ * @example | Mutual TLS (mTLS)
+ *   const creds = ChannelCredentials.createSsl(
+ *       fs.readFileSync('ca.pem'),
+ *       fs.readFileSync('client-key.pem'),
+ *       fs.readFileSync('client-cert.pem'),
+ *   );
+ *
+ * @example | Metadata credentials (e.g. Bearer token)
+ *   const creds = ChannelCredentials.createFromMetadata((params) => ({
+ *       authorization: 'Bearer ' + getToken(),
+ *   }));
+ *
+ * @example | Composed credentials (TLS + per-call metadata)
+ *   const creds = ChannelCredentials.combine(
+ *       ChannelCredentials.createSsl(ca),
+ *       ChannelCredentials.createFromMetadata(() => ({ authorization: 'Bearer ' + token })),
+ *   );
+ */
+
+const fs = require('fs');
+const log = require('../debug')('zero:grpc:credentials');
+
+// -- Credential Types ----------------------------------------
+
+/** @enum {string} */
+const CredentialType = {
+    INSECURE: 'insecure',
+    SSL: 'ssl',
+    METADATA: 'metadata',
+    COMPOSITE: 'composite',
+};
+
+// -- ChannelCredentials Class --------------------------------
+
+/**
+ * Channel credentials define how a gRPC client authenticates to the server.
+ *
+ * @class
+ */
+class ChannelCredentials
+{
+    /**
+     * @param {string} type - Credential type.
+     * @param {object} [config] - Type-specific configuration.
+     * @private
+     */
+    constructor(type, config = {})
+    {
+        /** @type {string} */
+        this.type = type;
+        /** @private */
+        this._config = config;
+    }
+
+    /**
+     * Create insecure (plaintext) credentials.
+     * No TLS — suitable for development or service-mesh environments
+     * where transport security is handled by the infrastructure.
+     *
+     * @returns {ChannelCredentials}
+     */
+    static createInsecure()
+    {
+        return new ChannelCredentials(CredentialType.INSECURE);
+    }
+
+    /**
+     * Create SSL/TLS credentials.
+     *
+     * @param {Buffer|string|null} [rootCerts] - Root CA certificate(s) in PEM format.
+     *        If null, uses the system default trust store.
+     * @param {Buffer|string|null} [clientKey] - Client private key in PEM format (for mTLS).
+     * @param {Buffer|string|null} [clientCert] - Client certificate in PEM format (for mTLS).
+     * @param {object} [opts] - Additional options.
+     * @param {boolean} [opts.rejectUnauthorized=true] - Reject connections with invalid certs.
+     * @returns {ChannelCredentials}
+     *
+     * @example | Server-only TLS
+     *   const creds = ChannelCredentials.createSsl(fs.readFileSync('ca.pem'));
+     *
+     * @example | Mutual TLS
+     *   const creds = ChannelCredentials.createSsl(caPem, keyPem, certPem);
+     */
+    static createSsl(rootCerts, clientKey, clientCert, opts = {})
+    {
+        const config = {
+            rejectUnauthorized: opts.rejectUnauthorized !== false,
+        };
+
+        if (rootCerts)
+        {
+            config.ca = Buffer.isBuffer(rootCerts) ? rootCerts : Buffer.from(rootCerts);
+        }
+        if (clientKey)
+        {
+            config.key = Buffer.isBuffer(clientKey) ? clientKey : Buffer.from(clientKey);
+        }
+        if (clientCert)
+        {
+            config.cert = Buffer.isBuffer(clientCert) ? clientCert : Buffer.from(clientCert);
+        }
+
+        if (config.key && !config.cert)
+            throw new Error('Client key provided without client certificate');
+        if (config.cert && !config.key)
+            throw new Error('Client certificate provided without client key');
+
+        return new ChannelCredentials(CredentialType.SSL, config);
+    }
+
+    /**
+     * Create SSL credentials from PEM file paths.
+     * Files are read once at creation time.
+     *
+     * @param {string|null} [caPath] - Path to CA certificate file.
+     * @param {string|null} [keyPath] - Path to client key file.
+     * @param {string|null} [certPath] - Path to client certificate file.
+     * @param {object} [opts] - Additional options.
+     * @returns {ChannelCredentials}
+     *
+     * @example
+     *   const creds = ChannelCredentials.createSslFromFiles('./certs/ca.pem', './certs/client.key', './certs/client.pem');
+     */
+    static createSslFromFiles(caPath, keyPath, certPath, opts = {})
+    {
+        const ca = caPath ? fs.readFileSync(caPath) : null;
+        const key = keyPath ? fs.readFileSync(keyPath) : null;
+        const cert = certPath ? fs.readFileSync(certPath) : null;
+        return ChannelCredentials.createSsl(ca, key, cert, opts);
+    }
+
+    /**
+     * Create per-call metadata credentials.
+     * The generator function is called before each RPC to produce
+     * metadata headers (e.g. authorization tokens).
+     *
+     * @param {Function} metadataGenerator - `(params?) => object|Promise<object>`.
+     *        Returns key-value pairs to merge into call metadata.
+     *        `params` includes `{ serviceUrl, methodName }`.
+     * @returns {ChannelCredentials}
+     *
+     * @example
+     *   const creds = ChannelCredentials.createFromMetadata(async () => ({
+     *       authorization: 'Bearer ' + await getAccessToken(),
+     *   }));
+     */
+    static createFromMetadata(metadataGenerator)
+    {
+        if (typeof metadataGenerator !== 'function')
+            throw new Error('createFromMetadata requires a function');
+
+        return new ChannelCredentials(CredentialType.METADATA, {
+            generator: metadataGenerator,
+        });
+    }
+
+    /**
+     * Combine multiple credentials into one.
+     * At most one channel credential (insecure/SSL) and any number
+     * of call credentials (metadata) can be combined.
+     *
+     * @param {...ChannelCredentials} credentials - Credentials to combine.
+     * @returns {ChannelCredentials}
+     *
+     * @example
+     *   const creds = ChannelCredentials.combine(
+     *       ChannelCredentials.createSsl(ca),
+     *       ChannelCredentials.createFromMetadata(() => ({ 'x-api-key': apiKey })),
+     *       ChannelCredentials.createFromMetadata(async () => ({ authorization: 'Bearer ' + token })),
+     *   );
+     */
+    static combine(...credentials)
+    {
+        let channelCred = null;
+        const metadataGens = [];
+
+        for (const cred of credentials)
+        {
+            if (!(cred instanceof ChannelCredentials))
+                throw new Error('combine() arguments must be ChannelCredentials instances');
+
+            if (cred.type === CredentialType.COMPOSITE)
+            {
+                // Flatten nested composites
+                if (cred._config.channelCred) channelCred = cred._config.channelCred;
+                metadataGens.push(...cred._config.metadataGenerators);
+            }
+            else if (cred.type === CredentialType.INSECURE || cred.type === CredentialType.SSL)
+            {
+                if (channelCred)
+                    throw new Error('Cannot combine multiple channel credentials (use at most one insecure/SSL)');
+                channelCred = cred;
+            }
+            else if (cred.type === CredentialType.METADATA)
+            {
+                metadataGens.push(cred._config.generator);
+            }
+        }
+
+        return new ChannelCredentials(CredentialType.COMPOSITE, {
+            channelCred,
+            metadataGenerators: metadataGens,
+        });
+    }
+
+    /**
+     * Whether this credential uses TLS.
+     * @returns {boolean}
+     */
+    isSecure()
+    {
+        if (this.type === CredentialType.INSECURE) return false;
+        if (this.type === CredentialType.SSL) return true;
+        if (this.type === CredentialType.METADATA) return false;
+        if (this.type === CredentialType.COMPOSITE)
+        {
+            const ch = this._config.channelCred;
+            return ch ? ch.isSecure() : false;
+        }
+        return false;
+    }
+
+    /**
+     * Get the TLS connection options for `http2.connect()`.
+     * Returns `null` for insecure/metadata-only credentials.
+     *
+     * @returns {object|null} TLS options `{ ca, key, cert, rejectUnauthorized }`.
+     */
+    getConnectionOptions()
+    {
+        if (this.type === CredentialType.SSL)
+        {
+            const opts = {};
+            if (this._config.ca) opts.ca = this._config.ca;
+            if (this._config.key) opts.key = this._config.key;
+            if (this._config.cert) opts.cert = this._config.cert;
+            opts.rejectUnauthorized = this._config.rejectUnauthorized;
+            return opts;
+        }
+
+        if (this.type === CredentialType.COMPOSITE && this._config.channelCred)
+        {
+            return this._config.channelCred.getConnectionOptions();
+        }
+
+        return null;
+    }
+
+    /**
+     * Generate per-call metadata by running all metadata generators.
+     *
+     * @param {object} [params] - Call parameters `{ serviceUrl, methodName }`.
+     * @returns {Promise<object>} Merged metadata key-value pairs.
+     */
+    async generateMetadata(params)
+    {
+        const generators = [];
+
+        if (this.type === CredentialType.METADATA)
+        {
+            generators.push(this._config.generator);
+        }
+        else if (this.type === CredentialType.COMPOSITE)
+        {
+            generators.push(...this._config.metadataGenerators);
+        }
+
+        if (generators.length === 0) return {};
+
+        const merged = {};
+        for (const gen of generators)
+        {
+            const md = await gen(params);
+            if (md && typeof md === 'object')
+            {
+                Object.assign(merged, md);
+            }
+        }
+
+        return merged;
+    }
+}
+
+// -- Certificate Rotation Helper ---------------------------------
+
+/**
+ * Create SSL credentials with automatic certificate rotation.
+ * Watches certificate files for changes and reloads them.
+ *
+ * Returns a credentials-like object with `getCurrent()` to get
+ * the latest credentials and `stop()` to cease watching.
+ *
+ * @param {object} opts - Options.
+ * @param {string} opts.caPath - Path to CA certificate file.
+ * @param {string} [opts.keyPath] - Path to client key file (for mTLS).
+ * @param {string} [opts.certPath] - Path to client certificate file (for mTLS).
+ * @param {number} [opts.pollInterval=30000] - Check interval in ms (default 30s).
+ * @param {object} [opts.sslOpts] - Additional SSL options.
+ * @returns {{ getCurrent: () => ChannelCredentials, stop: () => void }}
+ *
+ * @example
+ *   const rotating = createRotatingCredentials({
+ *       caPath: '/certs/ca.pem',
+ *       keyPath: '/certs/client.key',
+ *       certPath: '/certs/client.pem',
+ *   });
+ *   // Use rotating.getCurrent() when creating clients
+ *   const client = new GrpcClient({ address, credentials: rotating.getCurrent() }, schema, service);
+ *   // Stop watching on shutdown
+ *   rotating.stop();
+ */
+function createRotatingCredentials(opts)
+{
+    if (!opts || !opts.caPath)
+        throw new Error('createRotatingCredentials requires caPath');
+
+    let current = ChannelCredentials.createSslFromFiles(
+        opts.caPath, opts.keyPath || null, opts.certPath || null, opts.sslOpts || {}
+    );
+
+    /** @private */ let lastMtimes = _getMtimes(opts);
+
+    const timer = setInterval(() =>
+    {
+        try
+        {
+            const mtimes = _getMtimes(opts);
+            if (mtimes.ca !== lastMtimes.ca ||
+                mtimes.key !== lastMtimes.key ||
+                mtimes.cert !== lastMtimes.cert)
+            {
+                current = ChannelCredentials.createSslFromFiles(
+                    opts.caPath, opts.keyPath || null, opts.certPath || null, opts.sslOpts || {}
+                );
+                lastMtimes = mtimes;
+                log.info('SSL credentials rotated');
+            }
+        }
+        catch (err)
+        {
+            log.error('credential rotation check failed: %s', err.message);
+        }
+    }, opts.pollInterval || 30000);
+
+    if (timer.unref) timer.unref();
+
+    return {
+        getCurrent() { return current; },
+        stop() { clearInterval(timer); },
+    };
+}
+
+/**
+ * Get file modification times.
+ * @private
+ */
+function _getMtimes(opts)
+{
+    return {
+        ca: opts.caPath ? _safeMtime(opts.caPath) : 0,
+        key: opts.keyPath ? _safeMtime(opts.keyPath) : 0,
+        cert: opts.certPath ? _safeMtime(opts.certPath) : 0,
+    };
+}
+
+/**
+ * @private
+ */
+function _safeMtime(filePath)
+{
+    try { return fs.statSync(filePath).mtimeMs; }
+    catch (_) { return 0; }
+}
+
+// -- Exports -------------------------------------------------
+
+module.exports = {
+    ChannelCredentials,
+    CredentialType,
+    createRotatingCredentials,
+};

package/lib/grpc/frame.js

@@ -0,0 +1,262 @@
+/**
+ * @module grpc/frame
+ * @description gRPC length-prefixed message framing over HTTP/2.
+ *              Each gRPC message on the wire has a 5-byte header:
+ *              - Byte 0:   Compression flag (0 = uncompressed, 1 = compressed)
+ *              - Bytes 1-4: Message length as 32-bit big-endian unsigned integer
+ *              Followed by the protobuf-encoded message body.
+ *
+ *              Also handles optional gzip compression/decompression.
+ *
+ * @see https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md
+ */
+
+const zlib = require('zlib');
+const log = require('../debug')('zero:grpc');
+
+// -- Constants ---------------------------------------------
+
+/**
+ * Size of the gRPC frame header in bytes.
+ * @type {number}
+ */
+const FRAME_HEADER_SIZE = 5;
+
+/**
+ * Maximum frame size (16 MB — matches the default gRPC max).
+ * @type {number}
+ */
+const MAX_FRAME_SIZE = 16 * 1024 * 1024;
+
+/**
+ * Compression flag values.
+ * @enum {number}
+ */
+const COMPRESS_FLAG = {
+    NONE: 0,
+    GZIP: 1,
+};
+
+// -- Frame Encoder -----------------------------------------
+
+/**
+ * Encode a protobuf message buffer into a gRPC framed message.
+ *
+ * @param {Buffer} message - Protobuf-encoded message data.
+ * @param {object} [opts] - Framing options.
+ * @param {boolean} [opts.compress=false] - Whether to gzip-compress the message.
+ * @returns {Promise<Buffer>|Buffer} Framed message (async if compressing).
+ *
+ * @example
+ *   const frame = frameEncode(protobufBytes);
+ *   stream.write(frame);
+ *
+ * @example | With compression
+ *   const frame = await frameEncode(protobufBytes, { compress: true });
+ */
+function frameEncode(message, opts = {})
+{
+    if (!Buffer.isBuffer(message))
+        message = Buffer.from(message || []);
+
+    if (opts.compress)
+    {
+        return new Promise((resolve, reject) =>
+        {
+            zlib.gzip(message, (err, compressed) =>
+            {
+                if (err) return reject(err);
+                resolve(_buildFrame(compressed, COMPRESS_FLAG.GZIP));
+            });
+        });
+    }
+
+    return _buildFrame(message, COMPRESS_FLAG.NONE);
+}
+
+/**
+ * Build the 5-byte header + payload buffer.
+ * @private
+ * @param {Buffer} payload
+ * @param {number} flag
+ * @returns {Buffer}
+ */
+function _buildFrame(payload, flag)
+{
+    const header = Buffer.alloc(FRAME_HEADER_SIZE);
+    header[0] = flag;
+    header.writeUInt32BE(payload.length, 1);
+    return Buffer.concat([header, payload]);
+}
+
+// -- Frame Decoder -----------------------------------------
+
+/**
+ * Stateful gRPC frame parser — buffers incoming data and emits complete
+ * decompressed messages.  Designed to be fed chunks from an HTTP/2 stream.
+ *
+ * @class
+ *
+ * @param {object} [opts] - Parser options.
+ * @param {number} [opts.maxMessageSize=16777216] - Maximum allowed message size in bytes.
+ * @param {boolean} [opts.allowCompressed=true] - Whether to accept compressed frames.
+ *
+ * @example
+ *   const parser = new FrameParser();
+ *   parser.onMessage = (buf) => { /* fully deframed protobuf bytes *​/ };
+ *   stream.on('data', (chunk) => parser.push(chunk));
+ */
+class FrameParser
+{
+    /**
+     * @constructor
+     * @param {object} [opts] - Parser options.
+     * @param {number} [opts.maxMessageSize=16777216] - Max message size.
+     * @param {boolean} [opts.allowCompressed=true] - Accept gzip frames.
+     */
+    constructor(opts = {})
+    {
+        /** @private */
+        this._buffer = Buffer.alloc(0);
+        /** @private */
+        this._maxMessageSize = opts.maxMessageSize || MAX_FRAME_SIZE;
+        /** @private */
+        this._allowCompressed = opts.allowCompressed !== false;
+        /** @private */
+        this._destroyed = false;
+
+        /**
+         * Callback invoked with each complete deframed message buffer.
+         * @type {Function|null}
+         */
+        this.onMessage = null;
+
+        /**
+         * Callback invoked on parse errors.
+         * @type {Function|null}
+         */
+        this.onError = null;
+    }
+
+    /**
+     * Feed a data chunk to the parser. May trigger zero or more `onMessage` callbacks.
+     *
+     * @param {Buffer} chunk - Raw bytes from the HTTP/2 stream.
+     */
+    push(chunk)
+    {
+        if (this._destroyed) return;
+
+        this._buffer = this._buffer.length > 0
+            ? Buffer.concat([this._buffer, chunk])
+            : chunk;
+
+        this._drain();
+    }
+
+    /**
+     * Process buffered data, extracting complete frames.
+     * @private
+     */
+    _drain()
+    {
+        while (this._buffer.length >= FRAME_HEADER_SIZE)
+        {
+            const compressed = this._buffer[0];
+            const msgLen = this._buffer.readUInt32BE(1);
+
+            // Security: reject oversized messages before buffering
+            if (msgLen > this._maxMessageSize)
+            {
+                const err = new Error(`gRPC message size ${msgLen} exceeds limit ${this._maxMessageSize}`);
+                err.code = 'RESOURCE_EXHAUSTED';
+                this._emitError(err);
+                this._destroyed = true;
+                return;
+            }
+
+            const totalLen = FRAME_HEADER_SIZE + msgLen;
+            if (this._buffer.length < totalLen)
+            {
+                // Wait for more data
+                return;
+            }
+
+            const payload = this._buffer.subarray(FRAME_HEADER_SIZE, totalLen);
+            this._buffer = this._buffer.subarray(totalLen);
+
+            if (compressed && !this._allowCompressed)
+            {
+                const err = new Error('Compressed message received but compression is disabled');
+                err.code = 'UNIMPLEMENTED';
+                this._emitError(err);
+                continue;
+            }
+
+            if (compressed)
+            {
+                // Async decompress
+                zlib.gunzip(payload, (err, decompressed) =>
+                {
+                    if (err)
+                    {
+                        err.code = 'INTERNAL';
+                        this._emitError(err);
+                        return;
+                    }
+                    this._emitMessage(decompressed);
+                });
+            }
+            else
+            {
+                this._emitMessage(Buffer.from(payload));
+            }
+        }
+    }
+
+    /**
+     * Emit a parsed message.
+     * @private
+     */
+    _emitMessage(buf)
+    {
+        if (this._destroyed) return;
+        if (this.onMessage) this.onMessage(buf);
+    }
+
+    /**
+     * Emit a parse error.
+     * @private
+     */
+    _emitError(err)
+    {
+        log.error('frame parse error: %s', err.message);
+        if (this.onError) this.onError(err);
+    }
+
+    /**
+     * Reset the parser state, discarding any buffered data.
+     */
+    reset()
+    {
+        this._buffer = Buffer.alloc(0);
+        this._destroyed = false;
+    }
+
+    /**
+     * Destroy the parser, preventing further processing.
+     */
+    destroy()
+    {
+        this._destroyed = true;
+        this._buffer = Buffer.alloc(0);
+    }
+}
+
+module.exports = {
+    FRAME_HEADER_SIZE,
+    MAX_FRAME_SIZE,
+    COMPRESS_FLAG,
+    frameEncode,
+    FrameParser,
+};