storage-explorer 0.1.0 → 1.1.0

package/src/server/s3/handlers.ts

@@ -0,0 +1,134 @@
+import {
+  GetObjectCommand,
+  ListBucketsCommand,
+  ListObjectsV2Command,
+  S3ServiceException,
+} from "@aws-sdk/client-s3";
+import { fail, ok } from "../http/response";
+import { createS3Client } from "./client";
+import { mapListBucketsResult, mapListObjectsResult, mapS3Error } from "./mappers";
+import { invalidProfileError, parseDownloadInput, parseListObjectsInput, parseProfileFromBody } from "./validate";
+
+async function parseJsonBody(req: Request): Promise<unknown> {
+  try {
+    return await req.json();
+  } catch {
+    return null;
+  }
+}
+
+export async function testConnectionHandler(req: Request): Promise<Response> {
+  const body = await parseJsonBody(req);
+  const profile = parseProfileFromBody(body);
+
+  if (!profile) {
+    return fail(400, invalidProfileError());
+  }
+
+  const client = createS3Client(profile);
+
+  try {
+    await client.send(new ListBucketsCommand({}));
+    return ok({
+      connected: true,
+      message: "Connection successful.",
+    });
+  } catch (err) {
+    if (
+      err instanceof S3ServiceException &&
+      (err.name === "AccessDenied" || err.name === "AccessDeniedException")
+    ) {
+      return ok({
+        connected: true,
+        limitedPermissions: true,
+        message:
+          "Connected, but this key cannot list buckets. You can still browse known buckets.",
+      });
+    }
+
+    return fail(400, mapS3Error(err));
+  }
+}
+
+export async function listBucketsHandler(req: Request): Promise<Response> {
+  const body = await parseJsonBody(req);
+  const profile = parseProfileFromBody(body);
+
+  if (!profile) {
+    return fail(400, invalidProfileError());
+  }
+
+  const client = createS3Client(profile);
+
+  try {
+    const result = await client.send(new ListBucketsCommand({}));
+    return ok(mapListBucketsResult(result));
+  } catch (err) {
+    return fail(400, mapS3Error(err));
+  }
+}
+
+export async function listObjectsHandler(req: Request): Promise<Response> {
+  const body = await parseJsonBody(req);
+  const parsed = parseListObjectsInput(body);
+
+  if (!parsed.ok) {
+    return fail(400, parsed.error);
+  }
+
+  const { profile, bucket, prefix, continuationToken, maxKeys } = parsed.data;
+  const client = createS3Client(profile);
+
+  try {
+    const result = await client.send(
+      new ListObjectsV2Command({
+        Bucket: bucket,
+        Prefix: prefix,
+        ContinuationToken: continuationToken,
+        Delimiter: "/",
+        MaxKeys: maxKeys,
+      }),
+    );
+
+    return ok(mapListObjectsResult(result, bucket, prefix));
+  } catch (err) {
+    return fail(400, mapS3Error(err));
+  }
+}
+
+export async function downloadObjectHandler(req: Request): Promise<Response> {
+  const body = await parseJsonBody(req);
+  const parsed = parseDownloadInput(body);
+
+  if (!parsed.ok) {
+    return fail(400, parsed.error);
+  }
+
+  const { profile, bucket, key } = parsed.data;
+  const client = createS3Client(profile);
+
+  try {
+    const result = await client.send(
+      new GetObjectCommand({
+        Bucket: bucket,
+        Key: key,
+      }),
+    );
+
+    if (!result.Body) {
+      return fail(404, { message: "Object body is empty.", code: "EmptyBody" });
+    }
+
+    const filename = key.split("/").filter(Boolean).pop() ?? key;
+
+    return new Response(result.Body.transformToWebStream(), {
+      headers: {
+        "Content-Type": result.ContentType || "application/octet-stream",
+        "Content-Disposition": `attachment; filename="${filename}"`,
+        ...(result.ContentLength != null ? { "Content-Length": String(result.ContentLength) } : {}),
+      },
+    });
+  } catch (err) {
+    return fail(400, mapS3Error(err));
+  }
+}

