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

package/dist/esm/files/services/file-upload-grant.backend.service.js

@@ -0,0 +1,566 @@
+/**
+ * File Upload Grant Backend Service
+ *
+ * The ONE mint function behind both doors — the REST sibling route (`…/files/<field>/grant`) and the
+ * MCP derived tool — plus the route-binding check the upload middleware runs, the public status read,
+ * revocation, and the post-redemption write-back. Issue #312.
+ *
+ * ## What a grant is
+ *
+ * A `SINGLE_USE` consumable token of type `FILE_UPLOAD_GRANT` that lets whoever holds it perform ONE
+ * upload into ONE resource file field with the MINTER's authority. Nothing durable is created at mint
+ * but the token. The upload goes through the resource's EXISTING file-upload route: the token becomes
+ * an ordinary `CONSUMABLE_TOKEN` execution context (typed fields → identity) and the ordinary
+ * authorizer decides. This service never decides "may this principal put a file here" — the upload
+ * middleware does, once, for mint and upload alike, which is what makes mint-authority ≡
+ * upload-authority by construction.
+ *
+ * ## Why the route binding lives in `metadata` and is checked HERE
+ *
+ * `createExecutionContextFromRequest` turns the token's TYPED fields (`userId`, `organizationId`,
+ * `roles`, `resourceIdentifier`, `relatedId`) into identity and deliberately reads nothing from
+ * `metadata`. Which field, which operation kind, which concrete upload URL — those are ROUTE facts,
+ * and the upload middleware asks this service to check them against the route the token was
+ * presented on. Identity and route stay separate concerns.
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { injectable, inject, optional } from 'inversify';
+import { ConsumableToken_ConsumptionMode, CoreAuditableEventType, CoreConsumableTokenTypes, CORE_APP_ROLES, ErrorCustomMessageReference, ErrorType, ExecutionContext_ExecutionType, FILE_UPLOAD_GRANT_DEFAULT_MINUTES, FILE_UPLOAD_GRANT_PAGE_PATH, FileUploadGrantMetadataSchema, FileUploadGrantState, ResourceOperationRiskLevel, TokenAuthenticationPolicy, WildoHeaderKeys, CoreResourceType, CoreResourceOperation, } from '@wildo-ai/saas-models';
+import { DurationUnit, FileGenerationSource } from '@wildo-ai/zod-decorators';
+import { SAAS_SERVICE_TYPES } from '../../inject/models/service-types.js';
+import { ErrorBuilderBackendService } from '../../errors/services/error-builder.backend.service.js';
+import { projectCaughtErrorLogFields } from '../../errors/utils/error-log-level-classification.backend.utils.js';
+import { AppConfigurationService } from '../../config/services/app-configuration.backend.service.js';
+import { ConsumableTokenBackendService } from '../../security/consumable-tokens/services/consumable-token.backend.service.js';
+import { FileConstraintResolverChain } from '../../files/constraints/file-constraint-resolver-chain.backend.service.js';
+import { FileFieldDetectionBackendService } from '../../files/services/file-field-detection.backend.service.js';
+import { ExecutionContextCreatorBackendService } from '../../runtime/services/execution-context-creator.backend.service.js';
+import { RepositoriesRegistryHandlerBackendService } from '../../base-classes/services/repositories/repositories-registry-handler.backend.service.js';
+import { resolveFileUploaderPrincipal } from '../../files/utils/file-uploader.utils.js';
+import { AuthControllerUtils } from '../../security/authentications/services/utils/auth-controller.utils.js';
+/**
+ * Reduce an upload-route URL to the one form the grant's route check compares — its PATH — or
+ * `undefined` when it cannot be read as a URL at all.
+ *
+ * Accepts both shapes the two sides supply: an ABSOLUTE URL (what `metadata.uploadUrl` records, and
+ * what a proxy's absolute-form request target produces) and an ORIGIN-RELATIVE path (what Express's
+ * `req.originalUrl` normally is). Parsed against a throwaway base so one function handles both.
+ *
+ * ## What is normalised away, and why each is safe
+ *
+ * - **Query and fragment.** Mandatory, not cosmetic: GATE 1 accepts the grant in `?consumable_token=`
+ *   as well as the header, so a redemption legitimately carries a query the mint's URL never had.
+ *   Comparing with the query attached would refuse the query-token form outright.
+ * - **A single trailing slash.** Express routes with `strict: false` by default, so `…/attachment/`
+ *   reaches the same handler as `…/attachment`. Refusing one of the two would be an artefact of this
+ *   comparison rather than a fact about the grant. `/` itself is left alone.
+ *
+ * ## What is deliberately NOT normalised
+ *
+ * - **The ORIGIN is not compared at all** — only the path is. Both origins come from the same server
+ *   config (`runtime.endPoints.main_backend_api.publicUrl`, never the client's Host header, which is
+ *   why the mint reads config in the first place), so an origin comparison is tautological against an
+ *   attacker and can only ever produce a false refusal: change `publicUrl` and every unredeemed grant
+ *   — up to an hour of them — stops matching. Nothing is given up, because the origin carries no
+ *   value a caller could vary.
+ * - **Case.** Express matches case-insensitively by default, so `/Files/attachment` would reach the
+ *   route while comparing unequal. Case-folding was rejected: path segments carry IDs, and folding
+ *   them would make `/todos/AbC` ≡ `/todos/abc` and quietly weaken the row and parent pins this check
+ *   exists to add. Folding only the static segments is not available — nothing here can tell a static
+ *   segment from an id. The cost is that a caller who re-cases the URL is refused; there is no
+ *   legitimate reason to, since the grant hands back the exact URL to post to.
+ * - **Percent-encoding.** Not decoded. Decoding is how path-confusion bugs are born: `%2F` would
+ *   become `/` and two different routes would compare equal. The raw encoded forms are compared, and
+ *   the ids that reach these paths are constrained to alphanumerics, `-` and `_` by
+ *   `validateParameterFormat`, which are encoding-invariant.
+ */
+function normalizeUploadRoutePath(url) {
+    let path;
+    try {
+        // The base is never used for an absolute input, and for a relative one only its origin is
+        // discarded below — so it can be any valid origin.
+        path = new URL(url, 'http://upload-route.invalid').pathname;
+    }
+    catch {
+        return undefined;
+    }
+    return path.length > 1 && path.endsWith('/') ? path.slice(0, -1) : path;
+}
+let FileUploadGrantBackendService = class FileUploadGrantBackendService {
+    logger;
+    errorBuilder;
+    consumableTokenService;
+    constraintResolver;
+    fileFieldDetection;
+    executionContextCreator;
+    repositoriesRegistry;
+    appConfigService;
+    auditLogsService;
+    logDebug;
+    constructor(logger, errorBuilder, consumableTokenService, constraintResolver, fileFieldDetection, executionContextCreator, repositoriesRegistry, appConfigService, auditLogsService) {
+        this.logger = logger;
+        this.errorBuilder = errorBuilder;
+        this.consumableTokenService = consumableTokenService;
+        this.constraintResolver = constraintResolver;
+        this.fileFieldDetection = fileFieldDetection;
+        this.executionContextCreator = executionContextCreator;
+        this.repositoriesRegistry = repositoriesRegistry;
+        this.appConfigService = appConfigService;
+        this.auditLogsService = auditLogsService;
+        this.logDebug = this.logger.debugByType('FileUploadGrantBackendService');
+        this.logger.setDebugTypeLogging('FileUploadGrantBackendService', false);
+    }
+    /**
+     * The operation the upload routes hand to the execution-context creator (issue #312, D4).
+     *
+     * `tokenAuthentication` lives on the OPERATION, so declaring it on the authored CREATE/UPDATE would
+     * let a grant perform the whole JSON write. Instead the `…/files/<field>` and `…/files/<field>/grant`
+     * routes — and ONLY those — get this derived copy, which accepts the grant type as an ALTERNATIVE
+     * credential beside whatever the author declared. The JSON routes keep the authored operation, so a
+     * grant presented there is refused by GATE 1 (`CONSUMABLE_TOKEN_NOT_ACCEPTED_FOR_OPERATION`).
+     *
+     * An authored ADDITIVE policy is NOT preserved as ADDITIVE here: the upload route's own authorizer
+     * decides on the resulting context either way, and an additive token on a multipart upload is not a
+     * case any resource declares today. If one appears, this is the seam to widen — do not widen the
+     * authored operation.
+     */
+    static withUploadGrantAcceptance(operation) {
+        const authored = 'tokenAuthentication' in operation ? operation.tokenAuthentication : undefined;
+        const authoredTypes = authored?.policy === TokenAuthenticationPolicy.ALTERNATIVE ? (authored.types ?? []) : [];
+        return {
+            ...operation,
+            tokenAuthentication: {
+                types: [...authoredTypes, CoreConsumableTokenTypes.FILE_UPLOAD_GRANT],
+                policy: TokenAuthenticationPolicy.ALTERNATIVE,
+            },
+        };
+    }
+    /**
+     * Mint a grant for the target the caller has JUST been authorized on.
+     *
+     * Refuses two minter kinds: a `CONSUMABLE_TOKEN` context (a grant may not mint a grant — no
+     * delegation chains) and an `ANONYMOUS_SESSION` (no stable subject to attribute the file to, no
+     * roles worth snapshotting). `USER_REQUEST` and both machine principals mint.
+     */
+    async mint(params) {
+        const { executionContext, target } = params;
+        if (executionContext.executionType === ExecutionContext_ExecutionType.CONSUMABLE_TOKEN
+            || executionContext.executionType === ExecutionContext_ExecutionType.ANONYMOUS_SESSION) {
+            throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.FILE_UPLOAD_GRANT_MINTER_NOT_ELIGIBLE,
+                context: { executionType: executionContext.executionType }, // diagnostic (log-only)
+            });
+        }
+        const minter = resolveFileUploaderPrincipal(executionContext);
+        if (!minter) {
+            // A principal the uploader resolver cannot name cannot be the file's owner either.
+            throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.FILE_UPLOAD_GRANT_MINTER_NOT_ELIGIBLE,
+                context: { executionType: executionContext.executionType, reason: 'no uploader principal' }, // diagnostic (log-only)
+            });
+        }
+        const fieldMeta = this.fileFieldDetection.getFileFieldMetadata(target.resourceType, target.fieldName);
+        if (!fieldMeta) {
+            throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                context: { message: 'Not a file field', resourceType: target.resourceType, fieldName: target.fieldName }, // diagnostic (log-only)
+            });
+        }
+        if (fieldMeta.fileMetadata.generation?.source === FileGenerationSource.PDF_TEMPLATE) {
+            // Same refusal the upload handler makes, made EARLY: a grant for a field that can never receive a
+            // user upload would be a link that fails on redemption for a reason knowable at mint.
+            throw this.errorBuilder.buildError(ErrorType.BUSINESS_RULE, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.FILE_GENERATED_FIELD_NOT_WRITABLE,
+                context: { resourceType: target.resourceType, fieldName: target.fieldName }, // diagnostic (log-only)
+            });
+        }
+        const constraint = await this.constraintResolver.resolve({ resourceType: target.resourceType, fieldName: target.fieldName });
+        this.assertDeclarationFitsConstraint(params.declared, constraint, executionContext, target);
+        const expiresInMinutes = params.expiresInMinutes ?? FILE_UPLOAD_GRANT_DEFAULT_MINUTES;
+        const metadataWithoutUrl = {
+            fieldName: target.fieldName,
+            operation: target.operation,
+            minter: { entityType: minter.uploadedByEntityType, id: minter.uploadedBy },
+        };
+        // assurance-control: WILDO.IDENTITY.DELEGATED_AUTHORIZATION — a principal delegates ONE upload, into
+        // ONE field, under its own authority, to whoever holds the grant. The ceiling and SINGLE_USE are
+        // enforced inside createToken; the audit row below is what makes the delegation accountable.
+        const token = await this.consumableTokenService.createToken({
+            tokenType: CoreConsumableTokenTypes.FILE_UPLOAD_GRANT,
+            consumptionMode: ConsumableToken_ConsumptionMode.SINGLE_USE,
+            expiresIn: { value: expiresInMinutes, unit: DurationUnit.MINUTES },
+            organizationId: executionContext.initiatorIds?.organizationId,
+            userId: executionContext.initiatorIds?.userId,
+            resourceIdentifier: String(target.resourceType),
+            relatedId: target.resourceId,
+            roles: [...(executionContext.initiatorRoles ?? [])],
+            metadata: { ...metadataWithoutUrl, uploadUrl: params.uploadUrl },
+        });
+        const grantId = token._id;
+        const tokenValue = token.token;
+        const uploadPageUrl = this.resolveUploadPageUrl(tokenValue);
+        const statusUrl = `${params.apiBaseUrl}/files/upload-grants/${encodeURIComponent(tokenValue)}`;
+        const headerName = WildoHeaderKeys.CONSUMABLE_TOKEN;
+        const fileHint = params.declared?.name?.trim() ? this.safeFileName(params.declared.name) : this.suggestFileName(target.fieldName, constraint.allowedMimeTypes);
+        const grant = {
+            grantId,
+            state: FileUploadGrantState.PENDING,
+            expiresAt: token.expiresAt.toISOString(),
+            singleUse: true,
+            target: {
+                resourceType: String(target.resourceType),
+                fieldName: target.fieldName,
+                operation: target.operation,
+                resourceId: target.resourceId ?? null,
+            },
+            constraints: {
+                maxBytes: constraint.maxSize,
+                allowedMimeTypes: constraint.allowedMimeTypes ?? [],
+            },
+            uploadUrl: params.uploadUrl,
+            uploadHeader: { name: headerName, value: tokenValue },
+            // No `-f`: on a refusal the JSON error body is the only thing that tells the caller why.
+            uploadCommand: `curl -sS -H "${headerName}: ${tokenValue}" -F "file=@/path/to/${fileHint}" "${params.uploadUrl}"`,
+            // In PowerShell `curl` aliases Invoke-WebRequest, which does not understand -F; the real binary is curl.exe.
+            uploadCommandPowerShell: `curl.exe -sS -H "${headerName}: ${tokenValue}" -F "file=@C:\\path\\to\\${fileHint}" "${params.uploadUrl}"`,
+            uploadPageUrl,
+            statusUrl,
+            note: this.buildNote(target, uploadPageUrl !== null),
+        };
+        await this.audit(executionContext, CoreAuditableEventType.FILE_UPLOAD_GRANT_ISSUED, ResourceOperationRiskLevel.MEDIUM, {
+            grantId,
+            resourceType: String(target.resourceType),
+            fieldName: target.fieldName,
+            operation: target.operation,
+            resourceId: target.resourceId ?? null,
+            expiresAt: grant.expiresAt,
+            minter: metadataWithoutUrl.minter,
+            ipAddress: params.requestProvenance?.ipAddress,
+            userAgent: params.requestProvenance?.userAgent,
+        });
+        this.logDebug('File upload grant minted', { grantId, resourceType: target.resourceType, fieldName: target.fieldName, operation: target.operation });
+        return grant;
+    }
+    /**
+     * The upload middleware's question: is the token this context was built from a grant for THIS route?
+     *
+     * Returns `undefined` when the context is not a grant context at all — a JWT/API-key upload, or an
+     * authored non-grant ALTERNATIVE token, which keeps behaving as it did. Throws
+     * `FILE_UPLOAD_GRANT_TARGET_MISMATCH` when it IS a grant minted for a different resource, field,
+     * operation kind or row. Mirrors `validateFileToken` on the download twin: type pinned AND target
+     * pinned; a grant with no binding unlocks nothing.
+     *
+     * For UPDATE the creator has already coherence-checked `relatedId` against the URL id; the check is
+     * repeated here because CREATE has no id, so this is the one place both kinds are decided.
+     *
+     * ## The fifth check: the concrete ROUTE, added 2026-09-08
+     *
+     * `presentedRequestUrl` is the request's own `originalUrl`, and its path must equal the path of the
+     * `uploadUrl` the grant recorded at mint. The other four checks pin the resource, the field, the
+     * write kind and (for UPDATE) the row — they do NOT pin which of a resource's several upload ROUTES
+     * was used. A resource whose operation declares more than one `initiatorInfo` registers one upload
+     * route per parent path, and `validateParameterCoherence` only pins the `{param}`s the TOKEN itself
+     * supplies (`organizationId`, `userId`, and the resource's own id via `relatedId`); every other
+     * segment — an intermediate parent id, a nested FK — comes from the URL alone and matched nothing.
+     * So a grant minted under one parent could be redeemed under another, and the minter's snapshotted
+     * roles would be re-decided there. This closes that: the grant unlocks the ONE route its mint was
+     * authorized on, which is the same route it publishes in `uploadUrl` / `uploadCommand` /
+     * `uploadPageUrl` and re-emits from the status read.
+     *
+     * It does NOT close anything the authorizer would refuse anyway (roles are still re-evaluated on the
+     * presented route), replay (SINGLE_USE consumption does that), or a leaked token being redeemed on
+     * the recorded route by whoever holds it — the token IS the credential, by design.
+     *
+     * Note this middleware also fronts the MINT route (`…/files/<field>/grant`), whose path differs from
+     * the recorded one by that last segment. A grant presented THERE is now refused here rather than two
+     * steps later by mint's own "a grant may not mint a grant" rule. Both refusals stay.
+     */
+    async assertGrantMatchesRoute(executionContext, target, presentedRequestUrl) {
+        if (executionContext.executionType !== ExecutionContext_ExecutionType.CONSUMABLE_TOKEN)
+            return undefined;
+        const tokenValue = executionContext.consumableTokenValue;
+        if (!tokenValue)
+            return undefined;
+        const token = await this.consumableTokenService.validateToken(tokenValue);
+        if (token.tokenType !== CoreConsumableTokenTypes.FILE_UPLOAD_GRANT)
+            return undefined;
+        const parsed = FileUploadGrantMetadataSchema.safeParse(token.metadata);
+        const mismatch = (reason) => this.errorBuilder.buildError(ErrorType.AUTHENTICATION, executionContext, {
+            customMessageReference: ErrorCustomMessageReference.FILE_UPLOAD_GRANT_TARGET_MISMATCH,
+            context: {
+                // diagnostic (log-only)
+                grantId: token._id,
+                reason,
+                routeTarget: target,
+                grantTarget: { resourceIdentifier: token.resourceIdentifier, relatedId: token.relatedId, metadata: parsed.success ? parsed.data : undefined },
+            },
+        });
+        if (!parsed.success)
+            throw mismatch('unparseable grant metadata');
+        const metadata = parsed.data;
+        if (token.resourceIdentifier !== String(target.resourceType))
+            throw mismatch('resource');
+        if (metadata.fieldName !== target.fieldName)
+            throw mismatch('field');
+        if (metadata.operation !== target.operation)
+            throw mismatch('operation');
+        if (target.operation === CoreResourceOperation.UPDATE ? token.relatedId !== target.resourceId : token.relatedId != null)
+            throw mismatch('resourceId');
+        // The two `undefined` clauses are REDUNDANT today and kept deliberately, which is worth stating so
+        // nobody "simplifies" them back out. An unreadable side already loses the inequality against a
+        // readable one, and `metadata.uploadUrl` is `z.string().url()` so the recorded side cannot be
+        // unreadable at all — the parse above refuses first. What they guard is the ONE case where the
+        // inequality would ADMIT: both sides unreadable, `undefined === undefined`. Reaching it needs that
+        // schema to loosen, so it cannot be pinned from a test; the pin covers the outcome (an unreadable
+        // request target is refused) rather than the clause.
+        const recordedPath = normalizeUploadRoutePath(metadata.uploadUrl);
+        const presentedPath = normalizeUploadRoutePath(presentedRequestUrl);
+        if (recordedPath === undefined || presentedPath === undefined || recordedPath !== presentedPath)
+            throw mismatch('uploadUrl');
+        return { token, metadata };
+    }
+    /**
+     * The uploader the redeemed file is attributed to: the MINTER, from the grant, never the grant itself.
+     *
+     * No cast: `metadata.minter.entityType` is the `FileUploaderEntityType` enum because the metadata
+     * schema says so, and the metadata reached here through `safeParse`. It carried
+     * `as FileUploaderPrincipal['uploadedByEntityType']` until 2026-09-08 — a cast that told the type
+     * system a closed union had been checked when nothing had checked it. The runtime was not actually
+     * open (`validateUploadedByEntityType` re-checks membership in the upload handler and again in
+     * `createFile`), so this was a lie to the compiler rather than a hole to the database; what it cost
+     * was the refusal landing three layers downstream, as a VALIDATION error mid-upload, at a parameter
+     * typed `unknown`, instead of at the boundary that parses the grant.
+     */
+    resolveUploaderFromGrant(metadata) {
+        return { uploadedBy: metadata.minter.id, uploadedByEntityType: metadata.minter.entityType };
+    }
+    /**
+     * After the one upload landed: write the produced fileId back and audit the redemption. Best-effort
+     * by contract — the upload has succeeded; a failure here is logged and the status read degrades to
+     * "REDEEMED, file unknown".
+     */
+    async recordRedemption(grant, file, executionContext) {
+        try {
+            await this.consumableTokenService.recordFileUploadGrantProducedFile(grant.token._id, file.fileId);
+        }
+        catch (error) {
+            this.logger.warn('File upload grant: produced-file write-back failed; status read will not name the file', {
+                grantId: grant.token._id, fileId: file.fileId, ...projectCaughtErrorLogFields(error),
+            });
+        }
+        await this.audit(executionContext, CoreAuditableEventType.FILE_UPLOAD_GRANT_REDEEMED, ResourceOperationRiskLevel.LOW, {
+            grantId: grant.token._id,
+            fileId: file.fileId,
+            mimeType: file.mimeType,
+            size: file.size,
+            minter: grant.metadata.minter,
+        });
+    }
+    /**
+     * Public status read: the token IS the credential, so anyone holding it learns the grant's state,
+     * the target and constraints (what the drop page renders), and — after redemption — the `fileId`
+     * and file status (what the agent needs). Never the file's name.
+     */
+    async readStatus(tokenValue) {
+        const token = await this.consumableTokenService.findTokenByValue(tokenValue);
+        if (!token || token.tokenType !== CoreConsumableTokenTypes.FILE_UPLOAD_GRANT) {
+            throw this.errorBuilder.buildError(ErrorType.NOT_FOUND, undefined, {
+                customMessageReference: ErrorCustomMessageReference.FILE_UPLOAD_GRANT_NOT_FOUND,
+            });
+        }
+        const parsed = FileUploadGrantMetadataSchema.safeParse(token.metadata);
+        if (!parsed.success) {
+            throw this.errorBuilder.buildError(ErrorType.NOT_FOUND, undefined, {
+                customMessageReference: ErrorCustomMessageReference.FILE_UPLOAD_GRANT_NOT_FOUND,
+                context: { grantId: token._id, reason: 'unparseable grant metadata' }, // diagnostic (log-only)
+            });
+        }
+        const metadata = parsed.data;
+        const resourceType = token.resourceIdentifier;
+        const constraint = await this.constraintResolver.resolve({ resourceType, fieldName: metadata.fieldName });
+        let file = null;
+        if (metadata.producedFileId) {
+            const produced = await this.readProducedFile(metadata.producedFileId);
+            if (produced)
+                file = { fileId: produced.fileId, status: produced.status };
+        }
+        return {
+            grantId: token._id,
+            state: this.deriveState(token),
+            expiresAt: token.expiresAt.toISOString(),
+            target: {
+                resourceType: String(resourceType),
+                fieldName: metadata.fieldName,
+                operation: metadata.operation,
+                resourceId: token.relatedId ?? null,
+            },
+            constraints: { maxBytes: constraint.maxSize, allowedMimeTypes: constraint.allowedMimeTypes ?? [] },
+            uploadUrl: metadata.uploadUrl,
+            uploadHeaderName: WildoHeaderKeys.CONSUMABLE_TOKEN,
+            file,
+        };
+    }
+    /**
+     * Revoke an unredeemed grant — by ID, never by value, and AUTHENTICATED: the minter, or a platform
+     * super-administrator. Revoke-by-value on a public route was rejected: anyone holding the link could
+     * burn it (harmless) while learning that it existed (not).
+     */
+    async revoke(grantId, executionContext) {
+        const token = await this.consumableTokenService.findTokenById(grantId);
+        if (!token || token.tokenType !== CoreConsumableTokenTypes.FILE_UPLOAD_GRANT) {
+            throw this.errorBuilder.buildError(ErrorType.NOT_FOUND, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.FILE_UPLOAD_GRANT_NOT_FOUND,
+            });
+        }
+        const parsed = FileUploadGrantMetadataSchema.safeParse(token.metadata);
+        const caller = resolveFileUploaderPrincipal(executionContext);
+        const isMinter = parsed.success && caller !== undefined
+            && caller.uploadedBy === parsed.data.minter.id && caller.uploadedByEntityType === parsed.data.minter.entityType;
+        const isSuperAdmin = (executionContext.initiatorRoles ?? []).some((entry) => entry.roles.includes(CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN));
+        if (!isMinter && !isSuperAdmin) {
+            throw this.errorBuilder.buildError(ErrorType.AUTHORIZATION, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.AUTHORIZATIONS_ACCESS_DENIED,
+                context: { grantId }, // diagnostic (log-only)
+            });
+        }
+        const revoked = await this.consumableTokenService.revokeToken(grantId);
+        if (revoked) {
+            await this.audit(executionContext, CoreAuditableEventType.FILE_UPLOAD_GRANT_REVOKED, ResourceOperationRiskLevel.LOW, {
+                grantId,
+                revokedBy: caller ? { entityType: caller.uploadedByEntityType, id: caller.uploadedBy } : null,
+                asSuperAdmin: !isMinter && isSuperAdmin,
+            });
+        }
+        return revoked;
+    }
+    // ── helpers ────────────────────────────────────────────────────────────────
+    /**
+     * Read the produced FILES row with no caller context — the status route is public and the token is
+     * the credential. Same mechanism as the file controller's token-access download path (an internal
+     * system context against the FILES repository, keyed on `_id`); only `fileId` and `status` leave here.
+     */
+    async readProducedFile(fileId) {
+        const internalContext = await this.executionContextCreator.createForInternalSystemOperation();
+        const filesRepository = this.repositoriesRegistry.getRepositoryOrThrow(CoreResourceType.FILES, internalContext);
+        const file = await filesRepository.read(internalContext, { _id: fileId });
+        return file ? { fileId: file.fileId, status: file.status } : null;
+    }
+    deriveState(token) {
+        if (token.revokedAt)
+            return FileUploadGrantState.REVOKED;
+        if (token.isConsumed)
+            return FileUploadGrantState.REDEEMED;
+        if (token.expiresAt.getTime() <= Date.now())
+            return FileUploadGrantState.EXPIRED;
+        return FileUploadGrantState.PENDING;
+    }
+    /** `null` for a headless application (no frontend service declared) — there is no page to hand a human. */
+    resolveUploadPageUrl(tokenValue) {
+        const config = this.appConfigService.config;
+        const frontendServiceName = this.appConfigService.resolveDefaultFrontendServiceName();
+        const base = frontendServiceName ? AuthControllerUtils.lookupFrontendPublicUrl(config, frontendServiceName) : null;
+        if (!base)
+            return null;
+        const trimmed = base.endsWith('/') ? base.slice(0, -1) : base;
+        return `${trimmed}${FILE_UPLOAD_GRANT_PAGE_PATH}/${encodeURIComponent(tokenValue)}`;
+    }
+    /**
+     * Refuse, at MINT, a declared file the field could never accept — the early half of the check the
+     * upload route performs on receipt. Only what was declared is checked; an undeclared fact is checked
+     * on the bytes. `allowedMimeTypes` empty means every type is accepted; a `type/*` entry matches its
+     * whole family, as the upload validator reads it.
+     */
+    assertDeclarationFitsConstraint(declared, constraint, executionContext, target) {
+        if (!declared)
+            return;
+        if (declared.size !== undefined && declared.size > constraint.maxSize) {
+            throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                context: { message: 'Declared file size exceeds the field maximum', declaredSize: declared.size, maxBytes: constraint.maxSize, fieldName: target.fieldName }, // diagnostic (log-only)
+            });
+        }
+        const allowed = constraint.allowedMimeTypes ?? [];
+        if (declared.mimeType && allowed.length > 0) {
+            const mime = declared.mimeType.toLowerCase();
+            const fits = allowed.some((a) => a.toLowerCase() === mime || (a.endsWith('/*') && mime.startsWith(a.slice(0, -1).toLowerCase())));
+            if (!fits) {
+                throw this.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+                    customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                    context: { message: 'Declared MIME type is not accepted by the field', declaredMimeType: declared.mimeType, allowedMimeTypes: allowed, fieldName: target.fieldName }, // diagnostic (log-only)
+                });
+            }
+        }
+    }
+    /** A declared file name reduced to what is safe inside a quoted shell argument. */
+    safeFileName(name) {
+        return name.replace(/[^\w.\- ]+/g, '_').replace(/\s+/g, ' ').trim().slice(0, 120) || 'file';
+    }
+    /** A plausible file name for the curl example, from the field name and the first allowed MIME type. */
+    suggestFileName(fieldName, allowedMimeTypes) {
+        const stem = fieldName.replace(/[^\w.-]+/g, '_').replace(/\./g, '-').slice(0, 40) || 'file';
+        const first = allowedMimeTypes?.find((m) => !m.endsWith('/*'));
+        const ext = first ? first.split('/')[1]?.replace(/^x-/, '').replace(/\+.*$/, '') : undefined;
+        return ext && /^[a-z0-9]{2,5}$/i.test(ext) ? `${stem}.${ext}` : stem;
+    }
+    buildNote(target, hasPage) {
+        const attach = target.operation === CoreResourceOperation.UPDATE
+            ? `then pass the returned fileId as "${target.fieldName}.fileId" when updating ${String(target.resourceType)} ${target.resourceId}`
+            : `then pass the returned fileId as "${target.fieldName}.fileId" when creating the ${String(target.resourceType)} record`;
+        const human = hasPage ? 'or show uploadPageUrl to the user so they can drop the file in their browser, ' : '';
+        return `Run uploadCommand if you can execute commands and the file is on your filesystem, ${human}${attach}. `
+            + 'The link is single-use and bound to this one field: if it expires or the upload is refused, mint a new one. '
+            + 'The header value is not your credential — it unlocks exactly one upload.';
+    }
+    async audit(executionContext, eventType, riskLevel, eventData) {
+        if (!this.auditLogsService) {
+            this.logger.warn('File upload grant: audit service unbound; event not recorded', { eventType });
+            return;
+        }
+        try {
+            await this.auditLogsService.logGenericEvent({
+                userId: executionContext.initiatorIds?.userId,
+                organizationId: executionContext.initiatorIds?.organizationId,
+                riskLevel,
+                eventType,
+                eventData,
+            }, executionContext);
+        }
+        catch (error) {
+            // An audit failure never fails the operation it observes; it is logged so it is not silent.
+            this.logger.warn('File upload grant: audit emission failed', { eventType, ...projectCaughtErrorLogFields(error) });
+        }
+    }
+};
+FileUploadGrantBackendService = __decorate([
+    injectable(),
+    __param(0, inject(SAAS_SERVICE_TYPES.Logger)),
+    __param(1, inject(SAAS_SERVICE_TYPES.ErrorBuilderService)),
+    __param(2, inject(SAAS_SERVICE_TYPES.ConsumableTokenService)),
+    __param(3, inject(SAAS_SERVICE_TYPES.FileConstraintResolverChain)),
+    __param(4, inject(SAAS_SERVICE_TYPES.FileFieldDetectionService)),
+    __param(5, inject(SAAS_SERVICE_TYPES.ExecutionContextCreatorBackendService)),
+    __param(6, inject(SAAS_SERVICE_TYPES.RepositoriesRegistryHandlerService)),
+    __param(7, inject(SAAS_SERVICE_TYPES.AppConfigService)),
+    __param(8, inject(SAAS_SERVICE_TYPES.AuditLogsService)),
+    __param(8, optional()),
+    __metadata("design:paramtypes", [Function, ErrorBuilderBackendService,
+        ConsumableTokenBackendService,
+        FileConstraintResolverChain,
+        FileFieldDetectionBackendService,
+        ExecutionContextCreatorBackendService,
+        RepositoriesRegistryHandlerBackendService,
+        AppConfigurationService, Function])
+], FileUploadGrantBackendService);
+export { FileUploadGrantBackendService };
+//# sourceMappingURL=file-upload-grant.backend.service.js.map