elpaypg 0.0.0-stage → 2.0.0

package/src/vendor/common/secrets.js

@@ -0,0 +1,374 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { encrypt, decrypt } from './crypto.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// Resolved from this file, not cwd: every service must read the same files.
+const SECRETS_DIR = path.resolve(__dirname, '../../../data/.secrets');
+
+const cache = new Map();
+
+/**
+ * Resolves a service secret: explicit env var first, else a random value
+ * generated once and persisted under data/.secrets/ (shared by all local services).
+ * @param {string} name file-safe secret name
+ * @param {string} [envVar] env var that overrides the file
+ * @returns {string}
+ */
+export function resolveSecret(name, envVar) {
+  const fromEnv = envVar ? (process.env[envVar] || '').trim() : '';
+  if (fromEnv) return fromEnv;
+  if (cache.has(name)) return cache.get(name);
+
+  const file = path.join(SECRETS_DIR, name);
+  let value = '';
+  try { value = fs.readFileSync(file, 'utf8').trim(); } catch {}
+  if (!value) {
+    fs.mkdirSync(SECRETS_DIR, { recursive: true });
+    const fresh = crypto.randomBytes(32).toString('hex');
+    try {
+      fs.writeFileSync(file, fresh, { flag: 'wx', mode: 0o600 });
+      value = fresh;
+    } catch {
+      // Another process created it first: use theirs.
+      value = fs.readFileSync(file, 'utf8').trim();
+    }
+  }
+  cache.set(name, value);
+  return value;
+}
+
+/** Constant-time string comparison (length-independent via hashing). */
+export function safeEqual(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string') return false;
+  const ha = crypto.createHash('sha256').update(a).digest();
+  const hb = crypto.createHash('sha256').update(b).digest();
+  return crypto.timingSafeEqual(ha, hb);
+}
+
+export const getAdminToken = () => resolveSecret('admin_api_token', 'ADMIN_API_TOKEN');
+export const getObserverToken = () => resolveSecret('observer_api_token', 'OBSERVER_API_TOKEN');
+export const getCoinStoreWebhookSecret = () => resolveSecret('coin_store_webhook_secret', 'COIN_STORE_WEBHOOK_SECRET');
+
+/**
+ * Shared credential proving a request originated from a co-located service (server-side render
+ * proxies) rather than a browser. A plain `X-Internal-Render: true` header is attacker-settable,
+ * so the header is only honoured together with this secret.
+ */
+export const getInternalServiceToken = () => resolveSecret('internal_service_token', 'INTERNAL_SERVICE_TOKEN');
+
+/**
+ * Key used to sign device credentials and device challenges.
+ *
+ * Deliberately separate from the internal service token: that token is transmitted by the
+ * checkout portal on every internal render, so sharing a key with it would mean a leaked
+ * internal token could be used to mint a valid device credential for any device id.
+ */
+export const getDeviceCredentialKey = () => resolveSecret('device_credential_key', 'DEVICE_CREDENTIAL_KEY');
+
+/**
+ * Key used to index high-entropy secrets for lookup (session tokens, device tokens).
+ * Separate from the internal service token so a leaked internal token cannot be used to
+ * compute stored indexes.
+ */
+export const getBlindIndexKey = () => resolveSecret('blind_index_key', 'BLIND_INDEX_KEY');
+
+/** True when a socket remoteAddress is loopback (IPv4 or IPv6). */
+function isLoopbackRemoteAddress(remoteAddress) {
+  // Fail closed: an absent or malformed address is NOT loopback. Returning true here would
+  // let any request that hides its peer address satisfy the internal-service check.
+  if (!remoteAddress || typeof remoteAddress !== 'string') return false;
+  const addr = remoteAddress.trim().toLowerCase();
+  if (!addr) return false;
+  if (addr === '::1' || addr === '::ffff:127.0.0.1') return true;
+  // 127.0.0.0/8
+  return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(addr);
+}
+
+/** True only when the caller proves it is a trusted co-located internal service. */
+export function isInternalServiceRequest(req) {
+  if (!isLoopbackRemoteAddress(req?.socket?.remoteAddress)) return false;
+  const match = /^Bearer\s+(.+)$/i.exec(req?.headers?.['authorization'] || '');
+  const presented = (match ? match[1].trim() : '') || (req?.headers?.['x-internal-token'] || '');
+  return Boolean(presented) && safeEqual(presented, getInternalServiceToken());
+}
+
+/**
+ * Mints a server-signed device credential bound to a specific `deviceId`.
+ * Format: `devtok_<deviceId>.<nonce>.<issuedAt>.<hmac>`
+ * @param {string} deviceId
+ * @returns {string}
+ */
+export function issueDeviceCredential(deviceId) {
+  if (!deviceId || typeof deviceId !== 'string') {
+    throw new Error('deviceId is required to issue a device credential');
+  }
+  const nonce = crypto.randomBytes(16).toString('hex');
+  const issuedAt = String(Date.now());
+  const mac = crypto
+    .createHmac('sha256', getDeviceCredentialKey())
+    .update(`devcred:v1:${deviceId}:${nonce}:${issuedAt}`)
+    .digest('hex');
+  return `devtok_${deviceId}.${nonce}.${issuedAt}.${mac}`;
+}
+
+/**
+ * Verifies in constant time that a presented `deviceToken` is a genuine server-signed
+ * credential issued for `deviceId`.
+ * @param {string} deviceId
+ * @param {string} token
+ * @returns {boolean}
+ */
+export function verifyDeviceCredential(deviceId, token) {
+  if (!deviceId || typeof deviceId !== 'string' || !token || typeof token !== 'string') {
+    return false;
+  }
+  const prefix = `devtok_${deviceId}.`;
+  if (!token.startsWith(prefix)) return false;
+  const rest = token.slice(prefix.length);
+  const parts = rest.split('.');
+  if (parts.length !== 3) return false;
+  const [nonce, issuedAt, presentedMac] = parts;
+  if (!nonce || !issuedAt || !presentedMac) return false;
+  const expectedMac = crypto
+    .createHmac('sha256', getDeviceCredentialKey())
+    .update(`devcred:v1:${deviceId}:${nonce}:${issuedAt}`)
+    .digest('hex');
+  return safeEqual(presentedMac, expectedMac);
+}
+
+const DEVICE_CHALLENGE_TTL_MS = 5 * 60 * 1000;
+const consumedDeviceChallenges = new Map();
+
+function deviceChallengeMac(deviceId, nonce, expiresAt) {
+  return crypto
+    .createHmac('sha256', getDeviceCredentialKey())
+    .update(`devchal:v1:${deviceId}:${nonce}:${expiresAt}`)
+    .digest('hex');
+}
+
+/**
+ * Mints a short-lived, single-use challenge bound to a registered `deviceId` for
+ * challenge-response token re-issuance.
+ * @param {string} deviceId
+ * @returns {string}
+ */
+export function createDeviceChallenge(deviceId) {
+  if (!deviceId || typeof deviceId !== 'string') {
+    throw new Error('deviceId is required to create a device challenge');
+  }
+  const nonce = crypto.randomBytes(16).toString('hex');
+  const expiresAt = String(Date.now() + DEVICE_CHALLENGE_TTL_MS);
+  const mac = deviceChallengeMac(deviceId, nonce, expiresAt);
+  return `devchal_${deviceId}.${nonce}.${expiresAt}.${mac}`;
+}
+
+/**
+ * Verifies and consumes a single-use device challenge bound to `deviceId`.
+ * @param {string} challenge
+ * @param {string} deviceId
+ * @returns {boolean}
+ */
+export function consumeDeviceChallenge(challenge, deviceId) {
+  if (typeof challenge !== 'string' || typeof deviceId !== 'string' || !deviceId) return false;
+  const prefix = `devchal_${deviceId}.`;
+  if (!challenge.startsWith(prefix)) return false;
+  const parts = challenge.slice(prefix.length).split('.');
+  if (parts.length !== 3) return false;
+  const [nonce, expiresAt, mac] = parts;
+  if (!nonce || !expiresAt || !mac) return false;
+  if (!safeEqual(mac, deviceChallengeMac(deviceId, nonce, expiresAt))) return false;
+  const now = Date.now();
+  if (!(Number(expiresAt) > now)) return false;
+  for (const [k, exp] of consumedDeviceChallenges) {
+    if (exp <= now) consumedDeviceChallenges.delete(k);
+  }
+  const key = `${deviceId}:${nonce}`;
+  if (consumedDeviceChallenges.has(key)) return false;
+  consumedDeviceChallenges.set(key, Number(expiresAt));
+  return true;
+}
+
+/** Literal that older builds seeded into databases; must never be trusted. */
+export const LEGACY_DEFAULT_WEBHOOK_SECRET = 'merchant_webhook_secret_for_wallet_store';
+
+/**
+ * Master key for encrypting data at rest (merchant webhook secrets, OTPs).
+ * Generated once and persisted alongside the other local secrets.
+ */
+export const getEncryptionMasterKey = () => resolveSecret('encryption_master_key', 'ENCRYPTION_MASTER_KEY');
+
+/** Envelope prefix marking a stored value as AES-256-GCM ciphertext. */
+const ENC_PREFIX = 'enc:v1:';
+
+/** True when a stored value is in the ciphertext envelope. */
+export function isEncryptedValue(value) {
+  return typeof value === 'string' && value.startsWith(ENC_PREFIX);
+}
+
+/**
+ * Encrypts a value for storage. Values are idempotent: an already-encrypted value is
+ * returned unchanged so callers can wrap reads and writes without tracking state.
+ */
+export function encryptAtRest(plaintext) {
+  if (plaintext === null || plaintext === undefined || plaintext === '') return plaintext;
+  if (isEncryptedValue(plaintext)) return plaintext;
+  return ENC_PREFIX + encrypt(String(plaintext), getEncryptionMasterKey());
+}
+
+/**
+ * Decrypts a stored value, transparently passing through values written before encryption
+ * existed (plaintext) so existing databases keep working and get re-encrypted on next write.
+ */
+export function decryptAtRest(stored) {
+  if (!isEncryptedValue(stored)) return stored;
+  try {
+    return decrypt(stored.slice(ENC_PREFIX.length), getEncryptionMasterKey());
+  } catch {
+    // A value encrypted under a different/lost key must not silently become plaintext.
+    return null;
+  }
+}
+
+/**
+ * Keyed digest for high-entropy secrets that are only ever looked up, never read back
+ * (session tokens, device tokens). Unlike a plain hash this is not brute-forceable from a
+ * database dump, because the key lives outside the database.
+ *
+ * The key is dedicated to this purpose rather than shared with the internal service token:
+ * that token travels in a request header on every internal render, so a shared key would
+ * leak the indexing secret wherever those headers are logged.
+ */
+export function blindIndex(value, namespace = 'token') {
+  if (value === null || value === undefined || value === '') return null;
+  const digest = crypto.createHmac('sha256', getBlindIndexKey())
+    .update(`${namespace}:${value}`)
+    .digest('hex');
+  return `${namespace}_v1_${digest}`;
+}
+
+/**
+ * Compares a presented secret against a stored blind index in constant time.
+ *
+ * Rows written before the key was separated were indexed with the internal service token,
+ * so that key is still accepted for existing rows; the row is re-indexed on first use.
+ */
+export function blindIndexMatches(value, storedIndex, namespace = 'token') {
+  if (!value || !storedIndex) return false;
+  const candidate = blindIndex(value, namespace);
+  if (candidate && safeEqual(candidate, storedIndex)) return true;
+  // Legacy index produced with the previous key.
+  const legacy = crypto.createHmac('sha256', getInternalServiceToken())
+    .update(`${namespace}:${value}`)
+    .digest('hex');
+  return safeEqual(`${namespace}_v1_${legacy}`, storedIndex);
+}
+
+/** True when the request's `Authorization: Bearer` value matches any of the given tokens. */
+export function hasBearer(req, ...tokens) {
+  const match = /^Bearer\s+(.+)$/i.exec(req?.headers?.['authorization'] || '');
+  if (!match) return false;
+  const presented = match[1].trim();
+  return tokens.some(t => safeEqual(presented, t));
+}
+
+const BLOCKED_HOSTNAMES = new Set(['localhost', 'localhost.localdomain', 'ip6-localhost', 'ip6-loopback']);
+
+/** True for loopback, RFC1918, link-local, CGNAT, multicast and reserved IPv4/IPv6 ranges. */
+function isPrivateAddress(hostname) {
+  const lower = hostname.toLowerCase().replace(/^\[|\]$/g, '');
+  if (lower === '::1' || lower === '::' || lower === '0.0.0.0') return true;
+  if (lower.endsWith('.local') || lower.endsWith('.internal') || lower.endsWith('.localhost')) return true;
+
+  const v4 = lower.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+  if (!v4) {
+    // Unique-local (fc00::/7) and link-local (fe80::/10) IPv6.
+    return /^f[cd][0-9a-f]{2}:/.test(lower) || /^fe[89ab][0-9a-f]:/.test(lower);
+  }
+  const [a, b] = [Number(v4[1]), Number(v4[2])];
+  if (a === 10 || a === 127 || a === 0) return true;
+  if (a === 172 && b >= 16 && b <= 31) return true;
+  if (a === 192 && b === 168) return true;
+  if (a === 169 && b === 254) return true;
+  if (a === 100 && b >= 64 && b <= 127) return true;
+  if (a >= 224) return true;
+  return false;
+}
+
+/**
+ * Self-hosted merchants legitimately deliver webhooks to a host on their own LAN or loopback,
+ * so those are permitted only when explicitly opted in. Without the opt-in, private, loopback
+ * and link-local targets (including the cloud metadata endpoint) are refused.
+ */
+function privateWebhooksAllowed() {
+  return process.env.ELPAY_ALLOW_PRIVATE_WEBHOOKS === 'true';
+}
+
+/**
+ * Validates an operator-supplied outbound webhook URL.
+ * Rejects non-HTTP(S) schemes, embedded credentials and — unless explicitly opted in —
+ * loopback/private/link-local hosts, so the gateway cannot be pointed at cloud metadata
+ * endpoints or its own internal admin/control-plane services (SSRF).
+ * @param {string} value
+ * @returns {{ valid: boolean, error?: string, url?: URL }}
+ */
+export function validateOutboundWebhookUrl(value) {
+  const raw = typeof value === 'string' ? value.trim() : '';
+  if (!raw) return { valid: false, error: 'Webhook URL is required.' };
+  if (raw.length > 2048) return { valid: false, error: 'Webhook URL is too long.' };
+
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    return { valid: false, error: 'Webhook URL must be a valid absolute URL.' };
+  }
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+    return { valid: false, error: 'Webhook URL must use http:// or https://' };
+  }
+  if (url.username || url.password) {
+    return { valid: false, error: 'Webhook URL must not embed credentials.' };
+  }
+  const hostname = (url.hostname || '').toLowerCase().replace(/^\[|\]$/g, '');
+  if (!hostname) return { valid: false, error: 'Webhook URL must include a hostname.' };
+  if (!privateWebhooksAllowed() && (BLOCKED_HOSTNAMES.has(hostname) || isPrivateAddress(hostname))) {
+    return {
+      valid: false,
+      error: 'Webhook URL must not point to a loopback or private network address (set ELPAY_ALLOW_PRIVATE_WEBHOOKS=true for self-hosted LAN targets).'
+    };
+  }
+  return { valid: true, url };
+}
+
+const OAUTH_STATE_TTL_MS = 10 * 60 * 1000;
+const consumedOAuthStates = new Map();
+
+function oauthStateMac(payload) {
+  return crypto.createHmac('sha256', getObserverToken()).update(`oauth-state:${payload}`).digest('hex');
+}
+
+/**
+ * Creates a signed, expiring OAuth `state` value. Mint it only from an authenticated admin route:
+ * the callback accepts nothing that was not minted there, which blocks login-CSRF account linking.
+ */
+export function createOAuthState() {
+  const payload = `${crypto.randomBytes(16).toString('hex')}.${Date.now() + OAUTH_STATE_TTL_MS}`;
+  return `${payload}.${oauthStateMac(payload)}`;
+}
+
+/** Verifies signature and expiry, and accepts each state only once (per process). */
+export function consumeOAuthState(state) {
+  if (typeof state !== 'string') return false;
+  const parts = state.split('.');
+  if (parts.length !== 3) return false;
+  const [nonce, expiresAt, mac] = parts;
+  if (!safeEqual(mac, oauthStateMac(`${nonce}.${expiresAt}`))) return false;
+  const now = Date.now();
+  if (!(Number(expiresAt) > now)) return false;
+  for (const [key, exp] of consumedOAuthStates) if (exp <= now) consumedOAuthStates.delete(key);
+  if (consumedOAuthStates.has(nonce)) return false;
+  consumedOAuthStates.set(nonce, Number(expiresAt));
+  return true;
+}

