@wildo-ai/saas-backend-lib 1.1.1 → 1.1.3

package/dist/esm/files/storage/application-storage-key.backend.utils.d.ts

@@ -0,0 +1,109 @@
+/**
+ * The ONE composer every path-based storage provider addresses a blob with.
+ *
+ * ## Why this module exists rather than a second implementation per provider
+ *
+ * The key shape is not decoration: `<scope>/<scopeId>` is what makes ONE TENANT's blobs a PREFIX,
+ * and therefore what makes erasure, orphan sweeps, per-tenant listing and credential confinement
+ * expressible at all. A provider that composes its own shape is a deployment where none of those
+ * exist — silently, because nothing fails when a prefix is merely absent.
+ *
+ * That is exactly what had happened: the managed provider carried the tenant-scoped shape while the
+ * local-directory provider composed `[applicationId]/[folderPath]/<leaf>` from the field's
+ * declarative binding alone, so routing a field to local storage produced a store with no tenant
+ * structure whatsoever. Two implementations that "must agree" agreed for as long as nobody edited
+ * either. So the composition lives here, once, and both providers call it.
+ *
+ * ## What is NOT here
+ *
+ * Provider-specific framing stays with the provider:
+ * - the managed provider prepends its configured `bucketPrefix` (an object-store namespacing knob
+ *   with no filesystem meaning) and applies its textual stored-`storageRef` prefix guard;
+ * - the local provider resolves the returned relative key against its base directory and applies
+ *   its filesystem containment check.
+ *
+ * What is shared is the ANSWER to "where does this blob live", which is the part that must not
+ * differ between two providers serving the same authored `z_file()` binding.
+ */
+import type { FileScopeIdentifiers, ResourceType } from '@wildo-ai/saas-models';
+import type { StorageUploadOptions } from './file-storage-provider.types';
+/**
+ * The key segment for a blob with no resource type.
+ *
+ * A literal rather than a resource name, and prefixed with `_` so it can never collide with a
+ * value `resolveSharedPersistenceCollectionName` produces — that function returns collection
+ * names, which never start with an underscore.
+ */
+export declare const UNLINKED_STORAGE_SEGMENT = "_unlinked";
+/**
+ * The `<scope>/<scopeId>` segments of a storage key.
+ *
+ * This is what makes ONE TENANT's blobs a prefix. Without it every organization's files of a given
+ * resource share a single prefix, so erasure, orphan sweeps and "who owns this object" all become
+ * per-row database work instead of prefix operations — and no per-tenant confinement is expressible
+ * at all. (That was the state of the managed provider until 2026-08-14: the approved shape carried
+ * these segments and the first implementation dropped them. The local-directory provider never had
+ * them at all until this module existed.)
+ *
+ * Always emits BOTH segments, including for APPLICATION scope where the id repeats the one already
+ * in the prefix. The redundancy is deliberate: one key shape, no branch, nothing that can produce a
+ * second layout. A parser can always take the last three segments as scope/scopeId/fileId.
+ */
+export declare function resolveStorageScopeSegments(scope: FileScopeIdentifiers | undefined, applicationId: string): {
+    scope: string;
+    scopeId: string;
+};
+/**
+ * The caller-authored tail of a key: `[folderPath/]<fileName|fileId>`.
+ *
+ * Returns the empty string when nothing survives — the caller raises
+ * `FILE_STORAGE_KEY_COMPOSITION_FAILED` with its own execution context, which this module does not
+ * have.
+ */
+export declare function composeStorageLeafPath(fileId: string, options?: StorageUploadOptions): string;
+/**
+ * Does `candidate` contain a whole `.` or `..` path segment?
+ *
+ * ## Why a TEXTUAL check, beside a provider's own containment guard
+ *
+ * The local provider's guard resolves the path and checks it stays under the base directory, which
+ * is strictly stronger for the question "does this escape the store". It is strictly WEAKER for the
+ * question this key shape exists to answer: once a key carries a six-segment
+ * `applications/<app>/files/<resource>/<scope>/<scopeId>/` prefix, a `..` no longer has to escape
+ * the store to do damage — it only has to climb out of the TENANT prefix and land under a
+ * different one, which the containment check happily admits because the destination is still
+ * inside the base.
+ *
+ * The managed provider states the same thing from the other side (its stored-ref prefix check is
+ * textual, so `…/x/../../../elsewhere/y` satisfies it). Both providers therefore refuse a `.`/`..`
+ * SEGMENT in the composed key, and the verdict for one authored value no longer depends on which
+ * provider a deployment binds.
+ *
+ * Only a WHOLE segment counts. `v1.2.3`, `..config` and `file..name.txt` are ordinary names, and a
+ * substring match on `..` would refuse all three — an over-refusal invisible until an application
+ * authors a versioned folder.
+ */
+export declare function storageKeyHasTraversalSegment(candidate: string): boolean;
+/**
+ * The application-scoped, resource-scoped, tenant-scoped key for a blob.
+ *
+ * `applications/<applicationId>/files/<storageName>/<scope>/<scopeId>/<leafPath>`
+ *
+ * The managed provider prepends its bucket prefix to this; the local provider resolves it against
+ * its base directory. Nothing else may re-derive it — the shape is the tenant boundary, and a
+ * second derivation is a second boundary.
+ */
+export declare function composeApplicationStorageKey(args: {
+    applicationId: string;
+    /** `[folderPath/]<fileName|fileId>` — see {@link composeStorageLeafPath}. */
+    leafPath: string;
+    /**
+     * The resource this blob belongs to. Absent ⇒ {@link UNLINKED_STORAGE_SEGMENT}, an explicit
+     * staging segment rather than a fallthrough: late LINKING is allowed (the row's
+     * `linkedResourceId` fills in later), late TYPE declaration is not, because the key is derived
+     * once at create and the blob never moves.
+     */
+    linkedResourceType?: ResourceType;
+    scope?: FileScopeIdentifiers;
+}): string;
+//# sourceMappingURL=application-storage-key.backend.utils.d.ts.map

package/dist/esm/files/storage/application-storage-key.backend.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"application-storage-key.backend.utils.d.ts","sourceRoot":"","sources":["../../../../../src/files/storage/application-storage-key.backend.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,KAAK,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAEhF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAE1E;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,cAAc,CAAC;AAEpD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,oBAAoB,GAAG,SAAS,EACvC,aAAa,EAAE,MAAM,GACpB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAcpC;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,MAAM,CAO7F;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,6BAA6B,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAExE;AAED;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAAC,IAAI,EAAE;IACjD,aAAa,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,YAAY,CAAC;IAClC,KAAK,CAAC,EAAE,oBAAoB,CAAC;CAC9B,GAAG,MAAM,CAYT"}

