skapi-js 2.0.0-rc.6 → 2.0.0-rc.7

package/dist/skapi.d.mts

@@ -133,6 +133,46 @@ type BinaryFile = {
     uploaded: number;
     getFile: (dataType?: 'base64' | 'download' | 'endpoint' | 'blob' | 'text' | 'info', progress?: ProgressCallback) => Promise<Blob | string | void | FileInfo>;
 };
+/**
+ * Per-record encryption outcome. Present ONLY when the record's data went
+ * through the client-side encryption layer, so its absence means the record was
+ * stored in the clear.
+ *
+ * status 'encrypted' means the data in this object was decrypted successfully.
+ * status 'failed' means `data` is null and `reason` says why:
+ *   NO_SESSION_KEY      encryption is locked; call unlockEncryption()
+ *   NOT_A_RECIPIENT     this user has no key wrap on the record
+ *   BAD_KEY             the wrap did not open (wrong or rotated key)
+ *   BINDING_MISMATCH    the envelope does not belong to this record
+ *   CORRUPT             the payload failed its authentication tag
+ *   UNSUPPORTED_VERSION written by a newer SDK
+ *   ENCRYPTION_DISABLED the record is encrypted but this instance is not
+ */
+type RecordEncryptionInfo = {
+    status: 'encrypted' | 'failed';
+    reason?: string;
+    /** user_ids that hold a key wrap on this record. */
+    recipients?: string[];
+};
+/** Options for `new Skapi(..., { encryption })`. */
+type EncryptionOptions = boolean | {
+    /** PBKDF2 iteration count. Default 600000. Minimum 100000. */
+    iterations?: number;
+    /** 'tofu' pins a peer's key on first sight (default). 'strict' requires a prior pin. */
+    trustPolicy?: 'tofu' | 'strict';
+    /** Keep the master key in IndexedDB so a page reload stays unlocked. Default true. */
+    persistDevice?: boolean;
+    /** Refuse to enroll a password shorter than this. Default 0 (no check). */
+    minPasswordLength?: number;
+    /**
+     * Issue a one-time recovery code at enrollment. Default 'code'.
+     * 'none' opts out and accepts that a forgotten password means the user's
+     * encrypted records are permanently unreadable.
+     */
+    recovery?: 'code' | 'none';
+    /** Reserved keyring table name. Default 'skapi__keyring'. */
+    table?: string;
+};
 type RecordData = {
     record_id: string;
     unique_id?: string;
@@ -140,6 +180,8 @@ type RecordData = {
     updated: number;
     uploaded: number;
     referenced_count: number;
+    /** Set only when the record's data passed through the encryption layer. */
+    encrypted?: RecordEncryptionInfo;
     table: {
         name: string;
         /** Number range: 0 ~ 99 */
@@ -586,6 +628,7 @@ type Types_Connection = Connection;
 type Types_ConnectionInfo = ConnectionInfo;
 type Types_DatabaseResponse<T> = DatabaseResponse<T>;
 type Types_DelRecordQuery = DelRecordQuery;
+type Types_EncryptionOptions = EncryptionOptions;
 type Types_FetchOptions = FetchOptions;
 type Types_FileInfo = FileInfo;
 type Types_Form<T> = Form<T>;
@@ -601,6 +644,7 @@ type Types_RTCReceiverParams = RTCReceiverParams;
 type Types_RTCResolved = RTCResolved;
 type Types_RealtimeCallback = RealtimeCallback;
 type Types_RecordData = RecordData;
+type Types_RecordEncryptionInfo = RecordEncryptionInfo;
 type Types_RequestHistory = RequestHistory;
 type Types_Subscription = Subscription;
 type Types_Table = Table;
@@ -611,7 +655,7 @@ type Types_UserProfile = UserProfile;
 type Types_UserPublic = UserPublic;
 type Types_WebSocketMessage = WebSocketMessage;
 declare namespace Types {
-  export type { Types_BinaryFile as BinaryFile, Types_Condition as Condition, Types_Connection as Connection, Types_ConnectionInfo as ConnectionInfo, Types_DatabaseResponse as DatabaseResponse, Types_DelRecordQuery as DelRecordQuery, Types_FetchOptions as FetchOptions, Types_FileInfo as FileInfo, Types_Form as Form, Types_GetRecordQuery as GetRecordQuery, Types_Index as Index, Types_Newsletter as Newsletter, Types_PostRecordConfig as PostRecordConfig, Types_ProgressCallback as ProgressCallback, Types_RTCConnector as RTCConnector, Types_RTCConnectorParams as RTCConnectorParams, Types_RTCEvent as RTCEvent, Types_RTCReceiverParams as RTCReceiverParams, Types_RTCResolved as RTCResolved, Types_RealtimeCallback as RealtimeCallback, Types_RecordData as RecordData, Types_RequestHistory as RequestHistory, Types_Subscription as Subscription, Types_Table as Table, Types_Tag as Tag, Types_UniqueId as UniqueId, Types_UserAttributes as UserAttributes, Types_UserProfile as UserProfile, Types_UserPublic as UserPublic, Types_WebSocketMessage as WebSocketMessage };
+  export type { Types_BinaryFile as BinaryFile, Types_Condition as Condition, Types_Connection as Connection, Types_ConnectionInfo as ConnectionInfo, Types_DatabaseResponse as DatabaseResponse, Types_DelRecordQuery as DelRecordQuery, Types_EncryptionOptions as EncryptionOptions, Types_FetchOptions as FetchOptions, Types_FileInfo as FileInfo, Types_Form as Form, Types_GetRecordQuery as GetRecordQuery, Types_Index as Index, Types_Newsletter as Newsletter, Types_PostRecordConfig as PostRecordConfig, Types_ProgressCallback as ProgressCallback, Types_RTCConnector as RTCConnector, Types_RTCConnectorParams as RTCConnectorParams, Types_RTCEvent as RTCEvent, Types_RTCReceiverParams as RTCReceiverParams, Types_RTCResolved as RTCResolved, Types_RealtimeCallback as RealtimeCallback, Types_RecordData as RecordData, Types_RecordEncryptionInfo as RecordEncryptionInfo, Types_RequestHistory as RequestHistory, Types_Subscription as Subscription, Types_Table as Table, Types_Tag as Tag, Types_UniqueId as UniqueId, Types_UserAttributes as UserAttributes, Types_UserProfile as UserProfile, Types_UserPublic as UserPublic, Types_WebSocketMessage as WebSocketMessage };
 }
 
 declare function terminatePendingRequests(): void;
@@ -654,6 +698,18 @@ type Options = {
     autoLogin: boolean;
     refetchServiceInfo?: boolean;
     requestBatchSize?: number;
+    /**
+     * Enable client-side encryption of `data` on records written to
+     * access_group 'private'. Off by default. See EncryptionOptions.
+     */
+    encryption?: boolean | {
+        iterations?: number;
+        trustPolicy?: 'tofu' | 'strict';
+        persistDevice?: boolean;
+        minPasswordLength?: number;
+        recovery?: 'code' | 'none';
+        table?: string;
+    };
     eventListener?: {
         onLogin?: (user: UserProfile | null) => void;
         onUserUpdate?: (user: UserProfile | null) => void;
@@ -1487,6 +1543,105 @@ declare class Skapi {
         /** username(e-mail) user wish to change to. */
         username: string;
     }): Promise<'SUCCESS: confirmation e-mail has been sent.'>;
+    /**
+     * Reports whether client-side record encryption is on, and whether it is
+     * currently unlocked.
+     * @returns { status: 'disabled' | 'locked' | 'unlocked', reason?, user_id?, fingerprint? }
+     */
+    getEncryptionStatus(): {
+        status: string;
+        reason?: string;
+        user_id?: string;
+        fingerprint?: string;
+    };
+    /**
+     * True when a record's `data` is the placeholder returned in place of
+     * content this session cannot decrypt.
+     *
+     * Only relevant with `encryption: { withheld: 'sentinel' }`. Under the
+     * default, withheld data is `null` and an ordinary falsy check is enough.
+     * @param data The value of `record.data`.
+     * @returns boolean
+     */
+    isWithheld(data: any): boolean;
+    /**
+     * Unlocks record encryption with the user's password.
+     *
+     * Normally unnecessary: logging in unlocks automatically, and a page reload
+     * unlocks from the device store. This is for a session restored from a token
+     * on a device that has never been unlocked, and for Node, which has no
+     * IndexedDB and is therefore always locked after a token restore.
+     * @param params Request parameters.
+     * @returns A promise that resolves to Promise<{ status: string }>.
+     */
+    unlockEncryption(params: {
+        password: string;
+    }): Promise<{
+        status: string;
+    }>;
+    /**
+     * Drops encryption keys from memory without logging out. Pass
+     * { forgetDevice: true } to also clear the device store, which means the
+     * next reload will require the password again.
+     * @param params Request parameters.
+     * @returns A promise that resolves to Promise<{ status: string }>.
+     */
+    lockEncryption(params?: {
+        forgetDevice?: boolean;
+    }): Promise<{
+        status: string;
+    }>;
+    /**
+     * Collects a freshly minted recovery code, ONCE.
+     *
+     * Call it right after a login or signup that may have enrolled the user; it
+     * returns the code and forgets it. There is no way to fetch it again later,
+     * and that is the point: if the SDK could hand it back on demand it would be
+     * holding the key, and so could the service provider. Show it, make the user
+     * confirm they saved it, and never send it anywhere.
+     * @returns The code, or null if nothing was enrolled.
+     */
+    takeRecoveryCode(): string | null;
+    /**
+     * Unlocks with a recovery code after a forgotten-password reset, and repairs
+     * the keyring for the new password.
+     *
+     * The order is: reset the password, log in with the new one (encryption will
+     * report 'locked'), then call this with the code and that new password. A
+     * used code is retired and a replacement is returned.
+     * @param params Request parameters.
+     * @returns A promise that resolves to Promise<{ status, repaired, recoveryCode }>.
+     */
+    unlockWithRecoveryCode(params: {
+        code: string;
+        password?: string;
+    }): Promise<{
+        status: string;
+        repaired: boolean;
+        recoveryCode: string | null;
+    }>;
+    /**
+     * Retires the current recovery code and issues a new one. Requires an
+     * unlocked session: only someone who can already decrypt can mint a code.
+     * @returns A promise that resolves to Promise<{ recoveryCode: string }>.
+     */
+    regenerateRecoveryCode(): Promise<{
+        recoveryCode: string;
+    }>;
+    /**
+     * Pins another user's public key fingerprint after verifying it out of band.
+     *
+     * Only needed when a peer's key has changed, or when trustPolicy is
+     * 'strict'. The provider serves the key directory, so a changed key is both
+     * what a legitimate account reset looks like and what a key substitution
+     * attack looks like: the SDK refuses to guess.
+     * @param params Request parameters.
+     * @returns A promise that resolves to Promise<void>.
+     */
+    pinPeerKey(params: {
+        user_id: string;
+        fingerprint: string;
+    }): Promise<void>;
     /**
      * Grants users access to a private record.
      * @param params Request parameters.

package/dist/skapi.d.ts

@@ -133,6 +133,46 @@ type BinaryFile = {
     uploaded: number;
     getFile: (dataType?: 'base64' | 'download' | 'endpoint' | 'blob' | 'text' | 'info', progress?: ProgressCallback) => Promise<Blob | string | void | FileInfo>;
 };
+/**
+ * Per-record encryption outcome. Present ONLY when the record's data went
+ * through the client-side encryption layer, so its absence means the record was
+ * stored in the clear.
+ *
+ * status 'encrypted' means the data in this object was decrypted successfully.
+ * status 'failed' means `data` is null and `reason` says why:
+ *   NO_SESSION_KEY      encryption is locked; call unlockEncryption()
+ *   NOT_A_RECIPIENT     this user has no key wrap on the record
+ *   BAD_KEY             the wrap did not open (wrong or rotated key)
+ *   BINDING_MISMATCH    the envelope does not belong to this record
+ *   CORRUPT             the payload failed its authentication tag
+ *   UNSUPPORTED_VERSION written by a newer SDK
+ *   ENCRYPTION_DISABLED the record is encrypted but this instance is not
+ */
+type RecordEncryptionInfo = {
+    status: 'encrypted' | 'failed';
+    reason?: string;
+    /** user_ids that hold a key wrap on this record. */
+    recipients?: string[];
+};
+/** Options for `new Skapi(..., { encryption })`. */
+type EncryptionOptions = boolean | {
+    /** PBKDF2 iteration count. Default 600000. Minimum 100000. */
+    iterations?: number;
+    /** 'tofu' pins a peer's key on first sight (default). 'strict' requires a prior pin. */
+    trustPolicy?: 'tofu' | 'strict';
+    /** Keep the master key in IndexedDB so a page reload stays unlocked. Default true. */
+    persistDevice?: boolean;
+    /** Refuse to enroll a password shorter than this. Default 0 (no check). */
+    minPasswordLength?: number;
+    /**
+     * Issue a one-time recovery code at enrollment. Default 'code'.
+     * 'none' opts out and accepts that a forgotten password means the user's
+     * encrypted records are permanently unreadable.
+     */
+    recovery?: 'code' | 'none';
+    /** Reserved keyring table name. Default 'skapi__keyring'. */
+    table?: string;
+};
 type RecordData = {
     record_id: string;
     unique_id?: string;
@@ -140,6 +180,8 @@ type RecordData = {
     updated: number;
     uploaded: number;
     referenced_count: number;
+    /** Set only when the record's data passed through the encryption layer. */
+    encrypted?: RecordEncryptionInfo;
     table: {
         name: string;
         /** Number range: 0 ~ 99 */
@@ -586,6 +628,7 @@ type Types_Connection = Connection;
 type Types_ConnectionInfo = ConnectionInfo;
 type Types_DatabaseResponse<T> = DatabaseResponse<T>;
 type Types_DelRecordQuery = DelRecordQuery;
+type Types_EncryptionOptions = EncryptionOptions;
 type Types_FetchOptions = FetchOptions;
 type Types_FileInfo = FileInfo;
 type Types_Form<T> = Form<T>;
@@ -601,6 +644,7 @@ type Types_RTCReceiverParams = RTCReceiverParams;
 type Types_RTCResolved = RTCResolved;
 type Types_RealtimeCallback = RealtimeCallback;
 type Types_RecordData = RecordData;
+type Types_RecordEncryptionInfo = RecordEncryptionInfo;
 type Types_RequestHistory = RequestHistory;
 type Types_Subscription = Subscription;
 type Types_Table = Table;
@@ -611,7 +655,7 @@ type Types_UserProfile = UserProfile;
 type Types_UserPublic = UserPublic;
 type Types_WebSocketMessage = WebSocketMessage;
 declare namespace Types {
-  export type { Types_BinaryFile as BinaryFile, Types_Condition as Condition, Types_Connection as Connection, Types_ConnectionInfo as ConnectionInfo, Types_DatabaseResponse as DatabaseResponse, Types_DelRecordQuery as DelRecordQuery, Types_FetchOptions as FetchOptions, Types_FileInfo as FileInfo, Types_Form as Form, Types_GetRecordQuery as GetRecordQuery, Types_Index as Index, Types_Newsletter as Newsletter, Types_PostRecordConfig as PostRecordConfig, Types_ProgressCallback as ProgressCallback, Types_RTCConnector as RTCConnector, Types_RTCConnectorParams as RTCConnectorParams, Types_RTCEvent as RTCEvent, Types_RTCReceiverParams as RTCReceiverParams, Types_RTCResolved as RTCResolved, Types_RealtimeCallback as RealtimeCallback, Types_RecordData as RecordData, Types_RequestHistory as RequestHistory, Types_Subscription as Subscription, Types_Table as Table, Types_Tag as Tag, Types_UniqueId as UniqueId, Types_UserAttributes as UserAttributes, Types_UserProfile as UserProfile, Types_UserPublic as UserPublic, Types_WebSocketMessage as WebSocketMessage };
+  export type { Types_BinaryFile as BinaryFile, Types_Condition as Condition, Types_Connection as Connection, Types_ConnectionInfo as ConnectionInfo, Types_DatabaseResponse as DatabaseResponse, Types_DelRecordQuery as DelRecordQuery, Types_EncryptionOptions as EncryptionOptions, Types_FetchOptions as FetchOptions, Types_FileInfo as FileInfo, Types_Form as Form, Types_GetRecordQuery as GetRecordQuery, Types_Index as Index, Types_Newsletter as Newsletter, Types_PostRecordConfig as PostRecordConfig, Types_ProgressCallback as ProgressCallback, Types_RTCConnector as RTCConnector, Types_RTCConnectorParams as RTCConnectorParams, Types_RTCEvent as RTCEvent, Types_RTCReceiverParams as RTCReceiverParams, Types_RTCResolved as RTCResolved, Types_RealtimeCallback as RealtimeCallback, Types_RecordData as RecordData, Types_RecordEncryptionInfo as RecordEncryptionInfo, Types_RequestHistory as RequestHistory, Types_Subscription as Subscription, Types_Table as Table, Types_Tag as Tag, Types_UniqueId as UniqueId, Types_UserAttributes as UserAttributes, Types_UserProfile as UserProfile, Types_UserPublic as UserPublic, Types_WebSocketMessage as WebSocketMessage };
 }
 
 declare function terminatePendingRequests(): void;
@@ -654,6 +698,18 @@ type Options = {
     autoLogin: boolean;
     refetchServiceInfo?: boolean;
     requestBatchSize?: number;
+    /**
+     * Enable client-side encryption of `data` on records written to
+     * access_group 'private'. Off by default. See EncryptionOptions.
+     */
+    encryption?: boolean | {
+        iterations?: number;
+        trustPolicy?: 'tofu' | 'strict';
+        persistDevice?: boolean;
+        minPasswordLength?: number;
+        recovery?: 'code' | 'none';
+        table?: string;
+    };
     eventListener?: {
         onLogin?: (user: UserProfile | null) => void;
         onUserUpdate?: (user: UserProfile | null) => void;
@@ -1487,6 +1543,105 @@ declare class Skapi {
         /** username(e-mail) user wish to change to. */
         username: string;
     }): Promise<'SUCCESS: confirmation e-mail has been sent.'>;
+    /**
+     * Reports whether client-side record encryption is on, and whether it is
+     * currently unlocked.
+     * @returns { status: 'disabled' | 'locked' | 'unlocked', reason?, user_id?, fingerprint? }
+     */
+    getEncryptionStatus(): {
+        status: string;
+        reason?: string;
+        user_id?: string;
+        fingerprint?: string;
+    };
+    /**
+     * True when a record's `data` is the placeholder returned in place of
+     * content this session cannot decrypt.
+     *
+     * Only relevant with `encryption: { withheld: 'sentinel' }`. Under the
+     * default, withheld data is `null` and an ordinary falsy check is enough.
+     * @param data The value of `record.data`.
+     * @returns boolean
+     */
+    isWithheld(data: any): boolean;
+    /**
+     * Unlocks record encryption with the user's password.
+     *
+     * Normally unnecessary: logging in unlocks automatically, and a page reload
+     * unlocks from the device store. This is for a session restored from a token
+     * on a device that has never been unlocked, and for Node, which has no
+     * IndexedDB and is therefore always locked after a token restore.
+     * @param params Request parameters.
+     * @returns A promise that resolves to Promise<{ status: string }>.
+     */
+    unlockEncryption(params: {
+        password: string;
+    }): Promise<{
+        status: string;
+    }>;
+    /**
+     * Drops encryption keys from memory without logging out. Pass
+     * { forgetDevice: true } to also clear the device store, which means the
+     * next reload will require the password again.
+     * @param params Request parameters.
+     * @returns A promise that resolves to Promise<{ status: string }>.
+     */
+    lockEncryption(params?: {
+        forgetDevice?: boolean;
+    }): Promise<{
+        status: string;
+    }>;
+    /**
+     * Collects a freshly minted recovery code, ONCE.
+     *
+     * Call it right after a login or signup that may have enrolled the user; it
+     * returns the code and forgets it. There is no way to fetch it again later,
+     * and that is the point: if the SDK could hand it back on demand it would be
+     * holding the key, and so could the service provider. Show it, make the user
+     * confirm they saved it, and never send it anywhere.
+     * @returns The code, or null if nothing was enrolled.
+     */
+    takeRecoveryCode(): string | null;
+    /**
+     * Unlocks with a recovery code after a forgotten-password reset, and repairs
+     * the keyring for the new password.
+     *
+     * The order is: reset the password, log in with the new one (encryption will
+     * report 'locked'), then call this with the code and that new password. A
+     * used code is retired and a replacement is returned.
+     * @param params Request parameters.
+     * @returns A promise that resolves to Promise<{ status, repaired, recoveryCode }>.
+     */
+    unlockWithRecoveryCode(params: {
+        code: string;
+        password?: string;
+    }): Promise<{
+        status: string;
+        repaired: boolean;
+        recoveryCode: string | null;
+    }>;
+    /**
+     * Retires the current recovery code and issues a new one. Requires an
+     * unlocked session: only someone who can already decrypt can mint a code.
+     * @returns A promise that resolves to Promise<{ recoveryCode: string }>.
+     */
+    regenerateRecoveryCode(): Promise<{
+        recoveryCode: string;
+    }>;
+    /**
+     * Pins another user's public key fingerprint after verifying it out of band.
+     *
+     * Only needed when a peer's key has changed, or when trustPolicy is
+     * 'strict'. The provider serves the key directory, so a changed key is both
+     * what a legitimate account reset looks like and what a key substitution
+     * attack looks like: the SDK refuses to guess.
+     * @param params Request parameters.
+     * @returns A promise that resolves to Promise<void>.
+     */
+    pinPeerKey(params: {
+        user_id: string;
+        fingerprint: string;
+    }): Promise<void>;
     /**
      * Grants users access to a private record.
      * @param params Request parameters.