@openmdm/core 0.7.0 → 0.9.0

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-import { WebhookConfig, MDMEvent, WebhookEndpoint, EventType, DatabaseAdapter, TenantManager, AuthorizationManager, AuditConfig, AuditManager, ScheduleManager, MessageQueueManager, DashboardManager, PluginStorageAdapter, MDMConfig, MDMInstance, EnrollmentRequest } from './types.js';
-export { AppInstallationSummary, AppRollback, AppVersion, Application, ApplicationManager, ApplicationNotFoundError, AuditAction, AuditLog, AuditLogFilter, AuditLogListResult, AuditSummary, AuthConfig, AuthenticationError, AuthorizationError, Command, CommandFilter, CommandManager, CommandNotFoundError, CommandResult, CommandStatus, CommandSuccessRates, CommandType, CreateAppRollbackInput, CreateApplicationInput, CreateAuditLogInput, CreateDeviceInput, CreateGroupInput, CreatePolicyInput, CreateRoleInput, CreateScheduledTaskInput, CreateTenantInput, CreateUserInput, DashboardStats, DeployTarget, Device, DeviceFilter, DeviceListResult, DeviceLocation, DeviceManager, DeviceNotFoundError, DeviceStatus, DeviceStatusBreakdown, EnqueueMessageInput, EnrollmentConfig, EnrollmentError, EnrollmentMethod, EnrollmentResponse, EnrollmentTrendPoint, EventFilter, EventHandler, EventPayloadMap, Group, GroupHierarchyStats, GroupManager, GroupNotFoundError, GroupTreeNode, HardwareControl, Heartbeat, InstalledApp, MDMError, MDMPlugin, MaintenanceWindow, PasswordPolicy, Permission, PermissionAction, PermissionResource, PluginMiddleware, PluginRoute, PluginStorageEntry, Policy, PolicyApplication, PolicyManager, PolicyNotFoundError, PolicySettings, PushAdapter, PushBatchResult, PushConfig, PushMessage, PushProviderConfig, PushResult, PushToken, QueueMessageStatus, QueueStats, QueuedMessage, RegisterPushTokenInput, Role, RoleNotFoundError, ScheduledTask, ScheduledTaskFilter, ScheduledTaskListResult, ScheduledTaskStatus, SendCommandInput, StorageConfig, SystemUpdatePolicy, TaskExecution, TaskSchedule, TaskType, Tenant, TenantFilter, TenantListResult, TenantNotFoundError, TenantSettings, TenantStats, TenantStatus, TimeWindow, UpdateApplicationInput, UpdateDeviceInput, UpdateGroupInput, UpdatePolicyInput, UpdateRoleInput, UpdateScheduledTaskInput, UpdateTenantInput, UpdateUserInput, User, UserFilter, UserListResult, UserNotFoundError, UserWithRoles, ValidationError, VpnConfig, WebhookDeliveryResult, WebhookManager, WifiConfig } from './types.js';
+import { WebhookConfig, Logger, MDMEvent, WebhookEndpoint, EventType, MDMInstance, DeviceIdentityVerification, DatabaseAdapter, TenantManager, AuthorizationManager, AuditConfig, AuditManager, ScheduleManager, MessageQueueManager, DashboardManager, PluginStorageAdapter, MDMConfig, EnrollmentRequest } from './types.js';
+export { AppInstallationSummary, AppRollback, AppVersion, Application, ApplicationManager, ApplicationNotFoundError, AuditAction, AuditLog, AuditLogFilter, AuditLogListResult, AuditSummary, AuthConfig, AuthenticationError, AuthorizationError, Command, CommandFilter, CommandManager, CommandNotFoundError, CommandResult, CommandStatus, CommandSuccessRates, CommandType, CreateAppRollbackInput, CreateApplicationInput, CreateAuditLogInput, CreateDeviceInput, CreateGroupInput, CreatePolicyInput, CreateRoleInput, CreateScheduledTaskInput, CreateTenantInput, CreateUserInput, DashboardStats, DeployTarget, Device, DeviceFilter, DeviceListResult, DeviceLocation, DeviceManager, DeviceNotFoundError, DeviceStatus, DeviceStatusBreakdown, EnqueueMessageInput, EnrollmentChallenge, EnrollmentConfig, EnrollmentError, EnrollmentMethod, EnrollmentResponse, EnrollmentTrendPoint, EventFilter, EventHandler, EventPayloadMap, Group, GroupHierarchyStats, GroupManager, GroupNotFoundError, GroupTreeNode, HardwareControl, Heartbeat, InstalledApp, LogContext, MDMError, MDMPlugin, MaintenanceWindow, PasswordPolicy, Permission, PermissionAction, PermissionResource, PinnedKeyConfig, PluginMiddleware, PluginRoute, PluginStorageEntry, Policy, PolicyApplication, PolicyManager, PolicyNotFoundError, PolicySettings, PushAdapter, PushBatchResult, PushConfig, PushMessage, PushProviderConfig, PushResult, PushToken, QueueMessageStatus, QueueStats, QueuedMessage, RegisterPushTokenInput, Role, RoleNotFoundError, ScheduledTask, ScheduledTaskFilter, ScheduledTaskListResult, ScheduledTaskStatus, SendCommandInput, StorageConfig, SystemUpdatePolicy, TaskExecution, TaskSchedule, TaskType, Tenant, TenantFilter, TenantListResult, TenantNotFoundError, TenantSettings, TenantStats, TenantStatus, TimeWindow, UpdateApplicationInput, UpdateDeviceInput, UpdateGroupInput, UpdatePolicyInput, UpdateRoleInput, UpdateScheduledTaskInput, UpdateTenantInput, UpdateUserInput, User, UserFilter, UserListResult, UserNotFoundError, UserWithRoles, ValidationError, VpnConfig, WebhookDeliveryResult, WebhookManager, WifiConfig } from './types.js';
 export { ColumnDefinition, ColumnType, IndexDefinition, SchemaDefinition, TableDefinition, camelToSnake, getColumnNames, getPrimaryKey, getTableNames, mdmSchema, snakeToCamel, transformToCamelCase, transformToSnakeCase } from './schema.js';
