Prepare Image and File Uploads

Purpose

A staff member needs a shared way to send a selected file before saving its owning record. Upload issuance provides an expiring staging address and an accountable declaration.

How It Works

The editor declares the destination field and the file characteristics. Platform validates size, media type and filename. It creates a staging location and signs the upload request. The browser sends the bytes directly to storage using the returned headers. The response also contains the reference needed by the record save. Issuance records and audits the request. The owning save remains responsible for preparing and attaching the asset, and issuance alone does not prove that save-side enforcement.

Relationships

Image and file definitions identify the intended use. Custom-record saving delegates managed file preparation to the shared asset pipeline.

Show evidence (sources, provenance, origins, pinned commits)

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes: A staff member needs a shared way to send a selected file before saving its owning record.Issuance records and audits the request.
Surfaces: consoleapi
Preconditions: The caller can request uploads; record-write permission is evaluated separately.
Postconditions: Issuance leaves one upload declaration and its security audit event.
Intent sources: services-platform:docs/milestones/PLAT-M10-image-and-file-fields.md#D1, D4services-platform:docs/milestones/plans/PLAT-M10-plan.md#6. Approach; 9. Acceptance scenarios

Controls

31 controls apply, from the corpus control catalogue.

TC-AVL-005 TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-CRY-001 TC-CRY-002 TC-CRY-003 TC-CRY-004 TC-DAT-001 TC-DAT-002 TC-DAT-003 TC-IAM-001 TC-IAM-002 TC-IAM-004 TC-IAM-005 TC-LOG-002 TC-LOG-003 TC-LOG-004 TC-LOG-005 TC-PI-001 TC-PI-003 TC-PI-005 TC-PRV-001 TC-PRV-002 TC-TEN-001 TC-TEN-002 TC-TEN-003 TC-VEN-001 TC-VEN-002 TC-VEN-003

Permissions

Key	Checked at	Scope
`platform.files.upload`	api	tenant

Business Rules

8 rules, 8 to be proved before approval. A rule's product intent is derived from its origin: 8 confirmed by a product decision, the rest inheriting this capability's confirmed.

Id	Rule	Kind	Enforced at	Provenance
`01`must prove Confirmed	Upload issuance requires the upload permission, held by Platform Administrator and User but absent from Read Only; refusal issues nothing. origin: services-platform:docs/milestones/plans/PLAT-M10-plan.md#PLAT-M10-S11 proved by `ATS-PFM-MTD-007-01`, `TST-PFM-MTD-078`, `TST-PFM-MTD-084`	permission	api	test services-platform:modules/files/tests/e2e/files.e2e.spec.js#is refused 403 by the dispatcher, and nothing is issued
`02`must prove Confirmed	The signed caller context must include the workspace named in the route, and requests cannot substitute a workspace in the body or use another customer’s workspace. origin: services-platform:docs/milestones/plans/PLAT-M10-plan.md#PLAT-M10-S04 proved by `ATS-PFM-MTD-007-02`, `TST-PFM-MTD-078`, `TST-PFM-MTD-082`	permission	api, service	test services-platform:modules/files/tests/e2e/files.e2e.spec.js#refuses a body that names a workspace of its own
`03`must prove Confirmed	Upload size must be a positive whole byte count within ten mebibytes for images or twenty-five for files; oversized requests name the size problem without signing or recording an upload. origin: services-platform:docs/milestones/PLAT-M10-image-and-file-fields.md#D4 (Andrew, 2026-10-19: 10 MiB / 25 MiB) proved by `ATS-PFM-MTD-007-03`, `TST-PFM-MTD-082`, `TST-PFM-MTD-083`	validation	service	test services-platform:modules/files/tests/integration/services/uploads/issue-upload.integration.spec.js#refuses a picture over 10 MiB, naming size, and signs and records nothing
`04`must prove Confirmed	Images permit JPEG, PNG, GIF and WebP but exclude SVG; files additionally permit supported document, text, spreadsheet and archive formats, while mismatched image types and executables are refused. origin: services-platform:docs/milestones/plans/PLAT-M10-plan.md#4. Assumptions A7 (Andrew, 2026-10-08: SVG refused) proved by `ATS-PFM-MTD-007-04`, `TST-PFM-MTD-083`	validation	service	test services-platform:modules/files/tests/integration/services/uploads/issue-upload.integration.spec.js#refuses an SVG picture, naming content_type, and signs and records nothing
`05`must prove Confirmed	Platform derives staging location from workspace, record-type folder, a fresh upload identifier and a safe filename, uses public staging for images and rejects filenames containing paths. proved by `ATS-PFM-MTD-007-05`, `TST-PFM-MTD-083`	calculation	service	test services-platform:modules/files/tests/unit/upload-keys.spec.ts#is tmp, the workspace, the object folder, a public- upload directory for a picture, and the file name
`06`must prove Confirmed	The signed upload expires after fifteen minutes and binds declared type, length and uploader identity so storage rejects a changed declaration and saving can identify the uploader. origin: services-platform:docs/milestones/plans/PLAT-M10-plan.md#6. Approach proved by `ATS-PFM-MTD-007-06`, `TST-PFM-MTD-078`, `TST-PFM-MTD-085`	policy	service	test services-platform:modules/files/tests/unit/upload-presign.spec.ts#signs the type, the length and both metadata headers, so S3 refuses a PUT that changes any
`07`must prove Confirmed	Issuance records caller, object, field, location, type, size and expiry together with its security audit event. origin: services-platform:docs/milestones/plans/PLAT-M10-plan.md#7. Deliverables proved by `ATS-PFM-MTD-007-07`, `TST-PFM-MTD-082`	policy	service, database	test services-platform:modules/files/tests/integration/services/uploads/issue-upload.integration.spec.js#appends one file_upload audit event naming who was given the upload and for what
`08`must prove Confirmed	The owning save checks and copies uploaded or web-address files into managed storage and must refuse staging files issued to a different saving person. origin: services-platform:docs/milestones/PLAT-M10-image-and-file-fields.md#D1 (Andrew, 2026-10-19: copy at save) proved by `ATS-PFM-MTD-007-08`	policy	service	documented services-platform:docs/files.md#The signature

Scenarios

Id	Given	When	Then	Provenance
`01`	A staff editor is selecting Ruth Kim contact photo.	Request staging for a forty-eight-kilobyte JPEG.	The response supplies an upload identity, expiring PUT address, required headers and save reference.	test services-platform:modules/files/tests/e2e/files.e2e.spec.js#answers a PUT upload with the headers and the staging reference of this workspace

Edge Cases

Id	Given	When	Then	Provenance
`02`	The caller has customer administrator permissions.	Request an oversized image and an SVG upload.	Both requests identify the size or media-type problem and issue nothing.	test services-platform:modules/files/tests/e2e/files.e2e.spec.js#is refused an SVG picture by its type, and nothing is issued

Planning

Implementation

Prepare Image and File Uploads ​

Purpose ​

How It Works ​

Relationships ​