@eliware/elera-lib 0.1.9 → 0.1.10

package/README.md

@@ -2,9 +2,9 @@
 
 The alternative SQL client for Eliware applications. It provides generic
 primary/balanced MySQL or MariaDB routing without embedding Elera, HAProxy,
-backup, or GitOps policy. It is a v0.1.9 alternative to `@eliware/mysql`; the
+backup, or GitOps policy. It is a v0.1.10 alternative to `@eliware/mysql`; the
 existing package is intentionally unchanged. The current package version is
-0.1.9.
+0.1.10.
 
 `primary` is the preferred connection path. `balanced` is an optional alternate
 path. Both may accept writes; automatic routing sends only conservative,
@@ -34,7 +34,8 @@ Routing bundles passed to `createDbFromBundle` use the normalized shape
 `routes.primary` and `routes.balanced`, each containing ordered `{ host, port,
 weight }` nodes. A bundle may also carry an explicit `writer`, ordered
 `failover`, and `readers` assignment. The bundle carries `database`,
-`identity`, optional `credentials`, and `expiresAt`; `validateBundle` rejects
+`identity`, optional `application`, `credentialName`, `scopes`, and
+`credentials`, and `expiresAt`; `validateBundle` rejects
 expired, malformed, duplicated, or conflicting route data. The checked-in
 contract fixture documents the supervisor-facing wire representation
 separately.
@@ -49,6 +50,12 @@ library does not know about supervisors, Elera, HAProxy, GitOps, backups, or
 CLI commands. Applications provide those integrations through ordinary
 configuration and callbacks.
 
+An application-scoped token should resolve to one application, database, and
+credential context. The library does not select databases or credentials from
+request arguments. Callers that already have that authorization context may
+pass `tokenContext` to `createDb`; bundle creation and refresh then reject
+cross-database, identity, credential, or scope mismatches.
+
 When a route node is drained, the client immediately stops assigning new work
 to that node while existing operations continue. The drain window defaults to
 45 seconds and is capped at 45 seconds; remaining pool connections are then
@@ -100,8 +107,10 @@ Applications may opt into generic in-memory telemetry with
 failures, retries, in-flight work, and latency are exposed through
 `client.telemetry` and sent over an attached routing stream once per second.
 Telemetry is observational only; it does not carry SQL or credentials.
-Reconnect, failover, and cumulative reconnect-delay counters are included in
-the telemetry snapshot.
+The snapshot may include the application, database, credential name, and
+scopes associated with the already-authorized client, plus reconnect, failover,
+and cumulative reconnect-delay counters. It never includes bearer tokens or
+passwords.
 
 `createMaterializer` supports bounded plaintext use for a caller-provided
 operation. It creates a mode-restricted temporary file and removes its entire

package/RELEASE_NOTES.md

@@ -1,5 +1,27 @@
 # Release notes
 
