Reorganize repo structure and standards references
This commit is contained in:
1 parent
3cb93a81be
commit
be2054274d
5885 files changed
+2588
-195
No files matched your search
@@ -0,0 +1,24 @@
|
||||
{
|
||||
"name": "@toolctrl/storage",
|
||||
"version": "0.0.0",
|
||||
"private": true,
|
||||
"type": "module",
|
||||
"sideEffects": false,
|
||||
"exports": {
|
||||
".": "./src/index.ts"
|
||||
},
|
||||
"scripts": {
|
||||
"test": "vitest run src",
|
||||
"typecheck": "tsc -p tsconfig.json --noEmit"
|
||||
},
|
||||
"dependencies": {
|
||||
"@aws-sdk/client-s3": "^3.958.0",
|
||||
"clamscan": "^2.4.0",
|
||||
"file-type": "^22.0.1"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/node": "^25.6.0",
|
||||
"typescript": "^5.3.2",
|
||||
"vitest": "^3.2.4"
|
||||
}
|
||||
}
|
||||
@@ -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;
|
||||
}
|
||||
+128
@@ -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";
|
||||
}
|
||||
+27
@@ -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;
|
||||
}
|
||||
BIN
Binary file not shown.
+131
@@ -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);
|
||||
}
|
||||
+53
@@ -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[]>;
|
||||
+100
@@ -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;
|
||||
}
|
||||
@@ -0,0 +1,14 @@
|
||||
{
|
||||
"extends": "../../tsconfig.json",
|
||||
"compilerOptions": {
|
||||
"allowJs": false,
|
||||
"allowImportingTsExtensions": false,
|
||||
"lib": ["ES2022"],
|
||||
"module": "NodeNext",
|
||||
"moduleResolution": "NodeNext",
|
||||
"noEmit": true,
|
||||
"target": "ES2022",
|
||||
"types": ["node"]
|
||||
},
|
||||
"include": ["src/**/*.ts"]
|
||||
}
|
||||
Reference in new issue
Block a user