@openmdm/core 0.7.0 → 0.9.0

package/src/index.ts

@@ -73,6 +73,8 @@ import type {
   PluginStorageAdapter,
   GroupTreeNode,
   GroupHierarchyStats,
+  Logger,
+  EnrollmentChallenge,
 } from './types';
 import {
   DeviceNotFoundError,
@@ -88,6 +90,17 @@ import { createScheduleManager } from './schedule';
 import { createMessageQueueManager } from './queue';
 import { createDashboardManager } from './dashboard';
 import { createPluginStorageAdapter, createMemoryPluginStorageAdapter } from './plugin-storage';
+import { createConsoleLogger, createSilentLogger } from './logger';
+import {
+  importPublicKeyFromSpki,
+  verifyEcdsaSignature,
+  canonicalEnrollmentMessage,
+  canonicalDeviceRequestMessage,
+  verifyDeviceRequest,
+  InvalidPublicKeyError,
+  PublicKeyMismatchError,
+  ChallengeInvalidError,
+} from './device-identity';
 
 // Re-export all types
 export * from './types';
@@ -95,6 +108,19 @@ export * from './schema';
 export * from './agent-protocol';
 export { createWebhookManager, verifyWebhookSignature } from './webhooks';
 export type { WebhookPayload } from './webhooks';
+export { createConsoleLogger, createSilentLogger } from './logger';
+
+// Device identity (Phase 2b)
+export {
+  importPublicKeyFromSpki,
+  verifyEcdsaSignature,
+  canonicalEnrollmentMessage,
+  canonicalDeviceRequestMessage,
+  verifyDeviceRequest,
+  InvalidPublicKeyError,
+  PublicKeyMismatchError,
+  ChallengeInvalidError,
+} from './device-identity';
 
 // Re-export enterprise manager factories
 export { createTenantManager } from './tenant';
@@ -111,17 +137,36 @@ export { createPluginStorageAdapter, createMemoryPluginStorageAdapter, createPlu
 export function createMDM(config: MDMConfig): MDMInstance {
   const { database, push, enrollment, webhooks: webhooksConfig, plugins = [] } = config;
 
+  // Structured logger. Falls back to the console-backed default if
+  // the host doesn't pass one. Host code is expected to pass a real
+  // pino/winston instance in production.
+  const logger = config.logger ?? createConsoleLogger();
+
+  // Extract a stable message from an unknown thrown value so it
+  // survives JSON serialization into the log context. Error objects
+  // stringify to `{}` otherwise, which is the #1 cause of "we can't
+  // tell why this failed" in production logs.
+  const errorMessage = (err: unknown): string => {
+    if (err instanceof Error) return err.message;
+    if (typeof err === 'string') return err;
+    try {
+      return JSON.stringify(err);
+    } catch {
+      return String(err);
+    }
+  };
+
   // Event handlers registry
   const eventHandlers = new Map<EventType, Set<EventHandler<EventType>>>();
 
   // Create push adapter
   const pushAdapter: PushAdapter = push
-    ? createPushAdapter(push, database)
-    : createStubPushAdapter();
+    ? createPushAdapter(push, database, logger)
+    : createStubPushAdapter(logger);
 
   // Create webhook manager if configured
   const webhookManager: WebhookManager | undefined = webhooksConfig
-    ? createWebhookManager(webhooksConfig)
+    ? createWebhookManager(webhooksConfig, logger)
     : undefined;
 
   // ============================================
@@ -205,13 +250,16 @@ export function createMDM(config: MDMConfig): MDMInstance {
         payload: eventRecord.payload as Record<string, unknown>,
       });
     } catch (error) {
-      console.error('[OpenMDM] Failed to persist event:', error);
+      logger.error({ err: errorMessage(error), event }, 'Failed to persist event');
     }
 
     // Deliver webhooks (async, don't wait)
     if (webhookManager) {
       webhookManager.deliver(eventRecord).catch((error) => {
-        console.error('[OpenMDM] Webhook delivery error:', error);
+        logger.error(
+          { err: errorMessage(error), event },
+          'Webhook delivery error',
+        );
       });
     }
 
@@ -221,7 +269,10 @@ export function createMDM(config: MDMConfig): MDMInstance {
         try {
           await handler(eventRecord);
         } catch (error) {
-          console.error(`[OpenMDM] Event handler error for ${event}:`, error);
+          logger.error(
+            { err: errorMessage(error), event },
+            'Event handler threw',
+          );
         }
       }
     }