package/dist/esm/files/storage/application-storage-key.backend.utils.js

@@ -0,0 +1,123 @@
+/**
+ * The ONE composer every path-based storage provider addresses a blob with.
+ *
+ * ## Why this module exists rather than a second implementation per provider
+ *
+ * The key shape is not decoration: `<scope>/<scopeId>` is what makes ONE TENANT's blobs a PREFIX,
+ * and therefore what makes erasure, orphan sweeps, per-tenant listing and credential confinement
+ * expressible at all. A provider that composes its own shape is a deployment where none of those
+ * exist — silently, because nothing fails when a prefix is merely absent.
+ *
+ * That is exactly what had happened: the managed provider carried the tenant-scoped shape while the
+ * local-directory provider composed `[applicationId]/[folderPath]/<leaf>` from the field's
+ * declarative binding alone, so routing a field to local storage produced a store with no tenant
+ * structure whatsoever. Two implementations that "must agree" agreed for as long as nobody edited
+ * either. So the composition lives here, once, and both providers call it.
+ *
+ * ## What is NOT here
+ *
+ * Provider-specific framing stays with the provider:
+ * - the managed provider prepends its configured `bucketPrefix` (an object-store namespacing knob
+ *   with no filesystem meaning) and applies its textual stored-`storageRef` prefix guard;
+ * - the local provider resolves the returned relative key against its base directory and applies
+ *   its filesystem containment check.
+ *
+ * What is shared is the ANSWER to "where does this blob live", which is the part that must not
+ * differ between two providers serving the same authored `z_file()` binding.
+ */
+import { ResourcePrimaryScope, resolveSharedPersistenceCollectionName } from '@wildo-ai/saas-models';
+import { API_ROUTES_BACKEND_DEFINITIONS } from '../../requests/models/api-routes.backend.defintions.js';
+/**
+ * The key segment for a blob with no resource type.
+ *
+ * A literal rather than a resource name, and prefixed with `_` so it can never collide with a
+ * value `resolveSharedPersistenceCollectionName` produces — that function returns collection
+ * names, which never start with an underscore.
+ */
+export const UNLINKED_STORAGE_SEGMENT = '_unlinked';
+/**
+ * The `<scope>/<scopeId>` segments of a storage key.
+ *
+ * This is what makes ONE TENANT's blobs a prefix. Without it every organization's files of a given
+ * resource share a single prefix, so erasure, orphan sweeps and "who owns this object" all become
+ * per-row database work instead of prefix operations — and no per-tenant confinement is expressible
+ * at all. (That was the state of the managed provider until 2026-08-14: the approved shape carried
+ * these segments and the first implementation dropped them. The local-directory provider never had
+ * them at all until this module existed.)
+ *
+ * Always emits BOTH segments, including for APPLICATION scope where the id repeats the one already
+ * in the prefix. The redundancy is deliberate: one key shape, no branch, nothing that can produce a
+ * second layout. A parser can always take the last three segments as scope/scopeId/fileId.
+ */
+export function resolveStorageScopeSegments(scope, applicationId) {
+    // The SEGMENT IS the enum value — `ResourcePrimaryScope.ORGANIZATIONS === 'organizations'`. Using
+    // the enum directly keeps one vocabulary: a parallel string table here would be a second source
+    // that silently drifts the day a scope is added or renamed.
+    if (scope?.primaryScope === ResourcePrimaryScope.ORGANIZATIONS && scope.organizationId) {
+        return { scope: ResourcePrimaryScope.ORGANIZATIONS, scopeId: scope.organizationId };
+    }
+    if (scope?.primaryScope === ResourcePrimaryScope.USER_SELF && scope.userId) {
+        return { scope: ResourcePrimaryScope.USER_SELF, scopeId: scope.userId };
+    }
+    // APPLICATION scope, or a scope whose id is missing — fall back to the application. Never throw:
+    // a key must always be derivable, and an application-scoped key is the correct conservative answer
+    // (it is the narrowest scope every file provably has).
+    return { scope: ResourcePrimaryScope.APPLICATION, scopeId: applicationId };
+}
+/**
+ * The caller-authored tail of a key: `[folderPath/]<fileName|fileId>`.
+ *
+ * Returns the empty string when nothing survives — the caller raises
+ * `FILE_STORAGE_KEY_COMPOSITION_FAILED` with its own execution context, which this module does not
+ * have.
+ */
+export function composeStorageLeafPath(fileId, options) {
+    const leafName = options?.fileName?.trim() || fileId;
+    const folderPath = options?.folderPath?.trim();
+    if (!leafName) {
+        return '';
+    }
+    return folderPath ? `${folderPath}/${leafName}` : leafName;
+}
+/**
+ * Does `candidate` contain a whole `.` or `..` path segment?
+ *
+ * ## Why a TEXTUAL check, beside a provider's own containment guard
+ *
+ * The local provider's guard resolves the path and checks it stays under the base directory, which
+ * is strictly stronger for the question "does this escape the store". It is strictly WEAKER for the
+ * question this key shape exists to answer: once a key carries a six-segment
+ * `applications/<app>/files/<resource>/<scope>/<scopeId>/` prefix, a `..` no longer has to escape
+ * the store to do damage — it only has to climb out of the TENANT prefix and land under a
+ * different one, which the containment check happily admits because the destination is still
+ * inside the base.
+ *
+ * The managed provider states the same thing from the other side (its stored-ref prefix check is
+ * textual, so `…/x/../../../elsewhere/y` satisfies it). Both providers therefore refuse a `.`/`..`
+ * SEGMENT in the composed key, and the verdict for one authored value no longer depends on which
+ * provider a deployment binds.
+ *
+ * Only a WHOLE segment counts. `v1.2.3`, `..config` and `file..name.txt` are ordinary names, and a
+ * substring match on `..` would refuse all three — an over-refusal invisible until an application
+ * authors a versioned folder.
+ */
+export function storageKeyHasTraversalSegment(candidate) {
+    return candidate.split('/').some((segment) => segment === '.' || segment === '..');
+}
+/**
+ * The application-scoped, resource-scoped, tenant-scoped key for a blob.
+ *
+ * `applications/<applicationId>/files/<storageName>/<scope>/<scopeId>/<leafPath>`
+ *
+ * The managed provider prepends its bucket prefix to this; the local provider resolves it against
+ * its base directory. Nothing else may re-derive it — the shape is the tenant boundary, and a
+ * second derivation is a second boundary.
+ */
+export function composeApplicationStorageKey(args) {
+    const storageName = args.linkedResourceType
+        ? resolveSharedPersistenceCollectionName(args.linkedResourceType)
+        : UNLINKED_STORAGE_SEGMENT;
+    const { scope, scopeId } = resolveStorageScopeSegments(args.scope, args.applicationId);
+    return API_ROUTES_BACKEND_DEFINITIONS.FILE_STORAGE.STORAGE_KEY_APPLICATION_FILE(args.applicationId, args.leafPath, storageName, scope, scopeId);
+}
+//# sourceMappingURL=application-storage-key.backend.utils.js.map

