Storage and signed links
A stored file has an object identity and an application context. In Supabase Storage, the object identity is the bucket plus its path. Toolora’s application records associate that object with a company, project, conversation or other resource. A signed URL permits time-limited retrieval of that object; it does not create a customer-publication decision or a new relationship to the resource.
Publication owns audience decisions. Row-level security owns caller database access, while portal admission and worker/subcontractor access identify the additional conditions on privileged readers. A hidden UI control or a company-looking path alone does not enforce these rules.
Objects, metadata and content evidence
Section titled “Objects, metadata and content evidence”storage.objects holds Storage metadata. The file bytes are obtained through
Storage, not by selecting that table. entity_files holds application metadata
such as entity type/ID, company, display filename, path, content flags and soft
deletion. Conversation messages and UE submissions use their own attachment/photo
fields. Frozen invoice delivery bytes are another record family entirely.
The record model describes these ownership differences.
A metadata row can exist without an available object. content_valid=false marks
known unavailable content, including deferred imports. Conversely, a true flag
is not a universal fresh download, hash verification or malware scan. Staff project
registration checks its resource and canonical path but does not download/hash the
object. Quote assets, verified purchase originals and archive attachments have
more specific byte/hash contracts.
Path templates below use placeholders for stored IDs; they are not real credentials or URLs. The helpers reject a path that needs normalization instead of repairing it into a different resource. Project paths must have exactly three segments, match the specified company/project, and contain no traversal, leading slash, backslash, null byte or extra folder. The filename key is normalized separately from its human display name. A valid UUID in another company’s folder is still an unauthorized target.
| Selected family | Object and application binding | Writer and retrieval boundary | Lifecycle limit |
|---|---|---|---|
| Project file | Private project-files; <company>/<project>/<leaf>; entity_files project/company row |
Staff upload through Storage RLS, then register through scoped API. Customer, worker and UE readers apply different API conditions described below. | Soft deletion removes current metadata discovery, not necessarily stored bytes or an issued URL. |
| Opportunity attachment | Private opportunity-files; <company>/<opportunity>/<file-id>_<leaf>; entity_files |
Browser Storage and metadata policies require their respective read/write capabilities and company context. UI preview signs the selected object. | Upload/link requests are separate; removal soft-deletes metadata and retains bytes. |
| Checklist photo | Private checklist-photos; checklist/<project>/<item>.<extension>; checklist item’s photo reference |
Storage writes check the item, company/project, photo requirement and assignment or work-order write capability. Current reads use company plus work-order capabilities or published assigned work. | The later worker-day migration makes the bucket private; the older public baseline is not the current rule. |
| Conversation attachment | Private conversation-attachments; <company>/<conversation>/<unique-leaf>; message attachment path |
Browser Storage policy uses conversation membership/context. Privileged routes establish their conversation audience, validate the message’s canonical path and sign already scoped reads. | Upload does not itself create a message. A closed or hidden conversation has its own access rules. |
| UE evidence and offer photos | Submission photos use project-files under <principal>/ue-submissions/<commitment>/<leaf> and submission JSON; offer photos use service-only ue-listing-photos and listing metadata |
Executor commitment or offer/invitation access is checked by the API. Direct browser access to offer-photo bytes is denied even to a project administrator. | Submission work-order validation occurs after photo upload; there is no universal atomic upload/link cleanup. |
| Agent quote-draft image | Private service-only quote-draft-assets; <company>/<proposal>/r<revision>/<asset>.<extension> and asset row |
Scoped draft service validates image, proposal and revision, stores original bytes/hash and registers through RPC. Review signs selected assets. | Duplicate-content recognition and best-effort removal on registration failure are specific to this flow. |
| Purchase/mail original or frozen invoice PDF | Purchase originals can use purchase-invoice-files; mail originals remain in Estate; invoice delivery stores frozen PDF bytes/hash |
Purchase resolver binds company/invoice and checks bytes against registered size/hash. Mail route checks mailbox/item access and verifies an attachment against its archive original. Invoice delivery uses its own scoped frozen-document contract. | These are not interchangeable signed Storage links; missing archive/original coverage remains unavailable evidence. |
| Public tenant asset | tenant-assets is public in the active bucket definitions |
Public retrieval does not require a Toolora portal session. Upload/delete still have their own policies. | Public availability is not a private-document access model. |
Browser Storage access and privileged issuance
Section titled “Browser Storage access and privileged issuance”For an opportunity attachment, the browser first uploads the object and then
inserts its entity_files row. The active Storage policy checks the company
folder and opportunities:update for writes. Its SELECT policy includes
opportunities:read and an administrator branch; the applicable ALL write policy
can also allow a read. Metadata policies have their own entity-dependent
capability cases. A successful object upload does not establish that the metadata
insert succeeded, and a visible metadata row does not supply missing Storage
permission.
Project Storage reads have separate company capability, cross-project-origin
relationship and administrator branches. Ordinary writes require the company
folder and projects:write. Those SQL expressions are not a universal substitute
for a portal’s project/audience checks. Inspect the final policies after capability
reconciliation and later worker/conversation changes; policy comments in an old
migration may describe an earlier state. Malformed folder IDs can also fail a
SQL cast rather than yield an empty read.
Private buckets require authorized access or a signed URL. Public buckets allow retrieval by URL while retaining controls on other operations. Supabase’s bucket model explains that distinction. Its Storage access-control guidance explains policies and service-key bypass. Toolora’s service-role client bypasses Storage RLS, so the API must establish scope before issuing a URL or retrieving bytes.
For customer project files, the API admits the customer to the project, filters company/project metadata for current customer visibility, valid content and no soft deletion, then checks the exact canonical path before signing. A row in project A that names project B’s object is not signed merely because both belong to the same company. The response exposes selected display metadata and a signed URL, without echoing the internal path. Signing failure omits that file from the customer projection.
Worker files require unrevoked work_order_file_links for the worker’s exact
assigned published orders. The current loader selects valid, non-deleted
customer_upload project files and permits PDF/JPEG/PNG/WebP. Customer visibility
alone does not publish a file to workers. Revoking the order link does not delete
the project file or alter its customer flag.
The UE project-file loader verifies company/project and canonical path but does not apply the customer’s visibility/content-validity filters or an explicit UE file-publication filter. This existing broader projection remains a concrete limit, not proof that every project file was deliberately published to that executor. The assignment article owns the corresponding work-room rules.
flowchart TD B[Browser with company session] --> M[Application metadata query: caller RLS] B --> S[Private Storage operation: object policy] M --> U[Request signed link for selected object] S --> U P[Portal or API request] --> A[Identity, capability, resource and audience checks] A --> C[Canonical path and selected content checks] C --> R[Service-role signing: Storage RLS bypass] U --> L[Signed URL with operation-specific lifetime] R --> L L --> D[Storage validates retrieval token and object availability] D --> X[Downloaded bytes or local copy] W[Later publication withdrawal] --> F[Future issuance can be refused]
Link lifetime and bearer possession
Section titled “Link lifetime and bearer possession”A private signed URL is a bearer retrieval credential. Anyone who obtains it can attempt retrieval during its validity; opening it is not a new customer/worker admission request to Toolora. Keep full URLs/tokens out of logs and examples. Request a new URL through the authorized screen/API when an old one expires. A company cache key separates cached data; it is not a revocation mechanism.
| Current issuer or path | Requested lifetime | Important distinction |
|---|---|---|
| Staff project/opportunity preview and purchase-file signer | 3,600 seconds | Issuance uses the browser’s current Storage authority. Metadata may remain visible after signing fails. |
| Customer project files | 3,600 seconds | Each issuance follows portal/project, visibility/content and path checks. |
| Worker approved files and checklist-photo helper | 300 seconds | Work-order delivery and checklist-photo checks are distinct; old public checklist references are parsed only as scoped references. |
| Project conversation attachments | 3,600 seconds | Signer operates on an already scoped message read; it is not an independent audience policy. |
| UE offer/project/submission-photo signers | 3,600 seconds | Offer, commitment, canonical path and project-file projection differ by path. |
| Agent quote-draft asset review | 300 seconds | Draft/proposal authority is distinct from a published quote/customer file. |
| Mail attachment response or frozen invoice PDF | No universal Storage URL expiry | Authenticated byte responses, archive read references and frozen documents have their own retrieval/delivery contracts. |
These values are the callers’ current requested TTLs, not one system-wide promise. Expiry, object availability and Storage verification govern retrieval. Withdrawal can prevent future issuance without recalling an unexpired URL or downloaded bytes. Soft-deleting metadata likewise is not physical object deletion. Public assets and copies already delivered have different boundaries.
browser_reachable_storage_url rewrites eligible internal loopback Storage URLs
onto the configured HTTPS frontend origin for the callers that use it. It preserves
the signed path/query and leaves ineligible URLs unchanged. This solves browser reachability; it does not widen permission, renew the
signature or guarantee every signer uses that helper. Conversation presentation
removes the internal stored path and can omit an unavailable attachment without
making the whole dialogue unreadable.
Mail attachments illustrate another contract. The scoped route reads the selected archive original and extracts the attachment matching its recorded SHA-256 and MIME evidence. It returns bytes with private/no-store and content-type handling. It does not turn a mailbox attachment into a public Storage object. The mail-original owner and Estate integration explain coverage. The settlement workflow owns frozen invoice PDF review, document hashes and delivery evidence.
Uploads and metadata do not share one transaction
Section titled “Uploads and metadata do not share one transaction”Staff project upload stores bytes first and then registers their metadata through the API. If registration fails, the UI reports that the file uploaded but could not be linked; that path has no general compensating object removal. Registering the same filename is not a general idempotent replay contract.
Opportunity upload uses a UUID-based metadata identity. If the insert response fails, it checks whether that exact company/file row persisted before cleanup. A found row is acknowledged; a successful absence check allows object removal. An uncertain read does not justify deleting a potentially committed object. This specific recovery is not shared automatically by every uploader.
Customer project upload first admits the customer, checks allowed type and bounded bytes (20 MiB), verifies the selected file signatures and builds a canonical path. It writes private-by-default customer-upload metadata and attempts object removal if registration fails. Signature checks are not a general malware/content review. Subsequent staff inspection/publication is separate. Compensation is best effort; object and database requests remain separate failure boundaries.
Conversation upload returns a path, filename, MIME and size before the later message write. Worker and assigned-UE message routes have their own 20 MiB guards; a bucket’s configured maximum and MIME restrictions are separate from route checks. Conversation keys use unique prefixes and uploads disallow overwrite. Attaching the returned path to a message must still pass that conversation’s scope check.
UE submission admits the executor commitment before uploading, but its final work-order association check runs afterwards. Photos can therefore be stored before a later scope refusal. The current photo helper reads files fully and uses overwrite-enabled uploads; it does not inherit the message route’s bounded read/signature checks. Preserve this ordering/validation limit rather than claim all rejected submissions have no Storage effects. Object deletion, orphan cleanup and retry behaviour must be established for the actual flow.
Transaction boundaries distinguish a local atomic metadata operation from these external Storage requests. No bulk repair, file migration or shared-data cleanup follows merely from discovering an orphan.
Examples and recovery
Section titled “Examples and recovery”A synthetic company-A opportunity writer can upload under its own company folder with the required capability. The same caller targeting company B’s folder is refused by the ordinary Storage write policy. A missing write capability also refuses an own-company upload. These are different checks from whether a portal may sign an already registered project file.
For a customer, a company-A/project-P file pointing to project Q’s canonical folder is excluded before signing. A correctly scoped but hidden or invalid file is also excluded. If the file was previously visible and its URL later expires, reload the authorized project view: a still-published file can receive a new link, while a withdrawn file no longer qualifies for that customer projection.
| Symptom | Inspect | Recovery |
|---|---|---|
| Metadata is visible but opening fails | Exact bucket/path, object availability, Storage permission and URL age | Reload through the current authorized path. Retain unavailable metadata where its source requires evidence. |
| Foreign-company or malformed path refused | Token company, relevant policy and canonical resource binding | Correct the intended target; do not normalize traversal or sign an arbitrary supplied URL. |
| Customer cannot see a staff-visible file | Portal admission, customer flag, content flag, soft deletion and canonical project | Resolve the actual condition and deliberately publish if appropriate. Staff access alone is insufficient. |
| Worker cannot see a customer-visible file | Exact published assignment, unrevoked order-file link, selected category/type | Use the worker-publication action for that order. Do not broaden the project query. |
| Upload succeeded but linking failed | Whether the exact metadata write committed and whether the object remains | Follow that uploader’s reconciliation/cleanup contract; do not assume a database rollback removed bytes. |
| Withdrawn file still opens through an old URL | Issued URL lifetime, caches and downloaded copies | Stop future issuance through the owning publication rule; do not promise recall of existing copies. |
| Original is missing or hash verification fails | Source version, company/invoice/mailbox binding and byte coverage | Report unavailable evidence. Do not substitute another document merely because its filename matches. |
Actual database tests exercise Storage metadata policies under authenticated/anon roles, including company/capability denials, private checklist scope and service-only quote/offer-photo buckets. They do not download real object bytes through Storage. Some capability tests install a named historical migration and retain that scope. Mocked API tests cover canonical/foreign paths, hidden/invalid files, failed signing and publication differences; those are not live signed-link expiry or cache tests. The delivery PR records executed versus reused results with identical inputs. No shared private attachment or provider write is needed for this reference.