@jwilleke/ngdpbase-types 5.39.0 → 5.41.0

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

@@ -0,0 +1,57 @@
+/**
+ * Who may act in a shared folder, and how its key reaches the store I/O
+ * (#1775, #2125; docs/planning/shared-folders.md, "Access is by permission").
+ *
+ * A shared folder is the container `SHARED_FOLDER_OWNER`'s vault
+ * (`utils/privateStorePath.ts`), so the page and file doors reach it as they
+ * reach any vault. Two things differ, and both are here:
+ *
+ * - __Who may act__: never the vault owner rule (`mayActInPrivateContainer`
+ *   refuses everyone for this container). Every read asks `shared-folder-read`
+ *   and every add, edit or delete asks `shared-folder-file`, of the PDP, with
+ *   the caller's context and the folder as the policy resource
+ *   (`shared-folder`, `shared/{folder}`). A folder lists no roles. A share link
+ *   never gets in, and asks nothing (no share links into folders).
+ * - __The key__: the server holds every folder's key (SharedFolderManager,
+ *   decision 1). It reaches `dekFor` only for a context the PDP has just
+ *   permitted on that folder, remembered against that context object
+ *   ({@link openedFor}). A request's subject is built afresh for every
+ *   request, so a grant removed ends access on the next request (decision 5);
+ *   a context nothing asked about — a boot job, a link, another request — gets
+ *   no key, and a sealed folder reads as nothing to it.
+ *
+ * Nothing here decides an allow or a deny itself: the PDP does (P2).
+ */
+import type { ActorContext } from '../context/ActorContext.js';
+import type { VaultDecider } from './privateStoreAccess.js';
+/** Open a shared folder: its pages, their history and its files. */
+export declare const SHARED_FOLDER_READ = "shared-folder-read";
+/** Add, edit and delete a shared folder's pages and files. */
+export declare const SHARED_FOLDER_FILE = "shared-folder-file";
+/** The policy resource type a folder is named by (`ngdpbase.access.resource-types`). */
+export declare const SHARED_FOLDER_RESOURCE_TYPE = "shared-folder";
+/** The policy resource of folder `folder`: `shared/{folder}`, as a policy's pattern names it. */
+export declare function sharedFolderResource(folder: string): string;
+/**
+ * The folder permission an action on a folder's page or file asks:
+ * `shared-folder-read` for a read, `shared-folder-file` for a write, and null
+ * for anything else — sharing it by link, exporting it, raw edits — which is
+ * refused in a folder.
+ */
+export declare function sharedFolderPermissionFor(action: string): string | null;
+/**
+ * May `ctx` do `action` in shared folder `folder`? The PDP decides
+ * `shared-folder-read` or `shared-folder-file` ({@link sharedFolderPermissionFor})
+ * with the folder as the resource. A share link is refused without asking. A
+ * permit opens the folder's key to this context ({@link openedFor}).
+ */
+export declare function permitsInSharedFolder(pdp: VaultDecider | null | undefined, ctx: ActorContext, action: string, folder: string): Promise<boolean>;
+/** Whether the PDP permitted `ctx` on `folder` (read or file): what hands it the folder's key. */
+export declare function openedFor(ctx: ActorContext | undefined, folder: string): boolean;
+/** SharedFolderManager's folder keys, unwrapped with the server key; null to stop handing them out. */
+export declare function setSharedFolderKeySource(source: ((folder: string) => Buffer | undefined) | null): void;
+/**
+ * Folder `folder`'s key for `ctx`, for the store I/O (`dekFor`): only when
+ * the PDP permitted this context on the folder. A copy; the caller may zero it.
+ */
+export declare function sharedFolderKeyFor(ctx: ActorContext | undefined, folder: string): Buffer | undefined;

package/lib/src/utils/sharedFolderAccess.js

