@openmdm/core 0.4.1 → 0.6.0

package/dist/index.d.ts

@@ -2,6 +2,119 @@ import { WebhookConfig, MDMEvent, WebhookEndpoint, EventType, DatabaseAdapter, T
 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, EnrollmentRequest, 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';
 export { ColumnDefinition, ColumnType, IndexDefinition, SchemaDefinition, TableDefinition, camelToSnake, getColumnNames, getPrimaryKey, getTableNames, mdmSchema, snakeToCamel, transformToCamelCase, transformToSnakeCase } from './schema.js';
 
+/**
+ * OpenMDM Agent Wire Protocol v2.
+ *
+ * A unified response envelope for every `/agent/*` endpoint, plus the
+ * version-selection rules that let the server serve v1 and v2 clients
+ * simultaneously during a fleet rollout.
+ *
+ * ## Background
+ *
+ * Until now, agent-facing handlers returned either a bare JSON body
+ * on success or raised an `HTTPException(401|404|5xx)` on failure.
+ * The agent had to interpret five different HTTP status codes and
+ * infer what to do about each — which in practice meant "on auth
+ * error, wipe local enrollment state and re-enroll". That single
+ * ambiguity produced the auto-unenroll behavior we saw in production:
+ * a transient 401 or 404 was indistinguishable from "you are really
+ * unenrolled", so the agent self-destructed.
+ *
+ * ## Protocol v2
+ *
+ * Every agent-facing endpoint replies with HTTP 200 and a body of
+ * shape {@link AgentResponse}:
+ *
+ * ```json
+ * { "ok": true,  "action": "none",      "data": { ... } }
+ * { "ok": false, "action": "retry",     "message": "..." }
+ * { "ok": false, "action": "reauth",    "message": "..." }
+ * { "ok": false, "action": "unenroll",  "message": "..." }
+ * ```
+ *
+ * - `ok` is the boolean the agent checks first.
+ * - `action` is the *only* field the agent reads to decide what to do
+ *   next. There is exactly one handler per action on the client, so
+ *   adding a new server response path is a matter of picking an
+ *   existing action.
+ * - `data` carries the handler-specific payload (heartbeat response,
+ *   policy update, etc.) on success.
+ * - `message` is a human-readable hint, for logs.
+ *
+ * HTTP 5xx is still used for real infrastructure failures (the Lambda
+ * timed out, the database connection dropped, etc.). v2 envelopes are
+ * reserved for *application-level* failures the agent can reason about.
+ *
+ * ## Versioning and rollout
+ *
+ * The agent opts into v2 by sending the header
+ * `X-Openmdm-Protocol: 2` on every request. When absent, the server
+ * falls back to the legacy v1 behavior — bare JSON on success,
+ * `HTTPException(401|404|…)` on failure — so a fleet still running
+ * older APKs keeps working during rollout.
+ *
+ * After the fleet has been upgraded, v1 can be dropped in a future
+ * major release by ignoring the header and always emitting v2.
+ */
+/**
+ * Instruction the server gives the agent on how to react to this
+ * response. This is the entire client-side decision space.
+ *
+ * - `none`: happy path. The agent consumes `data` and continues.
+ * - `retry`: transient problem. The agent re-tries later without
+ *   touching local state.
+ * - `reauth`: the agent's access token is no longer valid. It should
+ *   call the refresh flow. It must NOT wipe enrollment state.
+ * - `unenroll`: the server-side record for this device is gone or
+ *   blocked and the agent's credentials will never work again. The
+ *   agent should stop making requests and surface this to the user.
+ *   In Phase 2b this will be further softened: the agent will attempt
+ *   a hardware-identity-based rebind before treating this as terminal.
+ */
+type AgentAction = 'none' | 'retry' | 'reauth' | 'unenroll';
+/**
+ * Unified response envelope for every `/agent/*` endpoint under
+ * protocol v2.
+ *
+ * Successful responses carry `data`; failure responses carry
+ * `message`. The envelope never carries both the happy-path payload
+ * and an error hint at the same time.
+ */
+type AgentResponse<T = unknown> = {
+    ok: true;
+    action: 'none';
+    data: T;
+} | {
+    ok: false;
+    action: Exclude<AgentAction, 'none'>;
+    message?: string;
+};
+/**
+ * HTTP header an agent sends to opt into protocol v2. Case-insensitive
+ * on the wire; use the constant to avoid typos.
+ */
+declare const AGENT_PROTOCOL_HEADER = "X-Openmdm-Protocol";
+/**
+ * Current wire-protocol version. Agents that send
+ * `X-Openmdm-Protocol: 2` get envelope responses. Absent or older
+ * values are served with the legacy flat shape.
+ */
+declare const AGENT_PROTOCOL_V2 = "2";
+/**
+ * Helper: build a success envelope.
+ */
+declare function agentOk<T>(data: T): AgentResponse<T>;
+/**
+ * Helper: build a failure envelope.
+ */
+declare function agentFail(action: Exclude<AgentAction, 'none'>, message?: string): AgentResponse<never>;
+/**
+ * Returns `true` iff the caller should be served protocol v2. The
+ * input is the value of the {@link AGENT_PROTOCOL_HEADER} header,
+ * which may be undefined.
+ */
+declare function wantsAgentProtocolV2(headerValue: string | undefined | null): boolean;
+
 /**
  * OpenMDM Webhook Delivery System
  *
@@ -189,4 +302,4 @@ declare function parsePluginKey(key: string): {
  */
 declare function createMDM(config: MDMConfig): MDMInstance;
 
-export { AuditConfig, AuditManager, AuthorizationManager, DashboardManager, DatabaseAdapter, EventType, MDMConfig, MDMEvent, MDMInstance, MessageQueueManager, PluginStorageAdapter, ScheduleManager, TenantManager, WebhookConfig, WebhookEndpoint, type WebhookPayload, createAuditManager, createAuthorizationManager, createDashboardManager, createMDM, createMemoryPluginStorageAdapter, createMessageQueueManager, createPluginKey, createPluginStorageAdapter, createScheduleManager, createTenantManager, createWebhookManager, parsePluginKey, verifyWebhookSignature };
+export { AGENT_PROTOCOL_HEADER, AGENT_PROTOCOL_V2, type AgentAction, type AgentResponse, AuditConfig, AuditManager, AuthorizationManager, DashboardManager, DatabaseAdapter, 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, verifyWebhookSignature, wantsAgentProtocolV2 };

package/dist/index.js

@@ -2026,6 +2026,19 @@ function transformToSnakeCase(obj) {
   return result;
 }
 
+// src/agent-protocol.ts
+var AGENT_PROTOCOL_HEADER = "X-Openmdm-Protocol";
+var AGENT_PROTOCOL_V2 = "2";
+function agentOk(data) {
+  return { ok: true, action: "none", data };
+}
+function agentFail(action, message) {
+  return { ok: false, action, message };
+}
+function wantsAgentProtocolV2(headerValue) {
+  return headerValue === AGENT_PROTOCOL_V2;
+}
+
 // src/index.ts
 function createMDM(config) {
   const { database, push, enrollment, webhooks: webhooksConfig, plugins = [] } = config;
@@ -2895,6 +2908,6 @@ function generateDeviceToken(deviceId, secret, expirationSeconds) {
   return `${header}.${payload}.${signature}`;
 }
 
-export { ApplicationNotFoundError, AuthenticationError, AuthorizationError, CommandNotFoundError, DeviceNotFoundError, EnrollmentError, GroupNotFoundError, MDMError, PolicyNotFoundError, RoleNotFoundError, TenantNotFoundError, UserNotFoundError, ValidationError, camelToSnake, createAuditManager, createAuthorizationManager, createDashboardManager, createMDM, createMemoryPluginStorageAdapter, createMessageQueueManager, createPluginKey, createPluginStorageAdapter, createScheduleManager, createTenantManager, createWebhookManager, getColumnNames, getPrimaryKey, getTableNames, mdmSchema, parsePluginKey, snakeToCamel, transformToCamelCase, transformToSnakeCase, verifyWebhookSignature };
+export { AGENT_PROTOCOL_HEADER, AGENT_PROTOCOL_V2, ApplicationNotFoundError, AuthenticationError, AuthorizationError, CommandNotFoundError, DeviceNotFoundError, EnrollmentError, GroupNotFoundError, MDMError, PolicyNotFoundError, RoleNotFoundError, TenantNotFoundError, UserNotFoundError, ValidationError, agentFail, agentOk, camelToSnake, createAuditManager, createAuthorizationManager, createDashboardManager, createMDM, createMemoryPluginStorageAdapter, createMessageQueueManager, createPluginKey, createPluginStorageAdapter, createScheduleManager, createTenantManager, createWebhookManager, getColumnNames, getPrimaryKey, getTableNames, mdmSchema, parsePluginKey, snakeToCamel, transformToCamelCase, transformToSnakeCase, verifyWebhookSignature, wantsAgentProtocolV2 };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map