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

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

@@ -0,0 +1,214 @@
+/**
+ * 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.
+ */
+import { type FileUploadGrant, type FileUploadGrantMetadata, type FileUploadGrantOperation, type FileUploadGrantStatus, type ResourceConfiguration_Operation, type ResourceType } from '@wildo-ai/saas-models';
+import type { LoggerService } from '../../monitoring/logger/services/logger.service';
+import { ErrorBuilderBackendService } from '../../errors/services/error-builder.backend.service';
+import { AppConfigurationService } from '../../config/services/app-configuration.backend.service';
+import type { ExecutionContext } from '../../runtime/models/execution-context.backend.schemas';
+import { ConsumableTokenBackendService } from '../../security/consumable-tokens/services/consumable-token.backend.service';
+import type { ConsumableToken } from '../../security/consumable-tokens/models/consumable-tokens.shared.schemas';
+import { FileConstraintResolverChain } from '../../files/constraints/file-constraint-resolver-chain.backend.service';
+import { FileFieldDetectionBackendService } from '../../files/services/file-field-detection.backend.service';
+import { ExecutionContextCreatorBackendService } from '../../runtime/services/execution-context-creator.backend.service';
+import { RepositoriesRegistryHandlerBackendService } from '../../base-classes/services/repositories/repositories-registry-handler.backend.service';
+import { type FileUploaderPrincipal } from '../../files/utils/file-uploader.utils';
+import type { AuditLogsBackendService } from '../../compliance/audit-trails/services/audit-logs.backend.service';
+/** The route facts a grant is bound to, as the upload middleware knows them. */
+export interface FileUploadGrantTarget {
+    resourceType: ResourceType;
+    fieldName: string;
+    operation: FileUploadGrantOperation;
+    resourceId?: string;
+}
+export interface MintFileUploadGrantParams {
+    /** The MINTER's context, produced by the upload route's own authorization middleware. */
+    executionContext: ExecutionContext<any>;
+    target: FileUploadGrantTarget;
+    /** Requested lifetime; the engine ceiling is enforced at `createToken`, rejecting never clamping. */
+    expiresInMinutes?: number;
+    /**
+     * What the caller intends to upload (the File Objects proposal's `{name, mimeType, size}`). Checked
+     * against the field's constraints HERE so an impossible file is refused before a link exists.
+     */
+    declared?: {
+        name?: string;
+        mimeType?: string;
+        size?: number;
+    };
+    /** The concrete, absolute URL of the upload route this grant is for (the request's own URL minus `/grant`). */
+    uploadUrl: string;
+    /** Absolute API base including the mount prefix (e.g. `https://api.example.com/api/v1`), for the status URL. */
+    apiBaseUrl: string;
+    /** Request provenance for the audit row; never the token. */
+    requestProvenance?: {
+        ipAddress?: string;
+        userAgent?: string;
+    };
+}
+export declare class FileUploadGrantBackendService {
+    private readonly logger;
+    private readonly errorBuilder;
+    private readonly consumableTokenService;
+    private readonly constraintResolver;
+    private readonly fileFieldDetection;
+    private readonly executionContextCreator;
+    private readonly repositoriesRegistry;
+    private readonly appConfigService;
+    /**
+     * Optional so a harness without the audit stack can construct this service; in production the
+     * container always binds it. A missing service is logged at WARN on first use, never silent.
+     */
+    private readonly auditLogsService?;
+    protected logDebug: (message: string, context?: Record<string, unknown>) => void;
+    constructor(logger: LoggerService, errorBuilder: ErrorBuilderBackendService, consumableTokenService: ConsumableTokenBackendService, constraintResolver: FileConstraintResolverChain, fileFieldDetection: FileFieldDetectionBackendService, executionContextCreator: ExecutionContextCreatorBackendService, repositoriesRegistry: RepositoriesRegistryHandlerBackendService, appConfigService: AppConfigurationService, 
+    /**
+     * Optional so a harness without the audit stack can construct this service; in production the
+     * container always binds it. A missing service is logged at WARN on first use, never silent.
+     */
+    auditLogsService?: AuditLogsBackendService);
+    /**
+     * 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<T extends ResourceConfiguration_Operation<any, any, any>>(operation: T): T;
+    /**
+     * 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.
+     */
+    mint(params: MintFileUploadGrantParams): Promise<FileUploadGrant>;
+    /**
+     * 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.
+     */
+    assertGrantMatchesRoute(executionContext: ExecutionContext<any>, target: FileUploadGrantTarget, presentedRequestUrl: string): Promise<{
+        token: ConsumableToken;
+        metadata: FileUploadGrantMetadata;
+    } | undefined>;
+    /**
+     * 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: FileUploadGrantMetadata): FileUploaderPrincipal;
+    /**
+     * 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".
+     */
+    recordRedemption(grant: {
+        token: ConsumableToken;
+        metadata: FileUploadGrantMetadata;
+    }, file: {
+        fileId: string;
+        mimeType: string;
+        size: number;
+    }, executionContext: ExecutionContext<any>): Promise<void>;
+    /**
+     * 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.
+     */
+    readStatus(tokenValue: string): Promise<FileUploadGrantStatus>;
+    /**
+     * 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).
+     */
+    revoke(grantId: string, executionContext: ExecutionContext<any>): Promise<boolean>;
+    /**
+     * 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.
+     */
+    private readProducedFile;
+    private deriveState;
+    /** `null` for a headless application (no frontend service declared) — there is no page to hand a human. */
+    private resolveUploadPageUrl;
+    /**
+     * 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.
+     */
+    private assertDeclarationFitsConstraint;
+    /** A declared file name reduced to what is safe inside a quoted shell argument. */
+    private safeFileName;
+    /** A plausible file name for the curl example, from the field name and the first allowed MIME type. */
+    private suggestFileName;
+    private buildNote;
+    private audit;
+}
+//# sourceMappingURL=file-upload-grant.backend.service.d.ts.map

package/dist/esm/files/services/file-upload-grant.backend.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-upload-grant.backend.service.d.ts","sourceRoot":"","sources":["../../../../../src/files/services/file-upload-grant.backend.service.ts"],"names":[],"mappings":"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"}