Reorganize repo structure and standards references

This commit is contained in:
david committed 2026-06-29 05:03:42 +02:00
1 parent 3cb93a81be
commit be2054274d
5885 files changed
+2588 -195

No files matched your search

@@ -0,0 +1,179 @@
import { describe, expect, it } from "vitest";
import { authorizeStorageObjectAccess, authorizeStorageUploadConstraints } from "./index.js";
describe("authorizeStorageObjectAccess", () => {
it("allows clean tenant-scoped object access with normalized identity", () => {
expect(
authorizeStorageObjectAccess({
tenantId: " acme ",
key: " tenants/acme/uploads/avatar.png ",
operation: "download",
status: "clean",
}),
).toEqual({
allowed: true,
tenantId: "acme",
key: "tenants/acme/uploads/avatar.png",
operation: "download",
status: "clean",
});
});
it("allows available upload access when the key belongs to the tenant", () => {
expect(
authorizeStorageObjectAccess({
tenantId: "acme",
key: "tenants/acme/uploads/new-file.txt",
operation: "upload",
status: "available",
}),
).toMatchObject({ allowed: true, status: "available" });
});
it.each([
["empty tenant", { tenantId: "", key: "tenants/acme/file.txt" }, "invalid_tenant"],
["empty key", { tenantId: "acme", key: "" }, "invalid_key"],
["absolute key", { tenantId: "acme", key: "/tenants/acme/file.txt" }, "invalid_key"],
["traversal key", { tenantId: "acme", key: "tenants/acme/../secret.txt" }, "invalid_key"],
["unscoped key", { tenantId: "acme", key: "uploads/file.txt" }, "invalid_key"],
])("denies %s", (_label, input, reason) => {
expect(
authorizeStorageObjectAccess({
...input,
operation: "download",
status: "clean",
}),
).toEqual({ allowed: false, operation: "download", reason });
});
it("denies keys scoped to another tenant without echoing the foreign tenant", () => {
const decision = authorizeStorageObjectAccess({
tenantId: "acme",
key: "tenants/other/uploads/file.txt",
operation: "download",
status: "clean",
});
expect(decision).toEqual({
allowed: false,
operation: "download",
reason: "tenant_mismatch",
});
expect(JSON.stringify(decision)).not.toContain("other");
});
it("denies explicit tenant mismatch without echoing the foreign tenant", () => {
const decision = authorizeStorageObjectAccess({
tenantId: "acme",
objectTenantId: "other",
key: "tenants/acme/uploads/file.txt",
operation: "download",
status: "clean",
});
expect(decision).toEqual({
allowed: false,
operation: "download",
reason: "tenant_mismatch",
});
expect(JSON.stringify(decision)).not.toContain("other");
});
it("denies blocked objects with a stable redacted reason code", () => {
expect(
authorizeStorageObjectAccess({
tenantId: "acme",
key: "tenants/acme/uploads/file.txt",
operation: "download",
status: "blocked",
}),
).toEqual({
allowed: false,
operation: "download",
reason: "blocked_object",
});
});
it("denies quarantined objects with a stable redacted reason code", () => {
expect(
authorizeStorageObjectAccess({
tenantId: "acme",
key: "tenants/acme/uploads/file.txt",
operation: "download",
status: "quarantined",
}),
).toEqual({
allowed: false,
operation: "download",
reason: "quarantined_object",
});
});
it("does not copy secret-like metadata into denied decisions", () => {
const decision = authorizeStorageObjectAccess({
tenantId: "acme",
objectTenantId: "other",
key: "tenants/other/uploads/file.txt",
operation: "download",
status: "quarantined",
metadata: {
token: "BearerSecret",
body: "request-body-secret",
signature: "Eicar-Test-Signature",
},
});
const serialized = JSON.stringify(decision);
expect(decision).toEqual({
allowed: false,
operation: "download",
reason: "tenant_mismatch",
});
expect(serialized).not.toContain("BearerSecret");
expect(serialized).not.toContain("request-body-secret");
expect(serialized).not.toContain("Eicar-Test-Signature");
expect(serialized).not.toContain("other");
});
});
describe("authorizeStorageUploadConstraints", () => {
it("allows configured content type and byte size", () => {
expect(
authorizeStorageUploadConstraints({
operation: "upload",
contentType: "Image/PNG; charset=utf-8",
byteSize: 1024,
allowedContentTypes: ["image/png"],
maxBytes: 2048,
}),
).toBeNull();
});
it("denies unsupported content types without echoing request metadata", () => {
const decision = authorizeStorageUploadConstraints({
operation: "upload",
contentType: "application/x-msdownload",
byteSize: 1024,
allowedContentTypes: ["image/png"],
metadata: { token: "BearerSecret", filename: "malware.exe" },
});
expect(decision).toEqual({ allowed: false, operation: "upload", reason: "unsupported_content_type" });
expect(JSON.stringify(decision)).not.toContain("BearerSecret");
expect(JSON.stringify(decision)).not.toContain("malware.exe");
});
it("denies oversized objects without echoing body metadata", () => {
const decision = authorizeStorageUploadConstraints({
operation: "upload",
contentType: "image/png",
byteSize: 2049,
maxBytes: 2048,
metadata: { body: "raw-body-secret" },
});
expect(decision).toEqual({ allowed: false, operation: "upload", reason: "object_too_large" });
expect(JSON.stringify(decision)).not.toContain("raw-body-secret");
});
});
@@ -0,0 +1,169 @@
export type StorageObjectStatus = "clean" | "available" | "blocked" | "quarantined";
export type StorageAccessOperation = "upload" | "download";
export type StorageAccessDenyReason =
| "invalid_tenant"
| "invalid_key"
| "tenant_mismatch"
| "blocked_object"
| "quarantined_object"
| "unsupported_content_type"
| "object_too_large";
export interface StorageAccessRequest {
tenantId: string;
key: string;
operation: StorageAccessOperation;
status?: StorageObjectStatus;
objectTenantId?: string;
metadata?: Record<string, unknown>;
}
export type StorageAccessDecision =
| {
allowed: true;
tenantId: string;
key: string;
operation: StorageAccessOperation;
status: StorageObjectStatus;
}
| {
allowed: false;
reason: StorageAccessDenyReason;
operation: StorageAccessOperation;
};
export type StorageAccessDeniedDecision = Extract<StorageAccessDecision, { allowed: false }>;
export interface StorageUploadConstraintRequest {
operation: Extract<StorageAccessOperation, "upload">;
contentType?: string | null;
byteSize?: number | null;
allowedContentTypes?: readonly string[];
maxBytes?: number | null;
metadata?: Record<string, unknown>;
}
const TENANT_KEY_PREFIX = "tenants/";
const DEFAULT_ALLOWED_STATUS: StorageObjectStatus = "available";
export function authorizeStorageObjectAccess(
request: StorageAccessRequest,
): StorageAccessDecision {
const operation = request.operation;
const tenantId = normalizeTenantId(request.tenantId);
if (tenantId === null) {
return deny(operation, "invalid_tenant");
}
const key = normalizeObjectKey(request.key);
if (key === null) {
return deny(operation, "invalid_key");
}
if (request.objectTenantId !== undefined) {
const objectTenantId = normalizeTenantId(request.objectTenantId);
if (objectTenantId === null || objectTenantId !== tenantId) {
return deny(operation, "tenant_mismatch");
}
}
const tenantPrefix = `${TENANT_KEY_PREFIX}${tenantId}/`;
if (!key.startsWith(tenantPrefix)) {
return deny(operation, "tenant_mismatch");
}
const status = request.status ?? DEFAULT_ALLOWED_STATUS;
if (status === "blocked") {
return deny(operation, "blocked_object");
}
if (status === "quarantined") {
return deny(operation, "quarantined_object");
}
return {
allowed: true,
tenantId,
key,
operation,
status,
};
}
export function authorizeStorageUploadConstraints(
request: StorageUploadConstraintRequest,
): StorageAccessDeniedDecision | null {
const operation = request.operation;
const allowedContentTypes = new Set((request.allowedContentTypes ?? []).map(normalizeContentType).filter((contentType): contentType is string => contentType !== null));
const contentType = normalizeContentType(request.contentType);
if (allowedContentTypes.size > 0 && (contentType === null || !allowedContentTypes.has(contentType))) {
return deny(operation, "unsupported_content_type");
}
if (typeof request.maxBytes === "number" && Number.isFinite(request.maxBytes) && request.maxBytes >= 0) {
const byteSize = normalizeByteSize(request.byteSize);
if (byteSize !== null && byteSize > request.maxBytes) {
return deny(operation, "object_too_large");
}
}
return null;
}
function deny(
operation: StorageAccessOperation,
reason: StorageAccessDenyReason,
): StorageAccessDeniedDecision {
return { allowed: false, operation, reason };
}
function normalizeTenantId(tenantId: string): string | null {
const normalized = tenantId.trim();
if (normalized.length === 0 || normalized.includes("/")) {
return null;
}
return normalized;
}
function normalizeObjectKey(key: string): string | null {
const normalized = key.trim().replace(/\\+/g, "/").replace(/\/+/g, "/");
if (normalized.length === 0 || normalized.startsWith("/")) {
return null;
}
const segments = normalized.split("/");
if (segments.some((segment) => segment.length === 0 || segment === "." || segment === "..")) {
return null;
}
if (!normalized.startsWith(TENANT_KEY_PREFIX)) {
return null;
}
return normalized;
}
function normalizeContentType(contentType: string | null | undefined): string | null {
const normalized = contentType?.split(";")[0]?.trim().toLowerCase();
return normalized ? normalized : null;
}
function normalizeByteSize(byteSize: number | null | undefined): number | null {
if (typeof byteSize !== "number" || !Number.isFinite(byteSize) || byteSize < 0) {
return null;
}
return Math.floor(byteSize);
}
@@ -0,0 +1,290 @@
import { describe, expect, it, vi } from "vitest";
import { mkdtemp, readFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import {
DeleteObjectCommand,
PutObjectCommand,
StorageAdapterError,
createLocalStorageAdapter,
createS3StorageAdapter,
type S3StorageAdapterConfig,
} from "./index.js";
const baseConfig: S3StorageAdapterConfig = {
endpoint: "https://s3.example.test",
region: "us-east-1",
bucket: "uploads",
accessKeyId: "access-key",
secretAccessKey: "secret-key",
};
describe("createS3StorageAdapter", () => {
it("sends PutObjectCommand input and returns object identity", async () => {
const send = vi.fn().mockResolvedValue({});
const adapter = createS3StorageAdapter({ ...baseConfig, client: { send } });
await expect(
adapter.putObject({
key: "avatars/user.png",
body: "file contents",
contentType: "image/png",
cacheControl: "public, max-age=3600",
metadata: { tenant: "acme" },
}),
).resolves.toEqual({
bucket: "uploads",
key: "avatars/user.png",
publicUrl: null,
});
expect(send).toHaveBeenCalledOnce();
const command = send.mock.calls[0]?.[0];
expect(command).toBeInstanceOf(PutObjectCommand);
expect(command.input).toEqual({
Bucket: "uploads",
Key: "avatars/user.png",
Body: "file contents",
ContentType: "image/png",
CacheControl: "public, max-age=3600",
Metadata: { tenant: "acme" },
});
});
it("constructs public URLs by encoding key segments", async () => {
const adapter = createS3StorageAdapter({
...baseConfig,
publicBaseUrl: "https://cdn.example.test/assets/",
client: { send: vi.fn().mockResolvedValue({}) },
});
await expect(
adapter.putObject({
key: "tenant one/folder/avatar #1.png",
body: new Uint8Array([1, 2, 3]),
}),
).resolves.toMatchObject({
publicUrl:
"https://cdn.example.test/assets/tenant%20one/folder/avatar%20%231.png",
});
});
it("throws redacted diagnostics for missing required config", () => {
const config = {
endpoint: "",
region: "us-east-1",
bucket: "",
accessKeyId: "provided-access-key",
secretAccessKey: "provided-secret-key",
} satisfies S3StorageAdapterConfig;
expect(() => createS3StorageAdapter(config)).toThrow(StorageAdapterError);
try {
createS3StorageAdapter(config);
} catch (error) {
expect(error).toBeInstanceOf(StorageAdapterError);
const adapterError = error as StorageAdapterError;
expect(adapterError.code).toBe("config_missing");
expect(adapterError.details).toEqual({
operation: "createS3StorageAdapter",
missingFields: ["endpoint", "bucket"],
});
expect(JSON.stringify(adapterError)).not.toContain("provided-access-key");
expect(JSON.stringify(adapterError)).not.toContain("provided-secret-key");
}
});
it("wraps upstream send failures with redacted request metadata", async () => {
const upstreamError = Object.assign(
new Error("signature mismatch for credential secret-key"),
{
name: "SignatureDoesNotMatch",
$metadata: { httpStatusCode: 403, requestId: "req-123" },
responseBody: "full upstream response should not be copied",
},
);
const adapter = createS3StorageAdapter({
...baseConfig,
client: { send: vi.fn().mockRejectedValue(upstreamError) },
});
await expect(
adapter.putObject({ key: "private/report.pdf", body: "body-secret" }),
).rejects.toMatchObject({
name: "StorageAdapterError",
code: "put_failed",
details: {
operation: "putObject",
bucket: "uploads",
key: "private/report.pdf",
upstream: {
name: "SignatureDoesNotMatch",
message: "signature mismatch for credential [redacted]",
status: 403,
requestId: "req-123",
},
},
});
});
it("does not copy credentials, session tokens, or request bodies into structured diagnostics", async () => {
const upstreamError = Object.assign(new Error("upstream failed"), {
accessKeyId: "access-key",
secretAccessKey: "secret-key",
sessionToken: "session-token",
body: "request-body",
$metadata: { httpStatusCode: 500, requestId: "req-500" },
});
const adapter = createS3StorageAdapter({
...baseConfig,
sessionToken: "session-token",
client: { send: vi.fn().mockRejectedValue(upstreamError) },
});
try {
await adapter.putObject({ key: "upload.txt", body: "request-body" });
throw new Error("expected putObject to fail");
} catch (error) {
expect(error).toBeInstanceOf(StorageAdapterError);
const serializedDetails = JSON.stringify((error as StorageAdapterError).details);
expect(serializedDetails).not.toContain("access-key");
expect(serializedDetails).not.toContain("secret-key");
expect(serializedDetails).not.toContain("session-token");
expect(serializedDetails).not.toContain("request-body");
expect(serializedDetails).not.toContain("responseBody");
}
});
it("sends DeleteObjectCommand input and defaults to the configured bucket", async () => {
const send = vi.fn().mockResolvedValue({});
const adapter = createS3StorageAdapter({ ...baseConfig, client: { send } });
await expect(
adapter.deleteObject({ key: "exports/job-123.csv" }),
).resolves.toEqual({
bucket: "uploads",
key: "exports/job-123.csv",
});
expect(send).toHaveBeenCalledOnce();
const command = send.mock.calls[0]?.[0];
expect(command).toBeInstanceOf(DeleteObjectCommand);
expect(command.input).toEqual({
Bucket: "uploads",
Key: "exports/job-123.csv",
});
});
it("allows deleteObject to target an explicit bucket", async () => {
const send = vi.fn().mockResolvedValue({});
const adapter = createS3StorageAdapter({ ...baseConfig, client: { send } });
await expect(
adapter.deleteObject({ bucket: "archive", key: "exports/job-123.csv" }),
).resolves.toEqual({
bucket: "archive",
key: "exports/job-123.csv",
});
expect(send.mock.calls[0]?.[0].input).toEqual({
Bucket: "archive",
Key: "exports/job-123.csv",
});
});
it("rejects invalid delete keys and buckets before sending to S3", async () => {
const send = vi.fn().mockResolvedValue({});
const adapter = createS3StorageAdapter({ ...baseConfig, client: { send } });
await expect(adapter.deleteObject({ key: " " })).rejects.toMatchObject({
code: "invalid_key",
details: { operation: "deleteObject", bucket: "uploads", key: " " },
});
await expect(
adapter.deleteObject({ bucket: " ", key: "exports/job-123.csv" }),
).rejects.toMatchObject({
code: "invalid_bucket",
details: {
operation: "deleteObject",
bucket: " ",
key: "exports/job-123.csv",
},
});
expect(send).not.toHaveBeenCalled();
});
it("wraps deleteObject failures with redacted upstream diagnostics", async () => {
const upstreamError = Object.assign(
new Error("delete failed token abc123 credential secret-key"),
{
name: "AccessDenied",
$metadata: { httpStatusCode: 403, requestId: "req-delete" },
body: "delete-request-body",
},
);
const adapter = createS3StorageAdapter({
...baseConfig,
client: { send: vi.fn().mockRejectedValue(upstreamError) },
});
try {
await adapter.deleteObject({ key: "exports/job-123.csv" });
throw new Error("expected deleteObject to fail");
} catch (error) {
expect(error).toBeInstanceOf(StorageAdapterError);
const adapterError = error as StorageAdapterError;
expect(adapterError).toMatchObject({
code: "delete_failed",
details: {
operation: "deleteObject",
bucket: "uploads",
key: "exports/job-123.csv",
upstream: {
name: "AccessDenied",
message: "delete failed token [redacted] credential [redacted]",
status: 403,
requestId: "req-delete",
},
},
});
expect(JSON.stringify(adapterError.details)).not.toContain("abc123");
expect(JSON.stringify(adapterError.details)).not.toContain("secret-key");
expect(JSON.stringify(adapterError.details)).not.toContain("delete-request-body");
}
});
});
describe("createLocalStorageAdapter", () => {
it("stores objects under the configured bucket root and returns a public URL", async () => {
const rootDir = await mkdtemp(join(tmpdir(), "toolctrl-storage-"));
const adapter = createLocalStorageAdapter({
rootDir,
bucket: "uploads",
publicBaseUrl: "http://localhost:3000/storage",
});
await expect(adapter.putObject({ key: "tenants/acme/avatar.png", body: "image" })).resolves.toEqual({
bucket: "uploads",
key: "tenants/acme/avatar.png",
publicUrl: "http://localhost:3000/storage/uploads/tenants/acme/avatar.png",
});
await expect(readFile(join(rootDir, "uploads", "tenants", "acme", "avatar.png"), "utf8")).resolves.toBe("image");
});
it("rejects local object keys that escape the storage root", async () => {
const rootDir = await mkdtemp(join(tmpdir(), "toolctrl-storage-"));
const adapter = createLocalStorageAdapter({ rootDir, bucket: "uploads" });
await expect(adapter.putObject({ key: "../secret.txt", body: "secret" })).rejects.toMatchObject({
code: "invalid_key",
details: {
operation: "normalizeLocalObjectKey",
key: "../secret.txt",
},
});
});
});
@@ -0,0 +1,765 @@
import {
AbortMultipartUploadCommand as AwsAbortMultipartUploadCommand,
CompleteMultipartUploadCommand as AwsCompleteMultipartUploadCommand,
CreateMultipartUploadCommand as AwsCreateMultipartUploadCommand,
DeleteObjectCommand as AwsDeleteObjectCommand,
PutObjectCommand as AwsPutObjectCommand,
S3Client as AwsS3Client,
UploadPartCopyCommand as AwsUploadPartCopyCommand,
} from "@aws-sdk/client-s3";
import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
import { dirname, resolve, sep } from "node:path";
export * from "./access/index.js";
export * from "./paths/index.js";
export * from "./scan/index.js";
export * from "./signed/index.js";
export type UploadBody = string | Uint8Array | ArrayBuffer | ReadableStream<Uint8Array>;
export interface StorageObjectResult {
bucket: string;
key: string;
publicUrl: string | null;
}
export interface DeleteObjectResult {
bucket: string;
key: string;
}
/** Handle for an in-flight multipart upload (S3 `UploadId` + target key). */
export interface MultipartUploadHandle {
bucket: string;
key: string;
uploadId: string;
}
/** One completed part of a multipart upload (1-based `partNumber` + ETag). */
export interface UploadedPart {
partNumber: number;
etag: string;
}
export type StorageAdapterErrorCode =
| "config_missing"
| "put_failed"
| "delete_failed"
| "signed_upload_failed"
| "signed_download_failed"
| "invalid_key"
| "invalid_bucket"
| "invalid_expiry";
export interface StorageAdapterErrorDetails {
operation: string;
bucket?: string;
key?: string;
missingFields?: string[];
upstream?: {
name?: string;
message?: string;
status?: number;
requestId?: string;
};
}
export class StorageAdapterError extends Error {
readonly code: StorageAdapterErrorCode;
readonly details: StorageAdapterErrorDetails;
override readonly cause?: unknown;
constructor(
code: StorageAdapterErrorCode,
message: string,
details: StorageAdapterErrorDetails,
options: { cause?: unknown } = {},
) {
super(message);
this.name = "StorageAdapterError";
this.code = code;
this.details = details;
this.cause = options.cause;
}
}
export interface PutObjectInput {
key: string;
body: UploadBody;
contentType?: string;
cacheControl?: string;
metadata?: Record<string, string>;
}
export interface DeleteObjectInput {
bucket?: string;
key: string;
}
export interface CreateMultipartUploadInput {
key: string;
contentType?: string;
metadata?: Record<string, string>;
}
export interface UploadPartCopyInput {
/** Target object key of the multipart upload. */
key: string;
uploadId: string;
/** 1-based part number. */
partNumber: number;
/** Source object key (already stored in the same bucket) to copy as this part. */
sourceKey: string;
}
export interface CompleteMultipartUploadInput {
key: string;
uploadId: string;
parts: readonly UploadedPart[];
}
export interface AbortMultipartUploadInput {
key: string;
uploadId: string;
}
export interface StorageAdapter {
putObject(input: PutObjectInput): Promise<StorageObjectResult>;
deleteObject(input: DeleteObjectInput): Promise<DeleteObjectResult>;
/**
* Server-side chunk assembly (§3). Chunks are first stored as temp objects in
* the same bucket, then assembled into the final object via multipart
* UploadPartCopy — memory-safe for files up to the 500 MB limit. The whole
* create/copy/complete sequence runs within a single `completeUpload` request,
* so the S3 `UploadId` never needs to be persisted across requests.
*/
createMultipartUpload(input: CreateMultipartUploadInput): Promise<MultipartUploadHandle>;
uploadPartCopy(input: UploadPartCopyInput): Promise<UploadedPart>;
completeMultipartUpload(input: CompleteMultipartUploadInput): Promise<StorageObjectResult>;
abortMultipartUpload(input: AbortMultipartUploadInput): Promise<void>;
}
export interface PutObjectCommandInput {
Bucket: string;
Key: string;
Body: UploadBody;
ContentType?: string;
CacheControl?: string;
Metadata?: Record<string, string>;
}
export class PutObjectCommand {
readonly input: PutObjectCommandInput;
constructor(input: PutObjectCommandInput) {
this.input = input;
}
}
export interface DeleteObjectCommandInput {
Bucket: string;
Key: string;
}
export class DeleteObjectCommand {
readonly input: DeleteObjectCommandInput;
constructor(input: DeleteObjectCommandInput) {
this.input = input;
}
}
export interface CreateMultipartUploadCommandInput {
Bucket: string;
Key: string;
ContentType?: string;
Metadata?: Record<string, string>;
}
export class CreateMultipartUploadCommand {
readonly input: CreateMultipartUploadCommandInput;
constructor(input: CreateMultipartUploadCommandInput) {
this.input = input;
}
}
export interface UploadPartCopyCommandInput {
Bucket: string;
Key: string;
UploadId: string;
PartNumber: number;
CopySource: string;
}
export class UploadPartCopyCommand {
readonly input: UploadPartCopyCommandInput;
constructor(input: UploadPartCopyCommandInput) {
this.input = input;
}
}
export interface CompleteMultipartUploadCommandInput {
Bucket: string;
Key: string;
UploadId: string;
MultipartUpload: { Parts: { ETag: string; PartNumber: number }[] };
}
export class CompleteMultipartUploadCommand {
readonly input: CompleteMultipartUploadCommandInput;
constructor(input: CompleteMultipartUploadCommandInput) {
this.input = input;
}
}
export interface AbortMultipartUploadCommandInput {
Bucket: string;
Key: string;
UploadId: string;
}
export class AbortMultipartUploadCommand {
readonly input: AbortMultipartUploadCommandInput;
constructor(input: AbortMultipartUploadCommandInput) {
this.input = input;
}
}
export type StorageCommand =
| PutObjectCommand
| DeleteObjectCommand
| CreateMultipartUploadCommand
| UploadPartCopyCommand
| CompleteMultipartUploadCommand
| AbortMultipartUploadCommand;
export interface S3StorageClient {
send(command: StorageCommand): Promise<unknown>;
}
export class S3Client implements S3StorageClient {
readonly config: {
endpoint: string;
region: string;
forcePathStyle?: boolean;
credentials: {
accessKeyId: string;
secretAccessKey: string;
sessionToken?: string;
};
};
private readonly client: AwsS3Client;
constructor(config: S3Client["config"]) {
this.config = config;
this.client = new AwsS3Client(config);
}
async send(command: StorageCommand): Promise<unknown> {
if (command instanceof PutObjectCommand) {
return this.client.send(new AwsPutObjectCommand(toAwsPutObjectInput(command.input)));
}
if (command instanceof CreateMultipartUploadCommand) {
return this.client.send(new AwsCreateMultipartUploadCommand(command.input));
}
if (command instanceof UploadPartCopyCommand) {
return this.client.send(new AwsUploadPartCopyCommand(command.input));
}
if (command instanceof CompleteMultipartUploadCommand) {
return this.client.send(new AwsCompleteMultipartUploadCommand(command.input));
}
if (command instanceof AbortMultipartUploadCommand) {
return this.client.send(new AwsAbortMultipartUploadCommand(command.input));
}
return this.client.send(new AwsDeleteObjectCommand(command.input));
}
}
function toAwsPutObjectInput(input: PutObjectCommandInput): ConstructorParameters<typeof AwsPutObjectCommand>[0] {
return {
...input,
Body: normalizeAwsUploadBody(input.Body) as ConstructorParameters<typeof AwsPutObjectCommand>[0]["Body"],
};
}
function normalizeAwsUploadBody(body: UploadBody) {
return body instanceof ArrayBuffer ? new Uint8Array(body) : body;
}
export interface S3StorageAdapterConfig {
endpoint: string;
region: string;
bucket: string;
accessKeyId: string;
secretAccessKey: string;
sessionToken?: string;
publicBaseUrl?: string;
forcePathStyle?: boolean;
client?: S3StorageClient;
}
export interface LocalStorageAdapterConfig {
rootDir: string;
bucket: string;
publicBaseUrl?: string;
}
const REQUIRED_CONFIG_FIELDS = [
"endpoint",
"region",
"bucket",
"accessKeyId",
"secretAccessKey",
] as const satisfies readonly (keyof S3StorageAdapterConfig)[];
export function createS3StorageAdapter(
config: S3StorageAdapterConfig,
): StorageAdapter {
const missingFields = REQUIRED_CONFIG_FIELDS.filter(
(field) => !isPresent(config[field]),
);
if (missingFields.length > 0) {
throw new StorageAdapterError(
"config_missing",
`Missing S3 storage configuration: ${missingFields.join(", ")}`,
{
operation: "createS3StorageAdapter",
bucket: isPresent(config.bucket) ? config.bucket : undefined,
missingFields: [...missingFields],
},
);
}
const client =
config.client ??
new S3Client({
endpoint: config.endpoint,
region: config.region,
forcePathStyle: config.forcePathStyle,
credentials: {
accessKeyId: config.accessKeyId,
secretAccessKey: config.secretAccessKey,
sessionToken: config.sessionToken,
},
});
return {
async putObject(input) {
const command = new PutObjectCommand({
Bucket: config.bucket,
Key: input.key,
Body: input.body,
ContentType: input.contentType,
CacheControl: input.cacheControl,
Metadata: input.metadata,
});
try {
await client.send(command);
} catch (cause) {
throw new StorageAdapterError(
"put_failed",
"Failed to put object in S3 storage.",
{
operation: "putObject",
bucket: config.bucket,
key: input.key,
upstream: extractUpstreamDetails(cause),
},
{ cause },
);
}
return {
bucket: config.bucket,
key: input.key,
publicUrl: buildPublicUrl(config.publicBaseUrl, input.key),
};
},
async deleteObject(input) {
const bucket = input.bucket ?? config.bucket;
if (!isPresent(bucket)) {
throw new StorageAdapterError(
"invalid_bucket",
"S3 object deletion requires a non-empty bucket.",
{
operation: "deleteObject",
bucket: input.bucket,
key: input.key,
},
);
}
if (!isPresent(input.key)) {
throw new StorageAdapterError(
"invalid_key",
"S3 object deletion requires a non-empty key.",
{
operation: "deleteObject",
bucket,
key: input.key,
},
);
}
const command = new DeleteObjectCommand({
Bucket: bucket,
Key: input.key,
});
try {
await client.send(command);
} catch (cause) {
throw new StorageAdapterError(
"delete_failed",
"Failed to delete object from S3 storage.",
{
operation: "deleteObject",
bucket,
key: input.key,
upstream: extractUpstreamDetails(cause),
},
{ cause },
);
}
return {
bucket,
key: input.key,
};
},
async createMultipartUpload(input) {
try {
const response = (await client.send(
new CreateMultipartUploadCommand({
Bucket: config.bucket,
Key: input.key,
ContentType: input.contentType,
Metadata: input.metadata,
}),
)) as { UploadId?: string };
if (!isPresent(response.UploadId)) {
throw new Error("S3 CreateMultipartUpload returned no UploadId.");
}
return { bucket: config.bucket, key: input.key, uploadId: response.UploadId };
} catch (cause) {
throw new StorageAdapterError(
"put_failed",
"Failed to create multipart upload in S3 storage.",
{ operation: "createMultipartUpload", bucket: config.bucket, key: input.key, upstream: extractUpstreamDetails(cause) },
{ cause },
);
}
},
async uploadPartCopy(input) {
try {
const response = (await client.send(
new UploadPartCopyCommand({
Bucket: config.bucket,
Key: input.key,
UploadId: input.uploadId,
PartNumber: input.partNumber,
// CopySource must be URL-encoded "bucket/key".
CopySource: `${config.bucket}/${input.sourceKey}`
.split("/")
.map((segment) => encodeURIComponent(segment))
.join("/"),
}),
)) as { CopyPartResult?: { ETag?: string } };
const etag = response.CopyPartResult?.ETag;
if (!isPresent(etag)) {
throw new Error("S3 UploadPartCopy returned no ETag.");
}
return { partNumber: input.partNumber, etag };
} catch (cause) {
throw new StorageAdapterError(
"put_failed",
"Failed to copy part in S3 multipart upload.",
{ operation: "uploadPartCopy", bucket: config.bucket, key: input.key, upstream: extractUpstreamDetails(cause) },
{ cause },
);
}
},
async completeMultipartUpload(input) {
try {
await client.send(
new CompleteMultipartUploadCommand({
Bucket: config.bucket,
Key: input.key,
UploadId: input.uploadId,
MultipartUpload: {
Parts: [...input.parts]
.sort((a, b) => a.partNumber - b.partNumber)
.map((part) => ({ ETag: part.etag, PartNumber: part.partNumber })),
},
}),
);
} catch (cause) {
throw new StorageAdapterError(
"put_failed",
"Failed to complete S3 multipart upload.",
{ operation: "completeMultipartUpload", bucket: config.bucket, key: input.key, upstream: extractUpstreamDetails(cause) },
{ cause },
);
}
return { bucket: config.bucket, key: input.key, publicUrl: buildPublicUrl(config.publicBaseUrl, input.key) };
},
async abortMultipartUpload(input) {
try {
await client.send(
new AbortMultipartUploadCommand({ Bucket: config.bucket, Key: input.key, UploadId: input.uploadId }),
);
} catch (cause) {
throw new StorageAdapterError(
"put_failed",
"Failed to abort S3 multipart upload.",
{ operation: "abortMultipartUpload", bucket: config.bucket, key: input.key, upstream: extractUpstreamDetails(cause) },
{ cause },
);
}
},
};
}
export function createLocalStorageAdapter(config: LocalStorageAdapterConfig): StorageAdapter {
const missingFields = [
...(!isPresent(config.rootDir) ? ["rootDir"] : []),
...(!isPresent(config.bucket) ? ["bucket"] : []),
];
if (missingFields.length > 0) {
throw new StorageAdapterError("config_missing", `Missing local storage configuration: ${missingFields.join(", ")}`, {
operation: "createLocalStorageAdapter",
bucket: isPresent(config.bucket) ? config.bucket : undefined,
missingFields,
});
}
const rootDir = resolve(config.rootDir);
const bucketRoot = resolve(rootDir, config.bucket);
return {
async putObject(input) {
const key = normalizeLocalObjectKey(input.key);
const target = resolve(bucketRoot, key);
ensureInsideRoot(bucketRoot, target, key);
try {
await mkdir(dirname(target), { recursive: true });
await writeFile(target, await toLocalStorageBuffer(input.body));
} catch (cause) {
throw new StorageAdapterError(
"put_failed",
"Failed to put object in local storage.",
{
operation: "putObject",
bucket: config.bucket,
key,
upstream: extractUpstreamDetails(cause),
},
{ cause },
);
}
return {
bucket: config.bucket,
key,
publicUrl: buildPublicUrl(config.publicBaseUrl, `${config.bucket}/${key}`),
};
},
async deleteObject(input) {
const bucket = input.bucket ?? config.bucket;
if (bucket !== config.bucket) {
throw new StorageAdapterError("invalid_bucket", "Local object deletion requires the configured bucket.", {
operation: "deleteObject",
bucket,
key: input.key,
});
}
const key = normalizeLocalObjectKey(input.key);
const target = resolve(bucketRoot, key);
ensureInsideRoot(bucketRoot, target, key);
try {
await rm(target, { force: true });
} catch (cause) {
throw new StorageAdapterError(
"delete_failed",
"Failed to delete object from local storage.",
{
operation: "deleteObject",
bucket,
key,
upstream: extractUpstreamDetails(cause),
},
{ cause },
);
}
return { bucket, key };
},
// Local multipart: parts are staged as files under "<key>.multipart/" and
// concatenated on complete. The whole sequence runs in one process, so the
// returned uploadId is just the key.
async createMultipartUpload(input) {
const key = normalizeLocalObjectKey(input.key);
return { bucket: config.bucket, key, uploadId: key };
},
async uploadPartCopy(input) {
const key = normalizeLocalObjectKey(input.key);
const sourceKey = normalizeLocalObjectKey(input.sourceKey);
const source = resolve(bucketRoot, sourceKey);
ensureInsideRoot(bucketRoot, source, sourceKey);
const partPath = resolve(bucketRoot, localMultipartPartKey(key, input.partNumber));
ensureInsideRoot(bucketRoot, partPath, key);
try {
const bytes = await readFile(source);
await mkdir(dirname(partPath), { recursive: true });
await writeFile(partPath, bytes);
} catch (cause) {
throw new StorageAdapterError(
"put_failed",
"Failed to copy part in local multipart upload.",
{ operation: "uploadPartCopy", bucket: config.bucket, key, upstream: extractUpstreamDetails(cause) },
{ cause },
);
}
return { partNumber: input.partNumber, etag: `local-${input.partNumber}` };
},
async completeMultipartUpload(input) {
const key = normalizeLocalObjectKey(input.key);
const target = resolve(bucketRoot, key);
ensureInsideRoot(bucketRoot, target, key);
const ordered = [...input.parts].sort((a, b) => a.partNumber - b.partNumber);
try {
const buffers: Buffer[] = [];
for (const part of ordered) {
const partPath = resolve(bucketRoot, localMultipartPartKey(key, part.partNumber));
ensureInsideRoot(bucketRoot, partPath, key);
buffers.push(await readFile(partPath));
}
await mkdir(dirname(target), { recursive: true });
await writeFile(target, Buffer.concat(buffers));
await rm(resolve(bucketRoot, localMultipartDir(key)), { recursive: true, force: true });
} catch (cause) {
throw new StorageAdapterError(
"put_failed",
"Failed to complete local multipart upload.",
{ operation: "completeMultipartUpload", bucket: config.bucket, key, upstream: extractUpstreamDetails(cause) },
{ cause },
);
}
return { bucket: config.bucket, key, publicUrl: buildPublicUrl(config.publicBaseUrl, `${config.bucket}/${key}`) };
},
async abortMultipartUpload(input) {
const key = normalizeLocalObjectKey(input.key);
const dir = resolve(bucketRoot, localMultipartDir(key));
ensureInsideRoot(bucketRoot, dir, key);
await rm(dir, { recursive: true, force: true }).catch(() => {});
},
};
}
function localMultipartDir(key: string): string {
return `${key}.multipart`;
}
function localMultipartPartKey(key: string, partNumber: number): string {
return `${localMultipartDir(key)}/part-${String(partNumber).padStart(6, "0")}`;
}
async function toLocalStorageBuffer(body: UploadBody): Promise<Buffer> {
if (typeof body === "string") {
return Buffer.from(body);
}
if (body instanceof ArrayBuffer) {
return Buffer.from(body);
}
if (body instanceof Uint8Array) {
return Buffer.from(body);
}
const reader = body.getReader();
const chunks: Uint8Array[] = [];
while (true) {
const chunk = await reader.read();
if (chunk.done) {
break;
}
chunks.push(chunk.value);
}
return Buffer.concat(chunks);
}
function normalizeLocalObjectKey(key: string): string {
if (!isPresent(key) || key.startsWith("/") || key.includes("\\") || key.split("/").some((part) => part === "..")) {
throw new StorageAdapterError("invalid_key", "Storage object key is invalid.", {
operation: "normalizeLocalObjectKey",
key,
});
}
return key.replace(/^\.\/+/, "");
}
function ensureInsideRoot(rootDir: string, target: string, key: string): void {
if (target !== rootDir && !target.startsWith(`${rootDir}${sep}`)) {
throw new StorageAdapterError("invalid_key", "Storage object key escapes the configured storage root.", {
operation: "resolveLocalObjectPath",
key,
});
}
}
function isPresent(value: unknown): value is string {
return typeof value === "string" && value.trim().length > 0;
}
function buildPublicUrl(publicBaseUrl: string | undefined, key: string): string | null {
if (!isPresent(publicBaseUrl)) {
return null;
}
const base = publicBaseUrl.replace(/\/+$/, "");
const encodedKey = key
.split("/")
.map((segment) => encodeURIComponent(segment))
.join("/");
return `${base}/${encodedKey}`;
}
function extractUpstreamDetails(cause: unknown): StorageAdapterErrorDetails["upstream"] {
if (!isRecord(cause)) {
return undefined;
}
const metadata = isRecord(cause.$metadata) ? cause.$metadata : undefined;
return {
name: typeof cause.name === "string" ? cause.name : undefined,
message: typeof cause.message === "string" ? redactSecretLikeText(cause.message) : undefined,
status: typeof metadata?.httpStatusCode === "number" ? metadata.httpStatusCode : undefined,
requestId: typeof metadata?.requestId === "string" ? metadata.requestId : undefined,
};
}
function redactSecretLikeText(value: string): string {
return value.replace(/(token|secret|credential)([\s:=]+)([^\s,;]+)/gi, "$1$2[redacted]");
}
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === "object" && value !== null;
}
@@ -0,0 +1,44 @@
import { mkdtempSync, readFileSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, beforeEach, describe, expect, it } from "vitest";
import { createLocalStorageAdapter } from "./index.js";
// AK-P4a §3: chunk assembly via multipart. The local adapter mirrors the S3
// create -> uploadPartCopy -> complete sequence by staging part files and
// concatenating them in part order on complete.
describe("local multipart assembly", () => {
let rootDir: string;
const bucket = "test-bucket";
beforeEach(() => {
rootDir = mkdtempSync(join(tmpdir(), "hg-storage-"));
});
afterEach(() => {
rmSync(rootDir, { recursive: true, force: true });
});
it("assembles temp chunk objects into a single object in part order", async () => {
const adapter = createLocalStorageAdapter({ rootDir, bucket });
await adapter.putObject({ key: "tmp/chunk-0", body: "hello " });
await adapter.putObject({ key: "tmp/chunk-1", body: "world" });
const handle = await adapter.createMultipartUpload({ key: "final/object" });
const part1 = await adapter.uploadPartCopy({ key: "final/object", uploadId: handle.uploadId, partNumber: 1, sourceKey: "tmp/chunk-0" });
const part2 = await adapter.uploadPartCopy({ key: "final/object", uploadId: handle.uploadId, partNumber: 2, sourceKey: "tmp/chunk-1" });
// Pass parts out of order to prove the adapter sorts by partNumber.
await adapter.completeMultipartUpload({ key: "final/object", uploadId: handle.uploadId, parts: [part2, part1] });
const assembled = readFileSync(join(rootDir, bucket, "final/object"), "utf8");
expect(assembled).toBe("hello world");
});
it("abort removes the part-staging directory", async () => {
const adapter = createLocalStorageAdapter({ rootDir, bucket });
await adapter.putObject({ key: "tmp/chunk-0", body: "x" });
const handle = await adapter.createMultipartUpload({ key: "final/object" });
await adapter.uploadPartCopy({ key: "final/object", uploadId: handle.uploadId, partNumber: 1, sourceKey: "tmp/chunk-0" });
await adapter.abortMultipartUpload({ key: "final/object", uploadId: handle.uploadId });
expect(() => readFileSync(join(rootDir, bucket, "final/object.multipart/part-000001"))).toThrow();
});
});
@@ -0,0 +1,43 @@
import { describe, expect, it } from "vitest";
import {
assertFileKeyBelongsToTenant,
buildFilePreviewKey,
buildFileStorageKeys,
buildUploadChunkKey,
fileStoragePrefix,
uploadChunkPrefix,
} from "./index.js";
describe("file storage paths", () => {
it("builds tenant-scoped original and thumbnail keys", () => {
expect(buildFileStorageKeys("acme", "file123")).toEqual({
original: "tenants/acme/files/file123/original",
thumbnail: "tenants/acme/files/file123/thumb.webp",
});
});
it("builds preview keys with the format-specific extension", () => {
expect(buildFilePreviewKey("acme", "file123", "png")).toBe("tenants/acme/files/file123/preview.png");
expect(buildFilePreviewKey("acme", "file123", "webp")).toBe("tenants/acme/files/file123/preview.webp");
expect(buildFilePreviewKey("acme", "file123", "jpg")).toBe("tenants/acme/files/file123/preview.jpg");
});
it("builds chunk keys and the chunk prefix", () => {
expect(buildUploadChunkKey("acme", "up1", 0)).toBe("tenants/acme/uploads/up1/chunk-0");
expect(buildUploadChunkKey("acme", "up1", 7)).toBe("tenants/acme/uploads/up1/chunk-7");
expect(uploadChunkPrefix("acme", "up1")).toBe("tenants/acme/uploads/up1");
});
it("rejects path-traversal and slash injection in segments", () => {
expect(() => fileStoragePrefix("acme", "../evil")).toThrow();
expect(() => buildUploadChunkKey("acme", "up1", -1)).toThrow();
expect(() => buildUploadChunkKey("a/b", "up1", 0)).toThrow();
});
it("asserts a key belongs to the requesting tenant", () => {
const key = buildFileStorageKeys("acme", "file123").original;
expect(assertFileKeyBelongsToTenant("acme", key)).toBe(key);
expect(() => assertFileKeyBelongsToTenant("other", key)).toThrow();
});
});
@@ -0,0 +1,79 @@
// P4 Files (AK-P4a) §2 — storage path convention (Hetzner, private).
//
// Tenant isolation is TWOFOLD:
// (a) every key carries the prefix `tenants/{tenantId}/` (hard-checked by
// authorizeStorageObjectAccess);
// (b) the app calls assertFileKeyBelongsToTenant() before every storage
// access, so a foreign tenant's key is never resolved.
//
// Pure functions, no I/O — testable without storage. The bucket itself comes
// from STORAGE_BUCKET (staging: hivegrid-staging-media), NOT from these keys.
import { authorizeStorageObjectAccess, type StorageAccessOperation } from "../access/index.js";
export type FilePreviewExtension = "png" | "webp" | "jpg";
export interface FileStorageKeys {
/** Original-Objekt: tenants/{tenantId}/files/{fileId}/original */
readonly original: string;
/** Thumbnail (immer WebP): tenants/{tenantId}/files/{fileId}/thumb.webp */
readonly thumbnail: string;
}
function requireSegment(value: string, field: string): string {
const normalized = value.trim();
if (normalized.length === 0 || normalized.includes("/") || normalized.includes("\\")) {
throw new Error(`Invalid storage path segment for ${field}: must be a non-empty id without slashes.`);
}
return normalized;
}
/** Base prefix of a file. */
export function fileStoragePrefix(tenantId: string, fileId: string): string {
return `tenants/${requireSegment(tenantId, "tenantId")}/files/${requireSegment(fileId, "fileId")}`;
}
/** Original and thumbnail key of a file. */
export function buildFileStorageKeys(tenantId: string, fileId: string): FileStorageKeys {
const prefix = fileStoragePrefix(tenantId, fileId);
return {
original: `${prefix}/original`,
thumbnail: `${prefix}/thumb.webp`,
};
}
/** Preview key with a format-dependent extension (PDF->png, image->webp, HEIC->jpg). */
export function buildFilePreviewKey(tenantId: string, fileId: string, extension: FilePreviewExtension): string {
return `${fileStoragePrefix(tenantId, fileId)}/preview.${extension}`;
}
/** Temp key of an upload chunk: tenants/{tenantId}/uploads/{uploadId}/chunk-{index}. */
export function buildUploadChunkKey(tenantId: string, uploadId: string, chunkIndex: number): string {
if (!Number.isInteger(chunkIndex) || chunkIndex < 0) {
throw new Error(`Invalid chunk index: ${chunkIndex}`);
}
return `tenants/${requireSegment(tenantId, "tenantId")}/uploads/${requireSegment(uploadId, "uploadId")}/chunk-${chunkIndex}`;
}
/** Prefix of all temp chunks of an upload session (for cleanup). */
export function uploadChunkPrefix(tenantId: string, uploadId: string): string {
return `tenants/${requireSegment(tenantId, "tenantId")}/uploads/${requireSegment(uploadId, "uploadId")}`;
}
/**
* Throws if `key` does not belong to `tenantId`. Thin wrapper around
* authorizeStorageObjectAccess (single source of truth for the
* `tenants/{tenantId}/` prefix + path-traversal guard). Call BEFORE every
* download/delete of a key read from the DB.
*/
export function assertFileKeyBelongsToTenant(
tenantId: string,
key: string,
operation: StorageAccessOperation = "download",
): string {
const decision = authorizeStorageObjectAccess({ tenantId, key, operation });
if (!decision.allowed) {
throw new Error(`Storage key does not belong to tenant (${decision.reason}).`);
}
return decision.key;
}
@@ -0,0 +1,36 @@
import { describe, expect, it } from "vitest";
import { DEFAULT_ALLOW_LIST, resolveAllowList } from "./allow-list.js";
describe("resolveAllowList", () => {
it("returns restrictive defaults when no environment overrides are supplied", () => {
expect(resolveAllowList()).toEqual(DEFAULT_ALLOW_LIST);
});
it("replaces a context default with the operator supplied env allow-list", () => {
const allowList = resolveAllowList({
STORAGE_SCAN_ALLOWLIST_EMAIL_ATTACHMENT: "application/pdf,text/calendar",
});
expect(allowList.emailAttachment).toEqual(["application/pdf", "text/calendar"]);
expect(allowList.avatar).toEqual(DEFAULT_ALLOW_LIST.avatar);
expect(allowList.mediaLibrary).toEqual(DEFAULT_ALLOW_LIST.mediaLibrary);
});
it("normalizes override values before they are used by upload validators", () => {
const allowList = resolveAllowList({
STORAGE_SCAN_ALLOWLIST_AVATAR: " Image/PNG, IMAGE/WEBP ,, image/jpeg ",
});
expect(allowList.avatar).toEqual(["image/png", "image/webp", "image/jpeg"]);
});
it("allows an explicit empty override to deny every mime type for a context", () => {
const allowList = resolveAllowList({
STORAGE_SCAN_ALLOWLIST_FORM_UPLOAD: " ",
});
expect(allowList.formUpload).toEqual([]);
expect(allowList.kbAsset).toEqual(DEFAULT_ALLOW_LIST.kbAsset);
});
});
@@ -0,0 +1,54 @@
import type { PreUploadAllowList, ScanContext } from "./pre-upload-types.js";
const IMAGE_TYPES = ["image/png", "image/jpeg", "image/webp"] as const;
const IMAGE_TYPES_WITH_GIF = [...IMAGE_TYPES, "image/gif"] as const;
const OFFICE_TYPES = [
"application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
"application/vnd.openxmlformats-officedocument.presentationml.presentation",
] as const;
/**
* Restrictive defaults per upload context. Operator can extend per-context via the
* STORAGE_SCAN_ALLOWLIST_<CONTEXT> env var (parsed as a comma-separated list and
* REPLACES the default — not merged, so the operator's list is authoritative).
*/
export const DEFAULT_ALLOW_LIST: PreUploadAllowList = {
avatar: IMAGE_TYPES,
mediaLibrary: [...IMAGE_TYPES_WITH_GIF, "image/svg+xml", "image/x-icon", "image/vnd.microsoft.icon"],
emailAttachment: [...IMAGE_TYPES_WITH_GIF, "application/pdf", "text/plain", "text/csv", "application/zip", ...OFFICE_TYPES],
formUpload: [...IMAGE_TYPES, "application/pdf"],
kbAsset: [...IMAGE_TYPES, "application/pdf"],
};
const ENV_PREFIX = "STORAGE_SCAN_ALLOWLIST_";
const ENV_KEYS: Record<ScanContext, string> = {
avatar: `${ENV_PREFIX}AVATAR`,
mediaLibrary: `${ENV_PREFIX}MEDIA_LIBRARY`,
emailAttachment: `${ENV_PREFIX}EMAIL_ATTACHMENT`,
formUpload: `${ENV_PREFIX}FORM_UPLOAD`,
kbAsset: `${ENV_PREFIX}KB_ASSET`,
};
/**
* Build the effective allow-list by merging the static defaults with any
* `STORAGE_SCAN_ALLOWLIST_<CONTEXT>` overrides in the supplied env. If the env
* var is set (even to an empty string), it REPLACES the default for that
* context. Unset env vars leave the default untouched.
*
* Caller responsibility: pass the runtime env explicitly so the function stays
* pure and testable. Don't read process.env inside this module.
*/
export function resolveAllowList(env: Record<string, string | undefined> = {}): PreUploadAllowList {
const next: Record<ScanContext, readonly string[]> = { ...DEFAULT_ALLOW_LIST };
for (const context of Object.keys(ENV_KEYS) as ScanContext[]) {
const raw = env[ENV_KEYS[context]];
if (raw === undefined) continue;
next[context] = raw
.split(",")
.map((value) => value.trim().toLowerCase())
.filter((value) => value.length > 0);
}
return next;
}
@@ -0,0 +1,128 @@
// @vitest-environment node
import { Buffer } from "node:buffer";
import { describe, expect, test, vi } from "vitest";
import { ClamAVUnreachableError, createClamAVStorageScanner, isClamAVUnreachableError, type ClamScanClient } from "./clamav-scanner.js";
const EICAR_BUFFER = Buffer.from("X5O!P%@AP[4\\PZX54(P^)7CC)7}$EICAR-STANDARD-ANTIVIRUS-TEST-FILE!$H+H*", "utf8");
const CLEAN_BUFFER = Buffer.from("hello world", "utf8");
function buildClient(overrides: Partial<ClamScanClient> = {}): ClamScanClient {
return {
isReachable: vi.fn(async () => true),
scanBuffer: vi.fn(async () => ({ isInfected: false })),
scanStream: vi.fn(async () => ({ isInfected: false })),
...overrides,
};
}
const baseConfig = {
host: "clamav",
port: 3310,
timeoutMs: 30000,
};
describe("ClamAVStorageScanner", () => {
test("returns 'clean' when clamd reports no infection", async () => {
const client = buildClient();
const scanner = createClamAVStorageScanner({
...baseConfig,
loadObject: async () => CLEAN_BUFFER,
initClient: async () => client,
});
const result = await scanner.scanObject({ bucket: "uploads", key: "user/1/avatar.png" });
expect(result.verdict).toBe("clean");
expect((result as { engine?: string }).engine).toBe("clamav");
expect(client.scanBuffer).toHaveBeenCalledWith(CLEAN_BUFFER);
});
test("returns 'infected' with the first signature when clamd hits", async () => {
const client = buildClient({
scanBuffer: vi.fn(async () => ({ isInfected: true, viruses: ["Win.Test.EICAR_HDB-1", "extra-signature"] })),
});
const scanner = createClamAVStorageScanner({
...baseConfig,
loadObject: async () => EICAR_BUFFER,
initClient: async () => client,
});
const result = await scanner.scanObject({ bucket: "uploads", key: "user/1/eicar.txt" });
expect(result.verdict).toBe("infected");
if (result.verdict === "infected") {
expect(result.signature).toBe("Win.Test.EICAR_HDB-1");
expect(result.engine).toBe("clamav");
}
});
test("falls back to signature 'unknown' when clamd reports infected with no viruses array", async () => {
const client = buildClient({ scanBuffer: vi.fn(async () => ({ isInfected: true })) });
const scanner = createClamAVStorageScanner({
...baseConfig,
loadObject: async () => EICAR_BUFFER,
initClient: async () => client,
});
const result = await scanner.scanObject({ bucket: "uploads", key: "x" });
expect(result.verdict).toBe("infected");
if (result.verdict === "infected") expect(result.signature).toBe("unknown");
});
test("throws ClamAVUnreachableError when isReachable returns false", async () => {
const client = buildClient({ isReachable: vi.fn(async () => false) });
const scanner = createClamAVStorageScanner({
...baseConfig,
loadObject: async () => CLEAN_BUFFER,
initClient: async () => client,
});
await expect(scanner.scanObject({ bucket: "uploads", key: "x" })).rejects.toThrow(ClamAVUnreachableError);
expect(client.scanBuffer).not.toHaveBeenCalled();
});
test("treats isReachable rejection as unreachable instead of leaking the error", async () => {
const client = buildClient({
isReachable: vi.fn(async () => {
throw new Error("ENOTFOUND");
}),
});
const scanner = createClamAVStorageScanner({
...baseConfig,
loadObject: async () => CLEAN_BUFFER,
initClient: async () => client,
});
await expect(scanner.scanObject({ bucket: "uploads", key: "x" })).rejects.toSatisfy(isClamAVUnreachableError);
});
test("scans a Readable stream when loadObject returns one", async () => {
const client = buildClient({
scanStream: vi.fn(async () => ({ isInfected: false })),
});
const { Readable } = await import("node:stream");
const stream = Readable.from([Buffer.from("payload")]);
const scanner = createClamAVStorageScanner({
...baseConfig,
loadObject: async () => stream,
initClient: async () => client,
});
const result = await scanner.scanObject({ bucket: "uploads", key: "x" });
expect(result.verdict).toBe("clean");
expect(client.scanStream).toHaveBeenCalledWith(stream);
expect(client.scanBuffer).not.toHaveBeenCalled();
});
test("caches the client between scans (single init)", async () => {
const client = buildClient();
const initClient = vi.fn(async () => client);
const scanner = createClamAVStorageScanner({
...baseConfig,
loadObject: async () => CLEAN_BUFFER,
initClient,
});
await scanner.scanObject({ bucket: "uploads", key: "a" });
await scanner.scanObject({ bucket: "uploads", key: "b" });
expect(initClient).toHaveBeenCalledTimes(1);
});
test("isClamAVUnreachableError narrows arbitrary errors", () => {
expect(isClamAVUnreachableError(new ClamAVUnreachableError("nope"))).toBe(true);
expect(isClamAVUnreachableError(new Error("regular"))).toBe(false);
expect(isClamAVUnreachableError("string")).toBe(false);
expect(isClamAVUnreachableError(null)).toBe(false);
});
});
@@ -0,0 +1,144 @@
// ClamAV-backed implementation of the StorageScanner contract from
// ./index.ts. Talks to a clamd daemon via the TCP clamscan protocol
// (default port 3310). Used by the worker runtime's scan-file job handler.
/// <reference path="./clamscan.d.ts" />
import type { StorageScanner, StorageScannerInput, StorageScannerResult } from "./index.js";
export interface ClamAVScannerConfig {
host: string;
port: number;
/**
* Connect / scan timeout in ms. clamd can take several seconds on the very
* first request after boot while it warms up; 30 s is the operational
* default.
*/
timeoutMs: number;
/**
* Loader for the upload payload. Returning a Buffer or Readable is fine;
* clamscan accepts both via scanStream/scanBuffer. The scanner doesn't read
* the object itself so callers (typically the worker job handler) can plug
* in any storage backend.
*/
loadObject: (input: StorageScannerInput) => Promise<Buffer | NodeJS.ReadableStream>;
/**
* Override for the clamscan client constructor. Used by tests; production
* leaves it unset so the real npm package is loaded lazily.
*/
initClient?: (options: { host: string; port: number; timeoutMs: number }) => Promise<ClamScanClient>;
/**
* Override for the wall clock. Tests inject a stub to make scannedAt
* deterministic.
*/
now?: () => Date;
}
export interface ClamScanResult {
isInfected: boolean | null;
viruses?: readonly string[];
}
export interface ClamScanClient {
/** Returns true when clamd answers a PING within the configured timeout. */
isReachable(): Promise<boolean>;
/** Scan a single in-memory buffer. Throws on transport errors. */
scanBuffer(buffer: Buffer): Promise<ClamScanResult>;
/** Scan a stream end-to-end. */
scanStream(stream: NodeJS.ReadableStream): Promise<ClamScanResult>;
}
const ENGINE = "clamav";
export function createClamAVStorageScanner(config: ClamAVScannerConfig): StorageScanner {
const initClient = config.initClient ?? defaultInitClient;
let cachedClient: ClamScanClient | undefined;
async function getClient(): Promise<ClamScanClient> {
if (!cachedClient) {
cachedClient = await initClient({ host: config.host, port: config.port, timeoutMs: config.timeoutMs });
}
return cachedClient;
}
return {
async scanObject(target: StorageScannerInput): Promise<StorageScannerResult> {
const client = await getClient();
const reachable = await client.isReachable().catch(() => false);
if (!reachable) {
throw new ClamAVUnreachableError(`clamd at ${config.host}:${config.port} is unreachable`);
}
const payload = await config.loadObject(target);
const result = await scanWithClient(client, payload);
if (result.isInfected) {
const signature = result.viruses?.[0] ?? "unknown";
return { verdict: "infected", signature, engine: ENGINE };
}
return { verdict: "clean", engine: ENGINE };
},
};
}
async function scanWithClient(client: ClamScanClient, payload: Buffer | NodeJS.ReadableStream): Promise<ClamScanResult> {
if (Buffer.isBuffer(payload)) {
return client.scanBuffer(payload);
}
return client.scanStream(payload);
}
async function defaultInitClient({ host, port, timeoutMs }: { host: string; port: number; timeoutMs: number }): Promise<ClamScanClient> {
// Lazy import so non-worker bundles (the web app, the API) don't try to
// resolve the native clamscan dependency. The clamscan package exports a
// factory whose init() returns the client. See clamscan.d.ts in this
// directory for the (intentionally narrow) module ambient typing.
const mod = await import("clamscan");
const Factory = (mod as { default?: unknown }).default ?? mod;
const factory = typeof Factory === "function" ? new (Factory as new () => { init: (opts: unknown) => Promise<unknown> })() : (Factory as { init: (opts: unknown) => Promise<unknown> });
const client = (await factory.init({
removeInfected: false,
debugMode: false,
clamdscan: {
host,
port,
timeout: timeoutMs,
localFallback: false,
},
preference: "clamdscan",
})) as ClamScanLib;
return {
async isReachable() {
const status = await client.ping();
return Boolean(status);
},
async scanBuffer(buffer) {
const res = await client.scanBuffer(buffer);
return { isInfected: res.isInfected, viruses: res.viruses };
},
async scanStream(stream) {
const res = await client.scanStream(stream);
return { isInfected: res.isInfected, viruses: res.viruses };
},
};
}
// Subset of the clamscan npm package surface that we actually use. Avoids a
// dependency on @types/clamscan and lets the lazy import stay loose.
interface ClamScanLib {
ping(): Promise<unknown>;
scanBuffer(buffer: Buffer): Promise<{ isInfected: boolean | null; viruses?: string[] }>;
scanStream(stream: NodeJS.ReadableStream): Promise<{ isInfected: boolean | null; viruses?: string[] }>;
}
export class ClamAVUnreachableError extends Error {
constructor(message: string) {
super(message);
this.name = "ClamAVUnreachableError";
}
}
export function isClamAVUnreachableError(error: unknown): error is ClamAVUnreachableError {
return error instanceof Error && error.name === "ClamAVUnreachableError";
}
@@ -0,0 +1,27 @@
// Narrow ambient typing for the `clamscan` npm package, which ships no
// .d.ts of its own. We only touch ping/scanBuffer/scanStream; anything else
// stays untyped on purpose.
declare module "clamscan" {
export interface ClamScanInitOptions {
removeInfected?: boolean;
debugMode?: boolean;
clamdscan?: {
host?: string;
port?: number;
timeout?: number;
localFallback?: boolean;
};
preference?: "clamdscan" | "clamscan";
}
export interface ClamScanInstance {
ping(): Promise<unknown>;
scanBuffer(buffer: Buffer): Promise<{ isInfected: boolean | null; viruses?: string[] }>;
scanStream(stream: NodeJS.ReadableStream): Promise<{ isInfected: boolean | null; viruses?: string[] }>;
}
export default class NodeClam {
init(options: ClamScanInitOptions): Promise<ClamScanInstance>;
}
}
@@ -0,0 +1,194 @@
import { describe, expect, it, vi } from "vitest";
import {
createStorageScanService,
type StorageQuarantineAdapter,
type StorageScanner,
} from "./index.js";
const fixedNow = new Date("2026-02-03T04:05:06.000Z");
function createService(overrides: {
scanner?: StorageScanner;
quarantine?: StorageQuarantineAdapter;
} = {}) {
return createStorageScanService({
scanner: overrides.scanner ?? {
scanObject: vi.fn().mockResolvedValue({ verdict: "clean", engine: "clamav-1.4" }),
},
quarantine: overrides.quarantine,
now: () => fixedNow,
});
}
describe("createStorageScanService", () => {
it("returns clean scan verdicts with scannedAt and invokes the scanner once", async () => {
const scanObject = vi.fn().mockResolvedValue({ verdict: "clean", engine: "clamav-1.4" });
const service = createService({ scanner: { scanObject } });
await expect(
service.scanObject({ bucket: "uploads", key: "avatars/user.png" }),
).resolves.toEqual({
verdict: "clean",
bucket: "uploads",
key: "avatars/user.png",
scannedAt: fixedNow,
engine: "clamav-1.4",
});
expect(scanObject).toHaveBeenCalledOnce();
expect(scanObject).toHaveBeenCalledWith({ bucket: "uploads", key: "avatars/user.png" });
});
it("normalizes infected scanner verdicts with signature and quarantine metadata", async () => {
const scanObject = vi.fn().mockResolvedValue({
verdict: "infected",
engine: "clamav-1.4",
signature: "Eicar-Test-Signature",
quarantineKey: "quarantine/uploads/avatar.png",
});
const quarantineObject = vi.fn().mockResolvedValue({
bucket: "quarantine",
key: "uploads/avatar.png",
quarantineKey: "quarantine/uploads/avatar.png",
action: "moved",
});
const service = createService({
scanner: { scanObject },
quarantine: { quarantineObject },
});
await expect(
service.scanObject({ bucket: "uploads", key: "avatar.png" }),
).resolves.toEqual({
verdict: "infected",
bucket: "uploads",
key: "avatar.png",
scannedAt: fixedNow,
engine: "clamav-1.4",
signature: "Eicar-Test-Signature",
quarantineKey: "quarantine/uploads/avatar.png",
quarantine: {
bucket: "quarantine",
key: "uploads/avatar.png",
quarantineKey: "quarantine/uploads/avatar.png",
action: "moved",
},
});
expect(scanObject).toHaveBeenCalledOnce();
expect(quarantineObject).toHaveBeenCalledWith({
bucket: "uploads",
key: "avatar.png",
quarantineKey: "quarantine/uploads/avatar.png",
signature: "Eicar-Test-Signature",
});
});
it("returns redacted scanner error verdicts without copying arbitrary thrown fields", async () => {
const scannerError = Object.assign(
new Error("scanner failed credential=secret-token body=malware password=hunter2"),
{
name: "ClamAvUnavailable",
accessKeyId: "access-key",
secretAccessKey: "secret-key",
body: "file-body-secret",
$metadata: { httpStatusCode: 503, requestId: "scan-req-1" },
},
);
const service = createService({
scanner: { scanObject: vi.fn().mockRejectedValue(scannerError) },
});
const result = await service.scanObject({ bucket: "uploads", key: "avatar.png" });
expect(result).toEqual({
verdict: "error",
bucket: "uploads",
key: "avatar.png",
scannedAt: fixedNow,
error: {
code: "scanner_failed",
message: "Storage scanner failed while scanning object.",
upstream: {
name: "ClamAvUnavailable",
message: "scanner failed credential=[redacted] body=[redacted] password=[redacted]",
status: 503,
requestId: "scan-req-1",
},
},
});
const serialized = JSON.stringify(result);
expect(serialized).not.toContain("secret-token");
expect(serialized).not.toContain("file-body-secret");
expect(serialized).not.toContain("secret-key");
expect(serialized).not.toContain("hunter2");
});
it("rejects invalid empty bucket or key before invoking the scanner", async () => {
const scanObject = vi.fn();
const service = createService({ scanner: { scanObject } });
await expect(service.scanObject({ bucket: "", key: "avatar.png" })).resolves.toMatchObject({
verdict: "error",
key: "avatar.png",
error: {
code: "invalid_target",
message: "Storage scan target bucket and key must be non-empty strings.",
},
});
await expect(service.scanObject({ bucket: "uploads", key: " " })).resolves.toMatchObject({
verdict: "error",
bucket: "uploads",
error: { code: "invalid_target" },
});
expect(scanObject).not.toHaveBeenCalled();
});
it("returns redacted quarantine failure diagnostics for infected objects", async () => {
const quarantineError = Object.assign(
new Error("copy failed authorization=BearerSecret body=infected-bytes"),
{
name: "QuarantineWriteFailed",
token: "BearerSecret",
responseBody: "infected-bytes",
$metadata: { httpStatusCode: 500, requestId: "quarantine-req-1" },
},
);
const service = createService({
scanner: {
scanObject: vi.fn().mockResolvedValue({
verdict: "infected",
signature: "Eicar-Test-Signature",
quarantineKey: "quarantine/avatar.png",
}),
},
quarantine: { quarantineObject: vi.fn().mockRejectedValue(quarantineError) },
});
const result = await service.scanObject({ bucket: "uploads", key: "avatar.png" });
expect(result).toEqual({
verdict: "error",
bucket: "uploads",
key: "avatar.png",
scannedAt: fixedNow,
error: {
code: "quarantine_failed",
message: "Storage quarantine failed for infected object.",
upstream: {
name: "QuarantineWriteFailed",
message: "copy failed authorization=[redacted] body=[redacted]",
status: 500,
requestId: "quarantine-req-1",
},
},
});
const serialized = JSON.stringify(result);
expect(serialized).not.toContain("BearerSecret");
expect(serialized).not.toContain("infected-bytes");
expect(serialized).not.toContain("responseBody");
});
});
@@ -0,0 +1,280 @@
export * from "./pre-upload-types.js";
export { createMagicBytesScanAdapter, type MagicBytesScanAdapterOptions } from "./magic-bytes-adapter.js";
export { DEFAULT_ALLOW_LIST, resolveAllowList } from "./allow-list.js";
export {
createClamAVStorageScanner,
ClamAVUnreachableError,
isClamAVUnreachableError,
type ClamAVScannerConfig,
type ClamScanClient,
type ClamScanResult,
} from "./clamav-scanner.js";
export { createS3StorageQuarantineAdapter, type S3QuarantineConfig } from "./s3-quarantine.js";
export type ScanVerdict = "clean" | "infected" | "error";
export interface StorageScanTarget {
bucket: string;
key: string;
requestId?: string;
metadata?: Record<string, unknown>;
}
export interface StorageScannerInput {
bucket: string;
key: string;
}
export type StorageScannerResult =
| {
verdict: "clean";
engine?: string;
}
| {
verdict: "infected";
signature: string;
engine?: string;
quarantineKey?: string;
};
export interface StorageScanner {
scanObject(target: StorageScannerInput): Promise<StorageScannerResult> | StorageScannerResult;
}
export interface StorageQuarantineInput {
bucket: string;
key: string;
quarantineKey?: string;
signature: string;
}
export interface StorageQuarantineResult {
bucket?: string;
key?: string;
quarantineKey?: string;
action?: "copied" | "moved" | "tagged" | "skipped";
}
export interface StorageQuarantineAdapter {
quarantineObject(input: StorageQuarantineInput): Promise<StorageQuarantineResult> | StorageQuarantineResult;
}
export interface StorageScanDiagnostic {
code: StorageScanErrorCode;
message: string;
upstream?: {
name?: string;
message?: string;
status?: number;
requestId?: string;
};
}
export type StorageScanErrorCode =
| "invalid_target"
| "scanner_failed"
| "quarantine_failed";
export type StorageScanResult =
| {
verdict: "clean";
bucket: string;
key: string;
scannedAt: Date;
engine?: string;
}
| {
verdict: "infected";
bucket: string;
key: string;
scannedAt: Date;
engine?: string;
signature: string;
quarantineKey?: string;
quarantine?: StorageQuarantineResult;
}
| {
verdict: "error";
bucket?: string;
key?: string;
scannedAt: Date;
error: StorageScanDiagnostic;
};
export interface StorageScanService {
scanObject(target: StorageScanTarget): Promise<StorageScanResult>;
}
export interface CreateStorageScanServiceInput {
scanner: StorageScanner;
quarantine?: StorageQuarantineAdapter;
now?: () => Date;
}
export class StorageScanError extends Error {
readonly code: StorageScanErrorCode;
readonly details: StorageScanDiagnostic;
override readonly cause?: unknown;
constructor(
code: StorageScanErrorCode,
message: string,
details: StorageScanDiagnostic,
options: { cause?: unknown } = {},
) {
super(message);
this.name = "StorageScanError";
this.code = code;
this.details = details;
this.cause = options.cause;
}
}
export function createStorageScanService({
scanner,
quarantine,
now = () => new Date(),
}: CreateStorageScanServiceInput): StorageScanService {
return {
async scanObject(target) {
const scannedAt = now();
const normalizedTarget = normalizeTarget(target);
if (!normalizedTarget) {
return {
verdict: "error",
bucket: isPresent(target.bucket) ? target.bucket : undefined,
key: isPresent(target.key) ? target.key : undefined,
scannedAt,
error: createDiagnostic(
"invalid_target",
"Storage scan target bucket and key must be non-empty strings.",
),
};
}
let scanResult: StorageScannerResult;
try {
scanResult = await scanner.scanObject(normalizedTarget);
} catch (cause) {
return {
verdict: "error",
bucket: normalizedTarget.bucket,
key: normalizedTarget.key,
scannedAt,
error: createDiagnostic(
"scanner_failed",
"Storage scanner failed while scanning object.",
cause,
),
};
}
if (scanResult.verdict === "clean") {
return {
verdict: "clean",
bucket: normalizedTarget.bucket,
key: normalizedTarget.key,
scannedAt,
engine: scanResult.engine,
};
}
const quarantineKey = scanResult.quarantineKey;
let quarantineResult: StorageQuarantineResult | undefined;
if (quarantine) {
try {
quarantineResult = await quarantine.quarantineObject({
bucket: normalizedTarget.bucket,
key: normalizedTarget.key,
quarantineKey,
signature: scanResult.signature,
});
} catch (cause) {
return {
verdict: "error",
bucket: normalizedTarget.bucket,
key: normalizedTarget.key,
scannedAt,
error: createDiagnostic(
"quarantine_failed",
"Storage quarantine failed for infected object.",
cause,
),
};
}
}
return {
verdict: "infected",
bucket: normalizedTarget.bucket,
key: normalizedTarget.key,
scannedAt,
engine: scanResult.engine,
signature: scanResult.signature,
quarantineKey: quarantineResult?.quarantineKey ?? quarantineKey,
quarantine: quarantineResult,
};
},
};
}
function normalizeTarget(target: StorageScanTarget): StorageScannerInput | null {
if (!isPresent(target.bucket) || !isPresent(target.key)) {
return null;
}
return {
bucket: target.bucket.trim(),
key: target.key.trim(),
};
}
function createDiagnostic(
code: StorageScanErrorCode,
message: string,
cause?: unknown,
): StorageScanDiagnostic {
const upstream = extractRedactedUpstreamDetails(cause);
return {
code,
message,
...(upstream ? { upstream } : {}),
};
}
function extractRedactedUpstreamDetails(
cause: unknown,
): StorageScanDiagnostic["upstream"] {
if (!isRecord(cause)) {
return undefined;
}
const metadata = isRecord(cause.$metadata) ? cause.$metadata : undefined;
const status = typeof metadata?.httpStatusCode === "number" ? metadata.httpStatusCode : undefined;
const requestId = typeof metadata?.requestId === "string" ? metadata.requestId : undefined;
const message = typeof cause.message === "string" ? redactSecretLikeText(cause.message) : undefined;
return {
name: typeof cause.name === "string" ? cause.name : undefined,
message,
status,
requestId,
};
}
function redactSecretLikeText(message: string): string {
return message
.replace(/(access[_-]?key(?:id)?|secret[_-]?access[_-]?key|session[_-]?token|credential|authorization|token|password)(\s*[=:]\s*)\S+/gi, "$1$2[redacted]")
.replace(/(body)(\s*[=:]\s*)\S+/gi, "$1$2[redacted]");
}
function isPresent(value: unknown): value is string {
return typeof value === "string" && value.trim().length > 0;
}
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === "object" && value !== null;
}
@@ -0,0 +1,131 @@
import { fileTypeFromBuffer } from "file-type";
import { DEFAULT_ALLOW_LIST } from "./allow-list.js";
import type { PreUploadAllowList, PreUploadScanAdapter, PreUploadScanInput, PreUploadScanResult } from "./pre-upload-types.js";
// Reject control characters (\x00 null, \x01-\x1f, \x7f DEL) and path-traversal
// sequences (../ or ..\\) which would let an attacker escape the bucket prefix.
// eslint-disable-next-line no-control-regex
const FILENAME_BAD_PATTERN = /[\x00-\x1f\x7f]|\.\.[\\/]/;
const FILENAME_MAX_LENGTH = 255;
const SVG_SIGNATURE = /^<\?xml[\s\S]*?<svg\b|^<svg\b/i;
const TEXT_PLAIN_FALLBACK_MIMES = new Set(["text/plain", "text/csv"]);
export interface MagicBytesScanAdapterOptions {
/**
* Per-context MIME allow-list. Defaults to DEFAULT_ALLOW_LIST.
*/
allowList?: PreUploadAllowList;
/**
* Env-style toggle. When false, scan() returns `{ status: "skipped",
* reason: "scanner_disabled" }`. Intended as a Notfall-Bypass — never
* default to false.
*/
enabled?: boolean;
}
/**
* Synchronous pre-upload scanner. Uses file-type's magic-bytes signature
* database to derive the actual MIME type from the leading bytes of the buffer
* and validates it against (a) the client-declared MIME type and (b) the
* per-context allow-list.
*
* Defense-in-depth: the adapter does NOT log the buffer contents. Only the
* filename, sizes, and detected/declared MIME types are surfaced via the
* `detail` field so the caller can decide what to write to the audit log.
*/
export function createMagicBytesScanAdapter(options: MagicBytesScanAdapterOptions = {}): PreUploadScanAdapter {
const allowList = options.allowList ?? DEFAULT_ALLOW_LIST;
const enabled = options.enabled !== false;
return {
async scan(input: PreUploadScanInput): Promise<PreUploadScanResult> {
if (!enabled) {
return { status: "skipped", reason: "scanner_disabled" };
}
const filenameVerdict = validateFilename(input.filename);
if (filenameVerdict) return filenameVerdict;
if (!input.buffer || input.buffer.byteLength === 0) {
return { status: "rejected", reason: "empty", detail: "buffer was empty" };
}
const declared = input.declaredMimeType.trim().toLowerCase();
const contextAllowList = allowList[input.context] ?? [];
const detected = await detectMimeType(input.buffer);
// SVG-special-case: file-type reports SVG (which is just XML) as
// application/xml. Promote it to image/svg+xml only when the declared
// type asks for SVG, the content looks like SVG, and the context
// allow-list permits it. Otherwise XML stays XML and falls through
// to the normal mismatch path below.
if (detected === "application/xml" && declared === "image/svg+xml" && contextAllowList.includes("image/svg+xml") && looksLikeSvg(input.buffer)) {
return { status: "clean", detectedMimeType: "image/svg+xml" };
}
if (!detected) {
// file-type returns undefined for plain text / csv and a handful of
// long-tail formats. Allow it through only when the declared MIME is
// in our text fallback set AND the allow-list permits it.
if (TEXT_PLAIN_FALLBACK_MIMES.has(declared) && contextAllowList.includes(declared)) {
return { status: "clean" };
}
return {
status: "rejected",
reason: "mime_undetectable",
detail: `unable to detect MIME for declared="${declared}"`,
};
}
if (detected !== declared) {
return {
status: "rejected",
reason: "mime_mismatch",
detectedMimeType: detected,
detail: `declared="${declared}", detected="${detected}"`,
};
}
if (!contextAllowList.includes(detected)) {
return {
status: "rejected",
reason: "mime_not_allowed",
detectedMimeType: detected,
detail: `context="${input.context}" does not permit "${detected}"`,
};
}
return { status: "clean", detectedMimeType: detected };
},
};
}
async function detectMimeType(buffer: Uint8Array): Promise<string | undefined> {
const head = buffer.byteLength > 4100 ? buffer.subarray(0, 4100) : buffer;
try {
const result = await fileTypeFromBuffer(head);
return result?.mime;
} catch {
return undefined;
}
}
function validateFilename(filename: string): PreUploadScanResult | undefined {
if (typeof filename !== "string" || filename.length === 0) {
return { status: "rejected", reason: "filename_invalid", detail: "filename was empty" };
}
if (filename.length > FILENAME_MAX_LENGTH) {
return { status: "rejected", reason: "filename_invalid", detail: `filename exceeded ${FILENAME_MAX_LENGTH} chars` };
}
if (FILENAME_BAD_PATTERN.test(filename)) {
return { status: "rejected", reason: "filename_invalid", detail: "filename contained control chars or path traversal" };
}
return undefined;
}
function looksLikeSvg(buffer: Uint8Array): boolean {
const head = new TextDecoder("utf-8", { fatal: false }).decode(buffer.subarray(0, 512)).trimStart();
return SVG_SIGNATURE.test(head);
}
@@ -0,0 +1,53 @@
// Pre-upload content-scan types. Distinct from the post-upload
// StorageScanner / StorageQuarantineAdapter pipeline in index.ts —
// those run after an object is already in the bucket. The types
// here run synchronously against an in-memory buffer before the
// commit, primarily to validate the declared MIME type against
// the actual magic-bytes signature (layer 1) and, in a follow-up,
// to hand the same buffer off to a content scanner like ClamAV
// (layer 2).
/** Logical upload contexts. Each one carries its own allow-list. */
export type ScanContext = "avatar" | "mediaLibrary" | "emailAttachment" | "formUpload" | "kbAsset";
export const SCAN_CONTEXTS: readonly ScanContext[] = ["avatar", "mediaLibrary", "emailAttachment", "formUpload", "kbAsset"] as const;
/** Verdict of a single pre-upload scan call. */
export type PreUploadScanStatus = "clean" | "rejected" | "skipped";
export type PreUploadScanReason =
| "empty"
| "mime_mismatch"
| "mime_not_allowed"
| "mime_undetectable"
| "filename_invalid"
| "scanner_disabled"
| "scanner_error";
export interface PreUploadScanInput {
/** The bytes about to be uploaded. Adapters MUST NOT log this content. */
buffer: Uint8Array;
/** The MIME type the client declared (Content-Type header or form metadata). */
declaredMimeType: string;
/** The original filename the client supplied. May be untrusted. */
filename: string;
/** Logical context that drives the allow-list. */
context: ScanContext;
}
export interface PreUploadScanResult {
status: PreUploadScanStatus;
/** Set on `rejected` / `skipped`. Concise enum, not a user-facing string. */
reason?: PreUploadScanReason;
/** MIME type the adapter detected from the buffer (e.g. by magic-bytes), if any. */
detectedMimeType?: string;
/** Adapter-level diagnostic detail. Safe to log and audit. */
detail?: string;
}
export interface PreUploadScanAdapter {
scan(input: PreUploadScanInput): Promise<PreUploadScanResult>;
}
/** Per-context allow-list configuration. Empty array = nothing accepted in that context. */
export type PreUploadAllowList = Record<ScanContext, readonly string[]>;
@@ -0,0 +1,100 @@
// @vitest-environment node
import { describe, expect, test, vi } from "vitest";
import { CopyObjectCommand, DeleteObjectCommand, S3Client as AwsS3Client } from "@aws-sdk/client-s3";
import { createS3StorageQuarantineAdapter } from "./s3-quarantine.js";
const baseConfig = {
region: "us-east-1",
accessKeyId: "ak",
secretAccessKey: "sk",
};
function buildFakeClient() {
return { send: vi.fn(async () => ({})) } as unknown as AwsS3Client;
}
describe("createS3StorageQuarantineAdapter", () => {
test("server-side copies into quarantine/<key> and deletes the source", async () => {
const client = buildFakeClient();
const adapter = createS3StorageQuarantineAdapter({ ...baseConfig, clientFactory: () => client });
const result = await adapter.quarantineObject({
bucket: "uploads",
key: "users/123/avatar.png",
signature: "Win.Test.EICAR_HDB-1",
});
expect(result.bucket).toBe("uploads");
expect(result.key).toBe("quarantine/users/123/avatar.png");
expect(result.quarantineKey).toBe("quarantine/users/123/avatar.png");
expect(result.action).toBe("moved");
const sendMock = vi.mocked(client.send);
expect(sendMock).toHaveBeenCalledTimes(2);
const copyCall = sendMock.mock.calls[0]?.[0];
expect(copyCall).toBeInstanceOf(CopyObjectCommand);
const copyInput = (copyCall as CopyObjectCommand).input;
expect(copyInput.Bucket).toBe("uploads");
expect(copyInput.Key).toBe("quarantine/users/123/avatar.png");
expect(copyInput.CopySource).toBe(`uploads/${encodeURIComponent("users/123/avatar.png")}`);
expect(copyInput.MetadataDirective).toBe("REPLACE");
expect(copyInput.Metadata?.["scan-signature"]).toBe("Win.Test.EICAR_HDB-1");
expect(copyInput.Metadata?.["scan-source-bucket"]).toBe("uploads");
expect(copyInput.Metadata?.["scan-source-key"]).toBe("users/123/avatar.png");
const deleteCall = sendMock.mock.calls[1]?.[0];
expect(deleteCall).toBeInstanceOf(DeleteObjectCommand);
const deleteInput = (deleteCall as DeleteObjectCommand).input;
expect(deleteInput.Bucket).toBe("uploads");
expect(deleteInput.Key).toBe("users/123/avatar.png");
});
test("uses an explicit quarantineKey when the input provides one", async () => {
const client = buildFakeClient();
const adapter = createS3StorageQuarantineAdapter({ ...baseConfig, clientFactory: () => client });
const result = await adapter.quarantineObject({
bucket: "uploads",
key: "foo",
quarantineKey: "isolated/bar",
signature: "sig",
});
expect(result.key).toBe("isolated/bar");
const copyCall = vi.mocked(client.send).mock.calls[0]?.[0] as CopyObjectCommand;
expect(copyCall.input.Key).toBe("isolated/bar");
});
test("targets a dedicated quarantineBucket when configured", async () => {
const client = buildFakeClient();
const adapter = createS3StorageQuarantineAdapter({ ...baseConfig, quarantineBucket: "infected", clientFactory: () => client });
const result = await adapter.quarantineObject({ bucket: "uploads", key: "a", signature: "sig" });
expect(result.bucket).toBe("infected");
const copyCall = vi.mocked(client.send).mock.calls[0]?.[0] as CopyObjectCommand;
expect(copyCall.input.Bucket).toBe("infected");
});
test("honours a custom buildQuarantineKey", async () => {
const client = buildFakeClient();
const adapter = createS3StorageQuarantineAdapter({
...baseConfig,
clientFactory: () => client,
buildQuarantineKey: (input) => `viral/${input.signature}/${input.key}`,
});
const result = await adapter.quarantineObject({ bucket: "uploads", key: "f.png", signature: "Foo.Bar-1" });
expect(result.key).toBe("viral/Foo.Bar-1/f.png");
});
test("caches the S3 client across calls", async () => {
const client = buildFakeClient();
const factory = vi.fn(() => client);
const adapter = createS3StorageQuarantineAdapter({ ...baseConfig, clientFactory: factory });
await adapter.quarantineObject({ bucket: "u", key: "a", signature: "s" });
await adapter.quarantineObject({ bucket: "u", key: "b", signature: "s" });
expect(factory).toHaveBeenCalledTimes(1);
});
test("surfaces SDK errors instead of swallowing them", async () => {
const client = { send: vi.fn(async () => { throw new Error("AccessDenied"); }) } as unknown as AwsS3Client;
const adapter = createS3StorageQuarantineAdapter({ ...baseConfig, clientFactory: () => client });
await expect(adapter.quarantineObject({ bucket: "u", key: "k", signature: "s" })).rejects.toThrow("AccessDenied");
});
});
@@ -0,0 +1,93 @@
// S3-backed implementation of the StorageQuarantineAdapter contract from
// ./index.ts. Server-side copies an infected object into a `quarantine/`
// prefix and deletes the original, so the file is gone from any public
// listing of the source key without ever round-tripping through the worker
// process memory.
import { CopyObjectCommand, DeleteObjectCommand, S3Client as AwsS3Client } from "@aws-sdk/client-s3";
import type { StorageQuarantineAdapter, StorageQuarantineInput, StorageQuarantineResult } from "./index.js";
export interface S3QuarantineConfig {
endpoint?: string;
region: string;
accessKeyId: string;
secretAccessKey: string;
sessionToken?: string;
forcePathStyle?: boolean;
/**
* Bucket the quarantined object lives in. Defaults to the same bucket as
* the source. Pass a dedicated quarantine bucket if your S3 ACL strategy
* keeps it isolated from public listing.
*/
quarantineBucket?: string;
/**
* Override the key derivation. Defaults to prefixing the source key with
* `quarantine/` so the bucket layout looks like quarantine/<originalKey>.
*/
buildQuarantineKey?: (input: StorageQuarantineInput) => string;
/**
* Test seam. Defaults to a real AwsS3Client constructed from the config.
*/
clientFactory?: () => AwsS3Client;
}
const DEFAULT_PREFIX = "quarantine/";
export function createS3StorageQuarantineAdapter(config: S3QuarantineConfig): StorageQuarantineAdapter {
const buildKey = config.buildQuarantineKey ?? defaultBuildQuarantineKey;
const clientFactory =
config.clientFactory ??
(() =>
new AwsS3Client({
endpoint: config.endpoint,
region: config.region,
forcePathStyle: config.forcePathStyle,
credentials: {
accessKeyId: config.accessKeyId,
secretAccessKey: config.secretAccessKey,
sessionToken: config.sessionToken,
},
}));
let client: AwsS3Client | undefined;
return {
async quarantineObject(input: StorageQuarantineInput): Promise<StorageQuarantineResult> {
const targetBucket = config.quarantineBucket ?? input.bucket;
const targetKey = buildKey(input);
if (!client) client = clientFactory();
await client.send(
new CopyObjectCommand({
Bucket: targetBucket,
Key: targetKey,
CopySource: `${input.bucket}/${encodeURIComponent(input.key)}`,
MetadataDirective: "REPLACE",
Metadata: {
"scan-signature": input.signature,
"scan-quarantined-at": new Date().toISOString(),
"scan-source-bucket": input.bucket,
"scan-source-key": input.key,
},
})
);
await client.send(
new DeleteObjectCommand({
Bucket: input.bucket,
Key: input.key,
})
);
return {
bucket: targetBucket,
key: targetKey,
quarantineKey: targetKey,
action: "moved",
};
},
};
}
function defaultBuildQuarantineKey(input: StorageQuarantineInput): string {
if (input.quarantineKey) return input.quarantineKey;
return `${DEFAULT_PREFIX}${input.key}`;
}
@@ -0,0 +1,196 @@
import { describe, expect, it, vi } from "vitest";
import { StorageAdapterError, createS3SignedUrlAdapter } from "../index.js";
const fixedNow = new Date("2026-01-01T00:00:00.000Z");
function createAdapter(overrides: Partial<Parameters<typeof createS3SignedUrlAdapter>[0]> = {}) {
return createS3SignedUrlAdapter({
bucket: "uploads",
now: () => fixedNow,
uploadSigner: vi.fn().mockResolvedValue("https://s3.example.test/uploads/avatar.png?put"),
downloadSigner: vi.fn().mockResolvedValue("https://s3.example.test/uploads/avatar.png?get"),
...overrides,
});
}
describe("createS3SignedUrlAdapter", () => {
it("creates signed PUT output and propagates signer metadata and headers", async () => {
const uploadSigner = vi.fn().mockResolvedValue("https://signed.example.test/upload");
const adapter = createAdapter({ uploadSigner });
await expect(
adapter.createSignedUploadUrl({
key: "avatars/user.png",
expiresInSeconds: 300,
contentType: "image/png",
contentLength: 1234,
checksumSha256: "sha256-checksum",
metadata: { tenant: "acme" },
headers: { "x-amz-acl": "private" },
}),
).resolves.toEqual({
bucket: "uploads",
key: "avatars/user.png",
method: "PUT",
url: "https://signed.example.test/upload",
expiresAt: new Date("2026-01-01T00:05:00.000Z"),
expiresInSeconds: 300,
headers: {
"x-amz-acl": "private",
"content-type": "image/png",
"content-length": "1234",
"x-amz-checksum-sha256": "sha256-checksum",
},
metadata: { tenant: "acme" },
});
expect(uploadSigner).toHaveBeenCalledWith({
bucket: "uploads",
key: "avatars/user.png",
expiresInSeconds: 300,
contentType: "image/png",
contentLength: 1234,
checksumSha256: "sha256-checksum",
metadata: { tenant: "acme" },
headers: { "x-amz-acl": "private" },
});
});
it("creates signed GET output and propagates response options", async () => {
const downloadSigner = vi.fn().mockResolvedValue("https://signed.example.test/download");
const adapter = createAdapter({ downloadSigner });
await expect(
adapter.createSignedDownloadUrl({
key: "avatars/user.png",
expiresInSeconds: 60,
responseContentType: "image/png",
responseContentDisposition: "inline",
headers: { "x-custom": "value" },
}),
).resolves.toEqual({
bucket: "uploads",
key: "avatars/user.png",
method: "GET",
url: "https://signed.example.test/download",
expiresAt: new Date("2026-01-01T00:01:00.000Z"),
expiresInSeconds: 60,
headers: { "x-custom": "value" },
});
expect(downloadSigner).toHaveBeenCalledWith({
bucket: "uploads",
key: "avatars/user.png",
expiresInSeconds: 60,
responseContentType: "image/png",
responseContentDisposition: "inline",
headers: { "x-custom": "value" },
});
});
it("rejects invalid object keys before invoking signers", async () => {
const uploadSigner = vi.fn();
const adapter = createAdapter({ uploadSigner });
await expect(
adapter.createSignedUploadUrl({ key: "", expiresInSeconds: 60 }),
).rejects.toMatchObject({
name: "StorageAdapterError",
code: "invalid_key",
details: {
operation: "createSignedUploadUrl",
bucket: "uploads",
},
});
await expect(
adapter.createSignedUploadUrl({ key: "/absolute/path.png", expiresInSeconds: 60 }),
).rejects.toMatchObject({ code: "invalid_key" });
await expect(
adapter.createSignedUploadUrl({ key: "../escape.txt", expiresInSeconds: 60 }),
).rejects.toMatchObject({ code: "invalid_key" });
expect(uploadSigner).not.toHaveBeenCalled();
});
it("rejects non-positive and out-of-range expiry seconds", async () => {
const downloadSigner = vi.fn();
const adapter = createAdapter({ downloadSigner, maxExpiresInSeconds: 600 });
await expect(
adapter.createSignedDownloadUrl({ key: "avatar.png", expiresInSeconds: 0 }),
).rejects.toMatchObject({ code: "invalid_expiry" });
await expect(
adapter.createSignedDownloadUrl({ key: "avatar.png", expiresInSeconds: 601 }),
).rejects.toMatchObject({ code: "invalid_expiry" });
expect(downloadSigner).not.toHaveBeenCalled();
});
it("wraps signer rejections with redacted upstream diagnostics", async () => {
const signerError = Object.assign(
new Error("credential=AKIA_SECRET body={\"password\":\"secret\"}"),
{
name: "SignatureDoesNotMatch",
$metadata: { httpStatusCode: 403, requestId: "req-123" },
accessKeyId: "AKIA_SECRET",
secretAccessKey: "secret-key",
body: "request-body",
},
);
const adapter = createAdapter({ uploadSigner: vi.fn().mockRejectedValue(signerError) });
try {
await adapter.createSignedUploadUrl({ key: "avatar.png", expiresInSeconds: 60 });
throw new Error("expected signed URL creation to fail");
} catch (error) {
expect(error).toBeInstanceOf(StorageAdapterError);
const adapterError = error as StorageAdapterError;
expect(adapterError.code).toBe("signed_upload_failed");
expect(adapterError.details).toEqual({
operation: "createSignedUploadUrl",
bucket: "uploads",
key: "avatar.png",
upstream: {
name: "SignatureDoesNotMatch",
message: "credential=[redacted] body=[redacted]",
status: 403,
requestId: "req-123",
},
});
const serialized = JSON.stringify(adapterError.details);
expect(serialized).not.toContain("AKIA_SECRET");
expect(serialized).not.toContain("secret-key");
expect(serialized).not.toContain("request-body");
expect(serialized).not.toContain("password");
}
});
it("wraps signed download signer failures with bucket, key, status, and request id", async () => {
const signerError = Object.assign(new Error("authorization=BearerToken"), {
name: "SignerUnavailable",
$metadata: { httpStatusCode: 503, requestId: "req-503" },
});
const adapter = createAdapter({ downloadSigner: vi.fn().mockRejectedValue(signerError) });
await expect(
adapter.createSignedDownloadUrl({ key: "avatar.png", expiresInSeconds: 60 }),
).rejects.toMatchObject({
code: "signed_download_failed",
details: {
operation: "createSignedDownloadUrl",
bucket: "uploads",
key: "avatar.png",
upstream: {
name: "SignerUnavailable",
message: "authorization=[redacted]",
status: 503,
requestId: "req-503",
},
},
});
});
});
@@ -0,0 +1,271 @@
import { StorageAdapterError, type StorageAdapterErrorDetails } from "../index.js";
export * from "./sigv4.js";
export type SignedUrlOperation = "putObject" | "getObject";
export interface SignedUrlCommonInput {
key: string;
expiresInSeconds: number;
}
export interface CreateSignedUploadUrlInput extends SignedUrlCommonInput {
contentType?: string;
contentLength?: number;
checksumSha256?: string;
metadata?: Record<string, string>;
headers?: Record<string, string>;
}
export interface CreateSignedDownloadUrlInput extends SignedUrlCommonInput {
responseContentType?: string;
responseContentDisposition?: string;
headers?: Record<string, string>;
}
export interface SignedUploadUrlResult {
bucket: string;
key: string;
method: "PUT";
url: string;
expiresAt: Date;
expiresInSeconds: number;
headers: Record<string, string>;
metadata: Record<string, string>;
}
export interface SignedDownloadUrlResult {
bucket: string;
key: string;
method: "GET";
url: string;
expiresAt: Date;
expiresInSeconds: number;
headers: Record<string, string>;
}
export interface SignedUploadSignerInput {
bucket: string;
key: string;
expiresInSeconds: number;
contentType?: string;
contentLength?: number;
checksumSha256?: string;
metadata: Record<string, string>;
headers: Record<string, string>;
}
export interface SignedDownloadSignerInput {
bucket: string;
key: string;
expiresInSeconds: number;
responseContentType?: string;
responseContentDisposition?: string;
headers: Record<string, string>;
}
export type SignedUploadSigner = (input: SignedUploadSignerInput) => Promise<string> | string;
export type SignedDownloadSigner = (input: SignedDownloadSignerInput) => Promise<string> | string;
export interface S3SignedUrlAdapterConfig {
bucket: string;
uploadSigner: SignedUploadSigner;
downloadSigner: SignedDownloadSigner;
now?: () => Date;
minExpiresInSeconds?: number;
maxExpiresInSeconds?: number;
}
export interface SignedUrlAdapter {
createSignedUploadUrl(input: CreateSignedUploadUrlInput): Promise<SignedUploadUrlResult>;
createSignedDownloadUrl(input: CreateSignedDownloadUrlInput): Promise<SignedDownloadUrlResult>;
}
export const DEFAULT_MIN_SIGNED_URL_EXPIRY_SECONDS = 1;
export const DEFAULT_MAX_SIGNED_URL_EXPIRY_SECONDS = 60 * 60;
export function createS3SignedUrlAdapter(config: S3SignedUrlAdapterConfig): SignedUrlAdapter {
return {
async createSignedUploadUrl(input) {
const normalized = normalizeSignedInput(input, config, "createSignedUploadUrl");
const metadata = normalizeRecord(input.metadata);
const headers = normalizeRecord(input.headers);
const signerInput: SignedUploadSignerInput = {
bucket: config.bucket,
key: normalized.key,
expiresInSeconds: normalized.expiresInSeconds,
contentType: input.contentType,
contentLength: input.contentLength,
checksumSha256: input.checksumSha256,
metadata,
headers,
};
try {
const url = await config.uploadSigner(signerInput);
return {
bucket: config.bucket,
key: normalized.key,
method: "PUT",
url,
expiresAt: normalized.expiresAt,
expiresInSeconds: normalized.expiresInSeconds,
headers: buildUploadHeaders(input, headers),
metadata,
};
} catch (cause) {
throw signedUrlError("signed_upload_failed", "Failed to create signed upload URL.", {
operation: "createSignedUploadUrl",
bucket: config.bucket,
key: normalized.key,
upstream: extractRedactedUpstreamDetails(cause),
}, cause);
}
},
async createSignedDownloadUrl(input) {
const normalized = normalizeSignedInput(input, config, "createSignedDownloadUrl");
const headers = normalizeRecord(input.headers);
const signerInput: SignedDownloadSignerInput = {
bucket: config.bucket,
key: normalized.key,
expiresInSeconds: normalized.expiresInSeconds,
responseContentType: input.responseContentType,
responseContentDisposition: input.responseContentDisposition,
headers,
};
try {
const url = await config.downloadSigner(signerInput);
return {
bucket: config.bucket,
key: normalized.key,
method: "GET",
url,
expiresAt: normalized.expiresAt,
expiresInSeconds: normalized.expiresInSeconds,
headers,
};
} catch (cause) {
throw signedUrlError("signed_download_failed", "Failed to create signed download URL.", {
operation: "createSignedDownloadUrl",
bucket: config.bucket,
key: normalized.key,
upstream: extractRedactedUpstreamDetails(cause),
}, cause);
}
},
};
}
function normalizeSignedInput(
input: SignedUrlCommonInput,
config: S3SignedUrlAdapterConfig,
operation: string,
): { key: string; expiresInSeconds: number; expiresAt: Date } {
if (!isPresent(config.bucket)) {
throw signedUrlError("config_missing", "Missing signed URL storage configuration: bucket", {
operation,
missingFields: ["bucket"],
});
}
const key = normalizeKey(input.key, config.bucket, operation);
const expiresInSeconds = normalizeExpirySeconds(input.expiresInSeconds, config, key, operation);
const now = config.now?.() ?? new Date();
const expiresAt = new Date(now.getTime() + expiresInSeconds * 1000);
return { key, expiresInSeconds, expiresAt };
}
function normalizeKey(key: string, bucket: string, operation: string): string {
if (!isPresent(key) || key.startsWith("/") || key.includes("..")) {
throw signedUrlError("invalid_key", "Signed URL object key must be a non-empty relative key.", {
operation,
bucket,
key: isPresent(key) ? key : undefined,
});
}
return key;
}
function normalizeExpirySeconds(
expiresInSeconds: number,
config: S3SignedUrlAdapterConfig,
key: string,
operation: string,
): number {
const min = config.minExpiresInSeconds ?? DEFAULT_MIN_SIGNED_URL_EXPIRY_SECONDS;
const max = config.maxExpiresInSeconds ?? DEFAULT_MAX_SIGNED_URL_EXPIRY_SECONDS;
if (!Number.isInteger(expiresInSeconds) || expiresInSeconds < min || expiresInSeconds > max) {
throw signedUrlError("invalid_expiry", `Signed URL expiry must be an integer between ${min} and ${max} seconds.`, {
operation,
bucket: config.bucket,
key,
});
}
return expiresInSeconds;
}
function buildUploadHeaders(
input: CreateSignedUploadUrlInput,
headers: Record<string, string>,
): Record<string, string> {
return {
...headers,
...(input.contentType ? { "content-type": input.contentType } : {}),
...(typeof input.contentLength === "number" ? { "content-length": String(input.contentLength) } : {}),
...(input.checksumSha256 ? { "x-amz-checksum-sha256": input.checksumSha256 } : {}),
};
}
function normalizeRecord(record: Record<string, string> | undefined): Record<string, string> {
if (!record) {
return {};
}
return Object.fromEntries(Object.entries(record).filter(([key]) => isPresent(key)));
}
function signedUrlError(
code: StorageAdapterError["code"],
message: string,
details: StorageAdapterErrorDetails,
cause?: unknown,
): StorageAdapterError {
return new StorageAdapterError(code, message, details, cause === undefined ? {} : { cause });
}
function extractRedactedUpstreamDetails(cause: unknown): StorageAdapterErrorDetails["upstream"] {
if (!isRecord(cause)) {
return undefined;
}
const metadata = isRecord(cause.$metadata) ? cause.$metadata : undefined;
const status = typeof metadata?.httpStatusCode === "number" ? metadata.httpStatusCode : undefined;
const requestId = typeof metadata?.requestId === "string" ? metadata.requestId : undefined;
return {
name: typeof cause.name === "string" ? cause.name : undefined,
message: typeof cause.message === "string" ? redactSecretLikeText(cause.message) : undefined,
status,
requestId,
};
}
function redactSecretLikeText(message: string): string {
return message
.replace(/(access[_-]?key(?:id)?|secret[_-]?access[_-]?key|session[_-]?token|credential|authorization)(\s*[=:]\s*)\S+/gi, "$1$2[redacted]")
.replace(/(body)(\s*[=:]\s*)\S+/gi, "$1$2[redacted]");
}
function isPresent(value: unknown): value is string {
return typeof value === "string" && value.trim().length > 0;
}
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === "object" && value !== null;
}
@@ -0,0 +1,129 @@
// Shared SigV4 presigned-GET signer for S3-compatible storage. Used by the
// auth-proxy media route (AK-P4a §6, web) and available to the API helper. Pure
// node:crypto SigV4 (query-string presign) so no @aws-sdk/s3-request-presigner
// dependency is needed. Returns a SignedDownloadSigner for createS3SignedUrlAdapter.
import { createHash, createHmac } from "node:crypto";
import { StorageAdapterError } from "../index.js";
import type { SignedDownloadSigner, SignedDownloadSignerInput } from "./index.js";
export interface SigV4SignerConfig {
endpoint: string;
region: string;
bucket: string;
accessKeyId: string;
secretAccessKey: string;
sessionToken?: string;
forcePathStyle?: boolean;
}
const signingKeyCache = new Map<string, Buffer>();
/** Build a SignedDownloadSigner that produces presigned GET URLs via SigV4. */
export function createSigV4DownloadSigner(config: SigV4SignerConfig): SignedDownloadSigner {
return (input: SignedDownloadSignerInput): string => createS3SignedGetUrl(config, input);
}
function createS3SignedGetUrl(config: SigV4SignerConfig, input: SignedDownloadSignerInput): string {
const missingFields = ["endpoint", "region", "bucket", "accessKeyId", "secretAccessKey"].filter(
(field) => !isPresent(config[field as keyof SigV4SignerConfig]),
);
if (missingFields.length > 0) {
throw new StorageAdapterError("config_missing", `Missing signed URL storage configuration: ${missingFields.join(", ")}`, {
operation: "createSigV4DownloadSigner",
bucket: isPresent(config.bucket) ? config.bucket : undefined,
key: input.key,
missingFields,
});
}
const endpoint = new URL(config.endpoint);
const bucketSegment = encodeRfc3986(config.bucket);
const keyPath = input.key.split("/").map(encodeRfc3986).join("/");
const pathname = config.forcePathStyle
? `${trimTrailingSlash(endpoint.pathname)}/${bucketSegment}/${keyPath}`
: `${trimTrailingSlash(endpoint.pathname)}/${keyPath}`;
const host = config.forcePathStyle ? endpoint.host : `${config.bucket}.${endpoint.host}`;
const url = new URL(endpoint.toString());
url.host = host;
url.pathname = pathname;
url.search = "";
if (input.responseContentType) {
url.searchParams.set("response-content-type", input.responseContentType);
}
if (input.responseContentDisposition) {
url.searchParams.set("response-content-disposition", input.responseContentDisposition);
}
const now = new Date();
const amzDate = toAmzDate(now);
const dateStamp = amzDate.slice(0, 8);
const credentialScope = `${dateStamp}/${config.region}/s3/aws4_request`;
const signedHeaders = "host";
url.searchParams.set("X-Amz-Algorithm", "AWS4-HMAC-SHA256");
url.searchParams.set("X-Amz-Credential", `${config.accessKeyId}/${credentialScope}`);
url.searchParams.set("X-Amz-Date", amzDate);
url.searchParams.set("X-Amz-Expires", String(input.expiresInSeconds));
url.searchParams.set("X-Amz-SignedHeaders", signedHeaders);
if (config.sessionToken) {
url.searchParams.set("X-Amz-Security-Token", config.sessionToken);
}
const canonicalQuery = canonicalizeSearchParams(url.searchParams);
const canonicalRequest = ["GET", url.pathname, canonicalQuery, `host:${host}\n`, signedHeaders, "UNSIGNED-PAYLOAD"].join("\n");
const stringToSign = ["AWS4-HMAC-SHA256", amzDate, credentialScope, sha256Hex(canonicalRequest)].join("\n");
const signature = hmacHex(getSigningKey(config.secretAccessKey, dateStamp, config.region), stringToSign);
url.searchParams.set("X-Amz-Signature", signature);
return url.toString();
}
function canonicalizeSearchParams(params: URLSearchParams): string {
return [...params.entries()]
.sort(([leftKey, leftValue], [rightKey, rightValue]) => leftKey.localeCompare(rightKey) || leftValue.localeCompare(rightValue))
.map(([key, value]) => `${encodeRfc3986(key)}=${encodeRfc3986(value)}`)
.join("&");
}
function getSigningKey(secretAccessKey: string, dateStamp: string, region: string): Buffer {
const secretFingerprint = createHash("sha256").update(secretAccessKey).digest("hex");
const cacheKey = `${secretFingerprint}:${region}:${dateStamp}`;
const cached = signingKeyCache.get(cacheKey);
if (cached) {
return cached;
}
const dateKey = hmacBuffer(`AWS4${secretAccessKey}`, dateStamp);
const regionKey = hmacBuffer(dateKey, region);
const serviceKey = hmacBuffer(regionKey, "s3");
const signingKey = hmacBuffer(serviceKey, "aws4_request");
signingKeyCache.set(cacheKey, signingKey);
return signingKey;
}
function hmacBuffer(key: string | Buffer, value: string): Buffer {
return createHmac("sha256", key).update(value).digest();
}
function hmacHex(key: string | Buffer, value: string): string {
return createHmac("sha256", key).update(value).digest("hex");
}
function sha256Hex(value: string): string {
return createHash("sha256").update(value).digest("hex");
}
function toAmzDate(date: Date): string {
return date.toISOString().replace(/[:-]|\.\d{3}/g, "");
}
function encodeRfc3986(value: string): string {
return encodeURIComponent(value).replace(/[!'()*]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`);
}
function trimTrailingSlash(pathname: string): string {
return pathname.replace(/\/+$/, "");
}
function isPresent(value: unknown): value is string {
return typeof value === "string" && value.trim().length > 0;
}