@_linked/server 2.19.0 → 2.21.0

package/lib/esm/shapes/filestores/LocalFileStore.d.ts

@@ -37,6 +37,22 @@ export declare class LocalFileStore implements IFileStore {
     constructor(n: string | {
         id: string;
     }, basePath?: string);
+    /**
+     * Resolve a key against the base folder, refusing anything that ends up
+     * outside it: dot segments (`../x`, `a/../../x`), and symlinks inside the
+     * folder that point out of it (`link/x` where `link -> /etc`, or a file that
+     * is itself such a link).
+     *
+     * The check runs twice. First lexically, before the file system is touched;
+     * then on real paths, with `fs.realpath` applied to the base folder and to
+     * the target (or, for a target that does not exist yet, its nearest existing
+     * ancestor), so a symlink anywhere along the way is followed before the
+     * comparison.
+     *
+     * Keys are joined, not resolved, so a leading `/` still means "relative to
+     * the base folder", as it always did.
+     */
+    private resolveInside;
     /**
      * Delete a file from the local filesystem
      * @param filePath The path to the file to delete, relative to the base upload folder

package/lib/esm/shapes/filestores/LocalFileStore.js

@@ -5,6 +5,45 @@ import { createHash } from 'node:crypto';
 import * as fsSync from 'node:fs';
 import fs from 'node:fs/promises';
 import path from 'node:path';
+function isInside(base, target) {
+    return target === base || target.startsWith(base + path.sep);
+}
+/**
+ * `fs.realpath` of `p`, or, when `p` does not exist (yet), the real path of its
+ * nearest existing ancestor with the missing segments appended. Every symlink
+ * on the existing part of the path is resolved, including a dangling one (a
+ * write through it would create its target), so the result is where a read or
+ * write of `p` would actually land.
+ */
+async function realpathOfNearestExisting(p, depth = 0) {
+    if (depth > 40) {
+        throw new Error(`Too many symbolic links resolving ${p}`);
+    }
+    const missing = [];
+    let current = p;
+    for (;;) {
+        try {
+            const real = await fs.realpath(current);
+            return missing.length ? path.join(real, ...missing.reverse()) : real;
+        }
+        catch (err) {
+            if ((err === null || err === void 0 ? void 0 : err.code) !== 'ENOENT' && (err === null || err === void 0 ? void 0 : err.code) !== 'ENOTDIR')
+                throw err;
+        }
+        const link = await fs.readlink(current).catch(() => undefined);
+        if (link !== undefined) {
+            // a dangling symlink: follow it to where it points
+            const pointsTo = path.resolve(path.dirname(current), link);
+            const real = await realpathOfNearestExisting(pointsTo, depth + 1);
+            return missing.length ? path.join(real, ...missing.reverse()) : real;
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            return p;
+        missing.push(path.basename(current));
+        current = parent;
+    }
+}
 /**
  * A file store is not a Shape.
  *
@@ -28,13 +67,43 @@ export class LocalFileStore {
         this.accessURL = process.env.SITE_ROOT;
         this.basePath = basePath;
     }
+    /**
+     * Resolve a key against the base folder, refusing anything that ends up
+     * outside it: dot segments (`../x`, `a/../../x`), and symlinks inside the
+     * folder that point out of it (`link/x` where `link -> /etc`, or a file that
+     * is itself such a link).
+     *
+     * The check runs twice. First lexically, before the file system is touched;
+     * then on real paths, with `fs.realpath` applied to the base folder and to
+     * the target (or, for a target that does not exist yet, its nearest existing
+     * ancestor), so a symlink anywhere along the way is followed before the
+     * comparison.
+     *
+     * Keys are joined, not resolved, so a leading `/` still means "relative to
+     * the base folder", as it always did.
+     */
+    async resolveInside(filePath) {
+        const base = path.resolve(this.basePath);
+        const target = path.resolve(path.join(this.basePath, String(filePath !== null && filePath !== void 0 ? filePath : '')));
+        if (!isInside(base, target)) {
+            throw new Error(`File path escapes the file store: ${filePath}`);
+        }
+        const [realBase, realTarget] = await Promise.all([
+            realpathOfNearestExisting(base),
+            realpathOfNearestExisting(target),
+        ]);
+        if (!isInside(realBase, realTarget)) {
+            throw new Error(`File path escapes the file store: ${filePath}`);
+        }
+        return target;
+    }
     /**
      * Delete a file from the local filesystem
      * @param filePath The path to the file to delete, relative to the base upload folder
      * @returns A promise that resolves when the file is deleted
      */
-    deleteFile(filePath) {
-        const fileToDelete = path.join(this.basePath, filePath);
+    async deleteFile(filePath) {
+        const fileToDelete = await this.resolveInside(filePath);
         return fs.rm(fileToDelete);
     }
     /**
@@ -42,8 +111,8 @@ export class LocalFileStore {
      * @param filePath The path to the file to check, relative to the base upload folder
      * @returns A promise that resolves to true if the file exists, false otherwise
      */
-    fileExists(filePath) {
-        const fileToCheck = path.join(this.basePath, filePath);
+    async fileExists(filePath) {
+        const fileToCheck = await this.resolveInside(filePath);
         return fs
             .access(fileToCheck)
             .then(() => true)
@@ -54,8 +123,8 @@ export class LocalFileStore {
      * @param filePath The path to the file to get, relative to the base upload folder
      * @returns A promise that resolves to the file contents as a buffer, or null if the file does not exist
      */
-    getFile(filePath) {
-        const fileToGet = path.join(this.basePath, filePath);
+    async getFile(filePath) {
+        const fileToGet = await this.resolveInside(filePath);
         return fs.readFile(fileToGet).catch(() => null);
     }
     /**
@@ -208,7 +277,7 @@ export class LocalFileStore {
         const target = await this.resolveTarget(filePath, normalized.mimeType, suffixDuplicates);
         // resolved against basePath, exactly like every read method does, so what
         // is written here can be read back by the same key
-        const targetFilePath = path.join(this.basePath, target.storedPath);
+        const targetFilePath = await this.resolveInside(target.storedPath);
         //make sure the target folder exists
         if (!fsSync.existsSync(path.dirname(targetFilePath))) {
             fsSync.mkdirSync(path.dirname(targetFilePath), { recursive: true });
@@ -230,7 +299,7 @@ export class LocalFileStore {
      * @returns The size and sha256 of the file, or null if it does not exist
      */
     async statFile(filePath) {
-        const fileToStat = path.join(this.basePath, filePath);
+        const fileToStat = await this.resolveInside(filePath);
         let stat;
         try {
             stat = await fs.stat(fileToStat);

package/lib/esm/shapes/filestores/LocalFileStore.js.map

@@ -1 +1 @@
-{"version":3,"file":"LocalFileStore.js","sourceRoot":"","sources":["../../../../src/shapes/filestores/LocalFileStore.ts"],"names":[],"mappings":"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","sourcesContent":["import { relativeFileSystemUploadPath } from '@_linked/server-utils/utils/Upload';\nimport { publicUploadPath } from '@_linked/server-utils/utils/ServerPaths';\nimport {\n  FileStat,\n  IFileStore,\n  SaveFileOptions,\n  normalizeSaveFileOptions,\n} from '@_linked/core/interfaces/IFileStore';\nimport { createHash } from 'node:crypto';\nimport * as fsSync from 'node:fs';\nimport fs from 'node:fs/promises';\nimport path from 'node:path';\n\n/**\n * What `saveFile` stored, and where.\n *\n * `storedPath` is the key as it ended up in the store: it is exactly what\n * `getFile`, `fileExists`, `deleteFile` and `statFile` expect, so a caller that\n * wants to verify what it just uploaded never has to guess a name back out of a\n * URL.\n */\nexport interface SavedFileLocation {\n  /** The key the file is stored under, relative to the store's base folder. */\n  storedPath: string;\n  /** The public URL, the same string `saveFile` returns. */\n  publicURL: string;\n}\n\n/**\n * A file store is not a Shape.\n *\n * This class used to `extends Shape`, but used nothing from it: no `this.id`, no\n * `this.uri`, no `nodeShape`, no Shape statics, no property decorators, and no\n * caller that treated it as a Shape. The only inherited behaviour was `super({id})`\n * writing an id that nothing ever read.\n *\n * Datasets and stores stopped being Shapes deliberately (core `0e8c86e`,\n * \"datasets are not shapes\"), and `Shape`'s instantiation guard is currently\n * DEFERRED naming this very class as the reason. Dropping the inheritance removes\n * one of the last obstacles to re-enabling it.\n */\nexport class LocalFileStore implements IFileStore {\n  private readonly basePath: string;\n\n  public readonly accessURL: string;\n\n  /**\n   * `n` names the store. It was previously also accepted as `{id}` because that is\n   * `Shape`'s constructor signature; both forms are still taken so existing callers\n   * keep working, but neither is stored as a node id any more.\n   */\n  constructor(\n    n: string | { id: string },\n    basePath: string = relativeFileSystemUploadPath\n  ) {\n    this.accessURL = process.env.SITE_ROOT;\n    this.basePath = basePath;\n  }\n\n  /**\n   * Delete a file from the local filesystem\n   * @param filePath The path to the file to delete, relative to the base upload folder\n   * @returns A promise that resolves when the file is deleted\n   */\n  deleteFile(filePath: string): Promise<void> {\n    const fileToDelete = path.join(this.basePath, filePath);\n\n    return fs.rm(fileToDelete);\n  }\n\n  /**\n   * Check if a file exists on the local filesystem\n   * @param filePath The path to the file to check, relative to the base upload folder\n   * @returns A promise that resolves to true if the file exists, false otherwise\n   */\n  fileExists(filePath: string): Promise<boolean> {\n    const fileToCheck = path.join(this.basePath, filePath);\n\n    return fs\n      .access(fileToCheck)\n      .then(() => true)\n      .catch(() => false);\n  }\n\n  /**\n   * Get a file from the local filesystem\n   * @param filePath The path to the file to get, relative to the base upload folder\n   * @returns A promise that resolves to the file contents as a buffer, or null if the file does not exist\n   */\n  getFile(filePath: string): Promise<Buffer | null> {\n    const fileToGet = path.join(this.basePath, filePath);\n\n    return fs.readFile(fileToGet).catch(() => null);\n  }\n\n  /**\n   * List every file in the store, recursively.\n   *\n   * @param prefix Only return keys starting with this string. Matched against\n   *   the returned (relative) key, so `listFiles('images/')` selects the\n   *   `images` folder and `listFiles('main-')` selects by file name.\n   * @returns Keys relative to the base folder, exactly as `getFile`,\n   *   `fileExists`, `deleteFile` and `statFile` expect them.\n   *\n   * The keys are relative on purpose: every other method on this store resolves\n   * its argument *against* `basePath`, so returning `data/uploads/x.txt` here\n   * meant a caller who fed the result straight back into `getFile` looked for\n   * `data/uploads/data/uploads/x.txt`. It also matches `S3FileStore`, which\n   * strips the bucket prefix before returning.\n   */\n  async listFiles(prefix?: string): Promise<string[]> {\n    const walk = async (relativeDir: string): Promise<string[]> => {\n      const absoluteDir = path.join(this.basePath, relativeDir);\n\n      let entries: fsSync.Dirent[];\n      try {\n        entries = await fs.readdir(absoluteDir, { withFileTypes: true });\n      } catch (err) {\n        console.warn('Error during listFiles', err);\n        return [];\n      }\n\n      const nested = await Promise.all(\n        entries.map((entry) => {\n          // path.join('', 'x') === 'x', so the top level stays unprefixed\n          const key = path.join(relativeDir, entry.name);\n          // recurse into the subdirectory itself. This used to call\n          // listFiles(prefix), which re-read basePath and so found the same\n          // directory again -- unbounded recursion as soon as the store held\n          // one folder.\n          return entry.isDirectory() ? walk(key) : Promise.resolve([key]);\n        })\n      );\n\n      return nested.flat();\n    };\n\n    const keys = await walk('');\n\n    return prefix ? keys.filter((key) => key.startsWith(prefix)) : keys;\n  }\n\n  /**\n   * Work out the key a save will use, and the URL that key is served under.\n   *\n   * This used to be `getUploadTarget` from `@_linked/server-utils`, which could\n   * not be used here for two reasons:\n   *\n   * - it lowercases the name. That is HTTP-upload hygiene (browsers hand over\n   *   whatever the user's filesystem had, and `getUploadTarget` is still the\n   *   right place for it — `uploadSingleFileFromFormData` calls it before it\n   *   ever reaches a store), but it corrupts a key a program chose on purpose,\n   *   such as a Vite content hash: `main-hwqwrAvA.css`.\n   * - it always resolves against `relativeFileSystemUploadPath`, ignoring this\n   *   store's `basePath`, so a store with a custom base folder wrote where it\n   *   could not read back.\n   *\n   * Characters that are not safe in a file name are still replaced, exactly as\n   * `getUploadTarget` does it — only the case is left alone.\n   */\n  private async resolveTarget(\n    filePath: string,\n    mimeType: string | undefined,\n    suffixDuplicates: boolean\n  ): Promise<SavedFileLocation> {\n    // alphanumerics, dot, underscore, dash and the path separator survive; a\n    // run of anything else becomes one dash. Case is deliberately preserved.\n    //\n    // The dash has to be in that set. Without it a run of dashes collapsed to\n    // one, so a Vite base64 content hash that happens to start with a dash —\n    // `shapeCodeGenerator--2JmNvrO.js` — came back as\n    // `shapeCodeGenerator-2JmNvrO.js`, a different key from the one the caller\n    // asked for and from the one baked into the bundle.\n    let sanitisedName = filePath.replace(/[^A-Za-z0-9\\._\\/-]+/g, '-');\n\n    if (sanitisedName.indexOf('.') === -1) {\n      //auto add an extension if none is present, based on the mimetype\n      if (!mimeType) {\n        throw new Error(\n          'This file does not have an extension and no mimetype was provided'\n        );\n      }\n      sanitisedName = sanitisedName + '.' + mimeType.split('/')[1];\n    }\n\n    const ext = sanitisedName.split('.').pop();\n    const withoutExt = sanitisedName.substring(\n      0,\n      sanitisedName.length - (ext.length + 1)\n    );\n\n    // A 6 character random string avoids clobbering an existing file,\n    // e.g. report.pdf -> report_312acb.pdf.\n    //\n    // It is only applied when the name is actually taken. This used to be\n    // unconditional, which did prevent duplicates but also meant a caller never\n    // got back the key it asked for: a content-hashed bundle handed over as\n    // `main-hwqwrAvA.css` landed as `main-hwqwrAvA_x9k2ml.css`, so the name\n    // baked into the HTML no longer resolved. Checking first keeps the\n    // never-clobber guarantee -- a taken name still gets a suffix, and the\n    // suffixed name is itself re-checked -- while leaving free names alone.\n    // `S3FileStore` has always worked this way, so the two implementations of\n    // IFileStore now read the flag the same.\n    let storedPath = withoutExt + '.' + ext;\n\n    if (suffixDuplicates) {\n      // 36^6 is ~2 billion, so a second collision is already vanishingly\n      // unlikely; the cap turns a pathological case into a clear error rather\n      // than a spin.\n      const maxAttempts = 10;\n      let attempt = 0;\n\n      while (await this.fileExists(storedPath)) {\n        if (attempt++ >= maxAttempts) {\n          throw new Error(\n            `Could not find a free name for '${filePath}' after ${maxAttempts} attempts`\n          );\n        }\n\n        storedPath =\n          withoutExt + '_' + Math.random().toString(36).substring(2, 8) + '.' + ext;\n      }\n    }\n\n    return {\n      storedPath,\n      publicURL: this.accessURL + publicUploadPath + '/' + storedPath,\n    };\n  }\n\n  /**\n   * Save a file to the local filesystem\n   * @param filePath The path to save the file to, relative to the base folder\n   * @param fileContent The contents of the file as a buffer\n   * @param options Save options, or a string read as the old positional mimeType.\n   *   A local file has no headers to attach, so only `mimeType` (used to add a\n   *   missing extension) and `preventDuplicates` mean anything here;\n   *   `cacheControl` and `metadata` are accepted and ignored.\n   * @param preventDuplicates Only honoured when `options` is a string\n   * @returns A promise that resolves to the public URL of the file. Use\n   *   {@link saveFileWithPath} when you also need the key it was stored under.\n   */\n  async saveFile(\n    filePath: string,\n    fileContent: Buffer,\n    options?: SaveFileOptions | string,\n    preventDuplicates?: boolean\n  ): Promise<string> {\n    const { publicURL } = await this.saveFileWithPath(\n      filePath,\n      fileContent,\n      options,\n      preventDuplicates\n    );\n\n    return publicURL;\n  }\n\n  /**\n   * Save a file and report both the key it was stored under and its URL.\n   *\n   * `saveFile` can only return one string, and `IFileStore` says that string is\n   * a URL — but a caller that wants to verify what it just wrote needs the\n   * *key*, which is what `statFile`, `getFile`, `fileExists` and `deleteFile`\n   * take. That is what `storedPath` is: hand it straight back to any of them.\n   *\n   * The key equals the `filePath` given verbatim — case included — as long as\n   * the name needs no sanitising and already has an extension. With\n   * `preventDuplicates` left unspecified (this store's default, kept for upload\n   * callers) that still holds for a name nothing else occupies; only a name\n   * already taken gains a random suffix, and `storedPath` is the only place\n   * that name is reported.\n   */\n  async saveFileWithPath(\n    filePath: string,\n    fileContent: Buffer,\n    options?: SaveFileOptions | string,\n    preventDuplicates?: boolean\n  ): Promise<SavedFileLocation> {\n    const normalized = normalizeSaveFileOptions(options, preventDuplicates);\n    // Core reports an unspecified preventDuplicates as undefined, leaving the\n    // default to each store. This one protects an existing file, so only an\n    // explicit `false` allows an overwrite.\n    const suffixDuplicates = normalized.preventDuplicates ?? true;\n\n    const target = await this.resolveTarget(\n      filePath,\n      normalized.mimeType,\n      suffixDuplicates\n    );\n\n    // resolved against basePath, exactly like every read method does, so what\n    // is written here can be read back by the same key\n    const targetFilePath = path.join(this.basePath, target.storedPath);\n\n    //make sure the target folder exists\n    if (!fsSync.existsSync(path.dirname(targetFilePath))) {\n      fsSync.mkdirSync(path.dirname(targetFilePath), { recursive: true });\n    }\n    await fs.writeFile(targetFilePath, fileContent);\n\n    return target;\n  }\n\n  /**\n   * Read back the metadata of a stored file, for verify-after-upload.\n   *\n   * The path is resolved exactly like saveFile/getFile/fileExists/deleteFile\n   * do, against this store's base folder, so the `storedPath` that\n   * saveFileWithPath reports can be handed straight back here.\n   *\n   * The sha256 is computed on demand from the bytes: statFile is only called\n   * during publish verification, not on every upload.\n   *\n   * @param filePath The path to the file, relative to the base upload folder\n   * @returns The size and sha256 of the file, or null if it does not exist\n   */\n  async statFile(filePath: string): Promise<FileStat | null> {\n    const fileToStat = path.join(this.basePath, filePath);\n\n    let stat: fsSync.Stats;\n    try {\n      stat = await fs.stat(fileToStat);\n    } catch (err) {\n      return null;\n    }\n    if (!stat.isFile()) {\n      return null;\n    }\n\n    const contents = await fs.readFile(fileToStat);\n    const sha256 = createHash('sha256').update(contents).digest('hex');\n\n    return { size: stat.size, sha256 };\n  }\n}\n"]}
+{"version":3,"file":"LocalFileStore.js","sourceRoot":"","sources":["../../../../src/shapes/filestores/LocalFileStore.ts"],"names":[],"mappings":"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","sourcesContent":["import { relativeFileSystemUploadPath } from '@_linked/server-utils/utils/Upload';\nimport { publicUploadPath } from '@_linked/server-utils/utils/ServerPaths';\nimport {\n  FileStat,\n  IFileStore,\n  SaveFileOptions,\n  normalizeSaveFileOptions,\n} from '@_linked/core/interfaces/IFileStore';\nimport { createHash } from 'node:crypto';\nimport * as fsSync from 'node:fs';\nimport fs from 'node:fs/promises';\nimport path from 'node:path';\n\nfunction isInside(base: string, target: string): boolean {\n  return target === base || target.startsWith(base + path.sep);\n}\n\n/**\n * `fs.realpath` of `p`, or, when `p` does not exist (yet), the real path of its\n * nearest existing ancestor with the missing segments appended. Every symlink\n * on the existing part of the path is resolved, including a dangling one (a\n * write through it would create its target), so the result is where a read or\n * write of `p` would actually land.\n */\nasync function realpathOfNearestExisting(p: string, depth = 0): Promise<string> {\n  if (depth > 40) {\n    throw new Error(`Too many symbolic links resolving ${p}`);\n  }\n  const missing: string[] = [];\n  let current = p;\n  for (;;) {\n    try {\n      const real = await fs.realpath(current);\n      return missing.length ? path.join(real, ...missing.reverse()) : real;\n    } catch (err: any) {\n      if (err?.code !== 'ENOENT' && err?.code !== 'ENOTDIR') throw err;\n    }\n    const link = await fs.readlink(current).catch(() => undefined);\n    if (link !== undefined) {\n      // a dangling symlink: follow it to where it points\n      const pointsTo = path.resolve(path.dirname(current), link);\n      const real = await realpathOfNearestExisting(pointsTo, depth + 1);\n      return missing.length ? path.join(real, ...missing.reverse()) : real;\n    }\n    const parent = path.dirname(current);\n    if (parent === current) return p;\n    missing.push(path.basename(current));\n    current = parent;\n  }\n}\n\n/**\n * What `saveFile` stored, and where.\n *\n * `storedPath` is the key as it ended up in the store: it is exactly what\n * `getFile`, `fileExists`, `deleteFile` and `statFile` expect, so a caller that\n * wants to verify what it just uploaded never has to guess a name back out of a\n * URL.\n */\nexport interface SavedFileLocation {\n  /** The key the file is stored under, relative to the store's base folder. */\n  storedPath: string;\n  /** The public URL, the same string `saveFile` returns. */\n  publicURL: string;\n}\n\n/**\n * A file store is not a Shape.\n *\n * This class used to `extends Shape`, but used nothing from it: no `this.id`, no\n * `this.uri`, no `nodeShape`, no Shape statics, no property decorators, and no\n * caller that treated it as a Shape. The only inherited behaviour was `super({id})`\n * writing an id that nothing ever read.\n *\n * Datasets and stores stopped being Shapes deliberately (core `0e8c86e`,\n * \"datasets are not shapes\"), and `Shape`'s instantiation guard is currently\n * DEFERRED naming this very class as the reason. Dropping the inheritance removes\n * one of the last obstacles to re-enabling it.\n */\nexport class LocalFileStore implements IFileStore {\n  private readonly basePath: string;\n\n  public readonly accessURL: string;\n\n  /**\n   * `n` names the store. It was previously also accepted as `{id}` because that is\n   * `Shape`'s constructor signature; both forms are still taken so existing callers\n   * keep working, but neither is stored as a node id any more.\n   */\n  constructor(\n    n: string | { id: string },\n    basePath: string = relativeFileSystemUploadPath\n  ) {\n    this.accessURL = process.env.SITE_ROOT;\n    this.basePath = basePath;\n  }\n\n  /**\n   * Resolve a key against the base folder, refusing anything that ends up\n   * outside it: dot segments (`../x`, `a/../../x`), and symlinks inside the\n   * folder that point out of it (`link/x` where `link -> /etc`, or a file that\n   * is itself such a link).\n   *\n   * The check runs twice. First lexically, before the file system is touched;\n   * then on real paths, with `fs.realpath` applied to the base folder and to\n   * the target (or, for a target that does not exist yet, its nearest existing\n   * ancestor), so a symlink anywhere along the way is followed before the\n   * comparison.\n   *\n   * Keys are joined, not resolved, so a leading `/` still means \"relative to\n   * the base folder\", as it always did.\n   */\n  private async resolveInside(filePath: string): Promise<string> {\n    const base = path.resolve(this.basePath);\n    const target = path.resolve(path.join(this.basePath, String(filePath ?? '')));\n    if (!isInside(base, target)) {\n      throw new Error(`File path escapes the file store: ${filePath}`);\n    }\n    const [realBase, realTarget] = await Promise.all([\n      realpathOfNearestExisting(base),\n      realpathOfNearestExisting(target),\n    ]);\n    if (!isInside(realBase, realTarget)) {\n      throw new Error(`File path escapes the file store: ${filePath}`);\n    }\n    return target;\n  }\n\n  /**\n   * Delete a file from the local filesystem\n   * @param filePath The path to the file to delete, relative to the base upload folder\n   * @returns A promise that resolves when the file is deleted\n   */\n  async deleteFile(filePath: string): Promise<void> {\n    const fileToDelete = await this.resolveInside(filePath);\n\n    return fs.rm(fileToDelete);\n  }\n\n  /**\n   * Check if a file exists on the local filesystem\n   * @param filePath The path to the file to check, relative to the base upload folder\n   * @returns A promise that resolves to true if the file exists, false otherwise\n   */\n  async fileExists(filePath: string): Promise<boolean> {\n    const fileToCheck = await this.resolveInside(filePath);\n\n    return fs\n      .access(fileToCheck)\n      .then(() => true)\n      .catch(() => false);\n  }\n\n  /**\n   * Get a file from the local filesystem\n   * @param filePath The path to the file to get, relative to the base upload folder\n   * @returns A promise that resolves to the file contents as a buffer, or null if the file does not exist\n   */\n  async getFile(filePath: string): Promise<Buffer | null> {\n    const fileToGet = await this.resolveInside(filePath);\n\n    return fs.readFile(fileToGet).catch(() => null);\n  }\n\n  /**\n   * List every file in the store, recursively.\n   *\n   * @param prefix Only return keys starting with this string. Matched against\n   *   the returned (relative) key, so `listFiles('images/')` selects the\n   *   `images` folder and `listFiles('main-')` selects by file name.\n   * @returns Keys relative to the base folder, exactly as `getFile`,\n   *   `fileExists`, `deleteFile` and `statFile` expect them.\n   *\n   * The keys are relative on purpose: every other method on this store resolves\n   * its argument *against* `basePath`, so returning `data/uploads/x.txt` here\n   * meant a caller who fed the result straight back into `getFile` looked for\n   * `data/uploads/data/uploads/x.txt`. It also matches `S3FileStore`, which\n   * strips the bucket prefix before returning.\n   */\n  async listFiles(prefix?: string): Promise<string[]> {\n    const walk = async (relativeDir: string): Promise<string[]> => {\n      const absoluteDir = path.join(this.basePath, relativeDir);\n\n      let entries: fsSync.Dirent[];\n      try {\n        entries = await fs.readdir(absoluteDir, { withFileTypes: true });\n      } catch (err) {\n        console.warn('Error during listFiles', err);\n        return [];\n      }\n\n      const nested = await Promise.all(\n        entries.map((entry) => {\n          // path.join('', 'x') === 'x', so the top level stays unprefixed\n          const key = path.join(relativeDir, entry.name);\n          // recurse into the subdirectory itself. This used to call\n          // listFiles(prefix), which re-read basePath and so found the same\n          // directory again -- unbounded recursion as soon as the store held\n          // one folder.\n          return entry.isDirectory() ? walk(key) : Promise.resolve([key]);\n        })\n      );\n\n      return nested.flat();\n    };\n\n    const keys = await walk('');\n\n    return prefix ? keys.filter((key) => key.startsWith(prefix)) : keys;\n  }\n\n  /**\n   * Work out the key a save will use, and the URL that key is served under.\n   *\n   * This used to be `getUploadTarget` from `@_linked/server-utils`, which could\n   * not be used here for two reasons:\n   *\n   * - it lowercases the name. That is HTTP-upload hygiene (browsers hand over\n   *   whatever the user's filesystem had, and `getUploadTarget` is still the\n   *   right place for it — `uploadSingleFileFromFormData` calls it before it\n   *   ever reaches a store), but it corrupts a key a program chose on purpose,\n   *   such as a Vite content hash: `main-hwqwrAvA.css`.\n   * - it always resolves against `relativeFileSystemUploadPath`, ignoring this\n   *   store's `basePath`, so a store with a custom base folder wrote where it\n   *   could not read back.\n   *\n   * Characters that are not safe in a file name are still replaced, exactly as\n   * `getUploadTarget` does it — only the case is left alone.\n   */\n  private async resolveTarget(\n    filePath: string,\n    mimeType: string | undefined,\n    suffixDuplicates: boolean\n  ): Promise<SavedFileLocation> {\n    // alphanumerics, dot, underscore, dash and the path separator survive; a\n    // run of anything else becomes one dash. Case is deliberately preserved.\n    //\n    // The dash has to be in that set. Without it a run of dashes collapsed to\n    // one, so a Vite base64 content hash that happens to start with a dash —\n    // `shapeCodeGenerator--2JmNvrO.js` — came back as\n    // `shapeCodeGenerator-2JmNvrO.js`, a different key from the one the caller\n    // asked for and from the one baked into the bundle.\n    let sanitisedName = filePath.replace(/[^A-Za-z0-9\\._\\/-]+/g, '-');\n\n    if (sanitisedName.indexOf('.') === -1) {\n      //auto add an extension if none is present, based on the mimetype\n      if (!mimeType) {\n        throw new Error(\n          'This file does not have an extension and no mimetype was provided'\n        );\n      }\n      sanitisedName = sanitisedName + '.' + mimeType.split('/')[1];\n    }\n\n    const ext = sanitisedName.split('.').pop();\n    const withoutExt = sanitisedName.substring(\n      0,\n      sanitisedName.length - (ext.length + 1)\n    );\n\n    // A 6 character random string avoids clobbering an existing file,\n    // e.g. report.pdf -> report_312acb.pdf.\n    //\n    // It is only applied when the name is actually taken. This used to be\n    // unconditional, which did prevent duplicates but also meant a caller never\n    // got back the key it asked for: a content-hashed bundle handed over as\n    // `main-hwqwrAvA.css` landed as `main-hwqwrAvA_x9k2ml.css`, so the name\n    // baked into the HTML no longer resolved. Checking first keeps the\n    // never-clobber guarantee -- a taken name still gets a suffix, and the\n    // suffixed name is itself re-checked -- while leaving free names alone.\n    // `S3FileStore` has always worked this way, so the two implementations of\n    // IFileStore now read the flag the same.\n    let storedPath = withoutExt + '.' + ext;\n\n    if (suffixDuplicates) {\n      // 36^6 is ~2 billion, so a second collision is already vanishingly\n      // unlikely; the cap turns a pathological case into a clear error rather\n      // than a spin.\n      const maxAttempts = 10;\n      let attempt = 0;\n\n      while (await this.fileExists(storedPath)) {\n        if (attempt++ >= maxAttempts) {\n          throw new Error(\n            `Could not find a free name for '${filePath}' after ${maxAttempts} attempts`\n          );\n        }\n\n        storedPath =\n          withoutExt + '_' + Math.random().toString(36).substring(2, 8) + '.' + ext;\n      }\n    }\n\n    return {\n      storedPath,\n      publicURL: this.accessURL + publicUploadPath + '/' + storedPath,\n    };\n  }\n\n  /**\n   * Save a file to the local filesystem\n   * @param filePath The path to save the file to, relative to the base folder\n   * @param fileContent The contents of the file as a buffer\n   * @param options Save options, or a string read as the old positional mimeType.\n   *   A local file has no headers to attach, so only `mimeType` (used to add a\n   *   missing extension) and `preventDuplicates` mean anything here;\n   *   `cacheControl` and `metadata` are accepted and ignored.\n   * @param preventDuplicates Only honoured when `options` is a string\n   * @returns A promise that resolves to the public URL of the file. Use\n   *   {@link saveFileWithPath} when you also need the key it was stored under.\n   */\n  async saveFile(\n    filePath: string,\n    fileContent: Buffer,\n    options?: SaveFileOptions | string,\n    preventDuplicates?: boolean\n  ): Promise<string> {\n    const { publicURL } = await this.saveFileWithPath(\n      filePath,\n      fileContent,\n      options,\n      preventDuplicates\n    );\n\n    return publicURL;\n  }\n\n  /**\n   * Save a file and report both the key it was stored under and its URL.\n   *\n   * `saveFile` can only return one string, and `IFileStore` says that string is\n   * a URL — but a caller that wants to verify what it just wrote needs the\n   * *key*, which is what `statFile`, `getFile`, `fileExists` and `deleteFile`\n   * take. That is what `storedPath` is: hand it straight back to any of them.\n   *\n   * The key equals the `filePath` given verbatim — case included — as long as\n   * the name needs no sanitising and already has an extension. With\n   * `preventDuplicates` left unspecified (this store's default, kept for upload\n   * callers) that still holds for a name nothing else occupies; only a name\n   * already taken gains a random suffix, and `storedPath` is the only place\n   * that name is reported.\n   */\n  async saveFileWithPath(\n    filePath: string,\n    fileContent: Buffer,\n    options?: SaveFileOptions | string,\n    preventDuplicates?: boolean\n  ): Promise<SavedFileLocation> {\n    const normalized = normalizeSaveFileOptions(options, preventDuplicates);\n    // Core reports an unspecified preventDuplicates as undefined, leaving the\n    // default to each store. This one protects an existing file, so only an\n    // explicit `false` allows an overwrite.\n    const suffixDuplicates = normalized.preventDuplicates ?? true;\n\n    const target = await this.resolveTarget(\n      filePath,\n      normalized.mimeType,\n      suffixDuplicates\n    );\n\n    // resolved against basePath, exactly like every read method does, so what\n    // is written here can be read back by the same key\n    const targetFilePath = await this.resolveInside(target.storedPath);\n\n    //make sure the target folder exists\n    if (!fsSync.existsSync(path.dirname(targetFilePath))) {\n      fsSync.mkdirSync(path.dirname(targetFilePath), { recursive: true });\n    }\n    await fs.writeFile(targetFilePath, fileContent);\n\n    return target;\n  }\n\n  /**\n   * Read back the metadata of a stored file, for verify-after-upload.\n   *\n   * The path is resolved exactly like saveFile/getFile/fileExists/deleteFile\n   * do, against this store's base folder, so the `storedPath` that\n   * saveFileWithPath reports can be handed straight back here.\n   *\n   * The sha256 is computed on demand from the bytes: statFile is only called\n   * during publish verification, not on every upload.\n   *\n   * @param filePath The path to the file, relative to the base upload folder\n   * @returns The size and sha256 of the file, or null if it does not exist\n   */\n  async statFile(filePath: string): Promise<FileStat | null> {\n    const fileToStat = await this.resolveInside(filePath);\n\n    let stat: fsSync.Stats;\n    try {\n      stat = await fs.stat(fileToStat);\n    } catch (err) {\n      return null;\n    }\n    if (!stat.isFile()) {\n      return null;\n    }\n\n    const contents = await fs.readFile(fileToStat);\n    const sha256 = createHash('sha256').update(contents).digest('hex');\n\n    return { size: stat.size, sha256 };\n  }\n}\n"]}

package/lib/esm/shapes/index.d.ts

@@ -1,4 +1,4 @@
-import '../ontologies/lincd-server.register.js';
+import '../ontologies/server.register.js';
 import './LinkedServer.js';
 import './LincdAPI.js';
 import './LincdWebApp.js';

package/lib/esm/shapes/index.js

@@ -1,7 +1,7 @@
 // Registers every shape this package defines. Side-effect imports only: a
 // consumer (or the host app) can load this one module to get the full set of
 // shapes registered, without pulling in components, providers or other exports.
-import '../ontologies/lincd-server.register.js';
+import '../ontologies/server.register.js';
 import './LinkedServer.js';
 import './LincdAPI.js';
 import './LincdWebApp.js';

package/lib/esm/shapes/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/shapes/index.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,6EAA6E;AAC7E,gFAAgF;AAChF,OAAO,wCAAwC,CAAC;AAEhD,OAAO,mBAAmB,CAAC;AAC3B,OAAO,eAAe,CAAC;AACvB,OAAO,kBAAkB,CAAC","sourcesContent":["// Registers every shape this package defines. Side-effect imports only: a\n// consumer (or the host app) can load this one module to get the full set of\n// shapes registered, without pulling in components, providers or other exports.\nimport '../ontologies/lincd-server.register.js';\n\nimport './LinkedServer.js';\nimport './LincdAPI.js';\nimport './LincdWebApp.js';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/shapes/index.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,6EAA6E;AAC7E,gFAAgF;AAChF,OAAO,kCAAkC,CAAC;AAE1C,OAAO,mBAAmB,CAAC;AAC3B,OAAO,eAAe,CAAC;AACvB,OAAO,kBAAkB,CAAC","sourcesContent":["// Registers every shape this package defines. Side-effect imports only: a\n// consumer (or the host app) can load this one module to get the full set of\n// shapes registered, without pulling in components, providers or other exports.\nimport '../ontologies/server.register.js';\n\nimport './LinkedServer.js';\nimport './LincdAPI.js';\nimport './LincdWebApp.js';\n"]}

package/lib/esm/utils/jsonBodyParser.js

@@ -16,6 +16,21 @@ export const JSON_BODY_LIMIT = '50mb';
  * the behaviour pinned by `json-body-parser.test.ts`.
  */
 export function createJsonBodyParser() {
-    return express.json({ limit: JSON_BODY_LIMIT });
+    return express.json({ limit: JSON_BODY_LIMIT, verify: keepRawBody });
+}
+/** The routes whose handlers get the body as received, on `request.rawBody`. */
+const RAW_BODY_PATHS = new Set(['/api/select-raw']);
+/**
+ * Keep the unparsed bytes of a raw SPARQL request on `request.rawBody`, so a
+ * raw query authorizer (`registerRawQueryAuthorizer` in server-utils) can
+ * verify a signature over the exact body. Only for those routes: every other
+ * body is parsed and its bytes dropped as before.
+ */
+function keepRawBody(req, _res, buf) {
+    var _a, _b;
+    const path = String((_b = (_a = req.originalUrl) !== null && _a !== void 0 ? _a : req.url) !== null && _b !== void 0 ? _b : '').split('?')[0];
+    if (req.method === 'POST' && RAW_BODY_PATHS.has(path)) {
+        req.rawBody = buf;
+    }
 }
 //# sourceMappingURL=jsonBodyParser.js.map

package/lib/esm/utils/jsonBodyParser.js.map

@@ -1 +1 @@
-{"version":3,"file":"jsonBodyParser.js","sourceRoot":"","sources":["../../../src/utils/jsonBodyParser.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAE9B;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC;AAEtC;;;;;;;;;GASG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,eAAe,EAAE,CAAC,CAAC;AAClD,CAAC","sourcesContent":["import express from 'express';\n\n/**\n * Largest JSON body the server accepts. `Server.call` sends its arguments as\n * one JSON document, and some callers (bulk imports, base64 file payloads)\n * send far more than the 100kb default.\n */\nexport const JSON_BODY_LIMIT = '50mb';\n\n/**\n * The request body parser LinkedServer mounts in front of every route.\n *\n * It is Express's own `express.json()`, i.e. the body-parser 1.x that ships\n * inside Express 4 — the server does not depend on body-parser directly. It\n * parses `application/json` only: multipart uploads (handled with formidable\n * by the upload utilities) and urlencoded forms pass through with their stream\n * unread. Changing parser, or moving to Express 5 (body-parser 2), must keep\n * the behaviour pinned by `json-body-parser.test.ts`.\n */\nexport function createJsonBodyParser() {\n  return express.json({ limit: JSON_BODY_LIMIT });\n}\n"]}
+{"version":3,"file":"jsonBodyParser.js","sourceRoot":"","sources":["../../../src/utils/jsonBodyParser.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAE9B;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC;AAEtC;;;;;;;;;GASG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;AACvE,CAAC;AAED,gFAAgF;AAChF,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC;AAEpD;;;;;GAKG;AACH,SAAS,WAAW,CAAC,GAAQ,EAAE,IAAa,EAAE,GAAW;;IACvD,MAAM,IAAI,GAAG,MAAM,CAAC,MAAA,MAAA,GAAG,CAAC,WAAW,mCAAI,GAAG,CAAC,GAAG,mCAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACpE,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM,IAAI,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QACtD,GAAG,CAAC,OAAO,GAAG,GAAG,CAAC;IACpB,CAAC;AACH,CAAC","sourcesContent":["import express from 'express';\n\n/**\n * Largest JSON body the server accepts. `Server.call` sends its arguments as\n * one JSON document, and some callers (bulk imports, base64 file payloads)\n * send far more than the 100kb default.\n */\nexport const JSON_BODY_LIMIT = '50mb';\n\n/**\n * The request body parser LinkedServer mounts in front of every route.\n *\n * It is Express's own `express.json()`, i.e. the body-parser 1.x that ships\n * inside Express 4 — the server does not depend on body-parser directly. It\n * parses `application/json` only: multipart uploads (handled with formidable\n * by the upload utilities) and urlencoded forms pass through with their stream\n * unread. Changing parser, or moving to Express 5 (body-parser 2), must keep\n * the behaviour pinned by `json-body-parser.test.ts`.\n */\nexport function createJsonBodyParser() {\n  return express.json({ limit: JSON_BODY_LIMIT, verify: keepRawBody });\n}\n\n/** The routes whose handlers get the body as received, on `request.rawBody`. */\nconst RAW_BODY_PATHS = new Set(['/api/select-raw']);\n\n/**\n * Keep the unparsed bytes of a raw SPARQL request on `request.rawBody`, so a\n * raw query authorizer (`registerRawQueryAuthorizer` in server-utils) can\n * verify a signature over the exact body. Only for those routes: every other\n * body is parsed and its bytes dropped as before.\n */\nfunction keepRawBody(req: any, _res: unknown, buf: Buffer) {\n  const path = String(req.originalUrl ?? req.url ?? '').split('?')[0];\n  if (req.method === 'POST' && RAW_BODY_PATHS.has(path)) {\n    req.rawBody = buf;\n  }\n}\n"]}

package/lib/esm/utils/queryPlane.d.ts

@@ -0,0 +1,58 @@
+import { type ProtectedNodeCheck, type ProtectedNodeProbe, type QueryOperation } from '@_linked/server-utils/utils/QueryAccess';
+/**
+ * Whether DSL-JSON carries a query-context reference (`{"@ctx": name}`) in any
+ * position: a select or count subject, an update target, a delete id, a
+ * where-clause operand or a mutation field value. Every DSL-JSON decoder in
+ * core reads a context reference from this one key.
+ */
+export declare function containsContextRef(json: unknown): boolean;
+/**
+ * A rehydrated query builder from the DSL-JSON a client sent. The result is
+ * what the store runs, so the access check and the store see the same query.
+ * A body that is not a query answers 400.
+ *
+ * A query-context reference (`{"@ctx": "user"}`) also answers 400. Core
+ * resolves one at lowering time against a process-wide context map, which on a
+ * server holds whatever some code last set there, not the caller's identity,
+ * and lowering runs twice (once for the access check, once in the store), so
+ * the two could even resolve it differently. A query built from client JSON
+ * names its nodes by id.
+ *
+ * Without context references, lowering a rehydrated builder is a pure function
+ * of the builder (closed and never mutated after `fromJSON`) and the shape
+ * registry: the IR `authorizeGenericQuery` checks is the IR the store lowers
+ * from the same builder.
+ */
+export declare function toQueryBuilder(query: any): any;
+/** The lowered IR of a query, or `undefined` when it cannot be lowered (refused). */
+export declare function lowerForAccessCheck(builder: any): unknown;
+/**
+ * The `ASK` that answers a protected-node check: is any node the mutation would
+ * write or delete typed with a protected class, or a subclass of one?
+ * `undefined` when there is nothing to ask.
+ */
+export declare function protectedNodeAsk(check: ProtectedNodeCheck): string | undefined;
+/**
+ * The default protected-node lookup: one `ASK` on the dataset the mutation's
+ * shape routes to (run in the current call's context, so a routing dataset
+ * resolves it exactly as it will resolve the mutation). A dataset that cannot
+ * run SPARQL (`rawQuery`) cannot be checked, and the mutation is refused.
+ */
+export declare const askProtectedNodes: ProtectedNodeProbe;
+/**
+ * Replace the protected-node lookup (see `checkQueryAccess`): an app whose
+ * protected nodes live in a known store can answer it there. Pass `undefined`
+ * to restore the default `ASK`.
+ */
+export declare function setProtectedNodeProbe(fn: ProtectedNodeProbe | undefined): void;
+/**
+ * Check `builder` (rehydrated from `query` with `toQueryBuilder`) against the
+ * generic-plane rules. Throws a `ServerCallError` (400/401/403) when the current
+ * call may not run it; the caller then hands the same builder to the store.
+ *
+ * Deliberately returns nothing: a query builder is a thenable, so resolving an
+ * async function with one would run it.
+ */
+export declare function authorizeGenericQuery(operation: QueryOperation, query: unknown, builder: any, endpoint: string): Promise<void>;
+/** Check a raw SPARQL query; see `registerRawQueryAuthorizer`. */
+export declare function authorizeRawQuery(query: unknown, endpoint: string): Promise<void>;

package/lib/esm/utils/queryPlane.js

@@ -0,0 +1,206 @@
+/**
+ * Authorization for the generic query plane: the endpoints that run a query the
+ * client built (`LincdServerBackendProvider.*Query` behind
+ * `/call/@_linked/server/*Query`, and `LincdAPI` `post_*` behind `/api/*`).
+ *
+ * The rules themselves (protected shapes, authorizers) are registered through
+ * `@_linked/server-utils/utils/QueryAccess`; see `checkQueryAccess` there for the
+ * order they apply in. This module turns the incoming query into the builder the
+ * store runs and the IR the rules read, and answers the rules' protected-node
+ * lookup with a SPARQL `ASK` against the store the mutation routes to.
+ */
+import { fromJSON } from '@_linked/core';
+import { lower } from '@_linked/core/queries/lower';
+import { LinkedStorage } from '@_linked/core/utils/LinkedStorage';
+import { getShapeClass } from '@_linked/core/utils/ShapeClass';
+import { checkQueryAccess, } from '@_linked/server-utils/utils/QueryAccess';
+import { ServerCallError } from '@_linked/server-utils/utils/ServerCallError';
+import { getRpcExposureMode } from './rpcExposure.js';
+/** The DSL-JSON tag of a query-context reference (`CONTEXT_REF_KEY` in core). */
+const CONTEXT_REF_KEY = '@ctx';
+/**
+ * Whether DSL-JSON carries a query-context reference (`{"@ctx": name}`) in any
+ * position: a select or count subject, an update target, a delete id, a
+ * where-clause operand or a mutation field value. Every DSL-JSON decoder in
+ * core reads a context reference from this one key.
+ */
+export function containsContextRef(json) {
+    const seen = new Set();
+    const stack = [json];
+    while (stack.length) {
+        const value = stack.pop();
+        if (!value || typeof value !== 'object' || seen.has(value))
+            continue;
+        seen.add(value);
+        if (Array.isArray(value)) {
+            for (const item of value)
+                stack.push(item);
+            continue;
+        }
+        if (Object.prototype.hasOwnProperty.call(value, CONTEXT_REF_KEY))
+            return true;
+        for (const key of Object.keys(value))
+            stack.push(value[key]);
+    }
+    return false;
+}
+/**
+ * A rehydrated query builder from the DSL-JSON a client sent. The result is
+ * what the store runs, so the access check and the store see the same query.
+ * A body that is not a query answers 400.
+ *
+ * A query-context reference (`{"@ctx": "user"}`) also answers 400. Core
+ * resolves one at lowering time against a process-wide context map, which on a
+ * server holds whatever some code last set there, not the caller's identity,
+ * and lowering runs twice (once for the access check, once in the store), so
+ * the two could even resolve it differently. A query built from client JSON
+ * names its nodes by id.
+ *
+ * Without context references, lowering a rehydrated builder is a pure function
+ * of the builder (closed and never mutated after `fromJSON`) and the shape
+ * registry: the IR `authorizeGenericQuery` checks is the IR the store lowers
+ * from the same builder.
+ */
+export function toQueryBuilder(query) {
+    // A live builder passed by backend code (never a plain object from JSON).
+    if (query &&
+        typeof query === 'object' &&
+        Object.getPrototypeOf(query) !== Object.prototype &&
+        typeof query.__queryKind === 'string') {
+        return query;
+    }
+    if (containsContextRef(query)) {
+        throw new ServerCallError(400, 'Query context references (@ctx) are not accepted by the generic query endpoints');
+    }
+    try {
+        const builder = fromJSON(query);
+        if (!builder || typeof builder !== 'object')
+            throw new Error('not a query');
+        return builder;
+    }
+    catch (_a) {
+        throw new ServerCallError(400, 'Invalid query');
+    }
+}
+/** The lowered IR of a query, or `undefined` when it cannot be lowered (refused). */
+export function lowerForAccessCheck(builder) {
+    try {
+        return lower(builder);
+    }
+    catch (_a) {
+        return undefined;
+    }
+}
+const RDF_TYPE = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#type';
+const RDFS_SUBCLASS_OF = 'http://www.w3.org/2000/01/rdf-schema#subClassOf';
+/** `<iri>`, refusing anything that is not a plain absolute IRI. */
+function iriTerm(value) {
+    if (typeof value !== 'string' ||
+        !/^[A-Za-z][A-Za-z0-9+.-]*:[^\s<>"{}|^`\\\u0000-\u001f\u007f]*$/.test(value)) {
+        throw new ServerCallError(400, 'Invalid node id');
+    }
+    return `<${value}>`;
+}
+/**
+ * The `ASK` that answers a protected-node check: is any node the mutation would
+ * write or delete typed with a protected class, or a subclass of one?
+ * `undefined` when there is nothing to ask.
+ */
+export function protectedNodeAsk(check) {
+    if (!check.classes.length)
+        return undefined;
+    const branches = [];
+    const owned = check.containsPredicates.length
+        ? '(' + check.containsPredicates.map(iriTerm).join('|') + ')+'
+        : undefined;
+    if (check.ids.length) {
+        branches.push(`{ VALUES ?n { ${check.ids.map(iriTerm).join(' ')} } }`);
+    }
+    if (owned && check.ownerIds.length) {
+        branches.push(`{ VALUES ?owner { ${check.ownerIds.map(iriTerm).join(' ')} } ?owner ${owned} ?n . }`);
+    }
+    for (const cls of check.scanClasses) {
+        branches.push(`{ ?n <${RDF_TYPE}> ${iriTerm(cls)} . }`);
+        if (owned)
+            branches.push(`{ ?s <${RDF_TYPE}> ${iriTerm(cls)} . ?s ${owned} ?n . }`);
+    }
+    if (!branches.length)
+        return undefined;
+    return (`ASK WHERE {\n  ${branches.join('\n  UNION ')}\n` +
+        `  ?n <${RDF_TYPE}> ?t .\n` +
+        `  VALUES ?c { ${check.classes.map(iriTerm).join(' ')} }\n` +
+        `  ?t <${RDFS_SUBCLASS_OF}>* ?c .\n}`);
+}
+/**
+ * The default protected-node lookup: one `ASK` on the dataset the mutation's
+ * shape routes to (run in the current call's context, so a routing dataset
+ * resolves it exactly as it will resolve the mutation). A dataset that cannot
+ * run SPARQL (`rawQuery`) cannot be checked, and the mutation is refused.
+ */
+export const askProtectedNodes = async (check) => {
+    var _a;
+    const sparql = protectedNodeAsk(check);
+    if (!sparql)
+        return false;
+    let shapeClass;
+    try {
+        shapeClass = getShapeClass(check.shape);
+    }
+    catch (_b) {
+        shapeClass = undefined;
+    }
+    const dataset = (_a = LinkedStorage.getDatasetForShapeClass(shapeClass)) !== null && _a !== void 0 ? _a : LinkedStorage.getDefaultDataset();
+    if (!dataset || typeof dataset.rawQuery !== 'function') {
+        throw new Error(`the dataset for ${check.shape} cannot run SPARQL, so the nodes this mutation writes cannot be checked`);
+    }
+    const json = await dataset.rawQuery(sparql);
+    if (typeof (json === null || json === void 0 ? void 0 : json.boolean) !== 'boolean') {
+        throw new Error('the dataset did not answer the ASK with a boolean');
+    }
+    return json.boolean;
+};
+let probe = askProtectedNodes;
+/**
+ * Replace the protected-node lookup (see `checkQueryAccess`): an app whose
+ * protected nodes live in a known store can answer it there. Pass `undefined`
+ * to restore the default `ASK`.
+ */
+export function setProtectedNodeProbe(fn) {
+    if (fn !== undefined && typeof fn !== 'function') {
+        throw new TypeError('setProtectedNodeProbe: expected a function');
+    }
+    probe = fn !== null && fn !== void 0 ? fn : askProtectedNodes;
+}
+/**
+ * Check `builder` (rehydrated from `query` with `toQueryBuilder`) against the
+ * generic-plane rules. Throws a `ServerCallError` (400/401/403) when the current
+ * call may not run it; the caller then hands the same builder to the store.
+ *
+ * Deliberately returns nothing: a query builder is a thenable, so resolving an
+ * async function with one would run it.
+ */
+export async function authorizeGenericQuery(operation, query, builder, endpoint) {
+    await checkQueryAccess({
+        operation,
+        query,
+        ir: lowerForAccessCheck(builder),
+        mode: getRpcExposureMode(),
+        endpoint,
+        probeProtectedNodes: probe,
+    });
+}
+/** Check a raw SPARQL query; see `registerRawQueryAuthorizer`. */
+export async function authorizeRawQuery(query, endpoint) {
+    if (typeof query !== 'string') {
+        throw new ServerCallError(400, 'Invalid query');
+    }
+    await checkQueryAccess({
+        operation: 'select',
+        query,
+        ir: undefined,
+        raw: true,
+        mode: getRpcExposureMode(),
+        endpoint,
+    });
+}
+//# sourceMappingURL=queryPlane.js.map

package/lib/esm/utils/queryPlane.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryPlane.js","sourceRoot":"","sources":["../../../src/utils/queryPlane.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Authorization for the generic query plane: the endpoints that run a query the\n * client built (`LincdServerBackendProvider.*Query` behind\n * `/call/@_linked/server/*Query`, and `LincdAPI` `post_*` behind `/api/*`).\n *\n * The rules themselves (protected shapes, authorizers) are registered through\n * `@_linked/server-utils/utils/QueryAccess`; see `checkQueryAccess` there for the\n * order they apply in. This module turns the incoming query into the builder the\n * store runs and the IR the rules read, and answers the rules' protected-node\n * lookup with a SPARQL `ASK` against the store the mutation routes to.\n */\nimport { fromJSON } from '@_linked/core';\nimport { lower } from '@_linked/core/queries/lower';\nimport { LinkedStorage } from '@_linked/core/utils/LinkedStorage';\nimport { getShapeClass } from '@_linked/core/utils/ShapeClass';\nimport {\n  checkQueryAccess,\n  type ProtectedNodeCheck,\n  type ProtectedNodeProbe,\n  type QueryOperation,\n} from '@_linked/server-utils/utils/QueryAccess';\nimport { ServerCallError } from '@_linked/server-utils/utils/ServerCallError';\nimport { getRpcExposureMode } from './rpcExposure.js';\n\n/** The DSL-JSON tag of a query-context reference (`CONTEXT_REF_KEY` in core). */\nconst CONTEXT_REF_KEY = '@ctx';\n\n/**\n * Whether DSL-JSON carries a query-context reference (`{\"@ctx\": name}`) in any\n * position: a select or count subject, an update target, a delete id, a\n * where-clause operand or a mutation field value. Every DSL-JSON decoder in\n * core reads a context reference from this one key.\n */\nexport function containsContextRef(json: unknown): boolean {\n  const seen = new Set<object>();\n  const stack: unknown[] = [json];\n  while (stack.length) {\n    const value = stack.pop();\n    if (!value || typeof value !== 'object' || seen.has(value)) continue;\n    seen.add(value);\n    if (Array.isArray(value)) {\n      for (const item of value) stack.push(item);\n      continue;\n    }\n    if (Object.prototype.hasOwnProperty.call(value, CONTEXT_REF_KEY)) return true;\n    for (const key of Object.keys(value)) stack.push((value as any)[key]);\n  }\n  return false;\n}\n\n/**\n * A rehydrated query builder from the DSL-JSON a client sent. The result is\n * what the store runs, so the access check and the store see the same query.\n * A body that is not a query answers 400.\n *\n * A query-context reference (`{\"@ctx\": \"user\"}`) also answers 400. Core\n * resolves one at lowering time against a process-wide context map, which on a\n * server holds whatever some code last set there, not the caller's identity,\n * and lowering runs twice (once for the access check, once in the store), so\n * the two could even resolve it differently. A query built from client JSON\n * names its nodes by id.\n *\n * Without context references, lowering a rehydrated builder is a pure function\n * of the builder (closed and never mutated after `fromJSON`) and the shape\n * registry: the IR `authorizeGenericQuery` checks is the IR the store lowers\n * from the same builder.\n */\nexport function toQueryBuilder(query: any): any {\n  // A live builder passed by backend code (never a plain object from JSON).\n  if (\n    query &&\n    typeof query === 'object' &&\n    Object.getPrototypeOf(query) !== Object.prototype &&\n    typeof query.__queryKind === 'string'\n  ) {\n    return query;\n  }\n  if (containsContextRef(query)) {\n    throw new ServerCallError(\n      400,\n      'Query context references (@ctx) are not accepted by the generic query endpoints'\n    );\n  }\n  try {\n    const builder = fromJSON(query);\n    if (!builder || typeof builder !== 'object') throw new Error('not a query');\n    return builder;\n  } catch {\n    throw new ServerCallError(400, 'Invalid query');\n  }\n}\n\n/** The lowered IR of a query, or `undefined` when it cannot be lowered (refused). */\nexport function lowerForAccessCheck(builder: any): unknown {\n  try {\n    return lower(builder);\n  } catch {\n    return undefined;\n  }\n}\n\nconst RDF_TYPE = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#type';\nconst RDFS_SUBCLASS_OF = 'http://www.w3.org/2000/01/rdf-schema#subClassOf';\n\n/** `<iri>`, refusing anything that is not a plain absolute IRI. */\nfunction iriTerm(value: unknown): string {\n  if (\n    typeof value !== 'string' ||\n    !/^[A-Za-z][A-Za-z0-9+.-]*:[^\\s<>\"{}|^`\\\\\\u0000-\\u001f\\u007f]*$/.test(value)\n  ) {\n    throw new ServerCallError(400, 'Invalid node id');\n  }\n  return `<${value}>`;\n}\n\n/**\n * The `ASK` that answers a protected-node check: is any node the mutation would\n * write or delete typed with a protected class, or a subclass of one?\n * `undefined` when there is nothing to ask.\n */\nexport function protectedNodeAsk(check: ProtectedNodeCheck): string | undefined {\n  if (!check.classes.length) return undefined;\n  const branches: string[] = [];\n  const owned = check.containsPredicates.length\n    ? '(' + check.containsPredicates.map(iriTerm).join('|') + ')+'\n    : undefined;\n  if (check.ids.length) {\n    branches.push(`{ VALUES ?n { ${check.ids.map(iriTerm).join(' ')} } }`);\n  }\n  if (owned && check.ownerIds.length) {\n    branches.push(\n      `{ VALUES ?owner { ${check.ownerIds.map(iriTerm).join(' ')} } ?owner ${owned} ?n . }`\n    );\n  }\n  for (const cls of check.scanClasses) {\n    branches.push(`{ ?n <${RDF_TYPE}> ${iriTerm(cls)} . }`);\n    if (owned) branches.push(`{ ?s <${RDF_TYPE}> ${iriTerm(cls)} . ?s ${owned} ?n . }`);\n  }\n  if (!branches.length) return undefined;\n  return (\n    `ASK WHERE {\\n  ${branches.join('\\n  UNION ')}\\n` +\n    `  ?n <${RDF_TYPE}> ?t .\\n` +\n    `  VALUES ?c { ${check.classes.map(iriTerm).join(' ')} }\\n` +\n    `  ?t <${RDFS_SUBCLASS_OF}>* ?c .\\n}`\n  );\n}\n\n/**\n * The default protected-node lookup: one `ASK` on the dataset the mutation's\n * shape routes to (run in the current call's context, so a routing dataset\n * resolves it exactly as it will resolve the mutation). A dataset that cannot\n * run SPARQL (`rawQuery`) cannot be checked, and the mutation is refused.\n */\nexport const askProtectedNodes: ProtectedNodeProbe = async (check) => {\n  const sparql = protectedNodeAsk(check);\n  if (!sparql) return false;\n  let shapeClass: any;\n  try {\n    shapeClass = getShapeClass(check.shape as any);\n  } catch {\n    shapeClass = undefined;\n  }\n  const dataset: any =\n    LinkedStorage.getDatasetForShapeClass(shapeClass) ?? LinkedStorage.getDefaultDataset();\n  if (!dataset || typeof dataset.rawQuery !== 'function') {\n    throw new Error(\n      `the dataset for ${check.shape} cannot run SPARQL, so the nodes this mutation writes cannot be checked`\n    );\n  }\n  const json = await dataset.rawQuery(sparql);\n  if (typeof json?.boolean !== 'boolean') {\n    throw new Error('the dataset did not answer the ASK with a boolean');\n  }\n  return json.boolean;\n};\n\nlet probe: ProtectedNodeProbe = askProtectedNodes;\n\n/**\n * Replace the protected-node lookup (see `checkQueryAccess`): an app whose\n * protected nodes live in a known store can answer it there. Pass `undefined`\n * to restore the default `ASK`.\n */\nexport function setProtectedNodeProbe(fn: ProtectedNodeProbe | undefined): void {\n  if (fn !== undefined && typeof fn !== 'function') {\n    throw new TypeError('setProtectedNodeProbe: expected a function');\n  }\n  probe = fn ?? askProtectedNodes;\n}\n\n/**\n * Check `builder` (rehydrated from `query` with `toQueryBuilder`) against the\n * generic-plane rules. Throws a `ServerCallError` (400/401/403) when the current\n * call may not run it; the caller then hands the same builder to the store.\n *\n * Deliberately returns nothing: a query builder is a thenable, so resolving an\n * async function with one would run it.\n */\nexport async function authorizeGenericQuery(\n  operation: QueryOperation,\n  query: unknown,\n  builder: any,\n  endpoint: string\n): Promise<void> {\n  await checkQueryAccess({\n    operation,\n    query,\n    ir: lowerForAccessCheck(builder),\n    mode: getRpcExposureMode(),\n    endpoint,\n    probeProtectedNodes: probe,\n  });\n}\n\n/** Check a raw SPARQL query; see `registerRawQueryAuthorizer`. */\nexport async function authorizeRawQuery(query: unknown, endpoint: string): Promise<void> {\n  if (typeof query !== 'string') {\n    throw new ServerCallError(400, 'Invalid query');\n  }\n  await checkQueryAccess({\n    operation: 'select',\n    query,\n    ir: undefined,\n    raw: true,\n    mode: getRpcExposureMode(),\n    endpoint,\n  });\n}\n"]}