@jwilleke/ngdpbase-types 5.26.0 → 5.28.0

package/lib/src/utils/privateStoreAccess.js

@@ -25,7 +25,6 @@
  * slice 4).
  */
 import { isJobContext } from '../context/ActorContext.js';
-import { toPermissionSubject } from '../context/JobContext.js';
 import { shareNamesVault } from '../types/Share.js';
 import { mixesProxyWithDelegation, proxyCarries } from './proxyClaim.js';
 export function mayActInPrivateContainer(ctx, owner, opts = {}) {
@@ -60,6 +59,5 @@ export function mayActInPrivateContainer(ctx, owner, opts = {}) {
 export async function permitsInVault(pdp, ctx, action, where) {
     if (!pdp || !mayActInPrivateContainer(ctx, where.owner, { vault: where.vault }))
         return false;
-    const subject = isJobContext(ctx) ? toPermissionSubject(ctx) : ctx;
-    return (await pdp.decide(subject, { action, resource: { type: 'page', id: where.resource }, attributes: { vault: where.vault } })).permit;
+    return (await pdp.decide(ctx, { action, resource: { type: 'page', id: where.resource }, attributes: { vault: where.vault } })).permit;
 }

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

@@ -0,0 +1,58 @@
+/**
+ * Reading a takeout handed back for import (#1472) — the mirror of
+ * `privateStoreExport.ts`.
+ *
+ * Pure: entries in, a description of what they hold out. No I/O, no access
+ * decision, no write. The door that acts on it is
+ * `ImportManager.importOwnStoreTakeout`.
+ *
+ * What a takeout is, as #1387 writes it: one `{store}/` folder holding each
+ * page as `{title}.md` with full frontmatter, files under `attachments/`, and
+ * `files-index.json` mapping each file's id to its path in the archive. The
+ * reader is lenient about the one thing people change — the folder. Someone
+ * who extracts a takeout and zips it again may add a level, or zip the
+ * contents with no folder at all, so the takeout's root is found rather than
+ * assumed.
+ */
+import type { ZipEntry } from './zipArchive.js';
+/** One page of a takeout. */
+export type TakeoutPage = {
+    /** Where it was in the archive — how the report names a page that failed. */
+    archivePath: string;
+    /** From the frontmatter, else the file's name. */
+    title: string;
+    /** From the frontmatter. Absent for a page written by hand. */
+    uuid?: string;
+    /** The frontmatter, as written. */
+    metadata: Record<string, unknown>;
+    body: string;
+};
+/** One file of a takeout. */
+export type TakeoutFile = {
+    archivePath: string;
+    /** Its id where it came from, when the file index names it. */
+    oldId?: string;
+    /** The name it was uploaded with. */
+    name: string;
+    encodingFormat?: string;
+    description?: string;
+    bytes: Buffer;
+};
+export type ParsedTakeout = {
+    pages: TakeoutPage[];
+    files: TakeoutFile[];
+    /** Archive members that are neither a page nor a file, left alone. */
+    ignored: string[];
+};
+/** What a takeout's entries hold. */
+export declare function readTakeout(entries: readonly ZipEntry[]): ParsedTakeout;
+/** `body` with every `/attachments/{old}` link pointed at its new id. */
+export declare function rewriteAttachmentLinks(body: string, ids: ReadonlyMap<string, string>): string;
+/** Whether `body` links to the file `id`. */
+export declare function linksToAttachment(body: string, id: string): boolean;
+/**
+ * The first free title of `title`, `title (imported)`, `title (imported 2)` …
+ * (operator, 2026-09-25): a DIFFERENT page already holding the title keeps it,
+ * and the import lands beside it.
+ */
+export declare function freeImportTitle(title: string, isTaken: (candidate: string) => Promise<boolean>): Promise<string>;

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

@@ -0,0 +1,25 @@
+/**
+ * A role change that did not happen (#2015).
+ *
+ * Operator, 2026-10-23: adding or removing a role completes or it does not
+ * happen, everywhere, and one that cannot be made is always an error. So a
+ * request that asks for several role changes either gets all of them or none:
+ * RoleManager undoes the ones that landed before the failure, then throws
+ * this, and the request that asked fails with it.
+ *
+ * The message is shown to whoever asked (an administrator's form). It names
+ * the account, the change that failed and, when it is something an
+ * administrator can fix, the reason (no Person record, no anchor
+ * Organization). Storage detail (paths, errno) stays in `cause`, for the log.
+ */
+export declare class RoleChangeError extends Error {
+    /** The change that could not be made, as `add <role>` / `remove <role>`. */
+    readonly failed: readonly string[];
+    /** Changes that landed, could not be undone, and so are still in effect. Empty when nothing was left changed. */
+    readonly notUndone: readonly string[];
+    constructor(subject: string, failed: readonly string[], options?: {
+        reason?: string;
+        cause?: unknown;
+        notUndone?: readonly string[];
+    });
+}

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

@@ -12,10 +12,10 @@
  * had somewhere to go that is not a second evaluator: a role name skips
  * PolicyEvaluator, deny policies and the token ceiling; this does not.
  */
-import type { PermissionSubject } from '../managers/UserManager.js';
+import type { ActorContext } from '../context/ActorContext.js';
 import type { CorePermission } from '../security/permissions.generated.js';
 type EngineLike = {
     getManager: (name: string) => unknown;
 } | null | undefined;
-export declare function subjectMayDo(engine: EngineLike, subject: PermissionSubject | null | undefined, action: CorePermission): Promise<boolean>;
+export declare function subjectMayDo(engine: EngineLike, subject: ActorContext | null | undefined, action: CorePermission): Promise<boolean>;
 export {};

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.26.0",
+  "version": "5.28.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",