@memberjunction/server 6.2.0-edge.5 → 6.2.0-edge.7

package/src/resolvers/ExecuteRemoteOperationResolver.ts

@@ -12,13 +12,13 @@ const REMOTE_OP_PROGRESS_TOPIC = 'RemoteOperationProgress';
 /** Input for the generic Remote Operation transport mutation. */
 @InputType()
 export class ExecuteRemoteOperationInput {
-    @Field()
+    @Field(() => String)
     operationKey: string;  // case-violation-ok-legacy-back-compat: the property name is the GraphQL schema field name — renaming it breaks every client query
 
-    @Field()
+    @Field(() => String)
     inputJSON: string;  // case-violation-ok-legacy-back-compat: the property name is the GraphQL schema field name — renaming it breaks every client query
 
-    @Field()
+    @Field(() => String)
     invokeMode: string;  // case-violation-ok-legacy-back-compat: the property name is the GraphQL schema field name — renaming it breaks every client query
 
     /**
@@ -28,16 +28,24 @@ export class ExecuteRemoteOperationInput {
      */
     @Field(() => String, { nullable: true })
     progressChannelId?: string;  // case-violation-ok-legacy-back-compat: the property name is the GraphQL schema field name — renaming it breaks every client query
+
+    /**
+     * Optional structural contract fingerprint emitted by CodeGen (or supplied by the caller).
+     * When provided, the server rejects requests whose fingerprint diverges from the server's
+     * active operation contract with `ResultCode = 'CONTRACT_MISMATCH'`.
+     */
+    @Field(() => String, { nullable: true })
+    contractFingerprint?: string;  // case-violation-ok-legacy-back-compat: matches camelCase GraphQL input field convention on ExecuteRemoteOperationInput
 }
 
 /** A single streamed progress envelope delivered over the `RemoteOperationProgress` subscription. */
 @ObjectType()
 export class RemoteOperationProgressNotification {
-    @Field()
+    @Field(() => String)
     ChannelId: string;
 
     /** JSON-serialized {@link RemoteOpProgress}. */
-    @Field()
+    @Field(() => String)
     ProgressJSON: string;
 }
 
