@memberjunction/storage 6.2.0-edge.4 → 6.2.0-edge.5

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kCAAkC,CAAC;AACjD,cAAc,iCAAiC,CAAC;AAChD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kCAAkC,CAAC;AACjD,cAAc,iCAAiC,CAAC;AAChD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,sBAAsB,CAAC;AACrC,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,qBAAqB,CAAC;AACpC,cAAc,0BAA0B,CAAC"}

package/dist/index.js

@@ -6,7 +6,9 @@ export * from './drivers/SharePointFileStorage.js';
 export * from './drivers/DropboxFileStorage.js';
 export * from './drivers/BoxFileStorage.js';
 export * from './generic/FileStorageBase.js';
+export * from './generic/ObjectKeys.js';
 export * from './util.js';
 export * from './config.js';
 export * from './FileStorageEngine.js';
+export * from './StorageAccessEvaluator.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kCAAkC,CAAC;AACjD,cAAc,iCAAiC,CAAC;AAChD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,kCAAkC,CAAC;AACjD,cAAc,iCAAiC,CAAC;AAChD,cAAc,8BAA8B,CAAC;AAC7C,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,sBAAsB,CAAC;AACrC,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,qBAAqB,CAAC;AACpC,cAAc,0BAA0B,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@memberjunction/storage",
   "type": "module",
-  "version": "6.2.0-edge.4",
+  "version": "6.2.0-edge.5",
   "description": "This library provides a set of objects that handle the interface between the server-side API and various cloud storage providers.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -21,11 +21,11 @@
     "@azure/identity": "^4.13.0",
     "@azure/storage-blob": "^12.30.0",
     "@google-cloud/storage": "^7.19.0",
-    "@memberjunction/core": "6.2.0-edge.4",
-    "@memberjunction/core-entities": "6.2.0-edge.4",
-    "@memberjunction/credentials": "6.2.0-edge.4",
-    "@memberjunction/global": "6.2.0-edge.4",
-    "@memberjunction/network-utils": "6.2.0-edge.4",
+    "@memberjunction/core": "6.2.0-edge.5",
+    "@memberjunction/core-entities": "6.2.0-edge.5",
+    "@memberjunction/credentials": "6.2.0-edge.5",
+    "@memberjunction/global": "6.2.0-edge.5",
+    "@memberjunction/network-utils": "6.2.0-edge.5",
     "@microsoft/mgt-element": "^4.6.0",
     "@microsoft/mgt-msal2-provider": "^4.6.0",
     "@microsoft/mgt-sharepoint-provider": "^4.6.0",

package/readme.md

