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; headers?: Record; } export interface CreateSignedDownloadUrlInput extends SignedUrlCommonInput { responseContentType?: string; responseContentDisposition?: string; headers?: Record; } export interface SignedUploadUrlResult { bucket: string; key: string; method: "PUT"; url: string; expiresAt: Date; expiresInSeconds: number; headers: Record; metadata: Record; } export interface SignedDownloadUrlResult { bucket: string; key: string; method: "GET"; url: string; expiresAt: Date; expiresInSeconds: number; headers: Record; } export interface SignedUploadSignerInput { bucket: string; key: string; expiresInSeconds: number; contentType?: string; contentLength?: number; checksumSha256?: string; metadata: Record; headers: Record; } export interface SignedDownloadSignerInput { bucket: string; key: string; expiresInSeconds: number; responseContentType?: string; responseContentDisposition?: string; headers: Record; } export type SignedUploadSigner = (input: SignedUploadSignerInput) => Promise | string; export type SignedDownloadSigner = (input: SignedDownloadSignerInput) => Promise | string; export interface S3SignedUrlAdapterConfig { bucket: string; uploadSigner: SignedUploadSigner; downloadSigner: SignedDownloadSigner; now?: () => Date; minExpiresInSeconds?: number; maxExpiresInSeconds?: number; } export interface SignedUrlAdapter { createSignedUploadUrl(input: CreateSignedUploadUrlInput): Promise; createSignedDownloadUrl(input: CreateSignedDownloadUrlInput): Promise; } 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, ): Record { 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 | undefined): Record { 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 { return typeof value === "object" && value !== null; }