+## 0.1.10 — Token-bound routing context
+
+### Added
+
+- Adds `validateTokenContext` for enforcing an application token's authorized
+  application, database, credential, identity, and scopes against a routing
+  bundle.
+- Applies that authorization check during initial client creation and every
+  subsequent bundle refresh.
+- Keeps routing-stream authorization token-only; database and application
+  selectors are not sent as query parameters.
+- Includes safe application, database, credential, and scope context in
+  opt-in in-memory telemetry without exposing tokens or passwords.
+
+### Validation
+
+- Adds focused coverage for matching contexts, rejected cross-database and
+  scope mismatches, refresh-time enforcement, and isolated token contexts.
+- Maintains 100% statements, branches, functions, and lines coverage with zero
+  lint warnings.
+- Typecheck, contract, syntax, and package dry-run checks pass.
+
 ## 0.1.9 — Standalone outage classification and complete operation telemetry
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@eliware/elera-lib",
-    "version": "0.1.9",
+    "version": "0.1.10",
     "description": "Generic MySQL and MariaDB client with resilient routing, telemetry, client-side drains, and failover",
     "keywords": [
         "eliware",

package/src/client/authorization-context.mjs

@@ -0,0 +1,9 @@
+export function validateTokenContext(bundle, tokenContext = {}) {
+  if (!bundle || typeof bundle !== 'object') throw new TypeError('routing bundle is required');
+  for (const field of ['application', 'database', 'credentialName']) {
+    if (tokenContext[field] !== undefined && bundle[field] !== tokenContext[field]) throw new Error(`routing bundle ${field} does not match token context`);
+  }
+  if (tokenContext.identity !== undefined && bundle.identity !== tokenContext.identity) throw new Error('routing bundle identity does not match token context');
+  if (tokenContext.scopes !== undefined && (!Array.isArray(bundle.scopes) || tokenContext.scopes.some((scope) => !bundle.scopes.includes(scope)))) throw new Error('routing bundle scopes exceed token context');
+  return bundle;
+}

package/src/client/create-db.mjs

@@ -3,17 +3,18 @@ import * as mysql from 'mysql2/promise';
 import { validateProfile, redactedProfile } from '../config.mjs';
 import { asSqlError } from '../errors.mjs';
 import { resolveCredentials, credentialContext } from '../credential-provider.mjs';
-import { validateBundle, bundleExpired, bundleNeedsRefresh } from '../bundle.mjs';
+import { validateBundle as validateBundleShape, bundleExpired, bundleNeedsRefresh } from '../bundle.mjs';
 import { createRouteFactory } from './route-factory.mjs';
 import { classifyQuery, routeFor } from '../routing.mjs';
 import { compareBundleVersions } from '../routing/bundle-version.mjs';
 import { clientDrainTimeout } from '../lifecycle/drain-policy.mjs';
 import { createTelemetry } from '../telemetry.mjs';
 import { createTimedOperation } from './telemetry-wrapper.mjs';
+import { validateTokenContext } from './authorization-context.mjs';
 
 const olderVersion = (candidate, current) => compareBundleVersions(candidate, current) < 0;
 
-export async function createDb({ primary, balanced, bundle, credentialProvider, mysqlLib = mysql, log = defaultLog, routing = 'auto', identity, quarantineMs = 5000, drainTimeoutMs = 45000, now = () => Date.now(), telemetry } = {}) {
+export async function createDb({ primary, balanced, bundle, credentialProvider, mysqlLib = mysql, log = defaultLog, routing = 'auto', identity, tokenContext, quarantineMs = 5000, drainTimeoutMs = 45000, now = () => Date.now(), telemetry } = {}) {
   if (!primary || typeof primary !== 'object') throw new TypeError('primary connection profile is required');
   const credentials = await resolveCredentials(credentialProvider, credentialContext(primary, { identity }));
   let primaryConfig = validateProfile({ ...primary, ...credentials }, 'primary');
@@ -23,12 +24,13 @@ export async function createDb({ primary, balanced, bundle, credentialProvider,
     primaryConfig = validateProfile({ ...primaryConfig, ...credentials }, 'primary');
     if (balancedConfig) balancedConfig = validateProfile({ ...balancedConfig, ...credentials }, 'balanced');
   }
+  const validateBundle = (candidate) => validateTokenContext(validateBundleShape(candidate), tokenContext);
   let activeBundle = bundle ? validateBundle(bundle) : undefined;
   const makeRoute = (route, fallback) => createRouteFactory({ bundle: activeBundle, now, mysqlLib, log, quarantineMs })(route, fallback);
   let primaryPool = makeRoute('primary', primaryConfig);
   let balancedPool = balancedConfig || activeBundle?.routes?.balanced ? makeRoute('balanced', balancedConfig ?? primaryConfig) : null;
   const choose = (sql, options = {}) => options.connection ?? (routeFor(sql, options.route ?? routing) === 'balanced' && balancedPool ? balancedPool : primaryPool);
-  const metrics = telemetry === true ? createTelemetry({ application: bundle?.application ?? identity ?? 'default', now }) : telemetry;
+  const metrics = telemetry === true ? createTelemetry({ application: bundle?.application ?? 'default', credentialName: bundle?.credentialName, database: bundle?.database, scopes: bundle?.scopes, now }) : telemetry;
   const timed = createTimedOperation({ metrics, now });
   const client = {
     async query(sql, values, options) { return timed(async () => { const selected = choose(sql, options); try { return await selected.query(sql, values); } catch (error) { const requestedRoute = options?.route ?? routing; if (error.retryable && balancedPool && routeFor(sql, requestedRoute) === 'balanced' && classifyQuery(sql) === 'balanced') { metrics?.record?.({ retry: true }); return balancedPool.query(sql, values); } throw error; } }); },

package/src/index.d.ts

@@ -15,6 +15,9 @@ export interface RoutingBundle {
   apiVersion?: string;
   database?: string;
   identity?: string;
+  application?: string;
+  credentialName?: string;
+  scopes?: string[];
   credentials?: { username?: string; password?: string };
   bundleVersion?: number | string;
   expiresAt: string;
@@ -28,7 +31,7 @@ export interface CredentialProviderResult { user: string; password: string; }
 export type CredentialProvider = (context: { database: string; identity: string | null; route: string }) => Promise<CredentialProviderResult> | CredentialProviderResult;
 export type QueryFunction = (sql: string, values?: unknown) => Promise<any>;
 export interface DbOptions { route?: 'auto' | 'primary' | 'balanced'; connection?: unknown; }
-export interface TelemetrySnapshot { type: 'client.telemetry'; application: string; queries: number; failures: number; retries: number; reconnects: number; failoverCount: number; reconnectDelayMs: number; inflight: number; totalLatencyMs: number; maxLatencyMs: number; avgLatencyMs: number; sentAt: string; }
+export interface TelemetrySnapshot { type: 'client.telemetry'; application: string; credentialName?: string; database?: string; scopes?: string[]; queries: number; failures: number; retries: number; reconnects: number; failoverCount: number; reconnectDelayMs: number; inflight: number; totalLatencyMs: number; maxLatencyMs: number; avgLatencyMs: number; sentAt: string; }
 export interface Telemetry { begin(): number; record(event?: { latencyMs?: number; failed?: boolean; retry?: boolean; reconnect?: boolean; failover?: boolean }): void; recordReconnect(event?: { delayMs?: number; failover?: boolean }): void; snapshot(): TelemetrySnapshot; start(stream: Pick<RoutingStream, 'sendTelemetry'>): void; stop(): void; }
 
 export interface DbClient {
@@ -61,7 +64,7 @@ export interface RoutingStream {
 export type RoutingEvent = { type: 'routing.update' | 'routing.resync' | 'routing.drain' | 'routing.recovery'; node?: string; version?: number | string; [key: string]: unknown } | { type: 'routing.shutdown'; node?: string; reason?: string; reconnect?: boolean; reconnectDeadlineMs?: number; loadBalancerEndpoint?: string };
 export function validateRoutingEvent(event: unknown): RoutingEvent;
 
-export function createDb(options: { primary: ConnectionProfile; balanced?: Partial<ConnectionProfile>; bundle?: RoutingBundle; credentialProvider?: CredentialProvider; identity?: string; mysqlLib?: unknown; log?: unknown; routing?: 'auto' | 'primary' | 'balanced'; quarantineMs?: number; drainTimeoutMs?: number; now?: () => number; telemetry?: true | Telemetry }): Promise<DbClient>;
+export function createDb(options: { primary: ConnectionProfile; balanced?: Partial<ConnectionProfile>; bundle?: RoutingBundle; tokenContext?: { application?: string; database?: string; credentialName?: string; identity?: string; scopes?: string[] }; credentialProvider?: CredentialProvider; identity?: string; mysqlLib?: unknown; log?: unknown; routing?: 'auto' | 'primary' | 'balanced'; quarantineMs?: number; drainTimeoutMs?: number; now?: () => number; telemetry?: true | Telemetry }): Promise<DbClient>;
 export function createDbFromEnvironment(options?: { env?: Record<string, string | undefined>; mysqlLib?: unknown; log?: unknown; routing?: 'auto' | 'primary' | 'balanced'; bundle?: RoutingBundle; credentialProvider?: CredentialProvider; identity?: string; telemetry?: true | Telemetry }): Promise<DbClient>;
 export function classifyQuery(sql: unknown): 'primary' | 'balanced';
 export function routeFor(sql: unknown, requested?: 'auto' | 'primary' | 'balanced'): 'primary' | 'balanced';
@@ -78,7 +81,7 @@ export function bundleNeedsRefresh(bundle: RoutingBundle, now?: number): boolean
 export function createAdminSql(options: { query: QueryFunction }): { transaction<T>(work: (context: { query: QueryFunction }) => Promise<T>): Promise<T>; migration(statements?: string[]): Promise<unknown> };
 export function createMigrationRunner(options: { query: QueryFunction; migrations?: Array<{ version: number; name: string; statements: string[] }> }): { status(): Promise<{ applied: unknown[] }>; migrate(): Promise<unknown> };
 export function selectRouteNodes(options: { bundle: RoutingBundle; route?: 'primary' | 'balanced'; now?: number }): RoutingNode[];
-export function createRoutingStream(options: { endpoint: string; token?: string; application?: string; fetchBundle: (application: string) => Promise<RoutingBundle>; onUpdate?: (event: unknown) => void; onError?: (error: unknown) => void; reconnectMs?: number; maxReconnectMs?: number; heartbeatMs?: number; telemetry?: Pick<Telemetry, 'recordReconnect'> }): RoutingStream;
+export function createRoutingStream(options: { endpoint: string; token?: string; fetchBundle: () => Promise<RoutingBundle>; onUpdate?: (event: unknown) => void; onError?: (error: unknown) => void; reconnectMs?: number; maxReconnectMs?: number; heartbeatMs?: number; telemetry?: Pick<Telemetry, 'recordReconnect'> }): RoutingStream;
 export function writerAssignment(bundle: RoutingBundle): WriterAssignment;
 export function failoverNodes(bundle: RoutingBundle): WriterAssignment[];
 export function compareBundleVersions(left: number | string | undefined, right: number | string | undefined): number;
@@ -87,4 +90,4 @@ export function clientDrainTimeout(timeoutMs?: number): number;
 export function createQuiesceController(options?: { close?: () => Promise<void>; onChange?: (state: string) => void }): { state(): { state: string; active: number }; enter(): () => void; begin(): Promise<void>; end(): Promise<void>; close(): Promise<void> };
 export function createSqlVerifier(options: { query: QueryFunction }): { connectivity(): Promise<{ verified: boolean }>; schema(database: string): Promise<{ database: string; verified: boolean }>; account(user: string, host?: string): Promise<{ user: string; host: string; verified: boolean; grants: string[] }>; all(options?: { database?: string; user?: string; host?: string }): Promise<unknown> };
 export function createMaterializer(options?: Record<string, unknown>): unknown;
-export function createTelemetry(options?: { application?: string; intervalMs?: number; now?: () => number; setIntervalImpl?: typeof setInterval; clearIntervalImpl?: typeof clearInterval }): Telemetry;
+export function createTelemetry(options?: { application?: string; credentialName?: string; database?: string; scopes?: string[]; intervalMs?: number; now?: () => number; setIntervalImpl?: typeof setInterval; clearIntervalImpl?: typeof clearInterval }): Telemetry;

package/src/index.mjs

@@ -1,4 +1,5 @@
 export { createDb } from './client/create-db.mjs';
+export { validateTokenContext } from './client/authorization-context.mjs';
 export { createDbFromBundle, profilesFromBundle } from './client/from-bundle.mjs';
 export { createDbFromEnvironment } from './client/environment.mjs';
 export { classifyQuery, routeFor } from './routing.mjs';

package/src/routing/stream-client.mjs

@@ -2,12 +2,12 @@ import { log as defaultLog } from '@eliware/common';
 import { compareBundleVersions } from './bundle-version.mjs';
 import { validateRoutingEvent } from './event-contract.mjs';
 
-export function createRoutingStream({ endpoint, token, application = 'default', fetchBundle, WebSocketImpl = globalThis.WebSocket, onUpdate, onError, reconnectMs = 1000, maxReconnectMs = 30000, heartbeatMs = 45000, now = () => Date.now(), telemetry } = {}) {
+export function createRoutingStream({ endpoint, token, fetchBundle, WebSocketImpl = globalThis.WebSocket, onUpdate, onError, reconnectMs = 1000, maxReconnectMs = 30000, heartbeatMs = 45000, now = () => Date.now(), telemetry } = {}) {
   if (!endpoint || typeof fetchBundle !== 'function') throw new TypeError('endpoint and fetchBundle are required');
   let socket; let closed = false; let timer; let heartbeat; let expectedVersion = 0; let delay = reconnectMs; let updateHandler = onUpdate; let mode = 'disconnected'; let plannedReconnect = false; let lastReconnectWasPlanned = false; let disconnectedAt; let reconnectDeadlineAt;
   const log = arguments[0]?.log ?? defaultLog;
-  const streamUrl = () => `${endpoint.replace(/^http/i, 'ws').replace(/\/$/, '')}/api/v1/routing/stream?application=${encodeURIComponent(application)}&token=${encodeURIComponent(token ?? '')}`;
-  async function fallback() { try { const bundle = await fetchBundle(application); if (closed) return; mode = 'rest'; updateHandler?.({ type: 'routing.resync', version: expectedVersion, bundle, receivedAt: now() }); } catch (error) { if (closed) return; mode = 'disconnected'; onError?.(error); log.warn?.('Routing REST fallback failed', { error }); } }
+  const streamUrl = () => `${endpoint.replace(/^http/i, 'ws').replace(/\/$/, '')}/api/v1/routing/stream?token=${encodeURIComponent(token ?? '')}`;
+  async function fallback() { try { const bundle = await fetchBundle(); if (closed) return; mode = 'rest'; updateHandler?.({ type: 'routing.resync', version: expectedVersion, bundle, receivedAt: now() }); } catch (error) { if (closed) return; mode = 'disconnected'; onError?.(error); log.warn?.('Routing REST fallback failed', { error }); } }
   function schedule() { if (closed || timer || (reconnectDeadlineAt !== undefined && now() >= reconnectDeadlineAt)) return; const wait = Math.min(delay, Math.max(0, reconnectDeadlineAt === undefined ? delay : reconnectDeadlineAt - now())); timer = setTimeout(() => { timer = undefined; void connect(); }, wait); delay = Math.min(maxReconnectMs, delay * 2); }
   async function connect() {
     if (closed || typeof WebSocketImpl !== 'function') { await fallback(); schedule(); return; }

package/src/telemetry.mjs

@@ -1,9 +1,9 @@
-export function createTelemetry({ application = 'default', intervalMs = 1000, now = () => Date.now(), setIntervalImpl = setInterval, clearIntervalImpl = clearInterval } = {}) {
+export function createTelemetry({ application = 'default', credentialName = undefined, database = undefined, scopes = undefined, intervalMs = 1000, now = () => Date.now(), setIntervalImpl = setInterval, clearIntervalImpl = clearInterval } = {}) {
   const stats = { queries: 0, failures: 0, retries: 0, reconnects: 0, failoverCount: 0, reconnectDelayMs: 0, inflight: 0, totalLatencyMs: 0, maxLatencyMs: 0 };
   let timer;
   const begin = () => { stats.inflight += 1; return now(); };
   const record = ({ latencyMs = 0, failed = false, retry = false, reconnect = false, failover = false } = {}) => { stats.queries += 1; stats.inflight = Math.max(0, stats.inflight - 1); stats.totalLatencyMs += latencyMs; stats.maxLatencyMs = Math.max(stats.maxLatencyMs, latencyMs); if (failed) stats.failures += 1; if (retry) stats.retries += 1; if (reconnect) stats.reconnects += 1; if (failover) stats.failoverCount += 1; };
-  const snapshot = () => ({ type: 'client.telemetry', application, ...stats, avgLatencyMs: stats.queries ? stats.totalLatencyMs / stats.queries : 0, sentAt: new Date(now()).toISOString() });
+  const snapshot = () => ({ type: 'client.telemetry', application, credentialName, database, scopes, ...stats, avgLatencyMs: stats.queries ? stats.totalLatencyMs / stats.queries : 0, sentAt: new Date(now()).toISOString() });
   const recordReconnect = ({ delayMs = 0, failover = false } = {}) => { stats.reconnects += 1; stats.reconnectDelayMs += Math.max(0, Number(delayMs) || 0); if (failover) stats.failoverCount += 1; };
   return { begin, record, recordReconnect, snapshot, start(stream) { if (timer) return; timer = setIntervalImpl(() => stream.sendTelemetry?.(snapshot()), intervalMs); timer.unref?.(); }, stop() { if (timer) clearIntervalImpl(timer); timer = undefined; } };
 }