Skip to content

Attachments ​

An attachment is a file hung on one entity. The metadata fact lives in the scope's own database, in _substrat_attachments, written in the same transaction as an attachment.added event. The bytes go to the tenant's blob store and never through invoke. A vertical opts an entity type in with attachmentTargets in its manifest:

ts
attachmentTargets: [
  { entityType: 'contract', readPermission: 'contract:read', writePermission: 'contract:write' },
],

readPermission gates list and open. writePermission gates upload and remove, and defaults to the read key. Both are checked on the owning entity, so an entity-narrowed grant resolves exactly as it does for ctx.check.

The attachment surface is on the host, not on ctx: host.attachments(principal, tenantId, scopeId) returns upload, list, open, openStream, remove and search. The platform ships no upload route. A vertical mounts its own, calls upload with the bytes, and decides what the platform does not: the size cap, which file types it accepts, any scanning. The kernel itself checks the write key and records the file. For a link share's read-only door, see Permissions.

Serving files from a deployed worker ​

A deployed worker reaches files through its door, as it reaches operations, so a route never names whose files it reads. door.attachments(c) is the signed-in person's file surface, minted from the session as door.scope(c) is, and a 401 for nobody. Name attachments and the door serves and removes a file itself:

ts
const door = workerDoor<Env>({ directory, nodeFor, hostFor, envSpec, attachments: true });
RouteAnswer
GET /api/attachments/:attachmentId200 with the file, or 206 with the byte range asked for
DELETE /api/attachments/:attachmentId204

Each runs as the signed-in person, so a read is gated by the target's readPermission and a removal by its writePermission, on the entity the file hangs on. An id the person cannot read is the same 404 as an id that does not exist.

The file is streamed from the blob store as the response is written, never held whole. A Range header naming one byte range is answered with a 206 and only those bytes are read from the store, so an <audio> or <video> element pointed at the route plays and seeks; a range with no byte in the file is a 416. The ETag is the file's SHA-256, which never changes under an id. A ranged read holds the slice to the recorded size but cannot check the SHA-256, which needs every byte; a whole read checks both. The response is always a download (Content-Disposition: attachment) and carries the headers in the warning below, which a media or image element ignores, so the same URL plays in the page and saves when opened directly.

A route of your own answers the same way through serveAttachment from @substrat-run/vertical-host:

ts
app.get('/api/recordings/:id', async (c) => {
  hardenFileResponse(c);
  try {
    return await serveAttachment(c, await door.attachments(c), c.req.param('id'));
  } catch (err) {
    return problemResponse(c, err);
  }
});

That leaves one gap. An MCP client calling an operation has no cookie and often no bearer for the vertical's own route, and a file of any real size cannot go through a tool call as base64. Upload links close it.

Bounds on what an upload names ​