package/src/server/s3/mappers.ts

@@ -0,0 +1,73 @@
+import { S3ServiceException } from "@aws-sdk/client-s3";
+import type { ApiErrorPayload } from "../http/response";
+
+export function mapS3Error(err: unknown): ApiErrorPayload {
+  if (err instanceof S3ServiceException) {
+    return {
+      message: err.message || "S3 request failed.",
+      code: err.name,
+    };
+  }
+
+  if (err instanceof Error) {
+    return {
+      message: err.message,
+      code: "UnknownError",
+    };
+  }
+
+  return {
+    message: "Unexpected error while talking to S3.",
+    code: "UnknownError",
+  };
+}
+
+export function mapListBucketsResult(result: {
+  Buckets?: Array<{ Name?: string; CreationDate?: Date }>;
+}) {
+  return {
+    buckets: (result.Buckets ?? []).map(bucket => ({
+      name: bucket.Name ?? "",
+      creationDate: bucket.CreationDate?.toISOString() ?? null,
+    })),
+  };
+}
+
+export function mapListObjectsResult(
+  result: {
+    CommonPrefixes?: Array<{ Prefix?: string }>;
+    Contents?: Array<{
+      Key?: string;
+      Size?: number;
+      LastModified?: Date;
+      ETag?: string;
+      StorageClass?: string;
+    }>;
+    IsTruncated?: boolean;
+    NextContinuationToken?: string;
+  },
+  bucket: string,
+  prefix?: string,
+) {
+  const folders = (result.CommonPrefixes ?? [])
+    .map(entry => entry.Prefix)
+    .filter((value): value is string => Boolean(value));
+  const files = (result.Contents ?? [])
+    .filter(item => item.Key && item.Key !== prefix)
+    .map(item => ({
+      key: item.Key ?? "",
+      size: item.Size ?? 0,
+      lastModified: item.LastModified?.toISOString() ?? null,
+      eTag: item.ETag ?? null,
+      storageClass: item.StorageClass ?? null,
+    }));
+
+  return {
+    bucket,
+    prefix: prefix ?? "",
+    folders,
+    files,
+    isTruncated: Boolean(result.IsTruncated),
+    nextContinuationToken: result.NextContinuationToken ?? null,
+  };
+}

package/src/server/s3/types.ts

@@ -0,0 +1,21 @@
+export type S3ProfileInput = {
+  endpoint: string;
+  region: string;
+  accessKeyId: string;
+  secretAccessKey: string;
+  forcePathStyle: boolean;
+};
+
+export type ParsedListObjectsInput = {
+  profile: S3ProfileInput;
+  bucket: string;
+  prefix?: string;
+  continuationToken?: string;
+  maxKeys: number;
+};
+
+export type ParsedDownloadInput = {
+  profile: S3ProfileInput;
+  bucket: string;
+  key: string;
+};

package/src/server/s3/validate.ts

