@infinitetoken/lumber-kit 0.5.2 → 0.6.0

package/README.md

@@ -50,7 +50,7 @@ import { LogLevel, LogRecord, LogEncrypted, LogPayload, LogsQuery } from '@infin
 | `PUSH_OFF` | constant | A push threshold one past Fatal (5): log pushes off |
 | `PushThreshold` | type | A `LogLevel` or `PUSH_OFF`, stored as a preference's `minimumLevel` |
 | `normalizePushThreshold` | function | A threshold from any stored or sent value: past Fatal is off, not a number is Warn |
-| `PushData` | type | The `data` each push type carries (`log`, `note`, `device_link`, `key_check`, `key_waiting`, `keys_shared`) |
+| `PushData` | type | The `data` each push type carries (`log`, `note`, `device_link`, `device_link_answered`, `key_check`, `key_waiting`, `keys_shared`) |
 | `parsePushData` | function | A push's data as `PushData`, or `null` for data no Lumber push sends |
 
 ### Socket events
@@ -100,6 +100,10 @@ import { LogLevel, LogRecord, LogEncrypted, LogPayload, LogsQuery } from '@infin
 | `AppKeyUpsertBody` | interface | Body of PUT /apps/:id/keys/:userId |
 | `KeyPin` | interface | An account key a user accepted for someone, with its MAC |
 | `HolderKeyCheck`, `ClaimantKeyCheck`, `KeyCheckResult` | interfaces | A key check as the holder and the person being confirmed read it |
