@jwilleke/ngdpbase-types 5.37.0 → 5.39.0

package/lib/src/utils/privateStoreUnlock.d.ts

@@ -52,6 +52,8 @@ export declare function unlockPrivateStoresWithMnemonic(args: {
 }): Promise<boolean>;
 /** Whether `username` has keys at all, i.e. a store that can be encrypted. */
 export declare function hasUserKeys(pagesDirectory: string, username: string): Promise<boolean>;
+/** Which set of recovery words `username` has (#1928, `recoveryWordsId`), or null when they have no keys. */
+export declare function recoveryWordsIdOf(pagesDirectory: string, username: string): Promise<string | null>;
 /**
  * The public half of `username`'s key pair (#1762 slice 5), or null when they
  * have no keys or no pair yet. Public: anyone may seal to it.

package/lib/src/utils/shareLockbox.d.ts

@@ -11,7 +11,7 @@
  * recipient's browser opens each lockbox with the private key from the link.
  *
  * The algorithm is WebCrypto's own, so the server (Node's `crypto.webcrypto`)
- * and the browser (`window.crypto.subtle`, public/js/share-viewer.js) run the
+ * and the browser (`window.crypto.subtle`, public/share/_assets/share-viewer.js) run the
  * same steps: ECDH on P-256 between a fresh ephemeral key and the link's key,
  * HKDF-SHA-256 over the shared secret, AES-256-GCM over the content.
  */

package/lib/src/utils/sharedFoldersKey.d.ts

@@ -0,0 +1,17 @@
+/** The environment variable holding the shared-folders key. Never a config key: config is readable from the admin screens. */
+export declare const SHARED_FOLDERS_KEY_ENV = "NGDPBASE_SHARED_FOLDERS_KEY";
+/** The shared-folders key as set now, trimmed; '' when there is none. Never logged. */
+export declare function currentSharedFoldersKey(): string;
+/**
+ * A short fingerprint of the shared-folders key: the first 16 hex digits of an
+ * HMAC of a fixed label under the key, as for the backup key. Shown on Admin →
+ * Backup and recorded with the wrapped folder keys, so a different key says so
+ * plainly; it never reveals the key.
+ */
+export declare function sharedFoldersKeyFingerprint(key: string): string;
+/**
+ * The 32-byte key the folder keys are wrapped under, derived from the `.env`
+ * value (HKDF-SHA256, one HMAC round: cheap, never a stall). Derived, not
+ * decoded, so a value an operator set themselves in any form still works.
+ */
+export declare function sharedFoldersWrapKey(key: string): Buffer;

package/lib/src/utils/sharedFoldersKey.js

@@ -0,0 +1,33 @@
+/**
+ * The shared-folders key (#2124, epic #1775 decision 1): the organization's
+ * server-held key, `NGDPBASE_SHARED_FOLDERS_KEY`, in the instance `.env`
+ * beside the backup, database and credentials keys. Generated on first start
+ * (`bootstrap-env.ts`), read at startup by SharedFolderManager, which wraps
+ * every shared folder's own key under it. One declaration here, with no
+ * dependencies, so the boot can name it without loading the manager, and
+ * BackupManager can fingerprint it for the "saved off the server" check.
+ */
+import { createHmac, hkdfSync } from 'node:crypto';
+/** The environment variable holding the shared-folders key. Never a config key: config is readable from the admin screens. */
+export const SHARED_FOLDERS_KEY_ENV = 'NGDPBASE_SHARED_FOLDERS_KEY';
+/** The shared-folders key as set now, trimmed; '' when there is none. Never logged. */
+export function currentSharedFoldersKey() {
+    return (process.env[SHARED_FOLDERS_KEY_ENV] ?? '').trim();
+}
+/**
+ * A short fingerprint of the shared-folders key: the first 16 hex digits of an
+ * HMAC of a fixed label under the key, as for the backup key. Shown on Admin →
+ * Backup and recorded with the wrapped folder keys, so a different key says so
+ * plainly; it never reveals the key.
+ */
+export function sharedFoldersKeyFingerprint(key) {
+    return createHmac('sha256', key).update('ngdpbase shared folders key fingerprint v1').digest('hex').slice(0, 16);
+}
+/**
+ * The 32-byte key the folder keys are wrapped under, derived from the `.env`
+ * value (HKDF-SHA256, one HMAC round: cheap, never a stall). Derived, not
+ * decoded, so a value an operator set themselves in any form still works.
+ */
+export function sharedFoldersWrapKey(key) {
+    return Buffer.from(hkdfSync('sha256', key, Buffer.alloc(0), 'ngdpbase shared folders wrap key v1', 32));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilleke/ngdpbase-types",
-  "version": "5.37.0",
+  "version": "5.39.0",
   "description": "TypeScript types for ngdpbase add-ons, and a test kit of core's own values. A dev dependency, versioned with ngdpbase.",
   "license": "Apache-2.0",
   "author": "Jim Willeke",
@@ -44,6 +44,7 @@
     "dotenv": "^18.0.9",
     "express": "^5.3.0",
     "express-session": "^1.19.0",
+    "fast-xml-parser": "^5.11.2",
     "fs-extra": "^11.4.1",
     "ipaddr.js": "^2.5.0",
     "jose": "^6.2.13",