@@ -251,6 +251,79 @@ sequenceDiagram
     Driver-->>App: initialized driver
 ```
 
+### Account Permissions (`StorageAccessEvaluator`)
+
+Neither `FileStorageEngine.GetDriver()` nor the utility functions check who is asking — they act on whatever account
+they are given. Anything that acts on an account on a user's behalf must ask `StorageAccessEvaluator` first. It is the
+one place `MJ: File Storage Account Permissions` (Everyone / Role / User rows with `CanRead` / `CanWrite`) are decided,
+and the one place the tracked-file rule (below) is decided:
+
+```typescript
+import { FileStorageEngine, StorageAccessEvaluator } from '@memberjunction/storage';
+
+const evaluator = StorageAccessEvaluator.Instance;
+
+// Throws StorageAccountAccessDeniedError ("You do not have access to this storage account or it does not exist.")
+await evaluator.AssertAccountAccess(accountId, contextUser, 'Write', provider);
+
+// Or filter a list: returns the NormalizeUUID'd IDs the user may read
+const readable = await evaluator.AccessibleAccountIDs(accountIds, contextUser, 'Read', provider);
+
+// Object keys in an account that back an MJ: Files row the user cannot read — pass the account's driver so keys are
+// compared the way that driver addresses them
+const driver = await FileStorageEngine.Instance.GetDriver(accountId, contextUser);
+const blocked = await evaluator.UnreadableTrackedObjectKeys(account.ProviderID, [objectKey], contextUser, provider, driver);
+// Or throw TrackedFileAccessDeniedError ("You do not have access to this file or it does not exist.")
+await evaluator.AssertTrackedObjectsReadable(account.ProviderID, [objectKey], contextUser, provider, driver);
+
+// From an MJ: Files row (loaded as the caller) to its bytes: account gate + tracked-file rule, then the driver
+const resolved = await FileStorageEngine.Instance.ResolveFileObject(fileRow, contextUser, 'Read', provider);
+const bytes = resolved ? await resolved.Driver.GetObject({ fullPath: resolved.ObjectKey }) : null;
+```
+
+**The account rule**
+
+- **Evaluated per call** — nothing is cached, so a grant or revocation applies to the next call.
+- **Read as the system user, decided for the caller** — the permission rows are read with the MJ system user
+  (`WellKnownUserSource`), so a caller who cannot read the permission table is not mistaken for an account with no rows.
+- **Never truncated** — every read sets `IgnoreMaxRows`, so the entity's row cap cannot drop an account's rows (which
+  would make it look like an account with none) or a tracked file's row.
+- **An account with no permission rows is open** to every authenticated user (the current product rule, kept in one
+  place in the evaluator; flipping it needs a data migration that writes explicit `Everyone` rows).
+- **`Read` vs `Write`** — listing, downloading, signing a download URL and searching need `CanRead`; uploading, signing an
+  upload URL, copying into, moving, deleting and creating directories need `CanWrite`. A copy between accounts needs
+  `Read` on the source and `Write` on the destination.
+- **Fails closed** — an unknown account, a malformed ID, a user without `UserRoles`, a missing system user or a failed
+  read all mean "no access". An unknown account is refused with the same message as a restricted one.
+
+**The tracked-file rule**
+
+- An object that backs an `MJ: Files` row — the row's `ProviderKey`, or `Name` when `ProviderKey` is empty, on the
+  account's storage provider — may be read, signed, listed or returned by search only when the caller can read that row
+  (entity permission and row-level security, asked as the caller). Untracked objects are governed by the account rule
+  alone. Rows are keyed by provider, not account, so a row in another account on the same provider counts too.
+- **Writes**: an object may be overwritten (upload, upload URL, copy/move destination), moved, copied out of or deleted
+  only when the caller can read every row that tracks it — the minimum; the account rule still requires `CanWrite`.
+  `UploadFile` applies this before `PutObject`.
+- **Matching** — the client's key and the row's key both go through the account driver's `NormalizeObjectKey` (default:
+  trim, collapse repeated `/`, strip leading/trailing `/`; S3 also strips its key prefix the way it addresses keys) and
+  are compared case-insensitively, so `/hr/secret.pdf`, `hr/secret.pdf/` and `HR/Secret.PDF` are the same tracked
+  object.
+- **Refused keys** — a key with a `.`/`..` segment, a backslash, a percent-encoded `/`, `\`, `.` or control character
+  (`%2F`, `%5C`, `%2E`, `%00`–`%1F`, `%7F`) or a raw control character is never compared: its meaning depends on the
+  provider, so it is treated as an object the caller may not read. A literal `%` otherwise (`50% off.pdf`) is fine.
+- **File-ID routes** (`DownloadUrl`, `GetFileContents`, `CreateMediaAccessToken`, `DeleteFile`, the artifact download
+  URL, the agent file handler, the realtime recording reader) go through `FileStorageEngine.ResolveFileObject`: the
+  row's provider resolves to its first account, which must allow the access, and the row's object gets the tracked-file
+  rule — so a row whose `ProviderKey`/`Name` aliases another row's object is refused. On the server, `ProviderID` and
+  `ProviderKey` cannot be changed on an existing row by a client save (`MJFileEntityServer`).
+
+**Pre-authenticated URLs** are scoped to one object: Azure Blob URLs carry a blob-scoped service SAS (`sr=b`, `r` to
+download, `cw` to upload), never an account SAS; every URL expires after 10 minutes.
+
+The MJServer storage GraphQL routes, the File Storage core actions (and `List Storage Accounts`, which lists only the
+accounts the caller may read), `StorageSearchProvider` and `SearchEngine`'s late permission filter all use it.
+
 ### Using Utility Functions
 
 The library provides high-level utility functions that work with MemberJunction's entity system:
@@ -594,6 +667,7 @@ Each provider also supports environment variable configuration. Environment vari
 | `STORAGE_GOOGLE_DRIVE_REFRESH_TOKEN` | OAuth refresh token |
 | `STORAGE_GOOGLE_DRIVE_REDIRECT_URI` | OAuth redirect URI |
 | `STORAGE_GDRIVE_ROOT_FOLDER_ID` | Root folder ID (optional) |
+| `STORAGE_GDRIVE_DRIVE_ID` | Shared Drive ID. Required for a service account to upload, since a service account has no storage quota of its own. Also the default root when no root folder is set. A credential record carries it as `driveID`. |
 | `STORAGE_GDRIVE_KEY_FILE` | Service account key file (legacy) |
 | `STORAGE_GDRIVE_CREDENTIALS_JSON` | Service account credentials JSON (legacy) |