@@ -231,7 +282,7 @@ export function createMDM(config: MDMConfig): MDMInstance {
       try {
         await config.onEvent(eventRecord);
       } catch (error) {
-        console.error('[OpenMDM] onEvent hook error:', error);
+        logger.error({ err: errorMessage(error) }, 'onEvent hook threw');
       }
     }
   };
@@ -907,8 +958,24 @@ export function createMDM(config: MDMConfig): MDMInstance {
       );
     }
 
-    // Verify signature if secret is configured
-    if (enrollment?.deviceSecret) {
+    // Determine which enrollment path the request is asking for.
+    // The presence of `publicKey` is the signal: if the device
+    // supplies a public key, it is attempting the Phase 2b
+    // device-pinned-key path and must also supply a valid
+    // attestation challenge. Otherwise we fall through to the
+    // legacy HMAC path.
+    const isPinnedKeyPath = Boolean(request.publicKey);
+
+    if (!isPinnedKeyPath && enrollment?.pinnedKey?.required) {
+      throw new EnrollmentError(
+        'Pinned-key enrollment is required but the request carried no publicKey. ' +
+          'The agent must generate a Keystore keypair and submit the SPKI public key ' +
+          'alongside an ECDSA signature over the canonical enrollment message.',
+      );
+    }
+
+    // HMAC path (Phase 2a): unchanged behavior.
+    if (!isPinnedKeyPath && enrollment?.deviceSecret) {
       const isValid = verifyEnrollmentSignature(
         request,
         enrollment.deviceSecret
@@ -918,6 +985,81 @@ export function createMDM(config: MDMConfig): MDMInstance {
       }
     }
 
+    // Pinned-key path (Phase 2b).
+    let challengeRecord: EnrollmentChallenge | null = null;
+    let importedPublicKey: ReturnType<typeof importPublicKeyFromSpki> | null = null;
+    if (isPinnedKeyPath) {
+      if (!request.attestationChallenge) {
+        throw new EnrollmentError(
+          'Pinned-key enrollment requires attestationChallenge. ' +
+            'Fetch a fresh challenge from /agent/enroll/challenge first.',
+        );
+      }
+      if (!database.consumeEnrollmentChallenge) {
+        throw new EnrollmentError(
+          'Pinned-key enrollment requires an adapter that implements enrollment ' +
+            'challenge storage. Upgrade to a database adapter that supports it, or ' +
+            'submit an HMAC-signed enrollment instead.',
+        );
+      }
+
+      // Parse the public key first — if it's malformed the signature
+      // cannot possibly verify and we want a specific error.
+      try {
+        importedPublicKey = importPublicKeyFromSpki(request.publicKey as string);
+      } catch (err) {
+        throw new EnrollmentError(
+          err instanceof Error
+            ? `Invalid enrollment public key: ${err.message}`
+            : 'Invalid enrollment public key',
+        );
+      }
+
+      // Atomically consume the challenge. This must happen BEFORE
+      // signature verification, otherwise two concurrent requests
+      // with the same challenge could both succeed.
+      challengeRecord = await database.consumeEnrollmentChallenge(
+        request.attestationChallenge,
+      );
+      if (!challengeRecord) {
+        throw new ChallengeInvalidError(
+          'Enrollment challenge is missing, expired, or already consumed',
+          request.attestationChallenge,
+        );
+      }
+      if (challengeRecord.expiresAt.getTime() < Date.now()) {
+        throw new ChallengeInvalidError(
+          'Enrollment challenge has expired',
+          request.attestationChallenge,
+        );
+      }
+
+      const canonical = canonicalEnrollmentMessage({
+        publicKey: request.publicKey as string,
+        model: request.model,
+        manufacturer: request.manufacturer,
+        osVersion: request.osVersion,
+        serialNumber: request.serialNumber,
+        imei: request.imei,
+        macAddress: request.macAddress,
+        androidId: request.androidId,
+        method: request.method,
+        timestamp: request.timestamp,
+        challenge: request.attestationChallenge,
+      });
+
+      const verified = verifyEcdsaSignature(
+        importedPublicKey,
+        canonical,
+        request.signature,
+      );
+      if (!verified) {
+        throw new EnrollmentError(
+          'Invalid enrollment signature (device-pinned-key path)',
+        );
+      }
+    }
+
     // Custom validation
     if (enrollment?.validate) {
       const isValid = await enrollment.validate(request);
@@ -943,14 +1085,40 @@ export function createMDM(config: MDMConfig): MDMInstance {
     let device = await database.findDeviceByEnrollmentId(enrollmentId);
 
     if (device) {
-      // Device re-enrolling
-      device = await database.updateDevice(device.id, {
+      // Device re-enrolling. If the device is already on the
+      // pinned-key path, the submitted public key MUST match the
+      // pinned one — otherwise we reject loudly. This is how we
+      // prevent an attacker who extracted the enrollment secret
+      // from hijacking an enrolled device's identity: without the
+      // original private key they cannot produce a valid signature,
+      // and even if they could (via a forged HMAC fallback), the
+      // pinned key still identifies the legitimate device.
+      if (isPinnedKeyPath && device.publicKey) {
+        if (device.publicKey !== request.publicKey) {
+          throw new PublicKeyMismatchError(device.id);
+        }
+      }
+
+      const updateInput: UpdateDeviceInput = {
         status: 'enrolled',
         model: request.model,
         manufacturer: request.manufacturer,
         osVersion: request.osVersion,
         lastSync: new Date(),
-      });
+      };
+
+      // Pin the key on first pinned-key enrollment for a device
+      // that originally enrolled on HMAC. This is the migration
+      // path: a device that used to sign with the shared secret
+      // can upgrade by sending its freshly-generated public key on
+      // its next enrollment, and the server will pin it from then
+      // on.
+      if (isPinnedKeyPath && !device.publicKey) {
+        updateInput.publicKey = request.publicKey;
+        updateInput.enrollmentMethod = 'pinned-key';
+      }
+
+      device = await database.updateDevice(device.id, updateInput);
     } else if (enrollment?.autoEnroll) {
       // Auto-create device
       device = await database.createDevice({
@@ -965,6 +1133,17 @@ export function createMDM(config: MDMConfig): MDMInstance {
         policyId: request.policyId || enrollment.defaultPolicyId,
       });
 
+      // Pin the public key on first enrollment for pinned-key path.
+      // `CreateDeviceInput` deliberately doesn't carry auth fields —
+      // we keep auth state a post-creation concern so legacy
+      // adapters don't have to know about it.
+      if (isPinnedKeyPath) {
+        device = await database.updateDevice(device.id, {
+          publicKey: request.publicKey,
+          enrollmentMethod: 'pinned-key',
+        });
+      }
+
       // Add to default group if configured
       if (enrollment.defaultGroupId) {
         await database.addDeviceToGroup(device.id, enrollment.defaultGroupId);
@@ -981,6 +1160,15 @@ export function createMDM(config: MDMConfig): MDMInstance {
         macAddress: request.macAddress,
         androidId: request.androidId,
       });
+
+      // Pin the public key even for pending devices — we want to
+      // know which key originally enrolled once an admin approves.
+      if (isPinnedKeyPath) {
+        device = await database.updateDevice(device.id, {
+          publicKey: request.publicKey,
+          enrollmentMethod: 'pinned-key',
+        });
+      }
       // Status remains 'pending'
     } else {
       throw new EnrollmentError(
@@ -1193,6 +1381,7 @@ export function createMDM(config: MDMConfig): MDMInstance {
     push: pushAdapter,
     webhooks: webhookManager,
     db: database,
+    logger,
     config,
     on,
     emit,
@@ -1217,11 +1406,11 @@ export function createMDM(config: MDMConfig): MDMInstance {
       if (plugin.onInit) {
         try {
           await plugin.onInit(instance);
-          console.log(`[OpenMDM] Plugin initialized: ${plugin.name}`);
+          logger.info({ plugin: plugin.name }, 'Plugin initialized');
         } catch (error) {
-          console.error(
-            `[OpenMDM] Failed to initialize plugin ${plugin.name}:`,
-            error
+          logger.error(
+            { plugin: plugin.name, err: errorMessage(error) },
+            'Failed to initialize plugin',
           );
         }
       }
@@ -1237,19 +1426,22 @@ export function createMDM(config: MDMConfig): MDMInstance {
 
 function createPushAdapter(
   config: MDMConfig['push'],
-  database: MDMConfig['database']
+  database: MDMConfig['database'],
+  logger: Logger,
 ): PushAdapter {
   if (!config) {
-    return createStubPushAdapter();
+    return createStubPushAdapter(logger);
   }
 
+  const pushLogger = logger.child({ component: 'push' });
+
   // The actual implementations will be provided by separate packages
   // This is a base implementation that logs and stores tokens
   return {
     async send(deviceId: string, message: PushMessage): Promise<PushResult> {
-      console.log(
-        `[OpenMDM] Push to ${deviceId}: ${message.type}`,
-        message.payload
+      pushLogger.debug(
+        { deviceId, type: message.type, payload: message.payload },
+        'send',
       );
 
       // In production, this would be replaced by FCM/MQTT adapter
@@ -1260,8 +1452,9 @@ function createPushAdapter(
       deviceIds: string[],
       message: PushMessage
     ): Promise<PushBatchResult> {
-      console.log(
-        `[OpenMDM] Push to ${deviceIds.length} devices: ${message.type}`
+      pushLogger.debug(
+        { count: deviceIds.length, type: message.type },
+        'sendBatch',
       );
 
       const results = deviceIds.map((deviceId) => ({
@@ -1298,10 +1491,11 @@ function createPushAdapter(
   };
 }
 
-function createStubPushAdapter(): PushAdapter {
+function createStubPushAdapter(logger: Logger): PushAdapter {
+  const stubLogger = logger.child({ component: 'push-stub' });
   return {
     async send(deviceId: string, message: PushMessage): Promise<PushResult> {
-      console.log(`[OpenMDM] Push (stub): ${deviceId} <- ${message.type}`);
+      stubLogger.debug({ deviceId, type: message.type }, 'send (stub)');
       return { success: true, messageId: 'stub' };
     },
 
@@ -1309,8 +1503,9 @@ function createStubPushAdapter(): PushAdapter {
       deviceIds: string[],
       message: PushMessage
     ): Promise<PushBatchResult> {
-      console.log(
-        `[OpenMDM] Push (stub): ${deviceIds.length} devices <- ${message.type}`
+      stubLogger.debug(
+        { count: deviceIds.length, type: message.type },
+        'sendBatch (stub)',
       );
       return {
         successCount: deviceIds.length,

package/src/logger.ts

@@ -0,0 +1,98 @@
+/**
+ * OpenMDM Logger
+ *
+ * Default logger implementations and helpers. Production users are
+ * expected to pass their own pino/winston/bunyan instance via
+ * `createMDM({ logger })`; these defaults are for development and
+ * for the zero-config path.
+ */
+
+import type { Logger, LogContext } from './types';
+
+/**
+ * Resolve (context, message) or (message) argument forms into a
+ * single shape. Matches the pino call convention used by the Logger
+ * interface.
+ */
+function normalize(
+  ...args: [LogContext, string] | [string]
+): { context: LogContext | undefined; message: string } {
+  if (args.length === 1) {
+    return { context: undefined, message: args[0] };
+  }
+  return { context: args[0], message: args[1] };
+}
+
+/**
+ * Console-backed logger. Writes JSON-ish lines to stdout/stderr with
+ * an `[openmdm]` prefix so they stand out in a mixed-log stream.
+ *
+ * This is the zero-config default — it intentionally does the
+ * minimum viable thing. Hosts running in production should replace
+ * it with a real structured logger.
+ */
+export function createConsoleLogger(scope: string[] = []): Logger {
+  const prefix = scope.length > 0 ? `[openmdm:${scope.join(':')}]` : '[openmdm]';
+
+  const render = (context: LogContext | undefined): string => {
+    if (!context || Object.keys(context).length === 0) return '';
+    // Keep single-line to remain friendly to `grep`. JSON.stringify is
+    // the cheapest structured-output format that every production
+    // logger can consume as-is.
+    try {
+      return ' ' + JSON.stringify(context);
+    } catch {
+      // Fall back to a string cast when the context has a circular
+      // reference — losing structure is better than crashing the call
+      // site.
+      return ' ' + String(context);
+    }
+  };
+
+  return {
+    debug: (...args: [LogContext, string] | [string]) => {
+      const { context, message } = normalize(...args);
+      // Debug is off by default when no DEBUG env var is set — keeps
+      // the dev experience quiet unless someone opts in.
+      if (!process.env.DEBUG) return;
+      console.debug(`${prefix} ${message}${render(context)}`);
+    },
+    info: (...args: [LogContext, string] | [string]) => {
+      const { context, message } = normalize(...args);
+      console.log(`${prefix} ${message}${render(context)}`);
+    },
+    warn: (...args: [LogContext, string] | [string]) => {
+      const { context, message } = normalize(...args);
+      console.warn(`${prefix} ${message}${render(context)}`);
+    },
+    error: (...args: [LogContext, string] | [string]) => {
+      const { context, message } = normalize(...args);
+      console.error(`${prefix} ${message}${render(context)}`);
+    },
+    child: (bindings: LogContext): Logger => {
+      // Console logger's `child` extends the scope with any
+      // `component` field if provided, otherwise appends nothing
+      // meaningful and just returns a new logger with the same
+      // scope. Real loggers (pino) properly attach bindings to every
+      // subsequent call — we do the simplest thing that won't lie.
+      const componentPart =
+        typeof bindings.component === 'string' ? [bindings.component] : [];
+      return createConsoleLogger([...scope, ...componentPart]);
+    },
+  };
+}
+
+/**
+ * No-op logger. Use to silence OpenMDM entirely — e.g. in tests or in
+ * environments where log noise is inappropriate.
+ */
+export function createSilentLogger(): Logger {
+  const silent: Logger = {
+    debug: () => undefined,
+    info: () => undefined,
+    warn: () => undefined,
+    error: () => undefined,
+    child: () => silent,
+  };
+  return silent;
+}

package/src/plugin-storage.ts

@@ -19,7 +19,11 @@ export function createPluginStorageAdapter(db: DatabaseAdapter): PluginStorageAd
       }
 
       // Fallback: not supported
-      console.warn('Plugin storage not supported by database adapter');
+      // Silently no-op: the plugin-storage contract treats missing
+      // adapter methods as "not configured", which is the same
+      // branch plugins handle via their in-memory fallback. A warn
+      // log here would flood production with one line per hit.
+      //
       return null;
     },
 
@@ -29,7 +33,11 @@ export function createPluginStorageAdapter(db: DatabaseAdapter): PluginStorageAd
         return;
       }
 
-      console.warn('Plugin storage not supported by database adapter');
+      // Silently no-op: the plugin-storage contract treats missing
+      // adapter methods as "not configured", which is the same
+      // branch plugins handle via their in-memory fallback. A warn
+      // log here would flood production with one line per hit.
+      //
     },
 
     async delete(pluginName: string, key: string): Promise<void> {
@@ -38,7 +46,11 @@ export function createPluginStorageAdapter(db: DatabaseAdapter): PluginStorageAd
         return;
       }
 
-      console.warn('Plugin storage not supported by database adapter');
+      // Silently no-op: the plugin-storage contract treats missing
+      // adapter methods as "not configured", which is the same
+      // branch plugins handle via their in-memory fallback. A warn
+      // log here would flood production with one line per hit.
+      //
     },
 
     async list(pluginName: string, prefix?: string): Promise<string[]> {
@@ -46,7 +58,11 @@ export function createPluginStorageAdapter(db: DatabaseAdapter): PluginStorageAd
         return db.listPluginKeys(pluginName, prefix);
       }
 
-      console.warn('Plugin storage not supported by database adapter');
+      // Silently no-op: the plugin-storage contract treats missing
+      // adapter methods as "not configured", which is the same
+      // branch plugins handle via their in-memory fallback. A warn
+      // log here would flood production with one line per hit.
+      //
       return [];
     },
 
@@ -56,7 +72,11 @@ export function createPluginStorageAdapter(db: DatabaseAdapter): PluginStorageAd
         return;
       }
 
-      console.warn('Plugin storage not supported by database adapter');
+      // Silently no-op: the plugin-storage contract treats missing
+      // adapter methods as "not configured", which is the same
+      // branch plugins handle via their in-memory fallback. A warn
+      // log here would flood production with one line per hit.
+      //
     },
   };
 }