@filelayer/core 0.3.0

package/dist/delivery.d.ts

@@ -0,0 +1,293 @@
+/**
+ * BYTE DELIVERY -- the library owns the response, not the developer.
+ *
+ * A security review found three live defects here and correctly identified their
+ * common root cause: `read()` and `redeem()` handed back a `Uint8Array` and
+ * left everything that happens to those bytes on the way to a browser as the
+ * application's problem. Three of the four security-sensitive decisions the
+ * library was still leaving to the developer lived in that gap:
+ *
+ *   - no `X-Content-Type-Options: nosniff` / `Content-Disposition` on the
+ *     authenticated read  -> a user-uploaded .html or .svg executes in OUR OWN
+ *     origin. Stored XSS with full session access, cross-tenant reach.
+ *   - no `Cache-Control: no-store` on the share download -> a revoked link is
+ *     replayable from disk cache or an intermediary. This one is worse than it
+ *     sounds: immediate revocation is the product's headline property, and a
+ *     cache replay partially defeats it.
+ *   - the share password in the query string -> the secret AND the password
+ *     land in access logs, proxy logs, browser history, and the `Referer`
+ *     header of any outbound link inside the delivered document.
+ *
+ * The fix is not "document the headers". A decision the developer can forget is
+ * a decision they will eventually forget, which is the entire premise of this
+ * design. So:
+ *
+ *   1. `read()` and `redeem()` now return a DELIVERY DESCRIPTOR -- bytes plus
+ *      the exact headers required to serve them safely. The headers are
+ *      computed by the library from the file record; there is no argument that
+ *      turns them off.
+ *   2. Framework-agnostic writers are provided (`toResponse` for anything with
+ *      a WHATWG `Response`, `sendNodeResponse` for `node:http`), so the
+ *      developer writes one line and cannot write the wrong headers.
+ *   3. For the share path the library owns the ROUTE, not just the response,
+ *      because the password-in-the-URL defect is a routing decision rather than
+ *      a response decision. `shareDownloadRoute()` reads the password from the
+ *      request body and REFUSES, loudly, with 400, if a credential appears in
+ *      the query string. A silent decision has been converted into a noisy one,
+ *      which by our own definition means it stops being a security-sensitive
+ *      decision at all.
+ *
+ * Residual, stated plainly: `delivery.body` is still a public field, so a
+ * developer who ignores the helpers and hand-writes `res.end(d.body)` gets the
+ * old behaviour. This is "hard to get wrong", not "impossible to get wrong".
+ * Making it impossible would mean never exposing the bytes, which would break
+ * every non-HTTP consumer (a queue worker, a virus scanner, a thumbnailer).
+ * We chose the weaker guarantee deliberately and state it rather than hide it.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Filelayer } from './filelayer.ts';
+import type { Principal } from './authz.ts';
+export type Disposition = 'attachment' | 'inline';
+export interface DeliverableFile {
+    name: string;
+    contentType: string;
+    sizeBytes?: number | null;
+}
+export interface FileDelivery {
+    file: DeliverableFile;
+    body: Uint8Array;
+    /**
+     * Everything that must be on the response. Lowercased, ready to spread into
+     * `res.writeHead()` or a `Headers` init.
+     */
+    headers: Record<string, string>;
+}
+export type DeliveryMode = 'proxy' | 'redirect';
+/**
+ * The literal a developer must type to enable redirect delivery.
+ *
+ * A boolean would be typed once and forgotten. A sentence has to be read to be
+ * copied, it appears verbatim in the diff, and it shows up in a grep of the
+ * codebase when someone asks "do we ever hand out URLs that outlive a
+ * revocation?" -- which is the question this whole mode exists to make
+ * answerable.
+ */
+export declare const REDIRECT_ACKNOWLEDGEMENT = "I accept a revocation window of up to ttlSeconds on redirected deliveries";
+/**
+ * Our ceiling, not the object store's. Five minutes is long enough for a client
+ * to follow a redirect on a bad mobile connection and short enough that the
+ * residual window is something you can put in a compliance document without
+ * flinching.
+ */
+export declare const MAX_REDIRECT_TTL_SECONDS = 300;
+export declare const DEFAULT_REDIRECT_TTL_SECONDS = 60;
+export interface RedirectDeliveryConfig {
+    /** Must be exactly `REDIRECT_ACKNOWLEDGEMENT`. Checked at runtime too. */
+    acknowledgeRevocationWindow: typeof REDIRECT_ACKNOWLEDGEMENT;
+    /** Clamped to [1, MAX_REDIRECT_TTL_SECONDS]. */
+    ttlSeconds?: number;
+    /**
+     * 'anonymous-grants-only' (DEFAULT) -- only a delivery authorized by an
+     * anonymous grant, i.e. something the customer has deliberately published,
+     * may be redirected. This is the setting where the residual window is a
+     * window onto an already-public object.
+     *
+     * 'all-grants' -- link and actor grants too. This is the setting that trades
+     * a real revocation window on genuinely private data for zero-proxy
+     * delivery. It is not the default and it never will be.
+     */
+    scope?: 'anonymous-grants-only' | 'all-grants';
+}
+export interface ResolvedRedirectConfig {
+    ttlSeconds: number;
+    scope: 'anonymous-grants-only' | 'all-grants';
+}
+export declare function resolveRedirectConfig(cfg: RedirectDeliveryConfig): ResolvedRedirectConfig;
+/** A delivery whose bytes flow through this process. */
+export interface ProxyDelivery {
+    mode: 'proxy';
+    file: DeliverableFile;
+    headers: Record<string, string>;
+    /** The bytes, as a stream. Nothing here is ever fully resident. */
+    body: ReadableStream<Uint8Array>;
+    /** Known length, when the store reported one. */
+    bytes: number | null;
+}
+/** A delivery answered with a 302 to a short-lived presigned URL. */
+export interface RedirectDelivery {
+    mode: 'redirect';
+    file: DeliverableFile;
+    headers: Record<string, string>;
+    status: 302;
+    url: string;
+    /** When the presigned URL stops working. */
+    expiresAt: Date;
+    /**
+     * The number the compliance document needs: revocation is immediate at
+     * decision time, PLUS up to this many seconds of in-flight window.
+     */
+    revocationWindowSeconds: number;
+}
+export type StreamedDelivery = ProxyDelivery | RedirectDelivery;
+export declare function isActiveContentType(contentType: string): boolean;
+/**
+ * A content type we are willing to put on a response.
+ *
+ * A `content-type` is attacker-controlled: it is whatever the uploader sent.
+ * Anything with a CR, an LF or a NUL is a header-injection attempt and is not
+ * negotiable; anything that is not a plausible media type is served as bytes.
+ */
+export declare function safeContentType(contentType: string, disposition: Disposition): string;
+/**
+ * RFC 6266 `Content-Disposition`, with the filename encoded rather than
+ * interpolated.
+ *
+ * NEW FINDING, found while doing this work: the example app wrote
+ * `filename="${file.name}"` directly. `file.name` is whatever the uploader
+ * sent. A name containing a double quote truncates the header; a name
+ * containing CR/LF injects an arbitrary header, including a second
+ * `Content-Type` or a `Set-Cookie`. That is a response-splitting bug in the
+ * shipped example, and it is not one the comparable integrations have, because
+ * none of them interpolate the name unescaped. It is fixed here, once, for
+ * every caller.
+ */
+export declare function contentDisposition(name: string, disposition: Disposition): string;
+/**
+ * The headers every Filelayer byte response carries. There is no option to
+ * omit any of them.
+ *
+ *  nosniff            - stops content-type sniffing turning a .txt into HTML.
+ *  Content-Disposition- attachment by default; the browser never renders it.
+ *  Cache-Control      - `private, no-store` + `no-cache` + `must-revalidate`.
+ *                       This is the one that matters most: it is what makes
+ *                       "revocation is immediate" true at the browser and at
+ *                       every intermediary, not just at our origin.
+ *  Pragma / Expires   - the HTTP/1.0 spelling of the same thing, because
+ *                       corporate proxies are real.
+ *  Referrer-Policy    - `no-referrer`. A share link's secret is in the URL. Any
+ *                       outbound link inside a delivered document would leak it
+ *                       in the Referer header. This closes the third vector of
+ *                       the credential-in-the-URL defect, the one that survives
+ *                       moving the password out of the query string.
+ *  CSP sandbox        - defence in depth for the inline case and for any future
+ *                       caller that overrides disposition.
+ *  X-Frame-Options    - the delivered bytes cannot be framed by a third party.
+ */
+export declare function deliveryHeaders(file: DeliverableFile, opts?: {
+    disposition?: Disposition;
+}): Record<string, string>;
+/** The same headers, minus the body ones, for a JSON error on a delivery path. */
+export declare function errorHeaders(): Record<string, string>;
+/**
+ * The headers on a 302 to a presigned URL.
+ *
+ * `cacheable` is true for an ANONYMOUS grant and only for an anonymous grant.
+ * That is the "public/anonymous grants should be able to use a cacheable path"
+ * requirement, and the negative half of it is the important half: nothing that
+ * was not already public becomes cacheable by a shared cache, ever.
+ *
+ * The cache lifetime is HALF the presigned URL's TTL. A cached 302 hands a
+ * client a URL that is already partly used up, so caching for the full TTL
+ * would let a client receive a redirect with milliseconds of life left and see
+ * a spurious 403. Half guarantees at least half the TTL remains.
+ *
+ * The 302 itself carries no bytes, so it carries no content-type protections;
+ * those are pinned INTO the presigned URL by the caller (see
+ * `Filelayer.readStream`), which is what stops a redirect from being a way to
+ * lose them.
+ */
+export declare function redirectHeaders(url: string, opts: {
+    ttlSeconds: number;
+    cacheable: boolean;
+}): Record<string, string>;
+/** WHATWG `Response` -- Workers, Deno, Bun, Next.js route handlers, Hono. */
+export declare function toResponse(delivery: FileDelivery, status?: number): Response;
+/**
+ * The streaming/redirect equivalent. One function for both modes, because the
+ * developer must not have to branch on the mode -- branching is where the
+ * `Cache-Control` gets copied from the wrong arm.
+ */
+export declare function toStreamResponse(delivery: StreamedDelivery): Response;
+/** `node:http` / Express. */
+export declare function sendNodeResponse(res: ServerResponse, delivery: FileDelivery, status?: number): void;
+/**
+ * `node:http`, streaming. Nothing is buffered: the object's bytes go from the
+ * store's socket to the client's socket a chunk at a time.
+ *
+ * The `content-length` from the record is dropped unless the STORE reported one
+ * for this response, for the same reason `sendNodeResponse` recomputes it: a
+ * `size_bytes` that disagrees with the object truncates or hangs the response,
+ * and on a streamed response the hang is the one you notice in production
+ * rather than in a test.
+ */
+export declare function sendNodeStream(res: ServerResponse, delivery: StreamedDelivery): Promise<void>;
+export interface ShareRouteOptions {
+    /** Path prefix the share links are served under. Must match `baseUrl`. */
+    prefix?: string;
+    disposition?: Disposition;
+    /**
+     * 'auto' (default) applies the INSTANCE's redirect policy -- which is "never"
+     * unless `redirectDelivery` was configured and acknowledged, so the default
+     * is proxying for everybody who has not opted in. 'proxy' forces proxying for
+     * this route even on an instance that has opted in.
+     *
+     * There is no 'redirect' value. A route cannot demand a mode the instance was
+     * not configured (and acknowledged) for; the opt-in lives in exactly one
+     * place and it is the place with the acknowledgement string next to it.
+     */
+    mode?: 'proxy' | 'auto';
+}
+/**
+ * `GET|POST <prefix>/:secret` -- the entire public share-link download path.
+ *
+ * The application supplies nothing. Identity is the secret itself, the password
+ * is read from the body, the counter is consumed by `redeem()`, and the
+ * response headers come from `deliveryHeaders()`. There is no parameter here
+ * whose wrong value leaks data.
+ *
+ * Returns true if it handled the request, so it can be dropped into any router.
+ */
+export declare function shareDownloadRoute(fl: Filelayer, opts?: ShareRouteOptions): (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
+export interface FileRouteOptions {
+    prefix?: string;
+    disposition?: Disposition;
+    /** See `ShareRouteOptions.mode`. */
+    mode?: 'proxy' | 'auto';
+    /** The application's own authentication. Filelayer never guesses identity. */
+    principal: (req: IncomingMessage) => Principal | Promise<Principal>;
+}
+/**
+ * `GET <prefix>/:fileId` -- the authenticated read path, headers included.
+ *
+ * The one thing the application must supply is who the caller is, because that
+ * is the one thing Filelayer cannot know. Everything downstream of that -- the
+ * decision, the audit event, the status code, and every response header -- is
+ * the library's.
+ */
+export declare function fileDownloadRoute(fl: Filelayer, opts: FileRouteOptions): (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
+export interface DeliveryHandlerOptions {
+    /** Where authorized file reads are served. Must match `publicUrl()`. */
+    filePrefix?: string;
+    /** Where share links are served. Must match `baseUrl` + `/d`. */
+    sharePrefix?: string;
+    disposition?: Disposition;
+    /** See `ShareRouteOptions.mode`. Applies to both routes. */
+    mode?: 'proxy' | 'auto';
+    /**
+     * The application's authentication. Omitted means every request to the file
+     * path is ANONYMOUS -- which is safe, because an anonymous principal can only
+     * reach a file carrying an explicit `anonymous` grant (P1). It is not a
+     * "public mode"; there is no public mode.
+     */
+    principal?: (req: IncomingMessage) => Principal | Promise<Principal>;
+}
+/**
+ * The whole byte-delivery surface as one `node:http` request listener.
+ *
+ * `createServer(deliveryHandler(fl))` is a complete, correct file server: both
+ * delivery paths, every security header, the query-string credential refusal,
+ * and a 404 for everything else. The developer writes no header and no status
+ * code, which means there is no header or status code for them to get wrong.
+ */
+export declare function deliveryHandler(fl: Filelayer, opts?: DeliveryHandlerOptions): (req: IncomingMessage, res: ServerResponse) => Promise<void>;
+//# sourceMappingURL=delivery.d.ts.map

package/dist/delivery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery.d.ts","sourceRoot":"","sources":["../src/delivery.ts"],"names":[],"mappings":"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"}