@oxyhq/core 12.6.0 → 12.8.0

package/dist/esm/crypto/keyManager.js

@@ -9,6 +9,7 @@ const { ec: EC } = _cjs_elliptic;
 import { isWeb, isIOS, isAndroid } from '../utils/platform.js';
 import { isReactNative, isNodeJS, loadExpoCrypto, loadNodeCrypto, loadSecureStore, loadSharedIdentityBridge } from '@oxyhq/protocol';
 import { isDev, logger } from '../logger/index.js';
+import { hkdfSha256 } from './kdf.js';
 /**
  * Thrown when an identity-mutating operation (createIdentity / importKeyPair)
  * is invoked while a valid identity already exists on the device.
@@ -41,6 +42,25 @@ export class IdentityPersistError extends Error {
     }
 }
 const ec = new EC('secp256k1');
+/**
+ * HKDF salt that domain-separates every identity-scoped seed produced by
+ * {@link KeyManager.deriveScopedSeed}. Versioned so a future scheme change is a
+ * new, non-colliding tag. The per-app domain (e.g. Oxy Pay's FairCoin wallet)
+ * is carried by the caller's `info` string, not this salt.
+ */
+const SCOPED_SEED_KDF_SALT = 'oxy-identity-scoped-seed-v1';
+/** UTF-8 encode an ASCII label to bytes (HKDF salt/info). */
+function utf8ToBytes(label) {
+    return new TextEncoder().encode(label);
+}
+/** Decode a hex string to bytes. Inverse of {@link uint8ArrayToHex}. */
+function hexToBytes(hex) {
+    const out = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < out.length; i++) {
+        out[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return out;
+}
 const STORAGE_KEYS = {
     PRIVATE_KEY: 'oxy_identity_private_key',
     PUBLIC_KEY: 'oxy_identity_public_key',
@@ -1385,6 +1405,36 @@ export class KeyManager {
             return false;
         }
     }
+    /**
+     * Derive a 32-byte, domain-separated seed from the on-device Oxy identity
+     * private key via HKDF-SHA256, WITHOUT ever exposing the raw private key.
+     *
+     * The domain separation is carried by `info` (e.g. `"oxypay/faircoin/v1"`),
+     * so distinct apps/purposes get independent seeds from the same identity.
+     * The output is HKDF keying material, never the private key itself — a
+     * consumer (e.g. Oxy Pay's FairCoin HD wallet) can feed it straight into
+     * `HDKey.fromMasterSeed` and never touches the identity key.
+     *
+     * Key source (native only): prefers the shared ecosystem identity written to
+     * `group.so.oxy.shared` (what a Relying Party like Oxy Pay reads), then falls
+     * back to this device's primary identity (Commons/Accounts). Both reproduce
+     * from the user's Oxy recovery phrase, so the derived seed is recoverable.
+     *
+     * @param info Context/domain-binding label (distinct labels → independent seeds).
+     * @returns 32 bytes of derived keying material, or `null` on web / when no
+     *          identity key is available on this device.
+     */
+    static async deriveScopedSeed(info) {
+        if (isWebPlatform()) {
+            return null;
+        }
+        const privateKey = (await KeyManager.getSharedPrivateKey()) ?? (await KeyManager.getPrivateKey());
+        if (!privateKey) {
+            return null;
+        }
+        const ikm = hexToBytes(KeyManager.canonicalPrivateKey(privateKey));
+        return hkdfSha256(ikm, utf8ToBytes(SCOPED_SEED_KDF_SALT), utf8ToBytes(info), 32);
+    }
     /**
      * Get a shortened version of the public key for display
      * Format: first 8 chars...last 8 chars

package/dist/esm/i18n/locales/en-US.json

@@ -1449,6 +1449,13 @@
             "emptyTitle": "No photos yet",
             "emptySubtitle": "Upload from your device to get started"
         },
+        "details": {
+            "title": "File Details",
+            "download": "Download",
+            "type": "Type",
+            "uploaded": "Uploaded",
+            "description": "Description"
+        },
         "a11y": {
             "viewAll": "Show all files",
             "viewPhotos": "Show photos only",

package/dist/esm/i18n/locales/es-ES.json

@@ -1449,6 +1449,13 @@
             "emptyTitle": "Aún no hay fotos",
             "emptySubtitle": "Sube desde tu dispositivo para empezar"
         },
+        "details": {
+            "title": "Detalles del archivo",
+            "download": "Descargar",
+            "type": "Tipo",
+            "uploaded": "Subido",
+            "description": "Descripción"
+        },
         "a11y": {
             "viewAll": "Mostrar todos los archivos",
             "viewPhotos": "Mostrar solo fotos",

package/dist/esm/i18n/locales/locales/en-US.json

@@ -1449,6 +1449,13 @@
       "emptyTitle": "No photos yet",
       "emptySubtitle": "Upload from your device to get started"
     },
+    "details": {
+      "title": "File Details",
+      "download": "Download",
+      "type": "Type",
+      "uploaded": "Uploaded",
+      "description": "Description"
+    },
     "a11y": {
       "viewAll": "Show all files",
       "viewPhotos": "Show photos only",

package/dist/esm/i18n/locales/locales/es-ES.json

@@ -1449,6 +1449,13 @@
       "emptyTitle": "Aún no hay fotos",
       "emptySubtitle": "Sube desde tu dispositivo para empezar"
     },
+    "details": {
+      "title": "Detalles del archivo",
+      "download": "Descargar",
+      "type": "Tipo",
+      "uploaded": "Subido",
+      "description": "Descripción"
+    },
     "a11y": {
       "viewAll": "Mostrar todos los archivos",
       "viewPhotos": "Mostrar solo fotos",

package/dist/esm/mixins/OxyServices.deviceTransfer.js

@@ -0,0 +1,317 @@
+/**
+ * Device-to-device Identity Transfer Mixin (b3 Feature 2 — "add a device")
+ *
+ * Clones an existing device's secp256k1 identity onto a fresh device over a
+ * short-lived, unauthenticated relay, WITHOUT the server ever holding a
+ * decryption key. Both devices end up holding the SAME private key.
+ *
+ * The two devices agree on a symmetric key via an ephemeral secp256k1 ECDH
+ * handshake (Phase-0 crypto): `deriveSharedSecret` → `hkdfSha256` → a per-pairing
+ * transfer key, used with `encryptAead`/`decryptAead` (XChaCha20-Poly1305) to
+ * seal `{ privateKey, publicKey }`. The relay carries only ephemeral public keys
+ * plus opaque ciphertext — a passive/at-rest-compromised backend cannot decrypt.
+ *
+ * Roles:
+ *  - NEW device (no identity): {@link initDeviceTransfer} (generate ephemeral
+ *    pair, register the pairing, render `pairingId` as a QR) then
+ *    {@link subscribeDeviceTransfer} (await approval over the `/device-pair`
+ *    socket with a poll fallback, decrypt, and import the key).
+ *  - OLD device (has identity): {@link getDeviceTransferInfo} (resolve the
+ *    scanned `pairingId` server-side — the QR is NOT self-contained) then
+ *    {@link approveDeviceTransfer} (biometric-gate in the UI, seal the key
+ *    material, and post it with a fresh signature over the CURRENT identity key).
+ *
+ * SECURITY: E2E against a passive relay only. Explicitly NOT hardened against an
+ * actively-malicious backend MITM'ing the ephemeral keys (same trust boundary as
+ * the existing QR sign-in; SAS compare deferred per owner decision). Approve
+ * requires BOTH a bearer token AND a fresh identity-key signature.
+ */
+import _cjs_elliptic from 'elliptic';
+const { ec: EC } = _cjs_elliptic;
+import { bytesToHex, hexToBytes, utf8ToBytes, bytesToUtf8 } from '@noble/hashes/utils';
+import { deriveSharedSecret } from '../crypto/ecdh.js';
+import { hkdfSha256 } from '../crypto/kdf.js';
+import { encryptAead, decryptAead } from '../crypto/aead.js';
+import { KeyManager } from '../crypto/keyManager.js';
+import { SignatureService } from '../crypto/signatureService.js';
+import { getSocketIO } from '../session/socketLoader.js';
+import { logger } from '../logger/index.js';
+const ecCurve = new EC('secp256k1');
+/**
+ * Ephemeral private keys for pairings an instance INITIATED, keyed by pairingId,
+ * held per OxyServices instance. In-memory ONLY (never persisted — single-use),
+ * cleared once the transfer settles. A module-level WeakMap (rather than a class
+ * field) keeps it off the mixin's emitted `.d.ts` (avoids TS4094 on the exported
+ * anonymous class) and lets the GC drop it with the instance.
+ */
+const ephemeralKeyStore = new WeakMap();
+function getEphemeralKeys(instance) {
+    let keys = ephemeralKeyStore.get(instance);
+    if (!keys) {
+        keys = new Map();
+        ephemeralKeyStore.set(instance, keys);
+    }
+    return keys;
+}
+/** HKDF `info` binding — MUST match the server/other-device byte-for-byte. */
+const DEVICE_TRANSFER_HKDF_INFO = 'oxy-device-transfer-v1';
+/** Socket.IO namespace the API pushes device-pair approval events on. */
+const DEVICE_PAIR_NAMESPACE = '/device-pair';
+/** Fallback poll cadence — the socket delivers approval instantly; this covers
+ *  the case where the socket can't connect. */
+const DEVICE_TRANSFER_POLL_INTERVAL_MS = 2500;
+/** Action string signed on approve (mirrors `link_identity`'s scheme). */
+const DEVICE_TRANSFER_APPROVE_ACTION = 'approve_device_transfer';
+/**
+ * Derive the per-pairing symmetric transfer key from an ECDH shared secret.
+ * Identical on both devices: `HKDF(ECDH, salt=pairingId, info=v1)`.
+ */
+function deriveTransferKey(sharedSecret, pairingId) {
+    return hkdfSha256(sharedSecret, utf8ToBytes(pairingId), utf8ToBytes(DEVICE_TRANSFER_HKDF_INFO), 32);
+}
+export function OxyServicesDeviceTransferMixin(Base) {
+    return class extends Base {
+        constructor(...args) {
+            super(...args);
+        }
+        /**
+         * NEW device — begin an "add a device" transfer. Generates a single-use
+         * ephemeral secp256k1 pair, registers the pairing, and returns the
+         * `pairingId` to render as a QR. The ephemeral private key is held in memory
+         * (keyed by `pairingId`) for the subsequent {@link subscribeDeviceTransfer}.
+         *
+         * @param label - Optional human-readable label for this new device.
+         */
+        async initDeviceTransfer(label) {
+            try {
+                const ephKeyPair = ecCurve.genKeyPair();
+                const ephPrivateKey = ephKeyPair.getPrivate('hex');
+                const ephPublicKey = ephKeyPair.getPublic('hex');
+                const res = await this.makeRequest('POST', '/identity/device-transfer/init', { newEphPub: ephPublicKey, ...(label ? { newDeviceLabel: label } : {}) }, { cache: false });
+                getEphemeralKeys(this).set(res.pairingId, ephPrivateKey);
+                return {
+                    pairingId: res.pairingId,
+                    expiresAt: res.expiresAt,
+                    newEphemeralPublicKey: ephPublicKey,
+                };
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * Resolve a pairing server-side (the QR carries only `pairingId`). The OLD
+         * device calls this after scanning to read the new device's ephemeral public
+         * key + label; the NEW device polls it to fetch the sealed material once
+         * approved. Public — no auth required.
+         */
+        async getDeviceTransferInfo(pairingId) {
+            try {
+                return await this.makeRequest('GET', `/identity/device-transfer/${encodeURIComponent(pairingId)}`, undefined, { cache: false, retry: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * OLD device — approve a scanned transfer. Reads the new device's ephemeral
+         * public key, derives the shared transfer key, AEAD-seals
+         * `{ privateKey, publicKey }`, and posts it PLUS a fresh signature over
+         * `{ action:'approve_device_transfer', pairingId, timestamp }` made with the
+         * CURRENT identity key (dual-proof alongside the bearer token).
+         *
+         * NATIVE-ONLY: requires a stored identity (throws otherwise). The UI must
+         * biometric-gate before calling this — a key clone leaves the device.
+         */
+        async approveDeviceTransfer(pairingId) {
+            try {
+                const info = await this.getDeviceTransferInfo(pairingId);
+                if (info.status !== 'pending') {
+                    throw new Error(`This transfer can no longer be approved (status: ${info.status}).`);
+                }
+                const privateKey = await KeyManager.getPrivateKey();
+                const publicKey = await KeyManager.getPublicKey();
+                if (!privateKey || !publicKey) {
+                    throw new Error('No identity found on this device. Create or import an identity first.');
+                }
+                // Ephemeral ECDH → per-pairing transfer key.
+                const oldEphKeyPair = ecCurve.genKeyPair();
+                const oldEphPrivateKey = oldEphKeyPair.getPrivate('hex');
+                const oldEphPublicKey = oldEphKeyPair.getPublic('hex');
+                const sharedSecret = deriveSharedSecret(oldEphPrivateKey, info.newDeviceEphemeralPublicKey);
+                const transferKey = deriveTransferKey(sharedSecret, pairingId);
+                // Seal the identity key material.
+                const plaintext = utf8ToBytes(JSON.stringify({ privateKey, publicKey }));
+                const { nonce, ciphertext } = encryptAead(transferKey, plaintext);
+                // Dual-proof: prove control of the CURRENT identity key (a bearer alone
+                // must not be able to exfiltrate the private key).
+                const timestamp = Date.now();
+                const message = JSON.stringify({
+                    action: DEVICE_TRANSFER_APPROVE_ACTION,
+                    pairingId,
+                    timestamp,
+                });
+                const signature = await SignatureService.sign(message);
+                return await this.makeRequest('POST', `/identity/device-transfer/${encodeURIComponent(pairingId)}/approve`, {
+                    oldEphPub: oldEphPublicKey,
+                    ciphertext: bytesToHex(ciphertext),
+                    nonce: bytesToHex(nonce),
+                    signature,
+                    timestamp,
+                }, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * OLD device — deny (cancel) a scanned transfer so the waiting new device
+         * stops. Public — no auth required.
+         */
+        async denyDeviceTransfer(pairingId) {
+            try {
+                return await this.makeRequest('POST', `/identity/device-transfer/${encodeURIComponent(pairingId)}/deny`, undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+        /**
+         * NEW device — await approval for a pairing started with
+         * {@link initDeviceTransfer}, then decrypt and import the transferred
+         * identity key. Primary path is an instant `device_pair_update` push over the
+         * `/device-pair` socket; a poll backstops a socket that can't connect.
+         *
+         * On `approved`: re-derives the shared transfer key from the old device's
+         * ephemeral public key, decrypts `{ privateKey, publicKey }`, imports it via
+         * `KeyManager.importKeyPair(privateKey, { overwrite: false })`, and invokes
+         * `onOutcome({ status:'approved', publicKey })`. The caller then runs the
+         * NORMAL challenge/verify sign-in — this method does not mint a session.
+         *
+         * @returns An unsubscribe function; call it to stop waiting (also called
+         *   automatically once the transfer settles).
+         */
+        subscribeDeviceTransfer(pairingId, onOutcome) {
+            const ephemeralKeys = getEphemeralKeys(this);
+            const ephPrivateKey = ephemeralKeys.get(pairingId);
+            if (!ephPrivateKey) {
+                throw new Error('No pending device transfer for this pairing id. Call initDeviceTransfer first.');
+            }
+            let settled = false;
+            let inFlight = false;
+            let socket = null;
+            let pollTimer = null;
+            const cleanup = () => {
+                if (pollTimer !== null) {
+                    clearInterval(pollTimer);
+                    pollTimer = null;
+                }
+                if (socket) {
+                    try {
+                        socket.off('device_pair_update');
+                        socket.off('connect');
+                        socket.disconnect();
+                    }
+                    catch (error) {
+                        logger.debug('[DeviceTransfer] socket close failed', { component: 'DeviceTransfer' }, error);
+                    }
+                    socket = null;
+                }
+                ephemeralKeys.delete(pairingId);
+            };
+            const finish = (outcome) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                onOutcome(outcome);
+            };
+            // Re-check authoritative status; on `approved`, decrypt + import.
+            const check = async () => {
+                if (settled || inFlight)
+                    return;
+                inFlight = true;
+                try {
+                    const info = await this.getDeviceTransferInfo(pairingId);
+                    if (settled)
+                        return;
+                    if (info.status === 'denied') {
+                        finish({ status: 'denied' });
+                        return;
+                    }
+                    if (info.status === 'expired') {
+                        finish({ status: 'expired' });
+                        return;
+                    }
+                    if (info.status === 'approved' &&
+                        info.oldDeviceEphemeralPublicKey &&
+                        info.ciphertext &&
+                        info.nonce) {
+                        const sharedSecret = deriveSharedSecret(ephPrivateKey, info.oldDeviceEphemeralPublicKey);
+                        const transferKey = deriveTransferKey(sharedSecret, pairingId);
+                        const plaintext = decryptAead(transferKey, hexToBytes(info.nonce), hexToBytes(info.ciphertext));
+                        const parsed = JSON.parse(bytesToUtf8(plaintext));
+                        // Import WITHOUT overwrite: a fresh device has no identity, and we
+                        // must never silently clobber an existing one.
+                        const importedPublicKey = await KeyManager.importKeyPair(parsed.privateKey, {
+                            overwrite: false,
+                        });
+                        finish({ status: 'approved', publicKey: importedPublicKey });
+                    }
+                }
+                catch (error) {
+                    // Transient (a poll tick that raced the approve write, a decrypt on a
+                    // half-written row) — keep waiting; the next tick/push retries.
+                    logger.debug('[DeviceTransfer] status check failed', { component: 'DeviceTransfer' }, error);
+                }
+                finally {
+                    inFlight = false;
+                }
+            };
+            // Primary: instant socket wake. Fall back to polling if unavailable.
+            void (async () => {
+                const io = await getSocketIO();
+                if (settled || !io)
+                    return;
+                try {
+                    const s = io(`${this.getBaseURL()}${DEVICE_PAIR_NAMESPACE}`, {
+                        transports: ['websocket'],
+                        autoConnect: true,
+                        reconnection: true,
+                        reconnectionAttempts: Number.POSITIVE_INFINITY,
+                        reconnectionDelay: 1000,
+                        reconnectionDelayMax: 10000,
+                    });
+                    const join = () => {
+                        try {
+                            s.emit('join', pairingId);
+                        }
+                        catch (error) {
+                            logger.debug('[DeviceTransfer] join failed', { component: 'DeviceTransfer' }, error);
+                        }
+                    };
+                    s.on('connect', join);
+                    if (s.connected)
+                        join();
+                    s.on('device_pair_update', () => {
+                        void check();
+                    });
+                    socket = s;
+                }
+                catch (error) {
+                    logger.debug('[DeviceTransfer] socket create failed (poll fallback)', { component: 'DeviceTransfer' }, error);
+                }
+            })();
+            // Fallback poll (also covers the already-approved-before-subscribe case via
+            // the immediate first tick below). unref so it never holds a Node event
+            // loop / test runner open.
+            pollTimer = setInterval(() => {
+                void check();
+            }, DEVICE_TRANSFER_POLL_INTERVAL_MS);
+            pollTimer.unref?.();
+            // Immediate first check — the transfer may already be approved/denied.
+            void check();
+            return cleanup;
+        }
+    };
+}

package/dist/esm/mixins/OxyServices.utility.js

@@ -8,6 +8,7 @@ import { jwtDecode } from 'jwt-decode';
 import { loadNodeCrypto } from '@oxyhq/protocol';
 import { buildUrl } from '../utils/apiUtils.js';
 import { logger } from '../logger/index.js';
+import { OXY_SERVICE_ENVIRONMENTS } from '../utils/oxyServiceEnvironment.js';
 /**
  * Expected JWT audience for tokens issued by the Oxy auth service.
  */
@@ -39,6 +40,10 @@ class ServiceTokenClaimError extends Error {
         this.name = 'ServiceTokenClaimError';
     }
 }
+function isOxyServiceEnvironment(value) {
+    return (typeof value === 'string' &&
+        OXY_SERVICE_ENVIRONMENTS.includes(value));
+}
 export function OxyServicesUtilityMixin(Base) {
     return class extends Base {
         // TypeScript's mixin pattern requires `(...args: any[])` here — the
@@ -335,7 +340,11 @@ export function OxyServicesUtilityMixin(Base) {
                         // Validate required service token fields
                         const appId = decoded.appId;
                         const credentialId = decoded.credentialId;
-                        if (!appId || typeof credentialId !== 'string' || credentialId.length === 0) {
+                        const environment = decoded.environment;
+                        if (!appId ||
+                            typeof credentialId !== 'string' ||
+                            credentialId.length === 0 ||
+                            !isOxyServiceEnvironment(environment)) {
                             if (optional) {
                                 req.userId = null;
                                 req.user = null;
@@ -388,6 +397,7 @@ export function OxyServicesUtilityMixin(Base) {
                             appName: decoded.appName || 'unknown',
                             credentialId,
                             scopes: Array.isArray(decoded.scopes) ? decoded.scopes : [],
+                            environment,
                         };
                         if (debug) {
                             logger.debug(`[oxy.auth] Service token OK app=${decoded.appName} delegateUser=${oxyUserId || '(none)'}`, {

package/dist/esm/mixins/index.js

@@ -29,6 +29,7 @@ import { OxyServicesCivicMixin } from './OxyServices.civic.js';
 import { OxyServicesNodesMixin } from './OxyServices.nodes.js';
 import { OxyServicesLinksMixin } from './OxyServices.links.js';
 import { OxyServicesDeviceBootMixin } from './OxyServices.deviceBoot.js';
+import { OxyServicesDeviceTransferMixin } from './OxyServices.deviceTransfer.js';
 /**
  * Mixin pipeline - applied in order from first to last.
  *
@@ -82,6 +83,9 @@ const MIXIN_PIPELINE = [
     // Device-first token mint: the client half of the zero-cookie transport
     // (`mintFromDeviceSecret` → `POST /session/device/token`).
     OxyServicesDeviceBootMixin,
+    // Device-to-device identity transfer ("add a device"): E2E-encrypted key
+    // clone over a short-lived relay (b3 Feature 2).
+    OxyServicesDeviceTransferMixin,
     // Utility (last, can use all above)
     OxyServicesUtilityMixin,
 ];

package/dist/esm/server/auth.js

@@ -1,3 +1,5 @@
+import { OXY_SERVICE_ENVIRONMENTS } from '../utils/oxyServiceEnvironment.js';
+export { OXY_SERVICE_ENVIRONMENTS };
 function normalizeId(value) {
     const normalized = value?.trim();
     return normalized && normalized.length > 0 ? normalized : null;

package/dist/esm/server/index.js

@@ -14,7 +14,7 @@
  * app.use(createOxyRateLimit(oxy, { store: redisStore }));
  * ```
  */
-export { createOptionalOxyAuth, createOxyAuthMiddleware, getOxyUserId, getRequiredOxyUserId, isOxyAuthenticated, requireOxyAuth, } from './auth.js';
+export { createOptionalOxyAuth, createOxyAuthMiddleware, getOxyUserId, getRequiredOxyUserId, isOxyAuthenticated, requireOxyAuth, OXY_SERVICE_ENVIRONMENTS, } from './auth.js';
 export { createOxyRateLimit } from './rateLimit.js';
 // SSRF-safe upstream fetch + URL validation (Node-only).
 export { assertSafePublicUrl, isBlockedIp, safeFetch, SsrfRejection, UpstreamError, ALLOWED_PORTS, ALLOWED_PROTOCOLS, BLOCKED_HOSTNAMES, DEFAULT_USER_AGENT, MAX_REDIRECTS, MAX_URL_LENGTH, UPSTREAM_HEADERS_TIMEOUT_MS, } from './safeFetch.js';

package/dist/esm/utils/oxyServiceEnvironment.js

@@ -0,0 +1,16 @@
+/**
+ * Environment segregation for Oxy service-token JWTs (test/live isolation).
+ * Mirrors `ApplicationCredentialEnvironment` on the API's `ApplicationCredential`
+ * model (`packages/api/src/models/ApplicationCredential.ts`) as an INDEPENDENT
+ * literal union — `@oxyhq/core` has zero dependency on `@oxyhq/api`, so this is
+ * kept in sync by hand, not by import.
+ *
+ * Defined here (not in `server/auth.ts` or `mixins/OxyServices.utility.ts`
+ * directly) because BOTH of those files need it and neither may import from
+ * the other: `server/` types import `express` (Node-only, a peer dependency
+ * `mixins/` deliberately avoids so it stays safe to bundle into RN/browser
+ * consumers — see the "Local request/response/socket typing" comment in
+ * `OxyServices.utility.ts`). This file has zero imports, so both sides can
+ * depend on it without crossing that boundary.
+ */
+export const OXY_SERVICE_ENVIRONMENTS = ['development', 'staging', 'production'];