dicode-relay

library0.1.7jsnpmunverified

OAuth broker and WebSocket relay server for dicode daemons (v0.1.7). This production-ready TypeScript/Node.js service combines an OAuth authorization-code flow broker with a persistent WebSocket relay tunnel, allowing local dicode daemons behind NAT to receive OAuth callbacks and webhooks without public ports, ngrok, or per-user OAuth app registration. The broker holds shared OAuth client credentials and delivers encrypted access tokens over the relay. Requires Node.js >=22. Active development by dicode-ayo, no notable alternatives in same niche.

devops

npm install dicode-relay

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · DICODE-RELAY

dicode-relay

devopsjavascriptv0.1.7

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

run

✓ import { run } from 'dicode-relay'

✗ import dicodeRelay from 'dicode-relay'

ESM only; no default export.

createRelayServer

✓ import { createRelayServer } from 'dicode-relay'

✗ const { createRelayServer } = require('dicode-relay')

ESM only since v0.1.0; require() will fail.

createOAuthBroker

✓ import { createOAuthBroker } from 'dicode-relay'

✗ import createOAuthBroker from 'dicode-relay'

Named export, not default.

Starts a dicode-relay server with OAuth broker and WebSocket relay on port 5553 using GitHub provider.

import { run } from 'dicode-relay'; import { createRelayServer, createOAuthBroker } from 'dicode-relay'; const relay = createRelayServer({ port: 5553 }); const broker = createOAuthBroker({ baseUrl: process.env.BASE_URL ?? 'http://localhost:5553', providers: { github: { clientId: process.env.GITHUB_CLIENT_ID ?? '', clientSecret: process.env.GITHUB_CLIENT_SECRET ?? '', }, }, }); relay.on('connection', (ws) => { console.log('Relay client connected'); }); await run({ relay, broker }); console.log('dicode-relay running on port 5553');

Debug

Known issues

breakingNode.js >=22 is required. Older versions will throw a syntax error due to top-level await and modern JS features.

fix

Update Node.js to version 22 or later.

affects: <0.1.0

deprecatedThe global `dicode-relay` binary reads config from `relay.yaml` or environment variables; no config file will fall back to env vars silently.

fix

Explicitly set RELAY_CONFIG or create relay.yaml file to avoid unexpected fallback.

affects: <0.1.5

gotchaThe export signature changed in v0.1.3: `run()` now returns a Promise instead of void. Code expecting synchronous behavior will break.

fix

Await the run() call or handle the returned promise.

affects: >=0.1.3

gotchaOAuth token encryption uses a default key if RELAY_ENCRYPTION_KEY is not set. This is insecure for production.

fix

Set a strong RELAY_ENCRYPTION_KEY environment variable.

affects: >=0.1.0

gotchaThe relay server uses self-signed certificates by default for WSS; browsers will block the connection unless configured to allow insecure content.

fix

Provide valid TLS certificates via RELAY_TLS_KEY and RELAY_TLS_CERT env vars, or use a reverse proxy.

affects: >=0.1.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/dicode-relay/index.js from /path/to/your/file.js not supported.

dicode-relay is ESM-only; require() fails because package.json has "type": "module".

fix

Use import syntax in an ESM context, or use dynamic import: const { run } = await import('dicode-relay');

TypeError: (0 , dicode_relay.run) is not a function

Default import used instead of named import because there is no default export.

fix

Change import to named: import { run } from 'dicode-relay'

Error: Cannot find module 'dicode-relay'

Package not installed or installed in wrong location when using npx.

fix

Run npx dicode-relay directly (no separate install) or install globally: npm install -g dicode-relay

SyntaxError: Unexpected token 'export'

Node.js version <22 does not support top-level await/ES modules used by dicode-relay.

fix

Upgrade Node.js to version 22 or later.

Upgrade

Version history

0.1.7latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/dicode-ayo/dicode-relay ↗

packagedicode-relay ↗

homepagehttps://github.com/dicode-ayo/dicode-relay#readme ↗