package/src/vendor/common/state-machine.d.ts

@@ -0,0 +1 @@
+export * from './state-transitions.js';

package/src/vendor/common/state-machine.js

@@ -0,0 +1 @@
+export * from './state-transitions.js';

package/src/vendor/common/state-transitions.js

@@ -0,0 +1,85 @@
+import { PaymentStatus } from './enums.js';
+
+/**
+ * Allowed payment session state transitions.
+ *
+ * This lives in `../common/index.js` rather than `../core/index.js` because the database layer
+ * (`../db/index.js`) must enforce it too, and `../db/index.js` cannot depend on `../core/index.js`
+ * (which already depends on it). `../core/index.js` re-exports these helpers unchanged.
+ */
+export const VALID_TRANSITIONS = Object.freeze({
+  // EXPIRED is reachable from every non-terminal state: it is the universal "gave up"
+  // outcome (timer elapsed, or an administrator clearing the queue), so it must never be
+  // blocked just because the session had not reached the next stage yet.
+  [PaymentStatus.INITIATED]: [
+    PaymentStatus.ACTIVE,
+    PaymentStatus.QUEUED,
+    PaymentStatus.CANCELLED,
+    PaymentStatus.EXPIRED,
+    // COD: placing a Cash-on-Delivery order is a business success even before any UPI
+    // slot is acquired, so an order that was never activated still terminates as SUCCESS.
+    PaymentStatus.SUCCESS
+  ],
+  [PaymentStatus.QUEUED]: [
+    PaymentStatus.ACTIVE,
+    PaymentStatus.CANCELLED,
+    PaymentStatus.EXPIRED,
+    // COD: a queued UPI order can be converted to a placed COD order.
+    PaymentStatus.SUCCESS
+  ],
+  [PaymentStatus.ACTIVE]: [
+    PaymentStatus.PROCESSING,
+    // Tier-1 attribution settles a still-ACTIVE session as soon as the bank notification is
+    // attributed, without waiting for the customer to press "I have paid". A bank-confirmed
+    // credit is terminal regardless of whether the customer pressed the button.
+    PaymentStatus.SUCCESS,
+    PaymentStatus.FAILED,
+    PaymentStatus.EXPIRED,
+    PaymentStatus.CANCELLED
+  ],
+  [PaymentStatus.PROCESSING]: [
+    PaymentStatus.SUCCESS,
+    PaymentStatus.FAILED,
+    PaymentStatus.EXPIRED
+  ],
+  [PaymentStatus.SUCCESS]: [],
+  [PaymentStatus.FAILED]: [],
+  [PaymentStatus.EXPIRED]: [],
+  [PaymentStatus.CANCELLED]: []
+});
+
+/** States that can never change again. */
+export const TERMINAL_STATES = Object.freeze([
+  PaymentStatus.SUCCESS,
+  PaymentStatus.FAILED,
+  PaymentStatus.EXPIRED,
+  PaymentStatus.CANCELLED
+]);
+
+/** States that occupy a merchant's single UPI concurrency slot. */
+export const SLOT_OCCUPYING_STATES = Object.freeze([
+  PaymentStatus.ACTIVE,
+  PaymentStatus.PROCESSING
+]);
+
+/**
+ * Validates whether a state transition is permitted.
+ * @param {string} currentState
+ * @param {string} nextState
+ * @returns {boolean}
+ */
+export function isValidTransition(currentState, nextState) {
+  const allowed = VALID_TRANSITIONS[currentState];
+  if (!allowed) return false;
+  return allowed.includes(nextState);
+}
+
+/** True when the state is a final, terminal outcome. */
+export function isTerminalStatus(status) {
+  return TERMINAL_STATES.includes(status);
+}
+
+/** True when the state holds a merchant concurrency slot. */
+export function holdsSlot(status) {
+  return SLOT_OCCUPYING_STATES.includes(status);
+}