@@ -0,0 +1,140 @@
+import type { ApiErrorPayload } from "../http/response";
+import type { ParsedDownloadInput, ParsedListObjectsInput, S3ProfileInput } from "./types";
+
+function parseProfile(value: unknown): S3ProfileInput | null {
+  if (typeof value !== "object" || value === null) {
+    return null;
+  }
+
+  const record = value as Record<string, unknown>;
+  const endpoint = typeof record.endpoint === "string" ? record.endpoint.trim() : "";
+  const accessKeyId =
+    typeof record.accessKeyId === "string" ? record.accessKeyId.trim() : "";
+  const secretAccessKey =
+    typeof record.secretAccessKey === "string" ? record.secretAccessKey.trim() : "";
+
+  if (!endpoint || !accessKeyId || !secretAccessKey) {
+    return null;
+  }
+
+  const region =
+    typeof record.region === "string" && record.region.trim()
+      ? record.region.trim()
+      : "us-east-1";
+
+  return {
+    endpoint,
+    region,
+    accessKeyId,
+    secretAccessKey,
+    forcePathStyle: record.forcePathStyle !== false,
+  };
+}
+
+export function parseProfileFromBody(body: unknown): S3ProfileInput | null {
+  const profile = (body as { profile?: unknown } | null)?.profile;
+  return parseProfile(profile);
+}
+
+export function parseListObjectsInput(body: unknown):
+  | { ok: true; data: ParsedListObjectsInput }
+  | { ok: false; error: ApiErrorPayload } {
+  const record = body as
+    | {
+        profile?: unknown;
+        bucket?: unknown;
+        prefix?: unknown;
+        continuationToken?: unknown;
+        maxKeys?: unknown;
+      }
+    | null;
+
+  const profile = parseProfile(record?.profile);
+  if (!profile) {
+    return {
+      ok: false,
+      error: {
+        message: "Invalid profile. endpoint, accessKeyId, and secretAccessKey are required.",
+        code: "InvalidProfile",
+      },
+    };
+  }
+
+  const bucket = typeof record?.bucket === "string" ? record.bucket.trim() : "";
+  if (!bucket) {
+    return {
+      ok: false,
+      error: {
+        message: "Bucket is required.",
+        code: "MissingBucket",
+      },
+    };
+  }
+
+  const prefix =
+    typeof record?.prefix === "string" && record.prefix.length > 0 ? record.prefix : undefined;
+  const continuationToken =
+    typeof record?.continuationToken === "string" && record.continuationToken.length > 0
+      ? record.continuationToken
+      : undefined;
+  const maxKeysRaw = typeof record?.maxKeys === "number" ? record.maxKeys : Number.NaN;
+  const maxKeys =
+    Number.isFinite(maxKeysRaw) && maxKeysRaw >= 1
+      ? Math.min(Math.floor(maxKeysRaw), 1000)
+      : 200;
+
+  return {
+    ok: true,
+    data: {
+      profile,
+      bucket,
+      prefix,
+      continuationToken,
+      maxKeys,
+    },
+  };
+}
+
+export function parseDownloadInput(body: unknown):
+  | { ok: true; data: ParsedDownloadInput }
+  | { ok: false; error: ApiErrorPayload } {
+  const record = body as
+    | { profile?: unknown; bucket?: unknown; key?: unknown }
+    | null;
+
+  const profile = parseProfile(record?.profile);
+  if (!profile) {
+    return {
+      ok: false,
+      error: {
+        message: "Invalid profile. endpoint, accessKeyId, and secretAccessKey are required.",
+        code: "InvalidProfile",
+      },
+    };
+  }
+
+  const bucket = typeof record?.bucket === "string" ? record.bucket.trim() : "";
+  if (!bucket) {
+    return {
+      ok: false,
+      error: { message: "Bucket is required.", code: "MissingBucket" },
+    };
+  }
+
+  const key = typeof record?.key === "string" ? record.key.trim() : "";
+  if (!key) {
+    return {
+      ok: false,
+      error: { message: "Object key is required.", code: "MissingKey" },
+    };
+  }
+
+  return { ok: true, data: { profile, bucket, key } };
+}
+
+export function invalidProfileError(): ApiErrorPayload {
+  return {
+    message: "Invalid profile. endpoint, accessKeyId, and secretAccessKey are required.",
+    code: "InvalidProfile",
+  };
+}

package/src/shared/api/s3Api.ts