+| `DeviceLinkCreateBody`, `DeviceLinkCreatedRecord` | interfaces | POST /device-links: a new device asking for the account key, and its answer |
+| `DeviceLinkRecord`, `DeviceLinkApproveBody` | interfaces | A link request as the new device polls it (the exchange's first message once a code is shown, then the account key and the tag proving a device that showed the code sent it), and the approval that carries them |
+| `PendingDeviceLink` | interface | A link request as a device holding the account key reads it, to show its code and finish it |
+| `DeviceLinkStatus`, `DeviceLinkPlatform` | types | `pending`, `approved`, `denied` or `failed` (a code that didn't match); what the request comes from |
 
 ### Colors
 

package/dist/index.d.mts

@@ -222,7 +222,24 @@ interface AppsQuery {
     cursor?: string;
 }
 
-type DeviceLinkStatus = 'pending' | 'approved' | 'denied';
+/**
+ * A device link request: a new device asking for the account key from a device that has it. `failed` is a code that
+ * didn't match, which ends the request.
+ */
+type DeviceLinkStatus = 'pending' | 'approved' | 'denied' | 'failed';
+/** What a request comes from, so the device answering it can say so and offer a QR code only to a phone's camera. */
+type DeviceLinkPlatform = 'ios' | 'android' | 'web' | 'desktop' | 'cli';
+/**
+ * Body of POST /device-links.
+ */
+interface DeviceLinkCreateBody {
+    deviceName: string;
+    platform: DeviceLinkPlatform;
+    /** The public half of the new device's one-off X25519 keypair, which the account key is wrapped to. */
+    publicKey: string;
+    /** The new device's push device id, so the push asking the account's devices to link it skips it. */
+    deviceId?: string;
+}
 /**
  * Response from POST /device-links.
  */
@@ -231,14 +248,48 @@ interface DeviceLinkCreatedRecord {
     expiresAt: string;
 }
 /**
- * Response from GET /device-links/:id.
- * encryptedKey is present only when status is 'approved'.
+ * Body of POST /device-links/:id/approve: the account key wrapped to the new device, and a tag over it made from the
+ * code's secret, which the new device checks before storing the key, so the server can't hand it a key of its own.
+ */
+interface DeviceLinkApproveBody {
+    encryptedKey: string;
+    deliveryTag: string;
+}
+/**
+ * Response from GET /device-links/:id, as the new device reads it.
+ * encryptedKey and deliveryTag are present only when status is 'approved'. sid and holderMessage are set once a device
+ * holding the account key shows the request's code, and answeredAt once the new device has answered it.
  */
 interface DeviceLinkRecord {
     id: string;
     status: DeviceLinkStatus;
     encryptedKey?: string;
+    deliveryTag?: string;
     expiresAt: string;
+    sid?: string | null;
+    holderMessage?: string | null;
+    answeredAt?: string | null;
+}
+/**
+ * A request waiting on the caller's account key (GET /device-links/pending), as a device holding it reads it: enough
+ * to show its code, and to finish it once answered. The messages are the same password-authenticated exchange as a key
+ * check's, so the server can't read or test codes against them. holderState is the code's side of the exchange, sealed
+ * under the account key, so any of the account's devices can show the same code or finish the request.
+ */
+interface PendingDeviceLink {
+    id: string;
+    deviceName: string;
+    platform: DeviceLinkPlatform;
+    /** The new device's one-off public key, which an answer's tag has to cover before anything is wrapped to it. */
+    publicKey: string;
+    sid: string | null;
+    holderMessage: string | null;
+    holderState: string | null;
+    claimantMessage: string | null;
+    tag: string | null;
+    answeredAt: string | null;
+    expiresAt: string;
+    createdAt: string;
 }
 
 /**
@@ -471,6 +522,12 @@ type PushData =
     deviceLinkId: string;
     deviceName: string;
 }
+/** The new device entered its link code, which a device holding the account key now checks (Lumber-API). */
+ | {
+    type: 'device_link_answered';
+    deviceLinkId: string;
+    deviceName: string;
+}
 /** The person the reader gave a code entered it (Lumber-API). */
  | {
     type: 'key_check';
@@ -657,4 +714,4 @@ declare const apiErrorCodeOf: (body: unknown) => ApiErrorCode | null;
 /** A push notification's data as PushData, or null for data no Lumber push sends. */
 declare const parsePushData: (data: unknown) => PushData | null;
 
-export { APP_COLORS, type ApiErrorBody, type ApiErrorCode, type ApiKeyRecord, type ApiResponse, type AppCreatedRecord, type AppEncryptedKey, type AppKeyUpsertBody, type AppPermission, type AppPersonRecord, type AppRecord, type AppTeamAccess, type Appearance, type AppsQuery, type ClaimantKeyCheck, type ClientToServerEvents, DEFAULT_ACCENT, DEFAULT_PUSH_THRESHOLD, type DeviceLinkCreatedRecord, type DeviceLinkRecord, type DeviceLinkStatus, type FlagRecord, type FlagsQuery, type GuestRecord, type HolderKeyCheck, type InvitationRecord, type KeyCheckResult, type KeyHolder, type KeyPin, type LogContext, type LogEncrypted, LogLevel, type LogLevelName, type LogPayload, type LogRecord, type LogTimeseriesQuery, type LogsQuery, type NoteEncrypted, type NoteRecord, type NotesQuery, type NotificationPreference, type NotificationPreferences, PUSH_OFF, type PendingAppKey, type PushData, type PushThreshold, type PushToken, type PushType, type ResponseMetadata, type ServerToClientEvents, type SocketAppPayload, SubscriptionLevel, type SubscriptionLevelName, type SubscriptionLimits, type SubscriptionPlan, type SubscriptionPlanRecord, type TeamMemberRecord, type TeamRecord, type TeamsQuery, type TimeseriesBucket, type TimeseriesResponse, type UserRecord, apiErrorCodeOf, apiErrorCodes, isApiErrorCode, isValidAppearance, isValidColor, isValidDeviceLinkStatus, isValidImageUrl, isValidLogLevel, isValidSubscriptionLevel, isValidTeamMemberRole, joinApiKey, logLevelColors, logLevelNameToLevel, logLevelToName, logLevels, nameColor, normalizePushThreshold, parsePushData, personColor, resolveAppColor, splitApiKey, subscriptionLevelToName, subscriptionLevels, subscriptionLimits, subscriptionPlans };
+export { APP_COLORS, type ApiErrorBody, type ApiErrorCode, type ApiKeyRecord, type ApiResponse, type AppCreatedRecord, type AppEncryptedKey, type AppKeyUpsertBody, type AppPermission, type AppPersonRecord, type AppRecord, type AppTeamAccess, type Appearance, type AppsQuery, type ClaimantKeyCheck, type ClientToServerEvents, DEFAULT_ACCENT, DEFAULT_PUSH_THRESHOLD, type DeviceLinkApproveBody, type DeviceLinkCreateBody, type DeviceLinkCreatedRecord, type DeviceLinkPlatform, type DeviceLinkRecord, type DeviceLinkStatus, type FlagRecord, type FlagsQuery, type GuestRecord, type HolderKeyCheck, type InvitationRecord, type KeyCheckResult, type KeyHolder, type KeyPin, type LogContext, type LogEncrypted, LogLevel, type LogLevelName, type LogPayload, type LogRecord, type LogTimeseriesQuery, type LogsQuery, type NoteEncrypted, type NoteRecord, type NotesQuery, type NotificationPreference, type NotificationPreferences, PUSH_OFF, type PendingAppKey, type PendingDeviceLink, type PushData, type PushThreshold, type PushToken, type PushType, type ResponseMetadata, type ServerToClientEvents, type SocketAppPayload, SubscriptionLevel, type SubscriptionLevelName, type SubscriptionLimits, type SubscriptionPlan, type SubscriptionPlanRecord, type TeamMemberRecord, type TeamRecord, type TeamsQuery, type TimeseriesBucket, type TimeseriesResponse, type UserRecord, apiErrorCodeOf, apiErrorCodes, isApiErrorCode, isValidAppearance, isValidColor, isValidDeviceLinkStatus, isValidImageUrl, isValidLogLevel, isValidSubscriptionLevel, isValidTeamMemberRole, joinApiKey, logLevelColors, logLevelNameToLevel, logLevelToName, logLevels, nameColor, normalizePushThreshold, parsePushData, personColor, resolveAppColor, splitApiKey, subscriptionLevelToName, subscriptionLevels, subscriptionLimits, subscriptionPlans };

package/dist/index.d.ts

@@ -222,7 +222,24 @@ interface AppsQuery {
     cursor?: string;
 }
 
-type DeviceLinkStatus = 'pending' | 'approved' | 'denied';
+/**
+ * A device link request: a new device asking for the account key from a device that has it. `failed` is a code that
+ * didn't match, which ends the request.
+ */
+type DeviceLinkStatus = 'pending' | 'approved' | 'denied' | 'failed';
+/** What a request comes from, so the device answering it can say so and offer a QR code only to a phone's camera. */
+type DeviceLinkPlatform = 'ios' | 'android' | 'web' | 'desktop' | 'cli';
+/**
+ * Body of POST /device-links.
+ */
+interface DeviceLinkCreateBody {
+    deviceName: string;
+    platform: DeviceLinkPlatform;
+    /** The public half of the new device's one-off X25519 keypair, which the account key is wrapped to. */
+    publicKey: string;
+    /** The new device's push device id, so the push asking the account's devices to link it skips it. */
+    deviceId?: string;
+}
 /**
  * Response from POST /device-links.
  */
@@ -231,14 +248,48 @@ interface DeviceLinkCreatedRecord {
     expiresAt: string;
 }
 /**
- * Response from GET /device-links/:id.
- * encryptedKey is present only when status is 'approved'.
+ * Body of POST /device-links/:id/approve: the account key wrapped to the new device, and a tag over it made from the
+ * code's secret, which the new device checks before storing the key, so the server can't hand it a key of its own.
+ */
+interface DeviceLinkApproveBody {
+    encryptedKey: string;
+    deliveryTag: string;
+}
+/**
+ * Response from GET /device-links/:id, as the new device reads it.
+ * encryptedKey and deliveryTag are present only when status is 'approved'. sid and holderMessage are set once a device
+ * holding the account key shows the request's code, and answeredAt once the new device has answered it.
  */
 interface DeviceLinkRecord {
     id: string;
     status: DeviceLinkStatus;
     encryptedKey?: string;
+    deliveryTag?: string;
     expiresAt: string;
+    sid?: string | null;
+    holderMessage?: string | null;
+    answeredAt?: string | null;
+}
+/**
+ * A request waiting on the caller's account key (GET /device-links/pending), as a device holding it reads it: enough
+ * to show its code, and to finish it once answered. The messages are the same password-authenticated exchange as a key
+ * check's, so the server can't read or test codes against them. holderState is the code's side of the exchange, sealed
+ * under the account key, so any of the account's devices can show the same code or finish the request.
+ */
+interface PendingDeviceLink {
+    id: string;
+    deviceName: string;
+    platform: DeviceLinkPlatform;
+    /** The new device's one-off public key, which an answer's tag has to cover before anything is wrapped to it. */
+    publicKey: string;
+    sid: string | null;
+    holderMessage: string | null;
+    holderState: string | null;
+    claimantMessage: string | null;
+    tag: string | null;
+    answeredAt: string | null;
+    expiresAt: string;
+    createdAt: string;
 }
 
 /**
@@ -471,6 +522,12 @@ type PushData =
     deviceLinkId: string;
     deviceName: string;
 }
+/** The new device entered its link code, which a device holding the account key now checks (Lumber-API). */
+ | {
+    type: 'device_link_answered';
+    deviceLinkId: string;
+    deviceName: string;
+}
 /** The person the reader gave a code entered it (Lumber-API). */
  | {
     type: 'key_check';
@@ -657,4 +714,4 @@ declare const apiErrorCodeOf: (body: unknown) => ApiErrorCode | null;
 /** A push notification's data as PushData, or null for data no Lumber push sends. */
 declare const parsePushData: (data: unknown) => PushData | null;
 
-export { APP_COLORS, type ApiErrorBody, type ApiErrorCode, type ApiKeyRecord, type ApiResponse, type AppCreatedRecord, type AppEncryptedKey, type AppKeyUpsertBody, type AppPermission, type AppPersonRecord, type AppRecord, type AppTeamAccess, type Appearance, type AppsQuery, type ClaimantKeyCheck, type ClientToServerEvents, DEFAULT_ACCENT, DEFAULT_PUSH_THRESHOLD, type DeviceLinkCreatedRecord, type DeviceLinkRecord, type DeviceLinkStatus, type FlagRecord, type FlagsQuery, type GuestRecord, type HolderKeyCheck, type InvitationRecord, type KeyCheckResult, type KeyHolder, type KeyPin, type LogContext, type LogEncrypted, LogLevel, type LogLevelName, type LogPayload, type LogRecord, type LogTimeseriesQuery, type LogsQuery, type NoteEncrypted, type NoteRecord, type NotesQuery, type NotificationPreference, type NotificationPreferences, PUSH_OFF, type PendingAppKey, type PushData, type PushThreshold, type PushToken, type PushType, type ResponseMetadata, type ServerToClientEvents, type SocketAppPayload, SubscriptionLevel, type SubscriptionLevelName, type SubscriptionLimits, type SubscriptionPlan, type SubscriptionPlanRecord, type TeamMemberRecord, type TeamRecord, type TeamsQuery, type TimeseriesBucket, type TimeseriesResponse, type UserRecord, apiErrorCodeOf, apiErrorCodes, isApiErrorCode, isValidAppearance, isValidColor, isValidDeviceLinkStatus, isValidImageUrl, isValidLogLevel, isValidSubscriptionLevel, isValidTeamMemberRole, joinApiKey, logLevelColors, logLevelNameToLevel, logLevelToName, logLevels, nameColor, normalizePushThreshold, parsePushData, personColor, resolveAppColor, splitApiKey, subscriptionLevelToName, subscriptionLevels, subscriptionLimits, subscriptionPlans };
+export { APP_COLORS, type ApiErrorBody, type ApiErrorCode, type ApiKeyRecord, type ApiResponse, type AppCreatedRecord, type AppEncryptedKey, type AppKeyUpsertBody, type AppPermission, type AppPersonRecord, type AppRecord, type AppTeamAccess, type Appearance, type AppsQuery, type ClaimantKeyCheck, type ClientToServerEvents, DEFAULT_ACCENT, DEFAULT_PUSH_THRESHOLD, type DeviceLinkApproveBody, type DeviceLinkCreateBody, type DeviceLinkCreatedRecord, type DeviceLinkPlatform, type DeviceLinkRecord, type DeviceLinkStatus, type FlagRecord, type FlagsQuery, type GuestRecord, type HolderKeyCheck, type InvitationRecord, type KeyCheckResult, type KeyHolder, type KeyPin, type LogContext, type LogEncrypted, LogLevel, type LogLevelName, type LogPayload, type LogRecord, type LogTimeseriesQuery, type LogsQuery, type NoteEncrypted, type NoteRecord, type NotesQuery, type NotificationPreference, type NotificationPreferences, PUSH_OFF, type PendingAppKey, type PendingDeviceLink, type PushData, type PushThreshold, type PushToken, type PushType, type ResponseMetadata, type ServerToClientEvents, type SocketAppPayload, SubscriptionLevel, type SubscriptionLevelName, type SubscriptionLimits, type SubscriptionPlan, type SubscriptionPlanRecord, type TeamMemberRecord, type TeamRecord, type TeamsQuery, type TimeseriesBucket, type TimeseriesResponse, type UserRecord, apiErrorCodeOf, apiErrorCodes, isApiErrorCode, isValidAppearance, isValidColor, isValidDeviceLinkStatus, isValidImageUrl, isValidLogLevel, isValidSubscriptionLevel, isValidTeamMemberRole, joinApiKey, logLevelColors, logLevelNameToLevel, logLevelToName, logLevels, nameColor, normalizePushThreshold, parsePushData, personColor, resolveAppColor, splitApiKey, subscriptionLevelToName, subscriptionLevels, subscriptionLimits, subscriptionPlans };

package/dist/index.js

@@ -157,7 +157,7 @@ var resolveAppColor = (name, color) => color && isValidColor(color) ? color : na
 var personColor = (userId) => nameColor(userId);
 var isValidLogLevel = (value) => logLevels.includes(value);
 var isValidSubscriptionLevel = (value) => subscriptionLevels.includes(value);
-var deviceLinkStatuses = ["pending", "approved", "denied"];
+var deviceLinkStatuses = ["pending", "approved", "denied", "failed"];
 var isValidDeviceLinkStatus = (value) => deviceLinkStatuses.includes(value);
 var teamMemberRoles = ["owner", "admin", "member"];
 var isValidTeamMemberRole = (value) => teamMemberRoles.includes(value);
@@ -199,7 +199,8 @@ var parsePushData = (data) => {
     case "note":
       return isId(d.appId) && isId(d.noteId) ? { type: "note", appId: d.appId, noteId: d.noteId } : null;
     case "device_link":
-      return isId(d.deviceLinkId) ? { type: "device_link", deviceLinkId: d.deviceLinkId, deviceName: typeof d.deviceName === "string" ? d.deviceName : "" } : null;
+    case "device_link_answered":
+      return isId(d.deviceLinkId) ? { type: d.type, deviceLinkId: d.deviceLinkId, deviceName: typeof d.deviceName === "string" ? d.deviceName : "" } : null;
     case "key_check":
       return isId(d.checkId) ? { type: "key_check", checkId: d.checkId } : null;
     case "key_waiting":

package/dist/index.mjs

@@ -101,7 +101,7 @@ var resolveAppColor = (name, color) => color && isValidColor(color) ? color : na
 var personColor = (userId) => nameColor(userId);
 var isValidLogLevel = (value) => logLevels.includes(value);
 var isValidSubscriptionLevel = (value) => subscriptionLevels.includes(value);
-var deviceLinkStatuses = ["pending", "approved", "denied"];
+var deviceLinkStatuses = ["pending", "approved", "denied", "failed"];
 var isValidDeviceLinkStatus = (value) => deviceLinkStatuses.includes(value);
 var teamMemberRoles = ["owner", "admin", "member"];
 var isValidTeamMemberRole = (value) => teamMemberRoles.includes(value);
@@ -143,7 +143,8 @@ var parsePushData = (data) => {
     case "note":
       return isId(d.appId) && isId(d.noteId) ? { type: "note", appId: d.appId, noteId: d.noteId } : null;
     case "device_link":
-      return isId(d.deviceLinkId) ? { type: "device_link", deviceLinkId: d.deviceLinkId, deviceName: typeof d.deviceName === "string" ? d.deviceName : "" } : null;
+    case "device_link_answered":
+      return isId(d.deviceLinkId) ? { type: d.type, deviceLinkId: d.deviceLinkId, deviceName: typeof d.deviceName === "string" ? d.deviceName : "" } : null;
     case "key_check":
       return isId(d.checkId) ? { type: "key_check", checkId: d.checkId } : null;
     case "key_waiting":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@infinitetoken/lumber-kit",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Shared TypeScript types and wire format contracts for the Lumber cloud logging suite",
   "keywords": [
     "lumber",