zplex-stream 🚀

zplex-stream is a blazing-fast Cloudflare Worker that securely streams files from Google Drive straight to your client apps. With JWT authentication from zplex-api 🔑 and full support for video seeking 🎬, it’s the perfect way to serve content without exposing your credentials.

---

Features ✨

• Stream Google Drive files securely to clients 🛡️
• Authenticate users via JWT issued by zplex-api 🔑 (Users must have 'Stream' capability)
• Supports HTTP Range requests for smooth video playback ⏯️
• Lightweight, fast, and production-ready ⚡
• No sensitive credentials are ever exposed to the client 🔒
• Workers KV caching of Google access tokens for efficiency

---

Setup 🛠️

Install dependencies

npm install

Required secrets and vars

For local development and production, set these required Worker secrets:

wrangler secret put SECRET_KEY        # Must be the same as zplex-api
wrangler secret put GOOGLE_DRIVE_CLIENT_EMAIL
wrangler secret put GOOGLE_DRIVE_CLIENT_ID
wrangler secret put GOOGLE_DRIVE_PRIVATE_KEY_PKCS8 # single line, replace newlines with \n

Required runtime keys right now:

Key	Required	Notes
SECRET_KEY	Yes	Must match zplex-api SECRET_KEY for JWT verification.
GOOGLE_DRIVE_CLIENT_EMAIL	Yes	Service account email (iss).
GOOGLE_DRIVE_CLIENT_ID	Yes	Used as JWT kid in the OAuth assertion.
GOOGLE_DRIVE_PRIVATE_KEY_PKCS8	Yes	PKCS8 private key, single-line escaped (\\n).
ALLOWED_ORIGINS	No	Comma-separated browser CORS allow-list. If missing/empty, browser CORS is denied.

GOOGLE_DRIVE_PRIVATE_KEY_ID is not currently consumed by the runtime and is therefore not required.

CORS is denied by default. To allow cross-origin browser clients, set ALLOWED_ORIGINS (comma-separated origins) as a Worker var/secret; native clients are unaffected.

Setup Workers KV

npx wrangler kv namespace create zplex

This Worker requires a KV namespace binding named zplex (see wrangler.jsonc).

Run locally

npm run dev

Deploy to Cloudflare

npm run deploy

---

Usage 📡

GET /stream/:fileId HTTP/1.1
Host: your-worker-domain
Authorization: Bearer <STREAM_GRANT>
Range: bytes=0-1023

• Authorization: short-lived stream grant from GET /api/stream/grant/{fileId} on zplex-api; the grant must contain the requested fileId and expires after approximately two minutes 🔑
• Range: optional; allows partial content requests for video seeking ⏩

---

Tech stack & dependencies 📦

Runtime: Cloudflare Workers (workerd). Framework: Hono. Language: TypeScript.

Package	Version	Notes
hono	^4.13.2	HTTP router/framework
jsonwebtoken	^9.0.3	JWT verification (shared SECRET_KEY with zplex-api)
typescript (dev)	^7.0.2	Native TypeScript compiler (v7); typechecks clean
wrangler (dev)	^4.123.0	Cloudflare Workers CLI / bundler
@types/node (dev)	^26.2.0	Node type definitions

Build gate (no tests in this project): npx tsc --noEmit for typecheck, and npx wrangler deploy --dry-run for the bundle check.