@@ -0,0 +1,80 @@
+import { permissionForPageAction } from '../security/pageActions.js';
+import { isValidStoreId, SHARED_URL_SEGMENT } from './privateStorePath.js';
+/** Open a shared folder: its pages, their history and its files. */
+export const SHARED_FOLDER_READ = 'shared-folder-read';
+/** Add, edit and delete a shared folder's pages and files. */
+export const SHARED_FOLDER_FILE = 'shared-folder-file';
+/** The policy resource type a folder is named by (`ngdpbase.access.resource-types`). */
+export const SHARED_FOLDER_RESOURCE_TYPE = 'shared-folder';
+/** The policy resource of folder `folder`: `shared/{folder}`, as a policy's pattern names it. */
+export function sharedFolderResource(folder) {
+    return `${SHARED_URL_SEGMENT}/${folder}`;
+}
+/** What reads a folder: a page, its history, a file. */
+const READS = new Set(['page-read', 'asset-read', 'media-read', 'history', 'diff', SHARED_FOLDER_READ]);
+/** What writes one: a page or a file added, changed or removed. */
+const WRITES = new Set(['page-create', 'page-edit', 'page-rename', 'page-delete', 'save', 'asset-upload', 'asset-edit', 'asset-delete', SHARED_FOLDER_FILE]);
+/**
+ * The folder permission an action on a folder's page or file asks:
+ * `shared-folder-read` for a read, `shared-folder-file` for a write, and null
+ * for anything else — sharing it by link, exporting it, raw edits — which is
+ * refused in a folder.
+ */
+export function sharedFolderPermissionFor(action) {
+    const asked = permissionForPageAction(action);
+    if (READS.has(asked))
+        return SHARED_FOLDER_READ;
+    if (WRITES.has(asked))
+        return SHARED_FOLDER_FILE;
+    return null;
+}
+/** Which folders each context was permitted on, by the context object: one request's subject. */
+const opened = new WeakMap();
+/**
+ * May `ctx` do `action` in shared folder `folder`? The PDP decides
+ * `shared-folder-read` or `shared-folder-file` ({@link sharedFolderPermissionFor})
+ * with the folder as the resource. A share link is refused without asking. A
+ * permit opens the folder's key to this context ({@link openedFor}).
+ */
+export async function permitsInSharedFolder(pdp, ctx, action, folder) {
+    const permission = sharedFolderPermissionFor(action);
+    if (!pdp || !ctx || typeof ctx !== 'object' || !permission || !isValidStoreId(folder))
+        return false;
+    if ('viaShare' in ctx && ctx.viaShare)
+        return false;
+    const resource = sharedFolderResource(folder);
+    const { permit } = await pdp.decide(ctx, {
+        action: permission,
+        resource: { type: SHARED_FOLDER_RESOURCE_TYPE, id: resource },
+        attributes: { [SHARED_FOLDER_RESOURCE_TYPE]: resource }
+    });
+    if (permit) {
+        const folders = opened.get(ctx) ?? new Set();
+        folders.add(folder);
+        opened.set(ctx, folders);
+    }
+    return permit;
+}
+/** Whether the PDP permitted `ctx` on `folder` (read or file): what hands it the folder's key. */
+export function openedFor(ctx, folder) {
+    if (!ctx || typeof ctx !== 'object')
+        return false;
+    if ('viaShare' in ctx && ctx.viaShare)
+        return false;
+    return opened.get(ctx)?.has(folder) === true;
+}
+/** Where folder keys come from: SharedFolderManager, which sets it at start. */
+let keySource = null;
+/** SharedFolderManager's folder keys, unwrapped with the server key; null to stop handing them out. */
+export function setSharedFolderKeySource(source) {
+    keySource = source;
+}
+/**
+ * Folder `folder`'s key for `ctx`, for the store I/O (`dekFor`): only when
+ * the PDP permitted this context on the folder. A copy; the caller may zero it.
+ */
+export function sharedFolderKeyFor(ctx, folder) {
+    if (!keySource || !openedFor(ctx, folder))
+        return undefined;
+    return keySource(folder);
+}

package/lib/src/utils/userCreateError.js

