Skip to content

Documentation · IGNIS

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 ​

SurfaceDefaultClose it with
Every built-in routeopen to anyoneauth on the entry
listObjects under publicReadprivatenothing to do
A commit tokencommits only for its ownerresolvers.owner, required
Objects an upload leaves under the pending prefixstay until you remove thema lifecycle rule
A validated file on a bucket without versioningpinned 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.

ts
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.authenticate is { strategies, mode }; auth.authorize is one authorization spec or a list.
  • A route's own authenticate or authorize in routes.<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, and authorize: { skip: true } drops authorization only.
  • Without auth a 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.

RouteWith publicRead
getObjectByNameopen
downloadObjectByNameopen
listObjectsstill guarded: listing a bucket is not reading an object
every other routestill 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 provesThe token does not prove
A policy was issued for this key, to this ownerthat the holder may use direct upload
The grant has not expiredthat the content is safe, only that your check passed it
Nobody edited the key, bucket, owner, metadata or pinthat 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 copy commit makes are conditional on the pin. Other content, or no object, fails with 409 core.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.

  • keyPrefix is required with directUpload. Every route refuses a key outside it, so the entry serves only what lives inside it.
  • directUpload.pendingPrefix (default pending/) must be disjoint from keyPrefix: 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 pendingPrefixStart-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 itdirectUpload.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/plain and text/csv. Everything else is served as application/octet-stream with Content-Disposition: attachment.
  • image/svg+xml is 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: nosniff and Content-Security-Policy: sandbox.
  • Of the storage's own metadata nothing is copied onto the response. ETag and Last-Modified come from the stat, and If-None-Match or If-Modified-Since answers 304 without reading the object.
  • downloadObjectByName always 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.

ts
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.upload when that is unset), or an object can vanish under a token that is still good.
  • Keep expires.upload short. It is only the time to post in. Give users time to fix and confirm with expires.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 own keyPrefix inside 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: