object-storage

Web (React+Vite)
  |
  | 1. POST /api/storage/uploads/request-url     (JSON metadata)
  | 2. PUT <presigned-url>                       (file bytes → GCS)
  | 3. GET /api/storage/public-objects/<path>    (serve public assets)
  | 4. GET /api/storage/objects/<path>           (serve object entities)
  |
  v
Express API Server
  ├── lib/objectStorage.ts       (GCS client wrapper, presigned URL generation)
  ├── lib/objectAcl.ts           (ACL policy framework)
  └── routes/storage.ts          (upload + serve endpoints, Zod-validated)
  |
  | @google-cloud/storage (Replit sidecar auth)
  v
Google Cloud Storage

const result = await setupObjectStorage();
console.log(result);
// { success: true, alreadySetUp: true/false, secretKeys: [...], bucketId: "..." }

pnpm --filter @workspace/api-spec run codegen

# Object storage service (GCS client wrapper, presigned URL generation)
mkdir -p artifacts/api-server/src/lib
cp .local/skills/object-storage/templates/api-server/src/lib/objectStorage.ts artifacts/api-server/src/lib/objectStorage.ts

# ACL framework (access control policies for objects)
cp .local/skills/object-storage/templates/api-server/src/lib/objectAcl.ts artifacts/api-server/src/lib/objectAcl.ts

# Storage routes (upload URL request + object serving)
mkdir -p artifacts/api-server/src/routes
cp .local/skills/object-storage/templates/api-server/src/routes/storage.ts artifacts/api-server/src/routes/storage.ts

pnpm --filter @workspace/api-server add @google-cloud/storage google-auth-library

import { Router, type IRouter } from "express";
import healthRouter from "./health";
import storageRouter from "./storage";

const router: IRouter = Router();

router.use(healthRouter);
router.use(storageRouter);

export default router;

mkdir -p lib/object-storage-web
cp -r .local/skills/object-storage/templates/lib/object-storage-web/* lib/object-storage-web/

"@workspace/object-storage-web": "workspace:*"

pnpm --filter @workspace/<web-app> add @uppy/aws-s3@^5.0.0 @uppy/core@^5.0.0 @uppy/dashboard@^5.0.0 @uppy/react@^5.0.0

{
  "pnpm": {
    "overrides": {
      "react": "$react",
      "react-dom": "$react-dom"
    }
  }
}

pnpm install

// root tsconfig.json – add to "references"
{ "path": "lib/object-storage-web" }

// artifacts/<web-app>/tsconfig.json – add to "references"
{ "path": "../../lib/object-storage-web" }

import { ObjectUploader } from "@workspace/object-storage-web";

<ObjectUploader
  onGetUploadParameters={async (file) => {
    const res = await fetch("/api/storage/uploads/request-url", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        name: file.name,
        size: file.size,
        contentType: file.type,
      }),
    });
    const { uploadURL } = await res.json();
    return {
      method: "PUT",
      url: uploadURL,
      headers: { "Content-Type": file.type },
    };
  }}
  onComplete={(result) => console.log("Upload complete:", result)}
>
  Upload Files
</ObjectUploader>

import { useUpload } from "@workspace/object-storage-web";

function MyUploader() {
  const { uploadFile, isUploading, progress } = useUpload({
    onSuccess: (response) => console.log("Uploaded:", response.objectPath),
  });

   This forces all packages to use the project's React version. Run `pnpm install` after adding the overrides.

1. **Define endpoints in the OpenAPI spec.** Add the object storage endpoints to `lib/api-spec/openapi.yaml`:

   - `POST /api/storage/uploads/request-url` -- request a presigned upload URL (accepts JSON metadata: name, size, contentType; returns uploadURL and objectPath)
   - `GET /api/storage/objects/{objectPath}` -- serve uploaded objects

   Then run codegen to generate typed route stubs and React Query hooks:

2. **Mount storage routes** on your Express app. Use `createObjectStorageRouter()` to register the route handlers:

   This registers `/api/storage/uploads/request-url` and `/api/storage/objects/*`.

3. **Install server dependencies:**

   Run this in the API server artifact directory.

4. **Use generated hooks on the frontend.** After codegen, use the generated React Query hooks from `@workspace/api-client-react` for requesting presigned URLs. The `ObjectUploader` component and `useUpload` hook are available for the Uppy modal UI and the direct-to-GCS upload step (step 2), which is outside your API spec since it goes to Google Cloud Storage directly.

   Example with `ObjectUploader` using the generated hook for step 1:

5. **Or use the useUpload hook** for custom upload UI:

## Presigned URL Upload Flow

File uploads use a two-step presigned URL flow:

1. **Request presigned URL** from the API server (send JSON metadata, NOT the file). This endpoint is defined in `openapi.yaml` and validated with Zod schemas on the server.
2. **Upload directly** to the presigned URL (NOT to your backend). This goes to Google Cloud Storage directly and is outside the OpenAPI spec.

Critical rules:

- DO NOT send the file as FormData to get the presigned URL
- DO NOT send the file to your backend server
- The file is uploaded DIRECTLY to Google Cloud Storage via the presigned URL
- Your backend only handles metadata and generates the presigned URL

## objectPath and Serving URL

The `objectPath` returned by the upload endpoint already includes the `/objects/` prefix (e.g., `/objects/uploads/some-uuid`). To construct the serving URL, simply prepend your storage mount path — do **not** add `/objects/` again:

Store `objectPath` in your database. To serve it: `fetch(\`/api/storage\${objectPath}\`)`.

For public assets (not user uploads), use the public-objects path instead:

For protected file uploads requiring user login:

- Use Replit Auth for user authentication (see the `replit-auth` skill)
- Add the `isAuthenticated` middleware to the storage routes
- Use ACL policies to control access (see `objectAcl.ts`)

When protected file uploading is requested, both **Replit Auth** and **PostgreSQL** must also be configured, even if not explicitly mentioned. Persistent storage and user authentication are implicitly required for protected file uploading.

If tracking upload metadata (which user uploaded what, file descriptions, etc.), define a Drizzle schema file in `lib/db/src/schema/` and push the schema with `pnpm --filter @workspace/db run push`

## Public Asset Serving

When the user wants to store app/website assets (not user uploads):

- Set up object storage
- Direct the user to upload files from the Object Storage tool pane
- Serve assets via `GET /api/storage/public-objects/<file-path>` — this route searches `PUBLIC_OBJECT_SEARCH_PATHS` and serves files unconditionally with no authentication

## Error Handling

If you encounter errors containing "App Storage service suspended" from `setupObjectStorage()` or from object storage operations at runtime:

1. Inform the user that their cloud budget has been exceeded
2. Call the `notify_cloud_budget_exceeded` tool with `service_name="object_storage"`

This error handling is ONLY for budget exceeded errors from Object Storage. Do NOT use `notify_cloud_budget_exceeded` for any other errors.

## Important

- Do NOT modify the GCS client setup in `objectStorage.ts` — it uses Replit sidecar authentication which is auto-configured.
- Do NOT modify the `objectAcl.ts` ACL framework unless adapting access group types for your use case.
- Do NOT modify `ObjectUploader.tsx` or `use-upload.ts` — the Uppy v5 imports and CSS paths are already correct. Do not consult external Uppy docs to "fix" them.