@@ -0,0 +1,82 @@
+/**
+ * Typed user-creation failures and the safe messages registration may show (#1086).
+ *
+ * `POST /register` used to disclose every username on the instance to an
+ * unauthenticated visitor. Two independent defects produced that:
+ *
+ * 1. `UserManager.createUser` built its duplicate-username error by joining
+ *    `getAllUsernames()` into the message.
+ * 2. `processRegister` forwarded `getErrorMessage(err)` straight into a
+ *    redirect, which the register page rendered.
+ *
+ * The second is the one that matters. Fixing only the message would leave the
+ * route one internal `throw` away from the same exposure, because it treats
+ * arbitrary exception text as user-facing copy — and every layer beneath it
+ * can throw.
+ *
+ * So failures now carry a machine-readable `reason`, and the route maps that to
+ * a small closed set of messages. Anything unrecognised — a disk error, a
+ * provider bug, a future exception nobody anticipated — becomes the generic
+ * failure. That default is what makes this hold for errors that do not exist
+ * yet.
+ *
+ * The codebase is careful about this elsewhere, which is what made the
+ * registration path look like an oversight rather than a policy: login returns
+ * a uniform "Invalid username or password", `requestMagicLink` always redirects
+ * with `magic=sent` whether or not the address exists, and agent-token revoke
+ * returns 404 rather than 403 to avoid confirming that a token exists.
+ */
+/**
+ * A user-creation failure with a reason a caller can branch on.
+ *
+ * The `message` is for logs and may contain internal detail; it must never be
+ * shown to a caller. `safeRegistrationMessage` is the only thing that decides
+ * what a visitor sees.
+ */
+export class UserCreateError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.name = 'UserCreateError';
+        this.reason = reason;
+    }
+}
+/** Shown when the cause is unknown, or known but not safe to describe. */
+export const GENERIC_REGISTRATION_FAILURE = 'Registration failed. Please try again.';
+/**
+ * Messages registration may show, keyed by reason.
+ *
+ * Both reveal only what registration structurally cannot hide — that *this*
+ * value is unavailable, which the visitor must be told in order to pick
+ * another. Neither reveals anything about what else exists.
+ *
+ * `display-name-conflict` is deliberately vague about the cause: internally it
+ * means the name collides with an existing page, and saying so would tell an
+ * anonymous visitor whether a given page exists, including a private one.
+ */
+const SAFE_MESSAGES = {
+    'username-taken': 'That username is not available. Please choose another.',
+    'display-name-conflict': 'That display name is not available. Please choose another.',
+    // #2073: plain, and without saying which account holds the address.
+    'admin-email-shared': 'That email address cannot be used. Please use another.',
+    'email-unconfirmed': 'Your email is set when you click the link we send to it.'
+    // No email-taken reason: since #2073 two accounts may share an email (#1748's refusal reversed).
+};
+/**
+ * Map a thrown value to a message that is safe to show an unauthenticated
+ * visitor.
+ *
+ * Deliberately conservative: only a real `UserCreateError` carrying a known
+ * reason produces a specific message. A plain object shaped like one is not
+ * trusted, because only the code that constructs a `UserCreateError` has
+ * decided the reason is accurate.
+ *
+ * Callers must still log the original error — this discards detail on purpose,
+ * and the detail is what makes a real failure diagnosable.
+ */
+export function safeRegistrationMessage(err) {
+    if (err instanceof UserCreateError) {
+        return SAFE_MESSAGES[err.reason] ?? GENERIC_REGISTRATION_FAILURE;
+    }
+    return GENERIC_REGISTRATION_FAILURE;
+}

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

@@ -44,6 +44,8 @@ export declare function sameUsername(a: unknown, b: unknown): boolean;
  * holding that name would collide with it wherever the name is compared.
  * `asserted` was the subject removed in #1435; it is reserved so the name
  * cannot be taken in the window before anyone reconsiders the concept.
+ * `shared-folders` owns the organization's shared folders (#2125): an account
+ * by that name would be the owner of every folder by the vault owner rule.
  *
  * The system principal is NOT listed here: its name comes from `.env` and is
  * checked separately by `isSystemPrincipal`, because an operator chooses it.

package/lib/src/utils/username.js