@@ -0,0 +1,86 @@
+import type {
+  BucketItem,
+  ObjectsPayload,
+  S3ConnectionProfile,
+  TestConnectionPayload,
+} from "../types/s3";
+
+type ApiEnvelope<T> = {
+  ok: true;
+  data: T;
+};
+
+type ApiErrorEnvelope = {
+  ok: false;
+  error?: {
+    message?: string;
+    code?: string;
+  };
+};
+
+async function postJson<T>(url: string, body: unknown): Promise<T> {
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(body),
+  });
+
+  const payload = (await response.json()) as ApiEnvelope<T> | ApiErrorEnvelope;
+
+  if (!response.ok || payload.ok === false) {
+    const message = payload.ok === false ? payload.error?.message : "Request failed.";
+    throw new Error(message || "Request failed.");
+  }
+
+  return payload.data;
+}
+
+export function testConnection(profile: S3ConnectionProfile): Promise<TestConnectionPayload> {
+  return postJson<TestConnectionPayload>("/api/s3/test-connection", { profile });
+}
+
+export function listBuckets(profile: S3ConnectionProfile): Promise<{ buckets: BucketItem[] }> {
+  return postJson<{ buckets: BucketItem[] }>("/api/s3/list-buckets", { profile });
+}
+
+export function listObjects(input: {
+  profile: S3ConnectionProfile;
+  bucket: string;
+  prefix?: string;
+  continuationToken?: string | null;
+  maxKeys?: number;
+}): Promise<ObjectsPayload> {
+  return postJson<ObjectsPayload>("/api/s3/list-objects", input);
+}
+
+export async function downloadObject(input: {
+  profile: S3ConnectionProfile;
+  bucket: string;
+  key: string;
+}): Promise<void> {
+  const response = await fetch("/api/s3/download-object", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(input),
+  });
+
+  if (!response.ok) {
+    const payload = (await response.json().catch(() => null)) as ApiErrorEnvelope | null;
+    const message = payload?.error?.message || "Download failed.";
+    throw new Error(message);
+  }
+
+  const disposition = response.headers.get("Content-Disposition");
+  const match = disposition?.match(/filename="(.+)"/);
+  const filename = match?.[1] ?? input.key.split("/").filter(Boolean).pop() ?? "download";
+
+  const blob = await response.blob();
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = filename;
+  a.click();
+  URL.revokeObjectURL(url);
+}

package/src/shared/hooks/useProfilesStorage.ts