package/src/vendor/common/tunnel-command.js

@@ -0,0 +1,59 @@
+import fs from 'node:fs';
+import { spawn } from 'node:child_process';
+
+const TOKEN_RE = /^[A-Za-z0-9_\-=+/.]{20,}$/;
+
+/**
+ * Extracts the Cloudflare tunnel token from whatever the operator pasted
+ * (`cloudflared service install <token>`, `cloudflared tunnel run --token <token>`, or the bare token)
+ * and returns a fixed argv for `cloudflared`. Nothing else from the pasted text is ever executed.
+ * @param {string} rawCommand
+ * @returns {{ file: string, args: string[], redacted: string }}
+ */
+export function buildCloudflaredInvocation(rawCommand) {
+  const text = String(rawCommand || '').trim();
+  if (!text) throw new Error('Cloudflare Tunnel command cannot be empty.');
+
+  const explicit = text.match(/--token[\s=]+(\S+)/i) || text.match(/\binstall\s+(\S+)/i);
+  const candidates = explicit ? [explicit[1]] : text.split(/\s+/);
+  const token = candidates.map(c => c.replace(/^["']|["']$/g, '')).find(c => TOKEN_RE.test(c));
+  if (!token) {
+    throw new Error('No valid Cloudflare tunnel token found. Paste the command containing your tunnel token.');
+  }
+
+  // Keep an explicit path to the binary (e.g. "C:\Tools\cloudflared.exe") when it exists; otherwise rely on PATH.
+  const first = text.match(/^"([^"]+)"|^(\S+)/);
+  const candidate = first ? (first[1] || first[2]) : '';
+  const file = /cloudflared(\.exe)?$/i.test(candidate) && /[\\/]/.test(candidate) && fs.existsSync(candidate)
+    ? candidate
+    : 'cloudflared';
+
+  return {
+    file,
+    args: ['tunnel', '--no-autoupdate', 'run', '--token', token],
+    redacted: 'cloudflared tunnel --no-autoupdate run --token ***'
+  };
+}
+
+/**
+ * Starts cloudflared for the pasted command without a shell. Never throws: a bad command or a
+ * missing binary is logged and boot continues without a tunnel.
+ * @param {string} rawCommand
+ * @param {import('node:child_process').SpawnOptions} [options]
+ * @returns {import('node:child_process').ChildProcess | null}
+ */
+export function startCloudflaredSafely(rawCommand, options = {}) {
+  let invocation;
+  try {
+    invocation = buildCloudflaredInvocation(rawCommand);
+  } catch (err) {
+    console.error(`[Cloudflare Tunnel] Not started: ${err.message}`);
+    return null;
+  }
+  console.log(`   > ${invocation.redacted}`);
+  const child = spawn(invocation.file, invocation.args, { shell: false, env: { ...process.env }, ...options });
+  child.on('error', err => {
+    console.error(`[Cloudflare Tunnel] Could not run '${invocation.file}': ${err.message}. Install cloudflared or put it on PATH.`);
+  });
+  return child;
+}