Every door that stores a file judges the strings that describe it before a byte is written, and refuses one that is too long: a filename over 512 characters, a content type over 255, an entity type over 128, an entity id over 255 or a creator over 128 (counted in UTF-16 units, the unit JavaScript's length counts). A connector reads the record back through a response header, and these bounds keep it small however many of those characters are non-ASCII. A file stored before the bounds is still read back; if a string on it is long enough to overflow the header, that string is cut to its bound and ends in … (a content type is sent as application/octet-stream; a creator recorded as a JSON actor, once cut, is no longer valid JSON, and the … marks it), and everything else about the file is exact. A link's entity is held to the same bounds when the link is minted.

Streamed bodies ​

upload takes the bytes as a buffer or as a sized stream, { stream, length }, where length is what the producer declares. A stream goes to the blob store as it is read, and its sha256 and size are taken on the way, so a file never has to fit in memory. The declared length is held: a stream that carries more or fewer bytes lands nothing. A connector reading a provider file passes the response's body on this way, with the length from the provider's own record of the file: Content-Length counts the bytes as sent, which for a compressed response is not the file.

Streaming bounds memory, and it bounds time by idleness rather than by the whole transfer. A connection's fetch runs under the connector's timeoutMs (30 seconds unless the registration says otherwise) until the response headers arrive, for any buffered read (text(), json(), arrayBuffer()), and for a body that is taken as a stream but not read: looking at ConnectorResponse.body releases nothing. From the first read of the stream, that deadline hands over to two limits:

  • Idle: the stream errors when the provider sends no byte for 30 seconds (STREAM_IDLE_TIMEOUT_MS). An empty chunk is not a byte, and a source that makes no progress (a thousand empty chunks in a row) errors the stream too. A transfer that keeps flowing can outlast timeoutMs, but only if it finishes within the absolute limit below. The window runs only while the stream waits on the provider, so a slow store does not spend it.
  • Absolute: the stream errors 10 minutes after its first read (STREAM_MAX_DURATION_MS), however steadily it flows, so a trickle that never stops does not hold a run for ever. A stream that is abandoned between reads ends at the same point and releases the connection.

Both fail with a TimeoutError, the same error timeoutMs ends in. The connection is released, and the upload lands no object and no row.

Reading a file as a stream ​

openStream(id) is open with the bytes as a sized stream, read from the blob store as you read it. A connector reads the same way through conn.openAttachmentStream(id). The permission check runs first, before the store is touched, and an id the scope does not know is null, as for open.

The integrity check moves to the stream. open holds the whole file and compares its sha256 before it answers. A stream cannot know its digest until the last byte, so it checks as the bytes pass:

  • The stream's length is the record's size. A stored object of any other size is refused before a byte is read.
  • The chunk that completes the file is held back until the store has ended and the digest matches. Bytes that do not match, or a store that ends short or carries more, error the stream instead, and that last chunk is never handed on. So if you have received all size bytes, they are the bytes the record names. If the stream errors, treat what you received as nothing: a prefix of a file that did not verify.
  • The held-back chunk is at most 1 MiB (VERIFIED_STREAM_CHUNK_MAX_BYTES): a larger chunk from the store is handed on in pieces of that size.

Every attachment row carries a sha256, because both spines declare it NOT NULL and the record requires it. A record without a valid one is refused before a byte is read, never handed on as verified.

On a hosted vertical, a connector the platform runs reads the file from your deployment over the platform's own link, and the stream is held to the same rules there. Each check runs again on the platform's side: the size, the digest, and the held-back last chunk. The link's time is bounded the way a connection's fetch is. Start reading within 30 seconds of opening the stream: the call's deadline runs until your first read. From then on, a deployment that sends no byte for 30 seconds (STREAM_IDLE_TIMEOUT_MS), or has not finished after 10 minutes (STREAM_MAX_DURATION_MS), errors the stream. When a stream errors, what you received before the error is a prefix of an unverified file. Discard it, and undo anything you wrote from it, such as a partial upload to the provider. Cancel a stream you will not read; that releases the stored object straight away.

Bytes that no row points at ​

The bytes go to the store before the row is written, so a few paths leave an object that no row names: a crash between the two, a call to the scope that fails in transport (the platform cannot tell whether the row committed, so it keeps the bytes rather than risk a row without its file), and a point-in-time rewind past a row. Nothing reads such an object, but it costs storage and the storage meter counts it. The platform's orphan sweep deletes it, under four guards. Each one alone stops a row that committed from losing its bytes:

  • A tombstone first. The scope never deletes. It records each candidate that no row names as condemned, in one transaction, and an attachment insert refuses a condemned id in its own transaction. The scope serializes the two, so either the row commits first and the sweep sees it, or the tombstone commits first and the upload fails with conflict (attachment_condemned). Only a condemned object is deleted. No clock is involved, so a slow upload, a retried call or a skewed clock cannot turn a committed row into a deleted object. A restore whose dump would bring back a row for a condemned id is refused the same way.

  • An age floor. Only an object whose id was minted more than seven days ago is judged. The id is a ULID minted just before the bytes are written, so an upload still in flight is never condemned in the first place. The age, and the fence below, are judged against the host's own clock. A pass takes no instant from its caller, so no caller can step past either one.

  • A restore fence. A Durable Object keeps 30 days of point-in-time history, so a row that a rewind or a restore took away can be brought back for that long. Every rewind and every restore of a scope first writes a fence object into the tenant's blob store, and the sweep deletes nothing of that scope until the fence is 35 days old. The fence lives in the blob store, not in the scope, because the rewind it records would erase it there. The sweep reads the fence before a pass and again after the condemnation, just before the first delete, so a rewind that lands mid-pass stops the deletes. A fence it cannot read counts as a fence.

  • The scope itself judges, and only while it is live. Only the copy that holds the scope's rows may say which objects are orphans. These all refuse, because any of them would read every object as an orphan:

    • a scope that is not active (archived, reaped, or under a suspended tenant);
    • a store that holds nothing, such as a scope whose data lives in another deployment;
    • a copy that a carry wiped or kept, a fork, or a snapshot;
    • a scope with no record that it was provisioned for the tenant.

    A host with a directory reads the scope's record before it addresses the scope's storage, so a reaped scope is never woken.

  • No unsettled copy elsewhere. After a carry, another version's script can keep a copy of the scope that took writes the serving copy lacks, uploads among them. Its bytes share the scope's prefix. The pass is refused while the copy ledger holds any entry for the scope that is not done, and done is the only state that lets it through, so a state added later holds the pass too. The states that hold it:

    • a move still pending;
    • a source still waiting for its wipe (eligible). That wipe is the step that finds a write landed after the export, and it may not have run;
    • a copy kept as divergent;
    • a copy retained unchecked.

    Settle the copy first. A deployment with no directory cannot read the ledger, so a pass there needs its caller to have checked it (copiesSettled).

On the hosted platform the control plane's scheduled pass runs the sweep. It is off until the platform turns it on, and it runs as a dry run before any delete. It visits a bounded window of scopes per pass. It checks the ledger itself and asks only the deployment that serves the scope. A scope held by an unsettled copy is counted as refused, never skipped silently. Every pass that finds or deletes an orphan leaves a sweepOrphanAttachments row in the admin log, with the keys. In delete mode, a scope is swept for real only after a dry run of it is in that log from the last seven days. Off the platform, a pass is run by calling sweepOrphanAttachments on a host.

A pass lists only the scope's own attachment keys (scope/<scopeId>/att/<ulid>). Other scopes' keys, other features' keys and anything malformed in the same bucket are never judged. A dry run condemns and deletes nothing and reports the keys a pass would delete.

A destructive pass needs a dry run first, and the scope holds that rule itself. A dry run records the ids it listed in the scope's own storage, at most 1,000, stamped with the host's clock. A destructive pass is refused with conflict (orphan_sweep_unlicensed) unless the scope holds such a record from the last seven days, and it deletes only ids that record lists. Each id it deletes leaves the record, so one dry run can license several passes that work through a backlog larger than one pass's limit. A licensed id whose object is gone some other way leaves it too, so a record with nothing left to delete sends the scope back to a dry run. The rule holds whoever asks for the pass, not only the platform. The record only narrows the pass: every guard above still applies to each id it lists. A dry run that finds the same orphans again writes nothing until the record is half the window old, when it refreshes the record's stamp; one that finds none clears the record. A dry run the restore fence holds lists nothing and leaves the record as it was. A dump never carries the record, and every restore, carry or fork drops it, so the next pass on a loaded scope is a dry run.

A restore refuses when its fence cannot be written. This is a deliberate trade of availability for safety: a rewind or a restore whose fence did not land could hand the sweep a state that lacks rows a later restore brings back. The refusal says so, and nothing has been replaced, so retry once the attachment store answers. A rewind also needs to know whose bucket to fence. The control plane names the tenant, and otherwise the scope's own provision receipt does. A scope that has neither and holds files is refused until it is reconciled. One that holds no file has nothing to lose and is not fenced.

What the sweep cannot protect. A restore from a dump older than 35 days can bring back rows whose bytes were swept. A removed attachment has the same exposure today, since removing it deletes its bytes. Restore from a dump younger than that, or expect some of its files to be missing.

An operation mints a single-use, short-lived URL that admits one file to one entity. The caller sends the bytes to that URL directly, with curl, and nothing else.

Declare it ​

The target says it takes links, and what a link may admit:

ts
attachmentTargets: [
  {
    entityType: 'contract',
    readPermission: 'contract:read',
    writePermission: 'contract:write',
    uploadLinks: { maxBytes: 15 * 1024 * 1024, contentTypes: ['application/pdf', 'image/*'] },
  },
],

Declaring uploadLinks is the opt-in. A target without it refuses a mint. maxBytes is required and held under 25 MiB. contentTypes is an allowlist of media types or families. A mint may only narrow the size, and the declaration appears in the vertical's PERMISSIONS.md under Upload links, so widening it is a reviewed diff.

A family never admits an active type. image/* admits PNG, JPEG and the rest, but not image/svg+xml. text/* admits plain text and CSV, but not text/html. Active means HTML, text/xsl (which Chrome parses as HTML even under nosniff), multipart/x-mixed-replace (whose parts WebKit renders as documents, also under nosniff), the types a browser sniffs for HTML (application/unknown, unknown/unknown), every XML type (text/xml, application/xml and any subtype ending in +xml, such as image/svg+xml, application/xhtml+xml or application/rss+xml), and every JavaScript MIME type the WHATWG MIME Sniffing standard lists (text/javascript, application/javascript, application/x-javascript, text/ecmascript and the rest). A browser runs these instead of showing them, and the person holding the link chooses the bytes. The type is judged as its essence, without parameters, spaces or capitals, so image/svg+xml; charset=utf-8 is still SVG, and image/jpg is judged and recorded as image/jpeg (so an allowlist entry spelled image/jpg never matches; write image/jpeg). A type that is not exactly one type/subtype (a list such as image/png,text/html, which a browser reads as its last type; text/html,x or text/html x, read as text/html; one with a control character; or a wildcard such as */* or image/*, which is an allowlist entry and never a file) is refused by every allowlist, including an absent one. To take an active type, name it exactly:

ts
uploadLinks: { maxBytes: 2 * 1024 * 1024, contentTypes: ['image/*', 'image/svg+xml'] },

Serve stored files as downloads, whatever the allowlist

Any route of yours that serves an attachment should answer with all three of X-Content-Type-Options: nosniff, Content-Disposition: attachment and a sandboxing Content-Security-Policy (default-src 'none'; sandbox), as the platform's file routes do (hardenFileResponse sets them), so a stored file is never run as your origin. The active-type rule is a second line, not the first: leaving contentTypes out admits every well-formed type, active ones included, and an exact entry admits the type it names. The rule was checked against Chrome and WebKit; Firefox was not covered.

Mint it, in an operation ​

ts
'contract/upload-link': async (ctx, input) => {
  assertAllowed(await ctx.check('contract:write', ref));      // your own guards first
  if (await isLocked(ctx, input.contractId)) throw substratError('conflict', 'the contract is locked');
  const link = await ctx.attachments.mintUploadUrl({
    entity: ref,                       // { entityType: 'contract', entityId }
    filename: 'signed-contract.pdf',   // optional: fixes the stored name
    maxBytes: 10 * 1024 * 1024,        // optional: narrows the target's
    ttlSeconds: 300,                   // optional: default 600, at most 3600
  });
  return { url: `${PUBLIC_ORIGIN}${link.path}`, expiresAt: link.expiresAt };
},

mintUploadUrl checks the target's writePermission on the entity, as the caller, so a caller without it is refused even if the operation forgot its own guard. Only a principal can mint or revoke. A schedule, a connector or a consumer holds no authorship to lend, and is refused with forbidden and reason upload_link_delegation. The result is { id, secret, path, expiresAt, maxBytes, filename }. path is /api/attachment-uploads/<entityType>/<entityId>/<secret>, and the origin is yours to put in front of it.

Upload with it ​

sh
curl --upload-file signed-contract.pdf \
  "https://crm.example/api/attachment-uploads/contract/01J…/sbup_…?filename=signed-contract.pdf"
json
{ "id": "01K…", "filename": "signed-contract.pdf", "contentType": "application/pdf",
  "size": 482113, "sha256": "…" }

Mount the route once, beside your others:

ts
import { mountUploadLinkRedeem } from '@substrat-run/vertical-host';

mountUploadLinkRedeem(app, { host: () => host, node: (c) => nodeOf(c) });

PUT and POST both work. The file name comes from the link if it fixed one, else ?filename=, else Content-Disposition, else upload, and is always a leaf name, never a path. The media type is the request's Content-Type unless that is absent or generic (curl --upload-file sends none), then the extension, then the bytes. For PDF, PNG, JPEG and GIF the bytes must agree with the claim, so a PNG called contract.pdf is refused.

AnswerWhenSpends the link?
201the file is storedyes
200a retry with the Idempotency-Key of the request that stored the file (below)n/a
404the secret names nothing or is not shaped like one, or the path names another entity or type than the link was minted for (whatever the link's state)no
410the link was used, has expired or was revoked, asked for at its own pathn/a
413the body is over the link's size, judged by Content-Length and again as bytes arriveno
415the type is not admitted, or the bytes contradict itno
403the minter no longer holds the write keyno
400an empty body, or a malformed Idempotency-Keyno
422a retry under the right Idempotency-Key whose bytes are not the stored filen/a

A refusal never spends the link: the caller can fix the file and send it again within the time box. A malformed secret is answered by the route without the scope being asked, with the same 404 an unknown one gets. The route listens at /api/attachment-uploads/… only, the path the mint returns.

A lost reply ​

A redemption can commit and still fail from the caller's side: the connection drops, or the scope restarts after the commit and before the answer. A plain retry of the same link then gets 410, though the file was stored. To make the retry safe, name the request with an Idempotency-Key header and send the same header with the retry:

sh
KEY=$(uuidgen)
curl --upload-file signed-contract.pdf -H "Idempotency-Key: $KEY" \
  "https://crm.example/api/attachment-uploads/contract/01J…/sbup_…?filename=signed-contract.pdf"
  • The key. 16 to 255 visible ASCII characters, with no space, " or \. A UUID or a ULID fits. The structured-field spelling Idempotency-Key: "…" is read without its quotes. Anything else is a 400, sent before the scope is asked, whatever the link's state.
  • What the spend records. The SHA-256 of the key, beside the link. The key itself is stored nowhere. A redemption without the header records nothing, and its link can never be replayed.
  • What a replay answers. The same link, with the same key and the same bytes (judged by size and SHA-256), within the link's lifetime plus 10 minutes, answers 200 with the body the stored 201 carried. A replay writes nothing: no bytes, no row, no event. The 200 tells "already stored" apart from "stored now". The same key with other bytes is 422 (upload_link_replay_mismatch), and nothing is stored.
  • A retry that races the first request. If the retry arrives while the first request is still writing, both send their bytes. The first commits, and the retry finds the link spent in its own transaction. Its own bytes, stored under an id of its own, are removed, and it is answered as the replay.
  • Everyone else still gets 410. A request for a spent link with no key, with another key, after the window, or after the stored file was removed or swept, gets the same 410 as before, down to its headers and body. Someone who holds the secret without the key cannot learn whether the file arrived. A key is no authority on its own: on another link, a pending one, it is an ordinary redemption, and a path naming another target is still a 404.

What it is, and is not ​

  • It is the platform's upload, not a second one. The route hands the bytes to ScopeHost.redeemUploadLink, which writes them through the same attachment write as any upload. The bytes go to the blob store, then the row and attachment.added land in one scope transaction. The author is the principal who minted the link, and the target's writePermission is checked as them again at redemption, so revoking their access ends what their links can do.
  • Single use is the transaction's. The link is marked used in the same transaction that inserts the attachment row. Two requests racing for one link are serialized by the scope and the second one gets 410, or the replay when it carries the first one's Idempotency-Key. A redemption that fails anywhere leaves the link unspent.
  • The secret is the authority. 256 random bits, sbup_-prefixed so a secret scanner can recognise one. Only its SHA-256 is stored. An operation that tries to persist the secret in an event, its own table or a platform intent is refused, the same tripwire ctx.capabilities has.
  • It is bound to one target and one scope. The target is in the path as well as in the link, so a URL pasted onto another entity is a 404 that spends nothing, and it is the same 404 whether the link is still pending or already spent. A link is not found in any other scope, of your tenant or another.
  • It never acts. A link is not a capability: it has no session, acts as nobody and can only ever produce the one attachment it was minted for.
  • Your own locks are checked at mint, not at redemption. An entity lock or state check in the operation runs before the mint. The platform does not know it and cannot run it again later, so keep ttlSeconds short, and revoke a link whose entity is locked after it was minted. It also does not check that the entity exists, which is true of an ordinary upload too.
  • The platform does not scan. The type check is the allowlist, the active-type rule for families, and the four sniffed formats. Anything stronger is the vertical's, in a consumer of attachment.added.

Find the file afterwards ​

Three ways, all carrying the attachment id so a follow-up operation can be called with it:

  • the upload's own answer, which the caller already has in hand;
  • the attachment.upload-link-redeemed event, written in the same transaction as attachment.added and carrying { linkId, attachmentId, entity, size, sha256, mintedBy }, which a consumer can use to run the follow-up itself;
  • ctx.attachments.uploadLinks({ entity }), whose records say pending, redeemed, revoked or expired and, once redeemed, the attachmentId.

ctx.attachments.revokeUploadLink(id) takes back a link that has not been used. The mint, the revoke and the redemption are each on the spine as attachment.upload-link-minted, attachment.upload-link-revoked and attachment.upload-link-redeemed. They are kernel-authored, so module code cannot forge or suppress them.

Things that will bite you ​

  • The secret is in the path. A header-only secret could not be used with curl --upload-file URL alone. What contains the cost: a link lives ten minutes by default and an hour at most, it is single-use, and invocationLog writes the secret segment, and any path segment that starts with sbup_, as [redacted]. A log the runtime keeps of full request URLs (Workers Logs, a proxy in front of the vertical) can still hold an unused link until it expires. Do not keep such a log for longer than the link lives.
  • CORS. The route sends no CORS headers and removes the ones an outer layer set. A blanket app.use('*', cors()) therefore cannot make the answer readable by a page that learned a link. A browser page that really must upload from another origin needs CORS added for this path, on purpose. A script, an MCP client's shell and curl need none.
  • Validators and echoes. The answer carries no ETag, Last-Modified or Location, never repeats the secret and is Cache-Control: no-store, so nothing in it is a handle on the bytes or the link. Do not forward the blob store's own ETag (for an object store, a hash of the content) in a wrapper of your own.
  • Version. ctx.attachments and the uploadLinks manifest key exist from the platform release that introduced upload links; a vertical that uses them needs that version or newer.

A download link is the read-side counterpart: a URL that lets whoever holds it read ONE file, with no session, until it expires. Use it where a cookie does not ride: an <audio> element on another origin, a file an MCP tool hands back, a link in a mail. On your own origin, with the person signed in, /api/attachments/:attachmentId (above) needs no link.

ts
// In an operation: the caller must hold the target's readPermission on the file's owner.
const link = await ctx.attachments.mintDownloadUrl({ attachmentId, ttlSeconds: 3600 });
return { url: `${origin}${link.path}`, expiresAt: link.expiresAt };

The path is /api/attachment-downloads/<attachmentId>/<secret>. workerDoor({ attachments: true }) mounts the route that reads it; a worker without the door mounts mountDownloadLinkRedeem from @substrat-run/vertical-host. The answer is the door's file route's: streamed, seekable, hardened and always a download.

  • It reads as the person who minted it, now. The file is opened through the ordinary read gate as the minter on every request, so taking their read key away ends every link they minted, and giving it back revives them. Only a principal mints; a consumer or a schedule cannot.
  • A read spends nothing. A media element reads a file in many ranged requests, so a link is good until it expires or is revoked: fifteen minutes by default, a day at most. Treat the URL as the file. ctx.attachments.revokeDownloadLink(id) takes it back sooner.
  • One file, one scope. The link named with another file's id, at another scope, or by a copy of the scope (a fork or a preview) is the 404 an unknown secret gets. An expired or revoked link is a 410, said only to someone holding the secret. A file removed since the mint is a 404.
  • On the spine. attachment.download-link-minted and attachment.download-link-revoked, as the minter. A read writes nothing. Only the secret's SHA-256 is stored, in _substrat_download_links, and invocationLog writes the secret segment, and any path segment that starts with sbdl_, as [redacted].