@@ -0,0 +1,175 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+import type { SavedProfile } from "../types/s3";
+
+const PROFILES_KEY = "s3-explorer:profiles:v1";
+const LAST_PROFILE_KEY = "s3-explorer:last-profile:v1";
+const PROFILE_VIEW_KEY = "s3-explorer:profile-view:v1";
+
+export type ProfileViewState = {
+  bucket: string;
+  prefix: string;
+  manualBucketName: string;
+};
+
+const emptyView: ProfileViewState = {
+  bucket: "",
+  prefix: "",
+  manualBucketName: "",
+};
+
+function parseStoredProfiles(raw: string | null): SavedProfile[] {
+  if (!raw) {
+    return [];
+  }
+
+  try {
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) {
+      return [];
+    }
+
+    return parsed
+      .filter(item => typeof item === "object" && item !== null)
+      .map(item => {
+        const record = item as Record<string, unknown>;
+        return {
+          id: String(record.id ?? crypto.randomUUID()),
+          name: String(record.name ?? ""),
+          endpoint: String(record.endpoint ?? ""),
+          region: String(record.region ?? "us-east-1"),
+          accessKeyId: String(record.accessKeyId ?? ""),
+          secretAccessKey: String(record.secretAccessKey ?? ""),
+          forcePathStyle: record.forcePathStyle !== false,
+        };
+      })
+      .filter(profile => profile.endpoint && profile.accessKeyId && profile.secretAccessKey);
+  } catch {
+    return [];
+  }
+}
+
+function parseStoredViews(raw: string | null): Record<string, ProfileViewState> {
+  if (!raw) {
+    return {};
+  }
+
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null) {
+      return {};
+    }
+
+    const record = parsed as Record<string, unknown>;
+    const next: Record<string, ProfileViewState> = {};
+
+    for (const [profileId, value] of Object.entries(record)) {
+      if (typeof value !== "object" || value === null) {
+        continue;
+      }
+
+      const view = value as Record<string, unknown>;
+      next[profileId] = {
+        bucket: typeof view.bucket === "string" ? view.bucket : "",
+        prefix: typeof view.prefix === "string" ? view.prefix : "",
+        manualBucketName:
+          typeof view.manualBucketName === "string" ? view.manualBucketName : "",
+      };
+    }
+
+    return next;
+  } catch {
+    return {};
+  }
+}
+
+export function useProfilesStorage() {
+  const [profiles, setProfiles] = useState<SavedProfile[]>(() =>
+    parseStoredProfiles(localStorage.getItem(PROFILES_KEY)),
+  );
+  const [profileViews, setProfileViews] = useState<Record<string, ProfileViewState>>(() =>
+    parseStoredViews(localStorage.getItem(PROFILE_VIEW_KEY)),
+  );
+  const [selectedProfileId, setSelectedProfileId] = useState<string | null>(() => {
+    const loadedProfiles = parseStoredProfiles(localStorage.getItem(PROFILES_KEY));
+    const storedProfileId = localStorage.getItem(LAST_PROFILE_KEY);
+    const fallbackProfile = loadedProfiles[0]?.id ?? null;
+
+    return loadedProfiles.some(profile => profile.id === storedProfileId)
+      ? storedProfileId
+      : fallbackProfile;
+  });
+
+  useEffect(() => {
+    localStorage.setItem(PROFILES_KEY, JSON.stringify(profiles));
+  }, [profiles]);
+
+  useEffect(() => {
+    localStorage.setItem(PROFILE_VIEW_KEY, JSON.stringify(profileViews));
+  }, [profileViews]);
+
+  useEffect(() => {
+    if (selectedProfileId) {
+      localStorage.setItem(LAST_PROFILE_KEY, selectedProfileId);
+    } else {
+      localStorage.removeItem(LAST_PROFILE_KEY);
+    }
+  }, [selectedProfileId]);
+
+  const selectedProfile = useMemo(
+    () => profiles.find(profile => profile.id === selectedProfileId) ?? null,
+    [profiles, selectedProfileId],
+  );
+
+  const saveProfile = useCallback((profile: SavedProfile) => {
+    setProfiles(prev => {
+      const existing = prev.findIndex(entry => entry.id === profile.id);
+      if (existing === -1) {
+        return [profile, ...prev];
+      }
+
+      const next = [...prev];
+      next[existing] = profile;
+      return next;
+    });
+  }, []);
+
+  const deleteProfile = useCallback((profileId: string) => {
+    setProfiles(prev => prev.filter(profile => profile.id !== profileId));
+    setProfileViews(prev => {
+      const next = { ...prev };
+      delete next[profileId];
+      return next;
+    });
+
+    setSelectedProfileId(current => (current === profileId ? null : current));
+  }, []);
+
+  const updateProfileView = useCallback((profileId: string, patch: Partial<ProfileViewState>) => {
+    setProfileViews(prev => ({
+      ...prev,
+      [profileId]: {
+        ...(prev[profileId] ?? emptyView),
+        ...patch,
+      },
+    }));
+  }, []);
+
+  const getProfileView = useCallback((profileId: string | null): ProfileViewState => {
+    if (!profileId) {
+      return emptyView;
+    }
+
+    return profileViews[profileId] ?? emptyView;
+  }, [profileViews]);
+
+  return {
+    profiles,
+    selectedProfileId,
+    selectedProfile,
+    setSelectedProfileId,
+    saveProfile,
+    deleteProfile,
+    updateProfileView,
+    getProfileView,
+  };
+}

package/src/shared/types/s3.ts

@@ -0,0 +1,42 @@
+export type S3ConnectionProfile = {
+  endpoint: string;
+  region: string;
+  accessKeyId: string;
+  secretAccessKey: string;
+  forcePathStyle: boolean;
+};
+
+export type SavedProfile = S3ConnectionProfile & {
+  id: string;
+  name: string;
+};
+
+export type EditableProfile = Omit<SavedProfile, "id">;
+
+export type BucketItem = {
+  name: string;
+  creationDate: string | null;
+};
+
+export type ObjectFile = {
+  key: string;
+  size: number;
+  lastModified: string | null;
+  eTag: string | null;
+  storageClass: string | null;
+};
+
+export type ObjectsPayload = {
+  bucket: string;
+  prefix: string;
+  folders: string[];
+  files: ObjectFile[];
+  isTruncated: boolean;
+  nextContinuationToken: string | null;
+};
+
+export type TestConnectionPayload = {
+  connected: boolean;
+  limitedPermissions?: boolean;
+  message: string;
+};