Security
A file route that anyone can call is a public file server. This page lists what is open when you declare nothing, then each control that closes it.
What is open by default
| Surface | Default | Close it with |
|---|---|---|
| Every built-in route | open to anyone | auth on the entry |
listObjects under publicRead | private | nothing to do |
| A commit token | commits only for its owner | resolvers.owner, required |
| Objects an upload leaves under the pending prefix | stay until you remove them | a lifecycle rule |
| A validated file on a bucket without versioning | pinned by ETag (an MD5 for a plain upload) | bucket versioning |
The entry serves one bucket and no route lists, creates or deletes buckets, so nothing about bucket management is exposed.
Authentication and authorization
Put auth on the entry and it applies to every built-in route, direct upload and validate included.
import { Authentication } from '@venizia/ignis';
import { DiskHelper } from '@venizia/ignis-helpers';
import type { TStaticAssetComponentOptions } from '@venizia/ignis/static-asset';
export const options: TStaticAssetComponentOptions = {
documents: {
basePath: '/documents',
bucket: 'documents',
helper: new DiskHelper({ basePath: './app_data' }),
auth: {
authenticate: { strategies: [Authentication.STRATEGY_JWT] },
authorize: { action: 'read', resource: 'document' },
},
serverUpload: { use: true },
directUpload: { use: false },
metaLink: { use: false },
routes: {
deleteObject: { use: true, authorize: { action: 'delete', resource: 'document' } },
downloadObjectByName: { use: true, authenticate: { skip: true } },
},
},
};auth.authenticateis{ strategies, mode };auth.authorizeis one authorization spec or a list.- A route's own
authenticateorauthorizeinroutes.<key>replaces the entry's for that route, field by field. { skip: true }opens the route:authenticate: { skip: true }drops authentication and authorization for it, andauthorize: { skip: true }drops authorization only.- Without
autha route has no authentication. The component never guesses a strategy.
The resolution is the one the CRUD controller factory uses (RouteConfigResolver.resolveAuthenticate and resolveAuthorize), so a static-asset route and a CRUD route answer the same way. Register an authorization enforcer before you use a spec: a route that declares one with no enforcer registered is refused, unless the authorization option defaultDecision is allow.
publicRead
auth.publicRead: { use: true } leaves reading one object unauthenticated, so a browser can show an image without a token.
| Route | With publicRead |
|---|---|
getObjectByName | open |
downloadObjectByName | open |
listObjects | still guarded: listing a bucket is not reading an object |
| every other route | still guarded |
publicRead is a default. A route that sets its own authenticate or authorize keeps it.
Direct upload
One key per policy
A POST policy signs the exact pending key (pending/<keyPrefix><generated>/<name>) and its form carries it. A browser cannot spend one policy on a second object, however long the policy lives. The final key appears in no policy, so content cannot be replaced after the commit - the property a presigned PUT cannot give you.
The commit token
The token is an HMAC over { bucket, object, expiresAt, owner, metadata, stage, pin? }, verified before any storage call. It is signed, not encrypted: the client can read it, so metadata holds no secrets. It has exactly two .-separated parts, and its key must sit under this entry's pending prefix and keyPrefix, in this entry's bucket. A caller cannot name an object it was never granted, and the route is not a name prober: a forged token fails without a round trip, so timing says nothing about what exists.
| The token proves | The token does not prove |
|---|---|
| A policy was issued for this key, to this owner | that the holder may use direct upload |
| The grant has not expired | that the content is safe, only that your check passed it |
| Nobody edited the key, bucket, owner, metadata or pin | that the file is valid, unless it is a validated token |
| A validated token: the content that was read is the content it commits |
The owner in the token
directUpload.resolvers.owner is required. The policy route signs the caller into the token, and the commit and validate routes refuse any other caller as an invalid token - the same answer a forged token gets, so it reveals nothing. See Who owns an upload.
A token commits once
A POST policy stays valid until it expires, so a client can post to the pending key again after a commit. Commit refuses a destination that already holds an object with 409 core.static_asset.upload_already_committed, so the second post never overwrites the first commit. See A commit is single-use.
authorize guards every direct-upload route
upload-policy, upload-validate and upload-commit all call directUpload.authorize first, and answer 403 core.static_asset.upload_not_authorized on false. The option may be left out only when auth authenticates or authorizes; with neither, the entry refuses to start.
The route's JSON validator runs before authorize, so a malformed body answers 422 before an unauthorized caller gets 403.
An unvalidated file never commits
With a validation on, commit takes only the token upload-validate returned. The token the policy issued is refused with 422 core.static_asset.upload_not_validated, so skipping the validate route does not skip the check. commit never runs your handler: validate does, once.
The pin binds the token to the content
A check that passes and then a copy of whatever is there later leaves a gap: the uploader can overwrite the pending object in between. The validated token closes it. validate stats the object, pins what it finds, parses the file once through that pin, and signs the pin into the token it returns.
- What the pin is. The exact version id when the bucket has real versions, else the ETag. It is chosen per object, from the stat: a version id of
null, an empty one or none means no version, so the ETag pins. - Where it is checked. Every read through
file.stream()and the copycommitmakes are conditional on the pin. Other content, or no object, fails with409core.static_asset.upload_changed, and nothing is copied or removed. - What it costs. No extra object is created, and no second parse.
- Re-validating. A token of either stage can be validated again. It pins whatever is there at that moment, then validates that.
WARNING
On a bucket without versioning the pin is the ETag, and for a plain upload the ETag is an MD5. A deliberately crafted collision, two different files with one MD5, is a theoretical bypass. If you use validation as a malware gate, enable bucket versioning: the pin is then an exact version, with no collision to craft.
With versioning on, overwritten and deleted pending objects stay as noncurrent versions. The bucket needs a lifecycle rule that expires noncurrent versions and delete markers under the pending prefix, beside the expiry rule for the pending objects.
The pending prefix
A direct upload lands in the pending prefix first, and moves to its final key at commit. The routes must never serve a pending object: it is unchecked, and the user may not have confirmed it. Two settings keep it out of reach, and the component checks both at start-up.
keyPrefixis required withdirectUpload. Every route refuses a key outside it, so the entry serves only what lives inside it.directUpload.pendingPrefix(defaultpending/) must be disjoint fromkeyPrefix: neither starts with the other.
With keyPrefix: 'products/' and pendingPrefix: 'products/pending/', a pending object would sit inside the scope, and getObjectByName, downloadObjectByName and listObjects would serve it. The component refuses that entry. A keyPrefix such as pending/imports/ collides with the default pending/ the same way.
The check holds within one entry. A second entry on the same bucket whose keyPrefix covers another entry's pendingPrefix would serve that entry's pending objects, and the component cannot see across entries. Keep the keyPrefix and pendingPrefix of every entry on one bucket disjoint from each other.
Rule for pendingPrefix | Start-up error when broken |
|---|---|
Not empty and ends with / | directUpload.pendingPrefix must be one or more valid key segments, each followed by a slash |
Every part is a valid key segment (no .., no leading ., no shell characters) | the same error |
Does not start with keyPrefix, and keyPrefix does not start with it | directUpload.pendingPrefix and keyPrefix must not contain one another |
Each error is prefixed with the entry's name, and it lists the offending values.
The pending key is pendingPrefix + keyPrefix + a generated folder + the file name, so the committed key lands inside the scope. A commit token that another entry signed with the same secretKey is refused: the commit checks its bucket and that its key starts with this entry's pending prefix and keyPrefix.
Served content
The component decides the served type from the object name, never from the uploader or the storage:
- A type is rendered inline only when it is in the allow list: common images, video, audio,
application/pdf,text/plainandtext/csv. Everything else is served asapplication/octet-streamwithContent-Disposition: attachment. image/svg+xmlis not in the list: SVG carries script, and a renderable upload on the API origin is stored XSS.- Every object response carries
X-Content-Type-Options: nosniffandContent-Security-Policy: sandbox. - Of the storage's own metadata nothing is copied onto the response.
ETagandLast-Modifiedcome from the stat, andIf-None-MatchorIf-Modified-Sinceanswers304without reading the object. downloadObjectByNamealways attaches.
Switch getObjectByName off (routes.getObjectByName: { use: false }) to make every read an attachment.
Rate-limit upload-policy
A policy is a write credential, so cap how often one caller can ask for it. A route override takes middleware, and it runs before the handler - before authorize too.
import type { MiddlewareHandler } from 'hono';
import type { TStaticAssetRoutes } from '@venizia/ignis/static-asset';
export const buildRoutes = (opts: { rateLimit: MiddlewareHandler }): TStaticAssetRoutes => ({
uploadPolicy: { use: true, middleware: [opts.rateLimit] },
});Use your own rate-limit middleware, shared across instances if you run more than one.
Clean up the pending prefix
Abandoned uploads, files a user replaced and objects whose commit never came all stay under the pending prefix. Put a lifecycle rule on that prefix in the bucket - for example, expire after one day. The rule must target the pendingPrefix you configured, which is pending/ unless you changed it.
- Make the rule longer than
expires.commit(expires.uploadwhen that is unset), or an object can vanish under a token that is still good. - Keep
expires.uploadshort. It is only the time to post in. Give users time to fix and confirm withexpires.commit. - The rule never touches a final key: a committed object lives inside
keyPrefix, which is disjoint from the pending prefix. That is also why the rule is safe to set on the whole prefix. - Entries that share a bucket can share
pendingPrefix: each entry's pending files sit under its ownkeyPrefixinside it, and one rule collects them all. - A commit whose follow-up fails leaves an object at its final key. The service example removes it.
A storage the browser cannot reach directly
host is inside every SigV4 signature, so the policy URL cannot be rewritten after it is signed. When your app talks to storage on an internal name, give the helper a public one too: endpoint: { default: 'http://minio:9000', public: 'https://cdn.example.com' }. See Behind a private endpoint.
Scope a shared bucket
keyPrefix confines an entry to one folder of a shared bucket. Every route refuses a key outside it as 404, before any storage call, so a caller learns nothing about keys it does not own; listObjects lists only inside it; and a commit token another entry signed with the same secretKey cannot land outside it.
Files:
packages/core-server/src/components/static-asset/utilities/route-options.utility.ts- the auth resolutionpackages/core-server/src/components/static-asset/utilities/key-scope.utility.ts-keyPrefixandpendingPrefixrulespackages/kernel/src/base/controllers/factory/definition.ts-RouteConfigResolverpackages/core-server/src/components/static-asset/utilities/commit-token.utility.ts- the tokenpackages/core-server/src/components/static-asset/utilities/pinned-file.utility.ts- the pin and the pinned read