@@ -0,0 +1,105 @@
+'use strict';
+import { SHARED_FOLDER_OWNER } from './privateStorePath.js';
+/**
+ * One spelling of a username, for comparison (#1436).
+ *
+ * A username is an identifier, not prose: `jim`, `Jim` and `" jim "` are one
+ * account, and every comparison has to agree about that. Before this they did
+ * not. `FileUserProvider` keyed its map on the raw string, so those three were
+ * three separate accounts and `createUser`'s duplicate check did not see the
+ * case variants — an account could be registered whose name differed from an
+ * existing one only in case, which is the classic lookalike.
+ *
+ * The same split ran through the code the other way. `getAnonymousUser()`
+ * emits `'Anonymous'` while roughly ten sites compare against `'anonymous'`,
+ * so those guards never fired for a real visitor. They failed closed, which is
+ * luck rather than design — it is the same defect as #1433, where a viewer was
+ * written to the cache key under one spelling and read back under another.
+ *
+ * __Normalize to compare; keep the original to display.__ The stored record
+ * keeps whatever the person typed, because that is their name; the index and
+ * every equality test use this.
+ */
+/**
+ * The comparison form of a username: trimmed, lower-cased.
+ *
+ * Lower-case rather than upper: `toLowerCase()` is what the existing checks
+ * already used (`isSystemPrincipal`, the sitemap subject list), so this agrees
+ * with them rather than introducing a third convention.
+ *
+ * A non-string is normalized to the empty string rather than throwing, because
+ * callers pass values straight from a request body — and empty is already the
+ * "no username" case every caller handles.
+ */
+export function normalizeUsername(username) {
+    return typeof username === 'string' ? username.trim().toLowerCase() : '';
+}
+/**
+ * True when two usernames name the same account.
+ *
+ * Exists so a comparison reads as the question it is asking, and so no call
+ * site re-implements the rule by hand — which is how the spellings diverged.
+ */
+export function sameUsername(a, b) {
+    const left = normalizeUsername(a);
+    return left !== '' && left === normalizeUsername(b);
+}
+/**
+ * Names no person may register.
+ *
+ * `anonymous` is the principal for "nobody authenticated" — a real account
+ * holding that name would collide with it wherever the name is compared.
+ * `asserted` was the subject removed in #1435; it is reserved so the name
+ * cannot be taken in the window before anyone reconsiders the concept.
+ * `shared-folders` owns the organization's shared folders (#2125): an account
+ * by that name would be the owner of every folder by the vault owner rule.
+ *
+ * The system principal is NOT listed here: its name comes from `.env` and is
+ * checked separately by `isSystemPrincipal`, because an operator chooses it.
+ */
+export const RESERVED_USERNAMES = ['anonymous', 'asserted', SHARED_FOLDER_OWNER];
+/**
+ * The prefix of a person's identifier when the person has no account (#1930):
+ * `person:<uuid>`. No username may start with it, so an account-less person's
+ * identifier can never be, or later become, someone's username.
+ */
+export const ACCOUNTLESS_PERSON_PREFIX = 'person:';
+/**
+ * The prefix of an identity's `@id` (#2041): `urn:uuid:<v4>`, and older
+ * organizations' `urn:…` ids. No username may start with it, so a stored
+ * reference is always told apart: a value starting `urn:` is an `@id`,
+ * anything else a username not yet converted.
+ */
+export const IDENTITY_ID_PREFIX = 'urn:';
+/**
+ * The prefix a start-up conversion gives a stored username that has no
+ * account (#2041): `orphan:<name>`. The record is then nobody's: a later
+ * account with the same name never takes it over, no "is it mine" check
+ * matches it, and only an administrator can act on it. No username may
+ * start with it.
+ */
+export const ORPHAN_PREFIX = 'orphan:';
+/**
+ * Values older records hold where no user was recorded (#2096, #2097): the
+ * footnote migration's `migrated`, the editor fallback `unknown` (and the
+ * attachment pool's `Unknown`), the JSPWiki import's `import`. Never a
+ * username: a start-up conversion never looks them up (an account that later
+ * takes one of these names must not gain the records), stores them as
+ * `orphan:<value>` and does not count them as needing attention.
+ */
+export const NO_RECORDED_USER = ['migrated', 'unknown', 'import'];
+/** True when `value` is one of {@link NO_RECORDED_USER}, bare or as its orphan form. */
+export function isNoRecordedUser(value) {
+    const name = normalizeUsername(value);
+    return NO_RECORDED_USER.includes(name.startsWith(ORPHAN_PREFIX) ? name.slice(ORPHAN_PREFIX.length) : name);
+}
+/**
+ * True when the name belongs to a principal rather than a user, is a "no user
+ * recorded" value ({@link NO_RECORDED_USER}, #2097: an account by that name
+ * would take over the records that hold it), or has the contact, `@id` or
+ * orphan prefix.
+ */
+export function isReservedUsername(username) {
+    const name = normalizeUsername(username);
+    return RESERVED_USERNAMES.includes(name) || NO_RECORDED_USER.includes(name) || name.startsWith(ACCOUNTLESS_PERSON_PREFIX) || name.startsWith(IDENTITY_ID_PREFIX) || name.startsWith(ORPHAN_PREFIX);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilleke/ngdpbase-types",
-  "version": "5.39.0",
+  "version": "5.41.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",
@@ -51,6 +51,7 @@
     "linkedom": "^0.18.14",
     "markdown-it": "^14.3.3",
     "minisearch": "7.2.0",
+    "mmdb-lib": "^3.0.3",
     "multer": "^2.4.0",
     "rrule-temporal": "2.2.8",
     "tar": "^7.5.22",