+import { KeyObject } from 'crypto';
 
 /**
  * OpenMDM Agent Wire Protocol v2.
@@ -164,13 +165,213 @@ interface WebhookManager {
 /**
  * Create a webhook manager instance
  */
-declare function createWebhookManager(config: WebhookConfig): WebhookManager;
+declare function createWebhookManager(config: WebhookConfig, logger?: Logger): WebhookManager;
 /**
  * Verify a webhook signature from incoming requests
  * (Utility for consumers to verify our webhooks)
  */
 declare function verifyWebhookSignature(payload: string, signature: string, secret: string): boolean;
 
+/**
+ * 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.
+ */
+
+/**
+ * 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.
+ */
+declare function createConsoleLogger(scope?: string[]): Logger;
+/**
+ * No-op logger. Use to silence OpenMDM entirely — e.g. in tests or in
+ * environments where log noise is inappropriate.
+ */
+declare function createSilentLogger(): Logger;
+
+/**
+ * OpenMDM Device Identity
+ *
+ * Device-pinned asymmetric identity, using an ECDSA P-256 keypair the
+ * device generates in its own Keystore and registers with the server on
+ * first enrollment. After pinning, every consumer can verify a signed
+ * request against the same pinned public key — no shared HMAC secret,
+ * no APK extraction footgun, no dependence on Google hardware
+ * attestation (which most non-GMS fleet hardware cannot produce).
+ *
+ * This module is the reusable primitive. `@openmdm/core` uses it to
+ * gate `/agent/enroll` and will use it for `/agent/*` in Phase 2c.
+ * External consumers (midiamob's `deviceValidation.ts`, other custom
+ * servers) import the same functions to verify requests against the
+ * same pinned key — one device identity, many consumers.
+ *
+ * Why zero dependencies: Node's built-in `node:crypto` supports EC
+ * P-256 SPKI import and `crypto.verify('sha256', ...)` over DER-encoded
+ * signatures, which is the default format the Android Keystore
+ * produces. We deliberately do not pull in `@peculiar/*` or `node-forge`
+ * for this primitive — the surface area we need is small enough that
+ * the built-in is the right call.
+ *
+ * @see docs/concepts/enrollment for the full flow
+ * @see docs/proposals/phase-2b-rollout for the Android + rollout story
+ */
+
+/**
+ * Import an EC P-256 public key from base64-encoded SubjectPublicKeyInfo
+ * (SPKI) bytes — the standard on-wire format the Android Keystore
+ * produces when you call `certificate.publicKey.encoded` on a
+ * `KeyStore.getCertificate(alias)` result.
+ *
+ * Throws `InvalidPublicKeyError` on any parse failure. This is a
+ * security boundary — we do NOT return `null` on malformed input,
+ * because a caller that forgot to handle the null case would silently
+ * treat bad keys as "no key configured" and fall through to an
+ * insecure path.
+ */
+declare function importPublicKeyFromSpki(spkiBase64: string): KeyObject;
+/**
+ * Verify an ECDSA-P256 signature over a message using a previously-
+ * imported or raw SPKI public key.
+ *
+ * Signature must be DER-encoded — the default Android Keystore
+ * produces DER, and `Signature.sign()` on JVM/Kotlin returns DER, so
+ * this matches what every reasonable agent sends on the wire.
+ *
+ * Returns `true` iff the signature is valid. Never throws on a bad
+ * signature (that is the whole point of a verify call). Throws only
+ * on an invalid public-key encoding, because that indicates a caller
+ * bug rather than a forged request.
+ */
+declare function verifyEcdsaSignature(publicKey: KeyObject | string, message: string, signatureBase64: string): boolean;
+/**
+ * Build the canonical message that an enrollment signature covers.
+ *
+ * Staying in lockstep with `@openmdm/client` and with the Android
+ * agent is load-bearing — any change here is a wire break across
+ * every enrolled device. The contract test in
+ * `packages/core/tests/device-identity.test.ts` guards against drift.
+ *
+ * Shape (order matters):
+ *
+ *   publicKey |
+ *   model | manufacturer | osVersion |
+ *   serialNumber | imei | macAddress | androidId |
+ *   method | timestamp | challenge
+ *
+ * The public key is prepended (rather than appended) because it's the
+ * field most likely to be the whole point of the message — putting it
+ * first makes the signature's intent visible at a glance in logs.
+ */
+declare function canonicalEnrollmentMessage(parts: {
+    publicKey: string;
+    model: string;
+    manufacturer: string;
+    osVersion: string;
+    serialNumber?: string;
+    imei?: string;
+    macAddress?: string;
+    androidId?: string;
+    method: string;
+    timestamp: string;
+    challenge: string;
+}): string;
+/**
+ * Build the canonical message that a *post-enrollment* request
+ * signature covers. Consumers (openmdm's `/agent/*` routes,
+ * midiamob's `deviceValidation.ts`, any custom server) call this
+ * with the fields they want committed to the signature.
+ *
+ * The shape is deliberately narrower than the enrollment form — only
+ * the parts every request has in common.
+ *
+ *   deviceId | timestamp | body | nonce
+ *
+ * `nonce` is optional; pass an empty string when the request does not
+ * carry a challenge. Replay protection on non-enrollment traffic is
+ * the caller's job — if your server already has a timestamp window
+ * check, you don't need a nonce per request.
+ */
+declare function canonicalDeviceRequestMessage(parts: {
+    deviceId: string;
+    timestamp: string;
+    body: string;
+    nonce?: string;
+}): string;
+/**
+ * Verify a signed request from an enrolled device against the
+ * public key pinned on that device's row.
+ *
+ * This is the primitive every consumer of device-pinned-key identity
+ * calls. It performs exactly the checks required to know the request
+ * came from the device that originally enrolled, in constant-ish
+ * time:
+ *
+ *  1. Look up the device by id.
+ *  2. Confirm the device has a pinned public key (refusing silently
+ *     if not — a device without a pinned key is still on the legacy
+ *     HMAC path and cannot be verified here).
+ *  3. Verify the ECDSA signature over the provided canonical message.
+ *
+ * Returns a tagged union so callers can react to the specific failure
+ * mode:
+ *
+ *  - `not-found`   — the device id doesn't exist. Almost always a bug
+ *                    in the caller, or a stolen/revoked device id.
+ *                    Return 401 to the client.
+ *  - `no-pinned-key` — the device is still on the HMAC path. Callers
+ *                    should fall through to their legacy verifier
+ *                    (or fail, if the caller has already migrated).
+ *  - `signature-invalid` — the signature did not verify against the
+ *                    pinned key. Return 401. **Do NOT** re-pin the
+ *                    submitted public key in response to a failure
+ *                    here — that's how re-pinning becomes a hijack.
+ */
+declare function verifyDeviceRequest(opts: {
+    mdm: MDMInstance;
+    deviceId: string;
+    canonicalMessage: string;
+    signatureBase64: string;
+}): Promise<DeviceIdentityVerification>;
+/**
+ * Thrown when a submitted public key cannot be parsed. This is a
+ * caller-facing error — the device sent something that is not a
+ * well-formed SPKI EC P-256 public key.
+ */
+declare class InvalidPublicKeyError extends Error {
+    readonly cause?: Error | undefined;
+    readonly code = "INVALID_PUBLIC_KEY";
+    constructor(message: string, cause?: Error | undefined);
+}
+/**
+ * Thrown when a device attempts to re-enroll with a public key that
+ * does not match the one originally pinned for its enrollment id.
+ *
+ * This is the core "device identity continuity" check. The server
+ * will NEVER automatically re-pin on mismatch — rebinding a device
+ * identity requires an explicit admin action (future work).
+ */
+declare class PublicKeyMismatchError extends Error {
+    readonly deviceId: string;
+    readonly code = "PUBLIC_KEY_MISMATCH";
+    constructor(deviceId: string);
+}
+/**
+ * Thrown when an enrollment attempts to use a challenge that is
+ * missing, expired, or already consumed.
+ */
+declare class ChallengeInvalidError extends Error {
+    readonly challenge?: string | undefined;
+    readonly code = "CHALLENGE_INVALID";
+    constructor(message: string, challenge?: string | undefined);
+}
+
 /**
  * OpenMDM Tenant Manager
  *
@@ -303,4 +504,4 @@ declare function parsePluginKey(key: string): {
 declare function createMDM(config: MDMConfig): MDMInstance;
 declare function verifyEnrollmentSignature(request: EnrollmentRequest, secret: string): boolean;
 
-export { AGENT_PROTOCOL_HEADER, AGENT_PROTOCOL_V2, type AgentAction, type AgentResponse, AuditConfig, AuditManager, AuthorizationManager, DashboardManager, DatabaseAdapter, EnrollmentRequest, EventType, MDMConfig, MDMEvent, MDMInstance, MessageQueueManager, PluginStorageAdapter, ScheduleManager, TenantManager, WebhookConfig, WebhookEndpoint, type WebhookPayload, agentFail, agentOk, createAuditManager, createAuthorizationManager, createDashboardManager, createMDM, createMemoryPluginStorageAdapter, createMessageQueueManager, createPluginKey, createPluginStorageAdapter, createScheduleManager, createTenantManager, createWebhookManager, parsePluginKey, verifyEnrollmentSignature, verifyWebhookSignature, wantsAgentProtocolV2 };
+export { AGENT_PROTOCOL_HEADER, AGENT_PROTOCOL_V2, type AgentAction, type AgentResponse, AuditConfig, AuditManager, AuthorizationManager, ChallengeInvalidError, DashboardManager, DatabaseAdapter, DeviceIdentityVerification, EnrollmentRequest, EventType, InvalidPublicKeyError, Logger, MDMConfig, MDMEvent, MDMInstance, MessageQueueManager, PluginStorageAdapter, PublicKeyMismatchError, ScheduleManager, TenantManager, WebhookConfig, WebhookEndpoint, type WebhookPayload, agentFail, agentOk, canonicalDeviceRequestMessage, canonicalEnrollmentMessage, createAuditManager, createAuthorizationManager, createConsoleLogger, createDashboardManager, createMDM, createMemoryPluginStorageAdapter, createMessageQueueManager, createPluginKey, createPluginStorageAdapter, createScheduleManager, createSilentLogger, createTenantManager, createWebhookManager, importPublicKeyFromSpki, parsePluginKey, verifyDeviceRequest, verifyEcdsaSignature, verifyEnrollmentSignature, verifyWebhookSignature, wantsAgentProtocolV2 };