package/dist/esm/files/storage/application-storage-key.backend.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"application-storage-key.backend.utils.js","sourceRoot":"","sources":["../../../../../src/files/storage/application-storage-key.backend.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,oBAAoB,EAAE,sCAAsC,EAAE,MAAM,uBAAuB,CAAC;AAErG,OAAO,EAAE,8BAA8B,EAAE,MAAM,kEAAkE,CAAC;AAGlH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,WAAW,CAAC;AAEpD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,2BAA2B,CACzC,KAAuC,EACvC,aAAqB;IAErB,kGAAkG;IAClG,gGAAgG;IAChG,4DAA4D;IAC5D,IAAI,KAAK,EAAE,YAAY,KAAK,oBAAoB,CAAC,aAAa,IAAI,KAAK,CAAC,cAAc,EAAE,CAAC;QACvF,OAAO,EAAE,KAAK,EAAE,oBAAoB,CAAC,aAAa,EAAE,OAAO,EAAE,KAAK,CAAC,cAAc,EAAE,CAAC;IACtF,CAAC;IACD,IAAI,KAAK,EAAE,YAAY,KAAK,oBAAoB,CAAC,SAAS,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;QAC3E,OAAO,EAAE,KAAK,EAAE,oBAAoB,CAAC,SAAS,EAAE,OAAO,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;IAC1E,CAAC;IACD,iGAAiG;IACjG,mGAAmG;IACnG,uDAAuD;IACvD,OAAO,EAAE,KAAK,EAAE,oBAAoB,CAAC,WAAW,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC;AAC7E,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAAc,EAAE,OAA8B;IACnF,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,MAAM,CAAC;IACrD,MAAM,UAAU,GAAG,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;IAC/C,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,IAAI,QAAQ,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC7D,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,6BAA6B,CAAC,SAAiB;IAC7D,OAAO,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,KAAK,GAAG,IAAI,OAAO,KAAK,IAAI,CAAC,CAAC;AACrF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,4BAA4B,CAAC,IAY5C;IACC,MAAM,WAAW,GAAG,IAAI,CAAC,kBAAkB;QACzC,CAAC,CAAC,sCAAsC,CAAC,IAAI,CAAC,kBAAkB,CAAC;QACjE,CAAC,CAAC,wBAAwB,CAAC;IAC7B,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,2BAA2B,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC;IACvF,OAAO,8BAA8B,CAAC,YAAY,CAAC,4BAA4B,CAC7E,IAAI,CAAC,aAAa,EAClB,IAAI,CAAC,QAAQ,EACb,WAAW,EACX,KAAK,EACL,OAAO,CACR,CAAC;AACJ,CAAC","sourcesContent":["/**\n * The ONE composer every path-based storage provider addresses a blob with.\n *\n * ## Why this module exists rather than a second implementation per provider\n *\n * The key shape is not decoration: `<scope>/<scopeId>` is what makes ONE TENANT's blobs a PREFIX,\n * and therefore what makes erasure, orphan sweeps, per-tenant listing and credential confinement\n * expressible at all. A provider that composes its own shape is a deployment where none of those\n * exist — silently, because nothing fails when a prefix is merely absent.\n *\n * That is exactly what had happened: the managed provider carried the tenant-scoped shape while the\n * local-directory provider composed `[applicationId]/[folderPath]/<leaf>` from the field's\n * declarative binding alone, so routing a field to local storage produced a store with no tenant\n * structure whatsoever. Two implementations that \"must agree\" agreed for as long as nobody edited\n * either. So the composition lives here, once, and both providers call it.\n *\n * ## What is NOT here\n *\n * Provider-specific framing stays with the provider:\n * - the managed provider prepends its configured `bucketPrefix` (an object-store namespacing knob\n *   with no filesystem meaning) and applies its textual stored-`storageRef` prefix guard;\n * - the local provider resolves the returned relative key against its base directory and applies\n *   its filesystem containment check.\n *\n * What is shared is the ANSWER to \"where does this blob live\", which is the part that must not\n * differ between two providers serving the same authored `z_file()` binding.\n */\n\nimport { ResourcePrimaryScope, resolveSharedPersistenceCollectionName } from '@wildo-ai/saas-models';\nimport type { FileScopeIdentifiers, ResourceType } from '@wildo-ai/saas-models';\nimport { API_ROUTES_BACKEND_DEFINITIONS } from '~wildo-backend-lib/requests/models/api-routes.backend.defintions';\nimport type { StorageUploadOptions } from './file-storage-provider.types';\n\n/**\n * The key segment for a blob with no resource type.\n *\n * A literal rather than a resource name, and prefixed with `_` so it can never collide with a\n * value `resolveSharedPersistenceCollectionName` produces — that function returns collection\n * names, which never start with an underscore.\n */\nexport const UNLINKED_STORAGE_SEGMENT = '_unlinked';\n\n/**\n * The `<scope>/<scopeId>` segments of a storage key.\n *\n * This is what makes ONE TENANT's blobs a prefix. Without it every organization's files of a given\n * resource share a single prefix, so erasure, orphan sweeps and \"who owns this object\" all become\n * per-row database work instead of prefix operations — and no per-tenant confinement is expressible\n * at all. (That was the state of the managed provider until 2026-08-14: the approved shape carried\n * these segments and the first implementation dropped them. The local-directory provider never had\n * them at all until this module existed.)\n *\n * Always emits BOTH segments, including for APPLICATION scope where the id repeats the one already\n * in the prefix. The redundancy is deliberate: one key shape, no branch, nothing that can produce a\n * second layout. A parser can always take the last three segments as scope/scopeId/fileId.\n */\nexport function resolveStorageScopeSegments(\n  scope: FileScopeIdentifiers | undefined,\n  applicationId: string,\n): { scope: string; scopeId: string } {\n  // The SEGMENT IS the enum value — `ResourcePrimaryScope.ORGANIZATIONS === 'organizations'`. Using\n  // the enum directly keeps one vocabulary: a parallel string table here would be a second source\n  // that silently drifts the day a scope is added or renamed.\n  if (scope?.primaryScope === ResourcePrimaryScope.ORGANIZATIONS && scope.organizationId) {\n    return { scope: ResourcePrimaryScope.ORGANIZATIONS, scopeId: scope.organizationId };\n  }\n  if (scope?.primaryScope === ResourcePrimaryScope.USER_SELF && scope.userId) {\n    return { scope: ResourcePrimaryScope.USER_SELF, scopeId: scope.userId };\n  }\n  // APPLICATION scope, or a scope whose id is missing — fall back to the application. Never throw:\n  // a key must always be derivable, and an application-scoped key is the correct conservative answer\n  // (it is the narrowest scope every file provably has).\n  return { scope: ResourcePrimaryScope.APPLICATION, scopeId: applicationId };\n}\n\n/**\n * The caller-authored tail of a key: `[folderPath/]<fileName|fileId>`.\n *\n * Returns the empty string when nothing survives — the caller raises\n * `FILE_STORAGE_KEY_COMPOSITION_FAILED` with its own execution context, which this module does not\n * have.\n */\nexport function composeStorageLeafPath(fileId: string, options?: StorageUploadOptions): string {\n  const leafName = options?.fileName?.trim() || fileId;\n  const folderPath = options?.folderPath?.trim();\n  if (!leafName) {\n    return '';\n  }\n  return folderPath ? `${folderPath}/${leafName}` : leafName;\n}\n\n/**\n * Does `candidate` contain a whole `.` or `..` path segment?\n *\n * ## Why a TEXTUAL check, beside a provider's own containment guard\n *\n * The local provider's guard resolves the path and checks it stays under the base directory, which\n * is strictly stronger for the question \"does this escape the store\". It is strictly WEAKER for the\n * question this key shape exists to answer: once a key carries a six-segment\n * `applications/<app>/files/<resource>/<scope>/<scopeId>/` prefix, a `..` no longer has to escape\n * the store to do damage — it only has to climb out of the TENANT prefix and land under a\n * different one, which the containment check happily admits because the destination is still\n * inside the base.\n *\n * The managed provider states the same thing from the other side (its stored-ref prefix check is\n * textual, so `…/x/../../../elsewhere/y` satisfies it). Both providers therefore refuse a `.`/`..`\n * SEGMENT in the composed key, and the verdict for one authored value no longer depends on which\n * provider a deployment binds.\n *\n * Only a WHOLE segment counts. `v1.2.3`, `..config` and `file..name.txt` are ordinary names, and a\n * substring match on `..` would refuse all three — an over-refusal invisible until an application\n * authors a versioned folder.\n */\nexport function storageKeyHasTraversalSegment(candidate: string): boolean {\n  return candidate.split('/').some((segment) => segment === '.' || segment === '..');\n}\n\n/**\n * The application-scoped, resource-scoped, tenant-scoped key for a blob.\n *\n * `applications/<applicationId>/files/<storageName>/<scope>/<scopeId>/<leafPath>`\n *\n * The managed provider prepends its bucket prefix to this; the local provider resolves it against\n * its base directory. Nothing else may re-derive it — the shape is the tenant boundary, and a\n * second derivation is a second boundary.\n */\nexport function composeApplicationStorageKey(args: {\n  applicationId: string;\n  /** `[folderPath/]<fileName|fileId>` — see {@link composeStorageLeafPath}. */\n  leafPath: string;\n  /**\n   * The resource this blob belongs to. Absent ⇒ {@link UNLINKED_STORAGE_SEGMENT}, an explicit\n   * staging segment rather than a fallthrough: late LINKING is allowed (the row's\n   * `linkedResourceId` fills in later), late TYPE declaration is not, because the key is derived\n   * once at create and the blob never moves.\n   */\n  linkedResourceType?: ResourceType;\n  scope?: FileScopeIdentifiers;\n}): string {\n  const storageName = args.linkedResourceType\n    ? resolveSharedPersistenceCollectionName(args.linkedResourceType)\n    : UNLINKED_STORAGE_SEGMENT;\n  const { scope, scopeId } = resolveStorageScopeSegments(args.scope, args.applicationId);\n  return API_ROUTES_BACKEND_DEFINITIONS.FILE_STORAGE.STORAGE_KEY_APPLICATION_FILE(\n    args.applicationId,\n    args.leafPath,\n    storageName,\n    scope,\n    scopeId,\n  );\n}\n"]}

