Secure Resident Document Upload and File Validation for AFHs

Resident document upload is more than a file picker. An adult family home system must keep the file with the correct resident and facility, reject unsafe or unsupported content, preserve the original evidence, control every view and download, and make deletion or replacement traceable.

This guide addresses application security and record workflow, not a legal opinion about which documents a facility must retain. It was reviewed on August 8, 2026. Providers should verify current licensing, privacy, retention, employment, health-record, and resident-specific requirements.

Define document classes before accepting files

Create a controlled type list that reflects real operations, such as:

• Resident identification and contacts
• Assessments and negotiated care plans
• Practitioner orders and medication documents
• Consents, acknowledgements, and rights information
• Incident follow-up evidence
• Insurance and benefit records
• Admission, transfer, and discharge records
• Caregiver credentials and training evidence
• Facility licenses, inspections, and policies

Each class needs an owner, permitted file formats, maximum size, resident or facility scope, required metadata, expiration behavior, access roles, retention rule, and deletion authority.

Do not make “Other” the default for most uploads. A controlled exception category can exist, but require a meaningful title and authorized review so important records remain discoverable.

Bind the upload to the correct context

Display the active facility, resident, document class, and uploader above the drop zone. If a resident is selected from search, keep the resident identity visible through preview and confirmation.

The server must independently verify that the uploader can access that facility and resident. Never rely on a hidden browser field or URL parameter. A multi-facility user should not carry a resident selection into another facility silently.

Use a final confirmation sentence such as “Upload to Maria Santos at Cedar View AFH” and allow the user to go back without losing the selected file. This small step helps prevent wrong-resident filing.

Allow only formats the workflow needs

The OWASP File Upload Cheat Sheet recommends allowlisting necessary extensions, validating types rather than trusting the submitted Content-Type header, generating application filenames, limiting size, restricting upload authorization, and scanning where available.

For an AFH, a narrow list might include PDF and specific image formats. Add DOCX only when the business case and preview process are defined. Reject executables, scripts, HTML, archives, macro-enabled office files, and double-extension tricks unless a separately secured process truly requires them.

Validate the extension, declared MIME type, detected file signature, parser result, and policy together. A valid PDF header alone does not prove the rest of the content is safe.

Quarantine before making a file available

Upload into a private quarantine area with a random storage key. Do not let the original filename determine a storage path, public URL, or executable behavior.

The processing pipeline should:

1. Enforce request and per-file limits.
2. Calculate a cryptographic checksum.
3. Detect actual type and basic structural validity.
4. Scan for malware using a maintained service.
5. Apply content disarm or safe rendering where appropriate.
6. Extract metadata in an isolated worker.
7. Generate a safe preview rather than executing active content.
8. Move the approved object into protected storage.
9. Persist the audit event and visible status.

If scanning is unavailable, keep the object quarantined and tell the user it is pending. Do not treat “scan service timed out” as “clean.”

Limit decompression and parser risk

Office files, images, and PDFs can consume extreme memory or exploit vulnerable parsers even when the extension looks ordinary. Set limits for compressed size, expanded size, page count, pixel dimensions, embedded objects, processing time, and recursion.

Run conversion and optical character recognition in isolated, least-privileged workers with current libraries. Terminate work that exceeds limits. The main application process should not parse arbitrary uploads directly.

Preserve the original file in protected storage if policy requires it, but deliver a safe derivative for routine preview when appropriate. Clearly label which version the user is viewing.

Preserve useful metadata without trusting filenames

Store the original filename only as display metadata after cleaning control characters and limiting length. Generate the actual object key independently.

Capture:

• Document title and class
• Resident and facility
• Original filename and detected type
• Size, page count, and checksum
• Uploader and upload time
• Document date and effective period
• Expiration date if applicable
• Source or issuing organization
• Processing and scan status
• Storage and encryption version
• Current version and prior versions

Do not infer a resident, expiration date, or document class from OCR alone. Extracted suggestions should remain unconfirmed until a user reviews them.

Make previews safe and accessible

A preview should not expose a permanent public object URL. Authorize each request on the server, then stream through a protected handler or issue a short-lived, narrowly scoped URL.

For PDFs and images, provide page navigation, zoom, download if authorized, and a clear filename. Include an accessible list view for users who cannot use the visual preview. Do not trap keyboard focus in a modal or cover confirmation controls on a small screen.

If a preview cannot be generated, show the reason and permitted next action. Never render uploaded HTML or active script in the application's origin.

Separate upload, verification, and approval

Use explicit statuses:

• Uploading
• Processing
• Quarantined
• Ready for review
• Verified
• Rejected
• Superseded
• Deleted under policy

