@jwilleke/ngdpbase-types 5.25.0 → 5.27.0

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

@@ -0,0 +1,71 @@
+/**
+ * Writing a zip archive from bytes already in hand (#1387).
+ *
+ * A takeout lands on the owner's laptop or phone, and that decides the format:
+ * iOS, iPadOS, Android, Windows and macOS all open a `.zip` by tapping it,
+ * while `.tar.gz` needs a third-party app on exactly the devices people carry.
+ *
+ * This is the only archive the system writes, and `readZip` below is the only
+ * one it reads: a takeout handed back for import (#1472). The instance backup does not use
+ * one: it carries private files as base64 inside the backup document (#1387),
+ * so there is nothing to unpack on restore.
+ *
+ * Bytes in, one Buffer out: a takeout is decrypted, and nothing decrypted may
+ * be staged on the server's disk, so there is no file for a packer to read.
+ *
+ * Written here rather than taken from a library because the zip container is
+ * small and completely specified, while every candidate library wants to read
+ * from or write to the filesystem. The tests extract each archive with an
+ * independent implementation and compare the bytes, so this is checked against
+ * a real reader rather than against its own assumptions.
+ *
+ * Deliberately NOT implemented: zip64. An archive over 4 GiB, a member over
+ * 4 GiB, or more than 65,535 members is refused with a clear error rather than
+ * written as something an extractor would mis-read. A store that large wants
+ * streaming and zip64 together, which is its own piece of work.
+ */
+/** One file to put in the archive. */
+export type ZipEntry = {
+    /** Path inside the archive, `/`-separated, no leading slash. */
+    path: string;
+    bytes: Buffer;
+    /** Defaults to now. Zip stores 2-second resolution, and nothing before 1980. */
+    mtime?: Date;
+};
+export declare function crc32(buf: Buffer): number;
+/**
+ * A zip archive of the given entries, as one Buffer.
+ *
+ * Entries are deflated when that makes them smaller — markdown compresses well,
+ * and a phone on mobile data is the expected destination — and stored as-is
+ * when it does not, which is the usual outcome for photos and other media.
+ */
+export declare function packZip(entries: readonly ZipEntry[]): Promise<Buffer>;
+/** Limits on what `readZip` will unpack, so an upload cannot exhaust memory. */
+export type ZipReadLimits = {
+    /** Most members accepted. */
+    maxEntries: number;
+    /** Most bytes accepted once everything is inflated. */
+    maxTotalBytes: number;
+};
+/**
+ * The files in a zip archive, as bytes in memory (#1472).
+ *
+ * Read from the central directory, which is the archive's own table of
+ * contents, so a member written with a data descriptor — what a streaming
+ * writer, or an OS re-zipping a folder, produces — is read the same as any
+ * other. Directory entries are dropped, and so is what macOS adds when it
+ * zips a folder (`__MACOSX/`, `.DS_Store`): they are not anyone's data.
+ *
+ * Refused, with an error naming why, rather than read as something else:
+ *
+ *   - a path that would climb out of wherever it is extracted — absolute, or
+ *     holding a `..` segment, with `\` read as the separator it is on Windows;
+ *   - encryption, zip64, split archives, and any method but stored and deflate;
+ *   - a member whose inflated bytes do not match the size or CRC the archive
+ *     declares for it;
+ *   - more members, or more inflated bytes, than `limits` allow. Inflating is
+ *     capped per member at what is left of the budget, so a small archive
+ *     that expands enormously stops at the budget, not at the machine's memory.
+ */
+export declare function readZip(archive: Buffer, limits: ZipReadLimits): ZipEntry[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilleke/ngdpbase-types",
-  "version": "5.25.0",
+  "version": "5.27.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",
@@ -31,6 +31,7 @@
     "node": ">=24.15.0"
   },
   "dependencies": {
+    "@elastic/elasticsearch": "^8.19.2",
     "@jwilleke/oidc-auth-server": "0.4.0",
     "@simplewebauthn/server": "^14.0.3",
     "@types/express": "^5.0.5",
@@ -40,6 +41,7 @@
     "@types/multer": "^2.3.0",
     "@types/node": "^24.19.2",
     "better-sqlite3-multiple-ciphers": "^13.0.3",
+    "dotenv": "^18.0.8",
     "express": "^5.3.0",
     "express-session": "^1.19.0",
     "fs-extra": "^11.4.1",
@@ -50,6 +52,9 @@
     "minimatch": "^10.2.6",
     "minisearch": "7.2.0",
     "multer": "^2.4.0",
+    "rrule-temporal": "2.2.8",
+    "tar": "^7.5.22",
+    "temporal-polyfill": "1.0.6",
     "winston": "^3.17.0"
   }
 }

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

@@ -1,21 +0,0 @@
-/**
- * Who an administrator notification goes to.
- *
- * __An administrator is whoever holds `admin-system`__, asked per user through
- * the policy (#1431 7b) — never a role name. Used by every report that must
- * reach administrators and nobody else: a damaged page (#1431 step 7) and
- * failing outbound email (#1916).
- *
- * An empty answer means "nobody to tell", and the caller must then log only:
- * an empty `targetUsers` list means ALL users in NotificationManager, which
- * would announce an operator problem to every reader.
- *
- * Null when the managers needed to answer are not registered (tests, a
- * half-booted engine) — the caller treats that like "nobody to tell".
- */
-type EngineLike = {
-    getManager: (name: string) => unknown;
-} | null | undefined;
-/** Usernames of every user who holds `admin-system`; null when it cannot be asked. */
-export declare function administratorUsernames(engine: EngineLike): Promise<string[] | null>;
-export {};