package/dist/esm/files/storage/file-storage-provider.types.d.ts

@@ -25,10 +25,11 @@ export interface StorageUploadOptions {
      * The resource type this blob belongs to, used to place it under a per-resource
      * segment in the object key: `applications/<appId>/files/<storageName>/…`.
      *
-     * OPTIONAL by design, and the two reasons are different:
-     * - the local-directory provider implements this same interface and does not use it;
-     * - a blob genuinely may have no resource yet (staged before linking), which lands
-     *   under `_unlinked/` rather than inventing a resource segment.
+     * OPTIONAL because a blob genuinely may have no resource yet (staged before linking), which
+     * lands under `_unlinked/` rather than inventing a resource segment. It is NOT optional because
+     * some provider ignores it — every path-based provider composes its key with the same shared
+     * composer, so this segment reaches the local-directory provider exactly as it reaches the
+     * managed one.
      *
      * The segment is `resolveSharedPersistenceCollectionName(resourceType)`, NOT the raw
      * resource type — the same vocabulary the database grants use, so `USER_SELF` and
@@ -49,7 +50,8 @@ export interface StorageUploadOptions {
      * the provider's namespace.
      *
      * When set, the provider stores the blob at
-     * `<providerRoot>/[applicationId/]<folderPath>/<fileName|fileId>`.
+     * `<providerRoot>/[applications/<appId>/files/<storageName>/<scope>/<scopeId>/]<folderPath>/<fileName|fileId>`,
+     * the bracketed prefix being present unless `includeApplicationId` is explicitly `false`.
      *
      * Forward-slash separated, no leading or trailing slash.
      * @example 'specs/icps/big_companies'
@@ -64,12 +66,16 @@ export interface StorageUploadOptions {
      */
     fileName?: string;
     /**
-     * Override the provider's default applicationId inclusion behavior.
+     * Whether the framework-derived prefix
+     * `applications/<appId>/files/<storageName>/<scope>/<scopeId>/` is placed above the authored
+     * folder path and leaf name.
      *
-     * - `true`  → always include applicationId in the path
-     * - `false` → never include applicationId in the path
-     * - `undefined` → use the provider's default
-     *   (S3 defaults to true, local directory defaults to false)
+     * - `true` / `undefined` → include it. This is now the default on EVERY provider; the
+     *   local-directory provider defaulted to `false` until 2026-09-09, which is what left it with no
+     *   tenant structure.
+     * - `false` → the key is the bare `[folderPath/]<fileName|fileId>`. This discards the WHOLE
+     *   prefix, not only the application segment, so nothing about the blob is addressable by tenant
+     *   any more. Both providers honour it identically, so one authored value has one meaning.
      */
     includeApplicationId?: boolean;
 }

package/dist/esm/files/storage/file-storage-provider.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-storage-provider.types.d.ts","sourceRoot":"","sources":["../../../../../src/files/storage/file-storage-provider.types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"file-storage-provider.types.d.ts","sourceRoot":"","sources":["../../../../../src/files/storage/file-storage-provider.types.ts"],"names":[],"mappings":"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"}

package/dist/esm/files/storage/file-storage-provider.types.js.map

@@ -1 +1 @@
-{"version":3,"file":"file-storage-provider.types.js","sourceRoot":"","sources":["../../../../../src/files/storage/file-storage-provider.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG","sourcesContent":["/**\n * File Storage Provider Interface\n *\n * Abstracts storage operations behind a unified interface.\n * The Wildo-managed MinIO/S3 provider is the default implementation.\n * Future providers (OneDrive, Google Drive, Dropbox, local-directory) implement the same interface.\n *\n * Services inject `IFileStorageProvider` via the `FileStorageRouterBackendService`.\n */\n\nimport { Readable } from 'stream';\nimport type { FileStorageAccepted } from '@wildo-ai/zod-decorators';\nimport type { FileScopeIdentifiers, ResourceType } from '@wildo-ai/saas-models';\nimport type { File } from '@wildo-ai/saas-models';\nimport type { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';\n\nexport type StoredFileStorageTarget = Pick<File, 'fileId' | 'storageProvider' | 'storageRef'>;\n\n/**\n * Optional parameters for upload operations.\n *\n * All path segments are pre-composed by the caller\n * (typically `FileStoragePathResolverBackendService`); the provider\n * only concatenates them onto its own root.\n */\nexport interface StorageUploadOptions {\n  /**\n   * The resource type this blob belongs to, used to place it under a per-resource\n   * segment in the object key: `applications/<appId>/files/<storageName>/…`.\n   *\n   * OPTIONAL by design, and the two reasons are different:\n   * - the local-directory provider implements this same interface and does not use it;\n   * - a blob genuinely may have no resource yet (staged before linking), which lands\n   *   under `_unlinked/` rather than inventing a resource segment.\n   *\n   * The segment is `resolveSharedPersistenceCollectionName(resourceType)`, NOT the raw\n   * resource type — the same vocabulary the database grants use, so `USER_SELF` and\n   * `USERS` resolve to one prefix because they are the same rows.\n   */\n  linkedResourceType?: ResourceType;\n\n  /**\n   * The file's tenant scope, placed into the object key as `<scope>/<scopeId>`.\n   *\n   * This is what makes a tenant's blobs a PREFIX: erasure, orphan sweeps and \"who owns this object\"\n   * become prefix operations instead of per-row database lookups. Omitted ⇒ the key falls back to\n   * APPLICATION scope with the resolved application id, so there is exactly ONE key shape and never\n   * a branch that produces a second layout.\n   */\n  scope?: FileScopeIdentifiers;\n\n  /**\n   * Composed relative folder path for organizing files within\n   * the provider's namespace.\n   *\n   * When set, the provider stores the blob at\n   * `<providerRoot>/[applicationId/]<folderPath>/<fileName|fileId>`.\n   *\n   * Forward-slash separated, no leading or trailing slash.\n   * @example 'specs/icps/big_companies'\n   * @example 'avatars'\n   */\n  folderPath?: string;\n\n  /**\n   * Explicit file name to use instead of the fileId.\n   * When omitted, the provider falls back to the fileId (UUID).\n   * @example 'personna.md'\n   * @example 'avatar.png'\n   */\n  fileName?: string;\n\n  /**\n   * Override the provider's default applicationId inclusion behavior.\n   *\n   * - `true`  → always include applicationId in the path\n   * - `false` → never include applicationId in the path\n   * - `undefined` → use the provider's default\n   *   (S3 defaults to true, local directory defaults to false)\n   */\n  includeApplicationId?: boolean;\n}\n\n/**\n * Result of a successful file upload.\n */\nexport interface StorageUploadResult {\n  /** Unique storage reference (provider-specific key) */\n  storageRef: string;\n  /** Storage provider identifier */\n  provider: FileStorageAccepted;\n}\n\n/**\n * Result of a file download.\n */\nexport interface StorageDownloadResult {\n  /** Readable stream of file content */\n  stream: Readable;\n  /** Content type (MIME type) */\n  contentType: string;\n  /** File size in bytes */\n  size: number;\n  /** ETag for caching */\n  etag?: string;\n  /** Last modification date */\n  lastModified?: Date;\n}\n\n/**\n * Storage metadata for a file.\n */\nexport interface StorageFileMetadata {\n  /** Content type (MIME type) */\n  contentType: string;\n  /** File size in bytes */\n  size: number;\n  /** ETag for caching */\n  etag?: string;\n  /** Last modification date */\n  lastModified?: Date;\n}\n\n/**\n * Health check result for a storage provider.\n */\nexport interface StorageProviderHealthResult {\n  healthy: boolean;\n  latency: number;\n  error?: string;\n}\n\n/**\n * Unified storage provider interface.\n *\n * All file storage providers must implement this interface.\n * Operations are scoped by executionContext for multi-tenant isolation.\n */\nexport interface IFileStorageProvider {\n  /** Provider identifier — must match a FileStorageAccepted enum value */\n  readonly providerId: FileStorageAccepted;\n\n  /**\n   * Whether this provider has the required configuration to operate.\n   * Returns false when env vars / credentials are absent.\n   */\n  isConfigured(): boolean;\n\n  /**\n   * Eagerly initialize the provider (connect, verify bucket/container).\n   * Called at startup for fail-fast. If not called, providers may lazy-init.\n   */\n  initialize(): Promise<void>;\n\n  /**\n   * Check provider health (connectivity, bucket reachability).\n   */\n  healthCheck(): Promise<StorageProviderHealthResult>;\n\n  /**\n   * Upload a file to storage.\n   *\n   * @param fileStream - Readable stream of file content\n   * @param fileId - Unique file identifier\n   * @param mimeType - MIME type of the file\n   * @param size - File size in bytes\n   * @param executionContext - Execution context (for auth/tenant scoping)\n   * @param options - Optional upload options\n   * @returns Storage upload result with provider-specific reference\n   */\n  upload(\n    fileStream: Readable,\n    fileId: string,\n    mimeType: string,\n    size: number,\n    executionContext: ExecutionContext<any>,\n    options?: StorageUploadOptions,\n  ): Promise<StorageUploadResult>;\n\n  /**\n   * Download a file from storage.\n   *\n   * @param fileId - File identifier\n   * @param executionContext - Execution context\n   * @returns Download result with stream and metadata\n   */\n  download(\n    file: StoredFileStorageTarget,\n    executionContext: ExecutionContext<any>,\n  ): Promise<StorageDownloadResult>;\n\n  /**\n   * Delete a file from storage.\n   *\n   * @param fileId - File identifier\n   * @param executionContext - Execution context\n   */\n  delete(\n    file: StoredFileStorageTarget,\n    executionContext: ExecutionContext<any>,\n  ): Promise<void>;\n\n  /**\n   * Get file metadata without downloading.\n   *\n   * @param fileId - File identifier\n   * @param executionContext - Execution context\n   * @returns File metadata\n   */\n  getMetadata(\n    file: StoredFileStorageTarget,\n    executionContext: ExecutionContext<any>,\n  ): Promise<StorageFileMetadata>;\n}\n"]}
+{"version":3,"file":"file-storage-provider.types.js","sourceRoot":"","sources":["../../../../../src/files/storage/file-storage-provider.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG","sourcesContent":["/**\n * File Storage Provider Interface\n *\n * Abstracts storage operations behind a unified interface.\n * The Wildo-managed MinIO/S3 provider is the default implementation.\n * Future providers (OneDrive, Google Drive, Dropbox, local-directory) implement the same interface.\n *\n * Services inject `IFileStorageProvider` via the `FileStorageRouterBackendService`.\n */\n\nimport { Readable } from 'stream';\nimport type { FileStorageAccepted } from '@wildo-ai/zod-decorators';\nimport type { FileScopeIdentifiers, ResourceType } from '@wildo-ai/saas-models';\nimport type { File } from '@wildo-ai/saas-models';\nimport type { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';\n\nexport type StoredFileStorageTarget = Pick<File, 'fileId' | 'storageProvider' | 'storageRef'>;\n\n/**\n * Optional parameters for upload operations.\n *\n * All path segments are pre-composed by the caller\n * (typically `FileStoragePathResolverBackendService`); the provider\n * only concatenates them onto its own root.\n */\nexport interface StorageUploadOptions {\n  /**\n   * The resource type this blob belongs to, used to place it under a per-resource\n   * segment in the object key: `applications/<appId>/files/<storageName>/…`.\n   *\n   * OPTIONAL because a blob genuinely may have no resource yet (staged before linking), which\n   * lands under `_unlinked/` rather than inventing a resource segment. It is NOT optional because\n   * some provider ignores it — every path-based provider composes its key with the same shared\n   * composer, so this segment reaches the local-directory provider exactly as it reaches the\n   * managed one.\n   *\n   * The segment is `resolveSharedPersistenceCollectionName(resourceType)`, NOT the raw\n   * resource type — the same vocabulary the database grants use, so `USER_SELF` and\n   * `USERS` resolve to one prefix because they are the same rows.\n   */\n  linkedResourceType?: ResourceType;\n\n  /**\n   * The file's tenant scope, placed into the object key as `<scope>/<scopeId>`.\n   *\n   * This is what makes a tenant's blobs a PREFIX: erasure, orphan sweeps and \"who owns this object\"\n   * become prefix operations instead of per-row database lookups. Omitted ⇒ the key falls back to\n   * APPLICATION scope with the resolved application id, so there is exactly ONE key shape and never\n   * a branch that produces a second layout.\n   */\n  scope?: FileScopeIdentifiers;\n\n  /**\n   * Composed relative folder path for organizing files within\n   * the provider's namespace.\n   *\n   * When set, the provider stores the blob at\n   * `<providerRoot>/[applications/<appId>/files/<storageName>/<scope>/<scopeId>/]<folderPath>/<fileName|fileId>`,\n   * the bracketed prefix being present unless `includeApplicationId` is explicitly `false`.\n   *\n   * Forward-slash separated, no leading or trailing slash.\n   * @example 'specs/icps/big_companies'\n   * @example 'avatars'\n   */\n  folderPath?: string;\n\n  /**\n   * Explicit file name to use instead of the fileId.\n   * When omitted, the provider falls back to the fileId (UUID).\n   * @example 'personna.md'\n   * @example 'avatar.png'\n   */\n  fileName?: string;\n\n  /**\n   * Whether the framework-derived prefix\n   * `applications/<appId>/files/<storageName>/<scope>/<scopeId>/` is placed above the authored\n   * folder path and leaf name.\n   *\n   * - `true` / `undefined` → include it. This is now the default on EVERY provider; the\n   *   local-directory provider defaulted to `false` until 2026-09-09, which is what left it with no\n   *   tenant structure.\n   * - `false` → the key is the bare `[folderPath/]<fileName|fileId>`. This discards the WHOLE\n   *   prefix, not only the application segment, so nothing about the blob is addressable by tenant\n   *   any more. Both providers honour it identically, so one authored value has one meaning.\n   */\n  includeApplicationId?: boolean;\n}\n\n/**\n * Result of a successful file upload.\n */\nexport interface StorageUploadResult {\n  /** Unique storage reference (provider-specific key) */\n  storageRef: string;\n  /** Storage provider identifier */\n  provider: FileStorageAccepted;\n}\n\n/**\n * Result of a file download.\n */\nexport interface StorageDownloadResult {\n  /** Readable stream of file content */\n  stream: Readable;\n  /** Content type (MIME type) */\n  contentType: string;\n  /** File size in bytes */\n  size: number;\n  /** ETag for caching */\n  etag?: string;\n  /** Last modification date */\n  lastModified?: Date;\n}\n\n/**\n * Storage metadata for a file.\n */\nexport interface StorageFileMetadata {\n  /** Content type (MIME type) */\n  contentType: string;\n  /** File size in bytes */\n  size: number;\n  /** ETag for caching */\n  etag?: string;\n  /** Last modification date */\n  lastModified?: Date;\n}\n\n/**\n * Health check result for a storage provider.\n */\nexport interface StorageProviderHealthResult {\n  healthy: boolean;\n  latency: number;\n  error?: string;\n}\n\n/**\n * Unified storage provider interface.\n *\n * All file storage providers must implement this interface.\n * Operations are scoped by executionContext for multi-tenant isolation.\n */\nexport interface IFileStorageProvider {\n  /** Provider identifier — must match a FileStorageAccepted enum value */\n  readonly providerId: FileStorageAccepted;\n\n  /**\n   * Whether this provider has the required configuration to operate.\n   * Returns false when env vars / credentials are absent.\n   */\n  isConfigured(): boolean;\n\n  /**\n   * Eagerly initialize the provider (connect, verify bucket/container).\n   * Called at startup for fail-fast. If not called, providers may lazy-init.\n   */\n  initialize(): Promise<void>;\n\n  /**\n   * Check provider health (connectivity, bucket reachability).\n   */\n  healthCheck(): Promise<StorageProviderHealthResult>;\n\n  /**\n   * Upload a file to storage.\n   *\n   * @param fileStream - Readable stream of file content\n   * @param fileId - Unique file identifier\n   * @param mimeType - MIME type of the file\n   * @param size - File size in bytes\n   * @param executionContext - Execution context (for auth/tenant scoping)\n   * @param options - Optional upload options\n   * @returns Storage upload result with provider-specific reference\n   */\n  upload(\n    fileStream: Readable,\n    fileId: string,\n    mimeType: string,\n    size: number,\n    executionContext: ExecutionContext<any>,\n    options?: StorageUploadOptions,\n  ): Promise<StorageUploadResult>;\n\n  /**\n   * Download a file from storage.\n   *\n   * @param fileId - File identifier\n   * @param executionContext - Execution context\n   * @returns Download result with stream and metadata\n   */\n  download(\n    file: StoredFileStorageTarget,\n    executionContext: ExecutionContext<any>,\n  ): Promise<StorageDownloadResult>;\n\n  /**\n   * Delete a file from storage.\n   *\n   * @param fileId - File identifier\n   * @param executionContext - Execution context\n   */\n  delete(\n    file: StoredFileStorageTarget,\n    executionContext: ExecutionContext<any>,\n  ): Promise<void>;\n\n  /**\n   * Get file metadata without downloading.\n   *\n   * @param fileId - File identifier\n   * @param executionContext - Execution context\n   * @returns File metadata\n   */\n  getMetadata(\n    file: StoredFileStorageTarget,\n    executionContext: ExecutionContext<any>,\n  ): Promise<StorageFileMetadata>;\n}\n"]}

package/dist/esm/files/storage/local-directory-storage-provider.backend.service.d.ts

@@ -2,9 +2,23 @@
  * Local Directory Storage Provider
  *
  * IFileStorageProvider implementation backed by the local filesystem.
- * Files are stored under a configurable base directory, organized by
- * application and file ID. Path traversal attacks are guarded against
- * by resolving all paths and verifying they stay inside the base dir.
+ * Files are stored under a configurable base directory, at the SAME relative key the
+ * Wildo-managed provider would use — `applications/<appId>/files/<storageName>/<scope>/<scopeId>/…`,
+ * composed by `application-storage-key.backend.utils`. Path traversal attacks are guarded against
+ * by refusing a `.`/`..` segment in the composed key AND by resolving every path and verifying it
+ * stays inside the base dir.
+ *
+ * ## Why the key shape is shared rather than provider-local
+ *
+ * Until 2026-09-09 this provider composed `[applicationId]/[folderPath]/<leaf>` from the field's
+ * declarative binding alone, and included the application id only when the binding asked
+ * (`includeApplicationId`, defaulting to `false` here). It therefore emitted NONE of the
+ * `<scope>/<scopeId>` segments the managed provider's shape carries, so a deployment routing a
+ * `z_file()` field to local storage had no per-tenant prefix to sweep, list or confine against —
+ * and nothing failed, because an absent prefix produces no error, only an absent capability.
+ *
+ * Both providers now call one composer. See `application-storage-key.backend.utils.ts` for the
+ * argument and for what deliberately stays provider-local.
  *
  * Configured through `storage.localDirectory.baseDir` in resolved application
  * configuration, which the configuration loader seeds from the
@@ -39,14 +53,18 @@ export declare class LocalDirectoryStorageProvider implements IFileStorageProvid
     healthCheck(): Promise<StorageProviderHealthResult>;
     private getBaseDir;
     /**
-     * Compose the ordered path segments for an upload.
+     * Compose the relative storage key for an upload.
      *
-     * Layout (all optional segments omitted when absent):
-     * [applicationId] / [folderPath] / <fileName|fileId>
+     * Layout — identical to the managed provider's, minus that provider's bucket prefix:
+     *   `applications/<applicationId>/files/<storageName>/<scope>/<scopeId>/[folderPath/]<fileName|fileId>`
      *
-     * `includeApplicationId` defaults to `false` for local storage.
+     * `includeApplicationId` defaults to `true` here, as it does on the managed provider. It used to
+     * default to `false` ("the volume is typically per-app"), which is exactly what left this provider
+     * with no tenant structure: a per-app VOLUME separates applications from each other and separates
+     * nothing inside one. Set explicitly to `false` the key collapses to the bare leaf path on BOTH
+     * providers — one authored value, one meaning, and the same loss of every prefix operation.
      */
-    private composePathSegments;
+    private composeStorageKey;
     /**
      * Resolve a safe absolute path from a relative storage ref.
      * Throws if the resolved path escapes the base directory (path traversal guard).
@@ -60,6 +78,47 @@ export declare class LocalDirectoryStorageProvider implements IFileStorageProvid
     /**
      * Resolve the absolute filesystem path from a persisted storageRef.
      * The ref IS the relative path from baseDir — just validate traversal.
+     *
+     * ## Already-stored files are NOT moved by the key-shape change, and nothing has to be migrated
+     *
+     * Every read verb (`download` / `delete` / `getMetadata`) reaches a blob through this method, and
+     * with a ref present it uses that ref VERBATIM. A blob written under the old
+     * `[applicationId]/[folderPath]/<leaf>` layout therefore stays addressable at exactly the path it
+     * was written to: the shape change governs where NEW uploads land, never how an existing row is
+     * resolved. No migration, and no compatibility branch, because there is nothing to be compatible
+     * with — the persisted ref is the address.
+     *
+     * ## The no-ref branch is LIVE, and it must track `upload` rather than freeze
+     *
+     * It looks like a legacy fallback for rows whose `storageRef` never committed. Its real caller is
+     * the audit-log archive batch: `archiveArtifactExists` probes `getMetadata` with
+     * `fileId: '<folderPath>/<fileName>'` and NO ref, deliberately, so that each provider re-derives
+     * the key its own `upload` produced and the batch never re-implements provider path logic. Pin
+     * the old composition here and that probe would address a blob the upload no longer writes, so
+     * `archiveArtifactExists` would answer `false` forever and every past day would be re-archived on
+     * every tick — a silent, unbounded regression with no failing test anywhere.
+     *
+     * So it composes through the SAME composer, with no resource type and no scope, mirroring the
+     * managed provider's `resolveApplicationObjectKey(file.fileId, ctx, undefined)` argument for
+     * argument. The parity is pinned in this provider's test suite (`upload` then `getMetadata` with
+     * no ref); the batch's own suite uses a fake provider and cannot see it.
+     *
+     * ## Residual, recorded rather than fixed: a `.`/`..` segment inside a PRESENT ref
+     *
+     * `composeStorageKey` refuses one on the composition path; this branch does not, and the managed
+     * provider's `assertNoTraversalSegments(normalizedStorageRef, …)` does. Two reasons it is left
+     * asymmetric, and neither is "nobody thought about it":
+     *
+     * - the containment check below is a real `path.resolve`, not managed's textual `startsWith`, so
+     *   the class of attack that motivated managed's stored-ref check (a ref that satisfies a textual
+     *   prefix while pointing elsewhere) is already caught here for anything leaving the base;
+     * - a `.` ref legitimately addresses the base directory and is pinned as NOT an authorization
+     *   refusal (`ADMITS the base directory itself`), which a whole-segment textual check would break.
+     *
+     * What survives is a ref whose text climbs out of one tenant prefix into another WITHIN the base.
+     * Reaching it needs write access to the `storageRef` column — the composition path can no longer
+     * produce one — so it is a smaller surface than the one closed above, not the same one. Closing it
+     * means deciding what `.` should mean first, which is a separate change.
      */
     private resolvePathFromStorageRef;
     private readLocalMetadata;

package/dist/esm/files/storage/local-directory-storage-provider.backend.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local-directory-storage-provider.backend.service.d.ts","sourceRoot":"","sources":["../../../../../src/files/storage/local-directory-storage-provider.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAKlC,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAE/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8DAA8D,CAAC;AAClG,OAAO,EAAE,0BAA0B,EAAE,MAAM,kEAAkE,CAAC;AAE9G,OAAO,EAAE,uBAAuB,EAAE,MAAM,sEAAsE,CAAC;AAC/G,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qEAAqE,CAAC;AAG5G,OAAO,KAAK,EACV,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,2BAA2B,EAC3B,uBAAuB,EACxB,MAAM,+BAA+B,CAAC;AAUvC,qBACa,6BAA8B,YAAW,oBAAoB;IAMtE,OAAO,CAAC,QAAQ,CAAC,MAAM;IAEvB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAE7B,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IATnC,QAAQ,CAAC,UAAU,uCAAuC;IAC1D,OAAO,CAAC,OAAO,CAAuB;gBAInB,MAAM,EAAE,aAAa,EAErB,YAAY,EAAE,0BAA0B,EAExC,gBAAgB,EAAE,uBAAuB;IAG5D;;;;;OAKG;IACH,YAAY,IAAI,OAAO;IAIvB,yFAAyF;IACzF,OAAO,KAAK,iBAAiB,GAE5B;IAEK,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB3B,WAAW,IAAI,OAAO,CAAC,2BAA2B,CAAC;IAmBzD,OAAO,CAAC,UAAU;IAkBlB;;;;;;;OAOG;IACH,OAAO,CAAC,mBAAmB;IAmC3B;;;OAGG;IACH,OAAO,CAAC,2BAA2B;IAkBnC,OAAO,CAAC,gBAAgB;IAMlB,MAAM,CACV,UAAU,EAAE,QAAQ,EACpB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,gBAAgB,EAAE,gBAAgB,CAAC,GAAG,CAAC,EACvC,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,mBAAmB,CAAC;IAsCzB,QAAQ,CACZ,IAAI,EAAE,uBAAuB,EAC7B,gBAAgB,EAAE,gBAAgB,CAAC,GAAG,CAAC,GACtC,OAAO,CAAC,qBAAqB,CAAC;IAgC3B,MAAM,CACV,IAAI,EAAE,uBAAuB,EAC7B,gBAAgB,EAAE,gBAAgB,CAAC,GAAG,CAAC,GACtC,OAAO,CAAC,IAAI,CAAC;IAoBV,WAAW,CACf,IAAI,EAAE,uBAAuB,EAC7B,gBAAgB,EAAE,gBAAgB,CAAC,GAAG,CAAC,GACtC,OAAO,CAAC,mBAAmB,CAAC;IA8B/B;;;OAGG;IACH,OAAO,CAAC,yBAAyB;YAYnB,iBAAiB;IAkB/B,OAAO,CAAC,mBAAmB;CAuD5B"}
+{"version":3,"file":"local-directory-storage-provider.backend.service.d.ts","sourceRoot":"","sources":["../../../../../src/files/storage/local-directory-storage-provider.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAKlC,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAE/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8DAA8D,CAAC;AAClG,OAAO,EAAE,0BAA0B,EAAE,MAAM,kEAAkE,CAAC;AAE9G,OAAO,EAAE,uBAAuB,EAAE,MAAM,sEAAsE,CAAC;AAC/G,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qEAAqE,CAAC;AAQ5G,OAAO,KAAK,EACV,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,2BAA2B,EAC3B,uBAAuB,EACxB,MAAM,+BAA+B,CAAC;AAUvC,qBACa,6BAA8B,YAAW,oBAAoB;IAMtE,OAAO,CAAC,QAAQ,CAAC,MAAM;IAEvB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAE7B,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IATnC,QAAQ,CAAC,UAAU,uCAAuC;IAC1D,OAAO,CAAC,OAAO,CAAuB;gBAInB,MAAM,EAAE,aAAa,EAErB,YAAY,EAAE,0BAA0B,EAExC,gBAAgB,EAAE,uBAAuB;IAG5D;;;;;OAKG;IACH,YAAY,IAAI,OAAO;IAIvB,yFAAyF;IACzF,OAAO,KAAK,iBAAiB,GAE5B;IAEK,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB3B,WAAW,IAAI,OAAO,CAAC,2BAA2B,CAAC;IAmBzD,OAAO,CAAC,UAAU;IAkBlB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,iBAAiB;IAqDzB;;;OAGG;IACH,OAAO,CAAC,2BAA2B;IAkBnC,OAAO,CAAC,gBAAgB;IAMlB,MAAM,CACV,UAAU,EAAE,QAAQ,EACpB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,gBAAgB,EAAE,gBAAgB,CAAC,GAAG,CAAC,EACvC,OAAO,CAAC,EAAE,oBAAoB,GAC7B,OAAO,CAAC,mBAAmB,CAAC;IAqCzB,QAAQ,CACZ,IAAI,EAAE,uBAAuB,EAC7B,gBAAgB,EAAE,gBAAgB,CAAC,GAAG,CAAC,GACtC,OAAO,CAAC,qBAAqB,CAAC;IAgC3B,MAAM,CACV,IAAI,EAAE,uBAAuB,EAC7B,gBAAgB,EAAE,gBAAgB,CAAC,GAAG,CAAC,GACtC,OAAO,CAAC,IAAI,CAAC;IAoBV,WAAW,CACf,IAAI,EAAE,uBAAuB,EAC7B,gBAAgB,EAAE,gBAAgB,CAAC,GAAG,CAAC,GACtC,OAAO,CAAC,mBAAmB,CAAC;IA8B/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4CG;IACH,OAAO,CAAC,yBAAyB;YAWnB,iBAAiB;IAkB/B,OAAO,CAAC,mBAAmB;CAuD5B"}