Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -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;
}