@@ -71,7 +79,7 @@ export class ExecuteRemoteOperationResultType {
 export class ExecuteRemoteOperationResolver extends ResolverBase {
     @Mutation(() => ExecuteRemoteOperationResultType)
     async ExecuteRemoteOperation(
-        @Arg('input') input: ExecuteRemoteOperationInput,
+        @Arg('input', () => ExecuteRemoteOperationInput) input: ExecuteRemoteOperationInput,
         @Ctx() ctx: AppContext,
         @PubSub() pubSub: PubSubEngine,
     ): Promise<ExecuteRemoteOperationResultType> {
@@ -111,9 +119,24 @@ export class ExecuteRemoteOperationResolver extends ResolverBase {
                 return fail(invokability.ResultCode ?? 'OPERATION_UNAVAILABLE', invokability.Reason ?? `Operation '${key}' is unavailable`);
             }
 
-            let parsedInput: unknown;
+            // (5) Contract fingerprint gate: when the client sends a contractFingerprint, verify it against
+            // the active server operation's ContractFingerprint (or metadata-derived fingerprint) so stale
+            // client bundles fail loudly with CONTRACT_MISMATCH rather than mis-deserializing.
+            const clientFingerprint = input.contractFingerprint?.trim();
+            if (clientFingerprint) {
+                const expectedFingerprint =
+                    opDecl?.ContractFingerprint ?? RemoteOperationEngineBase.Instance.GetContractFingerprint(key);
+                if (expectedFingerprint && clientFingerprint !== expectedFingerprint) {
+                    return fail(
+                        'CONTRACT_MISMATCH',
+                        `Contract fingerprint mismatch for operation '${key}' (client='${clientFingerprint}', server='${expectedFingerprint}')`,
+                    );
+                }
+            }
+
+            let parsedInput: object | string | number | boolean | null;
             try {
-                parsedInput = input.inputJSON ? JSON.parse(input.inputJSON) : {};
+                parsedInput = input.inputJSON ? (JSON.parse(input.inputJSON) as object | string | number | boolean | null) : {};
             } catch (e) {
                 return fail('INVALID_INPUT_JSON', `Invalid input JSON: ${e instanceof Error ? e.message : String(e)}`);
             }
@@ -127,7 +150,16 @@ export class ExecuteRemoteOperationResolver extends ResolverBase {
                 : undefined;
 
             // Route through the per-request provider (server in-process path; runs the op's Authorize + InternalExecute).
-            const result = await provider.RouteOperation(key, parsedInput, { user, mode: input.invokeMode as RemoteOpInvokeMode, onProgress });
+            const result = await provider.RouteOperation(key, parsedInput, {
+                user,
+                mode: input.invokeMode as RemoteOpInvokeMode,
+                onProgress,
+                contractFingerprint: clientFingerprint,
+                requestOrigin: ctx.RequestOrigin,
+                clientIp: ctx.ClientIp,
+                sessionId: ctx.userPayload?.sessionId,
+                apiKeyHash: ctx.userPayload?.apiKeyHash,
+            });
 
             return {
                 success: result.Success,

package/src/resolvers/FetchEntityVectorsResolver.ts

@@ -50,6 +50,12 @@ type LabelledVector = { row: StoredVectorRow; labels: Record<string, string> };
 /** Most Entity Record Document IDs named in one `ID IN (...)` filter when fetching VectorJSON. */
 const VECTOR_FETCH_CHUNK_SIZE = 1000;
 
+/** Most record keys named in one view when checking which matched records the caller may read. */
+const READABLE_KEY_CHECK_CHUNK_SIZE = 1000;
+
+/** A match returned by an external vector index's `QueryIndex`. */
+type IndexMatch = { id: string; values?: number[]; metadata?: Record<string, unknown>; score?: number };
+
 /* ───── Resolver ───── */
 
 @Resolver()
@@ -70,15 +76,18 @@ export class FetchEntityVectorsResolver extends ResolverBase {
             }
 
             const limit = maxRecords ?? 1000;
+            // Every read runs on this request's provider.
+            const md = GetReadOnlyProvider(providers, { allowFallbackToReadWrite: true }) ?? Metadata.Provider;
+            const rv = RunView.FromMetadataProvider(md);
 
             // Step 1: Load the EntityDocument
-            const entityDoc = await this.loadEntityDocument(entityDocumentID, currentUser);
+            const entityDoc = await this.loadEntityDocument(entityDocumentID, currentUser, rv);
             if (!entityDoc) {
                 return this.errorResult(`EntityDocument not found: ${entityDocumentID}`, startTime);
             }
 
             // Step 2: Resolve the VectorIndex
-            const vectorIndex = await this.resolveVectorIndex(entityDoc, currentUser);
+            const vectorIndex = await this.resolveVectorIndex(entityDoc, currentUser, rv);
             if (!vectorIndex) {
                 return this.errorResult(
                     `Could not resolve VectorIndex for EntityDocument "${entityDoc.Name}"`,
@@ -87,7 +96,7 @@ export class FetchEntityVectorsResolver extends ResolverBase {
             }
 
             // Step 3: Create VectorDB provider instance
-            const vectorDBInstance = await this.createVectorDBInstance(vectorIndex, currentUser);
+            const vectorDBInstance = await this.createVectorDBInstance(vectorIndex, currentUser, rv);
             if (!vectorDBInstance) {
                 return this.errorResult(
                     `Could not create VectorDB provider for index "${vectorIndex.Name}"`,
@@ -100,12 +109,21 @@ export class FetchEntityVectorsResolver extends ResolverBase {
             // document ID rather than the index name, and return matches without vector values.
             // Read the stored Entity Record Document rows instead.
             if (vectorDBInstance.QueryKeyIsEntityDocumentID) {
-                const md = GetReadOnlyProvider(providers, { allowFallbackToReadWrite: true }) ?? Metadata.Provider;
-                const results = await this.fetchStoredVectors(entityDoc, limit, filter, currentUser, md);
+                const results = await this.fetchStoredVectors(entityDoc, limit, filter, currentUser, md, rv);
                 LogStatus(`FetchEntityVectors: Loaded ${results.length} stored vectors for entity "${entityDoc.Entity}" in ${Date.now() - startTime}ms`);
                 return { Success: true, Results: results, TotalCount: results.length, ElapsedMs: Date.now() - startTime };
             }
 
+            // The external index was built under whoever ran the sync and is not filtered for this
+            // caller, so check here that they may read the source entity at all.
+            const entityInfo = this.readableEntity(entityDoc.Entity, currentUser, md);
+            if (!entityInfo) {
+                return this.errorResult(
+                    `Entity "${entityDoc.Entity}" does not exist or you do not have permission to read it`,
+                    startTime
+                );
+            }
+
             // Step 4: Query with zero vector + Entity metadata filter.
             // Pinecone's list API doesn't support metadata filtering, but query does.
             // A zero vector returns results in arbitrary order (similarity is meaningless),
@@ -136,12 +154,15 @@ export class FetchEntityVectorsResolver extends ResolverBase {
                 );
             }
 
-            // Step 5: Convert query matches to result format
-            const matches = (queryResponse.data as { matches?: Array<{ id: string; values?: number[]; metadata?: Record<string, unknown>; score?: number }> }).matches ?? [];
+            // Step 5: Keep only matches for records this caller may read (the index is not filtered
+            // by row-level security), then convert them without the fields this caller may not read
+            const allMatches = (queryResponse.data as { matches?: IndexMatch[] }).matches ?? [];
+            const matches = await this.readableMatches(entityInfo, allMatches, currentUser, rv);
+            const denied = entityInfo.GetDeniedReadFields(currentUser);
             const results: EntityVectorItem[] = matches.map(match => ({
                 ID: match.id,
                 Values: match.values ?? [],
-                Metadata: JSON.stringify(match.metadata ?? {}),
+                Metadata: JSON.stringify(this.withoutDeniedFields(match.metadata ?? {}, denied)),
             }));
             LogStatus(`FetchEntityVectors: Queried ${results.length} vectors for entity "${entityName}" in ${Date.now() - startTime}ms`);
 
@@ -158,12 +179,100 @@ export class FetchEntityVectorsResolver extends ResolverBase {
         }
     }
 
+    /**
+     * The entity's metadata when `contextUser` may read it, else null — whether it is missing or
+     * unreadable is deliberately not distinguished.
+     */
+    private readableEntity(entityName: string, contextUser: UserInfo, md: IMetadataProvider): EntityInfo | null {
+        const entityInfo = md.EntityByName(entityName);
+        if (!entityInfo) return null;
+        return entityInfo.GetUserPermisions(contextUser)?.CanRead ? entityInfo : null;
+    }
+
+    /**
+     * The matches whose record `contextUser` may read, in their original order. A match is kept only
+     * when its `RecordID` metadata names a key of the entity and a view run as `contextUser` returns
+     * that record; a match without a usable record ID cannot be checked, so it is dropped.
+     */
+    private async readableMatches(entityInfo: EntityInfo, matches: IndexMatch[], contextUser: UserInfo, rv: RunView): Promise<IndexMatch[]> {
+        const keyed = matches
+            .map(match => ({ match, key: this.matchRecordKey(entityInfo, match) }))
+            .filter((m): m is { match: IndexMatch; key: CompositeKey } => m.key !== null);
+        if (keyed.length === 0) return [];
+        const readable = await this.loadReadableKeys(entityInfo, keyed.map(k => k.key), contextUser, rv);
+        return keyed.filter(k => readable.has(this.canonicalKey(k.key))).map(k => k.match);
+    }
+
+    /** The record key a match's `RecordID` metadata names, or null when it names no key of the entity. */
+    private matchRecordKey(entityInfo: EntityInfo, match: IndexMatch): CompositeKey | null {
+        const recordID = match.metadata?.RecordID;
+        if (typeof recordID !== 'string' || recordID.length === 0) return null;
+        try {
+            return CompositeKey.FromRecordID(entityInfo, recordID);
+        } catch {
+            return null; // field names that are not the entity's primary key: never put into SQL
+        }
+    }
+
+    /**
+     * The canonical forms of the keys among `keys` whose record a view run as `contextUser` returns.
+     * The keys are checked in lists of at most {@link READABLE_KEY_CHECK_CHUNK_SIZE}, all sent in one
+     * `RunViews` batch.
+     */
+    private async loadReadableKeys(entityInfo: EntityInfo, keys: CompositeKey[], contextUser: UserInfo, rv: RunView): Promise<Set<string>> {
+        const views: RunViewParams[] = [];
+        for (let i = 0; i < keys.length; i += READABLE_KEY_CHECK_CHUNK_SIZE) {
+            views.push({
+                EntityName: entityInfo.Name,
+                ExtraFilter: this.keyFilter(entityInfo, keys.slice(i, i + READABLE_KEY_CHECK_CHUNK_SIZE)),
+                Fields: entityInfo.PrimaryKeys.map(pk => pk.Name),
+                IgnoreMaxRows: true,
+                BypassCache: true, // one-off key lists: a cache slot per call would only hold memory
+                ResultType: 'simple',
+            });
+        }
+        const readable = new Set<string>();
+        const results = await rv.RunViews<Record<string, unknown>>(views, contextUser);
+        for (const result of results) {
+            if (!result.Success) {
+                throw new Error(`Failed to check access to "${entityInfo.Name}" records: ${result.ErrorMessage}`);
+            }
+            for (const row of result.Results) {
+                readable.add(this.canonicalKey(CompositeKey.FromEntityRecord(entityInfo, row)));
+            }
+        }
+        return readable;
+    }
+
+    /** A filter matching exactly `keys`: `PK IN (...)` for a single-column key, one clause per key otherwise. */
+    private keyFilter(entityInfo: EntityInfo, keys: CompositeKey[]): string {
+        if (entityInfo.PrimaryKeys.length === 1) {
+            const values = keys.map(k => `'${EscapeSQLString(String(k.KeyValuePairs[0].Value))}'`).join(',');
+            return `${entityInfo.FirstPrimaryKey.Name} IN (${values})`; // first-pk-ok: single-column key, checked above
+        }
+        return keys.map(k => `(${k.ToWhereClause()})`).join(' OR ');
+    }
+
+    /** A key's field names and values, lower-cased, so keys from the index and from a view compare equal. */
+    private canonicalKey(key: CompositeKey): string {
+        return key.KeyValuePairs.map(kv => `${kv.FieldName.toLowerCase()}|${String(kv.Value).toLowerCase()}`).join('||');
+    }
+
+    /**
+     * A copy of a vector's metadata without the keys naming fields in `denied` (lowercased field
+     * names, as `EntityInfo.GetDeniedReadFields` returns them), compared case-insensitively.
+     */
+    private withoutDeniedFields(metadata: Record<string, unknown>, denied: Set<string>): Record<string, unknown> {
+        if (denied.size === 0) return metadata;
+        return Object.fromEntries(Object.entries(metadata).filter(([key]) => !denied.has(key.toLowerCase())));
+    }
+
     /** Load EntityDocument by ID */
     private async loadEntityDocument(
         entityDocumentID: string,
-        contextUser: UserInfo
+        contextUser: UserInfo,
+        rv: RunView
     ): Promise<MJEntityDocumentEntity | null> {
-        const rv = new RunView();
         const result = await rv.RunView<MJEntityDocumentEntity>({
             EntityName: 'MJ: Entity Documents',
             ExtraFilter: `ID='${EscapeSQLString(entityDocumentID)}'`,
@@ -183,9 +292,9 @@ export class FetchEntityVectorsResolver extends ResolverBase {
      */
     private async resolveVectorIndex(
         entityDoc: MJEntityDocumentEntity,
-        contextUser: UserInfo
+        contextUser: UserInfo,
+        rv: RunView
     ): Promise<MJVectorIndexEntity | null> {
-        const rv = new RunView();
 
         // If the EntityDocument has an explicit VectorIndexID, use it directly
         if (entityDoc.VectorIndexID) {
@@ -222,9 +331,9 @@ export class FetchEntityVectorsResolver extends ResolverBase {
     /** Create a VectorDBBase provider instance for a given VectorIndex */
     private async createVectorDBInstance(
         vectorIndex: MJVectorIndexEntity,
-        contextUser: UserInfo
+        contextUser: UserInfo,
+        rv: RunView
     ): Promise<VectorDBBase | null> {
-        const rv = new RunView();
         const dbResult = await rv.RunView<MJVectorDatabaseEntity>({
             EntityName: 'MJ: Vector Databases',
             ExtraFilter: `ID='${vectorIndex.VectorDatabaseID}'`,
@@ -258,19 +367,20 @@ export class FetchEntityVectorsResolver extends ResolverBase {
         limit: number,
         filter: string | undefined,
         contextUser: UserInfo,
-        md: IMetadataProvider
+        md: IMetadataProvider,
+        rv: RunView
     ): Promise<EntityVectorItem[]> {
         const entityInfo = md.EntityByName(entityDoc.Entity);
         if (!entityInfo) {
             throw new Error(`Entity "${entityDoc.Entity}" not found in metadata`);
         }
         const nameFields = this.labelFieldNames(entityInfo);
-        const { records, vectors } = await this.loadRecordsAndStoredVectors(entityInfo, entityDoc, nameFields, filter, contextUser);
+        const { records, vectors } = await this.loadRecordsAndStoredVectors(entityInfo, entityDoc, nameFields, filter, contextUser, rv);
         const labelsByRecordID = this.mapRecordLabels(entityInfo, nameFields, records);
 
         // VectorJSON is the heavy column: list without it, then fetch it only for the items returned.
         const chosen = this.selectLabelledVectors(vectors, labelsByRecordID, limit);
-        const valuesByID = await this.loadVectorValues(chosen.map(c => c.row.ID), contextUser);
+        const valuesByID = await this.loadVectorValues(chosen.map(c => c.row.ID), contextUser, rv);
 
         const results: EntityVectorItem[] = [];
         for (const { row, labels } of chosen) {
@@ -305,7 +415,7 @@ export class FetchEntityVectorsResolver extends ResolverBase {
      * Fetch `VectorJSON` for the given Entity Record Document IDs, keyed by ID. The ID lists are
      * capped at {@link VECTOR_FETCH_CHUNK_SIZE} per view and all sent in one `RunViews` batch.
      */
-    private async loadVectorValues(ids: string[], contextUser: UserInfo): Promise<Map<string, string>> {
+    private async loadVectorValues(ids: string[], contextUser: UserInfo, rv: RunView): Promise<Map<string, string>> {
         const valuesByID = new Map<string, string>();
         if (ids.length === 0) return valuesByID;
 
@@ -321,7 +431,7 @@ export class FetchEntityVectorsResolver extends ResolverBase {
                 ResultType: 'simple',
             });
         }
-        const results = await new RunView().RunViews<{ ID: string; VectorJSON: string | null }>(views, contextUser);
+        const results = await rv.RunViews<{ ID: string; VectorJSON: string | null }>(views, contextUser);
         for (const result of results) {
             if (!result.Success) {
                 throw new Error(`Failed to load vector values: ${result.ErrorMessage}`);
@@ -352,10 +462,11 @@ export class FetchEntityVectorsResolver extends ResolverBase {
         entityDoc: MJEntityDocumentEntity,
         nameFields: string[],
         filter: string | undefined,
-        contextUser: UserInfo
+        contextUser: UserInfo,
+        rv: RunView
     ): Promise<{ records: Record<string, unknown>[]; vectors: StoredVectorRow[] }> {
         const keyFields = entityInfo.PrimaryKeys.map(pk => pk.Name);
-        const [recordResult, docResult] = await new RunView().RunViews<Record<string, unknown>>([
+        const [recordResult, docResult] = await rv.RunViews<Record<string, unknown>>([
             {
                 EntityName: entityInfo.Name,
                 ExtraFilter: filter || undefined,

package/src/resolvers/FileCategoryResolver.ts

@@ -34,6 +34,7 @@ export class FileCategoryResolver extends FileCategoryResolverBase {
     fileCategoryEntity.CheckPermissions(EntityPermissionType.Delete, true);
 
     await fileCategoryEntity.Load(ID);
+    // fls-guard: loaded as the caller; width follows its user
     const returnValue = fileCategoryEntity.GetAll();
 
     // Any files using the deleted category fall back to its parent

package/src/resolvers/FileResolver.ts

@@ -1,4 +1,4 @@
-import { EntityPermissionType, FieldValueCollection, EntitySaveOptions, IMetadataProvider, LogError, UserInfo } from '@memberjunction/core';
+import { AssertClientInputWritableForUser, EntityPermissionType, FieldValueCollection, EntitySaveOptions, IMetadataProvider, LogError, UserInfo } from '@memberjunction/core';
 import { NormalizeUUID } from '@memberjunction/global';
 import { MJFileEntity, MJFileStorageProviderEntity, MJFileStorageAccountEntity } from '@memberjunction/core-entities';
 import {
@@ -47,6 +47,7 @@ import {
 import { CreateMJFileInput, MJFileResolver as FileResolverBase, MJFile_, UpdateMJFileInput } from '../generated/generated.js';
 import { FieldMapper } from '@memberjunction/graphql-dataprovider';
 import { GetReadOnlyProvider } from '../util.js';
+import { ProjectEntityObjectForCaller, ProjectableEntityObject } from '../generic/fieldSecurityTransport.js';
 import { MediaAccessKeyManager } from '../rest/MediaAccessKeys.js';
 import { UploadTokenManager } from '../rest/UploadTokenManager.js';
 import { DeriveSidecarPath, ParsePeaksSidecar } from './peaksSidecar.js';
@@ -666,6 +667,8 @@ export class FileResolver extends FileResolverBase {
     const fileEntity = await provider.GetEntityObject<MJFileEntity>('MJ: Files', user);
     const providerEntity = await provider.GetEntityObject<MJFileStorageProviderEntity>('MJ: File Storage Providers', user);
     fileEntity.CheckPermissions(EntityPermissionType.Create, true);
+    // Field-level security: refuse a key the caller may not read, or that names no field, before anything else
+    AssertClientInputWritableForUser(fileEntity.EntityInfo, { ...input }, user);
 
     // The upload URL signs an overwrite of `Name` (and the row will point at `ProviderKey`): Write on the account the
     // provider resolves to, and the tracked-file rule on both keys, as for every other route that writes an object.
@@ -693,7 +696,7 @@ export class FileResolver extends FileResolverBase {
     if (!saved) {
       console.error('[CreateFile] File save failed:', fileEntity.LatestResult?.CompleteMessage);
     }
-    const File = mapper.MapFields({ ...fileEntity.GetAll() });
+    const File = this.fileResponse(fileEntity, user, provider);
 
     return { File, UploadUrl, NameExists };
   }
@@ -760,8 +763,7 @@ export class FileResolver extends FileResolverBase {
       });
 
       const loaded = await fileEntity.Load(uploadResult.FileID);
-      const mapper = new FieldMapper();
-      const File = loaded ? (mapper.MapFields({ ...fileEntity.GetAll() }) as unknown as MJFile_) : undefined;
+      const File = loaded ? (this.fileResponse(fileEntity, user, provider) as unknown as MJFile_) : undefined;
 
       return {
         Success: true,
@@ -778,6 +780,14 @@ export class FileResolver extends FileResolverBase {
     }
   }
 
+  /**
+   * The file record for a response: its field values as the caller may read them, in GraphQL field
+   * names. The record was just saved or reloaded, and a save re-reads the whole row.
+   */
+  private fileResponse(fileEntity: ProjectableEntityObject, user: UserInfo, provider: IMetadataProvider): Record<string, unknown> {
+    return new FieldMapper().MapFields({ ...ProjectEntityObjectForCaller(fileEntity, user, provider) });
+  }
+
   /**
    * The account an upload will land in: the requested one, else the engine's default (the first active account) —
    * returned as an explicit ID so the account the gate checks is the account `UploadFile` uses. A requested ID is

package/src/resolvers/GetDataResolver.ts

@@ -6,6 +6,7 @@ import { QueryCompositionEngine } from '@memberjunction/generic-database-provide
 import { RequireSystemUser } from '../directives/RequireSystemUser.js';
 import { NoLog } from '../logging/NoLog.js';
 import { v4 as uuidv4 } from 'uuid';
+import { createHash, timingSafeEqual } from 'node:crypto';
 import { GetReadOnlyDataSource, GetReadOnlyProvider } from '../util.js';
 import { GetDbType } from '../index.js';
 import { GetSystemUser } from '../auth/index.js';
@@ -125,9 +126,9 @@ export class GetDataResolver {
             });
             LogStatus(`GetData invoked: ${input.Queries.length} queries`);
 
-            // validate the token
+            // validate the token (never echo the raw token into error messages or logs — Token is @NoLog)
             if (!IsTokenValid(input.Token)) {
-                throw new Error(`Token ${input.Token} is not valid or has expired`);
+                throw new Error('Access token is not valid or has expired');
             }
 
             // Use the read-only connection for executing queries
@@ -296,6 +297,26 @@ export class GetDataAccessToken {
 const __accessTokens: GetDataAccessToken[] = [];
 const __defaultTokenLifeSpan = 1000 * 60 * 5; // 5 minutes
 
+/**
+ * Non-short-circuiting constant-time scan over active access tokens: hashes the presented token
+ * once and compares against every stored token digest with `timingSafeEqual` without breaking early,
+ * so neither prefix similarity, token length, nor array index leaks through timing.
+ */
+function findMatchingAccessTokenIndex(token: string): number {
+    if (typeof token !== 'string' || token.length === 0) {
+        return -1;
+    }
+    const targetDigest = createHash('sha256').update(token).digest();
+    let matchedIndex = -1;
+    for (let i = 0; i < __accessTokens.length; i++) {
+        const candidateDigest = createHash('sha256').update(__accessTokens[i].Token).digest();
+        if (timingSafeEqual(candidateDigest, targetDigest)) {
+            matchedIndex = i;
+        }
+    }
+    return matchedIndex;
+}
+
 /**
  * Removes every token whose `ExpiresAt` has already passed (and its `TokenUses`
  * log along with it). Without this sweep `__accessTokens` grows forever — nothing
@@ -339,7 +360,7 @@ export function RegisterAccessToken(token?: string, lifeSpan: number = __default
 
     if (TokenExists(tokenToUse)) {
         // should never happen if we used the uuidv4() function but could happen if someone tries to use a custom token
-        throw new Error(`Token ${tokenToUse} already exists`);
+        throw new Error('Access token already exists');
     }
 
     const newToken = new GetDataAccessToken();
@@ -356,12 +377,12 @@ export function registerAccessToken(token?: string, lifeSpan: number = __default
     return RegisterAccessToken(token, lifeSpan, requestorPayload);
 }
 export function DeleteAccessToken(token: string) {
-    const index = __accessTokens.findIndex((t) => t.Token === token);
+    const index = findMatchingAccessTokenIndex(token);
     if (index >= 0) {
         __accessTokens.splice(index, 1);
     }
     else {
-        throw new Error(`Token ${token} does not exist`);
+        throw new Error('Access token does not exist');
     }
 }
 
@@ -370,7 +391,7 @@ export function deleteAccessToken(token: string) {
     return DeleteAccessToken(token);
 }
 export function TokenExists(token: string) {
-    return __accessTokens.find((t) => t.Token === token) !== undefined;
+    return findMatchingAccessTokenIndex(token) >= 0;
 }
 
 /** @deprecated Use {@link TokenExists}. */
@@ -378,9 +399,9 @@ export function tokenExists(token: string) {
     return TokenExists(token);
 }
 export function IsTokenValid(token: string) {
-    const t = __accessTokens.find((t) => t.Token === token);
-    if (t) {
-        return t.ExpiresAt > new Date();
+    const index = findMatchingAccessTokenIndex(token);
+    if (index >= 0) {
+        return __accessTokens[index].ExpiresAt > new Date();
     }
     return false;
 }
@@ -390,15 +411,16 @@ export function isTokenValid(token: string) {
     return IsTokenValid(token);
 } 
 export function RecordTokenUse(token: string, usePayload: any) {
-    const t = __accessTokens.find((t) => t.Token === token);
-    if (t) {
+    const index = findMatchingAccessTokenIndex(token);
+    if (index >= 0) {
+        const t = __accessTokens[index];
         if (!t.TokenUses) {
             t.TokenUses = [];
         }
-        t.TokenUses.push({ Token: token, UsedAt: new Date(), UsePayload: usePayload });
+        t.TokenUses.push({ Token: t.Token, UsedAt: new Date(), UsePayload: usePayload });
     }
     else {
-        throw new Error(`Token ${token} does not exist`);
+        throw new Error('Access token does not exist');
     }
 }