Uploading proves only that bytes arrived. Verification may confirm identity, dates, completeness, or issuing source. Approval may be needed before a document changes a workflow, such as accepting a medication order or credential.

Record each transition with actor, timestamp, reason, and source evidence. A processing failure must not be mislabeled as a user rejection.

Prevent silent replacement

When a user uploads a new version, create a version relationship. Retain the prior file, metadata, reviewer, and effective period according to policy. Do not overwrite the object in place.

Show a comparison of title, document date, expiration, source, and file checksum. If the same checksum already exists for that resident and class, warn about an exact duplicate and let an authorized user link or cancel.

A similar filename is not proof of duplication. Conversely, renaming identical bytes should not create an unnoticed second source of truth.

Design recoverable deletion

The documents module should include a deleted view for authorized users. A normal delete action should move the record to a recoverable state, capture who deleted it and why, and remove it from everyday views.

Define who may restore, how long recovery remains available, and when permanent deletion is permitted. Legal hold, investigation, licensing, or resident-record retention rules may prevent disposal.

Permanent deletion must remove the object and derivatives through a controlled lifecycle while retaining the minimum required audit evidence. Never offer an unbounded bulk-delete action across facilities.

The document management software guide covers broader organization, expiration, permissions, and retrieval workflows.

Protect confidentiality and integrity

WAC 388-76-10315 requires resident records to remain confidential, available only to authorized persons, and protected against loss, destruction, alteration, and unauthorized use.

Apply encryption in transit and at rest, tenant- and facility-aware authorization, least-privilege service identities, key rotation, backup controls, and immutable audit events. Do not place resident documents in a public web directory or indexable URL.

Log views, downloads, exports, uploads, replacements, restores, and permanent disposal. Restrict support access and make it attributable.

Handle failed and interrupted uploads clearly

Show progress based on bytes actually transferred. For resumable uploads, bind every chunk to the same authenticated session, expected size, checksum process, resident, and facility.

If a connection fails, label the item incomplete and offer a safe retry. Do not create a visible resident document until processing reaches the defined state. Expire abandoned chunks and quarantine objects automatically.

When a file exceeds a limit or has an unsupported type, explain the accepted formats and size without revealing security internals. Preserve other form metadata so the user does not repeat the entire workflow.

Support reports and review queues

Authorized managers need filters for:

• Facility and resident
• Document class and status
• Upload, document, effective, or expiration date
• Verification owner
• Missing required metadata
• Processing failure
• Expiring or expired documents
• Replaced and deleted records
• Source organization

Exports should list metadata and status without automatically bundling every protected file. A separate, authorized archive export can use encryption, manifest checksums, generation time, and expiring delivery.

Test hostile and accidental cases

Use nonproduction residents and safe test files to verify:

1. Valid PDF uploaded to the intended resident.
2. User switches facility before final confirmation.
3. Renamed executable is rejected.
4. Spoofed MIME type is detected.
5. Double extension is rejected.
6. Oversized file fails before exhausting resources.
7. Extreme page or pixel count is stopped.
8. Malware scanner timeout remains quarantined.
9. Duplicate checksum is flagged.
10. Upload is interrupted and resumed once.
11. Expired session cannot finish an upload.
12. Unauthorized resident preview and download are denied.
13. New version preserves the old document.
14. Deleted item appears only in the authorized deleted view.
15. Restore and permanent disposal create audit events.
16. PDF preview remains usable on phone and desktop.

Inspect storage as well as the interface. Confirm that rejected, abandoned, and deleted derivatives do not remain publicly retrievable.

Frequently asked questions

Is checking the filename extension enough?

No. Use an allowlist together with type detection, signature and parser checks, limits, scanning, authorization, private storage, and safe delivery.

Should uploaded files be immediately downloadable?

Only after the defined validation and scan state. Keep incomplete or uncertain files quarantined and display their status.

Can OCR assign the document to a resident automatically?

OCR can suggest metadata, but an authorized user should confirm resident, facility, class, dates, and source before filing.

What should deletion do?

Ordinary deletion should be recoverable, permission-controlled, and audited. Permanent disposal must follow retention, hold, and approved lifecycle rules.

Can two files with the same name be different?

Yes. Use checksums and version relationships, not filenames alone, to identify exact duplicates and replacements.

Make every file safe, attributable, and retrievable

Secure document management binds the file to the right resident, validates content in quarantine, protects delivery, preserves versions, and makes recovery and disposal accountable. Those controls improve usability because staff can trust what each status means.

Explore AFH Manager to test resident document upload, validation states, safe previews, version history, deleted-file recovery, expiration filters, and audit reporting with controlled sample documents.